100 lines
4.2 KiB
Markdown
100 lines
4.2 KiB
Markdown
# GYXX Flow
|
||
|
||
GYXX Flow 是面向业务自动化的模块化工作流平台，统一管理数据采集、经营分析、供应链处理、定时调度和外部系统集成。
|
||
|
||
- `content_marketing`：内容与营销采集
|
||
- `product_commerce`：商品、平台和经营分析
|
||
- `shop_intelligence`：店铺与竞店采集
|
||
- `supply_chain`：供应链采集与通知
|
||
|
||
项目采用模块化单体结构。框架能力位于 `src/gyxx_flow`，各业务模块运行时代码位于
|
||
`src/gyxx_flow/modules/<module>/runtime`。工作流、脚本、数据目录和外部系统配置均由
|
||
统一入口管理，同时保持模块间高内聚、低耦合。
|
||
|
||
## 核心能力
|
||
|
||
- 声明式工作流目录、依赖编排、超时、重试和失败恢复
|
||
- 计划任务生成、漂移检查和逐任务部署
|
||
- 手工执行、定时执行、日期回填、dry-run 和 shadow 模式
|
||
- 每次运行使用稳定的 `run_id`，记录步骤状态、日志、产物和外部写入
|
||
- JSON、Markdown、CSV、Excel、下载文件和截图统一分层存储
|
||
- 每个浏览器脚本独立 CDP 端口、Profile、Cookie 和 storage state
|
||
- 飞书、云端 PostgreSQL、本机 Hermes 和浏览器能力统一接入
|
||
|
||
## 安装与验证
|
||
|
||
要求 Python 3.12，推荐使用 `uv`：
|
||
|
||
```powershell
|
||
cd D:\gyxx-flow
|
||
uv sync --python 3.12 --extra test
|
||
uv run pytest
|
||
uv run gyxx doctor --json
|
||
uv run gyxx acceptance status --json
|
||
```
|
||
|
||
## 运行工作流
|
||
|
||
```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
|
||
```
|
||
|
||
`run`、`backfill` 和 `scripts run` 默认都是无副作用 dry-run；只有显式加
|
||
`--execute` 才会启动项目内的业务脚本。
|
||
|
||
## 运行任意脚本
|
||
|
||
```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
|
||
```
|
||
|
||
脚本 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。
|
||
|
||
## 数据目录
|
||
|
||
默认数据根为 `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>/` 并按脚本复用。源码与运行数据相互隔离，部署或更换
|
||
数据磁盘时只需调整环境变量。
|
||
|
||
## 定时任务
|
||
|
||
```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
|
||
```
|
||
|
||
该命令只生成 21 个任务定义和审核脚本，不会直接注册、禁用或修改系统任务。
|
||
生产启用时应先执行环境检查和 dry-run，再按工作流逐项应用调度配置。
|
||
|
||
## 关键文件
|
||
|
||
- `design.md`：系统架构和模块边界
|
||
- `plan.md`：逐项验收清单
|
||
- `config/workflows.json`：工作流定义与本地执行入口
|
||
- `config/schedules.json`：定时调度配置
|
||
- `config/runtime-bindings.json`：脚本 CDP 端口与外部服务策略
|
||
- `docs/`：部署、运行和回滚手册
|