From fb2d1d3a735b93bdd7c6de6a653b4448bf9be8bf Mon Sep 17 00:00:00 2001 From: WangLX <519407855@qq.com> Date: Tue, 18 Aug 2026 14:24:41 +0800 Subject: [PATCH] docs: define product workflow and phase one prototype --- README.md | 4 + docs/01-product-definition-and-prototype.md | 359 ++++++++++++++++++++ docs/DEVELOPMENT_PROCESS.md | 269 +++++++++++++++ 3 files changed, 632 insertions(+) create mode 100644 docs/01-product-definition-and-prototype.md create mode 100644 docs/DEVELOPMENT_PROCESS.md diff --git a/README.md b/README.md index efedd0e..0274c80 100644 --- a/README.md +++ b/README.md @@ -284,3 +284,7 @@ 本文档是模亦灵枢的产品介绍和发展蓝图,用于说明不同阶段的产品形态与长期方向。具体功能、供应商接入、商业规则、服务范围和上线节奏,将根据用户验证、合作资源、技术准备和合规评估逐步确定。 +## 产品开发文档 + +- [产品开发流程](docs/DEVELOPMENT_PROCESS.md) +- [阶段 1:产品定义与原型设计](docs/01-product-definition-and-prototype.md) diff --git a/docs/01-product-definition-and-prototype.md b/docs/01-product-definition-and-prototype.md new file mode 100644 index 0000000..f3e266d --- /dev/null +++ b/docs/01-product-definition-and-prototype.md @@ -0,0 +1,359 @@ +# 阶段 1:产品定义与原型设计 + +## 文档信息 + +- 产品:模亦灵枢 / MOYI Model Intelligence Hub +- 阶段:阶段 1——需求分析与原型设计 +- 当前版本:`v0.1-draft` +- 状态:待评审 +- 目标:明确第一阶段共享额度模型中转站的产品范围和核心使用路径 + +## 一、阶段目标 + +本阶段不进入正式开发,而是先回答四个问题: + +1. 第一版服务谁。 +2. 用户为什么使用模亦灵枢。 +3. 用户完成一次模型调用需要经过哪些步骤。 +4. 第一版做什么、不做什么。 + +阶段结束后,应形成可以交给设计、架构和开发团队继续执行的产品定义与原型产物。 + +## 二、第一阶段产品定义 + +### 产品形态 + +第一阶段的模亦灵枢是一个“统一模型调用服务”: + +- 用户在平台注册并获得账户。 +- 用户查看平台提供的模型、价格和服务状态。 +- 用户创建平台 API Key。 +- 用户通过统一 API 调用多个模型。 +- 平台根据实际用量扣减共享额度。 +- 用户可以查看调用量、费用和余额变化。 + +### 核心价值 + +让开发者不需要分别购买、配置和维护多个模型供应商的调用入口,通过一次接入即可使用多个模型。 + +### 当前商业模式 + +- 平台统一管理上游模型供应商和调用额度。 +- 用户通过预充值、套餐或按量消费使用模型。 +- 不同模型按照不同的使用成本和销售价格计费。 +- 平台负责模型调用、用量统计、余额扣减和基础服务支持。 + +## 三、目标用户 + +### 用户 A:个人开发者 + +#### 特征 + +- 正在开发 AI 应用、插件或个人工具。 +- 不希望为每个模型单独研究接入方式。 +- 需要快速比较模型效果和价格。 + +#### 主要需求 + +- 快速注册和获得 API Key。 +- 查看可用模型和价格。 +- 复制示例代码完成首次调用。 +- 查看余额、用量和调用错误。 + +### 用户 B:小型 AI 应用团队 + +#### 特征 + +- 有多个应用或多个开发环境。 +- 需要统一管理 API Key 和预算。 +- 希望在模型故障时切换到其他模型。 + +#### 主要需求 + +- 为不同项目创建不同 Key。 +- 查看每个项目的调用量和成本。 +- 控制并发、额度和模型访问权限。 +- 使用统一接口替换模型供应商。 + +### 用户 C:平台运营人员 + +#### 特征 + +- 负责供应商、模型、价格、额度和用户管理。 +- 需要及时发现异常请求和供应商故障。 + +#### 主要需求 + +- 配置供应商和模型。 +- 设置成本价、销售价和路由策略。 +- 查看平台收入、成本、调用量和异常情况。 +- 处理充值、退款、封禁和服务故障。 + +## 四、核心用户流程 + +### 开发者首次使用流程 + +```text +访问首页 + ↓ +注册/登录 + ↓ +查看模型目录和价格 + ↓ +创建 API Key + ↓ +获得试用额度或完成充值 + ↓ +复制调用示例 + ↓ +完成第一次模型调用 + ↓ +查看用量与费用 +``` + +### 开发者日常调用流程 + +```text +选择模型 + ↓ +配置 API Key 和调用地址 + ↓ +发送请求 + ↓ +平台执行鉴权、限流和路由 + ↓ +调用上游模型 + ↓ +返回普通或流式响应 + ↓ +记录用量并完成额度结算 +``` + +### 运营人员管理流程 + +```text +添加供应商 + ↓ +配置模型与能力 + ↓ +配置成本价和销售价 + ↓ +设置路由和限流策略 + ↓ +开放给指定用户 + ↓ +观察调用、成本和错误 + ↓ +调整价格、额度或路由 +``` + +## 五、第一版产品信息架构 + +### 面向公众的页面 + +- 首页:介绍平台价值、支持模型和接入方式。 +- 模型目录:查看模型能力、价格、上下文和服务状态。 +- 文档中心:提供快速开始、API 参考和示例代码。 +- 服务状态:展示供应商和平台服务状态。 +- 登录/注册:进入用户控制台。 + +### 用户控制台 + +- 总览:余额、今日用量、请求次数、常用模型和服务状态。 +- API Key:创建、查看、禁用和轮换 Key。 +- 模型:查看可用模型、能力、价格和调用说明。 +- 用量:按时间、模型、项目查看调用量和成本。 +- 账单:充值、套餐、消费流水和退款记录。 +- Playground:使用平台模型进行简单测试。 +- 文档:查看接入代码和常见问题。 + +### 运营后台 + +- 运营总览:用户、请求、收入、成本、余额和告警。 +- 用户管理:用户状态、额度、风险和调用记录。 +- 供应商管理:供应商账户、余额、限额和健康状态。 +- 模型管理:模型信息、上下架、能力和价格。 +- 路由管理:供应商优先级、权重、回退和限流。 +- 账务管理:充值、消费、退款、对账和异常流水。 +- 风控审计:异常用量、封禁、管理员操作和安全事件。 + +## 六、低保真原型页面说明 + +### P01:首页 + +**目的**:让首次访问者在一分钟内理解平台是什么以及如何开始使用。 + +**页面内容**: + +- 品牌名和口号。 +- “一套 API 接入多个模型”的核心说明。 +- 支持的模型类型和供应商入口。 +- 模型目录入口。 +- 快速开始入口。 +- 登录、注册和文档入口。 + +**主要操作**:查看模型、注册、阅读文档。 + +### P02:模型目录 + +**目的**:帮助用户选择合适的模型。 + +**页面内容**: + +- 模型名称和供应商。 +- 模型类型:文本、视觉、Embedding 等。 +- 能力标签:对话、推理、工具调用、结构化输出等。 +- 上下文长度和价格。 +- 服务状态和推荐场景。 +- 调用示例入口。 + +**主要操作**:筛选模型、查看详情、复制调用示例。 + +### P03:用户总览 + +**目的**:让用户快速了解账户和平台使用情况。 + +**页面内容**: + +- 当前余额。 +- 今日/本月消费。 +- 请求次数和 Token 用量。 +- 最近调用记录。 +- 常用模型。 +- 服务状态和异常提醒。 + +**主要操作**:创建 Key、充值、查看用量、进入 Playground。 + +### P04:API Key 管理 + +**目的**:让用户安全管理调用凭证。 + +**页面内容**: + +- Key 名称和所属项目。 +- 创建时间、最后使用时间和状态。 +- 调用权限和额度限制。 +- 创建、禁用和轮换操作。 + +**主要操作**:创建 Key、复制一次性密钥、禁用泄漏密钥。 + +### P05:用量与账单 + +**目的**:让用户理解“用了什么、花了多少、余额如何变化”。 + +**页面内容**: + +- 按日期、模型和项目筛选。 +- 请求次数、输入/输出用量和金额。 +- 成功、失败、限流和退款记录。 +- 余额流水和充值记录。 + +**主要操作**:查看明细、导出账单、充值和申请退款。 + +### P06:Playground + +**目的**:让用户在不写代码的情况下验证模型效果。 + +**页面内容**: + +- 模型选择。 +- Prompt 输入区。 +- 参数设置。 +- 普通/流式响应展示。 +- Token、延迟和费用信息。 +- 复制代码按钮。 + +**主要操作**:测试模型、切换模型、复制调用代码。 + +### P07:运营后台 + +**目的**:让平台运营人员管理供给、价格、用户和风险。 + +**页面内容**: + +- 平台请求量、收入、成本和毛利概览。 +- 供应商健康状态。 +- 模型上下架和价格管理。 +- 用户额度和异常调用。 +- 账务对账和退款处理。 + +**主要操作**:添加供应商、发布模型、调整价格、处理风险。 + +## 七、第一阶段功能优先级 + +### P0:必须具备 + +- 用户注册、登录和基础账户。 +- 模型目录和模型详情。 +- API Key 创建和禁用。 +- 统一模型调用入口。 +- 至少一个模型供应商的真实调用。 +- 共享额度或试用额度。 +- 基础用量和余额记录。 +- 用户调用文档和示例代码。 +- 运营后台的用户、模型和供应商管理。 + +### P1:内测阶段补充 + +- 多供应商路由和基础故障切换。 +- Playground。 +- 充值、退款和套餐。 +- 项目级 Key 和额度。 +- 更完整的账单和对账。 +- 调用状态、错误和服务状态页。 +- 基础风控和异常用量处理。 + +### P2:后续阶段 + +- BYOK。 +- 企业组织、团队和 RBAC。 +- 高级路由策略和 SLA。 +- 知识库、RAG、Agent 和工作流。 +- 模型评测和模型市场。 +- 自托管模型和 GPU 资源管理。 + +## 八、第一阶段明确不做的内容 + +- 自建或自托管大模型。 +- 模型微调和训练任务。 +- 复杂 Agent 编排。 +- 完整知识库和企业数据平台。 +- 多区域多活。 +- 面向所有行业的复杂企业解决方案。 + +## 九、阶段验收标准 + +阶段 1 通过评审需要满足: + +- 能清楚说明第一阶段服务的用户和核心价值。 +- 开发者首次使用流程可以从注册走到第一次调用。 +- 模型目录、API Key、用量和账单之间的关系清楚。 +- 运营人员的供应商、模型、价格和用户管理路径清楚。 +- P0/P1/P2 范围已经确认。 +- 页面和流程不存在无法解释的关键状态。 +- 架构设计可以直接依据本文档继续展开。 + +## 十、待确认事项 + +以下事项需要在进入系统架构设计前确定: + +- 首批接入哪些模型供应商。 +- 第一阶段服务个人开发者还是企业团队为主。 +- 是否提供免费试用额度。 +- 充值、套餐和退款规则。 +- 第一版支持哪些模型类型。 +- 是否需要手机号、邮箱或企业认证。 +- 平台首发地区和数据处理范围。 +- 亦城财富在产品中的联合品牌和运营角色。 + +## 十一、下一阶段产物 + +本阶段确认后,进入阶段 2 的系统设计,产物包括: + +- 系统上下文图和模块架构图。 +- 网关、控制台、账务、模型管理和供应商适配器的模块边界。 +- 核心数据库模型。 +- 统一 API 和供应商适配方案。 +- 认证、密钥、额度和账本的安全设计。 +- 部署环境、监控和故障处理方案。 + diff --git a/docs/DEVELOPMENT_PROCESS.md b/docs/DEVELOPMENT_PROCESS.md new file mode 100644 index 0000000..d970ecd --- /dev/null +++ b/docs/DEVELOPMENT_PROCESS.md @@ -0,0 +1,269 @@ +# 模亦灵枢产品开发流程 + +## 文档目的 + +本文档规定模亦灵枢从产品想法到上线运营的标准开发流程,以及每个阶段必须形成的阶段性产物。 + +流程参考了“需求分析、系统设计、实现、测试、部署、维护”的软件开发生命周期,并结合 MaaS 产品需要持续验证商业模式、模型供应商和用户体验的特点,增加了产品立项、可行性分析和原型评审环节。 + +参考文章:[软件开发全流程:从需求到上线的完整指南](https://blog.csdn.net/2301_80215285/article/details/148679049) + +## 一、总体流程 + +```text +产品立项与可行性分析 + ↓ +需求分析与产品定义 + ↓ +原型与交互设计 + ↓ +系统架构与详细设计 + ↓ +开发实现与代码审查 + ↓ +测试验证与用户验收 + ↓ +部署上线与发布管理 + ↓ +运营监控与持续迭代 +``` + +每个阶段都需要完成三个动作: + +1. 明确本阶段要解决的问题。 +2. 形成可查看、可评审、可追溯的产物。 +3. 通过阶段评审后,才能进入下一阶段。 + +## 二、阶段和标准产物 + +| 阶段 | 核心问题 | 标准产物 | 阶段门禁 | +|---|---|---|---| +| 0. 产品立项 | 为什么做、为谁做、是否值得做 | 产品蓝图、目标用户、商业假设、风险清单 | 明确产品方向和当前阶段目标 | +| 1. 产品定义 | 第一版到底做什么、不做什么 | PRD、用户故事、功能范围、验收标准 | MVP 范围明确,需求无重大歧义 | +| 2. 原型设计 | 用户如何使用、页面如何组织 | 信息架构、用户流程、低保真/高保真原型 | 核心流程可走通,产品体验达成一致 | +| 3. 系统设计 | 如何稳定、安全、可扩展地实现 | 系统架构、数据模型、API、部署和安全设计 | 技术方案可实现,主要风险有应对方案 | +| 4. 开发实现 | 如何分工并交付可运行版本 | 任务拆分、代码、单元测试、代码评审记录 | 核心功能完成并通过代码审查 | +| 5. 测试验收 | 产品是否正确、稳定、安全 | 测试计划、测试用例、缺陷记录、UAT 报告 | P0/P1 缺陷关闭,验收标准达成 | +| 6. 部署上线 | 如何安全发布和回滚 | 部署手册、配置清单、监控告警、回滚方案 | 生产环境可用,发布风险可控 | +| 7. 运营迭代 | 上线后是否产生价值、下一步做什么 | 运营数据、用户反馈、事故记录、版本计划 | 用数据进入下一轮需求分析 | + +## 三、各阶段工作说明 + +### 阶段 0:产品立项与可行性分析 + +#### 工作内容 + +- 明确产品愿景、当前阶段和长期方向。 +- 明确目标用户和核心使用场景。 +- 判断供应商、资金、技术和合规可行性。 +- 明确当前版本的商业模式和不做事项。 +- 记录重大假设、风险和需要外部确认的问题。 + +#### 产物 + +- `README.md`:产品介绍和发展蓝图。 +- 产品定位说明。 +- 目标用户与场景说明。 +- 商业模式假设。 +- 风险和依赖清单。 + +#### 评审重点 + +- 产品方向是否清楚。 +- 第一阶段是否足够聚焦。 +- 是否有无法绕开的外部依赖。 +- 是否具备进入需求分析的条件。 + +### 阶段 1:需求分析与产品定义 + +#### 工作内容 + +- 访谈或整理目标用户需求。 +- 建立用户角色、用户故事和用户流程。 +- 把需求拆成 P0、P1、P2 优先级。 +- 明确功能需求和非功能需求。 +- 编写 MVP 范围与验收标准。 + +#### 产物 + +- PRD。 +- 用户故事地图。 +- 功能清单和优先级。 +- 业务规则说明。 +- MVP 验收标准。 + +#### 评审重点 + +- 每个功能是否对应明确用户价值。 +- 是否存在范围蔓延。 +- 需求是否可以被设计、开发和测试。 +- 关键异常流程是否已经考虑。 + +### 阶段 2:原型与交互设计 + +#### 工作内容 + +- 设计产品信息架构。 +- 设计关键用户流程。 +- 先完成低保真线框,再确定视觉方向。 +- 明确页面状态、空状态、加载状态和错误状态。 +- 设计开发者控制台和运营后台的核心路径。 + +#### 产物 + +- 信息架构图。 +- 用户流程图。 +- 低保真原型。 +- 高保真视觉稿或可点击原型。 +- 页面状态清单。 + +#### 评审重点 + +- 新用户能否完成第一次调用。 +- 用户能否理解模型、价格和用量。 +- 充值、扣费、失败和退款路径是否清楚。 +- 管理员能否完成模型和供应商管理。 + +### 阶段 3:系统架构与详细设计 + +#### 工作内容 + +- 设计系统边界和模块职责。 +- 选择技术栈和部署方式。 +- 设计数据库、API 和事件模型。 +- 设计认证、权限、密钥和数据保护方案。 +- 评估并发、延迟、成本、容灾和可观测性。 +- 记录关键技术决策及其替代方案。 + +#### 产物 + +- 系统架构设计文档。 +- 模块和服务边界说明。 +- 数据库 ER 图和表结构。 +- OpenAPI/API 文档。 +- 安全设计和威胁模型。 +- 部署架构和环境说明。 +- ADR 技术决策记录。 + +#### 评审重点 + +- 是否覆盖 PRD 中的功能和质量要求。 +- 模块职责是否清晰、依赖是否合理。 +- 计量、账本和权限是否可追溯。 +- 供应商故障、重复扣费和数据泄露如何处理。 + +### 阶段 4:开发实现与代码审查 + +#### 工作内容 + +- 将需求和设计拆成可交付任务。 +- 建立开发、测试和生产环境。 +- 按代码规范实现模块。 +- 编写单元测试和必要的集成测试。 +- 通过 Pull Request 进行代码审查。 +- 使用 Git 记录清晰、可回滚的版本历史。 + +#### 产物 + +- 可运行的源代码。 +- 任务看板和迭代记录。 +- 单元测试和集成测试。 +- 代码审查记录。 +- 开发环境和配置说明。 + +### 阶段 5:测试验证与用户验收 + +#### 工作内容 + +- 根据 PRD 和验收标准编写测试用例。 +- 执行单元、集成、系统、性能和安全测试。 +- 验证流式响应、上游故障、限流和计费一致性。 +- 记录、分级和关闭缺陷。 +- 邀请目标用户进行 UAT。 + +#### 产物 + +- 测试计划。 +- 测试用例和测试报告。 +- 缺陷记录。 +- 性能测试报告。 +- 安全检查记录。 +- 用户验收报告。 + +### 阶段 6:部署上线与发布管理 + +#### 工作内容 + +- 准备部署清单和生产配置。 +- 执行数据库迁移和服务发布。 +- 配置监控、日志、告警和状态页。 +- 准备灰度、回滚和应急处理方案。 +- 记录版本变更和已知问题。 + +#### 产物 + +- 部署手册。 +- 发布检查清单。 +- 回滚方案。 +- 监控和告警说明。 +- 版本发布说明。 + +### 阶段 7:运营监控与持续迭代 + +#### 工作内容 + +- 观察注册、调用、留存、成本和收入数据。 +- 收集用户反馈、工单和故障信息。 +- 监控供应商可用性和平台毛利。 +- 定期复盘缺陷、事故和需求变化。 +- 根据数据规划下一版本。 + +#### 产物 + +- 运营数据报告。 +- 用户反馈记录。 +- 事故复盘报告。 +- 版本路线图。 +- 下一轮 PRD。 + +## 四、模亦灵枢的协作方式 + +### 我负责的工作 + +- 整理产品文档和需求。 +- 提出产品、交互和技术方案。 +- 生成原型、架构、接口和测试产物。 +- 在仓库中实施代码和文档变更。 +- 执行验证、修复问题并提交阶段结果。 + +### 你负责确认的事项 + +- 目标用户和商业优先级。 +- 合作方、供应商和资源条件。 +- 品牌、价格、业务规则和合规边界。 +- 每个阶段的范围和验收结果。 + +### 阶段协作规则 + +1. 我先提交本阶段产物草案。 +2. 双方讨论并记录需要修改的决策。 +3. 我根据确认结果完善产物。 +4. 通过阶段评审后提交并推送 Git 仓库。 +5. 再进入下一阶段,避免需求、原型和架构同时变化。 + +## 五、文档和版本规则 + +- 所有阶段产物优先保存到 `docs/`。 +- 文档名称使用阶段编号,便于追踪顺序。 +- 每份文档包含状态、负责人、更新时间和评审结论。 +- 重大产品和技术决策单独记录,不只存在聊天记录中。 +- 阶段完成后使用独立 Git 提交,提交信息说明阶段和产物。 +- 代码、API、部署和测试文档必须与实际版本保持一致。 + +## 六、当前进度 + +- 阶段 0:已完成产品蓝图和品牌定位。 +- 当前阶段:阶段 1,产品定义与原型设计。 +- 下一份产物:第一阶段 PRD、用户流程和低保真原型说明。 +- 后续阶段:系统架构、数据模型、API 设计和开发计划。 +