4.5 KiB
4.5 KiB
全局框架文档
用途：统一维护项目模块、脚本职责与接口定义，避免调用不存在接口与跨任务耦合失控。 范围：
src/、src2/，以及新增的全局模块（如后续core/）。
1. 日志系统总览（重构目标态）
1.1 目标架构
- 全局日志内核：位于任务目录外，提供统一记录能力。
- 任务一适配层：写入
logs/。 - 任务二适配层：写入
logs2/。 - 同步边界管理：每次同步使用唯一
sync_id分隔，结束时写统计。
1.2 统一日志字段（约定）
event_type：start_sync/api_call/end_synctimestamp：事件时间task：task1/task2sync_id：单次同步唯一标识module：smartsheet/tapd/weworkoperation：接口操作名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获取与缓存。 - 接口（对内）：
get_token()。
- 职责：企业微信
src/wework_notifier.py- 职责：企业微信消息通知。
- 接口（对内）：
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()。
src2/smartsheet.py- 职责：任务二智能表格 API 适配层。
- 关键点：应固定写入
logs2/。
src2/smartsheet_sync.py- 职责：任务二表格字段检查、记录提取与回写构造。
src2/tapd_api.py- 职责：任务二 TAPD Story 查询与状态映射。
src2/notifier.py- 职责：任务二失败通知封装（当前复用任务一通知器，存在串目录风险）。
src2/logger.py- 职责：任务二日志实例入口（后续接入统一内核）。
3. 现存问题与待改造点
- 串目录问题：任务二复用
TokenManager、WeWorkNotifier可能写入logs/。 - 双记录矛盾：同一次请求在部分分支可能出现先成功后失败两条记录。
- 写入稳定性问题：现有按 JSON 数组拼接的策略会造成结构损坏风险。
- 同步边界缺失：缺少标准化
start_sync/end_sync分隔与统计记录。
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接线。