OPC/chorus
2
0
Fork 0
Code Issues 11 Pull Requests Actions Packages Projects Releases Wiki Activity

design: 明确 MVP-1 路由、Provider 与数据技术设计 #16

New Issue
Closed
opened 2026-08-21 14:29:48 +08:00 by ila · 3 comments
ila commented 2026-08-21 14:29:48 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：需求
  • 所属 Epic：#3
  • 所属 MVP / 版本：#19
  • 阶段：已完成

依赖与并行

  • 前置工单：#4（已完成）
  • 是否允许与前置工单并行：否
  • 原因：MVP-1 以已验收的 MVP-0 为基线。

子项目影响

  • 仅影响的子项目 / 交付单元：架构设计，覆盖 internal/core、internal/platform、internal/worker、migrations/、管理端及 portal 共享契约
  • 是否跨子项目：是
  • 是否修改共享接口或契约：设计阶段只定义、不实现；唯一事实来源：Architecture-and-Code-Map、Business-Rules-and-Glossary、Product-Requirements-Overview
  • 各子项目需要执行的验证：设计评审；本工单不运行生产代码测试

原始需求

  • 来源：用户对话与已确认核心 Wiki
  • 提出时间：2026-08-21
  • 关键原话或脱敏摘要：用户确认“按原规划进入 MVP-1”，并确认先完成技术设计、管理端原型和用户端原型，再拆分生产实现工单。

要解决什么

把 MVP-1 已确认的能力整理成可实施的架构、API、数据、状态与安全设计，消除 Provider 配置、路由池、故障转移、协议能力、连通性测试和审计边界中的实现歧义，为后续迁移与生产工单提供唯一依据。

做什么 / 不做什么

  • 做：定义路由池、权重、maxFailover、gobreaker 状态与并发边界；定义 images、images_edits、gemini 协议契约；定义 Provider/API Key 仅写配置、AES-GCM 信封与轮换；定义一次性真实连通性测试的授权、审计、冷却和脱敏；定义 role_rule、图片 role/note/order、历史游标；设计可逆迁移、API、错误码、状态和 mock 测试矩阵。
  • 不做：不修改生产代码或数据库；不调用真实 Provider；不制作 UI；不加入计费、支付、配额、内容审核、公开注册、MVP-2 API Key/openapi 等排除范围。

已确认方案

先以 MVP-0 当前模型和安全红线为基线，输出字段级数据设计、接口契约、状态转换和失败语义。路由候选仅来自启用且未熔断的路由池；429/5xx/超时/连接错误可切换，400/401/内容策略拒绝立即返回。生产继续禁止 AutoMigrate，所有表与 sys_*/菜单/API 种子只经可逆 SQL。真实连通性测试只能由授权管理员主动触发一次低成本请求，并审计与冷却。

预计修改文件：

  • Gitea Wiki：Architecture-and-Code-Map
  • Gitea Wiki：Business-Rules-and-Glossary
  • Gitea Wiki：Product-Requirements-Overview
  • docs/ 对应核心 Wiki 镜像（通过 sync 生成）

需求变化记录

日期 变化内容 原因 用户确认
2026-08-21 按原规划进入 MVP-1，并先完成三项设计门禁 用户确认阶段与拆分 是

设计与原型门禁

  • 修改类型：非 UI
  • 所需设计证据：架构、API、数据、状态或流程设计
  • 可编辑设计源链接、版本或事实来源：本工单评论及上述核心 Wiki revision
  • 本地 HTML 审核快照路径和版本（不适用时说明原因）：不适用，非 UI 技术设计
  • 本地浏览方式和资源完整性检查：不适用
  • 版本、revision 或确认日期：Architecture c5a4385d79bfa1513b25cc35f2676e1e451336de；Business Rules f7c84780525130d468b4e0b0ff84c412846a9fdc；Product Requirements e832dfa2552c6cf97eda1927588bc85392f5fe8e；2026-08-21
  • 状态：已确认
  • 确认人、确认时间和覆盖范围：用户于 2026-08-21 验收通过 #16，确认字段、迁移、API、状态、安全、回退和测试设计
  • 无需 UI 原型或无需任何原型的原因：本工单不改变界面，只形成后续实现依据

文档影响

  • 不影响长期文档，原因：
  • 更新项目档案或本地开发与验证
  • 更新架构与代码地图
  • 更新业务规则与术语
  • 更新常见修改或故障排查
  • 更新其他 Wiki 页面：Product-Requirements-Overview

交付文档影响

  • 无交付文档影响，原因：只形成内部技术设计，尚无可供最终用户操作的新能力
  • 更新已有交付文档，受众与页面：
  • 新增交付文档，受众与页面：
  • 需要目标岗位或客户代表验证：否；验证方式：用户评审技术设计

验收标准

  • 数据表、字段、索引、外键、删除规则以及 up/down 迁移顺序明确，且不依赖生产 AutoMigrate。
  • Provider/Model/路由池、密钥轮换、审计和连通性冷却的 API、权限及脱敏规则明确。
  • images、images_edits、gemini 输入输出契约和能力匹配规则明确。
  • 加权选路、熔断、最大故障转移、attempt/租约一致性和 retryable 四类测试矩阵明确。
  • role_rule、图片 role/note/order、Prompt 覆盖顺序和历史游标契约明确。
  • Wiki 在线回读有 revision，核心镜像同步检查通过，并由用户确认后才能放行生产工单。

验证方式

  • 人工逐项评审架构、API、数据、状态、安全和回退设计。
  • python dev_scripts/harness.py check --strict
  • python dev_scripts/harness.py sync --check

风险和回退

  • 风险：过早锁定不兼容的数据结构、路由语义或管理端契约，导致迁移和 UI 重做；密钥或 SSRF 边界遗漏会形成高风险实现。
  • 回退：本工单只更新设计和文档；未确认时不建立或放行生产实现工单。修订通过新的 Wiki revision 和工单变更记录完成。

实施结果与证据（2026-08-21）

  • 已完成字段级数据设计、三段迁移顺序、Provider/管理 API、portal 提交/游标契约、worker CAS/熔断流程和完整测试矩阵；没有修改生产代码或数据库，也没有调用真实 Provider。
  • 核心 Wiki revision：Architecture c5a4385d79bfa1513b25cc35f2676e1e451336de；Business Rules f7c84780525130d468b4e0b0ff84c412846a9fdc；Product Requirements e832dfa2552c6cf97eda1927588bc85392f5fe8e。
  • Git 提交：84eb98075617c24899421a923515058bca3f99bd，已推送到 main。
  • 验证：harness.py check --strict 通过；DevHarness 42 项单元测试通过；harness.py sync --check 通过。
  • 任务归档：Task-16-明确-MVP-1-路由与-Provider-技术设计，revision be883f6177e784f6c4a218761b0a0a8cfec0416b。按规则未导出 docs/task/。
  • 未验证：没有生产实现，故未执行 MySQL 迁移、Go 产品测试、浏览器 E2E 或真实 Provider 连通性；由后续实现/集成工单覆盖。
  • 当前状态：已完成。#17/#18 的技术前置已满足；两个原型分别验收前，生产实现工单仍不放行。

验收结论（2026-08-21）

  • 用户明确确认 #16 验收通过，详细技术设计由草稿转为已确认。
  • 验收文档提交：ca75c26e39fc643cee8f4c0f7e825dd840350cbb，已推送到 main。
  • 最终任务归档 revision：be883f6177e784f6c4a218761b0a0a8cfec0416b。
  • #17、#18 的技术前置已满足，但原型和生产实现仍遵守各自设计门禁。
## 基本信息 - 类型：需求 - 所属 Epic：#3 - 所属 MVP / 版本：#19 - 阶段：已完成 ## 依赖与并行 - 前置工单：#4（已完成） - 是否允许与前置工单并行：否 - 原因：MVP-1 以已验收的 MVP-0 为基线。 ## 子项目影响 - 仅影响的子项目 / 交付单元：架构设计，覆盖 `internal/core`、`internal/platform`、`internal/worker`、`migrations/`、管理端及 portal 共享契约 - 是否跨子项目：是 - 是否修改共享接口或契约：设计阶段只定义、不实现；唯一事实来源：Architecture-and-Code-Map、Business-Rules-and-Glossary、Product-Requirements-Overview - 各子项目需要执行的验证：设计评审；本工单不运行生产代码测试 ## 原始需求 - 来源：用户对话与已确认核心 Wiki - 提出时间：2026-08-21 - 关键原话或脱敏摘要：用户确认“按原规划进入 MVP-1”，并确认先完成技术设计、管理端原型和用户端原型，再拆分生产实现工单。 ## 要解决什么 把 MVP-1 已确认的能力整理成可实施的架构、API、数据、状态与安全设计，消除 Provider 配置、路由池、故障转移、协议能力、连通性测试和审计边界中的实现歧义，为后续迁移与生产工单提供唯一依据。 ## 做什么 / 不做什么 - 做：定义路由池、权重、`maxFailover`、gobreaker 状态与并发边界；定义 `images`、`images_edits`、`gemini` 协议契约；定义 Provider/API Key 仅写配置、AES-GCM 信封与轮换；定义一次性真实连通性测试的授权、审计、冷却和脱敏；定义 role_rule、图片 role/note/order、历史游标；设计可逆迁移、API、错误码、状态和 mock 测试矩阵。 - 不做：不修改生产代码或数据库；不调用真实 Provider；不制作 UI；不加入计费、支付、配额、内容审核、公开注册、MVP-2 API Key/openapi 等排除范围。 ## 已确认方案 先以 MVP-0 当前模型和安全红线为基线，输出字段级数据设计、接口契约、状态转换和失败语义。路由候选仅来自启用且未熔断的路由池；429/5xx/超时/连接错误可切换，400/401/内容策略拒绝立即返回。生产继续禁止 AutoMigrate，所有表与 `sys_*`/菜单/API 种子只经可逆 SQL。真实连通性测试只能由授权管理员主动触发一次低成本请求，并审计与冷却。 预计修改文件： - Gitea Wiki：Architecture-and-Code-Map - Gitea Wiki：Business-Rules-and-Glossary - Gitea Wiki：Product-Requirements-Overview - `docs/` 对应核心 Wiki 镜像（通过 sync 生成） ## 需求变化记录 | 日期 | 变化内容 | 原因 | 用户确认 | |---|---|---|---| | 2026-08-21 | 按原规划进入 MVP-1，并先完成三项设计门禁 | 用户确认阶段与拆分 | 是 | ## 设计与原型门禁 - 修改类型：非 UI - 所需设计证据：架构、API、数据、状态或流程设计 - 可编辑设计源链接、版本或事实来源：本工单评论及上述核心 Wiki revision - 本地 HTML 审核快照路径和版本（不适用时说明原因）：不适用，非 UI 技术设计 - 本地浏览方式和资源完整性检查：不适用 - 版本、revision 或确认日期：Architecture `c5a4385d79bfa1513b25cc35f2676e1e451336de`；Business Rules `f7c84780525130d468b4e0b0ff84c412846a9fdc`；Product Requirements `e832dfa2552c6cf97eda1927588bc85392f5fe8e`；2026-08-21 - 状态：已确认 - 确认人、确认时间和覆盖范围：用户于 2026-08-21 验收通过 #16，确认字段、迁移、API、状态、安全、回退和测试设计 - 无需 UI 原型或无需任何原型的原因：本工单不改变界面，只形成后续实现依据 ## 文档影响 - [ ] 不影响长期文档，原因： - [ ] 更新项目档案或本地开发与验证 - [x] 更新架构与代码地图 - [x] 更新业务规则与术语 - [ ] 更新常见修改或故障排查 - [x] 更新其他 Wiki 页面：Product-Requirements-Overview ## 交付文档影响 - [x] 无交付文档影响，原因：只形成内部技术设计，尚无可供最终用户操作的新能力 - [ ] 更新已有交付文档，受众与页面： - [ ] 新增交付文档，受众与页面： - [ ] 需要目标岗位或客户代表验证：否；验证方式：用户评审技术设计 ## 验收标准 - [x] 数据表、字段、索引、外键、删除规则以及 up/down 迁移顺序明确，且不依赖生产 AutoMigrate。 - [x] Provider/Model/路由池、密钥轮换、审计和连通性冷却的 API、权限及脱敏规则明确。 - [x] `images`、`images_edits`、`gemini` 输入输出契约和能力匹配规则明确。 - [x] 加权选路、熔断、最大故障转移、attempt/租约一致性和 retryable 四类测试矩阵明确。 - [x] role_rule、图片 role/note/order、Prompt 覆盖顺序和历史游标契约明确。 - [x] Wiki 在线回读有 revision，核心镜像同步检查通过，并由用户确认后才能放行生产工单。 ## 验证方式 - 人工逐项评审架构、API、数据、状态、安全和回退设计。 - `python dev_scripts/harness.py check --strict` - `python dev_scripts/harness.py sync --check` ## 风险和回退 - 风险：过早锁定不兼容的数据结构、路由语义或管理端契约，导致迁移和 UI 重做；密钥或 SSRF 边界遗漏会形成高风险实现。 - 回退：本工单只更新设计和文档；未确认时不建立或放行生产实现工单。修订通过新的 Wiki revision 和工单变更记录完成。 ## 实施结果与证据（2026-08-21） - 已完成字段级数据设计、三段迁移顺序、Provider/管理 API、portal 提交/游标契约、worker CAS/熔断流程和完整测试矩阵；没有修改生产代码或数据库，也没有调用真实 Provider。 - 核心 Wiki revision：Architecture `c5a4385d79bfa1513b25cc35f2676e1e451336de`；Business Rules `f7c84780525130d468b4e0b0ff84c412846a9fdc`；Product Requirements `e832dfa2552c6cf97eda1927588bc85392f5fe8e`。 - Git 提交：`84eb98075617c24899421a923515058bca3f99bd`，已推送到 `main`。 - 验证：`harness.py check --strict` 通过；DevHarness 42 项单元测试通过；`harness.py sync --check` 通过。 - 任务归档：`Task-16-明确-MVP-1-路由与-Provider-技术设计`，revision `be883f6177e784f6c4a218761b0a0a8cfec0416b`。按规则未导出 `docs/task/`。 - 未验证：没有生产实现，故未执行 MySQL 迁移、Go 产品测试、浏览器 E2E 或真实 Provider 连通性；由后续实现/集成工单覆盖。 - 当前状态：已完成。#17/#18 的技术前置已满足；两个原型分别验收前，生产实现工单仍不放行。 ## 验收结论（2026-08-21） - 用户明确确认 #16 验收通过，详细技术设计由草稿转为已确认。 - 验收文档提交：`ca75c26e39fc643cee8f4c0f7e825dd840350cbb`，已推送到 `main`。 - 最终任务归档 revision：`be883f6177e784f6c4a218761b0a0a8cfec0416b`。 - #17、#18 的技术前置已满足，但原型和生产实现仍遵守各自设计门禁。
ila commented 2026-08-21 14:48:53 +08:00
Author
Owner
Copy Link
Copy Source

技术设计已完成并进入待验收。提交 84eb98075617c24899421a923515058bca3f99bd 已推送；核心 Wiki 三页已在线回读并通过镜像检查；42 项 DevHarness 测试通过。任务归档 revision：f6473774fd188ca3a345c42629318b607e205c2a。本工单未修改生产代码、数据库或调用真实 Provider。

技术设计已完成并进入待验收。提交 `84eb98075617c24899421a923515058bca3f99bd` 已推送；核心 Wiki 三页已在线回读并通过镜像检查；42 项 DevHarness 测试通过。任务归档 revision：`f6473774fd188ca3a345c42629318b607e205c2a`。本工单未修改生产代码、数据库或调用真实 Provider。
ila commented 2026-08-21 14:50:16 +08:00
Author
Owner
Copy Link
Copy Source

归档提交占位符已修正并在线回读。最终任务归档 revision：f86514a6a6dcdeb4d7567b6673fe22953963e42e。

归档提交占位符已修正并在线回读。最终任务归档 revision：`f86514a6a6dcdeb4d7567b6673fe22953963e42e`。
ila closed this issue 2026-08-21 15:02:58 +08:00
ila commented 2026-08-21 15:03:01 +08:00
Author
Owner
Copy Link
Copy Source

用户已验收 #16。技术设计 revision 已更新，验收提交 ca75c26e39fc643cee8f4c0f7e825dd840350cbb 已推送；最终任务归档 revision：be883f6177e784f6c4a218761b0a0a8cfec0416b。本工单关闭，#17/#18 技术前置解除。

用户已验收 #16。技术设计 revision 已更新，验收提交 `ca75c26e39fc643cee8f4c0f7e825dd840350cbb` 已推送；最终任务归档 revision：`be883f6177e784f6c4a218761b0a0a8cfec0416b`。本工单关闭，#17/#18 技术前置解除。
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: OPC/chorus#16