soul-yongping/开发文档/5、接口/接口定义规范.md

# 接口定义规范

**我是卡若。**

这个文档是后端API的完整说明书。所有接口遵循RESTful规范,返回JSON格式。

---

## 一、接口规范

### 1.1 基础URL

**开发环境**:
\`\`\`
http://localhost:3000/api
http://localhost:3001/api
\`\`\`

**生产环境**:
\`\`\`
http://kr-soul.lytiao.com/api
\`\`\`

### 1.2 统一返回格式

**成功响应**:
\`\`\`json
{
  "code": 0,
  "message": "成功",
  "data": {
    // 实际数据
  }
}
\`\`\`

**错误响应**:
\`\`\`json
{
  "code": 400,
  "message": "错误描述",
  "error": "详细错误信息"
}
\`\`\`

### 1.3 HTTP状态码

\`\`\`
200 - 成功
201 - 创建成功
400 - 请求参数错误
401 - 未授权
403 - 禁止访问
404 - 资源不存在
500 - 服务器错误
\`\`\`

### 1.4 认证方式

**用户Token**:
\`\`\`
Header: Authorization: Bearer <token>
\`\`\`

**管理员Token**:
\`\`\`
Header: Authorization: Bearer admin-token-secret
\`\`\`

---

## 二、书籍内容接口

### 2.1 获取书籍结构

**接口**: `GET /api/book/structure`

**描述**: 获取完整的书籍目录结构

**请求参数**: 无

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

---

### 2.2 获取最新章节

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

**描述**: 获取最新发布的章节列表

**请求参数**:
\`\`\`
limit: number (可选,默认10)
\`\`\`

**响应示例**:
\`\`\`json
{
  "code": 0,
  "message": "成功",
  "data": {
    "chapters": [
      {
        "id": "11.5",
        "title": "社会分层的最终逻辑",
        "partTitle": "真实的社会",
        "chapterTitle": "中国社会商业生态的未来",
        "isFree": false,
        "price": 1,
        "createdAt": "2025-01-14T10:30:00Z"
      }
    ]
  }
}
\`\`\`

---

### 2.3 获取章节内容

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

**描述**: 获取指定章节的完整内容

**请求参数**:
\`\`\`
id: string (章节ID,如"1.1")
userId?: string (可选,用于权限检查)
\`\`\`

**响应示例**:
\`\`\`json
{
  "code": 0,
  "message": "成功",
  "data": {
    "section": {
      "id": "1.1",
      "title": "自行车荷总:一个行业做到极致是什么样",
      "content": "# 自行车荷总\n\n...",
      "isFree": true,
      "price": 1,
      "isPurchased": false,
      "createdAt": "2025-01-01T00:00:00Z"
    }
  }
}
\`\`\`

**错误响应** (未购买):
\`\`\`json
{
  "code": 403,
  "message": "需要购买此章节",
  "data": {
    "needPurchase": true,
    "price": 1,
    "sectionId": "1.1"
  }
}
\`\`\`

---

### 2.4 根据路径获取内容

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

**描述**: 根据文件路径获取Markdown内容

**请求参数**:
\`\`\`
path: string (文件路径,如"book/序言.md")
\`\`\`

**响应示例**:
\`\`\`json
{
  "code": 0,
  "message": "成功",
  "data": {
    "content": "# 序言\n\n为什么我每天早上6点在Soul开播?..."
  }
}
\`\`\`

---

## 三、支付接口

### 3.1 创建订单

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

**描述**: 创建支付订单

**请求体**:
\`\`\`json
{
  "userId": "user_123",
  "type": "section",  // "section" | "fullbook"
  "sectionId": "1.1",
  "sectionTitle": "自行车荷总...",
  "amount": 1.00,
  "paymentMethod": "wechat",  // "wechat" | "alipay" | "usdt" | "paypal"
  "referralCode": "REFXXXX"  // 可选
}
\`\`\`

**响应示例**:
\`\`\`json
{
  "code": 0,
  "message": "订单创建成功",
  "data": {
    "orderId": "ORDER_1705200000_abc123",
    "userId": "user_123",
    "type": "section",
    "amount": 1.00,
    "paymentMethod": "wechat",
    "status": "pending",
    "createdAt": "2025-01-14T12:00:00Z",
    "expireAt": "2025-01-14T12:30:00Z",
    "paymentData": {
      // 微信支付参数
      "appId": "wx432c93e275548671",
      "timeStamp": "1705200000",
      "nonceStr": "abc123",
      "package": "prepay_id=wx123456789",
      "signType": "MD5",
      "paySign": "XXXXX"
    }
  }
}
\`\`\`

---

### 3.2 微信支付回调

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

**描述**: 微信支付异步通知接口(仅供微信服务器调用)

**请求体**: XML格式
\`\`\`xml
<xml>
  <return_code><![CDATA[SUCCESS]]></return_code>
  <result_code><![CDATA[SUCCESS]]></result_code>
  <out_trade_no><![CDATA[ORDER_xxx]]></out_trade_no>
  <total_fee>100</total_fee>
  <openid><![CDATA[xxxxx]]></openid>
</xml>
\`\`\`

**响应**: XML格式
\`\`\`xml
<xml>
  <return_code><![CDATA[SUCCESS]]></return_code>
  <return_msg><![CDATA[OK]]></return_msg>
</xml>
\`\`\`

---

### 3.3 支付宝回调

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

**描述**: 支付宝异步通知接口

**请求体**: Form表单格式
\`\`\`
out_trade_no=ORDER_xxx
trade_status=TRADE_SUCCESS
buyer_id=2088xxx
total_amount=1.00
sign=xxxxx
\`\`\`

**响应**: 纯文本
\`\`\`
success
\`\`\`

---

### 3.4 验证支付状态

**接口**: `POST /api/payment/verify`

**描述**: 验证订单支付状态

**请求体**:
\`\`\`json
{
  "orderId": "ORDER_xxx"
}
\`\`\`

**响应示例**:
\`\`\`json
{
  "code": 0,
  "message": "成功",
  "data": {
    "orderId": "ORDER_xxx",
    "status": "completed",  // "pending" | "completed" | "failed"
    "paidAt": "2025-01-14T12:05:00Z"
  }
}
\`\`\`

---

### 3.5 查询订单列表

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

**描述**: 查询用户订单列表

**请求参数**:
\`\`\`
userId: string
status?: string (可选,筛选状态)
page?: number (可选,默认1)
limit?: number (可选,默认10)
\`\`\`

**响应示例**:
\`\`\`json
{
  "code": 0,
  "message": "成功",
  "data": {
    "orders": [
      {
        "orderId": "ORDER_xxx",
        "type": "section",
        "sectionTitle": "自行车荷总...",
        "amount": 1.00,
        "status": "completed",
        "createdAt": "2025-01-14T12:00:00Z"
      }
    ],
    "total": 25,
    "page": 1,
    "limit": 10
  }
}
\`\`\`

---

## 四、用户接口

### 4.1 微信登录

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

**描述**: 微信一键登录

**请求体**:
\`\`\`json
{
  "code": "wx_login_code",
  "referralCode": "REFXXXX"  // 可选
}
\`\`\`

**响应示例**:
\`\`\`json
{
  "code": 0,
  "message": "登录成功",
  "data": {
    "token": "jwt_token_xxx",
    "user": {
      "id": "user_123",
      "nickname": "卡若",
      "phone": "158****2661",
      "referralCode": "REFABC123",
      "referredBy": "REFXXXX",
      "createdAt": "2025-01-14T12:00:00Z"
    }
  }
}
\`\`\`

---

### 4.2 获取用户统计

**接口**: `GET /api/user/stats`

**描述**: 获取用户阅读统计数据

**请求参数**:
\`\`\`
userId: string
\`\`\`

**响应示例**:
\`\`\`json
{
  "code": 0,
  "message": "成功",
  "data": {
    "purchasedSections": 12,
    "hasFullBook": false,
    "readingTime": 12480,  // 秒
    "readingProgress": 45,  // 百分比
    "lastReadSection": "3.2",
    "lastReadAt": "2025-01-14T12:00:00Z"
  }
}
\`\`\`

---

### 4.3 记录阅读进度

**接口**: `POST /api/user/read-progress`

**描述**: 记录用户阅读进度

**请求体**:
\`\`\`json
{
  "userId": "user_123",
  "sectionId": "3.2",
  "progress": 68,  // 百分比
  "readingTime": 180  // 本次阅读时长(秒)
}
\`\`\`

**响应示例**:
\`\`\`json
{
  "code": 0,
  "message": "记录成功"
}
\`\`\`

---

## 五、分销接口

### 5.1 获取收益数据

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

**描述**: 获取推广收益详情

**请求参数**:
\`\`\`
userId: string
\`\`\`

**响应示例**:
\`\`\`json
{
  "code": 0,
  "message": "成功",
  "data": {
    "totalEarnings": 256.80,
    "pendingEarnings": 128.90,
    "withdrawnEarnings": 127.90,
    "referralCount": 28,
    "todayEarnings": 12.60,
    "thisMonthEarnings": 156.80,
    "earnings": [
      {
        "orderId": "ORDER_xxx",
        "userId": "user_456",
        "userNickname": "张三",
        "amount": 1.00,
        "commission": 0.90,
        "createdAt": "2025-01-14T10:00:00Z"
      }
    ]
  }
}
\`\`\`

---

### 5.2 获取推广统计

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

**描述**: 获取推广数据统计

**请求参数**:
\`\`\`
userId: string
\`\`\`

**响应示例**:
\`\`\`json
{
  "code": 0,
  "message": "成功",
  "data": {
    "referralCount": 28,
    "conversionCount": 12,  // 已购买人数
    "conversionRate": 42.86,  // 转化率
    "avgOrderValue": 5.50,  // 平均订单金额
    "topReferrals": [
      {
        "userId": "user_456",
        "nickname": "张三",
        "totalPurchase": 19.80,
        "commission": 17.82
      }
    ]
  }
}
\`\`\`

---

### 5.3 申请提现

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

**描述**: 申请佣金提现

**请求体**:
\`\`\`json
{
  "userId": "user_123",
  "amount": 100.00,
  "method": "wechat",  // "wechat" | "alipay"
  "account": "微信号或支付宝账号",
  "name": "真实姓名"
}
\`\`\`

**响应示例**:
\`\`\`json
{
  "code": 0,
  "message": "提现申请已提交",
  "data": {
    "withdrawalId": "WD_xxx",
    "amount": 100.00,
    "status": "pending",
    "createdAt": "2025-01-14T12:00:00Z"
  }
}
\`\`\`

---

## 六、后台管理接口

### 6.1 管理员登录

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

**描述**: 管理员登录

**请求体**:
\`\`\`json
{
  "username": "admin",
  "password": "admin123"
}
\`\`\`

**响应示例**:
\`\`\`json
{
  "success": true,
  "token": "admin-token-secret",
  "user": {
    "id": "admin",
    "username": "admin",
    "role": "admin",
    "name": "卡若"
  }
}
\`\`\`

---

### 6.2 获取后台概览

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

**描述**: 获取后台概览数据

**请求头**:
\`\`\`
Authorization: Bearer admin-token-secret
\`\`\`

**响应示例**:
\`\`\`json
{
  "content": {
    "totalChapters": 65,
    "totalWords": 120000,
    "publishedChapters": 60,
    "draftChapters": 5,
    "lastUpdate": "2025-01-14T12:00:00Z"
  },
  "payment": {
    "totalRevenue": 12800.50,
    "todayRevenue": 560.00,
    "totalOrders": 128,
    "todayOrders": 12,
    "averagePrice": 100.00
  },
  "referral": {
    "totalReferrers": 45,
    "activeReferrers": 28,
    "totalCommission": 11520.45,
    "paidCommission": 8500.00,
    "pendingCommission": 3020.45
  },
  "users": {
    "totalUsers": 1200,
    "purchasedUsers": 128,
    "activeUsers": 456,
    "todayNewUsers": 23
  }
}
\`\`\`

---

### 6.3 内容管理接口

**① 章节列表**:
\`\`\`
GET /api/admin/content
\`\`\`

**② 创建章节**:
\`\`\`
POST /api/admin/content
{
  "title": "章节标题",
  "content": "章节内容",
  "price": 1,
  "isFree": false
}
\`\`\`

**③ 编辑章节**:
\`\`\`
PUT /api/admin/content/:id
{
  "title": "新标题",
  "content": "新内容"
}
\`\`\`

**④ 删除章节**:
\`\`\`
DELETE /api/admin/content/:id
\`\`\`

---

### 6.4 付费管理接口

**① 订单列表**:
\`\`\`
GET /api/admin/payment?status=completed&page=1&limit=20
\`\`\`

**② 收益统计**:
\`\`\`
GET /api/admin/payment/stats?startDate=2025-01-01&endDate=2025-01-31
\`\`\`

**③ 退款处理**:
\`\`\`
POST /api/admin/payment/refund
{
  "orderId": "ORDER_xxx",
  "reason": "用户申请退款"
}
\`\`\`

---

### 6.5 分销管理接口

**① 推广者列表**:
\`\`\`
GET /api/admin/referral?sortBy=earnings&order=desc&page=1
\`\`\`

**② 佣金结算**:
\`\`\`
POST /api/admin/referral/settle
{
  "userId": "user_123",
  "amount": 100.00,
  "method": "wechat",
  "account": "微信号"
}
\`\`\`

**③ 推广数据统计**:
\`\`\`
GET /api/admin/referral/stats?period=month
\`\`\`

---

## 七、实时同步接口

### 7.1 手动同步

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

**描述**: 手动触发内容同步

**请求体**:
\`\`\`json
{
  "force": true  // 是否强制全量同步
}
\`\`\`

**响应示例**:
\`\`\`json
{
  "code": 0,
  "message": "同步成功",
  "data": {
    "addedCount": 5,
    "updatedCount": 8,
    "deletedCount": 1,
    "totalCount": 65,
    "syncAt": "2025-01-14T12:00:00Z"
  }
}
\`\`\`

---

## 八、配置接口

### 8.1 获取系统配置

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

**描述**: 获取系统配置信息(支付方式、营销配置等)

**响应示例**:
\`\`\`json
{
  "paymentMethods": {
    "wechat": {
      "enabled": true,
      "qrCode": "/images/wechat-pay.png",
      "account": "卡若",
      "appId": "wx432c93e275548671"
    },
    "alipay": {
      "enabled": true,
      "qrCode": "/images/alipay.png",
      "account": "卡若"
    },
    "usdt": {
      "enabled": true,
      "network": "TRC20",
      "address": "TWeq9xxxxxxxxxxxxxxxxxxxx",
      "exchangeRate": 7.2
    }
  },
  "marketing": {
    "partyGroup": {
      "url": "https://soul.cn/party",
      "qrCode": "/images/party-group-qr.png"
    },
    "banner": {
      "text": "每日早上6-9点，Soul派对房不见不散",
      "visible": true
    }
  },
  "authorInfo": {
    "name": "卡若",
    "description": "私域运营与技术公司主理人",
    "liveTime": "06:00-09:00",
    "platform": "Soul"
  }
}
\`\`\`

---

## 九、接口测试示例

### 9.1 使用cURL测试

**创建订单**:
\`\`\`bash
curl -X POST http://localhost:3001/api/payment/create-order \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "type": "section",
    "sectionId": "1.1",
    "sectionTitle": "测试章节",
    "amount": 1.00,
    "paymentMethod": "wechat"
  }'
\`\`\`

**获取章节内容**:
\`\`\`bash
curl http://localhost:3001/api/book/chapter/1.1
\`\`\`

**后台登录**:
\`\`\`bash
curl -X POST http://localhost:3001/api/admin \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'
\`\`\`

---

## 十、错误码说明

\`\`\`
0     - 成功
400   - 请求参数错误
401   - 未授权(未登录)
403   - 禁止访问(权限不足或内容未购买)
404   - 资源不存在
500   - 服务器内部错误

1001  - 用户不存在
1002  - 验证码错误
1003  - 邀请码无效

2001  - 订单不存在
2002  - 订单已过期
2003  - 订单已支付
2004  - 支付失败
2005  - 签名验证失败

3001  - 章节不存在
3002  - 章节需要购买
3003  - 章节已购买

4001  - 提现金额不足
4002  - 提现申请失败
4003  - 提现记录不存在
\`\`\`

---

**总结**: 所有接口都经过生产环境验证,可直接使用。接口设计遵循RESTful规范,易于理解和调用。

---

**更新时间**: 2025年1月14日  
**负责人**: 卡若  
**API版本**: v1.0