157 lines
7.6 KiB
Markdown
157 lines
7.6 KiB
Markdown
# GYXX Flow
|
||
|
||
GYXX Flow 是一个 Python 3.12 业务自动化平台，用 LangGraph 编排内容营销、商品经营、
|
||
店铺分析和供应链工作流，并由项目内 Python 调度器统一定时运行。
|
||
|
||
项目采用模块化单体：公共调度、工作流、数据和外部系统契约集中维护，业务实现留在各自
|
||
模块内。运行时不依赖其他源码目录，也不使用 Windows Task Scheduler。
|
||
|
||
## 能力概览
|
||
|
||
- 23 条调度工作流（内容 8、商品 8、店铺 4、供应链 3），当前全部启用。
|
||
- 工作流目录只保存定时任务；补采、重试、映射刷新和受保护写操作统一由手动命令承载。
|
||
- Python 常驻调度支持日、周、月、间隔日、错过触发补偿、防重复和优雅停止。
|
||
- 31 个显式命令覆盖工作流节点和手动补偿入口；138 条内部浏览器绑定继续使用唯一 CDP、Profile、Cookie 和 storage state。
|
||
- PostgreSQL 使用运行时注入的云端 DSN；地址、数据库、用户和密码均不在源码中提供默认值。
|
||
- Hermes 保持本机 `data-collector`、`data-analyzer` 两个角色；飞书保持既有身份和接口。
|
||
- JSON、Markdown、CSV、Excel、下载文件和截图统一写入可迁移的数据根。
|
||
- `run`、`backfill`、`scripts run` 默认 dry-run，只有 `--execute` 允许真实副作用。
|
||
|
||
## 目录
|
||
|
||
```text
|
||
config/ 工作流、时间表、脚本绑定和服务策略
|
||
deploy/ PostgreSQL 与调度服务部署文件
|
||
docs/ 部署、运维、源码同步和回滚手册
|
||
src/gyxx_flow/
|
||
adapters/ PostgreSQL、Hermes、飞书、浏览器适配边界
|
||
core/ 配置、运行上下文、日志、锁、产物
|
||
workflow/ LangGraph 模型、工厂与执行引擎
|
||
modules/<module>/ 四个业务域的工作流入口与内部实现
|
||
scheduler_service.py Python 常驻调度器
|
||
tests/ 项目级契约与回归测试
|
||
var/ 默认运行数据；不属于源码
|
||
```
|
||
|
||
业务模块：
|
||
|
||
- `content_marketing`：内容指标、达人、评论和营销报告。
|
||
- `product_commerce`：商品数据、人群画像、市场排行、主图和经营分析。
|
||
- `shop_intelligence`：店铺、竞店和京东自营业绩。
|
||
- `supply_chain`：采购确认、补货、库存预警和采购单更新。
|
||
|
||
## 开发环境
|
||
|
||
```powershell
|
||
cd D:\gyxx-flow
|
||
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-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
|
||
```
|
||
|
||
`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 schedule run --dry-run --once
|
||
uv run gyxx schedule status
|
||
uv run gyxx schedule run
|
||
```
|
||
|
||
时间规则集中在 `config/schedules.json`：23 条声明全部启用，统一使用
|
||
`Asia/Shanghai`；单个日计划可以声明多个执行时间。服务器只托管一个 `gyxx schedule run` 进程，不要把业务规则复制为
|
||
Windows 任务或多条 cron。状态位于 `state/scheduler`，子任务日志位于 `logs/scheduler`。
|
||
|
||
## 数据目录
|
||
|
||
开发环境默认数据根是项目下的 `var`；生产环境必须通过 `GYXX_DATA_ROOT` 外置，例如
|
||
Linux 使用 `/var/lib/gyxx-flow`。现有数据可以整体迁移，不应删除或写回源码目录。
|
||
|
||
```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/ 可清理临时文件
|
||
```
|
||
|
||
## 业务源码同步
|
||
|
||
源码同步采用清单驱动的三方哈希比较，状态检查默认只读。源目录只用于发现更新，不是项目
|
||
运行依赖：
|
||
|
||
```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)。
|