linzelong/G41_TAPD_BUG_SYNC
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
G41_TAPD_BUG_SYNC/docs/全局迭代日志.md

15 KiB
Raw Blame History

全局迭代日志

用途：跨任务（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 段落）
  • 备注：可在后续补“消息模板配置化”减少文案硬编码。

阶段5：任务一 TAPD 429 限速通知与状态批量查询修复

  • 阶段名称：任务一 TAPD 429 限速与企微通知补丁
  • 日期：2026-06-02
  • 负责人：Codex
  • 目标：定位并修复智能表格存在数百条记录时，任务一开单和任务一 Bug 状态同步触发 TAPD 429 后不会触发企微推送、状态查询请求过多或未等待重试的问题。

根因

  • 开单链路：src/main.py 只把字段校验失败加入企微通知集合；TAPD 创建失败虽然会写回 ❌，但不会触发企微推送。
  • 任务归属修正：本阶段 429 问题归属任务一；任务二 src2/ 改动已回滚，不纳入本阶段。
  • 任务一状态同步链路：src/sync_status.py 原先逐条调用 self.tapd_api.get_bug(bug_id) 查询状态，数百条记录会放大 TAPD 限速风险。
  • 状态查询结果处理：单条查询失败需要进入失败统计和企微异常通知，避免被误判为“状态无变化”。
  • 接口能力未利用：TAPD bugs 查询接口支持多 ID 查询，默认返回 30 条，可通过 limit 设置到最大 200。

变更清单

  • 新增文件：无
  • 修改文件：
    • src/tapd_api.py
    • src/sync_status.py
    • src/main.py
    • src/wework_notifier.py
    • docs/全局任务列表.md
    • docs/全局框架文档.md
    • docs/全局迭代日志.md
  • 删除文件：无

关键改动说明

  • src/tapd_api.py 新增 RateLimitError，识别 HTTP 429 与业务错误文本中的限速信息。
  • src/tapd_api.py 新增 get_bugs_by_ids(...)，通过 GET /bugs 传 id、limit、page、fields 批量获取 Bug 信息，默认只取 id,status。
  • src/main.py 在开单触发限速后等待 120 秒重试当前记录一次；重试仍触发限速时才停止本轮后续 TAPD 开单，未处理记录保持未开单状态，等待下次调度重试。
  • src/main.py 将 TAPD 开单失败与限速事件纳入企微异常通知。
  • src/sync_status.py 将任务一 Bug 状态同步从逐条 get_bug 改为每批最多 200 个 ID 的批量查询。
  • src/sync_status.py 在批量状态查询触发 TAPD 429 时等待 120 秒重试当前批次一次；重试仍限速则停止本轮后续状态查询，并将失败批次纳入企微异常通知。
  • src/wework_notifier.py 的运行异常通知文案补充“当前记录或批次”，覆盖开单和状态查询两类限速场景。

验收结果

  • 通过项：
    • 已完成静态链路复查：限速错误从 TAPD API 层到任务一开单/状态同步编排层都有专用分支。
    • 已确认开单链路触发 429 后会先等待 120 秒重试当前记录。
    • 已确认任务一状态同步不再逐条调用 get_bug，而是通过 get_bugs_by_ids 按最多 200 个 ID 批量查询。
    • 已确认任务一状态同步触发 429 后会等待 120 秒重试当前批次一次。
    • 已确认开单链路和状态同步链路的 TAPD 异常都会进入企微运行异常通知。
    • 已确认 src2/tapd_api.py 的任务二 429 改动已回滚。
  • 未通过项：
    • 尚未执行运行态联调（按项目约束未在命令行执行 Python）。
  • 遗留风险：
    • 当前批量查询的多 ID 分隔符按英文逗号处理，需要运行态联调确认与 TAPD 实际返回一致。
    • 当前补丁是“限速后固定等待 120 秒重试一次”，尚未实现主动节流、按 Retry-After 动态等待或单轮处理上限。
    • 若 TAPD 限速信息不包含 429、限速、频繁等关键词，仍可能被识别为普通运行错误。

回滚与追踪

  • 可回滚点：优先按文件粒度回滚 src/tapd_api.py、src/sync_status.py、src/main.py、src/wework_notifier.py。
  • 关联文档：docs/全局框架文档.md、docs/全局任务列表.md
  • 备注：下一阶段建议做“请求节流 + 单轮最大处理数 + Retry-After 动态退避”，这是从根上降低 429 的方案。