wangyunlong
dc8be88e60
workflows/schedules/commands/notification-routing 与 source-manifests 四模块 清单同步登录统一化与新工作流(product.hk_anpei_public_inventory.daily 等)； docs 运维手册、控制台与耗时分布文档、CI 关键脚本清单、AGENTS 指南更新； 测试与模块注册对齐。
167 lines
11 KiB
Markdown
167 lines
11 KiB
Markdown
# 工作流控制台
|
||
|
||
GYXX Flow 自带一个只依赖 Python 运行时的工作流控制台。页面从当前工作流目录、定时配置、
|
||
调度状态和运行索引动态取数，不维护第二套工作流清单。
|
||
|
||
## 启动
|
||
|
||
```powershell
|
||
cd D:\gyxx-flow
|
||
uv run gyxx console
|
||
```
|
||
|
||
生产凭据不会从源码或任意 `.env` 自动发现。需要真实运行时，必须显式指定受控环境文件；
|
||
已经由服务环境注入的同名变量优先，不会被文件覆盖：
|
||
|
||
```powershell
|
||
uv run gyxx console --env-file D:\secure\gyxx-flow.env
|
||
```
|
||
|
||
香港客服库存工作流还需要聚水潭应用密钥。Windows 生产控制台必须额外加载受保护的聚水潭环境文件，
|
||
这样控制台发起的手动执行也能取得凭据；调度器和控制台应加载相同的环境文件集合：
|
||
|
||
```powershell
|
||
uv run gyxx console `
|
||
--env-file D:\product-collector-analyze-flow\.env `
|
||
--env-file D:\product-collector-analyze-flow\private-secrets\jushuitan.env
|
||
```
|
||
|
||
商品经营正式执行会在启动子进程前校验云端 PostgreSQL 和该工作流实际需要的运行时配置。
|
||
需要 Hermes 分析或业务通知的工作流仍会校验 `hermes-analyzer` lark-cli user 身份和负责人
|
||
通知路由；天猫/京东视频上传则校验 `STYLE_ANALYSIS_LLM_BASE_URL`（或
|
||
`GYXX_DIRECT_LLM_BASE_URL`）与对应 API Key，直接调用 MiniMax，不解析或转发 Hermes API
|
||
凭据；内容周度/月度汇总校验 `CONTENT_ANALYSIS_LLM_API_KEY`，使用
|
||
`CONTENT_ANALYSIS_LLM_BASE_URL` 指定的 MiniMax Anthropic 兼容接口。缺少任一实际必需项时，
|
||
前端会返回明确的配置错误，不会创建一个注定失败的“正式运行”。
|
||
运行调度服务的 Windows/NSSM 账户必须持有同一 profile 的有效 user 授权与
|
||
`im:message.send_as_user`、`im:message` scope。
|
||
|
||
默认地址为 `http://127.0.0.1:8765`。控制台进程与调度进程职责分离；服务器仍只运行一个
|
||
项目内调度服务：
|
||
|
||
```powershell
|
||
uv run gyxx schedule run
|
||
```
|
||
|
||
页面可以：
|
||
|
||
- 在顶部查看调度服务状态；显示“调度服务未运行”时，可点击“启动调度器”拉起唯一的常驻 Python 调度进程。启动会继承控制台的 `--env-file`，并在页面中持续刷新真实服务状态；若已有到期但尚未执行的计划，调度器会按现有补偿窗口评估并启动对应任务；
|
||
- 按内容营销、商品经营、店铺洞察和供应链分别展示全部工作流；
|
||
- 查看工作流定义、执行步骤、定时规则和下一次启动时间；
|
||
- 修改定时类型、一个或多个时间、日期规则、启停状态和业务日期偏移；
|
||
- 配置实际支持业务通知的工作流、发送应用和一个或多个收件人；
|
||
- 在云端数据库中增删改查业务目标表、平台画像目标和启停状态；款式名、ERP 款式编码、各平台商品编码及大/小 NFC 数统一在“产品生命进程”维护；
|
||
- 查看昨天或指定执行日的逐工作流运行汇总、异常原因和修复建议；
|
||
- 以安全预演或正式执行方式手动触发已注册工作流；
|
||
- 查看最近运行状态、步骤统计和经过脱敏的错误详情。
|
||
|
||
定时配置保存到 `config/schedules.json`。常驻 Python 调度器会在下一次轮询时重新验证并
|
||
加载配置，不需要创建或修改 Windows Task Scheduler 任务。若新规则在错过触发补偿窗口
|
||
内已经到期，下一次轮询可能立即启动该工作流。
|
||
|
||
## 商品与款式配置
|
||
|
||
侧栏“商品与款式配置”维护商品经营和内容营销共用的动态目标配置。页面提供款式、品牌、平台、
|
||
启停状态、平台画像和各业务飞书目标表的查询与 CRUD；款式身份字段以产品生命进程为准，动态表
|
||
中的历史 ERP/商品 ID 只作为兼容快照。保存后从下一次新启动的工作流生效。编辑和删除带行版本
|
||
校验，旧页面不能覆盖其他操作员已保存的新版本。
|
||
|
||
配置存储在云端 PostgreSQL，旧飞书配置主表不再属于运行路径。首次迁移、字段模型、受影响
|
||
工作流和失败回退边界见 [工作流动态配置](dynamic-workflow-config.md)。
|
||
|
||
## 每日运行汇总
|
||
|
||
侧栏“每日运行汇总”默认按 `config/schedules.json` 的时区读取昨天。统计窗口以工作流实际
|
||
`started_at` 所在的本地执行日为准，不会把“昨天执行、业务日期为前天”的采集任务漏掉。
|
||
汇总范围包含当天应由调度器触发的工作流，以及当天实际发生过正式执行、安全预演或控制台/
|
||
调度日志的工作流。
|
||
|
||
成功、失败、取消、仍在运行、计划未执行和失败后恢复等状态由运行索引、`run.json` 与计划
|
||
时点确定，大模型无权改写这些事实。分析端 Hermes 在服务端读取已脱敏、限长的调度/控制台
|
||
日志，并把技术信息翻译成非技术人员能理解的执行结果、异常影响和修复步骤。Hermes 未配置或
|
||
暂时不可用时，接口仍返回不含原始错误的通俗规则说明，页面会明确标记分析降级，不会整页失败。
|
||
|
||
接口如下：
|
||
|
||
- `GET /api/daily-summary`：读取昨天的缓存或生成汇总；可用 `date=YYYY-MM-DD` 指定执行日；
|
||
- `POST /api/daily-summary/refresh`：正文可传 `{"date":"YYYY-MM-DD"}`，强制重新读取日志并分析。
|
||
|
||
缓存位于 `GYXX_DATA_ROOT/state/ops/daily-summaries/<date>.json`。工作流/计划配置、当天运行
|
||
索引、相关日志或分析器配置发生变化时，指纹会失效并自动重建。日志原文、堆栈、路径、技术
|
||
错误载荷和步骤错误只作为服务端模型输入，不写入汇总缓存，也不返回浏览器；页面只收到运行
|
||
状态、时间等结构化事实和翻译后的中文结论。
|
||
|
||
## 通知路由
|
||
|
||
侧栏“通知路由”只展示代码中已经接入动态业务通知的工作流，不会让没有发送行为的工作流
|
||
凭空获得通知能力。当前范围为营销日报、内容平台登录态刷新、销量下滑告警、市场排行，以及
|
||
采购确认、补货结果、库存阈值预警共 7 条工作流。登录态刷新配置控制扫码二维码和失败汇总；
|
||
其余路由控制各自满足发送条件后的业务结果。每条路由有三种状态：
|
||
|
||
- “恢复沿用”继续使用该工作流已有的命令行或环境变量收件人；
|
||
- “动态接管”使用页面中选择的多人名单；
|
||
- “关闭通知”仍执行并保存工作流产出，但跳过该路由声明的业务消息。
|
||
|
||
页面不接管临时手工分析工具，也不改写策略固定的群通知。例如
|
||
`purchase-order-update` 的审单群消息继续由供应链策略维护，不会因为它能发消息就自动出现在
|
||
路由页面；这正是“不是所有工作流都要通知、也不是所有消息都允许在线改收件人”的边界。
|
||
|
||
人员的 `open_id` 按飞书应用隔离，不能跨应用复用。页面只允许选择配置中声明为分析端 Hermes
|
||
且服务器安装 profile 与 App ID 完全匹配的应用。可用手机号调用飞书通讯录接口解析该应用
|
||
作用域内的 `open_id`；应用密钥仍只存在于服务端运行时，不会进入浏览器或通知配置。解析结果
|
||
需要随“保存全部配置”一起提交才会生效；手工改写 OpenID 会自动取消手机号验证标记，服务端
|
||
也不会信任没有本次查询证明的“已验证”声明。
|
||
|
||
版本库中的 `config/notification-routing.json` 是首次启动的人员、应用和通知能力基线。页面
|
||
修改会带版本号原子写入 `GYXX_DATA_ROOT/state/notifications/routing.json`，不会修改源码配置；
|
||
冲突时页面会重新加载最新版本。每次工作流启动时会固定本次路由快照，所以保存后的配置从
|
||
下一次运行开始生效，不会在正在执行的任务中途改变收件人。声明了通知能力的公开手工命令也
|
||
会在启动时绑定到对应工作流路由；没有明确归属的通用命令不会误用其他工作流的快照。
|
||
|
||
## 执行安全
|
||
|
||
手动运行默认选择“安全预演”，不会产生真实外部副作用。只有在页面中选择“正式执行”并
|
||
确认影响后，控制台才会通过固定的 `python -m gyxx_flow run ... --execute` 入口启动独立
|
||
子进程。浏览器不能提交脚本路径、命令参数、环境变量或凭据。
|
||
|
||
运行弹窗中的“业务日期/业务月份”可手动选择，默认按定时配置的业务日期偏移预填；正式执行
|
||
时还可勾选“强制重跑”，控制台通过 `GYXX_FORCE_REFRESH=true` 环境变量让工作流忽略幂等
|
||
跳过并重新采集覆盖该业务日期。卡片与抽屉的“正式执行/强制重跑”按钮均先打开弹窗确认
|
||
日期与影响，不会未经确认直接提交。
|
||
|
||
天猫百亿补贴批量报名是例外：它按每次运行重新下载模板并提交所选入口，不使用按业务日期
|
||
划分的效果账本，也不要求核对旧导入回执；运行记录中的日期仅用于平台内部归档。
|
||
|
||
控制台沿用 `GYXX_DATA_ROOT`，因此运行日志、工作流锁、运行索引和副作用账本与 CLI、调度
|
||
服务保持同一边界。生产部署必须为所有进程设置同一个外部数据根。
|
||
|
||
页面中的“预演完成”和“正式成功”是两种不同状态。预演全部跳过外部写入时不会再显示为
|
||
最近正式成功；运行详情和历史记录会保留 `dry_run` 或 `execute` 模式。
|
||
|
||
## 远程访问
|
||
|
||
默认只监听回环地址。若需要绑定非回环地址，必须先通过安全环境注入不少于 24 个字符的
|
||
访问令牌：
|
||
|
||
```powershell
|
||
$env:GYXX_CONSOLE_TOKEN = '<由密钥系统注入的随机令牌>'
|
||
uv run gyxx console --host 0.0.0.0 --port 8765
|
||
```
|
||
|
||
令牌不会写入源码、配置、URL 或日志。页面会在当前浏览器会话中临时保存令牌。生产环境
|
||
应再通过 HTTPS 反向代理或 SSH 隧道访问，不应直接把明文 HTTP 控制端口暴露到公网。
|
||
|
||
控制台不提供工作流入口、参数、运行时绑定或凭据的在线编辑能力；这些仍由受版本控制的
|
||
项目配置和代码维护。
|
||
|
||
## 自检与保活
|
||
|
||
- `GET /api/health` 返回进程 PID、uptime 与调度器锁存活状态，不鉴权、不触外部依赖，专供探针使用。
|
||
- 控制台进程内置看门狗线程：周期自探测 `/api/health`，连续失败（默认 3 次）即以退出码 70 退出，
|
||
由 `deploy/watchdog/gyxx_keepalive.py`（登录自启动常驻）负责拉起；保活同时守护调度器进程，
|
||
详见 `docs/deployment.md` 的「Windows 工作站保活」章节。环境开关：
|
||
`GYXX_CONSOLE_WATCHDOG=0` 关闭、`GYXX_CONSOLE_WATCHDOG_INTERVAL_SECONDS`（默认 30）、
|
||
`GYXX_CONSOLE_WATCHDOG_FAILURES`（默认 3）。
|
||
- API 返回「控制台处理请求失败」时，完整堆栈在控制台 stderr 日志
|
||
（`var/logs/console-restarts/console-*.stderr.log`）中可查。
|