fnvtk/soul-yongping

Fork 0

Files

乘风 7b2123dfe5 打好基版

2026-02-09 15:09:29 +08:00

15 KiB

Raw Blame History

接口定义规范

我是卡若。

这个文档是后端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: ``` 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 <return_code></return_code> <result_code></result_code> <out_trade_no></out_trade_no> <total_fee>100</total_fee> ```

响应: XML格式 ```xml <return_code></return_code> <return_msg></return_msg> ```

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

15 KiB Raw Blame History Unescape Escape

接口定义规范

一、接口规范

1.1 基础URL

1.2 统一返回格式

1.3 HTTP状态码

1.4 认证方式

二、书籍内容接口

2.1 获取书籍结构

2.2 获取最新章节

2.3 获取章节内容

2.4 根据路径获取内容

三、支付接口

3.1 创建订单

3.2 微信支付回调

3.3 支付宝回调

3.4 验证支付状态

3.5 查询订单列表

四、用户接口

4.1 微信登录

4.2 获取用户统计

4.3 记录阅读进度

五、分销接口

5.1 获取收益数据

5.2 获取推广统计

5.3 申请提现

六、后台管理接口

6.1 管理员登录

6.2 获取后台概览

6.3 内容管理接口

6.4 付费管理接口

6.5 分销管理接口

七、实时同步接口

7.1 手动同步

八、配置接口

8.1 获取系统配置

九、接口测试示例

9.1 使用cURL测试

十、错误码说明

15 KiB

Raw Blame History