diff --git a/docs/01-product-definition-and-prototype.md b/docs/01-product-definition-and-prototype.md index f3e266d..ff96b1a 100644 --- a/docs/01-product-definition-and-prototype.md +++ b/docs/01-product-definition-and-prototype.md @@ -1,9 +1,9 @@ -# 阶段 1:产品定义与原型设计 +# 阶段 1:产品定义与原型设计说明 ## 文档信息 - 产品:模亦灵枢 / MOYI Model Intelligence Hub -- 阶段:阶段 1——需求分析与原型设计 +- 阶段:阶段 1——需求分析与产品定义 - 当前版本:`v0.1-draft` - 状态:待评审 - 目标:明确第一阶段共享额度模型中转站的产品范围和核心使用路径 @@ -17,7 +17,7 @@ 3. 用户完成一次模型调用需要经过哪些步骤。 4. 第一版做什么、不做什么。 -阶段结束后,应形成可以交给设计、架构和开发团队继续执行的产品定义与原型产物。 +阶段结束后,应形成可以交给交互设计和视觉设计继续执行的产品定义与原型需求说明;可视化原型通过评审后,才进入系统架构设计。 ## 二、第一阶段产品定义 @@ -89,7 +89,22 @@ - 查看平台收入、成本、调用量和异常情况。 - 处理充值、退款、封禁和服务故障。 -## 四、核心用户流程 +## 四、用户需求与产品需求映射 + +用户需求描述用户希望达成的业务目标;产品需求把目标转化为可实现、可验收的能力。每项需求在评审后分配唯一编号,并在后续原型、接口、开发任务和测试用例中继续引用。 + +| 需求编号 | 用户需求 | 对应产品能力 | 优先级 | 验收方向 | +|---|---|---|---|---| +| UR-001 | 开发者希望只接入一次就能调用多个模型 | 统一 API、标准模型标识、供应商适配 | P0 | 使用同一鉴权和请求格式成功调用已上线模型 | +| UR-002 | 开发者希望快速完成首次调用 | 注册登录、API Key、快速开始、示例代码 | P0 | 新用户可按文档独立完成首次调用 | +| UR-003 | 用户希望清楚知道用了多少、花了多少 | 用量统计、计费、余额和账单流水 | P0 | 每笔调用可追踪到模型、用量、金额和余额变化 | +| UR-004 | 团队希望隔离项目凭证和预算 | 项目级 Key、权限和额度限制 | P1 | 不同项目可独立统计并限制用量 | +| UR-005 | 用户希望上游异常时服务尽量可用 | 健康检查、路由和故障切换 | P1 | 可按策略切换可用供应商且不重复计费 | +| UR-006 | 运营人员希望管理供给、价格和风险 | 供应商、模型、定价、用户和风控后台 | P0 | 配置变更可审计并按权限生效 | + +> 当前为需求矩阵初稿。正常流程、异常场景、非功能指标和测试用例将在需求评审中继续补齐。 + +## 五、核心用户流程 ### 开发者首次使用流程 @@ -147,7 +162,7 @@ 调整价格、额度或路由 ``` -## 五、第一版产品信息架构 +## 六、第一版产品信息架构 ### 面向公众的页面 @@ -177,7 +192,7 @@ - 账务管理:充值、消费、退款、对账和异常流水。 - 风控审计:异常用量、封禁、管理员操作和安全事件。 -## 六、低保真原型页面说明 +## 七、低保真原型页面说明 ### P01:首页 @@ -279,7 +294,7 @@ **主要操作**:添加供应商、发布模型、调整价格、处理风险。 -## 七、第一阶段功能优先级 +## 八、第一阶段功能优先级 ### P0:必须具备 @@ -312,7 +327,7 @@ - 模型评测和模型市场。 - 自托管模型和 GPU 资源管理。 -## 八、第一阶段明确不做的内容 +## 九、第一阶段明确不做的内容 - 自建或自托管大模型。 - 模型微调和训练任务。 @@ -321,7 +336,7 @@ - 多区域多活。 - 面向所有行业的复杂企业解决方案。 -## 九、阶段验收标准 +## 十、阶段验收标准 阶段 1 通过评审需要满足: @@ -330,10 +345,12 @@ - 模型目录、API Key、用量和账单之间的关系清楚。 - 运营人员的供应商、模型、价格和用户管理路径清楚。 - P0/P1/P2 范围已经确认。 +- 用户需求和产品需求之间可以追踪。 +- 核心功能的正常、异常和边界场景已经形成闭环。 - 页面和流程不存在无法解释的关键状态。 -- 架构设计可以直接依据本文档继续展开。 +- 原型设计可以直接依据本文档继续展开。 -## 十、待确认事项 +## 十一、待确认事项 以下事项需要在进入系统架构设计前确定: @@ -346,14 +363,14 @@ - 平台首发地区和数据处理范围。 - 亦城财富在产品中的联合品牌和运营角色。 -## 十一、下一阶段产物 +## 十二、下一阶段产物 -本阶段确认后,进入阶段 2 的系统设计,产物包括: +本阶段确认后,进入阶段 2 的可视化原型设计,产物包括: -- 系统上下文图和模块架构图。 -- 网关、控制台、账务、模型管理和供应商适配器的模块边界。 -- 核心数据库模型。 -- 统一 API 和供应商适配方案。 -- 认证、密钥、额度和账本的安全设计。 -- 部署环境、监控和故障处理方案。 +- 产品信息架构图。 +- 开发者首次调用、日常调用和运营管理的用户流程图。 +- P01—P07 页面的低保真线框图。 +- 核心页面的状态、交互和异常提示说明。 +- 可点击原型或关键页面高保真视觉稿。 +原型评审通过后,才进入阶段 3 的总体、概要和详细设计。 diff --git a/docs/DEVELOPMENT_PROCESS.md b/docs/DEVELOPMENT_PROCESS.md index d970ecd..85227d5 100644 --- a/docs/DEVELOPMENT_PROCESS.md +++ b/docs/DEVELOPMENT_PROCESS.md @@ -4,28 +4,31 @@ 本文档规定模亦灵枢从产品想法到上线运营的标准开发流程,以及每个阶段必须形成的阶段性产物。 -流程参考了“需求分析、系统设计、实现、测试、部署、维护”的软件开发生命周期,并结合 MaaS 产品需要持续验证商业模式、模型供应商和用户体验的特点,增加了产品立项、可行性分析和原型评审环节。 +流程参考了“需求分析、系统设计、实现、测试、部署、维护”的软件开发生命周期,并结合 MaaS 产品需要持续验证商业模式、模型供应商和用户体验的特点,增加了产品立项、可行性分析和原型评审环节。项目采用“阶段基线 + 小步迭代”的方式:每个阶段先形成可评审基线,进入开发后再通过受控变更持续迭代,不机械套用纯瀑布或纯敏捷流程。 -参考文章:[软件开发全流程:从需求到上线的完整指南](https://blog.csdn.net/2301_80215285/article/details/148679049) +参考文章: + +- [软件开发全流程:从需求到上线的完整指南](https://blog.csdn.net/2301_80215285/article/details/148679049) +- [项目开发的完整流程(详解版)](https://blog.csdn.net/weixin_44621343/article/details/115512699) ## 一、总体流程 ```text -产品立项与可行性分析 +项目启动与可行性分析 ↓ -需求分析与产品定义 +用户需求与产品需求 ↓ 原型与交互设计 ↓ -系统架构与详细设计 +总体设计 → 概要设计 → 详细设计 ↓ 开发实现与代码审查 ↓ -测试验证与用户验收 +单元测试 → 集成测试 → 系统测试 → 用户验收 ↓ -部署上线与发布管理 +发布评审与部署上线 ↓ -运营监控与持续迭代 +运营监控 → 价值评估 → 项目复盘 → 持续迭代 ``` 每个阶段都需要完成三个动作: @@ -38,39 +41,46 @@ | 阶段 | 核心问题 | 标准产物 | 阶段门禁 | |---|---|---|---| -| 0. 产品立项 | 为什么做、为谁做、是否值得做 | 产品蓝图、目标用户、商业假设、风险清单 | 明确产品方向和当前阶段目标 | -| 1. 产品定义 | 第一版到底做什么、不做什么 | PRD、用户故事、功能范围、验收标准 | MVP 范围明确,需求无重大歧义 | +| 0. 项目启动 | 为什么做、为谁做、是否值得做 | 项目章程、目标与 ROI 假设、组织与职责、里程碑、风险清单 | 干系人对目标、范围、计划和职责达成一致 | +| 1. 产品定义 | 用户要解决什么、产品第一版做什么 | 用户需求、PRD、需求矩阵、用户故事、验收标准 | MVP 范围明确,正常与异常场景形成闭环 | | 2. 原型设计 | 用户如何使用、页面如何组织 | 信息架构、用户流程、低保真/高保真原型 | 核心流程可走通,产品体验达成一致 | -| 3. 系统设计 | 如何稳定、安全、可扩展地实现 | 系统架构、数据模型、API、部署和安全设计 | 技术方案可实现,主要风险有应对方案 | +| 3. 系统设计 | 如何稳定、安全、可扩展地实现 | 总体设计、概要设计、详细设计、数据模型、API、部署和安全设计 | 架构基线稳定,模块、接口和关键流程可实施 | | 4. 开发实现 | 如何分工并交付可运行版本 | 任务拆分、代码、单元测试、代码评审记录 | 核心功能完成并通过代码审查 | -| 5. 测试验收 | 产品是否正确、稳定、安全 | 测试计划、测试用例、缺陷记录、UAT 报告 | P0/P1 缺陷关闭,验收标准达成 | -| 6. 部署上线 | 如何安全发布和回滚 | 部署手册、配置清单、监控告警、回滚方案 | 生产环境可用,发布风险可控 | -| 7. 运营迭代 | 上线后是否产生价值、下一步做什么 | 运营数据、用户反馈、事故记录、版本计划 | 用数据进入下一轮需求分析 | +| 5. 测试验收 | 产品是否正确、稳定、安全 | 单元/集成/系统测试报告、缺陷记录、UAT 报告 | P0/P1 缺陷关闭,质量指标和验收标准达成 | +| 6. 发布上线 | 是否具备可控上线条件 | 发布评审记录、部署手册、监控告警、回滚方案 | Go/No-Go 评审通过,生产环境可用且可回滚 | +| 7. 运营复盘 | 上线后是否产生价值、下一步做什么 | 运营数据、价值评估、事故与项目复盘、版本计划 | 经验沉淀完成,用数据进入下一轮需求分析 | ## 三、各阶段工作说明 -### 阶段 0:产品立项与可行性分析 +### 阶段 0:项目启动与可行性分析 #### 工作内容 - 明确产品愿景、当前阶段和长期方向。 - 明确目标用户和核心使用场景。 -- 判断供应商、资金、技术和合规可行性。 +- 评估预期价值、投入成本与 ROI 假设。 +- 判断供应商、资金、技术、运营和合规可行性。 - 明确当前版本的商业模式和不做事项。 +- 明确发起人、产品、技术、测试、运营等关键角色及决策机制。 +- 划分阶段、里程碑和沟通机制,召开项目启动会。 - 记录重大假设、风险和需要外部确认的问题。 #### 产物 - `README.md`:产品介绍和发展蓝图。 -- 产品定位说明。 +- 项目章程和项目启动材料。 +- 产品定位与 ROI 假设。 - 目标用户与场景说明。 - 商业模式假设。 +- 组织结构、职责矩阵和沟通机制。 +- 阶段里程碑计划。 - 风险和依赖清单。 #### 评审重点 - 产品方向是否清楚。 - 第一阶段是否足够聚焦。 +- 目标、计划、职责和决策人是否明确。 - 是否有无法绕开的外部依赖。 - 是否具备进入需求分析的条件。 @@ -78,26 +88,33 @@ #### 工作内容 -- 访谈或整理目标用户需求。 +- 收集用户需求,只描述用户目标、业务场景和期望价值。 +- 将用户需求转化为可设计、可开发、可测试的产品需求。 - 建立用户角色、用户故事和用户流程。 - 把需求拆成 P0、P1、P2 优先级。 - 明确功能需求和非功能需求。 +- 建立“用户需求—产品功能—验收标准—测试用例”的追踪关系。 +- 评审正常流程、异常流程、业务闭环和跨系统影响。 - 编写 MVP 范围与验收标准。 #### 产物 -- PRD。 +- 用户需求说明。 +- PRD 和产品需求规格说明。 +- 产品需求矩阵及需求追踪矩阵。 - 用户故事地图。 - 功能清单和优先级。 - 业务规则说明。 - MVP 验收标准。 +- 需求评审记录。 #### 评审重点 - 每个功能是否对应明确用户价值。 - 是否存在范围蔓延。 - 需求是否可以被设计、开发和测试。 -- 关键异常流程是否已经考虑。 +- 正常、异常和边界场景是否完整并形成闭环。 +- 产品、技术和测试是否对需求理解一致。 ### 阶段 2:原型与交互设计 @@ -128,27 +145,36 @@ #### 工作内容 -- 设计系统边界和模块职责。 +- 总体设计:确定系统边界、架构风格、核心子系统和关键技术风险,建立架构基线。 +- 概要设计:划分模块和服务,明确调用关系、接口、数据流、全局数据结构和数据字典。 +- 详细设计:逐模块描述处理流程、状态转换、数据结构、异常处理和关键算法。 - 选择技术栈和部署方式。 - 设计数据库、API 和事件模型。 - 设计认证、权限、密钥和数据保护方案。 - 评估并发、延迟、成本、容灾和可观测性。 +- 使用业务流程图确认需求理解,使用时序图确认跨系统交互。 +- 对核心调用链提前制作技术验证或压测原型。 - 记录关键技术决策及其替代方案。 #### 产物 -- 系统架构设计文档。 +- 总体设计说明书和系统架构图。 +- 概要设计说明书、分层数据流图和数据字典。 +- 各核心模块的详细设计说明书。 - 模块和服务边界说明。 - 数据库 ER 图和表结构。 - OpenAPI/API 文档。 +- 关键业务流程图、状态图和系统时序图。 - 安全设计和威胁模型。 - 部署架构和环境说明。 - ADR 技术决策记录。 +- 技术方案评审记录、工作量估算和交付计划。 #### 评审重点 - 是否覆盖 PRD 中的功能和质量要求。 - 模块职责是否清晰、依赖是否合理。 +- 总体、概要和详细设计是否一致且可追溯。 - 计量、账本和权限是否可追溯。 - 供应商故障、重复扣费和数据泄露如何处理。 @@ -159,7 +185,9 @@ - 将需求和设计拆成可交付任务。 - 建立开发、测试和生产环境。 - 按代码规范实现模块。 -- 编写单元测试和必要的集成测试。 +- 开发人员同步编写并执行单元测试和必要的集成测试。 +- 对高并发网关、流式响应和计费等核心链路尽早执行性能验证。 +- 为关键过程保留结构化日志、指标和调用链,保证执行过程可观察。 - 通过 Pull Request 进行代码审查。 - 使用 Git 记录清晰、可回滚的版本历史。 @@ -168,6 +196,7 @@ - 可运行的源代码。 - 任务看板和迭代记录。 - 单元测试和集成测试。 +- 核心链路性能验证记录。 - 代码审查记录。 - 开发环境和配置说明。 @@ -175,18 +204,20 @@ #### 工作内容 -- 根据 PRD 和验收标准编写测试用例。 -- 执行单元、集成、系统、性能和安全测试。 +- 测试人员在需求阶段设计测试场景,在系统设计阶段完善测试用例。 +- 依次执行单元测试、模块间集成测试和系统测试。 +- 系统测试覆盖功能、回归、性能、稳定性、安全、安装部署和适应性。 - 验证流式响应、上游故障、限流和计费一致性。 - 记录、分级和关闭缺陷。 - 邀请目标用户进行 UAT。 #### 产物 -- 测试计划。 -- 测试用例和测试报告。 +- 测试计划和需求覆盖矩阵。 +- 单元、集成和系统测试用例及报告。 - 缺陷记录。 - 性能测试报告。 +- 稳定性测试报告。 - 安全检查记录。 - 用户验收报告。 @@ -195,6 +226,7 @@ #### 工作内容 - 准备部署清单和生产配置。 +- 召开发布评审会,回溯范围、质量、风险、预期效果和上线条件。 - 执行数据库迁移和服务发布。 - 配置监控、日志、告警和状态页。 - 准备灰度、回滚和应急处理方案。 @@ -203,12 +235,13 @@ #### 产物 - 部署手册。 +- 发布评审记录和 Go/No-Go 结论。 - 发布检查清单。 - 回滚方案。 - 监控和告警说明。 - 版本发布说明。 -### 阶段 7:运营监控与持续迭代 +### 阶段 7:运营监控、项目复盘与持续迭代 #### 工作内容 @@ -216,17 +249,48 @@ - 收集用户反馈、工单和故障信息。 - 监控供应商可用性和平台毛利。 - 定期复盘缺陷、事故和需求变化。 +- 对照立项时的目标和 ROI 假设评估实际产品价值。 +- 复盘各阶段的问题、原因和改进动作,不以追责为目的。 - 根据数据规划下一版本。 #### 产物 - 运营数据报告。 - 用户反馈记录。 +- 产品价值评估报告。 - 事故复盘报告。 +- 项目复盘和改进行动清单。 - 版本路线图。 - 下一轮 PRD。 -## 四、模亦灵枢的协作方式 +## 四、项目治理与需求变更 + +### 基线和迭代 + +- 产品蓝图、已评审需求、原型、架构、API 和发布版本分别建立基线。 +- 通用能力进入产品基线;客户或合作方的个性化诉求先判断能否抽象为通用需求。 +- 研发过程允许小步迭代,但不能绕过需求、设计、测试和发布的责任边界。 + +### 需求变更 + +1. 记录变更原因、提出人、目标用户和期望价值。 +2. 分析对范围、原型、架构、数据、接口、测试、进度和成本的影响。 +3. 由产品负责人和项目决策人确认接受、延期或拒绝。 +4. 更新受影响的基线文档、需求矩阵、任务和测试用例。 +5. 在版本说明中记录变更,避免只在口头或聊天中确认。 + +### 核心角色 + +| 角色 | 主要责任 | +|---|---| +| 项目发起人/决策人 | 确认目标、预算、重大范围和阶段放行 | +| 产品负责人 | 用户研究、PRD、优先级、原型和产品验收 | +| 技术负责人 | 技术方案、架构基线、估算、质量和发布技术决策 | +| 开发人员 | 详细设计、实现、单元测试、自测和代码审查 | +| 测试负责人 | 测试策略、用例、系统测试、缺陷闭环和质量意见 | +| 运维/运营负责人 | 环境、发布、监控、应急、用户反馈和价值数据 | + +## 五、模亦灵枢的协作方式 ### 我负责的工作 @@ -251,19 +315,19 @@ 4. 通过阶段评审后提交并推送 Git 仓库。 5. 再进入下一阶段,避免需求、原型和架构同时变化。 -## 五、文档和版本规则 +## 六、文档和版本规则 - 所有阶段产物优先保存到 `docs/`。 - 文档名称使用阶段编号,便于追踪顺序。 - 每份文档包含状态、负责人、更新时间和评审结论。 +- 需求使用唯一编号,并在设计、接口、任务、测试和发布记录中引用。 - 重大产品和技术决策单独记录,不只存在聊天记录中。 - 阶段完成后使用独立 Git 提交,提交信息说明阶段和产物。 - 代码、API、部署和测试文档必须与实际版本保持一致。 -## 六、当前进度 +## 七、当前进度 - 阶段 0:已完成产品蓝图和品牌定位。 -- 当前阶段:阶段 1,产品定义与原型设计。 -- 下一份产物:第一阶段 PRD、用户流程和低保真原型说明。 +- 当前阶段:阶段 1,产品定义;现有文档为待评审草案。 +- 下一份产物:补齐需求矩阵并完成阶段 1 评审,随后进入阶段 2 可视化原型设计。 - 后续阶段:系统架构、数据模型、API 设计和开发计划。 -