G41_TAPD_BUG_SYNC/docs/日志系统重构实施方案.md

日志系统重构实施方案（任务一 + 任务二）

1. 目标与边界

1.1 重构目标

• 在任务一和任务二之外，提供统一的全局日志记录系统。
• 覆盖生产链路：src/scheduler.py 与 src2/scheduler.py 触发的同步流程。
• 在每一个发起 API 调用的地方记录请求与结果（成功/失败都记录）。
• 任务一日志落在 logs/，任务二日志落在 logs2/。
• 每条日志必须包含 module 字段，允许值：smartsheet / tapd / wework。
• 通过 sync_id 分隔每次同步，并在同步完成后写入当次统计信息。

1.2 明确要解决的问题

• 解决“串目录”问题：任务二不得写入 logs/，任务一不得写入 logs2/。
• 解决“双记录矛盾”问题：同一次 API 调用只能有一条最终记录（不能先 success 再 failure）。
• 日志格式改为 jsonl（每行一条完整 JSON 记录）。
• 对 token 做脱敏，不做响应内容截断。

1.3 非目标

• 本次不改业务流程语义（只改日志系统与接线方式）。
• 本次不对历史 JSON 文件做离线迁移，仅保证新写入生效。

---

2. 总体设计

2.1 新增全局日志内核（任务外）

• 新增独立模块（建议路径：core/global_log_system.py）。
• 提供统一接口：
  • start_sync(...)：开始一次同步，生成 sync_id。
  • log_api(...)：记录单次 API 调用结果（成功/失败统一出口）。
  • end_sync_with_stats(...)：写入同步统计并结束。
• 通过构造参数确定任务上下文：task_name、log_dir、默认 module。

2.2 日志存储格式

• 文件命名：api_log_YYYY-MM-DD.jsonl。
• 存储目录：任务一 logs/，任务二 logs2/。
• 记录模型：
  • 通用字段：event_type、timestamp、task、sync_id、module。
  • API 事件字段：operation、request、response、success、error_message、duration_ms。
  • 同步边界字段：start_sync / end_sync 事件及统计 stats。

2.3 脱敏规则

• request/response 中出现 token 字段统一脱敏（如 access_token、Authorization、corpsecret、api_password）。
• 脱敏策略：保留前后少量字符，中间替换为 ***。

---

3. 分阶段实施路线（小步走）

阶段0：文档与约定先行

工作内容

• 新建并维护两份全局文档：
  • docs/全局迭代日志.md
  • docs/全局框架文档.md
• 在文档中建立日志重构专属章节、字段定义、阶段验收标准。

验收标准

• 文档结构可用于后续持续更新。
• 明确字段与职责边界（尤其是 sync_id、task、module）。

阶段1：实现全局日志内核

工作内容

• 新增 core/global_log_system.py，实现 jsonl 写入、脱敏、同步分隔和统计写入。
• 新增兼容层，避免一次性改动过大。

验收标准

• 能独立写入 logs/ / logs2/。
• start_sync -> 多条 log_api -> end_sync_with_stats 链路完整。

阶段2：接入任务一（src）

工作内容

• 改造 src/api_logger.py 为新内核兼容封装。
• 在任务一同步主流程增加 sync_id 生命周期。
• 覆盖所有 API 调用记录点，统一单次调用单条记录。

验收标准

• 任务一生产链路日志全部位于 logs/。
• 无“双记录矛盾”。

阶段3：接入任务二（src2）

工作内容

• 改造 src2/logger.py 接入同一内核并固定 logs2/。
• 在任务二同步主流程增加 sync_id 生命周期。
• 修复复用模块导致的串目录问题（含 token 获取、wework 通知链路）。

验收标准

• 任务二生产链路日志全部位于 logs2/。
• 与任务一日志完全隔离。

阶段4：查看工具与收尾

工作内容

• 更新 src/log_viewer.py 支持读取 jsonl。
• 更新 logs/README.md（新增 jsonl 规范与排障说明）。

验收标准

• 可按日期与 sync_id 追踪一次完整同步。
• 文档、代码、日志格式三者一致。

---

4. 核心风险与规避

• 风险1：兼容层改造影响原调用。
  • 规避：先保留 log_api_call(...) 旧接口，再逐步替换调用。
• 风险2：任务二通过复用模块写错目录。
  • 规避：统一使用可注入 logger/context，禁止隐式全局默认目录。
• 风险3：单次请求出现多状态记录。
  • 规避：采用“单出口记录”，业务错误也只写一次最终状态。

---

5. 验收清单（最终）

• 生产链路（两个 scheduler）所有 API 调用均有日志。
• 每次同步都有 start_sync 与 end_sync，并可通过 sync_id 聚合。
• 任务一只写 logs/，任务二只写 logs2/。
• 无同一次 API 调用 success/failure 双写冲突。
• token 已脱敏。
• jsonl 可被查看工具读取。