G41_TAPD_BUG_SYNC/docs/全局框架文档.md

全局框架文档

用途：统一维护项目模块、脚本职责与接口定义，避免调用不存在接口与跨任务耦合失控。 范围：src/、src2/、src3/，以及新增的全局模块（如后续 core/）。

---

1. 日志系统总览（重构目标态）

1.1 目标架构

• 全局日志内核：位于任务目录外，提供统一记录能力。
• 任务一适配层：写入 logs/。
• 任务二适配层：写入 logs2/。
• 同步边界管理：每次同步使用唯一 sync_id 分隔，结束时写统计。

1.2 统一日志字段（约定）

• event_type：start_sync / api_call / end_sync
• timestamp：事件时间
• task：task1 / task2
• sync_id：单次同步唯一标识
• module：smartsheet / tapd / wework
• operation：接口操作名
• request：请求快照（含脱敏）
• response：响应快照（含脱敏）
• success：调用是否成功
• error_message：失败原因
• duration_ms：调用耗时（毫秒）
• stats：同步完成统计（仅 end_sync）

---

2. 模块清单与职责（当前状态）

2.0 全局核心（core/）

• core/global_log_system.py
  • 职责：提供统一日志内核（jsonl 写入、同步分隔、API 事件、统计事件、脱敏）。
  • 接口（对内）：start_sync、log_api、end_sync_with_stats。
  • 创建器：create_task1_log_system（固定 logs/）、create_task2_log_system（固定 logs2/）。
• core/__init__.py
  • 职责：导出全局日志内核与创建器。

2.1 任务一（src/）

• src/scheduler.py
  • 职责：任务一调度入口，定时触发单次同步。
  • 关键依赖：src/main.py。
• src/main.py
  • 职责：任务一主流程编排（扫描、校验、开单、回写、通知）。
  • 接口（对内）：run_once(...)。
• src/smartsheet.py
  • 职责：智能表格 API 封装。
  • 接口（对内）：get_sheet_list、get_fields、get_records、update_records 等。
• src/tapd_api.py
  • 职责：TAPD Bug API 封装（创建、查询、附件上传）。
  • 接口（对内）：create_bug、get_bug、upload_attachment 等。
• src/token_manager.py
  • 职责：企业微信 access_token 获取与缓存。
  • 接口（对内）：__init__(cache_file_path=None, logger=None)、get_token()。
• src/wework_notifier.py
  • 职责：企业微信消息通知。
  • 接口（对内）：__init__(access_token, agentid, receivers, logger=None)、send_validation_failure_notification(...)。
• src/api_logger.py
  • 职责：现有日志记录器（后续将作为兼容层）。

2.2 任务二（src2/）

• src2/scheduler.py
  • 职责：任务二调度入口，定时触发同步并记录每次同步边界与统计。
  • 关键依赖：src2/sync_service.py。
• src2/sync_service.py
  • 职责：任务二同步编排（读取、解析链接、查询 TAPD、回写、通知）。
  • 接口（对内）：sync_once()、run_once(...)（无外层同步时自动兜底边界）。
• src2/smartsheet.py
  • 职责：任务二智能表格 API 适配层。
  • 关键点：应固定写入 logs2/。
• src2/smartsheet_sync.py
  • 职责：任务二表格字段检查、记录提取与回写构造。
• src2/tapd_api.py
  • 职责：任务二 TAPD Story 查询与状态映射。
• src2/notifier.py
  • 职责：任务二失败通知封装（复用任务一通知器并显式注入任务二 logger，避免串目录）。
• src2/logger.py
  • 职责：任务二日志实例入口（固定写入 logs2/，接入统一内核兼容层）。

2.3 任务三（src3/）

• src3/config.py
  • 职责：任务三配置入口；读取分组推送配置（组名/成员子表标题/Webhook），并通过子表标题自动解析 sheet_id 后加载成员白名单和 TAPD用户名 -> 企微UserID 映射。
  • 接口（对内）：get_workspace_id()、get_push_time()、get_group_push_configs()、get_group_team_configs(...)。
• src3/main.py
  • 职责：任务三主流程编排；合并多组成员执行一次过期单拉取，再按组过滤并分发到各组 webhook。
  • 接口（对内）：run_once()。
• src3/tapd_api.py
  • 职责：任务三 TAPD 查询封装（需求 + 缺陷），内置终态过滤、过期判定字段提取与重试。
• src3/overdue_fetcher.py
  • 职责：聚合 TAPD 结果并补齐过期天数、详情链接。
• src3/message_formatter.py
  • 职责：按处理人分组排序并生成企微 Markdown 内容；输出 mentioned_list。
• src3/webhook_sender.py
  • 职责：Webhook 推送与失败重试（重试2次，间隔30秒）；超长消息拆分发送。
• src3/scheduler.py
  • 职责：任务三定时调度入口（工作日定时触发 run_once）。
• src3/logger.py
  • 职责：任务三日志实例入口（固定写入 logs3/）。

---

3. 现存问题与待改造点（阶段3后）

• 串目录问题（生产链路）：已修复，src2 生产入口统一显式注入任务二 logger。
• 双记录矛盾（任务一）：已修复；任务二当前未发现同请求双写路径。
• 写入稳定性问题：已由统一 jsonl 事件流替代旧数组拼接策略。
• 阶段4待办：日志查看工具尚未完成 jsonl + sync_id 体验优化。
• 任务三V2注意点：分组成员若存在交叉，当前会导致同一过期单在多个群重复推送，应通过配置治理。

---

4. 模块接口演进计划（摘要）

• 阶段1：新增全局日志内核模块，定义统一接口。（已完成）
• 阶段2：src/api_logger.py 改造成兼容层，保证旧调用可用。（已完成）
• 阶段3：src2/logger.py 与任务二编排层切换到统一内核，修复串目录。（已完成）
• 阶段4：更新查看工具与文档，支持 jsonl + sync_id。

---

5. 变更记录

2026-02-28

• 新建本框架文档。
• 写入日志系统重构目标态、模块职责清单、问题清单与演进路线。

2026-02-28（更新）

• 新增 core/global_log_system.py 与 core/__init__.py 模块说明。
• 标记阶段1完成：统一日志内核已落地，待阶段2/3接线。

2026-02-28（更新2）

• 标记阶段2完成：任务一已接入统一日志内核。
• src/scheduler.py 的 job/sync_job 已接入同步边界与统计事件。
• src/main.py 的 run_once 已接入手动兜底同步边界。
• src/smartsheet.py 已消除同请求双记录矛盾。

2026-03-10（更新3）

• 标记阶段3完成：任务二生产链路已接入同步边界与统计收尾。
• TokenManager、WeWorkNotifier 已支持 logger 注入，用于任务二目录隔离。
• src2/notifier.py、src2/sync_service.py、src2/main.py、src2/scheduler.py 已完成 logs2 链路闭环。

2026-04-01（更新4）

• 新增任务三（src3/）模块清单与职责说明。
• 任务三配置改为多群分组推送：按顺序维护“组名-成员子表标题-Webhook”一一对应关系。
• 任务三成员配置读取由手填 sheet_id 调整为通过子表标题自动解析 sheet_id。