feat: complete production workflow migration

README.md

@@ -1,99 +1,156 @@
 # GYXX Flow
 
-GYXX Flow 是面向业务自动化的模块化工作流平台，统一管理数据采集、经营分析、供应链处理、定时调度和外部系统集成。
+GYXX Flow 是一个 Python 3.12 业务自动化平台，用 LangGraph 编排内容营销、商品经营、
+店铺分析和供应链工作流，并由项目内 Python 调度器统一定时运行。
 
-- `content_marketing`：内容与营销采集
-- `product_commerce`：商品、平台和经营分析
-- `shop_intelligence`：店铺与竞店采集
-- `supply_chain`：供应链采集与通知
+项目采用模块化单体：公共调度、工作流、数据和外部系统契约集中维护，业务实现留在各自
+模块内。运行时不依赖其他源码目录，也不使用 Windows Task Scheduler。
 
-项目采用模块化单体结构。框架能力位于 `src/gyxx_flow`，各业务模块运行时代码位于
-`src/gyxx_flow/modules/<module>/runtime`。工作流、脚本、数据目录和外部系统配置均由
-统一入口管理，同时保持模块间高内聚、低耦合。
+## 能力概览
 
-## 核心能力
+- 23 条调度工作流（内容 8、商品 8、店铺 4、供应链 3），当前全部启用。
+- 工作流目录只保存定时任务；补采、重试、映射刷新和受保护写操作统一由手动命令承载。
+- Python 常驻调度支持日、周、月、间隔日、错过触发补偿、防重复和优雅停止。
+- 31 个显式命令覆盖工作流节点和手动补偿入口；136 条内部浏览器绑定继续使用唯一 CDP、Profile、Cookie 和 storage state。
+- PostgreSQL 使用运行时注入的云端 DSN；地址、数据库、用户和密码均不在源码中提供默认值。
+- Hermes 保持本机 `data-collector`、`data-analyzer` 两个角色；飞书保持既有身份和接口。
+- JSON、Markdown、CSV、Excel、下载文件和截图统一写入可迁移的数据根。
+- `run`、`backfill`、`scripts run` 默认 dry-run，只有 `--execute` 允许真实副作用。
 
-- 声明式工作流目录、依赖编排、超时、重试和失败恢复
-- 计划任务生成、漂移检查和逐任务部署
-- 手工执行、定时执行、日期回填、dry-run 和 shadow 模式
-- 每次运行使用稳定的 `run_id`，记录步骤状态、日志、产物和外部写入
-- JSON、Markdown、CSV、Excel、下载文件和截图统一分层存储
-- 每个浏览器脚本独立 CDP 端口、Profile、Cookie 和 storage state
-- 飞书、云端 PostgreSQL、本机 Hermes 和浏览器能力统一接入
+## 目录
 
-## 安装与验证
+```text
+config/                         工作流、时间表、脚本绑定和服务策略
+deploy/                         PostgreSQL 与调度服务部署文件
+docs/                           部署、运维、源码同步和回滚手册
+src/gyxx_flow/
+  adapters/                     PostgreSQL、Hermes、飞书、浏览器适配边界
+  core/                         配置、运行上下文、日志、锁、产物
+  workflow/                     LangGraph 模型、工厂与执行引擎
+  modules/<module>/             四个业务域的工作流入口与内部实现
+  scheduler_service.py          Python 常驻调度器
+tests/                          项目级契约与回归测试
+var/                            默认运行数据；不属于源码
+```
 
-要求 Python 3.12，推荐使用 `uv`：
+业务模块：
+
+- `content_marketing`：内容指标、达人、评论和营销报告。
+- `product_commerce`：商品数据、人群画像、市场排行、主图和经营分析。
+- `shop_intelligence`：店铺、竞店和京东自营业绩。
+- `supply_chain`：采购确认、补货、库存预警和采购单更新。
+
+## 开发环境
 
 ```powershell
 cd D:\gyxx-flow
-uv sync --python 3.12 --extra test
+uv sync --python 3.12 --group dev
+uv run ruff check src tests
 uv run pytest
+uv build
 uv run gyxx doctor --json
 uv run gyxx acceptance status --json
 ```
 
-## 运行工作流
+## 云端 PostgreSQL
+
+由密钥系统向当前进程注入完整云端 DSN：
+
+```powershell
+# 示例只展示变量名；真实 DSN 由部署环境提供
+$env:GYXX_POSTGRES_DSN = '<secret-manager-provided-postgresql-dsn>'
+```
+
+应用优先从 `GYXX_POSTGRES_DSN` 读取云端连接，并映射到各业务模块使用的 `PG_*`、`DB_*` 和
+`AUTOFLOW_PG_*` 变量。源码、示例文件和运行报告均不保存真实地址或凭据；云端模式会拒绝回环数据库地址。
+
+## 本机 Hermes
+
+运行时使用两个本机业务 API base：
+
+- analyzer：`http://127.0.0.1:8642/v1`
+- collector：`http://127.0.0.1:8643/v1`
+
+`28790/28791` 不作为工作流业务端点。
+
+密钥通过 `GYXX_HERMES_API_KEY` 注入。非回环 Hermes 地址会在业务脚本启动前被拒绝。
+不使用 Hermes 的纯采集工作流可在无 AI 环境运行；依赖分析或通知的工作流需要对应本机
+角色可用。
+
+## 工作流与脚本
 
 ```powershell
 uv run gyxx list
-uv run gyxx run product.daily --date 2026-07-27
-uv run gyxx run product.daily --date 2026-07-27 --execute
+uv run gyxx run product.daily --date 2026-08-01
+uv run gyxx run product.daily --date 2026-08-01 --execute
+uv run gyxx scripts list --module shop_intelligence
+uv run gyxx scripts run shop.jd_self_operated.collect_product --date 2026-08-01
 ```
 
-`run`、`backfill` 和 `scripts run` 默认都是无副作用 dry-run；只有显式加
-`--execute` 才会启动项目内的业务脚本。
+`gyxx list` 只展示调度工作流。手动补采和维护操作使用 `gyxx scripts run`；已配置的业务日期参数会从 `--date` 自动渲染，仍然只有显式添加 `--execute` 才会真实执行。
 
-## 运行任意脚本
+主图定时采集只注册为 `product.main_image.weekly`：每周日 08:30 同时启动京东和天猫两个独立分支。每个平台都在各自的采集完成后调用对应插入脚本，分别写入云端 PostgreSQL `main_image_creatives` 和飞书主图表；任一分支失败都不会取消、跳过或回滚另一分支的采集与写入，两个分支结束后工作流再汇总状态，并在失败摘要中标明具体平台和错误。真实写入仍受 `--execute`、凭据、登录态和副作用门禁约束。
+
+| 场景 | 当前入口 |
+|---|---|
+| 内容映射重建 | `gyxx scripts run content.mapping.rebuild --date <日期>` |
+| 内容失败任务重试 | `gyxx scripts run content.failed.retry --date <日期>` |
+| 内容日报按日期重跑 | `gyxx backfill content.metrics.daily --from <日期> --to <日期>` |
+| 京东自营品牌单日回采 | `gyxx scripts run shop.jd_self_operated.collect_brand --date <日期>` |
+| 商品历史补采 | `gyxx scripts run product.backfill.run --date <日期>` |
+| 商品评价补采 | `gyxx scripts run product.review.orchestrate --date <日期>` |
+| 采购单更新 | `gyxx scripts run supply.workflow.run --date <日期>` |
+
+每次运行生成稳定 `run_id`，并记录图节点状态、日志、产物、资源锁和外部副作用账本。
+业务脚本通过共享适配器取得项目根、数据根、业务日期和服务配置，不应导入其他业务
+模块的内部代码。旧 `module:entry` 脚本 ID 暂时保留为兼容别名。
+
+## Python 定时调度
 
 ```powershell
-uv run gyxx scripts list
-uv run gyxx scripts list --module content_marketing
-uv run gyxx scripts run content_marketing:run_all.py --date 2026-07-27
-uv run gyxx scripts run content_marketing:run_all.py --date 2026-07-27 --execute
+uv run gyxx schedule run --dry-run --once
+uv run gyxx schedule status
+uv run gyxx schedule run
 ```
 
-脚本 ID 格式为 `<module>:<runtime 内相对路径>`。Python、BAT/CMD 和
-PowerShell 入口均受统一项目根、数据根、业务日期、run_id 和 shadow 环境约束。
-
-## 浏览器与外部系统绑定
-
-`config/runtime-bindings.json` 为当前 131 个脚本各自分配固定且唯一的 CDP 端口。
-无论从 workflow、`scripts run` 还是嵌套脚本启动，目标脚本都会重新取得自己的端口和
-`state/browser/<module>/<script>/` 下的 Profile、Cookie、storage state；同一脚本下次
-运行会复用登录态，不同脚本不会共享浏览器状态。
-
-飞书继续走原来的 lark-cli/OpenAPI 身份；数据库继续走现有云端 PostgreSQL；Hermes
-继续走本机服务。运行时会拒绝 localhost 数据库和非本机 Hermes 地址。不要在源码或
-`runtime-bindings.json` 中写入 Cookie、数据库密码、飞书密钥或 Hermes token。
+时间规则集中在 `config/schedules.json`：23 条声明全部启用，统一使用
+`Asia/Shanghai`；单个日计划可以声明多个执行时间。服务器只托管一个 `gyxx schedule run` 进程，不要把业务规则复制为
+Windows 任务或多条 cron。状态位于 `state/scheduler`，子任务日志位于 `logs/scheduler`。
 
 ## 数据目录
 
-默认数据根为 `D:\gyxx-flow\var`，可用 `GYXX_DATA_ROOT` 配置到其他磁盘或服务器目录。
-业务数据按模块写入 `data/raw`、`data/normalized`、`data/curated`、`data/exports`
-和 `data/evidence`；运行状态、日志和临时文件分别进入 `state`、`logs` 和 `tmp`。
-原始 JSON/CSV/XLS/XLSX/下载文件进 raw，清洗结果进 normalized，聚合数据进 curated，
-最终 Markdown/Excel 报告进 exports。浏览器 Profile、Cookie 和 storage state 位于
-`state/browser/<module>/<script>/` 并按脚本复用。源码与运行数据相互隔离，部署或更换
-数据磁盘时只需调整环境变量。
+开发环境默认数据根是项目下的 `var`；生产环境必须通过 `GYXX_DATA_ROOT` 外置，例如
+Linux 使用 `/var/lib/gyxx-flow`。现有数据可以整体迁移，不应删除或写回源码目录。
 
-## 定时任务
-
-```powershell
-uv run gyxx schedule plan `
-  --output D:\gyxx-flow\var\schedule-plan\candidate `
-  --start-date 2026-07-27 `
-  --python-executable D:\gyxx-flow\.venv\Scripts\python.exe
+```text
+<GYXX_DATA_ROOT>/
+  data/raw/<module>/          原始 JSON/CSV/XLS/XLSX、下载文件、截图
+  data/normalized/<module>/   清洗与标准化结果
+  data/curated/<module>/      聚合和业务事实
+  data/exports/<module>/      Markdown、Excel 等最终报告
+  data/evidence/<module>/     验收及对账证据
+  state/browser/<module>/     每脚本 Profile、Cookie、storage state
+  state/                      调度、工作流和幂等状态
+  logs/                       运行日志
+  tmp/                        可清理临时文件
 ```
 
-该命令只生成 21 个任务定义和审核脚本，不会直接注册、禁用或修改系统任务。
-生产启用时应先执行环境检查和 dry-run，再按工作流逐项应用调度配置。
+## 业务源码同步
 
-## 关键文件
+源码同步采用清单驱动的三方哈希比较，状态检查默认只读。源目录只用于发现更新，不是项目
+运行依赖：
 
-- `design.md`：系统架构和模块边界
-- `plan.md`：逐项验收清单
-- `config/workflows.json`：工作流定义与本地执行入口
-- `config/schedules.json`：定时调度配置
-- `config/runtime-bindings.json`：脚本 CDP 端口与外部服务策略
-- `docs/`：部署、运行和回滚手册
+```powershell
+uv run gyxx sources status `
+  --source-root content_marketing=<内容源码目录> `
+  --source-root product_commerce=<商品源码目录> `
+  --source-root shop_intelligence=<店铺源码目录> `
+  --source-root supply_chain=<供应链源码目录>
+```
+
+只有未转换、无冲突的源端单边变化可通过 `sources apply --execute` 自动复制；经过统一适配
+的文件必须人工复核并更新来源/目标哈希。Cookie、Profile、凭据、日志和采集结果不会进入
+源码同步清单。
+
+详细操作见 [架构说明](docs/architecture.md)、[部署手册](docs/deployment.md)、
+[运维手册](docs/runbook.md) 和 [验收报告](docs/acceptance-report.md)。