soul-yongping/开发文档/5、接口/API接口完整文档.md

# API接口完整文档 - Soul创业实验项目

> **API风格**: RESTful | **版本**: v1.0 | **基础路径**: `/api`  
> **说明**：本文档已整合原《API接口》内容，为项目唯一 API 参考。

**我是卡若。**

接口设计原则：**简单、清晰、易用**。

---

## 1. 接口总览

### 1.1 接口分类

| 模块 | 路径前缀 | 描述 |
|------|---------|------|
| 书籍内容 | `/api/book` | 章节列表、内容获取、同步 |
| 支付系统 | `/api/payment` | 订单创建、支付回调、状态查询 |
| 分销系统 | `/api/referral` | 邀请码、收益查询、提现 |
| 用户系统 | `/api/user` | 登录、注册、信息更新 |
| 匹配系统 | `/api/match` | 寻找匹配、匹配历史 |
| 管理后台 | `/api/admin` | 内容/订单/用户/分销管理 |
| 配置系统 | `/api/config` | 系统配置获取 |

### 1.2 认证方式

**用户认证** (可选):
```
Cookie: session_id=<session-id>
```

**管理员认证** (必需):
```
Authorization: Bearer admin-token-secret
```

---

## 2. 书籍内容API

### 2.1 获取所有章节

**接口**: `GET /api/book/all-chapters`

**请求**:
```bash
curl https://your-domain.com/api/book/all-chapters
```

**响应**:
```json
{
  "success": true,
  "data": [
    {
      "id": "part-1",
      "number": "01",
      "title": "真实的人",
      "subtitle": "人性观察与社交逻辑",
      "chapters": [
        {
          "id": "chapter-1",
          "title": "人与人之间的底层逻辑",
          "sections": [
            {
              "id": "1.1",
              "title": "自行车荷总:一个行业做到极致是什么样",
              "price": 1,
              "isFree": true,
              "filePath": "book/第一篇｜真实的人/...",
              "unlockAfterDays": 0
            }
          ]
        }
      ]
    }
  ],
  "total": 64
}
```

### 2.2 获取单章内容

**接口**: `GET /api/book/chapter/:id`

**请求**:
```bash
curl https://your-domain.com/api/book/chapter/1.1
```

**响应**:
```json
{
  "success": true,
  "data": {
    "id": "1.1",
    "title": "自行车荷总:一个行业做到极致是什么样",
    "content": "# 章节内容...",
    "chapter": "第1章｜人与人之间的底层逻辑",
    "section": "第一篇｜真实的人",
    "isFree": true,
    "price": 1,
    "prev": null,
    "next": "1.2"
  }
}
```

### 2.3 同步章节

**接口**: `POST /api/book/sync`

**请求**:
```bash
curl -X POST https://your-domain.com/api/book/sync \
  -H "Authorization: Bearer admin-token-secret"
```

**响应**:
```json
{
  "success": true,
  "message": "同步完成",
  "synced": 64,
  "updated": 3
}
```

---

## 3. 支付API

### 3.1 创建订单

**接口**: `POST /api/payment/create-order`

**请求**:
```bash
curl -X POST https://your-domain.com/api/payment/create-order \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "type": "fullbook",
    "amount": 9.9,
    "paymentMethod": "alipay"
  }'
```

**参数**:
```typescript
{
  userId: string          // 用户ID
  type: 'section' | 'fullbook'  // 订单类型
  sectionId?: string      // 章节ID (章节购买时必需)
  amount: number          // 支付金额
  paymentMethod: 'wechat' | 'alipay' | 'usdt'  // 支付方式
}
```

**响应**:
```json
{
  "success": true,
  "data": {
    "orderId": "order_1705230000000",
    "amount": 9.9,
    "qrCode": "https://qr.alipay.com/...",
    "expireTime": "2026-01-14T11:00:00.000Z"
  }
}
```

### 3.2 支付回调 - 支付宝

**接口**: `POST /api/payment/alipay/notify`

**参数** (支付宝POST):
```
out_trade_no: "order_1705230000000"
trade_status: "TRADE_SUCCESS"
total_amount: "9.90"
buyer_id: "2088xxx"
sign: "..."
```

**响应**:
```
success
```

### 3.3 支付回调 - 微信

**接口**: `POST /api/payment/wechat/notify`

**参数** (微信XML):
```xml
<xml>
  <return_code>SUCCESS</return_code>
  <out_trade_no>order_1705230000000</out_trade_no>
  <total_fee>990</total_fee>
</xml>
```

**响应**:
```xml
<xml>
  <return_code>SUCCESS</return_code>
  <return_msg>OK</return_msg>
</xml>
```

### 3.4 验证支付状态

**接口**: `GET /api/payment/verify?orderId={orderId}`

**请求**:
```bash
curl "https://your-domain.com/api/payment/verify?orderId=order_123"
```

**响应**:
```json
{
  "success": true,
  "data": {
    "orderId": "order_123",
    "status": "completed",
    "paidAt": "2026-01-14T10:30:00.000Z"
  }
}
```

---

## 4. 分销API

### 4.1 获取邀请码

**接口**: `GET /api/referral/code`

**认证**: 需要用户登录

**请求**:
```bash
curl https://your-domain.com/api/referral/code \
  -H "Cookie: session_id=xxx"
```

**响应**:
```json
{
  "success": true,
  "data": {
    "code": "REF1705230",
    "url": "https://your-domain.com?ref=REF1705230"
  }
}
```

### 4.2 绑定推荐关系

**接口**: `POST /api/referral/bind`

**请求**:
```bash
curl -X POST https://your-domain.com/api/referral/bind \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "referralCode": "REF1705229"
  }'
```

**响应**:
```json
{
  "success": true,
  "message": "绑定成功"
}
```

### 4.3 查询收益

**接口**: `GET /api/referral/earnings`

**认证**: 需要用户登录

**请求**:
```bash
curl https://your-domain.com/api/referral/earnings \
  -H "Cookie: session_id=xxx"
```

**响应**:
```json
{
  "success": true,
  "data": {
    "total": 89.10,
    "pending": 35.64,
    "withdrawn": 53.46,
    "referralCount": 10,
    "recentOrders": [
      {
        "userId": "user_456",
        "amount": 9.9,
        "earnings": 8.91,
        "createdAt": "2026-01-14T10:00:00.000Z"
      }
    ]
  }
}
```

### 4.4 申请提现

**接口**: `POST /api/referral/withdraw`

**认证**: 需要用户登录

**请求**:
```bash
curl -X POST https://your-domain.com/api/referral/withdraw \
  -H "Content-Type: application/json" \
  -H "Cookie: session_id=xxx" \
  -d '{
    "amount": 50,
    "method": "alipay",
    "account": "13800138000",
    "name": "王**"
  }'
```

**响应**:
```json
{
  "success": true,
  "data": {
    "withdrawalId": "wd_123",
    "amount": 50,
    "status": "pending",
    "estimatedTime": "1-3个工作日"
  }
}
```

---

## 5. 用户API

### 5.1 登录

**接口**: `POST /api/user/login`

**请求**:
```bash
curl -X POST https://your-domain.com/api/user/login \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "13800138000",
    "code": "123456"
  }'
```

**响应**:
```json
{
  "success": true,
  "data": {
    "user": {
      "id": "user_123",
      "phone": "****8000",
      "nickname": "创业者小王",
      "hasFullBook": false
    },
    "token": "session_token_xxx"
  }
}
```

### 5.2 注册

**接口**: `POST /api/user/register`

**请求**:
```bash
curl -X POST https://your-domain.com/api/user/register \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "13800138000",
    "nickname": "创业者小王",
    "referralCode": "REF1705229"
  }'
```

**响应**:
```json
{
  "success": true,
  "data": {
    "user": {
      "id": "user_1705230000000",
      "phone": "****8000",
      "nickname": "创业者小王",
      "referralCode": "REF1705230"
    },
    "token": "session_token_xxx"
  }
}
```

---

## 6. 匹配API

### 6.1 寻找匹配

**接口**: `POST /api/match/find`

**认证**: 需要用户登录

**请求**:
```bash
curl -X POST https://your-domain.com/api/match/find \
  -H "Content-Type: application/json" \
  -H "Cookie: session_id=xxx" \
  -d '{
    "mbti": "INTP",
    "interests": ["私域运营", "内容创业"]
  }'
```

**响应**:
```json
{
  "success": true,
  "data": {
    "matchId": "match_123",
    "user": {
      "nickname": "创业者小李",
      "mbti": "ENTJ",
      "interests": ["私域运营", "供应链"],
      "matchRate": 85
    },
    "commonInterests": ["私域运营"]
  }
}
```

### 6.2 匹配历史

**接口**: `GET /api/match/history`

**认证**: 需要用户登录

**响应**:
```json
{
  "success": true,
  "data": [
    {
      "matchId": "match_123",
      "nickname": "创业者小李",
      "matchRate": 85,
      "createdAt": "2026-01-14T10:00:00.000Z"
    }
  ]
}
```

---

## 7. 管理后台API

### 7.1 概览数据

**接口**: `GET /api/admin`

**认证**: 管理员Token

**响应**:
```json
{
  "success": true,
  "data": {
    "content": {
      "totalChapters": 65,
      "totalWords": 120000,
      "publishedChapters": 60,
      "draftChapters": 5
    },
    "payment": {
      "totalRevenue": 12800.50,
      "todayRevenue": 560.00,
      "totalOrders": 128,
      "todayOrders": 12
    },
    "referral": {
      "totalReferrers": 45,
      "activeReferrers": 28,
      "totalCommission": 11520.45
    },
    "users": {
      "totalUsers": 1200,
      "purchasedUsers": 128,
      "activeUsers": 456
    }
  }
}
```

### 7.2 内容管理

**接口**: `GET /api/admin/content`

**接口**: `POST /api/admin/content` - 创建

**接口**: `PUT /api/admin/content/:id` - 更新

**接口**: `DELETE /api/admin/content/:id` - 删除

### 7.3 订单管理

**接口**: `GET /api/admin/payment?status=completed&page=1&limit=20`

**响应**:
```json
{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "order_123",
        "userId": "user_123",
        "amount": 9.9,
        "status": "completed",
        "createdAt": "2026-01-14T10:00:00.000Z"
      }
    ],
    "total": 128,
    "page": 1,
    "limit": 20
  }
}
```

---

## 8. 错误码规范

### 8.1 HTTP状态码

| 状态码 | 含义 | 使用场景 |
|--------|------|----------|
| 200 | 成功 | 请求成功 |
| 201 | 创建成功 | 资源创建成功 |
| 400 | 请求错误 | 参数错误 |
| 401 | 未授权 | 需要登录 |
| 403 | 禁止访问 | 权限不足 |
| 404 | 未找到 | 资源不存在 |
| 500 | 服务器错误 | 内部错误 |

### 8.2 业务错误码

```typescript
enum ErrorCode {
  // 用户相关
  USER_NOT_FOUND = 1001,
  USER_ALREADY_EXISTS = 1002,
  INVALID_PHONE = 1003,
  INVALID_CODE = 1004,
  
  // 支付相关
  ORDER_NOT_FOUND = 2001,
  PAYMENT_FAILED = 2002,
  INSUFFICIENT_BALANCE = 2003,
  
  // 分销相关
  INVALID_REFERRAL_CODE = 3001,
  WITHDRAWAL_FAILED = 3002,
  INSUFFICIENT_EARNINGS = 3003,
  
  // 内容相关
  CHAPTER_NOT_FOUND = 4001,
  CHAPTER_NOT_PURCHASED = 4002,
}
```

**错误响应格式**:
```json
{
  "success": false,
  "error": {
    "code": 1001,
    "message": "用户不存在",
    "details": "用户ID: user_123"
  }
}
```

---

## 9. 接口性能优化

### 9.1 缓存策略

**内容缓存**:
```typescript
// 章节内容缓存1小时
res.setHeader('Cache-Control', 'public, max-age=3600')

// 章节列表缓存10分钟
res.setHeader('Cache-Control', 'public, max-age=600')
```

**ETag**:
```typescript
const etag = generateETag(content)
res.setHeader('ETag', etag)

if (req.headers['if-none-match'] === etag) {
  return res.status(304).end()
}
```

### 9.2 限流策略

```typescript
// 接口限流: 100次/分钟
const limiter = {
  '/api/book/all-chapters': { limit: 100, window: 60 },
  '/api/payment/create-order': { limit: 10, window: 60 },
  '/api/admin/*': { limit: 1000, window: 60 }
}
```

---

**总结**: API设计遵循RESTful规范,响应格式统一,错误处理清晰。所有接口都有明确的认证要求和错误处理。核心功能包括内容获取、支付流程、分销系统、用户管理、匹配功能。