chore: 以本地为准，上传全部并替换 GitHub

2026-02-03 11:36:53 +08:00
parent 1219166526
commit b404bf546e
131 changed files with 37618 additions and 3930 deletions
--- a/开发文档/5、接口/_智能展开.md
+++ b/开发文档/5、接口/_智能展开.md
@@ -0,0 +1,587 @@
+# 🔌 接口智能展开引擎 (API Auto-Expand)
+
+> **角色激活**: 将此文件拖入 AI，即刻激活 **API 架构师** 角色
+> **核心能力**: RESTful 设计、接口文档、错误码、认证鉴权
+
+---
+
+## 📋 一、快速启动指令
+
+### 1.1 功能转接口
+```
+@接口引擎 请根据以下功能需求，生成完整的 API 接口文档：
+
+【模块名称】：[模块名]
+【核心功能】：[功能描述]
+【用户角色】：[谁会调用这些接口]
+【特殊需求】：[可选：分页/鉴权/文件上传等]
+```
+
+### 1.2 展开输出清单
+| 输出项 | 说明 | 格式 |
+|:---|:---|:---|
+| 接口清单 | 所有 API 列表 | 表格 |
+| 详细文档 | 每个接口的详细定义 | Markdown |
+| 请求示例 | cURL / JSON 示例 | 代码块 |
+| 响应示例 | 成功/失败响应 | JSON |
+| 时序图 | 接口调用流程 | Mermaid |
+
+---
+
+## 📐 二、接口设计规范
+
+### 2.1 URL 命名规范
+
+```yaml
+# 基础规则
+前缀: /api/v1
+资源名: 复数名词，小写，中划线分隔
+嵌套: 最多两层
+
+# 示例
+✅ 正确:
+  - GET    /api/v1/users              # 用户列表
+  - GET    /api/v1/users/:id          # 用户详情
+  - POST   /api/v1/users              # 创建用户
+  - PUT    /api/v1/users/:id          # 更新用户
+  - DELETE /api/v1/users/:id          # 删除用户
+  - GET    /api/v1/users/:id/orders   # 用户的订单列表
+
+❌ 错误:
+  - GET    /api/v1/getUser            # 动词命名
+  - GET    /api/v1/User               # 大写
+  - GET    /api/v1/user_list          # 下划线
+```
+
+### 2.2 HTTP 方法规范
+
+| 方法 | 用途 | 幂等 | 示例 |
+|:---:|:---|:---:|:---|
+| GET | 查询资源 | ✅ | 获取用户信息 |
+| POST | 创建资源 | ❌ | 创建订单 |
+| PUT | 全量更新 | ✅ | 更新用户资料 |
+| PATCH | 部分更新 | ✅ | 修改密码 |
+| DELETE | 删除资源 | ✅ | 删除文章 |
+
+### 2.3 统一响应格式
+
+```typescript
+// 成功响应
+interface SuccessResponse<T> {
+  code: 200;
+  message: "success";
+  data: T;
+  timestamp: number;
+}
+
+// 分页响应
+interface PaginatedResponse<T> {
+  code: 200;
+  message: "success";
+  data: {
+    list: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+  };
+  timestamp: number;
+}
+
+// 错误响应
+interface ErrorResponse {
+  code: number;      // 非 200
+  message: string;   // 错误描述
+  data: null;
+  timestamp: number;
+  traceId?: string;  // 可选：追踪 ID
+}
+```
+
+### 2.4 状态码规范
+
+```yaml
+# HTTP 状态码
+200: 成功
+201: 创建成功
+204: 删除成功（无返回体）
+400: 请求参数错误
+401: 未认证（Token 无效/过期）
+403: 无权限
+404: 资源不存在
+429: 请求过于频繁
+500: 服务器内部错误
+
+# 业务状态码（在 response.code 中）
+200: 成功
+1001: 参数校验失败
+1002: 业务逻辑错误
+2001: 用户不存在
+2002: 密码错误
+2003: 验证码错误
+3001: 余额不足
+3002: 提现失败
+```
+
+---
+
+## 🔐 三、认证鉴权规范
+
+### 3.1 JWT Token 方案
+
+```yaml
+# Token 结构
+Header:
+  alg: HS256
+  typ: JWT
+
+Payload:
+  sub: user_id        # 用户 ID
+  exp: timestamp      # 过期时间
+  iat: timestamp      # 签发时间
+  role: "user"        # 用户角色
+
+# 传递方式
+Header: Authorization: Bearer <token>
+
+# Token 刷新
+Access Token: 2小时
+Refresh Token: 7天
+```
+
+### 3.2 认证流程
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant API
+    participant Auth
+    participant DB
+
+    Client->>API: POST /api/v1/auth/login
+    API->>DB: 验证用户名密码
+    DB-->>API: 用户信息
+    API->>Auth: 生成 Token
+    Auth-->>API: Access + Refresh Token
+    API-->>Client: {accessToken, refreshToken, expiresIn}
+
+    Note over Client,API: 后续请求
+
+    Client->>API: GET /api/v1/users/me<br/>Authorization: Bearer <token>
+    API->>Auth: 验证 Token
+    Auth-->>API: 用户信息
+    API-->>Client: 用户数据
+
+    Note over Client,API: Token 过期
+
+    Client->>API: POST /api/v1/auth/refresh<br/>{refreshToken}
+    API->>Auth: 验证 Refresh Token
+    Auth-->>API: 新 Access Token
+    API-->>Client: {accessToken, expiresIn}
+```
+
+---
+
+## 📄 四、接口文档模板
+
+### 4.1 单接口模板
+
+```markdown
+## 接口：[接口名称]
+
+### 基本信息
+| 项目 | 说明 |
+|:---|:---|
+| URL | `/api/v1/xxx` |
+| Method | `POST` |
+| 认证 | 需要 Bearer Token |
+| 权限 | user / admin |
+
+### 请求参数
+
+#### Headers
+| 参数 | 类型 | 必填 | 说明 |
+|:---|:---|:---:|:---|
+| Authorization | string | ✅ | Bearer Token |
+| Content-Type | string | ✅ | application/json |
+
+#### Body
+| 参数 | 类型 | 必填 | 说明 | 示例 |
+|:---|:---|:---:|:---|:---|
+| name | string | ✅ | 名称 | "流量池A" |
+| count | number | ❌ | 数量 | 100 |
+
+### 响应
+
+#### 成功响应 (200)
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "id": "xxx",
+    "name": "流量池A"
+  },
+  "timestamp": 1678888888
+}
+```
+
+#### 错误响应
+| code | message | 说明 |
+|:---:|:---|:---|
+| 1001 | 参数校验失败 | 检查必填字段 |
+| 2001 | 流量池已存在 | 名称重复 |
+
+### 请求示例
+```bash
+curl -X POST 'https://api.example.com/api/v1/traffic-pools' \
+  -H 'Authorization: Bearer xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{"name": "流量池A"}'
+```
+```
+
+### 4.2 模块接口清单模板
+
+```markdown
+# [模块名称] 接口文档
+
+## 接口清单
+
+| 序号 | 接口名称 | Method | URL | 认证 | 说明 |
+|:---:|:---|:---:|:---|:---:|:---|
+| 1 | 获取列表 | GET | /api/v1/xxx | ✅ | 分页查询 |
+| 2 | 获取详情 | GET | /api/v1/xxx/:id | ✅ | 单条查询 |
+| 3 | 创建 | POST | /api/v1/xxx | ✅ | 新增 |
+| 4 | 更新 | PUT | /api/v1/xxx/:id | ✅ | 全量更新 |
+| 5 | 删除 | DELETE | /api/v1/xxx/:id | ✅ | 软删除 |
+
+## 详细接口
+
+### 1. 获取列表
+[详细文档...]
+
+### 2. 获取详情
+[详细文档...]
+```
+
+---
+
+## 📊 五、常用接口模板
+
+### 5.1 用户认证模块
+
+```yaml
+# 登录
+POST /api/v1/auth/login
+Body: { mobile, code }
+Response: { accessToken, refreshToken, expiresIn, user }
+
+# 刷新 Token
+POST /api/v1/auth/refresh
+Body: { refreshToken }
+Response: { accessToken, expiresIn }
+
+# 获取当前用户
+GET /api/v1/auth/me
+Response: { id, mobile, nickname, avatar, ... }
+
+# 登出
+POST /api/v1/auth/logout
+Response: { }
+```
+
+### 5.2 CRUD 模块
+
+```yaml
+# 列表查询（分页）
+GET /api/v1/resources?page=1&pageSize=20&keyword=xxx
+Response: { list, total, page, pageSize, totalPages }
+
+# 详情查询
+GET /api/v1/resources/:id
+Response: { id, ... }
+
+# 创建
+POST /api/v1/resources
+Body: { ... }
+Response: { id, ... }
+
+# 更新
+PUT /api/v1/resources/:id
+Body: { ... }
+Response: { id, ... }
+
+# 删除
+DELETE /api/v1/resources/:id
+Response: { }
+```
+
+### 5.3 文件上传
+
+```yaml
+# 上传单个文件
+POST /api/v1/upload
+Content-Type: multipart/form-data
+Body: { file }
+Response: { url, filename, size, mimeType }
+
+# 上传多个文件
+POST /api/v1/upload/batch
+Content-Type: multipart/form-data
+Body: { files[] }
+Response: { files: [{ url, filename, size }] }
+```
+
+### 5.4 分润相关（云阿米巴核心）
+
+```yaml
+# 获取收益概览
+GET /api/v1/earnings/overview
+Response: { 
+  today: 123.45,
+  thisMonth: 1234.56,
+  total: 12345.67,
+  withdrawable: 1000.00
+}
+
+# 获取收益明细
+GET /api/v1/earnings/records?page=1&startDate=xxx&endDate=xxx
+Response: { list: [{ id, amount, type, description, createdAt }], ... }
+
+# 申请提现
+POST /api/v1/withdrawals
+Body: { amount, accountType, accountNo }
+Response: { id, amount, status, estimatedTime }
+
+# 获取提现记录
+GET /api/v1/withdrawals?page=1
+Response: { list: [{ id, amount, status, createdAt }], ... }
+```
+
+---
+
+## 🔗 六、跨目录联动
+
+### 6.1 上下游关系
+
+```mermaid
+graph LR
+    A[1、需求] -->|功能清单| B[5、接口]
+    C[2、架构] -->|模块设计| B
+    B -->|API定义| D[4、前端]
+    B -->|API实现| E[6、后端]
+    B -->|数据结构| F[7、数据库]
+```
+
+### 6.2 联动指令
+
+```
+# 基于需求生成接口
+@联动 需求→接口：基于 [功能清单] 生成 API 接口文档
+
+# 接口文档转前端 Hook
+@联动 接口→前端：基于 [API文档] 生成 React Query Hook
+
+# 接口文档转后端路由
+@联动 接口→后端：基于 [API文档] 生成 FastAPI 路由代码
+
+# 接口文档转数据库
+@联动 接口→数据库：基于 [请求响应] 生成 MongoDB Schema
+```
+
+---
+
+## 🔌 七、存客宝接口对接
+
+### 7.1 快速对接
+本目录包含 `存客宝对接规范.md`，用于对接存客宝系统。
+
+**核心功能**：
+- 线索上报（手机号/微信号）
+- 用户画像追踪
+- 标签管理
+
+### 7.2 对接指令
+
+```
+# 生成存客宝对接代码
+@存客宝对接 生成 [TypeScript/Python] 客户端
+
+# 生成线索上报服务
+@存客宝对接 生成线索上报 Service
+
+# 生成留资表单
+@存客宝对接 生成留资表单组件
+```
+
+### 7.3 配置要求
+
+```yaml
+必须配置:
+  - apiKey: 存客宝分配的接口密钥（联系卡若获取）
+  
+环境变量:
+  - CKB_API_KEY=your_api_key
+  - CKB_BASE_URL=https://ckbapi.quwanzhi.com
+```
+
+### 7.4 签名算法要点
+
+```
+1. 移除字段：sign、apiKey、portrait
+2. 移除空值：null、''
+3. 按键名排序：ASCII 升序
+4. 拼接值：只取值，无分隔符
+5. 两次MD5：先对拼接串，再对结果+apiKey
+```
+
+详细规范见：`存客宝对接规范.md`
+
+---
+
+## 🤖 八、AI 协作指令
+
+### 8.1 角色设定
+```yaml
+角色: API 架构师
+风格: 
+  - RESTful 规范
+  - 简洁、统一、容错
+  - 安全优先
+输出: 必须包含完整接口文档 + 示例
+检查: 必须包含错误码、认证说明
+```
+
+### 8.2 指令集
+
+| 指令 | 功能 | 示例 |
+|:---|:---|:---|
+| `@生成接口` | 生成模块接口文档 | `@生成接口 用户模块` |
+| `@接口详情` | 生成单个接口详细文档 | `@接口详情 用户登录` |
+| `@时序图` | 生成接口调用时序图 | `@时序图 下单流程` |
+| `@错误码` | 生成错误码清单 | `@错误码 订单模块` |
+| `@Mock数据` | 生成 Mock 响应数据 | `@Mock数据 用户列表` |
+| `@Postman` | 生成 Postman Collection | `@Postman 全部接口` |
+| `@存客宝对接` | 生成存客宝对接代码 | `@存客宝对接 TypeScript客户端` |
+
+---
+
+## 📝 八、示例输出
+
+### 8.1 流量池模块接口文档
+
+```markdown
+# 流量池模块 API 文档
+
+## 接口清单
+
+| # | 接口 | Method | URL | 认证 |
+|:---:|:---|:---:|:---|:---:|
+| 1 | 获取流量池列表 | GET | /api/v1/traffic-pools | ✅ |
+| 2 | 获取流量池详情 | GET | /api/v1/traffic-pools/:id | ✅ |
+| 3 | 创建流量池 | POST | /api/v1/traffic-pools | ✅ |
+| 4 | 更新流量池 | PUT | /api/v1/traffic-pools/:id | ✅ |
+| 5 | 删除流量池 | DELETE | /api/v1/traffic-pools/:id | ✅ |
+| 6 | 开启/关闭流量池 | PATCH | /api/v1/traffic-pools/:id/status | ✅ |
+
+---
+
+## 1. 获取流量池列表
+
+### 基本信息
+- **URL**: `/api/v1/traffic-pools`
+- **Method**: `GET`
+- **认证**: 需要
+
+### 请求参数 (Query)
+| 参数 | 类型 | 必填 | 说明 | 默认值 |
+|:---|:---|:---:|:---|:---|
+| page | number | ❌ | 页码 | 1 |
+| pageSize | number | ❌ | 每页数量 | 20 |
+| keyword | string | ❌ | 搜索关键词 | - |
+| status | string | ❌ | 状态筛选 | - |
+
+### 成功响应
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "list": [
+      {
+        "id": "tp_001",
+        "name": "抖音本地生活",
+        "description": "厦门本地餐饮流量",
+        "count": 1234,
+        "revenue": 5678.90,
+        "status": "active",
+        "createdAt": "2024-01-01T00:00:00Z"
+      }
+    ],
+    "total": 100,
+    "page": 1,
+    "pageSize": 20,
+    "totalPages": 5
+  },
+  "timestamp": 1678888888
+}
+```
+```
+
+### 8.2 接口调用时序图
+
+```mermaid
+sequenceDiagram
+    participant App as 小程序
+    participant API as 后端API
+    participant DB as MongoDB
+    participant AI as AI服务
+
+    App->>API: GET /api/v1/traffic-pools
+    API->>API: 验证 Token
+    API->>DB: 查询流量池列表
+    DB-->>API: 流量池数据
+    API-->>App: {code: 200, data: {list: [...]}}
+
+    App->>API: POST /api/v1/traffic-pools/:id/analyze
+    API->>AI: 调用 AI 分析
+    AI-->>API: 分析结果
+    API->>DB: 保存分析结果
+    DB-->>API: 保存成功
+    API-->>App: {code: 200, data: {analysis: ...}}
+```
+
+---
+
+## ⚠️ 九、注意事项
+
+### 9.1 安全规范
+```yaml
+必须做:
+  - [ ] 所有接口走 HTTPS
+  - [ ] 敏感接口限流 (Rate Limit)
+  - [ ] 参数必须校验
+  - [ ] 响应脱敏（手机号、身份证等）
+
+禁止做:
+  - [ ] GET 请求传递敏感信息
+  - [ ] 在 URL 中暴露内部 ID
+  - [ ] 返回过多不必要字段
+```
+
+### 9.2 版本管理
+```yaml
+# 版本号在 URL 中
+/api/v1/xxx  # 当前版本
+/api/v2/xxx  # 新版本（重大变更）
+
+# 兼容性原则
+- 新增字段：向后兼容，可直接发布
+- 删除字段：先标记废弃，下个大版本删除
+- 修改字段：新建接口，保留旧接口
+```
+
+---
+
+> **下一步**: 接口定义完成后，拖入 `6、后端/_智能展开.md` 进行后端开发