From d9a8a0e93c26293e4ff1f95b5cd1d51d10757c81 Mon Sep 17 00:00:00 2001 From: qyyfw Date: Sat, 27 Jun 2026 10:51:13 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=A8=E5=9F=BA=E7=A1=80?= =?UTF-8?q?=E8=AE=BE=E6=96=BD=E6=96=87=E6=A1=A3=20(DB=E8=AE=BE=E8=AE=A1/AP?= =?UTF-8?q?I=E8=A7=84=E8=8C=83/MiMoCode=E9=85=8D=E7=BD=AE)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 的上下文输入 --- docs/01-PRD-产品需求文档.md | 445 +++++++++++++++++++++++++ docs/02-系统架构设计.md | 453 ++++++++++++++++++++++++++ docs/03-数据库设计.md | 443 +++++++++++++++++++++++++ docs/04-API接口规范.md | 572 +++++++++++++++++++++++++++++++++ docs/05-AGENTS-MiMoCode配置.md | 186 +++++++++++ 5 files changed, 2099 insertions(+) create mode 100644 docs/01-PRD-产品需求文档.md create mode 100644 docs/02-系统架构设计.md create mode 100644 docs/03-数据库设计.md create mode 100644 docs/04-API接口规范.md create mode 100644 docs/05-AGENTS-MiMoCode配置.md diff --git a/docs/01-PRD-产品需求文档.md b/docs/01-PRD-产品需求文档.md new file mode 100644 index 0000000..574aaf0 --- /dev/null +++ b/docs/01-PRD-产品需求文档.md @@ -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）: 集成上线 +- ✅ 全链路测试 +- ✅ 生产部署 +- ✅ 监控告警 +- ✅ 完整文档 + +--- + +*文档结束* diff --git a/docs/02-系统架构设计.md b/docs/02-系统架构设计.md new file mode 100644 index 0000000..749c348 --- /dev/null +++ b/docs/02-系统架构设计.md @@ -0,0 +1,453 @@ +# AI PaaS 商业平台 — 系统架构设计 + +> 版本: 1.0 | 日期: 2026-06-27 +> 基于: 5 平台交叉验证共识 + 方案二（稳扎稳打） + +--- + +## 1. 架构总览 + +### 1.1 分层架构图 + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ 用户入口层 (Access) │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐│ +│ │ Web UI │ │ REST API │ │ WebSocket│ │ CLI │ │ IM Bot ││ +│ │ (React) │ │ │ │ (SSE) │ │ (Phase5) │ │ (Phase4) ││ +│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘│ +└───────┼──────────────┼──────────────┼──────────────┼──────────────┼──────┘ + │ │ │ │ │ + ▼ ▼ ▼ ▼ ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ API Gateway (Apache APISIX 3.15+) │ +│ │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐ │ +│ │jwt-auth │ │key-auth │ │limit- │ │api- │ │ proxy-rewrite │ │ +│ │JWT验证 │ │Key验证 │ │count │ │breaker │ │ + CORS │ │ +│ │ │ │ │ │限流 │ │熔断 │ │ │ │ +│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────────────┘ │ +│ │ +│ 路由表: │ +│ /api/v1/auth/* → auth-service:8081 │ +│ /api/v1/capabilities/* → registry-service:8082 │ +│ /v1/chat/completions → openapi-gateway:8083 │ +│ /api/v1/billing/* → billing-service:8084 │ +│ /api/v1/skills/* → skills-service:8085 │ +│ /api/v1/admin/* → admin-service:8086 │ +│ /api/v1/im/* → im-gateway:8087 │ +│ /api/v1/mcp/* → mcp-proxy:8088 │ +│ /api/v1/agent/* → agent-proxy:8089 │ +└─────────────────────────────┬───────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ 核心业务层 (Core Services) │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────────┐ │ +│ │ auth-service │ │ billing-svc │ │ registry-service │ │ +│ │ Go :8081 │ │ Go :8084 │ │ Go :8082 │ │ +│ │ │ │ │ │ │ │ +│ │ • JWT 验证 │ │ • Credit 扣费│ │ • 能力注册/注销 │ │ +│ │ • API Key │ │ • 余额查询 │ │ • 版本管理 │ │ +│ │ • RBAC 角色 │ │ • 流水记录 │ │ • 服务发现 │ │ +│ │ • 租户上下文 │ │ • 订阅管理 │ │ • 状态管理 │ │ +│ │ • 注册/登录 │ │ • 充值 │ │ • gRPC + REST │ │ +│ └──────┬───────┘ └──────┬───────┘ └──────────────┬───────────────┘ │ +│ │ │ │ │ +│ ┌──────┴───────┐ ┌──────┴───────┐ ┌─────────────┴───────────────┐ │ +│ │openapi-gw │ │ metering-svc │ │ skills-service │ │ +│ │Go :8083 │ │ Go :8090 │ │ Go :8085 │ │ +│ │ │ │ │ │ │ │ +│ │• OpenAI API │ │• Kafka消费 │ │• 技能发布/审核 │ │ +│ │• 请求拦截链 │ │• PG持久化 │ │• 市场浏览/搜索 │ │ +│ │• 流式 SSE │ │• 预聚合 │ │• 购买/分成 │ │ +│ │• 用量上报 │ │• 用量查询 │ │• 全文搜索 │ │ +│ └──────┬───────┘ └──────────────┘ └─────────────────────────────┘ │ +│ │ │ +│ ┌──────┴───────┐ ┌──────────────┐ ┌─────────────────────────────┐ │ +│ │llm-router │ │im-gateway │ │ admin-service │ │ +│ │Go :8091 │ │ Go :8087 │ │ Go :8086 │ │ +│ │ │ │ │ │ │ │ +│ │• 多平台适配 │ │• 微信/QQ/钉钉│ │• 用户管理 │ │ +│ │• 智能路由 │ │• 会话管理 │ │• 租户管理 │ │ +│ │• 故障转移 │ │• 消息收发 │ │• 能力审核 │ │ +│ │• 连接池 │ │• 上下文注入 │ │• 系统配置 │ │ +│ └──────────────┘ └──────────────┘ └─────────────────────────────┘ │ +└─────────────────────────────┬───────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ AI 能力层 (AI Capabilities) │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐│ +│ │ LangFlow │ │ mcp-hub │ │ Milvus │ │ vLLM ││ +│ │ [开源] │ │ [开源] │ │ [开源] │ │ [开源] ││ +│ │ Agent 编排 │ │ MCP 服务管理 │ │ 向量数据库 │ │ 模型推理 ││ +│ │ :7860 │ │ :3001 │ │ :19530 │ │ :8000 ││ +│ └──────────────┘ └──────────────┘ └──────────────┘ └────────────┘│ +└─────────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ 外部 LLM 平台 (External LLM) │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐│ +│ │ DeepSeek │ │ 千问 │ │ 豆包 │ │ 智谱 │ │ 百度/元宝 ││ +│ │ API │ │ API │ │ API │ │ API │ │ API ││ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────────┘│ +└─────────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ 基础设施层 (Infrastructure) │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐│ +│ │PostgreSQL│ │ Redis 7 │ │ Kafka │ │ Keycloak │ │ Prometheus ││ +│ │ 16 │ │ │ │ 3.x │ │ 25+ │ │ + Grafana ││ +│ │ 主数据库 │ │ 缓存+Lua │ │ 事件总线 │ │ 认证 │ │ 监控 ││ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────────┘│ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 2. 核心数据流 + +### 2.1 LLM 调用 + 计费完整流程 + +``` +用户代码 APISIX openapi-gw billing-svc + │ │ │ │ + │ POST /v1/chat/completions │ │ │ + │ Authorization: Bearer xxx │ │ │ + ├──────────────────────────→│ │ │ + │ │ jwt-auth 验证 │ │ + │ │ 提取 tenant_id │ │ + │ │ 注入 X-Tenant-Id │ │ + │ ├───────────────────→│ │ + │ │ │ │ + │ │ │ 1. API Key 验证 │ + │ │ │ (→ auth-svc) │ + │ │ │ │ + │ │ │ 2. 余额检查 │ + │ │ │ GET /balance │ + │ │ ├───────────────────→│ + │ │ │ balance: 12580 │ + │ │ │←───────────────────│ + │ │ │ │ + │ │ │ 3. 路由到 LLM │ + │ │ │ Router │ + │ │ │ │ + │ │ │ llm-router │ + │ │ │ ├─选择 DeepSeek │ + │ │ │ ├─调用 API │ + │ │ │ └─返回 + usage │ + │ │ │ │ + │ │ │ 4. 计费扣减 │ + │ │ │ POST /meter │ + │ │ │ {tokens: 1280} │ + │ │ ├───────────────────→│ + │ │ │ Redis Lua 扣费 │ + │ │ │ balance: 12580 │ + │ │ │ → 11300 │ + │ │ │←───────────────────│ + │ │ │ │ + │ │ │ 5. 异步上报用量 │ + │ │ │ → Kafka │ + │ │ │ │ + │ {choices: [...], │ │ │ + │ usage: { │ │ │ + │ prompt_tokens: 800, │ │ │ + │ completion_tokens: 480│ │ │ + │ }} │ │ │ + │←──────────────────────────│←───────────────────│ │ + │ │ │ │ +``` + +### 2.2 流式 SSE 响应流程 + +``` +用户浏览器 APISIX openapi-gw llm-router + │ │ │ │ + │ POST /v1/chat/completions │ │ │ + │ stream: true │ │ │ + ├──────────────────────────→│───────────────────→│───────────────────→│ + │ │ │ │ + │ │ │ HTTP 200 │ + │ │ │ Content-Type: │ + │ │ │ text/event-stream │ + │←──────────────────────────│←───────────────────│←───────────────────│ + │ │ │ │ + │ data: {"choices":[{ │ │ │ + │ "delta":{"content":"你"}}│ │ │ + │←──────────────────────────│←───────────────────│←───────────────────│ + │ │ │ │ + │ data: {"choices":[{ │ │ │ + │ "delta":{"content":"好"}}│ │ │ + │←──────────────────────────│←───────────────────│←───────────────────│ + │ │ │ │ + │ data: [DONE] │ │ │ + │←──────────────────────────│←───────────────────│←───────────────────│ + │ │ │ │ + │ │ │ 4. 计费扣减 │ + │ │ │ 5. 上报用量 │ +``` + +--- + +## 3. 服务间通信 + +### 3.1 同步调用（HTTP/gRPC） + +| 调用方 | 被调用方 | 协议 | 说明 | +|--------|---------|------|------| +| APISIX | 所有后端服务 | HTTP | 路由转发 | +| openapi-gw | auth-service | HTTP | JWT 验证 | +| openapi-gw | billing-svc | HTTP | 余额检查+扣费 | +| openapi-gw | llm-router | HTTP | LLM 调用 | +| openapi-gw | registry-service | gRPC | 能力查询（内部） | +| skills-service | billing-svc | HTTP | 购买扣费 | +| im-gateway | llm-router | HTTP | LLM 调用 | +| registry-service | mcp-hub | HTTP | MCP 同步 | +| registry-service | langflow | HTTP | Agent 同步 | + +### 3.2 异步通信（Kafka） + +| 生产者 | Topic | 消费者 | 说明 | +|--------|-------|--------|------| +| openapi-gw | usage.events | metering-svc | LLM 用量上报 | +| billing-svc | billing.events | metering-svc | 计费事件 | +| registry-svc | capability.events | mcp-hub, langflow | 能力变更通知 | + +### 3.3 缓存策略（Redis） + +| Key 模式 | 类型 | TTL | 说明 | +|----------|------|-----|------| +| auth:session:{token} | Hash | 24h | 用户会话 | +| auth:apikey:{key_hash} | Hash | 1h | API Key 缓存 | +| billing:balance:{tenant_id} | String | - | Credit 余额（毫 Credit） | +| billing:idempotency:{tenant_id}:{key} | Hash | 24h | 幂等键 | +| billing:daily:{tenant_id}:{YYYY-MM-DD} | Hash | 7d | 每日统计 | +| billing:subscription:{tenant_id} | Hash | - | 订阅信息 | +| ratelimit:{tenant_id}:{window} | String | 60s | 限流计数 | +| im:session:{platform}:{user_id} | Hash | 24h | IM 会话上下文 | + +--- + +## 4. 数据库架构 + +### 4.1 PostgreSQL Schema 概览 + +``` +┌─────────────────────────────────────────────────────────┐ +│ PostgreSQL 16 │ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌────────────────┐ │ +│ │ tenants │ │ users │ │ capabilities │ │ +│ │ (租户) │←─│ (用户) │ │ (能力) │ │ +│ └──────┬──────┘ └─────────────┘ └───────┬────────┘ │ +│ │ │ │ +│ ┌──────┴──────┐ ┌─────────────┐ ┌───────┴────────┐ │ +│ │ subscriptions│ │ api_keys │ │ cap_versions │ │ +│ │ (订阅) │ │ (API密钥) │ │ (能力版本) │ │ +│ └─────────────┘ └─────────────┘ └────────────────┘ │ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌────────────────┐ │ +│ │credit_trans │ │ token_usage │ │ skills │ │ +│ │(Credit流水) │ │ (Token用量) │ │ (技能) │ │ +│ │ 不可变 │ │ 按月分区 │ │ │ │ +│ └─────────────┘ └─────────────┘ └───────┬────────┘ │ +│ │ │ +│ ┌─────────────┐ ┌─────────────┐ ┌───────┴────────┐ │ +│ │skill_purchases│ │ im_sessions │ │ im_messages │ │ +│ │(技能购买) │ │ (IM会话) │ │ (IM消息) │ │ +│ └─────────────┘ └─────────────┘ └────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────┐ │ +│ │ All tables have RLS policies based on tenant_id │ │ +│ └─────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────┘ +``` + +### 4.2 RLS 策略 + +```sql +-- 所有表启用 RLS +ALTER TABLE tenants ENABLE ROW LEVEL SECURITY; +ALTER TABLE users ENABLE ROW LEVEL SECURITY; +ALTER TABLE capabilities ENABLE ROW LEVEL SECURITY; +-- ... 所有表 + +-- 通用策略: 基于 tenant_id 隔离 +CREATE POLICY tenant_isolation ON capabilities + USING (tenant_id = current_setting('app.tenant_id')::uuid); + +-- 管理员可以看所有数据 +CREATE POLICY admin_full_access ON capabilities + USING (current_setting('app.user_role') = 'admin'); +``` + +--- + +## 5. 安全架构 + +### 5.1 认证流程 + +``` + ┌──────────────┐ + │ Keycloak │ + │ (认证中心) │ + └──────┬───────┘ + │ + ┌────────────────┼────────────────┐ + ▼ ▼ ▼ + ┌──────────┐ ┌──────────┐ ┌──────────┐ + │ 用户登录 │ │ API Key │ │ 服务间 │ + │ JWT 签发 │ │ Hash验证 │ │ Client │ + │ │ │ │ │ Credentials│ + └──────────┘ └──────────┘ └──────────┘ + +JWT Payload: +{ + "sub": "user-uuid", + "tenant_id": "tenant-uuid", + "role": "developer", + "exp": 1719552000, + "iat": 1719548400 +} +``` + +### 5.2 API Key 安全 + +``` +用户创建 Key: + 明文 Key: aip_xxxxxxxxxxxxxxxxxxxxxxxx (仅展示一次) + 存储: SHA-256(aip_xxx) → db + +用户调用: + Header: Authorization: Bearer aip_xxxxxxxxxxxxxxxxxxxxxxxx + 验证: SHA-256(bearer_token) → 查 DB 匹配 +``` + +### 5.3 敏感数据加密 + +| 数据 | 加密方式 | 说明 | +|------|---------|------| +| API Key 明文 | 不存储 | 仅展示一次 | +| API Key 哈希 | SHA-256 | 用于验证 | +| LLM API Key | AES-256-GCM | 存储在 DB | +| 用户密码 | bcrypt | Keycloak 管理 | +| Credit 余额 | 明文（整数） | 需要原子操作 | + +--- + +## 6. 部署架构 + +### 6.1 开发环境 (Docker Compose) + +```yaml +# docker-compose.yml 核心服务 +services: + # 基础设施 + postgresql: # :5432 + redis: # :6379 + kafka: # :9092 + keycloak: # :8080 + apisix: # :9080 (HTTP) / :9443 (HTTPS) + etcd: # :2379 + + # 自研服务 + auth-service: # :8081 + registry-service: # :8082 + openapi-gateway: # :8083 + billing-service: # :8084 + skills-service: # :8085 + admin-service: # :8086 + im-gateway: # :8087 + metering-service: # :8090 + llm-router: # :8091 + + # 前端 + web: # :3000 (React Dev Server) + admin: # :3001 (React Dev Server) + + # 开源 AI 服务 + langflow: # :7860 + mcp-hub: # :3001 + milvus: # :19530 + + # 监控 + prometheus: # :9090 + grafana: # :3002 +``` + +### 6.2 生产环境 (Kubernetes) + +``` +┌─────────────────────────────────────────────────┐ +│ Kubernetes Cluster │ +│ │ +│ ┌────────────────────────────────────────────┐ │ +│ │ Namespace: aipaaS-prod │ │ +│ │ │ │ +│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ +│ │ │ APISIX │ │ APISIX │ │ APISIX │ │ │ +│ │ │ Pod x3 │ │ Pod x3 │ │ Pod x3 │ │ │ +│ │ └─────────┘ └─────────┘ └─────────┘ │ │ +│ │ │ │ +│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ +│ │ │ auth-svc│ │billing │ │registry │ │ │ +│ │ │ x2 │ │ x2 │ │ x2 │ │ │ +│ │ └─────────┘ └─────────┘ └─────────┘ │ │ +│ │ │ │ +│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ +│ │ │llm-route│ │openapi │ │skills │ │ │ +│ │ │ x2 │ │ x2 │ │ x2 │ │ │ +│ │ └─────────┘ └─────────┘ └─────────┘ │ │ +│ │ │ │ +│ │ HPA: CPU > 70% 时自动扩容 │ │ +│ │ PDB: 至少保留 1 个 Pod 可用 │ │ +│ └────────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────────┐ │ +│ │ Namespace: aipaaS-data │ │ +│ │ PostgreSQL (Primary + Replica) │ │ +│ │ Redis (Sentinel) │ │ +│ │ Kafka (3 Brokers) │ │ +│ │ Milvus (Standalone) │ │ +│ └────────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────────┐ │ +│ │ Namespace: aipaaS-monitor │ │ +│ │ Prometheus + Grafana + Loki │ │ +│ └────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────┘ +``` + +--- + +## 7. 技术栈汇总 + +| 层级 | 技术 | 版本 | 许可证 | 用途 | +|------|------|------|--------|------| +| **前端** | React + TypeScript | 18+ / 5+ | MIT | Web UI | +| **UI 框架** | Ant Design Pro | 6+ | MIT | 组件库 | +| **图表** | ECharts | 5+ | Apache 2.0 | 数据可视化 | +| **后端** | Go | 1.22+ | BSD-3 | 核心服务 | +| **AI 服务** | Python | 3.11+ | PSF | LangFlow/MCP | +| **数据库** | PostgreSQL | 16+ | PostgreSQL | 主存储 | +| **缓存** | Redis | 7+ | BSD-3 | 缓存+Lua计费 | +| **消息队列** | Kafka | 3.x+ | Apache 2.0 | 事件总线 | +| **向量库** | Milvus | 2.x+ | Apache 2.0 | RAG | +| **认证** | Keycloak | 25+ | Apache 2.0 | SSO | +| **网关** | Apache APISIX | 3.15+ | Apache 2.0 | API Gateway | +| **Agent** | LangFlow | latest | MIT | 工作流编排 | +| **MCP** | mcp-hub | latest | MIT | MCP 管理 | +| **监控** | Prometheus+Grafana | latest | Apache 2.0 | 可观测性 | +| **开发工具** | MiMo Code | latest | Apache 2.0 | AI 编程 | + +--- + +*文档结束* diff --git a/docs/03-数据库设计.md b/docs/03-数据库设计.md new file mode 100644 index 0000000..fcb854b --- /dev/null +++ b/docs/03-数据库设计.md @@ -0,0 +1,443 @@ +# AI PaaS 商业平台 — 数据库设计 + +> 版本: 1.0 | 日期: 2026-06-27 +> 数据库: PostgreSQL 16+ | 缓存: Redis 7+ + +--- + +## 1. ER 关系图 + +``` +tenants ──1:N──→ users +tenants ──1:N──→ capabilities +tenants ──1:N──→ subscriptions +tenants ──1:N──→ credit_transactions +tenants ──1:N──→ token_usage +tenants ──1:N──→ skills +tenants ──1:N──→ im_sessions + +users ──1:N──→ api_keys +users ──1:N──→ skill_purchases + +capabilities ──1:N──→ capability_versions +skills ──1:N──→ skill_purchases + +im_sessions ──1:N──→ im_messages +``` + +--- + +## 2. 表定义 + +### 2.1 tenants（租户） + +```sql +CREATE TABLE tenants ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + name VARCHAR(255) NOT NULL, + slug VARCHAR(100) NOT NULL UNIQUE, -- URL 友好标识 + plan VARCHAR(20) NOT NULL DEFAULT 'free', -- free/pro/team/enterprise + credit_balance BIGINT NOT NULL DEFAULT 0, -- 毫 Credit (1 Credit = 1000) + credit_included BIGINT NOT NULL DEFAULT 100000, -- 月包含 Credit (毫) + credit_used BIGINT NOT NULL DEFAULT 0, -- 本月已用 (毫) + status VARCHAR(20) NOT NULL DEFAULT 'active', -- active/suspended/deleted + settings JSONB DEFAULT '{}', -- 租户配置 + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() +); + +CREATE INDEX idx_tenants_slug ON tenants(slug); +CREATE INDEX idx_tenants_status ON tenants(status); + +-- RLS +ALTER TABLE tenants ENABLE ROW LEVEL SECURITY; +CREATE POLICY tenant_isolation ON tenants + USING (id = current_setting('app.tenant_id')::uuid); +``` + +### 2.2 users（用户） + +```sql +CREATE TABLE users ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE, + email VARCHAR(255) NOT NULL, + password_hash VARCHAR(255), -- Keycloak 管理时可为空 + name VARCHAR(255) NOT NULL, + role VARCHAR(20) NOT NULL DEFAULT 'user', -- owner/admin/developer/user + avatar_url VARCHAR(500), + status VARCHAR(20) NOT NULL DEFAULT 'active', -- active/suspended/deleted + last_login_at TIMESTAMP WITH TIME ZONE, + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), + UNIQUE(tenant_id, email) +); + +CREATE INDEX idx_users_tenant ON users(tenant_id); +CREATE INDEX idx_users_email ON users(email); +CREATE INDEX idx_users_role ON users(role); + +ALTER TABLE users ENABLE ROW LEVEL SECURITY; +CREATE POLICY tenant_isolation ON users + USING (tenant_id = current_setting('app.tenant_id')::uuid); +``` + +### 2.3 api_keys（API 密钥） + +```sql +CREATE TABLE api_keys ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE, + user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, + name VARCHAR(255) NOT NULL, -- 用途标识 + key_hash VARCHAR(64) NOT NULL UNIQUE, -- SHA-256 哈希 + key_prefix VARCHAR(10) NOT NULL, -- 前缀 aip_xxxx + scopes TEXT[] DEFAULT '{}', -- 权限范围 + last_used_at TIMESTAMP WITH TIME ZONE, + expires_at TIMESTAMP WITH TIME ZONE, -- 可选过期时间 + status VARCHAR(20) NOT NULL DEFAULT 'active', -- active/revoked + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() +); + +CREATE INDEX idx_api_keys_tenant ON api_keys(tenant_id); +CREATE INDEX idx_api_keys_hash ON api_keys(key_hash); +CREATE INDEX idx_api_keys_user ON api_keys(user_id); + +ALTER TABLE api_keys ENABLE ROW LEVEL SECURITY; +CREATE POLICY tenant_isolation ON api_keys + USING (tenant_id = current_setting('app.tenant_id')::uuid); +``` + +### 2.4 subscriptions（订阅） + +```sql +CREATE TABLE subscriptions ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE, + plan VARCHAR(20) NOT NULL, -- free/pro/team/enterprise + credits_included BIGINT NOT NULL, -- 月包含 Credit (毫) + credits_used BIGINT NOT NULL DEFAULT 0, -- 本月已用 + price_cents INTEGER NOT NULL DEFAULT 0, -- 月费 (分) + billing_cycle VARCHAR(10) NOT NULL DEFAULT 'monthly', -- monthly/yearly + period_start TIMESTAMP WITH TIME ZONE NOT NULL, + period_end TIMESTAMP WITH TIME ZONE NOT NULL, + status VARCHAR(20) NOT NULL DEFAULT 'active', -- active/cancelled/expired + stripe_sub_id VARCHAR(255), -- Stripe 订阅 ID + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() +); + +CREATE INDEX idx_subscriptions_tenant ON subscriptions(tenant_id); +CREATE INDEX idx_subscriptions_status ON subscriptions(status); +CREATE INDEX idx_subscriptions_period ON subscriptions(period_start, period_end); + +ALTER TABLE subscriptions ENABLE ROW LEVEL SECURITY; +CREATE POLICY tenant_isolation ON subscriptions + USING (tenant_id = current_setting('app.tenant_id')::uuid); +``` + +### 2.5 credit_transactions（Credit 流水 — 不可变） + +```sql +CREATE TABLE credit_transactions ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + tenant_id UUID NOT NULL REFERENCES tenants(id), + type VARCHAR(30) NOT NULL, -- usage/topup/subscription/bonus/refund + amount BIGINT NOT NULL, -- 变动量 (毫 Credit)，正=加，负=减 + balance_after BIGINT NOT NULL, -- 变动后余额 + description TEXT, -- 描述 + trace_id VARCHAR(64), -- 关联的调用 trace + idempotency_key VARCHAR(64) UNIQUE, -- 幂等键 (防重复扣费) + reference_type VARCHAR(30), -- llm_call/skill_purchase/topup/subscription + reference_id UUID, -- 关联 ID + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() + -- 不可变: 无 updated_at, 无 DELETE +); + +CREATE INDEX idx_credit_tx_tenant ON credit_transactions(tenant_id); +CREATE INDEX idx_credit_tx_type ON credit_transactions(type); +CREATE INDEX idx_credit_tx_created ON credit_transactions(created_at); +CREATE INDEX idx_credit_tx_trace ON credit_transactions(trace_id); + +-- 不可变表: 禁用 UPDATE 和 DELETE +CREATE RULE credit_tx_no_update AS ON UPDATE TO credit_transactions DO INSTEAD NOTHING; +CREATE RULE credit_tx_no_delete AS ON DELETE TO credit_transactions DO INSTEAD NOTHING; + +ALTER TABLE credit_transactions ENABLE ROW LEVEL SECURITY; +CREATE POLICY tenant_isolation ON credit_transactions + USING (tenant_id = current_setting('app.tenant_id')::uuid); +``` + +### 2.6 token_usage（Token 用量 — 按月分区） + +```sql +-- 主表 (自动分区) +CREATE TABLE token_usage ( + id UUID NOT NULL DEFAULT gen_random_uuid(), + tenant_id UUID NOT NULL, + capability_id UUID, + user_id UUID, + model VARCHAR(100) NOT NULL, -- deepseek-chat, qwen-turbo + provider VARCHAR(50) NOT NULL, -- deepseek, qianwen, doubao + prompt_tokens INTEGER NOT NULL, + completion_tokens INTEGER NOT NULL, + total_tokens INTEGER NOT NULL, + cost_credits BIGINT NOT NULL, -- 消耗 Credit (毫) + trace_id VARCHAR(64), + metadata JSONB DEFAULT '{}', + created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), + PRIMARY KEY (id, created_at) +) PARTITION BY RANGE (created_at); + +-- 按月创建分区 +CREATE TABLE token_usage_2026_07 PARTITION OF token_usage + FOR VALUES FROM ('2026-07-01') TO ('2026-08-01'); +CREATE TABLE token_usage_2026_08 PARTITION OF token_usage + FOR VALUES FROM ('2026-08-01') TO ('2026-09-01'); +-- ... 自动创建未来分区 + +CREATE INDEX idx_token_usage_tenant ON token_usage(tenant_id, created_at); +CREATE INDEX idx_token_usage_model ON token_usage(model, created_at); +CREATE INDEX idx_token_usage_trace ON token_usage(trace_id); + +-- 不可变表 +CREATE RULE token_usage_no_update AS ON UPDATE TO token_usage DO INSTEAD NOTHING; +CREATE RULE token_usage_no_delete AS ON DELETE TO token_usage DO INSTEAD NOTHING; +``` + +### 2.7 capabilities（能力） + +```sql +CREATE TABLE capabilities ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE, + name VARCHAR(255) NOT NULL, + type VARCHAR(30) NOT NULL, -- agent/mcp/skill/llm/custom + version VARCHAR(50) NOT NULL, -- SemVer + description TEXT, + tags TEXT[] DEFAULT '{}', + endpoint VARCHAR(500), -- 调用地址 + protocol VARCHAR(20) DEFAULT 'rest', -- rest/grpc/websocket + pricing_config JSONB DEFAULT '{}', -- 计费配置 + dependencies JSONB DEFAULT '[]', -- 依赖的其他能力 + owner_id UUID REFERENCES users(id), + status VARCHAR(20) NOT NULL DEFAULT 'draft', -- draft/pending_review/active/deprecated/rejected + review_note TEXT, -- 审核备注 + view_count INTEGER DEFAULT 0, -- 浏览次数 + invoke_count BIGINT DEFAULT 0, -- 调用次数 + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), + UNIQUE(tenant_id, name, version) +); + +CREATE INDEX idx_capabilities_tenant ON capabilities(tenant_id); +CREATE INDEX idx_capabilities_type ON capabilities(type); +CREATE INDEX idx_capabilities_status ON capabilities(status); +CREATE INDEX idx_capabilities_tags ON capabilities USING GIN(tags); + +ALTER TABLE capabilities ENABLE ROW LEVEL SECURITY; +CREATE POLICY tenant_isolation ON capabilities + USING (tenant_id = current_setting('app.tenant_id')::uuid); +``` + +### 2.8 capability_versions（能力版本） + +```sql +CREATE TABLE capability_versions ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + capability_id UUID NOT NULL REFERENCES capabilities(id) ON DELETE CASCADE, + version VARCHAR(50) NOT NULL, + endpoint VARCHAR(500), + changelog TEXT, + status VARCHAR(20) NOT NULL DEFAULT 'active', -- active/deprecated + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), + UNIQUE(capability_id, version) +); + +CREATE INDEX idx_cap_versions_cap ON capability_versions(capability_id); +``` + +### 2.9 skills（技能） + +```sql +CREATE TABLE skills ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE, + name VARCHAR(255) NOT NULL, + description TEXT, + category VARCHAR(50), -- 分类 + tags TEXT[] DEFAULT '{}', + pricing_model VARCHAR(20) NOT NULL DEFAULT 'per_call', -- per_call/per_token/subscription/free + price_credits BIGINT NOT NULL DEFAULT 0, -- 价格 (毫 Credit) + developer_share NUMERIC(3,2) DEFAULT 0.75, -- 开发者分成比例 + endpoint VARCHAR(500), -- API 地址 + documentation TEXT, -- 使用文档 + icon_url VARCHAR(500), + status VARCHAR(20) NOT NULL DEFAULT 'draft', -- draft/active/suspended/deleted + rating NUMERIC(3,2) DEFAULT 0, -- 评分 + rating_count INTEGER DEFAULT 0, -- 评分人数 + view_count INTEGER DEFAULT 0, -- 浏览次数 + purchase_count INTEGER DEFAULT 0, -- 购买次数 + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() +); + +CREATE INDEX idx_skills_tenant ON skills(tenant_id); +CREATE INDEX idx_skills_category ON skills(category); +CREATE INDEX idx_skills_status ON skills(status); +CREATE INDEX idx_skills_tags ON skills USING GIN(tags); +CREATE INDEX idx_skills_rating ON skills(rating DESC); +CREATE INDEX idx_skills_name_search ON skills USING GIN(to_tsvector('simple', name || ' ' || COALESCE(description, ''))); + +ALTER TABLE skills ENABLE ROW LEVEL SECURITY; +CREATE POLICY tenant_isolation ON skills + USING (tenant_id = current_setting('app.tenant_id')::uuid); +``` + +### 2.10 skill_purchases（技能购买） + +```sql +CREATE TABLE skill_purchases ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + tenant_id UUID NOT NULL REFERENCES tenants(id), + user_id UUID NOT NULL REFERENCES users(id), + skill_id UUID NOT NULL REFERENCES skills(id), + developer_id UUID NOT NULL, -- 开发者 user_id + amount_credits BIGINT NOT NULL, -- 支付金额 (毫 Credit) + platform_share BIGINT NOT NULL, -- 平台分成 + developer_share BIGINT NOT NULL, -- 开发者分成 + status VARCHAR(20) NOT NULL DEFAULT 'active', -- active/refunded + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() +); + +CREATE INDEX idx_skill_purchases_user ON skill_purchases(user_id); +CREATE INDEX idx_skill_purchases_skill ON skill_purchases(skill_id); +CREATE INDEX idx_skill_purchases_tenant ON skill_purchases(tenant_id); +``` + +### 2.11 im_sessions（IM 会话） + +```sql +CREATE TABLE im_sessions ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + tenant_id UUID NOT NULL REFERENCES tenants(id), + platform VARCHAR(20) NOT NULL, -- wechat/qq/dingtalk/feishu + user_identifier VARCHAR(255) NOT NULL, -- 平台用户标识 + user_name VARCHAR(255), -- 平台用户名 + bot_id VARCHAR(255), -- 机器人标识 + model VARCHAR(100) DEFAULT 'deepseek-chat', -- 当前使用模型 + status VARCHAR(20) NOT NULL DEFAULT 'active', -- active/closed + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), + last_active_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() +); + +CREATE INDEX idx_im_sessions_tenant ON im_sessions(tenant_id); +CREATE INDEX idx_im_sessions_platform ON im_sessions(platform, user_identifier); + +ALTER TABLE im_sessions ENABLE ROW LEVEL SECURITY; +CREATE POLICY tenant_isolation ON im_sessions + USING (tenant_id = current_setting('app.tenant_id')::uuid); +``` + +### 2.12 im_messages（IM 消息） + +```sql +CREATE TABLE im_messages ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + session_id UUID NOT NULL REFERENCES im_sessions(id), + role VARCHAR(10) NOT NULL, -- user/assistant/system + content TEXT NOT NULL, + model VARCHAR(100), -- 使用的模型 + tokens_used INTEGER, + cost_credits BIGINT, + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() +); + +CREATE INDEX idx_im_messages_session ON im_messages(session_id, created_at); +``` + +--- + +## 3. Redis 数据结构 + +### 3.1 计费相关 + +``` +# Credit 余额 (毫 Credit) +billing:balance:{tenant_id} → "12580000" +# 类型: String +# 操作: GET / DECRBY (Lua 原子) +# TTL: 永不过期 + +# 幂等键 +billing:idempotency:{tenant_id}:{idempotency_key} → { + "result": "success", + "amount": -1280, + "trace_id": "abc-123" +} +# 类型: Hash +# TTL: 24 小时 + +# 每日统计 +billing:daily:{tenant_id}:{YYYY-MM-DD} → { + "calls": "342", + "tokens": "456000", + "credits": "1280000" +} +# 类型: Hash +# TTL: 7 天 + +# 订阅信息 +billing:subscription:{tenant_id} → { + "plan": "pro", + "credits_included": "50000000", + "credits_used": "12800000", + "period_end": "2026-07-27T00:00:00Z" +} +# 类型: Hash +# TTL: 永不过期 +``` + +### 3.2 限流相关 + +``` +# 滑动窗口限流 +ratelimit:{tenant_id}:{window_key} → "1" (INCR) +# 类型: String +# TTL: 窗口大小 (如 60s) +``` + +### 3.3 IM 会话 + +``` +# 会话上下文 +im:session:{platform}:{user_id} → { + "tenant_id": "xxx", + "model": "deepseek-chat", + "messages": "[{role,content}, ...]" # 最近 20 条 +} +# 类型: Hash +# TTL: 24 小时 +``` + +--- + +## 4. Migration 策略 + +``` +migrations/ +├── 001_init.sql # 所有表 + RLS + 索引 +├── 002_seed_data.sql # 开发环境种子数据 +├── 003_add_partitions.sql # token_usage 分区 +└── 004_add_fulltext.sql # 全文搜索索引 +``` + +**规则**: +- Migration 文件名: `{序号}_{描述}.sql` +- 不允许修改已执行的 Migration +- 每个 Migration 必须可回滚 +- 生产环境 Migration 必须在低峰期执行 + +--- + +*文档结束* diff --git a/docs/04-API接口规范.md b/docs/04-API接口规范.md new file mode 100644 index 0000000..2766114 --- /dev/null +++ b/docs/04-API接口规范.md @@ -0,0 +1,572 @@ +# AI PaaS 商业平台 — API 接口规范 + +> 版本: 1.0 | 日期: 2026-06-27 +> 规范: OpenAPI 3.0 | Base URL: https://api.aipaas.com + +--- + +## 1. 通用约定 + +### 1.1 认证方式 + +| 方式 | Header | 说明 | +|------|--------|------| +| JWT | `Authorization: Bearer {access_token}` | Web 前端登录后使用 | +| API Key | `Authorization: Bearer aip_{key}` | 程序化调用 | + +### 1.2 响应格式 + +```json +// 成功 +{ + "code": 0, + "message": "success", + "data": { ... } +} + +// 分页 +{ + "code": 0, + "message": "success", + "data": { + "items": [...], + "total": 100, + "page": 1, + "page_size": 20 + } +} + +// 错误 +{ + "code": 40001, + "message": "Insufficient balance", + "data": null +} +``` + +### 1.3 错误码 + +| 错误码 | HTTP Status | 说明 | +|--------|------------|------| +| 0 | 200 | 成功 | +| 40001 | 400 | 请求参数错误 | +| 40101 | 401 | 未认证 | +| 40102 | 401 | API Key 无效 | +| 40301 | 403 | 权限不足 | +| 40401 | 404 | 资源不存在 | +| 40201 | 402 | Credit 余额不足 | +| 42901 | 429 | 请求频率超限 | +| 50001 | 500 | 服务内部错误 | +| 50201 | 502 | 上游服务不可用 | + +--- + +## 2. Auth 接口 + +### POST /api/v1/auth/register +```yaml +description: 用户注册 +request: + body: + email: string (required) + password: string (required, min 8) + name: string (required) +response: + 200: + data: + user_id: uuid + email: string + tenant_id: uuid +``` + +### POST /api/v1/auth/login +```yaml +description: 用户登录 +request: + body: + email: string (required) + password: string (required) +response: + 200: + data: + access_token: string (JWT, 1h) + refresh_token: string (JWT, 7d) + expires_in: integer (seconds) + user: + id: uuid + name: string + email: string + role: string + tenant_id: uuid +``` + +### POST /api/v1/auth/refresh +```yaml +description: 刷新 Token +request: + body: + refresh_token: string (required) +response: + 200: + data: + access_token: string + expires_in: integer +``` + +### GET /api/v1/auth/me +```yaml +description: 获取当前用户信息 +auth: JWT +response: + 200: + data: + id: uuid + name: string + email: string + role: string + tenant_id: uuid + tenant: + name: string + plan: string + credit_balance: integer +``` + +--- + +## 3. API Key 接口 + +### POST /api/v1/apikeys +```yaml +description: 创建 API Key +auth: JWT +request: + body: + name: string (required) # 用途标识 +response: + 200: + data: + id: uuid + name: string + key: string # 仅此一次展示明文 + key_prefix: string # aip_xxxx + created_at: datetime +``` + +### GET /api/v1/apikeys +```yaml +description: API Key 列表 +auth: JWT +response: + 200: + data: + items: + - id: uuid + name: string + key_prefix: string + last_used_at: datetime + status: string + created_at: datetime +``` + +### DELETE /api/v1/apikeys/{id} +```yaml +description: 删除 API Key +auth: JWT +response: + 200: { code: 0, message: "success" } +``` + +--- + +## 4. LLM 调用接口（OpenAI 兼容） + +### POST /v1/chat/completions +```yaml +description: Chat Completion (OpenAI 兼容格式) +auth: API Key 或 JWT +request: + body: + model: string (required) # deepseek-chat, qwen-turbo, etc. + messages: + - role: string # system/user/assistant + content: string + temperature: number (optional, 0-2, default 1) + max_tokens: integer (optional) + stream: boolean (optional, default false) + top_p: number (optional) + stop: string | array (optional) +response: + 200: + # 非流式 + id: string + object: "chat.completion" + model: string + choices: + - index: 0 + message: + role: "assistant" + content: string + finish_reason: "stop" + usage: + prompt_tokens: integer + completion_tokens: integer + total_tokens: integer + # 流式 (SSE) + # Content-Type: text/event-stream + # data: {"id":"...","choices":[{"delta":{"content":"token"}}]} + # data: [DONE] +``` + +### GET /v1/models +```yaml +description: 可用模型列表 +auth: API Key 或 JWT +response: + 200: + data: + - id: "deepseek-chat" + object: "model" + provider: "deepseek" + pricing: + credits_per_1k: 1.0 + - id: "qwen-turbo" + object: "model" + provider: "qianwen" + pricing: + credits_per_1k: 0.8 +``` + +--- + +## 5. Billing 接口 + +### GET /api/v1/billing/balance +```yaml +description: 查询 Credit 余额 +auth: JWT +response: + 200: + data: + balance: integer # 当前余额 (毫 Credit) + balance_display: number # 显示余额 (Credit) + plan: string + credits_included: integer + credits_used: integer + period_end: datetime +``` + +### POST /api/v1/billing/topup +```yaml +description: 充值 +auth: JWT +request: + body: + amount: integer (required) # 充值金额 (分) + payment_method: string # alipay/wechat +response: + 200: + data: + order_id: string + payment_url: string # 支付链接 +``` + +### GET /api/v1/billing/transactions +```yaml +description: Credit 流水查询 +auth: JWT +request: + query: + page: integer (default 1) + page_size: integer (default 20) + type: string (optional) # usage/topup/subscription + start_date: date (optional) + end_date: date (optional) +response: + 200: + data: + items: + - id: uuid + type: string + amount: integer + balance_after: integer + description: string + trace_id: string + created_at: datetime + total: integer + page: integer + page_size: integer +``` + +### POST /api/v1/billing/subscribe +```yaml +description: 订阅管理 +auth: JWT +request: + body: + plan: string (required) # pro/team + billing_cycle: string # monthly/yearly +response: + 200: + data: + subscription_id: uuid + plan: string + price_cents: integer + credits_included: integer + period_start: datetime + period_end: datetime +``` + +--- + +## 6. Capability Registry 接口 + +### POST /api/v1/capabilities +```yaml +description: 注册新能力 +auth: JWT +request: + body: + name: string (required) + type: string (required) # agent/mcp/skill/llm/custom + version: string (required) # SemVer + description: string + tags: array[string] + endpoint: string + protocol: string # rest/grpc/websocket + pricing_config: object +response: + 200: + data: + id: uuid + status: "draft" +``` + +### GET /api/v1/capabilities +```yaml +description: 能力列表 +auth: JWT 或 API Key +request: + query: + type: string (optional) + status: string (optional) + tags: string (optional) # 逗号分隔 + page: integer + page_size: integer +response: + 200: + data: + items: + - id: uuid + name: string + type: string + version: string + status: string + tags: array[string] + invoke_count: integer + created_at: datetime +``` + +### GET /api/v1/capabilities/{id} +```yaml +description: 能力详情 +auth: JWT 或 API Key +response: + 200: + data: + id: uuid + name: string + type: string + version: string + description: string + tags: array[string] + endpoint: string + protocol: string + pricing_config: object + status: string + invoke_count: integer + created_at: datetime +``` + +### PUT /api/v1/capabilities/{id} +```yaml +description: 更新能力 +auth: JWT +request: + body: + name: string (optional) + description: string (optional) + tags: array[string] (optional) + endpoint: string (optional) + pricing_config: object (optional) +``` + +### DELETE /api/v1/capabilities/{id} +```yaml +description: 注销能力 +auth: JWT +``` + +### POST /api/v1/capabilities/{id}/versions +```yaml +description: 发布新版本 +auth: JWT +request: + body: + version: string (required) + endpoint: string + changelog: string +``` + +--- + +## 7. Skills 市场接口 + +### POST /api/v1/skills +```yaml +description: 发布技能 +auth: JWT +request: + body: + name: string (required) + description: string + category: string + tags: array[string] + pricing_model: string # per_call/per_token/subscription/free + price_credits: integer + endpoint: string + documentation: string +response: + 200: + data: + id: uuid +``` + +### GET /api/v1/skills +```yaml +description: 市场列表 +auth: 公开 +request: + query: + q: string (optional) # 搜索关键词 + category: string (optional) + tags: string (optional) + sort: string # rating/popular/newest + page: integer + page_size: integer +response: + 200: + data: + items: + - id: uuid + name: string + description: string + category: string + pricing_model: string + price_credits: integer + rating: number + purchase_count: integer + developer: + name: string +``` + +### POST /api/v1/skills/{id}/purchase +```yaml +description: 购买技能 +auth: JWT +request: + body: + # 无需参数，自动扣费 +response: + 200: + data: + purchase_id: uuid + credits_deducted: integer + balance_after: integer +``` + +### GET /api/v1/skills/purchased +```yaml +description: 已购技能列表 +auth: JWT +response: + 200: + data: + items: + - skill_id: uuid + name: string + purchased_at: datetime +``` + +--- + +## 8. IM Bot 接口 + +### POST /api/v1/im/callback/{platform} +```yaml +description: 平台回调 (Webhook) +auth: 平台签名验证 +request: + body: 平台消息格式 (各平台不同) +response: + 200: 平台要求的响应格式 +``` + +### GET /api/v1/im/sessions +```yaml +description: 会话列表 +auth: JWT +response: + 200: + data: + items: + - id: uuid + platform: string + user_identifier: string + user_name: string + model: string + last_active_at: datetime +``` + +--- + +## 9. Admin 接口 + +### GET /api/v1/admin/dashboard +```yaml +description: 管理仪表盘 +auth: JWT (admin 角色) +response: + 200: + data: + total_users: integer + total_tenants: integer + total_api_calls: integer (今日) + total_revenue: integer (本月) + system_status: object +``` + +### GET /api/v1/admin/users +```yaml +description: 用户列表 +auth: JWT (admin 角色) +request: + query: + q: string (optional) + status: string (optional) + page: integer + page_size: integer +``` + +### POST /api/v1/admin/capabilities/{id}/review +```yaml +description: 能力审核 +auth: JWT (admin 角色) +request: + body: + action: string # approve/reject + note: string +``` + +--- + +*文档结束* diff --git a/docs/05-AGENTS-MiMoCode配置.md b/docs/05-AGENTS-MiMoCode配置.md new file mode 100644 index 0000000..3d87e18 --- /dev/null +++ b/docs/05-AGENTS-MiMoCode配置.md @@ -0,0 +1,186 @@ +# AI PaaS Platform — AGENTS.md（MiMo Code 核心配置） + +> 此文件放在项目根目录 `.mimocode/AGENTS.md`，MiMo Code 每次启动时自动加载。 +> 这是 MiMo Code 理解整个项目的唯一上下文来源——写得越精确，生成的代码质量越高。 + +--- + +# AI PaaS 商业平台 + +## 项目概述 +面向个人开发者的 AI 能力服务平台。提供 Agent、MCP、Skills、IM Bot、LLM 调用等 AI 能力，支持按 Token 计费和订阅制收费。 + +## 架构模式 +微服务架构 + 事件驱动。核心业务自研，基础设施开源。 + +## 技术栈 +- **后端核心**: Go 1.22+ (所有核心服务) +- **AI 服务**: Python 3.11+ (LangFlow, MCP Hub 集成) +- **前端**: React 18 + TypeScript 5+ + Ant Design Pro 6 + ECharts +- **数据库**: PostgreSQL 16 (RLS 多租户隔离) +- **缓存**: Redis 7 (Lua 原子计费) +- **消息队列**: Kafka 3.x (用量上报) +- **向量库**: Milvus 2.x (RAG) +- **认证**: Keycloak 25+ (JWT + API Key) +- **网关**: Apache APISIX 3.15+ (API Gateway) +- **Agent**: LangFlow (工作流编排) +- **MCP**: mcp-hub (MCP 服务管理) +- **监控**: Prometheus + Grafana + +## 项目结构 +``` +ai-paas-platform/ +├── .mimocode/ +│ └── AGENTS.md ← 本文件 +├── docs/ ← 设计文档 +│ ├── 01-PRD-产品需求文档.md +│ ├── 02-系统架构设计.md +│ ├── 03-数据库设计.md +│ └── 04-API接口规范.md +├── packages/ ← 前端应用 +│ ├── web/ ← 用户 Dashboard (React) +│ └── admin/ ← 管理后台 (React) +├── services/ ← 后端服务 (Go) +│ ├── auth/ ← 认证服务 (:8081) +│ ├── registry/ ← 能力注册中心 (:8082) +│ ├── openapi-gateway/ ← OpenAI 兼容网关 (:8083) +│ ├── billing/ ← 计费引擎 (:8084) +│ ├── skills/ ← Skills 市场 (:8085) +│ ├── admin/ ← 管理后台 API (:8086) +│ ├── im-gateway/ ← IM Bot 网关 (:8087) +│ ├── metering/ ← 用量追踪 (:8090) +│ └── llm-router/ ← LLM 智能路由 (:8091) +├── infra/ ← 基础设施配置 +│ ├── keycloak/ +│ ├── postgresql/ +│ ├── redis/ +│ ├── kafka/ +│ ├── milvus/ +│ └── apisix/ +├── deploy/ ← 部署配置 +│ ├── docker-compose.yml +│ └── k8s/ +└── migrations/ ← 数据库 Migration + ├── 001_init.sql + └── ... +``` + +## 开发规范 + +### Go 服务 +- 遵循 Effective Go + gofmt + golangci-lint +- 每个服务独立 main.go，可独立编译运行 +- 服务间通信: 同步用 HTTP/gRPC，异步用 Kafka +- 错误处理: 统一错误码，返回 `{code, message, data}` 格式 +- 配置管理: 环境变量 + YAML 配置文件 +- 日志: 结构化 JSON 日志 (slog) + +### TypeScript 前端 +- 遵循 eslint + prettier +- 组件: React 函数组件 + Hooks +- 状态管理: React Query (服务端) + Zustand (客户端) +- 路由: React Router v6 +- 样式: Ant Design Pro 内置 + CSS Modules + +### Python AI 服务 +- 遵循 ruff + black +- 类型注解: 必须 +- 异步: asyncio + +### 数据库 +- 所有表启用 RLS，策略基于 tenant_id +- 所有金额使用整数 (毫 Credit)，避免浮点 +- Migration 文件名: `{序号}_{描述}.sql` +- 不可变表: credit_transactions, token_usage (无 UPDATE/DELETE) + +### Git +- 分支: main (生产), develop (开发), feature/* (功能) +- 提交: Conventional Commits (feat/fix/docs/chore/test) +- PR: 必须通过 CI + Code Review + +### 测试 +- Go: testing + testify, 覆盖率 > 80% +- TypeScript: vitest + playwright +- 单元测试: 每个服务的核心逻辑 +- 集成测试: 服务间调用链 + +## 核心模块说明 + +### auth-service (:8081) +- Keycloak 适配器 +- JWT 验证中间件 +- API Key 验证 (SHA-256 哈希查 DB) +- 租户上下文提取 (JWT claim → tenant_id) +- RBAC: owner > admin > developer > user + +### llm-router (:8091) +- 多平台 LLM 对接 (OpenAI 兼容格式) +- 7 个平台: DeepSeek, 千问, 豆包, 智谱, 元宝, 百度, Ollama +- 智能路由: 用户选择 / 成本优先 / 延迟优先 +- 故障转移: 主模型不可用自动切换 +- 流式响应: SSE 透传 +- API Key 加密存储 (AES-256-GCM) + +### billing (:8084) +- Credit 模型: 1 Credit = 1000 tokens +- 模型系数: deepseek-chat=1.0, deepseek-reasoner=2.0, doubao-pro=1.5 +- Redis Lua 原子操作: 先扣后服 + 幂等 + 可审计 +- 订阅套餐: Free/Pro/Team/Enterprise +- 每日对账: Redis ↔ PostgreSQL 一致性检查 + +### registry (:8082) +- 能力 CRUD (REST + gRPC 双协议) +- 能力类型: agent/mcp/skill/llm/custom +- 版本管理: SemVer +- 状态: draft → pending_review → active → deprecated +- 服务发现: 按类型/标签/状态查询 + +### metering (:8090) +- Kafka Consumer: 消费 usage.events +- PostgreSQL 持久化: token_usage 表 (按月分区) +- 预聚合: 每小时刷新 usage_summaries +- 用量查询: 按日/周/月/模型/能力统计 + +### skills (:8085) +- 技能发布/审核/交易 +- 计费模式: per_call/per_token/subscription/free +- 分成: 平台 25% / 开发者 75% +- 全文搜索: PostgreSQL GIN 索引 + +### im-gateway (:8087) +- 多平台适配器: 微信(LangBot) / QQ(OneBot) / 钉钉 +- 会话管理: Redis Hash, 24h 过期 +- 上下文窗口: 最近 20 条消息 +- 指令系统: /help /model /clear /balance + +### openapi-gateway (:8083) +- OpenAI 兼容 API: POST /v1/chat/completions +- 请求拦截链: Auth → Balance → LLM → Billing → Response +- 流式 SSE 支持 +- 用量异步上报 Kafka + +## 计费原则（最重要） +1. **先扣后服**: 先扣减余额，再允许调用 +2. **幂等**: 通过 idempotency_key 防重复扣费 +3. **原子**: Redis Lua 脚本保证原子性 +4. **可审计**: 每笔变动有 trace_id + 原因 +5. **实时可见**: Dashboard 余额秒级更新 + +## LLM 对接 +- 统一 OpenAI 兼容格式: POST /v1/chat/completions +- 百度需适配层 (非标准 API) +- 其他平台直接兼容 +- 流式: SSE (text/event-stream) + +## 部署 +- 开发: docker-compose.yml (一键启动) +- 生产: Kubernetes + Helm Charts +- 监控: Prometheus + Grafana +- 日志: 结构化 JSON → Loki + +## 重要约束 +- 所有 API 必须有 OpenAPI 3.0 规范 +- 所有数据库变更必须有 Migration +- 所有金额使用整数 (毫 Credit) +- 所有敏感数据加密 (AES-256) +- 所有关键操作有审计日志