# 接口定义规范 **我是卡若。** 这个文档是后端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 100 \`\`\` **响应**: XML格式 \`\`\`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