Files

Made-with: Cursor

2026-03-07 22:58:43 +08:00

11 KiB

Raw Blame History

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

请求:

curl https://your-domain.com/api/book/all-chapters

响应:

{
  "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

请求:

curl https://your-domain.com/api/book/chapter/1.1

响应:

{
  "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

请求:

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

响应:

{
  "success": true,
  "message": "同步完成",
  "synced": 64,
  "updated": 3
}

3. 支付API

3.1 创建订单

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

请求:

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"
  }'

参数:

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

响应:

{
  "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>
  <return_code>SUCCESS</return_code>
  <out_trade_no>order_1705230000000</out_trade_no>
  <total_fee>990</total_fee>
</xml>

响应:

<xml>
  <return_code>SUCCESS</return_code>
  <return_msg>OK</return_msg>
</xml>

3.4 验证支付状态

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

请求:

curl "https://your-domain.com/api/payment/verify?orderId=order_123"

响应:

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

4. 分销API

4.1 获取邀请码

接口: GET /api/referral/code

认证: 需要用户登录

请求:

curl https://your-domain.com/api/referral/code \
  -H "Cookie: session_id=xxx"

响应:

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

4.2 绑定推荐关系

接口: POST /api/referral/bind

请求:

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

响应:

{
  "success": true,
  "message": "绑定成功"
}

4.3 查询收益

接口: GET /api/referral/earnings

认证: 需要用户登录

请求:

curl https://your-domain.com/api/referral/earnings \
  -H "Cookie: session_id=xxx"

响应:

{
  "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

认证: 需要用户登录

请求:

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": "王**"
  }'

响应:

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

5. 用户API

5.1 登录

接口: POST /api/user/login

请求:

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

响应:

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

5.2 注册

接口: POST /api/user/register

请求:

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

响应:

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

6. 匹配API

6.1 寻找匹配

接口: POST /api/match/find

认证: 需要用户登录

请求:

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

响应:

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

6.2 匹配历史

接口: GET /api/match/history

认证: 需要用户登录

响应:

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

7. 管理后台API

7.1 概览数据

接口: GET /api/admin

认证: 管理员Token

响应:

{
  "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

响应:

{
  "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 业务错误码

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,
}

错误响应格式:

{
  "success": false,
  "error": {
    "code": 1001,
    "message": "用户不存在",
    "details": "用户ID: user_123"
  }
}

9. 接口性能优化

9.1 缓存策略

内容缓存:

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

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

ETag:

const etag = generateETag(content)
res.setHeader('ETag', etag)

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

9.2 限流策略

// 接口限流: 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规范,响应格式统一,错误处理清晰。所有接口都有明确的认证要求和错误处理。核心功能包括内容获取、支付流程、分销系统、用户管理、匹配功能。

11 KiB Raw Blame History Unescape Escape

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

1. 接口总览

1.1 接口分类

1.2 认证方式

2. 书籍内容API

2.1 获取所有章节

2.2 获取单章内容

2.3 同步章节

3. 支付API

3.1 创建订单

3.2 支付回调 - 支付宝

3.3 支付回调 - 微信

3.4 验证支付状态

4. 分销API

4.1 获取邀请码

4.2 绑定推荐关系

4.3 查询收益

4.4 申请提现

5. 用户API

5.1 登录

5.2 注册

6. 匹配API

6.1 寻找匹配

6.2 匹配历史

7. 管理后台API

7.1 概览数据

7.2 内容管理

7.3 订单管理

8. 错误码规范

8.1 HTTP状态码

8.2 业务错误码

9. 接口性能优化

9.1 缓存策略

9.2 限流策略

11 KiB

Raw Blame History