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 人天** |