From fdf3a328ce6ea31d2d7d9ffc4ad28ca4ce21d5c8 Mon Sep 17 00:00:00 2001 From: WangLX <519407855@qq.com> Date: Fri, 21 Aug 2026 18:22:35 +0800 Subject: [PATCH] docs: clarify staged information readiness --- README.md | 1 + docs/01-product-definition-and-prototype.md | 2 + ...n-source-baseline-and-development-nodes.md | 6 +- docs/05-information-readiness-checklist.md | 161 ++++++++++++++++++ 4 files changed, 168 insertions(+), 2 deletions(-) create mode 100644 docs/05-information-readiness-checklist.md diff --git a/README.md b/README.md index 559f995..2fdcb2a 100644 --- a/README.md +++ b/README.md @@ -298,6 +298,7 @@ MaaS 模型服务与应用开发 - [阶段 2:可视化交互原型](docs/02-interactive-prototype.md) - [双端产品形态与开源技术底座](docs/03-dual-portal-and-open-source-foundation.md) - [开源技术基线与开发节点](docs/04-open-source-baseline-and-development-nodes.md) +- [信息准备与阶段门禁清单](docs/05-information-readiness-checklist.md) ## 前端原型 diff --git a/docs/01-product-definition-and-prototype.md b/docs/01-product-definition-and-prototype.md index 3f64b8c..b0cdb10 100644 --- a/docs/01-product-definition-and-prototype.md +++ b/docs/01-product-definition-and-prototype.md @@ -583,6 +583,8 @@ ## 十一、待确认事项 +本节是完整的长期输入清单,不代表阶段 1 就要全部提供。每项信息的准备时点、开发门禁和上线要求见[信息准备与阶段门禁清单](05-information-readiness-checklist.md)。当前进入 D4 前,优先确认第一版边界、管理员账号、首个验收方式,以及是否先用 Mock 推进。 + 以下事项先保留为待填写决策项。阶段 1 不要求一次性全部确定,但在涉及对应开发范围前必须完成确认。 ### A. 首批模型与供应商 diff --git a/docs/04-open-source-baseline-and-development-nodes.md b/docs/04-open-source-baseline-and-development-nodes.md index d817376..cf12fcf 100644 --- a/docs/04-open-source-baseline-and-development-nodes.md +++ b/docs/04-open-source-baseline-and-development-nodes.md @@ -120,9 +120,11 @@ POST /v1/tasks | D7 管理运营 | 接入用户额度、供应商、路由、并发、审计 | 管理端真实 API 与高风险操作审计 | 关键管理操作可追踪和回滚 | | D8 测试与部署 | 完成功能、性能、安全和上线准备 | 自动化测试、部署、监控、告警、回滚 | UAT 与发布评审通过 | -## 五、D2 前置资源清单 +## 五、分阶段资源与信息门禁 -以下内容在进入 D2/D3 时逐项确认,暂未确定项可以先使用本地开发替代方案: +完整的信息准备时点见[信息准备与阶段门禁清单](05-information-readiness-checklist.md)。本节保留工程资源视角,避免把生产资源误认为当前开发前置条件。 + +以下内容在对应节点前逐项确认,暂未确定项可以先使用本地开发替代方案: | 资源 | 开发阶段替代 | 生产前需要确认 | |---|---|---| diff --git a/docs/05-information-readiness-checklist.md b/docs/05-information-readiness-checklist.md new file mode 100644 index 0000000..3a98a76 --- /dev/null +++ b/docs/05-information-readiness-checklist.md @@ -0,0 +1,161 @@ +# 信息准备与阶段门禁清单 + +## 一、先看结论 + +产品文档中的“待确认事项”是完整的长期输入清单,不代表现在必须一次性提供。模亦灵枢采用分阶段准备: + +| 时间点 | 必须掌握的信息 | 可以暂时不确定 | +|---|---|---| +| 当前进入 D4 前 | 第一版边界、首个管理员、认证规则、Key 目标、首批真实调用方式 | 供应商最终名单、价格、支付、公开注册、企业认证、正式合规结论 | +| D4 真实供应商联调前 | 至少一个供应商/模型的接口资料、测试 Key、模型能力和限制 | 第二家供应商、复杂路由、最终计费 | +| 测试环境/UAT 前 | 测试部署资源、测试账号、测试模型、测试数据、验收场景、容量假设 | 生产域名、正式支付、最终 SLA | +| 生产开放前 | 运营主体、域名/TLS/备案、供应商授权、数据与合规、计费支付、安全运维和容量 | 后续 MaaS、自托管模型等长期能力 | + +## 二、现在必须确认 + +以下内容是进入 D4 仍需要项目负责人确认的最小集合。没有这些信息,可以继续做 Schema、Mock 和页面;但不能完成真实供应商调用验收。 + +| 编号 | 需要确认 | 当前状态/默认处理 | +|---|---|---| +| N-01 | 第一版目标用户 | 已确认:先服务模灵科技内部项目,再逐步邀请外部开发者 | +| N-02 | 第一版模型范围 | 已确认:不是只做大语言模型,覆盖文本、图像、音频、视频、Embedding 和生成式 3D | +| N-03 | 第一版准入 | 已确认:邀请码注册;手机号/邮箱公开注册只预留 | +| N-04 | 第一版额度 | 已确认:管理员发放;充值/套餐入口保留但暂不启用真实支付 | +| N-05 | 登录与权限 | 已确认:用户端和管理端分权限;企业认证可后置 | +| N-06 | 首个管理员账号 | 需要提供一个开发环境管理员账号,密码由你本地设置,不提交 Git | +| N-07 | 首个接入验收方式 | 需要选择一种实际调用方式作为验收,例如标准 HTTP/SDK 接入;不绑定某个客户端品牌 | +| N-08 | D4 是否先使用 Mock | 可以先确认“先 Mock 后真实供应商”;供应商未定时默认这样推进 | + +### 现在不需要提供密钥 + +真实供应商 Key、服务器密码、数据库密码、短信/邮件密钥都不应发到聊天或写入仓库。需要联调时,只在你本地 .env 或服务器密钥管理中配置。 + +## 三、开发过程中逐步确认 + +这些信息不是今天必须全部确定,而是在对应节点开始前补齐。 + +### D4:Key 与模型目录 + +真实供应商联调前必须有: + +- 供应商名称、API 文档、Base URL、认证方式和测试环境。 +- 至少一个可调用的测试 Key,或由供应商提供的测试账号。 +- 模型名称/版本、模型类型、输入输出格式、同步/流式/异步模式。 +- 输入大小、输出大小、超时、速率、并发、额度和内容限制。 +- 3D 模型的任务提交、进度查询、回调/轮询、结果文件格式和下载方式。 +- 统一模型名是否由 MOYI 自定义,以及供应商模型 ID 如何映射。 + +可以继续留空: + +- 第二家及更多供应商。 +- 最终价格、套餐、充值和退款。 +- 复杂路由、自动降级和跨区域部署。 +- 自托管模型和企业 BYOK。 + +### D5:调用与计量 + +开始真实计量前必须有: + +- 各模型的计量单位,例如 Token、请求、图片张数、任务次数、文件大小或时长。 +- 成功、失败、超时、取消、重试和供应商切换的计量处理。 +- 额度预占、结算、释放和幂等规则。 +- API 错误格式、请求 ID、流式断开和异步任务状态。 + +如果暂时不收费,可以先使用“管理员额度 + 记录用量、不做支付”的测试规则。 + +### D6:异步任务与 3D + +开始 3D/图像/视频真实任务前必须有: + +- 一个可测试的任务型模型或 AI SoulMate 测试接口。 +- 测试输入文件、输出文件格式、文件大小限制和保存周期。 +- 任务状态定义、回调签名或轮询频率、超时和重试规则。 +- 失败、取消、重复提交和结果下载的验收样例。 + +## 四、测试环境/UAT 前必须确认 + +测试环境重点是“能不能稳定验证”,不要求已经具备生产规模。 + +### 环境资源 + +| 资源 | 测试环境最低要求 | 生产前再升级 | +|---|---|---| +| 应用服务器 | 一台可运行 Docker 的开发/测试服务器,或本机 | 高可用、扩容、备份和故障切换 | +| PostgreSQL | 独立测试数据库,能重建和清理 | 高可用、加密、备份、恢复演练 | +| Redis/队列 | D6 之前准备测试实例;D4/D5 可暂用同步或内存方案 | 持久化、容量和故障恢复 | +| 对象存储 | D6 之前准备 MinIO 或测试 OSS | 地区、生命周期、跨域和下载授权 | +| 域名/TLS | UAT 可使用内网域名或测试域名 | 正式域名、证书、备案和网关策略 | +| 供应商 | 至少一个测试账号和测试 Key | 商业授权、正式额度、SLA 和账务 | + +### UAT 资料 + +- 测试用户:管理员、普通用户、停用用户各至少一个。 +- 测试邀请码:单次、多人次、过期、停用各一个。 +- 测试模型:至少一个同步/流式模型和一个异步模型;暂时没有真实 3D 时可用 Mock。 +- 测试数据:文本、图片、音频、视频、3D 示例及禁止上传的敏感数据样例。 +- 验收场景:注册、登录、创建 Key、模型发现、调用、排队、失败、用量、额度和管理审计。 +- 容量假设:预计测试用户数、并发请求数、异步任务数和可接受等待时间。 + +UAT 通过的标准不是“所有模型都接入”,而是首批约定模型的核心闭环可重复完成。 + +## 五、生产开放前必须确认 + +生产信息分为业务、供应商、合规、安全和运维五类。没有这些信息,系统可以在内网或封闭测试环境运行,但不建议面向公众开放。 + +### 业务与运营 + +- 运营主体、客服/故障联系人、用户支持方式和账号封禁流程。 +- 外部开放对象、邀请范围、开放地区和服务时间。 +- 额度发放、价格、计费单位、失败退款、充值、发票和对账规则。 +- 用户协议、隐私政策、服务条款、模型使用限制和申诉机制。 + +### 供应商与模型 + +- 供应商是否允许 API 转售、共享额度、二次封装和商业化。 +- 正式供应商账户、额度、限流、并发、区域、SLA 和账单。 +- 模型版本锁定、上下线流程、价格变更和故障切换策略。 +- 生成式 3D 的素材授权、结果使用权和第三方许可证。 + +### 地区与合规 + +- 服务地区、服务器和数据库所在地区、是否跨境传输。 +- 域名、备案、TLS、支付主体和开票主体。 +- 注册信息、Prompt、上传文件、结果文件和日志的保存期限与删除方式。 +- 内容安全审核、违规处置、审计留存、个人信息保护和生成内容标识要求。 + +以上内容是上线准备清单,不构成法律意见;正式上线前需要由运营主体和法务确认。 + +### 安全与运维 + +- 生产密钥管理、最小权限、轮换、撤销和泄露应急流程。 +- 数据库、对象存储和日志备份,恢复目标和恢复演练。 +- 监控、告警、请求追踪、供应商故障处理和发布回滚。 +- 平台总并发、用户/项目/API Key 限制、队列长度、超时和扩容阈值。 +- 生产镜像、依赖许可证、漏洞扫描和变更审批记录。 + +## 六、可以后置的信息 + +以下内容不应阻塞当前 D3/D4: + +- 手机号/邮箱公开注册和真实短信/邮件验证码。 +- 企业认证、组织、团队和复杂审批。 +- 充值、套餐、支付、退款、发票和财务对账。 +- 多供应商智能路由、复杂降级和跨区域容灾。 +- BYOK、专属模型、自托管模型和 GPU 调度。 +- 知识库、RAG、Agent、工作流和模型评测平台。 +- 正式公网域名、品牌营销和大规模容量承诺。 + +## 七、你现在只需要准备的内容 + +为了继续 D4,你可以按下面 8 项回复,暂时不知道的写“待定”即可: + +1. 第一个开发环境管理员登录账号。 +2. 首个真实验收方式:HTTP、SDK 或某个 AI 应用接入。 +3. 是否先用 Mock 完成 Key/模型目录,再接真实供应商。 +4. 首个准备接入的模型类型,建议先选一个同步模型和一个异步/3D 模型。 +5. 是否已有可用于测试的供应商或 AI SoulMate 接口。 +6. 测试环境准备在本机、现有服务器,还是另建测试服务器。 +7. 第一轮内部测试预计几个人、几个项目。 +8. 是否接受当前默认规则:邀请码、管理员额度、暂不支付、公开注册后置。 + +除第 1—3 项外,其余都可以先填“待定”,我们继续用 Mock 和可替换配置推进。