# AI PaaS Platform — AGENTS.md (v2.0)

> 放置于 `.mimocode/AGENTS.md`，MiMo Code 每次启动自动加载。

---

# AI PaaS 商业平台

## 一句话描述
**让任何 AI 使用者都能像用水电一样使用 AI 能力，注册即用，按量付费。**

## 用户模型
- 扁平化：只有用户，没有租户概念
- 权限分级：未认证 → 已实名 → 订阅用户
- 订阅用户：完成实名认证 + 支付月费，自动获得创建/发布 AI 能力权限
- **核心规则：欠费不影响已发布能力**

## 技术栈
- **AI 服务层**: Python 3.11+ (FastAPI) — 所有自研业务服务
- **LLM 网关**: NEW API (Go, 开源) — 多模型统一管理
- **SSO 认证**: Casdoor (Go, 开源) — OAuth2/OIDC/社交登录
- **API 网关**: APISIX (Lua, 开源) — 路由/限流/鉴权
- **本地 LLM**: Ollama (Go, 开源) — 本地模型推理
- **Agent 编排**: LangFlow (Python, 开源) — 可视化工作流
- **前端**: React 18 + TypeScript + Ant Design Pro + ECharts
- **数据库**: PostgreSQL 16
- **缓存**: Redis 7 (Lua 原子计费)
- **消息队列**: Kafka 3.x (用量上报)
- **实名认证**: 阿里云实名认证 API

## 项目结构
```
ai-paas-platform/
├── .mimocode/
│   └── AGENTS.md                ← 本文件
├── docs/
│   ├── 01-PRD-产品需求文档.md
│   ├── 02-系统架构设计.md
│   ├── 03-数据库设计.md
│   └── 04-API接口规范.md
├── packages/
│   └── web/                      ← React Dashboard
├── services/
│   ├── gateway/                  ← FastAPI 核心网关 (:8080)
│   ├── billing/                  ← FastAPI 计费引擎 (:8081)
│   ├── registry/                 ← FastAPI 能力注册 (:8082)
│   ├── skills/                   ← FastAPI Skills 市场 (:8083)
│   ├── metering/                 ← FastAPI 用量追踪 (:8084)
│   └── admin/                    ← FastAPI 管理后台 (:8085)
├── infra/
│   ├── casdoor/                  ← Casdoor 配置
│   ├── new-api/                  ← NEW API 配置
│   ├── ollama/                   ← Ollama 配置
│   ├── apisix/                   ← APISIX 配置
│   ├── postgresql/               ← 数据库初始化
│   ├── redis/
│   └── kafka/
├── deploy/
│   ├── docker-compose.yml        ← 一键启动开发环境
│   └── k8s/
├── migrations/
└── pyproject.toml
```

## 开发规范

### Python 服务 (FastAPI)
- 遵循 ruff + black 格式化
- 每个服务独立目录，可独立运行
- 服务间通信: 同步 HTTP，异步 Kafka
- 错误处理: 统一 `{code, message, data}` 格式
- 配置管理: 环境变量 + .env 文件
- 日志: structlog (结构化 JSON)
- 类型注解: 必须 (Pydantic v2)
- 测试: pytest + httpx, 覆盖率 > 80%

### TypeScript 前端
- eslint + prettier
- React 函数组件 + Hooks
- 状态: React Query (服务端) + Zustand (客户端)
- 路由: React Router v6
- 样式: Ant Design Pro 内置

### Git
- 分支: main, develop, feature/*
- 提交: Conventional Commits (feat/fix/docs/chore/test)
- PR: 必须通过 CI

## 核心服务说明

### ai-paas-gateway (:8080)
- 所有业务请求入口
- JWT 验证 (对接 Casdoor)
- API Key 验证 (SHA-256 查 DB)
- 用户状态检查 (订阅/欠费)
- LLM 调用代理: gateway → NEW API → LLM
- 流式 SSE 透传
- 用量异步上报 (Kafka)

### ai-paas-billing (:8081)
- Redis Lua 原子操作
- 先扣后服 + 幂等 + 可审计
- 订阅管理 (Free/Developer/Pro/Flagship)
- Token 包充值
- 欠费保护期 (7 天)
- 开发者分成结算

### ai-paas-registry (:8082)
- 能力 CRUD
- 能力类型: agent/mcp/skill/llm/custom
- 版本管理: SemVer
- 状态: draft → pending_review → active → deprecated
- **欠费时已发布能力保持 active**

### ai-paas-skills (:8083)
- 技能市场浏览/搜索/购买
- 开发者发布技能
- 分成: 平台 25% / 开发者 75%
- 全文搜索 (PostgreSQL GIN)
- 评分系统

### ai-paas-metering (:8084)
- Kafka Consumer
- PostgreSQL 持久化
- 按月分区表
- 预聚合统计

### ai-paas-admin (:8085)
- 用户管理
- 能力审核
- 财务管理
- 系统监控

## 计费原则（最重要）
1. **先扣后服**: 先扣减余额，再允许调用
2. **幂等**: idempotency_key 防重复扣费
3. **原子**: Redis Lua 保证原子性
4. **可审计**: 每笔变动有 trace_id
5. **欠费保护**: 已发布能力不被下架

## LLM 对接
- 统一通过 NEW API 代理
- NEW API 配置各平台 API Key
- 格式: OpenAI 兼容 (POST /v1/chat/completions)
- 流式: SSE (text/event-stream)
- 百度需适配层 (NEW API 内置)

## 实名认证
- 阿里云实名认证 API
- 用户提交: 真实姓名 + 身份证号
- 验证通过: 标记 verified = true
- 信息加密存储 (AES-256)

## 重要约束
- 所有 API 必须有 OpenAPI 文档 (FastAPI 自动生成)
- 所有数据库变更必须有 Migration
- 所有金额使用整数 (分)
- 所有敏感数据加密
- **欠费不影响已发布能力**