docs: 补全基础设施文档 (DB设计/API规范/MiMoCode配置)

- 03-数据库设计.md: ER图 + 12张表定义 + Redis数据结构 + Migration策略 - 04-API接口规范.md: OpenAPI 3.0 约定 + 全部接口定义 (Auth/APIKey/LLM/Billing/Registry/Skills/IM/Admin) - 05-AGENTS-MiMoCode配置.md: MiMo Code 核心配置文件，包含项目结构/技术栈/开发规范/模块说明至此 docs/ 目录包含完整的6份基础设计文档，可作为 MiMo Code 的上下文输入
2026-06-27 10:51:13 +00:00
1 parent 67c3270aad
commit d9a8a0e93c
@@ -0,0 +1,445 @@
+# AI PaaS 商业平台 — 产品需求文档（PRD）
+
+> 版本: 1.0 | 日期: 2026-06-27
+> 产品名: **AIPaaS**（AI能力服务平台）
+> 目标用户: 个人开发者 / AI 爱好者 / 小型团队
+
+---
+
+## 1. 产品定位
+
+**一句话描述**: 让任何开发者都能像用水电一样使用 AI 能力——注册即用，按量付费。
+
+**核心价值**:
+- **统一入口**: Agent、MCP、Skills、IM Bot、LLM 调用，一个平台全搞定
+- **按需付费**: 不买服务器，不养团队，按 Token 用量付费
+- **能力交易**: 开发者发布 AI 技能，用户购买使用，平台促成交易
+- **多平台接入**: 一个 API Key 调用 DeepSeek/千问/豆包/百度/元宝/智谱
+
+---
+
+## 2. 用户角色
+
+| 角色 | 说明 | 典型操作 |
+|------|------|---------|
+| **平台管理员** | 平台运营者 | 审核能力、管理用户、配置系统、查看收入 |
+| **租户（开发者）** | 注册开发者，创建和发布 AI 能力 | 创建 Agent、发布 Skill、管理 API Key、查看用量 |
+| **终端用户** | 使用 AI 能力的最终用户 | 调用 API、购买 Skill、通过 IM Bot 对话 |
+
+---
+
+## 3. 功能模块
+
+### 3.1 用户认证与多租户（Auth）
+
+#### 3.1.1 注册/登录
+
+| 功能 | 说明 | 优先级 |
+|------|------|--------|
+| 邮箱注册 | 邮箱 + 密码注册，发送验证邮件 | P0 |
+| GitHub OAuth | 第三方登录 | P1 |
+| 微信扫码登录 | 第三方登录 | P2 |
+| 登录 | 邮箱 + 密码，返回 JWT | P0 |
+| Token 刷新 | Access Token 过期后用 Refresh Token 续期 | P0 |
+| 忘记密码 | 邮箱重置密码 | P0 |
+
+#### 3.1.2 多租户
+
+| 功能 | 说明 | 优先级 |
+|------|------|--------|
+| 租户隔离 | 每个用户/团队是独立租户，数据严格隔离 | P0 |
+| 角色体系 | owner / admin / developer / user 四级角色 | P0 |
+| 团队管理 | 邀请成员、分配角色（Phase 2） | P1 |
+
+#### 3.1.3 API Key 管理
+
+| 功能 | 说明 | 优先级 |
+|------|------|--------|
+| 创建 Key | 用户创建 API Key，用于程序化调用 | P0 |
+| 删除 Key | 可随时删除，立即失效 | P0 |
+| Key 列表 | 查看所有 Key 的创建时间、最后使用时间 | P0 |
+| 用途标识 | 给每个 Key 标记用途（如"我的应用"） | P1 |
+
+---
+
+### 3.2 LLM 智能路由（LLM Router）
+
+#### 3.2.1 多平台对接
+
+| 平台 | 协议 | 模型列表 | 优先级 |
+|------|------|---------|--------|
+| DeepSeek | OpenAI 兼容 | deepseek-chat, deepseek-reasoner | P0 |
+| 千问（阿里云） | OpenAI 兼容 | qwen-turbo, qwen-plus, qwen-max | P0 |
+| 豆包（字节） | OpenAI 兼容 | doubao-pro, doubao-lite | P0 |
+| 智谱 GLM | OpenAI 兼容 | glm-4, glm-4-flash | P0 |
+| 元宝（腾讯） | OpenAI 兼容 | yuanbao-pro, yuanbao-lite | P1 |
+| 百度文心 | 自定义（需适配层） | ernie-4.0, ernie-3.5 | P1 |
+| 本地 Ollama | OpenAI 兼容 | 用户自定义 | P1 |
+
+#### 3.2.2 智能路由
+
+| 功能 | 说明 | 优先级 |
+|------|------|--------|
+| 用户选择 | 用户指定使用哪个平台/模型 | P0 |
+| 成本优先 | 自动选择当前最便宜的模型 | P1 |
+| 延迟优先 | 自动选择响应最快的模型 | P1 |
+| 故障转移 | 主模型不可用时自动切换备用模型 | P0 |
+| 负载均衡 | 同一模型多个 API Key 时轮询 | P2 |
+
+#### 3.2.3 调用方式
+
+```
+POST /v1/chat/completions    ← OpenAI 兼容格式，用户直接用
+GET  /v1/models              ← 可用模型列表
+POST /v1/embeddings          ← 向量嵌入（Phase 2）
+```
+
+---
+
+### 3.3 计费系统（Billing）
+
+#### 3.3.1 Credit 模型
+
+| 概念 | 说明 |
+|------|------|
+| **Credit** | 内部统一计费单位，1 Credit = 1000 tokens |
+| **模型系数** | 不同模型消耗不同: deepseek-chat=1.0, deepseek-reasoner=2.0, doubao-pro=1.5 |
+| **余额** | 租户 Credit 余额，先扣后服 |
+| **充值** | 支持手动充值（支付宝/微信支付） |
+| **订阅** | 每月固定 Credit 额度，超出按量计费 |
+
+#### 3.3.2 订阅套餐
+
+| 套餐 | 月费 | 包含 Credits | 超出价格 | QPS 限制 |
+|------|------|-------------|---------|---------|
+| **Free** | ¥0 | 100 | 不允许超出 | 2 |
+| **Pro** | ¥99 | 50,000 | ¥0.01/Credit | 20 |
+| **Team** | ¥499 | 300,000 | ¥0.008/Credit | 100 |
+| **Enterprise** | 定制 | 定制 | 定制 | 定制 |
+
+#### 3.3.3 计费流程
+
+```
+用户调用 API
+    ↓
+1. API Key 验证 → 提取 tenant_id
+    ↓
+2. 余额检查 → 余额不足返回 402
+    ↓
+3. 预扣费（预留最大可能消耗）
+    ↓
+4. 调用 LLM Router → 获取实际消耗
+    ↓
+5. 结算（实际消耗 vs 预扣，多退少补）
+    ↓
+6. 记录流水（不可变审计日志）
+    ↓
+7. 返回结果 + 用量信息
+```
+
+#### 3.3.4 核心原则
+
+| 原则 | 说明 |
+|------|------|
+| **先扣后服** | 先扣减余额，再允许调用，绝不允许"调用成功但余额为负" |
+| **幂等** | 同一请求多次重试，绝不重复扣费 |
+| **原子** | Redis Lua 脚本保证扣费操作原子性 |
+| **可审计** | 每笔 Credit 变动都有 trace_id + 原因 |
+| **实时可见** | Dashboard 上余额和用量秒级更新 |
+
+---
+
+### 3.4 能力注册中心（Capability Registry）
+
+#### 3.4.1 能力类型
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| **agent** | AI 智能体 | 客服机器人、代码助手、翻译器 |
+| **mcp** | MCP 协议服务 | 文件操作、数据库查询、API 调用 |
+| **skill** | 可交易技能 | 文案生成、图片分析、数据分析 |
+| **llm** | LLM 提供商 | DeepSeek、千问、豆包 |
+| **custom** | 自定义 OpenAPI 应用 | 用户自己的 API 服务 |
+
+#### 3.4.2 能力生命周期
+
+```
+draft (草稿) → pending_review (待审核) → active (活跃) → deprecated (弃用)
+                                        ↘ rejected (拒绝)
+```
+
+#### 3.4.3 能力元数据
+
+```yaml
+name: "智能客服 Agent"
+type: agent
+version: "1.2.0"
+description: "基于 GPT-4 的智能客服，支持多轮对话和知识库检索"
+tags: [客服, 多轮对话, 知识库]
+endpoint: "https://my-agent.example.com/api"
+protocol: rest
+pricing:
+  model: per_token
+  rate: 2  # 每 1000 tokens 消耗 2 Credits
+dependencies:
+  - capability_id: "milvus-rag"
+    version: ">=1.0.0"
+status: active
+```
+
+---
+
+### 3.5 Skills 市场
+
+#### 3.5.1 核心功能
+
+| 功能 | 说明 | 优先级 |
+|------|------|--------|
+| 发布技能 | 开发者上传技能，填写描述、定价、示例 | P0 |
+| 浏览市场 | 按分类、标签、评分、热度浏览 | P0 |
+| 搜索技能 | 全文搜索 + 分类过滤 | P0 |
+| 购买技能 | 用 Credit 购买，立即可用 | P0 |
+| 已购管理 | 查看已购技能列表 | P0 |
+| 技能评分 | 用户评分和评论 | P1 |
+| 技能试用 | 免费试用 N 次 | P1 |
+
+#### 3.5.2 计费模式
+
+| 模式 | 说明 | 分成 |
+|------|------|------|
+| per_call | 每次调用扣费 | 平台 25% / 开发者 75% |
+| per_token | 按 Token 扣费 | 平台 25% / 开发者 75% |
+| subscription | 订阅制（月/年） | 平台 25% / 开发者 75% |
+| free | 免费 | 无 |
+
+#### 3.5.3 技能详情页内容
+
+```
+名称 / 作者 / 版本 / 价格
+简介 / 详细描述
+功能列表 / 使用示例
+API 文档 / 调用示例
+评分 / 评论 / 使用次数
+```
+
+---
+
+### 3.6 IM Bot 网关
+
+#### 3.6.1 支持平台
+
+| 平台 | 协议 | 优先级 | 说明 |
+|------|------|--------|------|
+| 微信 | LangBot / OpenClaw | P0 | 个人微信，扫码登录 |
+| QQ | OneBot v11 | P1 | go-cqhttp |
+| 钉钉 | 钉钉开放平台 | P1 | 企业机器人 |
+| 飞书 | 飞书开放平台 | P2 | 企业机器人 |
+| Telegram | Bot API | P2 | 个人机器人 |
+
+#### 3.6.2 核心功能
+
+| 功能 | 说明 | 优先级 |
+|------|------|--------|
+| 多轮对话 | 维护会话上下文（Redis，24h 过期） | P0 |
+| 模型选择 | 用户可切换不同 LLM 模型 | P0 |
+| 指令系统 | /help /model /clear /balance 等快捷指令 | P0 |
+| 消息格式 | 文本 / Markdown / 图片 | P0 |
+| 按钮交互 | 平台支持时提供按钮选择 | P1 |
+| 文件处理 | 接收和发送文件（图片、文档） | P2 |
+
+#### 3.6.3 会话管理
+
+```
+每个用户 + 每个平台 = 独立会话
+会话存储: Redis Hash
+上下文窗口: 最近 20 条消息
+过期时间: 24 小时无活动自动清除
+```
+
+---
+
+### 3.7 用户 Dashboard
+
+#### 3.7.1 页面结构
+
+```
+Dashboard
+├── 首页概览
+│   ├── Credit 余额卡片
+│   ├── 今日/本月用量趋势图
+│   ├── 快捷操作按钮
+│   └── 最近调用记录
+├── API Key 管理
+│   ├── Key 列表（创建时间/最后使用/状态）
+│   ├── 创建新 Key
+│   └── 删除 Key
+├── 用量详情
+│   ├── 按日/周/月图表
+│   ├── 按模型分类统计
+│   ├── 按能力分类统计
+│   └── 导出 CSV
+├── 账单中心
+│   ├── Credit 流水记录
+│   ├── 订阅管理（升级/降级/取消）
+│   └── 充值历史
+├── 我的能力
+│   ├── 已创建的能力列表
+│   ├── 创建新能力
+│   └── 能力统计（调用量/收入）
+├── 市场
+│   ├── 浏览技能
+│   ├── 搜索技能
+│   └── 已购技能
+└── 设置
+    ├── 个人信息
+    ├── 修改密码
+    └── 通知偏好
+```
+
+#### 3.7.2 首页概览卡片
+
+```
+┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
+│ Credit 余额   │ │ 今日调用次数  │ │ 今日消耗      │ │ 当前套餐      │
+│ 12,580       │ │ 342 次       │ │ 1,280 Credits│ │ Pro          │
+│ [充值] [升级] │ │ ↑12% vs 昨日 │ │ ↓5% vs 昨日  │ │ 到期: 07-27  │
+└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
+```
+
+---
+
+### 3.8 管理后台
+
+#### 3.8.1 页面结构
+
+```
+Admin Console
+├── 仪表盘
+│   ├── 核心指标（用户数/API调用量/收入）
+│   ├── 趋势图表
+│   └── 系统状态
+├── 用户管理
+│   ├── 用户列表（搜索/过滤/分页）
+│   ├── 用户详情
+│   └── 封禁/解封
+├── 租户管理
+│   ├── 租户列表
+│   ├── 租户详情（订阅/用量/余额）
+│   └── 调整余额
+├── 能力审核
+│   ├── 待审核列表
+│   ├── 审核详情
+│   └── 通过/拒绝
+├── 系统配置
+│   ├── LLM 提供商配置
+│   ├── 订阅套餐配置
+│   └── 全局限流配置
+└── 数据分析
+    ├── API 调用趋势
+    ├── 热门能力排行
+    └── 收入报表
+```
+
+---
+
+### 3.9 MCP Hub 集成
+
+| 功能 | 说明 | 优先级 |
+|------|------|--------|
+| MCP Server 注册 | 开发者注册自己的 MCP Server | P0 |
+| 工具列表 | 查看已注册 MCP Server 提供的工具 | P0 |
+| 工具调用 | 通过平台调用 MCP 工具（经过计费） | P0 |
+| Server 市场 | 浏览和使用社区 MCP Server | P1 |
+
+---
+
+### 3.10 Agent 编排（LangFlow 集成）
+
+| 功能 | 说明 | 优先级 |
+|------|------|--------|
+| 可视化编辑器 | 嵌入 LangFlow 的 Flow 编辑器 | P1 |
+| Flow 发布 | 将 Flow 发布为可调用的 Agent | P0 |
+| Flow 运行 | API 调用运行 Flow（经过计费） | P0 |
+| Flow 模板 | 预置常用 Flow 模板 | P2 |
+
+---
+
+### 3.11 ACP 协议（Phase 4）
+
+| 功能 | 说明 | 优先级 |
+|------|------|--------|
+| Agent 发现 | 发现已注册的 Agent | P1 |
+| Agent 通信 | Agent 间发送消息 | P1 |
+| 工作流编排 | 多 Agent 协作完成复杂任务 | P2 |
+
+---
+
+## 4. 非功能需求
+
+### 4.1 性能要求
+
+| 指标 | 目标值 |
+|------|--------|
+| API 响应时间 (P95) | < 200ms（不含 LLM 调用） |
+| LLM 调用响应时间 (P95) | < 5s（流式首 token < 1s） |
+| 并发用户数 | 1000+ |
+| API QPS | 500+ |
+| 计费延迟 | < 100ms（Redis Lua） |
+
+### 4.2 安全要求
+
+| 要求 | 说明 |
+|------|------|
+| 数据加密 | 传输 HTTPS，存储敏感字段 AES-256 |
+| 多租户隔离 | PostgreSQL RLS，数据严格隔离 |
+| API Key 安全 | 哈希存储，仅展示一次 |
+| 限流防刷 | 按租户/Key 限流，防止滥用 |
+| 审计日志 | 所有关键操作可追溯 |
+
+### 4.3 可用性要求
+
+| 指标 | 目标值 |
+|------|--------|
+| 系统可用性 | 99.9% |
+| 数据备份 | 每日自动备份 |
+| 故障恢复 | RPO < 1h, RTO < 4h |
+
+---
+
+## 5. Phase 交付范围
+
+### Phase 1（Week 1-4）: 基座
+- ✅ 注册/登录/鉴权
+- ✅ 多租户隔离
+- ✅ 数据库 Schema
+- ✅ API Gateway 基础路由
+- ✅ 项目骨架可运行
+
+### Phase 2（Week 5-8）: 核心引擎
+- ✅ LLM Router（7 个平台对接）
+- ✅ Token 计费引擎
+- ✅ 用量追踪
+- ✅ OpenAI 兼容 API
+- ✅ 流式响应 SSE
+
+### Phase 3（Week 9-12）: 能力治理
+- ✅ Capability Registry
+- ✅ Skills 市场
+- ✅ 用户 Dashboard
+- ✅ 管理后台
+
+### Phase 4（Week 13-16）: 生态扩展
+- ✅ IM Bot 网关（微信/QQ/钉钉）
+- ✅ MCP Hub 集成
+- ✅ LangFlow Agent 集成
+- ✅ ACP 协议基础
+
+### Phase 5（Week 17-20）: 集成上线
+- ✅ 全链路测试
+- ✅ 生产部署
+- ✅ 监控告警
+- ✅ 完整文档
+
+---
+
+*文档结束*