gyxx-flow/plan.md

GYXX Flow 执行计划与验收清单

规则：只有完成对应验证并保存证据后才把 [ ] 改为 [x]。每次更新复核 python -m pytest、gyxx acceptance status 和本文件。

P0 设计与迁移基线

• P0.1 固化模块化单体、数据分层、影子运行和逐任务回滚设计。
  • 文件：design.md
  • 验证：设计包含目标、边界、模块、数据、安全、迁移和验收。
• P0.2 建立项目骨架、依赖文件和忽略规则。
  • 文件：pyproject.toml、.gitignore、README.md、src/、tests/
  • 验证：干净环境可安装，CLI 能显示帮助。
• P0.3 生成四个旧项目的代码、任务、数据基线清单。
  • 文件：var/baseline/<timestamp>/
  • 验证：包含 21 个实际任务、代码哈希、数据汇总；不包含密钥值。
• P0.4 建立敏感信息扫描并记录轮换门禁。
  • 文件：src/gyxx_flow/security/、config/secrets.example.env
  • 验证：仓库扫描无明文凭据；生产切换要求凭据轮换确认。

P1 核心运行与数据基础设施

• P1.1 TDD 实现可移植路径配置，不允许业务代码硬编码旧盘符。
• P1.2 TDD 实现 RunContext、稳定 run_id 和业务日期校验。
• P1.3 TDD 实现原子 JSON 写入、SHA-256 和 artifact manifest。
• P1.4 TDD 实现 raw/normalized/curated/export/evidence/state/log/tmp 目录解析。
• P1.5 TDD 实现结构化运行及步骤状态记录。
• P1.6 TDD 实现文件锁、工作流锁和命名资源锁。

P2 工作流引擎与 CLI

• P2.1 TDD 实现工作流、步骤、依赖、超时和重试模型。
• P2.2 TDD 实现命令步骤及无副作用 dry-run。
• P2.3 TDD 实现 shadow 模式，禁止生产 Sink 和正式通知。
• P2.4 TDD 实现 gyxx list、gyxx run、gyxx backfill。
• P2.5 TDD 实现失败恢复、步骤级重跑和最终退出码。
• P2.6 建立 ops 运行记录和 outbox 接口。

P3 工作流目录与调度

• P3.1 建立四个模块及模块依赖约束测试。
• P3.2 映射 21 个实际计划任务到稳定 workflow ID。
• P3.3 登记未调度/手工工作流，保持原触发语义。
• P3.4 建立声明式 schedule 配置及 schema 校验。
• P3.5 生成 Windows Task Scheduler XML/PowerShell 安装计划，但默认不应用。
• P3.6 实现 gyxx schedule plan，检测系统任务漂移。

P4 迁移和验收工具

• P4.1 实现旧命令适配器，所有旧根目录均通过配置注入。
• P4.2 实现历史数据只复制、不删除的迁移计划及校验清单。
• P4.3 实现文件数量、字节数、SHA-256 对账。
• P4.4 实现 shadow 结果主键、行数、指标和错误对比。
• P4.5 实现 gyxx doctor 环境、解释器、CLI、路径和权限预检。
• P4.6 实现 gyxx acceptance status 和机器可读验收报告。
• P4.7 生成四个旧项目的源码迁移清单；每个文件记录来源哈希、目标路径和处置类型。

P5 分模块源码迁移

• P5.1 将 shop_intelligence 全部业务源码、资源和入口复制并改造到新模块；两个周任务可独立运行。
• P5.2 将 supply_chain 全部业务源码、资源和入口复制并改造到新模块；三个定时和全部手工入口可独立运行。
• P5.3 将 content_marketing 全部业务源码、资源和入口复制并改造到新模块；全部定时和手工入口可独立运行。
• P5.4 将 product_commerce 全部业务源码、资源、内置 vendors 和入口复制并改造到新模块；全部定时和手工入口可独立运行。
• P5.5 消除营销二维码写入商品项目、商品配置回退到 Auto Flow，以及任何跨业务模块内部导入。
• P5.6 将重复的飞书、PostgreSQL、Hermes、浏览器能力收敛为适配器，业务行为保持可回放对账。
  • 证据：src/gyxx_flow/adapters/integration.py、browser.py、bootstrap.py、runtime_exec.py；原飞书后端不变，数据库只允许云端，Hermes 只允许本机。
• P5.7 删除最终工作流中的 DeferredLegacyCommandStep，运行时不再要求 GYXX_LEGACY_*_ROOT。
• P5.8 全量入口分类完成：scheduled、manual、library、intentionally-excluded 均有证据，不遗漏脚本。

P6 自动化工程验收

• P6.1 21 个计划任务逐项有且只有一个新项目本地入口映射，没有意外新增。
• P6.2 源码、配置、启动命令和动态导入中均不存在四个旧项目的运行时依赖。
• P6.3 临时隐藏四个旧项目路径并更换项目根、数据根后，入口导入和 dry-run 全部通过。
• P6.4 每个迁移后的业务运行可从 run_id 追溯输入、输出、日志和外部写入。
• P6.5 迁移后的业务代码重跑不会重复写数据库、飞书或正式通知。
• P6.6 旧数据复制前后数量、大小和 SHA-256 一致。
• P6.7 迁移后的浏览器 Profile 和共享资源全部进入新数据根，且并发锁验证通过。
• P6.8 源码仓库敏感信息扫描通过。
• P6.9 全量测试、静态检查、源码覆盖清单和代码评审无阻断项。

P7 生产切换门禁

• P7.1 用户确认迁移基线、密钥轮换和第一个切换任务。
• P7.2 单次只切一个任务；旧任务只禁用、不删除。
• P7.3 回滚演练证明能关闭新任务并重新启用旧任务。
• P7.4 日任务真实连续成功 7 天。
• P7.5 周任务真实连续成功 2 个周期。
• P7.6 月任务指定历史月份回放通过。
• P7.7 生产通知无重复，数据库/飞书对账通过。
• P7.8 旧项目只读保留期满并取得退役确认。

P8 完成

• P8.1 所有上述检查项均有证据且已勾选。
• P8.2 按源码完整迁移的新口径重新生成 review.md 和 final_report.md。
• P8.3 按独立运行的新口径更新部署、迁移、回滚和日常运维手册。

P9 每脚本运行时隔离与外部系统统一边界

• P9.1 为 131 个可执行脚本建立显式、稳定、唯一的 22000..22999 CDP 端口分配。
• P9.2 每脚本独立 Profile、Cookie、storage state，全部位于 GYXX_DATA_ROOT/state/browser。
• P9.3 顶层 workflow、手工脚本和嵌套 Python/PowerShell 子脚本均按真实 script ID 重新绑定。
• P9.4 Cookie/storage state 支持首次为空、原子保存和后续运行复用，内容不进入日志或源码。
• P9.5 飞书保持原 lark-cli profile、身份和 OpenAPI 应用，不切换后端或凭据来源。
• P9.6 PG_*、DB_*、AUTOFLOW_PG_* 统一映射现有云端 PostgreSQL，拒绝本地回环数据库。
• P9.7 Hermes 保持本机 HTTP/CLI，非回环 Hermes URL 在业务调用前失败。
• P9.8 移除生产代码固定 9222/18801/18802/18803 和源码目录/临时 Profile，刷新迁移哈希。
• P9.9 Python 3.12 全量 294 passed，compileall、敏感信息、端口和旧根依赖扫描通过；历史 Ruff 证据保留。

P10 采集数据统一分层与目录收口

• P10.1 四个模块的新产物统一使用 <GYXX_DATA_ROOT>/data/{raw,normalized,curated,exports,evidence}/<module>，运行状态、日志和临时文件分别使用 state/、logs/、tmp/。
• P10.2 JSON、Markdown、CSV、XLS/XLSX、浏览器下载和截图均由模块路径边界定位，不写入源码目录、模块目录或当前工作目录。
• P10.3 var/data/raw/<module>/legacy 历史数据不移动、不删除、不改写，迁移前后文件数和总字节数一致。
• P10.4 四模块保留原业务脚本公开路径常量，统一改接共享 ModuleDataPaths，新增模块只需声明模块名即可扩展。
• P10.5 更换 GYXX_DATA_ROOT 后所有产物路径整体迁移，路径解析不创建目录、不访问四个旧项目。
• P10.6 路径红测、静态旁路扫描、全量测试、Ruff、compileall、敏感信息和旧根依赖扫描全部通过，清单与验收报告已刷新。

P11 四源项目增量 Bug 修复重新对齐（2026-07-28）

• P11.1 以四份来源清单 SHA-256 为基线，识别源端变更、新增、删除和目标端二次改造。
• P11.2 合并内容营销模块发布链接非空触发、星图普通失败不熔断和精确续跑修复。
• P11.3 合并商品模块“ERP 编码只读取天猫分组”的权威来源修复，并迁入波塞冬历史销量回填工具。
• P11.4 刷新来源/目标哈希、两份动态业务映射、迁移清单和新增回归测试，不纳入运行数据、临时文件或敏感状态。
• P11.5 定向测试、全量测试、compileall、敏感信息、旧根依赖和 doctor 通过；acceptance 正确保留 P6/P7 生产门禁为 incomplete，Ruff 因当前虚拟环境未安装而未执行。