docs: 更新业务模块智能体目录及文件结构，优化文档内容

.cursor/README.md

@@ -0,0 +1,21 @@
+# Soul 创业派对 · `.cursor` 速览
+
+## 路径约定
+
+- 所有 Skill、会议纪要、agent 经验路径均以 **本 Git 仓库根** 为基准（与 `miniprogram/`、`soul-api/` 同级）。
+- Rules 中「必须 Read」的路径形如 `.cursor/skills/{name}/SKILL.md`。
+- Python 脚本统一可用 `config/paths.py` 的 `ROOT`、`SKILLS`、`AGENT`、`MEETING`。
+
+## 入口优先级
+
+1. **三端开发**：`rules/soul-project-boundary.mdc` + `skills/*-dev` / `change-checklist`。
+2. **派对 AI**：若存在仓库根目录 `派对AI/`，可补充读其 `BOOTSTRAP.md`；与 `.cursor` 冲突时 **以 `.cursor` 三端约定为准**（见 `rules/party-ai-dev.mdc`）。
+
+## 噪声与体积
+
+- `meeting/`、`agent/`：历史纪要/evolution 会增多，属正常；需要时可按月归档到子目录或压缩备份。
+- `scripts/db-exec/node_modules/`：已在 `.cursorignore` 与 `.gitignore` 中排除，首次使用在 `db-exec` 下执行 `npm install`。
+
+## 文档
+
+- 架构与迭代说明：`docs/cursor规则与架构分析及优化建议.md`

.cursor/agent/开发助理/README.md

@@ -0,0 +1,12 @@
+# 开发助理（橙子）
+
+> 规则进化执行、通用经验池、项目索引。经验：`.cursor/agent/开发助理/evolution/`
+
+## 目录结构
+
+| 目录 | 说明 |
+|------|------|
+| evolution/ | 通用经验池 |
+| archived/ | 已归档经验 |
+| script/ | 规则进化 bat 入口 |
+| 项目索引/ | 各角色开发进度索引 |

.cursor/agent/开发助理/evolution/2026-02-26.md

@@ -0,0 +1,5 @@
+# 2026-02-26 | 助理橙子经验
+
+> 本日经验条目，格式：类型 | 摘要 | 升级 Skill
+
+---

.cursor/agent/开发助理/evolution/2026-03-11.md

@@ -0,0 +1,7 @@
+# 开发助理 经验记录 - 2026-03-11
+
+## 会议收尾：开发团队对齐业务逻辑与以界面定需求
+
+- 用户提出「结束会议」后执行会议收尾：生成会议纪要、各角色经验入库、更新项目索引与会议记录索引。
+- 纪要：`.cursor/meeting/2026-03-11_开发团队对齐业务逻辑与以界面定需求会议收尾.md`。
+- 各角色经验已写入：团队、产品经理、后端工程师、管理端开发工程师、小程序开发工程师 evolution/2026-03-11.md；项目索引（团队、产品、后端、管理端、小程序、助理橙子）开发进度表已追加 2026-03-11。

.cursor/agent/开发助理/evolution/2026-03-16-交互习惯分析.md

@@ -0,0 +1,91 @@
+# 用户交互习惯分析（基于 agent-transcripts 抽样）
+
+> 乘风发起，读取 97 个 agent 会话记录，抽样分析后总结。用于优化 agent 响应策略与 Skill 设计。
+
+---
+
+## 一、角色与触发词使用习惯
+
+| 触发词/角色 | 使用场景 | 期望动作 |
+|-------------|----------|----------|
+| **乘风** | 开会、同步进度、协调开发、总结经验 | 老板分身主持，协调各角色 |
+| **开会** | 需求评审、方案讨论、进度同步 | 按 team-meeting SKILL 主持多角色会议 |
+| **吸收经验** | 功能完成、讨论完毕 | 经验入库 + Skill 升级 + 同步需求文档 |
+| **橙子 / 小橙** | 记录、同步文档、会议收尾 | 文档同步、纪要生成、索引更新 |
+| **加个需求：xxx** | 新增功能 | 产品经理三端分析 → 功能规划 → 指派 |
+| **变更完成 / 检查一下** | 代码改完 | 过 change-checklist 三端关联检查 |
+
+---
+
+## 二、表达方式偏好
+
+### 1. 直接点名角色
+- 如：「小程序工程师」「后端工程师」「管理端工程师」「测试工程师」
+- 期望：agent 按该角色 Skill 执行，不混用其他端逻辑
+
+### 2. @ 文件引用
+- 如：@new-soul、@scripts、@soul-admin、@开发文档
+- 期望：agent 读取并理解引用内容，作为上下文执行任务
+
+### 3. 任务导向、先分析再实现
+- 典型句式：「帮我对比」「整理出迁移清单」「分析有没有逻辑盲点」「从经营角度看看」
+- 期望：先出方案/文档，再写代码；不直接动手改
+
+### 4. 图片辅助反馈
+- 经常截图 + 文字描述问题（如「@匹配有问题」「弹窗太大」「封面图要长这样」）
+- 期望：agent 结合截图理解 UI/交互问题，给出针对性修改
+
+---
+
+## 三、工作流程偏好
+
+| 阶段 | 习惯 | 说明 |
+|------|------|------|
+| **需求** | 以需求驱动、以界面定需求 | 不凭空加功能，需求与实现可追溯 |
+| **分析** | 先对比、出方案、写文档 | 迁移清单、逻辑盲点、技术协调、经营建议 |
+| **实现** | 小步迭代、可读性优先 | 函数单一职责，避免深层嵌套 |
+| **验收** | 测试 → 吸收经验 → 同步文档 | 闭环：经验入库、Skill 升级、需求汇总更新 |
+| **会议** | 开会 → 各角色发言 → 决议 → 橙子总结 | 会议结束触发收尾流程 |
+
+---
+
+## 四、沟通风格
+
+- **简洁**：如「帮我处理」「帮我测试一下」「修复」
+- **追问细节**：如「界面有什么变化」「有逻辑盲点吗」「从经营角度看看」
+- **强调合理性**：如「产品经理要根据实际情况判断，不能随意增加管理列表」
+- **确认后执行**：如「先帮我对比」「整理出迁移清单」——先出结果再决定是否实现
+
+---
+
+## 五、技术偏好（Soul 项目）
+
+- **三端隔离**：小程序只调 `/api/miniprogram/*`，管理端只调 `/api/admin/*`、`/api/db/*`
+- **存客宝对接**：Person、LinkTag、ckb_api_key、planType、sceneId、status 等参数约定
+- **测试规范**：scripts/test 目录，miniapp / web / process 分类，pytest + requests，运行前显式提示测试环境
+
+---
+
+## 六、反馈与确认习惯
+
+| 用户表达 | 触发动作 |
+|----------|----------|
+| 「搞定了」「可以了」「解决了」 | 经验自动收集（老板分身-索引.mdc） |
+| 「会议结束」「散会」 | 助理橙子会议收尾 |
+| 「吸收经验」「同步到需求文档」 | 经验入库 + 需求汇总更新 |
+| 「不要记录」「不用沉淀」 | 不触发经验入库 |
+
+---
+
+## 七、Agent 响应建议
+
+1. **先理解再动手**：用户说「帮我xxx」时，先确认范围、出方案，再写代码
+2. **按角色执行**：用户点名角色时，必须 Read 对应 Skill，按规范执行
+3. **文档先行**：迁移、重构类任务，先出清单/分析文档，再实现
+4. **闭环收尾**：功能完成时主动提示「可以说吸收经验同步到文档」
+5. **图片理解**：用户发截图时，结合截图分析问题，不只看文字
+
+---
+
+**来源**：agent-transcripts 抽样（约 15 个会话），结合经验清单与项目索引交叉验证。  
+**适用**：开发助理、老板分身、各角色 agent 的响应策略优化。

.cursor/agent/开发助理/evolution/2026-03-17.md

@@ -0,0 +1,9 @@
+# 开发助理 经验记录 - 2026-03-17
+
+## 会议收尾（2026-03-17）
+
+- **纪要**：2026-03-17_会议收尾-源码优化完成与测试流程定稿.md
+- **经验入库**：各角色 evolution 已追加收尾经验
+- **项目索引**：后端、管理端、小程序、测试、助理橙子已更新
+- **会议索引**：README.md 已追加
+- **开发文档**：运营与变更第十七部分已追加

.cursor/agent/开发助理/evolution/2026-03-18.md

@@ -0,0 +1,15 @@
+# 开发助理 经验记录 - 2026-03-18
+
+## 开发文档归档整理（统一入口与索引一致性）
+
+### 发现与修复
+- `开发文档/README.md` 索引引用了 `开发文档/10、项目管理/项目落地推进表.md`，但该文件缺失。
+- 已补齐：新建 `开发文档/10、项目管理/项目落地推进表.md`，用于记录里程碑、风险与下一步。
+
+### 归档建议（持续维护规则）
+- 需求基准：`以界面定需求.md`
+- 需求清单：`需求汇总.md`
+- 决议与变更：`运营与变更.md`
+- 执行层推进：`项目落地推进表.md`
+- 每次变更后按上述 4 份文档联动更新，避免“清单/决议/执行层”脱节。
+

.cursor/agent/开发助理/evolution/2026-03-21-MBTI头像C端全链路兜底.md

@@ -0,0 +1,13 @@
+# 2026-03-21 MBTI 头像 C 端全链路兜底
+
+## 问题
+系统设置瘦身与 MBTI 映射迁到用户管理后，需在小程序多页面与匹配接口统一「无微信头像 → MBTI 映射」行为，避免仅海报单点生效。
+
+## 做法
+- 新增 `miniprogram/utils/mbtiAvatar.js`（`resolveAvatarWithMbti`）；`app.resolveAvatarWithMbti` 封装全局 map。
+- 我的页 `profileAvatarDisplay`；资料编辑 `avatarPreviewUrl`；profile-show、member-detail、referral 海报复用同一逻辑。
+- 后端 `match.go`：`avatar` 为空时用 `getMbtiAvatar`；响应增加 `mbti` 字段；找伙伴卡片 wxml 增加无图占位。
+- 管理端 `MbtiAvatarsManager` 补充 downloadFile 域名说明。
+
+## 可复用规则
+配置驱动展示：公开 `GET /api/miniprogram/config/mbti-avatars` + 本地短时缓存；业务侧只调 `resolveAvatarWithMbti`，避免重复拼接 baseUrl。

.cursor/agent/开发助理/evolution/2026-04-14.md

@@ -0,0 +1,6 @@
+# 开发助理（橙子）经验记录 - 2026-04-14
+
+## 吸收沉淀：各智能体同步开发需求
+
+- 触发：用户「各智能体吸收经验沉淀，同步开发需求」→ 执行 `assistant-doc-sync` §5 + 文档同步：补齐仓库根 `开发文档/` 骨架，写入 `需求汇总.md`、`运营与变更.md`。
+- 同步 `经验清单.md`、`智能体-技能-经验总索引.md`、各角色 `evolution/索引.md`、项目索引一行、`sync-log`；轻量升级 `role-flow-control` §1.2（小程序逆推闭环）。

.cursor/agent/开发助理/evolution/2026-04-15.md

@@ -0,0 +1,7 @@
+# 开发助理 经验记录 - 2026-04-15
+
+## 联网吸收：编程思维写入智能体
+
+- **触发**：用户要求联网吸收优秀编程思维并沉淀到智能体。
+- **动作**：检索垂直切片、追踪弹、AI 编码验证、SRE 无责复盘等公开论述；写入 `agent/团队/evolution/2026-04-15.md`；在 `role-flow-control/SKILL.md` 增加 **§1.3 智能体协作提要**；更新 `经验清单`、`智能体-技能-经验总索引`、团队/助理橙子项目索引、`sync-log`。
+- **注意**：外链为思想参考；执行顺序仍以本仓库 `.cursor/rules` 与各主 Skill 为准。

.cursor/agent/开发助理/evolution/索引.md

@@ -0,0 +1,10 @@
+# 开发助理 经验索引（通用）
+
+> 无明确角色归属的通用经验。助理橙子执行时可按需参考。
+
+| 日期 | 摘要 | 文件 |
+|------|------|------|
+| 2026-03-21 | MBTI 头像小程序全链路兜底 + 匹配接口回填 | 2026-03-21-MBTI头像C端全链路兜底.md |
+| 2026-03-16 | 用户交互习惯分析（基于 agent-transcripts） | 2026-03-16-交互习惯分析.md |
+| 2026-04-14 | 各智能体吸收经验沉淀：开发文档骨架、经验清单、role-flow §1.2 | 2026-04-14.md |
+| 2026-04-15 | 联网吸收编程思维：团队 evolution、role-flow §1.3、索引与 sync-log | 2026-04-15.md |

.cursor/agent/开发助理/script/一键-全部.bat

@@ -0,0 +1,46 @@
+@echo off
+chcp 65001 >nul
+set PYTHONUTF8=1
+set PYTHONIOENCODING=utf-8
+cd /d "%~dp0..\..\..\.."
+:menu
+cls
+echo ========================================
+echo   开发助理 - 规则进化 一键操作
+echo ========================================
+echo.
+echo 1. 添加经验（从 stdin 粘贴 JSON）
+echo 2. 列出经验池
+echo 3. 执行进化（归档 + 可选应用新规则）
+echo 4. 退出
+echo.
+set /p choice=请选择 (1-4): 
+if "%choice%"=="1" goto add
+if "%choice%"=="2" goto list
+if "%choice%"=="3" goto evolve
+if "%choice%"=="4" exit
+goto menu
+
+:add
+echo.
+echo 请粘贴 AI 输出的 JSON，按 Ctrl+Z 回车结束：
+python .cursor\scripts\evolution.py add --stdin
+pause
+goto menu
+
+:list
+echo.
+python .cursor\scripts\evolution.py list
+pause
+goto menu
+
+:evolve
+echo.
+set /p RULE_FILE=新规则文件路径（留空则仅归档）: 
+if "%RULE_FILE%"=="" (
+    python .cursor\scripts\evolution.py evolve --archive
+) else (
+    python .cursor\scripts\evolution.py evolve --archive --rule "%RULE_FILE%"
+)
+pause
+goto menu

.cursor/agent/开发助理/script/一键-列出经验池.bat

@@ -0,0 +1,6 @@
+@echo off
+chcp 65001 >nul
+cd /d "%~dp0..\..\..\.."
+echo 开发助理 - 列出经验池
+python .cursor\scripts\evolution.py list
+pause

.cursor/agent/开发助理/script/一键-执行进化.bat

@@ -0,0 +1,6 @@
+@echo off
+chcp 65001 >nul
+cd /d "%~dp0..\..\..\.."
+echo 开发助理 - 执行进化（归档经验池）
+python .cursor\scripts\evolution.py evolve --archive
+pause

.cursor/agent/开发助理/script/一键-添加经验.bat

@@ -0,0 +1,12 @@
+@echo off
+chcp 65001 >nul
+set PYTHONUTF8=1
+set PYTHONIOENCODING=utf-8
+cd /d "%~dp0..\..\..\.."
+echo 开发助理 - 添加经验
+echo.
+echo 请将 AI 输出的 JSON 粘贴到下方，按 Ctrl+Z 回车结束：
+echo.
+python .cursor\scripts\evolution.py add --stdin
+echo.
+pause

.cursor/agent/开发助理/经验清单.md

@@ -0,0 +1,68 @@
+# 开发团队经验清单
+
+> 跨角色经验索引。经验在 `agent/*/evolution/`，项目索引在 `agent/开发助理/项目索引/`。
+
+---
+
+## 各角色经验库
+
+| 角色 | 项目索引 | 按日经验 |
+|------|----------|----------|
+| 小程序 | [agent/开发助理/项目索引/小程序.md](./项目索引/小程序.md) | agent/小程序开发工程师/evolution/ |
+| 管理端 | [agent/开发助理/项目索引/管理端.md](./项目索引/管理端.md) | agent/管理端开发工程师/evolution/ |
+| 后端 | [agent/开发助理/项目索引/后端.md](./项目索引/后端.md) | agent/后端工程师/evolution/ |
+| 产品 | [agent/开发助理/项目索引/产品.md](./项目索引/产品.md) | agent/产品经理/evolution/ |
+| 测试 | [agent/开发助理/项目索引/测试.md](./项目索引/测试.md) | agent/软件测试/evolution/ |
+| 助理橙子 | [agent/开发助理/项目索引/助理橙子.md](./项目索引/助理橙子.md) | agent/开发助理/evolution/ |
+| 团队（跨角色共享） | [agent/开发助理/项目索引/团队.md](./项目索引/团队.md) | agent/团队/evolution/ |
+
+---
+
+## 索引表
+
+| 日期 | 角色 | 类型 | 升级 Skill | 摘要 |
+|------|------|------|------------|------|
+| 2026-02-27 | 小程序、团队 | 最佳实践 | SKILL-小程序开发 §6、SKILL-管理端开发 §4.1 | 输入框 padding 用 view/div 包裹 |
+| 2026-02-28 | 小程序、管理端 | 最佳实践 | miniprogram §6、admin §4.1 | input 边距口诀「外边包 view、内部 width 100%」；match 弹窗已修正 |
+| 2026-03-03 | 小程序 | 最佳实践 | miniprogram §8 | 我的页面卡片区边距 16rpx，个人中心类页面布局规范 |
+| 2026-03-10 | 小程序 | 最佳实践 | miniprogram-dev SKILL §my | my.js 阅读统计改为后端接口（loadDashboardStats），禁止用随机数时间/标题占位 |
+| 2026-03-10 | 后端 | bug 修复 | api-dev SKILL | 聚合接口三处修复：recentChapters 去重、totalReadMinutes 最小1分钟、DB 错误返回 500 |
+| 2026-03-10 | 团队 | 方法论 | - | 新旧版代码对比：以功能完整性为基准，批量 diff + 分类取舍，不以日期判优劣 |
+| 2026-03-10 | 管理端 | 最佳实践 | admin-dev SKILL §toast | Toast 通知系统落地：utils/toast.ts 纯原生实现，全系统 18 文件 alert → toast 批量替换 |
+| 2026-03-12 | 管理端 | bug 修复 | admin-dev SKILL §ts | ContentPage TypeScript 严格类型：可选字段 ?? 兜底、接口补字段、API 映射、setState 传参 |
+| 2026-03-12 | 团队 | 架构/设计 | - | 密钥/token 设计：关联小程序 key、@ 人物 token；不暴露真实密钥、服务端兑换 |
+| 2026-03-12 | 后端 | 最佳实践 | mysql-direct SKILL | persons token 字段；Model 新增字段后需执行 ALTER 迁移脚本 |
+| 2026-03-12 | 管理端 | 设计落地 | - | 关联小程序存 key、@ 人物 id=token；链接标签与 PersonItem 约定 |
+| 2026-03-12 | 小程序 | 设计落地 | - | contentParser mpKey/token；onLinkTagTap、onMentionTap 传 key/token 兑换 |
+| 2026-03-10 | 后端 | bug 修复 | api-dev SKILL | chapters 表新增 hot_score 列，修复 1054 Unknown column 错误；DB 变更 SOP：ALTER→model→重启 |
+| 2026-03-10 | 团队 | 方法论 | - | DB 变更 SOP + Toast 批量替换方法论（脚本替换后必须人工复查 toast.info 语义） |
+
+| 2026-03-12 | 后端、团队 | 业务规则 | api-dev SKILL、team three-tier-arch | 9.9 买断统一由后端折叠为 hasFullBook/has_full_book，小程序和管理端只认该信号；可通过用户资料开关 OR 订单实现赠送全书 |
+| 2026-03-13 | 小程序、后端、团队 | 业务规则 | api-dev SKILL、miniprogram-dev SKILL、three-tier-arch SKILL | 文章详情预览统一由后端按 50% 截取，小程序按 accessState 使用预览/全文，外层 content 与 data.content 始终一致以避免泄露全文 |
+| 2025-03-14 | 小程序 | 最佳实践 | miniprogram-dev SKILL §10 | 阅读页文本长按选中复制：text 组件 user-select（selectable 已废弃），正文/标题/预览均加 user-select |
+| 2026-03-14 | 后端、管理端、小程序、团队 | 业务规则/bug 修复 | - | 内容排名算法修正（排名分公式）；保存权重后 loadRanking 刷新；我的页设置隐藏；资料引导场景梳理 |
+| 2026-03-16 | 软件测试 | 知识沉淀 | testing SKILL | scripts 目录与测试关联：本地启动.sh 联调必备、飞书脚本非回归范围、soul-api/scripts 与根 scripts 区分 |
+| 2026-03-16 | 软件测试 | 目录约定 | testing SKILL §5 | scripts/test：miniapp 小程序接口测试、web 管理端测试；测试工程师在此编写用例 |
+| 2026-03-16 | 软件测试 | 目录约定 | testing SKILL §5 | scripts/test/process：流程测试，跨端多接口串联（下单→支付→分润等） |
+| 2026-03-16 | 软件测试 | 配置约定 | testing SKILL | pytest 架构、配置从 soul-api/.env* 读取、SOUL_TEST_ENV 必显；运行前报告头部显示测试环境，避免误测正式库 |
+| 2026-03-16 | 小程序 | 最佳实践 | miniprogram-dev SKILL §10 | 编辑资料页分享名片：转发/朋友圈特殊处理，Canvas 绘制 5:4 封面，标题「昵称+为您分享名片」，路径 member-detail |
+| 2026-03-16 | 开发助理 | 交互习惯分析 | - | 乘风读取 agent-transcripts 抽样分析：角色触发词、表达方式、工作流程、沟通风格、技术偏好、Agent 响应建议 |
+| 2026-03-17 | 小程序、后端、团队 | 业务规则/bug 修复 | - | 代付美团式：读页→代付页→分享；PayNotify beneficiaryUserID 权益归发起人；detail 返回 initiatorUserId；目录 loading、最新新增 5 条折叠 |
+| 2026-03-17 | 小程序 | 业务规则 | - | 代付统一到代付页：gift=1&ref 打开 read 时 redirectTo 代付页，禁止在阅读页代付 |
+| 2026-03-17 | 软件测试 | 流程定稿 | testing SKILL | 功能测试流程：成功 ☑️、失败列问题、最终报告；scripts/test/功能测试流程.md、测试报告-环境与用例清单.md |
+| 2026-03-17 | 后端、团队 | 架构/最佳实践 | api-dev SKILL | Redis 缓存：parts/hot/recommended/stats/config/章节 content；容灾回退 DB；OSS 上传；/health 返回 database/redis 状态 |
+| 2026-03-18 | 小程序、团队 | 业务规则/最佳实践 | - | 分享链路兼容好友/朋友圈 singlePage：单页模式能力降级（不支付/不自动领取），引导点击底部“前往小程序”进入完整版 |
+| 2026-03-18 | 产品、后端、管理端、测试 | 文档归档/需求口径 | - | 文档归档整理：以《以界面定需求》为基准，各角色重整“功能需求+验收口径+风险点”并写入各自经验库；补齐《项目落地推进表》 |
+| 2026-04-14 | 团队、产品、后端、管理端、小程序、测试、助理橙子 | 方法论/需求同步 | role-flow-control SKILL §1.2、assistant-doc-sync 文档树说明 | 吸收沉淀：小程序逆推闭环、写死vs配置、需求汇总+运营与变更骨架；各角色 evolution/2026-04-14.md |
+| 2026-04-15 | 团队、助理橙子 | 方法论（联网） | role-flow-control SKILL §1.3 | 垂直切片、追踪弹与 AI slop 控制、验证优先、Google SRE 无责复盘；详 `agent/团队/evolution/2026-04-15.md` |
+
+---
+
+## 已吸收经验（历史）
+
+- **SetVipModal**：SKILL-管理端开发 4.1 表单弹窗
+- **vip_roles**：SKILL-API开发 3.2、SKILL-MySQL直接操作 8
+
+---
+
+**最后更新**：2026-04-15

.cursor/agent/开发助理/项目索引/README.md

@@ -0,0 +1,5 @@
+# 项目索引
+
+存放各角色子项目开发进度、状态。每角色对应一份索引。
+
+- **玩值三端汇总**：[`玩值.md`](玩值.md)（与 `开发文档/玩值/进度-看板.md` 联动）

.cursor/agent/开发助理/项目索引/产品.md

@@ -0,0 +1,41 @@
+# 产品 - 项目索引
+
+> 根据开发进度对项目做总结，保存开发进度，方便下次继续开发。**每次保存必须写日期**。
+
+---
+
+## 项目总结
+
+Soul 创业派对产品定位：面向创业者的社区/工具型小程序。核心需求文档在 `开发文档/1、需求/2026-03-20-需求.md`（主需求清单，若未入库见同目录 `需求汇总.md`），闭环结论见 `开发文档/10、项目管理/闭环与文档同步-2026-04-07.md`（若存在），临时需求/分析在 `临时需求池/`（按需创建）。
+
+---
+
+## 开发进度
+
+| 日期 | 摘要 | 状态 |
+|------|------|------|
+| 2026-02-26 | 项目索引初始化，.cursor 规则优化完成 | 已完成 |
+| 2026-02-27 | 开发进度同步会议：汇报进度，待办「资料不解锁」补充、≥3 章弹窗明确 | 已完成 |
+| 2026-02-28 | stitch_soul 需求评审：内容→会员→导师变现路径，待产品补充正式需求文档 | 待续 |
+| 2026-03-05 | 分支冲突后功能完整性分析会议：核对需求文档与实现一致性 | 待续 |
+| 2026-03-05 | 文章详情@某人加好友方案讨论：验收标准、添加好友接口 path 待确认 | 待续 |
+| 2026-03-10 | 会议：管理端迁移 Mycontent-temp，新菜单/布局与入口收敛验收口径确定 | 待续 |
+| 2026-03-11 | 以界面定需求文档建立；需求基准以《以界面定需求》为准 | 已完成 |
+| 2026-03-16 | 乘风发起例行开发进度同步 | 已完成 |
+| 2026-03-16 | 会议：new-soul 新需求与当前项目差异分析 | 已完成 |
+| 2026-03-17 | 会议：稳定版源码质量优化；验收标准功能不变、三端联调通过 | 待续 |
+| 2026-03-18 | 文档归档整理：以《以界面定需求》为基准，重整需求口径/验收点/分享 singlePage 约束，写入产品经验库 | 已完成 |
+| 2026-03-18 | 会议：超级个体开通后自动创建@人与支付前资料引导（头像+昵称） | 已完成 |
+| 2026-03-24 | 会议：开发进度同步；项目索引补齐 2026-03-19/20 及之后记录；文档同步原则确认 | 已完成 |
+| 2026-03-24 | 会议：需求与进度及三端闭环评审；规则/风控缺口清单化；VIP 支付前资料规则待拍板 | 已完成 |
+| 2026-03-31 | 会议：超级个体列表与 @ 列表融合方案（先数据互链再单页）；一期验收口径待拍板 | 待续 |
+| 2026-04-02 | 会议：工作进度与需求同步；一期融合验收口径澄清、各端索引与需求 delta 跟进 | 进行中 |
+| 2026-04-07 | 开发文档与主需求交叉同步；闭环分析落盘（主路径成立、规则/风控与纪要问题区待闭环） | 已完成 |
+| 2026-04-13 | 会议：按功能同步开发文档；功能完成=实现+文档/索引可追溯；待办见纪要问题区 | 进行中 |
+| 2026-04-14 | 吸收沉淀：新建 `开发文档/1、需求/需求汇总.md` 与 `开发文档/10、项目管理/运营与变更.md`；需求清单 SYNC/LOOP/MAINT/BACKEND 行 | 进行中 |
+
+> **格式说明**：每次开发后在此追加一行，日期格式 YYYY-MM-DD，状态用：已完成 / 进行中 / 待续 / 搁置
+
+---
+
+**最后更新**：2026-04-14

.cursor/agent/开发助理/项目索引/助理橙子.md

@@ -0,0 +1,36 @@
+# 助理橙子 - 项目索引
+
+> 根据开发进度对项目做总结，保存开发进度，方便下次继续开发。**每次保存必须写日期**。
+
+---
+
+## 项目总结
+
+助理橙子负责开发团队文档同步与经验升级。触发词：小橙/橙子/橙橙/🍊。核心流程文件：`SKILL-助理橙子-文档同步.md`。经验结构：agent/*/evolution 按角色 + 按日/按条存储 + 项目索引。
+
+---
+
+## 开发进度
+
+| 日期 | 摘要 | 状态 |
+|------|------|------|
+| 2026-02-26 | 项目索引初始化；经验库五角色目录结构搭建；SKILL 补充角色映射表与跨端写入规则 | 已完成 |
+| 2026-02-28 | .cursor 按 cursor标准模板 重构：agent 目录、config、evolution.py、meeting | 已完成 |
+| 2026-03-11 | 会议收尾：开发团队对齐业务逻辑与以界面定需求；纪要生成、各角色经验入库、项目索引与会议索引更新 | 已完成 |
+| 2026-03-16 | 乘风发起例行开发进度同步 | 已完成 |
+| 2026-03-16 | 乘风读取 agent-transcripts 分析交互习惯，总结经验并吸收 | 已完成 |
+| 2026-03-17 | 吸收需求：代付美团式流程、PayNotify 权益归属、目录 loading、最新新增 5 条折叠 → 开发文档与 agent | 已完成 |
+| 2026-03-17 | 乘风吸收经验与交互：迁移完成度与待办清单、运营与变更第十二部分 | 已完成 |
+| 2026-03-17 | 吸收新需求：代付统一到代付页（gift=1&ref redirectTo）→ 需求汇总、找朋友代付流程、运营与变更 | 已完成 |
+| 2026-03-17 | 会议收尾：新版管理端迁移到稳定版实施方案确认；纪要、各角色经验入库、项目索引更新 | 已完成 |
+| 2026-03-17 | 会议收尾：源码优化完成与测试流程定稿；纪要、经验入库、开发文档同步 | 已完成 |
+| 2026-04-02 | 会议收尾：工作进度与需求同步会；纪要、各角色 evolution、项目索引与会议索引更新 | 已完成 |
+| 2026-04-07 | 同步开发文档与主需求；新增《闭环与文档同步-2026-04-07》并更新索引、sync-log | 已完成 |
+| 2026-04-14 | 吸收经验：各角色 evolution/2026-04-14、开发文档骨架、经验清单、总索引、role-flow §1.2 | 已完成 |
+| 2026-04-15 | 联网吸收编程思维：团队 evolution/2026-04-15、role-flow §1.3、经验清单与 sync-log | 已完成 |
+
+> **格式说明**：每次开发后在此追加一行，日期格式 YYYY-MM-DD，状态用：已完成 / 进行中 / 待续 / 搁置
+
+---
+
+**最后更新**：2026-04-15

.cursor/agent/开发助理/项目索引/后端.md

@@ -0,0 +1,54 @@
+# 后端 - 项目索引
+
+> 根据开发进度对项目做总结，保存开发进度，方便下次继续开发。**每次保存必须写日期**。
+
+---
+
+## 项目总结
+
+soul-api（Go + Gin + GORM + MySQL）提供三组路由：`/api/miniprogram/*`（小程序）、`/api/admin/*` + `/api/db/*`（管理端）、`/api/payment/*`（支付回调）。微信生态通过 PowerWeChat 集成。当前核心模块：用户、订单、分销、VIP、提现、章节、配置。
+
+---
+
+## 开发进度
+
+| 日期 | 摘要 | 状态 |
+|------|------|------|
+| 2026-02-26 | 项目索引初始化，.cursor 规则优化完成 | 已完成 |
+| 2026-02-27 | 开发进度汇报：computeOrderCommission 会员分润差异化（20%/10%）已实现；vip_roles、vip_activated_at、referral_config 扩展已完成；miniprogram/admin/db 三组路由就绪 | 已完成 |
+| 2026-02-27 | 开发进度同步会议：进度已同步至开发文档，待办资料完善校验 | 已完成 |
+| 2026-02-28 | stitch_soul 需求评审：需梳理 chapter/book/vip，设计导师/预约/会员权益模型与接口 | 待续 |
+| 2026-03-05 | 分支冲突后功能完整性分析会议：在 soul-api 确认合并状态，核对 orders、distribution 接口 | 待续 |
+| 2026-03-05 | 文章详情@某人加好友方案讨论：content 内嵌 @ 标记、miniprogram 添加好友接口 | 待续 |
+| 2026-03-10 | 会议：管理端迁移 Mycontent-temp；后端接口边界不变，overview 聚合接口可选但需降级 | 待续 |
+| 2026-03-10 | 新增 GET /api/miniprogram/user/dashboard-stats：聚合阅读统计接口，含去重、min1分钟、500错误码修复 | 已完成 |
+| 2026-03-10 | chapters 表新增 hot_score 列（ALTER TABLE + model 同步），修复前端保存章节报 1054 错误 | 已完成 |
+| 2026-03-11 | users 迁移仅 VIP 身份/状态五字段，不再新增 VIP 资料列；chapters 补 hot_score；sync 脚本与 README-schema-sync 更新 | 已完成 |
+| 2026-03-12 | persons 表新增 token 字段（add-persons-token.sql）；CKBLead 用 token 兑换 ckb_api_key | 已完成 |
+| 2026-03-12 | 9.9 买断后端开关方案：users 增手动 fullbook 开关，purchase-status/check-purchased 折叠为统一 hasFullBook/has_full_book，小程序免改即支持赠送全书 | 已完成 |
+| 2026-03-13 | 文章详情预览统一与安全：previewContent 改为截取正文前 50%，findChapterAndRespond 保证外层 content 与 data.content 一致，未授权只返回预览 | 已完成 |
+| 2026-03-14 | 内容排名算法修正：computeSectionsWithHotScore 改为排名分公式（阅读/新度/付款前 N 名得分），支持手动 hot_score 覆盖 | 已完成 |
+| 2026-03-16 | 乘风发起例行开发进度同步 | 已完成 |
+| 2026-03-16 | ParseAutoLinkContent 添加 data-label；存客宝 create planType=1 sceneId=9 status=1 | 已完成 |
+| 2026-03-16 | 会议：new-soul 新需求与当前项目差异分析；content_upload.py 与 chapters 一致性待核对 | 待续 |
+| 2026-03-17 | 代付 PayNotify 权益归属修复：beneficiaryUserID（代付=发起人）；gift-pay detail 返回 initiatorUserId | 已完成 |
+| 2026-03-17 | 会议：新版管理端迁移；router 补齐 users/rfm、journey-stats、shensheshou 共 5 个；确认 ossConfig | 进行中 |
+| 2026-03-17 | 会议：稳定版源码质量优化；敏感配置生产强制校验、新增 /api/admin/user/track、AdminWithdrawTest 环境限制 | 已完成 |
+| 2026-03-17 | 会议收尾：源码优化 10 项全部完成；开发环境测试 10 通过 2 跳过 | 已完成 |
+| 2026-03-17 | 性能优化会议：Redis 缓存接入（parts/hot/recommended/stats/config/章节 content）、容灾回退 DB；OSS 上传接入；/health 返回 database/redis 状态 | 已完成 |
+| 2026-03-18 | 文档归档整理：按界面→接口→规则口径重整后端功能需求与风险点，写入角色经验库 | 已完成 |
+| 2026-03-18 | 会议：超级个体开通后自动创建@人（Person 绑定 userId 幂等）与资料完善 flags 方案 | 已完成 |
+| 2026-03-20 | 提现：审批逻辑修复、fail_reason/error_message 落库、referral_config withdrawFee/enableAutoWithdraw | 已完成 |
+| 2026-03-24 | 会议：开发进度同步；项目索引补齐；router/ossConfig 待确认 | 已完成 |
+| 2026-03-24 | 会议：三端闭环评审；提现/CKB/匹配后端校验与 errorCode 为 P0/P1 | 已完成 |
+| 2026-03-31 | 会议：超级个体与 @ 列表融合；优先扩展 vip-members 聚合 Person 关联字段 | 待续 |
+| 2026-04-02 | 会议：工作进度与需求同步；deploy 验证后提交；vip-members 聚合优先；router/ossConfig 历史待办跟进 | 进行中 |
+| 2026-04-13 | 会议：按功能同步开发文档；接口/迁移变更须标路由组与 P0/P1；文档待补齐 | 进行中 |
+| 2026-04-14 | 吸收沉淀：`需求汇总.md` 增加 BACKEND-P0 行；接口说明与迁移落文档 | 进行中 |
+| 2026-04-15 | 业务补齐：`mentor_consultation` 支付计价/回调/权益；`CKBJoin` investor 显式失败；`getStandardPrice` 增加 buyerUserID | 已完成 |
+
+> **格式说明**：每次开发后在此追加一行，日期格式 YYYY-MM-DD，状态用：已完成 / 进行中 / 待续 / 搁置
+
+---
+
+**最后更新**：2026-04-15

.cursor/agent/开发助理/项目索引/团队.md

@@ -0,0 +1,45 @@
+# 团队 - 项目索引
+
+> 跨角色共享的架构决策、业务规则、团队级经验。根据讨论进度更新，**每次保存必须写日期**。
+
+---
+
+## 项目总结
+
+Soul 创业派对全项目架构与约定：路由隔离（miniprogram/admin/db）、三端协同流程、经验按角色+按日存储、会议纪要独立存档、语义触发词驱动角色切换。
+
+---
+
+## 开发进度
+
+| 日期 | 摘要 | 状态 |
+|------|------|------|
+| 2026-02-27 | 项目索引初始化；团队经验库目录建立 | 已完成 |
+| 2026-02-28 | stitch_soul 需求评审：内容→会员→导师变现路径，需与现有三端架构协同 | 已完成 |
+| 2026-03-08 | 文章阅读付费规则澄清：免费章节以 free_chapters 为准；VIP 全章免费；后端 book.go 合并配置修复 | 已完成 |
+| 2026-03-10 | 会议：管理端迁移 Mycontent-temp，新菜单/布局作为团队规范基线，避免两套后台并行发散 | 待续 |
+| 2026-03-10 | 新旧版代码对比方法论：以功能完整性而非日期判断优劣，批量 diff + 分类取舍 + 移植修复 | 已完成 |
+| 2026-03-11 | 以界面定需求文档建立；需求基准与业务逻辑对齐（用户/VIP 资料、三端路由）；会议收尾纪要与各角色经验入库 | 已完成 |
+| 2026-03-12 | 密钥/token 设计：关联小程序 key、@ 人物 token；不暴露真实密钥、服务端兑换 | 已完成 |
+| 2026-03-12 | 9.9 买断团队约定：后端统一输出 hasFullBook/has_full_book，小程序和管理端只认该信号；支持通过用户资料开关 OR 订单赠送全书且不影响 VIP 逻辑 | 已完成 |
+| 2026-03-13 | 文章详情预览规则统一：预览长度由后端统一按 50% 计算，小程序按 accessState 切换预览/全文，接口约定 content 与 data.content 始终一致 | 已完成 |
+| 2026-03-14 | 内容排名算法跨端复用：管理端内容排行与小程序精选推荐共用 computeArticleRankingSections，排名分公式、权重配置统一 | 已完成 |
+| 2026-03-16 | 乘风发起例行开发进度同步 | 已完成 |
+| 2026-03-16 | TipTap Mention 需 data-label 规则；链接人与事与存客宝对接优化会议收尾 | 已完成 |
+| 2026-03-17 | 代付美团式流程与权益归属约定：读页→代付页→分享；权益/分佣归发起人；PayNotify beneficiaryUserID | 已完成 |
+| 2026-03-17 | 性能优化与 Redis 缓存方案落地：Redis 容灾回退 DB、OSS 上传容灾；/health 返回 database/redis 状态 | 已完成 |
+| 2026-03-18 | 吸收经验：分享进入链路需兼容朋友圈 singlePage；单页模式不执行支付/自动领取等强动作并引导“前往小程序” | 已完成 |
+| 2026-03-18 | 会议：超级个体开通后自动创建@人统一走 Person；幂等键绑定 userId；默认资料 flags 后端输出 | 已完成 |
+| 2026-03-24 | 会议：需求与进度及三端闭环评审；主路径闭环成立、规则闭环待加固；失败响应与 err.response 契约 | 已完成 |
+| 2026-03-31 | 会议：超级个体与 @ 列表融合；先数据与入口融合、路由边界不变 | 已完成 |
+| 2026-04-02 | 会议：工作进度与需求同步；融合落地顺序与 deploy 验证门禁、问题与作答区待闭环 | 已完成 |
+| 2026-04-07 | 文档同步：需求与开发文档索引对齐；闭环结论：主路径成立、规则/风控待加固项见《闭环与文档同步-2026-04-07》 | 已完成 |
+| 2026-04-13 | 会议：按功能同步开发文档；功能完成=实现+索引一行；跨端契约双写团队/纪要 | 进行中 |
+| 2026-04-14 | 吸收沉淀：小程序逆推闭环方法论；`role-flow-control` §1.2；开发文档需求真源 | 进行中 |
+| 2026-04-15 | 联网：垂直切片/追踪弹/验证优先/无责复盘 → `role-flow-control` §1.3、`团队/evolution/2026-04-15.md` | 已完成 |
+
+> **格式说明**：每次架构级讨论后在此追加一行，日期格式 YYYY-MM-DD
+
+---
+
+**最后更新**：2026-04-15

.cursor/agent/开发助理/项目索引/小程序.md

@@ -0,0 +1,60 @@
+# 小程序 - 项目索引
+
+> 根据开发进度对项目做总结，保存开发进度，方便下次继续开发。**每次保存必须写日期**。
+
+---
+
+## 项目总结
+
+小程序（微信原生）C 端主要功能：用户注册/登录、VIP 购买、章节阅读、分销推荐、提现申请、找伙伴。当前已上线核心功能，持续迭代优化中。
+
+---
+
+## 开发进度
+
+| 日期 | 摘要 | 状态 |
+|------|------|------|
+| 2026-02-26 | 项目索引初始化，.cursor 规则优化完成 | 已完成 |
+| 2026-02-27 | 开发进度汇报：永平落地已完成（海报 scene、我的收益、推广中心、VIP 相关）；找伙伴、提现、阅读、分销核心功能已上线 | 已完成 |
+| 2026-02-27 | 开发进度同步会议：进度已同步至开发文档，待办资料完善弹窗、≥3 章弹窗 | 已完成 |
+| 2026-02-27 | 吸收经验：输入框 padding 用 view 包裹，已升级 SKILL-小程序开发 §6 | 已完成 |
+| 2026-02-28 | stitch_soul 需求评审：首页/目录/导师/会员/资料五类页面，待需求与接口确定后分阶段实现 | 待续 |
+| 2026-02-28 | 吸收经验：input 边距口诀「外边包 view、内部 width 100%」写入 Skill §6；match 资源对接弹窗已按规范修正 | 已完成 |
+| 2026-03-03 | 吸收经验：我的页面卡片区边距优化，16rpx 为个人中心类页面推荐值，已升级 SKILL §8 | 已完成 |
+| 2026-03-05 | 分支冲突后功能完整性分析会议：修正 app.json 拆行、核心流程自测、确认 orders 接口 | 待续 |
+| 2026-03-05 | 文章详情@某人加好友方案讨论：阅读页解析 @、高亮可点击、调添加好友接口 | 待续 |
+| 2026-03-10 | 会议：管理端迁移 Mycontent-temp；小程序侧关注内容产物格式变化与阅读页兼容回归 | 待续 |
+| 2026-03-10 | 移植 loadDashboardStats()：my.js 阅读统计改为后端接口，去除随机数时间/标题占位 | 已完成 |
+| 2026-03-10 | 富文本渲染技术债分析：contentParser.js 剥除 HTML 格式，建议改 rich-text 组件（待实施） | 待续 |
+| 2026-03-11 | 以界面定需求：小程序界面清单纳入《以界面定需求》；展示以用户资料为准，与现有实现一致 | 已完成 |
+| 2026-03-12 | 链接标签 mpKey 兑换 appId；@ 人物 token 兑换 ckb_api_key；contentParser、onLinkTagTap、onMentionTap | 已完成 |
+| 2026-03-13 | 阅读页文章预览与付费解锁对齐：预览长度改由后端统一计算，前端按 accessState 显示预览/全文，避免 data.content 泄露全文 | 已完成 |
+| 2025-03-14 | 阅读页文本长按选中复制：text 组件 user-select，已升级 SKILL §10 | 已完成 |
+| 2026-03-14 | 我的页设置入口隐藏（wx:if）；资料修改引导场景梳理（登录后、@某人、找伙伴、链接卡若） | 已完成 |
+| 2026-03-16 | 乘风发起例行开发进度同步 | 已完成 |
+| 2026-03-16 | 编辑资料页分享名片：转发/朋友圈改为分享名片，Canvas 封面（头像+昵称+四栏信息），路径 member-detail | 已完成 |
+| 2026-03-16 | 会议：new-soul 新需求与当前项目差异分析；派对AI 小程序站管理与当前一致 | 已完成 |
+| 2026-03-17 | 代付美团式：读页→创建请求→跳转代付详情页；详情页双态（发起人分享/好友帮他付款）；目录 loading、首页最新新增 5 条折叠 | 已完成 |
+| 2026-03-17 | 代付统一到代付页：gift=1&ref 打开 read 时 redirectTo 代付页，禁止在阅读页代付 | 已完成 |
+| 2026-03-17 | 代付页营销：章节标题+20%内容预览；我的代付列表点击进详情；页面协调 | 已完成 |
+| 2026-03-17 | 会议：稳定版源码质量优化；删除 payment.js、goToMatch 重复、备份文件；config 读取、totalSections 动态化 | 已完成 |
+| 2026-03-17 | 会议收尾：源码优化 5 项全部完成；开发环境测试通过 | 已完成 |
+| 2026-03-18 | 吸收经验：分享链路需兼容好友/朋友圈 singlePage；单页模式能力降级并引导“前往小程序”进入完整版 | 已完成 |
+| 2026-03-18 | 会议：支付超级个体前/开通后资料默认校验，跳转 avatar-nickname 引导页（仅头像+昵称） | 已完成 |
+| 2026-03-19 | 原生按钮覆盖定位（cover-view）经验入库 | 已完成 |
+| 2026-03-20 | 手机号一键登录、login-modal 公用组件（read/my/gift-pay 引入）；我的收益取 availableEarnings | 已完成 |
+| 2026-03-24 | 会议：开发进度同步；项目索引补齐；富文本 rich-text 技术债待续 | 已完成 |
+| 2026-03-24 | 会议：三端闭环评审；app.request err.response；提现双入口与后端契约对齐 | 已完成 |
+| 2026-03-24 | 落地：app.request 挂 err.response；soulBridge 留资扩展；阅读页带码与 referral/my 提现 catch 对齐 | 已完成 |
+| 2026-03-30 | 会议：文章详情 # 跳转关联小程序（如 MBTI）时 path 追加 `phone`；read.js 已实现 | 已完成 |
+| 2026-03-31 | 会议：超级个体与 @ 列表融合；C 端默认不改接口，仅回归 | 已完成 |
+| 2026-04-02 | 会议：工作进度与需求同步；全局 app/request 类改动需主路径冒烟；融合仍以回归为主 | 已完成 |
+| 2026-04-13 | 会议：按功能同步开发文档；页面级记 miniprogram 接口与分享行为；无接口变更亦标注 | 进行中 |
+| 2026-04-14 | 吸收沉淀：逆推闭环自检写入 evolution；LOOP 需求行 | 进行中 |
+| 2026-04-15 | 业务补齐：`app.js` 挂 `err.response`；导师详情微信支付；找伙伴 join 失败展示后端文案 | 已完成 |
+
+> **格式说明**：每次开发后在此追加一行，日期格式 YYYY-MM-DD，状态用：已完成 / 进行中 / 待续 / 搁置
+
+---
+
+**最后更新**：2026-04-15

.cursor/agent/开发助理/项目索引/测试.md

@@ -0,0 +1,44 @@
+# 测试 - 项目索引
+
+> 测试人员经验与测试进度。**每次保存必须写日期**。
+
+---
+
+## 项目总结
+
+测试人员负责小程序、管理端、API 的功能测试、回归测试与三端联调。主 Skill：SKILL-测试.md。
+
+---
+
+## 开发/测试进度
+
+| 日期 | 进度摘要 | 状态 |
+|------|----------|------|
+| 2026-02-27 | 测试人员角色与 Skill 初始化 | 已完成 |
+| 2026-02-27 | 小程序静态审查（API 路径、页面接口、手工验证建议） | 已完成 |
+| 2026-02-28 | stitch_soul 需求评审：关键场景为阅读/付费/会员/导师预约/资料；待需求确定后补充联调用例 | 待续 |
+| 2026-03-05 | 分支冲突后功能完整性分析会议：制定「分支合并后回归清单」 | 待续 |
+| 2026-03-05 | 文章详情@某人加好友方案讨论：@ 展示与添加好友用例、联调与回归 | 待续 |
+| 2026-03-10 | 会议：管理端迁移 Mycontent-temp；回归重点为菜单一致性、隐藏路由可达性、鉴权跳转 | 待续 |
+| 2026-03-16 | 乘风发起例行开发进度同步 | 已完成 |
+| 2026-03-16 | scripts 目录知识吸收：本地启动、飞书脚本、联调环境准备 | 已完成 |
+| 2026-03-16 | scripts/test 测试用例目录约定：miniapp 小程序接口、web 管理端 | 已完成 |
+| 2026-03-16 | scripts/test/process 流程测试目录：跨端业务流程 | 已完成 |
+| 2026-03-16 | pytest 架构、配置从项目读取、运行前显示测试环境 | 已完成 |
+| 2026-03-16 | 文章 @某人 自动创建存客宝：用例编写、执行、报告；归档规则 | 已完成 |
+| 2026-03-16 | 会议：new-soul 新需求与当前项目差异分析；引入派对AI 时回归文章上传/飞书推送/小程序展示 | 已完成 |
+| 2026-03-17 | 会议：稳定版源码质量优化；每项小回归、全部完成后完整三端联调 | 待续 |
+| 2026-03-17 | 会议收尾：功能测试流程定稿、测试报告模板、开发环境 10 通过 2 跳过 | 已完成 |
+| 2026-03-17 | 性能优化会议：test_upload.py 6 用例；/health 可验证 database/redis；部署后回归缓存接口 | 已完成 |
+| 2026-03-18 | 文档归档整理：按界面驱动口径统一验收；补充分享 singlePage 降级与引导为必测项 | 已完成 |
+| 2026-03-18 | 会议：新增用例（资料默认阻断支付、Person 自动创建幂等、昵称变更同步回归） | 已完成 |
+| 2026-03-24 | 会议：开发进度同步；项目索引补齐；提现/登录/收益/推广设置用例补充；singlePage、getPhoneNumber 边界 | 已完成 |
+| 2026-03-24 | 会议：三端闭环评审；API 绕过负例与双入口提现回归待契约落地后执行 | 已完成 |
+| 2026-03-31 | 会议：超级个体与 @ 列表融合；回归清单含排序/@/绑定/Webhook 边界 | 待续 |
+| 2026-04-02 | 会议：工作进度与需求同步；融合清单待联调后执行；deploy PR 增加 compose/health/smoke | 待续 |
+| 2026-04-13 | 会议：按功能同步开发文档；以文档与索引为真源更新回归；契约未入文档可阻塞 | 进行中 |
+| 2026-04-14 | 吸收沉淀：LOOP 需求与逆推清单纳入回归裁剪依据 | 进行中 |
+
+---
+
+**最后更新**：2026-04-14

.cursor/agent/开发助理/项目索引/玩值.md

@@ -0,0 +1,14 @@
+# 玩值（Wanzhi）项目索引
+
+真源进度看板：**`开发文档/玩值/进度-看板.md`**。本文件为橙子侧「开发进度」摘要，与看板同步更新。
+
+## 开发进度
+
+| 日期 | 子项目 | 内容摘要 |
+|------|--------|----------|
+| 2026-04-20 | wz-api | Go module 更名 `wz-api`；`GET /api/app/health`；`MIGRATION.md`；部署脚本/Dockerfile 二进制名对齐 |
+| 2026-04-20 | wz-admin | Vite React-TS 脚手架；`src/api/client.ts`；README |
+| 2026-04-20 | wz-app | `utils/request.js`；首页联调 `/api/app/health`；README |
+| 2026-04-20 | .cursor | 玩值三智能体 + wz-* Skills；Soul 角色 agent 与 karuo-party 归档；总索引与 paths.py 更新 |
+
+最后更新：2026-04-20

.cursor/agent/开发助理/项目索引/管理端.md

@@ -0,0 +1,60 @@
+# 管理端 - 项目索引
+
+> 根据开发进度对项目做总结，保存开发进度，方便下次继续开发。**每次保存必须写日期**。
+
+---
+
+## 项目总结
+
+管理端（React + Vite + Tailwind）主要功能：用户管理、订单管理、提现审核、VIP 管理、内容/章节管理、配置项管理、数据统计。调用 `/api/admin/*` 与 `/api/db/*` 接口，JWT Bearer 鉴权。
+
+### 项目路径定义
+
+| 版本 | 路径 | 说明 |
+|------|------|------|
+| **稳定版（主用）** | `soul-admin/` | 根目录，线上部署 |
+| **新版（参考）** | `new-soul/soul-admin/` | 迁移时对照，含 ApiDocsPage 完整版、OSS region 等 |
+
+---
+
+## 开发进度
+
+| 日期 | 摘要 | 状态 |
+|------|------|------|
+| 2026-02-26 | 项目索引初始化，.cursor 规则优化完成 | 已完成 |
+| 2026-02-27 | 开发进度汇报：内容管理仅 API 按钮、推广中心、SetVipModal、VIP 角色管理、推广设置会员分润配置、VIP 排序等均已落地 | 已完成 |
+| 2026-02-27 | 开发进度同步会议：进度已同步至运营与变更 | 已完成 |
+| 2026-02-28 | stitch_soul 需求评审：待后端方案确定后规划章节/导师/会员/预约管理页面 | 待续 |
+| 2026-03-05 | 分支冲突后功能完整性分析会议：全功能自测，记录 404/异常接口 | 待续 |
+| 2026-03-05 | 文章详情@某人加好友方案讨论：编辑页插入 @用户、保存约定 content 格式 | 待续 |
+| 2026-03-10 | 会议：管理端迁移 Mycontent-temp 新菜单/布局；主导航收敛、author/admin 并入 Settings Tab | 待续 |
+| 2026-03-10 | Toast 通知系统落地：创建 utils/toast.ts（纯原生），全系统 18 文件约 90 处 alert 全部替换为 toast.success/error/info | 已完成 |
+| 2026-03-11 | 以界面定需求：管理端界面清单纳入《以界面定需求》，作为验收基准 | 已完成 |
+| 2026-03-12 | ContentPage TypeScript 严格类型修复；关联小程序 key、@ 人物 token 设计（链接标签存 key、PersonItem.id=token） | 已完成 |
+| 2026-03-14 | 排名算法权重保存后刷新：handleSaveRankingWeights 成功后 loadRanking + 关闭弹窗，列表立即更新 | 已完成 |
+| 2026-03-16 | 乘风发起例行开发进度同步 | 已完成 |
+| 2026-03-16 | 链接人与事：table 布局、planId/apiKey 列、复制图标、删除 Dialog 弹窗 | 已完成 |
+| 2026-03-16 | 会议：new-soul 新需求与当前项目差异分析；派对AI 不新增管理端需求 | 已完成 |
+| 2026-03-17 | 会议：新版管理端迁移到稳定版实施方案确认；新版独有全部吸纳，内容管理以稳定版为主 | 已完成 |
+| 2026-03-17 | 吸收新版管理端定义（new-soul/soul-admin）；迁移 ApiDocsPage 完整版、OSS region、鉴权失败 clearAdminToken | 已完成 |
+| 2026-03-17 | 修复 DistributionPage Order.description；用户余额人工调整（后端 adjust API + 用户详情入口）；代付列表页（后端 gift-pay-requests + 推广中心 Tab） | 已完成 |
+| 2026-03-17 | 会议：稳定版源码质量优化；UserDetailModal 改 /api/admin/user/track、RichEditor HTML 转义 | 已完成 |
+| 2026-03-17 | 会议收尾：源码优化已落地；开发环境测试通过 | 已完成 |
+| 2026-03-17 | 性能优化会议：OSS 配置后上传自动优先 OSS，失败回退本地；无需前端改动 | 已完成 |
+| 2026-03-18 | 文档归档整理：按《以界面定需求》重整管理端功能需求与验收口径，写入角色经验库 | 已完成 |
+| 2026-03-18 | 会议：超级个体开通后自动创建@人；管理端可选展示 userId/来源以便排查重名 | 已完成 |
+| 2026-03-20 | 提现审核：备注列（fail_reason/error_message）、自动审批开关；推广设置提现手续费 | 已完成 |
+| 2026-03-24 | 会议：开发进度同步；项目索引补齐；DistributionPage Order.description 待修 | 已完成 |
+| 2026-03-24 | 会议：三端闭环评审；管理端与小程序配套整体齐全；类型债择机修 | 已完成 |
+| 2026-03-31 | 会议：超级个体与 @ 列表融合；UsersPage 表格加 @ 状态与跳转内容页 | 待续 |
+| 2026-04-02 | 会议：工作进度与需求同步；UsersPage 待接口字段就绪后联调；deploy 文档基址与后端对齐 | 进行中 |
+| 2026-04-13 | 会议：按功能同步开发文档；页面粒度记 admin/db 依赖；类型债排期入文档 | 进行中 |
+| 2026-04-14 | 吸收沉淀：MAINT-ADMIN-TS 入需求表；配置入口与运营与变更联动 | 进行中 |
+
+> **格式说明**：每次开发后在此追加一行，日期格式 YYYY-MM-DD，状态用：已完成 / 进行中 / 待续 / 搁置
+
+---
+
+**最后更新**：2026-04-14
+
+> 注：soul-admin 构建仍有 DistributionPage Order.description 类型错误（与本次迁移无关），待修复。

.cursor/agent/智能体-技能-经验总索引.md

@@ -0,0 +1,49 @@
+# 智能体技能&经验总索引
+
+用途：让任何智能体在“开始实现或回答”之前，先快速匹配“有没有相关经验”和“应该用哪个 Skill”，再综合处理。
+
+**Soul 时期角色**（产品/测试/团队/安全/小程序/管理端/后端工程师）已迁至 **`.cursor/archive/agents-legacy-soul/`**，以下默认索引**不再**逐条展开其 evolution；需要考古时直接打开归档目录内 `evolution/索引.md`。
+
+---
+
+## 1. 经验索引（按角色）
+
+- 助理橙子：`agent/开发助理/evolution/索引.md`
+- 老板分身：`agent/老板分身/evolution/索引.md`
+- **玩值 API 工程师**：`agent/玩值API工程师/evolution/索引.md`
+- **玩值管理端工程师**：`agent/玩值管理端工程师/evolution/索引.md`
+- **玩值移动端工程师**：`agent/玩值移动端工程师/evolution/索引.md`
+
+---
+
+## 2. 技能索引（按任务类型/触发）
+
+- **玩值 API**：`skills/wz-api-dev/SKILL.md` — `new/wz-api`、玩值后端
+- **玩值管理端**：`skills/wz-admin-dev/SKILL.md` — `new/wz-admin`
+- **玩值移动端（uni-app）**：`skills/wz-app-dev/SKILL.md` — `new/wz-app`
+- Soul 小程序（归档期仍维护 `miniprogram/` 时）：`skills/miniprogram-dev/SKILL.md`
+- Soul 管理端（`soul-admin/`）：`skills/admin-dev/SKILL.md`
+- Soul 后端（`soul-api/`）：`skills/api-dev/SKILL.md`
+- 产品经理：`skills/product-manager/SKILL.md`（触发词仍可用；经验默认写入开发助理 evolution）
+- 测试：`skills/testing/SKILL.md`
+- 助理橙子：`skills/assistant-doc-sync/SKILL.md`
+- 团队会议：`skills/team-meeting/SKILL.md`
+- 变更关联检查：`skills/change-checklist/SKILL.md`
+- 跨端协同：`skills/role-flow-control/SKILL.md`
+- 三端架构：`skills/three-tier-arch/SKILL.md`
+- 新版/迁移分析：`skills/new-version-analyze/SKILL.md`
+- next 预览：`skills/next-preview/SKILL.md`
+- Next 拆解：`skills/next-split/SKILL.md`
+- MySQL 直连：`skills/mysql-direct/SKILL.md`
+- 安全运维：`skills/security-miner-guard/SKILL.md`、`skills/security-server-ops/SKILL.md`
+- 飞书 Webhook：`skills/feishu-webhook/SKILL.md`
+- **卡若运营技能包（已归档）**：见 `.cursor/archive/skills-karuo-party/karuo-party/SKILL.md`
+
+---
+
+## 3. 使用流程（任何智能体都照做）
+
+1. 先归类：根据编辑目录或触发词判断“可能涉及哪些角色/任务类型”。
+2. 再查经验：打开对应角色的 `evolution/索引.md`，找最近且最贴近的经验条目。
+3. 再查技能：打开对应 Skill 的 `SKILL.md`，按其执行流程/约束落地。
+4. 再综合：若命中多个条目，按“边界规则 + 变更闭环（如 change-checklist）+ 必要的联动（如会议/跨端）”合并决策。

.cursor/agent/玩值API工程师/README.md

@@ -0,0 +1,7 @@
+# 玩值 API 工程师
+
+- **绑定目录**：`new/wz-api/`
+- **主 Skill**：`.cursor/skills/wz-api-dev/SKILL.md`
+- **契约真源**：`开发文档/玩值/迁移-API对照表.md`、`迁移-API前缀决议.md`
+
+负责 Go 服务、路由分组（`/api/admin`、`/api/db`、`/api/app`、`/api/screen`、`/api/public`）、GORM 模型与迁移脚本。

.cursor/agent/玩值API工程师/evolution/2026-04-20-玩值迁移-吸收.md

@@ -0,0 +1,8 @@
+# 2026-04-20 玩值迁移 - 经验吸收摘要
+
+从 Soul/团队经验中抽取、**去掉 Soul 业务专有名词**后适用于玩值 API 的条目：
+
+1. **路由按使用方分组**：管理端与 C 端路径前缀分离，共用逻辑可复用 handler 但须分别注册（与 wz-api-dev 一致）。
+2. **GORM 变更闭环**：model → AutoMigrate 或 scripts SQL → handler → router → 开发文档对照表状态更新。
+3. **列表接口**：分页参数 `page`/`pageSize`、返回 `total` 等与前端约定写进对照表，避免联调返工。
+4. **Mongo→MySQL**：以《迁移-数据模型.md》为真源，先表结构再写接口，避免无表实现。

.cursor/agent/玩值API工程师/evolution/索引.md

@@ -0,0 +1,5 @@
+# 玩值 API 工程师 - 经验索引
+
+| 日期 | 主题 |
+|------|------|
+| 2026-04-20 | [玩值迁移-吸收（方法论）](2026-04-20-玩值迁移-吸收.md) |

.cursor/agent/玩值移动端工程师/README.md

@@ -0,0 +1,7 @@
+# 玩值移动端工程师（uni-app）
+
+- **绑定目录**：`new/wz-app/`
+- **主 Skill**：`.cursor/skills/wz-app-dev/SKILL.md`
+- **API 前缀**：`/api/app/*`（见 `开发文档/玩值/迁移-API前缀决议.md`）
+
+负责 uni-app 页面、条件编译、与 wz-api 的 C 端契约；不维护微信原生 `miniprogram/` 目录。

.cursor/agent/玩值移动端工程师/evolution/2026-04-20-玩值迁移-吸收.md

@@ -0,0 +1,8 @@
+# 2026-04-20 玩值迁移 - 经验吸收摘要
+
+从原小程序/团队经验中可迁移到 **uni-app** 的概念（非 WXML 语法）：
+
+1. **登录与票据**：uni 存储 token；请求头携带方式与 wz-api `/api/app` 约定一致；登出清理本地态。
+2. **支付/微信能力**：用 `uni.requestPayment` 等与后端回调 URL 对齐；错误提示用户可理解文案。
+3. **契约双写**：任何新接口同步《迁移-API对照表》与进度看板，避免「前端写了路径后端未挂」。
+4. **垂直切片**：一用户旅程（如登录→列表→详情）尽量同迭代内闭环 API + 页面。

.cursor/agent/玩值移动端工程师/evolution/索引.md

@@ -0,0 +1,5 @@
+# 玩值移动端工程师 - 经验索引
+
+| 日期 | 主题 |
+|------|------|
+| 2026-04-20 | [玩值迁移-吸收](2026-04-20-玩值迁移-吸收.md) |

.cursor/agent/玩值管理端工程师/README.md

@@ -0,0 +1,7 @@
+# 玩值管理端工程师
+
+- **绑定目录**：`new/wz-admin/`
+- **主 Skill**：`.cursor/skills/wz-admin-dev/SKILL.md`
+- **脚手架参考**：`soul-admin/`（同栈复制后改环境变量与路由）
+
+仅对接 wz-api 的 `/api/admin/*`、`/api/db/*`。

.cursor/agent/玩值管理端工程师/evolution/2026-04-20-玩值迁移-吸收.md

@@ -0,0 +1,8 @@
+# 2026-04-20 玩值迁移 - 经验吸收摘要
+
+从管理端/团队经验抽取：
+
+1. **仅 admin/db 路径**：与 wz-api 的 `/api/app` 严格隔离；client 统一封装 Token。
+2. **列表页**：分页、搜索防抖、loading、空状态、错误条；禁止 `alert`，统一 Toast。
+3. **TypeScript**：可选字段用 `??` 兜底，API 响应类型与后端字段对齐，避免 `undefined` 流入 UI。
+4. **文档**：每页依赖的 API 在《迁移-API对照表》与进度看板登记联调状态。

.cursor/agent/玩值管理端工程师/evolution/索引.md

@@ -0,0 +1,5 @@
+# 玩值管理端工程师 - 经验索引
+
+| 日期 | 主题 |
+|------|------|
+| 2026-04-20 | [玩值迁移-吸收](2026-04-20-玩值迁移-吸收.md) |

.cursor/agent/老板分身/evolution/索引.md

@@ -0,0 +1,4 @@
+# 老板分身 经验索引
+
+| 日期 | 摘要 | 文件 |
+|------|------|------|

.cursor/apifox-mcp-setup.md

@@ -0,0 +1,116 @@
+# Apifox MCP 配置说明
+
+已在 Cursor 的 `mcp.json` 中添加 Apifox MCP 配置，你需要根据使用场景填写对应参数。
+
+## 前置条件
+
+- Node.js >= 18
+- Apifox 版本 >= 2.7.2（若使用项目/文档站）
+
+---
+
+## 方式一：项目 ID + 访问令牌（推荐，团队私有文档）
+
+适用于：读取自己团队 Apifox 项目内的 API 文档。
+
+### 1. 获取项目 ID
+
+- 打开 Apifox 项目
+- 左侧边栏 → **项目设置** → **基本设置**
+- 复制「项目 ID」
+
+### 2. 获取访问令牌
+
+- Apifox 右上角头像 → **账号设置** → **API 访问令牌**
+- 创建新的 API 访问令牌并复制
+
+### 3. 修改 mcp.json
+
+编辑 `C:\Users\29195\.cursor\mcp.json`，将 Apifox 配置中的占位符替换为实际值：
+
+```json
+"Apifox": {
+  "command": "npx",
+  "args": [
+    "-y",
+    "apifox-mcp-server@latest",
+    "--project-id=你的项目ID"
+  ],
+  "env": {
+    "APIFOX_ACCESS_TOKEN": "你的访问令牌"
+  }
+}
+```
+
+---
+
+## 方式二：Site ID（公开发布的文档）
+
+适用于：读取已公开发布的 API 文档站，无需令牌。
+
+### 1. 获取 Site ID
+
+- Apifox 项目内：**分享文档** → **发布文档站** → **AI 功能**
+- 开启 MCP 服务，复制生成的 `site-id`
+
+### 2. 修改 mcp.json
+
+将 Apifox 配置改为使用 `--site-id`，并移除 `env`：
+
+```json
+"Apifox": {
+  "command": "npx",
+  "args": [
+    "-y",
+    "apifox-mcp-server@latest",
+    "--site-id=你的SiteID"
+  ],
+  "env": {}
+}
+```
+
+---
+
+## 方式三：OpenAPI/Swagger 文件
+
+适用于：本地或线上的 OpenAPI/Swagger 文档，不依赖 Apifox 项目。
+
+```json
+"Apifox": {
+  "command": "npx",
+  "args": [
+    "-y",
+    "apifox-mcp-server@latest",
+    "--oas=https://example.com/openapi.json"
+  ],
+  "env": {}
+}
+```
+
+本地文件示例：`--oas=E:/path/to/openapi.json`
+
+---
+
+## 私有化部署
+
+若使用 Apifox 私有化部署，需在 `args` 中增加：
+
+```
+"--apifox-api-base-url=https://你的私有化服务器地址"
+```
+
+---
+
+## 生效方式
+
+修改 `mcp.json` 后，重启 Cursor 或重新加载 MCP 服务即可。
+
+## 使用示例
+
+配置完成后，可对 AI 说：
+
+- 「通过 MCP 获取 API 文档，然后生成 Product 及其相关模型的定义代码」
+- 「根据 API 文档，在 Product DTO 里添加 API 文档新增的几个字段」
+- 「根据 API 文档，生成接口 /users 相关的所有 MVC 代码」
+
+文档有更新时，可提示 AI「刷新接口文档数据」。

.cursor/archive/README.md

@@ -0,0 +1,3 @@
+# 历史归档
+
+存放已归档的文档、分析报告等。

.cursor/archive/agents-legacy-soul/README.md

@@ -0,0 +1,13 @@
+# 已归档：Soul 派对时期角色智能体
+
+2026-04-20 玩值三端迁移后，主仓库 `.cursor/agent/` 仅保留 **开发助理（橙子）**、**老板分身（乘风）** 与 **玩值三项目智能体**。下列目录为原 Soul 角色经验与脚本的完整搬迁，供查阅，**不再作为默认索引入口**。
+
+- `产品经理/`
+- `软件测试/`
+- `团队/`
+- `安全工程师/`
+- `小程序开发工程师/`
+- `管理端开发工程师/`
+- `后端工程师/`
+
+新开发请查 `agent/玩值*` 与 `开发文档/玩值/`。

.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-02-26.md

@@ -0,0 +1,5 @@
+# 2026-02-26 | 产品经验
+
+> 本日经验条目，格式：类型 | 摘要 | 升级 Skill
+
+---

.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-02-28.md

@@ -0,0 +1,19 @@
+# 产品经理 经验记录 - 2026-02-28
+
+## stitch_soul 需求评审会议
+
+- **stitch_soul 串联「内容→会员→导师」变现路径**：临时需求池 10 个稿子覆盖目录、导师、会员、首页、资料编辑，需在正式需求文档中明确 73 章、导师、案例库、会员的业务定义与验收标准。
+- **待澄清项**：73 章与现有内容库是否同一套；导师与内容作者是否同一人；「案例库」是独立内容池还是章节分类；会员权益与价格策略。
+- **优先级建议**：首页/目录/会员 > 导师列表/详情 > 资料编辑。
+
+## 个人资料页实现评估会议
+
+- **展示/编辑页一致性**：展示页（enhanced_professional_profile）与编辑页（comprehensive_profile_editor_v1_1）需字段一一对应、配色统一。
+- **skills「我擅长」**：展示页已有，编辑页必须补充；验收时确认两页数据一致。
+
+## 文章类型（普通版/增值版）需求分析会议
+
+- **普通版**：9.9 元买断，与现有 fullbook 一致。
+- **增值版**：基础价 + 后 N 章（N 可配置）按章额外付费；每购一章价格累加该章单价。
+- **已确认**：普通版与增值版**分开、互斥**，用户购买其一，非叠加。
+- **待输出**：增值版基础价是否固定 9.9；N 默认值。

.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-05.md

@@ -0,0 +1,12 @@
+# 产品经理 经验记录 - 2026-03-05
+
+## 分支冲突后功能完整性分析会议
+
+- **分支冲突后需优先核对需求文档与实现一致性**：避免「文档在合并中丢失」导致需求与实现脱节。重点核对 `开发文档/1、需求/`、`临时需求池/` 与当前实现是否一致。
+- **重点确认项**：个人资料页、增值版/普通版计价、找伙伴联系方式完善弹窗等近期需求是否按文档落地。
+
+## 文章详情 @某人 高亮与一键加好友方案讨论
+
+- **需求**：文章中支持 @某人，名称高亮、点击添加好友；编辑侧能插入 @用户并落库（含用户 id）。
+- **验收**：详情页 @ 高亮可点击；点击调起添加好友并提示；管理端插入 @ 后保存再编辑不错位。
+- **待确认**：添加好友接口 path、入参/出参及业务规则（已是好友、重复请求等）；开发文档中接口放置位置。

.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-10.md

@@ -0,0 +1,13 @@
+# 产品经理 经验记录 - 2026-03-10
+
+## 管理端迁移 Mycontent-temp：信息架构与验收口径
+
+- **主导航收敛**：侧栏只保留运营主链路 5 项（概览/内容/用户/找伙伴/推广），系统设置固定在底部；其余能力不删除但不占主导航入口。
+- **入口承载策略**：非主菜单页面（订单/提现/推广设置/VIP角色/导师等）通过“概览卡片/页面内按钮/系统设置 Tab”进入，确保可达且路径更短。
+- **验收标准**：
+  - 菜单与布局一致（新规范）
+  - 隐藏页面路由仍可访问（功能不丢）
+  - author/admin 设置统一在 `/settings?tab=...` 承载，旧路径可兼容跳转
+
+> 详见会议纪要：`.cursor/meeting/2026-03-10_管理端迁移Mycontent-temp菜单布局讨论.md`
+

.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-11.md

@@ -0,0 +1,7 @@
+# 产品经理 经验记录 - 2026-03-11
+
+## 需求基准：以界面定需求
+
+- 需求与验收以《开发文档/1、需求/以界面定需求》为准；新增/变更功能时先对齐界面再更新《需求汇总》需求清单。
+- 小程序与管理端界面清单、主要接口、业务逻辑对齐（用户/VIP 资料展示、三端 API 边界等）已落档，作为验收基准。
+- 详见团队共享：`agent/团队/evolution/2026-03-11.md`。

.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-16.md

@@ -0,0 +1,7 @@
+# 产品经理 经验记录 - 2026-03-16
+
+## new-soul 派对AI 与 Mycontent 定位差异（会议：new-soul 新需求与当前项目差异分析）
+
+- **new-soul 派对AI**：内容运营侧 AI 助手，服务于《一场soul的创业实验》的派对→录屏→剪辑→成片→分发→文章→小程序全链路
+- **当前 Mycontent**：产品侧，面向创业者的社区/工具型小程序，核心是内容→会员→导师变现、存客宝对接、分销等
+- **结论**：两者是同一业务的不同层面（运营 vs 产品），互补非替代

.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-17.md

@@ -0,0 +1,13 @@
+# 产品经理 经验记录 - 2026-03-17
+
+## 稳定版源码质量优化（会议：2026-03-17）
+
+- **验收标准**：优化后现有功能行为不变，三端联调通过
+- **优先级**：高优（安全）→ 中优（可维护）→ 低优（性能/结构）
+- **原则**：源码质量优化按安全→可维护→性能分批，用户无感知
+
+---
+
+## 会议收尾（2026-03-17）
+
+- 10 项优化全部完成；测试流程与报告模板已定稿；开发文档已同步

.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-18.md

@@ -0,0 +1,38 @@
+# 产品经理 经验记录 - 2026-03-18
+
+## 文档归档与需求口径（界面驱动）
+
+### 需求基准（验收口径）
+- **需求以界面为准**：以 `开发文档/1、需求/以界面定需求.md` 的“界面清单 + 业务逻辑对齐”为验收基准。
+- **需求清单与变更记录**：
+  - 需求清单：`开发文档/1、需求/需求汇总.md`
+  - 近期讨论/决议：`开发文档/10、项目管理/运营与变更.md`
+  - 里程碑执行层：`开发文档/10、项目管理/项目落地推进表.md`
+
+### 归档原则（避免文档发散）
+- 新增/改版功能必须同步更新：
+  - 《以界面定需求》（界面与主要接口）
+  - 《需求汇总》（需求清单条目：日期/描述/状态/备注）
+  - 《运营与变更》（决议与实现摘要）
+- 旧方案文档若已过时：在 `开发文档/README.md` 的“已移除文档”里登记清理原因，避免重复讨论。
+
+### 功能需求整理（按产品域）
+- **内容阅读与付费**：预览与解锁规则、VIP 全章免费、余额支付与微信支付链路、阅读统计与埋点。
+- **代付分享**：发起人支付后分享；好友打开阅读页自动领取并解锁；发起人可查看领取进度与明细。
+- **推广分销与提现**：分润规则可配置（会员 20%/非会员 10%、内容 90%）、提现闭环（申请→审核/打款→回写→订阅消息）。
+- **找伙伴/存客宝**：@mention/#标签自动创建与同步；留资与匹配流程；限频与风控边界。
+
+### 分享场景强约束（验收必测）
+- **好友分享 vs 朋友圈分享（singlePage）**：
+  - 朋友圈进入可能是单页模式，页面能力不完整
+  - 验收必须覆盖：单页模式不触发支付/自动领取等强动作，且明确引导“前往小程序”进入完整版
+
+## 超级个体开通后自动创建@人与资料引导（会议决议）
+
+### 业务目标与规则
+- **自动创建 @人**：用户开通超级个体后，管理端「链接人与事」自动创建一条 Person 记录，展示名与用户**当前昵称一致**。
+- **资料完善拦截**：支付超级个体前若昵称/头像为默认值，必须引导至仅头像+昵称的引导页完成修改；开通后进入权益/成功页也需再次检测兜底。
+
+### 待确认
+- 昵称变更后的同步规则：是否强制同步更新 Person.name，是否需要保留历史别名/展示区分。
+

.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-24.md

@@ -0,0 +1,16 @@
+# 产品经理 经验记录 - 2026-03-24
+
+## 开发进度同步会议
+
+### 文档同步原则
+- 实现变更后需同步更新：《需求汇总》《运营与变更》及对应角色项目索引。
+- 项目索引「最后更新」应与实际变更日期一致，避免滞后。
+
+### 当前状态
+- 2026-03-20 需求（提现、我的收益、推广设置等）已与实现对齐。
+- 主需求、落地推进表已基本同步；项目索引已补齐至 2026-03-24。
+
+## 需求与进度及三端闭环评审
+
+- 区分「用户主路径闭环」与「规则/风控闭环」；后者缺口见《产品意图与功能闭环分析》，用清单驱动排期而非推翻里程碑。
+- 待确认：VIP 支付前是否强制完善头像昵称（与当前 vip.js 策略二选一）。

.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-31.md

@@ -0,0 +1,6 @@
+# 产品经理 经验记录 - 2026-03-31
+
+## 会议：超级个体列表与 @ 列表融合
+
+- 超级个体（VIP 曝光）与 @ 人物（内容引用）应视为同一业务的两面；融合优先统一运营心智与验收口径，再决定 UI 是否单页。
+- 一期验收需明确：无 @ 人物的有效 VIP 的提示策略、管理端跳转路径是否满足运营闭环。

.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-04-02.md

@@ -0,0 +1,7 @@
+# 产品经理 经验记录 - 2026-04-02
+
+## 会议：工作进度与需求同步会
+
+- **场景**：4 月初全员同步进度，衔接 2026-03-31 超级个体与 @ 列表融合待办。
+- **要点**：融合类需求需同步明确「一期验收口径」（UsersPage @ 状态、列表入口是否收敛），并写入需求汇总/运营与变更，避免实现先行、验收滞后。
+- **待办**：问题与作答区 Q1 由产品补充作答后闭环。

.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-04-13.md

@@ -0,0 +1,6 @@
+# 产品经理 经验记录 - 2026-04-13
+
+## 会议：按功能同步开发文档
+
+- **要点**：以可验收功能点为最小同步单位；主需求与《以界面定需求》为验收真源；跨端规则变更须同时更新需求清单状态与优先级。
+- **待办**：核对 2026-04-02 以来实现与文档差异；vip-members/融合一期验收口径在需求文档中单点定稿。

.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-04-14.md

@@ -0,0 +1,7 @@
+# 产品经理 经验记录 - 2026-04-14
+
+## 吸收沉淀：同步开发需求
+
+- **需求清单**：在 `开发文档/1、需求/需求汇总.md` 维护编号行（SYNC / LOOP / MAINT 等），状态与责任角色与纪要待办一致。
+- **验收绑定**：功能完成 = 实现可合并 + **需求表或项目索引当日一行**；跨端规则须在需求或运营与变更中单点写清优先级。
+- **管理端必要性**：沿用产品 Skill — 纯文案/纯视觉可不建管理端；**配置/开关/审核/统计** 必须显式在需求表标「管理端入口」避免壳功能。

.cursor/archive/agents-legacy-soul/产品经理/evolution/索引.md

@@ -0,0 +1,10 @@
+# 产品经理 经验索引
+
+| 日期 | 摘要 | 文件 |
+|------|------|------|
+| 2026-03-05 | 分支冲突后需求文档与实现一致性核对 | [2026-03-05.md](./2026-03-05.md) |
+| 2026-03-05 | 文章详情@某人高亮与一键加好友验收标准与待确认 | [2026-03-05.md](./2026-03-05.md) |
+| 2026-03-10 | 管理端迁移 Mycontent-temp：主导航收敛与隐藏页面入口承载策略 | [2026-03-10.md](./2026-03-10.md) |
+| 2026-03-24 | 开发进度同步会议：文档同步原则、项目索引补齐 | [2026-03-24.md](./2026-03-24.md) |
+| 2026-04-13 | 按功能同步开发文档会议：验收与需求真源、功能完成定义 | [2026-04-13.md](./2026-04-13.md) |
+| 2026-04-14 | 吸收沉淀：需求汇总表维护、验收与管理端必要性 | [2026-04-14.md](./2026-04-14.md) |

.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-02-26.md

@@ -0,0 +1,5 @@
+# 2026-02-26 | 后端经验
+
+> 本日经验条目，格式：类型 | 摘要 | 升级 Skill
+
+---

.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-02-28.md

@@ -0,0 +1,23 @@
+# 后端开发 经验记录 - 2026-02-28
+
+## stitch_soul 需求评审会议
+
+- **现有基础**：soul-api 已有 chapter、book、vip 模型；导师能力需新建或扩展现有 match 体系（现有 mentor 为 match 类型，非独立导师实体）。
+- **待设计**：导师列表/详情/搜索筛选、预约单、会员权益与预约支付打通；接口挂 `/api/miniprogram/*`。
+- **协同**：与产品核对 chapter/book/vip 现状后，给出导师/预约/会员权益的模型与接口方案。
+
+## chapter/book/vip 模型补充（问题 5 作答）
+
+- **chapters 表**：每行一节，id 如 1.1/preface；part/chapter/section 三层；73 章=行数统计。
+- **book**：无独立表，= chapters 聚合；接口 `/api/book/all-chapters`、`/api/book/chapter/:id`。
+- **vip**：vip_roles 配置角色；users 存 is_vip/vip_expire_date 等；权益优先 users，无则 orders 兜底；¥1980。
+
+## 个人资料页实现评估会议
+
+- **profile API**：`GET/POST /api/miniprogram/user/profile` 已覆盖 skills 等全部扩展字段；无需新增接口。
+
+## 文章类型（普通版/增值版）需求分析会议
+
+- **premium_config**：system_config 新增 premium_base_price、premium_chapter_count（后 N 个 section）。
+- **增值章节购买**：沿用 product_type=section、product_id=section_id，金额为 chapters.price。
+- **purchase-status 扩展**：需返回 editionType、premiumPurchasedSections 等。

.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-05.md

@@ -0,0 +1,13 @@
+# 后端工程师 经验记录 - 2026-03-05
+
+## 分支冲突后功能完整性分析会议
+
+- **soul-api 被 gitignore 时**：需在 soul-api 所在位置单独确认 git 状态与合并情况，无法从本仓库直接检查。
+- **重点核对接口**：`/api/miniprogram/orders`（购买记录）、`/api/db/distribution`（分销）是否已实现并挂载到对应路由组。
+- **建议**：对照「三端需求业务对齐」文档逐项核对接口注册与实现；明确 soul-api 的版本管理与合并策略。
+
+## 文章详情 @某人 高亮与一键加好友方案讨论
+
+- **内容存储**：推荐正文内嵌 @ 标记，格式 `@[昵称](userId)`（或 `{{@userId:昵称}}`），后端只存不解析；章节/文章接口原样返回 content。
+- **添加好友接口**：在 miniprogram 路由组新增，如 `POST /api/miniprogram/friend/add`，入参 `targetUserId`；与存客宝 api_v1 分离，在开发文档中单独说明或 api_v1 新增小节。
+- **数据模型**：无需单独 mention 表，扩展内容表 content 存带 @ 标记字符串即可。

.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-10.md

@@ -0,0 +1,67 @@
+# 后端工程师 经验记录 - 2026-03-10
+
+## 管理端迁移 Mycontent-temp：后端视角注意点
+
+- **接口边界不变**：管理端迁移/重构只允许调用 `/api/admin/*`、`/api/db/*`、`/api/orders`，严禁引入 `/api/miniprogram/*`。
+- **概览聚合接口可选**：`/api/admin/dashboard/overview` 可作为“优化项”提供更轻量的统计聚合，但必须保留**降级策略**（用 `/api/db/users` + `/api/orders` 拼）以免阻塞前端迁移与部署节奏。
+- **鉴权一致性**：页面入口/菜单变化不影响鉴权口径，仍以 `GET /api/admin` 作为 session/token 校验；401 统一跳登录并清 token。
+
+> 详见会议纪要：`.cursor/meeting/2026-03-10_管理端迁移Mycontent-temp菜单布局讨论.md`
+
+---
+
+## 新增聚合接口 UserDashboardStats
+
+**场景**：小程序「我的」页需要一个聚合接口返回阅读统计，避免多次请求。
+
+**接口**：`GET /api/miniprogram/user/dashboard-stats?userId=xxx`
+
+**数据来源**：
+- `readSectionIds` / `readCount` → `reading_progress` WHERE `user_id = userId`
+- `totalReadMinutes` → `SUM(duration) / 60`（秒转分，最小值 1 分钟）
+- `recentChapters` → `reading_progress` ORDER BY `last_open_at DESC` JOIN `chapters`（最近 5 条**去重**）
+- `matchHistory` → `match_records` COUNT WHERE `user_id = userId`
+
+**三处 bug 修复点**（对比 Mycontent-temp 参考版发现）：
+
+| Bug | 错误做法 | 正确做法 |
+|-----|---------|---------|
+| 最近阅读重复 | 直接取前 5 条（同章节可重复） | `seenRecent` map 去重，保证 5 条不重复 |
+| 阅读时长最小值 | 不足 60 秒返回 0 | `if totalReadSeconds > 0 && totalReadMinutes == 0 { totalReadMinutes = 1 }` |
+| DB 错误状态码 | 返回 200 + `success:false` | 返回 HTTP 500 `InternalServerError` |
+
+**规则沉淀**：新增聚合接口时，先参考已有版本实现，对比 diff 后修复潜在 bug，再提交。
+
+> 详见会议纪要：`.cursor/meeting/2026-03-10_小程序新旧版对比与dashboard接口新增.md`
+
+---
+
+## chapters 表新增 hot_score 字段
+
+### 问题
+
+前端 `ContentPage.tsx` 保存章节时传递 `hotScore` 字段，但后端 model 和数据库均缺少该列，导致：
+```
+Error 1054 (42S22): Unknown column 'hot_score' in 'field list'
+```
+
+### 修复步骤
+
+1. 执行迁移 SQL（`soul-api/scripts/add-hot-score.sql`）：
+   ```sql
+   ALTER TABLE chapters ADD COLUMN hot_score INT NOT NULL DEFAULT 0;
+   ```
+2. 同步 model（`internal/model/chapter.go`）：
+   ```go
+   HotScore int `gorm:"column:hot_score;default:0" json:"hotScore"`
+   ```
+3. 重启后端服务生效
+
+### 规则沉淀
+
+- **model 与 DB 必须同步**：前端传入新字段时，必须先确认 DB 列存在，再确认 model struct 中有对应字段，缺一不可
+- **变更流程**：前端加字段 → ALTER TABLE → 更新 model struct → 重启服务
+- 迁移 SQL 统一放 `soul-api/scripts/` 目录，文件名格式 `add-{描述}.sql`
+
+> 详见会议纪要：`.cursor/meeting/2026-03-10_Toast通知系统全局落地.md`
+

.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-11.md

@@ -0,0 +1,8 @@
+# 后端工程师 经验记录 - 2026-03-11
+
+## 数据库迁移：users 仅 VIP 身份/状态，chapters 补 hot_score
+
+- users 表：迁移脚本只添加 is_vip、vip_expire_date、vip_activated_at、vip_sort、vip_role；不再添加 vip_name、vip_avatar、vip_project、vip_contact、vip_bio（小程序已改为直接读用户资料）。
+- chapters 表：SQL 导出仅有 hot_score_override，Model 使用 hot_score；迁移脚本增加 hot_score 列。
+- 脚本：`soul-api/scripts/sync-users-vip-and-schema.sql`；说明：`soul-api/scripts/README-schema-sync.md`。
+- 详见团队共享：`agent/团队/evolution/2026-03-11.md`。

.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-12.md

@@ -0,0 +1,61 @@
+# 后端工程师 经验记录 - 2026-03-12
+
+## 1. persons 表 token 字段与 DB 迁移
+
+### 问题
+
+新增 @ 人物时报错：`Unknown column 'token' in 'field list'`。GORM model 已加 `Token` 字段，但数据库未执行迁移。
+
+### 解决方案
+
+- **迁移脚本**：`soul-api/scripts/add-persons-token.sql`
+- **执行**：`node .cursor/scripts/db-exec/run.js -f soul-api/scripts/add-persons-token.sql`
+- **内容**：`ALTER TABLE persons ADD COLUMN token VARCHAR(36) NOT NULL DEFAULT '' AFTER person_id` + 唯一索引
+
+### 规则
+
+- **Model 新增字段后**：需编写并执行 ALTER 脚本，GORM AutoMigrate 不一定自动生效（取决于启动时机与连接）
+- **迁移脚本位置**：`soul-api/scripts/`，命名 `add-xxx.sql`
+- **执行方式**：db-exec 脚本读取 soul-api/.env 的 DB_DSN
+
+---
+
+## 2. CKBLead 用 token 兑换真实密钥
+
+- `targetUserId` 现为 persons.token（非 person_id）
+- 查询：`db.Where("token = ?", body.TargetUserID).First(&p)`
+- 取 `p.CkbApiKey` 调用存客宝
+
+---
+
+## 3. 9.9 买断与后端开关（hasFullBook）
+
+### 场景
+
+- 小程序已通过 `hasFullBook` 标识「买断全书」，权限判断和文案都依赖该字段（由 `/api/miniprogram/user/purchase-status` 与 `/api/miniprogram/user/check-purchased` 返回）。
+- 现在需要在用户资料里增加一个布尔开关：运维/客服手动打开后，相当于该用户已经买过 9.9，全书可看，后续不再需要支付。
+
+### 设计要点
+
+- **统一事实来源**：9.9 买断是否生效完全由后端计算，前端只认：
+  - `purchase-status` 返回的 `hasFullBook = true`；
+  - 或 `check-purchased` 返回 `isPurchased = true` 且 `reason = "has_full_book"`。
+- **用户资料开关**：
+  - 在 `users` 表或 user profile 中新增布尔字段（例如 `manual_fullbook`，具体命名按现有规范调整）。
+  - 仅管理端/运维修改该字段，小程序不直接写入。
+- **接口契约调整**：
+  - `/api/miniprogram/user/purchase-status`：
+    - 计算 `hasFullBook` 时，将订单表中的全书订单结果与 `manual_fullbook` 做 **OR**，只要任一为真就返回 `hasFullBook = true`。
+  - `/api/miniprogram/user/check-purchased`：
+    - 对章节做权限判断时，如果由 `manual_fullbook` 推导出可看，应返回：
+      - `isPurchased = true`
+      - `reason = "has_full_book"`
+    - 前端的 `chapterAccessManager.syncLocalCache` 会据此把 `app.globalData.hasFullBook = true` 并同步到 `userInfo.hasFullBook`。
+- **与 VIP 的边界**：
+  - `hasFullBook`（9.9 买断）与 `isVip`（会员）继续解耦：手动开 fullbook 开关不会自动授予 VIP。
+  - VIP 相关逻辑只看 `isVip` / `vipExpireDate`，不受 `manual_fullbook` 影响。
+
+### 规则
+
+- 不在前端增加「跳过支付」开关，所有免 9.9 行为都通过后端折叠到 `hasFullBook/has_full_book` 暴露给小程序。
+- 满足以上约定后，小程序现有代码无需修改即可支持「后台手动赠送 9.9 买断」。

.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-13.md

@@ -0,0 +1,45 @@
+# 2026-03-13 - 文章详情预览统一与内容安全
+
+## 问题 / 场景
+
+- 文章详情目前小程序侧只展示约 20% 内容作为预览，再引导用户付费解锁。
+- 历史实现中前端本地按 20% 计算预览，后端曾同时返回外层 `content`（预览）和 `data.content`（全文），存在「接口约定不统一」和「误用 data.content 泄露全文」的风险。
+- 需求：统一由后端按业务规则截取预览（改为 50%），小程序只按「是否已付费」选择用预览还是全文；未付费时，无论字段层级都不能拿到全文。
+
+## 解决方案
+
+- 在 `internal/handler/book.go` 中调整章节预览逻辑：
+  - `previewContent` 改为按字符数取正文前 50%（`total/2`），同时保证预览不少于 100 个字符；
+  - 预览结尾统一追加 `……（购买后阅读完整内容）` 作为提示文案。
+- 在 `findChapterAndRespond` 中统一内容返回策略：
+  - 先根据 system_config.free_chapters / chapter_config.freeChapters / chapters.is_free / price 判断章节是否免费；
+  - 免费章节：`returnContent = ch.Content`（全文）；
+  - 付费章节：
+    - 若 `checkUserChapterAccess` 判断用户已购买 / VIP / 全书：`returnContent = ch.Content`（全文）；
+    - 否则：`returnContent = previewContent(ch.Content)`（仅预览）；
+  - 构造响应时，将 `chForResponse.Content = returnContent`，并通过：
+    - 外层 `content: returnContent`，
+    - 内层 `data: chForResponse`（其中 `content` 也为 `returnContent`），
+    - 确保未授权用户在任意字段上都拿不到完整正文。
+
+## 与前端的接口约定
+
+- 小程序阅读页通过 `userId` 查询章节详情，`accessManager` 基于返回的章节信息与用户购买状态计算 `accessState`：
+  - 当 `accessState` 为 `free` 或 `unlocked_purchased` 时，前端使用 `res.data.content ?? res.content` 渲染全文；
+  - 当 `accessState` 为未登录 / 未购买时，前端只使用 `res.content` 渲染预览。
+- 预览比例完全由后端控制（当前为 50%），小程序不再自行用 20% 做二次截断，只是把后端提供的预览完整展示出来。
+
+## 代码位置
+
+- 后端：
+  - `soul-api/internal/handler/book.go`
+- 小程序（前端配合）：
+  - `miniprogram/pages/read/read.js`
+  - `miniprogram/pages/read/read.wxml`
+
+## 对后续开发的约定
+
+- 预览长度（包括比例、最小字符数、提示文案）统一由后端控制；如需调整比例，只需修改 `previewContent`，保持接口字段含义不变。
+- 任何需要「只返回部分内容预览」的场景，应优先复用「外层 `content` + 内层 `data.content` 保持一致」的安全模式，避免在不同字段中混放全文与预览内容。
+- 涉及付费内容时，优先在后端用「权限判断 + 统一内容裁剪」实现安全边界，前端只根据状态选择展示预览还是全文。
+

.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-14.md

@@ -0,0 +1,33 @@
+# 2026-03-14 - 内容排名算法修正（排名分公式）
+
+## 问题 / 场景
+
+- 管理端「内容排行」与小程序「精选推荐」共用 `computeArticleRankingSections`，原算法错误：
+  - 使用「原始数值 × 权重」：`hot = readCnt×readWeight + payCnt×payWeight + recencyScore×recencyWeight`
+  - `recencyScore` 为 0–1 的天数衰减，非排名分
+- 管理端修改权重后，列表不刷新（只调了 loadList，未调 loadRanking）。
+
+## 解决方案
+
+### 算法修正（db_book.go computeSectionsWithHotScore）
+
+- **公式**：热度积分 = 阅读权重×阅读排名分 + 新度权重×新度排名分 + 付款权重×付款排名分（三权重之和须为 1）
+- **排名分规则**：
+  - 阅读量前 20 名：第 1 名=20 分 … 第 20 名=1 分，其余 0 分
+  - 最近更新前 30 篇：第 1 名=30 分 … 第 30 名=1 分，其余 0 分
+  - 付款数前 20 名：第 1 名=20 分 … 第 20 名=1 分，其余 0 分
+- **权重配置**：从 `system_config.article_ranking_weights` 读取 readWeight、recencyWeight、payWeight
+- **手动覆盖**：若 `chapters.hot_score > 0`，则优先使用该值
+
+### 与前端约定
+
+- 管理端保存权重后需同时调用 `loadList()` 和 `loadRanking()`，并关闭弹窗，列表才能立即刷新。
+
+## 代码位置
+
+- `soul-api/internal/handler/db_book.go`：`computeSectionsWithHotScore`、`computeArticleRankingSections`
+- 管理端 `ContentPage.tsx`：`handleSaveRankingWeights` 中 loadRanking + setShowRankingAlgorithmModal(false)
+
+## 影响
+
+- 管理端内容排行榜、小程序精选推荐（`/api/miniprogram/book/recommended`）均复用该算法，修正后两端同步生效。

.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-16.md

@@ -0,0 +1,17 @@
+# 后端工程师 经验记录 - 2026-03-16
+
+## ParseAutoLinkContent 必须输出 data-label
+
+- TipTap Mention 仅从 `data-label` 解析显示名，缺则回退显示 `data-id`（token）
+- 新建 mention span：`<span data-type="mention" data-id="TOKEN" data-label="名字">@名字</span>`
+- 已损坏内容（span 内为 token）：用 token 查 persons 取真实名字补回 data-label
+
+## 存客宝创建计划参数
+
+- planType=1、sceneId=9、scenario=9、status=1
+- 管理端添加、文章 @ 自动创建两处均已同步
+
+## new-soul 派对AI 与 content_upload.py（会议：new-soul 新需求与当前项目差异分析）
+
+- content_upload.py 直连 DB 与 soul-api 并存，需核对 chapters 表结构与字段一致性
+- 中长期可规划将文章上传迁移到 soul-api admin/db 接口，统一数据入口

.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-17.md

@@ -0,0 +1,73 @@
+# 后端 - 2026-03-17
+
+## 代付 PayNotify 权益归属修复
+
+### 问题
+
+代付支付回调中，`buyerUserID` 由 openID 解析得到，即**代付人**。权益激活（全书、VIP、章节、余额充值）和分佣均用 `buyerUserID`，导致权益错误给到代付人，而非发起人。
+
+### 修复
+
+引入 `beneficiaryUserID`（权益归属人）：
+
+- **代付订单**：`beneficiaryUserID = order.UserID`（发起人）
+- **普通订单**：`beneficiaryUserID = buyerUserID`（付款人）
+
+权益激活、分佣、取消未支付订单等逻辑统一改用 `beneficiaryUserID`。
+
+### 经验
+
+- 代付场景：`order.user_id` = 发起人，`payer_user_id` = 代付人；权益与分佣必须按 `order.user_id` 处理
+- PayNotify 中 openID 解析得到的是实际付款人，代付时需以 order 的 user_id 为权益归属
+
+---
+
+## gift-pay detail 返回 initiatorUserId
+
+- 供小程序区分发起人/好友，展示不同 UI
+- 字段：`initiatorUserId`（发起人 user_id）
+
+---
+
+## 新版管理端迁移 - 后端任务（会议：2026-03-17）
+
+- **router 补齐**：迁移前注册 5 个路由：`db.GET("/users/rfm")`、`db.GET("/users/journey-stats")`、`admin.GET("/shensheshou/query")`、`admin.POST("/shensheshou/enrich")`、`admin.POST("/shensheshou/ingest")`
+- **待确认**：/api/admin/settings 是否已支持 ossConfig，若不支持需补充
+
+---
+
+## 稳定版源码质量优化（会议：2026-03-17）
+
+- **敏感配置**：生产环境（MODE=release）强制校验，缺敏感 env 则 Fatal
+- **user/track 鉴权**：新增 GET /api/admin/user/track + AdminAuth，原 /api/user/track 保留给小程序 POST 埋点
+- **AdminWithdrawTest**：非 develop 环境返回 404 或拒绝
+
+---
+
+## 会议收尾（2026-03-17）
+
+- 源码优化 10 项全部完成；开发环境测试 10 通过 2 跳过
+
+---
+
+## 性能优化与 Redis 缓存方案落地（2026-03-17）
+
+### Redis 缓存
+
+- **internal/cache**：Get/Set/Del、GetString/SetString；Redis 不可用时回退 DB
+- **已缓存**：book/parts、hot、recommended、stats、config、章节 content
+- **失效**：InvalidateBookParts、InvalidateBookCache、InvalidateConfig、InvalidateChapterContent
+
+### OSS 上传
+
+- **internal/oss**：LoadConfig、Upload、Delete；失败回退本地
+- 配置从 system_config.oss_config 读取
+
+### /health
+
+- 返回 database、redis 连接状态（ok/disconnected/disabled）
+
+### 经验
+
+- Redis 容灾：未配置或失败时回退 DB，不阻塞业务
+- 缓存 key：soul:{业务}:{标识}

.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-18.md

@@ -0,0 +1,41 @@
+# 后端工程师 经验记录 - 2026-03-18
+
+## 功能需求口径整理（按接口契约与风险）
+
+### 需求基准（后端视角）
+- 以 `开发文档/1、需求/以界面定需求.md` 的“界面→接口”映射为准：  
+  - 小程序只用 `/api/miniprogram/*`
+  - 管理端只用 `/api/admin/*`、`/api/db/*`、`/api/orders` 等
+
+### 核心功能域（必须稳定）
+- **阅读与权限**：
+  - 未授权只返回预览；授权返回全文
+  - VIP 全章免费信号必须后端折叠输出，前端只认统一字段（避免各端各自判断）
+- **支付链路**：
+  - 下单→支付→回调→解锁/分润，必须具备幂等与可追溯（订单号、来源、日志）
+- **代付分享（发起人支付，好友领取）**：
+  - 发起人支付后产生可分享 requestSn
+  - 好友领取必须并发安全（名额扣减原子、重复领取幂等）
+  - 权益归属必须正确（代付场景 beneficiaryUserID=发起人）
+- **推广/分润/提现**：
+  - 分润规则可配置，计算口径一致
+  - 提现流转：申请→审核/打款→回写状态→订阅消息
+
+### 分享场景风险点（联调/验收必测）
+- **朋友圈 singlePage**：属于前端能力限制，但后端要做到：
+  - 接口幂等（前端重试/重复进入会更频繁）
+  - 错误码与提示文案清晰（便于前端引导“前往小程序”）
+
+### 文档归档（后端相关）
+- 里程碑推进表：`开发文档/10、项目管理/项目落地推进表.md`
+- 测试流程与回归口径：`scripts/test/功能测试流程.md`
+
+## 超级个体开通后自动创建@人（Person）与资料完善 flags
+
+### 幂等与建模建议
+- 自动创建 Person 建议以业务主键（`userId`）作为**幂等键**，避免仅依赖昵称导致重名/改名混乱。
+- 倾向在 `persons` 增加 `user_id`（并做唯一索引/约束），后续昵称变更时可按 `user_id` 同步更新 `name`。
+
+### 端上资料完善判断
+- 默认头像/昵称判定不建议只靠前端字符串规则；后端可在用户资料/登录态接口返回明确布尔值（如 `profileNeedComplete` / `isDefaultAvatar` / `isDefaultNickname`），小程序仅消费并跳转引导页。
+

.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-24.md

@@ -0,0 +1,22 @@
+# 后端工程师 经验记录 - 2026-03-24
+
+## 开发进度同步会议
+
+### 提现相关（2026-03-20 已落地，与文档一致）
+- 审批逻辑：doApproveWithdrawal 校验「累计-已提现>=待审核」，-0.01 浮点容差。
+- referral_config：withdrawFee、enableAutoWithdraw、minWithdrawAmount 使用正确。
+- admin_withdrawals：fail_reason、error_message 落库。
+
+### router 缺失 handler 补齐（编译通过）
+- `BookRanking`：`book.go`，复用 `computeArticleRankingSections`，`?limit=` 默认 50、最大 200；字段与 `sectionListItem` 对齐（无 `titles` 字段）。
+- `DBPersonPinnedToken` / `CKBPinnedPerson`：`db_person.go`，置顶人物 `Order("updated_at DESC").First`，与 `DBPersonPinnedList` 首条一致；小程序无置顶返回 `data: null`。
+- `AdminDashboardLeads`：`admin_dashboard.go`，`ckb_lead_records` / `ckb_submit_records` 总量、今日量、留资去重用户数。
+
+### 待办
+- router 补齐：users/rfm、users/journey-stats、shensheshou 共 5 个。
+- 确认 /api/admin/settings 是否支持 ossConfig。
+
+## 需求与进度及三端闭环评审
+
+- 三端路由分组未被破坏；缺口为业务校验：提现 wechat_id、CKBJoin investor 付费、MatchUsers 发起者资料。
+- 失败响应需带 `needBindWechat` / `errorCode` 等稳定字段，配合小程序 `err.response` 约定（详见团队 evolution 与 meeting 纪要）。

.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-31.md

@@ -0,0 +1,6 @@
+# 后端工程师 经验记录 - 2026-03-31
+
+## 会议：超级个体列表与 @ 列表融合
+
+- 列表融合优先在现有聚合接口（如 `/api/db/vip-members`）上增加 Person 关联只读字段，避免新表与重复「谁算超级个体」规则；注意批量查询、路由组边界不变。
+- 字段命名宜与 read-extras / mention 侧对齐，便于管理端一行展示。

.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-04-02.md

@@ -0,0 +1,8 @@
+# 后端工程师 经验记录 - 2026-04-02
+
+## 会议：工作进度与需求同步会
+
+- **场景**：进度同步 + deploy 目录变更与业务待续项并行。
+- **要点**：`soul-api/deploy` 改动合并前应用 compose（或等价）验证，README 与 compose 环境变量保持一致；vip-members 聚合 Person 字段优先，满足管理端 UsersPage 联调。
+- **路由**：miniprogram / admin / db 分组边界不变。
+- **待办**：问题与作答区 Q2、Q3 作答后闭环。

.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-04-13.md

@@ -0,0 +1,6 @@
+# 后端工程师 经验记录 - 2026-04-13
+
+## 会议：按功能同步开发文档
+
+- **要点**：接口变更须写明路由组（miniprogram/admin/db）、路径、字段与错误码；表结构/迁移在部署文档或临时需求池留痕；历史待办按 P0/P1 标注与依赖方。
+- **待办**：router/ossConfig、vip-members 等待办在文档中优先级化。

.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-04-14.md

@@ -0,0 +1,6 @@
+# 后端工程师 经验记录 - 2026-04-14
+
+## 吸收沉淀：接口与需求文档同步
+
+- 新增/变更接口须在需求或运营摘要中写明 **路由组（miniprogram/admin/db）**、路径、关键字段与错误码；迁移写在 `开发文档/8、部署/` 或临时需求池（若存在）。
+- **P0/P1 待办**（router、ossConfig、vip-members 等）在 `需求汇总.md` 已单列 BACKEND-P0 行，合并前更新状态与依赖方。

.cursor/archive/agents-legacy-soul/后端工程师/evolution/索引.md

@@ -0,0 +1,14 @@
+# 后端工程师 经验索引
+
+| 日期 | 摘要 | 文件 |
+|------|------|------|
+| 2026-03-05 | soul-api 合并状态确认；orders、distribution 接口核对 | [2026-03-05.md](./2026-03-05.md) |
+| 2026-03-05 | 文章详情@某人：content 内嵌 @ 标记、miniprogram 添加好友接口 | [2026-03-05.md](./2026-03-05.md) |
+| 2026-03-10 | 管理端迁移 Mycontent-temp：接口边界不变；overview 聚合接口可选但需降级 | [2026-03-10.md](./2026-03-10.md) |
+| 2026-03-12 | persons token 字段与 DB 迁移；CKBLead 用 token 兑换 ckb_api_key | [2026-03-12.md](./2026-03-12.md) |
+| 2026-03-14 | 内容排名算法修正：排名分公式（阅读/新度/付款前 N 名），支持 hot_score 手动覆盖 | [2026-03-14.md](./2026-03-14.md) |
+| 2026-03-16 | ParseAutoLinkContent data-label；存客宝 create planType/sceneId/status | [2026-03-16.md](./2026-03-16.md) |
+| 2026-03-17 | 代付 PayNotify beneficiaryUserID 权益归发起人；gift-pay detail 返回 initiatorUserId | [2026-03-17.md](./2026-03-17.md) |
+| 2026-03-24 | router 缺失四 handler：BookRanking、DBPersonPinnedToken、CKBPinnedPerson、AdminDashboardLeads | [2026-03-24.md](./2026-03-24.md) |
+| 2026-04-13 | 按功能同步开发文档：接口/迁移文档化与 P0/P1 标注 | [2026-04-13.md](./2026-04-13.md) |
+| 2026-04-14 | 吸收沉淀：接口与需求表同步、BACKEND-P0 行 | [2026-04-14.md](./2026-04-14.md) |

.cursor/archive/agents-legacy-soul/团队/evolution/2026-02-27.md

@@ -0,0 +1,10 @@
+# 2026-02-27 | 团队经验
+
+> 本日跨角色共享的架构决策、业务规则。格式：类型 | 摘要 | 关联 Skill
+
+---
+
+## 输入框样式（前端通用）
+
+- **最佳实践 | 输入框 padding**：设置 input 的 padding/背景/边框时，用 div 或 view 包裹 input；padding 写在容器上，input 仅做文字样式，可避免光标截断、布局异常。
+- **适用**：小程序、管理端（React input 同理）

.cursor/archive/agents-legacy-soul/团队/evolution/2026-02-28.md

@@ -0,0 +1,21 @@
+# 团队共享 经验记录 - 2026-02-28
+
+## stitch_soul 需求评审会议
+
+- **stitch_soul 定位**： stitch 产品线在 Soul 创业派对上的扩展，串联「内容阅读 + 导师咨询」变现路径。
+- **架构协同**：需与现有 soul-api/soul-admin/miniprogram 架构协同；严禁混用 admin/miniprogram 路由；接口按使用方挂载。
+- **开发顺序**：产品补充需求文档 → 后端给出模型与接口方案 → 管理端/小程序按优先级分阶段实现。
+
+## 会议规则升级
+
+- **问题与作答区**：开完会后必须将待确认/待澄清问题列出，在会议纪要中增加「问题与作答区」节，问题表含：序号、问题、责任角色、作答（留空供后续填写）；便于追溯闭环。
+
+## 个人资料页实现评估会议
+
+- **展示/编辑页协同**：profile-show 与 profile-edit 共用同一 API，skills 等扩展字段需双向同步；配色统一为 enhanced（#5EEAD4）强化品牌一致。
+
+## 文章类型（普通版/增值版）需求分析会议
+
+- **增值版计价**：基础价 + Σ(增值章节单价)，按章购买、按章累加。
+- **后 N 章**：指全书最后 N 个 section；N 可配置。
+- **普通版与增值版**：分开、互斥的两套产品，用户购买其一。

.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-05.md

@@ -0,0 +1,17 @@
+# 团队 经验记录 - 2026-03-05
+
+## 分支冲突后功能完整性分析会议（跨角色共享）
+
+- **分支冲突后各端需做完整性自查**：
+  - 产品：核对需求文档与实现一致性
+  - 后端：在 soul-api 确认合并状态，核对 orders、distribution 等接口
+  - 管理端：全功能自测，记录 404/异常接口
+  - 小程序：核心流程自测，确认 orders 接口；修正 app.json 格式
+  - 测试：制定「分支合并后回归清单」
+- **待确认**：`完整的` 分支上的提交是否已全部并入 devlop；soul-api 的版本管理与合并策略。
+
+## 文章详情 @某人 高亮与一键加好友方案讨论（跨角色共享）
+
+- **内容格式**：正文内嵌 @ 标记，统一格式 `@[昵称](userId)`（或约定等价格式），后端/管理端/小程序共用。
+- **添加好友接口**：归属 soul-api 的 miniprogram 组，与存客宝 api_v1 分离；path、入参由后端/产品确认后写入开发文档。
+- **分工**：管理端编辑侧插入 @ 并写入 content；小程序解析、高亮、点击调添加好友；后端提供章节 content 与添加好友接口。

.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-08.md

@@ -0,0 +1,20 @@
+# 团队共享 经验记录 - 2026-03-08
+
+## 文章阅读付费规则澄清与后端修复
+
+### 业务规则（全团队共识）
+
+1. **非会员专属文章**：免费，无需登录/付费；以管理端「系统设置 → 免费章节」配置为准
+2. **VIP 会员**：开通 VIP 后，所有文章免费阅读；`check-purchased` 按 `is_vip=1` 且 `vip_expire_date>NOW` 返回 `isPurchased: true`
+
+### 技术实现
+
+- **免费章节**：soul-api `book.go` 从 `system_config.free_chapters` 或 `chapter_config.freeChapters` 读取，优先于 chapters 表
+- **VIP 全章免费**：`user.go` 的 `UserCheckPurchased` 已实现，无需改动
+
+### 影响角色
+
+- 后端：book.go 变更，部署后需重启
+- 管理端：确保免费章节配置正确
+- 产品：作为验收规则
+- 小程序：无变更

.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-10.md

@@ -0,0 +1,67 @@
+# 团队共享 经验记录 - 2026-03-10
+
+## 管理端迁移 Mycontent-temp：菜单/布局新规范基线
+
+### 决议（团队共享）
+
+- **目标态基线**：以 `Mycontent-temp/soul-admin` 的 `AdminLayout` + `SettingsPage` 作为“新规范基线”，后续管理端所有菜单/布局调整按该基线执行，避免两套后台并行发散。
+- **主导航收敛**：侧栏只保留 5 个主入口（概览/内容/用户/找伙伴/推广），系统设置固定底部，取消“更多”折叠入口。
+- **功能不丢但入口收敛**：订单/提现/推广设置/VIP角色/导师等页面保留路由可达，入口通过概览卡片或页面内跳转承载；作者/管理员设置并入 `/settings?tab=author|admin`。
+
+### 实施建议
+
+- 迁移时优先保证：**鉴权一致（GET /api/admin）**、**路由可达性**、**菜单一致性**，再逐步优化概览聚合接口与快捷入口。
+
+---
+
+## 新旧版代码对比方法论（Mycontent-temp vs miniprogram）
+
+### 场景
+
+存在两个并行代码库（主线 + 预览版），需要判断哪个版本更可靠，以及如何安全地吸收另一版的优点。
+
+### 最佳实践
+
+1. **批量 diff 优先于逐文件比较**：用 PowerShell 批量对比 WXSS/JS/WXML 文件，精确列出「相同/有差异」的文件清单，再聚焦差异文件逐一分析。
+2. **以功能完整性为基准**：不以「新/旧」日期判断优劣，而以**功能是否完整**为主要依据；本次判断旧版（miniprogram）才是功能更完整的版本。
+3. **差异归类**：
+   - **旧版有、新版没有** → 旧版是主线，保留旧版
+   - **新版有、旧版没有** → 评估是否需要移植（如 dashboard-stats 调用）
+   - **样式差异** → 对比具体行数，判断是改进还是遗漏
+4. **接口对比时对照新版参考修复 bug**：新版的接口实现即使存在，也可能有遗漏；参考后自行修复（去重、最小值、错误码等）再提交。
+
+### 适用场景
+
+- 分支合并前的功能完整性分析
+- 迁移预览版到主线时的取舍决策
+- 跨版本 bug 溯源
+
+> 同时影响：小程序开发工程师、后端工程师
+> 详见会议纪要：`.cursor/meeting/2026-03-10_小程序新旧版对比与dashboard接口新增.md`
+
+---
+
+## Toast 通知系统 & DB 变更 SOP（团队共享）
+
+### Toast 批量替换方法论
+
+使用 PowerShell 正则脚本批量替换 alert → toast，**替换后必须人工复查 `toast.info()`**：
+- 验证提示类（"请输入/请填写/密码至少/ID已存在"）被脚本误判为 info，应改为 error
+- 核查方式：`grep -r "toast.info(" src/` 逐条确认语义
+
+### DB 变更 SOP（前后端联动）
+
+当前端新增字段时，完整变更流程：
+
+| 步骤 | 执行方 | 操作 |
+|------|--------|------|
+| 1 | 后端 | 执行 `ALTER TABLE` 或用 `db-exec` 脚本 |
+| 2 | 后端 | 更新 `internal/model/*.go` struct |
+| 3 | 后端 | 重启服务验证 |
+| 4 | 管理端 | 确认保存请求不再报 1054 |
+
+若跳过任一步骤，GORM 写入时必报 `Unknown column`。
+
+> 同时影响：管理端开发工程师、后端工程师
+> 详见会议纪要：`.cursor/meeting/2026-03-10_Toast通知系统全局落地.md`
+

.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-11.md

@@ -0,0 +1,30 @@
+# 团队共享 经验记录 - 2026-03-11
+
+## 以界面定需求与业务逻辑对齐（全团队）
+
+### 背景
+
+用户要求开发团队对齐业务逻辑，并更新开发文档和需求文档，**以界面来定需求**。
+
+### 决议与产出
+
+1. **新增《以界面定需求》**
+   - 路径：`开发文档/1、需求/以界面定需求.md`
+   - 内容：原则（界面即需求、三端路由隔离、用户/VIP 展示以用户资料为准）；小程序界面清单（每页功能要点与主要 /api/miniprogram/* 接口）；管理端界面清单（每页功能要点与主要 /api/admin/*、/api/db/*、/api/orders 等）；业务逻辑对齐（用户与 VIP 资料展示、三端 API 边界、免费章与 VIP、分销提现）。
+
+2. **需求基准**
+   - 需求以《以界面定需求》为准；《需求汇总》增加「需求基准（必读）」节，新增/变更功能先对齐界面再更新需求清单。
+   - 开发文档 README 增加《以界面定需求》链接；运营与变更第九部分记录本次对齐。
+
+3. **用户/VIP 资料规则（与界面一致）**
+   - 展示以**用户资料**为准（nickname、avatar、projectIntro、phone 等）；不再单独存 vip_name、vip_avatar、vip_project、vip_contact、vip_bio；数据库迁移脚本不再新增上述五列；VIP 身份/状态（is_vip、vip_expire_date、vip_activated_at、vip_sort、vip_role）仍保留。
+
+### 适用角色
+
+- 产品经理：需求与验收以《以界面定需求》为准。
+- 小程序 / 管理端 / 后端：开发与联调以界面清单中的功能要点与主要接口为准；业务规则以《以界面定需求》第四节为准。
+- 测试：功能与回归以界面清单与业务逻辑对齐节为验收范围。
+
+### 会议纪要
+
+- `.cursor/meeting/2026-03-11_开发团队对齐业务逻辑与以界面定需求会议收尾.md`

.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-12.md

@@ -0,0 +1,47 @@
+# 团队共享 经验记录 - 2026-03-12
+
+## 密钥/token 设计：关联小程序与 @ 人物
+
+### 背景
+
+- **关联小程序**：添加时生成 32 位英文+数字密钥，链接标签存 key，小程序点击 # 时用 key 查 appId 再跳转
+- **@ 人物**：添加时生成 32 位 token，文章 @ 时存 token，小程序点击 @ 时用 token 兑换真实 ckb_api_key 后加好友
+
+### 设计原则
+
+1. **不暴露真实密钥**：管理端配置的真实密钥（appId、ckb_api_key）不写入文章内容，仅存可对外传递的 token/key
+2. **服务端兑换**：小程序端只传 token/key，后端用其查表得到真实密钥再调用第三方
+3. **不兼容旧数据**：项目未上架，无需兼容 person_id、appId 等旧格式
+
+### 数据流
+
+| 场景 | 添加时 | 内容存储 | 小程序点击 | 后端兑换 |
+|------|--------|----------|------------|----------|
+| 关联小程序 | 生成 key | data-mp-key | 传 mpKey | 查 linked_miniprograms 得 appId |
+| @ 人物 | 生成 token | data-id | 传 targetUserId | 查 persons 得 ckb_api_key |
+
+### 适用角色
+
+- 后端：persons.token、linked_miniprograms.key、CKBLead 兑换逻辑
+- 管理端：链接标签选 key、@ 人物 id=token、列表展示
+- 小程序：contentParser 解析 mpKey、onLinkTagTap/onMentionTap 传 key/token
+
+---
+
+## 9.9 买断与团队级约定
+
+### 结论
+
+- 「9.9 买断全书」在三端的唯一来源是后端的 `hasFullBook`/`has_full_book` 信号：
+  - 小程序：只看 `/user/purchase-status` 的 `hasFullBook` 和 `/user/check-purchased` 的 `reason = "has_full_book"`。
+  - 后端：可以通过订单或用户资料开关（如 `manual_fullbook`）计算该状态。
+  - 管理端：如需赠送 9.9 买断，应只改后端用户资料中的开关，不直接改前端逻辑。
+
+### 约定
+
+- 任意「免 9.9」或「赠送全书」能力都必须：
+  - 由后端在 purchase-status/check-purchased 中折叠为统一的 `hasFullBook/has_full_book`。
+  - 不允许在小程序或管理端各自新增本地开关绕过后端逻辑。
+- VIP 与 9.9 买断继续分离：
+  - `hasFullBook` → 只代表书的权限；
+  - `isVip` → 代表会员权益（案例库、增值版等），两者可以独立打开。

.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-13.md

@@ -0,0 +1,42 @@
+# 2026-03-13 - 文章详情预览规则统一（小程序 + 后端）
+
+## 场景
+
+- 文章详情页采用「部分内容预览 + 付费解锁全文」的收费模式。
+- 历史实现中，预览比例由小程序本地按 20% 行数截取，后端可能同时返回预览与全文两个 content 字段，存在：
+  - 三端对「预览长度」的理解不一致；
+  - 前端误用 `data.content` 导致未付费用户拿到全文的潜在风险。
+- 本次目标：将「预览长度 + 安全边界」下沉到后端统一控制，小程序只按「是否已解锁」选择展示预览或全文。
+
+## 团队级决策
+
+- 预览长度统一由 **soul-api** 控制：
+  - 当前规则：对付费章节，未解锁用户默认看到正文前 **50%**，且不少于 100 个字符，末尾追加「购买后阅读完整内容」提示；
+  - 未来如需改为 40% / 30% 等，只需调整后端 `previewContent`，前端逻辑保持不变。
+- 接口约定统一：
+  - 章节详情接口（含 `/api/miniprogram/book/chapter/:id`、`/api/miniprogram/book/chapter/by-mid/:mid`）返回的：
+    - 外层 `content` 字段，
+    - 内层 `data.content`（Chapter.Content）字段，
+    - **在同一次响应中必须保持一致**：
+      - 免费或已解锁：两处都是全文；
+      - 未解锁：两处都是预览（50%）。
+  - 不允许出现「外层是预览、`data.content` 是全文」这类混合返回，避免前端误用泄露付费内容。
+- 小程序阅读页约定：
+  - 只根据 `accessState` 判断是否有权看全文；
+  - 有权限时使用 `data.content` / `content` 渲染全文；
+  - 无权限时仅使用后端返回的预览内容，不再在前端重新按 20% 行数切割。
+
+## 影响角色
+
+- **后端工程师（soul-api）**：
+  - 负责实现和维护 `previewContent` 预览算法及权限判断逻辑；
+  - 在新增/修改与付费内容相关的接口时，必须遵守「外层 content 与 data.content 一致」的安全约定。
+- **小程序开发工程师**：
+  - 阅读页不自行决定预览比例，只展示后端返回的预览内容；
+  - 通过 `accessManager` 与章节详情响应判断权限，严格按照 `accessState` 切换「预览 / 全文」视图。
+
+## 对后续迭代的提示
+
+- 若未来引入「增值版内容」「章节试读长度差异化」等新收费形态，优先在后端扩展 `previewContent` 与权限判断逻辑，对前端暴露统一、稳定的字段语义。
+- 若管理端需要控制预览比例或提示文案，可在配置中心增加相关配置项，由后端读取后影响 `previewContent` 行为，保持三端一致。
+

.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-14.md

@@ -0,0 +1,17 @@
+# 2026-03-14 - 内容排名算法跨端复用约定
+
+## 业务规则
+
+- **热度积分公式**：阅读权重×阅读排名分 + 新度权重×新度排名分 + 付款权重×付款排名分（三权重之和须为 1）
+- **排名分规则**：阅读量前 20 名（20~1 分）、最近更新前 30 篇（30~1 分）、付款数前 20 名（20~1 分）
+
+## 跨端复用
+
+- **管理端**：`/api/db/book?action=ranking` → `computeArticleRankingSections`
+- **小程序**：`/api/miniprogram/book/recommended` → `computeArticleRankingSections`（取前 3 条）
+- 两者共用同一套算法、权重配置（`article_ranking_weights`）、置顶配置（`pinned_section_ids`）
+
+## 约定
+
+- 排名算法修改只需改 soul-api 一处，管理端与小程序自动同步。
+- 管理端保存权重后必须调用 `loadRanking()` 刷新列表，否则用户看不到变化。

.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-16.md

@@ -0,0 +1,12 @@
+# 团队 经验记录 - 2026-03-16
+
+## TipTap Mention 显示规则
+
+- **data-label 必填**：TipTap Mention 的 label 仅从 `data-label` 解析，不解析 span 内文本
+- 后端 ParseAutoLinkContent 输出 mention 时必须含 data-label，否则管理端重开后显示 token 而非名字
+
+## new-soul 派对AI 与 Mycontent 关系（会议：new-soul 新需求与当前项目差异分析）
+
+- new-soul 派对AI（魂AI）9 技能 5 组：魂资/魂流/魂产/魂码/魂质
+- 与 Mycontent 三端（soul-api、soul-admin、miniprogram）为同一业务不同层面：运营侧 vs 产品侧
+- 路径差异（Mac vs Windows）需在文档中说明

.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-17.md

@@ -0,0 +1,66 @@
+# 团队 - 2026-03-17
+
+## 代付美团式流程与权益归属约定
+
+### 流程约定
+
+1. **入口**：读页「找好友代付」→ 创建请求 → **跳转代付详情页**（不再弹窗）
+2. **代付页**：发起人看到「分享给好友」，好友看到「帮他付款」
+3. **后端**：detail 返回 `initiatorUserId`，前端据此区分
+
+### 权益与分佣约定
+
+- 代付订单：`order.user_id` = 发起人，`payer_user_id` = 代付人
+- 权益（全书、VIP、章节、余额充值）归属发起人
+- 分佣按发起人的推荐关系计算
+- PayNotify 中 openID 解析得到的是代付人，权益与分佣必须用 `order.user_id`
+
+### 同时影响
+
+- 小程序：代付详情页双态 UI、读页跳转
+- 后端：PayNotify beneficiaryUserID、detail initiatorUserId
+
+---
+
+## 新版管理端迁移到稳定版（会议：2026-03-17）
+
+### 决议
+
+- **内容管理**：以稳定版为主，不采纳新版
+- **新版独有**：API 文档 Tab、api-docs 独立页、OSS 配置、编辑时手机号禁用、鉴权逻辑 → **全部吸纳**
+- **后端**：迁移前补 router（users/rfm、journey-stats、shensheshou 共 5 个）
+
+### 影响角色
+
+- 管理端开发工程师：主导迁移
+- 后端开发：router 补齐、ossConfig 确认
+- 测试人员：迁移后验收
+
+---
+
+## 稳定版源码质量优化（会议：2026-03-17）
+
+- **原则**：增量修复、不改功能逻辑；高优安全项优先，中优可维护项次之，低优可后续迭代
+- **影响角色**：后端、管理端、小程序、测试
+
+---
+
+## 会议收尾（2026-03-17）
+
+- 源码优化 10 项全部完成；功能测试流程定稿；开发环境测试 10 通过 2 跳过
+
+---
+
+## 性能优化与 Redis 缓存方案落地（2026-03-17）
+
+### 架构约定
+
+- **Redis 容灾**：不可用时回退 DB，不阻塞业务
+- **缓存 key**：soul:{业务}:{标识}
+- **OSS 上传**：优先 OSS，失败回退本地
+
+### 影响角色
+
+- 后端开发：cache、oss 包；/health 增强
+- 管理端开发工程师：OSS 配置后上传自动优先 OSS
+- 测试人员：test_upload.py、/health 验证、部署后回归缓存接口

.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-18.md

@@ -0,0 +1,24 @@
+# 团队 经验记录 - 2026-03-18
+
+## 分享链路统一规则：兼容朋友圈 singlePage（单页模式）
+
+### 背景
+微信“朋友圈分享”点进小程序页可能是 **singlePage**，能力不完整；如果不做判断，容易出现支付/登录/领取等链路断裂，引发转化损失与投诉。
+
+### 团队级决议（跨端共识）
+- **任何“分享进入”的关键流程**（支付、代付、领取、绑定等）都要：
+  - **识别 singlePage**：`wx.getSystemInfoSync().mode === 'singlePage'`（并允许通过 `app.globalData.isSinglePageMode` 兜底标记）
+  - **做能力降级**：单页模式不执行强动作（支付/自动领取/自动登录等）
+  - **给出明确引导**：提示用户点击底部 **「前往小程序」** 进入完整版后再操作
+
+### 落地建议
+- UI/交互层：统一封装 `ensureFullAppMode()`（或页面内统一判断），避免每个按钮散落实现导致漏判
+- 测试层：新增用例覆盖“朋友圈 singlePage 打开 + 点击关键按钮”应出现引导而非报错/卡死
+
+## 超级个体开通后自动创建@人与资料完善拦截（跨端共识）
+
+### 团队级决议
+- “可被 @ 的人”统一走 Person 体系，避免为超级个体另建一套 mention 逻辑。
+- 幂等键应绑定业务主键（优先 `userId`），展示名同步为昵称（具体同步规则由产品确认）。
+- 默认资料判定尽量由后端提供明确 flags，前端仅做跳转与阻断，并保留兜底规则。
+

.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-24.md

@@ -0,0 +1,22 @@
+# 团队 经验记录 - 2026-03-24
+
+## 开发进度同步会议 - 文档同步原则（跨角色共识）
+
+### 团队级决议
+- **实现变更后**需同步更新：`开发文档/1、需求/需求汇总.md`、`开发文档/10、项目管理/运营与变更.md` 及对应角色 `agent/开发助理/项目索引/{角色}.md`。
+- **项目索引**：每次开发完成或会议收尾后，在开发进度表追加一行（含日期），并将「最后更新」改为当前日期。
+- 避免文档与实现脱节：索引滞后会导致下次同步会议重复盘点。
+
+### 落地建议
+- 各角色在完成功能开发或吸收经验时，主动更新项目索引。
+- 橙子收尾时统一检查并补齐索引。
+
+## 需求与进度及三端闭环评审（跨角色）
+
+### 结论摘要
+- **主业务闭环**：阅读/付费/代付/分销/提现主链路在文档与里程碑上成立；**规则闭环**有已知缺口，以《产品意图与功能闭环分析》《需求未补齐清单》为准。
+- **三端配套**：小程序页面域与管理端路由域整体对齐；**miniprogram/admin/db 边界未被破坏**。
+- **工程契约**：统一「失败时 body 可解析」约定（`err.response`），否则后端 errorCode 设计无法在前端落地。
+
+### 详见
+- `.cursor/meeting/2026-03-24_需求与进度及三端闭环评审.md`

.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-31.md

@@ -0,0 +1,7 @@
+# 团队 经验记录 - 2026-03-31
+
+## 会议：超级个体列表与 @ 列表融合
+
+- **架构决议**：先 **数据与入口融合（接口字段 + 管理端互链）**，再视需求做单页；不先合并数据库表。
+- **路由约定不变**：小程序仅 `/api/miniprogram/*`，管理端 `/api/db/*` 聚合；详见 `meeting/2026-03-31_超级个体与@列表融合.md`。
+- **业务澄清（@ 列表与绑定）**：@ 列表已承载超级个体与人物的绑定；**合并后不应再单独保留「超级个体绑定」这一层**，以 @ 人物 ↔ 用户为真源，运营字段（排序/Webhook/获客等）挂在用户侧展示即可。

.cursor/archive/agents-legacy-soul/团队/evolution/2026-04-02.md

@@ -0,0 +1,8 @@
+# 团队 经验记录 - 2026-04-02
+
+## 会议：工作进度与需求同步会
+
+- **跨角色决议**：
+  - 融合方案落地顺序：后端 vip-members 聚合 → 管理端 UsersPage → 测试全量回归清单；小程序回归为主。
+  - 部署变更与业务 PR 区分 scope，deploy 合并前环境验证必做。
+- **详见**：`.cursor/meeting/2026-04-02_工作进度与需求同步会.md`

.cursor/archive/agents-legacy-soul/团队/evolution/2026-04-13.md

@@ -0,0 +1,6 @@
+# 团队 经验记录 - 2026-04-13
+
+## 会议：按功能同步开发文档（跨角色）
+
+- **决议**：功能完成定义包含 **代码可合并状态 + 当日文档/项目索引一行摘要（含日期）**；跨端字段或接口变更除各角色文档外，须在团队 evolution 或会议纪要留契约摘要。
+- **关联**：详见 `agent/产品经理|后端工程师|管理端开发工程师|小程序开发工程师|软件测试/evolution/2026-04-13.md` 与 `.cursor/meeting/2026-04-13_按功能同步开发文档.md`。

.cursor/archive/agents-legacy-soul/团队/evolution/2026-04-14.md

@@ -0,0 +1,19 @@
+# 团队 经验记录 - 2026-04-14
+
+## 吸收沉淀：小程序优先闭环 + 需求同步
+
+### 场景
+
+评审「功能是否闭环」、区分界面写死与配置化、识别仅有样式无管理端入口、评估对其它模块的影响。
+
+### 结论（团队约定）
+
+1. **逆推顺序**：从小程序用户路径出发 → 数据来源（常量 / 本地 / `app.request`）→ `/api/miniprogram/*` 是否存在与错误语义 → 是否需要 **管理端或远程配置**（运营是否会改、是否与钱/风控相关）→ 是否影响支付/登录/分享/其它页 `onShow`。
+2. **写死 vs 配置化**：按 **变更频率、责任主体（运营/研发）、风险** 决策；需运行时开关/灰度时采用 **Feature Toggle** 思路（见业界 Martin Fowler *Feature Toggles*），避免永久堆砌 `if(flag)` 无退役计划。
+3. **壳功能信号**：有入口但无 API、仅有样式、管理端无对应配置且业务上明显需运营改的，标为 **技术债或假完成**，需求表状态不得标「已完成」。
+4. **跨模块同步**：契约线（字段/枚举/缓存）、流程线（支付/分销/scene）、权限配置线；变更须在 **需求汇总 / 运营与变更 / 纪要** 之一可追溯，并双写本文件或 `2026-04-13` 纪要中的契约摘要。
+5. **仓库需求真源**：本仓库已建 `开发文档/1、需求/需求汇总.md` 与 `开发文档/10、项目管理/运营与变更.md`，与 `.cursor/meeting/`、各角色 evolution 交叉引用。
+
+### 同时影响
+
+小程序、管理端、后端、测试、产品（文档与验收）。

.cursor/archive/agents-legacy-soul/团队/evolution/2026-04-15.md

@@ -0,0 +1,50 @@
+# 团队 经验记录 - 2026-04-15
+
+## 联网吸收：优秀编程思维 → 智能体执行约束
+
+> 以下为公开资料的**提炼与落地映射**，便于 Soul 多智能体（Cursor 角色）统一行为；**非**替代项目 boundary / Skill 全文。
+
+### 1. 垂直切片（Vertical slicing）
+
+- **含义**：按「用户可感知的一小条价值」贯穿 **展示 → 接口 → 数据/配置**，而不是长期只做「全后端再全前端」的水平分层半成品。
+- **对智能体**：拆任务时优先 **end-to-end 最小可演示**（例如：一条只读列表从真实 API 出数），再迭代字段与交互；避免单次会话产出大量未接线 UI。
+
+**参考**：敏捷社区对 vertical slicing 的讨论（如 *The Art of the Vertical Slice* 等文章，关键词 *vertical slice user story*）。
+
+### 2. 追踪弹（Tracer bullets）
+
+- **出处思想**：《The Pragmatic Programmer》——用一发「能穿过各层的薄路径」验证架构是否通畅。
+- **与原型区别**：原型可丢；追踪弹是**进主分支的骨架**，后续在其上增厚。
+- **对智能体**：强制 **小步、可编译、可运行、可测** 的增量；先打通再美化，降低大模型「一次写太多未验证代码」的风险。延伸阅读：*Tracer Bullets: Keeping AI Slop Under Control*（`https://www.aihero.dev/tracer-bullets`）。
+
+### 3. AI 编码与多智能体：验证优先
+
+- **上下文优先**：先给目的、约束、边界、失败模式，再让生成代码（多篇 2024–2025 *AI coding best practices* 共性）。
+- **分块生成 + 人审合并**：大纲 → 分文件小改 → 跑测试/静态检查；不把未读 diff 直接合并。
+- **评估维度（借鉴 Agent 质量讨论）**：任务是否完成、工具/接口调用是否准确、是否引入多余依赖（参见 AWS 等「Agent 质量评估」类文章中的 TCR、工具准确率等提法）。
+
+### 4. 工程文化：无责复盘与简单性
+
+- **Blameless postmortem**：复盘关注**系统与流程**如何允许失误、行动项是否可验证，避免归罪个人；利于真实写入经验库（Google SRE Book — Postmortem Culture：`https://sre.google/sre-book/postmortem-culture/`）。
+- **简单性**：偏好无聊但清晰的实现；与 Feature Toggle 一样，**实验性分支要有退役计划**。
+
+### 5. 映射到本仓库（Soul）
+
+| 外部思维 | 本仓库落地 |
+|----------|------------|
+| 垂直切片 / 追踪弹 | 跨端任务走 `role-flow-control`：先契约与最小联调，再扩功能；纪要/需求表可追溯 |
+| 验证优先 | `change-checklist`、测试 Skill、`app.request` 与三端路由自检 |
+| 无责复盘 | `.cursor/meeting/*` 问题与作答区 + 各角色 `evolution` 按日沉淀 |
+| 简单性 | 禁止跨端乱调路由；避免无退役计划的永久 feature flag |
+
+---
+
+## 业务补齐（同日追加）
+
+- **`app.request`**：`success:false` 与部分非 200 响应在 `reject` 的 `Error` 上挂载 **`response`**，与 `miniprogram-dev` Skill 及 `referral/my` 提现分支一致。
+- **导师咨询支付**：`productType=mentor_consultation`，`getStandardPrice` 校验预约单归属与金额；`activateOrderBenefits` + `PayNotify` 将 `mentor_consultations.status` 置 `paid`；**分销佣金**对导师单显式跳过（待产品另定规则）。
+- **资源对接 `investor`**：`CKBJoin` 未购章节时 **`success:false` + `errorCode: CONTENT_PURCHASE_REQUIRED`**，小程序 `match.js` 用 `e.response` 展示文案。
+
+---
+
+**最后更新**：2026-04-15

.cursor/archive/agents-legacy-soul/团队/evolution/索引.md

@@ -0,0 +1,16 @@
+# 团队 经验索引（跨角色共享）
+
+> 架构决策、业务规则、路由约定等跨角色共享内容。
+
+| 日期 | 摘要 | 文件 |
+|------|------|------|
+| 2026-03-05 | 分支冲突后各端完整性自查流程 | [2026-03-05.md](./2026-03-05.md) |
+| 2026-03-10 | 管理端迁移 Mycontent-temp：菜单/布局新规范基线与入口收敛规则 | [2026-03-10.md](./2026-03-10.md) |
+| 2026-03-12 | 密钥/token 设计：关联小程序 key、@ 人物 token，不暴露真实密钥、服务端兑换 | [2026-03-12.md](./2026-03-12.md) |
+| 2026-03-14 | 内容排名算法跨端复用：管理端内容排行与小程序精选推荐共用 computeArticleRankingSections | [2026-03-14.md](./2026-03-14.md) |
+| 2026-03-16 | TipTap Mention 需 data-label，否则显示 token | [2026-03-16.md](./2026-03-16.md) |
+| 2026-03-17 | 代付美团式流程与权益归属约定：读页→代付页→分享；权益/分佣归发起人 | [2026-03-17.md](./2026-03-17.md) |
+| 2026-03-24 | 文档同步原则：实现变更后同步需求/运营与变更/项目索引 | [2026-03-24.md](./2026-03-24.md) |
+| 2026-04-13 | 按功能同步开发文档：功能完成=实现+索引；跨端契约双写 | [2026-04-13.md](./2026-04-13.md) |
+| 2026-04-14 | 小程序优先闭环审计、写死vs配置化、需求表骨架与 role-flow §1.2 | [2026-04-14.md](./2026-04-14.md) |
+| 2026-04-15 | 联网：垂直切片、追踪弹、AI验证优先、无责复盘；role-flow §1.3 | [2026-04-15.md](./2026-04-15.md) |

.cursor/archive/agents-legacy-soul/安全工程师/evolution/2026-03-20-挖矿与服务器Skills.md

@@ -0,0 +1,32 @@
+# 挖矿病毒排查与服务器操作 Skills 创建
+
+**日期**：2026-03-20
+
+## 背景
+
+基于 agent 记录（3b9e0fa0、bc781e1b、1c1a81c3 等）中挖矿病毒排查经验，以及本地部署脚本（devloy.py、master.py、soul-admin/deploy.py、Cunkebao/miner_guard_install.py 等），将经验吸收转化为 Skills。
+
+## 新增 Skills
+
+### 1. security-miner-guard
+
+- **路径**：`.cursor/skills/security-miner-guard/SKILL.md`
+- **触发词**：挖矿病毒、xmrig、服务器被入侵、miner_guard、安全排查、杀挖矿
+- **内容**：挖矿病毒特征、入侵链路、排查脚本、加固建议、miner_guard 安装与检查
+
+### 2. security-server-ops
+
+- **路径**：`.cursor/skills/security-server-ops/SKILL.md`
+- **触发词**：部署、服务器操作、SSH、宝塔、devloy、master、Cunkebao 部署
+- **内容**：服务器索引、部署脚本索引、环境变量一览、常用操作（不含明文密码）
+
+## 配置更新
+
+- `paths.py`：新增 `AGENT_SECURITY`、`ROLE_TO_AGENT["安全工程师"]`
+- `老板分身-索引.mdc`：经验自动收集推断增加「挖矿/安全/服务器操作→安全工程师」
+- `soul-project-boundary.mdc`：按语义触发词增加安全工程师及对应 Skills
+
+## 安全提醒
+
+- Skills 中**不写入明文密码**，仅说明配置来源（环境变量、脚本 get_cfg()）
+- 建议将 master.py、devloy.py 等中的默认密码迁移到环境变量