# 方案二：稳扎稳打 — 详细实施计划

> **定位**: 核心服务全部自研，基础设施用开源，架构完全自主可控
> **周期**: 20 周（5 个 Phase，每 Phase 4 周）
> **开发工具**: MiMo Code（Quest Mode + Agent Mode + AGENTS.md）
> **技术栈**: Go(核心) + Python(AI) + TypeScript(前端) + PostgreSQL + Redis + Kafka + Milvus

---

## 总览：5 Phase 里程碑

```
Week  1-4   Phase 1: 基座搭建（Auth + DB + Gateway + 项目骨架）
Week  5-8   Phase 2: 核心引擎（LLM Router + Billing + Metering）
Week  9-12  Phase 3: 能力治理（Registry + Skills + Dashboard）
Week 13-16  Phase 4: 生态扩展（IM Bot + MCP + Agent + ACP）
Week 17-20  Phase 5: 集成上线（测试 + 部署 + 监控 + 运营）
```

```
         Phase 1        Phase 2        Phase 3        Phase 4        Phase 5
    ┌──────────────┬──────────────┬──────────────┬──────────────┬──────────────┐
    │ 域基础设施    │ 核心引擎      │ 能力治理      │ 生态扩展      │ 集成上线      │
    │              │              │              │              │              │
    │ ✅ 项目骨架   │ ✅ LLM Router │ ✅ Registry  │ ✅ IM Bot GW │ ✅ 全链路测试 │
    │ ✅ Keycloak  │ ✅ Billing    │ ✅ Skills 市场│ ✅ MCP Hub   │ ✅ K8s 部署   │
    │ ✅ APISIX    │ ✅ Metering   │ ✅ Dashboard │ ✅ LangFlow  │ ✅ 监控告警   │
    │ ✅ DB Schema │ ✅ OpenAPI GW │ ✅ Admin     │ ✅ ACP 协议  │ ✅ 文档上线   │
    └──────────────┴──────────────┴──────────────┴──────────────┴──────────────┘
         ▲               ▲               ▲               ▲               ▼
         └───────────────┴───────────────┴───────────────┴───── 可运行交付 ─┘
```

---

## Phase 1：基座搭建（Week 1-4）

> **目标**: 项目可运行，基础设施就绪，Auth + Gateway + DB 全部跑通
> **结束标志**: `docker-compose up` 启动所有服务，可注册用户、登录、通过网关调用 API

### 1.1 项目骨架初始化（Day 1-2）

**MiMo Code Quest Prompt**:
```
初始化 AI PaaS 平台项目骨架。

项目名: ai-paas-platform
Monorepo 结构 (pnpm workspace):
- packages/web (React + TypeScript + Ant Design Pro)
- packages/admin (React + TypeScript + Ant Design Pro)
- services/gateway (Go)
- services/auth (Go)
- services/billing (Go)
- services/metering (Go)
- services/registry (Go)
- services/llm-router (Go)
- services/skills (Go)
- services/im-gateway (Go)
- infra/keycloak (Docker)
- infra/postgresql (Docker + migrations)
- infra/redis (Docker)
- infra/kafka (Docker)
- infra/milvus (Docker)
- infra/apisix (Docker)
- deploy/docker-compose.yml

生成:
1. 根目录 Makefile, docker-compose.yml, .env.example
2. 各 Go 服务的基础 main.go + health endpoint
3. 各 React 应用的基础 vite 配置
4. PostgreSQL migration 初始脚本 (001_init.sql)
5. .mimocode/AGENTS.md 配置文件
```

**交付物**:
- [ ] Monorepo 目录结构
- [ ] docker-compose.yml 一键启动所有基础设施
- [ ] 各服务 health endpoint 可访问
- [ ] AGENTS.md 配置完成

### 1.2 数据库 Schema 设计（Day 3-5）

**MiMo Code Quest Prompt**:
```
设计 AI PaaS 平台的 PostgreSQL 数据库 Schema。

核心表:
1. tenants (租户) - id, name, plan, credit_balance, status, created_at
2. users (用户) - id, tenant_id, email, name, role, api_key_hash, status
3. capabilities (能力) - id, tenant_id, name, type, version, endpoint, protocol, status, pricing_config
4. capability_versions (能力版本) - id, capability_id, version, endpoint, changelog, status
5. credit_transactions (Credit 流水) - id, tenant_id, type, amount, balance_after, trace_id, idempotency_key
6. token_usage (Token 用量) - id, tenant_id, capability_id, model, prompt_tokens, completion_tokens, cost_credits, trace_id (按月分区)
7. subscriptions (订阅) - id, tenant_id, plan, credits_included, credits_used, period_start, period_end, status
8. skills (技能) - id, tenant_id, name, description, pricing_model, price_credits, status
9. skill_purchases (技能购买) - id, user_id, skill_id, amount_credits
10. im_sessions (IM 会话) - id, tenant_id, platform, user_identifier, bot_id, status

要求:
- 所有表启用 RLS (Row Level Security)，策略基于 tenant_id
- 所有表有 created_at/updated_at
- token_usage 按月分区
- 外键关系完整
- 索引覆盖高频查询
```

**交付物**:
- [ ] 001_init.sql 完整建表脚本
- [ ] RLS 策略配置
- [ ] 种子数据脚本 (开发环境)

### 1.3 Keycloak 认证服务（Day 6-10）

**MiMo Code Quest Prompt**:
```
部署 Keycloak 并实现多租户认证适配器。

1. Docker 部署 Keycloak 25.x
2. 配置 Realm: ai-paas
3. 配置 Clients:
   - web-app (PKCE, React 前端)
   - admin-app (PKCE, 管理后台)
   - api-service (Client Credentials, 服务间调用)
4. 实现 Go 适配器 (services/auth):
   - JWT 验证中间件
   - API Key 验证 (查 DB)
   - 租户上下文提取 (从 JWT claim 提取 tenant_id)
   - RBAC 角色: owner, admin, developer, user
5. 实现用户注册/登录 API:
   - POST /api/v1/auth/register (邮箱+密码)
   - POST /api/v1/auth/login (返回 JWT)
   - POST /api/v1/auth/refresh
   - GET  /api/v1/auth/me (当前用户信息)
6. APISIX 集成: jwt-auth 插件配置
```

**交付物**:
- [ ] Keycloak Docker 配置
- [ ] Go auth 中间件 (JWT + API Key)
- [ ] Auth API (注册/登录/刷新)
- [ ] APISIX jwt-auth 插件配置
- [ ] RBAC 角色体系

### 1.4 Apache APISIX 网关（Day 11-14）

**MiMo Code Quest Prompt**:
```
部署 Apache APISIX 3.15+ 并配置核心插件。

1. Docker 部署 APISIX + etcd
2. 配置以下插件:
   - jwt-auth: JWT 令牌验证
   - key-auth: API Key 验证
   - limit-count: 按租户限流 (1000/min)
   - limit-req: 请求限速
   - api-breaker: 熔断保护
   - proxy-rewrite: 动态路由
   - prometheus: 指标采集
   - cors: 跨域配置
3. 初始路由配置:
   - /api/v1/auth/* → auth-service:8081
   - /api/v1/capabilities/* → registry-service:8082
   - /api/v1/llm/* → llm-router:8083
   - /api/v1/billing/* → billing-service:8084
   - /api/v1/skills/* → skills-service:8085
   - /api/v1/admin/* → admin-service:8086
4. 实现动态路由更新机制 (通过 etcd 监听)
```

**交付物**:
- [ ] APISIX Docker 配置
- [ ] 插件配置文件
- [ ] 初始路由表
- [ ] 动态路由更新机制

---

## Phase 2：核心引擎（Week 5-8）

> **目标**: LLM Router + 计费引擎 + 用量追踪 全部跑通，可以调用 LLM 并计费
> **结束标志**: 用户通过 API Key 调用 LLM，自动扣费，用量可查

### 2.1 LLM Provider Router（Day 15-20）

**MiMo Code Quest Prompt**:
```
实现 LLM Provider Router 服务 (Go)。

功能:
1. 多平台 LLM 对接 (OpenAI 兼容格式):
   - DeepSeek: https://api.deepseek.com/v1
   - 千问: https://dashscope.aliyuncs.com/compatible-mode/v1
   - 豆包: https://ark.cn-beijing.volces.com/api/v3
   - 百度: 适配层封装为 OpenAI 格式
   - 元宝: https://api.yuanbao.tencent.com/v1
   - 智谱: https://open.bigmodel.cn/api/paas/v4
   - 本地 Ollama: http://localhost:11434/v1

2. 智能路由:
   - 按用户选择路由
   - 按成本自动选择最便宜模型
   - 按延迟自动选择最快模型
   - 故障转移: 主模型不可用时自动切换

3. API:
   - POST /v1/chat/completions (OpenAI 兼容)
   - GET  /api/v1/models (可用模型列表)
   - GET  /api/v1/providers (提供商状态)

4. 数据模型:
   - providers: id, name, base_url, api_key_encrypted, models_json, status, priority
   - model_routing_rules: model, provider_id, priority, is_default

5. 配置:
   - YAML 配置文件 + DB 动态更新
   - API Key 加密存储 (AES-256)
   - 连接池管理
   - 超时配置 (默认 30s)
```

**交付物**:
- [ ] llm-router Go 服务
- [ ] 7 个平台适配器
- [ ] 智能路由逻辑
- [ ] 故障转移机制
- [ ] OpenAI 兼容 API

### 2.2 Token 计费引擎（Day 21-27）

**MiMo Code Quest Prompt**:
```
实现 Token 计费引擎 (Go + Redis Lua)。

核心设计原则:
- 先扣后服: 先扣减余额，再允许调用
- 幂等: 通过 idempotency_key 防重复扣费
- 原子: Redis Lua 脚本保证原子性
- 可审计: 每笔变动有 trace_id

Credit 模型:
- 1 Credit = 1000 tokens (默认)
- 不同模型有系数: deepseek-chat=1.0, deepseek-reasoner=2.0, gpt-4o=10.0

Redis Lua 脚本 (metering.lua):
1. 幂等检查 (billing:idempotency:{tenant}:{key})
2. 余额检查 (billing:balance:{tenant})
3. 扣减余额 (DECRBY)
4. 记录幂等结果 (SET + 24h TTL)
5. 更新今日统计 (billing:daily:{tenant}:{date})

Go 服务 (services/billing):
- POST /api/v1/billing/meter (实时计量，调用 Lua)
- POST /api/v1/billing/topup (充值)
- GET  /api/v1/billing/balance (查询余额)
- GET  /api/v1/billing/transactions (流水查询)
- POST /api/v1/billing/subscribe (订阅管理)
- GET  /api/v1/billing/subscription (订阅状态)

订阅套餐:
- Free: ¥0/月, 100 Credits, 2 QPS
- Pro: ¥99/月, 50000 Credits, ¥0.01/Credit 超出, 20 QPS
- Team: ¥499/月, 300000 Credits, ¥0.008/Credit 超出, 100 QPS

Redis Key 设计:
- billing:balance:{tenant_id} → String (毫 Credit)
- billing:idempotency:{tenant_id}:{key} → Hash
- billing:daily:{tenant_id}:{YYYY-MM-DD} → Hash
- billing:subscription:{tenant_id} → Hash
```

**交付物**:
- [ ] metering.lua 脚本
- [ ] billing-service Go 服务
- [ ] 计费 API (6 个接口)
- [ ] 订阅套餐配置
- [ ] 单元测试 (Lua + Go)

### 2.3 用量追踪 Kafka → PostgreSQL（Day 28-32）

**MiMo Code Quest Prompt**:
```
实现用量追踪服务 (Go)。

架构:
LLM Router → Kafka Topic (usage.events) → Metering Consumer → PostgreSQL

Kafka Topic:
- topic: usage.events
- partition_key: tenant_id
- retention: 7d

Consumer (services/metering):
1. 消费 usage.events
2. 写入 token_usage 表 (按月分区)
3. 更新 tenant_balances 表 (从 Redis 同步)
4. 异常处理: 消费失败重试 3 次后进入死信队列

API:
- GET /api/v1/usage/summary?period=daily&date=2026-06-27 (用量汇总)
- GET /api/v1/usage/detail?start=...&end=... (用量明细)
- GET /api/v1/usage/by-model (按模型统计)
- GET /api/v1/usage/by-capability (按能力统计)

PostgreSQL 表:
- token_usage (按月分区，不可变)
- tenant_balances (实时同步)
- usage_summaries (预聚合，每小时刷新)
```

**交付物**:
- [ ] Kafka producer (在 LLM Router 中)
- [ ] metering-service Go 服务
- [ ] Consumer 逻辑
- [ ] 用量查询 API
- [ ] 预聚合定时任务

### 2.4 OpenAPI 网关（Day 33-35）

**MiMo Code Quest Prompt**:
```
实现平台 OpenAPI 网关 (Go)。

功能:
1. 对外暴露统一 OpenAI 兼容 API:
   - POST /v1/chat/completions
   - GET  /v1/models
   - POST /v1/embeddings
2. 内部路由到 LLM Router
3. 请求拦截链:
   - API Key 验证 → 租户上下文 → 余额检查 → 调用 LLM Router → 计费扣减 → 返回结果
4. 流式响应支持 (SSE)
5. 用量上报 (异步发 Kafka)

API:
- POST /v1/chat/completions (OpenAI 兼容，对外入口)
- POST /v1/capabilities/{id}/invoke (能力调用)
- GET  /v1/capabilities (能力列表)
```

**交付物**:
- [ ] openapi-gateway Go 服务
- [ ] OpenAI 兼容 API
- [ ] 流式 SSE 支持
- [ ] 请求拦截链

---

## Phase 3：能力治理（Week 9-12）

> **目标**: 能力注册中心 + Skills 市场 + 用户 Dashboard + 管理后台
> **结束标志**: 用户可在 Dashboard 管理能力、购买技能、查看用量

### 3.1 Capability Registry（Day 36-42）

**MiMo Code Quest Prompt**:
```
实现能力注册中心 (Go + gRPC/REST)。

功能:
1. 能力 CRUD:
   - POST   /api/v1/capabilities (注册)
   - DELETE /api/v1/capabilities/{id} (注销)
   - GET    /api/v1/capabilities (列表，支持 type/status/tags 过滤)
   - GET    /api/v1/capabilities/{id} (详情)
   - PUT    /api/v1/capabilities/{id} (更新)
   - POST   /api/v1/capabilities/{id}/versions (发布新版本)

2. 能力类型:
   - agent: AI 智能体
   - mcp: MCP 服务
   - skill: 技能
   - llm: LLM 提供商
   - custom: 自定义 OpenAPI 应用

3. 元数据:
   - name, type, version, description, tags
   - endpoint (调用地址)
   - protocol (rest/grpc/websocket)
   - pricing_config (计费配置)
   - dependencies (依赖的其他能力)
   - status: active / deprecated / beta

4. 服务发现:
   - 按类型查询
   - 按标签查询
   - 按状态过滤

5. gRPC 接口 (服务间调用):
   - RegisterCapability
   - DeregisterCapability
   - GetCapability
   - ListCapabilities
   - HealthCheck
```

**交付物**:
- [ ] registry-service Go 服务
- [ ] REST API (6 个接口)
- [ ] gRPC 接口 (5 个方法)
- [ ] 能力发现/查询
- [ ] 版本管理

### 3.2 Skills 市场（Day 43-47）

**MiMo Code Quest Prompt**:
```
实现 Skills 市场服务 (Go)。

功能:
1. 技能管理:
   - POST   /api/v1/skills (发布技能)
   - GET    /api/v1/skills (市场列表，支持搜索/分类/排序)
   - GET    /api/v1/skills/{id} (技能详情)
   - PUT    /api/v1/skills/{id} (更新)
   - DELETE /api/v1/skills/{id} (下架)

2. 技能购买:
   - POST /api/v1/skills/{id}/purchase (购买，扣 Credit)
   - GET  /api/v1/skills/purchased (已购列表)
   - 扣费通过 Billing Engine API

3. 计费模式:
   - per_call: 每次调用扣费
   - per_token: 按 Token 扣费
   - subscription: 订阅制
   - free: 免费

4. 分成:
   - 平台抽成 25%
   - 开发者分成 75%
   - 预留 skill_earnings 表

5. 搜索:
   - PostgreSQL 全文搜索 (中文分词: zhparser)
   - 按分类、标签、评分排序
```

**交付物**:
- [ ] skills-service Go 服务
- [ ] 技能 CRUD API
- [ ] 购买流程 (调用 Billing)
- [ ] 全文搜索
- [ ] 分成逻辑 (预留)

### 3.3 用户 Dashboard（Day 48-54）

**MiMo Code Quest Prompt**:
```
实现用户 Dashboard (React + TypeScript + Ant Design Pro)。

页面:
1. 首页概览:
   - Credit 余额 + 充值按钮
   - 今日/本月用量图表 (ECharts)
   - 快捷操作 (创建能力、浏览市场)

2. API Key 管理:
   - 创建/删除 API Key
   - Key 使用统计

3. 用量详情:
   - 按日/周/月图表
   - 按模型/能力分类统计
   - 导出 CSV

4. 账单中心:
   - Credit 流水记录
   - 订阅管理 (升级/降级/取消)
   - 充值历史

5. 我的能力:
   - 已创建的能力列表
   - 已购买的技能

6. 设置:
   - 个人信息
   - 通知偏好

技术:
- React 18 + TypeScript + Ant Design Pro 6
- ECharts 图表
- React Query 数据管理
- React Router 路由
```

**交付物**:
- [ ] web React 应用
- [ ] 6 个页面
- [ ] API 对接
- [ ] 响应式设计

### 3.4 管理后台（Day 55-58）

**MiMo Code Quest Prompt**:
```
实现管理后台 (React + TypeScript + Ant Design Pro)。

页面:
1. 仪表盘:
   - 总用户数、总租户数、总 API 调用量
   - 收入统计
   - 系统状态

2. 用户管理:
   - 用户列表 (搜索/过滤/分页)
   - 用户详情
   - 封禁/解封

3. 租户管理:
   - 租户列表
   - 租户详情 (订阅/用量/余额)
   - 调整余额

4. 能力审核:
   - 待审核能力列表
   - 审核通过/拒绝

5. 系统配置:
   - LLM 提供商配置
   - 订阅套餐配置
   - 全局限流配置

6. 监控:
   - API 调用趋势
   - 错误率
   - 响应时间
```

**交付物**:
- [ ] admin React 应用
- [ ] 6 个管理页面
- [ ] RBAC 权限控制

---

## Phase 4：生态扩展（Week 13-16）

> **目标**: IM Bot + MCP + Agent + ACP 全部接入
> **结束标志**: 用户可通过微信/QQ 与 AI 对话，可使用 MCP 工具，可创建 Agent

### 4.1 IM Bot 网关（Day 59-65）

**MiMo Code Quest Prompt**:
```
实现 IM Bot 网关 (Go)。

功能:
1. 多平台适配器:
   - 微信 (通过 LangBot/OpenClaw 协议)
   - QQ (通过 go-cqhttp 协议)
   - 钉钉 (通过钉钉开放平台 API)

2. 统一路由:
   - 消息接收 → 平台识别 → 上下文注入 → 调用 LLM Router → 回复
   - 会话管理 (Redis 存储上下文)

3. API:
   - POST /api/v1/im/callback/{platform} (平台回调)
   - GET  /api/v1/im/sessions (会话列表)
   - GET  /api/v1/im/sessions/{id}/messages (消息历史)

4. 配置:
   - 每个平台独立配置 (token, secret, etc.)
   - 每个租户独立的 bot 实例

5. 消息格式:
   - 文本/图片/文件
   - Markdown 渲染
   - 按钮交互
```

**交付物**:
- [ ] im-gateway Go 服务
- [ ] 微信适配器 (集成 LangBot)
- [ ] QQ 适配器
- [ ] 钉钉适配器
- [ ] 会话管理

### 4.2 MCP Hub 集成（Day 66-68）

**MiMo Code Quest Prompt**:
```
集成 mcp-hub 开源服务。

1. Docker 部署 mcp-hub
2. 与 Capability Registry 联动:
   - MCP Server 注册时自动在 Registry 创建 capability 记录
   - Registry 中 MCP 类型能力自动同步到 mcp-hub
3. API 代理:
   - /api/v1/mcp/servers → mcp-hub API
   - /api/v1/mcp/tools → mcp-hub 工具列表
   - /api/v1/mcp/call → mcp-hub 工具调用 (经过计费)
4. 计费集成:
   - MCP 工具调用经过 Billing Engine 扣费
```

**交付物**:
- [ ] mcp-hub Docker 配置
- [ ] Registry 联动逻辑
- [ ] MCP API 代理
- [ ] 计费集成

### 4.3 LangFlow Agent 集成（Day 69-73）

**MiMo Code Quest Prompt**:
```
集成 LangFlow 开源服务。

1. Docker 部署 LangFlow
2. 与 Capability Registry 联动:
   - LangFlow Flow 发布时自动在 Registry 创建 capability 记录
   - 支持 Flow 版本管理
3. API 代理:
   - /api/v1/agent/flows → LangFlow Flow 列表
   - /api/v1/agent/flows/{id}/run → 运行 Flow (经过计费)
   - /api/v1/agent/flows/{id}/chat → 流式对话 (SSE)
4. 计费集成:
   - Agent 调用经过 Billing Engine 扣费
5. 用户界面:
   - Dashboard 中嵌入 LangFlow 编辑器 (iframe)
   - Flow 管理页面
```

**交付物**:
- [ ] LangFlow Docker 配置
- [ ] Registry 联动逻辑
- [ ] Agent API 代理
- [ ] 计费集成

### 4.4 ACP 协议基础（Day 74-77）

**MiMo Code Quest Prompt**:
```
实现 ACP (Agent Communication Protocol) 基础。

1. 协议定义:
   - Agent 间消息格式 (JSON)
   - 消息类型: request, response, notification, error
   - 路由: 基于 agent_id 寻址

2. 消息总线:
   - 基于 Kafka 的 Agent 消息队列
   - topic: agent.messages.{agent_id}
   - 支持同步/异步通信

3. API:
   - POST /api/v1/acp/send (发送消息)
   - GET  /api/v1/acp/messages (接收消息)
   - GET  /api/v1/acp/agents (已注册 Agent 列表)

4. 安全:
   - Agent 间通信需要认证
   - 消息签名验证
```

**交付物**:
- [ ] ACP 协议定义
- [ ] 消息总线实现
- [ ] ACP API
- [ ] 安全机制

---

## Phase 5：集成上线（Week 17-20）

> **目标**: 全链路测试 + 生产部署 + 监控 + 文档
> **结束标志**: 平台可在生产环境运行，有完整文档

### 5.1 全链路测试（Day 78-83）

**MiMo Code Quest Prompt**:
```
编写 AI PaaS 平台的全链路测试。

1. 单元测试:
   - 各 Go 服务核心逻辑
   - Redis Lua 脚本测试
   - TypeScript 前端组件测试

2. 集成测试:
   - Auth → LLM Router → Billing 完整流程
   - Capability 注册 → 调用 → 计费流程
   - Skills 购买 → 使用 → 分成流程

3. E2E 测试:
   - 用户注册 → 登录 → 创建 API Key → 调用 LLM → 查看用量
   - 管理员登录 → 审核能力 → 查看统计

4. 压力测试:
   - LLM Router 并发 (100 QPS)
   - Billing Engine 并发 (1000 TPS)
   - API Gateway 压力 (500 RPS)

5. 测试工具:
   - Go: testing + testify
   - TypeScript: vitest + playwright
   - 压力: k6
```

**交付物**:
- [ ] 单元测试覆盖率 > 80%
- [ ] 集成测试套件
- [ ] E2E 测试脚本
- [ ] 压力测试报告

### 5.2 生产部署（Day 84-88）

**MiMo Code Quest Prompt**:
```
准备 AI PaaS 平台的生产部署配置。

1. Docker Compose (单机部署):
   - 所有服务容器化
   - 环境变量配置
   - 健康检查
   - 自动重启

2. Kubernetes (集群部署):
   - Helm Chart 编写
   - Deployment + Service + Ingress
   - ConfigMap + Secret
   - HPA 自动扩缩容
   - PDB (Pod Disruption Budget)

3. 数据库:
   - PostgreSQL 备份策略 (pg_dump 每日)
   - Redis 持久化配置
   - Kafka 备份

4. 域名 + SSL:
   - Nginx Ingress 配置
   - Let's Encrypt 自动证书

5. 环境区分:
   - dev: docker-compose
   - staging: k8s namespace
   - production: k8s namespace
```

**交付物**:
- [ ] docker-compose.prod.yml
- [ ] Helm Chart
- [ ] 部署脚本
- [ ] 环境配置模板

### 5.3 监控告警（Day 89-91）

**MiMo Code Quest Prompt**:
```
配置 AI PaaS 平台的监控告警系统。

1. Prometheus:
   - 各服务 metrics 端点
   - 自定义指标:
     - llm_router_request_total (by provider, model, status)
     - billing_credit_deduction_total (by tenant)
     - api_gateway_request_duration_seconds
   - 采集配置

2. Grafana:
   - Dashboard 配置:
     - 平台总览 (请求数/错误率/延迟)
     - LLM Router (各提供商状态/延迟)
     - Billing (收入/扣费趋势)
     - 用户活跃度
   - 告警规则

3. 告警:
   - 错误率 > 5% → 告警
   - 延迟 P99 > 5s → 告警
   - 余额 < 阈值 → 通知用户
   - 服务不可用 → 立即告警

4. 日志:
   - 结构化日志 (JSON)
   - 日志级别: debug/info/warn/error
   - 集中收集 (Loki 或 ELK)
```

**交付物**:
- [ ] Prometheus 配置
- [ ] Grafana Dashboard JSON
- [ ] 告警规则
- [ ] 日志配置

### 5.4 文档上线（Day 92-95）

**MiMo Code Quest Prompt**:
```
编写 AI PaaS 平台的完整文档。

1. API 文档:
   - OpenAPI 3.0 规范 (api-spec.yaml)
   - 每个接口的详细说明
   - 请求/响应示例
   - 错误码列表

2. 开发者文档:
   - 快速开始指南
   - 认证说明 (JWT + API Key)
   - SDK 使用示例 (Python/Go/TypeScript)
   - MCP Server 接入指南
   - Agent 发布指南

3. 运维文档:
   - 部署指南
   - 配置说明
   - 故障排查
   - 备份恢复

4. 架构文档:
   - 系统架构图
   - 数据流图
   - 数据库 ER 图
   - 部署架构图

5. 用户文档:
   - 注册/登录指南
   - API Key 使用指南
   - 用量查看指南
   - 订阅管理指南
```

**交付物**:
- [ ] API 文档 (OpenAPI 3.0)
- [ ] 开发者文档站
- [ ] 运维文档
- [ ] 架构文档
- [ ] 用户文档

---

## MiMo Code 核心配置 (.mimocode/AGENTS.md)

```markdown
# AI PaaS Platform

## 架构
- Go 后端服务 (API Gateway, LLM Router, Billing, Registry, Metering, Skills, IM Gateway)
- Python AI 服务 (LangFlow, MCP Hub)
- TypeScript 前端 (React + Ant Design Pro: web + admin)
- Infrastructure: PostgreSQL + Redis + Kafka + Milvus + Keycloak + APISIX

## 技术栈
- Go 1.22+ (高服务: 网关, 路由, 计费, 注册中心)
- Python 3.11+ (AI 服务: LangFlow, MCP)
- TypeScript 5+ (前端: React 18, Ant Design Pro 6, ECharts)
- PostgreSQL 16 (主数据库, RLS 多租户隔离)
- Redis 7 (缓存 + Lua 原子计费)
- Kafka 3.x (事件总线: 用量上报)
- Milvus 2.x (向量数据库: RAG)
- Keycloak 25+ (认证授权)
- Apache APISIX 3.15+ (API Gateway)
- Docker + K8s (部署)
- Prometheus + Grafana (监控)

## 开发规范
- Go: gofmt + golangci-lint, 遵循 Effective Go
- Python: ruff + black
- TypeScript: eslint + prettier
- 所有 API 必须有 OpenAPI 3.0 规范
- 所有数据库变更必须有 Migration 脚本 (版本号递增)
- Git: Conventional Commits (feat/fix/docs/chore)
- 测试: 单元测试覆盖率 > 80%

## 核心模块
- services/auth: Keycloak 适配器 + JWT/API Key 验证
- services/gateway: APISIX 自研插件
- services/llm-router: 多平台 LLM 智能路由 + 故障转移
- services/billing: Token 计费引擎 (Redis Lua 原子操作)
- services/metering: 用量追踪 (Kafka → PostgreSQL)
- services/registry: 能力注册中心 (gRPC + REST)
- services/skills: Skills 市场
- services/im-gateway: IM Bot 多平台网关

## 数据库
- 所有表启用 RLS，策略基于 tenant_id
- token_usage 按月分区
- credit_transactions 不可变 (追加写)
- 所有金额使用整数 (毫 Credit)，避免浮点

## 计费原则
- 先扣后服: 先扣减余额，再允许调用
- 幂等: 通过 idempotency_key 防重复扣费
- 原子: Redis Lua 脚本保证原子性
- 可审计: 每笔变动有 trace_id + 原因

## LLM 对接
- 统一 OpenAI 兼容格式: POST /v1/chat/completions
- 百度需要适配层 (非标准 API)
- 其他平台直接兼容
- API Key 加密存储 (AES-256)
```

---

## 风险与对策

| 风险 | 等级 | 影响 | 对策 |
|------|------|------|------|
| 开发周期长 | 高 | 20 周投入大 | 分 Phase 交付，每 Phase 结束有可运行成果 |
| 技术复杂度高 | 中 | 多服务协调 | MiMo Code 辅助生成骨架，降低编码量 |
| 单人开发 | 中 | 人力瓶颈 | 严格控制范围，Phase 内任务优先级排序 |
| APISIX 学习曲线 | 低 | 网关配置复杂 | 文档完善，社区活跃，插件机制成熟 |
| Kafka 运维 | 中 | 消息积压 | 监控 Consumer Lag，自动扩缩容 |
| 数据一致性 | 中 | 计费准确性 | Redis Lua 原子操作 + 每日对账 |
| LLM 平台 API 变动 | 低 | 适配器失效 | 抽象 Provider 接口，变动时只改适配器 |

---

## 每日开发节奏建议

```
09:00-09:15  每日站会 (自检: 昨日完成/今日计划/阻塞)
09:15-12:00  MiMo Code 核心开发 (Quest Mode / Agent Mode)
12:00-13:30  午休
13:30-15:00  MiMo Code 继续开发
15:00-15:30  Code Review + 测试
15:30-17:00  MiMo Code 补充测试 + 文档
17:00-17:30  Git 提交 + 推送 + 更新进度
```

---

## Phase 完成检查清单

每个 Phase 结束时，必须通过以下检查：

### Phase 1 检查
- [ ] `docker-compose up` 所有服务正常启动
- [ ] Keycloak 可注册/登录用户
- [ ] APISIX 可转发请求到后端服务
- [ ] 数据库 Schema 已创建，RLS 策略生效
- [ ] 各服务 health endpoint 返回 200

### Phase 2 检查
- [ ] 可通过 API Key 调用 LLM (至少 3 个平台)
- [ ] 调用后自动扣费，余额正确
- [ ] 用量数据写入 PostgreSQL
- [ ] 流式响应 (SSE) 正常工作
- [ ] 故障转移测试通过 (关闭主模型，自动切换)

### Phase 3 检查
- [ ] 可注册新能力 (Agent/MCP/Skill)
- [ ] 可在市场购买技能
- [ ] Dashboard 显示正确的余额和用量
- [ ] 管理后台可管理用户和租户
- [ ] 搜索功能正常

### Phase 4 检查
- [ ] IM Bot 可收发消息 (至少 1 个平台)
- [ ] MCP 工具可调用并计费
- [ ] LangFlow Flow 可运行并计费
- [ ] ACP 消息可发送和接收

### Phase 5 检查
- [ ] 单元测试覆盖率 > 80%
- [ ] 全链路 E2E 测试通过
- [ ] 压力测试报告 (目标: 500 RPS)
- [ ] Docker Compose 生产配置可用
- [ ] Grafana Dashboard 正常显示
- [ ] API 文档完整 (OpenAPI 3.0)
- [ ] 开发者文档可访问

---

*文档版本: 1.0 | 更新日期: 2026-06-27 | 基于 5 平台交叉验证共识*