# GYXX Flow

GYXX Flow 将原来分散在四个项目中的定时工作流和可执行脚本迁入一个可安装、可迁移的模块化项目：

- `content_marketing`：内容与营销采集
- `product_commerce`：商品、平台和经营分析
- `shop_intelligence`：店铺与竞店采集
- `supply_chain`：供应链采集与通知

运行时源码全部位于 `src/gyxx_flow/modules/<module>/runtime`。新项目不会从
`D:\yingxiaoyunying`、`D:\shop-data-flow`、`D:\product-collector-analyze-flow`
或 `E:\auto-flow` 导入或启动代码；这些旧项目仅保留为只读迁移来源和回滚基线。

## 安装与验证

要求 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>/` 并按脚本复用。现有 `data/raw/<module>/legacy`
历史数据只读保留，源码与可变数据不混放。

## 定时任务

```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 个任务定义和审核脚本，不会注册、禁用或修改任何系统任务。
生产切换必须遵循 `docs/migration-runbook.md` 的逐任务门禁。

## 关键文件

- `design.md`：目标架构和迁移边界
- `plan.md`：逐项验收清单
- `config/workflows.json`：工作流到新项目本地入口的映射
- `config/source-manifests/`：四个来源的逐文件哈希与处置清单
- `docs/`：部署、运行、迁移和回滚手册