# TQ_catN 远程日志系统设计方案

**版本**：v1.0（待审核）
**日期**：2026-06-27
**范围**：全设备日志收集、本地缓冲、网络上传

---

## 一、设计目标

| 目标 | 说明 |
|------|------|
| **可靠性** | 网络抖动或断开时，日志不丢失，具备本地持久化和重传能力 |
| **低开销** | 对实时语音交互（PTT/WS/audio）零干扰，CPU 占用 < 5%，内存占用 < 256KB |
| **分层合规** | 严格遵循现有四层单向依赖架构（platform → domain → control_plane → app_composition） |
| **可配置** | 支持按模块/级别动态开关，支持生产环境静默/调试环境全量 |
| **安全性** | 日志上传使用 HTTPS + device JWT 认证，敏感字段自动脱敏 |

---

## 二、架构设计

### 2.1 与现有分层架构的集成

```
app_composition
    └── 初始化 remote_log_runtime（在 boot sequence 中启动）

control_plane
    └── remote_log_policy.c         # 策略：上传触发条件、级别控制、模块过滤
    └── remote_log_config.h         # 模块/级别开关配置

domain
    └── remote_log_format.c         # 日志格式化：JSON 序列化、时间戳、device_id 注入
    └── remote_log_compress.c       # 可选：压缩（miniz/lz4）

platform
    └── remote_log_buffer.c         # 双缓冲：内存 ring buffer + 文件队列（LittleFS）
    └── remote_log_transport.c      # 网络传输：复用 platform_https_post_json
    └── remote_log_hook.c           # ESP-IDF log hook：esp_log_set_vprintf 重定向
```

**依赖方向**：
- platform 层提供底层能力（buffer、transport、hook）
- domain 层提供格式化/压缩（无状态转换）
- control_plane 层提供策略（何时上传、上传什么）
- app_composition 层负责初始化编排

**禁止**：control_plane / domain 直接调用 esp_log_set_vprintf 或 esp_http_client API，必须通过 platform facade。

---

### 2.2 数据流

```
[App Code: ESP_LOGI/ESP_LOGE]
    │
    ▼
[platform/remote_log_hook.c] ──→ 拦截 ESP-IDF 日志输出
    │                              （原始串口输出保留，不影响调试）
    ▼
[platform/remote_log_buffer.c]
    ├── 内存环形缓冲区（热路径，ISR/任务安全）
    │   └── 容量：64KB（PSRAM 优先，内部 RAM 回退）
    │
    └── 文件队列（冷路径，网络断开时持久化）
        └── 容量：512KB（LittleFS gifpack 分区空闲空间）
        └── 最大文件数：32 个，每个 16KB
        └── 命名：log_batch_001.jsonl ~ log_batch_032.jsonl
    │
    ▼（满足上传条件时）
[domain/remote_log_format.c]
    └── 封装为 JSON batch：
        {
          "device_id": "66c...",
          "batch_id": "uuid",
          "timestamp_ms": 1782552243000,
          "logs": [
            {"ts": 1782552243001, "level": "E", "tag": "cp_mm_session", "msg": "..."},
            ...
          ]
        }
    │
    ▼
[domain/remote_log_compress.c] ──→ 可选：miniz 压缩（压缩率 ~60%）
    │
    ▼
[platform/remote_log_transport.c]
    └── 复用 platform_https_post_json() → 服务端
        POST https://gz.api.talkingq.com/log/batch
        Content-Type: application/json
        Authorization: Bearer <device_token>
```

---

## 三、核心模块设计

### 3.1 日志拦截层（platform/remote_log_hook.c）

**方案**：使用 ESP-IDF 的 `esp_log_set_vprintf()` 钩子，在保留原有串口输出的同时，将日志复制到远程日志缓冲区。

```c
// 接口设计
void platform_remote_log_hook_install(void);
void platform_remote_log_hook_uninstall(void);

// 内部实现
static int remote_log_vprintf(const char *fmt, va_list args)
{
    // 1. 调用原始 vprintf，保持串口输出
    int ret = s_original_vprintf(fmt, args);

    // 2. 格式化为结构化记录，写入 ring buffer
    //    使用非阻塞写入，buffer 满时丢弃最旧记录
    platform_remote_log_buffer_write(fmt, args);

    return ret;
}
```

**关键约束**：
- `remote_log_vprintf` 可能在 ISR 上下文被调用（如 `ESP_EARLY_LOG`），因此 `platform_remote_log_buffer_write` 内部必须：
  - 使用 `xRingbufferSendFromISR` 或自旋锁保护的环形缓冲区
  - 禁止任何可能阻塞的操作（malloc、semaphore take 等）
- 如果检测到 ISR 上下文，只做**原子计数 + 标记**，由后台任务在退出 ISR 后批量拷贝

**日志级别过滤**：在 hook 层不做级别过滤（避免重复判断），过滤由 control_plane 策略层通过 Kconfig 宏控制编译期开关。

---

### 3.2 双缓冲层（platform/remote_log_buffer.c）

#### 3.2.1 内存环形缓冲区（热路径）

```c
#define REMOTE_LOG_RING_BUFFER_SIZE  (64 * 1024)   // 64KB
#define REMOTE_LOG_RING_BLOCK_SIZE   256            // 每条日志最大 256 字节（超长截断）

static uint8_t s_ring_buffer[REMOTE_LOG_RING_BUFFER_SIZE];  // PSRAM 优先分配
static volatile size_t s_ring_write_idx;
static volatile size_t s_ring_read_idx;
```

**设计**：
- 使用简单的无锁环形缓冲区（单生产者：hook ISR/任务；单消费者：后台 flush 任务）
- 写入：原子递增 write_idx，memcpy 数据
- 读取：后台任务定期（100ms）将数据从 ring buffer 搬到文件队列
- 满策略：丢弃最旧记录（覆盖 read_idx 指向的数据），避免阻塞生产者

#### 3.2.2 文件队列（冷路径 / 持久化）

```c
#define REMOTE_LOG_FILE_MAX_BATCHES   32
#define REMOTE_LOG_FILE_BATCH_SIZE    (16 * 1024)  // 16KB / 文件
```

**设计**：
- 使用 LittleFS 的 `gifpack` 分区空闲空间（当前分区 8MB，OTA 后仍有富余）
- 文件名：`/littlefs/log/batch_001.jsonl` ~ `/littlefs/log/batch_032.jsonl`
- 写入格式：JSON Lines（每行一条 JSON，便于追加和断点续传）
- 循环覆盖：当 32 个文件都写满后，覆盖最早的文件

**掉电保护**：
- 每个 batch 文件写完后调用 `fsync`，确保数据落盘
- 启动时扫描 `/littlefs/log/` 目录，恢复未上传的 batch

---

### 3.3 格式化层（domain/remote_log_format.c）

**输入**：原始 ESP-IDF 日志字符串（如 `I (1934379) cp_mm_session: Transport unavailable`）

**输出**：结构化 JSON batch

```c
typedef struct {
    int64_t timestamp_ms;       // SNTP 同步后的毫秒时间戳
    char level;                 // 'V'/'D'/'I'/'W'/'E'
    char tag[32];               // 模块 TAG
    char message[192];          // 日志内容（超长截断）
} remote_log_entry_t;
```

**批处理策略**：
- 每批最多 50 条日志 或 每批最多 8KB 数据（先到为准）
- 超时机制：即使不满 50 条，最多等待 5 秒后强制上传
- 压缩：使用 miniz（zlib 兼容，纯 C，~8KB 代码）压缩 JSON batch，减少流量 50-70%

**脱敏规则**：
- 自动匹配并替换：`password=xxx`、`Bearer xxx`、`token=xxx`
- 使用正则或简单字符串扫描：`s/([Pp]assword|[Tt]oken|[Bb]earer)[=:]\S+/\1=***REDACTED***/g`

---

### 3.4 传输层（platform/remote_log_transport.c）

**复用现有能力**：
- HTTP 客户端：复用 `platform_https_post_json()`（已有 TLS、DNS、超时处理）
- 认证：复用 device JWT token（已有 `control_plane_multimodal_auth_service`）

**上传策略**：
```c
typedef struct {
    const char *endpoint_url;           // 如 "https://gz.api.talkingq.com/log/batch"
    uint32_t batch_max_count;           // 50
    uint32_t batch_max_size_bytes;      // 8192
    uint32_t flush_interval_ms;         // 5000
    uint32_t upload_timeout_ms;         // 10000
    uint32_t max_retry_count;           // 3
    uint32_t retry_backoff_ms;          // 2000
} remote_log_transport_config_t;
```

**上传流程**：
1. 检查 Wi-Fi 是否连接（`control_plane_is_sta_connected()`）
2. 检查 device token 是否有效（复用 auth service）
3. 读取一批日志（优先内存 buffer，其次文件队列）
4. 封装 JSON batch + device_id + batch_id
5. 调用 `platform_https_post_json()` 上传
6. 上传成功：删除已上传的文件 batch / 释放内存 buffer
7. 上传失败（非 401）：按指数退避重试（2s / 4s / 8s），失败后回写文件队列
8. 上传失败（401）：触发 device token 刷新，刷新成功后重试

**网络降级**：
- WS 连接活跃时（用户正在对话）：暂停日志上传，避免干扰实时音频/WS 流量
- Wi-Fi 断开时：完全停止上传，仅写入文件队列
- 内存 buffer 满且文件队列满时：丢弃最旧记录（采样策略：优先保留 Error/Warning）

---

### 3.5 策略层（control_plane/remote_log_policy.c）

**职责**：控制"上传什么、何时上传、上传多少"

```c
typedef enum {
    REMOTE_LOG_LEVEL_NONE = 0,
    REMOTE_LOG_LEVEL_ERROR = 1,     // 仅 Error
    REMOTE_LOG_LEVEL_WARN = 2,      // Error + Warning
    REMOTE_LOG_LEVEL_INFO = 3,      // Error + Warning + Info
    REMOTE_LOG_LEVEL_DEBUG = 4,     // 全部
} remote_log_level_t;

// 模块级别开关（与现有 TAG 对齐）
typedef struct {
    bool cp_mm_session;             // control_plane multimodal session
    bool cp_mm_runtime;             // control_plane multimodal runtime
    bool cp_workers;                // control_plane runtime workers
    bool cp_connectivity;           // control_plane connectivity
    bool transport_ws;              // platform transport ws
    bool audio_pipeline;            // platform audio pipeline
    bool direction;                 // domain direction
    bool fortune;                   // domain fortune
    // ... 其他模块
} remote_log_module_mask_t;
```

**策略规则**：
- 生产环境默认：`LEVEL_ERROR`，仅关键模块开启
- 调试环境默认：`LEVEL_DEBUG`，全部模块开启
- 动态调整：通过 LAN HTTP 配置页面（复用 `domain_user_config_server`）下发策略变更

---

## 四、Kconfig 配置项

建议在 `main/Kconfig.projbuild` 中新增菜单：

```kconfig
menu "Remote Logging"

    config TQ_REMOTE_LOG_ENABLED
        bool "Enable remote logging"
        default n
        help
            Enable log collection and remote upload. Increases flash
            usage by ~24KB and RAM usage by ~80KB.

    config TQ_REMOTE_LOG_LEVEL
        int "Default log level for remote upload"
        default 1
        range 0 4
        help
            0=NONE, 1=ERROR, 2=WARN, 3=INFO, 4=DEBUG

    config TQ_REMOTE_LOG_RING_BUFFER_SIZE
        int "Memory ring buffer size (KB)"
        default 64
        range 8 256

    config TQ_REMOTE_LOG_FILE_BATCHES
        int "Max file batches on LittleFS"
        default 32
        range 8 64

    config TQ_REMOTE_LOG_BATCH_MAX_COUNT
        int "Max log entries per batch"
        default 50
        range 10 200

    config TQ_REMOTE_LOG_FLUSH_INTERVAL_MS
        int "Flush interval (ms)"
        default 5000
        range 1000 30000

    config TQ_REMOTE_LOG_UPLOAD_TIMEOUT_MS
        int "Upload HTTP timeout (ms)"
        default 10000
        range 3000 30000

    config TQ_REMOTE_LOG_COMPRESS
        bool "Enable miniz compression"
        default y
        help
            Compress log batches before upload. Reduces data usage
            by ~60% at the cost of ~8KB flash and ~2KB RAM.

    config TQ_REMOTE_LOG_ENDPOINT
        string "Log upload endpoint URL"
        default "https://gz.api.talkingq.com/log/batch"
        help
            HTTPS endpoint for log batch upload.

endmenu
```

---

## 五、内存和性能预算

### 5.1 Flash 占用

| 组件 | 代码+数据 | 说明 |
|------|----------|------|
| remote_log_hook.c | ~4KB | 钩子 + ring buffer 管理 |
| remote_log_buffer.c | ~6KB | 双缓冲 + LittleFS 文件操作 |
| remote_log_transport.c | ~4KB | HTTP 上传 + 重试逻辑 |
| remote_log_format.c | ~6KB | JSON 序列化 + 脱敏 |
| remote_log_compress.c | ~8KB | miniz 压缩库 |
| remote_log_policy.c | ~2KB | 策略判断 + 模块过滤 |
| **合计** | **~30KB** | 可配置关闭压缩节省 8KB |

### 5.2 RAM 占用（运行时）

| 组件 | 内存 | 位置 |
|------|------|------|
| Ring buffer | 64KB | PSRAM（配置为 PSRAM 优先） |
| Upload working buffer | 8KB | PSRAM |
| HTTP client（复用现有） | ~4KB | 内部 RAM（复用已有实例） |
| 格式化/压缩临时区 | ~4KB | PSRAM |
| **合计** | **~80KB** | 其中内部 RAM < 10KB |

### 5.3 CPU 占用

| 场景 | CPU 占用 |
|------|----------|
| 日志写入（hook） | < 1%（纯内存拷贝） |
| 定时 flush（100ms） | < 2%（文件写入） |
| 上传（每 5s 一次） | < 5%（JSON 格式化 + HTTP POST） |
| 用户对话期间（WS 活跃） | 0%（暂停上传） |

---

## 六、启动时序

在 `app_composition_default_runtime.c` 的 boot sequence 中，在 `control_plane_init()` 之后、`wifi_bootstrap` 之前插入：

```c
// 步骤 7.5：初始化远程日志系统
esp_err_t log_err = control_plane_init_remote_logging();
if (log_err != ESP_OK) {
    ESP_LOGW(TAG, "Remote logging init failed: %s", esp_err_to_name(log_err));
    // 非致命错误，继续启动
}
```

**理由**：
- 在 `control_plane_init()` 之后：确保 device auth 已加载（用于上传认证）
- 在 `wifi_bootstrap` 之前：确保 Wi-Fi 连接建立后日志系统已就绪，可以立即开始收集

---

## 七、服务端接口契约

### 7.1 上传接口

```http
POST /log/batch
Content-Type: application/json
Authorization: Bearer <device_jwt_token>

{
  "device_id": "66c7f8a2e4b0d1e2f3a4b5c6",
  "batch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp_ms": 1782552243000,
  "firmware_version": "1.2.3",
  "logs": [
    {
      "ts": 1782552243001,
      "level": "E",
      "tag": "transport_ws",
      "msg": "Sec-WebSocket-Accept not found"
    },
    {
      "ts": 1782552243010,
      "level": "W",
      "tag": "cp_mm_session",
      "msg": "Transport unavailable: reason=ws_error"
    }
  ]
}
```

### 7.2 服务端响应

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 200,
  "message": "OK",
  "data": {
    "accepted": 2,
    "dropped": 0
  }
}
```

### 7.3 错误码

| HTTP 状态码 | 含义 | 客户端行为 |
|------------|------|-----------|
| 200 | 成功 | 删除已上传的 batch |
| 400 | 格式错误 | 丢弃当前 batch（避免无限重试） |
| 401 | 认证失败 | 刷新 device JWT 后重试 |
| 413 | Payload 过大 | 减小 batch size 后重试 |
| 429 | 频率限制 | 指数退避后重试 |
| 500+ | 服务端错误 | 指数退避后重试 |

---

## 八、安全与隐私

### 8.1 认证
- 复用现有 device JWT 认证体系，不引入新密钥
- token 过期时自动刷新（复用 `control_plane_multimodal_auth_service`）

### 8.2 传输
- 强制 HTTPS，复用现有 TLS 证书校验（`esp-x509-crt-bundle`）
- 禁止 HTTP 明文传输

### 8.3 脱敏
- 自动脱敏：password、token、Bearer、secret、api_key 等前缀后的值
- 用户配置：支持通过 LAN HTTP 配置页面自定义脱敏关键词

### 8.4 数据保留
- 本地：最多保留 32 个 batch 文件（~512KB），循环覆盖
- 服务端：建议保留 30 天，过期自动清理

---

## 九、故障排查与调试

### 9.1 本地诊断命令
通过现有的 factory CLI 或 LAN HTTP 配置页面，增加以下诊断接口：

```
GET /api/diag/log/status
→ {
    "enabled": true,
    "level": 2,
    "ring_buffer_used": 32768,
    "ring_buffer_total": 65536,
    "file_batches_pending": 5,
    "last_upload_status": "success",
    "last_upload_time": "2026-06-27T10:30:00Z"
  }
```

### 9.2 本地日志导出
```
GET /api/diag/log/download?batch=latest
→ 返回最近一个 batch 文件的内容（纯文本）
```

---

## 十、实施建议

### Phase 1（最小可用）
1. `platform/remote_log_hook.c` — 拦截 ESP_LOG 到 ring buffer
2. `platform/remote_log_buffer.c` — 内存缓冲 + 文件持久化
3. `platform/remote_log_transport.c` — 复用 HTTPS 上传
4. `control_plane/remote_log_policy.c` — 级别过滤 + 模块开关
5. Kconfig 配置项 + boot sequence 初始化

### Phase 2（增强）
6. `domain/remote_log_format.c` — JSON 格式化 + 脱敏
7. `domain/remote_log_compress.c` — miniz 压缩
8. LAN HTTP 配置页面集成（动态调整级别）
9. 诊断接口（`/api/diag/log/status`）

### Phase 3（优化）
10. 服务端实时告警（Error 级别日志触发服务端告警）
11. 日志采样（高频 Debug 日志按概率采样）
12. 日志关联（与 device session_id 关联，便于追踪单设备全链路）

---

## 十一、风险评估

| 风险 | 缓解措施 |
|------|----------|
| 日志写入拖慢 ISR | hook 层使用纯内存拷贝 + 无锁 ring buffer，禁止 malloc |
| 文件写入磨损 Flash | LittleFS 磨损均衡，日志 batch 文件大小控制在 16KB |
| 上传流量过大 | 压缩（-60%）+ 级别过滤（仅 ERROR/WARN）+ 批量上传（5s 间隔） |
| 上传干扰 WS 音频 | WS 活跃时暂停上传，仅写入本地 buffer |
| 敏感信息泄露 | 自动脱敏 + HTTPS + 服务端 ACL |
| 内存不足 | PSRAM 优先分配，内部 RAM 占用 < 10KB |

---

## 十二、总结

本方案基于现有四层架构，以 **"零侵入、低开销、高可靠"** 为核心原则：

- **platform 层**：提供日志拦截、双缓冲、网络传输的底层能力
- **domain 层**：提供 JSON 格式化、压缩、脱敏的业务处理
- **control_plane 层**：提供级别控制、模块过滤、上传策略的策略决策
- **app_composition 层**：负责启动编排

关键设计决策：
1. 复用 `platform_https_post_json()`，不引入新 HTTP 客户端
2. 复用 device JWT，不引入新认证体系
3. 使用 `esp_log_set_vprintf()` 拦截，不修改现有 ESP_LOGx 调用
4. 使用 LittleFS 持久化，不引入新文件系统
5. 用户对话期间暂停上传，保证实时语音不受干扰