# 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`：采购确认、补货、库存预警和采购单更新。

## 智能工作台（dsh-refact 分支）

`workbench/` 以 [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) 为
agent 底座，把现有工作流以 dsh 插件形式接入 Web UI：侧边栏选中任意工作流即可提问、
诊断、修复，支持监控告警与受控启动。使用与设计见 [workbench/README.md](workbench/README.md)
与 [docs/workbench.md](docs/workbench.md)。

```powershell
powershell -File workbench\bin\start-workbench.ps1
```

## 开发环境

```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)。