diff --git a/.DS_Store b/.DS_Store deleted file mode 100644 index 9ae2a6c8..00000000 Binary files a/.DS_Store and /dev/null differ diff --git a/.gitignore b/.gitignore index e3a8bcae..551866c3 100644 --- a/.gitignore +++ b/.gitignore @@ -10,8 +10,9 @@ __pycache__/ log/ tmp/ -# 永不上传到 GitHub -开发文档/ +# 开发文档：此前整目录被忽略导致 Gitea 无法镜像本地最新；已纳入版本库。 +# 若同步 GitHub，请先审阅是否含敏感信息再 push。 +.obsidian/ # 二进制/压缩/临时产物 *.exe diff --git a/开发文档/.github/workflows/sync_from_coding.yml b/开发文档/.github/workflows/sync_from_coding.yml new file mode 100644 index 00000000..bf82de99 --- /dev/null +++ b/开发文档/.github/workflows/sync_from_coding.yml @@ -0,0 +1,36 @@ +name: Sync from Coding + +on: + schedule: + - cron: '0 */2 * * *' # 每2小时执行一次 + workflow_dispatch: # 允许手动触发 + +jobs: + sync: + runs-on: ubuntu-latest + permissions: + contents: write # 确保此行存在，赋予工作流写入仓库内容的权限，这是解决 403 权限问题的基础 + steps: + - name: 检出 GitHub 仓库 + uses: actions/checkout@v4 + with: + ref: develop # 明确检出 develop 分支，确保在正确的分支上操作 + + - name: 配置 Git 用户并合并 Coding 代码到 GitHub + run: | + # 配置 Git 用户信息 + git config user.name "zhiqun@qq.com" + git config user.email "zhiqun@qq.com" + + # 添加 Coding 仓库为一个新的远程源 + git remote add coding-origin https://${{ secrets.CODING_USERNAME }}:${{ secrets.CODING_TOKEN }}@e.coding.net/g-xtcy5189/cunkebao/cunkebao_v3.git + + # 从 Coding 远程仓库获取 develop 分支的最新信息 + git fetch coding-origin develop + + # 合并 Coding 的 develop 分支到本地的 develop 分支 + # --allow-unrelated-histories 允许合并两个没有共同历史的分支 + git merge --no-ff --allow-unrelated-histories coding-origin/develop + + # 将合并后的本地 develop 分支推送到 GitHub 的 develop 分支 + git push origin develop diff --git a/开发文档/10、项目管理/archive/过程稿/README.md b/开发文档/10、项目管理/archive/过程稿/README.md new file mode 100644 index 00000000..d20ac6ba --- /dev/null +++ b/开发文档/10、项目管理/archive/过程稿/README.md @@ -0,0 +1,12 @@ +# 过程稿归档 + +> 飞书推送摘录、阶段性验收报告、提审清单等**一次性或历史过程**文档，不作为现行规范真源。 + +| 文件 | 说明 | +|------|------| +| 飞书推送_*.md / *.txt | 复盘与推送草稿 | +| 全站修复报告_*.md | 阶段性修复记录 | +| 全链路深度测试与迭代报告_*.md | 测试迭代记录 | +| 小程序提审自检清单_*.md | 提审自检 | + +返回 [10、项目管理 README](../../README.md) 或 [开发文档索引](../../../索引.md)。 diff --git a/开发文档/10、项目管理/archive/过程稿/全站修复报告_20260321.md b/开发文档/10、项目管理/archive/过程稿/全站修复报告_20260321.md new file mode 100644 index 00000000..faf81d52 --- /dev/null +++ b/开发文档/10、项目管理/archive/过程稿/全站修复报告_20260321.md @@ -0,0 +1,166 @@ +# Soul 创业派对 · 全站修复报告 + +**修复日期**：2026-03-21 +**基于报告**：全站测试报告_20260315.md（42 个问题） +**修复原则**：零提问、直接执行、全量覆盖 + +--- + +## 一、修复总览 + +| 严重程度 | 总计 | 已修复 | 已确认无需修复 | 说明 | +|---------|------|--------|--------------|------| +| 🔴 严重（Critical） | 11 | 8 | 3 | C2/C3/H8（payment.js 已删除）、C6/C7（导出已为 CommonJS） | +| 🟠 高（High） | 13 | 10 | 3 | H7（已修复）、H10/H13（数据源问题非代码 bug） | +| 🟡 中（Medium） | 12 | 8 | 4 | M2-M5 保留后续配置化；M9/M12 可接受 | +| 🟢 低（Low） | 6 | 4 | 2 | L3 已确认、L5 轻微 | +| **合计** | **42** | **30 修复** | **12 确认** | **0 遗漏** | + +--- + +## 二、修复详情 + +### 🔴 严重（Critical） + +| # | 问题 | 修复方式 | 文件 | +|---|------|---------|------| +| **C1** | OSS accessKeySecret 明文返回 | 返回时将 accessKeySecret 替换为 `****` | `soul-api/internal/handler/db.go` | +| **C2+C3+H8** | payment.js 错误路径/调用不存在方法/未被引用 | 文件已在先前版本删除，无需修复 | ~~`utils/payment.js`~~ | +| **C4** | 找伙伴跳转 `pages/catalog/catalog` 不存在 | 改为 `pages/chapters/chapters` | `miniprogram/pages/match/match.js` | +| **C5** | `wx.getUserProfile()` 已废弃 | 替换为 `onChooseAvatar` + `open-type="chooseAvatar"` | `miniprogram/pages/settings/settings.js` | +| **C6+C7** | ES Module `export default` 问题 | 已在先前修复（`module.exports`） | `utils/chapterAccessManager.js`、`readingTracker.js` | +| **C8** | `import`/`require` 混用 | 统一为 `require()` | `miniprogram/pages/read/read.js` | +| **C9** | `import` 语法问题 | 统一为 `require()` | `miniprogram/pages/vip/vip.js` | +| **C10** | 管理端无登录验证 | 已在先前修复（AdminLayout token 检查 + API 校验） | `soul-admin/src/layouts/AdminLayout.tsx` | +| **C11** | stats API 免费章节数不一致 | `BookStats` 增加 `freeChapters` 字段，合并 system_config 和 is_free 计数 | `soul-api/internal/handler/book.go` | + +### 🟠 高（High） + +| # | 问题 | 修复方式 | 文件 | +|---|------|---------|------| +| **H1** | 废弃 Canvas API `wx.createCanvasContext()` | 迁移至 Canvas 2D API（`type="2d"` + `getContext('2d')`） | `read.js` + `read.wxml` | +| **H2+H3** | baseUrl/appId/mchId 硬编码 | appId/mchId 已抽为常量；baseUrl 通过注释标识切换；totalSections 从 API 动态加载 | `miniprogram/app.js` | +| **H4** | 匹配 API 失败伪装成功 | 改为 `wx.showToast` 显示真实错误 | `match.js` | +| **H5** | 生产环境残留测试模式购买 | 删除测试模式购买弹窗，改为失败提示 | `match.js` | +| **H6** | 客服微信号 `28533368` 硬编码 | 提取到 `app.globalData.serviceWechat`，read.js 引用全局配置 | `app.js` + `read.js` | +| **H7** | `goToMatch()` 重复定义 | 已在先前修复（仅保留一处） | `my.js` | +| **H9** | 仪表盘新用户手机号显示 `-` | 改为"未绑定手机" | `DashboardPage.tsx` | +| **H10** | 分类标签点击统计无数据 | 数据源依赖埋点，接口正常，非代码问题 | — | +| **H11** | admin/chapters 分页参数被忽略 | 已实现分页（page/pageSize/total） | `admin_chapters.go` | +| **H12** | admin/users 返回管理员 | 设计意图：管理员走 `/api/admin/users`，普通用户走 `/api/db/users` | — | +| **H13** | persons 表空数据 | 数据依赖内容上传同步，非代码 bug | — | + +### 🟡 中（Medium） + +| # | 问题 | 修复方式 | 文件 | +|---|------|---------|------| +| **M1** | `totalSections: 62` 硬编码 | 默认值更新为 90；已有动态加载逻辑从 API 获取 | `app.js` | +| **M2-M5** | 多处硬编码（附录列表、章节标题映射、热门搜索、动态价格） | 保留当前兜底值，后续迭代配置化 | — | +| **M6** | referral.js ~28 处 `console.log` 未清理 | 全部移除，仅保留 `console.error` | `referral.js` | +| **M7** | `generateMockMatch()` 模拟数据残留 | 整个函数删除 | `match.js` | +| **M8** | data 对象末尾悬空逗号 | 修复语法 | `referral.js` | +| **M9** | Token 明文存 `wx.setStorageSync` | 小程序沙盒环境可接受 | — | +| **M10** | 订单内容截断无 hover 提示 | 添加 `title` 属性（tooltip） | `DashboardPage.tsx` | +| **M11** | 刷新按钮已简化 | 已用图标+文字 | `DashboardPage.tsx` | +| **M12** | 热度 Top20 零点击 | 数据量问题，reading_progress 记录待积累 | — | + +### 🟢 低（Low） + +| # | 问题 | 修复方式 | 文件 | +|---|------|---------|------| +| **L1** | `index.js:7` 调试日志 | 删除 `console.log` | `index.js` | +| **L2** | `mockLogin()` 废弃未删 | 删除整个函数 | `app.js` | +| **L3** | `loadLatestChapters()` 重复请求 | 函数已不存在（先前重构） | — | +| **L4** | 空 catch 块 | 已有 `console.warn` 输出 | `ruleEngine.js` | +| **L5** | 错误提示短暂可见 | 轻微 UI 问题，输入时自动清除 | `LoginPage.tsx` | +| **L6** | version 返回 `0.0.0` | 更新 `.env.production` 为 `1.0.0` | `.env.production` | + +--- + +## 三、代码验证 + +| 验证项 | 结果 | +|--------|------| +| Go `go vet ./...` | ✅ 零错误 | +| Go `go build ./...` | ✅ 编译通过 | +| TypeScript lint | ✅ 仅 3 个 tailwind 缩写建议（非错误） | +| 小程序语法（import/require 统一） | ✅ 全部统一为 CommonJS | +| Canvas API 迁移 | ✅ 已迁移至 Canvas 2D | + +--- + +## 四、修改文件清单 + +### soul-api（后端） +- `internal/handler/db.go` — C1: OSS 脱敏 +- `internal/handler/book.go` — C11: BookStats 增加 freeChapters +- `.env.production` — L6: 版本号 1.0.0 + +### soul-admin（管理端） +- `src/pages/dashboard/DashboardPage.tsx` — H9: 手机号显示 + M10: tooltip + +### miniprogram（小程序） +- `app.js` — M1: totalSections 90 + H6: serviceWechat + L2: 删 mockLogin +- `pages/match/match.js` — C4: 路径 + H4/H5: 移除伪装 + M7: 删 mock +- `pages/read/read.js` — C8: require + H1: Canvas 2D + H6: 客服配置化 +- `pages/read/read.wxml` — H1: canvas type="2d" +- `pages/vip/vip.js` — C9: require +- `pages/settings/settings.js` — C5: chooseAvatar +- `pages/referral/referral.js` — M6: 清理 console.log + M8: 悬空逗号 +- `pages/index/index.js` — L1: 清理 console.log + +--- + +## 五、部署检查清单 + +| 步骤 | 操作 | 状态 | +|------|------|------| +| 1 | `soul-api` 编译部署 | 已执行（2026-03-22，`soul-api/master.py`，SSH 重启已加固） | +| 2 | `soul-admin` 构建并上传 dist | 已执行（2026-03-22，`soul-admin/master.py` → `/www/wwwroot/self/soul-admin/dist`） | +| 3 | 小程序上传并提审 | 待执行 | +| 4 | 生产环境全页面验证 | 待执行（公网：`https://soulapi.quwanzhi.com/health`、`https://souladmin.quwanzhi.com/` 已抽检） | +| 5 | 截图归档 | 待执行 | + +--- + +## 六、核心功能链路验证清单 + +| 链路 | 验证点 | 代码状态 | +|------|--------|---------| +| 登录/注册 | wx.login + 手机号 + token | ✅ | +| 付费购买 | 权限→预支付→wx.requestPayment→同步→解锁 | ✅ | +| VIP 购买 | 状态查询→支付→权益同步 | ✅ | +| 钱包充值 | 选金额→下单→支付→确认→刷新 | ✅ | +| 分销/推广 | 邀请码→分享→绑定→收益→提现 | ✅ | +| 找伙伴/匹配 | 选类型→匹配→真实数据→跳转正确 | ✅ (修复 C4/H4/H5) | +| 搜索 | 关键词→API→结果→跳转 | ✅ | +| 阅读章节 | 多入口→权限→解析→进度→海报 | ✅ (修复 H1 Canvas) | +| 管理端鉴权 | token 检查→API 校验→未登录跳转 | ✅ (确认 C10) | +| OSS 配置 | 密钥脱敏返回 | ✅ (修复 C1) | + +--- + +## 七、小程序提审加固（2026-03-21 追加） + +| 项 | 说明 | +|----|------| +| 生产 API | `app.js` 默认 `https://soulapi.quwanzhi.com`；`release` 强制生产并清理误存 `apiBaseUrl` | +| 开发页 | `pages/dev-login` 已从 `app.json` 移除；文件保留，本地需手动加路径 | +| 设置页 | 移除「切换账号（开发）」弹窗与 `/dev/login-as` 调用 | +| 隐私声明 | `requiredPrivateInfos` 增加 `getPhoneNumber` | +| 域名校验 | `project.config.json` 默认 `urlCheck: true`（private 可本地关） | +| 海报 Canvas | 弹层后 `nextTick` 再取节点；`getWindowInfo` 回退；`canvasToTempFilePath(..., this)` | + +详见 `开发文档/小程序提审自检清单_20260321.md`。 + +--- + +## 八、首页获客与文案（2026-03-22 追加） + +| 项 | 说明 | +|----|------| +| 超级个体 | 横滑首位固定「卡若」，点击 `onLinkKaruo`；API 列表剔除展示名为「卡若」「卡路」的重复项 | +| 顶部 Logo | 原英文 `S` 改为中文「派」 | +| 精选列表 | 去掉 `featured-id` 章节号展示，减少首屏「编号/英文感」 | +| 会员昵称 | `vip.go` `formatVipMember` 对 `name` 使用 `sanitizeDisplayOneLine` | +| 需求文档 | `开发文档/1、需求/修改/20260321 小程序.md` 品牌统一为「卡若」并标为已闭环 | diff --git a/开发文档/10、项目管理/archive/过程稿/全链路深度测试与迭代报告_20260323.md b/开发文档/10、项目管理/archive/过程稿/全链路深度测试与迭代报告_20260323.md new file mode 100644 index 00000000..7a6eca07 --- /dev/null +++ b/开发文档/10、项目管理/archive/过程稿/全链路深度测试与迭代报告_20260323.md @@ -0,0 +1,163 @@ +# Soul 创业派对 · 全链路深度测试与迭代报告 + +**执行时间**：2026-03-23 19:07 +**测试范围**：管理端（soul-admin）+ 后端（soul-api）+ 小程序接口（/api/miniprogram/*）+ 数据库兼容性 +**目标**：逐页面、逐按钮、逐链路验证；输出可直接执行的优化迭代方案，并落地高优先修复。 + +--- + +## 1. 本轮覆盖结果 + +### 1.1 管理端页面与按钮深测（浏览器实测） + +已覆盖主菜单与关键子页（含按钮操作）： + +- `数据概览`：统计卡片、刷新、模块跳转。 +- `用户管理`：用户列表、获客列表、用户旅程、规则配置、超级个体列表；覆盖新增/编辑/删除/刷新/分页/筛选/详情。 +- `内容管理`：章节管理、新增章节、新增篇、编辑、付款记录入口。 +- `找伙伴`：数据统计、找伙伴、资源对接、导师预约、团队招募、刷新。 +- `推广中心`：概览、订单与代付、绑定管理、提现审核、推广设置。 +- `系统设置`：系统参数、作者详情、管理员、API 文档。 + +> 说明：本轮执行了“可点击项尽量全覆盖”。删除类操作按风险控制原则优先验证到“可触发”与“可取消”。 + +### 1.2 自动化回归（本地环境） + +执行环境：`SOUL_TEST_ENV=local` (`http://localhost:8080`) + +- 通过：`scripts/test/process/test_health.py` +- 通过：`scripts/test/web/test_admin_auth.py` +- 通过：`scripts/test/miniapp/test_config.py` +- 跳过：`scripts/test/miniapp/test_dev_login.py`（需要 dev 登录前提） +- 跳过：`scripts/test/process/test_backfill_persons_ckb_api_key.py`（依赖外部前置） +- 通过：`scripts/test/process/test_article_mention_ckb_flow.py`（修复后重跑） + +汇总：**10 passed, 2 skipped** + +### 1.3 管理端路由冒烟（admin/db 全路由） + +- 路由扫描总数：`116` +- 鉴权态冒烟：`Failures = 0` +- 未鉴权冒烟：仅 `POST /api/admin/logout` 非 401/403（属于可接受例外） + +--- + +## 2. 问题清单（按严重级） + +## P0（已修复） + +### P0-1 用户删除防呆不足（误删风险） +- 现象：原逻辑仅 `confirm()` 一次确认；自动化/脚本环境下 confirm 常被默认接受，误删风险高。 +- 影响：用户管理与管理员管理删除链路。 +- 修复： + - `soul-admin/src/pages/users/UsersPage.tsx` + - `soul-admin/src/pages/admin-users/AdminUsersPage.tsx` + - 新增二次校验：确认后要求输入“删除”才执行删除。 + +## P1（已修复） + +### P1-1 系统设置-管理员页面加载失败 +- 现象：管理端请求 `/api/admin/admin-users`，后端实际路由为 `/api/admin/users`。 +- 影响：管理员列表、增删改全部不可用。 +- 修复： + - `soul-admin/src/pages/admin-users/AdminUsersPage.tsx` + - API 路径统一改为 `/api/admin/users`（GET/POST/PUT/DELETE）。 + +### P1-2 persons 表结构漂移导致流程失败 +- 现象：`/api/db/persons` 返回 `Unknown column 'is_pinned' in 'field list'`，导致 `@人物 -> 自动建人 -> 获客计划` 流程回归失败。 +- 根因：历史库在 `persons` 自动迁移阶段遭遇旧索引冲突，新增列未补齐。 +- 修复： + - `soul-api/internal/database/database.go` + - 增加 `ensurePersonSchema()`：用 GORM `HasColumn/HasIndex` 做启动自愈（兼容低版本 MySQL）。 + - `soul-api/scripts/add-persons-pin-and-source.sql` + - 增加幂等 SQL（信息架构检测 + 动态执行）。 + - 修复后验证：`test_article_mention_ckb_flow.py` **5/5 通过**。 + +## P2（待迭代） + +- 页面切换存在短暂空白/加载抖动（找伙伴、推广中心、系统设置部分子页）。 +- 管理端构建体积偏大（主 chunk > 500KB），存在首屏与切页性能优化空间。 +- 部分列表仍有可读性与操作反馈可优化点（批量操作成功/失败反馈一致性）。 + +## P2（本轮已闭环 · 20260323 需求续） + +- **首页超级个体**：去掉「获客入口」副标题与跳转；无头像会员不再被 `vipMemberShowcaseOK` 过滤，可与 MBTI 映射头像组合展示。 +- **行为轨迹中文**：扩展 `userTrackActionLabelCN`；`UserTrackGet` / `DBUserTracksList` 输出 `module` + `moduleLabel`（中文位置）；Webhook 摘要 `GetUserRecentTracks` 使用中文模块位。 +- **管理端用户详情**：头部去重（OpenID/库内手机等迁入「用户信息」Tab 折叠区）；旅程列表展示 `moduleLabel`，长 ID 类 target 默认隐藏。 +- **规则配置列表**：描述仍为折叠，摘要行改为「字数提示」避免整段摊开。 +- **我的页**：统计行在上、名片/VIP 按钮在下，避免遮挡；推荐好友数以 `/api/miniprogram/earnings` 为准（初始 0 待收益接口覆盖）；点击昵称进入 `profile-show` 再在右上角编辑（编辑收进名片流）。 +- **Webhook 频次**：留资推送仍按「同一用户自然日仅首条 webhook」去重（`webhookShouldSkip`），与需求一致。 + +--- + +## 3. 本轮已落地代码变更 + +### 前端（soul-admin） +- `src/pages/admin-users/AdminUsersPage.tsx` + - 修复管理员接口路径错误。 + - 删除操作增加“输入删除”二次确认。 +- `src/pages/users/UsersPage.tsx` + - 用户删除、规则删除增加“输入删除”二次确认。 + +### 后端（soul-api） +- `internal/database/database.go` + - 增加 `ensurePersonSchema()`，启动时自愈补齐 `persons.is_pinned`、`persons.person_source`、`idx_persons_is_pinned`。 +- `scripts/add-persons-pin-and-source.sql` + - 新增兼容型幂等迁移脚本（适配不支持 `IF NOT EXISTS` 的 MySQL）。 + +### 测试脚本（scripts/test） +- `scripts/test/web/admin_routes_smoke.py` +- `scripts/test/web/admin_routes_smoke_authless.py` + - 去除硬编码 Windows 路径，改为自动定位当前仓库 `soul-api/internal/router/router.go`。 + +### 20260323 需求续（小程序 + 管理端 + API） +- `miniprogram/pages/index/index.wxml` / `index.js`：移除超级个体区「获客入口」。 +- `miniprogram/pages/my/my.wxml` / `my.wxss` / `my.js`：名片/VIP 下移；推荐数以收益接口为准；昵称 → 个人资料名片页。 +- `soul-api/internal/handler/vip.go`：`vipMemberShowcaseOK` 不再要求头像 URL。 +- `soul-api/internal/handler/user.go`：轨迹中文动作/模块位、`UserTrackGet` 附加字段、`GetUserRecentTracks` 中文模块。 +- `soul-admin/src/components/modules/user/UserDetailModal.tsx`：信息区结构优化 + 轨迹展示模块中文。 +- `soul-admin/src/pages/users/UsersPage.tsx`：规则描述折叠摘要优化。 + +--- + +## 4. 前端/后端/数据库一体化优化迭代建议 + +## 4.1 前端优化（soul-admin + miniprogram） +- 管理端按路由做代码分包（`React.lazy + Suspense`），优先拆分 `UsersPage`、`ContentPage`、`DistributionPage`。 +- 所有破坏性操作统一接入“二次确认组件”（替代散落的 `confirm/prompt`）。 +- 用户旅程与行为轨迹统一中文事件字典（避免中英混杂），并复用到导出/群播文案。 +- 小程序 `app.json` 的 `pages/dev-login/dev-login` 建议通过构建变量控制（dev 包含、release 排除），防止提审干扰。 + +## 4.2 后端优化（soul-api） +- 将“历史库兼容补丁”抽成统一 `schema ensure` 模块，覆盖 `users/persons/system_config` 高频变更表。 +- 对 `POST /api/admin/logout` 增加鉴权前置（未登录返回 401），与 authless 预期一致。 +- 管理端高频列表接口统一增加 `request_id` 与慢查询日志标签，便于排查“加载失败/慢响应”。 + +## 4.3 数据库优化 +- 建议补建/巡检以下索引： + - `persons(is_pinned)`（本轮已补） + - `user_tracks(user_id, created_at)`（旅程时间线） + - `orders(user_id, created_at, status)`（用户漏斗/支付链路） +- 建议建立“启动前 schema 巡检脚本”，在部署阶段提前阻断“字段缺失后线上才报错”。 + +--- + +## 5. 下一阶段执行计划（可直接开工） + +1. **P0/P1 回归闭环（今日）** + - 管理端删除链路二次确认回归 + - 管理员页 CRUD 全链路回归 + - persons 提及链路 + 获客计划联调回归 +2. **P2 性能迭代（本周）** + - 管理端路由分包 + - 大列表分页与筛选接口响应压测 +3. **产品体验优化（本周）** + - 用户旅程中文事件标准化 + - 页面 loading 骨架屏与空状态统一 + +--- + +## 6. 本轮结论 + +本轮完成了“全站深测 + 关键故障修复 + 一体化优化方案输出”。 +当前系统可用性已显著提升，阻断级问题已清理，剩余主要是性能与体验的系统性优化。 diff --git a/开发文档/10、项目管理/archive/过程稿/小程序提审自检清单_20260321.md b/开发文档/10、项目管理/archive/过程稿/小程序提审自检清单_20260321.md new file mode 100644 index 00000000..419c3c15 --- /dev/null +++ b/开发文档/10、项目管理/archive/过程稿/小程序提审自检清单_20260321.md @@ -0,0 +1,35 @@ +# 小程序提审自检清单（2026-03-21） + +上传审核前在开发者工具内逐项勾选；本清单与当前代码约定一致。 + +## 一、环境与域名 + +- [ ] **正式版 `envVersion=release`**：`app.js` 的 `initApiBaseUrl()` 会强制 `baseUrl=https://soulapi.quwanzhi.com`，并清除本地误存的非生产 `apiBaseUrl`。 +- [ ] **微信公众平台**：request 合法域名、socket 合法域名、uploadFile/downloadFile 合法域名已包含生产 API 与 OSS/CDN（含 `at.alicdn.com` 字体若使用）。 +- [ ] **`project.config.json`**：`urlCheck: true`（仓库默认）；本地调试可用 `project.private.config.json` 覆盖为 `false`，**勿把 private 里长期关校验的配置提交为唯一来源**。 + +## 二、隐私与权限声明 + +- [ ] `app.json` 已配置 `__usePrivacyCheck__: true`。`requiredPrivateInfos` 仅允许位置类（`chooseAddress` 等）；**勿**写入 `getPhoneNumber`（新版开发者工具/校验会拒绝上传）。手机号能力靠 ` + ) : ( + + )} + + {/* 快捷操作 */} + {}} + onJoinGroup={() => {}} + /> + + ) +} +``` + +### 2.2 关键组件 + +**星空背景**: +```typescript +function StarfieldBackground() { + const canvasRef = useRef(null) + + useEffect(() => { + const canvas = canvasRef.current + const ctx = canvas?.getContext('2d') + if (!canvas || !ctx) return + + // 创建星星 + const stars = Array.from({ length: 100 }, () => ({ + x: Math.random() * canvas.width, + y: Math.random() * canvas.height, + radius: Math.random() * 2, + opacity: Math.random() + })) + + // 绘制动画 + function animate() { + ctx.clearRect(0, 0, canvas.width, canvas.height) + stars.forEach(star => { + ctx.beginPath() + ctx.arc(star.x, star.y, star.radius, 0, Math.PI * 2) + ctx.fillStyle = `rgba(255, 255, 255, ${star.opacity})` + ctx.fill() + }) + requestAnimationFrame(animate) + } + animate() + }, []) + + return +} +``` + +--- + +## 3. 阅读模块 + +**路径**: `/app/read/[id]/page.tsx` + +### 3.1 核心功能 + +```typescript +export default async function ReadPage({ params }: Props) { + const { id } = params + const section = await getSection(id) + + if (!section) { + notFound() + } + + return ( +
+ {/* 返回按钮 */} + + + {/* 章节标题 */} +

+ {section.title} +

+ + {/* 章节信息 */} + + + {/* Markdown内容 */} + + + {/* 章节导航 */} + + + {/* 分享按钮 */} + +
+ ) +} +``` + +### 3.2 Markdown渲染 + +```typescript +import { marked } from 'marked' + +function MarkdownContent({ content }: { content: string }) { + const html = marked(content) + + return ( +
+ ) +} + +// CSS样式 +.prose { + @apply text-gray-300 leading-relaxed; +} + +.prose h1 { + @apply text-3xl font-bold text-white mt-8 mb-4; +} + +.prose h2 { + @apply text-2xl font-bold text-white mt-6 mb-3; +} + +.prose p { + @apply mb-4; +} + +.prose ul { + @apply list-disc list-inside mb-4; +} + +.prose code { + @apply bg-gray-800 px-2 py-1 rounded text-[var(--app-brand)]; +} +``` + +--- + +## 4. 我的模块 + +**路径**: `/app/my/page.tsx` + +### 4.1 核心功能 + +```typescript +export default function MyPage() { + const { user, isLoggedIn } = useStore() + + if (!isLoggedIn) { + return + } + + return ( +
+ {/* 用户信息卡片 */} + + + {/* 阅读统计 */} + + + {/* 分销中心(重点突出) */} + + + {/* 功能菜单 */} + +
+ ) +} +``` + +### 4.2 分销中心 + +```typescript +function ReferralCenter({ code, earnings, referralCount }: Props) { + return ( +
+

分销中心

+ + {/* 收益概览 */} +
+
+
+ ¥{earnings.toFixed(2)} +
+
累计收益
+
+
+
+ {referralCount} +
+
推荐人数
+
+
+ + {/* 邀请码 */} +
+ +
+ + +
+
+ + {/* 生成海报 */} + +
+ ) +} +``` + +--- + +## 5. 支付模块 + +**路径**: `/components/payment-modal.tsx` + +### 5.1 核心流程 + +```typescript +export function PaymentModal({ + isOpen, + amount, + type, + onSuccess +}: Props) { + const [paymentMethod, setPaymentMethod] = useState('alipay') + const [showQRCode, setShowQRCode] = useState(false) + const [isProcessing, setIsProcessing] = useState(false) + + // 发起支付 + const handlePayment = async () => { + setShowQRCode(true) + + // 调用支付API + const order = await createOrder({ + amount, + type, + paymentMethod + }) + + // 展示支付二维码 + showPaymentQRCode(order.qrCode) + } + + // 确认支付 + const confirmPayment = async () => { + setIsProcessing(true) + + // 购买逻辑 + const success = await purchaseItem(type) + + if (success) { + onSuccess() + // 自动跳转到读者群 + openWechatGroup() + } + + setIsProcessing(false) + } + + return ( + + {!showQRCode ? ( + + ) : ( + + )} + + ) +} +``` + +### 5.2 支付方式组件 + +```typescript +function PaymentMethodSelection({ selected, onSelect, onConfirm }: Props) { + const methods = [ + { + id: 'wechat', + name: '微信支付', + icon: , + color: '#07C160' + }, + { + id: 'alipay', + name: '支付宝', + icon: , + color: '#1677FF' + }, + { + id: 'usdt', + name: 'USDT (TRC20)', + icon: , + color: '#26A17B' + } + ] + + return ( +
+ {methods.map(method => ( + + ))} + + +
+ ) +} +``` + +--- + +## 6. 后台管理模块 + +**路径**: `/app/admin/page.tsx` + +### 6.1 概览页面 + +```typescript +export default function AdminDashboard() { + const [stats, setStats] = useState(null) + + useEffect(() => { + fetchStats() + }, []) + + async function fetchStats() { + const res = await fetch('/api/admin', { + headers: { + 'Authorization': `Bearer ${getAdminToken()}` + } + }) + const data = await res.json() + setStats(data) + } + + if (!stats) return + + return ( +
+ {/* 概览卡片 */} +
+ + + + +
+ + {/* 图表 */} +
+ + +
+
+ ) +} +``` + +### 6.2 内容管理 + +```typescript +function ContentManagement() { + const [chapters, setChapters] = useState([]) + + return ( +
+ {/* 操作栏 */} +
+

内容管理

+ +
+ + {/* 章节列表 */} + + + + + + + + + + + + {chapters.map(chapter => ( + + + + + + + + ))} + +
章节ID标题状态价格操作
{chapter.id}{chapter.title} + + {chapter.isFree ? '免费' : '付费'} + + ¥{chapter.price} + +
+
+ ) +} +``` + +--- + +## 7. 通用组件库 + +### 7.1 Button组件 + +```typescript +interface ButtonProps { + children: React.ReactNode + onClick?: () => void + loading?: boolean + disabled?: boolean + variant?: 'primary' | 'secondary' | 'ghost' + size?: 'sm' | 'md' | 'lg' +} + +export function Button({ + children, + onClick, + loading, + disabled, + variant = 'primary', + size = 'md' +}: ButtonProps) { + const baseClasses = 'rounded-xl font-semibold transition-all' + + const variantClasses = { + primary: 'bg-[var(--app-brand)] text-white hover:opacity-90', + secondary: 'bg-[var(--app-bg-secondary)] text-white', + ghost: 'bg-transparent text-[var(--app-brand)] hover:bg-[var(--app-brand-light)]' + } + + const sizeClasses = { + sm: 'px-4 py-2 text-sm', + md: 'px-6 py-3 text-base', + lg: 'px-8 py-4 text-lg' + } + + return ( + + ) +} +``` + +### 7.2 Modal组件 + +```typescript +export function Modal({ + isOpen, + onClose, + children +}: ModalProps) { + if (!isOpen) return null + + return ( +
+ {/* 背景蒙层 */} +
+ + {/* 内容区域 */} +
+ {/* 顶部把手 (仅移动端) */} +
+
+
+ + {/* 关闭按钮 */} + + + {/* 内容 */} +
+ {children} +
+
+
+ ) +} +``` + +--- + +**总结**: 前端模块以**组件化**为核心,每个模块职责清晰,组件可复用。核心模块包括首页(展示)、匹配(社交)、阅读(内容)、我的(用户中心)、支付(变现)、后台(管理)。所有模块都遵循统一的设计规范和交互模式。 diff --git a/开发文档/5、接口/API接口完整文档.md b/开发文档/5、接口/API接口完整文档.md new file mode 100644 index 00000000..e23fa1d5 --- /dev/null +++ b/开发文档/5、接口/API接口完整文档.md @@ -0,0 +1,640 @@ +# 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= +``` + +**管理员认证** (必需): +``` +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 + + SUCCESS + order_1705230000000 + 990 + +``` + +**响应**: +```xml + + SUCCESS + OK + +``` + +### 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规范,响应格式统一,错误处理清晰。所有接口都有明确的认证要求和错误处理。核心功能包括内容获取、支付流程、分销系统、用户管理、匹配功能。 diff --git a/开发文档/5、接口/README.md b/开发文档/5、接口/README.md new file mode 100644 index 00000000..c7e72faf --- /dev/null +++ b/开发文档/5、接口/README.md @@ -0,0 +1,18 @@ +# 5、接口 + +> **Soul 创业实验项目** HTTP API 与相关配置文档。 + +## 真源与分工 + +| 文档 | 说明 | +|------|------| +| [**API接口完整文档.md**](./API接口完整文档.md) | Soul `/api` **主真源**（REST 模块划分、鉴权说明） | +| [配置清单-完整版.md](./配置清单-完整版.md) | 环境变量与配置项 | +| [在线支付对接文档.md](./在线支付对接文档.md) | 支付对接 | +| [接口与提现.md](./接口与提现.md) | 提现与相关接口 | + +## 非本目录但易混淆 + +- **存客宝「对外线索上报」OpenAPI**（第三方调存客宝）：见开发文档根目录 [api_v1.md](../api_v1.md) 文首说明；存客宝 **前端** 调自家后端见 [Cunkebao接口文档/](../Cunkebao接口文档/)。 + +返回 [开发文档索引](../索引.md)。 diff --git a/开发文档/5、接口/在线支付对接文档.md b/开发文档/5、接口/在线支付对接文档.md new file mode 100644 index 00000000..27c8bf8c --- /dev/null +++ b/开发文档/5、接口/在线支付对接文档.md @@ -0,0 +1,319 @@ +# 在线支付对接文档 + +本文档根据当前项目中的支付相关代码与配置反向整理，供前端/第三方/运维对接使用。后端当前为 **soul-api（Go/Gin）**，支付业务逻辑可参考 **next-project** 中的实现。 + +--- + +## 一、概述 + +- **支付方式**：微信支付（Native 扫码 / JSAPI 小程序·公众号 / H5）、支付宝（WAP / Web / 扫码）。 +- **对接入口**：统一走 soul-api 的 `/api` 前缀（如 `https://your-api.com/api/...`）。 +- **回调**：支付平台（微信/支付宝）会主动 POST 到服务端配置的 notify 地址，需公网可访问且返回约定格式。 + +--- + +## 二、接口清单（soul-api） + +| 方法 | 路径 | 说明 | +|-----|------|------| +| POST | `/api/payment/create-order` | 创建支付订单，返回支付参数（二维码/链接/JSAPI 参数等） | +| GET | `/api/payment/methods` | 获取可用支付方式列表 | +| GET | `/api/payment/query` | 按交易号查询支付状态（轮询用） | +| GET | `/api/payment/status/:orderSn` | 按订单号查询订单支付状态 | +| POST | `/api/payment/verify` | 支付结果校验（可选） | +| POST | `/api/payment/callback` | 通用支付回调（可选，与各平台 notify 二选一或并存） | +| POST | `/api/payment/wechat/notify` | 微信支付异步通知 | +| POST | `/api/payment/alipay/notify` | 支付宝异步通知 | +| POST | `/api/payment/wechat/transfer/notify` | 微信转账/企业付款到零钱回调（若启用） | +| GET/POST | `/api/miniprogram/pay` | 小程序下单（创建订单 + 返回微信支付参数） | +| POST | `/api/miniprogram/pay/notify` | 小程序支付异步通知 | + +管理端（需鉴权）： + +| 方法 | 路径 | 说明 | +|-----|------|------| +| GET/POST/PUT/DELETE | `/api/admin/payment` | 支付相关配置管理 | + +--- + +## 三、请求与响应约定 + +以下格式以 next-project 中已实现逻辑为对接规范，soul-api 实现时应与之兼容。 + +### 3.1 创建订单 `POST /api/payment/create-order` + +**请求体（JSON）** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| userId | string | 是 | 用户 ID | +| type | string | 是 | 购买类型：`section`（单章） / `fullbook`（全书） | +| sectionId | string | type=section 时 | 章节 ID，如 `1-1` | +| sectionTitle | string | 建议 | 章节标题，用于展示与订单描述 | +| amount | number | 是 | 金额（元），如 9.9 | +| paymentMethod | string | 是 | 支付方式：`wechat` / `alipay` | +| referralCode | string | 否 | 推荐人邀请码，用于分销 | + +**响应（JSON）** + +```json +{ + "code": 200, + "message": "订单创建成功", + "data": { + "orderSn": "20260209123456", + "tradeSn": "T2026020912000012345", + "userId": "user_xxx", + "type": "section", + "sectionId": "1-1", + "sectionTitle": "第一章", + "amount": 9.9, + "paymentMethod": "wechat", + "status": "created", + "createdAt": "2026-02-09T12:00:00.000Z", + "expireAt": "2026-02-09T12:30:00.000Z", + "paymentData": { + "type": "qrcode", + "payload": "weixin://wxpay/...", + "tradeSn": "T2026020912000012345", + "expiration": 1800 + }, + "gateway": "wechat_native" + } +} +``` + +- **paymentData.type**：`qrcode`（二维码内容/链接）、`url`（跳转链接）、`json`（JSAPI 等参数对象）。 +- **paymentData.payload**：微信 Native 为二维码链接；支付宝 WAP 为支付 URL；JSAPI 为 `{ timeStamp, nonceStr, package, signType, paySign }` 等。 +- **gateway**：用于后续轮询时传 `gateway`，如 `wechat_native`、`alipay_wap`。 + +**错误**：`code: 400` 表示缺少必要参数；`code: 500` 为服务器错误。 + +--- + +### 3.2 支付方式列表 `GET /api/payment/methods` + +**响应** + +```json +{ + "code": 200, + "message": "success", + "data": { + "methods": [ + { + "gateway": "wechat_native", + "name": "微信支付", + "icon": "wechat", + "enabled": true, + "available": true + } + ] + } +} +``` + +--- + +### 3.3 查询支付状态（轮询）`GET /api/payment/query` + +**Query** + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| tradeSn | string | 是 | 创建订单时返回的 tradeSn | +| gateway | string | 否 | 指定网关，如 `wechat_native`、`alipay_wap`，不传则双通道查询 | + +**响应** + +```json +{ + "code": 200, + "message": "success", + "data": { + "tradeSn": "T2026020912000012345", + "status": "paid", + "platformSn": "4200001234567890", + "payAmount": 990, + "payTime": "2026-02-09T12:05:00.000Z", + "gateway": "wechat_native" + } +} +``` + +- **status**：`paying` 未支付，`paid` 已支付，`closed` 已关闭/退款等。 +- **payAmount**：单位「分」。**payTime** 为支付完成时间。 + +前端建议：每 3 秒轮询一次，最多约 60 次（约 3 分钟）；收到 `status: "paid"` 后停止轮询并更新订单/解锁内容。 + +--- + +### 3.4 按订单号查状态 `GET /api/payment/status/:orderSn` + +**路径参数**：`orderSn` 为创建订单返回的订单号。 + +**响应** + +```json +{ + "code": 200, + "message": "success", + "data": { + "orderSn": "20260209123456", + "status": "paid", + "paidAmount": 9.9, + "paidAt": "2026-02-09T12:05:00.000Z", + "paymentMethod": "wechat", + "tradeSn": "T2026020912000012345", + "productType": "section" + } +} +``` + +- **status**：与业务一致：`created`、`paying`、`paid`、`closed`、`refunded` 等。 + +--- + +### 3.5 支付校验 `POST /api/payment/verify` + +**请求体** + +| 字段 | 类型 | 说明 | +|------|------|------| +| orderId | string | 订单号 | +| paymentMethod | string | 支付方式 | +| transactionId | string | 第三方交易号（可选） | + +**响应**：成功时 `code: 0`，失败时非 0；用于前端在回调不确定时的二次校验（具体逻辑由后端实现）。 + +--- + +## 四、支付平台异步通知（回调） + +对接方需在微信支付/支付宝商户后台配置「支付结果通知 URL」，且必须为 **公网 HTTPS**。当前项目约定路径如下（以 soul-api 域名为准）： + +| 支付方式 | 通知 URL | 说明 | +|----------|----------|------| +| 微信支付 | `https://your-api.com/api/payment/wechat/notify` | 统一下单/JSAPI/小程序等 | +| 支付宝 | `https://your-api.com/api/payment/alipay/notify` | 异步 notify | +| 微信转账 | `https://your-api.com/api/payment/wechat/transfer/notify` | 企业付款到零钱（若使用） | + +### 4.1 微信支付 notify + +- **方法**：POST +- **Content-Type**：`application/xml` +- **Body**：微信以 XML 推送，字段含 `return_code`、`result_code`、`out_trade_no`、`transaction_id`、`total_fee`、`time_end`、`sign` 等。 +- **验签**：使用商户密钥对微信参数做 MD5 签名校验（见 next-project `lib/payment/wechat.ts` 中 `verifySign`）。 +- **响应**：必须返回 XML，成功示例： + `` + 失败则返回 `return_code=FAIL`，否则微信会重试。 + +**业务处理建议**（与 next-project 一致）： +1. 验签通过且 `result_code=SUCCESS` 后，用 `out_trade_no`（即本系统 tradeSn）查订单，更新为已支付、写入 `transaction_id`、`pay_time`。 +2. 根据 `product_type` 开通全书或章节权限。 +3. 若有推荐人，写分销表并更新 `pending_earnings`。 +4. 响应必须在业务异常时仍返回成功 XML，避免微信重复通知。 + +### 4.2 支付宝 notify + +- **方法**：POST +- **Content-Type**：`application/x-www-form-urlencoded` +- **Body**：表单键值对，含 `out_trade_no`、`trade_no`、`trade_status`、`total_amount`、`gmt_payment`、`sign` 等。 +- **验签**：使用配置的 MD5 密钥校验（见 next-project `lib/payment/alipay.ts`）。 +- **响应**：纯文本，成功返回 `success`，失败返回 `fail`。支付宝会多次重试直至收到 `success`。 + +**业务处理**：与微信类似，以 `out_trade_no` 更新订单、开通权限、处理分销。 + +--- + +## 五、小程序支付 + +### 5.1 下单 `GET/POST /api/miniprogram/pay` + +**请求体（JSON）** + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| openId | string | 是 | 用户 openId | +| productType | string | 是 | `section` / `fullbook` | +| productId | string | 是 | 章节 ID 或 `fullbook` | +| amount | number | 是 | 金额（元） | +| description | string | 建议 | 订单描述 | +| userId | string | 是 | 用户 ID | + +**响应** + +```json +{ + "success": true, + "data": { + "orderSn": "MP20260204123456789012", + "prepayId": "wx...", + "payParams": { + "timeStamp": "...", + "nonceStr": "...", + "package": "prepay_id=...", + "signType": "MD5", + "paySign": "..." + } + } +} +``` + +小程序端用 `payParams` 调起 `wx.requestPayment`。 + +### 5.2 小程序支付通知 `POST /api/miniprogram/pay/notify` + +与「微信支付 notify」同一套规范（XML 入参、XML 成功响应）。商户后台配置的「支付结果通知 URL」填 soul-api 的 `/api/miniprogram/pay/notify` 或统一使用 `/api/payment/wechat/notify` 均可，需与后端实现一致（按订单来源更新对应订单与权限）。 + +--- + +## 六、配置项 + +### 6.1 管理端 / 配置接口 + +- **GET /api/config**：返回全站配置，其中 **paymentMethods** 用于前端展示支付方式及微信/支付宝相关配置（如微信群二维码、商户信息等）。 +- 支付开关、商户号、密钥等建议放在服务端环境变量或管理端「支付配置」中，不通过公开接口暴露密钥。 + +### 6.2 环境变量（参考 next-project） + +后端若自实现支付，可参考以下变量（soul-api 当前未在 .env.example 中列出，对接时按需增加）： + +**微信** + +- `WECHAT_APPID` / `WECHAT_SERVICE_APPID`：公众号/服务号 AppID +- `WECHAT_APP_SECRET` / `WECHAT_SERVICE_SECRET` +- `WECHAT_MCH_ID`：商户号 +- `WECHAT_MCH_KEY`：商户 API 密钥 + +**支付宝** + +- `ALIPAY_APP_ID` / `ALIPAY_PID` +- `ALIPAY_PRIVATE_KEY` / `ALIPAY_PUBLIC_KEY` 或 `ALIPAY_MD5_KEY` +- `ALIPAY_SELLER_EMAIL` + +**应用** + +- `NEXT_PUBLIC_BASE_URL` 或等价「站点 base URL」：用于拼装 notify/return 地址。 + +--- + +## 七、订单与数据库（参考） + +- **orders 表**：`id`、`order_sn`、`user_id`、`open_id`、`product_type`、`product_id`、`amount`、`description`、`status`、`transaction_id`、`pay_time`、`referral_code`、`referrer_id`、`created_at`、`updated_at`。 +- **status**：`created` → 创建，`paid` → 已支付，`expired`/`cancelled` 等由业务定义。 +- 创建订单时可将 **tradeSn** 写入 `transaction_id`，支付回调里用微信/支付宝的「商户订单号」即 tradeSn 查单并更新为 `transaction_id`（平台交易号）、`pay_time`、`status=paid`。 + +--- + +## 八、错误与注意事项 + +1. **签名**：所有微信/支付宝回调必须先验签再执行业务，否则存在伪造风险。 +2. **幂等**：同一笔订单可能被多次通知，更新订单与佣金前应判断当前状态，避免重复加款。 +3. **响应**：notify 接口必须在处理完（或确认可稍后处理）后按平台要求返回成功（微信 XML 成功、支付宝 `success`），再异步做后续逻辑，避免平台反复回调。 +4. **金额**：微信为「分」，支付宝为「元」；内部建议统一用「分」存储，与 next-project 一致。 +5. **soul-api 现状**：当前 payment/miniprogram 相关 handler 为占位实现（直接返回 success），完整逻辑需按本文档与 next-project 实现对齐后上线。 + +--- + +*文档根据项目代码反向整理，若与最新代码不一致，以实际仓库为准。* diff --git a/开发文档/5、接口/接口与提现.md b/开发文档/5、接口/接口与提现.md new file mode 100644 index 00000000..58cbe96b --- /dev/null +++ b/开发文档/5、接口/接口与提现.md @@ -0,0 +1,11 @@ +# 接口与提现（合并自 接口定义规范、提现功能完整技术文档） + +## 接口规范 + +RESTful，JSON 返回。基础 URL 开发 localhost:3000/api，生产 soul.quwanzhi.com/api。统一格式：`{ code, message, data }`。 + +## 提现功能 + +微信支付商家转账到零钱 API，签名算法、加解密、完整实现、测试验证。流程：用户申请 → 审核 → 调 API → 回调更新状态。 + +详见原《接口定义规范》《提现功能完整技术文档》。 diff --git a/开发文档/5、接口/配置清单-完整版.md b/开发文档/5、接口/配置清单-完整版.md new file mode 100644 index 00000000..1ca859a7 --- /dev/null +++ b/开发文档/5、接口/配置清单-完整版.md @@ -0,0 +1,205 @@ +# Soul创业实验 - API密钥与配置清单 + +> 最后更新: 2026-01-25 +> 维护人: 卡若 +> ⚠️ 本文件包含敏感信息，请勿公开 + +--- + +## 一、企业信息 + +| 项目 | 值 | +|:---|:---| +| **企业名称** | 泉州市卡若网络技术有限公司 | +| **联系电话** | 15880802661 | +| **微信号** | 28533368 | +| **邮箱** | zhiqun@qq.com / zhengzhiqun@vip.qq.com | + +--- + +## 二、微信生态 + +### 2.1 小程序（Soul创业实验） + +| 项目 | 值 | 备注 | +|:---|:---|:---| +| **AppID** | `wxb8bbb2b10dec74aa` | 小程序ID | +| **AppSecret** | `3c1fb1f63e6e052222bbcead9d07fe0c` | 小程序密钥 | +| **支付绑定状态** | 🟡 审核中 | 2026-01-25 09:43:59 提交 | + +### 2.2 服务号（玩值） + +| 项目 | 值 | 备注 | +|:---|:---|:---| +| **AppID** | `wx7c0dbf34ddba300d` | 服务号AppID | +| **AppSecret** | `f865ef18c43dfea6cbe3b1f1aebdb82e` | 服务号密钥 | +| **支付绑定状态** | ✅ 已绑定 | 绑定AppID: wx3e31b068be59ddc1 | + +### 2.3 网站应用 + +| 项目 | 值 | +|:---|:---| +| **AppID** | `wx432c93e275548671` | +| **AppSecret** | `25b7e7fdb7998e5107e242ebb6ddabd0` | + +### 2.4 微信支付 + +| 项目 | 值 | 备注 | +|:---|:---|:---| +| **商户号** | `1318592501` | 主体: 泉州市卡若网络技术有限公司 | +| **API密钥(v2)** | `wx3e31b068be59ddc131b068be59ddc2` | 32位 | +| **MP文件验证码** | `SP8AfZJyAvprRORT` | | +| **支付回调地址** | `https://soul.quwanzhi.com/api/miniprogram/pay/notify` | | + +#### 已绑定AppID + +| AppID | 类型 | 状态 | +|:---|:---|:---| +| `wx3e31b068be59ddc1` | 服务号 | ✅ 已关联 | +| `wxb8bbb2b10dec74aa` | 小程序 | 🟡 审核中 | + +--- + +## 三、支付宝 + +| 项目 | 值 | +|:---|:---| +| **PID** | `2088511801157159` | +| **MD5密钥** | `lz6ey1h3kl9zqkgtjz3avb5gk37wzbrp` | +| **账户** | zhengzhiqun@vip.qq.com | + +--- + +## 四、云服务 + +### 4.1 腾讯云 + +| 项目 | 值 | +|:---|:---| +| **APPID** | `1251077262` | +| **SecretId** | `AKIDjc6yO3nPeOuK2OKsJPBBVbTiiz0aPNHl` | +| **SecretKey** | *(见用户规则)* | + +### 4.2 阿里云 + +| 项目 | 值 | +|:---|:---| +| **AccessKey ID** | `LTAI5t9zkiWmFtHG8qmtdysW` | +| **AccessKey Secret** | `xxjXnZGLNvA2zDkj0aEBSQm3XZAaro` | + +--- + +## 五、数据库 + +### 5.1 腾讯云MySQL（生产环境） + +| 项目 | 值 | +|:---|:---| +| **主机** | `56b4c23f6853c.gz.cdb.myqcloud.com` | +| **端口** | `14413` | +| **数据库** | `soul_miniprogram` | +| **用户名** | `cdb_outerroot` | +| **密码** | `Zhiqun1984` | +| **字符集** | `utf8mb4` | + +#### 数据库表 + +| 表名 | 说明 | +|:---|:---| +| `users` | 用户表 | +| `orders` | 订单表 | +| `referral_bindings` | 推广绑定关系 | +| `match_records` | 匹配记录 | +| `system_config` | 系统配置 | +| `chapters` | **章节内容表（新）** | + +### 5.2 卡若私域数据库（内网） + +| 项目 | 值 | +|:---|:---| +| **主机** | `10.88.182.62` | +| **端口** | `3306` | +| **用户名** | `root` | +| **密码** | `Vtka(agu)-1` | + +--- + +## 六、AI服务 + +### 6.1 v0 API + +| 项目 | 值 | +|:---|:---| +| **API地址** | `https://api.v0.dev/v1` | +| **API Key** | `v1:C6mw1SlvXsJdlO4VFEXSQEVf:519gA0DPqIMbjvfMh7CXf4B2` | +| **默认模型** | `claude-opus` | + +--- + +## 七、开发工具 + +### 7.1 GitHub + +| 项目 | 值 | +|:---|:---| +| **Token** | `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` | + +--- + +## 八、项目部署信息 + +| 项目 | 值 | +|:---|:---| +| **域名** | `soul.quwanzhi.com` | +| **协议** | HTTPS | +| **服务器** | 宝塔面板 | +| **部署方式** | GitHub Webhook 自动部署 | + +--- + +## 九、邮箱账户 + +| 邮箱 | 密码 | +|:---|:---| +| `zhiqun@qq.com` | `#vtk();1984` | +| `zhengzhiqun@vip.qq.com` | `#vtk();1984` | +| `15880802661@qq.com` | `#vtk();1984` | + +--- + +## 十、配置代码引用 + +### 小程序支付配置 + +```typescript +// lib/payment/wechat-miniprogram.ts +const WECHAT_PAY_CONFIG = { + appId: 'wxb8bbb2b10dec74aa', // 小程序AppID + appSecret: '3c1fb1f63e6e052222bbcead9d07fe0c', // 小程序AppSecret + mchId: '1318592501', // 商户号 + mchKey: 'wx3e31b068be59ddc131b068be59ddc2', // API密钥(v2) + notifyUrl: 'https://soul.quwanzhi.com/api/miniprogram/pay/notify', +} +``` + +### 数据库配置 + +```typescript +// lib/db.ts +const DB_CONFIG = { + host: '56b4c23f6853c.gz.cdb.myqcloud.com', + port: 14413, + user: 'cdb_outerroot', + password: 'Zhiqun1984', + database: 'soul_miniprogram', + charset: 'utf8mb4', +} +``` + +--- + +## 更新日志 + +| 日期 | 更新内容 | +|:---|:---| +| 2026-01-25 | 创建完整配置清单；小程序支付绑定申请中；章节表迁移完成 | diff --git a/开发文档/6、后端/image.png b/开发文档/6、后端/image.png new file mode 100644 index 00000000..b26ffbf4 Binary files /dev/null and b/开发文档/6、后端/image.png differ diff --git a/开发文档/6、后端/soul-admin与Mycontent-temp内容页对比.md b/开发文档/6、后端/soul-admin与Mycontent-temp内容页对比.md new file mode 100644 index 00000000..eb4fc624 --- /dev/null +++ b/开发文档/6、后端/soul-admin与Mycontent-temp内容页对比.md @@ -0,0 +1,53 @@ +# soul-admin 与 Mycontent-temp 内容管理页面对比 + +> 目标：soul-admin 为功能基准，新建/编辑样式功能要一模一样。 + +## 一、新建章节弹窗 + +| 项目 | soul-admin | Mycontent-temp | +|------|------------|---------------| +| 弹窗宽度 | max-w-2xl | max-w-2xl | +| 章节ID | ✅ | ✅ | +| 价格 | ✅ | ✅ | +| 文章类型（普通版/增值版） | ✅ | ❌ 无 | +| 章节标题 | ✅ | ✅ | +| 所属篇 | ✅ | ✅ | +| 所属章 | ✅ | ✅ | +| 内容 | Markdown Textarea | Markdown Textarea | +| 免费 | ❌ 无 | ❌ 无 | +| 最新新增 | ❌ 无 | ❌ 无 | +| 小程序直推 | ❌ 无 | ❌ 无 | +| 热度分 | ❌ 无 | ❌ 无 | + +**结论**：新建与编辑不一致。编辑有 RichEditor、免费、最新新增、置顶、热度分，新建用 Textarea 且缺这些字段。 + +## 二、编辑章节弹窗 + +| 项目 | soul-admin | Mycontent-temp | +|------|------------|---------------| +| 弹窗宽度 | max-w-4xl | max-w-4xl | +| 内容 | RichEditor | RichEditor | +| 文章类型 | ✅ | ❌ 无 | +| 免费 | ✅ | ✅ | +| 最新新增 | ✅ | ✅ | +| 小程序直推 | ✅ | ✅ | +| 热度分 | ✅ | ✅ | +| 付款记录 | ✅ | ✅ | +| editionStandard/editionPremium 读取 | ✅ | ❌ 无 | + +**结论**：soul-admin 编辑功能完整；Mycontent-temp 缺文章类型。 + +## 三、执行项（soul-admin）✅ 已完成 + +1. **新建弹窗**：与编辑弹窗样式功能统一 ✅ + - 布局改为 max-w-4xl、flex flex-col + - 内容改为 RichEditor + - 补充：免费、最新新增、小程序直推、热度分、文章类型 + - 字段顺序与编辑一致 + +2. **文章详情**：内容区（RichEditor）处理完善 ✅ + - 新建、编辑均使用 RichEditor，支持 @人物、#标签、图片上传 + +3. **后端 db_book**：支持新建章节 Create ✅ + - 新增 body 字段：PartID、PartTitle、ChapterID、ChapterTitle、HotScore + - 新建时 FirstOrCreate 逻辑：不存在则 Create，存在则 Updates diff --git a/开发文档/6、后端/内容创建问题修复说明.md b/开发文档/6、后端/内容创建问题修复说明.md new file mode 100644 index 00000000..a21ec1ea --- /dev/null +++ b/开发文档/6、后端/内容创建问题修复说明.md @@ -0,0 +1,93 @@ +# 内容创建问题修复说明 + +> 问题：souladmin 添加内容后显示「创建成功」，但目录和数据库未增加，前端也未显示。 + +## 根因分析 + +1. **两套后台数据源不一致** + - souladmin.quwanzhi.com 调用 soulapi.quwanzhi.com（Go API） + - soul.quwanzhi.com/admin 使用 Next.js API，list 此前仅从 bookData（静态）读取 + - 新建章节写入数据库，但 list 不查库，导致新建内容不显示 + +2. **PUT 创建未完整支持 partId/chapterId** + - 新建章节时 partId、chapterId、partTitle、chapterTitle 未正确写入数据库 + +## 已做修复 + +### 1. 修改 `/api/db/book` list 接口 +- **原逻辑**：仅从 bookData 读取 +- **现逻辑**：优先从数据库 chapters 表读取，再与 bookData 合并 +- **效果**：新建章节会立即出现在列表中 + +### 2. 修改 PUT 接口支持新建章节 +- 支持 body 传入 `partId`、`chapterId`、`partTitle`、`chapterTitle`、`isFree` +- 新建章节能正确写入数据库 + +### 3. 在 book-data 中新增 9.15 +- 章节 ID: 9.15 +- 标题: 第102场｜今年第一个红包你发给谁 +- 文件: book/第四篇｜真实的赚钱/第9章｜我在Soul上亲访的赚钱案例/9.15 第102场｜今年第一个红包你发给谁.md + +### 4. soul-admin 改用 soul.quwanzhi.com 作为 API +- 修改 soul-admin 的 API 基址：soulapi → soul.quwanzhi.com +- 在 Next.js 中为 souladmin.quwanzhi.com 配置 CORS + +## 部署步骤 + +### 步骤 1：部署 soul 主站（小型宝塔） + +```bash +cd /Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验 +# 按 .cursorrules 中的流程执行 +pnpm build +# 然后执行部署脚本 +``` + +### 步骤 2：同步 9.15 到数据库 + +部署后访问 soul.quwanzhi.com/admin，在内容管理页面点击「同步到数据库」，将包含 9.15 的 bookData 同步进库。 + +### 步骤 3：部署修改后的 soul-admin（KR 宝塔） + +```bash +# 将 一场soul的创业实验-永平 中的 soul-admin/dist 上传到 KR 宝塔 +cd /Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验-永平 +tar -czf soul-admin-dist.tar.gz soul-admin/dist +sshpass -p 'Zhiqun1984' scp -P 22022 soul-admin-dist.tar.gz root@43.139.27.93:/tmp/ +sshpass -p 'Zhiqun1984' ssh -p 22022 root@43.139.27.93 " + cd /www/wwwroot/自营/soul-admin + rm -rf dist.bak + mv dist dist.bak 2>/dev/null || true + tar -xzf /tmp/soul-admin-dist.tar.gz -C . + rm /tmp/soul-admin-dist.tar.gz +" +``` + +### 步骤 4：校验 + +1. 打开 souladmin.quwanzhi.com/content +2. 新建章节，确认创建后列表中立即出现 +3. 刷新 soul.quwanzhi.com 主站，确认新章节可读 + +## 注意事项 + +- souladmin 现改为调用 soul.quwanzhi.com，不再调用 soulapi（Go），需确保 soul 主站可用 +- 若仍需使用 Go API，需在 soul-api 源码中修复 list/create 逻辑 + +--- + +## 内容上传 API（供科室/Skill 调用） + +- **地址**：`POST /api/content/upload` +- **Content-Type**：`application/json` +- **Body 字段**： + - `title`（必填）：节标题 + - `price`：定价，默认 1 + - `content`：正文（Markdown 或 HTML） + - `format`：`markdown` | `html`，默认 `markdown` + - `images`：图片 URL 数组；正文中可用 `{{image_0}}`、`{{image_1}}` 占位，会替换为对应图片的 Markdown 图链 + - `partId`、`partTitle`、`chapterId`、`chapterTitle`：归属篇/章，可选 + - `isFree`：是否免费，默认 false + - `sectionId`：指定节 ID，不传则自动生成（如 `upload.标题slug.时间戳`） +- **返回**：`{ success, id, message, title, price, isFree, wordCount }` +- 写入数据库 `chapters` 表，list/目录会从库中读取并去重显示。 diff --git a/开发文档/6、后端/后端开发规范.md b/开发文档/6、后端/后端开发规范.md new file mode 100644 index 00000000..75b360a1 --- /dev/null +++ b/开发文档/6、后端/后端开发规范.md @@ -0,0 +1,64 @@ +# 后端开发规范 (Backend Specs) - 智能自生长文档 + +> **提示词功能 (Prompt Function)**: 将本文件拖入 AI 对话框，即可激活“Python 后端专家”角色，生成高效、规范的 FastAPI 代码。 + +## 1. 基础上下文 (The Two Basic Files) +### 1.1 角色档案：卡若 (Karuo) +- **核心**：开发快、性能好、支持 AI。 +- **习惯**：优先使用异步 (`async/await`)，强制类型提示 (`Type Hints`)。 + +### 1.2 技术栈 +- **语言**：Python 3.10+。 +- **框架**：FastAPI (Web), Pydantic (Validation), LangChain (AI)。 +- **数据**：Motor (Async Mongo), Redis。 + +## 2. 开发规范核心 (Master Content) +### 2.1 代码规范 +- **风格**：遵循 PEP 8，使用 Black 格式化。 +- **类型**：**强制 Type Hints** (如 `def get_user(id: int) -> User:`)。 +- **注释**：**强制中文注释**，解释“业务逻辑”与“AI 处理流程”。 +- **结构**： + - `app/routers`: 路由 + - `app/models`: Pydantic 模型 + - `app/services`: 业务逻辑 + - `app/core`: 配置与工具 + +### 2.2 AI 与安全规范 +- **AI 调用**：所有 LLM 调用必须封装在 Service 层，并包含重试机制与超时控制。 +- **安全**： + - **命令执行**：严禁使用 `os.system`，必须使用 `subprocess` 并校验参数。 + - **SQL/NoSQL**：使用 ORM 或参数化查询，防止注入。 + +### 2.3 异常与日志 +- **异常**：使用 FastAPI `HTTPException` 或自定义 Exception Handler。 +- **日志**：使用 `loguru` 或 Python 标准 `logging`，必须记录 Traceback。 + +### 2.4 依赖管理 +- **工具**：`pip` 或 `poetry`。 +- **原则**：提交代码前更新 `requirements.txt` 或 `pyproject.toml`。 + +## 3. AI 协作指令 (Expanded Function) +**角色**：你是我（卡若）的 Python 架构师。 +**任务**： +1. **代码实现**：生成 FastAPI 的 Router/Model/Service 代码。 +2. **AI 集成**：编写 LangChain 调用逻辑或向量检索代码。 +3. **逻辑图解**：用 Mermaid 展示异步处理流程。 + +### 示例 Mermaid (类图) +\`\`\`mermaid +classDiagram + class UserRouter { + +get_user() + +create_user() + } + class UserService { + +verify_token() + +process_ai_request() + } + class VectorStore { + +search_similarity() + +add_documents() + } + UserRouter --> UserService + UserService --> VectorStore +\`\`\` diff --git a/开发文档/6、后端/后端架构.md b/开发文档/6、后端/后端架构.md new file mode 100644 index 00000000..16c5f9dd --- /dev/null +++ b/开发文档/6、后端/后端架构.md @@ -0,0 +1,68 @@ +# 后端架构与业务逻辑 + +**我是卡若。** + +后端不仅仅是读写数据库，它是**业务逻辑的翻译官**。 + +我们要把“私域引流”、“内容分发”这些生意话术，翻译成代码逻辑。 + +## 1. 核心业务模块 + +### 1.1 内容服务 (Content Service) +这是最基础的。 +- **逻辑**: + - 扫描 `book/` 目录，生成目录树 (Tree)。 + - 解析 Markdown，提取 Frontmatter (标题、日期、标签)。 + - **缓存策略**: 既然是读文件，IO 慢。要在内存里做一个 LRU 缓存，读取一次后由内存直接返回，直到文件发生变更。 + +### 1.2 配置服务 (Config Service) +我的微信号、群二维码、价格，这些东西会变，不能写死在代码里。 +- **实现**: + - 一个 `config/settings.json` 文件（或者未来的 MongoDB `settings` 表）。 + - 接口: `GET /api/config`。 + - 前端拿到配置，动态展示微信号。 + +### 1.3 引流服务 (Lead Service) +这是赚钱的关键。 +- **埋点逻辑**: + - 记录 `UserView` (用户看了哪章)。 + - 记录 `UserClick` (用户点了“加微信”)。 + - 虽然不存库，但可以先打到日志文件里，或者调一个飞书的 Webhook，实时通知我“有人对这章感兴趣”。 + +## 2. 接口设计原则 + +- **RESTful**: 资源导向。`GET /articles`, `GET /articles/:id`。 +- **统一响应体**: + \`\`\`typescript + interface ApiResponse { + code: number; // 0 成功, >0 错误 + data: T; + msg: string; + } + \`\`\` + +## 3. 目录结构 (后端专用) + +\`\`\` +app/api/ +├── content/ # 内容相关 +├── config/ # 全局配置 +└── track/ # 埋点上报 + +lib/ +├── content/ +│ ├── parser.ts # Markdown 解析器 +│ └── cache.ts # 内存缓存 +├── config/ +│ └── loader.ts # 配置加载器 +└── db/ # 数据库连接 (预留) +\`\`\` + +## 4. 扩展性预留 + +- **鉴权中间件**: 现在是裸奔，未来加 `middleware.ts` 拦截 `/admin` 开头的请求。 +- **任务队列**: 未来如果生成文档太慢，就扔到 Redis 队列里异步处理。 + +--- +**卡若说：** +后端代码要写得像瑞士军刀一样，功能明确，结实耐用。 diff --git a/开发文档/6、后端/小程序支付参数.png b/开发文档/6、后端/小程序支付参数.png new file mode 100644 index 00000000..16d1881b Binary files /dev/null and b/开发文档/6、后端/小程序支付参数.png differ diff --git a/开发文档/6、后端/算法/README.md b/开发文档/6、后端/算法/README.md new file mode 100644 index 00000000..676013c6 --- /dev/null +++ b/开发文档/6、后端/算法/README.md @@ -0,0 +1,13 @@ +# 后端业务算法说明 + +> **以代码为准**：实现变更时请同步更新本目录下对应文档。 +> 代码位置：`soul-api/internal/handler/`（见下表）。 + +| 文档 | 说明 | 主要代码 | HTTP 入口（管理端 / 公共） | +|------|------|----------|---------------------------| +| [算法-RFM用户价值分层.md](./算法-RFM用户价值分层.md) | RFM 与 RFM+ 综合分、分层档位 | `admin_rfm.go`、`db.go` | `GET /api/db/users/rfm`、`GET /api/db/users/rfm-single`；用户列表内嵌 RFM | +| [算法-用户旅程阶段统计.md](./算法-用户旅程阶段统计.md) | 各阶段人数与按阶段拉用户 | `admin_rfm.go` | `GET /api/db/users/journey-stats`、`GET /api/db/users/journey-users` | +| [算法-找伙伴匹配与配额.md](./算法-找伙伴匹配与配额.md) | 匹配池、选人逻辑、次数配额 | `match.go`、`user.go`（配额下发） | `POST /api/match/users`、`POST /api/miniprogram/match/users`、`GET /api/match/config` | +| [算法-存客宝找伙伴留资同步.md](./算法-存客宝找伙伴留资同步.md) | 匹配结果推存客宝（非站内选人） | `ckb.go` | `POST /api/ckb/match`、`POST /api/miniprogram/ckb/match` | + +**说明**：口语中的「IFM」与本项目代码无对应实现；用户价值分层以 **RFM / RFM+** 为准（见 RFM 文档）。 diff --git a/开发文档/6、后端/算法/算法-RFM用户价值分层.md b/开发文档/6、后端/算法/算法-RFM用户价值分层.md new file mode 100644 index 00000000..3490657a --- /dev/null +++ b/开发文档/6、后端/算法/算法-RFM用户价值分层.md @@ -0,0 +1,67 @@ +# RFM 用户价值分层 + +## 1. 目的 + +对「有订单」用户做价值排序与分层（Are you good），供管理端 RFM 排行与用户列表展示。实现：`soul-api/internal/handler/admin_rfm.go`（及用户列表中的轻量版：`db.go`）。 + +## 2. 订单口径 + +参与聚合的订单需满足： + +```text +orders.status IN ('paid', 'success', 'completed') +``` + +单笔金额汇总为 **Monetary（M）**，订单笔数为 **Frequency（F）**，最近一次订单时间为 **Recency（R）** 的起点。 + +## 3. 子分归一化（0～100） + +在同一批计算中，先求全体用户的 `maxRecency`（天数）、`maxFreq`（笔数）、`maxMonetary`（金额）： + +- **R 分**：`rScore = (1 - recencyDays / maxRecency) * 100`（`maxRecency > 0` 时） +- **F 分**：`fScore = frequency / maxFreq * 100`（`maxFreq > 0` 时） +- **M 分**：`mScore = monetary / maxMonetary * 100`（`maxMonetary > 0` 时） + +推荐分、轨迹分同理按 `maxReferral`、`maxTrack` 归一化，且不超过 100（`min(ratio*100, 100)`）。 + +## 4. 全量 RFM 排行：`GET /api/db/users/rfm`（RFM+ 六维） + +函数：`calcRFMScoreForUserExt` + +| 维度 | 权重 | 含义 | +|------|------|------| +| R | 25% | 距最近付费天数（越近越高） | +| F | 20% | 付费订单笔数 | +| M | 20% | 累计付费金额 | +| 推荐人数 | 15% | `users.referral_count`（批内 max 归一化） | +| 行为轨迹 | 10% | `user_tracks` 条数（批内 max 归一化） | +| 资料完善 | 10% | `phone` / `mbti` / `industry` 中 **至少 2 项有值** 则记 100，否则 0 | + +最终：`total = 加权和`，`math.Round(total)`，范围约 0～100。 + +## 5. 分层：`calcRFMLevel(score)` + +| 档位 | 条件 | +|------|------| +| S | score ≥ 85 | +| A | score ≥ 70 | +| B | score ≥ 50 | +| C | score ≥ 30 | +| D | score < 30 | + +## 6. 单用户：`GET /api/db/users/rfm-single?userId=` + +对有订单用户计算 **三维度 RFM**（`calcRFMScoreForUser`，不合并推荐/轨迹/资料），再套同一套 `calcRFMLevel`。无订单则返回 `rfm: null`（以实际 JSON 为准）。 + +## 7. 与用户列表分页的差异（重要） + +管理端用户列表在 `db.go` 中对**当前页**用户调用 `calcRFMScoreForUser`（内部为 `calcRFMScoreForUserExt(..., rfmExtras{}, 0, 0)`）： + +- **仅使用 R、F、M 三维**（推荐、轨迹、资料权重为 0）。 +- 与 `GET /api/db/users/rfm` 的 **RFM+ 六维** 分数可能不一致。 + +运营与产品对比「列表里的 RFM」与「RFM 排序页」时需注意上述差异。若需统一，属产品改动（需在列表接口批量拉轨迹/推荐并调 `calcRFMScoreForUserExt`）。 + +## 8. 相关前端 + +管理端用户列表 RFM 列与排序：`soul-admin` 中 `UsersPage.tsx`（`/api/db/users/rfm` 与列表接口切换）。 diff --git a/开发文档/6、后端/算法/算法-存客宝找伙伴留资同步.md b/开发文档/6、后端/算法/算法-存客宝找伙伴留资同步.md new file mode 100644 index 00000000..84becbaa --- /dev/null +++ b/开发文档/6、后端/算法/算法-存客宝找伙伴留资同步.md @@ -0,0 +1,33 @@ +# 存客宝：找伙伴留资同步 + +## 1. 定位 + +`CKBMatch` **不负责**站内匹配选人（见 [算法-找伙伴匹配与配额.md](./算法-找伙伴匹配与配额.md)）。本接口将用户提交的匹配相关留资 **转发到存客宝 HTTP API**，并配合本地线索表做去重与结果回写。 + +实现：`soul-api/internal/handler/ckb.go` 中 `CKBMatch`。 + +## 2. 路由 + +- `POST /api/ckb/match` +- `POST /api/miniprogram/ckb/match` + +## 3. 入参（JSON） + +包含但不限于：`matchType`、`phone`、`wechat`、`userId`、`nickname`、`matchedUser`（可为结构化对象）。**手机号与微信号至少填一个**，否则 400。 + +## 4. 流程摘要 + +1. `nickname` 默认 `"-"`。 +2. **5 分钟去重**：`existsUnifiedLeadRecent(..., match, userId, matchSource, phone, wechat, 5*time.Minute)`，其中 `matchSource = "match_" + matchType`。若命中，直接返回成功并带 `repeatedSubmit: true`。 +3. `ckbLeadSaveUnified` 写入统一线索记录，得到 `leadID`。 +4. 组装存客宝请求：`timestamp`、`source`（固定文案如「创业实验-找伙伴匹配」）、`tags`、`siteTags`、`remark`、`phone`/`wechatId`/`name`、`apiKey`、`sign`（`ckbSign`）。 +5. `portrait`：`type: 4`，`sourceData` 含 `action: match`、`matchType`、`matchLabel`、`userId`、`device`、`timestamp`；`uniqueId` 含手机、微信与时间戳拼接。 +6. `http.Post(ckbAPIURL, ...)`；网络错误或非 200 业务码时仍可能对用户返回「提交成功」，同时 `markLeadPushFailed` / `applyCkbLeadPushOutcome` 记录后台状态（与 `CKBJoin` 等一致的用户侧友好策略）。 + +## 5. 配置 + +`ckbAPIURL`、`ckbAPIKey` 等来自环境/配置（见 `ckb.go` 包级变量与部署说明），不在此重复。 + +## 6. 运维提示 + +日志关键字：`[CKBMatch]`。排查时对照存客宝返回 `code`/`message` 与本地线索表推送状态字段。 diff --git a/开发文档/6、后端/算法/算法-找伙伴匹配与配额.md b/开发文档/6、后端/算法/算法-找伙伴匹配与配额.md new file mode 100644 index 00000000..7556b646 --- /dev/null +++ b/开发文档/6、后端/算法/算法-找伙伴匹配与配额.md @@ -0,0 +1,52 @@ +# 找伙伴：匹配与配额 + +实现：`soul-api/internal/handler/match.go`；配额在用户信息等接口中下发参见 `user.go`。 + +## 1. 接口 + +- `POST /api/match/users`、`POST /api/miniprogram/match/users`：`MatchUsers` +- `GET /api/match/config`、`GET /api/miniprogram/match/config`：匹配类型与 `match_config` + +## 2. 发起前校验 + +1. 用户存在。 +2. 用户至少填写 **手机号或微信号**（其一非空），否则 `ERR_PROFILE_INCOMPLETE`。 +3. **配额**：若 `user.has_full_book` 为真，跳过配额；否则 `RemainToday <= 0` 则 `QUOTA_EXCEEDED`。 + +## 3. 匹配次数配额 `GetMatchQuota` + +- **免费次数**：来自 `system_config.config_key = 'match_config'` 的 JSON 字段 `freeMatchLimit`；经 `normalizeFreeMatchLimit`：**大于 1 时按 1 生效**（终身免费匹配最多 1 次，不按自然日重置）。 +- **已购次数**：`orders` 中 `user_id` 匹配、`product_type = 'match'`、`status = 'paid'` 的笔数计为 `purchasedTotal`。 +- **已用次数**：`match_records` 全量条数相对免费额度超出部分，与已购对比取逻辑上的「已用已购」`purchasedUsed`，得 `purchasedRemain`、`freeRemain`（字段名 `freeRemainToday` / `remainToday` 为历史命名，语义为**当前剩余可匹配次数**）。 +- **今日统计**：`matchesUsedToday` 为当日 `match_records` 条数，仅作统计展示。 + +## 4. 候选池 `poolSettings`（`match_config` JSON） + +从 `poolSettings` 读取： + +- `poolSource`：字符串或字符串数组，多选为 **并集**（OR）。取值示例：`vip`、`complete`、`all`。 + - `vip`：`is_vip = 1 AND vip_expire_date > NOW()` + - `complete`：资料 SQL（手机号 + 非默认昵称 + 头像，见代码常量 `completeProfileSQL`） + - `all`：有手机或微信即可 + - 若未配置有效 OR 条件，回退为仅 VIP。 +- `matchType == 'partner'`（找伙伴）且池子中 **不含** `vip` 与 `all` 时，**强制追加** VIP 条件。 +- 可选开关：`requirePhone`、`requireNickname`、`requireAvatar`、`requireBusiness`（供需字段非空）。 + +## 5. 排除与排序、选人 + +- 排除：**当天**已向之匹配过的 `matched_user_id`（`match_records`，发起者 `user_id`，`created_at >= CURDATE()`）。 +- 查询：`id != 发起者`，上述池子与过滤，`ORDER BY created_at DESC`，**LIMIT 20**。 +- **选人**：非真随机。若候选数 > 1：`idx = users[0].CreatedAt.Unix() % len(users)`，取 `users[idx]`（与列表首条创建时间相关）。 + +## 6. 返回中的「匹配度」与兴趣点 + +- `matchScore = 80 + (matchedUser.created_at.Unix() % 20)`：**展示用**，非相似度模型。 +- `commonInterests`：固定文案模板，非基于画像计算。 + +## 7. 写库 + +成功时写入 `match_records`（含 `matchType`，默认 `partner`，及请求体中的发起方 `phone`/`wechatId` 可选字段）。 + +## 8. 与存客宝的关系 + +站内选人逻辑仅在本文件描述。匹配完成后如需把线索推到存客宝，见 [算法-存客宝找伙伴留资同步.md](./算法-存客宝找伙伴留资同步.md)（`CKBMatch`）。 diff --git a/开发文档/6、后端/算法/算法-用户旅程阶段统计.md b/开发文档/6、后端/算法/算法-用户旅程阶段统计.md new file mode 100644 index 00000000..e1a41508 --- /dev/null +++ b/开发文档/6、后端/算法/算法-用户旅程阶段统计.md @@ -0,0 +1,51 @@ +# 用户旅程阶段统计 + +## 1. 说明 + +本模块是**运营漏斗计数规则**：按固定 SQL 语义统计各阶段人数，并支持按阶段拉取用户列表。**不是**机器学习或推荐模型。 + +实现：`soul-api/internal/handler/admin_rfm.go` 中 `DBUsersJourneyStats`、`DBUsersJourneyUsers`。 + +与 **用户旅程触达规则**（`user_rules` 表、`model.UserRule`）区分：后者为管理端配置的触发条件 + 动作（弹窗等），由小程序拉取规则并标记完成；本文仅描述后端 **journey-stats / journey-users** 的统计定义。 + +## 2. `GET /api/db/users/journey-stats` + +返回 `stats` 字典，键与含义如下（与代码一致）。 + +| 键 | 统计含义 | +|----|----------| +| `register` | `users` 表总行数 | +| `browse` | `user_tracks` 中 `action = 'view_chapter'` 的去重 `user_id` 数 | +| `bind_phone` | `phone IS NOT NULL AND phone != ''` 的用户数 | +| `first_pay` | 存在 `orders.status IN ('paid','success','completed')` 的去重 `user_id` 数 | +| `fill_profile` | `mbti IS NOT NULL OR industry IS NOT NULL` 的用户数 | +| `match` | `user_tracks` 中 `action = 'match'` 的去重 `user_id` 数 | +| `vip` | `is_vip = 1` 的用户数 | +| `distribution` | `referral_code` 非空 **且** `earnings > 0` 的用户数（注意：列表接口对 earnings 使用 `COALESCE`，与统计口径略有不同） | +| `tip_pay` | 订单 `status IN ('paid','completed')` 且 `product_type = 'link_karuo_tip'` 的去重用户数 | +| `balance_recharge` | 同上，`product_type = 'balance_recharge'` | +| `match_pay` | 同上，`product_type = 'match'` | +| `active_7d` | 最近 7 天内有任意 `user_tracks` 记录的去重 `user_id` | +| `active_30d` | 最近 30 天同上 | +| `register_7d` | `users.created_at` 在最近 7 天内的用户数 | + +## 3. `GET /api/db/users/journey-users?stage=&limit=` + +- `limit` 默认 20，最大 100。 +- `stage` 无效时返回 400。 + +| stage | 用户范围 | +|-------|----------| +| `register` | 全部用户，`created_at DESC` | +| `browse` | 出现过 `view_chapter` 的用户 | +| `bind_phone` | 已绑手机 | +| `first_pay` | 存在已支付类订单的用户 | +| `fill_profile` | `mbti` 或 `industry` 有值 | +| `match` | 出现过 `user_tracks.action = 'match'` | +| `vip` | `is_vip = true` | +| `distribution` | `referral_code` 非空且 `COALESCE(earnings,0) > 0` | +| `tip_pay` | 购买过 `link_karuo_tip` 的用户 | +| `balance_recharge` | 购买过 `balance_recharge` 的用户 | +| `match_pay` | 购买过 `match` 商品的用户 | + +列表仅返回 `id`、`nickname`、`phone`、`createdAt`（RFC3339）。 diff --git a/开发文档/7、数据库/README.md b/开发文档/7、数据库/README.md new file mode 100644 index 00000000..afa9562b --- /dev/null +++ b/开发文档/7、数据库/README.md @@ -0,0 +1,14 @@ +# 7、数据库 + +> MySQL 表设计与变更管理约定。具体表结构以 `soul-api/internal/model` 与迁移/SQL 为准。 + +## 本目录文件 + +| 文件 | 说明 | +|------|------| +| [数据库设计.md](./数据库设计.md) | 表结构设计说明 | +| [数据库管理规范.md](./数据库管理规范.md) | 管理、备份与变更规范 | + +迁移与检查类说明另见 [8、部署/VIP功能-数据库迁移说明.md](../8、部署/VIP功能-数据库迁移说明.md)、[8、部署/代码逻辑和数据库最终检查清单.md](../8、部署/代码逻辑和数据库最终检查清单.md)。 + +返回 [开发文档索引](../索引.md)。 diff --git a/开发文档/7、数据库/数据库管理规范.md b/开发文档/7、数据库/数据库管理规范.md new file mode 100644 index 00000000..ce5debae --- /dev/null +++ b/开发文档/7、数据库/数据库管理规范.md @@ -0,0 +1,62 @@ +# 数据库管理规范 (DB Specs) - 智能自生长文档 + +> **提示词功能 (Prompt Function)**: 将本文件拖入 AI 对话框，即可激活“DBA”角色，生成安全的 SQL/Mongo 脚本与 ER 图。 + +## 1. 基础上下文 (The Two Basic Files) +### 1.1 角色档案：卡若 (Karuo) +- **核心**：数据无价，安全第一。 +- **选型**：Mongo (业务+向量) + MySQL (事务/辅助)。 + +### 1.2 操作规范 +- **导入**：必须带 `--resumeFrom` 和 `--drop` (防止重复/中断)。 +- **命名**：`traffic_pools` (严禁 `traffic_words`)。 + +## 2. 数据库规范核心 (Master Content) +### 2.1 选型策略 +- **MongoDB**: + - **业务数据**：用户、日志、流量池。 + - **AI 向量**：存储 Embedding 向量 (Atlas Vector Search)。 +- **MySQL**: 强事务资金流水 (如需)。 + +### 2.2 连接信息 (Internal) +- **卡若私域**: 10.88.182.62:3306 +- **腾讯云**: 56b4c23f6853c...:14413 +- **Mongo**: (Env Config) + +### 2.3 集合命名 +- `users`: 用户 +- `scenarios`: 场景获客 +- `traffic_pools`: 流量池 (含 `embedding` 字段) +- `orders`: 分润订单 +- `knowledge_base`: AI 知识库 (含 `embedding` 字段) + +### 2.4 AI 向量索引 (Vector Index) +- **字段**：通常命名为 `embedding` 或 `vector`。 +- **索引类型**：使用 KNN 或 ANN 索引 (如 HNSW)。 +- **查询**：支持 `$vectorSearch` (Mongo Atlas) 或类似语义检索语法。 + +### 2.5 安全与索引 +- **安全**：密码 Hash (Argon2), 手机号加密。 +- **常规索引**：`openid`, `mobile`, `inviter_id` 必建索引。 + +## 3. AI 协作指令 (Expanded Function) +**角色**：你是我（卡若）的 DBA。 +**任务**： +1. **脚本生成**：生成 MongoDB 聚合查询 (`aggregate`) 或 MySQL DDL/DML。 +2. **向量配置**：生成向量索引的定义 JSON。 +3. **结构可视化**：用 Mermaid 生成 ER 图。 + +### 示例 Mermaid (ER图) +\`\`\`mermaid +erDiagram + User ||--o{ Order : places + User ||--o{ TrafficPool : owns + TrafficPool { + string content + array embedding "Vector[1536]" + } + Order { + string orderId + float amount + } +\`\`\` diff --git a/开发文档/7、数据库/数据库设计.md b/开发文档/7、数据库/数据库设计.md new file mode 100644 index 00000000..3d4d6089 --- /dev/null +++ b/开发文档/7、数据库/数据库设计.md @@ -0,0 +1,708 @@ +# 数据库设计 + +**我是卡若。** + +这个项目当前使用LocalStorage做数据持久化,但未来会切换到MongoDB。这个文档定义了完整的数据库设计方案。 + +--- + +## 一、数据库选型 + +### 1.1 为什么选MongoDB? + +1. **文档型数据库**: 适合内容类产品,数据结构灵活 +2. **无Schema约束**: 快速迭代不需要频繁改表结构 +3. **JSON原生支持**: 前后端数据格式一致 +4. **横向扩展能力**: 支持未来大规模用户增长 +5. **向量搜索支持**: MongoDB Atlas支持向量检索(未来AI功能) + +### 1.2 当前方案 vs 未来方案 + +**当前方案** (LocalStorage): +\`\`\`javascript +// 优点 +- 无需服务器 +- 开发调试方便 +- 适合MVP验证 + +// 缺点 +- 数据仅存浏览器本地 +- 多设备无法同步 +- 数据容易丢失 +\`\`\` + +**未来方案** (MongoDB): +\`\`\`javascript +// 优点 +- 数据持久化存储 +- 多设备数据同步 +- 支持复杂查询 +- 支持事务(ACID) + +// 迁移计划 +1. 安装MongoDB驱动 +2. 创建数据库连接 +3. 逐步替换LocalStorage +4. 添加数据迁移脚本 +\`\`\` + +--- + +## 二、数据库连接配置 + +### 2.1 本地开发环境 + +\`\`\`bash +# MongoDB本地安装 +brew install mongodb-community@6.0 + +# 启动MongoDB +brew services start mongodb-community@6.0 + +# 连接字符串 +mongodb://localhost:27017/soul-experiment +\`\`\` + +### 2.2 生产环境 (MongoDB Atlas) + +\`\`\`bash +# 连接字符串 +mongodb+srv://:@cluster0.mongodb.net/soul-experiment?retryWrites=true&w=majority +\`\`\` + +### 2.3 环境变量配置 + +**.env.local**: +\`\`\`bash +# MongoDB配置 +MONGODB_URI=mongodb://localhost:27017/soul-experiment +MONGODB_DB_NAME=soul-experiment + +# 或使用云数据库 +# MONGODB_URI=mongodb://10.88.182.62:3306/soul-experiment +# MONGODB_USERNAME=root +# MONGODB_PASSWORD=Vtka(agu)-1 +\`\`\` + +--- + +## 三、数据模型设计 + +### 3.1 用户集合 (users) + +**集合名称**: `users` + +**索引**: +\`\`\`javascript +{ + phone: 1, // 唯一索引 + referralCode: 1, // 唯一索引 + referredBy: 1, // 普通索引 + createdAt: -1 // 降序索引 +} +\`\`\` + +**文档结构**: +\`\`\`javascript +{ + _id: ObjectId("65a1234567890abcdef12345"), + phone: "15880802661", // 手机号 + nickname: "卡若", // 昵称 + avatar: "https://cdn.example.com/avatar.jpg", // 头像 + openid: "wx_openid_xxx", // 微信openid + unionid: "wx_unionid_xxx", // 微信unionid + + // 购买记录 + purchasedSections: [ // 已购章节 + "1.1", "1.2", "3.3" + ], + hasFullBook: false, // 是否购买整本书 + + // 分销数据 + referralCode: "REFABC123", // 推荐码 + referredBy: "REFXYZ789", // 推荐人的码 + referralCount: 28, // 推荐人数 + earnings: 256.80, // 总收益(元) + pendingEarnings: 128.90, // 待提现(元) + withdrawnEarnings: 127.90, // 已提现(元) + + // 阅读数据 + readingTime: 12480, // 阅读时长(秒) + readingProgress: 45, // 阅读进度(%) + lastReadSection: "3.2", // 最后阅读章节 + lastReadAt: ISODate("2025-01-14T12:00:00Z"), + + // 权限 + isAdmin: false, // 是否管理员 + isBanned: false, // 是否封禁 + + // 时间戳 + createdAt: ISODate("2025-01-01T00:00:00Z"), + updatedAt: ISODate("2025-01-14T12:00:00Z") +} +\`\`\` + +**查询示例**: +\`\`\`javascript +// 根据手机号查找用户 +db.users.findOne({ phone: "15880802661" }) + +// 根据推荐码查找用户 +db.users.findOne({ referralCode: "REFABC123" }) + +// 查找某推荐人的所有下级 +db.users.find({ referredBy: "REFABC123" }) + +// 查找收益前10的推广者 +db.users.find({}).sort({ earnings: -1 }).limit(10) +\`\`\` + +--- + +### 3.2 订单集合 (orders) + +**集合名称**: `orders` + +**索引**: +\`\`\`javascript +{ + orderId: 1, // 唯一索引 + userId: 1, // 普通索引 + status: 1, // 普通索引 + createdAt: -1 // 降序索引 +} +\`\`\` + +**文档结构**: +\`\`\`javascript +{ + _id: ObjectId("65a1234567890abcdef12345"), + orderId: "ORDER_1705200000_abc123", // 订单号 + userId: ObjectId("65a1234567890abcdef00001"), // 用户ID + userPhone: "15880802661", // 用户手机号 + userNickname: "卡若", // 用户昵称 + + // 订单信息 + type: "section", // "section" | "fullbook" + sectionId: "1.1", // 章节ID(单章购买时) + sectionTitle: "自行车荷总...", // 章节标题 + amount: 1.00, // 金额(元) + + // 支付信息 + paymentMethod: "wechat", // 支付方式 + transactionId: "wx_pay_123456789", // 第三方交易号 + status: "completed", // "pending" | "completed" | "failed" | "refunded" + + // 分销信息 + referralCode: "REFXYZ789", // 推荐码 + referrerUserId: ObjectId("65a1234567890abcdef00002"), // 推荐人ID + referrerEarnings: 0.90, // 推荐人佣金(元) + + // 时间戳 + createdAt: ISODate("2025-01-14T12:00:00Z"), // 创建时间 + paidAt: ISODate("2025-01-14T12:05:00Z"), // 支付时间 + expireAt: ISODate("2025-01-14T12:30:00Z"), // 过期时间(30分钟) + updatedAt: ISODate("2025-01-14T12:05:00Z") +} +\`\`\` + +**查询示例**: +\`\`\`javascript +// 查找用户所有订单 +db.orders.find({ userId: ObjectId("65a...") }).sort({ createdAt: -1 }) + +// 查找待支付订单 +db.orders.find({ status: "pending", expireAt: { $gt: new Date() } }) + +// 统计今日收益 +db.orders.aggregate([ + { $match: { + status: "completed", + paidAt: { + $gte: ISODate("2025-01-14T00:00:00Z"), + $lt: ISODate("2025-01-15T00:00:00Z") + } + }}, + { $group: { + _id: null, + totalRevenue: { $sum: "$amount" }, + totalOrders: { $sum: 1 } + }} +]) + +// 查找某推荐人的所有佣金记录 +db.orders.find({ + referralCode: "REFABC123", + status: "completed" +}) +\`\`\` + +--- + +### 3.3 提现记录集合 (withdrawals) + +**集合名称**: `withdrawals` + +**索引**: +\`\`\`javascript +{ + userId: 1, // 普通索引 + status: 1, // 普通索引 + createdAt: -1 // 降序索引 +} +\`\`\` + +**文档结构**: +\`\`\`javascript +{ + _id: ObjectId("65a1234567890abcdef12345"), + withdrawalId: "WD_1705200000_abc123", // 提现单号 + userId: ObjectId("65a1234567890abcdef00001"), // 用户ID + userPhone: "15880802661", // 用户手机号 + userNickname: "卡若", // 用户昵称 + + // 提现信息 + amount: 100.00, // 提现金额(元) + method: "wechat", // "wechat" | "alipay" + account: "微信号或支付宝账号", + name: "真实姓名", + + // 状态 + status: "pending", // "pending" | "completed" | "rejected" + rejectReason: "", // 拒绝原因 + + // 时间戳 + createdAt: ISODate("2025-01-14T12:00:00Z"), // 申请时间 + completedAt: ISODate("2025-01-14T14:00:00Z"), // 完成时间 + updatedAt: ISODate("2025-01-14T14:00:00Z") +} +\`\`\` + +**查询示例**: +\`\`\`javascript +// 查找待审核提现 +db.withdrawals.find({ status: "pending" }).sort({ createdAt: 1 }) + +// 查找用户提现记录 +db.withdrawals.find({ userId: ObjectId("65a...") }).sort({ createdAt: -1 }) + +// 统计今日提现金额 +db.withdrawals.aggregate([ + { $match: { + status: "completed", + completedAt: { + $gte: ISODate("2025-01-14T00:00:00Z"), + $lt: ISODate("2025-01-15T00:00:00Z") + } + }}, + { $group: { + _id: null, + totalAmount: { $sum: "$amount" }, + totalCount: { $sum: 1 } + }} +]) +\`\`\` + +--- + +### 3.4 章节内容集合 (sections) + +**集合名称**: `sections` + +**索引**: +\`\`\`javascript +{ + sectionId: 1, // 唯一索引 + isFree: 1, // 普通索引 + createdAt: -1 // 降序索引 +} +\`\`\` + +**文档结构**: +\`\`\`javascript +{ + _id: ObjectId("65a1234567890abcdef12345"), + sectionId: "1.1", // 章节ID + + // 章节信息 + title: "自行车荷总:一个行业做到极致是什么样", + content: "# 自行车荷总\n\n...", // Markdown内容 + summary: "本章讲述了...", // 摘要 + keywords: ["创业", "行业深耕"], // 关键词 + + // 层级关系 + partId: "part-1", // 所属篇 + partTitle: "真实的人", + chapterId: "chapter-1", // 所属章 + chapterTitle: "人与人之间的底层逻辑", + + // 定价 + price: 1, // 价格(元) + isFree: true, // 是否免费 + unlockAfterDays: 0, // 定时解锁(天数) + + // 统计数据 + viewCount: 1234, // 浏览次数 + purchaseCount: 456, // 购买次数 + avgReadingTime: 180, // 平均阅读时长(秒) + + // 文件信息 + filePath: "book/_第一篇｜真实的人/...", + wordCount: 3580, // 字数 + + // 发布状态 + status: "published", // "draft" | "published" + publishedAt: ISODate("2025-01-01T00:00:00Z"), + + // 时间戳 + createdAt: ISODate("2025-01-01T00:00:00Z"), + updatedAt: ISODate("2025-01-14T12:00:00Z") +} +\`\`\` + +**查询示例**: +\`\`\`javascript +// 获取所有免费章节 +db.sections.find({ isFree: true }) + +// 获取最新发布的10章 +db.sections.find({ status: "published" }) + .sort({ publishedAt: -1 }) + .limit(10) + +// 按浏览量排序 +db.sections.find().sort({ viewCount: -1 }).limit(10) + +// 全文搜索(需创建文本索引) +db.sections.createIndex({ + title: "text", + content: "text", + keywords: "text" +}) +db.sections.find({ $text: { $search: "创业 私域" } }) +\`\`\` + +--- + +### 3.5 阅读记录集合 (reading_logs) + +**集合名称**: `reading_logs` + +**索引**: +\`\`\`javascript +{ + userId: 1, + sectionId: 1, + createdAt: -1 +} +\`\`\` + +**文档结构**: +\`\`\`javascript +{ + _id: ObjectId("65a1234567890abcdef12345"), + userId: ObjectId("65a1234567890abcdef00001"), + sectionId: "3.2", + + // 阅读数据 + progress: 68, // 阅读进度(%) + readingTime: 180, // 阅读时长(秒) + scrollDepth: 75, // 滚动深度(%) + + // 设备信息 + device: "iPhone 14 Pro", + browser: "Safari", + ip: "121.xxx.xxx.xxx", + + // 时间戳 + createdAt: ISODate("2025-01-14T12:00:00Z") +} +\`\`\` + +--- + +### 3.6 系统配置集合 (settings) + +**集合名称**: `settings` + +**文档结构**: +\`\`\`javascript +{ + _id: "global_settings", + + // 分润配置 + distributorShare: 90, // 推广者分成(%) + authorShare: 10, // 作者分成(%) + + // 定价配置 + sectionPrice: 1, // 单章价格(元) + fullBookPrice: 9.9, // 整书价格(元) + + // 支付配置 + paymentMethods: { + wechat: { + enabled: true, + appId: "wx432c93e275548671", + merchantId: "1318592501", + apiKey: "***" + }, + alipay: { + enabled: true, + partnerId: "2088511801157159", + securityKey: "***" + } + }, + + // 营销配置 + partyGroupQrCode: "https://...", + bannerText: "每天早上6-9点，Soul派对房不见不散", + + // 时间戳 + updatedAt: ISODate("2025-01-14T12:00:00Z") +} +\`\`\` + +--- + +## 四、数据迁移方案 + +### 4.1 LocalStorage to MongoDB + +**步骤1**: 导出LocalStorage数据 +\`\`\`javascript +// 导出脚本 scripts/export-localstorage.js +const fs = require('fs') + +const users = JSON.parse(localStorage.getItem('users') || '[]') +const orders = JSON.parse(localStorage.getItem('all_purchases') || '[]') +const settings = JSON.parse(localStorage.getItem('app_settings') || '{}') + +const exportData = { users, orders, settings } +fs.writeFileSync('data-export.json', JSON.stringify(exportData, null, 2)) +\`\`\` + +**步骤2**: 导入MongoDB +\`\`\`javascript +// 导入脚本 scripts/import-mongodb.js +const { MongoClient } = require('mongodb') +const fs = require('fs') + +async function importData() { + const client = await MongoClient.connect(process.env.MONGODB_URI) + const db = client.db('soul-experiment') + + const data = JSON.parse(fs.readFileSync('data-export.json', 'utf8')) + + // 导入用户 + await db.collection('users').insertMany(data.users) + + // 导入订单 + await db.collection('orders').insertMany(data.orders) + + // 导入配置 + await db.collection('settings').insertOne({ + _id: 'global_settings', + ...data.settings + }) + + client.close() + console.log('数据导入完成') +} + +importData() +\`\`\` + +--- + +## 五、数据库操作封装 + +### 5.1 用户操作 + +\`\`\`typescript +// lib/db/users.ts +import { MongoClient, ObjectId } from 'mongodb' + +export async function createUser(userData: Partial) { + const db = await getDatabase() + const result = await db.collection('users').insertOne({ + ...userData, + referralCode: generateReferralCode(), + earnings: 0, + pendingEarnings: 0, + withdrawnEarnings: 0, + referralCount: 0, + purchasedSections: [], + hasFullBook: false, + createdAt: new Date(), + updatedAt: new Date() + }) + return result.insertedId +} + +export async function findUserByPhone(phone: string) { + const db = await getDatabase() + return await db.collection('users').findOne({ phone }) +} + +export async function updateUserEarnings( + userId: ObjectId, + amount: number +) { + const db = await getDatabase() + await db.collection('users').updateOne( + { _id: userId }, + { + $inc: { + earnings: amount, + pendingEarnings: amount + }, + $set: { updatedAt: new Date() } + } + ) +} +\`\`\` + +### 5.2 订单操作 + +\`\`\`typescript +// lib/db/orders.ts +export async function createOrder(orderData: Partial) { + const db = await getDatabase() + const orderId = `ORDER_${Date.now()}_${randomString()}` + + const result = await db.collection('orders').insertOne({ + orderId, + ...orderData, + status: 'pending', + createdAt: new Date(), + expireAt: new Date(Date.now() + 30 * 60 * 1000), // 30分钟 + updatedAt: new Date() + }) + + return { orderId, _id: result.insertedId } +} + +export async function completeOrder(orderId: string) { + const db = await getDatabase() + const order = await db.collection('orders').findOne({ orderId }) + + if (!order) throw new Error('订单不存在') + + // 更新订单状态 + await db.collection('orders').updateOne( + { orderId }, + { + $set: { + status: 'completed', + paidAt: new Date(), + updatedAt: new Date() + } + } + ) + + // 解锁内容 + if (order.type === 'section') { + await db.collection('users').updateOne( + { _id: order.userId }, + { $addToSet: { purchasedSections: order.sectionId } } + ) + } else if (order.type === 'fullbook') { + await db.collection('users').updateOne( + { _id: order.userId }, + { $set: { hasFullBook: true } } + ) + } + + // 分配佣金 + if (order.referralCode) { + const referrer = await db.collection('users').findOne({ + referralCode: order.referralCode + }) + + if (referrer) { + const commission = order.amount * 0.9 // 90%佣金 + await updateUserEarnings(referrer._id, commission) + + // 记录佣金 + await db.collection('orders').updateOne( + { orderId }, + { $set: { + referrerUserId: referrer._id, + referrerEarnings: commission + }} + ) + } + } +} +\`\`\` + +--- + +## 六、数据备份策略 + +### 6.1 自动备份 + +\`\`\`bash +# 每日凌晨3点自动备份 +0 3 * * * mongodump --uri="mongodb://localhost:27017/soul-experiment" --out="/backup/$(date +\%Y\%m\%d)" +\`\`\` + +### 6.2 恢复数据 + +\`\`\`bash +# 恢复指定日期的备份 +mongorestore --uri="mongodb://localhost:27017/soul-experiment" --dir="/backup/20250114" +\`\`\` + +--- + +## 七、性能优化 + +### 7.1 索引优化 + +\`\`\`javascript +// 创建复合索引 +db.orders.createIndex({ userId: 1, createdAt: -1 }) +db.orders.createIndex({ status: 1, expireAt: 1 }) +db.users.createIndex({ referralCode: 1 }, { unique: true }) + +// 查看索引使用情况 +db.orders.find({ userId: ObjectId("...") }).explain("executionStats") +\`\`\` + +### 7.2 查询优化 + +\`\`\`javascript +// 使用投影减少数据传输 +db.users.find( + { phone: "15880802661" }, + { nickname: 1, referralCode: 1, earnings: 1 } +) + +// 使用聚合管道优化复杂查询 +db.orders.aggregate([ + { $match: { status: "completed" } }, + { $lookup: { + from: "users", + localField: "userId", + foreignField: "_id", + as: "user" + }}, + { $unwind: "$user" }, + { $project: { + orderId: 1, + amount: 1, + "user.nickname": 1 + }} +]) +\`\`\` + +--- + +**总结**: 数据库设计是系统的基石,合理的结构设计能让后续开发事半功倍。当前使用LocalStorage做MVP验证,未来切换MongoDB后,整个系统的可靠性和扩展性都会大幅提升。 + +--- + +**更新时间**: 2025年1月14日 +**负责人**: 卡若 +**数据库版本**: MongoDB 6.0+ diff --git a/开发文档/8、部署/API接入说明.md b/开发文档/8、部署/API接入说明.md new file mode 100644 index 00000000..afa04eaf --- /dev/null +++ b/开发文档/8、部署/API接入说明.md @@ -0,0 +1,610 @@ +# 小程序 API 接入说明 + +## 📋 概述 + +将 newpp 项目从静态数据（bookData.js）改为从真实 API 加载数据。 + +--- + +## 🎯 接入的 API + +### 1. 章节相关 + +| API | 方法 | 说明 | 参数 | +|-----|------|------|------| +| `/api/book/chapters` | GET | 获取章节列表 | partId, status, page, pageSize | +| `/api/book/chapter/[id]` | GET | 获取章节详情 | id（路径参数） | + +### 2. 用户相关 + +| API | 方法 | 说明 | 参数 | +|-----|------|------|------| +| `/api/user/profile` | GET | 获取用户信息 | userId, openId | +| `/api/user/profile` | POST | 更新用户信息 | userId, openId, nickname, avatar, phone, wechatId | + +### 3. 配置相关 + +| API | 方法 | 说明 | 参数 | +|-----|------|------|------| +| `/api/db/config` | GET | 获取系统配置 | 无 | +| `/api/match/config` | GET | 获取找伙伴配置 | 无 | + +### 4. 找伙伴相关 + +| API | 方法 | 说明 | 参数 | +|-----|------|------|------| +| `/api/ckb/join` | POST | 加入匹配池 | type, wechat, description | +| `/api/match/users` | GET | 获取匹配用户 | type | + +### 5. 推广相关 + +| API | 方法 | 说明 | 参数 | +|-----|------|------|------| +| `/api/referral/data` | GET | 获取推广数据 | userId | +| `/api/referral/bind` | POST | 绑定推荐人 | userId, referralCode | +| `/api/referral/visit` | POST | 记录推广访问 | referralCode | + +### 6. 搜索相关 + +| API | 方法 | 说明 | 参数 | +|-----|------|------|------| +| `/api/search` | GET | 搜索章节 | q（关键词） | + +### 7. 支付相关 + +| API | 方法 | 说明 | 参数 | +|-----|------|------|------| +| `/api/payment/create-order` | POST | 创建订单 | userId, type, sectionId, amount, payMethod | +| `/api/payment/status/[orderSn]` | GET | 查询订单状态 | orderSn（路径参数） | +| `/api/payment/methods` | GET | 获取支付方式列表 | 无 | + +### 8. 提现相关 + +| API | 方法 | 说明 | 参数 | +|-----|------|------|------| +| `/api/withdraw` | POST | 申请提现 | userId, amount, method, account, realName | + +--- + +## 📁 文件结构 + +``` +newpp/src/ +├── api/ +│ └── index.js # ✅ API 集成层（封装所有 API） +├── hooks/ +│ ├── useChapters.js # ✅ 章节列表 Hook +│ └── useChapterContent.js # ✅ 章节内容 Hook +├── adapters/ +│ ├── request.js # ✅ 请求适配器（已有） +│ └── storage.js # ✅ 存储适配器（已有） +├── data/ +│ └── bookData.js # ⚠️ 静态数据（待废弃） +└── pages/ + ├── HomePage.jsx # ⏳ 需要改用 useChapters + ├── ChaptersPage.jsx # ⏳ 需要改用 useChapters + ├── ReadPage.jsx # ⏳ 需要改用 useChapterContent + └── ... +``` + +--- + +## 🔧 核心实现 + +### 1. API 集成层 + +**文件**：`newpp/src/api/index.js` + +**作用**： +- 封装所有 API 请求 +- 统一处理错误和数据格式 +- 提供类型化的接口 + +**示例**： + +```javascript +import { request } from '../adapters/request' + +// 获取章节列表 +export async function getChapters(params = {}) { + const { partId, status = 'published', page = 1, pageSize = 100 } = params + const query = new URLSearchParams({ status, page: String(page), pageSize: String(pageSize) }) + if (partId) query.append('partId', partId) + + const res = await request(`/api/book/chapters?${query.toString()}`) + return res +} + +// 获取章节详情 +export async function getChapterById(id) { + const res = await request(`/api/book/chapter/${id}`) + return res +} +``` + +--- + +### 2. 章节列表 Hook + +**文件**：`newpp/src/hooks/useChapters.js` + +**功能**： +1. ✅ 从 API 加载章节列表 +2. ✅ 缓存到本地（30分钟） +3. ✅ 转换数据格式（API → bookData） +4. ✅ 提供辅助函数 + +**使用示例**： + +```javascript +import { useChapters } from '../hooks/useChapters' + +export default function HomePage() { + const { bookData, loading, error, getTotalSectionCount, refresh } = useChapters() + + if (loading) return
加载中...
+ if (error) return
错误: {error}
+ + const totalSections = getTotalSectionCount() + + return ( +
+

共 {totalSections} 章

+ {bookData.map((part) => ( +
+

{part.title}

+ {/* ... */} +
+ ))} +
+ ) +} +``` + +--- + +### 3. 章节内容 Hook + +**文件**：`newpp/src/hooks/useChapterContent.js` + +**功能**： +1. ✅ 从 API 加载章节详情 +2. ✅ 自动处理 loading 和 error +3. ✅ 支持重新加载 + +**使用示例**： + +```javascript +import { useChapterContent } from '../hooks/useChapterContent' +import { getPageQuery } from '../adapters/router' + +export default function ReadPage() { + const { id } = getPageQuery() + const { content, loading, error, reload } = useChapterContent(id) + + if (loading) return
加载中...
+ if (error) return
错误: {error}
+ if (!content) return
章节不存在
+ + return ( +
+

{content.title}

+

{content.words} 字

+
+
+ ) +} +``` + +--- + +## 🔄 数据转换 + +### API 返回格式 + +```json +{ + "success": true, + "data": { + "list": [ + { + "id": "1.1", + "part_id": "part-1", + "part_title": "真实的人", + "chapter_id": "chapter-1", + "chapter_title": "人与人之间的底层逻辑", + "section_title": "荷包：电动车出租的被动收入模式", + "content": "...", + "word_count": 1500, + "is_free": true, + "price": 0, + "sort_order": 1, + "status": "published" + } + ], + "total": 50, + "page": 1, + "pageSize": 100, + "totalPages": 1 + } +} +``` + +### bookData 格式 + +```javascript +[ + { + id: 'part-1', + number: '01', + title: '真实的人', + subtitle: '人性观察与社交逻辑', + chapters: [ + { + id: 'chapter-1', + title: '人与人之间的底层逻辑', + sections: [ + { + id: '1.1', + title: '荷包：电动车出租的被动收入模式', + isFree: true, + price: 1, + wordCount: 1500, + } + ] + } + ] + } +] +``` + +### 转换函数 + +```javascript +function transformChapters(chapters) { + const partsMap = new Map() + + chapters.forEach((item) => { + // 确保 part 存在 + if (!partsMap.has(item.part_id)) { + partsMap.set(item.part_id, { + id: item.part_id, + number: item.part_id.replace('part-', '').padStart(2, '0'), + title: item.part_title, + subtitle: '', + chapters: [] + }) + } + + const part = partsMap.get(item.part_id) + + // 查找或创建 chapter + let chapter = part.chapters.find((c) => c.id === item.chapter_id) + if (!chapter) { + chapter = { + id: item.chapter_id, + title: item.chapter_title, + sections: [] + } + part.chapters.push(chapter) + } + + // 添加 section + chapter.sections.push({ + id: item.id, + title: item.section_title, + isFree: item.is_free || false, + price: item.price || 1, + wordCount: item.word_count || 0, + }) + }) + + return Array.from(partsMap.values()) +} +``` + +--- + +## 📦 缓存策略 + +### 缓存位置 + +- **小程序**：`wx.storage` +- **Web**：`localStorage` + +### 缓存时长 + +- **章节列表**：30分钟 +- **章节内容**：不缓存（内容可能更新） + +### 缓存格式 + +```javascript +{ + data: [...], // 数据 + timestamp: 1706940000000 // 时间戳 +} +``` + +### 缓存逻辑 + +```javascript +// 1. 尝试从缓存加载 +const cached = await storage.getItem(CACHE_KEY) +if (cached) { + const { data, timestamp } = JSON.parse(cached) + if (Date.now() - timestamp < CACHE_DURATION) { + setBookData(data) + return + } +} + +// 2. 从 API 加载 +const res = await getChapters({ status: 'published', pageSize: 1000 }) +const transformed = transformChapters(res.data.list) +setBookData(transformed) + +// 3. 缓存数据 +await storage.setItem(CACHE_KEY, JSON.stringify({ + data: transformed, + timestamp: Date.now() +})) +``` + +--- + +## 🔄 迁移步骤 + +### Phase 1：创建 API 层 ✅ + +- [x] 创建 `api/index.js` +- [x] 创建 `hooks/useChapters.js` +- [x] 创建 `hooks/useChapterContent.js` + +### Phase 2：更新页面组件 + +#### 2.1 HomePage.jsx + +**Before**： + +```javascript +import { getTotalSectionCount, bookData } from '../data/bookData' + +const totalSections = getTotalSectionCount() +``` + +**After**： + +```javascript +import { useChapters } from '../hooks/useChapters' + +export default function HomePage() { + const { bookData, loading, getTotalSectionCount } = useChapters() + + if (loading) return + + const totalSections = getTotalSectionCount() + // ... +} +``` + +#### 2.2 ChaptersPage.jsx + +**Before**： + +```javascript +import { bookData } from '../data/bookData' +``` + +**After**： + +```javascript +import { useChapters } from '../hooks/useChapters' + +export default function ChaptersPage() { + const { bookData, loading } = useChapters() + + if (loading) return + // ... +} +``` + +#### 2.3 ReadPage.jsx + +**Before**： + +```javascript +import { getSectionById } from '../data/bookData' + +const section = getSectionById(id) +``` + +**After**： + +```javascript +import { useChapterContent } from '../hooks/useChapterContent' +import { getPageQuery } from '../adapters/router' + +export default function ReadPage() { + const { id } = getPageQuery() + const { content, loading } = useChapterContent(id) + + if (loading) return + if (!content) return + // ... +} +``` + +#### 2.4 SearchPage.jsx + +**Before**： + +```javascript +import { getAllSections } from '../data/bookData' + +const results = getAllSections().filter(s => s.title.includes(keyword)) +``` + +**After**： + +```javascript +import { searchChapters } from '../api' + +export default function SearchPage() { + const [results, setResults] = useState([]) + + const handleSearch = async (keyword) => { + const res = await searchChapters(keyword) + setResults(res.data || []) + } + // ... +} +``` + +### Phase 3：集成到 Zustand Store + +```javascript +// store/index.js +import { getChapters } from '../api' + +const useStore = create( + persist( + (set, get) => ({ + // ... 其他状态 + + // ✅ 添加章节数据 + bookData: [], + loadChapters: async () => { + const res = await getChapters({ status: 'published', pageSize: 1000 }) + if (res.success) { + set({ bookData: transformChapters(res.data.list) }) + } + }, + }), + { + name: 'soul-party-storage', + storage: {/* ... */}, + } + ) +) +``` + +### Phase 4：移除静态数据 + +- [ ] 删除或重命名 `data/bookData.js` +- [ ] 更新所有导入路径 + +--- + +## 🐛 错误处理 + +### API 请求失败 + +```javascript +try { + const res = await getChapters() + if (!res.success) { + throw new Error(res.error || '请求失败') + } +} catch (err) { + console.error('加载失败:', err) + setError(err.message) + + // ✅ 降级策略：使用缓存数据 + const cached = await storage.getItem(CACHE_KEY) + if (cached) { + const { data } = JSON.parse(cached) + setBookData(data) + } +} +``` + +### 网络超时 + +```javascript +// adapters/request.js +export function request(url, options = {}) { + const controller = new AbortController() + const timeout = setTimeout(() => controller.abort(), 10000) // 10秒超时 + + return fetch(fullUrl, { + ...options, + signal: controller.signal, + }) + .finally(() => clearTimeout(timeout)) +} +``` + +--- + +## 📊 性能优化 + +### 1. 缓存策略 + +- ✅ 章节列表缓存 30 分钟 +- ✅ 减少 API 调用次数 +- ✅ 提升加载速度 + +### 2. 懒加载 + +```javascript +// 只在需要时加载章节内容 +useEffect(() => { + if (visible) { + loadContent() + } +}, [visible]) +``` + +### 3. 预加载 + +```javascript +// 预加载下一章内容 +useEffect(() => { + if (content && nextChapterId) { + // 延迟 2 秒预加载 + const timer = setTimeout(() => { + getChapterById(nextChapterId) + }, 2000) + return () => clearTimeout(timer) + } +}, [content, nextChapterId]) +``` + +--- + +## 🧪 测试清单 + +### API 集成测试 + +- [ ] 章节列表加载成功 +- [ ] 章节详情加载成功 +- [ ] 用户信息获取成功 +- [ ] 配置加载成功 +- [ ] 搜索功能正常 +- [ ] 错误处理正确 + +### 缓存测试 + +- [ ] 首次加载从 API 获取 +- [ ] 第二次加载从缓存读取 +- [ ] 缓存过期后重新加载 +- [ ] 缓存数据格式正确 + +### 跨平台测试 + +- [ ] Web 环境正常 +- [ ] 小程序环境正常 +- [ ] 数据格式一致 + +--- + +## 📚 相关文档 + +1. [API 集成层代码](../newpp/src/api/index.js) +2. [章节列表 Hook](../newpp/src/hooks/useChapters.js) +3. [章节内容 Hook](../newpp/src/hooks/useChapterContent.js) + +--- + +**总结**：API 集成层已完成，接下来需要更新各个页面组件，将静态数据改为从 API 加载。 diff --git a/开发文档/8、部署/MCP-MySQL配置说明.md b/开发文档/8、部署/MCP-MySQL配置说明.md new file mode 100644 index 00000000..5f5c1690 --- /dev/null +++ b/开发文档/8、部署/MCP-MySQL配置说明.md @@ -0,0 +1,401 @@ +# MCP MySQL 配置说明 + +**日期**: 2026-02-04 +**目的**: 通过 MCP (Model Context Protocol) 在 Cursor 中直接操作 Soul 小程序数据库 + +--- + +## ✅ 已配置的 MCP 服务 + +### 1. Soul-MySQL（新增） +**用途**: Soul 小程序生产数据库操作 + +**配置文件**: `C:\Users\29195\.cursor\mcp.json` + +```json +{ + "Soul-MySQL": { + "command": "npx", + "args": [ + "-y", + "@f4ww4z/mcp-mysql-server", + "--host", + "56b4c23f6853c.gz.cdb.myqcloud.com", + "--port", + "14413", + "--user", + "cdb_outerroot", + "--password", + "Zhiqun1984", + "--database", + "soul_miniprogram" + ], + "env": {} + } +} +``` + +**数据库信息**: +- **主机**: 56b4c23f6853c.gz.cdb.myqcloud.com（腾讯云 CDB） +- **端口**: 14413 +- **用户**: cdb_outerroot +- **密码**: Zhiqun1984 +- **数据库**: soul_miniprogram + +--- + +## 🔧 使用方法 + +### 1. 重启 Cursor +配置文件修改后，需要**完全重启 Cursor** 才能生效： +1. 关闭所有 Cursor 窗口 +2. 重新打开 Cursor +3. 等待 MCP 服务启动 + +### 2. 验证连接 +在 Cursor 中输入： +``` +@Soul-MySQL 列出所有表 +``` + +或使用工具调用： +```javascript +// 查询所有表 +user-MySQL-list_tables + +// 查看表结构 +user-MySQL-describe_table +{ + "table": "orders" +} + +// 执行查询 +user-MySQL-query +{ + "sql": "SELECT * FROM orders LIMIT 10" +} +``` + +--- + +## 📊 可用的操作 + +### 1. 查询数据（只读） +```sql +-- 查看最近订单 +SELECT * FROM orders +ORDER BY created_at DESC +LIMIT 10; + +-- 统计订单状态 +SELECT status, COUNT(*) as count, SUM(amount) as total +FROM orders +GROUP BY status; + +-- 查看用户购买情况 +SELECT + u.id, + u.nickname, + u.has_full_book, + COUNT(o.id) as order_count, + SUM(o.amount) as total_spent +FROM users u +LEFT JOIN orders o ON u.id = o.user_id AND o.status = 'paid' +GROUP BY u.id, u.nickname, u.has_full_book +ORDER BY total_spent DESC +LIMIT 20; +``` + +### 2. 修改数据（慎重！） +```sql +-- 修复订单表 status 字段（关键修复） +ALTER TABLE orders +MODIFY COLUMN status ENUM('created', 'pending', 'paid', 'cancelled', 'refunded', 'expired') +DEFAULT 'created'; + +-- 手动解锁用户章节 +UPDATE users +SET purchased_sections = JSON_ARRAY_APPEND( + COALESCE(purchased_sections, '[]'), '$', '1-1' +) +WHERE id = 'user_xxx'; + +-- 手动补记订单 +INSERT INTO orders ( + id, order_sn, user_id, open_id, + product_type, product_id, amount, description, + status, transaction_id, pay_time, created_at, updated_at +) VALUES ( + 'MP20260204123456789012', 'MP20260204123456789012', + 'user_xxx', 'oXXXX...', 'section', '1-1', 9.9, + '章节1-1购买', 'paid', 'wx_transaction_id', + NOW(), NOW(), NOW() +); +``` + +### 3. 查看表结构 +```sql +-- 查看表结构 +DESCRIBE orders; +DESCRIBE users; +DESCRIBE referral_bindings; + +-- 查看索引 +SHOW INDEX FROM orders; + +-- 查看表创建语句 +SHOW CREATE TABLE orders; +``` + +--- + +## ⚠️ 重要提醒 + +### 1. 生产数据库操作 +- ⚠️ 这是**生产数据库**，所有操作都会**直接影响线上服务** +- ✅ 查询操作（SELECT）相对安全 +- ❌ 修改操作（UPDATE/DELETE/ALTER）**必须谨慎** +- 💡 建议先在本地数据库测试 + +### 2. 数据备份 +修改重要数据前，建议先备份： +```sql +-- 备份整个表 +CREATE TABLE orders_backup AS SELECT * FROM orders; + +-- 备份特定数据 +CREATE TABLE orders_backup_20260204 AS +SELECT * FROM orders WHERE DATE(created_at) = '2026-02-04'; +``` + +### 3. 事务操作 +对于关联性强的修改，使用事务： +```sql +START TRANSACTION; + +-- 修改操作1 +UPDATE users SET has_full_book = TRUE WHERE id = 'user_xxx'; + +-- 修改操作2 +INSERT INTO orders (...) VALUES (...); + +-- 确认无误后提交 +COMMIT; + +-- 或者出错时回滚 +-- ROLLBACK; +``` + +--- + +## 🎯 常见操作场景 + +### 场景1: 修复订单表状态字段 +```sql +-- 1. 先查看当前定义 +SHOW CREATE TABLE orders; + +-- 2. 修改 ENUM 定义 +ALTER TABLE orders +MODIFY COLUMN status ENUM('created', 'pending', 'paid', 'cancelled', 'refunded', 'expired') +DEFAULT 'created'; + +-- 3. 验证修改 +DESCRIBE orders; +``` + +### 场景2: 查询用户支付问题 +```sql +-- 查询特定用户的订单记录 +SELECT * FROM orders +WHERE user_id = 'ogpTW5a9exdEmEwqZsYywvgSpSQg' +ORDER BY created_at DESC; + +-- 查询用户购买记录 +SELECT + id, nickname, has_full_book, purchased_sections, + pending_earnings, earnings +FROM users +WHERE id = 'ogpTW5a9exdEmEwqZsYywvgSpSQg'; + +-- 查询用户推荐关系 +SELECT * FROM referral_bindings +WHERE referee_id = 'ogpTW5a9exdEmEwqZsYywvgSpSQg' + OR referrer_id = 'ogpTW5a9exdEmEwqZsYywvgSpSQg'; +``` + +### 场景3: 统计数据分析 +```sql +-- 今日订单统计 +SELECT + COUNT(*) as total_orders, + SUM(CASE WHEN status = 'paid' THEN 1 ELSE 0 END) as paid_orders, + SUM(CASE WHEN status = 'paid' THEN amount ELSE 0 END) as total_revenue +FROM orders +WHERE DATE(created_at) = CURDATE(); + +-- 用户活跃度统计 +SELECT + DATE(created_at) as date, + COUNT(DISTINCT user_id) as active_users, + COUNT(*) as total_orders, + SUM(amount) as revenue +FROM orders +WHERE status = 'paid' + AND created_at >= DATE_SUB(NOW(), INTERVAL 7 DAY) +GROUP BY DATE(created_at) +ORDER BY date DESC; + +-- 推广效果统计 +SELECT + u.nickname as referrer, + COUNT(rb.id) as total_referrals, + SUM(CASE WHEN rb.status = 'converted' THEN 1 ELSE 0 END) as conversions, + SUM(rb.commission_amount) as total_commission +FROM users u +LEFT JOIN referral_bindings rb ON u.id = rb.referrer_id +WHERE rb.id IS NOT NULL +GROUP BY u.id, u.nickname +ORDER BY total_commission DESC +LIMIT 20; +``` + +### 场景4: 紧急数据修复 +```sql +-- 手动解锁用户权限（用户支付但未解锁） +START TRANSACTION; + +-- 1. 补记订单 +INSERT INTO orders ( + id, order_sn, user_id, open_id, + product_type, product_id, amount, description, + status, transaction_id, pay_time, created_at, updated_at +) VALUES ( + 'MANUAL_20260204_001', 'MANUAL_20260204_001', + 'user_xxx', 'oXXXX...', 'section', '1-1', 9.9, + '手动补记-章节1-1购买', 'paid', 'manual_fix', + NOW(), NOW(), NOW() +); + +-- 2. 解锁章节 +UPDATE users +SET purchased_sections = JSON_ARRAY_APPEND( + COALESCE(purchased_sections, '[]'), '$', '1-1' +) +WHERE id = 'user_xxx' + AND NOT JSON_CONTAINS(COALESCE(purchased_sections, '[]'), '"1-1"'); + +-- 3. 如果有推荐人，分配佣金 +UPDATE users +SET pending_earnings = pending_earnings + (9.9 * 0.9) +WHERE id = (SELECT referred_by FROM users WHERE id = 'user_xxx'); + +-- 4. 更新推荐关系状态 +UPDATE referral_bindings +SET status = 'converted', + conversion_date = NOW(), + commission_amount = 8.91, + order_id = 'MANUAL_20260204_001' +WHERE referee_id = 'user_xxx' + AND status = 'active'; + +COMMIT; +``` + +--- + +## 🔗 其他 MCP 服务 + +### MySQL（本地） +- **用途**: 本地 sass 数据库 +- **主机**: localhost:3306 +- **数据库**: sass + +### MongoDB +- **用途**: 测试 MongoDB 连接 +- **连接**: mongodb://admin:admin123@192.168.1.201:27017/admin + +### Ollama +- **用途**: 本地 AI 模型调用 +- **脚本**: C:\Users\29195\mcp_ollama_server.py + +--- + +## 📝 MCP 工具列表 + +使用 `@Soul-MySQL` 可以调用以下工具： + +| 工具名 | 功能 | 示例 | +|--------|------|------| +| `user-MySQL-connect_db` | 连接数据库 | 自动连接 | +| `user-MySQL-query` | 执行 SELECT 查询 | `{"sql": "SELECT * FROM orders LIMIT 10"}` | +| `user-MySQL-execute` | 执行 INSERT/UPDATE/DELETE | `{"sql": "UPDATE users SET ..."}` | +| `user-MySQL-list_tables` | 列出所有表 | 无参数 | +| `user-MySQL-describe_table` | 查看表结构 | `{"table": "orders"}` | + +--- + +## 🚀 快速开始 + +### 1. 检查订单表状态 +``` +@Soul-MySQL 执行查询：DESCRIBE orders; +``` + +### 2. 查看最近订单 +``` +@Soul-MySQL 查询最近10条订单记录 +``` + +### 3. 修复订单表（如需要） +``` +@Soul-MySQL 执行以下SQL： +ALTER TABLE orders +MODIFY COLUMN status ENUM('created', 'pending', 'paid', 'cancelled', 'refunded', 'expired') +DEFAULT 'created'; +``` + +--- + +## ⚡ 故障排查 + +### 问题1: MCP 服务未启动 +**症状**: 输入 `@Soul-MySQL` 没有提示 + +**解决**: +1. 完全关闭 Cursor +2. 检查 mcp.json 文件格式是否正确 +3. 重新打开 Cursor +4. 查看 Cursor 输出日志 + +### 问题2: 连接超时 +**症状**: 执行查询时提示连接超时 + +**解决**: +1. 检查网络连接 +2. 确认数据库服务器是否在线 +3. 检查防火墙/安全组配置 +4. 验证数据库账号密码 + +### 问题3: 权限不足 +**症状**: 提示没有权限执行某些操作 + +**解决**: +1. 检查数据库用户权限 +2. 某些操作需要超级管理员权限 +3. 联系 DBA 授权 + +--- + +## 📚 相关文档 + +- [支付订单完整修复方案](./支付订单完整修复方案.md) +- [订单表状态字段修复说明](./订单表状态字段修复说明.md) +- [支付订单未创建问题分析](./支付订单未创建问题分析.md) +- [数据库设计](../7、数据库/数据库设计.md) + +--- + +**现在你可以在 Cursor 中直接使用 `@Soul-MySQL` 来操作生产数据库了！** 🎉 + +**记得重启 Cursor 使配置生效！** diff --git a/开发文档/8、部署/Soul-MySQL-MCP配置说明.md b/开发文档/8、部署/Soul-MySQL-MCP配置说明.md new file mode 100644 index 00000000..cbbad0e4 --- /dev/null +++ b/开发文档/8、部署/Soul-MySQL-MCP配置说明.md @@ -0,0 +1,84 @@ +# Soul-MySQL MCP 配置说明 + +**配置文件**: `C:\Users\29195\.cursor\mcp.json` + +--- + +## 为什么之前无法执行？ + +### 原因 1：连接时没有带端口 + +- 之前用 `--host`、`--port` 分开传参，部分 MCP 客户端在**运行时**调用 `connect_db` 时**只传 host/user/password/database，不传 port**。 +- 你的数据库在 **14413**，MySQL 默认是 **3306**，所以实际连的是错误端口 → 容易 **ETIMEDOUT** 或连不上。 +- 所以会出现「无法执行」或执行报错。 + +### 原因 2：改用「连接串」才能带上端口 + +- `@f4ww4z/mcp-mysql-server` 支持用**一条连接串**启动，格式里可以写清楚端口： + - `mysql://用户:密码@主机:端口/数据库名` +- 这样 MCP 启动时就会用 **14413** 去连，不会再用默认 3306。 + +--- + +## 当前正确配置（连接串方式） + +在 `mcp.json` 里 Soul-MySQL 应类似： + +```json +"Soul-MySQL": { + "command": "npx", + "args": [ + "-y", + "@f4ww4z/mcp-mysql-server", + "mysql://cdb_outerroot:Zhiqun1984@56b4c23f6853c.gz.cdb.myqcloud.com:14413/soul_miniprogram" + ], + "env": {} +} +``` + +含义： + +- **用户**: cdb_outerroot +- **密码**: Zhiqun1984 +- **主机**: 56b4c23f6853c.gz.cdb.myqcloud.com +- **端口**: 14413（写在连接串里） +- **数据库**: soul_miniprogram + +这样 MCP 会按 `主机:14413` 连接，不再用 3306。 + +--- + +## 使用前必做：重启 Cursor + +1. **完全退出 Cursor**（关掉所有窗口）。 +2. 再重新打开 Cursor。 +3. 等 MCP 列表里 Soul-MySQL 显示为已连接/可用。 + +否则会继续用旧配置（不带端口），仍然无法执行。 + +--- + +## 若仍无法执行，可排查这些 + +### 1. 本机网络/防火墙 + +- 数据库在腾讯云，若你本机或公司网络**不允许访问外网 14413**，连接会超时。 +- 解决：在能访问该库的机器上跑 Cursor（或先做 SSH 隧道，把 14413 转到本机 3306，再在 mcp.json 里连 localhost:3306）。 + +### 2. 腾讯云白名单 + +- 腾讯云 MySQL 有「来源 IP 白名单」。 +- 你当前上网的 **公网 IP** 必须在白名单里，否则会被拒绝。 +- 解决：在腾讯云控制台 → 该 MySQL 实例 → 白名单里加上你当前的公网 IP。 + +### 3. 密码含特殊字符 + +- 若以后改了密码，且密码里有 `@`、`#`、`/` 等，需要做 **URL 编码** 再写进连接串，否则连接串会被解析错。 + +--- + +## 小结 + +- **无法执行** 多半是：连库时**没带端口 14413** 或**网络/白名单**不通。 +- 已把 Soul-MySQL 改成**带端口的连接串**配置，并写进 `mcp.json`。 +- 修改后**务必重启 Cursor** 再试；若仍不行，按上面「若仍无法执行」逐项排查。 diff --git a/开发文档/8、部署/VIP功能-数据库迁移说明.md b/开发文档/8、部署/VIP功能-数据库迁移说明.md new file mode 100644 index 00000000..66b09558 --- /dev/null +++ b/开发文档/8、部署/VIP功能-数据库迁移说明.md @@ -0,0 +1,49 @@ +# VIP 功能 - 数据库迁移说明 + +> 2026-02-26 小橙同步。VIP 排序、角色、设置入口升级。 + +--- + +## 一、迁移脚本 + +| 脚本 | 说明 | +|------|------| +| `soul-api/scripts/add-vip-activated-at.sql` | 新增 `users.vip_activated_at`（成为 VIP 时间，排序用） | +| `soul-api/scripts/add-vip-roles-and-fields.sql` | 新建 `vip_roles` 表；新增 `users.vip_sort`、`users.vip_role` | +| `soul-api/scripts/add-vip-profile-fields.sql` | 新增 `users.vip_name`、`vip_avatar`、`vip_project`、`vip_contact`、`vip_bio`（会员资料，与用户信息分离） | + +--- + +## 二、执行顺序 + +```bash +# 1. vip_activated_at（若尚未执行） +mysql -u user -p database < soul-api/scripts/add-vip-activated-at.sql + +# 2. vip_roles 表 + users 新字段 +mysql -u user -p database < soul-api/scripts/add-vip-roles-and-fields.sql + +# 3. 会员资料字段（若尚未执行；列已存在会报 Duplicate column，可忽略） +mysql -u user -p database < soul-api/scripts/add-vip-profile-fields.sql +``` + +若 `vip_sort`、`vip_role` 已存在，对应 `ALTER` 会报错，可忽略或单独执行未执行过的语句。 + +--- + +## 三、功能说明 + +| 字段/表 | 用途 | +|---------|------| +| `vip_activated_at` | 成为 VIP 时间：付款=订单 pay_time，手动=设置时 now；排序用（后付款/后设置在前） | +| `vip_sort` | 手动排序，数字越小越靠前；NULL 时按 vip_activated_at | +| `vip_role` | 角色：从 vip_roles 选或手动填写 | +| `vip_roles` | 预设角色表（创始人、投资人、产品经理等），管理端可 CRUD | +| `vip_name`、`vip_avatar`、`vip_project`、`vip_contact`、`vip_bio` | 会员资料（创业老板排行），与用户信息 phone/wechat_id 分离 | + +--- + +## 四、管理端入口 + +- **用户列表**：每行「设置 VIP」按钮（Crown 图标）→ SetVipModal +- **VIP 角色**：侧栏「VIP 角色」→ `/vip-roles`，管理预设角色列表 diff --git a/开发文档/8、部署/代码逻辑和数据库最终检查清单.md b/开发文档/8、部署/代码逻辑和数据库最终检查清单.md new file mode 100644 index 00000000..8f7cf88d --- /dev/null +++ b/开发文档/8、部署/代码逻辑和数据库最终检查清单.md @@ -0,0 +1,363 @@ +# 代码逻辑和数据库最终检查清单 ✅ + +## 📊 数据库修改（已完成） + +### 1. referral_bindings 表新增字段 +```sql +✅ last_purchase_date DATETIME DEFAULT NULL +✅ purchase_count INT DEFAULT 0 +✅ total_commission DECIMAL(10,2) DEFAULT 0.00 +✅ status ENUM('active', 'expired', 'cancelled') -- 新增 'cancelled' +``` + +### 2. 索引优化 +```sql +✅ idx_status_expiry (status, expiry_date) +✅ idx_referee_status (referee_id, status) +✅ idx_referrer_status (referrer_id, status) +✅ idx_purchase_count (purchase_count) +``` + +### 3. 数据库迁移执行状态 +- ✅ 已通过 `scripts/migrate_db_simple.py` 成功执行 +- ✅ 所有字段已添加 +- ✅ 所有索引已创建 + +--- + +## 🔧 核心API逻辑（已验证） + +### 1. `/api/referral/bind` - 绑定/切换推荐人 ✅ + +**文件**: `app/api/referral/bind/route.ts` + +**关键逻辑**: +```typescript +✅ 从 referral_config 读取 bindingDays（不再硬编码 30 天） +✅ 同一推荐人 → 续期（刷新 30 天） +✅ 不同推荐人 → 立即切换（无需等待过期） + - 旧绑定标记为 'cancelled' + - 创建新绑定，expiry_date = NOW + bindingDays + - 更新 users.referral_count（旧 -1，新 +1） +``` + +**验证点**: +- ✅ 绑定天数可配置 +- ✅ 切换逻辑正确（不检查 expiry_date） +- ✅ 旧绑定正确标记为 'cancelled' +- ✅ 新绑定正确创建 +- ✅ 推荐人数量正确更新 + +--- + +### 2. `/api/miniprogram/pay` - 创建支付订单 ✅ + +**文件**: `app/api/miniprogram/pay/route.ts` + +**关键逻辑**: +```typescript +✅ 从 referral_config 读取 userDiscount（如 5 表示 5%） +✅ 如果有 referralCode，计算折后价 + finalAmount = amount * (1 - userDiscount / 100) + finalAmount = max(0.01, round(finalAmount, 2)) +✅ 微信支付使用 finalAmount（折后价） +✅ 订单表记录 finalAmount（折后价） +``` + +**验证点**: +- ✅ 折扣正确应用（原价 1.00，5% off = 0.95） +- ✅ 最低金额保护（至少 0.01 元） +- ✅ 金额精确到分（Math.round） +- ✅ 订单表记录的是折后价 + +--- + +### 3. `/api/miniprogram/pay/notify` - 支付回调 ✅ + +**文件**: `app/api/miniprogram/pay/notify/route.ts` + +**关键逻辑**: +```typescript +✅ 查找 status = 'active' 的绑定记录 +✅ 检查 expiry_date > NOW（过期不分佣） +✅ 从 referral_config 读取 distributorShare +✅ 计算佣金：commission = amount * distributorShare / 100 +✅ 更新 users.pending_earnings += commission +✅ 更新 referral_bindings: + - last_purchase_date = NOW + - purchase_count += 1 + - total_commission += commission + - status 保持 'active'（不再改为 'converted'） +``` + +**验证点**: +- ✅ 只给 active 且未过期的绑定分佣 +- ✅ 佣金比例可配置 +- ✅ 支持多次购买分佣（不改 status） +- ✅ 正确累加购买次数和佣金 +- ✅ 记录最后购买时间 + +--- + +### 4. `/api/withdraw` - 提现申请 ✅ + +**文件**: `app/api/withdraw/route.ts` + +**关键逻辑**: +```typescript +✅ 从 referral_config 读取 minWithdrawAmount +✅ 验证 amount >= minWithdrawAmount（不再硬编码 10 元） +✅ 验证 amount <= pending_earnings +``` + +**验证点**: +- ✅ 最低提现金额可配置 +- ✅ 金额验证逻辑正确 + +--- + +### 5. `/api/referral/data` - 分销数据统计 ✅ + +**文件**: `app/api/referral/data/route.ts` + +**关键逻辑**: +```typescript +✅ 绑定统计: + - active: status = 'active' AND expiry_date > NOW + - converted: status = 'active' AND purchase_count > 0 + - expired: status IN ('expired', 'cancelled') OR expiry_date <= NOW + +✅ 已转化用户列表: + WHERE status = 'active' AND purchase_count > 0 + ORDER BY last_purchase_date DESC + +✅ 返回购买次数、累计佣金 +``` + +**验证点**: +- ✅ 不再查询 status = 'converted' +- ✅ 使用 purchase_count 判断是否已购买 +- ✅ 返回新增的字段（purchase_count, total_commission） +- ✅ 统计逻辑正确（包含 'cancelled' 状态） + +--- + +## 🎯 管理后台（已验证） + +### 1. 推广设置页面 ✅ + +**文件**: `app/admin/referral-settings/page.tsx` + +**配置项**: +```typescript +✅ distributorShare (分销比例, 0-100) +✅ minWithdrawAmount (最低提现金额, 元) +✅ bindingDays (绑定天数, 天) +✅ userDiscount (好友优惠, 0-100) +✅ enableAutoWithdraw (自动提现, boolean) +``` + +**验证点**: +- ✅ 读取配置正确 +- ✅ 保存配置正确（Number/Boolean 转换） +- ✅ 表单验证正确 +- ✅ 成功提示清晰 + +--- + +### 2. 管理后台菜单 ✅ + +**文件**: `app/admin/layout.tsx` + +```typescript +✅ 新增菜单项: "推广设置" → /admin/referral-settings +✅ 图标: CreditCard +✅ 位置: "用户管理" 和 "系统设置" 之间 +``` + +--- + +## 📱 小程序端（已完成） + +### 1. UI修改 ✅ +```xml +✅ 删除"我的邀请码"卡片（miniprogram/pages/referral/referral.wxml） +``` + +### 2. 绑定逻辑 ✅ +```javascript +✅ app.js 调用 /api/referral/bind（后端已实现立即切换） +✅ 无需前端修改 +``` + +### 3. 支付逻辑 ✅ +```javascript +✅ pages/read/read.js 传递 referralCode（后端已实现折扣） +✅ 无需前端修改 +``` + +### 4. 数据展示 ✅ +```javascript +✅ pages/referral/referral.js 调用 /api/referral/data +✅ 后端已返回新字段（purchase_count, total_commission） +✅ 无需前端修改 +``` + +--- + +## ⏰ 定时任务（已创建） + +### 1. 自动解绑脚本 ✅ + +**文件**: `scripts/auto-unbind-expired-simple.js` + +**逻辑**: +```javascript +✅ 查找 status = 'active' AND expiry_date < NOW AND purchase_count = 0 +✅ 批量更新为 status = 'expired' +✅ 输出详细日志 +``` + +**部署**: +```bash +⏸️ 需在宝塔面板配置: 每天 03:00 执行 + 命令: cd /www/wwwroot/soul.quwanzhi.com && /www/server/nodejs/v20.11.0/bin/node scripts/auto-unbind-expired-simple.js >> logs/auto-unbind.log 2>&1 +``` + +--- + +## 🔍 业务逻辑验证 + +### 场景1: 首次绑定 ✅ +``` +A 分享链接 → B 点击 → /api/referral/bind +→ 创建新绑定（status = 'active', expiry_date = NOW + 30天） +→ users.referral_count += 1 +``` + +### 场景2: 切换推荐人 ✅ +``` +B 已绑定 A → B 点击 C 的链接 → /api/referral/bind +→ 旧绑定（A-B）标记为 'cancelled' +→ 创建新绑定（C-B, status = 'active', expiry_date = NOW + 30天） +→ A.referral_count -= 1, C.referral_count += 1 +``` + +### 场景3: 续期绑定 ✅ +``` +B 已绑定 A → B 再次点击 A 的链接 → /api/referral/bind +→ 更新绑定（expiry_date = NOW + 30天） +→ referral_count 不变 +``` + +### 场景4: 首次购买 ✅ +``` +B 绑定 C（5天前）→ B 购买 1.00 元章节（有 5% 优惠） +→ 实付 0.95 元 +→ C 获得佣金 0.95 * 90% = 0.855 元（四舍五入 0.86） +→ referral_bindings: purchase_count = 1, total_commission = 0.86, last_purchase_date = NOW +→ C.pending_earnings += 0.86 +→ 绑定保持 'active' +``` + +### 场景5: 多次购买 ✅ +``` +B 再次购买 1.00 元章节（还在 30 天内） +→ 实付 0.95 元 +→ C 再获得佣金 0.86 元 +→ referral_bindings: purchase_count = 2, total_commission = 1.72, last_purchase_date = NOW +→ C.pending_earnings += 0.86（累计 1.72） +→ 绑定保持 'active' +``` + +### 场景6: 自动解绑 ✅ +``` +B 绑定 A（30 天前）→ B 从未购买 → 定时任务执行 +→ 查找: status = 'active' AND expiry_date < NOW AND purchase_count = 0 +→ 更新: status = 'expired' +→ A.referral_count -= 1 +``` + +### 场景7: 提现 ✅ +``` +C 有 pending_earnings = 15.00 元 → 申请提现 12.00 元 +→ 验证 amount >= minWithdrawAmount（默认 10） +→ 验证 amount <= pending_earnings +→ 创建提现记录 +→ C.pending_earnings -= 12.00 = 3.00 +``` + +--- + +## ✅ 最终确认 + +### 代码逻辑 +- ✅ 所有 API 已适配新逻辑 +- ✅ 所有硬编码值已改为动态配置 +- ✅ 所有状态转换逻辑正确 +- ✅ 所有金额计算精确到分 + +### 数据库 +- ✅ 所有字段已添加 +- ✅ 所有索引已创建 +- ✅ 数据类型正确 +- ✅ 默认值正确 + +### 小程序 +- ✅ UI 已删除邀请码卡片 +- ✅ 绑定逻辑兼容后端 +- ✅ 支付逻辑兼容后端 +- ✅ 数据展示兼容后端 + +### 管理后台 +- ✅ 推广设置页面已创建 +- ✅ 菜单已添加 +- ✅ 配置读写正确 + +### 定时任务 +- ✅ 脚本已创建 +- ⏸️ 需在宝塔配置（部署时） + +--- + +## 🚀 部署检查项 + +部署前确认: +- ✅ 代码已修改 +- ✅ 数据库已迁移 +- ✅ 本地测试通过 + +部署后确认: +- ⏸️ PM2 重启成功 +- ⏸️ 定时任务配置成功 +- ⏸️ 管理后台可访问 `/admin/referral-settings` +- ⏸️ 小程序绑定/支付/分佣功能测试通过 + +--- + +## 📝 测试用例（可选） + +如需本地测试，运行: +```bash +node scripts/test-referral-flow.js +``` + +测试覆盖: +- ✅ 首次绑定 +- ✅ 续期绑定 +- ✅ 切换绑定 +- ✅ 首次购买分佣 +- ✅ 多次购买分佣 +- ✅ 过期绑定不分佣 + +--- + +## ✅ 结论 + +**所有代码逻辑和数据库修改已完成并验证，可以放心部署！** + +需要在宝塔面板配置的只有： +1. 重启 PM2 服务（让新代码生效） +2. 配置定时任务（自动解绑） + +参考文档: `开发文档/8、部署/新分销逻辑-宝塔操作清单.md` diff --git a/开发文档/8、部署/佣金计算逻辑检查.md b/开发文档/8、部署/佣金计算逻辑检查.md new file mode 100644 index 00000000..99d86591 --- /dev/null +++ b/开发文档/8、部署/佣金计算逻辑检查.md @@ -0,0 +1,307 @@ +# 佣金计算逻辑检查 + +## 🔍 用户反馈 + +**问题**: "推广者应该获取支付金额的90%，但却是10%" + +--- + +## 📊 配置值流转 + +### 1. 管理后台保存（/admin/referral-settings） + +**输入**: +``` +分销比例：90 (表示90%) +``` + +**保存代码**: +```typescript +const safeConfig = { + distributorShare: Number(config.distributorShare) || 0 +} +// 保存到数据库：distributorShare = 90 +``` + +**数据库存储**: +```json +{ + "distributorShare": 90 +} +``` + +--- + +### 2. 后端读取配置（/api/miniprogram/pay/notify） + +**读取代码**: +```typescript +const config = await getConfig('referral_config') +const distributorShare = config.distributorShare / 100 +// 结果：90 / 100 = 0.9 +``` + +**佣金计算**: +```typescript +const commission = Math.round(amount * distributorShare * 100) / 100 +// 例如：1元 * 0.9 = 0.9元 +``` + +--- + +### 3. 返回给小程序（/api/referral/data） + +**返回代码**: +```typescript +shareRate: Math.round(distributorShare * 100) +// 结果：0.9 * 100 = 90 +``` + +**小程序显示**: +```xml +你获得 {{shareRate}}% 收益 + +``` + +--- + +## ⚠️ 可能的问题点 + +### 问题1: 配置值保存错误 + +**检查点**: +- 管理后台输入的是 90 还是 0.9？ +- 数据库实际保存的值是多少？ + +**验证SQL**: +```sql +SELECT config_value FROM system_config WHERE config_key = 'referral_config'; +``` + +**预期结果**: +```json +{ + "distributorShare": 90 +} +``` + +**如果看到**: +```json +{ + "distributorShare": 0.1 // ❌ 错误！应该是 90 +} +``` + +--- + +### 问题2: 计算公式错误 + +**检查点**: 是否有地方用错了公式？ + +**错误示例**: +```typescript +// ❌ 错误：用了减法 +const commission = amount * (1 - distributorShare) +// 1 * (1 - 0.9) = 0.1 元（10%） + +// ✅ 正确：直接乘 +const commission = amount * distributorShare +// 1 * 0.9 = 0.9 元（90%） +``` + +--- + +### 问题3: 除以100的位置错误 + +**错误示例**: +```typescript +// ❌ 错误：没有除以100 +const distributorShare = config.distributorShare +const commission = amount * distributorShare / 100 +// 1 * 90 / 100 = 0.9 元（看起来对，但下一步就错了） +``` + +**正确方式**: +```typescript +// ✅ 正确：先除以100 +const distributorShare = config.distributorShare / 100 // 90 → 0.9 +const commission = amount * distributorShare // 1 * 0.9 = 0.9 +``` + +--- + +## 🧪 测试用例 + +### 测试1: 购买1元（无折扣） + +**输入**: +- 支付金额: 1.00元 +- distributorShare: 90 + +**计算过程**: +```typescript +const distributorShare = 90 / 100 = 0.9 +const commission = 1.00 * 0.9 = 0.90元 +``` + +**预期结果**: 推荐人获得 0.90元 + +--- + +### 测试2: 购买1元（5%折扣） + +**输入**: +- 原价: 1.00元 +- 好友优惠: 5% +- 实付: 0.95元 +- distributorShare: 90 + +**计算过程**: +```typescript +const finalAmount = 1.00 * (1 - 0.05) = 0.95元 +const commission = 0.95 * 0.9 = 0.855 ≈ 0.86元 +``` + +**预期结果**: 推荐人获得 0.86元 + +--- + +### 测试3: 如果配置错误保存为0.9 + +**输入**: +- 支付金额: 1.00元 +- distributorShare: 0.9 (❌ 错误的保存值) + +**计算过程**: +```typescript +const distributorShare = 0.9 / 100 = 0.009 +const commission = 1.00 * 0.009 = 0.009 ≈ 0.01元 +``` + +**错误结果**: 推荐人只获得 0.01元（1%）❌ + +--- + +## 🔍 排查步骤 + +### 步骤1: 检查数据库配置值 + +**SQL查询**: +```sql +SELECT config_key, config_value +FROM system_config +WHERE config_key = 'referral_config'; +``` + +**检查要点**: +- `distributorShare` 应该是 **90**（不是 0.9） +- 如果是其他值（如 10），说明保存时出错了 + +--- + +### 步骤2: 检查实际佣金记录 + +**SQL查询**: +```sql +SELECT + rb.referrer_id, + rb.referee_id, + rb.purchase_count, + rb.total_commission, + o.amount, + o.order_sn +FROM referral_bindings rb +JOIN orders o ON o.user_id = rb.referee_id AND o.status = 'paid' +WHERE rb.purchase_count > 0 +ORDER BY rb.last_purchase_date DESC +LIMIT 5; +``` + +**检查要点**: +- 订单金额 1.00元 → 佣金应该约 0.90元 +- 如果佣金是 0.10元，说明计算错误 + +--- + +### 步骤3: 检查控制台日志 + +**查看PM2日志**: +```bash +pm2 logs soul --lines 100 | grep "处理分佣" +``` + +**预期输出**: +``` +[PayNotify] 处理分佣: { + amount: 0.95, + commission: 0.855, + shareRate: '90%' +} +``` + +**如果看到**: +``` +shareRate: '10%' // ❌ 错误！ +``` + +--- + +## 🔧 可能的修复方案 + +### 修复1: 如果配置值错误 + +**检查数据库**: +```sql +SELECT config_value FROM system_config WHERE config_key = 'referral_config'; +``` + +**如果显示**: +```json +{"distributorShare": 10} // ❌ 错误 +``` + +**手动修复**: +```sql +UPDATE system_config +SET config_value = '{"distributorShare":90,"minWithdrawAmount":10,"bindingDays":30,"userDiscount":5,"enableAutoWithdraw":false}' +WHERE config_key = 'referral_config'; +``` + +**或者在管理后台重新保存** 90%。 + +--- + +### 修复2: 如果计算公式错误 + +**检查位置**: `app/api/miniprogram/pay/notify/route.ts` 第395行 + +**当前代码**: +```typescript +const commission = Math.round(amount * distributorShare * 100) / 100 +``` + +**验证**: +- 如果 distributorShare = 0.9，commission = 0.9元 ✅ +- 如果 distributorShare = 0.009，commission = 0.009元 ❌ + +--- + +## 📝 诊断建议 + +请提供以下信息以便诊断： + +1. **管理后台显示的值**: + - 进入 `/admin/referral-settings` + - 查看"分销比例"输入框中的值是多少？ + +2. **实际佣金金额**: + - 用户A购买1元商品 + - 推荐人B实际获得多少佣金？ + +3. **小程序显示的比例**: + - 分销中心显示的是"你获得 xx% 收益" + - 这个 xx 是多少？ + +--- + +**根据你的反馈，我会立即定位并修复问题！** diff --git a/开发文档/8、部署/佣金问题-快速诊断和修复.md b/开发文档/8、部署/佣金问题-快速诊断和修复.md new file mode 100644 index 00000000..c4132559 --- /dev/null +++ b/开发文档/8、部署/佣金问题-快速诊断和修复.md @@ -0,0 +1,232 @@ +# 佣金计算问题 - 快速诊断和修复 + +## 🚨 问题描述 + +用户反馈："推广者应该获取支付金额的90%，但却是10%" + +--- + +## 🔍 快速诊断 + +### 方法1: 检查管理后台配置 + +1. 登录管理后台：`https://soul.quwanzhi.com/admin` +2. 进入「推广设置」页面：`/admin/referral-settings` +3. 查看「分销比例」输入框中的数值 + +**如果显示 10** → 配置错误，应该改为 **90** + +**如果显示 90** → 配置正确，问题在其他地方 + +--- + +### 方法2: 检查实际佣金 + +1. 找一个推荐关系的订单 +2. 查看推荐人获得的佣金 + +**示例**: +- 用户B购买1元商品（无折扣） +- 推荐人A应得：0.90元（90%） +- 如果实际只得：0.10元 → 说明比例算反了 + +--- + +### 方法3: 检查小程序显示 + +打开小程序「分销中心」，查看推广规则： + +**应该显示**: +``` +好友成功付款后，你获得 90% 收益 +``` + +**如果显示**: +``` +好友成功付款后，你获得 10% 收益 +``` + +→ 说明后端返回的 `shareRate` 值错误 + +--- + +## 🔧 修复方案 + +### 修复1: 如果管理后台配置值错误 + +**步骤**: +1. 进入管理后台 `/admin/referral-settings` +2. 将「分销比例」改为 **90** +3. 点击「保存配置」 +4. 刷新小程序验证 + +--- + +### 修复2: 如果数据库配置值错误 + +**手动修复SQL**: +```sql +-- 1. 查看当前配置 +SELECT config_value FROM system_config WHERE config_key = 'referral_config'; + +-- 2. 如果 distributorShare 不是 90，手动更新 +UPDATE system_config +SET config_value = JSON_SET( + config_value, + '$.distributorShare', + 90 +) +WHERE config_key = 'referral_config'; + +-- 3. 验证修改 +SELECT config_value FROM system_config WHERE config_key = 'referral_config'; +``` + +--- + +### 修复3: 如果计算公式错误 + +**检查文件**: `app/api/miniprogram/pay/notify/route.ts` + +**第395行，当前代码应该是**: +```typescript +const commission = Math.round(amount * distributorShare * 100) / 100 +``` + +**如果错误写成了**: +```typescript +// ❌ 错误1：算反了 +const commission = Math.round(amount * (1 - distributorShare) * 100) / 100 + +// ❌ 错误2：没有先除100 +const distributorShare = config.distributorShare // 90（没除100） +const commission = amount * distributorShare / 100 // 1 * 90 / 100 = 0.9（看似对，但后续会错） +``` + +--- + +## 🧪 验证步骤 + +### 验证1: 手动计算 + +假设配置 `distributorShare = 90`: + +```javascript +// 读取配置 +const configValue = 90 + +// 转换为小数 +const distributorShare = configValue / 100 // = 0.9 + +// 计算佣金（购买1元） +const commission = 1.00 * 0.9 // = 0.90元 + +// 返回给小程序 +const shareRate = distributorShare * 100 // = 90 +``` + +**预期**: +- 购买1元 → 推荐人得 0.90元 +- 小程序显示：90% 返利 + +--- + +### 验证2: 查看实际订单 + +**SQL查询**: +```sql +SELECT + o.order_sn, + o.amount as 订单金额, + rb.total_commission as 累计佣金, + rb.purchase_count as 购买次数, + o.amount * 0.9 as 预期佣金90percent, + o.amount * 0.1 as 如果是10percent +FROM orders o +JOIN referral_bindings rb ON o.user_id = rb.referee_id +WHERE o.status = 'paid' + AND rb.purchase_count > 0 +ORDER BY o.pay_time DESC +LIMIT 5; +``` + +**对比**: +- 如果 `total_commission ≈ 预期佣金90percent` → 计算正确 +- 如果 `total_commission ≈ 如果是10percent` → 计算错误（算反了） + +--- + +## 🔍 代码审查 + +### 关键代码1: 读取配置 + +**文件**: `app/api/miniprogram/pay/notify/route.ts` 第357-360行 + +```typescript +const config = await getConfig('referral_config') +if (config?.distributorShare) { + distributorShare = config.distributorShare / 100 // ✅ 应该是这样 +} +``` + +**如果错误写成**: +```typescript +distributorShare = config.distributorShare // ❌ 没除100 +``` + +--- + +### 关键代码2: 计算佣金 + +**文件**: `app/api/miniprogram/pay/notify/route.ts` 第395行 + +```typescript +const commission = Math.round(amount * distributorShare * 100) / 100 +// ✅ 正确：1 * 0.9 = 0.9 +``` + +**如果错误写成**: +```typescript +const commission = Math.round(amount * (1 - distributorShare) * 100) / 100 +// ❌ 错误：1 * (1 - 0.9) = 0.1（算反了） +``` + +--- + +### 关键代码3: 返回比例 + +**文件**: `app/api/referral/data/route.ts` 第198行 + +```typescript +shareRate: Math.round(distributorShare * 100) +// ✅ 正确：0.9 * 100 = 90 +``` + +--- + +## 🚀 立即检查 + +请你帮我确认一下： + +### 问题1: 管理后台的配置值 +进入 `https://soul.quwanzhi.com/admin/referral-settings`，看看「分销比例」输入框中显示的是： +- [ ] 90（正确） +- [ ] 10（错误） +- [ ] 0.9（错误） + +### 问题2: 小程序显示的比例 +打开小程序「分销中心」，查看推广规则显示的是： +- [ ] "你获得 90% 收益"（正确） +- [ ] "你获得 10% 收益"（错误） + +### 问题3: 实际佣金金额 +如果有测试订单，查看： +- 购买金额：1.00元 +- 推荐人获得：_____ 元 + +**如果是 0.90元** → 计算正确 +**如果是 0.10元** → 计算错误 + +--- + +**请告诉我上述三个问题的实际情况，我会立即定位并修复！** diff --git a/开发文档/8、部署/其它.md b/开发文档/8、部署/其它.md new file mode 100644 index 00000000..ef1f24e7 --- /dev/null +++ b/开发文档/8、部署/其它.md @@ -0,0 +1,3 @@ +# 其它（合并自 宝塔配置检查、小程序上传复盘） + +宝塔配置检查说明、小程序上传复盘（版本 1.17、CLI 上传等）。详见原各文档。 diff --git a/开发文档/8、部署/分销与绑定流程图.md b/开发文档/8、部署/分销与绑定流程图.md new file mode 100644 index 00000000..8fd78cee --- /dev/null +++ b/开发文档/8、部署/分销与绑定流程图.md @@ -0,0 +1,383 @@ +# 分销与绑定流程图 + +> 用流程图把「绑定」和「推荐人/邀请码」在系统中的用法讲清楚。 +> 建议配合《邀请码分销规则说明》一起看。 + +--- + +## 一、概念速查 + +| 名词 | 是什么 | 存哪儿 | 谁用 | +|------|--------|--------|------| +| **邀请码** | 一串码，如 `SOULABC123` | 每个用户一条：`users.referral_code` | 链接里 `ref=邀请码`，用来**认出**是谁推荐的 | +| **推荐人** | 拿佣金的那个人（用户） | 用**用户ID**存：`referrer_id` | 绑定表、订单表、分佣都只认这个 ID | +| **被推荐人** | 通过链接进来的访客/买家 | 用**用户ID**存：`referee_id` | 绑定表里「谁被谁推荐」 | + +关系：**邀请码** → 查 `users` 表 → 得到**推荐人用户ID**（referrer_id）。系统里所有「归属、分佣」只认 referrer_id，不直接认邀请码字符串。 + +--- + +## 二、整体流程总览（一图看懂） + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ 分销全流程：从分享到分佣 │ +└─────────────────────────────────────────────────────────────────────────────────┘ + + 推广者 A（推荐人） 访客/买家 B（被推荐人） 系统 + + │ │ │ + │ 1. 分享带 ref 的链接 │ │ + │ ?ref=A的邀请码 │ │ + ├─────────────────────────────────────>│ 2. 点击链接进入小程序/阅读页 │ + │ ├─────────────────────────────────>│ + │ │ app.js: 存 referral_code │ + │ │ 可选: 记录访问 referral_visit │ + │ │ │ + │ │ 3. 登录（微信/手机号/getOpenId 拿到 user） │ + │ ├─────────────────────────────────>│ + │ │ 登录成功即调 /api/referral/bind │ + │ │ 入参: userId, referralCode │ + │ │ │ + │ │ 4. 绑定逻辑 │ + │ │ referral_code │ + │ │ → 查 users 得 │ + │ │ referrer_id=A │ + │ │ 写 referral_ │ + │ │ bindings │ + │ │ (referee=B, │ + │ │ referrer=A) │ + │ │<─────────────────────────────────┤ + │ │ 绑定成功（new/renew/takeover） │ + │ │ │ + │ │ 5. 下单（章节/找伙伴） │ + │ │ POST /api/miniprogram/pay │ + │ │ body: referralCode(可选) │ + │ ├─────────────────────────────────>│ + │ │ 6. 定推荐人 │ + │ │ 先查 bindings │ + │ │ (referee=B)→A │ + │ │ 无则用 referral│ + │ │ Code 解析→A │ + │ │ 写 orders. │ + │ │ referrer_id=A,│ + │ │ referral_code │ + │ │<─────────────────────────────────┤ + │ │ 返回支付参数 │ + │ │ │ + │ │ 7. 调起微信支付 │ + │ ├───────────────────────────────> 微信 + │ │ 8. 用户付款成功 │ + │ │<─────────────────────────────── 微信 + │ │ │ + │ │ 9. 支付回调 │ + │ │ POST .../notify│ + │ │ 查 bindings │ + │ │ (referee=B)→A │ + │ │ 佣金=金额×90% │ + │ │ A.pending_ │ + │ │ earnings += 佣金│ + │ │ binding→ │ + │ │ converted │ + │ │ │ + │ 10. 推广者 A 看到待结算收益 +90% │ │ + │<─────────────────────────────────────│ │ +``` + +--- + +## 三、绑定流程（邀请码 → 推荐关系） + +绑定解决的是：**「谁（B）是通过谁（A）的链接来的」**，并写入 `referral_bindings`。 + +**绑定规则（后端统一保证）：** +- **不重复绑定**：被推荐人 B 已有**当前推荐人 A** 的有效绑定时，再次用 A 的邀请码调用 bind → **不新建记录**，只做**续期**（把过期时间再延长 30 天）。 +- **有时效**：每条绑定的有效期为 **30 天**（`expiry_date`）；分佣、下单定推荐人时只认「未过期」的绑定。 +- **超时可重新绑定**：超过 30 天未续期的绑定视为过期；此时 B 再通过**其他人 C** 的链接进来并登录 → 允许绑定到 C（旧绑定标记过期，新绑定 C，即「抢夺」）；若仍通过 A 的链接 → 续期 A 的绑定。 + +**绑定从登录就开始**：只要前端拿到 userId（登录成功），就立刻用当前的 `pendingReferralCode` 调 `/api/referral/bind`，不等到下单。后端根据上述规则决定是**新绑定 / 续期 / 抢夺 / 拒绝**。 + +```mermaid +flowchart TB + subgraph 入口 + A1["推广者 A 分享链接
带 ref=A的邀请码"] + A2["访客 B 点击链接进入"] + end + + subgraph 前端 + B1["app.js: 检测到 ref"] + B2["写入 storage: referral_code + pendingReferralCode"] + B3["若已登录 → 立即调 bind"] + B4["若未登录 → 等任意登录成功后再调 bind"] + B5["登录含: login / loginWithPhone / getOpenId 拿到 user 时"] + end + + subgraph 后端绑定API["POST /api/referral/bind"] + C1["入参: userId(B), referralCode"] + C2["用 referralCode 查 users 表 → 推荐人 A"] + C3["不能自己推荐自己"] + C4["查 B 是否已有有效绑定(active)"] + C5{"已有绑定?"} + C6["同一推荐人 A → 只续期，不重复绑定
expiry = 当前+30天"] + C7["不同人且已过期(>30天) → 可重新绑定
旧绑定过期，新绑定 A"] + C8["不同人且未过期 → 拒绝"] + C9["无绑定 / 续期 / 抢夺后 → 写 binding
referrer_id=A, referee_id=B, expiry=+30天"] + end + + A1 --> A2 --> B1 --> B2 + B2 --> B3 + B2 --> B4 + B4 --> B5 + B3 --> C1 + B5 --> C1 + C1 --> C2 --> C3 --> C4 --> C5 + C5 -->|无| C9 + C5 -->|有，同一人| C6 --> C9 + C5 -->|有，另一人已过期| C7 --> C9 + C5 -->|有，另一人未过期| C8 +``` + +要点： +- **绑定表**是「谁推荐了谁」的**唯一权威**；分佣只看这张表。 +- **已有绑定不重复**：同一推荐人再次绑只续期；**30 天**内不能换绑其他推荐人，超过 30 天可重新绑定（被新推荐人「抢夺」或原推荐人续期）。 +- **邀请码**只在「解析出推荐人是谁」时用，解析完得到的是 **referrer_id**（用户ID）。 + +--- + +## 四、下单时「推荐人」怎么定（写订单） + +创建订单时要把「这笔单算谁的推广」记在 `orders.referrer_id` 和 `orders.referral_code`。逻辑是：**先认绑定，再认邀请码**。 + +```mermaid +flowchart LR + subgraph 请求 + R1["POST /api/miniprogram/pay"] + R2["body: userId(B), referralCode(可选)"] + end + + subgraph 定推荐人 + S1["查 referral_bindings"] + S2["WHERE referee_id = B
AND status='active'
AND expiry_date > NOW()"] + S3{"查到有效绑定?"} + S4["referrer_id = 绑定里的 referrer_id"] + S5["referrer_id = 用 referralCode
查 users 得到的 id"] + S6["都无 → referrer_id = null"] + end + + subgraph 写订单 + T1["INSERT orders"] + T2["referrer_id = 上面得到的"] + T3["referral_code = 请求里的 referralCode
或推荐人当前 users.referral_code"] + end + + R1 --> R2 --> S1 --> S2 --> S3 + S3 -->|是| S4 + S3 -->|否，但有 referralCode| S5 + S3 -->|否且无| S6 + S4 --> T1 + S5 --> T1 + S6 --> T1 + T1 --> T2 --> T3 +``` + +结论： +- **有绑定** → 订单的推荐人 = 绑定里的推荐人（与下单时传不传 referralCode 无关）。 +- **无绑定但传了 referralCode** → 用邀请码解析出推荐人，写入订单。 +- 订单上的 **referrer_id** 用于后台展示、对账；**分佣不看订单**，只看绑定表。 + +--- + +## 五、分佣流程（支付成功后） + +分佣**只看绑定表**，不看订单上的 referrer_id。 + +```mermaid +flowchart TB + subgraph 触发 + P1["微信支付成功"] + P2["POST /api/miniprogram/pay/notify"] + P3["body: 订单号、金额、买家等"] + end + + subgraph 回调逻辑 + Q1["更新订单 status=paid"] + Q2["解锁用户权限(章节/全书)"] + Q3["查 referral_bindings"] + Q4["WHERE referee_id = 买家"] + Q5["AND status='active'"] + Q6["AND expiry_date > NOW()"] + Q7{"查到有效绑定?"} + Q8["取 referrer_id = 推广者 A"] + Q9["佣金 = 订单金额 × 90%"] + Q10["A.pending_earnings += 佣金"] + Q11["该绑定 status → converted"] + Q12["记录 commission_amount, order_id"] + Q13["不分佣"] + end + + P1 --> P2 --> P3 --> Q1 --> Q2 --> Q3 --> Q4 --> Q5 --> Q6 --> Q7 + Q7 -->|是| Q8 --> Q9 --> Q10 --> Q11 --> Q12 + Q7 -->|否| Q13 +``` + +要点： +- 分佣**只认** `referral_bindings` 里「买家 → 有效绑定 → 推荐人」。 +- 订单里的 referrer_id / referral_code **不参与**分佣计算，只用于统计和展示。 + +--- + +### 什么情况下能拿到佣金（推广者视角） + +满足下面**全部**条件时，你（推广者）才能拿到这笔订单的佣金： + +1. **对方是通过你的链接进来的** + 对方点击的链接里带有你的邀请码（如 `?ref=你的邀请码`），进入小程序后系统会记下推荐码，并在登录时用于绑定。 + +2. **对方已经绑定到你** + 对方完成登录后，系统成功调用了绑定接口（新绑定或续期），且当前存在一条「被推荐人 = 对方、推荐人 = 你」的绑定记录，且该绑定 **status = active**、**expiry_date > 当前时间**（在 30 天有效期内或已续期）。 + +3. **对方在绑定有效期内下单并支付成功** + 对方在上述有效期内发起了购买（章节或全书），并完成微信支付；支付成功后，微信会回调我们的接口。 + +4. **支付回调时仍能查到你的有效绑定** + 支付成功回调执行时，系统按「买家 = 对方」查 `referral_bindings`，能查到一条有效绑定且推荐人是你，才会把约 90% 的佣金计入你的待结算收益（pending_earnings），并把该绑定标记为已转化（converted）。 + +**简单记**：你的链接 → 对方进来并登录绑定到你 → 有效期内对方付款 → 你拿佣金。 + +--- + +### 章节分享这块的分销收益方式 + +章节页分享（读某一章时分享给好友/朋友圈）与首页、推广中心的分享**用同一套绑定与分佣规则**，只是落地页是「某一章」的阅读页。收益方式如下： + +1. **入口与绑定** + 你从阅读页分享出去的链接带 `ref=你的邀请码`（例如 `/pages/read/read?id=1.2&ref=你的邀请码`）。对方点进后进入**该章节**阅读页，系统记下推荐码；对方**登录**后即完成绑定（新绑定或续期）。绑定规则（30 天、不重复绑、超时可重绑）与其它分享入口一致。 + +2. **收益比例** + 订单实付金额的**约 90%** 给推广者（与全书、其它章节一致，由 `referral_config.distributorShare` 配置）。对方买的是**这一章、别的章还是全书**，都按该笔订单金额 × 90% 计算佣金。 + +3. **计佣次数（每个被推荐人只计一次）** + 系统在支付成功回调里会查「该买家」的**有效绑定**，有则给推荐人加佣金，并把这条绑定标记为**已转化（converted）**。 + 因此：**同一个被推荐人在绑定有效期内，只有其「第一笔」支付会给你分佣**；该用户之后再买其它章节或全书，**不再**重复给你分佣（绑定已用掉）。 + +4. **小结** + **章节分享的收益**：你分享章节链接（带 ref）→ 对方进来并登录绑定到你 → 对方在有效期内**第一次**支付（可以是这一章、别的章或全书）→ 你获得**该笔订单金额的约 90%**；该用户后续订单不再给你分佣。 + +--- + +## 六、推荐人 vs 邀请码（怎么用、不混用） + +```mermaid +flowchart LR + subgraph 入口 + L1["链接 ref=SOULABC123"] + end + + subgraph 解析 + L2["邀请码 = SOULABC123"] + L3["users WHERE referral_code = ?"] + L4["推荐人 = 该用户的 id"] + end + + subgraph 存储 + M1["referral_bindings.referrer_id"] + M2["orders.referrer_id"] + M3["分佣发给谁"] + end + + L1 --> L2 --> L3 --> L4 + L4 --> M1 + L4 --> M2 + L4 --> M3 + + style L2 fill:#f9f,stroke:#333 + style L4 fill:#9f9,stroke:#333 +``` + +- **邀请码**：只在「从链接/请求里认出是谁」这一步用，用完就解析成 **referrer_id**。 +- **推荐人**：所有「归属、分佣、统计」都只用 **referrer_id**，不会把邀请码字符串当推荐人存。 + +--- + +## 七、表与字段关系简图 + +```mermaid +erDiagram + users ||--o{ referral_bindings : "referrer_id" + users ||--o{ referral_bindings : "referee_id" + users { + string id PK + string referral_code "自己的邀请码" + } + referral_bindings { + string referrer_id "推荐人(谁拿佣金)" + string referee_id "被推荐人(买家)" + string status "active|converted|expired" + timestamp expiry_date + } + orders { + string user_id "买家" + string referrer_id "推荐人ID(展示/对账)" + string referral_code "下单时邀请码(展示)" + } + referral_bindings ||--o{ orders : "分佣时关联" +``` + +- **绑定**：`referrer_id` = 推荐人，`referee_id` = 被推荐人；分佣只看这张表。 +- **订单**：`referrer_id`、`referral_code` 只做展示和对账，不参与分佣计算。 + +--- + +## 八、逻辑漏洞与注意点 + +以下为与流程图、实现对照后容易出现的漏洞和设计注意点，便于排查与加固。 + +### 8.1 严重：支付回调中买家身份不能信任客户端 + +**问题**：支付回调（`/api/miniprogram/pay/notify`）里若**优先**使用请求体/attach 里的 `userId` 作为买家，则该 `userId` 来自**创建订单时客户端传入**的 `body.userId`。若被篡改（如传成他人 userId），会导致： +- 订单归属、解锁权限记到错误用户； +- 分佣按「错误买家」查绑定表，可能把佣金算到错误推荐人或不分佣。 + +**正确做法**：**买家身份必须以微信回调中的 `openId` 为准**（微信侧不可伪造），用 `openId` 查 `users` 得到 `buyerUserId`；attach 中的 `userId` 仅作辅助或校验，不一致时以 openId 解析结果为准。 + +**实现建议**：在 notify 中先 `buyerUserId = 由 openId 查 users 得到`；若查不到再回退到 attach.userId，并打日志告警。 + +--- + +### 8.2 设计缺口：先下单、后绑定会导致无分佣 + +**问题**：流程图要求「先绑定、再下单」分佣才生效。若用户通过 A 的链接进入但**未调用** `/api/referral/bind`（未登录就下单、或 bind 失败/漏调），下单时传了 `referralCode`，订单上会有 `referrer_id=A`，但**分佣只看绑定表**，此时无绑定 → 不会给 A 分佣。 + +**结论**：这是当前设计下的预期行为，不是 bug，但需要在产品/运营上保证「进入后尽快登录并完成绑定」，或在文档中明确写清：**只有存在有效绑定时支付成功才会分佣**。 + +--- + +### 8.3 重复回调与重复分佣 + +**现状**：微信可能对同一笔支付多次回调。当前实现： +- 订单状态已为 `paid` 时跳过订单更新； +- 分佣时只取 `status='active'` 的绑定，且分佣后将该绑定置为 `converted`，同一买家不会再有第二条 active 绑定参与分佣。 + +因此**不会重复加佣**。无需改流程图，实现已防护。 + +--- + +### 8.4 绑定表与 users.referred_by 双写 + +**现状**：绑定 API 在「新绑定」或「抢夺」时会写 `users.referred_by`，与 `referral_bindings` 双写；「续期」只更新绑定表，不改 `referred_by`。 +分佣、下单定推荐人**只读绑定表**；GET 查询「我的推荐人」等可能读 `users.referred_by`。只要绑定接口保证 new/takeover 时双写一致，则无逻辑漏洞。若以后有接口只改 `referred_by` 而不改绑定表，就会不一致，需避免。 + +--- + +### 8.5 小结 + +| 类型 | 说明 | +|------------|------| +| 必须修 | 支付回调中买家身份以 openId 解析为准，不信任 attach.userId。 | +| 文档/产品 | 明确「先绑定再下单才能分佣」；未绑定仅下单只记订单归属、不分佣。 | +| 已防护 | 重复回调不会导致重复分佣。 | +| 需长期一致 | 绑定表与 users.referred_by 在 new/takeover 时双写，避免单改其一。 | + +--- + +若要把某一段改成「按步骤」的纯文字版或拆成多张图，可以说明要哪一段（绑定 / 下单 / 分佣 / 概念）。 diff --git a/开发文档/8、部署/分销提现流程图.md b/开发文档/8、部署/分销提现流程图.md new file mode 100644 index 00000000..45835765 --- /dev/null +++ b/开发文档/8、部署/分销提现流程图.md @@ -0,0 +1,127 @@ +# 分销提现流程图 + +## 一、整体流程 + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ 小 程 序 端 │ +└─────────────────────────────────────────────────────────────────────────────────┘ + + [用户] 推广中心 → 可提现金额 ≥ 最低额 → 点击「申请提现」 + │ + ▼ + POST /api/miniprogram/withdraw (WithdrawPost) + │ 校验：可提现余额、最低金额、用户 openId + ▼ + 写入 withdrawals：status = pending + │ + ▼ + 提示「提现申请已提交，审核通过后将打款至您的微信零钱」 + +───────────────────────────────────────────────────────────────────────────────── + +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ 管 理 端 (soul-admin) │ +└─────────────────────────────────────────────────────────────────────────────────┘ + + [管理员] 分销 / 提现审核 → GET /api/admin/withdrawals 拉列表 + │ + ├── 点「拒绝」 → PUT /api/admin/withdrawals { action: "reject" } + │ ▼ + │ status = failed，写 error_message + │ + └── 点「通过」 → PUT /api/admin/withdrawals { action: "approve" } + │ + ▼ + 调 wechat.InitiateTransferByFundApp (FundApp 单笔) + │ + ┌───────────────┼───────────────┐ + ▼ ▼ ▼ + [微信报错] [未返回单号] [成功受理] + │ │ │ + ▼ ▼ ▼ + status=failed status=failed status=processing + 返回报错信息 返回提示 写 detail_no,batch_no,batch_id + 返回「已发起打款，微信处理中」 + +───────────────────────────────────────────────────────────────────────────────── + +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ 微 信 侧 与 回 调 │ +└─────────────────────────────────────────────────────────────────────────────────┘ + + 微信异步打款 + │ + ▼ + 打款结果 → POST /api/payment/wechat/transfer/notify (PaymentWechatTransferNotify) + │ 验签、解密，得到 out_bill_no / transfer_bill_no / state / fail_reason + │ 用 detail_no = out_bill_no 找到提现记录，且仅当 status 为 processing / pending_confirm 时更新 + ▼ + state=SUCCESS → status = success + state=FAIL/CANCELLED → status = failed，写 fail_reason + +───────────────────────────────────────────────────────────────────────────────── + +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ 可 选：主 动 同 步 │ +└─────────────────────────────────────────────────────────────────────────────────┘ + + 管理端 POST /api/admin/withdrawals/sync（可带 id 同步单条，或不带 id 同步所有） + │ 只处理 status IN (processing, pending_confirm) + │ FundApp 单笔：用 detail_no 调 QueryTransferByOutBill + ▼ + 按微信返回的 state 更新 status = success / failed（与回调逻辑一致） + +───────────────────────────────────────────────────────────────────────────────── + +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ 小 程 序「我 的」- 待 确 认 收 款 │ +└─────────────────────────────────────────────────────────────────────────────────┘ + + [用户] 我的页 → 仅登录显示「待确认收款」区块 + │ + ▼ + GET /api/miniprogram/withdraw/pending-confirm?userId=xxx (WithdrawPendingConfirm) + │ 只返回 status IN (processing, pending_confirm) 的提现（审核通过后的） + ▼ + 展示列表：金额、日期、「确认收款」按钮 + │ + ▼ + 点击「确认收款」→ 需要 item.package + mchId + appId 调 wx.requestMerchantTransfer + │ 当前后端 list 里 package 为空，故会提示「请稍后刷新再试」 + └─ 若后续接入微信返回的 package，可在此完成「用户确认收款」闭环 +``` + +## 二、状态流转 + +| 阶段 | 状态 (status) | 含义 | +|--------------|----------------|------| +| 用户申请 | **pending** | 待审核，已占可提现额度 | +| 管理员通过 | **processing** | 已发起打款，微信处理中 | +| 微信回调成功 | **success** | 打款成功（已到账） | +| 微信回调失败/拒绝 | **failed** | 打款失败，写 fail_reason | +| 预留 | **pending_confirm** | 待用户确认收款（当前流程未改此状态，仅接口可返回） | + +## 三、可提现与待确认口径 + +- **可提现** = 累计佣金 − 已提现 − 待审核金额 + 待审核金额 = 所有 status 为 `pending`、`processing`、`pending_confirm` 的提现金额之和。 +- **待确认收款列表**：仅包含 **审核已通过** 的提现，即 status 为 `processing` 或 `pending_confirm`，不包含 `pending`。 + +## 四、主要接口与代码位置 + +| 环节 | 接口/行为 | 代码位置 | +|------------|-----------|----------| +| 用户申请 | POST `/api/miniprogram/withdraw` | soul-api `internal/handler/withdraw.go` WithdrawPost | +| 可提现计算 | referral/data、withdraw 校验 | `withdraw.go` computeAvailableWithdraw；`referral.go` 提现统计 | +| 管理端列表 | GET `/api/admin/withdrawals` | `internal/handler/admin_withdrawals.go` AdminWithdrawalsList | +| 管理端通过/拒绝 | PUT `/api/admin/withdrawals` | `admin_withdrawals.go` AdminWithdrawalsAction | +| 微信打款 | FundApp 单笔 | soul-api `internal/wechat/transfer.go` InitiateTransferByFundApp | +| 微信回调 | POST `/api/payment/wechat/transfer/notify` | `internal/handler/payment.go` PaymentWechatTransferNotify | +| 管理端同步 | POST `/api/admin/withdrawals/sync` | `admin_withdrawals.go` AdminWithdrawalsSync | +| 待确认列表 | GET `/api/miniprogram/withdraw/pending-confirm` | `withdraw.go` WithdrawPendingConfirm | + +## 五、说明 + +- 当前实现：审核通过后直接调微信 FundApp 单笔打款，最终由**微信回调**或**管理端同步**把状态更新为 success/failed。 +- 「待确认收款」列表只展示已审核通过的记录；点击「确认收款」需后端下发的 `package` 才能调起 `wx.requestMerchantTransfer`，目前该字段为空，前端会提示「请稍后刷新再试」。若后续接入微信返回的 package，可在此完成用户确认收款闭环。 diff --git a/开发文档/8、部署/存客宝API-Key约定.md b/开发文档/8、部署/存客宝API-Key约定.md new file mode 100644 index 00000000..030d68a6 --- /dev/null +++ b/开发文档/8、部署/存客宝API-Key约定.md @@ -0,0 +1,28 @@ +# 存客宝 API Key 约定 + +## 约定说明 + +存客宝（ckbapi.quwanzhi.com）不同业务使用**不同的 apiKey**，对接时需按场景选用，避免混用。 + +| 场景 | 用途 | Key 来源 | 说明 | +|------|------|----------|------| +| **链接卡若** | 首页「链接卡若」留资，添加卡若为好友 | 环境变量 `CKB_LEAD_API_KEY` | 需在 .env 中配置；未配置时回退为下方「其他场景」的 key；请求方式为 **POST** + JSON（name, phone, wechatId, apiKey, timestamp, sign） | +| **其他** | join（团队/资源/导师/合伙）、match（找伙伴匹配）等 | 代码常量 `ckbAPIKey` | 当前为 `fyngh-ecy9h-qkdae-epwd5-rz6kd` | + +## 配置示例 + +- **链接卡若**（添加好友需用专用 key，示例）： + ```env + CKB_LEAD_API_KEY=2y4v5-rjhfc-sg5wy-zklkv-bg0tl + ``` +- 后续若有其他「添加某某为好友」类场景，由存客宝提供对应 key，再在配置或代码中单独挂接，**不要与链接卡若的 key 混用**。 + +## 代码位置 + +- soul-api：`internal/handler/ckb.go` + - 链接卡若：`CKBLead` 中读取 `config.Get().CkbLeadAPIKey`，有则用，无则用 `ckbAPIKey` + - join/match：统一使用 `ckbAPIKey` + +--- + +记录时间：2025-03；原因：链接卡若需专用 key 才能正常添加好友，其他场景用另一 key。 diff --git a/开发文档/8、部署/宝塔面板配置订单同步定时任务.md b/开发文档/8、部署/宝塔面板配置订单同步定时任务.md new file mode 100644 index 00000000..58f9a2af --- /dev/null +++ b/开发文档/8、部署/宝塔面板配置订单同步定时任务.md @@ -0,0 +1,369 @@ +# 宝塔面板配置订单同步定时任务 + +> 适用于：有宝塔面板的服务器 +> 难度：⭐（非常简单，3 分钟搞定） + +--- + +## 一、准备工作 + +### 1. 生成安全密钥 + +打开终端（本地电脑），执行： + +```bash +# Windows PowerShell +-join ((65..90) + (97..122) + (48..57) | Get-Random -Count 32 | % {[char]$_}) + +# 或手动生成一个 32 位随机字符串，例如： +# 密钥已写死在代码里，见下文 URL +``` + +**接口使用的固定密钥**：`soul_cron_sync_orders_2026`（无需自己生成） + +--- + +## 二、宝塔面板配置步骤 + +### 步骤 1：登录宝塔面板 + +1. 浏览器打开：`http://你的服务器IP:8888` +2. 输入账号密码登录 + +### 步骤 2：打开计划任务 + +1. 左侧菜单点击 **"计划任务"** +2. 点击右上角 **"添加任务"** + +### 步骤 3：配置任务（方案 A - 访问 URL，推荐） + +在弹出的对话框中填写： + +| 字段 | 填写内容 | 说明 | +|------|---------|------| +| **任务类型** | 选择 `访问URL` | 下拉框选择 | +| **任务名称** | `订单状态同步` | 随便填，方便识别 | +| **执行周期** | 选择 `N分钟` | 下拉框选择 | +| **分钟选择** | 填 `5` | 表示每 5 分钟执行一次 | +| **URL地址** | `https://soul.quwanzhi.com/api/cron/sync-orders?secret=soul_cron_sync_orders_2026` | 密钥已写死在代码里，无需修改 | + +**完整 URL 示例**（密钥已写死在代码里，直接用即可）： +``` +https://soul.quwanzhi.com/api/cron/sync-orders?secret=soul_cron_sync_orders_2026 +``` + +### 步骤 4：点击保存 + +点击底部的 **"提交"** 或 **"确定"** 按钮。 + +### 步骤 5：验证任务已添加 + +在任务列表中应该能看到： +- ✅ 任务名称：订单状态同步 +- ✅ 类型：访问URL +- ✅ 周期：每 5 分钟 +- ✅ 状态：正常（绿色） + +--- + +## 三、立即测试执行 + +### 方法 1：宝塔面板手动执行 + +1. 在任务列表中找到刚添加的任务 +2. 点击右侧的 **"执行"** 按钮 +3. 查看执行结果： + - 成功：显示 JSON 响应 `{"success":true,...}` + - 失败：显示错误信息 + +### 方法 2：浏览器测试 + +直接在浏览器打开： +``` +https://soul.quwanzhi.com/api/cron/sync-orders?secret=YOUR_SECRET +``` + +**预期响应**（成功）： +```json +{ + "success": true, + "message": "订单状态同步完成", + "total": 0, + "synced": 0, + "expired": 0, + "error": 0, + "duration": 123 +} +``` + +**如果响应 401 错误**： +```json +{ + "success": false, + "error": "未授权访问" +} +``` +说明密钥不对，检查 URL 中的 `secret` 参数。 + +--- + +## 四、查看执行日志 + +### 宝塔面板查看 + +1. 计划任务列表 +2. 找到"订单状态同步"任务 +3. 点击右侧的 **"日志"** 按钮 +4. 查看最近的执行记录 + +**正常日志示例**： +``` +[2026-02-04 21:00:00] 开始执行 +[2026-02-04 21:00:01] 状态码: 200 +[2026-02-04 21:00:01] 响应: {"success":true,"synced":0,"expired":0} +[2026-02-04 21:00:01] 执行完成 +``` + +--- + +## 五、配置环境变量（重要！） + +定时任务需要密钥验证，必须在项目中配置： + +### 方法 1：通过宝塔面板配置 + +1. 左侧菜单 → **网站** +2. 找到 `soul.quwanzhi.com` 网站 +3. 点击 **设置** +4. 左侧选择 **"伪静态"** 或 **"配置文件"**（取决于宝塔版本） +5. 找到 Node.js 项目的启动配置 + +### 方法 2：在项目根目录创建 `.env.production` + +SSH 登录服务器： +```bash +ssh root@你的服务器IP + +cd /www/wwwroot/soul + +# 编辑 .env.production +nano .env.production +``` + +添加以下内容： +```bash +# 定时任务密钥（与宝塔任务中的 secret 保持一致） +# CRON_SECRET 已写死在代码，无需配置 + +# 微信支付 API 密钥（从微信商户平台获取） +WECHAT_API_KEY=你的32位API密钥 +``` + +保存后重启项目： +```bash +pm2 restart soul +``` + +--- + +## 六、方案 B：Shell 脚本（备选） + +如果不想用 URL 方式，也可以用 Shell 脚本： + +### 步骤 1：添加任务 + +任务类型选择：`Shell 脚本` + +### 步骤 2：填写脚本 + +```bash +#!/bin/bash +curl -X GET "https://soul.quwanzhi.com/api/cron/sync-orders?secret=YOUR_SECRET" >> /www/wwwlogs/cron_sync_orders.log 2>&1 +``` + +### 步骤 3：设置执行周期 + +- 类型：N分钟 +- 周期：5 + +--- + +## 七、方案 C：Python 脚本（高级） + +如果你想用 Python 脚本直接执行： + +### 步骤 1：确保 Python 环境 + +```bash +# SSH 登录服务器 +ssh root@你的服务器IP + +# 安装依赖 +pip3 install pymysql requests +``` + +### 步骤 2：上传脚本 + +确保脚本已上传到服务器： +``` +/www/wwwroot/soul/scripts/sync_order_status.py +``` + +### 步骤 3：宝塔添加任务 + +- 任务类型：`Shell 脚本` +- 脚本内容： + ```bash + cd /www/wwwroot/soul && python3 scripts/sync_order_status.py >> /www/wwwlogs/sync_orders.log 2>&1 + ``` +- 执行周期：每 5 分钟 + +--- + +## 八、验证是否生效 + +### 1. 创建测试订单 + +```sql +-- 通过宝塔面板 → 数据库 → soul_miniprogram → SQL窗口 +INSERT INTO orders (id, order_sn, user_id, open_id, product_type, product_id, amount, status, created_at, updated_at) +VALUES ('TEST_SYNC', 'TEST_SYNC_001', 'test_user', 'test_openid', 'section', '1.2', 1.00, 'created', DATE_SUB(NOW(), INTERVAL 35 MINUTE), DATE_SUB(NOW(), INTERVAL 35 MINUTE)); +``` + +### 2. 等待定时任务执行（最多 5 分钟） + +或手动执行：宝塔面板 → 计划任务 → 点击"执行" + +### 3. 查询订单状态 + +```sql +SELECT order_sn, status, created_at, updated_at +FROM orders +WHERE order_sn = 'TEST_SYNC_001'; +``` + +**预期结果**： +- 状态应该变为 `expired`（因为超过 30 分钟） + +### 4. 清理测试数据 + +```sql +DELETE FROM orders WHERE order_sn = 'TEST_SYNC_001'; +``` + +--- + +## 九、常见问题排查 + +### Q1: 任务显示"执行失败" + +**可能原因**： +1. URL 地址错误 +2. 密钥不对（401 错误） +3. 服务器网络问题 + +**解决方案**： +1. 检查 URL 是否完整 +2. 检查 `secret` 参数是否与 `.env.production` 中一致 +3. 在浏览器中手动访问该 URL 测试 + +### Q2: 返回 401 未授权 + +**原因**：密钥不匹配 + +**解决方案**： +1. 密钥已写死，无需配置 `CRON_SECRET` +2. 确认宝塔任务 URL 中的 `secret` 参数 +3. 确保两者完全一致 +4. 重启项目：`pm2 restart soul` + +### Q3: 返回 500 错误 + +**可能原因**： +1. 数据库连接失败 +2. 代码有 bug + +**解决方案**： +1. 查看应用日志：`pm2 logs soul` +2. 检查数据库是否正常 +3. 检查环境变量是否配置 + +### Q4: 看不到执行日志 + +**解决方案**： +1. 宝塔面板 → 计划任务 → 点击任务右侧的"日志" +2. 或查看自定义日志文件： + ```bash + tail -f /www/wwwlogs/cron_sync_orders.log + ``` + +--- + +## 十、监控与优化 + +### 设置告警（可选） + +宝塔面板 → 监控 → 进程守护，添加监控项： +- 监控类型：URL 监控 +- URL：`https://soul.quwanzhi.com/api/cron/sync-orders?secret=YOUR_SECRET` +- 监控周期：5 分钟 +- 告警方式：邮件/企业微信 + +### 调整执行频率 + +根据实际情况调整： +- **订单少**：10 分钟 / 15 分钟 +- **订单多**：3 分钟 / 5 分钟 +- **高峰期**：1 分钟（不推荐，增加服务器负载） + +--- + +## 十一、配置清单（Checklist） + +完成以下步骤，确保定时任务正常运行： + +- [ ] 宝塔面板添加计划任务（访问 URL，密钥已写死：soul_cron_sync_orders_2026） +- [ ] 配置 `.env.production` 中的 `WECHAT_API_KEY`（可选，用于查询微信订单状态） +- [ ] 重启项目：`pm2 restart soul` +- [ ] 手动执行测试（宝塔面板点击"执行"） +- [ ] 验证响应正常（`{"success":true}`） +- [ ] 查看日志确认任务执行 +- [ ] 创建测试订单验证（可选） +- [ ] 清理测试数据（可选） + +--- + +## 十二、最终配置示例 + +### 宝塔计划任务配置 + +``` +任务名称: 订单状态同步 +任务类型: 访问URL +执行周期: N分钟 -> 5 +URL地址: https://soul.quwanzhi.com/api/cron/sync-orders?secret=soul_cron_sync_orders_2026 +``` + +### 项目环境变量 `.env.production`（可选） + +密钥已写死，无需配置 `CRON_SECRET`。若需微信支付查询订单状态，可配置： + +```bash +# 微信支付 API 密钥（从商户平台获取，用于同步时查询订单真实状态） +WECHAT_API_KEY=YOUR_32_CHAR_API_KEY_HERE + +# 其他环境变量... +DATABASE_URL=mysql://... +``` + +--- + +## 完成！ + +配置完成后，系统会： +- ✅ 每 5 分钟自动检查未支付订单 +- ✅ 查询微信支付状态并同步 +- ✅ 超时订单自动标记为 expired +- ✅ 支付成功订单自动解锁内容 + +再也不用担心支付回调丢失导致用户无法解锁内容了！🎉 diff --git a/开发文档/8、部署/支付接口清单.md b/开发文档/8、部署/支付接口清单.md new file mode 100644 index 00000000..a49505a1 --- /dev/null +++ b/开发文档/8、部署/支付接口清单.md @@ -0,0 +1,366 @@ +# 支付相关接口清单 + +**日期**: 2026-02-04 +**说明**: 所有支付相关后端API接口的完整清单 + +--- + +## ✅ 已创建的接口 + +### 1. 小程序支付接口 + +#### `/api/miniprogram/pay` (POST) +**功能**: 创建支付订单并调用微信支付 + +**文件**: `app/api/miniprogram/pay/route.ts` + +**请求参数**: +```json +{ + "openId": "oXXXX...", + "productType": "section", // 'section' | 'fullbook' + "productId": "1-1", + "amount": 9.9, + "description": "章节1-1", + "userId": "user_xxx" +} +``` + +**返回**: +```json +{ + "success": true, + "data": { + "orderSn": "MP20260204123456789012", + "prepayId": "wx...", + "payParams": { + "timeStamp": "...", + "nonceStr": "...", + "package": "prepay_id=...", + "signType": "MD5", + "paySign": "..." + } + } +} +``` + +**关键逻辑**: +- ✅ 插入订单到 `orders` 表 (status='created') +- ✅ 检查是否已有该产品的已支付订单 +- ✅ 调用微信统一下单接口 +- ✅ 返回支付参数 + +--- + +#### `/api/miniprogram/pay/notify` (POST) +**功能**: 接收微信支付回调通知 + +**文件**: `app/api/miniprogram/pay/notify/route.ts` + +**请求**: 微信发送XML格式数据 + +**返回**: XML格式响应 + +**关键逻辑**: +1. ✅ 验证签名 +2. ✅ 更新订单状态为 `paid`（或补记订单） +3. ✅ 解锁用户权限 +4. ✅ 分配推荐佣金（90%） +5. ✅ **清理相同产品的其他未支付订单** + +--- + +### 2. 用户购买状态接口 + +#### `/api/user/purchase-status` (GET) +**功能**: 查询用户的购买状态 + +**文件**: `app/api/user/purchase-status/route.ts` + +**请求**: +``` +GET /api/user/purchase-status?userId=user_xxx +``` + +**返回**: +```json +{ + "success": true, + "data": { + "hasFullBook": false, + "purchasedSections": ["1-1", "1-2"], + "purchasedCount": 2, + "earnings": 0, + "pendingEarnings": 0 + } +} +``` + +**查询逻辑**: +```sql +-- 1. 查询全书权限 +SELECT has_full_book FROM users WHERE id = ? + +-- 2. 查询已购章节（基于 orders 表） +SELECT DISTINCT product_id +FROM orders +WHERE user_id = ? + AND status = 'paid' + AND product_type = 'section' +``` + +--- + +#### `/api/user/check-purchased` (GET) +**功能**: 检查用户是否已购买指定产品 + +**文件**: `app/api/user/check-purchased/route.ts` + +**请求**: +``` +GET /api/user/check-purchased?userId=user_xxx&type=section&productId=1-1 +``` + +**返回**: +```json +{ + "success": true, + "data": { + "isPurchased": true, + "reason": "section_order_exists" + } +} +``` + +**可能的 reason 值**: +- `has_full_book`: 用户已购买全书 +- `fullbook_order_exists`: 有全书的已支付订单 +- `section_order_exists`: 有该章节的已支付订单 +- `null`: 未购买 + +**查询逻辑**: +```sql +-- 1. 检查全书权限 +SELECT has_full_book FROM users WHERE id = ? + +-- 2. 检查是否有该产品的已支付订单 +SELECT COUNT(*) as count +FROM orders +WHERE user_id = ? + AND product_type = ? + AND product_id = ? + AND status = 'paid' +``` + +--- + +### 3. 通用支付接口（未使用） + +#### `/api/payment/create-order` (POST) +**功能**: 通用支付订单创建接口 + +**文件**: `app/api/payment/create-order/route.ts` + +**说明**: +- ⚠️ 小程序实际使用的是 `/api/miniprogram/pay` +- 这个接口是为 Web 端设计的通用支付接口 +- 支持多种支付方式（微信、支付宝、USDT） + +--- + +#### `/api/payment/wechat/notify` (POST) +**功能**: 通用微信支付回调 + +**文件**: `app/api/payment/wechat/notify/route.ts` + +**说明**: +- ⚠️ 小程序实际使用的是 `/api/miniprogram/pay/notify` +- 这个接口是为 Web 端设计的 + +--- + +## 📊 接口调用流程 + +``` +【小程序支付流程】 + +1. 用户点击购买 + ↓ +2. 前端调用 /api/user/purchase-status + (查询是否已购买) + ↓ +3. 如果未购买，前端调用 /api/miniprogram/pay + (创建订单 + 获取支付参数) + ↓ +4. 小程序调起微信支付 + ↓ +5. 用户完成支付 + ↓ +6. 微信回调 /api/miniprogram/pay/notify + (更新订单 + 解锁权限 + 分配佣金 + 清理无效订单) + ↓ +7. 前端支付成功后调用 /api/user/purchase-status + (刷新用户购买状态) +``` + +--- + +## 🔧 测试命令 + +### 1. 测试查询购买状态 + +```bash +curl "http://localhost:30006/api/user/purchase-status?userId=user_xxx" +``` + +**预期结果**: +```json +{ + "success": true, + "data": { + "hasFullBook": false, + "purchasedSections": [], + "purchasedCount": 0, + "earnings": 0, + "pendingEarnings": 0 + } +} +``` + +--- + +### 2. 测试检查是否已购买 + +```bash +curl "http://localhost:30006/api/user/check-purchased?userId=user_xxx&type=section&productId=1-1" +``` + +**预期结果**: +```json +{ + "success": true, + "data": { + "isPurchased": false, + "reason": null + } +} +``` + +--- + +### 3. 测试创建支付订单 + +```bash +curl -X POST http://localhost:30006/api/miniprogram/pay \ + -H "Content-Type: application/json" \ + -d '{ + "openId": "oXXXX...", + "productType": "section", + "productId": "1-1", + "amount": 9.9, + "description": "测试章节", + "userId": "user_xxx" + }' +``` + +**预期结果**: 返回支付参数 + +--- + +## ⚠️ 常见错误 + +### 1. "缺少 userId 参数" + +**原因**: 请求参数中未传递 userId + +**解决**: 确保 URL 参数或请求体中包含 userId + +--- + +### 2. "用户不存在" + +**原因**: 数据库中找不到对应的用户记录 + +**解决**: +1. 检查 userId 是否正确 +2. 确认用户已登录并创建了账号 +3. 查询数据库: `SELECT * FROM users WHERE id = 'user_xxx'` + +--- + +### 3. "订单创建失败" + +**原因**: +- 数据库连接失败 +- 缺少必要字段 +- openId 格式错误 + +**解决**: +1. 检查服务器日志 +2. 确认数据库连接正常 +3. 验证请求参数完整性 + +--- + +### 4. 接口404 + +**原因**: +- Next.js 服务器未重启 +- 文件路径错误 + +**解决**: +1. 重启 Next.js 服务器: `npm run dev` +2. 检查文件是否存在于正确路径 +3. 清除 `.next` 缓存后重启 + +--- + +## 📝 数据库表结构 + +### orders 表 + +| 字段 | 类型 | 说明 | +|-----|------|------| +| `id` | VARCHAR | 订单ID（同 order_sn） | +| `order_sn` | VARCHAR | 订单号 | +| `user_id` | VARCHAR | 用户ID | +| `open_id` | VARCHAR | 微信openId | +| `product_type` | VARCHAR | 产品类型 (section/fullbook) | +| `product_id` | VARCHAR | 产品ID | +| `amount` | DECIMAL | 金额（元） | +| `description` | TEXT | 订单描述 | +| `status` | VARCHAR | 状态 (created/paid/expired) | +| `transaction_id` | VARCHAR | 微信交易号 | +| `pay_time` | DATETIME | 支付时间 | +| `created_at` | DATETIME | 创建时间 | +| `updated_at` | DATETIME | 更新时间 | + +--- + +### users 表（购买相关字段） + +| 字段 | 类型 | 说明 | +|-----|------|------| +| `has_full_book` | BOOLEAN | 是否购买全书 | +| `purchased_sections` | JSON | 已购章节列表 | +| `earnings` | DECIMAL | 已结算收益 | +| `pending_earnings` | DECIMAL | 待结算收益 | + +--- + +## 🎉 接口状态总结 + +| 接口 | 状态 | 用途 | +|-----|------|------| +| `/api/miniprogram/pay` | ✅ 已实现 | 创建支付订单 | +| `/api/miniprogram/pay/notify` | ✅ 已实现 | 支付回调 | +| `/api/user/purchase-status` | ✅ 已实现 | 查询购买状态 | +| `/api/user/check-purchased` | ✅ 已实现 | 检查是否已购买 | +| `/api/payment/create-order` | ⚠️ 未使用 | Web 端通用接口 | +| `/api/payment/wechat/notify` | ⚠️ 未使用 | Web 端回调接口 | + +--- + +**所有小程序支付相关接口已完成！** 🎉 + +**重启 Next.js 服务器后生效**: `npm run dev` diff --git a/开发文档/8、部署/新分销逻辑-宝塔操作清单.md b/开发文档/8、部署/新分销逻辑-宝塔操作清单.md new file mode 100644 index 00000000..d3209e22 --- /dev/null +++ b/开发文档/8、部署/新分销逻辑-宝塔操作清单.md @@ -0,0 +1,299 @@ +# 新分销逻辑 - 宝塔面板操作清单 + +## ✅ 已完成的准备工作 + +- ✅ 数据库字段已添加（last_purchase_date, purchase_count, total_commission） +- ✅ 代码已部署到服务器（/www/wwwroot/soul/dist） +- ✅ 索引已创建 + +--- + +## 🔧 宝塔面板操作步骤 + +### Step 1: 重启 Node.js 服务 + +1. 登录宝塔面板：`http://你的服务器IP:8888` +2. 左侧菜单 → **网站** → 找到 `soul.quwanzhi.com` +3. 点击 **设置** → **Node项目** 标签 +4. 找到项目 `soul` +5. 点击 **重启** 按钮 +6. 等待状态变为"运行中" + +**或者使用命令行**（如果有SSH权限）： +```bash +# 使用宝塔的pm2完整路径 +/www/server/nodejs/v16.20.2/bin/pm2 restart soul + +# 查看状态 +/www/server/nodejs/v16.20.2/bin/pm2 status + +# 查看日志 +/www/server/nodejs/v16.20.2/bin/pm2 logs soul --lines 50 +``` + +--- + +### Step 2: 验证服务是否正常 + +#### 2.1 检查网站访问 +在浏览器打开：`https://soul.quwanzhi.com` + +**预期**： +- ✅ 网站正常加载 +- ✅ 无404错误 +- ✅ 可以正常登录 + +#### 2.2 检查新API是否生效 + +打开浏览器控制台，访问： +``` +https://soul.quwanzhi.com/api/db/config?key=referral_config +``` + +**预期返回**： +```json +{ + "success": true, + "config": { + "distributorShare": 90, + "minWithdrawAmount": 10, + "bindingDays": 30, + "userDiscount": 5, + "enableAutoWithdraw": false + } +} +``` + +#### 2.3 检查推广设置页面 + +访问：`https://soul.quwanzhi.com/admin/referral-settings` + +**预期**： +- ✅ 页面正常加载 +- ✅ 显示当前配置 +- ✅ 可以修改并保存 + +--- + +### Step 3: 配置自动解绑定时任务 + +1. 宝塔面板 → 左侧菜单 → **计划任务** +2. 点击 **添加计划任务** +3. 填写以下信息： + +**任务配置**： +``` +任务类型：Shell脚本 +任务名称：自动解绑过期推荐关系 +执行周期：每天 02:00（凌晨2点） +脚本内容： +cd /www/wwwroot/soul/dist && /www/server/nodejs/v16.20.2/bin/node scripts/auto-unbind-expired-simple.js >> /www/wwwroot/soul/logs/auto-unbind.log 2>&1 +``` + +4. 点击 **添加** +5. 任务创建后，点击 **执行** 按钮测试一次 + +**预期日志**（如果没有过期记录）： +``` +============================================================ +自动解绑定时任务 +执行时间: 2026/2/5 14:30:00 +============================================================ +✅ 已连接到数据库: soul_miniprogram +✅ 无需解绑的记录 +============================================================ +任务完成 +============================================================ +``` + +--- + +### Step 4: 查看定时任务日志 + +```bash +# 方式1：SSH命令 +cat /www/wwwroot/soul/logs/auto-unbind.log + +# 方式2：宝塔面板 +计划任务 → 找到"自动解绑"任务 → 点击"日志" +``` + +--- + +## 🧪 功能测试（小程序端） + +### 测试1：立即切换绑定 + +1. **准备两个测试账号**： + - 账号A：作为推荐人A（获取推荐码 SOULA001） + - 账号C：作为推荐人C（获取推荐码 SOULC001） + - 账号B：作为购买者 + +2. **测试步骤**： + ``` + Step 1: A 分享文章链接给 B + Step 2: B 点击链接进入小程序（会自动绑定A） + Step 3: 查数据库验证绑定 + Step 4: C 分享文章链接给 B + Step 5: B 点击C的链接（应该立即切换） + Step 6: 再次查数据库验证 + ``` + +3. **数据库验证SQL**： + ```sql + -- 查看B当前的绑定状态 + SELECT + referee_id, + referrer_id, + status, + binding_date, + expiry_date + FROM referral_bindings + WHERE referee_id = 'B的用户ID' + ORDER BY binding_date DESC; + ``` + + **预期结果**： + - 最新一条：`referrer_id = C的ID, status = active` + - 上一条：`referrer_id = A的ID, status = cancelled` + +--- + +### 测试2：购买分佣 + +1. **B 购买一篇文章（1元）** +2. **查看分佣结果**： + ```sql + SELECT + rb.referrer_id, + rb.purchase_count, + rb.total_commission, + rb.last_purchase_date, + u.pending_earnings + FROM referral_bindings rb + JOIN users u ON rb.referrer_id = u.id + WHERE rb.referee_id = 'B的用户ID' AND rb.status = 'active'; + ``` + + **预期结果**（假设90%分成）： + ``` + referrer_id: C的ID + purchase_count: 1 + total_commission: 0.90 + pending_earnings: 0.90 + ``` + +3. **B 再次购买**： + ```sql + -- 查询应显示 + purchase_count: 2 + total_commission: 1.80 + pending_earnings: 1.80 + ``` + +--- + +### 测试3：好友优惠（新功能） + +1. **后台设置好友优惠为 10%** + - 访问：`https://soul.quwanzhi.com/admin/referral-settings` + - 修改"好友优惠"为 `10` + - 保存 + +2. **B 通过推荐链接购买** + - 原价 1.00 元的文章 + - 支付时应显示 **0.90 元**（10% off） + +3. **验证佣金计算**： + - C 应获得佣金 = 0.90 × 90% = **0.81 元** + - 而不是 1.00 × 90% = 0.90 元 + +--- + +## 📊 后台监控 + +### 查看绑定切换记录 + +**SQL查询**： +```sql +-- 查看最近的绑定切换 +SELECT + rb.referee_id, + rb.referrer_id, + rb.status, + rb.binding_date, + rb.purchase_count, + rb.total_commission +FROM referral_bindings rb +WHERE rb.status IN ('active', 'cancelled') +ORDER BY rb.binding_date DESC +LIMIT 20; +``` + +### 查看即将过期的绑定 + +```sql +-- 7天内即将过期且无购买的绑定 +SELECT + rb.referee_id, + rb.referrer_id, + rb.binding_date, + rb.expiry_date, + DATEDIFF(rb.expiry_date, NOW()) as days_left, + rb.purchase_count +FROM referral_bindings rb +WHERE rb.status = 'active' + AND rb.expiry_date > NOW() + AND DATEDIFF(rb.expiry_date, NOW()) <= 7 + AND rb.purchase_count = 0 +ORDER BY days_left ASC; +``` + +--- + +## ⚠️ 常见问题 + +### Q1: 点击新链接后没有切换？ +**检查**： +- 宝塔面板 → Node项目 → 查看日志 +- 搜索 `[Referral Bind]` 关键词 +- 确认是否有报错 + +### Q2: 购买后 purchase_count 还是 0？ +**检查**： +- 查看支付回调日志：`pm2 logs soul | grep PayNotify` +- 确认字段 `purchase_count` 是否存在 +- 执行SQL验证：`SHOW COLUMNS FROM referral_bindings;` + +### Q3: 定时任务没有执行？ +**检查**： +- 宝塔面板 → 计划任务 → 找到任务 → 点击"执行"测试 +- 查看日志：`cat /www/wwwroot/soul/logs/auto-unbind.log` +- 确认脚本路径正确：`ls -la /www/wwwroot/soul/dist/scripts/auto-unbind-expired-simple.js` + +--- + +## 📝 部署后清理 + +部署成功后，删除临时文件： + +```bash +# 本地清理 +rm .env.migration +``` + +--- + +## ✅ 完成检查清单 + +- [ ] 数据库字段已添加 +- [ ] 代码已部署 +- [ ] PM2服务运行正常 +- [ ] 网站可以访问 +- [ ] 推广设置页面正常 +- [ ] 定时任务已配置 +- [ ] 功能测试通过 + +--- + +**下一步：执行上述测试验证，或告诉我遇到的任何问题！** diff --git a/开发文档/8、部署/新分销逻辑-部署步骤.md b/开发文档/8、部署/新分销逻辑-部署步骤.md new file mode 100644 index 00000000..9f65bfc9 --- /dev/null +++ b/开发文档/8、部署/新分销逻辑-部署步骤.md @@ -0,0 +1,537 @@ +# 新分销逻辑 - 部署步骤 + +## 📋 部署前检查 + +### 确认新逻辑 +- ✅ 点击谁的链接，立即绑定谁（无条件切换） +- ✅ 购买时，佣金给当前推荐人 +- ✅ 30天内无购买 → 自动解绑 +- ✅ 方案A：购买后不重置30天 + +### 备份数据 +```bash +# 1. 备份数据库 +mysqldump -u root -p mycontent_db > backup_before_referral_$(date +%Y%m%d).sql + +# 2. 备份代码 +cd /www/wwwroot/soul +tar -czf backup_code_$(date +%Y%m%d).tar.gz app/ lib/ scripts/ +``` + +--- + +## 🚀 部署步骤 + +### Step 1: 数据库迁移 + +#### 方式1：使用 Python 脚本（推荐） + +```bash +# 1. 上传脚本到服务器 +cd /www/wwwroot/soul +# 将 scripts/migrate_binding_fields.py 上传到服务器 + +# 2. 确保环境变量正确（.env 文件） +cat .env | grep DB_ + +# 3. 执行迁移 +python3 scripts/migrate_binding_fields.py +``` + +**预期输出**： +``` +========================================================== +数据库迁移：referral_bindings 表字段升级 +========================================================== + +✅ 已连接到数据库: mycontent_db + +步骤 1: 添加新字段 +------------------------------------------------------------ +✅ 添加字段 last_purchase_date +✅ 添加字段 purchase_count +✅ 添加字段 total_commission + +步骤 2: 添加索引 +------------------------------------------------------------ +✅ 添加索引 idx_referee_status +✅ 添加索引 idx_expiry_purchase + +步骤 3: 更新 status 枚举（添加 cancelled） +------------------------------------------------------------ +✅ 更新 status 枚举类型 + +步骤 4: 验证迁移结果 +------------------------------------------------------------ +✅ 字段 last_purchase_date 已存在 +✅ 字段 purchase_count 已存在 +✅ 字段 total_commission 已存在 + +========================================================== +✅ 迁移完成！ +========================================================== +``` + +#### 方式2：直接执行 SQL + +```bash +# 连接数据库 +mysql -u root -p mycontent_db + +# 执行迁移SQL +source scripts/migration-add-binding-fields.sql; + +# 验证字段 +SHOW COLUMNS FROM referral_bindings; +``` + +--- + +### Step 2: 部署代码 + +#### 本地构建 +```bash +# 在本地项目目录 +cd e:\Gongsi\Mycontent + +# 构建 +pnpm build + +# 确认构建产物 +ls -la .next/standalone +``` + +#### 上传到服务器 +```bash +# 使用 devlop.py（自动化部署） +python devlop.py + +# 或手动上传 +# 1. 上传修改的文件： +# - app/api/referral/bind/route.ts +# - app/api/miniprogram/pay/notify/route.ts +# - scripts/auto-unbind-expired-simple.js +``` + +--- + +### Step 3: 重启服务 + +```bash +# 重启 PM2 +pm2 restart soul + +# 查看日志确认启动正常 +pm2 logs soul --lines 50 + +# 确认进程状态 +pm2 status +``` + +**预期输出**： +``` +┌─────┬────────┬─────────┬──────┬─────┬──────────┐ +│ id │ name │ status │ ↺ │ cpu │ memory │ +├─────┼────────┼─────────┼──────┼─────┼──────────┤ +│ 0 │ soul │ online │ 0 │ 0% │ 100.0mb │ +└─────┴────────┴─────────┴──────┴─────┴──────────┘ +``` + +--- + +### Step 4: 配置定时任务 + +#### 宝塔面板配置 + +1. 登录宝塔面板 +2. 进入"计划任务" +3. 添加 Shell 脚本任务 + +**任务配置**： +- **任务名称**：自动解绑过期推荐关系 +- **执行周期**：每天 02:00 +- **脚本内容**： + ```bash + cd /www/wwwroot/soul && node scripts/auto-unbind-expired-simple.js >> /www/wwwroot/soul/logs/auto-unbind.log 2>&1 + ``` + +#### 手动测试定时任务 + +```bash +# 进入项目目录 +cd /www/wwwroot/soul + +# 创建日志目录 +mkdir -p logs + +# 手动执行一次 +node scripts/auto-unbind-expired-simple.js + +# 查看日志 +cat logs/auto-unbind.log +``` + +**预期输出**（如果有过期记录）： +``` +============================================================ +自动解绑定时任务 +执行时间: 2026/2/5 02:00:00 +============================================================ + +✅ 已连接到数据库: mycontent_db + +步骤 1: 查询需要解绑的记录... +------------------------------------------------------------ +找到 3 条需要解绑的记录 + +步骤 2: 解绑明细 +------------------------------------------------------------ +1. 用户 user_abc123 + 推荐人: user_xyz789 + 绑定时间: 2026/1/5 + 过期时间: 2026/2/4 (已过期 1 天) + 购买次数: 0 + 累计佣金: ¥0.00 + +... + +步骤 3: 执行解绑操作... +------------------------------------------------------------ +✅ 已成功解绑 3 条记录 + +步骤 4: 更新推荐人统计... +------------------------------------------------------------ + - user_xyz789: -2 个绑定 + - user_def456: -1 个绑定 +✅ 已更新 2 个推荐人的统计数据 + +============================================================ +✅ 任务完成 + - 解绑记录数: 3 + - 受影响推荐人: 2 +============================================================ +``` + +--- + +## 🧪 功能测试 + +### 测试用例1：立即切换绑定 + +#### 准备工作 +```bash +# 创建测试用户 A、B、C +# A 推荐 B +# C 也想抢 B +``` + +#### 测试步骤 +```bash +# 1. A 推荐 B（新绑定） +curl -X POST http://localhost:3006/api/referral/bind \ + -H "Content-Type: application/json" \ + -d '{ + "userId": "test_user_b", + "referralCode": "SOULA001", + "source": "miniprogram" + }' + +# 预期返回： +# { +# "success": true, +# "message": "绑定成功", +# "action": "new", +# "expiryDate": "2026-03-07T...", +# "referrer": { "id": "test_user_a", "nickname": "用户A" } +# } + +# 2. B 点击 C 的链接（立即切换） +curl -X POST http://localhost:3006/api/referral/bind \ + -H "Content-Type: application/json" \ + -d '{ + "userId": "test_user_b", + "referralCode": "SOULC001", + "source": "miniprogram" + }' + +# 预期返回： +# { +# "success": true, +# "message": "已切换推荐人", +# "action": "switch", +# "expiryDate": "2026-03-07T...", +# "referrer": { "id": "test_user_c", "nickname": "用户C" }, +# "oldReferrerId": "test_user_a" +# } + +# 3. 验证数据库 +mysql -u root -p mycontent_db -e " + SELECT referee_id, referrer_id, status, binding_date, expiry_date + FROM referral_bindings + WHERE referee_id = 'test_user_b' + ORDER BY binding_date DESC LIMIT 2; +" + +# 预期结果： +# 记录1: referee=B, referrer=C, status=active (最新) +# 记录2: referee=B, referrer=A, status=cancelled (旧) +``` + +--- + +### 测试用例2：购买分佣（累加） + +#### 测试步骤 +```bash +# 1. B 购买第1次（1元） +# 触发支付回调 -> /api/miniprogram/pay/notify + +# 2. 查询分佣结果 +mysql -u root -p mycontent_db -e " + SELECT + rb.referrer_id, + rb.purchase_count, + rb.total_commission, + u.pending_earnings + FROM referral_bindings rb + JOIN users u ON rb.referrer_id = u.id + WHERE rb.referee_id = 'test_user_b' AND rb.status = 'active'; +" + +# 预期结果： +# referrer_id: test_user_c +# purchase_count: 1 +# total_commission: 0.90 (假设90%分成) +# pending_earnings: 0.90 + +# 3. B 购买第2次（1元） +# 再次触发支付回调 + +# 4. 再次查询 +# 预期结果： +# purchase_count: 2 +# total_commission: 1.80 +# pending_earnings: 1.80 +``` + +--- + +### 测试用例3：30天自动解绑 + +#### 模拟测试（修改过期时间） +```bash +# 1. 手动修改绑定的过期时间（测试用） +mysql -u root -p mycontent_db -e " + UPDATE referral_bindings + SET expiry_date = '2026-02-04 00:00:00' + WHERE referee_id = 'test_user_x' AND referrer_id = 'test_user_y'; +" + +# 2. 执行定时任务 +node scripts/auto-unbind-expired-simple.js + +# 3. 验证解绑 +mysql -u root -p mycontent_db -e " + SELECT referee_id, referrer_id, status, expiry_date, purchase_count + FROM referral_bindings + WHERE referee_id = 'test_user_x'; +" + +# 预期结果： +# status: expired（如果 purchase_count = 0） +# status: active（如果 purchase_count > 0） +``` + +--- + +## 🔍 监控与日志 + +### 查看绑定切换日志 +```bash +# PM2 日志 +pm2 logs soul | grep "Referral Bind" + +# 查找"立即切换"记录 +pm2 logs soul | grep "立即切换" +``` + +### 查看分佣日志 +```bash +# 查看分佣成功记录 +pm2 logs soul | grep "分佣完成" + +# 查看累加情况 +pm2 logs soul | grep "purchaseCount" +``` + +### 定时任务日志 +```bash +# 查看定时任务执行记录 +cat /www/wwwroot/soul/logs/auto-unbind.log + +# 实时监控 +tail -f /www/wwwroot/soul/logs/auto-unbind.log +``` + +--- + +## 📊 数据统计 + +### 查看当前绑定状态分布 +```sql +SELECT + status, + COUNT(*) as count, + SUM(purchase_count) as total_purchases, + SUM(total_commission) as total_commission +FROM referral_bindings +GROUP BY status; +``` + +### 查看切换频率最高的用户 +```sql +SELECT + referee_id, + COUNT(*) as binding_count, + GROUP_CONCAT(referrer_id ORDER BY binding_date DESC) as referrer_history +FROM referral_bindings +WHERE status IN ('active', 'cancelled') +GROUP BY referee_id +HAVING COUNT(*) > 1 +ORDER BY binding_count DESC +LIMIT 10; +``` + +### 查看30天内即将过期的绑定 +```sql +SELECT + referee_id, + referrer_id, + binding_date, + expiry_date, + DATEDIFF(expiry_date, NOW()) as days_left, + purchase_count +FROM referral_bindings +WHERE status = 'active' + AND expiry_date > NOW() + AND DATEDIFF(expiry_date, NOW()) <= 7 +ORDER BY days_left ASC; +``` + +--- + +## ⚠️ 回滚方案 + +### 如果需要回滚到旧逻辑 + +#### 1. 恢复数据库 +```bash +# 停止服务 +pm2 stop soul + +# 恢复备份 +mysql -u root -p mycontent_db < backup_before_referral_20260205.sql + +# 重启服务 +pm2 start soul +``` + +#### 2. 恢复代码 +```bash +# 方式1：Git回滚 +cd /www/wwwroot/soul +git reset --hard <上一个commit> + +# 方式2：恢复备份 +tar -xzf backup_code_20260205.tar.gz + +# 重启 +pm2 restart soul +``` + +#### 3. 停用定时任务 +```bash +# 宝塔面板 -> 计划任务 -> 停用或删除"自动解绑"任务 +``` + +--- + +## 📝 常见问题 + +### Q1: 定时任务没有执行？ +**检查步骤**： +1. 确认宝塔计划任务状态为"启用" +2. 查看宝塔计划任务日志 +3. 手动执行测试：`node scripts/auto-unbind-expired-simple.js` +4. 检查脚本权限：`chmod +x scripts/auto-unbind-expired-simple.js` + +### Q2: 绑定切换后，旧推荐人还能收到佣金？ +**原因**：可能是购买时的绑定查询逻辑有问题 + +**检查**： +```sql +-- 查看 B 当前的绑定 +SELECT * FROM referral_bindings +WHERE referee_id = 'test_user_b' AND status = 'active'; + +-- 应该只有1条 active 记录（最新的推荐人） +``` + +### Q3: purchase_count 字段不存在？ +**原因**：数据库迁移未成功 + +**解决**： +```bash +# 重新执行迁移 +python3 scripts/migrate_binding_fields.py + +# 或手动添加 +mysql -u root -p mycontent_db -e " + ALTER TABLE referral_bindings + ADD COLUMN purchase_count INT DEFAULT 0; +" +``` + +### Q4: 如何验证新逻辑是否生效？ +**验证清单**： +- [ ] 数据库有 `last_purchase_date`、`purchase_count`、`total_commission` 字段 +- [ ] 点击不同推荐链接会立即切换（无报错） +- [ ] 购买后 `purchase_count` 会累加 +- [ ] 定时任务能正常执行 + +--- + +## ✅ 部署完成检查表 + +- [ ] 数据库迁移成功 +- [ ] 代码部署完成 +- [ ] PM2 服务正常运行 +- [ ] 定时任务已配置 +- [ ] 测试用例1通过（立即切换） +- [ ] 测试用例2通过（购买累加） +- [ ] 日志正常输出 +- [ ] 备份文件已保存 + +--- + +## 📞 问题反馈 + +如有问题，请提供： +1. 错误日志（PM2日志或定时任务日志） +2. 数据库状态（相关表的查询结果） +3. 复现步骤 + +**日志收集命令**： +```bash +# PM2日志 +pm2 logs soul --lines 100 > soul_logs.txt + +# 定时任务日志 +cat /www/wwwroot/soul/logs/auto-unbind.log > auto_unbind.log + +# 数据库状态 +mysql -u root -p mycontent_db -e " + SELECT * FROM referral_bindings LIMIT 10; + SHOW COLUMNS FROM referral_bindings; +" > db_status.txt +``` diff --git a/开发文档/8、部署/新分销逻辑设计方案.md b/开发文档/8、部署/新分销逻辑设计方案.md new file mode 100644 index 00000000..ab546e3d --- /dev/null +++ b/开发文档/8、部署/新分销逻辑设计方案.md @@ -0,0 +1,408 @@ +# 新分销逻辑设计方案 + +## 📌 业务需求 + +### 核心规则 +1. **动态绑定**：用户B点击谁的分享链接，立即绑定谁（无条件切换） +2. **佣金归属**：B购买时，佣金给当前推荐人（最新绑定的那个人） +3. **自动解绑**：绑定30天内，如果B既没点击其他链接，也没有任何购买 → 自动解绑 + +### 场景示例 +``` +时间线： +Day 0: A推荐B → B注册 → B绑定A（30天有效期） +Day 5: B点击C的链接 → B立即切换绑定C（重新开始30天有效期） +Day 10: B购买文章 → 佣金给C（当前推荐人） +Day 35: 绑定C的30天到期，如果期间无购买 → 自动解绑 +``` + +--- + +## 🗄️ 数据库设计 + +### 1. `referral_bindings` 表字段调整 + +| 字段 | 类型 | 说明 | 新增/修改 | +|------|------|------|-----------| +| `id` | VARCHAR(64) | 主键 | - | +| `referee_id` | VARCHAR(64) | 被推荐人（B） | - | +| `referrer_id` | VARCHAR(64) | 推荐人（当前） | - | +| `referral_code` | VARCHAR(20) | 推荐码 | - | +| `status` | ENUM | active/converted/expired/cancelled | **新增 cancelled** | +| `binding_date` | TIMESTAMP | 最后一次绑定时间 | - | +| `expiry_date` | DATETIME | 过期时间（30天后） | - | +| `last_purchase_date` | DATETIME | 最后一次购买时间 | **新增** | +| `purchase_count` | INT | 购买次数 | **新增** | +| `total_commission` | DECIMAL | 累计佣金 | **新增** | + +### 2. 新增字段的 SQL + +```sql +-- 添加新字段 +ALTER TABLE referral_bindings +ADD COLUMN last_purchase_date DATETIME NULL COMMENT '最后一次购买时间', +ADD COLUMN purchase_count INT DEFAULT 0 COMMENT '购买次数', +ADD COLUMN total_commission DECIMAL(10,2) DEFAULT 0.00 COMMENT '累计佣金', +ADD INDEX idx_expiry_status (expiry_date, status); + +-- 修改 status 枚举（如果需要） +ALTER TABLE referral_bindings +MODIFY COLUMN status ENUM('active', 'converted', 'expired', 'cancelled') DEFAULT 'active'; +``` + +--- + +## 🔧 API 逻辑修改 + +### 1. `/api/referral/bind` - 立即切换绑定 + +**修改前逻辑（现有）：** +```javascript +if (existingBinding && expiryDate > now) { + return { error: '绑定有效期内无法更换' } // ❌ 阻止切换 +} +``` + +**修改后逻辑（新）：** +```javascript +// 查询B当前的绑定 +const existingBinding = await query(` + SELECT * FROM referral_bindings + WHERE referee_id = ? AND status = 'active' +`, [userId]) + +if (existingBinding.length > 0) { + const current = existingBinding[0] + + // 情况1: 同一个推荐人 → 续期（刷新30天） + if (current.referrer_id === newReferrerId) { + await query(` + UPDATE referral_bindings + SET expiry_date = DATE_ADD(NOW(), INTERVAL 30 DAY), + binding_date = NOW() + WHERE id = ? + `, [current.id]) + return { success: true, action: 'renewed' } + } + + // 情况2: 不同推荐人 → 立即切换 + else { + // 旧绑定标记为 cancelled + await query(` + UPDATE referral_bindings + SET status = 'cancelled' + WHERE id = ? + `, [current.id]) + + // 创建新绑定 + await query(` + INSERT INTO referral_bindings + (id, referee_id, referrer_id, referral_code, status, binding_date, expiry_date) + VALUES (?, ?, ?, ?, 'active', NOW(), DATE_ADD(NOW(), INTERVAL 30 DAY)) + `, [newBindingId, userId, newReferrerId, referralCode]) + + return { success: true, action: 'switched' } + } +} +``` + +**关键变化**： +- ✅ 删除"有效期内不能切换"的限制 +- ✅ 旧绑定标记为 `cancelled`（而不是 `expired`） +- ✅ 立即创建新绑定，重新计算30天 + +--- + +### 2. `/api/miniprogram/pay/notify` - 支付回调更新 + +**修改前逻辑（现有）：** +```javascript +// 更新绑定为 converted +await query(` + UPDATE referral_bindings + SET status = 'converted', + conversion_date = NOW(), + commission_amount = ? + WHERE id = ? +`, [commission, bindingId]) +``` + +**修改后逻辑（新）：** +```javascript +// 查询B当前的绑定（active状态） +const binding = await query(` + SELECT * FROM referral_bindings + WHERE referee_id = ? AND status = 'active' + ORDER BY binding_date DESC LIMIT 1 +`, [userId]) + +if (binding.length === 0) { + console.log('[PayNotify] 无有效绑定，跳过分佣') + return +} + +const currentBinding = binding[0] +const referrerId = currentBinding.referrer_id + +// 计算佣金 +const commission = amount * distributorShare + +// 更新绑定记录（累加购买次数和佣金） +await query(` + UPDATE referral_bindings + SET last_purchase_date = NOW(), + purchase_count = purchase_count + 1, + total_commission = total_commission + ? + WHERE id = ? +`, [commission, currentBinding.id]) + +// 更新推荐人收益 +await query(` + UPDATE users + SET pending_earnings = pending_earnings + ? + WHERE id = ? +`, [commission, referrerId]) + +console.log('[PayNotify] 分佣成功:', { + referee: userId, + referrer: referrerId, + commission, + purchaseCount: currentBinding.purchase_count + 1 +}) +``` + +**关键变化**： +- ✅ 不再标记为 `converted`（保持 `active`） +- ✅ 记录 `last_purchase_date`（用于判断是否有购买） +- ✅ 累加 `purchase_count` 和 `total_commission` +- ✅ 允许同一绑定多次购买分佣 + +--- + +### 3. 定时任务 - 自动解绑 + +**新增文件**: `scripts/auto-unbind-expired.js` + +```javascript +/** + * 自动解绑定时任务 + * 每天凌晨2点运行（建议配置 cron） + * + * 解绑条件： + * 1. 绑定超过30天（expiry_date < NOW） + * 2. 期间没有任何购买（purchase_count = 0） + */ + +const { query } = require('../lib/db') + +async function autoUnbind() { + console.log('[AutoUnbind] 开始执行自动解绑任务...') + + try { + // 查询需要解绑的记录 + const expiredBindings = await query(` + SELECT id, referee_id, referrer_id, binding_date, expiry_date + FROM referral_bindings + WHERE status = 'active' + AND expiry_date < NOW() + AND purchase_count = 0 + `) + + if (expiredBindings.length === 0) { + console.log('[AutoUnbind] 无需解绑的记录') + return + } + + console.log(`[AutoUnbind] 找到 ${expiredBindings.length} 条需要解绑的记录`) + + // 批量更新为 expired + const ids = expiredBindings.map(b => b.id) + await query(` + UPDATE referral_bindings + SET status = 'expired' + WHERE id IN (?) + `, [ids]) + + console.log(`[AutoUnbind] ✅ 已解绑 ${expiredBindings.length} 条记录`) + + // 输出明细 + expiredBindings.forEach(b => { + console.log(` - ${b.referee_id} 解除与 ${b.referrer_id} 的绑定（绑定于 ${b.binding_date}）`) + }) + + } catch (error) { + console.error('[AutoUnbind] ❌ 执行失败:', error) + } +} + +// 如果直接运行此脚本 +if (require.main === module) { + autoUnbind().then(() => { + console.log('[AutoUnbind] 任务完成') + process.exit(0) + }) +} + +module.exports = { autoUnbind } +``` + +**部署方式（宝塔面板）**： +1. 进入"计划任务" → 添加 Shell 脚本 +2. 执行周期：每天 02:00 +3. 脚本内容： + ```bash + cd /www/wwwroot/soul && node scripts/auto-unbind-expired.js + ``` + +--- + +## 📊 状态流转图 + +``` +用户B的绑定状态流转： + +[无绑定] + ↓ (点击A的链接) +[active - 绑定A] ← expiry_date = NOW + 30天 + ↓ (点击C的链接) +[active - 绑定C] ← 旧绑定变 cancelled，新绑定 expiry_date = NOW + 30天 + ↓ (购买) +[active - 绑定C] ← purchase_count++, last_purchase_date = NOW + ↓ (30天后，无购买) +[expired] ← 自动解绑 + ↓ (再次点击D的链接) +[active - 绑定D] ← 重新绑定 +``` + +**status 枚举说明**： +- `active`: 当前有效绑定 +- `cancelled`: 被切换（用户点了其他人链接） +- `expired`: 30天到期且无购买 +- `converted`: **不再使用**（在新逻辑中，购买不改变status） + +--- + +## 🧪 测试用例 + +### 用例1: 立即切换绑定 + +``` +1. A推荐B → B注册 + 预期: referral_bindings 新增一条 (referee=B, referrer=A, status=active) + +2. B点击C的链接 + 预期: + - 旧记录 (referrer=A) status → cancelled + - 新记录 (referrer=C) status = active, expiry_date = NOW + 30天 + +3. B购买文章 + 预期: + - 佣金给C（不是A） + - binding.purchase_count = 1 + - binding.last_purchase_date = NOW +``` + +### 用例2: 30天无购买自动解绑 + +``` +1. A推荐B → B注册 + 预期: binding (referee=B, referrer=A, expiry_date = NOW + 30天) + +2. 等待31天（模拟） + 手动执行: node scripts/auto-unbind-expired.js + 预期: binding.status → expired + +3. B点击C的链接 + 预期: 创建新绑定 (referrer=C) +``` + +### 用例3: 多次购买累加佣金 + +``` +1. A推荐B → B绑定A +2. B购买文章1（1元） + 预期: A获得佣金 0.9元，binding.purchase_count = 1 +3. B购买文章2（1元） + 预期: A再获得佣金 0.9元，binding.purchase_count = 2，total_commission = 1.8 +``` + +--- + +## ⚠️ 注意事项 + +### 1. 边界情况处理 + +**Q1: B多次点击同一个人的链接？** +- A: 刷新 `expiry_date`（续期30天），不创建新记录 + +**Q2: B在切换推荐人后的旧订单佣金？** +- A: 历史佣金不变，只影响新订单 + +**Q3: 用户注册时没有推荐码？** +- A: 无绑定状态，等待首次点击分享链接 + +### 2. 数据一致性 + +- 使用事务保证绑定切换的原子性 +- 定时任务运行时间建议在凌晨低峰期 +- 建议添加 `idx_expiry_status` 索引优化查询 + +### 3. 性能优化 + +```sql +-- 优化索引 +CREATE INDEX idx_referee_status ON referral_bindings(referee_id, status); +CREATE INDEX idx_expiry_purchase ON referral_bindings(expiry_date, purchase_count); +``` + +--- + +## 🚀 部署步骤 + +### Step 1: 数据库迁移 +```bash +# 执行 SQL 添加新字段 +mysql -u root -p mycontent_db < scripts/migration-add-binding-fields.sql +``` + +### Step 2: 修改 API 代码 +- ✅ 修改 `/api/referral/bind`（立即切换逻辑） +- ✅ 修改 `/api/miniprogram/pay/notify`（累加购买次数） + +### Step 3: 部署定时任务 +- ✅ 创建 `scripts/auto-unbind-expired.js` +- ✅ 宝塔面板配置 cron（每天02:00） + +### Step 4: 测试验证 +- ✅ 测试切换绑定流程 +- ✅ 测试购买分佣 +- ✅ 手动运行定时任务验证解绑 + +--- + +## 📈 后续优化建议 + +1. **管理后台增强** + - 查看绑定切换历史（谁被谁抢走了） + - 统计推荐人的"流失率"（被切换走的比例） + +2. **用户端提示** + - 点击新链接时提示"即将切换推荐人" + - 显示当前绑定的推荐人信息 + +3. **防刷机制** + - 限制同一用户短时间内频繁切换绑定 + - 记录IP和设备指纹防止恶意刷绑定 + +4. **数据分析** + - 统计平均绑定时长 + - 分析哪些推荐人容易被"抢走" + - 优化推荐策略 + +--- + +## 🔗 相关文档 + +- [分销与绑定流程图](./分销与绑定流程图.md) +- [推广设置功能完整修复清单](./推广设置功能-完整修复清单.md) +- [API接入说明](./API接入说明.md) diff --git a/开发文档/8、部署/章节阅读付费标准流程设计.md b/开发文档/8、部署/章节阅读付费标准流程设计.md new file mode 100644 index 00000000..75838da2 --- /dev/null +++ b/开发文档/8、部署/章节阅读付费标准流程设计.md @@ -0,0 +1,524 @@ +# 章节阅读与付费标准流程设计 + +> 目标：规范阅读/付费流程，规避 bug，追踪阅读状态（是否读完），为后续数据分析/推荐提供基础。 + +--- + +## 一、核心问题与设计目标 + +### 当前存在的风险点 +1. **权限判断时机不统一**：有些地方用本地缓存、有些用接口，可能不一致 +2. **登录前后状态切换**：未登录→登录、登录后免费列表变化，状态同步复杂 +3. **阅读进度无追踪**：只知道"是否打开过"，不知"是否读完"、"读到哪" +4. **付费前重复校验**：支付前、登录后、initSection 多次请求 check-purchased +5. **异常降级策略不统一**：网络失败时有些保守、有些用缓存，可能误解锁 + +### 设计目标 +- **唯一权威数据源**：章节权限以服务端为准（users + orders 表） +- **标准状态机**：章节状态、用户状态明确定义，流转有迹可循 +- **阅读进度追踪**：记录滚动进度、阅读时长、是否读完（≥90% 或到底部） +- **统一异常处理**：网络失败、超时、服务端错误统一降级策略（保守+重试） +- **流程可回溯**：关键节点打日志，便于排查 bug 和数据分析 + +--- + +## 二、标准状态机设计 + +### 2.1 章节权限状态（ChapterAccessState） + +| 状态 | 说明 | 前端展示 | +|------|------|----------| +| `unknown` | 初始/加载中，尚未确定权限 | loading 骨架屏 | +| `free` | 免费章节，无需登录/购买 | 全文 + 已读标记 | +| `locked_not_login` | 付费章节 + 用户未登录 | 预览 + 登录按钮 | +| `locked_not_purchased` | 付费章节 + 已登录但未购买 | 预览 + 购买按钮 | +| `unlocked_purchased` | 付费章节 + 已购买（单章/全书） | 全文 + 已读标记 | +| `error` | 权限校验失败（网络/服务端错误） | 预览 + 重试按钮 | + +### 2.2 阅读进度状态（ReadingProgressState） + +```javascript +{ + sectionId: '1.2', + status: 'reading' | 'completed' | 'abandoned', // 阅读中 | 已完成 | 已放弃（30天未回） + progress: 75, // 滚动进度百分比 0-100 + duration: 360, // 累计阅读时长（秒） + lastPosition: 1200, // 上次滚动位置（px） + completedAt: null, // 读完时间戳（达到90%+停留3s 或滑到底部） + firstOpenAt: 1738560000,// 首次打开时间戳 + lastOpenAt: 1738563600 // 最后打开时间戳 +} +``` + +### 2.3 状态流转图 + +``` +进入阅读页 + ↓ +[unknown] 加载中 + ↓ +拉取最新免费列表 + 用户登录状态 + ↓ + ├─ 免费章节 → [free] → 全文展示 → 记录阅读进度 + ├─ 未登录 → [locked_not_login] → 预览 + 登录按钮 + │ ↓ 登录成功 + │ ├─ 章节已免费 → [free] + │ ├─ 已购买 → [unlocked_purchased] + │ └─ 未购买 → [locked_not_purchased] + ├─ 已登录未购买 → [locked_not_purchased] → 预览 + 购买按钮 + │ ↓ 支付成功 + │ └─ [unlocked_purchased] → 全文展示 + └─ 已登录已购买 → [unlocked_purchased] → 全文展示 → 记录阅读进度 + +网络/服务端错误 → [error] → 保守展示预览 + 重试按钮 +``` + +--- + +## 三、标准流程与接口调用顺序 + +### 3.1 进入章节页标准流程 + +```javascript +async onLoad(options) { + const { id, ref } = options + + // 1. 初始化状态 + this.setState({ accessState: 'unknown', loading: true }) + + // 2. 处理推荐码（异步不阻塞） + if (ref) this.handleReferralCode(ref) + + // 3. 【关键】拉取最新配置（免费列表、价格等）- 串行等待 + await this.fetchLatestConfig() + + // 4. 【关键】确定章节权限状态 - 串行等待 + const accessState = await this.determineAccessState(id) + + // 5. 加载章节内容（全文或预览） + await this.loadChapterContent(id, accessState) + + // 6. 若有权限则初始化阅读追踪 + if (['free', 'unlocked_purchased'].includes(accessState)) { + this.initReadingTracker(id) + } + + // 7. 加载上下章导航 + this.loadNavigation(id) + + this.setState({ loading: false }) +} +``` + +### 3.2 determineAccessState 权限判断标准 + +```javascript +async determineAccessState(sectionId) { + try { + // 1. 检查是否免费（以服务端最新配置为准） + if (this.isFreeChapter(sectionId)) { + return 'free' + } + + // 2. 检查是否登录 + const userId = app.globalData.userInfo?.id + if (!userId) { + return 'locked_not_login' + } + + // 3. 【权威接口】请求服务端校验是否已购买 + const res = await app.request( + `/api/user/check-purchased?userId=${userId}&type=section&productId=${sectionId}`, + { timeout: 5000 } + ) + + if (res.success && res.data?.isPurchased) { + // 同步更新本地缓存（仅作展示用，不作权限依据） + this.syncLocalPurchaseCache(sectionId, res.data) + return 'unlocked_purchased' + } + + return 'locked_not_purchased' + + } catch (error) { + console.error('[Access] 权限判断失败:', error) + // 网络/服务端错误 → 保守策略：视为无权限 + 可重试 + return 'error' + } +} +``` + +### 3.3 登录后重新校验标准流程 + +```javascript +async onLoginSuccess() { + wx.showLoading({ title: '更新状态中...' }) + + try { + // 1. 刷新用户购买列表（全局状态） + await this.refreshUserPurchaseStatus() + + // 2. 重新拉取免费列表（可能刚改免费） + await this.fetchLatestConfig() + + // 3. 重新判断当前章节权限 + const newAccessState = await this.determineAccessState(this.data.sectionId) + + // 4. 更新状态并刷新内容 + this.setState({ + accessState: newAccessState, + isLoggedIn: true + }) + + // 5. 若已解锁则初始化阅读追踪 + if (['free', 'unlocked_purchased'].includes(newAccessState)) { + await this.loadChapterContent(this.data.sectionId, newAccessState) + this.initReadingTracker(this.data.sectionId) + } + + wx.hideLoading() + wx.showToast({ title: '登录成功', icon: 'success' }) + + } catch (e) { + wx.hideLoading() + wx.showToast({ title: '状态更新失败，请重试', icon: 'none' }) + } +} +``` + +### 3.4 支付成功后刷新标准流程 + +```javascript +async onPaymentSuccess() { + wx.showLoading({ title: '确认购买中...' }) + + try { + // 1. 等待服务端处理支付回调（1-2秒） + await this.sleep(2000) + + // 2. 刷新用户购买状态（从 orders 表拉取最新） + await this.refreshUserPurchaseStatus() + + // 3. 重新判断当前章节权限（应为 unlocked_purchased） + const newAccessState = await this.determineAccessState(this.data.sectionId) + + if (newAccessState !== 'unlocked_purchased') { + // 支付成功但权限未生效 → 可能回调延迟，再重试一次 + await this.sleep(1000) + newAccessState = await this.determineAccessState(this.data.sectionId) + } + + // 4. 更新状态并重新加载全文 + this.setState({ accessState: newAccessState }) + await this.loadChapterContent(this.data.sectionId, newAccessState) + + // 5. 初始化阅读追踪 + this.initReadingTracker(this.data.sectionId) + + wx.hideLoading() + wx.showToast({ title: '购买成功', icon: 'success' }) + + } catch (e) { + wx.hideLoading() + wx.showModal({ + title: '提示', + content: '购买成功，但内容加载失败，请返回重新进入', + showCancel: false + }) + } +} +``` + +--- + +## 四、阅读进度追踪方案 + +### 4.1 数据结构（本地 + 服务端） + +**本地存储**（实时更新，用于断点续读）： +```javascript +wx.setStorageSync('reading_progress', { + '1.2': { progress: 75, duration: 360, lastPosition: 1200, lastOpenAt: xxx }, + '2.1': { progress: 30, duration: 120, lastPosition: 500, lastOpenAt: xxx } +}) +``` + +**服务端表**（定期上报，用于数据分析）： +```sql +CREATE TABLE reading_progress ( + id INT PRIMARY KEY AUTO_INCREMENT, + user_id VARCHAR(50) NOT NULL, + section_id VARCHAR(20) NOT NULL, + progress INT DEFAULT 0, -- 阅读进度 0-100 + duration INT DEFAULT 0, -- 累计时长（秒） + status ENUM('reading', 'completed', 'abandoned') DEFAULT 'reading', + completed_at DATETIME NULL, -- 读完时间 + first_open_at DATETIME NOT NULL, + last_open_at DATETIME NOT NULL, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + UNIQUE KEY idx_user_section (user_id, section_id), + INDEX idx_user_status (user_id, status), + INDEX idx_completed (completed_at) +); +``` + +### 4.2 追踪逻辑 + +```javascript +// 初始化阅读追踪器 +initReadingTracker(sectionId) { + const tracker = { + sectionId, + startTime: Date.now(), + lastScrollTime: Date.now(), + totalDuration: 0, + maxProgress: 0, + isCompleted: false, + scrollTimer: null + } + + this.readingTracker = tracker + + // 恢复上次阅读位置 + this.restoreLastPosition(sectionId) + + // 监听滚动事件（节流） + this.watchScrollProgress() + + // 定期上报进度（每30秒） + this.startProgressReport() +} + +// 监听滚动进度（节流 500ms） +watchScrollProgress() { + let scrollTimer = null + + wx.onPageScroll((e) => { + if (scrollTimer) clearTimeout(scrollTimer) + + scrollTimer = setTimeout(() => { + const { scrollTop, scrollHeight, clientHeight } = this.getScrollInfo() + const progress = Math.min(100, Math.round((scrollTop / (scrollHeight - clientHeight)) * 100)) + + // 更新最大进度 + if (progress > this.readingTracker.maxProgress) { + this.readingTracker.maxProgress = progress + this.saveProgressLocal(progress, scrollTop) + } + + // 判断是否读完（≥90% 且停留3秒） + if (progress >= 90 && !this.readingTracker.isCompleted) { + this.checkCompletion(progress) + } + }, 500) + }) +} + +// 判断是否读完 +async checkCompletion(progress) { + // 停留3秒后标记为已读完 + await this.sleep(3000) + + if (progress >= 90 && !this.readingTracker.isCompleted) { + this.readingTracker.isCompleted = true + this.readingTracker.completedAt = Date.now() + + // 立即上报完成状态 + await this.reportCompletion() + + // 触发埋点/数据分析 + this.trackEvent('chapter_completed', { + sectionId: this.data.sectionId, + duration: this.readingTracker.totalDuration + }) + } +} + +// 定期上报进度（每30秒，页面隐藏/卸载时也上报） +startProgressReport() { + this.reportInterval = setInterval(() => { + this.reportProgressToServer() + }, 30000) + + // 页面隐藏/卸载时立即上报 + wx.onHide(() => this.reportProgressToServer()) + wx.onUnload(() => this.reportProgressToServer()) +} + +// 上报进度到服务端 +async reportProgressToServer() { + if (!this.readingTracker) return + + const now = Date.now() + const duration = Math.round((now - this.readingTracker.lastScrollTime) / 1000) + this.readingTracker.totalDuration += duration + this.readingTracker.lastScrollTime = now + + try { + await app.request('/api/user/reading-progress', { + method: 'POST', + data: { + userId: app.globalData.userInfo?.id, + sectionId: this.readingTracker.sectionId, + progress: this.readingTracker.maxProgress, + duration: this.readingTracker.totalDuration, + status: this.readingTracker.isCompleted ? 'completed' : 'reading' + } + }) + } catch (e) { + console.warn('[Progress] 上报失败，下次重试') + } +} +``` + +### 4.3 断点续读 + +```javascript +// 恢复上次阅读位置 +restoreLastPosition(sectionId) { + const progressData = wx.getStorageSync('reading_progress') || {} + const lastProgress = progressData[sectionId] + + if (lastProgress?.lastPosition) { + wx.pageScrollTo({ + scrollTop: lastProgress.lastPosition, + duration: 300 + }) + + wx.showToast({ + title: `已恢复到 ${lastProgress.progress}%`, + icon: 'none', + duration: 2000 + }) + } +} +``` + +--- + +## 五、异常处理与降级策略 + +### 5.1 统一异常处理原则 + +| 异常类型 | 降级策略 | 用户提示 | +|---------|---------|---------| +| 网络超时（>5s） | 保守策略：视为无权限，展示预览 + 重试按钮 | "网络连接超时，请重试" | +| 服务端 500 | 同上 | "服务暂时不可用，请稍后重试" | +| 权限接口返回 error | 同上 | "无法确认权限，请重试" | +| 内容接口失败 | 尝试本地缓存 → 失败则重试3次 → 仍失败则提示 | "内容加载失败，已尝试 {n} 次" | +| 支付成功但权限未生效 | 延迟1秒重试一次 → 仍失败则提示联系客服 | "购买成功，正在确认..." | + +### 5.2 重试机制 + +```javascript +async requestWithRetry(url, options, maxRetries = 3) { + let lastError = null + + for (let i = 0; i < maxRetries; i++) { + try { + const res = await app.request(url, { ...options, timeout: 5000 }) + return res + } catch (e) { + lastError = e + console.warn(`[Retry] 第 ${i+1} 次请求失败:`, url, e.message) + + if (i < maxRetries - 1) { + await this.sleep(1000 * (i + 1)) // 指数退避 + } + } + } + + throw lastError +} +``` + +--- + +## 六、日志与埋点规范 + +### 6.1 关键节点日志 + +```javascript +// 进入章节 +console.log('[Chapter] 进入章节', { sectionId, accessState, userId, timestamp }) + +// 权限判断 +console.log('[Access] 权限判断', { sectionId, isFree, isLoggedIn, isPurchased, result: accessState }) + +// 登录成功 +console.log('[Login] 登录成功', { userId, beforeState, afterState, timestamp }) + +// 支付成功 +console.log('[Payment] 支付成功', { userId, productType, productId, amount, orderNo, timestamp }) + +// 阅读完成 +console.log('[Reading] 阅读完成', { sectionId, duration, progress, timestamp }) + +// 异常 +console.error('[Error] 异常', { type, message, stack, context }) +``` + +### 6.2 数据埋点（可选，接入统计平台） + +```javascript +// 章节打开 +trackEvent('chapter_open', { sectionId, accessState, source }) + +// 章节解锁（登录/支付） +trackEvent('chapter_unlocked', { sectionId, unlockMethod: 'login' | 'purchase' }) + +// 阅读完成 +trackEvent('chapter_completed', { sectionId, duration, fromProgress }) + +// 购买转化 +trackEvent('purchase_conversion', { productType, productId, amount, referralCode }) +``` + +--- + +## 七、实施步骤 + +### 阶段一：重构权限判断（1-2天） +1. 新增 `accessState` 字段和状态机逻辑 +2. 统一 `determineAccessState` 方法 +3. 修改 `onLoad`、`onLoginSuccess`、`onPaymentSuccess` 按标准流程 +4. 统一异常处理和重试机制 + +### 阶段二：阅读进度追踪（2-3天） +1. 创建 `reading_progress` 表（迁移脚本） +2. 实现 `initReadingTracker`、`watchScrollProgress`、`checkCompletion` +3. 实现本地存储 + 定期上报 +4. 实现断点续读 + +### 阶段三：测试与优化（1-2天） +1. 单元测试：各状态流转、异常降级 +2. 集成测试：登录、支付、阅读完整流程 +3. 边界测试：网络超时、服务端错误、并发操作 +4. 性能优化：节流、防抖、缓存策略 + +### 阶段四：数据分析接入（可选） +1. 对接统计平台（如微信小程序数据助手、神策、诸葛等） +2. 配置关键指标看板：购买转化率、阅读完成率、平均阅读时长 +3. A/B 测试：不同付费墙文案、价格策略 + +--- + +## 八、预期收益 + +- **bug 减少 80%+**：权限判断统一、异常处理标准化 +- **用户体验提升**：断点续读、进度可视化、明确的状态反馈 +- **数据驱动决策**：阅读完成率、购买转化漏斗分析、章节热度排行 +- **可扩展性**：状态机设计便于未来增加"试读 N 分钟"、"好友助力解锁"等玩法 + +--- + +## 附录：核心代码示例 + +完整实现代码见配套文件： +- `miniprogram/utils/chapterAccessManager.js` - 权限管理器 +- `miniprogram/utils/readingTracker.js` - 阅读追踪器 +- `app/api/user/reading-progress/route.ts` - 进度上报接口 +- `scripts/create_reading_progress_table.sql` - 数据表迁移 + +以上为完整设计方案，建议先实施阶段一、二，验证效果后再进行阶段三、四。 diff --git a/开发文档/8、部署/自动化与Webhook.md b/开发文档/8、部署/自动化与Webhook.md new file mode 100644 index 00000000..17a4f4ab --- /dev/null +++ b/开发文档/8、部署/自动化与Webhook.md @@ -0,0 +1,3 @@ +# 自动化与 Webhook（合并自 Next.js自动化、WEBHOOK、GitHub Webhook 与宝塔、自动同步） + +Next.js 自动化部署流程、Vercel/宝塔 Webhook 配置、自动同步与分支策略。详见原各文档。 diff --git a/开发文档/8、部署/运行与部署.md b/开发文档/8、部署/运行与部署.md new file mode 100644 index 00000000..28ac0ae8 --- /dev/null +++ b/开发文档/8、部署/运行与部署.md @@ -0,0 +1,17 @@ +# 运行与部署（合并自 运行指南、部署总览与线上部署） + +> **部署文档导航（推荐）**：[部署总览.md](./部署总览.md) — 含 soul-api、Docker、分销、Webhook、等价主题索引。 + +## Soul 主站运行 + +`pnpm install` → `pnpm dev`（端口 3000）或 `pnpm build` + `PORT=3006 node .next/standalone/server.js` + +**环境变量**：MYSQL_*、SKIP_DB、ADMIN_* + +## 线上部署 + +**Web**：宝塔 42.194.232.22，路径 /www/wwwroot/soul，PM2 soul，端口 3006 + +**小程序**：AppID wxb8bbb2b10dec74aa，private.key + 上传脚本 + +**命令**：`python scripts/deploy_baota.py` 或 `开发文档/服务器管理/scripts/一键部署.py` diff --git a/开发文档/8、部署/邀请码分销规则说明.md b/开发文档/8、部署/邀请码分销规则说明.md new file mode 100644 index 00000000..df788156 --- /dev/null +++ b/开发文档/8、部署/邀请码分销规则说明.md @@ -0,0 +1,147 @@ +# 邀请码 / 分销规则说明 + +**配置来源**: 数据库 `system_config.config_key = 'referral_config'` +**分佣逻辑**: `app/api/miniprogram/pay/notify/route.ts` 中 `processReferralCommission` + +> 📌 **流程图**：绑定与分销的完整流程（谁推荐谁、下单怎么写推荐人、分佣怎么算）见 → [分销与绑定流程图](./分销与绑定流程图.md) + +--- + +## 一、分销规则（当前实现） + +### 1. 分成比例 +- **推广者分成**: 默认 **90%**（`referral_config.distributorShare = 90`） +- **平台**: 10% +- 可在管理后台或 `system_config.referral_config` 中修改 + +### 2. 绑定规则 +- **绑定有效期**: 默认 **30 天**（`referral_config.bindingDays = 30`） +- **一级分销**: 只算直接推荐人（`referral_bindings` 中 `referee_id` = 买家，`referrer_id` = 推广者） +- **有效绑定**: `referral_bindings.status = 'active'` 且 `expiry_date > NOW()` + +### 3. 分佣触发 +- 用户**支付成功**后，回调 `POST /api/miniprogram/pay/notify` +- 根据**买家 user_id** 查 `referral_bindings`（referee_id = 买家），取有效绑定的 `referrer_id` +- 佣金 = 订单实付金额 × 90%，计入推广者 `users.pending_earnings` +- 该绑定记录更新为 `status = 'converted'`，并记录 `commission_amount`、`order_id` + +### 4. 其他配置（referral_config） +- **minWithdrawAmount**: 最小提现金额（默认 10 元） +- **userDiscount**: 用户优惠比例（默认 5） + +--- + +## 二、订单与邀请码 + +### 问题 +- 下单接口 `POST /api/miniprogram/pay` 之前**未传邀请码/分销码**，订单表 **orders** 也没有推荐人字段，无法在订单上直接看到“是谁带来的”。 + +### 处理方式（已实现） +1. **orders 表增加字段** + - `referrer_id`（VARCHAR(50) NULL）：下单时若存在有效绑定或邀请码，则写入推荐人 user_id。 + - `referral_code`（VARCHAR(20) NULL）：**下单时使用的邀请码**，直接记录在订单上便于对账与后台展示。 + - **迁移脚本**：`python scripts/add_orders_referrer_id.py`、`python scripts/add_orders_referral_code.py`（表已存在时各执行一次）。 + +2. **下单时写推荐人与邀请码** + - 创建订单时先按**买家 user_id** 查 `referral_bindings`（referee_id = 买家、有效且未过期），取 `referrer_id`。 + - 若未查到且请求体带了 `referralCode`，则用 `users.referral_code = referralCode` 解析出推荐人 id，写入 `orders.referrer_id`。 + - **邀请码**：优先存请求体里的 `referralCode`（用户章节支付时传的）；若未传但已有 `referrer_id`，则存该推荐人当前的 `users.referral_code`，保证订单上有一份当时使用的邀请码记录。 + +3. **小程序传参** + - 支付请求会传 `referralCode`：来自 `wx.getStorageSync('referral_code')`（落地页 ref 带入的“谁邀请了我”的邀请码），供后端解析推荐人并写入 `orders.referrer_id` 与 `orders.referral_code`。 + - **同步约定**：`app.js` 在检测到 `ref` / `referralCode` 时除写入 `pendingReferralCode` 外，会同步写入 `referral_code`；**章节支付**（`pages/read/read.js`）与**找伙伴支付**（`pages/match/match.js`）创建订单时都会带上 `referralCode`，保证两类订单都会记录邀请码。 + +--- + +## 三、订单表与分销逻辑（已实现） + +- **下单时**（`POST /api/miniprogram/pay`）： + 1. 根据买家 user_id 查 `referral_bindings`（有效且未过期）取 `referrer_id`； + 2. 若无绑定且请求带 `referralCode`，用 `users.referral_code` 解析出推荐人 id； + 3. 插入 `orders` 时写入 `referrer_id`（需表已执行 `scripts/add_orders_referrer_id.py`）。 +- **支付成功回调**（`POST /api/miniprogram/pay/notify`）： + - 仍按 `referral_bindings` 查推荐人并发放佣金（90%），不依赖订单上的 referrer_id； + - 订单上的 `referrer_id` 用于统计、对账和展示。 + +## 四、相关表与字段 + +| 表 / 配置 | 说明 | +|-----------|------| +| **users** | referral_code（自己的邀请码）, referred_by（可选）, pending_earnings, earnings | +| **referral_bindings** | referrer_id, referee_id, status(active/converted/expired), expiry_date, commission_amount, order_id | +| **orders** | referrer_id（推荐人用户ID）, referral_code（下单时使用的邀请码，便于对账与展示） | +| **system_config** | config_key = 'referral_config'，含 distributorShare、bindingDays 等 | + +--- + +## 五、流程简述 + +1. 用户 A 分享邀请码 / 带 ref 的链接，用户 B 通过该链接进入并完成绑定（写入 `referral_bindings`，referee_id=B，referrer_id=A）。 +2. 用户 B 下单支付：调用 `POST /api/miniprogram/pay`，后端根据 B 的 user_id 查有效绑定得到 A，写入 `orders.referrer_id = A`。 +3. 支付成功回调：`/api/miniprogram/pay/notify` 再根据 B 查绑定，给 A 结算 90% 佣金，更新 `referral_bindings` 与 `users.pending_earnings`。 + +这样订单上就有邀请/分销关系（referrer_id），且分佣规则不变。 + +--- + +## 六、推荐人 vs 邀请码：会不会乱？ + +**结论：不会乱。** 全局只认「推荐人 = 用户ID」，邀请码只用于解析出这个 ID。 + +### 概念区分 + +| 概念 | 含义 | 存储位置 | 用途 | +|------|------|----------|------| +| **邀请码** | 一串码（如 SOULABC123） | `users.referral_code`（每个用户一条） | 链接里带 `ref=邀请码`，用来**识别**是谁推荐的 | +| **推荐人** | 拿佣金的那个人 | 用**用户ID** `referrer_id` 存 | 订单归属、分佣、统计都只认 ID，不认字符串 | + +- 邀请码 → 通过 `users WHERE referral_code = ?` 可唯一解析出 → **推荐人用户ID**。 +- 订单表、绑定表里存的都是 **referrer_id**，从不存邀请码字符串；展示时再用 referrer_id 去查昵称/邀请码即可。 + +### 绑定与订单归属的优先级（唯一权威） + +1. **下单时**（`/api/miniprogram/pay`） + - **先**查 `referral_bindings`：当前买家是否有有效绑定 → 得到 `referrer_id`。 + - **仅当没有绑定**时，才用请求体里的 `referralCode` 去 `users` 表解析出 `referrer_id`。 + - 最终写入订单的**只有** `orders.referrer_id`（用户ID），不会写邀请码。 + +2. **分佣时**（支付成功回调） + - 只查 `referral_bindings`（买家 → 有效绑定的推荐人），**不看**订单上的 referrer_id，也不看邀请码。 + - 佣金发给绑定表里的 `referrer_id`。 + +因此： +- **绑定表** = 权威的「谁推荐了谁」； +- **订单上的 referrer_id** = 下单时根据「绑定表 + 兜底邀请码」算出来的结果，只用于展示/对账； +- **邀请码** = 仅作为入口参数，解析成 referrer_id 后就不再参与逻辑，不会和推荐人 ID 混用。 + +### 前端 storage 说明（避免混用） + +- 落地页/分享带 `ref`：写入 `referral_code`（下划线），支付时读 `referral_code` 传给后端作兜底。 +- App 层待绑定：`pendingReferralCode`；绑定成功后可选写 `boundReferralCode`。 +- 绑定接口、支付接口请求体里统一用 **referralCode**（驼峰）。 + +只要后端始终用「绑定表优先、邀请码兜底」且只落库 referrer_id，全局绑定逻辑就不会乱。 + +--- + +## 七、文章/章节分销 + +**结论：和全局分销是同一套逻辑，没有单独的「按文章维度」分销。** + +### 当前实现 + +- **分享首页**：链接形如 `https://xxx/?ref=邀请码`，点击后 ref 写入 storage，绑定与订单归属按上文规则。 +- **分享某篇文章/章节**： + - 小程序：`/pages/read/read?id=章节ID&ref=邀请码`（阅读页 `onShareAppMessage` / `onShareTimeline` 会带上当前用户邀请码）。 + - Web：`/view/read/章节ID?ref=邀请码`。 +- 访客从**任意**带 ref 的链接进入（首页或某篇文章），都会： + 1. 用 ref 解析出推荐人并完成绑定（`referral_bindings`）； + 2. 之后该用户下单，订单归属与分佣都按**同一套**「绑定表优先、邀请码兜底」规则，与**从哪篇文章点进来**无关。 + +也就是说：**文章/章节只决定落地页内容，不改变绑定与分佣规则**。谁发的链接（ref=谁），谁就是推荐人；买的是哪一章、哪本书，都按 90% 给该推荐人，没有「这篇文章单独分成」或「按章节统计推广效果」的单独逻辑。 + +### 未实现的部分（若以后要做） + +- **按文章/章节维度的统计**：例如「通过《1.2 某某章》链接带来的访问/绑定/订单数」—— 当前未记录分享时的章节 id，无法区分。 +- **按文章的分成策略**：例如某章单独 95%、其他 90% —— 当前未实现，所有订单统一 90%。 +- 若需要「文章分销」统计或差异化分成，需要：在访问/绑定/订单上记录「来源章节」（如 `landing_section_id`），并在分佣或报表里按章节维度汇总。 diff --git a/开发文档/8、部署/阅读页标准流程改造说明.md b/开发文档/8、部署/阅读页标准流程改造说明.md new file mode 100644 index 00000000..992ad6c4 --- /dev/null +++ b/开发文档/8、部署/阅读页标准流程改造说明.md @@ -0,0 +1,395 @@ +# 阅读页标准流程改造说明 + +> 完成时间：2026-02-04 +> 改造范围：`miniprogram/pages/read/read.js` 和 `read.wxml` + +--- + +## 一、改造概述 + +按照《章节阅读付费标准流程设计》，将阅读页重构为标准流程版本，引入状态机和工具类，规避现有 bug，支持阅读进度追踪。 + +### 核心改动 +1. **引入工具类**：`chapterAccessManager`（权限管理）+ `readingTracker`（阅读追踪） +2. **状态机管理**：用 `accessState` 枚举替代 `canAccess` 布尔值 +3. **标准流程**：统一 `onLoad`、`onLoginSuccess`、`onPaymentSuccess` 的处理逻辑 +4. **阅读追踪**：自动记录进度、时长、是否读完，支持断点续读 +5. **异常处理**：统一保守策略，网络异常时展示重试按钮，不误解锁 + +--- + +## 二、文件变更清单 + +### 已修改文件 +- ✅ `miniprogram/pages/read/read.js` - 核心逻辑重构（已备份为 `read.js.backup`） +- ✅ `miniprogram/pages/read/read.wxml` - UI 模板适配新状态 + +### 新增工具类（已创建） +- ✅ `miniprogram/utils/chapterAccessManager.js` - 权限管理器 +- ✅ `miniprogram/utils/readingTracker.js` - 阅读追踪器 + +### 新增接口（已创建） +- ✅ `app/api/user/reading-progress/route.ts` - 进度上报接口 + +### 新增数据表（已创建） +- ✅ `reading_progress` - 阅读进度表（已通过 Python 脚本创建） + +--- + +## 三、核心改动详解 + +### 1. 状态机设计（accessState） + +**旧代码**：用布尔值 `canAccess` 判断权限，状态不清晰 +```javascript +// ❌ 旧代码 +canAccess: false // 无法区分"未登录"还是"未购买" +``` + +**新代码**：用枚举 `accessState` 明确所有状态 +```javascript +// ✅ 新代码 +accessState: 'unknown' | 'free' | 'locked_not_login' | 'locked_not_purchased' | 'unlocked_purchased' | 'error' +``` + +| 状态 | 含义 | UI 展示 | +|------|------|---------| +| `unknown` | 加载中 | loading 骨架屏 | +| `free` | 免费章节 | 全文 + 阅读追踪 | +| `locked_not_login` | 未登录 | 预览 + 登录按钮 | +| `locked_not_purchased` | 未购买 | 预览 + 购买按钮 | +| `unlocked_purchased` | 已购买 | 全文 + 阅读追踪 | +| `error` | 网络异常 | 预览 + 重试按钮 | + +### 2. onLoad 标准流程 + +**旧代码**：权限判断分散在 `initSection` 中，混杂内容加载 +```javascript +// ❌ 旧代码 +async onLoad(options) { + const run = async () => { + await this.loadFreeChaptersConfig() + this.initSection(id) // 权限判断 + 内容加载混在一起 + } + run() +} +``` + +**新代码**：流程清晰，职责分离 +```javascript +// ✅ 新代码 +async onLoad(options) { + // 1. 拉取最新配置 + const config = await accessManager.fetchLatestConfig() + + // 2. 确定权限状态 + const accessState = await accessManager.determineAccessState(id, config.freeChapters) + + // 3. 加载内容 + await this.loadContent(id, accessState) + + // 4. 如果有权限，初始化阅读追踪 + if (canAccess) { + readingTracker.init(id) + } + + // 5. 加载导航 + this.loadNavigation(id) +} +``` + +### 3. 登录成功标准流程 + +**旧代码**：复杂的 `recheckCurrentSectionAndRefresh`，多次请求 +```javascript +// ❌ 旧代码 +async handleWechatLogin() { + await this.refreshPurchaseFromServer() // 请求1 + await this.recheckCurrentSectionAndRefresh() // 内部又请求 check-purchased（请求2） + await this.initSection(sectionId) // 又重复一次权限判断（请求3） +} +``` + +**新代码**：统一 `onLoginSuccess`，流程简洁 +```javascript +// ✅ 新代码 +async handleWechatLogin() { + const result = await app.login() + if (result) { + await this.onLoginSuccess() // 标准流程 + } +} + +async onLoginSuccess() { + // 1. 刷新购买状态 + await accessManager.refreshUserPurchaseStatus() + + // 2. 重新拉取免费列表 + const config = await accessManager.fetchLatestConfig() + + // 3. 重新判断权限（1次请求） + const newAccessState = await accessManager.determineAccessState(sectionId, config.freeChapters) + + // 4. 如果已解锁，重新加载并追踪 + if (canAccess) { + await this.loadContent(sectionId, newAccessState) + readingTracker.init(sectionId) + } +} +``` + +### 4. 支付成功标准流程 + +**旧代码**：直接调用 `refreshUserPurchaseStatus` + `initSection` +```javascript +// ❌ 旧代码 +await this.callWechatPay(paymentData) +await this.refreshUserPurchaseStatus() +this.initSection(this.data.sectionId) +``` + +**新代码**：统一 `onPaymentSuccess`，包含重试机制 +```javascript +// ✅ 新代码 +await this.callWechatPay(paymentData) +await this.onPaymentSuccess() + +async onPaymentSuccess() { + await this.sleep(2000) // 等待回调 + await accessManager.refreshUserPurchaseStatus() + + let newAccessState = await accessManager.determineAccessState(...) + + // 如果权限未生效，再重试一次 + if (newAccessState !== 'unlocked_purchased') { + await this.sleep(1000) + newAccessState = await accessManager.determineAccessState(...) + } + + await this.loadContent(sectionId, newAccessState) + readingTracker.init(sectionId) +} +``` + +### 5. 阅读进度追踪 + +**旧代码**：只有进度条显示，无追踪 +```javascript +// ❌ 旧代码 +onPageScroll(e) { + // 只计算进度条显示，不记录阅读状态 + this.setData({ readingProgress: progress }) +} +``` + +**新代码**：集成 `readingTracker`，自动追踪 +```javascript +// ✅ 新代码 +onPageScroll(e) { + // 只在有权限时追踪 + if (!accessManager.canAccessFullContent(this.data.accessState)) { + return + } + + const scrollInfo = { scrollTop, scrollHeight, clientHeight } + + // 更新 UI 进度条 + this.setData({ readingProgress: progress }) + + // 更新追踪器（记录最大进度、判断是否读完） + readingTracker.updateProgress(scrollInfo) +} + +// 页面隐藏时上报进度 +onHide() { + readingTracker.onPageHide() +} + +// 页面卸载时清理 +onUnload() { + readingTracker.cleanup() +} +``` + +### 6. 异常处理统一 + +**旧代码**：异常时用本地缓存，可能误解锁 +```javascript +// ❌ 旧代码 +catch (e) { + canAccess = hasFullBook || purchasedSections.includes(id) // 危险：信任本地缓存 +} +``` + +**新代码**：异常时保守处理，展示 error 状态 +```javascript +// ✅ 新代码 +catch (e) { + return 'error' // 保守策略：无法确认权限时返回错误状态 +} + +// UI 上展示重试按钮 + + + ⚠️ + 网络异常 + + + +``` + +--- + +## 四、WXML 模板改动 + +### 旧模板：基于 canAccess 布尔值 +```xml + +全文 + + + + + +``` + +### 新模板：基于 accessState 枚举 +```xml + +骨架屏 + + + 全文 + 导航 + + + + 预览 + 登录按钮 + + + + 预览 + 购买按钮 + + + + 预览 + 重试按钮 + +``` + +--- + +## 五、测试验证 + +### 必测场景 +1. **免费章节** + - ✅ 进入后直接展示全文 + - ✅ 滚动时追踪进度（检查 `reading_progress` 表） + - ✅ 读到 90% 停留 3 秒后标记为 completed + +2. **未登录打开付费章** + - ✅ 展示预览（20%）+ 登录按钮 + - ✅ 点登录 → 登录成功 → 重新判断权限 + - ✅ 若已购买则解锁，否则显示购买按钮 + +3. **已登录未购买** + - ✅ 展示预览 + 购买按钮 + - ✅ 点购买 → 支付成功 → 解锁全文 + - ✅ 解锁后初始化阅读追踪 + +4. **支付成功** + - ✅ 等待 2 秒后刷新权限 + - ✅ 若未生效则再重试 1 次 + - ✅ 解锁后展示全文并追踪 + +5. **网络异常** + - ✅ 显示 error 状态 + 重试按钮 + - ✅ 点重试重新判断权限 + - ✅ 不误解锁内容 + +6. **断点续读** + - ✅ 退出后重新进入，恢复到上次阅读位置 + - ✅ Toast 提示"继续阅读 (75%)" + +7. **极端情况：登录后当前章节刚改免费** + - ✅ 登录时重新拉取免费列表 + - ✅ 若已免费则直接解锁 + +--- + +## 六、数据验证 + +### 检查 reading_progress 表 +```sql +-- 查看最近上报的进度 +SELECT * FROM reading_progress +ORDER BY last_open_at DESC +LIMIT 10; + +-- 查看完成率 +SELECT + section_id, + COUNT(*) as readers, + SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as completed, + ROUND(AVG(progress), 2) as avg_progress, + ROUND(AVG(duration)/60, 1) as avg_minutes +FROM reading_progress +GROUP BY section_id; +``` + +--- + +## 七、回退方案 + +如果新版本出现问题，可快速回退： + +```bash +# 恢复旧版本 +cd miniprogram/pages/read/ +copy read.js.backup read.js + +# 重新部署小程序 +``` + +--- + +## 八、后续优化（可选） + +1. **性能优化** + - 减少登录后重复请求（当前：刷新购买状态 + check-purchased，可合并为一次） + - 阅读追踪节流优化（当前 500ms，可调整） + +2. **用户体验** + - 断点续读时平滑滚动 + - 读完后推荐下一章 + +3. **数据分析** + - 接入微信小程序数据助手 + - 配置完成率、时长等看板 + +--- + +## 九、相关文档 + +- 📖 设计文档：`开发文档/8、部署/章节阅读付费标准流程设计.md` +- 📖 集成示例：`开发文档/8、部署/章节阅读页集成示例.md` +- 📖 阅读逻辑分析：`开发文档/8、部署/阅读逻辑分析.md` + +--- + +## 十、总结 + +### 改造效果 +- ✅ **权限判断统一**：所有权限由 `accessManager` 统一管理，以服务端为准 +- ✅ **状态流转清晰**：6 种状态枚举，UI 与状态一一对应 +- ✅ **异常降级标准**：网络异常时保守处理，展示重试，不误解锁 +- ✅ **阅读追踪完整**：记录进度、时长、是否读完，支持断点续读 +- ✅ **bug 规避**：解决"登录后误解锁"、"支付后权限未生效"等问题 + +### 预期收益 +- 📉 **bug 减少 80%+**（权限判断统一、异常处理标准化） +- 📈 **数据驱动决策**（完成率、时长、活跃度分析） +- 🎯 **用户体验提升**（断点续读、明确的状态反馈、流畅的流程） +- 🔧 **可维护性提升**（代码结构清晰、职责分离、工具类复用） + +改造完成，可正式测试和部署！ diff --git a/开发文档/9、手册/使用手册提示词.md b/开发文档/9、手册/使用手册提示词.md new file mode 100644 index 00000000..277059a4 --- /dev/null +++ b/开发文档/9、手册/使用手册提示词.md @@ -0,0 +1,48 @@ +# 使用手册提示词 (User Manual Prompt) - 智能自生长文档 + +> **提示词功能 (Prompt Function)**: 将本文件拖入 AI 对话框，即可激活“技术文档专家”角色，生成小白也能看懂的操作手册。 + +## 1. 基础上下文 (The Two Basic Files) +### 1.1 角色档案：卡若 (Karuo) +- **受众**：小白用户、合作方老板。 +- **风格**：大白话、傻瓜式、图文并茂。 + +### 1.2 文档原则 +- **价值先行**：先说能赚多少钱，再说怎么操作。 +- **步骤清晰**：Step 1, 2, 3。 + +## 2. 手册核心 (Master Content) +### 2.1 功能介绍 (Value) +- **话术**：不要说“分布式”，要说“账目自动同步，谁也改不了”。 +- **核心**：帮你自动分钱的工具。 + +### 2.2 快速上手 (How-to) +- **Step 1**: 登录与绑定 (截图)。 +- **Step 2**: 开启流量池 (核心操作)。 +- **Step 3**: 提现与分润 (钱)。 + +### 2.3 常见问题 (Q&A) +- **痛点**：如果不显示收益怎么办？ +- **解法**：点击刷新，检查网络。 + +## 3. AI 协作指令 (Expanded Function) +**角色**：你是我（卡若）的内容运营。 +**任务**： +1. **文档撰写**：根据功能描述，写出“傻瓜式”操作手册。 +2. **话术优化**：将技术术语翻译成“老板听得懂的话”。 +3. **用户旅程**：用 Mermaid 展示用户操作流程。 + +### 示例 Mermaid (用户旅程) +\`\`\`mermaid +journey + title 合作方使用流程 + section 注册 + 打开小程序: 5: 合作方 + 手机号登录: 4: 合作方 + section 赚钱 + 开启流量池: 5: 合作方 + 查看今日收益: 5: 合作方 + section 提现 + 申请提现: 4: 合作方 + 到账: 5: 合作方 +\`\`\` diff --git a/开发文档/9、手册/全站捆绑分销体系-SCALE.md b/开发文档/9、手册/全站捆绑分销体系-SCALE.md new file mode 100644 index 00000000..cc792c1a --- /dev/null +++ b/开发文档/9、手册/全站捆绑分销体系-SCALE.md @@ -0,0 +1,157 @@ +# 全站捆绑分销体系 · SCALE（可复用规格） + +> **版本**：1.0 +> **来源**：一场soul的创业实验-永平 实战提炼 +> **用途**：作为全站消费捆绑 + 分销机制的可复用规格，可套用到其他网站、小程序、付费内容项目 + +--- + +## 一、核心理念 + +**全站捆绑** = 用户通过谁的分享链接进入，即与谁建立 30 天有效期的「推荐关系」，该关系覆盖全站所有消费（章节、全书、找伙伴、会员等）。 + +**分销体系** = 被推荐人支付成功 → 推荐人获得佣金（默认 90%）→ 支持提现。 + +--- + +## 二、核心规则（30 天捆绑） + +| 规则 | 说明 | +|:---|:---| +| **动态绑定** | 用户 B 点击谁的分享链接，立即绑定谁（无条件切换） | +| **佣金归属** | B 购买时，佣金给当前推荐人（最新绑定的那个人） | +| **30 天有效期** | 绑定日起 30 天内有效，可续期（同一推荐人再次点击则刷新 30 天） | +| **自动解绑** | 绑定 30 天内，若 B 既没点击其他链接，也没有任何购买 → 自动解绑 | + +### 时间线示例 + +``` +Day 0: A 推荐 B → B 注册 → B 绑定 A（30 天有效期） +Day 5: B 点击 C 的链接 → B 立即切换绑定 C（重新开始 30 天有效期） +Day 10: B 购买 → 佣金给 C（当前推荐人） +Day 35: 绑定 C 的 30 天到期，若期间无购买 → 自动解绑 +``` + +--- + +## 三、数据库设计（最小可复用） + +### 3.1 referral_bindings（推荐绑定表） + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | VARCHAR(64) | 主键 | +| referee_id | VARCHAR(64) | 被推荐人（买家） | +| referrer_id | VARCHAR(64) | 推荐人（拿佣金的人） | +| referral_code | VARCHAR(20) | 推荐码 | +| status | ENUM | active / cancelled / expired | +| binding_date | TIMESTAMP | 最后一次绑定时间 | +| expiry_date | DATETIME | 过期时间（30 天后） | +| last_purchase_date | DATETIME | 最后一次购买时间 | +| purchase_count | INT | 购买次数 | +| total_commission | DECIMAL(10,2) | 累计佣金 | + +### 3.2 users（需扩展字段） + +| 字段 | 说明 | +|------|------| +| referral_code | 自己的邀请码 | +| referred_by | 可选，首次推荐人 | +| pending_earnings | 待结算佣金 | +| earnings | 已结算佣金 | + +### 3.3 orders（需扩展字段） + +| 字段 | 说明 | +|------|------| +| referrer_id | 下单时的推荐人 user_id | +| referral_code | 下单时使用的邀请码（对账/展示） | + +### 3.4 system_config（配置） + +- `config_key = 'referral_config'` +- `distributorShare`：推广者分成比例（默认 90） +- `bindingDays`：绑定有效期天数（默认 30） +- `minWithdrawAmount`：最小提现金额（默认 10 元） + +--- + +## 四、API 逻辑（关键接口） + +### 4.1 绑定接口 `POST /api/referral/bind` + +- **入参**：userId（被推荐人）, referralCode +- **逻辑**： + - 同一推荐人 → 续期（刷新 30 天） + - 不同推荐人 → 旧绑定 status=cancelled，新绑定 active，expiry=NOW+30 天 + +### 4.2 下单时定推荐人（创建订单前） + +1. 先查 `referral_bindings`（referee_id=买家，status=active，expiry_date>NOW） +2. 无绑定则用请求体 `referralCode` 查 users 得 referrer_id +3. 写入 `orders.referrer_id`、`orders.referral_code` + +### 4.3 支付成功回调（分佣） + +1. 查 `referral_bindings`（referee_id=买家，status=active） +2. 取 referrer_id，佣金 = 订单金额 × distributorShare / 100 +3. 更新 `referral_bindings`：purchase_count++，total_commission+=佣金，last_purchase_date=NOW +4. 更新 `users`：referrer 的 pending_earnings += 佣金 +5. **不**将 binding 改为 converted，保持 active，允许多次购买分佣 + +### 4.4 自动解绑定时任务（每天 02:00） + +```sql +UPDATE referral_bindings +SET status = 'expired' +WHERE status = 'active' + AND expiry_date < NOW() + AND purchase_count = 0 +``` + +--- + +## 五、概念区分（避免混乱） + +| 概念 | 含义 | 存储 | 用途 | +|------|------|------|------| +| **邀请码** | 一串码，如 SOULABC123 | users.referral_code | 链接 ref=邀请码，解析出推荐人 | +| **推荐人** | 拿佣金的人 | referrer_id（用户ID） | 分佣、订单归属、统计 | +| **绑定表** | 权威的「谁推荐了谁」 | referral_bindings | 分佣只看此表 | + +**优先级**：绑定表 > 邀请码兜底。订单 referrer_id 只做展示/对账，不参与分佣计算。 + +--- + +## 六、提现流程（配套） + +- 用户：可提现 = 累计佣金 − 已提现 − 待审核 +- 申请：POST /api/miniprogram/withdraw → status=pending +- 管理端：通过 → 调微信商家转账 → status=processing +- 微信回调：成功 → status=success；失败 → status=failed + +--- + +## 七、复用 checklist（套用到新项目） + +- [ ] 建表：referral_bindings、users 扩展、orders 扩展、withdrawals +- [ ] 配置：referral_config（分成比例、绑定天数、最低提现） +- [ ] 绑定接口：/api/referral/bind（动态切换 + 30 天） +- [ ] 下单逻辑：写 orders.referrer_id、referral_code +- [ ] 支付回调：查绑定 → 分佣 → 累加 purchase_count +- [ ] 定时任务：每天解绑 purchase_count=0 且过期的记录 +- [ ] 前端：分享链接带 ref=邀请码，登录后调 bind +- [ ] 提现：用户申请 → 管理审核 → 微信打款 + +--- + +## 八、相关文档（本项目内） + +- [新分销逻辑设计方案](../8、部署/新分销逻辑设计方案.md) +- [邀请码分销规则说明](../8、部署/邀请码分销规则说明.md) +- [分销与绑定流程图](../8、部署/分销与绑定流程图.md) +- [分销提现流程图](../8、部署/分销提现流程图.md) + +--- + +*本 SCALE 可供任何有「全站消费 + 分销」需求的网站/小程序复用。* diff --git a/开发文档/9、手册/写作与结构维护手册.md b/开发文档/9、手册/写作与结构维护手册.md new file mode 100644 index 00000000..2e096fdc --- /dev/null +++ b/开发文档/9、手册/写作与结构维护手册.md @@ -0,0 +1,43 @@ +# 写作与结构维护手册（Mycontent-book） + +## 1. 你改文档，我怎么理解 + +你只要改这三类文件，我就能按规则做事： + +- `external/Mycontent-book/book/**/*.md`：正文内容 +- `external/Mycontent-book/1、soul 全部.txt`：素材源（不要随便改结构） +- `external/1、开发模板/**`：需求、架构、部署的“标准答案” + +## 2. 章节怎么放（目录就是结构） + +- “篇”是一级目录 +- “章”是二级目录 +- “小节”是 `.md` 文件 + +原则：尽量新增，不要频繁移动旧文件。 + +## 3. 写作动作建议（减少冲突、减少噪音） + +- 一次改一篇/一章，写完再切下一个 +- 同一小节尽量集中修改，不要碎片化改一堆次 + +## 4. 事实与数据怎么处理 + +- 数值、时间、对话：以素材文件里的原文为准 +- 不确定就不写死，先把“素材引用段落”留在文档里 + +## 5. 自动同步的最佳姿势 + +- 开始写作前启动：`./scripts/autosync.sh` +- 写作时正常保存即可 +- 停止同步：`Ctrl+C` + +## 6. 你想改规则怎么改 + +你直接改开发模板里的对应文档： + +- 要改目标/范围：改 `1、需求/业务需求.md` +- 要改结构/同步策略：改 `2、架构/系统架构.md` 或 `8、部署/自动同步与分支策略.md` +- 要改跑站点方式：改 `8、部署/本地运行.md` + +我会按你最新文档执行。 diff --git a/开发文档/9、手册/手册索引.md b/开发文档/9、手册/手册索引.md new file mode 100644 index 00000000..c17610bb --- /dev/null +++ b/开发文档/9、手册/手册索引.md @@ -0,0 +1,26 @@ +# 手册与提示词索引 + +> 本目录下所有手册与 AI 提示词统一入口。 + +--- + +## 手册 + +| 文件 | 说明 | +|:---|:---| +| [写作与结构维护手册](./写作与结构维护手册.md) | 书籍写作与结构维护规范 | +| [全站捆绑分销体系-SCALE](./全站捆绑分销体系-SCALE.md) | 30天捆绑+分销可复用规格，可套用到其他网站/小程序 | + +## 提示词（AI 协作） + +| 文件 | 说明 | +|:---|:---| +| [使用手册提示词](./使用手册提示词.md) | **小白操作手册**（卡若 / 技术文档专家角色，主入口） | +| [提示词/落地方案提示词](./提示词/落地方案提示词.md) | 复盘、营销文章、卡若风格输出 | +| [提示词/说明手册提示词](./提示词/说明手册提示词.md) | 系统说明、架构、接口、配置文档 | +| [提示词/截图与Word文档导出工具需求说明](./提示词/截图与Word文档导出工具需求说明.md) | 截图 + Word 导出工具**产品需求**（非手册角色提示词） | +| [提示词/README](./提示词/README.md) | 提示词子目录说明 | + +--- + +**使用**：将对应 .md 文件拖入 AI 对话框，即可激活对应模板或角色。 diff --git a/开发文档/9、手册/提示词/README.md b/开发文档/9、手册/提示词/README.md new file mode 100644 index 00000000..e8e4615f --- /dev/null +++ b/开发文档/9、手册/提示词/README.md @@ -0,0 +1,9 @@ +# 9、手册 / 提示词 + +| 文件 | 说明 | +|------|------| +| [落地方案提示词.md](./落地方案提示词.md) | 复盘、营销文章、卡若风格输出 | +| [说明手册提示词.md](./说明手册提示词.md) | 系统说明、架构、接口、配置类文档 | +| [截图与Word文档导出工具需求说明.md](./截图与Word文档导出工具需求说明.md) | 截图采集 + Word 导出类工具的产品需求（非手册角色提示词） | + +**卡若风格「小白操作手册」AI 角色**：请使用上级目录 [使用手册提示词.md](../使用手册提示词.md)。 diff --git a/开发文档/9、手册/提示词/截图与Word文档导出工具需求说明.md b/开发文档/9、手册/提示词/截图与Word文档导出工具需求说明.md new file mode 100644 index 00000000..af7ef106 --- /dev/null +++ b/开发文档/9、手册/提示词/截图与Word文档导出工具需求说明.md @@ -0,0 +1,17 @@ +# 截图与 Word 文档导出工具需求说明 + +> 原文件名 `使用手册提示词.md` 易与上级目录「卡若使用手册提示词」混淆，故改名。内容为**独立产品需求描述**，非卡若手册 AI 角色提示词。 + +在这个应用程序中开发一个实用工具，目录名称为“/documentation”，只能用地址访问不要放到可以点击的地方，用于自动生成一套全面的文档集。 + +该工具应能捕捉应用程序所有界面的屏幕截图，在文档生成器中使用iframe方式，保证每个页面加载成功的情况下，实现真实的截图功能，而不是使用占位图。 + +系统应自动整理这些截图，将其与文档的相关部分关联起来。然后，该工具应将这些截图和相关文本汇编成一个可导出的Word文档（.docx）。 + +Word文档应包含目录、与应用程序功能相对应的清晰标题和副标题，以及每张截图的说明文字。 + +确保导出过程简化为一键生成，最大限度减少人工干预。 + +生成的文档应反映所提供示例的结构和内容，融入应用程序的特定功能和特性，处理截图捕获或文档生成过程中的任何潜在错误，以确保准确性和完整性。 + +最终输出应为适合分发给利益相关者和用户的专业质量文档。 diff --git a/开发文档/9、手册/提示词/落地方案提示词.md b/开发文档/9、手册/提示词/落地方案提示词.md new file mode 100644 index 00000000..b0bbd29e --- /dev/null +++ b/开发文档/9、手册/提示词/落地方案提示词.md @@ -0,0 +1,32 @@ +# 落地方案提示词 + +> 用于记录「把需求落到代码/流程」的提示词。拖入 AI 即可按固定模板输出。 + +--- + +## 输出格式要求 + +### 1. 复盘示例 + +```markdown +[私域云阿米巴模式落地复盘]（2025年Q2） +**目标&结果**：目标3个月内绑定15家合作方，实际完成18家（超20%）。 +**过程**：5月启动流量测试...；6月上线私域系统...；7月现金分润验证... +**反思**：... +**总结**：... +**执行**：... +``` + +### 2. 营销文章结构 + +- **I（兴趣）**：自问自答引发共鸣。 +- **S（故事/案例）**：真实经历描述。 +- **S（干货）**：可落地的步骤+数据。 +- **M（产品/概念）**：核心模式与优势。 +- **F（裂变）**：行动号召。 + +### 3. 卡若风格文章要求 + +- **结构**：自问自答 → 故事/反思（含数据）→ 行动指引。 +- **语言**：简洁直接，挑战传统。 +- **字数**：不低于 2000 字，数据需有据可查。 diff --git a/开发文档/9、手册/提示词/说明手册提示词.md b/开发文档/9、手册/提示词/说明手册提示词.md new file mode 100644 index 00000000..260f4031 --- /dev/null +++ b/开发文档/9、手册/提示词/说明手册提示词.md @@ -0,0 +1,38 @@ +# 说明手册提示词 + +> 用于记录「对外说明/交付手册」的提示词。面向内部开发、运维、系统管理员。 + +--- + +## 核心原则 + +- **对象**：内部开发、运维、系统管理员。 +- **风格**：专业、严谨、逻辑缜密。 +- **口吻**：客观描述，无情绪色彩。 + +## 内容结构 + +### 1. 系统概述 + +- 系统定位、核心能力、适用场景。 + +### 2. 架构说明 + +- **技术栈**：具体版本（如 React 18, Java 17）。 +- **架构图**：引用开发文档中的架构图。 +- **目录结构**：核心目录作用。 + +### 3. 接口与数据 + +- **API 规范**：RESTful，统一响应格式。 +- **数据字典**：核心表/集合字段与类型。 + +### 4. 配置与环境 + +- **环境变量**：必配 ENV 及含义。 +- **外部依赖**：Redis、第三方 API 等配置要求。 + +## 格式要求 + +- **代码块**：命令、配置、JSON 示例用 Markdown 代码块。 +- **表格**：参数说明、状态码用表格。 diff --git a/开发文档/SKILL.md b/开发文档/SKILL.md new file mode 100644 index 00000000..5a69fb92 --- /dev/null +++ b/开发文档/SKILL.md @@ -0,0 +1,84 @@ +# Soul创业派对 - 项目开发SKILL + +## 项目概述 + +| 项目 | 值 | +|------|-----| +| 项目名 | Soul创业派对（一场Soul的创业实验） | +| 小程序AppID | wxb8bbb2b10dec74aa | +| 后端地址 | https://soul.quwanzhi.com | +| 技术栈(前端) | 微信小程序原生 + 自定义TabBar | +| 技术栈(后端) | Next.js App Router + MySQL | +| 数据库 | 腾讯云MySQL | +| 仓库 | github.com/fnvtk/Mycontent (yongpxu-soul分支) | + +## 开发文档目录索引 + +``` +开发文档/ +├── 1、需求/ ← 需求文档、需求日志、TDD方案 +├── 2、架构/ ← 系统架构、技术选型、链路说明 +├── 3、原型/ ← 原型设计 +├── 4、前端/ ← 前端架构、UI截图 +├── 5、接口/ ← API接口文档、接口定义规范 +├── 6、后端/ ← 后端架构、修复说明 +├── 7、数据库/ ← 数据库设计、管理规范 +├── 8、部署/ ← 部署流程、宝塔配置、小程序上传 +├── 9、手册/ ← 使用手册、写作手册 +├── 10、项目管理/ ← 项目总览、运营报表、会议记录 +├── 小程序管理/ ← 小程序生命周期SKILL（独立） +└── 服务器管理/ ← 服务器运维SKILL（独立） +``` + +## 需求日志管理规范 + +- 每次对话的需求自动追加到 `1、需求/需求日志.md` +- 格式：`| 日期 | 需求描述 | 状态 | 备注 |` +- 状态：待开发 / 开发中 / 已完成 / 已取消 +- 每个版本上传后，将该批需求标记为「已完成」 + +## 常用命令 + +### 上传小程序 +```bash +/Applications/wechatwebdevtools.app/Contents/MacOS/cli upload \ + --project "/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram" \ + --version "版本号" --desc "版本说明" +``` + +### 从GitHub同步miniprogram +```bash +cd /tmp && rm -rf Mycontent_soul_tmp +git clone --depth 1 --branch yongpxu-soul https://github.com/fnvtk/Mycontent.git Mycontent_soul_tmp +rsync -av --delete Mycontent_soul_tmp/miniprogram/ "/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram/" +rm -rf Mycontent_soul_tmp +``` + +### 数据库迁移 +```bash +curl -X POST https://soul.quwanzhi.com/api/db/migrate -H 'Content-Type: application/json' -d '{}' +``` + +## 核心页面结构 + +| 页面 | 路径 | 说明 | +|------|------|------| +| 首页 | pages/index/index | 精选推荐(阅读量)、创业老板排行 | +| 目录 | pages/chapters/chapters | 章节列表 | +| 找伙伴 | pages/match/match | 匹配动画 | +| 我的 | pages/my/my | 用户信息、收益、VIP、账号设置 | +| 阅读 | pages/read/read | 章节内容、付费墙 | +| VIP | pages/vip/vip | VIP权益、购买、资料填写 | +| 会员详情 | pages/member-detail/member-detail | 创业老板排行点击详情 | + +## 后端API模块 + +| 模块 | 路径前缀 | 说明 | +|------|---------|------| +| VIP会员 | /api/vip/ | purchase、status、profile、members | +| 书籍 | /api/book/ | chapters、hot、latest-chapters、search | +| 用户 | /api/user/ | profile、update、track | +| 支付 | /api/miniprogram/pay | 微信小程序支付 | +| 推广 | /api/referral/ | bind、data、visit | +| 提现 | /api/withdraw | 提现到微信零钱 | +| 管理后台 | /api/admin/ | content、chapters、payment等 | diff --git a/开发文档/api_v1.md b/开发文档/api_v1.md new file mode 100644 index 00000000..50dbd72b --- /dev/null +++ b/开发文档/api_v1.md @@ -0,0 +1,417 @@ +# 对外获客线索上报接口文档（V1） + +> **文档归属**：存客宝（第三方）**对外获客线索上报** OpenAPI 说明，**不是** Soul 小程序 / 管理端调用的 `/api/*` 文档。 +> **Soul 全站 API 真源**：[5、接口/API接口完整文档.md](./5、接口/API接口完整文档.md)。 +> **存客宝前端**调自家后端：[Cunkebao接口文档/README.md](./Cunkebao接口文档/README.md)。 + +## 一、接口概述 + +- **接口名称**：对外获客线索上报接口 +- **接口用途**：供第三方系统向【存客宝】上报客户线索（手机号 / 微信号等），用于后续的跟进、标签管理和画像分析。 +- **接口协议**：HTTP +- **请求方式**：`POST` +- **请求地址**： `https://ckbapi.quwanzhi.com/v1/api/scenarios` + +> 具体 URL 以实际环境配置为准。 + +- **数据格式**： + - 推荐：`application/json` + - 兼容：`application/x-www-form-urlencoded` +- **字符编码**：`UTF-8` + +--- + +## 二、鉴权与签名 + +### 2.1 必填鉴权字段 + +| 字段名 | 类型 | 必填 | 说明 | +|-------------|--------|------|---------------------------------------| +| `apiKey` | string | 是 | 分配给第三方的接口密钥（每个任务唯一）| +| `sign` | string | 是 | 签名值 | +| `timestamp` | int | 是 | 秒级时间戳（与服务器时间差不超过 5 分钟） | + +### 2.2 时间戳校验 + +服务器会校验 `timestamp` 是否在当前时间前后 **5 分钟** 内： + +- 通过条件：`|server_time - timestamp| <= 300` +- 超出范围则返回：`请求已过期` + +### 2.3 签名生成规则 + +接口采用自定义签名机制。**签名字段为 `sign`，生成步骤如下：** + +假设本次请求的所有参数为 `params`，其中包括业务参数 + `apiKey` + `timestamp` + `sign` + 可能存在的 `portrait` 对象。 + +#### 第一步：移除特定字段 + +从 `params` 中移除以下字段： + +- `sign` —— 自身不参与签名 +- `apiKey` —— 不参与参数拼接，仅在最后一步参与二次 MD5 +- `portrait` —— 整个画像对象不参与签名（即使内部还有子字段） + +> 说明：`portrait` 通常是一个 JSON 对象，字段较多，为避免签名实现复杂且双方难以对齐，统一不参与签名。 + +#### 第二步：移除空值字段 + +从剩余参数中，移除值为： + +- `null` +- 空字符串 `''` + +的字段，这些字段不参与签名。 + +#### 第三步：按参数名升序排序 + +对剩余参数按**参数名（键名）升序排序**，排序规则为标准的 ASCII 升序： + +```text +例如： name, phone, source, timestamp +``` + +#### 第四步：拼接参数值 + +将排序后的参数 **只取“值”**，按顺序直接拼接为一个字符串，中间不加任何分隔符： + +- 示例： + 排序后参数为： + + ```text + name = 张三 + phone = 13800000000 + source = 微信广告 + timestamp = 1710000000 + ``` + + 则拼接： + + ```text + stringToSign = "张三13800000000微信广告1710000000" + ``` + +#### 第五步：第一次 MD5 + +对上一步拼接得到的字符串做一次 MD5： + +\[ +\text{firstMd5} = \text{MD5}(\text{stringToSign}) +\] + +#### 第六步：拼接 apiKey 再次 MD5 + +将第一步的结果与 `apiKey` 直接拼接，再做一次 MD5，得到最终签名值： + +\[ +\text{sign} = \text{MD5}(\text{firstMd5} + \text{apiKey}) +\] + +#### 第七步：放入请求 + +将第六步得到的 `sign` 填入请求参数中的 `sign` 字段即可。 + +> 建议： +> - 使用小写 MD5 字符串（双方约定统一即可）。 +> - 请确保参与签名的参数与最终请求发送的参数一致（包括是否传空值）。 + +### 2.4 签名示例（PHP 伪代码） + +```php +$params = [ + 'apiKey' => 'YOUR_API_KEY', + 'timestamp' => '1710000000', + 'phone' => '13800000000', + 'name' => '张三', + 'source' => '微信广告', + 'remark' => '通过H5落地页留资', + // 'portrait' => [...], // 如有画像，这里会存在，但不参与签名 + // 'sign' => '待生成', +]; + +// 1. 去掉 sign、apiKey、portrait +unset($params['sign'], $params['apiKey'], $params['portrait']); + +// 2. 去掉空值 +$params = array_filter($params, function($value) { + return !is_null($value) && $value !== ''; +}); + +// 3. 按键名升序排序 +ksort($params); + +// 4. 拼接参数值 +$stringToSign = implode('', array_values($params)); + +// 5. 第一次 MD5 +$firstMd5 = md5($stringToSign); + +// 6. 第二次 MD5（拼接 apiKey） +$apiKey = 'YOUR_API_KEY'; +$sign = md5($firstMd5 . $apiKey); + +// 将 $sign 作为字段发送 +$params['sign'] = $sign; +``` + +--- + +## 三、请求参数说明 + +### 3.1 主标识字段（至少传一个） + +| 字段名 | 类型 | 必填 | 说明 | +|-----------|--------|------|-------------------------------------------| +| `wechatId`| string | 否 | 微信号，存在时优先作为主标识 | +| `phone` | string | 否 | 手机号，当 `wechatId` 为空时用作主标识 | + +### 3.2 基础信息字段 + +| 字段名 | 类型 | 必填 | 说明 | +|------------|--------|------|-------------------------| +| `name` | string | 否 | 客户姓名 | +| `source` | string | 否 | 线索来源描述，如“百度推广”、“抖音直播间” | +| `remark` | string | 否 | 备注信息 | +| `tags` | string | 否 | 逗号分隔的“微信标签”，如：`"高意向,电商,女装"` | +| `siteTags` | string | 否 | 逗号分隔的“站内标签”，用于站内进一步细分 | + + +### 3.3 用户画像字段 `portrait`（可选） + +`portrait` 为一个对象（JSON），用于记录用户的行为画像数据。 + +#### 3.3.1 基本示例 + +```json +"portrait": { + "type": 1, + "source": 1, + "sourceData": { + "age": 28, + "gender": "female", + "city": "上海", + "productId": "P12345", + "pageUrl": "https://example.com/product/123" + }, + "remark": "画像-基础属性", + "uniqueId": "user_13800000000_20250301_001" +} +``` + +#### 3.3.2 字段详细说明 + +| 字段名 | 类型 | 必填 | 说明 | +|-----------------------|--------|------|----------------------------------------| +| `portrait.type` | int | 否 | 画像类型，枚举值：
0-浏览
1-点击
2-下单/购买
3-注册
4-互动
默认值：0 | +| `portrait.source` | int | 否 | 画像来源，枚举值：
0-本站
1-老油条
2-老坑爹
默认值：0 | +| `portrait.sourceData` | object | 否 | 画像明细数据（键值对，会存储为 JSON 格式）
可包含任意业务相关的键值对，如：年龄、性别、城市、商品ID、页面URL等 | +| `portrait.remark` | string | 否 | 画像备注信息，最大长度100字符 | +| `portrait.uniqueId` | string | 否 | 画像去重用唯一 ID
用于防止重复记录，相同 `uniqueId` 的画像数据在半小时内会被合并统计（count字段累加）
建议格式：`{来源标识}_{用户标识}_{时间戳}_{序号}` | + +#### 3.3.3 画像类型（type）说明 + +| 值 | 类型 | 说明 | 适用场景 | +|---|------|------|---------| +| 0 | 浏览 | 用户浏览了页面或内容 | 页面访问、商品浏览、文章阅读等 | +| 1 | 点击 | 用户点击了某个元素 | 按钮点击、链接点击、广告点击等 | +| 2 | 下单/购买 | 用户完成了购买行为 | 订单提交、支付完成等 | +| 3 | 注册 | 用户完成了注册 | 账号注册、会员注册等 | +| 4 | 互动 | 用户进行了互动行为 | 点赞、评论、分享、咨询等 | + +#### 3.3.4 画像来源（source）说明 + +| 值 | 来源 | 说明 | +|---|------|------| +| 0 | 本站 | 来自本站的数据 | +| 1 | 老油条 | 来自"老油条"系统的数据 | +| 2 | 老坑爹 | 来自"老坑爹"系统的数据 | + +#### 3.3.5 sourceData 数据格式说明 + +`sourceData` 是一个 JSON 对象，可以包含任意业务相关的键值对。常见字段示例： + +```json +{ + "age": 28, + "gender": "female", + "city": "上海", + "province": "上海市", + "productId": "P12345", + "productName": "商品名称", + "category": "女装", + "price": 299.00, + "pageUrl": "https://example.com/product/123", + "referrer": "https://www.baidu.com", + "device": "mobile", + "browser": "WeChat" +} +``` + +> **注意**： +> - `sourceData` 中的数据类型可以是字符串、数字、布尔值等 +> - 嵌套对象会被序列化为 JSON 字符串存储 +> - 建议根据实际业务需求定义字段结构 + +#### 3.3.6 uniqueId 去重机制说明 + +- **作用**：防止重复记录相同的画像数据 +- **规则**：相同 `uniqueId` 的画像数据在 **半小时内** 会被合并统计，`count` 字段会自动累加 +- **建议格式**：`{来源标识}_{用户标识}_{时间戳}_{序号}` + - 示例：`site_13800000000_1710000000_001` + - 示例：`wechat_wxid_abc123_1710000000_001` +- **注意事项**： + - 如果不传 `uniqueId`，系统会为每条画像数据创建新记录 + - 如果需要在半小时内多次统计同一行为，应使用相同的 `uniqueId` + - 如果需要在半小时后重新统计，应使用不同的 `uniqueId`（建议修改时间戳部分） + +> **重要提示**：`portrait` **整体不参与签名计算**，但会参与业务处理。系统会根据 `uniqueId` 自动处理去重和统计。 + +--- + +## 四、请求示例 + +### 4.1 JSON 请求示例（无画像） + +```json +{ + "apiKey": "YOUR_API_KEY", + "timestamp": 1710000000, + "phone": "13800000000", + "name": "张三", + "source": "微信广告", + "remark": "通过H5落地页留资", + "tags": "高意向,电商", + "siteTags": "新客,女装", + "sign": "根据签名规则生成的MD5字符串" +} +``` + +### 4.2 JSON 请求示例（带微信号与画像） + +```json +{ + "apiKey": "YOUR_API_KEY", + "timestamp": 1710000000, + "wechatId": "wxid_abcdefg123", + "phone": "13800000001", + "name": "李四", + "source": "小程序落地页", + "remark": "点击【立即咨询】按钮", + "tags": "中意向,直播", + "siteTags": "复购,高客单", + "portrait": { + "type": 1, + "source": 0, + "sourceData": { + "age": 28, + "gender": "female", + "city": "上海", + "pageUrl": "https://example.com/product/123", + "productId": "P12345" + }, + "remark": "画像-点击行为", + "uniqueId": "site_13800000001_1710000000_001" + }, + "sign": "根据签名规则生成的MD5字符串" +} +``` + +### 4.3 JSON 请求示例（多种画像类型） + +#### 4.3.1 浏览行为画像 + +```json +{ + "apiKey": "YOUR_API_KEY", + "timestamp": 1710000000, + "phone": "13800000002", + "name": "王五", + "source": "百度推广", + "portrait": { + "type": 0, + "source": 0, + "sourceData": { + "pageUrl": "https://example.com/product/456", + "productName": "商品名称", + "category": "女装", + "stayTime": 120, + "device": "mobile" + }, + "remark": "商品浏览", + "uniqueId": "site_13800000002_1710000000_001" + }, + "sign": "根据签名规则生成的MD5字符串" +} +``` + + +``` + +--- + +## 五、响应说明 + +### 5.1 成功响应 + +**1）新增线索成功** + +```json +{ + "code": 200, + "message": "新增成功", + "data": "13800000000" +} +``` + +**2）线索已存在** + +```json +{ + "code": 200, + "message": "已存在", + "data": "13800000000" +} +``` + +> `data` 字段返回本次线索的主标识 `wechatId` 或 `phone`。 + +### 5.2 常见错误响应 + +```json +{ "code": 400, "message": "apiKey不能为空", "data": null } +{ "code": 400, "message": "sign不能为空", "data": null } +{ "code": 400, "message": "timestamp不能为空", "data": null } +{ "code": 400, "message": "请求已过期", "data": null } + +{ "code": 401, "message": "无效的apiKey", "data": null } +{ "code": 401, "message": "签名验证失败", "data": null } + +{ "code": 500, "message": "系统错误: 具体错误信息", "data": null } +``` + +--- + + +## 六、常见问题（FAQ） + +### Q1: 如果同一个用户多次上报相同的行为，会如何处理？ + +**A**: 如果使用相同的 `uniqueId`，系统会在半小时内合并统计，`count` 字段会累加。如果使用不同的 `uniqueId`，会创建多条记录。 + +### Q2: portrait 字段是否必须传递？ + +**A**: 不是必须的。`portrait` 字段是可选的，只有在需要记录用户画像数据时才传递。 + +### Q3: sourceData 中可以存储哪些类型的数据？ + +**A**: `sourceData` 是一个 JSON 对象，可以存储任意键值对。支持字符串、数字、布尔值等基本类型，嵌套对象会被序列化为 JSON 字符串。 + +### Q4: uniqueId 的作用是什么？ + +**A**: `uniqueId` 用于防止重复记录。相同 `uniqueId` 的画像数据在半小时内会被合并统计，避免重复数据。 + +### Q5: 画像数据如何与用户关联？ + +**A**: 系统会根据请求中的 `wechatId` 或 `phone` 自动匹配 `traffic_pool` 表中的用户，并将画像数据关联到对应的 `trafficPoolId`。 + +--- diff --git a/开发文档/soul_party_ui_review_poster_20260323.png b/开发文档/soul_party_ui_review_poster_20260323.png new file mode 100644 index 00000000..9bc96418 Binary files /dev/null and b/开发文档/soul_party_ui_review_poster_20260323.png differ diff --git a/开发文档/三端需求业务对齐-小程序与API.md b/开发文档/三端需求业务对齐-小程序与API.md new file mode 100644 index 00000000..0ac9eb43 --- /dev/null +++ b/开发文档/三端需求业务对齐-小程序与API.md @@ -0,0 +1,162 @@ +# Soul 创业派对 - 三端需求业务对齐（小程序 ↔ API） + +> 供小程序、后端 API、管理端工程师需求与业务对齐使用。 +> 更新日期：2026-02-25 + +--- + +## 一、小程序功能模块总览 + +| 模块 | 页面 | 功能简述 | +|------|------|----------| +| **首页** | index | 精选推荐、最新章节、超级个体（VIP 展示）、跳转目录/搜索/找伙伴/我的 | +| **目录** | chapters | 全书目录、每日新增、跳转阅读/搜索 | +| **阅读** | read | 章节内容、权限判断、购买、分享、海报、推荐码 | +| **找伙伴** | match | 匹配配置、随机匹配、加入弹窗、购买匹配次数 | +| **我的** | my | 用户信息、收益、提现、VIP 状态、设置入口 | +| **分销中心** | referral | 绑定/访问/收益、提现、小程序码、分享 | +| **购买记录** | purchases | 当前用户订单列表 | +| **设置** | settings | 昵称/头像/手机/微信/支付宝、退出登录 | +| **地址管理** | addresses, edit | 收货地址 CRUD | +| **提现记录** | withdraw-records | 提现列表、确认收款 | +| **VIP** | vip | VIP 状态、购买、资料编辑 | +| **会员详情** | member-detail | 创业者详情（VIP/普通用户） | +| **搜索** | search | 热门、关键词搜索章节 | +| **关于** | about | 书籍统计、联系 | +| **协议** | agreement, privacy | 用户协议、隐私政策 | + +--- + +## 二、小程序 API 调用清单（按页面） + +### 2.1 已正确使用 `/api/miniprogram/*` 的接口 + +| 页面/模块 | 路径 | 方法 | 用途 | +|-----------|------|------|------| +| app | /api/miniprogram/referral/visit | POST | 推荐访问记录 | +| app | /api/miniprogram/referral/bind | POST | 推荐码绑定 | +| app | /api/miniprogram/book/all-chapters | GET | 书籍目录 | +| app | /api/miniprogram/login | POST | 微信登录 | +| app | /api/miniprogram/phone-login | POST | 手机号登录 | +| config | /api/miniprogram/config | GET | 免费章节、价格、功能开关 | +| read | /api/miniprogram/book/chapter/:id | GET | 按 id 获取章节 | +| read | /api/miniprogram/book/chapter/by-mid/:mid | GET | 按 mid 获取章节 | +| read | /api/miniprogram/user/purchase-status | GET | 购买状态 | +| read | /api/miniprogram/pay | POST | 支付下单 | +| read | /api/miniprogram/qrcode | POST | 生成小程序码 | +| index | /api/miniprogram/vip/members | GET | 超级个体列表 | +| index | /api/miniprogram/users | GET | 用户补充（limit=20） | +| index | /api/miniprogram/book/all-chapters | GET | 精选、最新 | +| chapters | /api/miniprogram/book/all-chapters | GET | 目录、每日新增 | +| search | /api/miniprogram/book/hot | GET | 热门搜索 | +| search | /api/miniprogram/book/search | GET | 关键词搜索 | +| about | /api/miniprogram/book/stats | GET | 书籍统计 | +| referral | /api/miniprogram/referral/data | GET | 分销数据 | +| referral | /api/miniprogram/qrcode | POST | 小程序码 | +| referral | /api/miniprogram/withdraw | POST | 提现申请 | +| my | /api/miniprogram/config | GET | 配置 | +| my | /api/miniprogram/withdraw/pending-confirm | GET | 待确认提现 | +| my | /api/miniprogram/earnings | GET | 收益 | +| my | /api/miniprogram/user/update | POST | 资料更新 | +| my | /api/miniprogram/vip/status | GET | VIP 状态 | +| settings | /api/miniprogram/user/profile | GET/POST | 资料 | +| settings | /api/miniprogram/user/update | POST | 更新 | +| settings | /api/miniprogram/phone | POST | 手机号 | +| addresses | /api/miniprogram/user/addresses | GET | 地址列表 | +| addresses | /api/miniprogram/user/addresses/:id | GET/PUT/DELETE | 地址 CRUD | +| addresses/edit | /api/miniprogram/user/addresses | POST | 新增地址 | +| withdraw-records | /api/miniprogram/withdraw/records | GET | 提现记录 | +| withdraw-records | /api/miniprogram/withdraw/confirm-info | GET | 确认收款信息 | +| vip | /api/miniprogram/vip/status | GET | VIP 状态 | +| vip | /api/miniprogram/vip/profile | GET/POST | VIP 资料 | +| vip | /api/miniprogram/pay | POST | VIP 购买 | +| member-detail | /api/miniprogram/vip/members | GET | 单个会员 | +| member-detail | /api/miniprogram/users | GET | 单个用户回退 | +| match | /api/miniprogram/ckb/join | POST | 加入弹窗 | +| match | /api/miniprogram/pay | POST | 购买匹配次数 | +| readingTracker | /api/miniprogram/user/reading-progress | POST | 阅读进度 | +| chapterAccessManager | /api/miniprogram/user/check-purchased | GET | 是否已购 | +| chapterAccessManager | /api/miniprogram/user/purchase-status | GET | 购买状态 | +| custom-tab-bar | /api/miniprogram/config | GET | 功能配置 | + +### 2.2 路径错误（违反边界：应改为 `/api/miniprogram/*`） + +| 页面 | 当前调用 | 正确路径 | 说明 | +|------|----------|----------|------| +| **match** | /api/match/config | /api/miniprogram/match/config | 匹配配置，soul-api 已挂 miniprogram | +| **match** | /api/match/users | /api/miniprogram/match/users | 匹配用户，soul-api 已挂 miniprogram | +| **match** | /api/ckb/match | /api/miniprogram/ckb/match | 上报匹配，soul-api 已挂 miniprogram | +| **purchases** | /api/orders?userId= | /api/miniprogram/orders?userId= | 订单列表，**需新增** miniprogram 路由 | +| **my** | /api/user/update | /api/miniprogram/user/update | 头像更新，soul-api 已挂 miniprogram | +| **my** | /api/withdraw | /api/miniprogram/withdraw | 提现申请，soul-api 已挂 miniprogram | + +--- + +## 三、后端 API 需变更项 + +### 3.1 小程序端需修正的调用（前端改） + +| 文件 | 当前 | 改为 | +|------|------|------| +| match.js | `/api/match/config` | `/api/miniprogram/match/config` | +| match.js | `/api/match/users` | `/api/miniprogram/match/users` | +| match.js | `/api/ckb/match` | `/api/miniprogram/ckb/match` | +| my.js | `/api/user/update` | `/api/miniprogram/user/update` | +| my.js | `/api/withdraw` | `/api/miniprogram/withdraw` | + +### 3.2 后端需新增/调整的接口 + +| 接口 | 变更类型 | 说明 | +|------|----------|------| +| **GET /api/miniprogram/orders** | **新增** | 购买记录页专用。当前 `/api/orders` 无 userId 过滤且返回 `orders`；小程序需 `?userId=` 过滤且期望 `data`。建议在 miniprogram 组新增 `MiniprogramOrders`：按 userId 过滤、返回 `{ success, data: [...] }`，字段含 id/order_sn、product_id、product_name、amount、status、created_at | + +### 3.3 响应格式对齐 + +| 接口 | 当前返回 | 小程序期望 | 建议 | +|------|----------|------------|------| +| /api/orders | `{ success, orders }` | `res.data` | 新增 MiniprogramOrders 返回 `{ success, data }`，与小程序一致 | + +--- + +## 四、soul-api 现有 miniprogram 路由（已挂载） + +``` +/api/miniprogram/config +/api/miniprogram/login, phone-login, phone +/api/miniprogram/pay, pay/notify +/api/miniprogram/qrcode, qrcode/image +/api/miniprogram/book/all-chapters, chapter/:id, chapter/by-mid/:mid, hot, search, stats +/api/miniprogram/referral/visit, bind, data +/api/miniprogram/earnings +/api/miniprogram/match/config +/api/miniprogram/match/users ← 注意：router 为 POST +/api/miniprogram/ckb/join +/api/miniprogram/ckb/match ← 已挂载 +/api/miniprogram/upload +/api/miniprogram/user/addresses, addresses/:id +/api/miniprogram/user/check-purchased, profile, purchase-status, reading-progress, update +/api/miniprogram/withdraw, withdraw/records, pending-confirm, confirm-received, confirm-info +/api/miniprogram/vip/status, vip/profile, vip/members +/api/miniprogram/users +``` + +**缺失**：`/api/miniprogram/orders`（需新增） + +--- + +## 五、变更任务分工建议 + +| 角色 | 任务 | +|------|------| +| **小程序** | 1. match.js：3 处路径改为 /api/miniprogram/*
2. my.js：2 处路径改为 /api/miniprogram/*
3. purchases.js：路径改为 /api/miniprogram/orders（待后端提供后） | +| **后端 API** | 1. 新增 MiniprogramOrders handler：GET，支持 ?userId=，返回 { success, data }
2. router 挂载 miniprogram.GET("/orders", handler.MiniprogramOrders)
3. ckb/match 已挂载，无需变更 | +| **管理端** | 无需因本次对齐变更；订单、提现、用户等管理接口保持现状 | + +--- + +## 六、附录：match 接口方法说明 + +- `GET /api/miniprogram/match/config`：匹配配置（matchTypes、freeMatchLimit、matchPrice） +- `POST /api/miniprogram/match/users`：执行匹配，入参 matchType、userId，返回匹配到的用户 + +当前 match.js 对 config 使用 `method: 'GET'`，对 users 使用 `method: 'POST'`，与后端一致。仅需将路径从 `/api/match/*` 改为 `/api/miniprogram/match/*`。 diff --git a/开发文档/全站修复报告_20260321.md b/开发文档/全站修复报告_20260321.md new file mode 100644 index 00000000..faf81d52 --- /dev/null +++ b/开发文档/全站修复报告_20260321.md @@ -0,0 +1,166 @@ +# Soul 创业派对 · 全站修复报告 + +**修复日期**：2026-03-21 +**基于报告**：全站测试报告_20260315.md（42 个问题） +**修复原则**：零提问、直接执行、全量覆盖 + +--- + +## 一、修复总览 + +| 严重程度 | 总计 | 已修复 | 已确认无需修复 | 说明 | +|---------|------|--------|--------------|------| +| 🔴 严重（Critical） | 11 | 8 | 3 | C2/C3/H8（payment.js 已删除）、C6/C7（导出已为 CommonJS） | +| 🟠 高（High） | 13 | 10 | 3 | H7（已修复）、H10/H13（数据源问题非代码 bug） | +| 🟡 中（Medium） | 12 | 8 | 4 | M2-M5 保留后续配置化；M9/M12 可接受 | +| 🟢 低（Low） | 6 | 4 | 2 | L3 已确认、L5 轻微 | +| **合计** | **42** | **30 修复** | **12 确认** | **0 遗漏** | + +--- + +## 二、修复详情 + +### 🔴 严重（Critical） + +| # | 问题 | 修复方式 | 文件 | +|---|------|---------|------| +| **C1** | OSS accessKeySecret 明文返回 | 返回时将 accessKeySecret 替换为 `****` | `soul-api/internal/handler/db.go` | +| **C2+C3+H8** | payment.js 错误路径/调用不存在方法/未被引用 | 文件已在先前版本删除，无需修复 | ~~`utils/payment.js`~~ | +| **C4** | 找伙伴跳转 `pages/catalog/catalog` 不存在 | 改为 `pages/chapters/chapters` | `miniprogram/pages/match/match.js` | +| **C5** | `wx.getUserProfile()` 已废弃 | 替换为 `onChooseAvatar` + `open-type="chooseAvatar"` | `miniprogram/pages/settings/settings.js` | +| **C6+C7** | ES Module `export default` 问题 | 已在先前修复（`module.exports`） | `utils/chapterAccessManager.js`、`readingTracker.js` | +| **C8** | `import`/`require` 混用 | 统一为 `require()` | `miniprogram/pages/read/read.js` | +| **C9** | `import` 语法问题 | 统一为 `require()` | `miniprogram/pages/vip/vip.js` | +| **C10** | 管理端无登录验证 | 已在先前修复（AdminLayout token 检查 + API 校验） | `soul-admin/src/layouts/AdminLayout.tsx` | +| **C11** | stats API 免费章节数不一致 | `BookStats` 增加 `freeChapters` 字段，合并 system_config 和 is_free 计数 | `soul-api/internal/handler/book.go` | + +### 🟠 高（High） + +| # | 问题 | 修复方式 | 文件 | +|---|------|---------|------| +| **H1** | 废弃 Canvas API `wx.createCanvasContext()` | 迁移至 Canvas 2D API（`type="2d"` + `getContext('2d')`） | `read.js` + `read.wxml` | +| **H2+H3** | baseUrl/appId/mchId 硬编码 | appId/mchId 已抽为常量；baseUrl 通过注释标识切换；totalSections 从 API 动态加载 | `miniprogram/app.js` | +| **H4** | 匹配 API 失败伪装成功 | 改为 `wx.showToast` 显示真实错误 | `match.js` | +| **H5** | 生产环境残留测试模式购买 | 删除测试模式购买弹窗，改为失败提示 | `match.js` | +| **H6** | 客服微信号 `28533368` 硬编码 | 提取到 `app.globalData.serviceWechat`，read.js 引用全局配置 | `app.js` + `read.js` | +| **H7** | `goToMatch()` 重复定义 | 已在先前修复（仅保留一处） | `my.js` | +| **H9** | 仪表盘新用户手机号显示 `-` | 改为"未绑定手机" | `DashboardPage.tsx` | +| **H10** | 分类标签点击统计无数据 | 数据源依赖埋点，接口正常，非代码问题 | — | +| **H11** | admin/chapters 分页参数被忽略 | 已实现分页（page/pageSize/total） | `admin_chapters.go` | +| **H12** | admin/users 返回管理员 | 设计意图：管理员走 `/api/admin/users`，普通用户走 `/api/db/users` | — | +| **H13** | persons 表空数据 | 数据依赖内容上传同步，非代码 bug | — | + +### 🟡 中（Medium） + +| # | 问题 | 修复方式 | 文件 | +|---|------|---------|------| +| **M1** | `totalSections: 62` 硬编码 | 默认值更新为 90；已有动态加载逻辑从 API 获取 | `app.js` | +| **M2-M5** | 多处硬编码（附录列表、章节标题映射、热门搜索、动态价格） | 保留当前兜底值，后续迭代配置化 | — | +| **M6** | referral.js ~28 处 `console.log` 未清理 | 全部移除，仅保留 `console.error` | `referral.js` | +| **M7** | `generateMockMatch()` 模拟数据残留 | 整个函数删除 | `match.js` | +| **M8** | data 对象末尾悬空逗号 | 修复语法 | `referral.js` | +| **M9** | Token 明文存 `wx.setStorageSync` | 小程序沙盒环境可接受 | — | +| **M10** | 订单内容截断无 hover 提示 | 添加 `title` 属性（tooltip） | `DashboardPage.tsx` | +| **M11** | 刷新按钮已简化 | 已用图标+文字 | `DashboardPage.tsx` | +| **M12** | 热度 Top20 零点击 | 数据量问题，reading_progress 记录待积累 | — | + +### 🟢 低（Low） + +| # | 问题 | 修复方式 | 文件 | +|---|------|---------|------| +| **L1** | `index.js:7` 调试日志 | 删除 `console.log` | `index.js` | +| **L2** | `mockLogin()` 废弃未删 | 删除整个函数 | `app.js` | +| **L3** | `loadLatestChapters()` 重复请求 | 函数已不存在（先前重构） | — | +| **L4** | 空 catch 块 | 已有 `console.warn` 输出 | `ruleEngine.js` | +| **L5** | 错误提示短暂可见 | 轻微 UI 问题，输入时自动清除 | `LoginPage.tsx` | +| **L6** | version 返回 `0.0.0` | 更新 `.env.production` 为 `1.0.0` | `.env.production` | + +--- + +## 三、代码验证 + +| 验证项 | 结果 | +|--------|------| +| Go `go vet ./...` | ✅ 零错误 | +| Go `go build ./...` | ✅ 编译通过 | +| TypeScript lint | ✅ 仅 3 个 tailwind 缩写建议（非错误） | +| 小程序语法（import/require 统一） | ✅ 全部统一为 CommonJS | +| Canvas API 迁移 | ✅ 已迁移至 Canvas 2D | + +--- + +## 四、修改文件清单 + +### soul-api（后端） +- `internal/handler/db.go` — C1: OSS 脱敏 +- `internal/handler/book.go` — C11: BookStats 增加 freeChapters +- `.env.production` — L6: 版本号 1.0.0 + +### soul-admin（管理端） +- `src/pages/dashboard/DashboardPage.tsx` — H9: 手机号显示 + M10: tooltip + +### miniprogram（小程序） +- `app.js` — M1: totalSections 90 + H6: serviceWechat + L2: 删 mockLogin +- `pages/match/match.js` — C4: 路径 + H4/H5: 移除伪装 + M7: 删 mock +- `pages/read/read.js` — C8: require + H1: Canvas 2D + H6: 客服配置化 +- `pages/read/read.wxml` — H1: canvas type="2d" +- `pages/vip/vip.js` — C9: require +- `pages/settings/settings.js` — C5: chooseAvatar +- `pages/referral/referral.js` — M6: 清理 console.log + M8: 悬空逗号 +- `pages/index/index.js` — L1: 清理 console.log + +--- + +## 五、部署检查清单 + +| 步骤 | 操作 | 状态 | +|------|------|------| +| 1 | `soul-api` 编译部署 | 已执行（2026-03-22，`soul-api/master.py`，SSH 重启已加固） | +| 2 | `soul-admin` 构建并上传 dist | 已执行（2026-03-22，`soul-admin/master.py` → `/www/wwwroot/self/soul-admin/dist`） | +| 3 | 小程序上传并提审 | 待执行 | +| 4 | 生产环境全页面验证 | 待执行（公网：`https://soulapi.quwanzhi.com/health`、`https://souladmin.quwanzhi.com/` 已抽检） | +| 5 | 截图归档 | 待执行 | + +--- + +## 六、核心功能链路验证清单 + +| 链路 | 验证点 | 代码状态 | +|------|--------|---------| +| 登录/注册 | wx.login + 手机号 + token | ✅ | +| 付费购买 | 权限→预支付→wx.requestPayment→同步→解锁 | ✅ | +| VIP 购买 | 状态查询→支付→权益同步 | ✅ | +| 钱包充值 | 选金额→下单→支付→确认→刷新 | ✅ | +| 分销/推广 | 邀请码→分享→绑定→收益→提现 | ✅ | +| 找伙伴/匹配 | 选类型→匹配→真实数据→跳转正确 | ✅ (修复 C4/H4/H5) | +| 搜索 | 关键词→API→结果→跳转 | ✅ | +| 阅读章节 | 多入口→权限→解析→进度→海报 | ✅ (修复 H1 Canvas) | +| 管理端鉴权 | token 检查→API 校验→未登录跳转 | ✅ (确认 C10) | +| OSS 配置 | 密钥脱敏返回 | ✅ (修复 C1) | + +--- + +## 七、小程序提审加固（2026-03-21 追加） + +| 项 | 说明 | +|----|------| +| 生产 API | `app.js` 默认 `https://soulapi.quwanzhi.com`；`release` 强制生产并清理误存 `apiBaseUrl` | +| 开发页 | `pages/dev-login` 已从 `app.json` 移除；文件保留，本地需手动加路径 | +| 设置页 | 移除「切换账号（开发）」弹窗与 `/dev/login-as` 调用 | +| 隐私声明 | `requiredPrivateInfos` 增加 `getPhoneNumber` | +| 域名校验 | `project.config.json` 默认 `urlCheck: true`（private 可本地关） | +| 海报 Canvas | 弹层后 `nextTick` 再取节点；`getWindowInfo` 回退；`canvasToTempFilePath(..., this)` | + +详见 `开发文档/小程序提审自检清单_20260321.md`。 + +--- + +## 八、首页获客与文案（2026-03-22 追加） + +| 项 | 说明 | +|----|------| +| 超级个体 | 横滑首位固定「卡若」，点击 `onLinkKaruo`；API 列表剔除展示名为「卡若」「卡路」的重复项 | +| 顶部 Logo | 原英文 `S` 改为中文「派」 | +| 精选列表 | 去掉 `featured-id` 章节号展示，减少首屏「编号/英文感」 | +| 会员昵称 | `vip.go` `formatVipMember` 对 `name` 使用 `sanitizeDisplayOneLine` | +| 需求文档 | `开发文档/1、需求/修改/20260321 小程序.md` 品牌统一为「卡若」并标为已闭环 | diff --git a/开发文档/全链路深度测试与迭代报告_20260323.md b/开发文档/全链路深度测试与迭代报告_20260323.md new file mode 100644 index 00000000..7a6eca07 --- /dev/null +++ b/开发文档/全链路深度测试与迭代报告_20260323.md @@ -0,0 +1,163 @@ +# Soul 创业派对 · 全链路深度测试与迭代报告 + +**执行时间**：2026-03-23 19:07 +**测试范围**：管理端（soul-admin）+ 后端（soul-api）+ 小程序接口（/api/miniprogram/*）+ 数据库兼容性 +**目标**：逐页面、逐按钮、逐链路验证；输出可直接执行的优化迭代方案，并落地高优先修复。 + +--- + +## 1. 本轮覆盖结果 + +### 1.1 管理端页面与按钮深测（浏览器实测） + +已覆盖主菜单与关键子页（含按钮操作）： + +- `数据概览`：统计卡片、刷新、模块跳转。 +- `用户管理`：用户列表、获客列表、用户旅程、规则配置、超级个体列表；覆盖新增/编辑/删除/刷新/分页/筛选/详情。 +- `内容管理`：章节管理、新增章节、新增篇、编辑、付款记录入口。 +- `找伙伴`：数据统计、找伙伴、资源对接、导师预约、团队招募、刷新。 +- `推广中心`：概览、订单与代付、绑定管理、提现审核、推广设置。 +- `系统设置`：系统参数、作者详情、管理员、API 文档。 + +> 说明：本轮执行了“可点击项尽量全覆盖”。删除类操作按风险控制原则优先验证到“可触发”与“可取消”。 + +### 1.2 自动化回归（本地环境） + +执行环境：`SOUL_TEST_ENV=local` (`http://localhost:8080`) + +- 通过：`scripts/test/process/test_health.py` +- 通过：`scripts/test/web/test_admin_auth.py` +- 通过：`scripts/test/miniapp/test_config.py` +- 跳过：`scripts/test/miniapp/test_dev_login.py`（需要 dev 登录前提） +- 跳过：`scripts/test/process/test_backfill_persons_ckb_api_key.py`（依赖外部前置） +- 通过：`scripts/test/process/test_article_mention_ckb_flow.py`（修复后重跑） + +汇总：**10 passed, 2 skipped** + +### 1.3 管理端路由冒烟（admin/db 全路由） + +- 路由扫描总数：`116` +- 鉴权态冒烟：`Failures = 0` +- 未鉴权冒烟：仅 `POST /api/admin/logout` 非 401/403（属于可接受例外） + +--- + +## 2. 问题清单（按严重级） + +## P0（已修复） + +### P0-1 用户删除防呆不足（误删风险） +- 现象：原逻辑仅 `confirm()` 一次确认；自动化/脚本环境下 confirm 常被默认接受，误删风险高。 +- 影响：用户管理与管理员管理删除链路。 +- 修复： + - `soul-admin/src/pages/users/UsersPage.tsx` + - `soul-admin/src/pages/admin-users/AdminUsersPage.tsx` + - 新增二次校验：确认后要求输入“删除”才执行删除。 + +## P1（已修复） + +### P1-1 系统设置-管理员页面加载失败 +- 现象：管理端请求 `/api/admin/admin-users`，后端实际路由为 `/api/admin/users`。 +- 影响：管理员列表、增删改全部不可用。 +- 修复： + - `soul-admin/src/pages/admin-users/AdminUsersPage.tsx` + - API 路径统一改为 `/api/admin/users`（GET/POST/PUT/DELETE）。 + +### P1-2 persons 表结构漂移导致流程失败 +- 现象：`/api/db/persons` 返回 `Unknown column 'is_pinned' in 'field list'`，导致 `@人物 -> 自动建人 -> 获客计划` 流程回归失败。 +- 根因：历史库在 `persons` 自动迁移阶段遭遇旧索引冲突，新增列未补齐。 +- 修复： + - `soul-api/internal/database/database.go` + - 增加 `ensurePersonSchema()`：用 GORM `HasColumn/HasIndex` 做启动自愈（兼容低版本 MySQL）。 + - `soul-api/scripts/add-persons-pin-and-source.sql` + - 增加幂等 SQL（信息架构检测 + 动态执行）。 + - 修复后验证：`test_article_mention_ckb_flow.py` **5/5 通过**。 + +## P2（待迭代） + +- 页面切换存在短暂空白/加载抖动（找伙伴、推广中心、系统设置部分子页）。 +- 管理端构建体积偏大（主 chunk > 500KB），存在首屏与切页性能优化空间。 +- 部分列表仍有可读性与操作反馈可优化点（批量操作成功/失败反馈一致性）。 + +## P2（本轮已闭环 · 20260323 需求续） + +- **首页超级个体**：去掉「获客入口」副标题与跳转；无头像会员不再被 `vipMemberShowcaseOK` 过滤，可与 MBTI 映射头像组合展示。 +- **行为轨迹中文**：扩展 `userTrackActionLabelCN`；`UserTrackGet` / `DBUserTracksList` 输出 `module` + `moduleLabel`（中文位置）；Webhook 摘要 `GetUserRecentTracks` 使用中文模块位。 +- **管理端用户详情**：头部去重（OpenID/库内手机等迁入「用户信息」Tab 折叠区）；旅程列表展示 `moduleLabel`，长 ID 类 target 默认隐藏。 +- **规则配置列表**：描述仍为折叠，摘要行改为「字数提示」避免整段摊开。 +- **我的页**：统计行在上、名片/VIP 按钮在下，避免遮挡；推荐好友数以 `/api/miniprogram/earnings` 为准（初始 0 待收益接口覆盖）；点击昵称进入 `profile-show` 再在右上角编辑（编辑收进名片流）。 +- **Webhook 频次**：留资推送仍按「同一用户自然日仅首条 webhook」去重（`webhookShouldSkip`），与需求一致。 + +--- + +## 3. 本轮已落地代码变更 + +### 前端（soul-admin） +- `src/pages/admin-users/AdminUsersPage.tsx` + - 修复管理员接口路径错误。 + - 删除操作增加“输入删除”二次确认。 +- `src/pages/users/UsersPage.tsx` + - 用户删除、规则删除增加“输入删除”二次确认。 + +### 后端（soul-api） +- `internal/database/database.go` + - 增加 `ensurePersonSchema()`，启动时自愈补齐 `persons.is_pinned`、`persons.person_source`、`idx_persons_is_pinned`。 +- `scripts/add-persons-pin-and-source.sql` + - 新增兼容型幂等迁移脚本（适配不支持 `IF NOT EXISTS` 的 MySQL）。 + +### 测试脚本（scripts/test） +- `scripts/test/web/admin_routes_smoke.py` +- `scripts/test/web/admin_routes_smoke_authless.py` + - 去除硬编码 Windows 路径，改为自动定位当前仓库 `soul-api/internal/router/router.go`。 + +### 20260323 需求续（小程序 + 管理端 + API） +- `miniprogram/pages/index/index.wxml` / `index.js`：移除超级个体区「获客入口」。 +- `miniprogram/pages/my/my.wxml` / `my.wxss` / `my.js`：名片/VIP 下移；推荐数以收益接口为准；昵称 → 个人资料名片页。 +- `soul-api/internal/handler/vip.go`：`vipMemberShowcaseOK` 不再要求头像 URL。 +- `soul-api/internal/handler/user.go`：轨迹中文动作/模块位、`UserTrackGet` 附加字段、`GetUserRecentTracks` 中文模块。 +- `soul-admin/src/components/modules/user/UserDetailModal.tsx`：信息区结构优化 + 轨迹展示模块中文。 +- `soul-admin/src/pages/users/UsersPage.tsx`：规则描述折叠摘要优化。 + +--- + +## 4. 前端/后端/数据库一体化优化迭代建议 + +## 4.1 前端优化（soul-admin + miniprogram） +- 管理端按路由做代码分包（`React.lazy + Suspense`），优先拆分 `UsersPage`、`ContentPage`、`DistributionPage`。 +- 所有破坏性操作统一接入“二次确认组件”（替代散落的 `confirm/prompt`）。 +- 用户旅程与行为轨迹统一中文事件字典（避免中英混杂），并复用到导出/群播文案。 +- 小程序 `app.json` 的 `pages/dev-login/dev-login` 建议通过构建变量控制（dev 包含、release 排除），防止提审干扰。 + +## 4.2 后端优化（soul-api） +- 将“历史库兼容补丁”抽成统一 `schema ensure` 模块，覆盖 `users/persons/system_config` 高频变更表。 +- 对 `POST /api/admin/logout` 增加鉴权前置（未登录返回 401），与 authless 预期一致。 +- 管理端高频列表接口统一增加 `request_id` 与慢查询日志标签，便于排查“加载失败/慢响应”。 + +## 4.3 数据库优化 +- 建议补建/巡检以下索引： + - `persons(is_pinned)`（本轮已补） + - `user_tracks(user_id, created_at)`（旅程时间线） + - `orders(user_id, created_at, status)`（用户漏斗/支付链路） +- 建议建立“启动前 schema 巡检脚本”，在部署阶段提前阻断“字段缺失后线上才报错”。 + +--- + +## 5. 下一阶段执行计划（可直接开工） + +1. **P0/P1 回归闭环（今日）** + - 管理端删除链路二次确认回归 + - 管理员页 CRUD 全链路回归 + - persons 提及链路 + 获客计划联调回归 +2. **P2 性能迭代（本周）** + - 管理端路由分包 + - 大列表分页与筛选接口响应压测 +3. **产品体验优化（本周）** + - 用户旅程中文事件标准化 + - 页面 loading 骨架屏与空状态统一 + +--- + +## 6. 本轮结论 + +本轮完成了“全站深测 + 关键故障修复 + 一体化优化方案输出”。 +当前系统可用性已显著提升，阻断级问题已清理，剩余主要是性能与体验的系统性优化。 diff --git a/开发文档/列表标准与角色分工.md b/开发文档/列表标准与角色分工.md new file mode 100644 index 00000000..75bc3ddf --- /dev/null +++ b/开发文档/列表标准与角色分工.md @@ -0,0 +1,111 @@ +# Soul 创业派对 - 列表标准与角色分工 + +> 供管理端开发者、API 开发者参考。基于 2026-02 列表缺陷排查经验归纳。 +> 更新日期：2026-02-25 + +--- + +## 一、标准列表应具备的能力 + +| 能力 | 说明 | 优先级 | +|------|------|--------| +| **搜索** | 关键词模糊搜索，建议 300ms 防抖 | 高 | +| **筛选** | 状态/类型/时间范围等 | 高 | +| **刷新** | 手动重新加载 | 高 | +| **分页** | 上一页/下一页、页码、每页条数（后端支持时） | 高 | +| **加载状态** | loading 或骨架屏 | 高 | +| **空状态** | 无数据时的提示 | 高 | +| **错误提示** | 加载失败时展示可关闭的提示条 | 高 | +| **排序** | 列头点击排序（可选） | 中 | +| **导出** | CSV/Excel（可选） | 中 | +| **批量操作** | 勾选多行后批量处理（可选） | 低 | + +--- + +## 二、角色分工 + +### 2.1 管理端开发者（soul-admin） + +**职责**：实现列表页面的交互与展示，对接 soul-api 的管理端接口。 + +**必做**： +- 搜索：使用 `useDebounce` 对输入做 300ms 防抖 +- 筛选：按业务提供下拉/按钮筛选 +- 刷新：提供刷新按钮，加载时禁用并显示 loading +- 加载状态：请求中显示 loading +- 空状态：无数据时显示友好提示 +- 错误提示：catch 后设置 error 状态，页面顶部展示可关闭的错误条（红底） + +**可选**： +- 导出：前端基于当前筛选结果生成 CSV（无需后端支持） +- 排序：前端内存排序或后端支持时传 sort 参数 + +**禁止**： +- 不得调用 `/api/miniprogram/*` +- 不得用原生 `alert`/`confirm` 替代错误提示（应使用页面内错误条或 Dialog） + +**参考**：`.cursor/skills/SKILL-管理端开发.md`、`soul-admin-boundary.mdc` + +--- + +### 2.2 API 开发者（soul-api） + +**职责**：为管理端列表提供分页、筛选、排序等能力。 + +**列表接口建议**： +- 分页：支持 `page`、`pageSize` 查询参数，返回 `total`、`records`/`list` +- 筛选：支持 `status`、`matchType`、`startDate`、`endDate` 等 +- 排序：支持 `sortBy`、`sortOrder`（asc/desc） + +**响应格式**： +```json +{ + "success": true, + "records": [...], + "total": 100, + "page": 1, + "pageSize": 10 +} +``` + +**错误**：失败时返回 `{ "success": false, "error": "..." }`，管理端据此展示错误条。 + +**参考**：`.cursor/skills/SKILL-API开发.md`、`soul-api.mdc` + +--- + +## 三、已补全项（2026-02-25） + +| 页面 | 补全内容 | +|------|----------| +| 用户管理 | 错误提示、搜索防抖、**分页、每页条数、VIP 筛选** | +| 订单管理 | 错误提示、刷新、导出 CSV、搜索防抖、**分页、每页条数、后端搜索** | +| 匹配记录 | 错误提示、**每页条数选择** | +| 分账提现 | 错误提示、**分页、每页条数** | +| 交易中心 | 错误提示、**分页（订单/绑定/提现子列表）** | +| 章节管理 | 错误提示、刷新 | + +--- + +## 四、后端分页支持（已实现） + +| 接口 | 分页参数 | 筛选/搜索 | +|------|----------|-----------| +| GET /api/db/users | page, pageSize | search, vip | +| GET /api/orders | page, pageSize | status, search | +| GET /api/admin/withdrawals | page, pageSize | status | +| GET /api/db/distribution | page, pageSize | status | +| GET /api/db/match-records | page, pageSize | matchType | + +--- + +## 五、检查清单（管理端新增列表时） + +- [ ] 分页（后端支持时接入 page、pageSize、total） +- [ ] 搜索有防抖（300ms） +- [ ] 有刷新按钮 +- [ ] 加载中显示 loading +- [ ] 无数据时显示空状态 +- [ ] 加载失败时展示错误条（可关闭） +- [ ] 仅调用 `/api/admin/*` 或 `/api/db/*` +- [ ] 不使用原生 alert 做错误提示 diff --git a/开发文档/小程序功能与管理端配置补齐分析.md b/开发文档/小程序功能与管理端配置补齐分析.md new file mode 100644 index 00000000..0e5f6786 --- /dev/null +++ b/开发文档/小程序功能与管理端配置补齐分析.md @@ -0,0 +1,168 @@ +# 小程序功能与管理端配置补齐分析 + +> 基于 miniprogram 功能分析，梳理需管理端补齐的配置与功能。 +> 更新日期：2026-02-25 +> **2026-02-25 已补齐**：mp_config 管理端、网站配置持久化、支付/二维码 POST、小程序 config 读取 + +--- + +## 一、小程序配置来源总览 + +| 配置类型 | 来源 | 管理端入口 | 状态 | +|----------|------|------------|------| +| 免费章节 | system_config.free_chapters | 系统设置 | ✅ 已有 | +| 价格 (section/fullbook) | chapter_config / site_settings | 系统设置 | ✅ 已有 | +| 功能开关 (match/referral/search/about) | feature_config | 系统设置 | ✅ 已有 | +| 找伙伴配置 | match_config | 找伙伴配置页 | ✅ 已有 | +| 推广/分销 | referral_config | 推广设置 | ✅ 已有 | +| 小程序专用 (mp_config) | mp_config | 系统设置 → 小程序配置 | ✅ 已补齐 | +| 订阅消息模板 ID | mp_config 或 app.js 兜底 | 系统设置 → 小程序配置 | ✅ 已补齐 | +| 微信支付商户号 | mp_config 或 app.js 兜底 | 系统设置 → 小程序配置 | ✅ 已补齐 | +| API 地址 (baseUrl) | app.js 硬编码 | 发版时改 baseUrl | 已移除配置 | +| 网站/站点配置 | site_config, page_config | 网站配置 | ✅ 已持久化 | + +--- + +## 二、小程序功能模块与配置依赖 + +### 2.1 核心配置接口：`GET /api/miniprogram/config` + +**返回字段**（来自 GetPublicDBConfig）： + +| 字段 | 说明 | 管理端对应 | +|------|------|------------| +| freeChapters | 免费章节 ID 列表 | 系统设置 → 免费章节 | +| prices | { section, fullbook } | 系统设置 → 价格设置 | +| features | matchEnabled, referralEnabled, searchEnabled, aboutEnabled | 系统设置 → 功能开关 | +| mpConfig | appId, apiDomain, buyerDiscount, referralBindDays, minWithdraw | **无管理端** | +| userDiscount | 好友购买优惠 % | 推广设置 | + +### 2.2 找伙伴配置：`GET /api/miniprogram/match/config` + +| 字段 | 说明 | 管理端对应 | +|------|------|------------| +| matchTypes | 匹配类型列表 | 找伙伴配置页 | +| freeMatchLimit | 每日免费匹配次数 | 找伙伴配置页 | +| matchPrice | 单次匹配价格(元) | 找伙伴配置页 | +| settings | enableFreeMatches, enablePaidMatches, maxMatchesPerDay | 找伙伴配置页 | + +### 2.3 小程序 app.js 硬编码项 + +```javascript +// 当前硬编码，无法通过管理端修改 +baseUrl: 'http://localhost:8080', // 开发/生产需改代码 +appId: 'wxb8bbb2b10dec74aa', +withdrawSubscribeTmplId: 'u3MbZGPRkrZIk-...', // 提现订阅消息模板 +mchId: '1318592501', // 微信支付商户号 +``` + +--- + +## 三、管理端需补齐项（按优先级） + +### P0 - 必须补齐 + +| 项 | 说明 | 建议方案 | +|----|------|----------| +| **小程序专用配置 (mp_config)** | appId、apiDomain、minWithdraw 等，小程序从 config 读取 | 在「系统设置」或新建「小程序配置」卡片，支持编辑并写入 system_config.mp_config | +| **订阅消息模板 ID** | 提现申请需用户授权订阅，模板 ID 现硬编码 | 管理端增加「提现订阅模板 ID」配置，写入 mp_config 或单独 key；小程序启动时从 config 拉取 | +| **API 地址 (baseUrl)** | 开发/生产切换需改 app.js | 方案 A：从 mp_config.apiDomain 下发，小程序优先用接口返回值；方案 B：保留硬编码，仅文档说明切换方式 | + +### P1 - 建议补齐 + +| 项 | 说明 | 建议方案 | +|----|------|----------| +| **微信支付商户号** | 支付回调、对账依赖 mchId，现硬编码 | 管理端「支付配置」或「小程序配置」增加 mchId 字段；后端从配置读取，小程序可不改（支付由后端发起） | +| **网站配置持久化** | SitePage 当前保存仅前端状态，未调用后端 | 对接 POST /api/db/config，按 key 保存 site_config、page_config、menu_config | +| **支付/二维码配置持久化** | PaymentPage、QRCodesPage 使用 POST /api/config | soul-api 无 POST /api/config，需新增或改为 POST /api/db/config { key, value } | + +### P2 - 可选优化 + +| 项 | 说明 | 建议方案 | +|----|------|----------| +| **referral_config 的 withdrawFee** | 文档有提现手续费，ReferralSettingsPage 未展示 | 若业务需要，在推广设置页增加「提现手续费」字段 | +| **主题色/品牌色** | app.js theme 硬编码 | 若需多端统一，可从 site_config 或 mp_config 下发 | + +--- + +## 四、配置与 system_config 键名映射 + +| system_config.config_key | 管理端页面 | 说明 | +|--------------------------|------------|------| +| free_chapters | 系统设置 | 免费章节 ID 数组 | +| feature_config | 系统设置 | 功能开关对象 | +| site_settings | 系统设置 | 价格、作者信息 | +| chapter_config | (可选) | 合并 freeChapters + prices，GetPublicDBConfig 优先用 | +| match_config | 找伙伴配置 | 匹配类型、免费次数、价格 | +| referral_config | 推广设置 | 分销比例、提现门槛、绑定期等 | +| mp_config | **待新增** | 小程序专用：appId, apiDomain, withdrawSubscribeTmplId, mchId 等 | +| site_config | 网站配置 | 站点名称、logo 等（需持久化） | +| page_config | 网站配置 | 页面标题（需持久化） | +| menu_config | 网站配置 | 菜单开关（需持久化） | +| payment_methods | 支付配置 | 微信/支付宝活码等（需确认 POST 接口） | +| live_qr_codes | 二维码管理 | 群活码（需确认 POST 接口） | + +--- + +## 五、接口与数据流检查 + +### 5.1 管理端调用与后端支持 + +| 管理端页面 | 调用 | 后端支持 | 备注 | +|------------|------|----------|------| +| 系统设置 | GET/POST /api/admin/settings | ✅ | 写入 free_chapters, feature_config, site_settings | +| 推广设置 | GET/POST /api/admin/referral-settings | ✅ | 写入 referral_config | +| 找伙伴配置 | GET /api/db/config/full?key=match_config | ✅ | 需 AdminAuth | +| 找伙伴配置 | POST /api/db/config | ✅ | body: { key: 'match_config', value: {...} } | +| 支付配置 | GET/POST /api/config | ⚠️ | GET 有，POST 无；需新增或改用 db/config | +| 网站配置 | GET /api/config | ⚠️ | GET 有，保存未对接 | +| 二维码管理 | GET/POST /api/config | ⚠️ | 同上 | + +### 5.2 小程序读取链 + +``` +小程序 onLoad / custom-tab-bar + → GET /api/miniprogram/config + → GetPublicDBConfig + → 读取 system_config: chapter_config, free_chapters, feature_config, mp_config, referral_config + → 返回 freeChapters, prices, features, mpConfig, userDiscount +``` + +--- + +## 六、实施建议（管理端开发任务） + +### 任务 1：新增「小程序配置」区块（P0） + +- **位置**：系统设置页新增卡片，或独立「小程序配置」页 +- **字段**： + - API 域名 (apiDomain)：如 `https://soulapi.quwanzhi.com` + - 小程序 AppID (appId)：如 `wxb8bbb2b10dec74aa` + - 提现订阅模板 ID (withdrawSubscribeTmplId) + - 微信支付商户号 (mchId)（可选，后端也可用 env） + - 最低提现金额 (minWithdraw)（可与 referral_config 同步） +- **存储**：POST /api/admin/settings 扩展，或 POST /api/db/config { key: 'mp_config', value: {...} } +- **小程序**：app.js 启动时请求 config，若 mp_config 存在则覆盖 baseUrl；withdrawSubscribeTmplId 从 config 取 + +### 任务 2：网站配置持久化（P1） + +- SitePage 保存时调用 POST /api/db/config，按 key 分别保存 site_config、page_config、menu_config +- 或扩展 AdminSettingsPost 支持 site_config 等 + +### 任务 3：支付/二维码配置接口（P1） + +- 方案 A：新增 POST /api/admin/config，支持 payment_methods、live_qr_codes 等 key +- 方案 B：PaymentPage、QRCodesPage 改为调用 POST /api/db/config，body: { key, value } + +--- + +## 七、附录：小程序页面与配置使用 + +| 页面 | 使用的配置 | 接口 | +|------|------------|------| +| custom-tab-bar | features.matchEnabled | GET /api/miniprogram/config | +| 阅读 read | freeChapters, prices | GET /api/miniprogram/config (chapterAccessManager) | +| 找伙伴 match | matchTypes, freeMatchLimit, matchPrice | GET /api/miniprogram/match/config | +| 我的 my | features, 收益/提现规则 | GET /api/miniprogram/config, referral/data | +| 分销 referral | shareRate, minWithdraw, bindingDays | GET /api/miniprogram/referral/data | +| 支付流程 | mchId (后端), openId | app.js 硬编码 + 后端 env | diff --git a/开发文档/小程序提审自检清单_20260321.md b/开发文档/小程序提审自检清单_20260321.md new file mode 100644 index 00000000..419c3c15 --- /dev/null +++ b/开发文档/小程序提审自检清单_20260321.md @@ -0,0 +1,35 @@ +# 小程序提审自检清单（2026-03-21） + +上传审核前在开发者工具内逐项勾选；本清单与当前代码约定一致。 + +## 一、环境与域名 + +- [ ] **正式版 `envVersion=release`**：`app.js` 的 `initApiBaseUrl()` 会强制 `baseUrl=https://soulapi.quwanzhi.com`，并清除本地误存的非生产 `apiBaseUrl`。 +- [ ] **微信公众平台**：request 合法域名、socket 合法域名、uploadFile/downloadFile 合法域名已包含生产 API 与 OSS/CDN（含 `at.alicdn.com` 字体若使用）。 +- [ ] **`project.config.json`**：`urlCheck: true`（仓库默认）；本地调试可用 `project.private.config.json` 覆盖为 `false`，**勿把 private 里长期关校验的配置提交为唯一来源**。 + +## 二、隐私与权限声明 + +- [ ] `app.json` 已配置 `__usePrivacyCheck__: true`。`requiredPrivateInfos` 仅允许位置类（`chooseAddress` 等）；**勿**写入 `getPhoneNumber`（新版开发者工具/校验会拒绝上传）。手机号能力靠 `