# GYXX Flow 运维手册

## 日常检查

```bash
uv run gyxx doctor --json
uv run gyxx schedule status
uv run gyxx list
```

Linux 服务同时检查：

```bash
systemctl status gyxx-flow.service
journalctl -u gyxx-flow.service --since today
```

工作流失败时，使用 `workflow_id`、业务日期和 `run_id` 对照 `<GYXX_DATA_ROOT>/logs`、运行记录、节点产物和副作用账本。

## 手工执行

```bash
uv run gyxx run <workflow_id> --date 2026-08-01
uv run gyxx run <workflow_id> --date 2026-08-01 --execute
uv run gyxx scripts list --json
uv run gyxx scripts run <command_id> --date 2026-08-01
uv run gyxx scripts run <command_id> --date 2026-08-01 --execute
```

`gyxx run` 只接受 22 个调度工作流；补采和维护操作使用 `gyxx scripts run`。两类入口都默认 dry-run，只有业务日期、凭据、浏览器登录态、PostgreSQL 和对应 Hermes 角色全部确认后才使用 `--execute`。

| 手动场景 | 命令 ID | 日期行为 |
|---|---|---|
| 内容映射重建 | `content.mapping.rebuild` | 业务日期只用于运行审计 |
| 内容失败任务重试 | `content.failed.retry` | 业务日期只用于运行审计 |
| 内容日报重跑 | `gyxx backfill content.metrics.daily` | 使用 `--from/--to` 指定日期范围 |
| 京东自营品牌单日回采 | `shop.jd_self_operated.collect_brand` | `--date` 自动成为起止日期 |
| 商品历史补采 | `product.backfill.run` | `--date` 自动成为 `--from/--to` |
| 商品评价补采 | `product.review.orchestrate` | `--date` 自动成为目标日期 |
| 采购单更新 | `supply.workflow.run` | 自动选择 `mcp-run purchase-order-update` |

命令的额外脚本参数使用可重复的 `--arg=<值>` 传入。`supply.workflow.run --execute` 会进入真实 ERP 修改链路，必须在任务文件、目标范围和回滚条件全部复核后执行。

### 主图周工作流

主图调度的唯一工作流 ID 是 `product.main_image.weekly`，每周日 08:30 启动。图同时运行 JD、TM 两个无依赖分支；一个平台失败不会取消、跳过或回滚另一个平台的采集、PG upsert 和飞书插入。两个分支全部结束后再汇总工作流状态：任一平台失败时整体状态为失败，并在错误摘要中标明具体平台和错误，另一平台已经成功的结果继续保留。

两个平台默认都在采集后执行飞书主图表插入和本地 PostgreSQL `main_image_creatives` upsert。执行前必须同时确认两套浏览器登录态、飞书身份和本地数据库；排障时分别检查 `jd`、`tmall` 节点以及对应插入脚本日志，不能只以采集文件存在判断双 sink 已完成。

## 调度操作

```bash
uv run gyxx schedule run --dry-run --once
uv run gyxx schedule status
sudo systemctl restart gyxx-flow.service
```

调度服务也只加载显式指定的受控环境文件：

```bash
uv run gyxx schedule run --env-file /etc/gyxx-flow/gyxx-flow.env
```

业务时间只在 `config/schedules.json` 中维护。systemd 负责进程守护，Python scheduler 负责全部业务定时；不要重复注册 cron、systemd timer 或 Windows 任务计划。

需要停用单个工作流时，优先修改该工作流的调度启用状态，先 dry-run，再重启服务。其他模块继续运行。

## 数据和浏览器状态

生产 `GYXX_DATA_ROOT` 必须位于源码目录之外，Linux 推荐 `/var/lib/gyxx-flow`：

- `data/raw/<module>`：原始采集结果，不按临时文件清理。
- `data/normalized`、`data/curated`：清洗、标准化和聚合数据。
- `data/exports`：Markdown、Excel 等交付文件。
- `state/browser/<module>/<script>`：独立 Cookie、Profile 和 storage state。
- `state/scheduler`、`state/locks`、运行账本：调度和幂等状态。
- `tmp`：仅存放可重建临时文件。

项目不会自动搬动或删除已有 `var/`。迁移数据根时应停止调度器，完整备份和复制原目录，修改环境变量后依次运行 doctor、dry-run 和一次指定日期的对账执行。

## 清理和保留

可以在确认没有任务运行后清理缓存、`tmp`、dry-run 目录和可重建构建产物。以下内容不得作为普通缓存删除：

- `data/raw` 原始数据；
- `state/scheduler` 和资源锁；
- EffectLedger、运行 journal 和浏览器状态；
- 尚未核对或尚未导入数据库的 Excel、JSON、Markdown 导出。

旧 Windows 任务计划 XML 只属于历史部署证据，确认 Python scheduler 已接管且完成备份后再归档。

## 故障处理

1. 按 `workflow_id`、业务日期和 `run_id` 定位失败节点。
2. 检查本机 PostgreSQL、对应 Hermes 角色、飞书身份和脚本专属 CDP 端口。
3. 检查 Cookie/storage state 是否存在且未失效。
4. 修复后按同一业务日期重跑，依靠唯一键和 EffectLedger 防止重复写入。
5. 仍失败时停用该工作流，不停止其他模块。

### 副作用账本对账

正式节点失败后，EffectLedger 会保留 `ambiguous` 回执，避免不确定状态下重复写库或重复
发送飞书。不要删除或手工修改回执文件。只有先从 PostgreSQL、飞书消息回执和目标文档
确认该节点是否已产生外部效果，才可执行审计式对账：

```bash
uv run gyxx effects reconcile <workflow_id> \
  --date 2026-08-04 \
  --step <step_id> \
  --expected-run-id <原失败run_id> \
  --action retry \
  --operator <操作人> \
  --reason <重试原因> \
  --evidence <已核对的证据> \
  --execute
```

`retry` 仅在证明确实没有完成外部写入时允许同日重试；若证据表明外部写入已经完成，使用
`--action applied`。命令只接受当前仍为 `ambiguous` 且 `run_id` 精确匹配的回执，并保留
操作人、原因、证据和时间，不能用于绕过正在执行的节点。

## 回滚

代码回滚时先停止 `gyxx-flow.service`，切换到上一个已验收版本，重新安装锁定依赖并执行 doctor 和调度 dry-run；确认后再启动服务。不得用代码回滚覆盖 `GYXX_DATA_ROOT`。

数据撤销必须针对明确表、业务键和 `run_id`，先备份 PostgreSQL，再执行经过复核的 SQL。不得删除整个数据库、数据卷或数据根。

浏览器状态异常时，只备份并处理目标脚本的 `state/browser/<module>/<script>`，不要清理其他脚本状态。调度状态异常时先停止唯一调度进程并备份 `state/scheduler`，不要同时启动第二实例。

## 业务源码同步

外部业务源码目录只用于发现更新，GYXX Flow 运行时不导入或挂载这些目录。只读检查：

```powershell
uv run gyxx sources status `
  --source-root content_marketing=<内容源码目录> `
  --source-root product_commerce=<商品源码目录> `
  --source-root shop_intelligence=<店铺源码目录> `
  --source-root supply_chain=<供应链源码目录> `
  --json
```

只有未转换、无冲突的 `source_changed` 可以显式执行：

```powershell
uv run gyxx sources apply ... --execute --json
```

经过统一路径、数据库、Hermes、飞书或浏览器适配的文件必须人工合并并运行回归测试。新增可执行脚本还需登记工作流、调度和独立 CDP 绑定。同步完成后执行测试、doctor、acceptance 和 source status；真实采集不在源码同步过程中自动触发。