# 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/`：部署、运行和回滚手册