G41_TAPD_BUG_SYNC/docs/全局迭代日志.md

全局迭代日志

用途：跨任务（src / src2）记录每个阶段的增改内容、验收结果与回滚点。 约束：每次阶段验收通过后，必须追加一条日志记录。

---

记录模板

阶段：

• 阶段名称：
• 日期：
• 目标：

变更清单

• 新增文件：
• 修改文件：
• 删除文件：

关键改动说明

• 日志结构变更：
• 接口/调用链变更：
• 兼容性说明：

验收结果

• 通过项：
• 未通过项：
• 遗留风险：

回滚与追踪

• 可回滚点：
• 关联文档：
• 备注：

---

阶段日志

阶段0：文档与约定先行

• 阶段名称：日志系统重构 - 阶段0
• 日期：2026-02-28
• 目标：建立重构方案与全局文档骨架，为后续代码改造提供统一约束。

变更清单

• 新增文件：
  • docs/日志系统重构实施方案.md
  • docs/全局迭代日志.md
  • docs/全局框架文档.md
• 修改文件：无
• 删除文件：无

关键改动说明

• 日志结构变更：确定后续采用 jsonl，并以 sync_id 分隔每次同步。
• 接口/调用链变更：明确生产链路以 src/scheduler.py、src2/scheduler.py 为准。
• 兼容性说明：阶段0仅文档，不影响现网行为。

验收结果

• 通过项：
  • 分阶段路线、边界条件、验收清单已落文档。
  • 已建立全局迭代日志与框架文档容器。
• 未通过项：无
• 遗留风险：
  • 任务二存在复用模块导致串目录风险（待阶段3修复）。
  • 现有日志写入策略存在双记录与结构损坏风险（待阶段1/2修复）。

回滚与追踪

• 可回滚点：当前为纯文档提交，可直接整提交回滚。
• 关联文档：docs/日志系统重构实施方案.md
• 备注：阶段1开始前需再次确认日志字段最终版。

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

• 阶段名称：日志系统重构 - 阶段1
• 日期：2026-02-28
• 负责人：Codex
• 目标：在任务目录外提供可复用的统一日志内核，支持 jsonl、sync_id、token 脱敏。

变更清单

• 新增文件：
  • core/global_log_system.py
  • core/__init__.py
• 修改文件：
  • docs/全局迭代日志.md
  • docs/全局框架文档.md
• 删除文件：无

关键改动说明

• 日志结构变更：新增 start_sync / api_call / end_sync 三类事件模型。
• 接口/调用链变更：提供 start_sync、log_api、end_sync_with_stats 三个核心接口。
• 兼容性说明：阶段1仅新增内核，未接入任务一/任务二业务调用，不影响现网逻辑。

验收结果

• 通过项：
  • 已支持按天写入 api_log_YYYY-MM-DD.jsonl。
  • 已支持 sync_id 生命周期记录。
  • 已支持 token/secret 脱敏。
  • 已提供任务一、任务二创建器（固定目录）。
• 未通过项：
  • 尚未接入 src / src2，串目录与双记录矛盾仍待后续阶段修复。
• 遗留风险：
  • 阶段2/3接线时若沿用旧 logger 分支逻辑，可能再次引入双记录。

回滚与追踪

• 可回滚点：core/ 新增为独立改动，可单独回滚。
• 关联文档：docs/日志系统重构实施方案.md
• 备注：下一阶段优先完成任务一接入并验证“单次调用单条记录”。

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

• 阶段名称：日志系统重构 - 阶段2
• 日期：2026-02-28
• 负责人：Codex
• 目标：将任务一接入全局日志内核，补齐同步分隔与统计，并修复双记录矛盾。

变更清单

• 新增文件：无
• 修改文件：
  • src/api_logger.py
  • src/main.py
  • src/scheduler.py
  • src/smartsheet.py
  • docs/全局迭代日志.md
  • docs/全局框架文档.md
• 删除文件：无

关键改动说明

• 日志结构变更：任务一日志由旧 JSON 数组切换为 jsonl 事件流（通过兼容层接入）。
• 接口/调用链变更：
  • src/api_logger.py 保留旧接口，内部转发到全局内核。
  • src/scheduler.py 的 job/sync_job 增加 start_sync/end_sync_with_stats。
  • src/main.py 的 run_once 增加“无外层同步时自动兜底”的同步边界。
• 兼容性说明：旧调用 log_api_call(...) 保持可用；历史 api_type 通过映射落入 module 三类。

验收结果

• 通过项：
  • 任务一生产链路（scheduler 触发）已具备每次同步分隔与统计写入。
  • 任务一 API 日志已接入统一内核。
  • src/smartsheet.py 已修复“同一次请求先 success 后 failure”的双记录问题。
• 未通过项：
  • 任务二串目录问题尚未处理（待阶段3）。
• 遗留风险：
  • main.py 直跑与 scheduler 路径都可触发同步边界，后续需确保运维使用一致入口。

回滚与追踪

• 可回滚点：可按文件粒度回滚（src/api_logger.py 与 src/scheduler.py 为关键点）。
• 关联文档：docs/日志系统重构实施方案.md
• 备注：下一阶段优先处理任务二串目录与通知链路复用问题。

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

• 阶段名称：日志系统重构 - 阶段3
• 日期：2026-03-10
• 负责人：Codex
• 目标：修复任务二串目录问题，补齐任务二同步分隔与统计收尾，确保生产链路日志只落 logs2/。

变更清单

• 新增文件：无
• 修改文件：
  • src/token_manager.py
  • src/wework_notifier.py
  • src2/scheduler.py
  • src2/main.py
  • src2/sync_service.py
  • src2/notifier.py
  • docs/全局迭代日志.md
  • docs/全局框架文档.md
• 删除文件：无

关键改动说明

• 日志结构变更：任务二调度链路与手动入口均补齐 start_sync/end_sync_with_stats，按 sync_id 分隔并写入统计。
• 接口/调用链变更：
  • TokenManager 与 WeWorkNotifier 新增可选 logger 注入参数。
  • src2/scheduler.py、src2/main.py、src2/sync_service.py 全部接入任务二 logger 边界控制。
  • src2/notifier.py 调用通知器时显式注入 get_task2_logger()。
• 兼容性说明：旧调用不传 logger 仍保持任务一默认行为，生产链路通过显式注入实现目录隔离。

验收结果

• 通过项：
  • 任务二生产链路（src2/scheduler.py）已具备每次同步开始/结束事件与统计写入。
  • 任务二手动入口（src2/main.py）与 run_once 兜底路径已具备同步边界。
  • 任务二 token 获取、通知链路、sync_service 自动取 token 全部使用任务二 logger，不再串写 logs/。
  • api_type 已明确映射为 smartsheet/tapd/wework 三类语义。
• 未通过项：
  • 未执行运行态联调（仅完成静态改造与代码级复核）。
• 遗留风险：
  • src2/test_* 中仍有 TokenManager() 默认实例，属于测试路径，不影响生产链路。

回滚与追踪

• 可回滚点：可按文件粒度回滚，优先关注 src2/scheduler.py、src2/main.py、src2/sync_service.py。
• 关联文档：docs/日志系统重构实施方案.md
• 备注：阶段4建议优先补日志查看工具对 jsonl + sync_id 的检索能力。

阶段4：任务三V2多群分组推送（src3）

• 阶段名称：任务三迭代 - V2 多群分组推送
• 日期：2026-04-01
• 负责人：Codex
• 目标：在不改 src/、src2/ 的前提下，将任务三由单群推送升级为技术/美术/策划三群分组推送，并按子表标题自动解析成员配置表 sheet_id。

变更清单

• 新增文件：无
• 修改文件：
  • src3/config.py
  • src3/main.py
  • config3/config.ini
  • docs/全局迭代日志.md
  • docs/全局框架文档.md
• 删除文件：无

关键改动说明

• 日志结构变更：无新增日志事件类型，沿用任务三现有同步边界和统计写入。
• 接口/调用链变更：
  • src3/config.py 新增 get_group_push_configs 与 get_group_team_configs，从配置读取“组名-子表标题-Webhook”顺序映射，并通过 smartsheet/get_sheet 自动按标题解析 sheet_id。
  • src3/main.py 从“单组白名单 + 单Webhook”改为“多组配置”，执行一次 TAPD 拉取后按组成员过滤并分别推送到对应群。
  • 空白名单由“全局失败”调整为“按组跳过并继续其他组”；当所有组均为空时整体跳过本次推送。
• 兼容性说明：
  • 仅改 src3 与 config3，未触碰 src/、src2/。
  • config3/config.ini 改为 GroupPush 分组配置，移除手填 sheet_id。

验收结果

• 通过项：
  • 支持三组（技术/美术/策划）Webhook 一一对应配置，并按顺序生效。
  • 支持通过子表 title 自动解析成员配置 sheet_id，无需手填 sheet_id。
  • TAPD 过期单拉取改为合并成员单次拉取，避免重复调用后再按组分发。
• 未通过项：
  • 尚未执行运行态联调（未在命令行执行 Python，自检留待人工验收）。
• 遗留风险：
  • 若同一 TAPD 用户同时存在于多个组，当前会在多个群重复推送（由配置侧避免）。
  • Webhook 当前为测试地址，合入生产前需替换并再次验收。

回滚与追踪

• 可回滚点：可按文件粒度回滚，关键文件为 src3/config.py、src3/main.py、config3/config.ini。
• 关联文档：需求文档.md（任务三 V2 段落）
• 备注：建议下一阶段补“配置校验命令”与“跨组重复成员检测告警”。

阶段4-补丁1：任务三V2消息头增加组别名

• 阶段名称：任务三迭代 - V2 文案补丁1
• 日期：2026-04-01
• 负责人：Codex
• 目标：每个分组推送消息标题增加组别名，格式如“⏰ TAPD 过期单提醒 — 策划组（YYYY-MM-DD）”。

变更清单

• 新增文件：无
• 修改文件：
  • src3/message_formatter.py
  • src3/main.py
  • docs/全局迭代日志.md
• 删除文件：无

关键改动说明

• MessageFormatter.format_message(...) 新增 group_name 参数，消息头按组名渲染。
• 若组名未包含“组”后缀，自动补齐“组”。
• src3/main.py 在按组发送时将当前组名传入格式化器。

验收结果

• 通过项：
  • 分组消息头可显示组别名（技术组/美术组/策划组）。
• 未通过项：
  • 尚未执行运行态联调（未在命令行执行 Python，自检留待人工验收）。
• 遗留风险：
  • 若配置中的组名为空，消息头将退化为不带组别名（由配置校验保障）。

回滚与追踪

• 可回滚点：src3/message_formatter.py 与 src3/main.py 可独立回滚。
• 关联文档：需求文档.md（任务三 V2 段落）
• 备注：可在后续补“消息模板配置化”减少文案硬编码。