supply-intelligence/specs/功能清单.md

Supply Intelligence 功能清单（按钮级任务版）

状态说明（2026-05 收敛修订）：本文件为旧版按钮级任务清单，已不再作为当前实施真源。 当前实施真源以“2026-05 新 PM 基线 + tech/BASELINE_TECHLEAD_V2.md + 首期消费闭环决议”为准。 下列旧任务类型已明确废止或降期，不得继续直接派发给 Engineer：

• gateway 管理接口热更新主路径
• pricing / prediction / 向量检索 / SFI 仪表盘等超范围能力
• 自动注册深链路作为本期硬门槛
• 以 Temporal / 独立 worker / 独立平台骨架为默认落地前提

版本：v1.0 日期：2026-04-27 说明：每个任务 5 分钟可完成，可直接安排进任务管理

---

Phase 1：模块 A（探针）+ 模块 E（工作台只读观测）

模块 A1：探针管理基础

A1.1 供应商账号列表页

• 任务：实现供应商账号列表页路由 /supply/dashboard/accounts
• 任务：在账号列表渲染数据表格，每行显示：账号ID / 供应商名称 / 账号标识(昵称) / 当前状态(徽章) / 风险评分 / 最近探针时间 / 操作
• 任务：账号状态徽章颜色：active=绿色 / suspended=黄色 / disabled=红色
• 任务：账号行风险评分显示为进度条（0-100），>80 显示红色
• 任务：账号行渲染"查看详情"按钮，点击展开显示最近 5 次探针结果
• 任务：账号列表支持分页，每页 50 条
• 任务：账号列表支持按供应商名称筛选（下拉框）
• 任务：账号列表支持按状态筛选（全部 / active / suspended / disabled）
• 任务：账号列表支持按风险评分范围筛选（滑块）

A1.2 账号详情页

• 任务：实现账号详情页路由 /supply/dashboard/accounts/{account_id}
• 任务：详情页渲染账号基本信息区块：账号ID / 供应商 / 状态 / 创建时间 / 最近探针时间
• 任务：详情页渲染探针历史时间线，每条显示：探针时间 / 结果(成功/失败/不可判定) / 延迟 / HTTP状态码 / 风险评分
• 任务：详情页渲染"手动触发探针"按钮，点击后立即执行一次探针，显示加载状态，完成后刷新时间线
• 任务：详情页渲染"暂停此账号探针"开关按钮（默认关闭），开启后该账号不参与自动探针
• 任务：详情页渲染"查看历史状态变更"按钮，点击展开状态变更记录（时间 / 从 → 到 / 原因）

A1.3 探针后端核心

• 任务：实现探针调度器（基于主仓既有调度能力或轻量本地调度器，每 5 分钟轮询所有 active/suspended 账号）
• 任务：实现探针执行器，对单个账号发起 HTTP GET/POST 请求，记录响应码/延迟/返回体
• 任务：实现探针结果评估逻辑：HTTP 200 = 成功 / 401/403 = 明确失败 / 429/5xx/超时/格式突变 = 不可判定
• 任务：实现状态机：active 收到 1 次 explicit_failure → suspended；suspended 连续 3 次 explicit_failure → disabled
• 任务：实现 429/暂时性错误指数退避：1min → 2min → 4min 重试，超 3 次则本次跳过并保留状态
• 任务：实现探针结果写入 supply_intelligence_probe_logs 表，保留 30 天

模块 A2：供应商适配层

A2.1 供应商适配器框架

• 任务：定义 SupplierAdapter 接口：(Probe(ctx context.Context, account Account) ProbeResult, GetModels(ctx context.Context, account Account) ([]Model, error))
• 任务：实现 SupplierAdapterRegistry map，按供应商名称注册适配器实例
• 任务：实现配置文件加载供应商适配器列表（suppliers[].name + suppliers[].adapter）
• 任务：每个适配器实现health check端点探测（发送测试请求验证连通性）

A2.2 Phase 1 目标供应商适配（2个）

• 任务：实现 OpenAI 供应商适配器（Probe：用 /v1/models 查询；获取模型列表：用 /v1/models）
• 任务：实现 Anthropic 供应商适配器（Probe：用 /v1/models 查询；获取模型列表：用 /v1/models）
• 任务：适配器配置项：API Base URL / API Key（加密存储）/ 是否允许受控自动补给 / Rate Limit 阈值

模块 E1：运营工作台（只读观测部分）

E1.1 工作台首页

• 任务：实现工作台首页路由 /supply/dashboard
• 任务：首页渲染 4 个统计卡片：账号总数(按状态颜色分段) / 本小时新发现模型数 / 待处理候选模型数 / 受控自动补给任务队列长度
• 任务：首页渲染候选处理与账号健康摘要（避免引入 SFI 仪表盘等超范围指标体系）
• 任务：首页渲染"探针健康度"简表，显示各供应商最后探针结果（绿色OK/黄色不可判定/红色明确失败/灰色未探）

E1.2 待处理事项列表

• 任务：在工作台首页渲染"待处理" Tab，展示以下待办项：
  • 风险评分 > 70 的账号（红色高亮）
  • 状态 = discovered 的候选模型（待准入测试）
  • 受控自动补给失败或待验证的任务（待人工介入）
  • 模型已下架告警（待确认）
• 任务：每项待办渲染"处理"按钮，点击进入对应详情页
• 任务：每项待办渲染"忽略"按钮，点击后该项从待办列表暂时移除（3小时后重现）

---

Phase 2：模块 B（模型发现）+ 模块 C（准入测试）

模块 B1：模型发现

B1.1 模型列表页

• 任务：实现模型列表页路由 /supply/dashboard/models
• 任务：模型列表每行显示：模型ID / 所属供应商 / 当前状态(活跃/草稿/已下线/发现中/测试失败) / 发现时间 / 来源
• 任务：状态筛选 Tab：全部 / 发现中 / 待测试 / 活跃 / 已下线
• 任务：模型列表支持按供应商筛选
• 任务：模型列表支持按发现时间范围筛选
• 任务：模型行点击"查看详情"进入模型详情页

B1.2 模型发现后端

• 任务：实现模型发现调度任务（基于主仓既有调度能力或轻量本地调度器），每 1 小时触发一次扫描
• 任务：实现模型列表抓取器：调用各供应商适配器的 GetModels() 方法
• 任务：实现模型比对逻辑：将抓取的模型列表与 supply_packages 中 active/paused/draft 记录去重
• 任务：发现新模型时，写入 supply_intelligence_model_candidates 表，status = discovered
• 任务：发现模型下架时（供应商列表有、平台 active 记录也有但 ID 消失），写入运营告警，不改变 package 状态
• 任务：实现模型来源记录：discovery_source 字段（official_api / manual_import）

模块 C1：准入测试

C1.1 准入测试配置

• 任务：实现测试用例管理页路由 /supply/dashboard/tests/cases
• 任务：测试用例列表每行显示：用例ID / 所属模型类型 / 测试目标(endpoint) / 状态(启用/禁用)
• 任务：渲染"新增用例"按钮，点击弹出用例创建表单（endpoint地址 / 请求方法 / 预期响应格式 / 超时时间）
• 任务：测试用例表单支持选择模板（chat/completion/embedding）
• 任务：实现每个模型类型默认测试用例集（≥ 5 个用例）

C1.2 准入测试执行

• 任务：实现准入测试任务流，接收 candidate_id 参数并由主仓既有调度能力或轻量任务执行器驱动
• 任务：AdmissionTestWorkflow 从 model_candidates 加载 discovered 状态的候选模型
• 任务：按顺序执行所有启用的测试用例，记录每条的 HTTP 状态/延迟/响应格式/Token 计数
• 任务：所有用例返回 HTTP 200 + 格式正确 → 更新 candidate status = test_passed，生成 supply_package 草稿
• 任务：任意用例返回非 200 或格式错误 → 更新 candidate status = test_failed，写入 failure_reason
• 任务：单个用例超时（60 秒）→ 标记为 timeout，整体判定失败
• 任务：准入测试完成后，发送飞书通知给运营人员

C1.3 草稿生成

• 任务：准入测试通过后，自动生成 supply_packages 草稿记录（status = draft）
• 任务：草稿字段：platform / model_id / model_name / price_per_1m_input（默认值）/ price_per_1m_output（默认值）/ suggested_by = si_auto
• 任务：草稿生成后，在工作台"待上架"列表中显示该草稿

---

Phase 3：模块 D（受控自动补给）+ 模块 E（工作台完整干预）

模块 D1：受控自动补给配置

D1.1 自动补给设置页

• 任务：实现自动补给设置页路由 /supply/dashboard/auto-supply/settings
• 任务：页面渲染供应商列表，每行显示：供应商名称 / 是否开启受控自动补给（开关）/ 可用账号阈值（数字输入）/ 状态
• 任务：点击供应商行"配置"按钮，弹出自动补给配置弹窗
• 任务：配置弹窗字段：启用自动补给（开关）/ 白名单供应商标记 / 触发阈值（账号数）/ 补给方式（任务化/人工补录入口）/ 审批要求
• 任务：弹窗保存后，按主仓既有配置方式持久化并生效，不引入 Redis 首期前置依赖
• 任务：配置页顶部渲染"通知/补给受理链路测试"按钮，点击后发送测试通知或验证受理接口可达

D1.2 自动补给执行后端

• 任务：实现受控自动补给任务流，监控白名单供应商可用账号数 < 阈值时触发
• 任务：按供应商配置创建补给任务或调用受控补给受理接口，禁止默认走浏览器自动化注册深链路
• 任务：补给成功后写入待验证/待启用记录，不允许绕过验证直接进入 active
• 任务：若涉及凭证写入，则将密钥发送至 KMS 加密，密文存入 supply_accounts
• 任务：触发验证或人工审核链路，验证通过后再进入可用状态
• 任务：补给失败时，写入 supply_intelligence_auto_supply_tasks 或等价任务表，status = failed，记录失败原因

模块 D2：Fail-closed 安全机制

• 任务：补给流程中，若通知网关/补给受理接口返回 503 或超时，任务立即标记为 failed，不执行虚假成功写操作
• 任务：补给流程中，若 KMS 加密超时（60 秒），任务立即标记为 failed
• 任务：明文凭证在内存中的存活时间不超过 60 秒，超时自动清除
• 任务：审计日志中记录补给请求/响应（脱敏后：隐藏敏感标识、隐藏凭证）

模块 E2：工作台完整干预

E2.1 候选模型处理

• 任务：工作台"待上架模型"列表，每行显示：模型ID / 供应商 / 发现时间 / 测试结果摘要 / 来源
• 任务：模型行渲染"查看测试详情"按钮，点击展开显示所有测试用例结果（每条：通过/失败/超时）
• 任务：模型行渲染"确认上架"绿色按钮，点击后弹出确认框（显示将生成的 package 草稿内容）
• 任务：模型行渲染"忽略"按钮，点击后该模型 7 天内不出现（写入 ignored_until 字段）
• 任务：模型行渲染"手动强制上架"橙色按钮（仅测试失败时可见），点击后需填写强制上架理由（必填）

E2.2 草稿确认上架

• 任务：点击"确认上架"后，PUT supply_packages/{id} status = active
• 任务：同时更新 model_candidates 对应记录 status = published
• 任务：写入 gateway package change event，等待首期消费方按决议链路拉取并 ack
• 任务：完成后显示成功提示："模型已上架，已生成待消费变更事件；是否进入路由以消费方 ack 为准"

E2.3 工单与通知

• 任务：模型下架告警 → 自动生成运营工单（类型 = model_deprecated），推送到运营工作台
• 任务：受控自动补给失败 → 自动生成运营工单（类型 = auto_supply_failed），推送飞书通知
• 任务：连续 3 次探针失败账号 → 生成运营工单（类型 = account_risk），推送飞书通知

---

全局模块

模块 G1：供应商配置管理

• 任务：实现供应商列表页路由 /supply/dashboard/settings/suppliers
• 任务：供应商列表每行显示：供应商ID / 名称 / 适配器类型 / 账号数量 / 接口状态 / 操作
• 任务：渲染"添加供应商"按钮，点击弹出供应商创建表单
• 任务：供应商表单字段：名称 / 适配器类型(下拉) / API Base URL / API Key（加密存储）/ 探针周期(默认5min) / 是否启用
• 任务：实现供应商"测试连通性"按钮，点击后执行一次 probe 并显示结果
• 任务：供应商配置变更后，刷新当前集成运行实例中的适配器装配或调度配置（不得以 Temporal Worker 作为首期前置依赖）

模块 G2：配置热更新

• 任务：关键配置项（探针周期/扫描周期/阈值）按主仓既有配置方式存储与生效，避免把 Redis 作为首期前置依赖
• 任务：实现 GET /api/v1/supply-intelligence/config 接口，返回当前生效配置
• 任务：实现 PUT /api/v1/supply-intelligence/config 接口，修改配置后 60 秒内生效
• 任务：配置变更生成审计日志记录（action = config_update）
• 任务：不支持的配置项修改返回 400 错误码

模块 G3：OpenAPI + 健康检查

• 任务：实现 GET /actuator/health / /actuator/health/live / /actuator/health/ready
• 任务：实现 Swagger UI 路由 /docs
• 任务：实现 OpenAPI 3.0 spec 端点 /openapi.json
• 任务：实现关键后台任务执行链路健康检查，调度/执行链路不可用时 /actuator/health/ready 返回 503

模块 G4：权限与认证

• 任务：实现 JWT 认证中间件（与立连桥统一认证打通）
• 任务：实现角色权限：运营人员（观测 + 部分操作）/ 管理员（全部操作）
• 任务：权限不足返回 HTTP 403，错误码 SUP_INT_AUTH_1001

---

技术基础设施

T1：项目骨架

• 任务：初始化或挂载到主仓中的 Go module / 子模块边界，保持与 supply-api 一致的技术栈约束
• 任务：创建集成运行入口；如保留独立运行，也仅作为轻量可选形态，不以双进程 api/worker 为首期强依赖
• 任务：创建 internal/ 目录结构（domain/service/handler/infrastructure/repository）
• 任务：配置 Viper 读取 config.yaml，支持环境变量覆盖
• 任务：配置 log/slog 结构化日志，输出 JSON 格式
• 任务：创建 PostgreSQL schema migration（使用 golang-migrate），表前缀 supply_intelligence_
• 任务：按主仓既有能力接入配置、调度、审计与内部路由，不额外引入 Redis 作为首期前置依赖
• 任务：配置 Dockerfile 和最小部署说明，优先支持主仓集成部署
• 任务：如需部署文档，仅按当前真源补充最小启动命令，不再回写旧 DEPLOYMENT.md 为实现依据

T2：单元测试骨架

• 任务：为每个 domain 层函数编写单元测试，覆盖率 >= 70%
• 任务：为每个 service 层函数编写单元测试，覆盖率 >= 80%
• 任务：配置 CI（GitHub Actions），PR 必须通过全部测试和覆盖率检查

T3：IntegrationPlugin 接口

• 任务：实现 IntegrationPlugin 接口（Init() error / Serve() error / Shutdown() error）
• 任务：实现插件模式下各模块的开关配置（viper 读取 supply_intelligence.enabled_modules）
• 任务：实现内部/外部路径前缀可配置，并区分 /internal/supply-intelligence/ 与对外暴露路径
• 任务：编写集成测试：插件模式启动，关键探针/发现/发布事件接口与内部消费接口正常运作

---

任务估算汇总

Phase	模块	任务数	估计工时
Phase 1	A1 探针管理 + A2 适配层 + E1 工作台只读	34	3 人天
Phase 2	B1 模型发现 + C1 准入测试	22	3 人天
Phase 3	D1/D2 受控自动补给 + E2 工作台干预	24	3 人天
全局	G1 供应商配置 + G2 配置热更新 + G3 OpenAPI + G4 权限认证	18	2 人天
技术基础设施	T1 骨架 + T2 测试 + T3 插件	14	2 人天
合计		112	~13 人天