fnvtk/soul-yongping
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

sync: 2026-03-19 14:54

Browse Source
This commit is contained in:
卡若
2026-03-19 14:54:01 +08:00
parent 7f5a75e489
commit 01d700aab2
24 changed files with 164 additions and 1842 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
.DS_Store vendored
View File

Binary file not shown.

55
.cursor/scripts/README-gitea-sync.md Normal file
View File

@@ -0,0 +1,55 @@
# 与 Gitea（192.168.1.201）同步
## 远程
- **gitea-local**：`http://192.168.1.201:3000/fnvtk/soul-yongping.git`（拉取 + 推送）
## 手动同步
```bash
./.cursor/scripts/gitea-sync.sh
```
## 每 10 分钟自动同步（macOS launchd）
- 已安装：`~/Library/LaunchAgents/com.soul.yongping.gitea-sync.plist`
- 每 10 分钟执行一次，登录后自动加载
**启用：**
```bash
launchctl load ~/Library/LaunchAgents/com.soul.yongping.gitea-sync.plist
```
**停用：**
```bash
launchctl unload ~/Library/LaunchAgents/com.soul.yongping.gitea-sync.plist
```
**查看是否在跑：**
```bash
launchctl list | grep com.soul.yongping.gitea-sync
```
## 认证（192.168.1.201 需登录时）
若 push/pull 需要账号密码，定时任务无法弹窗，请把凭证写进 remote URL（勿提交到仓库）：
```bash
git remote set-url gitea-local 'http://用户名:token或密码@192.168.1.201:3000/fnvtk/soul-yongping.git'
```
或用系统钥匙串：
```bash
git config --global credential.helper osxkeychain
# 然后手动执行一次 gitea-sync.sh，输入一次账号密码，之后由钥匙串记住
```
## 日志
- 脚本内部：`.cursor/scripts/gitea-sync.log`
- launchd 标准输出：`.cursor/scripts/gitea-sync-launchd.log`
- launchd 错误：`.cursor/scripts/gitea-sync-launchd.err.log`

1
.cursor/scripts/gitea-sync-launchd.err.log Normal file
View File

@@ -0,0 +1 @@
/bin/bash: /Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验-永平/.cursor/scripts/gitea-sync.sh: Operation not permitted

0
.cursor/scripts/gitea-sync-launchd.log Normal file
View File

6
.cursor/scripts/gitea-sync.log Normal file
View File

@@ -0,0 +1,6 @@
[2026-03-19 14:54:01] --- sync start (branch=devlop, remote=gitea-local) ---
From http://192.168.1.201:3000/fnvtk/soul-yongping
* [new branch] devlop -> gitea-local/devlop
* [new branch] main -> gitea-local/main
error: cannot pull with rebase: You have unstaged changes.
error: Please commit or stash them.

43
.cursor/scripts/gitea-sync.sh Executable file
View File

@@ -0,0 +1,43 @@
#!/usr/bin/env bash
# 与 Gitea（192.168.1.201）双向同步：先拉取，有本地变更则提交并推送
# 可手动执行，也可由 launchd 每 10 分钟执行
set -e
REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
REMOTE="gitea-local"
LOG_FILE="$REPO_ROOT/.cursor/scripts/gitea-sync.log"
cd "$REPO_ROOT"
BRANCH=$(git rev-parse --abbrev-ref HEAD)
log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" | tee -a "$LOG_FILE"; }
log "--- sync start (branch=$BRANCH, remote=$REMOTE) ---"
# 1. 拉取远程更新（若远程无此分支则仅 fetch）
git fetch "$REMOTE" 2>&1 | tee -a "$LOG_FILE" || true
if git ls-remote --exit-code --heads "$REMOTE" "$BRANCH" &>/dev/null; then
git pull "$REMOTE" "$BRANCH" --no-edit 2>&1 | tee -a "$LOG_FILE" || log "pull 失败或冲突，继续尝试推送本地变更"
else
log "远程无 $REMOTE/$BRANCH，仅 fetch"
fi
# 2. 若有本地未提交变更，则提交并推送
STATUS=$(git status -s)
if [ -n "$STATUS" ]; then
git add -A
git commit -m "sync: $(date '+%Y-%m-%d %H:%M')" 2>&1 | tee -a "$LOG_FILE" || log "commit failed (nothing to commit or conflict)"
git push "$REMOTE" "$BRANCH" 2>&1 | tee -a "$LOG_FILE" || log "push failed"
else
# 若有已提交但未推送的提交，也推送（仅当远程有此分支且本地比远程多提交时）
if git ls-remote --exit-code --heads "$REMOTE" "$BRANCH" &>/dev/null; then
AHEAD=$(git rev-list "refs/remotes/${REMOTE}/${BRANCH}"..HEAD --count 2>/dev/null || echo 0)
if [ "${AHEAD:-0}" -gt 0 ]; then
git push "$REMOTE" "$BRANCH" 2>&1 | tee -a "$LOG_FILE" || log "push failed"
fi
else
git push -u "$REMOTE" "$BRANCH" 2>&1 | tee -a "$LOG_FILE" || log "push (new branch) failed"
fi
fi
log "--- sync end ---"

59
project.config.json Normal file
View File

@@ -0,0 +1,59 @@
{
"compileType": "miniprogram",
"miniprogramRoot": "miniprogram/",
"description": "Soul创业派对 - 来自派对房的真实商业故事",
"appid": "wxb8bbb2b10dec74aa",
"setting": {
"urlCheck": false,
"es6": true,
"enhance": true,
"postcss": true,
"preloadBackgroundData": false,
"minified": true,
"newFeature": true,
"coverView": true,
"nodeModules": false,
"autoAudits": false,
"showShadowRootInWxmlPanel": true,
"scopeDataCheck": false,
"uglifyFileName": false,
"checkInvalidKey": true,
"checkSiteMap": true,
"uploadWithSourceMap": true,
"compileHotReLoad": true,
"lazyloadPlaceholderEnable": false,
"useMultiFrameRuntime": true,
"babelSetting": {
"ignore": [],
"disablePlugins": [],
"outputPath": ""
},
"enableEngineNative": false,
"useIsolateContext": true,
"userConfirmedBundleSwitch": false,
"packNpmManually": false,
"packNpmRelationList": [],
"minifyWXSS": true,
"disableUseStrict": false,
"minifyWXML": true,
"showES6CompileOption": false,
"useCompilerPlugins": false,
"ignoreUploadUnusedFiles": true,
"compileWorklet": false,
"localPlugins": false,
"condition": false,
"swc": false,
"disableSWC": true
},
"condition": {},
"editorSetting": {
"tabIndent": "insertSpaces",
"tabSize": 2
},
"simulatorPluginLibVersion": {},
"packOptions": {
"ignore": [],
"include": []
}
}

158
开发文档/1、需求/文章详情-阅读页线框图.md
View File

@@ -1,158 +0,0 @@
# 文章详情（阅读页）线框图
> Soul 创业派对 - 小程序 `pages/read/read` 界面结构
---
## 一、完整内容态（免费/已购买）
```
┌─────────────────────────────────────────┐
│ ████████████░░░░░░░░░░ 阅读进度 60% │ ← 顶部固定进度条
├─────────────────────────────────────────┤
│ ← 第 4 章 真实的行业 │ ← 导航栏
├─────────────────────────────────────────┤
│ [4] [免费] │ ← 章节元信息
│ 4.1 旅游号：30天10万粉的真实逻辑 │ ← 章节标题（可长按复制）
├─────────────────────────────────────────┤
│ │
│ 这是一段正文内容，文中包含 @卡若 和 │
│ #创业资源 可以点击。支持长按复制文字。 │ ← @ 高亮可点，# 金色可点
│ │
│ 第二段纯文本，无特殊标记。 │
│ │
│ ┌─────────────────────────────────┐ │ ← 图片（可点击全屏预览）
│ │ [ 插图 ] │ │
│ └─────────────────────────────────┘ │
│ │
├─────────────────────────────────────────┤
│ ┌──────────────┐ ┌──────────────────┐│
│ │ 上一篇 │ │ 下一篇 ││ ← 章节导航
│ │ 3.5 桶装水 │ │ 4.2 美业整合 → ││
│ └──────────────┘ └──────────────────┘│
│ │
│ [ 📣 分享到朋友圈 ] [ 🖼️ 生成海报 ] │ ← 操作区
└─────────────────────────────────────────┘
```
---
## 二、付费墙态（未登录）
```
┌─────────────────────────────────────────┐
│ ← 第 4 章 真实的行业 │
├─────────────────────────────────────────┤
│ 这是一段预览内容，显示前 50%... │
│ 第二段预览... │
│ │
│ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │ ← 渐变遮罩
│ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │
├─────────────────────────────────────────┤
│ 🔒 │
│ 登录后继续阅读 │
│ 已阅读50%，登录后查看完整内容 │
│ │
│ [ 立即登录 ] │
├─────────────────────────────────────────┤
│ [ 上一篇 ] [ 下一篇 → ] │
└─────────────────────────────────────────┘
```
---
## 三、付费墙态（已登录未购买）
```
┌─────────────────────────────────────────┐
│ （同上：预览内容 + 渐变遮罩） │
├─────────────────────────────────────────┤
│ 🔒 │
│ 解锁完整内容 │
│ 已阅读50%，购买后继续阅读 │
│ │
│ [ 购买本章 ¥1.0 ] │
│ [ ✨ 解锁全部 62 章 ¥9.9 省82% ] │ ← 购买≥3章才显示
│ │
│ 分享给好友一起学习，还能赚取佣金 │
├─────────────────────────────────────────┤
│ [ 上一篇 ] [ 下一篇 → ] │
└─────────────────────────────────────────┘
```
---
## 四、交互说明
| 元素 | 交互 |
|------|------|
| **@卡若** | 点击 → 确认弹窗「是否添加 @卡若？」→ 调 CKB 留资加好友 |
| **#创业资源** | 点击 → 按类型：内链跳转 / 外链复制 / 小程序唤醒 / CKB 加好友 |
| **正文/标题** | 长按 → 选中复制（user-select） |
| **图片** | 点击 → 全屏预览；长按 → 保存菜单 |
| **上一篇/下一篇** | 点击 → 切换章节 |
---
## 五、@ / # 三端数据流线框图
```mermaid
flowchart TB
subgraph 管理端["管理端 soul-admin"]
A1[链接人与事 Person]
A2[链接标签 LinkTag]
A3[RichEditor 编辑]
A4[autoLinkContent 转换]
A1 --> A3
A2 --> A3
A3 --> A4
A4 --> |"content HTML"| DB
end
subgraph 后端["后端 soul-api"]
DB[(chapters.content)]
API[GET /api/miniprogram/book/chapter]
CKB[POST /api/miniprogram/ckb/lead]
CFG[GET /api/miniprogram/config]
DB --> API
end
subgraph 小程序["小程序 miniprogram"]
B1[contentParser 解析]
B2[contentSegments 渲染]
B3[onMentionTap]
B4[onLinkTagTap]
API --> B1
B1 --> B2
B2 --> B3
B2 --> B4
B3 --> CKB
B4 --> |"内链"| Nav[wx.navigateTo]
B4 --> |"外链"| Clip[复制剪贴板]
B4 --> |"miniprogram"| MP[wx.navigateToMiniProgram]
CFG --> B4
end
```
---
## 六、数据流文字说明
```
管理端 ContentPage
→ 编辑插入 @[名称](token) / #标签
→ 保存 content（TipTap HTML）
后端 chapters.content
→ 原样存储、原样返回
小程序 contentParser
→ 解析 → contentSegments
→ WXML 渲染 text / mention / linkTag / image
用户点击 @
→ onMentionTap → POST /api/miniprogram/ckb/lead
用户点击 #
→ onLinkTagTap → 按 tagType 分支处理
```

82
开发文档/1、需求/链接人与事-所有同步需求.md
View File

@@ -1,82 +0,0 @@
# 链接人与事 — 所有同步需求汇总
> 整合自：链接人与事-存客宝同步-需求规划、实现方案、2026-03-16 文章编辑自动创建
---
## 一、同步场景总览
| 场景 | 触发 | 同步动作 | 状态 |
|------|------|----------|------|
| **创建 Person** | 管理端添加 / 文章 @某人 不存在时自动创建 | 调存客宝创建获客计划 → 落库 ckb_plan_id、ckb_api_key | ✅ 已实现 |
| **编辑 Person** | 管理端编辑弹窗保存 | 调存客宝更新计划 | 待实现 |
| **删除 Person** | 管理端删除 | 调存客宝删除计划 → 再删本地 | ✅ 已实现 |
| **文章 @某人 不存在** | 编辑文章输入 @新人物 并保存 | ensureMentionsAndTags → POST persons → 自动创建 + 同步存客宝 | ✅ 已实现 |
---
## 二、已实现同步
### 2.1 创建 Person 时同步存客宝
- **触发**：POST /api/db/persons（仅传 name 或完整表单）
- **流程**：生成 token → 调 ckbOpenCreatePlan（deviceGroups 未传时默认选名为 soul 的设备）→ 落库 person_id、token、name、ckb_api_key、ckb_plan_id
- **实现**：`soul-api/internal/handler/db_person.go`、`ckb_open.go`
### 2.2 删除 Person 时同步删存客宝
- **触发**：DELETE /api/db/persons?personId=xxx
- **流程**：若有 ckb_plan_id → 调 ckbOpenDeletePlan → 再删本地
- **实现**：`db_person.go` DBPersonDelete
### 2.3 文章 @某人 自动创建并同步
- **触发**：管理端保存文章，content 含 @新人物（persons 中不存在）
- **流程**：ensureMentionsAndTags 提取 @name → POST /api/db/persons {name} → 创建 Person + 存客宝计划
- **实现**：`soul-admin` ContentPage ensureMentionsAndTags；`db_person.go` 按 name 查找/创建
---
## 三、待实现同步
### 3.1 编辑 Person 时同步存客宝
- **触发**：管理端编辑 Person 后保存（PUT 逻辑，personId 已存在）
- **流程**：更新本地 persons → 若有 ckb_plan_id，调存客宝 PUT /v1/plan/update 同步 name、greeting、tips 等
- **参考**：`链接人与事-存客宝同步-需求规划.md` 4.2、7.1
---
## 四、配置与前置
| 配置 | 说明 |
|------|------|
| CKB_OPEN_API_KEY | 存客宝开放 API 密钥 |
| CKB_OPEN_ACCOUNT | 存客宝账号（鉴权） |
| 设备 | 创建计划时 deviceGroups 必填；未传时默认选 memo/nickname 含 "soul" 的设备 |
### 创建计划必填参数（2026-03-16）
| 参数 | 值 | 说明 |
|------|-----|------|
| planType | 1 | 必填 |
| sceneId | 9 | 必填 |
| scenario | 9 | 与 sceneId 一致 |
| status | 1 | 必填 |
---
## 五、mention 存储格式（2026-03-16）
| 规则 | 说明 |
|------|------|
| **data-label 必填** | TipTap Mention 仅从 `data-label` 解析显示名，缺则回退显示 `data-id`（token） |
| **ParseAutoLinkContent** | 输出 `data-type="mention"` 的 span 必须含 `data-label` |
| **已损坏内容** | span 内为 token 时，用 token 查 persons 取真实名字补回 data-label |
## 六、相关文档
- `链接人与事-存客宝同步-需求规划.md` — 原始需求与 API 约定
- `链接人与事-实现方案.md` — 实现清单
- `临时需求池/2026-03-16-文章编辑自动创建@和#.md` — 自动创建需求
- `开发文档/存客宝对接逻辑图.md` — 对接逻辑与参数约定

236
开发文档/全站测试报告_20260315.md
View File

@@ -1,236 +0,0 @@
# Soul 创业派对 · 全站测试报告
**测试日期**：2026-03-15
**测试范围**：管理端前端（20+ 页面） + 后端 API（35 端点） + 小程序代码审查（25 页面） + 数据库（25 张表）
**测试原则**：只检测不修改，不做任何部署
---
## 一、测试覆盖总览
| 测试维度 | 覆盖量 | 通过 | 问题 |
|---------|-------|------|------|
| 管理端页面（浏览器截图） | 20+ 页面/子Tab | 18 | 2 |
| API 端点测试 | 35 端点 | 29 | 6 |
| 小程序代码审查 | 25 页面 + 8 工具文件 | 核心流程完整 | 32 |
| 数据库检查 | 25 张表 | 数据一致 | 2 |
| **合计** | **全站** | — | **42 个问题** |
---
## 二、问题清单（按严重程度排序）
### 🔴 严重（Critical）— 必须修复 · 共 11 个
| # | 模块 | 问题 | 文件/位置 | 解决方案 |
|---|------|------|----------|---------|
| C1 | API/安全 | **OSS accessKeySecret 明文返回前端** | `db.go` AdminSettingsGet | 后端返回 ossConfig 时脱敏处理，accessKeySecret 返回 `****` |
| C2 | 小程序 | **payment.js API 路径全部错误**：使用不存在的 `app.globalData.apiBase` 和 `/payment/create` 等非标准路径 | `utils/payment.js` 全文件 | 若已不使用应删除；若要用需改为 `baseUrl` + `/api/miniprogram/*` |
| C3 | 小程序 | **payment.js 调用不存在的 `app.getUserInfo()`** | `utils/payment.js:188,201` | 改为 `app.globalData.userInfo` |
| C4 | 小程序 | **找伙伴跳转路径错误**：`pages/catalog/catalog` 不存在 | `pages/match/match.js:311` | 改为 `pages/chapters/chapters` |
| C5 | 小程序 | **`wx.getUserProfile()` 已废弃**（2022年后不可用） | `pages/settings/settings.js:251` | 改用 `<button open-type="chooseAvatar">` |
| C6 | 小程序 | **ES Module 语法与 CommonJS 混用**：`export default` 在小程序默认环境不支持 | `utils/chapterAccessManager.js:209` | 统一为 `module.exports` 或确认构建工具可转译 |
| C7 | 小程序 | **同上 ES Module 问题** | `utils/readingTracker.js:249` | 同 C6 |
| C8 | 小程序 | **import/require 混用** | `pages/read/read.js:16-17` | 统一模块导入方式 |
| C9 | 小程序 | **import 语法问题** | `pages/vip/vip.js:1` | 同 C8 |
| C10 | 管理端 | **首次访问无登录验证**：直接打开 / 跳转到仪表盘无需登录 | 前端路由守卫 | 添加路由守卫：未登录强制跳转 `/login` |
| C11 | 数据库 | **stats API 免费章节数不一致**：stats 返回 2，all-chapters 实际 3 个 `isFree=true` | `book.go` BookStats | 核查 `is_free` 字段查询条件 |
### 🟠 高（High）— 优先修复 · 共 13 个
| # | 模块 | 问题 | 文件/位置 | 解决方案 |
|---|------|------|----------|---------|
| H1 | 小程序 | **废弃 Canvas API**：`wx.createCanvasContext()` 将被移除 | `read.js:1377` | 迁移到 Canvas 2D 接口 |
| H2 | 小程序 | **baseUrl 硬编码生产环境 URL** | `app.js:11` | 通过环境变量或配置文件管理 |
| H3 | 小程序 | **appId/mchId 硬编码** | `app.js:17,22` | 移至配置文件或从 API 获取 |
| H4 | 小程序 | **匹配 API 失败时伪装成功**：显示 `joinSuccess: true` | `match.js:656-662` | 移除伪装逻辑，正确显示错误 |
| H5 | 小程序 | **生产环境残留测试模式购买逻辑** | `match.js:741-753` | 删除测试模式代码 |
| H6 | 小程序 | **客服微信号硬编码** | `read.js:1158,1207` | 从系统配置 API 获取 |
| H7 | 小程序 | **goToMatch() 方法重复定义**，后者覆盖前者 | `my.js:784,801` | 删除重复定义 |
| H8 | 小程序 | **payment.js 未被任何页面引用**，支付逻辑在 read.js 直接实现 | `utils/payment.js` | 删除无用文件或统一支付入口 |
| H9 | 管理端 | **仪表盘新注册用户列表用户名显示为"-"** | 仪表盘页面 | 改为显示昵称或手机号（脱敏） |
| H10 | 管理端 | **分类标签点击统计无数据**，提示"暂无点击数据" | 仪表盘页面 | 确认埋点数据源或改进空状态提示 |
| H11 | API | **admin/chapters 分页参数被忽略**：无论 pageSize 多大，返回结构不含分页数据 | `db_book.go` | 添加 page/pageSize 参数支持 |
| H12 | API | **admin/users 实际返回管理员列表**而非普通用户 | `db.go` | 确认是否需要独立的普通用户管理 API |
| H13 | 数据库 | **persons 表数据为空**（0条记录），但管理端"链接人与事"有展示 | 数据同步 | 检查 persons 数据来源和同步逻辑 |
### 🟡 中（Medium）— 建议修复 · 共 12 个
| # | 模块 | 问题 | 文件/位置 | 解决方案 |
|---|------|------|----------|---------|
| M1 | 小程序 | `totalSections: 62` 硬编码 | `app.js:32` | 从 API 获取 |
| M2 | 小程序 | `appendixList` 硬编码 3 个附录条目 | `chapters.js:31-35` | 从 API 获取 |
| M3 | 小程序 | `getSectionTitle()` 硬编码部分章节 ID→标题映射 | `read.js:351-366` | 从 API 获取 |
| M4 | 小程序 | 热门搜索关键词硬编码 | `search.js:17` | 从配置 API 获取 |
| M5 | 小程序 | `startDate = new Date('2025-01-01')` 动态价格逻辑硬编码 | `payment.js:163` | 若文件保留，改为配置驱动 |
| M6 | 小程序 | 大量 `console.log` 调试日志未清理 | `referral.js` 约50+行 | 生产环境前清理 |
| M7 | 小程序 | `generateMockMatch()` 模拟数据残留 | `match.js:470-496` | 删除模拟数据 |
| M8 | 小程序 | `data` 对象末尾悬空逗号 | `referral.js:68` | 修复语法 |
| M9 | 小程序 | Token 明文存储 `wx.setStorageSync` | `app.js:515` | 小程序环境可接受，建议加密存储 |
| M10 | 管理端 | 订单内容文字过长被截断，无 hover 提示 | 仪表盘最近订单 | 添加 tooltip 或点击查看详情 |
| M11 | 管理端 | 数据刷新按钮文字过长 | 仪表盘 | 简化为图标+tooltip |
| M12 | API | 热度 Top20 中有 8/20 条零点击数 | `/api/book/hot` | 检查 reading_progress 数据是否完整 |
### 🟢 低（Low）— 可优化 · 共 6 个
| # | 模块 | 问题 | 文件/位置 |
|---|------|------|----------|
| L1 | 小程序 | 文件顶部 console.log 调试输出 | `index.js:7` |
| L2 | 小程序 | `mockLogin()` 已废弃但未删除 | `app.js:600-603` |
| L3 | 小程序 | `loadLatestChapters()` 重复请求 `all-chapters` | `index.js:494` |
| L4 | 小程序 | `catch {}` 空 catch 块无日志 | `ruleEngine.js:45,53` |
| L5 | 管理端 | 错误提示在输入正确凭据后仍短暂可见 | 登录页 |
| L6 | API | `version` 返回 `0.0.0`，建议使用实际版本号 | `/health` |
---
## 三、核心功能流程评估
| 流程 | 状态 | 评估 |
|------|------|------|
| 登录/注册 | ✅ 完整 | wx.login + 手机号双通道，协议勾选，单页模式兜底 |
| 付费购买章节 | ✅ 完整 | 权限状态机→预支付→wx.requestPayment→同步→解锁 |
| VIP 购买 | ✅ 完整 | VIP 状态查询→支付→同步权益→刷新全局 |
| 钱包充值 | ✅ 完整 | 选金额→创建订单→支付→确认→刷新余额 |
| 分销/推广 | ✅ 完整 | 邀请码→分享带ref→绑定→收益→提现→微信零钱 |
| 找伙伴/匹配 | ⚠️ 有缺陷 | 路径错误(C4)、失败伪装成功(H4)、测试模式残留(H5) |
| 搜索 | ✅ 完整 | 关键词搜索→API 查询→结果展示→跳转阅读 |
| 阅读章节 | ✅ 完整 | 多入口(scene/mid/id)→权限判断→内容解析→进度追踪 |
---
## 四、管理端页面测试详情
### 已测试页面清单（全部截图）
| 模块 | 子页面/Tab | 状态 | 关键数据 |
|------|-----------|------|---------|
| 登录 | 登录页 | ✅ | 错误凭据有提示，正确登录跳转仪表盘 |
| 仪表盘 | 数据概览 | ✅ | 149用户, ¥2007.75收入, 29订单, 10.7%转化率 |
| 内容管理 | 章节管理 | ✅ | 8篇 · 90节内容 |
| 内容管理 | 内容排行榜 | ✅ | 90节排行，预览比例20% |
| 内容管理 | 内容搜索 | ✅ | 搜索框正常 |
| 内容管理 | 链接人与事 | ✅ | AI列表，token/位置/类型展示 |
| 内容管理 | 链接标签 | ✅ | 3个标签（卡若创业派对/碎片时间/神仙团队） |
| 用户管理 | 用户列表 | ✅ | 149位用户，筛选/搜索/分页正常 |
| 用户管理 | 用户旅程 | ✅ | 8阶段漏斗（149→4→12→10→14→0→0→0） |
| 找伙伴 | 数据统计 | ✅ | 总匹配63, 17用户, AI线索51 |
| 找伙伴 | 匹配记录 | ✅ | 63条记录 |
| 找伙伴 | 匹配池设置 | ✅ | VIP 6人, 完善资料 7人, 全部 13人 |
| 找伙伴 | 资源对接 | ✅ | 0条记录 |
| 找伙伴 | 导师管理 | ✅ | 1位导师（卡若），3种价格方案 |
| 找伙伴 | 团队招募 | ✅ | 4条记录 |
| 推广中心 | 数据概览 | ✅ | 累计: 1025点击, 41绑定, 2转化, ¥2007.75 |
| 推广中心 | 订单管理 | ✅ | 444条订单记录 |
| 推广中心 | 绑定管理 | ✅ | 41条绑定关系 |
| 推广中心 | 提现审核 | ✅ | 3条记录（含已拒绝/已完成） |
| 推广中心 | 推广设置 | ✅ | 好友收益/推广者收益/提现规则 |
| 系统设置 | 系统设置 | ✅ | 功能开关/价格/小程序/OSS均有配置 |
| 系统设置 | 作者详情 | ✅ | 基本信息/统计数据/亮点标签 |
| 系统设置 | 管理员 | ✅ | 1个管理员（admin/卡若/超级管理员） |
| 系统设置 | API文档 | ✅ | 完整的接口文档 |
---
## 五、API 端点测试详情
### 全部 35 端点测试结果
| 端点 | 状态码 | 数据 | 问题 |
|------|-------|------|------|
| GET /health | 200 | ok, version 0.0.0 | L6: version 未设置 |
| GET /api/config | 200 | 配置完整 | ✅ |
| GET /api/book/all-chapters | 200 | 90 条 | ✅ |
| GET /api/book/hot | 200 | 20 条 | M12: 8条零点击 |
| GET /api/book/recommended | 200 | 数据完整 | ✅ |
| GET /api/book/search?q=创业 | 200 | 20 条 | ✅ |
| GET /api/book/search?q= | 200 | 0 条 | ✅ 空搜索正确处理 |
| GET /api/book/search?q=xxx | 200 | 0 条 | ✅ 无结果正确处理 |
| GET /api/book/stats | 200 | 90章/2免费/209624字/149用户 | C11: 免费数量可能不准 |
| GET /api/miniprogram/config | 200 | 配置完整 | ✅ |
| GET /api/miniprogram/book/hot | 200 | 数据完整 | ✅ |
| GET /api/miniprogram/book/stats | 200 | 同 stats | ✅ |
| GET /api/miniprogram/mentors | 200 | 1 条 | ✅ |
| GET /api/miniprogram/vip/members | 200 | 数据完整 | ✅ |
| GET /api/admin/dashboard/stats | 200 | 149用户/30付费/¥2008.75 | ✅ |
| GET /api/admin/chapters | 200 | 章节数据 | H11: 无分页支持 |
| GET /api/admin/users | 200 | 1条(管理员) | H12: 返回管理员非用户 |
| GET /api/admin/orders | 200 | 448笔/¥2008.75 | ✅ |
| GET /api/admin/track/stats | 200 | 追踪数据 | ✅ |
| GET /api/admin/settings | 200 | 完整设置 | C1: OSS密钥明文 |
| GET /api/admin/referral-settings | 200 | 推广配置 | ✅ |
| GET /api/admin/author-settings | 200 | 作者配置 | ✅ |
| GET /api/db/book?action=list | 200 | 数据 | ✅ |
| GET /api/db/ckb-leads | 200 | 0 条 | ✅ |
| GET /api/db/ckb-plan-stats | 200 | 数据 | ✅ |
| GET /api/db/vip-roles | 200 | 10 条 | ✅ |
| GET /api/db/mentors | 200 | 1 条 | ✅ |
| GET /api/db/persons | 200 | 0 条 | H13: 空数据 |
| 无Token→admin/settings | 401 | 拒绝 | ✅ 鉴权正常 |
| 错误Token→admin/settings | 401 | 拒绝 | ✅ 鉴权正常 |
| POST /api/admin 空body | 错误 | 有提示 | ✅ |
| search 无 q 参数 | 200 | 空结果 | ✅ |
| upload 非图片 | 400 | 拒绝 | ✅ |
| upload 图片(OSS) | 200 | OSS签名URL | ✅ |
---
## 六、数据库检查结果
### 6.1 表结构（25 张表）
users, chapters, orders, persons, mentors, mentor_consultations, vip_roles, link_tags, user_balances, balance_transactions, gift_unlocks, system_config, admin_users, match_records, referral_bindings, referral_visits, user_tracks, user_rules, reading_progress, withdrawals, wechat_callback_logs, ckb_submit_records, ckb_lead_records, user_addresses, author_config
### 6.2 数据量
| 表 | 数据量 | 说明 |
|---|-------|------|
| chapters | 90 | 8篇, 0无标题, 0零字数 |
| users | 149 | dashboard 显示 |
| orders | 448 | 含已支付/待支付/其他 |
| match_records | 63 | 匹配记录 |
| referral_bindings | 41 | 推广绑定 |
| vip_roles | 10 | VIP 角色定义 |
| mentors | 1 | 导师（卡若） |
| persons | 0 | ⚠️ 空 |
| ckb_lead_records | 0 | ⚠️ 空 |
### 6.3 数据一致性
| 检查项 | 结果 |
|--------|------|
| 章节数 stats vs all-chapters | ✅ 一致（90） |
| 收入 orders vs dashboard | ✅ 一致（¥2008.75） |
| 用户数 stats vs dashboard | ✅ 一致（149） |
| 订单无重复 | ✅ 无重复订单号 |
| 免费章节数 | ⚠️ stats=2, 实际可能=3 |
---
## 七、优先修复路线图
### 第一批：安全问题（紧急）
1. **C1** OSS 密钥脱敏 — 后端 AdminSettingsGet 返回 ossConfig 时隐藏 accessKeySecret
2. **C10** 管理端登录守卫 — 前端路由添加 token 检查
### 第二批：功能修复（高优先）
3. **C4** match.js 跳转路径修正
4. **H4+H5** 移除匹配失败伪装成功 + 测试模式购买逻辑
5. **C5** 移除废弃 wx.getUserProfile()
6. **C2+C3+H8** 清理或修复 payment.js
7. **C6-C9** 统一模块导入方式
### 第三批：数据优化
8. **C11** 修正免费章节计数
9. **H9** 仪表盘用户名显示
10. **H11+H12** API 分页和用户列表修正
11. **M12** 热度数据零点击检查
### 第四批：代码清理
12. **M6+M7** 清理调试日志和模拟数据
13. **H6+M1-M5** 消除硬编码
14. **L1-L6** 低优先优化
---
**测试结论**：项目核心功能链路（登录→阅读→购买→分销）基本完整可用，管理端 UI 质量良好。主要风险集中在安全层面（OSS 密钥泄露、登录守卫缺失）和小程序代码质量（废弃 API、模块语法混用、调试残留）。建议按优先级路线图逐批修复。

121
开发文档/存客宝对接逻辑图.md
View File

@@ -1,121 +0,0 @@
# 存客宝对接逻辑图
## 一、概念区分
| 字段 | 含义 | 来源 | 用途 |
|------|------|------|------|
| **token** | 32 位唯一标识 | 我们 `genPersonToken()` 生成 | 存在文章 `data-id`，小程序传 `targetUserId` |
| **ckb_api_key** | 存客宝计划级密钥 | 存客宝 `plan/detail` 接口返回 | 调 scenarios 内部 API 时作为 `apiKey` 鉴权 |
**token ≠ apiKey**。scenarios 内部 API 需要的是 `ckb_api_key`，不是 token。
---
## 二、Person 创建流程（含存客宝计划）
```
管理端添加 / 文章 @新人物 保存
│
▼
┌─────────────────────────────────────────────────────────────┐
│ DBPersonSave / createPersonMinimal │
├─────────────────────────────────────────────────────────────┤
│ 1. genPersonToken() → 生成 token（32 位） │
│ 2. ckbOpenGetToken() → 获取开放 API JWT │
│ 3. ckbOpenCreatePlan(JWT, payload) → 创建计划，返回 planId │
│ 4. ckbOpenGetPlanDetail(JWT, planId) → 获取 plan 的 apiKey │
│ 5. 落库 Person: │
│ - token = 我们生成的 token │
│ - ckb_api_key = 存客宝返回的 apiKey │
│ - ckb_plan_id = planId │
└─────────────────────────────────────────────────────────────┘
```
---
## 三、文章 @ 到留资提交流程
```
文章 content 解析
<span data-type="mention" data-id="TOKEN" data-label="远志">@远志</span>
│
▼
小程序 contentParser → seg.userId = TOKEN
│
▼
用户点击 @远志 → onMentionTap → targetUserId = TOKEN
│
▼
POST /api/miniprogram/ckb/lead
{ targetUserId: TOKEN, phone, wechatId, ... }
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CKBLead │
├─────────────────────────────────────────────────────────────┤
│ 1. targetUserId 有值 → 用 token 查 Person │
│ 2. leadKey = Person.CkbApiKey（存客宝计划级 apiKey） │
│ 3. 若 CkbApiKey 为空 → 报错，不 fallback .env │
│ 4. 调 scenarios: GET ckbAPIURL?apiKey=leadKey&...&sign=... │
└─────────────────────────────────────────────────────────────┘
│
▼
存客宝 scenarios 内部 API 按 apiKey 路由到对应计划，收线索
```
---
## 四、首页「链接卡若」流程
```
首页留资（无 targetUserId）
│
▼
POST /api/miniprogram/ckb/lead
{ phone, wechatId, ... } // 无 targetUserId
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CKBLead / CKBIndexLead │
├─────────────────────────────────────────────────────────────┤
│ leadKey = getCkbLeadApiKey() │
│ → system_config.site_settings.ckbLeadApiKey │
│ → .env CKB_LEAD_API_KEY │
│ → 代码内置 ckbAPIKey │
└─────────────────────────────────────────────────────────────┘
```
---
## 五、数据流总览
```
┌──────────────┐ token ┌──────────────┐ ckb_api_key ┌──────────────┐
│ 文章 content │ ──────────────▶│ persons 表 │ ─────────────────▶│ scenarios │
│ data-id │ │ token │ │ 内部 API │
└──────────────┘ │ ckb_api_key │ └──────────────┘
▲ │ ckb_plan_id │
│ └──────────────┘
│ ▲
│ │ 创建时
│ ┌──────┴──────┐
│ │ 开放 API │
│ │ createPlan │
│ │ getPlanDetail│
│ └─────────────┘
│
┌──────┴──────┐
│ 管理端/autolink │
│ 添加/编辑 Person │
└──────────────┘
```
---
## 六、关键结论
1. **apiKey 已存储**：创建计划时 `ckbOpenGetPlanDetail` 返回的 apiKey 会写入 `persons.ckb_api_key`。
2. **CKBLead 应用 CkbApiKey**：文章 @ 场景下，用 token 查 Person，取 `CkbApiKey` 作为 scenarios 的 apiKey，**不能用 token 代替**。
3. **CkbApiKey 为空时**：应返回明确错误，提示该人物尚未配置存客宝密钥，**不要 fallback 到 .env**（.env 是卡若的，会路由到错误计划）。
4. **创建计划参数**：`planType=1`、`sceneId=9`、`scenario=9`、`status=1`（2026-03-16 修正，否则 401 无效 apiKey）。
5. **mention span 需 data-label**：TipTap 仅从 `data-label` 解析显示名，缺则显示 token；ParseAutoLinkContent 输出必须含 `data-label`。

BIN
开发文档/小程序管理/scripts/reports/体验版二维码_soul-party_20260315_2344.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 96 KiB

BIN
开发文档/小程序管理/scripts/reports/体验版二维码_soul-party_20260316_0221.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 96 KiB

BIN
开发文档/小程序管理/scripts/reports/体验版二维码_soul-party_20260316_1804.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 96 KiB

154
开发文档/新版管理端迁移到稳定版-需求评估.md
View File

@@ -1,154 +0,0 @@
# 新版管理端迁移到稳定版 - 需求评估
> 乘风整理。更新日期：2026-03-17
**目录说明**：`new-soul/soul-admin` = **稳定版**（生产主用）；`soul-admin/`（根目录）= 根目录版。迁移时以稳定版为基准，从根目录版带入缺失能力。
---
## 一、评估基准
| 基准 | 说明 |
|------|------|
| **稳定版小程序** | 已梳理完毕，定义 C 端能力：余额、代付、VIP、规则引擎、埋点、找伙伴、推广等 |
| **稳定版管理端** | `new-soul/soul-admin`，需支撑上述小程序的运营与管理 |
| **以界面定需求** | 管理端界面清单见《以界面定需求》§三；业务逻辑对齐见§四 |
---
## 二、稳定版管理端必须保留的能力（不可丢）
以下能力对应小程序功能，迁移时**必须保留**，新版若缺失则需从稳定版补齐。
| 能力 | 对应小程序 | 稳定版现状 | 迁移时动作 |
|------|------------|------------|------------|
| 用户详情 - 当前余额 | wallet、read/vip 余额支付 | ✅ 有 | **保留**，新版无则从稳定版代码带入 |
| 订单 - 支付方式（微信/余额/支付宝） | 余额购买、代付 | ✅ 有 | **保留**，新版无则从稳定版代码带入 |
| 订单 - 代付标识、代付人 | gift-pay | ✅ 有 | **保留** |
| 用户规则 CRUD | ruleEngine | ✅ 有 | **保留** |
| 超级个体/VIP 管理 | vip、member-detail | ✅ 有 | **保留** |
| 提现审核、分销、找伙伴、导师 | 对应小程序页 | ✅ 有 | **保留** |
| **内容管理（文章内容）** | chapters、read | ✅ 有 | **以稳定版为主**，不采纳新版 |
| RechargeAlert | 商户号余额不足提示 | ✅ 有 | **保留**，运营需及时感知 |
| LinkedMp（关联小程序） | 多小程序场景 | ✅ 有 | **保留**，若业务使用 |
---
## 三、稳定版可选能力（依赖后端，当前 404）
以下能力稳定版 UI 已有，但 soul-api **router 未注册**，会 404。迁移时需决策：**修后端** 或 **暂隐 UI**。
| 能力 | 接口 | 调用位置 | 建议 |
|------|------|----------|------|
| 用户列表 RFM 排序 | `GET /api/db/users/rfm` | UsersPage | 若运营需要 RFM 分析 → 补 router；否则迁移时可隐 |
| 用户旅程总览 | `GET /api/db/users/journey-stats` | UsersPage | 若运营需要 → 补 router；否则迁移时可隐 |
| 神射手（用户资料完善） | `GET/POST /api/admin/shensheshou/*` | UserDetailModal | 若使用神射手 → 补 router；否则迁移时可隐 |
---
## 四、新版独有、稳定版可吸纳的能力
以下为新版有、稳定版无，迁移时**可选择性吸纳**到稳定版。
| 能力 | 说明 | 需求评估 | 建议 |
|------|------|----------|------|
| **OSS 配置** | 阿里云对象存储 endpoint、bucket、accessKey 等 | 新版有 → 迁移 | **吸纳**（2026-03-17 会议决议） |
| **API 文档 Tab** | 系统设置内嵌 ApiDocsPage | 新版有 → 迁移 | **吸纳** |
| **api-docs 独立页** | `/api-docs` 路由 | 新版有 → 迁移 | **吸纳** |
| **编辑时手机号禁用** | 编辑用户时手机号不可改 | 新版有 → 迁移 | **吸纳** |
| **鉴权逻辑优化** | 先检查 token 再请求 | 新版有 → 迁移 | **吸纳** |
---
## 五、迁移策略（按模块）
### 5.1 内容管理（文章内容）— 以稳定版为主
| 策略 | 说明 |
|------|------|
| **ContentPage** | 完全以稳定版为准，不采纳新版 |
| **章节树、内容编辑、LinkTag、Person、LinkedMp** | 稳定版实现为准 |
| **富文本、排序、预览、免费章节配置** | 稳定版为准 |
迁移时：内容管理相关代码**不覆盖**，保持稳定版实现。
---
### 5.2 其他模块迁移策略
| 模块 | 策略 | 说明 |
|------|------|------|
| **用户管理** | 以稳定版为主 | 用户详情余额、RFM、旅程、规则、超级个体均保留稳定版；可吸纳新版「编辑时手机号禁用」 |
| **订单** | 以稳定版为主 | 支付方式、代付、导出格式不覆盖 |
| **推广中心** | 以稳定版为主 | 保持稳定版实现 |
| **提现** | 以稳定版为主 | 保持稳定版实现 |
| **找伙伴** | 以稳定版为主 | CKB、匹配池、导师、资源对接等保持稳定版 |
| **系统设置** | 稳定版为主 + 吸纳 | 保持稳定版结构；可吸纳新版 API 文档 Tab、OSS 配置 |
| **Layout** | 以稳定版为主 | RechargeAlert、菜单结构保留；可吸纳新版鉴权逻辑 |
| **Dashboard** | 以稳定版为主 | 保持稳定版 |
| **支付/站点/小程序码/导师/API 文档** | 以稳定版为主 | 保持稳定版；API 文档可吸纳新版 ApiDocsPage |
---
### 5.3 需调整的项
| 项 | 调整说明 |
|----|----------|
| **后端 router** | 若保留 RFM、journey-stats、神射手，需 soul-api 补 5 个路由 |
| **OSS** | 若吸纳，需 soul-api 支持 ossConfig（/api/admin/settings 需确认） |
| **ApiDocsPage** | 新版有独立实现，可复制到稳定版并接入设置 Tab 或独立路由 |
---
### 5.4 不采纳的项
| 项 | 说明 |
|----|------|
| 新版 ContentPage | 内容管理以稳定版为准 |
| 新版 Layout 结构差异 | 系统设置分区等保持稳定版 |
| 新版部分 UI 细节 | grid-cols、间距等以稳定版为准 |
---
## 六、需求优先级与实施顺序
| 阶段 | 内容 | 优先级 |
|------|------|:------:|
| **1. 必须保留** | 确保迁移后稳定版不丢失：用户详情余额、订单支付方式/代付、RechargeAlert、LinkedMp | P0 |
| **2. 后端补齐** | 若保留 RFM/journey/神射手：soul-api router 注册 5 个路由 | P1 |
| **3. 吸纳优化** | 编辑时手机号禁用、鉴权逻辑、API 文档 Tab | P2 |
| **4. 按需吸纳** | OSS 配置、api-docs 独立页 | P3 |
---
## 七、验收标准（迁移完成后）
| 验收项 | 标准 |
|--------|------|
| 用户详情 | 基础信息 Tab 有「当前余额」卡，数据来自 `/api/admin/users/:id/balance` |
| 订单页 | 支付方式列含微信/余额/支付宝，代付订单展示代付人 |
| 用户规则 | 规则配置 Tab 可 CRUD，与小程序 ruleEngine 联动 |
| RechargeAlert | 余额不足等错误时顶部红条可展示 |
| 内容管理 | 章节树、文章编辑、LinkTag、Person、LinkedMp 等以稳定版为准 |
| 其他 | 提现、分销、找伙伴、设置等页面功能正常 |
---
## 八、迁移策略汇总
| 原则 | 模块 |
|------|------|
| **以稳定版为主（不覆盖）** | 内容管理、用户管理、订单、推广、提现、找伙伴、Layout、Dashboard |
| **吸纳新版** | 编辑时手机号禁用、鉴权逻辑、API 文档 Tab、OSS 配置（按需） |
| **内容管理** | **明确以稳定版为主**，章节树、文章编辑、LinkTag、Person、LinkedMp 等均不采纳新版 |
---
## 九、总结
| 类型 | 说明 |
|------|------|
| **必须保留** | 余额、代付、规则、VIP、RechargeAlert、LinkedMp、**内容管理** |
| **可选（依赖后端）** | RFM、journey-stats、神射手 |
| **可吸纳** | OSS、API 文档、编辑禁用、鉴权优化 |
| **结论** | 内容管理以稳定版为主；其他模块以稳定版为主，选择性吸纳新版优化；后端按需补 router。 |

107
开发文档/新版迁移-开发方案与清单.md
View File

@@ -1,107 +0,0 @@
# 新版迁移 - 开发方案与清单
> 从 new-soul 迁移到稳定版 miniprogram 的完整开发方案，整合需求、经营、技术、运营视角。
> 更新日期：2026-03-16
---
## 一、迁移范围总览
| 需求 | 说明 | 优先级 |
|------|------|--------|
| R1～R4 | 余额体系：充值、消费、交易记录、退款 | P0 |
| R5 | 我的页「我的余额」入口 | P0 |
| R2 | 阅读页余额购买（章节/全书） | P0 |
| R6～R8 | 首页精选/最新展开、按热度 | P1 |
| R9～R10 | 代付（我的代付链接 + 阅读页代付分享） | P2 |
| R11 | 埋点 trackClick | P0 |
| VIP 余额 | VIP 页支持余额购买 | P1 |
| 管理端 | 订单支付方式、用户详情余额 | P0 |
---
## 二、技术实现要点
### 2.1 余额消费必须写 orders
同一事务内：扣 user_balances → 写 balance_transactions → 写 orders（product_type、status=paid、payment_method=balance）。否则 check-purchased、purchase-status 失效。
### 2.2 分销 + 余额消费
consume 入参增加 referralCode，创建订单时与 pay 一致解析 referrer_id、计算佣金。
### 2.3 充值流程
1. POST balance/recharge → 创建 orders（product_type=balance_recharge, status=created）→ 返回 orderSn
2. POST pay（productType=balance_recharge, productId=orderSn）→ 后端从 orders 查 amount
3. 支付成功 → 前端调 recharge/confirm；PayNotify 也触发加余额（幂等）
### 2.4 consume 价格校验
后端必须用 getStandardPrice 校验 amount，禁止仅信前端。
---
## 三、实现清单（可执行）
### soul-api
| # | 任务 | 接口/表 | 状态 |
|---|------|---------|:----:|
| 1 | 埋点 | POST /api/miniprogram/track | ✅ |
| 2 | 余额表 | user_balances、balance_transactions | ✅ |
| 3 | 余额接口 | GET balance、GET transactions、POST recharge、POST recharge/confirm、POST refund、POST consume | ✅ |
| 4 | pay 扩展 | productType=balance_recharge，从 orders 取 amount | ✅ |
| 5 | PayNotify | balance_recharge 分支，加余额幂等 | ✅ |
| 6 | BookHot | 支持 ?limit=，最大 50 | ✅ |
| 7 | orders | 增加 payment_method 字段 | ✅ |
| 8 | 管理端 | GET /api/admin/users/:id/balance | ✅ |
### miniprogram
| # | 任务 | 文件 | 状态 |
|---|------|------|:----:|
| 1 | trackClick | utils/trackClick.js | ✅ |
| 2 | wallet 页 | pages/wallet/* | ✅ |
| 3 | 我的页 | 余额入口、handleMenuTap wallet、loadWalletBalance | ✅ |
| 4 | read 页 | 余额支付、walletBalance 拉取 | ✅ |
| 5 | 首页 | featuredExpanded、latestExpanded、book/hot?limit=50 | ✅ |
| 6 | VIP 页 | 余额支付分支 | ✅ |
### soul-admin
| # | 任务 | 说明 | 状态 |
|---|------|------|:----:|
| 1 | 订单支付方式 | balance → 余额支付 | ✅ |
| 2 | 余额订单 | 不展示退款按钮 | ✅ |
| 3 | 用户详情 | 余额 + 最近交易 | ✅ |
---
## 四、开发顺序
```
1. soul-api: 余额表 + 接口 + pay 扩展 + PayNotify + track + BookHot limit + payment_method
2. soul-api: 管理端用户余额接口
3. miniprogram: trackClick + wallet + 我的页 + read 页余额
4. miniprogram: 首页展开 + VIP 余额
5. soul-admin: 订单展示 + 用户详情余额
```
---
## 五、不迁移项
ruleEngine、user-rules、loadRuntimeConfig。avatar-nickname 保留迁移（稳定版已有，继续使用）。
---
## 六、数据库迁移
执行 `soul-api/scripts/add-balance-tables.sql` 创建 user_balances、balance_transactions，并为 orders 增加 payment_method 列。GORM AutoMigrate 也会自动同步。
---
## 七、实现说明（2026-03-16）
已完成：余额体系（充值/消费/退款）、埋点、我的页余额入口、阅读页余额支付、VIP 页余额支付、管理端订单展示与用户详情余额、首页精选/最新展开、搜索页 book/hot?limit=50。代付链接：后端 GET /api/miniprogram/gift/link + gift-link 页对接。阅读页代付分享为后续迭代项。

269
开发文档/稳定版-小程序与API对比.md
View File

@@ -1,269 +0,0 @@
# 稳定版 vs 新版 · 小程序与 API 对比清单
> 稳定版：`miniprogram/`；新版：`new-soul/miniprogram/`
> 生成日期：2026-03-16
---
## 一、页面差异
| 页面 | 稳定版 | 新版 | 说明 |
|------|:-----:|:----:|------|
| pages/avatar-nickname | ✓ | ✗ | 新版移除，可能合并到 profile-edit |
| pages/wallet | ✗ | ✓ | **新版新增**：钱包（余额、充值、退款、交易记录） |
| 其它 22 页 | ✓ | ✓ | 一致 |
---
## 二、小程序页面清单（稳定版）
| 页面路径 | 功能 | Tab |
|---------|------|-----|
| pages/index/index | 首页 | ✓ |
| pages/chapters/chapters | 目录 | ✓ |
| pages/match/match | 找伙伴 | ✓ |
| pages/my/my | 我的 | ✓ |
| pages/read/read | 文章阅读 | - |
| pages/link-preview/link-preview | 链接预览 | - |
| pages/about/about | 关于作者 | - |
| pages/agreement/agreement | 用户协议 | - |
| pages/privacy/privacy | 隐私政策 | - |
| pages/referral/referral | 推广中心 | - |
| pages/purchases/purchases | 我的订单 | - |
| pages/settings/settings | 设置 | - |
| pages/search/search | 搜索 | - |
| pages/addresses/addresses | 收货地址列表 | - |
| pages/addresses/edit | 地址编辑 | - |
| pages/withdraw-records/withdraw-records | 提现记录 | - |
| pages/vip/vip | VIP 购买 | - |
| pages/member-detail/member-detail | 会员/用户详情 | - |
| pages/mentors/mentors | 导师列表 | - |
| pages/mentor-detail/mentor-detail | 导师详情 | - |
| pages/profile-show/profile-show | 资料展示 | - |
| pages/profile-edit/profile-edit | 资料编辑 | - |
| pages/avatar-nickname/avatar-nickname | 头像昵称 | - |
---
## 三、小程序调用的 API 清单（稳定版，按模块）
### 3.1 配置与登录
| 接口 | 方法 | 调用位置 | 用途 |
|------|------|----------|------|
| /api/miniprogram/config | GET | app.js, my.js, read.js, chapterAccessManager.js, custom-tab-bar | 公开配置（persons、linkTags、freeChapters 等） |
| /api/miniprogram/login | POST | app.js | 微信 code 登录 |
| /api/miniprogram/phone-login | POST | app.js | 手机号一键登录 |
| /api/miniprogram/phone | POST | index.js, settings.js | 获取手机号 |
| /api/miniprogram/dev/login-as | POST | settings.js | 开发专用：按 userId 切换账号 |
### 3.2 书籍/章节
| 接口 | 方法 | 调用位置 | 用途 |
|------|------|----------|------|
| /api/miniprogram/book/all-chapters | GET | app.js, index.js, read.js | 全量章节树 |
| /api/miniprogram/book/parts | GET | chapters.js | 篇章列表（懒加载） |
| /api/miniprogram/book/chapters-by-part | GET | chapters.js | 按篇章返回章节 |
| /api/miniprogram/book/chapter/:id | GET | read.js | 按 id 获取章节 |
| /api/miniprogram/book/chapter/by-mid/:mid | GET | read.js | 按 mid 解析章节 |
| /api/miniprogram/book/hot | GET | search.js | 热门排行 |
| /api/miniprogram/book/recommended | GET | index.js | 推荐章节 |
| /api/miniprogram/book/latest-chapters | GET | index.js | 最新章节 |
| /api/miniprogram/book/search | GET | search.js | 搜索 |
| /api/miniprogram/book/stats | GET | about.js | 书籍统计 |
### 3.3 用户/资料
| 接口 | 方法 | 调用位置 | 用途 |
|------|------|----------|------|
| /api/miniprogram/user/profile | GET/POST | profile-show, profile-edit, member-detail, index, read, match, my, settings, avatar-nickname | 用户资料 |
| /api/miniprogram/user/update | POST | my.js, settings.js | 更新用户（头像、昵称等） |
| /api/miniprogram/user/purchase-status | GET | read.js, chapterAccessManager.js | 购买状态（VIP/买断/单章） |
| /api/miniprogram/user/check-purchased | GET | chapterAccessManager.js | 校验是否已购买 |
| /api/miniprogram/user/dashboard-stats | GET | my.js | 阅读统计（我的页） |
| /api/miniprogram/user/reading-progress | GET/POST | readingTracker.js | 阅读进度 |
| /api/miniprogram/user/addresses | GET/POST | addresses.js, addresses/edit.js | 收货地址 CRUD |
| /api/miniprogram/user/addresses/:id | GET/PUT/DELETE | addresses.js, addresses/edit.js | 单条地址 |
### 3.4 VIP
| 接口 | 方法 | 调用位置 | 用途 |
|------|------|----------|------|
| /api/miniprogram/vip/status | GET | vip.js, chapters.js, my.js, profile-edit | VIP 状态 |
| /api/miniprogram/vip/members | GET | index.js, member-detail.js | VIP 会员列表/单个 |
| /api/miniprogram/vip/profile | GET/POST | （未直接调用，vip 组有） | VIP 资料 |
### 3.5 支付与订单
| 接口 | 方法 | 调用位置 | 用途 |
|------|------|----------|------|
| /api/miniprogram/pay | GET/POST | read.js, vip.js, match.js | 创建订单/查询 |
| /api/miniprogram/orders | GET | purchases.js | 订单列表 |
| /api/miniprogram/qrcode | POST | read.js, referral.js | 生成小程序码 |
### 3.6 分销/推广
| 接口 | 方法 | 调用位置 | 用途 |
|------|------|----------|------|
| /api/miniprogram/referral/visit | POST | app.js | 访问记录 |
| /api/miniprogram/referral/bind | POST | app.js | 绑定推广关系 |
| /api/miniprogram/referral/data | GET | referral.js | 推广数据 |
| /api/miniprogram/earnings | GET | my.js | 我的收益 |
| /api/miniprogram/withdraw | POST | my.js, referral.js | 申请提现 |
| /api/miniprogram/withdraw/records | GET | withdraw-records.js | 提现记录 |
| /api/miniprogram/withdraw/pending-confirm | GET | my.js | 待确认收款 |
| /api/miniprogram/withdraw/confirm-received | POST | my.js | 确认收款 |
| /api/miniprogram/withdraw/confirm-info | GET | my.js, withdraw-records.js | 领取零钱参数 |
### 3.7 存客宝（CKB）
| 接口 | 方法 | 调用位置 | 用途 |
|------|------|----------|------|
| /api/miniprogram/ckb/index-lead | POST | index.js | 首页「链接卡若」留资 |
| /api/miniprogram/ckb/lead | POST | read.js | 文章 @某人 留资 |
| /api/miniprogram/ckb/match | POST | match.js | 找伙伴留资 |
| /api/miniprogram/ckb/join | POST | match.js | 加入匹配池 |
### 3.8 找伙伴
| 接口 | 方法 | 调用位置 | 用途 |
|------|------|----------|------|
| /api/miniprogram/match/config | GET | match.js | 找伙伴配置 |
| /api/miniprogram/match/users | POST | match.js | 匹配用户 |
### 3.9 导师
| 接口 | 方法 | 调用位置 | 用途 |
|------|------|----------|------|
| /api/miniprogram/mentors | GET | mentors.js | 导师列表 |
| /api/miniprogram/mentors/:id | GET | mentor-detail.js | 导师详情 |
| /api/miniprogram/mentors/:id/book | POST | mentor-detail.js | 预约导师 |
### 3.10 其它
| 接口 | 方法 | 调用位置 | 用途 |
|------|------|----------|------|
| /api/miniprogram/upload | POST | my.js, profile-edit, settings, avatar-nickname | 图片上传 |
| /api/miniprogram/users | GET | index.js, member-detail.js | 用户列表/单个（超级个体、回退） |
| /api/miniprogram/about/author | GET | about.js | 关于作者配置 |
---
## 四、soul-api 已注册的 miniprogram 路由（稳定版）
| 路由 | 方法 | Handler |
|------|------|---------|
| /api/miniprogram/config | GET | GetPublicDBConfig |
| /api/miniprogram/login | POST | MiniprogramLogin |
| /api/miniprogram/phone-login | POST | WechatPhoneLogin |
| /api/miniprogram/dev/login-as | POST | MiniprogramDevLoginAs |
| /api/miniprogram/phone | POST | MiniprogramPhone |
| /api/miniprogram/pay | GET/POST | MiniprogramPay |
| /api/miniprogram/pay/notify | POST | MiniprogramPayNotify |
| /api/miniprogram/qrcode | POST | MiniprogramQrcode |
| /api/miniprogram/qrcode/image | GET | MiniprogramQrcodeImage |
| /api/miniprogram/book/all-chapters | GET | BookAllChapters |
| /api/miniprogram/book/parts | GET | BookParts |
| /api/miniprogram/book/chapters-by-part | GET | BookChaptersByPart |
| /api/miniprogram/book/chapter/:id | GET | BookChapterByID |
| /api/miniprogram/book/chapter/by-mid/:mid | GET | BookChapterByMID |
| /api/miniprogram/book/hot | GET | BookHot |
| /api/miniprogram/book/recommended | GET | BookRecommended |
| /api/miniprogram/book/latest-chapters | GET | BookLatestChapters |
| /api/miniprogram/book/search | GET | BookSearch |
| /api/miniprogram/book/stats | GET | BookStats |
| /api/miniprogram/referral/visit | POST | ReferralVisit |
| /api/miniprogram/referral/bind | POST | ReferralBind |
| /api/miniprogram/referral/data | GET | ReferralData |
| /api/miniprogram/earnings | GET | MyEarnings |
| /api/miniprogram/match/config | GET | MatchConfigGet |
| /api/miniprogram/match/users | POST | MatchUsers |
| /api/miniprogram/ckb/join | POST | CKBJoin |
| /api/miniprogram/ckb/match | POST | CKBMatch |
| /api/miniprogram/ckb/lead | POST | CKBLead |
| /api/miniprogram/ckb/index-lead | POST | CKBIndexLead |
| /api/miniprogram/upload | POST/DELETE | UploadPost / UploadDelete |
| /api/miniprogram/user/addresses | GET/POST | UserAddressesGet/Post |
| /api/miniprogram/user/addresses/:id | GET/PUT/DELETE | UserAddressesByID |
| /api/miniprogram/user/check-purchased | GET | UserCheckPurchased |
| /api/miniprogram/user/dashboard-stats | GET | UserDashboardStats |
| /api/miniprogram/user/profile | GET/POST | UserProfileGet/Post |
| /api/miniprogram/user/purchase-status | GET | UserPurchaseStatus |
| /api/miniprogram/user/reading-progress | GET/POST | UserReadingProgressGet/Post |
| /api/miniprogram/user/update | POST | UserUpdate |
| /api/miniprogram/withdraw | POST | WithdrawPost |
| /api/miniprogram/withdraw/records | GET | WithdrawRecords |
| /api/miniprogram/withdraw/pending-confirm | GET | WithdrawPendingConfirm |
| /api/miniprogram/withdraw/confirm-received | POST | WithdrawConfirmReceived |
| /api/miniprogram/withdraw/confirm-info | GET | WithdrawConfirmInfo |
| /api/miniprogram/vip/status | GET | VipStatus |
| /api/miniprogram/vip/profile | GET/POST | VipProfileGet/Post |
| /api/miniprogram/vip/members | GET | VipMembers |
| /api/miniprogram/users | GET | MiniprogramUsers |
| /api/miniprogram/orders | GET | MiniprogramOrders |
| /api/miniprogram/mentors | GET | MiniprogramMentorsList |
| /api/miniprogram/mentors/:id | GET | MiniprogramMentorsDetail |
| /api/miniprogram/mentors/:id/book | POST | MiniprogramMentorsBook |
| /api/miniprogram/about/author | GET | MiniprogramAboutAuthor |
---
## 五、对齐情况
| 状态 | 说明 |
|------|------|
| ✓ 已对齐 | 小程序调用的所有 `/api/miniprogram/*` 接口均在 soul-api router 中注册 |
| - | 小程序未调用 `/api/miniprogram/vip/profile`，但后端已提供（备用） |
---
## 六、新版（new-soul）新增 API（稳定版 soul-api 暂无）
| 接口 | 方法 | 调用位置 | 用途 |
|------|------|----------|------|
| /api/miniprogram/balance | GET | wallet.js | 查询余额、累计充值/赠送/退款 |
| /api/miniprogram/balance/transactions | GET | wallet.js | 交易记录列表 |
| /api/miniprogram/balance/recharge | POST | wallet.js | 创建充值订单 |
| /api/miniprogram/balance/recharge/confirm | POST | wallet.js | 支付成功后确认充值 |
| /api/miniprogram/balance/refund | POST | wallet.js | 余额退款 |
| /api/miniprogram/user-rules | GET | ruleEngine.js | 规则引擎：按场景触发引导 |
| /api/miniprogram/track | POST | trackClick.js, ruleEngine.js | 埋点上报 |
**说明**：新版 wallet 页的支付流程为：`balance/recharge` → `pay`（productType: 'balance_recharge'）→ `balance/recharge/confirm`。稳定版 soul-api 需新增上述路由才能支持新版钱包功能。
---
## 七、新版新增能力（稳定版无）
| 能力 | 说明 |
|------|------|
| **规则引擎** | `utils/ruleEngine.js` + `/api/miniprogram/user-rules`，按 page_show、after_login 等场景触发引导 |
| **埋点上报** | `utils/trackClick.js` + `/api/miniprogram/track` |
| **运行配置** | `loadRuntimeConfig()` 从 config 取 `mpConfig.apiDomain` 等，支持动态覆盖 baseUrl |
| **单页模式** | `ensureFullAppForAuth()` 检测朋友圈单页，引导用户「前往小程序」 |
| **更新检测** | `checkUpdate()` 基于 wx.getUpdateManager |
| **navigateToMiniProgramAppIdList** | 新版 app.json 配置 `wx6489c26045912fe1`、`wx3d15ed02e98b04e3` |
| **我的页** | 新版有 `loadWalletBalance`、`loadGiftList`（代付链接） |
---
## 八、config 返回格式差异
| 字段 | 稳定版 | 新版 |
|------|--------|------|
| 主结构 | persons、linkTags、freeChapters、prices 等 | 同上 + `mpConfig`、`features` |
| mpConfig | - | apiDomain、appId、mchId、withdrawSubscribeTmplId |
| features | - | matchEnabled 等 |
| configs.feature_config | - | 备用格式，含 matchEnabled |
---
## 九、迁移建议
1. **后端**：soul-api 需新增 balance、user-rules、track 相关路由，才能完整支持新版。
2. **稳定版→新版**：若稳定版要升级，需补充 wallet 页、ruleEngine、trackClick，并调整 config 返回格式。
3. **新版→稳定版**：若新版要回退，需移除 wallet、user-rules、track 依赖，或在后端做空实现。
---
*文档由助理橙子生成 | 基于 miniprogram/、new-soul/miniprogram/ 与 soul-api/internal/router/router.go 扫描*

175
开发文档/稳定版-源码质量分析报告.md
View File

@@ -1,175 +0,0 @@
# Soul 创业派对稳定版 - 源码质量分析报告
> 分析时间：2026-03-17
> 分析人：乘风（老板分身）
---
## 一、高优先级（建议优先处理）
### 1. soul-api：敏感配置默认值泄露
**位置**：`soul-api/internal/config/config.go` 第 174–237 行
**问题**：AppSecret、MchKey、APIv3Key、adminPassword、adminSessionSecret、证书序列号等敏感信息有硬编码默认值。若 `.env` 未配置，将使用这些默认值，存在泄露与撞库风险。
**建议**：
- 生产环境强制从环境变量读取，缺则 `log.Fatal` 启动失败
- 或使用占位符如 `"MUST_SET_IN_ENV"`，启动时校验并拒绝
---
### 2. soul-api：`/api/user/track` 无鉴权
**位置**：`soul-api/internal/router/router.go` 第 260–261 行；`soul-api/internal/handler/user.go` 第 535 行
**问题**：`GET /api/user/track?userId=xxx` 无 AdminAuth，任何人可查任意用户行为轨迹。管理端 `UserDetailModal` 调用此接口展示用户行为。
**建议**：
- 将接口迁至 `/api/admin/user/track` 或 `/api/db/user/track`，并加 `AdminAuth()` 中间件
- 或保留路径，在 handler 内校验管理员 token
---
### 3. miniprogram：`payment.js` 使用未定义变量
**位置**：`miniprogram/utils/payment.js` 第 25 行
**问题**：使用 `app.globalData.apiBase`，而 app 中仅有 `baseUrl`，会导致 `undefined + '/payment/create'`，请求失败。
**说明**：当前支付流程在 `read.js` 中直接调用 `/api/miniprogram/pay`，未使用 `payment.js`，该文件疑似废弃。若确认废弃，建议删除；若保留，需改为 `baseUrl` 并统一走 miniprogram 支付接口。
---
## 二、中优先级
### 4. miniprogram：`goToMatch()` 重复定义
**位置**：`miniprogram/pages/my/my.js` 第 801、816 行
**问题**：两个完全相同的 `goToMatch()`，后者覆盖前者，易造成维护困惑。
**建议**：删除其中一个。
---
### 5. miniprogram：敏感信息硬编码
**位置**：`miniprogram/app.js` 第 18–25 行
**问题**：appId、mchId、withdrawSubscribeTmplId 写死在代码中，与后端 config 重复。
**建议**：优先从 `/api/miniprogram/config` 的 `mpConfig` 读取，代码中仅保留开发兜底。
---
### 6. miniprogram：开发接口暴露
**位置**：`miniprogram/pages/settings/settings.js` 第 416 行
**问题**：`dev/login-as` 在开发/体验版可见，生产需确保后端关闭或鉴权。
**建议**：后端对该接口做环境或 IP 白名单限制。
---
### 7. soul-admin：RichEditor innerHTML 潜在 XSS
**位置**：`soul-admin/src/components/RichEditor.tsx` 第 177 行
**问题**：`popup.innerHTML = items.map(...)` 直接拼接 `item.name`、`item.label`，若含 HTML 可能 XSS。
**建议**：对 `name`、`label` 做 HTML 转义，或使用 `textContent` 渲染。
---
### 8. miniprogram：`totalSections: 62` 多处硬编码
**位置**：`app.js`、`index.js`、`my.js`、`chapters.js` 等
**问题**：章节总数写死为 62，与真实数据可能不一致。
**建议**：从 `book/stats` 或 `all-chapters` 动态获取，或统一从 config 读取。
---
### 9. miniprogram：废弃/备份文件
**位置**：
- `miniprogram/pages/read/read.js.backup`
- `miniprogram/pages/referral/referral.wxss.backup`
**问题**：备份文件混入源码，增加噪音。
**建议**：若无需保留，可删除或移出版本库。
---
### 10. soul-admin：`/api/user/track` 三端边界
**位置**：`soul-admin/src/components/modules/user/UserDetailModal.tsx` 第 192 行
**问题**：管理端调用 `/api/user/track`（非 admin/db 路径），与「管理端只调 admin/db」约定不符。
**建议**：后端将 track 查询迁至 `/api/admin/user/track` 或 `/api/db/user/track`，管理端同步改路径。
---
## 三、低优先级
### 11. soul-api：`DBUsersList` 函数过长
**位置**：`soul-api/internal/handler/db.go`
**建议**：拆分为统计、过滤、分页等子函数，提升可读性。
---
### 12. soul-api：`AdminWithdrawTest` 默认值
**位置**：`soul-api/internal/handler/withdraw.go` 第 137–138 行
**问题**：测试接口默认 userId、amount 写死，易误用。
**建议**：仅开发环境启用，或强制从请求体传入。
---
### 13. miniprogram：错误处理不统一
**问题**：部分 `app.request` 用 `try/catch` 并提示用户，部分 `catch (e) {}` 静默吞错。
**建议**：统一约定：用户可见操作需提示，静默请求可吞错但需 `console.warn`。
---
### 14. soul-admin：上传逻辑重复
**位置**：`ContentPage.tsx`、`MentorsPage.tsx` 等
**建议**：抽取公共 `uploadFile(apiUrl, file)` 方法复用。
---
### 15. 性能：config / book 请求缓存
**问题**：`/api/miniprogram/config`、`book/all-chapters` 等频繁请求，无本地缓存。
**建议**：对 config 做短期缓存（如 5 分钟），减少重复请求。
---
## 四、已确认无问题
- **三端路由边界**：小程序统一走 `/api/miniprogram/*`，管理端走 `/api/admin/*`、`/api/db/*`，主体符合约定
- **支付流程**：`read.js` 正确使用 `/api/miniprogram/pay`，未依赖有问题的 `payment.js`
- **read.js.backup**：未在业务中引用，可安全清理
---
## 五、建议处理顺序
1. **立即**：soul-api 敏感默认值、`/api/user/track` 鉴权
2. **短期**：`payment.js` 废弃或修复、`goToMatch` 去重、`totalSections` 动态化
3. **中期**：管理端 track 路径迁移、RichEditor XSS 修复、配置与缓存优化
4. **长期**：代码结构优化、备份文件清理、错误处理统一

123
开发文档/稳定版-管理端与小程序对接分析.md
View File

@@ -1,123 +0,0 @@
# 稳定版：管理端与小程序功能对接分析
> 分析时间：2026-03-17
> 分析人：乘风（老板分身）
> 更新：2026-03-17 已完成 referralEnabled、searchEnabled 对接，删除 aboutEnabled 及关于作者页
## 一、结论概览
| 类型 | 数量 | 说明 |
|-----|------|------|
| ✅ 已对接 | 3 | matchEnabled、referralEnabled、searchEnabled |
| 🗑️ 已删除 | 1 | aboutEnabled、关于作者页 |
| ⚠️ 需确认 | 1 | site_settings 与 chapter_config 价格同步 |
---
## 二、功能开关（feature_config）对接情况
### 管理端配置项（SettingsPage 系统设置）
| 开关 | 管理端 | 后端 config 返回 | 小程序使用 |
|-----|--------|------------------|------------|
| **matchEnabled** | ✅ 有 | ✅ features.matchEnabled | ✅ **已用**：custom-tab-bar 控制找伙伴 tab；my 页根据此隐藏/显示找伙伴入口 |
| **referralEnabled** | ✅ 有 | ✅ features.referralEnabled | ✅ **已用**：my 页推荐好友/我的收益入口 `wx:if`；goToReferral 二次校验 |
| **searchEnabled** | ✅ 有 | ✅ features.searchEnabled | ✅ **已用**：首页搜索栏、目录页搜索按钮 `wx:if` |
| ~~aboutEnabled~~ | 🗑️ 已删除 | - | 关于作者页已移除 |
### 小程序实际使用（对接后）
- **custom-tab-bar**：读取 `matchEnabled`，控制找伙伴 tab
- **my.js**：`loadFeatureConfig()` 取 matchEnabled、referralEnabled、searchEnabled，存 globalData.features
- **my.wxml**：推荐好友/我的收益 `wx:if="{{referralEnabled}}"`；已删除关于作者菜单
- **index**：`loadFeatureConfig()` 取 searchEnabled；搜索栏 `wx:if="{{searchEnabled}}"`
- **chapters**：`loadFeatureConfig()` 取 searchEnabled；搜索按钮 `wx:if="{{searchEnabled}}"`
---
## 三、其他配置对接情况
### 已对接
| 配置项 | 来源 | 小程序使用位置 |
|--------|------|----------------|
| prices (section/fullbook) | chapter_config | read.js 展示价格、chapterAccessManager |
| userDiscount | referral_config | referral 页展示好友优惠 |
| linkTags | link_tag 表 | read.js onLinkTagTap |
| linkedMiniprograms | system_config | read.js 跳转关联小程序 |
| mpConfig | mp_config | 支付、提现等 |
### 需确认
| 配置项 | 说明 |
|--------|------|
| site_settings (sectionPrice, baseBookPrice) | 管理端保存到 `site_settings`，小程序 config 的 prices 来自 `chapter_config`。需确认两处是否同步，或是否有单独维护 chapter_config 的流程。 |
---
## 四、建议改造（补齐未用开关）
### 1. 推广开关 referralEnabled
**影响入口**：我的页「推荐好友」「我的收益」统计、goToReferral 跳转
**改造建议**：
- my.js：`loadFeatureConfig()` 增加 `referralEnabled`
- my.wxml：`profile-stat`（推荐好友、我的收益）加 `wx:if="{{referralEnabled}}"`
- 若有单独推广入口（如菜单项），也加 `wx:if="{{referralEnabled}}"`
### 2. 搜索开关 searchEnabled
**影响入口**：首页搜索栏、目录页搜索按钮
**改造建议**：
- app.js 或各页：从 config 拉取 `searchEnabled` 存 globalData
- index.wxml：搜索栏加 `wx:if="{{searchEnabled}}"`
- chapters.wxml：搜索按钮加 `wx:if="{{searchEnabled}}"`
### 3. 关于作者开关 aboutEnabled
**影响入口**：我的页「关于作者」菜单项
**改造建议**：
- my.js：`loadFeatureConfig()` 增加 `aboutEnabled`
- my.wxml：关于作者 menu-item 加 `wx:if="{{aboutEnabled}}"`
---
## 五、数据流说明
```
管理端 SettingsPage
→ POST /api/admin/settings { featureConfig }
→ 写入 system_config.feature_config
小程序
→ GET /api/miniprogram/config
→ GetPublicDBConfig 读取 feature_config，合并到 features
→ 返回 { features: { matchEnabled, referralEnabled, searchEnabled, aboutEnabled } }
当前：仅 matchEnabled 被小程序使用
```
---
## 六、附录：config 接口返回结构（GetPublicDBConfig）
```json
{
"success": true,
"prices": { "section": 1, "fullbook": 9.9 },
"features": {
"matchEnabled": true,
"referralEnabled": true,
"searchEnabled": true,
"aboutEnabled": true
},
"mpConfig": { "appId", "apiDomain", "buyerDiscount", ... },
"userDiscount": 5,
"linkTags": [...],
"linkedMiniprograms": [...],
"configs": { "chapter_config", "feature_config", "mp_config" }
}
```

87
开发文档/稳定版适配新界面-调整清单.md
View File

@@ -1,87 +0,0 @@
# 稳定版适配新界面 - 调整清单
> 基于 stitch_soul 设计稿与迁移方案，梳理稳定版 miniprogram 需调整项及完成路径。
> 更新日期：2026-03-16
---
## 一、设计稿与当前状态对照
| 设计稿 | 页面 | 当前状态 | 待调整 |
|--------|------|----------|--------|
| optimized_home_content_feed_v1 | 首页 | 品牌+搜索、最新更新、**阅读进度**、超级个体、精选推荐、最新新增、展开折叠 | ✅ |
| catalog_with_new_additions_v1 | 目录 | 篇章折叠、章节列表 | 基本对齐 |
| premium_membership_landing_v1 | VIP | 权益卡片、¥1980 按钮 | 基本对齐 |
| professional_profile_with_earnings_vip | 我的 | VIP 徽章、收益、阅读统计、最近阅读、订单、代付链接、**编辑→profile-show** | ✅ |
| enhanced_professional_profile | 个人资料展示 | profile-show、member-detail | 基本对齐 |
| comprehensive_profile_editor_v1_2 | 手机/微弹窗 | 提现/找伙伴时弹窗 | 已实现 |
---
## 二、需完成的调整项（按优先级）
### P1：首页补充「阅读进度」✅
**设计稿要求**：最新更新 → **阅读进度** → 超级个体 → 精选推荐 → 最新新增
**已完成**：在「最新更新」与「超级个体」之间插入阅读进度卡，已登录时显示，点击跳转目录。
---
### P2：我的页增加「编辑」入口 ✅
**设计稿要求**：我的页头像资料卡片增加「编辑」图标，点击进入**个人资料展示页**（profile-show）
**已完成**：在 profile-name-row 增加「编辑」按钮，点击进入 profile-show，展示页内可再进 profile-edit。
---
### P3：代付功能闭环 ✅
**已完成**：
1. **后端**：`GET /api/miniprogram/gift/link?userId=` 返回 path、ref、scene
2. **小程序**：gift-link 页 loadGiftLink 对接真实 API
**已完成**：
3. **阅读页**：分享操作区「代付分享」按钮 + 付费墙「找好友代付」+ 代付分享弹窗（复制链接/分享给好友，path 带 gift=1）
---
### P4：目录页与设计稿对齐（可选）
**设计稿**：免费/NEW/¥1 标签、找伙伴图标高亮
**当前**：chapters 页已有篇章折叠，标签与找伙伴状态需核对
---
## 三、保护区域（调整时勿动）
| 模块 | 文件 | 说明 |
|------|------|------|
| @/# 标签 | contentParser.js、read.js、read.wxml | mention、linkTag 解析与点击 |
| 分销 | app.js、read.js、vip.js、match.js、referral/* | referralCode、bind、visit |
| 支付 | read.js、vip.js、wallet.js | pay、consume、balance |
---
## 四、建议执行顺序
```
1. 首页补充阅读进度（P1，仅改 index，不动支付/分销）
2. 我的页编辑入口（P2，仅改 my.wxml + 跳转逻辑）
3. 代付后端接口 + gift-link 对接（P3）
4. 阅读页代付分享（P3，可选）
```
---
## 五、已完成（无需再改）
- 代付链接：后端 gift/link 接口 + gift-link 对接 + 阅读页代付分享入口
- navigateToMiniProgramAppIdList 配置
- 余额体系、埋点、wallet、VIP 余额支付
- 首页精选/最新展开、搜索 book/hot?limit=50
- 我的页余额入口、代付链接入口（界面）
- 管理端订单、用户详情余额
- 超级个体、精选推荐、最新新增布局

37
开发文档/管理端两版界面差异-新需求参考.md
View File

@@ -1,37 +0,0 @@
# 管理端两版界面差异（新需求参考）
> 更新日期：2026-03-17
**目录说明**：`new-soul/soul-admin` = **稳定版**（生产主用）；`soul-admin/`（根目录）= 根目录版
---
## 一、稳定版（new-soul）有、根目录版无（以稳定版为准）
| 页面/组件 | 界面差异 | 说明 |
|-----------|----------|------|
| **系统设置** | 审核模式 auditMode、aboutEnabled、API 文档 Tab、OSS 完整 | 稳定版更全 |
| **Dashboard** | 代付金额 giftedTotal、订单可展开 4→10、埋点统计 | 稳定版有 |
| **用户编辑** | 编辑时手机号禁用 | 稳定版更安全 |
| **Layout** | 鉴权逻辑优化 | 稳定版优化 |
---
## 二、根目录版有、稳定版无（迁移时需保留）
迁移时若以稳定版为基准合并，以下能力需从根目录版**带入**，不可丢失。
| 页面/组件 | 界面差异 | 说明 |
|-----------|----------|------|
| **用户详情** | 基础信息 Tab 有「当前余额」卡片 | 对应小程序 wallet、余额支付 |
| **订单页** | 支付方式（微信/余额/支付宝）、代付标识、代付人 | 对应小程序 gift-pay、余额购买 |
| **用户列表** | RFM 排序模式、RFM 分值列 | 运营分析用（依赖后端 users/rfm） |
| **用户列表** | 用户旅程总览 Tab | 依赖后端 users/journey-stats |
| **内容管理** | 关联小程序管理（LinkedMpPage） | 多小程序场景 |
| **全局** | RechargeAlert 充值告警条 | 商户号余额不足提示 |
---
## 三、与需求评估的关系
详见《新版管理端迁移到稳定版-需求评估.md》。迁移时以**稳定版（new-soul/soul-admin）为基准**，从根目录版带入用户余额、订单支付方式、RechargeAlert、LinkedMp 等能力。

89
开发文档/管理端迁移分析-基于小程序功能.md
View File

@@ -1,89 +0,0 @@
# 管理端迁移分析：基于现有小程序功能
> 乘风整理。以 miniprogram 当前功能为基准，分析稳定版与新版管理端的差异及迁移建议。
> 更新日期：2026-03-17
---
## 一、背景与范围
| 项目 | 路径 | 说明 |
|------|------|------|
| **稳定版管理端** | `new-soul/soul-admin/` | 生产主用 |
| **根目录版** | `soul-admin/` | 迁移对照 |
| **分析基准** | miniprogram 当前页面与接口（app.json、以界面定需求.md） |
**迁移方向**：新版 → 稳定版。分析目标：**以稳定版真实需求为基准，评估新版迁移时的保留项与吸纳项**。详见《新版管理端迁移到稳定版-需求评估.md》。
---
## 二、稳定版 vs 新版 差异对比
| 能力 | 稳定版 soul-admin | 新版 new-soul/soul-admin |
|------|-------------------|---------------------------|
| **用户详情-余额** | ✅ 有 balanceData、余额 Tab、`GET /api/admin/users/:id/balance` | ❌ 无余额展示 |
| **订单-支付方式** | ✅ 展示 wechat/balance/alipay、代付人 payerNickname | ❌ 仅 wechat/alipay，无 balance、无代付 |
| **用户规则** | ✅ 规则配置 Tab、user-rules CRUD | ✅ 已有 |
| **超级个体/VIP** | ✅ 有 | ✅ 有 |
| **用户详情-VIP 表单** | ✅ 含 isVip、vipExpireDate、vipRole 等完整字段 | ⚠️ 有 vipForm，但 payload 不含 isVip/vipExpireDate 等（handleSave 仅保存基础字段，handleSaveVip 单独保存 VIP） |
| **LinkedMp 页** | 稳定版有 `/linked-mp` | 新版无（需确认是否需迁移） |
| **ApiDocs 页** | 单页 api-doc | 新版多 api-docs 页 |
---
## 三、小程序功能 → 管理端能力对照
以下按 miniprogram 核心能力，逐项对照管理端是否已覆盖（以稳定版为基准）。
| 小程序能力 | 小程序页面/接口 | 管理端需支持 | 稳定版 | 新版 |
|------------|-----------------|--------------|:------:|:----:|
| **余额体系** | wallet、read/vip 余额支付 | 用户余额查看、交易记录 | ✅ | ❌ |
| **代付（美团式）** | gift-pay/detail、list | 订单页展示代付信息 | ✅ | ❌ |
| **规则引擎** | ruleEngine | 用户规则 CRUD | ✅ | ✅ |
| **VIP** | vip、member-detail | VIP 状态、超级个体 | ✅ | ✅ |
| **订单** | purchases、read/vip 支付 | 订单列表、支付方式、退款 | ✅ | ⚠️ 缺余额/代付 |
| **提现、分销、找伙伴、导师、内容** | 对应页面 | 已有 | ✅ | ✅ |
---
## 四、迁移时稳定版必须保留（新版缺失则从稳定版带入）
### 4.1 用户详情 - 余额展示
| 项 | 说明 |
|----|------|
| **目标** | 迁移后稳定版保留「当前余额」卡 |
| **接口** | `GET /api/admin/users/:id/balance` |
| **实现** | 稳定版 UserDetailModal 已有，合并时不可覆盖 |
### 4.2 订单页 - 支付方式与代付
| 项 | 说明 |
|----|------|
| **目标** | 迁移后稳定版保留 balance、代付人展示 |
| **接口** | `GET /api/admin/orders` 已返回 |
| **实现** | 稳定版 OrdersPage 已有，合并时不可覆盖 |
### 4.3 LinkedMp、RechargeAlert
稳定版 ContentPage 嵌入 LinkedMpPage、Layout 有 RechargeAlert，合并时保留。
---
## 五、稳定版待补充（两版共用）
| 优先级 | 项 | 说明 |
|:------:|----|------|
| P2 | 用户余额人工调整 | 用户详情增加「调整余额」入口，需 soul-api 新增 `POST /api/admin/users/:id/balance/adjust` |
| P2 | 代付列表页 | 新增代付请求维度管理，需 soul-api 新增 `GET /api/admin/gift-pay-requests` |
| P3 | 埋点看板 | 可选，低优先级 |
---
## 六、总结
| 类型 | 说明 |
|------|------|
| **新版迁移** | 用户详情余额、订单页支付方式（余额/代付）——2 项，参考稳定版实现 |
| **稳定版待补充** | 用户余额人工调整、代付列表页——2 项，两版共用后端接口 |
| **结论** | 新版管理端需从稳定版迁移余额与代付相关展示能力，接口已就绪，以 UI 与数据绑定为主。

77
开发文档/规则引擎迁移-影响分析.md
View File

@@ -1,77 +0,0 @@
# 规则引擎迁移 - 影响分析
> 乘风严格分析，确保不破坏现有功能。2026-03-17
---
## 一、现有逻辑梳理
### 1. 完善头像逻辑（将被吸收）
| 调用位置 | 文件 | 行号 | 触发时机 |
|----------|------|------|----------|
| login 成功 | app.js | 525 | 微信 code 登录成功后 |
| getOpenId 登录 | app.js | 587 | getOpenId 时接口返回 user |
| loginWithPhone | app.js | 641 | 手机号登录成功后 |
**逻辑**：`_ensureProfileCompletedAfterLogin(user)` → 若头像/昵称未完善 → Toast + `navigateTo` avatar-nickname
### 2. 规则引擎将接管
- **场景**：after_login（对应 trigger「注册」）
- **规则**：checkRule_FillAvatar
- **行为**：Modal（去完善/稍后再说）→ 确认则 navigateTo
- **目标页**：改为 avatar-nickname（与稳定版一致）
### 3. 破坏性风险点
| 风险 | 条件 | 后果 | 缓解 |
|------|------|------|------|
| 规则 API 404 | 后端未部署 user-rules | loadRules 返回 []，无引导 | 先部署后端 |
| user_rules 表空 | 无「注册」规则 | isRuleEnabled 为 false，无引导 | SQL 脚本插入默认规则 |
| globalData 不兼容 | readCount/hasPurchasedFull | 部分规则不触发 | ruleEngine 内做兼容 |
| 目标页错误 | target=profile-edit | 跳错页 | 改为 avatar-nickname |
---
## 二、兼容性修改清单
### ruleEngine.js
| 修改项 | 原值 | 新值 | 原因 |
|--------|------|------|------|
| checkRule_FillAvatar target | profile-edit | avatar-nickname | 稳定版用 avatar-nickname |
| readCount | globalData.readCount | getReadCount() | 稳定版无 readCount |
| hasPurchasedFull | globalData.hasPurchasedFull | globalData.hasFullBook | 稳定版用 hasFullBook |
### 空规则兜底
当 `rules` 为空时，after_login 不触发 → 用户无引导。**方案**：SQL 脚本插入默认「注册」规则，部署时执行。
---
## 三、执行顺序（防破坏）
1. **soul-api**：新增 GET /api/miniprogram/user-rules
2. **soul-api**：确保 user_rules 表存在（GORM AutoMigrate）
3. **SQL**：插入默认「注册」规则（幂等）
4. **miniprogram**：复制 ruleEngine.js 并做兼容
5. **miniprogram**：app.js 替换 _ensureProfileCompletedAfterLogin 为 checkAndExecute
6. **miniprogram**：match.js 接入 after_match
---
## 四、回滚方案
若规则引擎导致问题：
1. app.js：恢复 _ensureProfileCompletedAfterLogin 调用，注释 checkAndExecute
2. match.js：移除 checkAndExecute 调用
3. 规则引擎仅新增不删，可随时停用
---
## 五、部署步骤（2026-03-17 已执行）
1. **soul-api**：重启后 AutoMigrate 会创建 user_rules 表
2. **数据库**：执行 `soul-api/scripts/add-user-rules-default.sql` 插入默认「注册」规则
3. **miniprogram**：已接入 ruleEngine，无需额外配置

127
开发文档/迁移完成度与待办清单.md
View File

@@ -1,127 +0,0 @@
# 迁移完成度与待办清单
> 乘风吸收当前经验与交互后整理。基于 new-soul 迁移方案、稳定版适配清单、agent 经验库。
> 更新日期：2026-03-17（乘风同步进度）
---
## 一、已迁移完成（✅）
### 新版迁移方案（R1～R11）
| 需求 | 说明 | 状态 |
|------|------|:----:|
| R1～R4 | 余额体系：充值、消费、交易记录、退款 | ✅ |
| R5 | 我的页「我的余额」入口 | ✅ |
| R2 | 阅读页余额购买（章节/全书） | ✅ |
| R6～R8 | 首页精选/最新展开、按热度、book/hot?limit=50 | ✅ |
| R9～R10 | 代付（我的代付 + 阅读页代付分享） | ✅ |
| R11 | 埋点 trackClick | ✅ |
| VIP 余额 | VIP 页支持余额购买 | ✅ |
| 管理端 | 订单支付方式、用户详情余额 | ✅ |
### 稳定版适配（P1～P3）
| 项 | 说明 | 状态 |
|----|------|:----:|
| P1 | 首页「阅读进度」卡 | ✅ |
| P2 | 我的页「编辑」入口 → profile-show | ✅ |
| P3 | 代付功能闭环（美团式：读页→代付页→分享） | ✅ |
### 代付美团式（2026-03-17）
| 项 | 说明 | 状态 |
|----|------|:----:|
| 读页入口 | 创建请求 → 跳转代付详情页 | ✅ |
| 代付详情页 | 发起人「分享给好友」/ 好友「帮他付款」双态 | ✅ |
| PayNotify | beneficiaryUserID 权益归发起人 | ✅ |
| 订单与分佣 | 并入 orders、分销 | ✅ |
### 体验优化（2026-03-17）
| 项 | 说明 | 状态 |
|----|------|:----:|
| 目录页 | book/parts 加载 loading | ✅ |
| 首页最新新增 | 默认 5 条、折叠，点击展开 | ✅ |
### 代付营销与体验（近期）
| 项 | 说明 | 状态 |
|----|------|:----:|
| 代付页营销 | 章节标题+内容预览（20%），吸引代付人 | ✅ |
| 我的代付列表 | 点击卡片进入代付详情页 | ✅ |
| 代付页布局 | 页面协调、间距统一、视觉统一 | ✅ |
---
## 二、未迁移 / 待办
### 明确暂不处理
| 项 | 说明 | 决策 |
|----|------|------|
| 导师预约支付 | mentor-detail 预约成功后调起支付 | 暂不处理，保持与 new-soul 一致，弹「请联系客服」 |
### 边缘场景（可选）
| 项 | 说明 | 优先级 |
|----|------|:------:|
| ~~阅读页代付直链~~ | **已禁止**：gift=1&ref 打开 read 页时直接 redirectTo 代付页，统一在代付页代付 | ✅ |
| ~~阅读统计埋点~~ | chapters/read 页补充 trackClick（篇章展开、章节点击、搜索、分享、购买） | ✅ |
| ~~目录页「每日新增」~~ | latest-chapters 拉取 + 每日新增区块展示 | ✅ |
| ~~P4 目录页与设计稿~~ | 免费/NEW/¥1/增值标签、每日新增区块 | ✅ |
### 稳定版已有（2026-03-17 分析）
| 项 | 说明 | 与 new-soul 对比 |
|----|------|-----------------|
| ~~富文本渲染~~ | 按稳定版处理，用户已落地 | ✅ |
| ~~打包购买引导~~ | 购买 ≥3 章显示「解锁全书」按钮，两端一致 | 稳定版 = new-soul |
| ~~存客宝对接~~ | ckb/lead、index-lead、match、join 均已对接 | 稳定版更完善：限频、linkTag ckb |
### 搁置项（无）
原搁置项富文本/打包引导/存客宝均已确认稳定版已有，无新增搁置。
### 新版细节未迁移（2026-03-17 乘风分析）
| 项 | 说明 | 优先级 |
|----|------|:------:|
| 运行时配置 | getRuntimeBootstrapConfig、extConfig/Storage、默认生产 baseUrl | P0 |
| loadMpConfig 扩展 | apiDomain、auditMode、supportWechat | P0 |
| auditMode 审核模式 | index/my/wallet/read 支付相关 UI 按审核隐藏 | P1 |
| request timeout | app.request 增加 timeout | P2 |
详见 `开发文档/新版迁移-功能差异清单.md`（小程序）、`开发文档/新版迁移-管理端功能差异清单.md`（管理端）。
### 规则引擎（2026-03-17 已迁移）
| 项 | 状态 |
|----|:----:|
| ruleEngine.js | ✅ 已接入，兼容 readCount/hasFullBook |
| GET /api/miniprogram/user-rules | ✅ soul-api 已新增 |
| after_login（完善头像） | ✅ 吸收 _ensureProfileCompletedAfterLogin，跳 avatar-nickname |
| after_match（匹配后引导） | ✅ match.js reportMatch 后触发 |
| user_rules 表 + 默认规则 | ✅ AutoMigrate + add-user-rules-default.sql |
### 埋点（已补齐 2026-03-17）
| 项 | 当前状态 |
|----|----------|
| **埋点 trackClick** | 已接入：index、my、match、vip、search、referral、chapters、read、wallet |
---
## 三、文档待更新
| 文档 | 待更新内容 |
|------|------------|
| 稳定版-小程序与API对比.md | wallet 已迁移，可更新为 ✓ |
---
## 四、总结
**核心迁移已全部完成**：余额体系、代付美团式、埋点、首页/目录/阅读/VIP 相关功能均已落地。
**剩余**：导师预约支付（暂不处理）；埋点待补充（见上表）。规则引擎已迁移，富文本、打包购买引导、存客宝对接均已确认稳定版已有。