140 lines
8.3 KiB
Markdown
140 lines
8.3 KiB
Markdown
# GYXX Flow 工作流合并验收报告
|
||
|
||
验收日期：2026-08-01
|
||
|
||
## 验收结论
|
||
|
||
项目工作流目录已收敛为 21 个真实且启用的调度任务。每个调度任务对应一个 LangGraph 工作流；补采、重试、映射刷新和受保护写操作不再重复注册为工作流，统一通过显式命令执行。
|
||
|
||
重复且原本禁用的 `content.self_operated.weekly` 已删除，其自营映射、B 站、蝉妈妈和指标同步脚本继续由每日 `content.metrics.daily` 调用。京东与天猫主图周采集收敛为唯一工作流 `product.main_image.weekly`，其余时间规则和失败隔离边界保持不变。
|
||
|
||
## 数量总览
|
||
|
||
| 项目 | 数量 | 说明 |
|
||
|---|---:|---|
|
||
| 业务模块 | 4 | 内容营销、商品经营、店铺洞察、供应链 |
|
||
| 调度工作流 | 21 | 内容 8、商品 7、店铺 3、供应链 3 |
|
||
| 启用状态 | 21 / 21 | 所有当前调度均启用 |
|
||
| LangGraph 节点 | 29 | 所有调度工作流均声明显式节点 |
|
||
| 公开命令 | 31 | 覆盖工作流节点及手动补偿入口 |
|
||
| 浏览器状态绑定 | 136 | 唯一 CDP、Profile、Cookie 与 storage state |
|
||
| 源同步清单 | 233 | 运行时不依赖外部源码目录 |
|
||
|
||
## 工作流清单
|
||
|
||
所有时间均使用 `Asia/Shanghai`。
|
||
|
||
### 内容营销（8）
|
||
|
||
| 工作流 | 时间 | 用途 |
|
||
|---|---|---|
|
||
| `content.cooperations.daily` | 每日 09:00 | 刷新业务映射并同步合作记录。 |
|
||
| `content.marketing_report.daily` | 每日 10:00 | 生成营销日报并按现有飞书策略发送。 |
|
||
| `content.metrics.daily` | 每日 22:00 | 依次完成合作达人、自营映射、自营 B 站、蝉妈妈和指标同步。 |
|
||
| `content.relogin.weekly` | 周五 10:00 | 维护各内容平台可复用登录状态。 |
|
||
| `content.comments.weekly` | 周日 12:00 | 并行补采 B 站、小红书和抖音评论。 |
|
||
| `content.summary.weekly` | 周二 10:00 | 生成跨平台内容周汇总。 |
|
||
| `content.summary.monthly` | 每月 1 日 08:00 | 生成跨平台内容月汇总。 |
|
||
| `content.creator_report.monthly` | 每月 1 日 08:30 | 生成达人月度报告。 |
|
||
|
||
### 店铺洞察（4）
|
||
|
||
| 工作流 | 时间 | 用途 |
|
||
|---|---|---|
|
||
| `shop.metrics.weekly` | 周一 12:00 | 并行采集京东、抖音和天猫店铺经营指标。 |
|
||
| `shop.competitor.weekly` | 周一 12:30 | 采集京东、抖音竞店数据并形成对比结果。 |
|
||
| `shop.douyin_price_appeal` | 每日 08:00、16:00、22:00 | 复用店铺周采集登录态，扫描全部待改价列表并对可申诉商品提交固定原因申诉。 |
|
||
| `shop.jd_self_operated.daily` | 每日 16:00，业务日 -1 | 京东自营数据从下午开始推送；预留刷新窗口后先采集品牌，再采集商品，品牌失败后商品仍继续。 |
|
||
|
||
### 商品经营（7）
|
||
|
||
| 工作流 | 时间 | 用途 |
|
||
|---|---|---|
|
||
| `product.daily` | 每日 08:40，业务日 -1 | 编排 ERP 与三平台采集、分析、导出和入库。 |
|
||
| `product.persona.daily` | 每日 10:00 | 并行采集天猫、抖音和京东商品画像。 |
|
||
| `product.import.daily` | 每日 19:00 | 幂等导入三平台商品日报。 |
|
||
| `product.alert.daily` | 每日 23:00 | 独立检测商品异常并按条件通知。 |
|
||
| `product.style_analysis.interval` | 每 3 天 11:00 | 使用本地 Hermes 分析到期款式。 |
|
||
| `product.main_image.weekly` | 周日 08:30 | 并行启动 JD、TM 两个独立主图分支，各自写入本地 PG 和飞书；一个平台失败不阻断另一平台，全部结束后汇总整体状态和平台级具体错误。 |
|
||
| `product.market_rank` | 周一 10:00 | 并行采集天猫、京东、抖音市场排行并汇总归档。 |
|
||
|
||
### 供应链（3）
|
||
|
||
| 工作流 | 时间 | 用途 |
|
||
|---|---|---|
|
||
| `supply.replenishment_alert.daily` | 每日 07:00 | 检测补货风险并执行告警链路。 |
|
||
| `supply.purchase_confirmation.daily` | 每日 08:00 | 采集采购确认数据，经本地 Hermes 分析后通知。 |
|
||
| `supply.replenishment.weekly` | 周一 08:00 | 采集并分析周度补货数据。 |
|
||
|
||
## 手动能力合并结果
|
||
|
||
| 原目录入口 | 当前入口 | 合并结果 |
|
||
|---|---|---|
|
||
| `content.mapping.refresh` | `content.mapping.rebuild` | 改为内容映射重建命令。 |
|
||
| `content.retry_failed` | `content.failed.retry` | 改为失败任务重试命令。 |
|
||
| `content.metrics.backfill` | `gyxx backfill content.metrics.daily` | 合并到标准内容日报图，按日期范围重跑。 |
|
||
| `shop.jd_self_operated.history` | `shop.jd_self_operated.collect_brand` | 保留品牌单日回采；`--date` 自动渲染起止日期。 |
|
||
| `product.backfill` | `product.backfill.run` | 保留商品补采语义；`--date` 自动渲染 `--from/--to`。 |
|
||
| `product.review_collection` | `product.review.orchestrate` | 保留评价补采；`--date` 自动渲染目标日期。 |
|
||
| `supply.purchase_order_update` | `supply.workflow.run` | 保留受保护 ERP 更新；自动选择 `mcp-run purchase-order-update`。 |
|
||
|
||
`content.self_operated.weekly` 因与每日指标工作流重复且原调度已禁用而删除；底层自营脚本继续保留。`product.weekly_aggregate.documented_missing` 没有对应脚本和调度任务，也只在历史证据中保留说明。
|
||
|
||
## 整体架构
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
S["Python Scheduler"] --> C["21 Scheduled Workflows"]
|
||
U["CLI Manual Commands"] --> M["31 Explicit Commands"]
|
||
C --> G["LangGraph StateGraph"]
|
||
G --> B1["content_marketing"]
|
||
G --> B2["product_commerce"]
|
||
G --> B3["shop_intelligence"]
|
||
G --> B4["supply_chain"]
|
||
M --> B1
|
||
M --> B2
|
||
M --> B3
|
||
M --> B4
|
||
B1 --> A["Shared Adapters"]
|
||
B2 --> A
|
||
B2 --> MI["product.main_image.weekly"]
|
||
MI -->|"parallel independent branch"| JD["JD collect + PG + Feishu"]
|
||
MI -->|"parallel independent branch"| TM["TM collect + PG + Feishu"]
|
||
B3 --> A
|
||
B4 --> A
|
||
A --> P["Local PostgreSQL"]
|
||
A --> H["Local Hermes Collector / Analyzer"]
|
||
A --> F["Existing Feishu Integration"]
|
||
A --> R["Per-script Browser State"]
|
||
G --> J["Journal / Locks / Effect Ledger"]
|
||
G --> D["Layered Data Layout"]
|
||
```
|
||
|
||
业务模块只依赖共享 `core`、`workflow`、`adapters` 和 `ops` 契约，不跨模块导入内部实现。时间规则集中在 `config/schedules.json`，生产环境只守护一个 `gyxx schedule run` 进程。
|
||
|
||
## 数据与外部系统边界
|
||
|
||
- PostgreSQL：`127.0.0.1:5432/gyxx_super_data`，非回环地址会被拒绝。
|
||
- Hermes：本机 analyzer 与 collector 两个角色，分别使用独立 API 和 gateway。
|
||
- 飞书：保持现有身份、应用和业务调用方式，凭据只从运行环境注入。
|
||
- 浏览器：每个脚本独立 CDP 端口、Profile、Cookie 和 storage state。
|
||
- 数据：JSON、CSV、Markdown、Excel、下载文件和截图按模块及处理阶段写入 `GYXX_DATA_ROOT`。
|
||
|
||
## 工程验收
|
||
|
||
全量回归结果为 `940 passed, 1 skipped`。
|
||
|
||
本次主图合并、失败语义与双 sink 静态定向回归为 `21 passed`；自动化测试没有连接生产 PostgreSQL，也没有执行真实飞书写入。另已在本地 `gyxx_super_data` 将 `main_image_creatives` 主键迁移为四列，3681 条存量数据数量不变；同键 JD/TM 双行事务探针成功并已回滚测试数据。
|
||
|
||
- [x] 工作流目录仅包含 21 个有效调度任务，且与 21 条时间规则一一对应。
|
||
- [x] 21 个当前调度全部启用，重复禁用项已删除。
|
||
- [x] 主图调度仅保留 `product.main_image.weekly`，JD、TM 以独立资源并行编排；分支失败隔离、成功写入保留、最终状态汇总和平台级错误明细已有配置和自动化测试覆盖。
|
||
- [x] 京东、天猫入口默认均调用飞书插入与本地 PG upsert 链路；相关 21 项定向测试通过，不代表已执行真实外部写入。
|
||
- [x] 本地 PG 存量主键已完成平台隔离迁移；同日、同款、同图片名的京东与天猫记录可同时存在。
|
||
- [x] 7 个手动能力已转为命令或合并进标准工作流，默认仍为 dry-run。
|
||
- [x] 单日回采、商品补采、评价补采和采购单更新具备安全默认参数。
|
||
- [x] 不可执行历史项不再参与目录、注册和数量统计。
|
||
- [x] 最终全量测试、Ruff、构建、doctor、调度 dry-run 与敏感信息扫描通过。
|
||
|
||
真实浏览器登录、飞书写入、Hermes 分析和 ERP 修改不由本次结构合并自动触发。各业务链路最近一次实跑结果与未通过原因见 [工作流验收测试报告](workflow-acceptance-test-report.md)。
|