2.6 KiB
2.6 KiB
API接口文档 - Soul创业实验项目
API风格: RESTful | 版本: v1.0 | 基础路径:
/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
- GET /api/book/all-chapters — 获取所有章节
- GET /api/book/chapter/:id — 获取单章内容
- POST /api/book/sync — 同步章节（需管理员Token）
3. 支付API
- POST /api/payment/create-order — 创建订单（参数：userId, type, sectionId?, amount, paymentMethod）
- POST /api/payment/alipay/notify — 支付宝回调
- POST /api/payment/wechat/notify — 微信回调
- GET /api/payment/verify?orderId= — 验证支付状态
4. 分销API
- GET /api/referral/code — 获取邀请码
- POST /api/referral/bind — 绑定推荐关系
- GET /api/referral/earnings — 查询收益
- POST /api/referral/withdraw — 申请提现
5. 用户API
- POST /api/user/login — 登录（phone, code）
- POST /api/user/register — 注册（phone, nickname, referralCode?）
6. 匹配API
- POST /api/match/find — 寻找匹配
- GET /api/match/history — 匹配历史
7. 管理后台API
- GET /api/admin — 概览数据
- GET/POST/PUT/DELETE /api/admin/content — 内容管理
- GET /api/admin/payment — 订单管理（?status=completed&page=1&limit=20）
8. 错误码规范
| 状态码 | 含义 |
|---|---|
| 200/201 | 成功 |
| 400 | 请求错误 |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 未找到 |
| 500 | 服务器错误 |
错误响应: { "success": false, "error": { "code": 1001, "message": "...", "details": "..." } }
9. 性能与限流
- 内容缓存：章节 1h、列表 10min；支持 ETag 304
- 限流：内容 100/分钟、下单 10/分钟、管理端 1000/分钟