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