9.3 KiB
工作流控制台
GYXX Flow 自带一个只依赖 Python 运行时的工作流控制台。页面从当前工作流目录、定时配置、 调度状态和运行索引动态取数，不维护第二套工作流清单。
启动
cd D:\gyxx-flow
uv run gyxx console
生产凭据不会从源码或任意 .env 自动发现。需要真实运行时，必须显式指定受控环境文件；
已经由服务环境注入的同名变量优先，不会被文件覆盖：
uv run gyxx console --env-file D:\secure\gyxx-flow.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。控制台进程与调度进程职责分离；服务器仍只运行一个
项目内调度服务：
uv run gyxx schedule run
页面可以：
- 在顶部查看调度服务状态；显示“调度服务未运行”时，可点击“启动调度器”拉起唯一的常驻 Python 调度进程。启动会继承控制台的
--env-file，并在页面中持续刷新真实服务状态；若已有到期但尚未执行的计划，调度器会按现有补偿窗口评估并启动对应任务； - 按内容营销、商品经营、店铺洞察和供应链分别展示全部工作流；
- 查看工作流定义、执行步骤、定时规则和下一次启动时间；
- 修改定时类型、一个或多个时间、日期规则、启停状态和业务日期偏移；
- 配置实际支持业务通知的工作流、发送应用和一个或多个收件人；
- 在云端数据库中增删改查商品 ID、ERP 款式编码和各业务飞书目标表；
- 查看昨天或指定执行日的逐工作流运行汇总、异常原因和修复建议；
- 以安全预演或正式执行方式手动触发已注册工作流；
- 查看最近运行状态、步骤统计和经过脱敏的错误详情。
定时配置保存到 config/schedules.json。常驻 Python 调度器会在下一次轮询时重新验证并
加载配置，不需要创建或修改 Windows Task Scheduler 任务。若新规则在错过触发补偿窗口
内已经到期，下一次轮询可能立即启动该工作流。
商品与款式配置
侧栏“商品与款式配置”维护商品经营和内容营销共用的动态配置。页面提供款式、品牌、平台、 商品 ID、ERP 编码、启停状态和各业务飞书目标表的查询与 CRUD；保存后从下一次新启动的工作流 生效。编辑和删除带行版本校验，旧页面不能覆盖其他操作员已保存的新版本。
配置存储在云端 PostgreSQL，旧飞书配置主表不再属于运行路径。首次迁移、字段模型、受影响 工作流和失败回退边界见 工作流动态配置。
每日运行汇总
侧栏“每日运行汇总”默认按 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 个字符的 访问令牌：
$env:GYXX_CONSOLE_TOKEN = '<由密钥系统注入的随机令牌>'
uv run gyxx console --host 0.0.0.0 --port 8765
令牌不会写入源码、配置、URL 或日志。页面会在当前浏览器会话中临时保存令牌。生产环境 应再通过 HTTPS 反向代理或 SSH 隧道访问，不应直接把明文 HTTP 控制端口暴露到公网。
控制台不提供工作流入口、参数、运行时绑定或凭据的在线编辑能力；这些仍由受版本控制的 项目配置和代码维护。