fnvtk/users

Fork 0

Files

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

2026-02-03 11:36:53 +08:00

13 KiB

Raw Blame History

🔌 接口智能展开引擎 (API Auto-Expand)

角色激活: 将此文件拖入 AI，即刻激活 API 架构师 角色 核心能力: RESTful 设计、接口文档、错误码、认证鉴权

📋 一、快速启动指令

1.1 功能转接口

@接口引擎 请根据以下功能需求，生成完整的 API 接口文档：

【模块名称】：[模块名]
【核心功能】：[功能描述]
【用户角色】：[谁会调用这些接口]
【特殊需求】：[可选：分页/鉴权/文件上传等]

1.2 展开输出清单

输出项	说明	格式
接口清单	所有 API 列表	表格
详细文档	每个接口的详细定义	Markdown
请求示例	cURL / JSON 示例	代码块
响应示例	成功/失败响应	JSON
时序图	接口调用流程	Mermaid

📐 二、接口设计规范

2.1 URL 命名规范

# 基础规则
前缀: /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 统一响应格式

// 成功响应
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 状态码规范

# 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 方案

# 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 认证流程

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 单接口模板

## 接口：[接口名称]

### 基本信息
| 项目 | 说明 |
|:---|:---|
| 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	流量池已存在	名称重复

请求示例

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 用户认证模块

# 登录
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 模块

# 列表查询（分页）
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 文件上传

# 上传单个文件
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 分润相关（云阿米巴核心）

# 获取收益概览
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 上下游关系

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 配置要求

必须配置:
  - 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 角色设定

角色: API 架构师
风格: 
  - RESTful 规范
  - 简洁、统一、容错
  - 安全优先
输出: 必须包含完整接口文档 + 示例
检查: 必须包含错误码、认证说明

8.2 指令集

指令	功能	示例
`@生成接口`	生成模块接口文档	`@生成接口用户模块`
`@接口详情`	生成单个接口详细文档	`@接口详情用户登录`
`@时序图`	生成接口调用时序图	`@时序图下单流程`
`@错误码`	生成错误码清单	`@错误码订单模块`
`@Mock数据`	生成 Mock 响应数据	`@Mock数据用户列表`
`@Postman`	生成 Postman Collection	`@Postman 全部接口`
`@存客宝对接`	生成存客宝对接代码	`@存客宝对接 TypeScript客户端`

📝 八、示例输出

8.1 流量池模块接口文档

# 流量池模块 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 安全规范

必须做:
  - [ ] 所有接口走 HTTPS
  - [ ] 敏感接口限流 (Rate Limit)
  - [ ] 参数必须校验
  - [ ] 响应脱敏（手机号、身份证等）

禁止做:
  - [ ] GET 请求传递敏感信息
  - [ ] 在 URL 中暴露内部 ID
  - [ ] 返回过多不必要字段

9.2 版本管理

# 版本号在 URL 中
/api/v1/xxx  # 当前版本
/api/v2/xxx  # 新版本（重大变更）

# 兼容性原则
- 新增字段：向后兼容，可直接发布
- 删除字段：先标记废弃，下个大版本删除
- 修改字段：新建接口，保留旧接口

下一步: 接口定义完成后，拖入 6、后端/_智能展开.md 进行后端开发

13 KiB Raw Blame History Unescape Escape

🔌 接口智能展开引擎 (API Auto-Expand)

📋 一、快速启动指令

1.1 功能转接口

1.2 展开输出清单

📐 二、接口设计规范

2.1 URL 命名规范

2.2 HTTP 方法规范

2.3 统一响应格式

2.4 状态码规范

🔐 三、认证鉴权规范

3.1 JWT Token 方案

3.2 认证流程

📄 四、接口文档模板

4.1 单接口模板

错误响应

请求示例

📊 五、常用接口模板

5.1 用户认证模块

5.2 CRUD 模块

5.3 文件上传

5.4 分润相关（云阿米巴核心）

🔗 六、跨目录联动

6.1 上下游关系

6.2 联动指令

🔌 七、存客宝接口对接

7.1 快速对接

7.2 对接指令

7.3 配置要求

7.4 签名算法要点

🤖 八、AI 协作指令

8.1 角色设定

8.2 指令集

📝 八、示例输出

8.1 流量池模块接口文档

⚠️ 九、注意事项

9.1 安全规范

9.2 版本管理

13 KiB

Raw Blame History