chore: initial snapshot for gitea/github upload

docs/supply_button_level_prd_v1_2026-03-25.md

@@ -0,0 +1,241 @@
+# 供应侧按钮级 PRD 分解（首批 3 个核心页面）
+
+- 版本：v1.0（草案）
+- 日期：2026-03-25
+- 适用范围：供应侧 S0/S1 首批上线页面
+- 关联 SSOT：
+  - `llm_gateway_subapi_evolution_plan_v4_2_2026-03-24.md`
+  - `acceptance_gate_single_source_v1_2026-03-18.md`
+  - `supply_side_product_design_v1_2026-03-18.md`
+  - `supply_detailed_design_v1_2026-03-18.md`
+
+---
+
+## 1. 目标与范围
+
+本稿用于把供应侧功能从“流程级”下钻到“按钮级”，用于：
+
+1. 前端实现不歧义。
+2. 后端接口可映射。
+3. QA 可直接编写用例。
+4. 审计与埋点可落地。
+
+首批覆盖页面：
+
+1. `SUP-PAGE-001` 供应账号挂载页。
+2. `SUP-PAGE-002` 套餐发布与上下架页。
+3. `SUP-PAGE-003` 收益结算与提现页。
+
+---
+
+## 2. 全局硬约束（所有页面生效）
+
+1. 用户A（供应方）仅向平台提交上游凭证；用户B不可见、不可得。
+2. 页面、接口、导出、错误文案均不得返回可复用上游凭证片段。
+3. 凭证相关动作必须有审计事件，且支持按 `request_id/operator_id` 追踪。
+4. 任何违反凭证边界的行为按 P0 处理，阻断发布（M-013~M-016）。
+
+---
+
+## 3. 页面一：供应账号挂载（SUP-PAGE-001）
+
+## 3.1 页面目标
+
+供应方完成账号挂载、验证、激活/停用，确保只在平台托管上游凭证。
+
+## 3.2 字段规格
+
+| 字段ID | 字段名 | 类型 | 必填 | 校验规则 | 脱敏规则 |
+|---|---|---|---|---|---|
+| F-001 | `provider` | 下拉 | 是 | 枚举：openai/anthropic/gemini/baidu/xfyun/tencent | 不脱敏 |
+| F-002 | `account_type` | 单选 | 是 | 枚举：api_key/oauth | 不脱敏 |
+| F-003 | `credential_input` | 密文输入框 | 是 | 长度、前缀、字符集校验 | UI 全程掩码，后端不回显 |
+| F-004 | `account_alias` | 文本 | 否 | 1-100 字符，禁止敏感词 | 不脱敏 |
+| F-005 | `min_quota_threshold` | 数值 | 否 | >=0，最多 6 位小数 | 不脱敏 |
+| F-006 | `risk_ack` | 勾选框 | 是 | 必须勾选协议确认 | 不脱敏 |
+
+## 3.3 按钮级规格
+
+| 按钮ID | 按钮文案 | 可见条件 | 可点击条件 | 触发动作 | 成功态 | 失败态 | 审计事件 | 测试用例ID |
+|---|---|---|---|---|---|---|---|---|
+| BTN-ACC-001 | 立即验证 | 已选择 `provider` 且输入凭证 | F-001/F-002/F-003 合法，未处于提交中 | `POST /api/v1/supply/accounts/verify` | 展示验证通过与额度摘要 | 展示错误码与修复建议 | `supply.account.verify` | `UI-SUP-ACC-001` |
+| BTN-ACC-002 | 提交挂载 | 验证通过后显示 | 风险确认已勾选 | `POST /api/v1/supply/accounts` | 新建记录 `pending/active` | 留在当前页，字段高亮报错 | `supply.account.create` | `UI-SUP-ACC-002` |
+| BTN-ACC-003 | 激活账号 | 账号状态为 `pending/suspended` | 当前用户拥有供应方权限 | `POST /api/v1/supply/accounts/{id}/activate` | 状态变更 `active` | 状态不变并提示原因 | `supply.account.activate` | `UI-SUP-ACC-003` |
+| BTN-ACC-004 | 暂停账号 | 账号状态为 `active` | 账号无未结清风险单 | `POST /api/v1/supply/accounts/{id}/suspend` | 状态变更 `suspended` | 状态不变并提示依赖项 | `supply.account.suspend` | `UI-SUP-ACC-004` |
+| BTN-ACC-005 | 删除账号 | 账号状态非 `active` | 无关联在售套餐 | `DELETE /api/v1/supply/accounts/{id}` | 列表移除 | 删除失败并提示阻塞原因 | `supply.account.delete` | `UI-SUP-ACC-005` |
+| BTN-ACC-006 | 查看审计 | 用户有审计权限 | 总是可点 | `GET /api/v1/supply/accounts/{id}/audit-logs` | 打开侧边栏 | 提示“暂无审计数据”或加载失败 | `supply.account.audit.view` | `UI-SUP-ACC-006` |
+
+## 3.4 状态机
+
+`pending -> active -> suspended -> disabled`
+
+约束：
+
+1. `active` 状态不可直接删除。
+2. `disabled` 为平台风控态，仅管理员可恢复。
+
+## 3.5 错误码映射（页面级）
+
+| 错误码 | 文案 | 前端动作 |
+|---|---|---|
+| `SUP_ACC_4001` | 凭证格式非法 | 高亮 `credential_input` |
+| `SUP_ACC_4002` | 上游连通性校验失败 | 展示“重试验证”入口 |
+| `SUP_ACC_4003` | ToS 不允许该账号进入供给池 | 阻断提交并展示合规说明 |
+| `SUP_ACC_5001` | 系统繁忙，请稍后再试 | 保留输入并允许重试 |
+
+---
+
+## 4. 页面二：套餐发布与上下架（SUP-PAGE-002）
+
+## 4.1 页面目标
+
+供应方发布可售套餐，执行上架/下架/暂停/恢复，受价格与风控规则约束。
+
+## 4.2 字段规格
+
+| 字段ID | 字段名 | 类型 | 必填 | 校验规则 | 备注 |
+|---|---|---|---|---|---|
+| F-101 | `supply_account_id` | 下拉 | 是 | 必须为 `active` 账号 | 来源 SUP-PAGE-001 |
+| F-102 | `model` | 下拉 | 是 | 模型白名单内 | 按供应商过滤 |
+| F-103 | `total_quota` | 数值 | 是 | >0 且 <= 账户可用额度 | 单位与主账务一致 |
+| F-104 | `price_per_1m_input` | 数值 | 是 | >= 平台最低保护价 | 6 位小数 |
+| F-105 | `price_per_1m_output` | 数值 | 是 | >= 平台最低保护价 | 6 位小数 |
+| F-106 | `valid_days` | 数值 | 是 | 1-365 | 过期自动下架 |
+| F-107 | `max_concurrent` | 数值 | 否 | 1-1000 | 默认 10 |
+| F-108 | `rate_limit_rpm` | 数值 | 否 | 1-100000 | 默认 60 |
+
+## 4.3 按钮级规格
+
+| 按钮ID | 按钮文案 | 可见条件 | 可点击条件 | 触发动作 | 成功态 | 失败态 | 审计事件 | 测试用例ID |
+|---|---|---|---|---|---|---|---|---|
+| BTN-PKG-001 | 保存草稿 | 已进入编辑页 | 基础字段合法 | `POST /api/v1/supply/packages/draft` | 状态 `draft` 持久化 | 保留页面并提示字段错误 | `supply.package.draft.save` | `UI-SUP-PKG-001` |
+| BTN-PKG-002 | 发布上架 | 套餐为 `draft/paused` | 价格、额度、有效期全部通过 | `POST /api/v1/supply/packages/{id}/publish` | 状态变更 `active` | 阻断并展示具体不满足项 | `supply.package.publish` | `UI-SUP-PKG-002` |
+| BTN-PKG-003 | 暂停售卖 | 套餐为 `active` | 无平台强制冻结 | `POST /api/v1/supply/packages/{id}/pause` | 状态变更 `paused` | 状态不变并提示原因 | `supply.package.pause` | `UI-SUP-PKG-003` |
+| BTN-PKG-004 | 立即下架 | 套餐为 `active/paused` | 无未完成的结算锁 | `POST /api/v1/supply/packages/{id}/unlist` | 状态变更 `expired` 或 `paused` | 状态不变并提示阻塞订单 | `supply.package.unlist` | `UI-SUP-PKG-004` |
+| BTN-PKG-005 | 批量调价 | 列表页多选后显示 | 所选套餐均可编辑 | `POST /api/v1/supply/packages/batch-price` | 批量更新成功数回显 | 部分失败返回明细 | `supply.package.price.batch_update` | `UI-SUP-PKG-005` |
+| BTN-PKG-006 | 复制套餐 | 任意套餐行可见 | 原套餐存在 | `POST /api/v1/supply/packages/{id}/clone` | 新增草稿套餐 | 复制失败提示 | `supply.package.clone` | `UI-SUP-PKG-006` |
+
+## 4.4 状态机
+
+`draft -> active -> paused -> sold_out -> expired`
+
+约束：
+
+1. `sold_out` 仅系统自动迁移，不可人工强制设置。
+2. `expired` 后仅允许“复制套餐”，不允许直接恢复。
+
+## 4.5 错误码映射（页面级）
+
+| 错误码 | 文案 | 前端动作 |
+|---|---|---|
+| `SUP_PKG_4001` | 售价低于保护价 | 锁定发布按钮并高亮价格字段 |
+| `SUP_PKG_4002` | 可用额度不足 | 高亮额度字段并提示可用值 |
+| `SUP_PKG_4003` | 账号状态不可发布套餐 | 跳转账号页处理 |
+| `SUP_PKG_4091` | 套餐状态冲突，请刷新后重试 | 强制刷新当前行 |
+
+---
+
+## 5. 页面三：收益结算与提现（SUP-PAGE-003）
+
+## 5.1 页面目标
+
+供应方查看收益、发起提现、追踪结算状态，形成可审计资金链路。
+
+## 5.2 字段规格
+
+| 字段ID | 字段名 | 类型 | 必填 | 校验规则 | 备注 |
+|---|---|---|---|---|---|
+| F-201 | `available_amount` | 只读金额 | 是 | >=0 | 后端计算 |
+| F-202 | `withdraw_amount` | 数值输入 | 是 | >0 且 <= `available_amount` | 2 位小数 |
+| F-203 | `payment_method` | 单选 | 是 | 枚举：bank/alipay/wechat | 与账户一致 |
+| F-204 | `payment_account` | 文本 | 是 | 按通道校验账号格式 | 敏感信息掩码展示 |
+| F-205 | `sms_code` | 验证码 | 是 | 时效 5 分钟 | 提交后失效 |
+
+## 5.3 按钮级规格
+
+| 按钮ID | 按钮文案 | 可见条件 | 可点击条件 | 触发动作 | 成功态 | 失败态 | 审计事件 | 测试用例ID |
+|---|---|---|---|---|---|---|---|---|
+| BTN-SET-001 | 刷新收益 | 页面可见 | 总是可点 | `GET /api/v1/supplier/billing` | 卡片与趋势图更新 | 提示“刷新失败，请稍后重试” | `supply.settlement.refresh` | `UI-SUP-SET-001` |
+| BTN-SET-002 | 发起提现 | 有可提现金额 | 金额、账户、验证码合法 | `POST /api/v1/supply/settlements/withdraw` | 生成结算单 `pending` | 错误提示并保留输入 | `supply.settlement.withdraw.create` | `UI-SUP-SET-002` |
+| BTN-SET-003 | 撤销申请 | 结算单状态为 `pending` | 申请属于本人 | `POST /api/v1/supply/settlements/{id}/cancel` | 状态变更 `failed/cancelled` | 提示不可撤销原因 | `supply.settlement.withdraw.cancel` | `UI-SUP-SET-003` |
+| BTN-SET-004 | 下载对账单 | 有结算记录 | 总是可点 | `GET /api/v1/supply/settlements/{id}/statement` | 下载文件成功 | 弹窗提示失败原因 | `supply.settlement.statement.export` | `UI-SUP-SET-004` |
+| BTN-SET-005 | 查看流水明细 | 页面可见 | 总是可点 | `GET /api/v1/supply/earnings/records` | 打开明细抽屉 | 提示无数据/加载失败 | `supply.earnings.records.view` | `UI-SUP-SET-005` |
+
+## 5.4 状态机
+
+`pending -> processing -> completed/failed`
+
+约束：
+
+1. `completed` 状态不可撤销。
+2. `processing` 状态禁止重复提交提现申请。
+
+## 5.5 错误码映射（页面级）
+
+| 错误码 | 文案 | 前端动作 |
+|---|---|---|
+| `SUP_SET_4001` | 可提现余额不足 | 高亮金额并提示可提现额度 |
+| `SUP_SET_4002` | 收款账户校验失败 | 高亮账户字段 |
+| `SUP_SET_4003` | 验证码失效或错误 | 清空验证码并可重新获取 |
+| `SUP_SET_4091` | 当前有处理中提现单 | 禁用“发起提现”按钮 |
+
+---
+
+## 6. 页面级埋点与审计最小集
+
+## 6.1 埋点事件（分析）
+
+1. `sup_page_view`：页面访问。
+2. `sup_button_click`：按钮点击（含按钮 ID）。
+3. `sup_submit_success`：关键提交成功。
+4. `sup_submit_fail`：关键提交失败（含错误码）。
+
+## 6.2 审计事件（合规）
+
+1. 账号相关：创建、激活、暂停、删除、查看审计日志。
+2. 套餐相关：发布、调价、暂停、下架、复制。
+3. 结算相关：提现发起、提现撤销、对账单导出。
+
+审计最小字段：
+
+1. `event_id`
+2. `operator_id`
+3. `tenant_id`
+4. `object_type`
+5. `object_id`
+6. `before_state`
+7. `after_state`
+8. `request_id`
+9. `created_at`
+
+---
+
+## 7. 与凭证边界门禁映射
+
+| 约束 | 页面控制点 | 对应 Gate/指标 |
+|---|---|---|
+| 供应方上游凭证不外发 | SUP-PAGE-001 的 `credential_input` 只入不出；所有页面禁止回显原文 | M-013 |
+| 需求方仅平台凭证入站 | 页面与接口文案统一“平台凭证”，不提供上游凭证下载入口 | M-014 |
+| 禁止需求方绕过平台直连上游 | 无任何“上游直连参数配置”入口；异常由安全策略阻断 | M-015 |
+| 外部 query key 全拒绝 | 页面帮助文档和 SDK 示例仅给 header 鉴权方式 | M-016 |
+
+---
+
+## 8. 测试用例骨架（新增）
+
+| 用例ID | 页面 | 关注点 | 期望 |
+|---|---|---|---|
+| UI-SUP-ACC-001~006 | SUP-PAGE-001 | 按钮可见性、禁用态、状态迁移、审计 | 与按钮规格一致 |
+| UI-SUP-PKG-001~006 | SUP-PAGE-002 | 发布前校验、状态机、批量操作 | 不越权、不跳态 |
+| UI-SUP-SET-001~005 | SUP-PAGE-003 | 提现流程、并发防重、撤销边界 | 资金状态一致 |
+| SEC-SUP-001 | 全局 | 错误体/导出脱敏 | 不出现可复用上游凭证 |
+| SEC-SUP-002 | 全局 | 凭证边界回归（与 CB-001~CB-004 对齐） | M-013~M-016 达标 |
+
+---
+
+## 9. 待拍板项（进入 PRD v1.0 前必须确认）
+
+1. `POST /api/v1/supply/*` 系列接口是否按本稿命名冻结。
+2. 提现金额风控阈值（单笔/单日）与冷却期。
+3. 套餐“下架”与“暂停”的财务影响口径是否一致。
+4. 供应方是否允许批量导入账号（当前建议 S1 后）。