diff --git a/.cursor/README.md b/.cursor/README.md new file mode 100644 index 0000000..5e26ce9 --- /dev/null +++ b/.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` diff --git a/.cursor/agent/开发助理/README.md b/.cursor/agent/开发助理/README.md new file mode 100644 index 0000000..b1d4c09 --- /dev/null +++ b/.cursor/agent/开发助理/README.md @@ -0,0 +1,12 @@ +# 开发助理（橙子） + +> 规则进化执行、通用经验池、项目索引。经验：`.cursor/agent/开发助理/evolution/` + +## 目录结构 + +| 目录 | 说明 | +|------|------| +| evolution/ | 通用经验池 | +| archived/ | 已归档经验 | +| script/ | 规则进化 bat 入口 | +| 项目索引/ | 各角色开发进度索引 | diff --git a/.cursor/agent/开发助理/archived/.gitkeep b/.cursor/agent/开发助理/archived/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.cursor/agent/开发助理/evolution/.gitkeep b/.cursor/agent/开发助理/evolution/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.cursor/agent/开发助理/evolution/2026-02-26.md b/.cursor/agent/开发助理/evolution/2026-02-26.md new file mode 100644 index 0000000..41a5d0e --- /dev/null +++ b/.cursor/agent/开发助理/evolution/2026-02-26.md @@ -0,0 +1,5 @@ +# 2026-02-26 | 助理橙子经验 + +> 本日经验条目，格式：类型 | 摘要 | 升级 Skill + +--- diff --git a/.cursor/agent/开发助理/evolution/2026-03-11.md b/.cursor/agent/开发助理/evolution/2026-03-11.md new file mode 100644 index 0000000..dd7ba40 --- /dev/null +++ b/.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。 diff --git a/.cursor/agent/开发助理/evolution/2026-03-16-交互习惯分析.md b/.cursor/agent/开发助理/evolution/2026-03-16-交互习惯分析.md new file mode 100644 index 0000000..bd17ed6 --- /dev/null +++ b/.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 的响应策略优化。 diff --git a/.cursor/agent/开发助理/evolution/2026-03-17.md b/.cursor/agent/开发助理/evolution/2026-03-17.md new file mode 100644 index 0000000..32e5d66 --- /dev/null +++ b/.cursor/agent/开发助理/evolution/2026-03-17.md @@ -0,0 +1,9 @@ +# 开发助理 经验记录 - 2026-03-17 + +## 会议收尾（2026-03-17） + +- **纪要**：2026-03-17_会议收尾-源码优化完成与测试流程定稿.md +- **经验入库**：各角色 evolution 已追加收尾经验 +- **项目索引**：后端、管理端、小程序、测试、助理橙子已更新 +- **会议索引**：README.md 已追加 +- **开发文档**：运营与变更第十七部分已追加 diff --git a/.cursor/agent/开发助理/evolution/2026-03-18.md b/.cursor/agent/开发助理/evolution/2026-03-18.md new file mode 100644 index 0000000..71afa90 --- /dev/null +++ b/.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 份文档联动更新，避免“清单/决议/执行层”脱节。 + diff --git a/.cursor/agent/开发助理/evolution/2026-03-21-MBTI头像C端全链路兜底.md b/.cursor/agent/开发助理/evolution/2026-03-21-MBTI头像C端全链路兜底.md new file mode 100644 index 0000000..173f347 --- /dev/null +++ b/.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。 diff --git a/.cursor/agent/开发助理/evolution/2026-04-14.md b/.cursor/agent/开发助理/evolution/2026-04-14.md new file mode 100644 index 0000000..12f256f --- /dev/null +++ b/.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（小程序逆推闭环）。 diff --git a/.cursor/agent/开发助理/evolution/2026-04-15.md b/.cursor/agent/开发助理/evolution/2026-04-15.md new file mode 100644 index 0000000..c7c3d0f --- /dev/null +++ b/.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 为准。 diff --git a/.cursor/agent/开发助理/evolution/索引.md b/.cursor/agent/开发助理/evolution/索引.md new file mode 100644 index 0000000..459543e --- /dev/null +++ b/.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 | diff --git a/.cursor/agent/开发助理/script/一键-全部.bat b/.cursor/agent/开发助理/script/一键-全部.bat new file mode 100644 index 0000000..6e0df33 --- /dev/null +++ b/.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 diff --git a/.cursor/agent/开发助理/script/一键-列出经验池.bat b/.cursor/agent/开发助理/script/一键-列出经验池.bat new file mode 100644 index 0000000..16f92cd --- /dev/null +++ b/.cursor/agent/开发助理/script/一键-列出经验池.bat @@ -0,0 +1,6 @@ +@echo off +chcp 65001 >nul +cd /d "%~dp0..\..\..\.." +echo 开发助理 - 列出经验池 +python .cursor\scripts\evolution.py list +pause diff --git a/.cursor/agent/开发助理/script/一键-执行进化.bat b/.cursor/agent/开发助理/script/一键-执行进化.bat new file mode 100644 index 0000000..66db410 --- /dev/null +++ b/.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 diff --git a/.cursor/agent/开发助理/script/一键-添加经验.bat b/.cursor/agent/开发助理/script/一键-添加经验.bat new file mode 100644 index 0000000..5fefae1 --- /dev/null +++ b/.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 diff --git a/.cursor/agent/开发助理/经验清单.md b/.cursor/agent/开发助理/经验清单.md new file mode 100644 index 0000000..d97374d --- /dev/null +++ b/.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 diff --git a/.cursor/agent/开发助理/项目索引/README.md b/.cursor/agent/开发助理/项目索引/README.md new file mode 100644 index 0000000..2b2cf32 --- /dev/null +++ b/.cursor/agent/开发助理/项目索引/README.md @@ -0,0 +1,5 @@ +# 项目索引 + +存放各角色子项目开发进度、状态。每角色对应一份索引。 + +- **玩值三端汇总**：[`玩值.md`](玩值.md)（与 `开发文档/玩值/进度-看板.md` 联动） diff --git a/.cursor/agent/开发助理/项目索引/产品.md b/.cursor/agent/开发助理/项目索引/产品.md new file mode 100644 index 0000000..f69c522 --- /dev/null +++ b/.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 diff --git a/.cursor/agent/开发助理/项目索引/助理橙子.md b/.cursor/agent/开发助理/项目索引/助理橙子.md new file mode 100644 index 0000000..a3e12ac --- /dev/null +++ b/.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 diff --git a/.cursor/agent/开发助理/项目索引/后端.md b/.cursor/agent/开发助理/项目索引/后端.md new file mode 100644 index 0000000..e8a8903 --- /dev/null +++ b/.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 diff --git a/.cursor/agent/开发助理/项目索引/团队.md b/.cursor/agent/开发助理/项目索引/团队.md new file mode 100644 index 0000000..b7bf039 --- /dev/null +++ b/.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 diff --git a/.cursor/agent/开发助理/项目索引/小程序.md b/.cursor/agent/开发助理/项目索引/小程序.md new file mode 100644 index 0000000..2fc93a8 --- /dev/null +++ b/.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 diff --git a/.cursor/agent/开发助理/项目索引/测试.md b/.cursor/agent/开发助理/项目索引/测试.md new file mode 100644 index 0000000..f737f31 --- /dev/null +++ b/.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 diff --git a/.cursor/agent/开发助理/项目索引/玩值.md b/.cursor/agent/开发助理/项目索引/玩值.md new file mode 100644 index 0000000..2090068 --- /dev/null +++ b/.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 diff --git a/.cursor/agent/开发助理/项目索引/管理端.md b/.cursor/agent/开发助理/项目索引/管理端.md new file mode 100644 index 0000000..921a69a --- /dev/null +++ b/.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 类型错误（与本次迁移无关），待修复。 diff --git a/.cursor/agent/智能体-技能-经验总索引.md b/.cursor/agent/智能体-技能-经验总索引.md new file mode 100644 index 0000000..5d592cc --- /dev/null +++ b/.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）+ 必要的联动（如会议/跨端）”合并决策。 diff --git a/.cursor/agent/玩值API工程师/README.md b/.cursor/agent/玩值API工程师/README.md new file mode 100644 index 0000000..6636044 --- /dev/null +++ b/.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 模型与迁移脚本。 diff --git a/.cursor/agent/玩值API工程师/evolution/.gitkeep b/.cursor/agent/玩值API工程师/evolution/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.cursor/agent/玩值API工程师/evolution/2026-04-20-玩值迁移-吸收.md b/.cursor/agent/玩值API工程师/evolution/2026-04-20-玩值迁移-吸收.md new file mode 100644 index 0000000..364ff96 --- /dev/null +++ b/.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》为真源，先表结构再写接口，避免无表实现。 diff --git a/.cursor/agent/玩值API工程师/evolution/索引.md b/.cursor/agent/玩值API工程师/evolution/索引.md new file mode 100644 index 0000000..51a461f --- /dev/null +++ b/.cursor/agent/玩值API工程师/evolution/索引.md @@ -0,0 +1,5 @@ +# 玩值 API 工程师 - 经验索引 + +| 日期 | 主题 | +|------|------| +| 2026-04-20 | [玩值迁移-吸收（方法论）](2026-04-20-玩值迁移-吸收.md) | diff --git a/.cursor/agent/玩值移动端工程师/README.md b/.cursor/agent/玩值移动端工程师/README.md new file mode 100644 index 0000000..86e0d30 --- /dev/null +++ b/.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/` 目录。 diff --git a/.cursor/agent/玩值移动端工程师/evolution/.gitkeep b/.cursor/agent/玩值移动端工程师/evolution/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.cursor/agent/玩值移动端工程师/evolution/2026-04-20-玩值迁移-吸收.md b/.cursor/agent/玩值移动端工程师/evolution/2026-04-20-玩值迁移-吸收.md new file mode 100644 index 0000000..64d18a9 --- /dev/null +++ b/.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 + 页面。 diff --git a/.cursor/agent/玩值移动端工程师/evolution/索引.md b/.cursor/agent/玩值移动端工程师/evolution/索引.md new file mode 100644 index 0000000..321ed87 --- /dev/null +++ b/.cursor/agent/玩值移动端工程师/evolution/索引.md @@ -0,0 +1,5 @@ +# 玩值移动端工程师 - 经验索引 + +| 日期 | 主题 | +|------|------| +| 2026-04-20 | [玩值迁移-吸收](2026-04-20-玩值迁移-吸收.md) | diff --git a/.cursor/agent/玩值管理端工程师/README.md b/.cursor/agent/玩值管理端工程师/README.md new file mode 100644 index 0000000..de2bfb0 --- /dev/null +++ b/.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/*`。 diff --git a/.cursor/agent/玩值管理端工程师/evolution/.gitkeep b/.cursor/agent/玩值管理端工程师/evolution/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.cursor/agent/玩值管理端工程师/evolution/2026-04-20-玩值迁移-吸收.md b/.cursor/agent/玩值管理端工程师/evolution/2026-04-20-玩值迁移-吸收.md new file mode 100644 index 0000000..425d906 --- /dev/null +++ b/.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对照表》与进度看板登记联调状态。 diff --git a/.cursor/agent/玩值管理端工程师/evolution/索引.md b/.cursor/agent/玩值管理端工程师/evolution/索引.md new file mode 100644 index 0000000..b1e8796 --- /dev/null +++ b/.cursor/agent/玩值管理端工程师/evolution/索引.md @@ -0,0 +1,5 @@ +# 玩值管理端工程师 - 经验索引 + +| 日期 | 主题 | +|------|------| +| 2026-04-20 | [玩值迁移-吸收](2026-04-20-玩值迁移-吸收.md) | diff --git a/.cursor/agent/老板分身/evolution/.gitkeep b/.cursor/agent/老板分身/evolution/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.cursor/agent/老板分身/evolution/索引.md b/.cursor/agent/老板分身/evolution/索引.md new file mode 100644 index 0000000..35c30be --- /dev/null +++ b/.cursor/agent/老板分身/evolution/索引.md @@ -0,0 +1,4 @@ +# 老板分身 经验索引 + +| 日期 | 摘要 | 文件 | +|------|------|------| diff --git a/.cursor/apifox-mcp-setup.md b/.cursor/apifox-mcp-setup.md new file mode 100644 index 0000000..81440ae --- /dev/null +++ b/.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「刷新接口文档数据」。 diff --git a/.cursor/archive/README.md b/.cursor/archive/README.md new file mode 100644 index 0000000..df75bf6 --- /dev/null +++ b/.cursor/archive/README.md @@ -0,0 +1,3 @@ +# 历史归档 + +存放已归档的文档、分析报告等。 diff --git a/.cursor/archive/agents-legacy-soul/README.md b/.cursor/archive/agents-legacy-soul/README.md new file mode 100644 index 0000000..08d565b --- /dev/null +++ b/.cursor/archive/agents-legacy-soul/README.md @@ -0,0 +1,13 @@ +# 已归档：Soul 派对时期角色智能体 + +2026-04-20 玩值三端迁移后，主仓库 `.cursor/agent/` 仅保留 **开发助理（橙子）**、**老板分身（乘风）** 与 **玩值三项目智能体**。下列目录为原 Soul 角色经验与脚本的完整搬迁，供查阅，**不再作为默认索引入口**。 + +- `产品经理/` +- `软件测试/` +- `团队/` +- `安全工程师/` +- `小程序开发工程师/` +- `管理端开发工程师/` +- `后端工程师/` + +新开发请查 `agent/玩值*` 与 `开发文档/玩值/`。 diff --git a/.cursor/archive/agents-legacy-soul/产品经理/evolution/.gitkeep b/.cursor/archive/agents-legacy-soul/产品经理/evolution/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-02-26.md b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-02-26.md new file mode 100644 index 0000000..de5d3f9 --- /dev/null +++ b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-02-26.md @@ -0,0 +1,5 @@ +# 2026-02-26 | 产品经验 + +> 本日经验条目，格式：类型 | 摘要 | 升级 Skill + +--- diff --git a/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-02-28.md b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-02-28.md new file mode 100644 index 0000000..33efc5e --- /dev/null +++ b/.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 默认值。 diff --git a/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-05.md b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-05.md new file mode 100644 index 0000000..52ccd6e --- /dev/null +++ b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-05.md @@ -0,0 +1,12 @@ +# 产品经理 经验记录 - 2026-03-05 + +## 分支冲突后功能完整性分析会议 + +- **分支冲突后需优先核对需求文档与实现一致性**：避免「文档在合并中丢失」导致需求与实现脱节。重点核对 `开发文档/1、需求/`、`临时需求池/` 与当前实现是否一致。 +- **重点确认项**：个人资料页、增值版/普通版计价、找伙伴联系方式完善弹窗等近期需求是否按文档落地。 + +## 文章详情 @某人 高亮与一键加好友方案讨论 + +- **需求**：文章中支持 @某人，名称高亮、点击添加好友；编辑侧能插入 @用户并落库（含用户 id）。 +- **验收**：详情页 @ 高亮可点击；点击调起添加好友并提示；管理端插入 @ 后保存再编辑不错位。 +- **待确认**：添加好友接口 path、入参/出参及业务规则（已是好友、重复请求等）；开发文档中接口放置位置。 diff --git a/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-10.md b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-10.md new file mode 100644 index 0000000..e5f77d2 --- /dev/null +++ b/.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` + diff --git a/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-11.md b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-11.md new file mode 100644 index 0000000..74e4966 --- /dev/null +++ b/.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`。 diff --git a/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-16.md b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-16.md new file mode 100644 index 0000000..19b7585 --- /dev/null +++ b/.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 产品），互补非替代 diff --git a/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-17.md b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-17.md new file mode 100644 index 0000000..f7603af --- /dev/null +++ b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-17.md @@ -0,0 +1,13 @@ +# 产品经理 经验记录 - 2026-03-17 + +## 稳定版源码质量优化（会议：2026-03-17） + +- **验收标准**：优化后现有功能行为不变，三端联调通过 +- **优先级**：高优（安全）→ 中优（可维护）→ 低优（性能/结构） +- **原则**：源码质量优化按安全→可维护→性能分批，用户无感知 + +--- + +## 会议收尾（2026-03-17） + +- 10 项优化全部完成；测试流程与报告模板已定稿；开发文档已同步 diff --git a/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-18.md b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-18.md new file mode 100644 index 0000000..6612125 --- /dev/null +++ b/.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，是否需要保留历史别名/展示区分。 + diff --git a/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-24.md b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-24.md new file mode 100644 index 0000000..4820706 --- /dev/null +++ b/.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 策略二选一）。 diff --git a/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-31.md b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-31.md new file mode 100644 index 0000000..c0ec575 --- /dev/null +++ b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-03-31.md @@ -0,0 +1,6 @@ +# 产品经理 经验记录 - 2026-03-31 + +## 会议：超级个体列表与 @ 列表融合 + +- 超级个体（VIP 曝光）与 @ 人物（内容引用）应视为同一业务的两面；融合优先统一运营心智与验收口径，再决定 UI 是否单页。 +- 一期验收需明确：无 @ 人物的有效 VIP 的提示策略、管理端跳转路径是否满足运营闭环。 diff --git a/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-04-02.md b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-04-02.md new file mode 100644 index 0000000..b670821 --- /dev/null +++ b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-04-02.md @@ -0,0 +1,7 @@ +# 产品经理 经验记录 - 2026-04-02 + +## 会议：工作进度与需求同步会 + +- **场景**：4 月初全员同步进度，衔接 2026-03-31 超级个体与 @ 列表融合待办。 +- **要点**：融合类需求需同步明确「一期验收口径」（UsersPage @ 状态、列表入口是否收敛），并写入需求汇总/运营与变更，避免实现先行、验收滞后。 +- **待办**：问题与作答区 Q1 由产品补充作答后闭环。 diff --git a/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-04-13.md b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-04-13.md new file mode 100644 index 0000000..210e4a7 --- /dev/null +++ b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-04-13.md @@ -0,0 +1,6 @@ +# 产品经理 经验记录 - 2026-04-13 + +## 会议：按功能同步开发文档 + +- **要点**：以可验收功能点为最小同步单位；主需求与《以界面定需求》为验收真源；跨端规则变更须同时更新需求清单状态与优先级。 +- **待办**：核对 2026-04-02 以来实现与文档差异；vip-members/融合一期验收口径在需求文档中单点定稿。 diff --git a/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-04-14.md b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-04-14.md new file mode 100644 index 0000000..3c1fb31 --- /dev/null +++ b/.cursor/archive/agents-legacy-soul/产品经理/evolution/2026-04-14.md @@ -0,0 +1,7 @@ +# 产品经理 经验记录 - 2026-04-14 + +## 吸收沉淀：同步开发需求 + +- **需求清单**：在 `开发文档/1、需求/需求汇总.md` 维护编号行（SYNC / LOOP / MAINT 等），状态与责任角色与纪要待办一致。 +- **验收绑定**：功能完成 = 实现可合并 + **需求表或项目索引当日一行**；跨端规则须在需求或运营与变更中单点写清优先级。 +- **管理端必要性**：沿用产品 Skill — 纯文案/纯视觉可不建管理端；**配置/开关/审核/统计** 必须显式在需求表标「管理端入口」避免壳功能。 diff --git a/.cursor/archive/agents-legacy-soul/产品经理/evolution/索引.md b/.cursor/archive/agents-legacy-soul/产品经理/evolution/索引.md new file mode 100644 index 0000000..090bd55 --- /dev/null +++ b/.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) | diff --git a/.cursor/archive/agents-legacy-soul/后端工程师/evolution/.gitkeep b/.cursor/archive/agents-legacy-soul/后端工程师/evolution/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-02-26.md b/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-02-26.md new file mode 100644 index 0000000..b83c7b4 --- /dev/null +++ b/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-02-26.md @@ -0,0 +1,5 @@ +# 2026-02-26 | 后端经验 + +> 本日经验条目，格式：类型 | 摘要 | 升级 Skill + +--- diff --git a/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-02-28.md b/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-02-28.md new file mode 100644 index 0000000..c428db1 --- /dev/null +++ b/.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 等。 diff --git a/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-05.md b/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-05.md new file mode 100644 index 0000000..f747138 --- /dev/null +++ b/.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 存带 @ 标记字符串即可。 diff --git a/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-10.md b/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-10.md new file mode 100644 index 0000000..8755e1d --- /dev/null +++ b/.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` + diff --git a/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-11.md b/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-11.md new file mode 100644 index 0000000..679a4fc --- /dev/null +++ b/.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`。 diff --git a/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-12.md b/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-12.md new file mode 100644 index 0000000..c0d5bca --- /dev/null +++ b/.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 买断」。 diff --git a/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-13.md b/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-13.md new file mode 100644 index 0000000..4590c53 --- /dev/null +++ b/.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` 保持一致」的安全模式，避免在不同字段中混放全文与预览内容。 +- 涉及付费内容时，优先在后端用「权限判断 + 统一内容裁剪」实现安全边界，前端只根据状态选择展示预览还是全文。 + diff --git a/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-14.md b/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-14.md new file mode 100644 index 0000000..b8db677 --- /dev/null +++ b/.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`）均复用该算法，修正后两端同步生效。 diff --git a/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-16.md b/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-16.md new file mode 100644 index 0000000..0cbeba7 --- /dev/null +++ b/.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 内为 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 接口，统一数据入口 diff --git a/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-17.md b/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-17.md new file mode 100644 index 0000000..c82615f --- /dev/null +++ b/.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:{业务}:{标识} diff --git a/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-18.md b/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-18.md new file mode 100644 index 0000000..608b550 --- /dev/null +++ b/.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`），小程序仅消费并跳转引导页。 + diff --git a/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-24.md b/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-24.md new file mode 100644 index 0000000..66e0c44 --- /dev/null +++ b/.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 纪要）。 diff --git a/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-31.md b/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-03-31.md new file mode 100644 index 0000000..c9a3563 --- /dev/null +++ b/.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 侧对齐，便于管理端一行展示。 diff --git a/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-04-02.md b/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-04-02.md new file mode 100644 index 0000000..6e77f07 --- /dev/null +++ b/.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 作答后闭环。 diff --git a/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-04-13.md b/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-04-13.md new file mode 100644 index 0000000..a7fc963 --- /dev/null +++ b/.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 等待办在文档中优先级化。 diff --git a/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-04-14.md b/.cursor/archive/agents-legacy-soul/后端工程师/evolution/2026-04-14.md new file mode 100644 index 0000000..4caddfa --- /dev/null +++ b/.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 行，合并前更新状态与依赖方。 diff --git a/.cursor/archive/agents-legacy-soul/后端工程师/evolution/索引.md b/.cursor/archive/agents-legacy-soul/后端工程师/evolution/索引.md new file mode 100644 index 0000000..256200e --- /dev/null +++ b/.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) | diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/.gitkeep b/.cursor/archive/agents-legacy-soul/团队/evolution/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/2026-02-27.md b/.cursor/archive/agents-legacy-soul/团队/evolution/2026-02-27.md new file mode 100644 index 0000000..f552faf --- /dev/null +++ b/.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 同理） diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/2026-02-28.md b/.cursor/archive/agents-legacy-soul/团队/evolution/2026-02-28.md new file mode 100644 index 0000000..264bcb8 --- /dev/null +++ b/.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 可配置。 +- **普通版与增值版**：分开、互斥的两套产品，用户购买其一。 diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-05.md b/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-05.md new file mode 100644 index 0000000..dc7dc05 --- /dev/null +++ b/.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 与添加好友接口。 diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-08.md b/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-08.md new file mode 100644 index 0000000..ef45712 --- /dev/null +++ b/.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 变更，部署后需重启 +- 管理端：确保免费章节配置正确 +- 产品：作为验收规则 +- 小程序：无变更 diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-10.md b/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-10.md new file mode 100644 index 0000000..4e7ab4f --- /dev/null +++ b/.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` + diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-11.md b/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-11.md new file mode 100644 index 0000000..2223b98 --- /dev/null +++ b/.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` diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-12.md b/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-12.md new file mode 100644 index 0000000..d16d87d --- /dev/null +++ b/.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` → 代表会员权益（案例库、增值版等），两者可以独立打开。 diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-13.md b/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-13.md new file mode 100644 index 0000000..54b080d --- /dev/null +++ b/.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` 行为，保持三端一致。 + diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-14.md b/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-14.md new file mode 100644 index 0000000..346a20c --- /dev/null +++ b/.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()` 刷新列表，否则用户看不到变化。 diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-16.md b/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-16.md new file mode 100644 index 0000000..95ed1a0 --- /dev/null +++ b/.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）需在文档中说明 diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-17.md b/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-17.md new file mode 100644 index 0000000..6c54aae --- /dev/null +++ b/.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 验证、部署后回归缓存接口 diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-18.md b/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-18.md new file mode 100644 index 0000000..85ffb62 --- /dev/null +++ b/.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，前端仅做跳转与阻断，并保留兜底规则。 + diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-24.md b/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-24.md new file mode 100644 index 0000000..8322cfa --- /dev/null +++ b/.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` diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-31.md b/.cursor/archive/agents-legacy-soul/团队/evolution/2026-03-31.md new file mode 100644 index 0000000..d6b023f --- /dev/null +++ b/.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/获客等）挂在用户侧展示即可。 diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/2026-04-02.md b/.cursor/archive/agents-legacy-soul/团队/evolution/2026-04-02.md new file mode 100644 index 0000000..1f07a9b --- /dev/null +++ b/.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` diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/2026-04-13.md b/.cursor/archive/agents-legacy-soul/团队/evolution/2026-04-13.md new file mode 100644 index 0000000..904a4ec --- /dev/null +++ b/.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`。 diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/2026-04-14.md b/.cursor/archive/agents-legacy-soul/团队/evolution/2026-04-14.md new file mode 100644 index 0000000..467a7dc --- /dev/null +++ b/.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 交叉引用。 + +### 同时影响 + +小程序、管理端、后端、测试、产品（文档与验收）。 diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/2026-04-15.md b/.cursor/archive/agents-legacy-soul/团队/evolution/2026-04-15.md new file mode 100644 index 0000000..9b124c0 --- /dev/null +++ b/.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 diff --git a/.cursor/archive/agents-legacy-soul/团队/evolution/索引.md b/.cursor/archive/agents-legacy-soul/团队/evolution/索引.md new file mode 100644 index 0000000..b80c057 --- /dev/null +++ b/.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) | diff --git a/.cursor/archive/agents-legacy-soul/安全工程师/evolution/.gitkeep b/.cursor/archive/agents-legacy-soul/安全工程师/evolution/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.cursor/archive/agents-legacy-soul/安全工程师/evolution/2026-03-20-挖矿与服务器Skills.md b/.cursor/archive/agents-legacy-soul/安全工程师/evolution/2026-03-20-挖矿与服务器Skills.md new file mode 100644 index 0000000..8fd3351 --- /dev/null +++ b/.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 等中的默认密码迁移到环境变量 diff --git a/.cursor/archive/agents-legacy-soul/安全工程师/evolution/2026-03-20-管理端部署触发词.md b/.cursor/archive/agents-legacy-soul/安全工程师/evolution/2026-03-20-管理端部署触发词.md new file mode 100644 index 0000000..b8464d0 --- /dev/null +++ b/.cursor/archive/agents-legacy-soul/安全工程师/evolution/2026-03-20-管理端部署触发词.md @@ -0,0 +1,26 @@ +# 管理端部署触发词约定 + +**日期**：2026-03-20 + +## 场景 + +用户说「管理端帮我部署到xx环境」时，安全工程师应语义化解析 xx，直接执行对应部署脚本。 + +## 解决方案 + +- **触发词**：管理端帮我部署到xx环境（语义化，理解意图即可） +- **脚本映射**： + - 含「正式」「线上」「生产」→ `cd soul-admin && python master.py`（正式环境，/www/wwwroot/self/soul-admin） + - 含「测试」「dev」→ `cd soul-admin && python deploy.py`（测试环境，/www/wwwroot/self/soul-admin-dev） + +## soul-admin 部署脚本 + +| 脚本 | 环境 | 目标目录 | 构建命令 | +|------|------|----------|----------| +| master.py | 正式 | soul-admin | pnpm build | +| deploy.py | 测试 | soul-admin-dev | pnpm run build:dev | + +## 已升级 Skills + +1. **security-server-ops**：何时使用表、2.2 soul-admin 脚本索引、4.4/4.5 常用操作 +2. **soul-project-boundary**：按场景触发词表新增 diff --git a/.cursor/archive/agents-legacy-soul/安全工程师/evolution/2026-03-20-部署API触发词.md b/.cursor/archive/agents-legacy-soul/安全工程师/evolution/2026-03-20-部署API触发词.md new file mode 100644 index 0000000..63fb2dc --- /dev/null +++ b/.cursor/archive/agents-legacy-soul/安全工程师/evolution/2026-03-20-部署API触发词.md @@ -0,0 +1,18 @@ +# 部署 API 触发词约定 + +**日期**：2026-03-20 + +## 场景 + +用户说「帮我部署api到线上」时，安全工程师应直接执行部署脚本，无需再询问或选择。 + +## 解决方案 + +- **触发词**：帮我部署api到线上 +- **动作**：直接执行 `cd soul-api && python master.py` +- **脚本**：`soul-api/master.py`（soul-api 正式环境部署） + +## 已升级 Skills + +1. **security-server-ops**：何时使用表新增该触发词，明确直接执行命令 +2. **soul-project-boundary**：按场景触发词表新增，加载 security-server-ops 后执行 diff --git a/.cursor/archive/agents-legacy-soul/安全工程师/evolution/索引.md b/.cursor/archive/agents-legacy-soul/安全工程师/evolution/索引.md new file mode 100644 index 0000000..905caa6 --- /dev/null +++ b/.cursor/archive/agents-legacy-soul/安全工程师/evolution/索引.md @@ -0,0 +1,9 @@ +# 安全工程师 经验索引 + +> 挖矿病毒排查、服务器加固、部署与运维相关经验。 + +| 日期 | 摘要 | 文件 | +|------|------|------| +| 2026-03-20 | 挖矿病毒排查经验转化为 Skills；服务器操作 Skill 创建 | 2026-03-20-挖矿与服务器Skills.md | +| 2026-03-20 | 「帮我部署api到线上」→ 执行 soul-api/master.py | 2026-03-20-部署API触发词.md | +| 2026-03-20 | 「管理端帮我部署到xx环境」→ 语义化解析，正式→master.py，测试→deploy.py | 2026-03-20-管理端部署触发词.md | diff --git a/.cursor/archive/agents-legacy-soul/小程序开发工程师/evolution/.gitkeep b/.cursor/archive/agents-legacy-soul/小程序开发工程师/evolution/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.cursor/archive/agents-legacy-soul/小程序开发工程师/evolution/2025-03-14-文本长按复制.md b/.cursor/archive/agents-legacy-soul/小程序开发工程师/evolution/2025-03-14-文本长按复制.md new file mode 100644 index 0000000..c58cb91 --- /dev/null +++ b/.cursor/archive/agents-legacy-soul/小程序开发工程师/evolution/2025-03-14-文本长按复制.md @@ -0,0 +1,40 @@ +# 阅读页文本长按选中复制 + +> 问题→解决闭环，已升级 miniprogram-dev SKILL + +--- + +## 问题 + +小程序阅读页正文长按时无法选中、复制文本。 + +--- + +## 解决方案 + +使用 `text` 组件的 **`user-select`** 属性（基础库 2.12.1+，官方推荐；`selectable` 已废弃）： + +```html +{{seg.text}} +``` + +--- + +## 实施范围（read.wxml） + +- 章节标题：`` +- 正文片段：text / mention / linkTag 均加 `user-select` +- 预览段落：`{{item}}`（原为 view 内直接 `{{item}}`，需用 text 包裹） + +--- + +## 备选方案 + +- **selectable**：已废弃但多数环境仍可用，若 `user-select` 导致布局异常（inline-block 换行）可回退 +- **wx.setClipboardData + bindlongpress**：iOS 原生选中失效时，可做长按整段复制兜底 + +--- + +## Skill 升级 + +已写入 miniprogram-dev SKILL §10 文本可选与复制。 diff --git a/.cursor/archive/agents-legacy-soul/小程序开发工程师/evolution/2025-03-14-联网吸收小程序最新开发规则与API.md b/.cursor/archive/agents-legacy-soul/小程序开发工程师/evolution/2025-03-14-联网吸收小程序最新开发规则与API.md new file mode 100644 index 0000000..3067584 --- /dev/null +++ b/.cursor/archive/agents-legacy-soul/小程序开发工程师/evolution/2025-03-14-联网吸收小程序最新开发规则与API.md @@ -0,0 +1,90 @@ +# 联网吸收：微信小程序最新开发规则与 API（2025-03） + +> 来源：微信开放文档、基础库更新日志、Skyline 文档、隐私合规指南等 + +--- + +## 一、基础库版本与更新节奏 + +- **当前最新**：v3.14.2（2026-01-22），v3.14.3 灰度中 +- **建议**：在 `app.json` 中设置 `"useExtendedLib": { "weui": true }` 或指定 `libVersion`，关注灰度版本说明 +- **兼容**：使用 `wx.canIUse('api.xxx')` 做能力检测，避免在低版本报错 + +--- + +## 二、新增 / 重要 API（基础库 3.14 系列） + +| API | 用途 | 基础库 | +|-----|------|--------| +| `wx.rewriteRoute` | 路由重写 | 3.14+ | +| `wx.openOfficialAccountProfile` | 打开公众号 | 3.14+ | +| `wx.openOfficialAccountChat` | 跳转公众号会话 | 3.14+ | +| `wx.openInquiriesTopic` | 跳转问一问话题 | 3.14.0 | +| `wx.loadBuiltInFontFace` | 加载微信内置字体 | 3.14+ | +| `wx.onUserOffTranslation` | 监听用户关闭翻译 | 3.14.3 灰度 | + +**其他能力**： +- 鼠标右键点击事件支持（PC 端） +- 图片分享朋友圈 +- 半屏小程序 `openEmbeddedMiniProgram` 上限提升到 100 +- TCPSocket 支持 `TCP_NODELAY` + +--- + +## 三、Skyline 渲染引擎（可选升级） + +- **定位**：新一代渲染引擎，以性能为首要目标，仍用 WXML/WXSS +- **配置**：页面级 `page.json` 中 `"renderer": "skyline"` +- **性能**：启动耗时降约 20%，跳页耗时降约 50%；长列表 `scroll-view` 仅渲染屏内节点 +- **注意**：CSS 特性精简，只保留更现代的集合；鸿蒙 OS 已灰度支持 +- **Soul 项目**：当前为 WebView 渲染，若需性能优化可逐步按页面接入 Skyline + +--- + +## 四、隐私合规（2025 重要变更） + +### 4.1 核心变化：从集中授权改为按需授权 + +- **旧**：首次启动一次性请求所有权限 +- **新**：必须在用户**实际触发相关功能时**才发起对应授权请求 +- **影响**：需拆分授权逻辑到具体业务场景，不能集中在 `app.onLaunch` 里 + +### 4.2 必须完成的步骤 + +1. **后台配置**：在小程序管理后台填写《小程序用户隐私保护指引》，声明处理的用户信息类型及用途 +2. **查询与展示**：`wx.getPrivacySetting` 查询授权状态，`wx.openPrivacyContract` 打开隐私协议 +3. **获取同意**：使用 ` + +``` + +```css +.avatar-wrap { position: relative; } +.avatar-overlay-btn { + position: absolute; top: 0; left: 0; + width: 130rpx; height: 130rpx; /* 与头像一致 */ + padding: 0; margin: 0; + background: transparent; border: none; +} +.avatar-overlay-btn::after { border: none; } +``` + +## 要点 + +- **同级关系**：button 与展示元素是 sibling，不是 parent-child +- **绝对定位**：`position: absolute` 覆盖在目标区域上，不参与文档流 +- **透明无内容**：button 仅负责点击事件，样式完全透明 +- **适用**：chooseAvatar、open-type 等需 button 触发的原生能力 + +## 升级 Skill + +已写入 `miniprogram-dev` SKILL §12。 diff --git a/.cursor/archive/agents-legacy-soul/小程序开发工程师/evolution/2026-03-20-手机号登录与公用组件.md b/.cursor/archive/agents-legacy-soul/小程序开发工程师/evolution/2026-03-20-手机号登录与公用组件.md new file mode 100644 index 0000000..1df4e17 --- /dev/null +++ b/.cursor/archive/agents-legacy-soul/小程序开发工程师/evolution/2026-03-20-手机号登录与公用组件.md @@ -0,0 +1,39 @@ +# 手机号一键登录与登录弹窗公用组件 + +> 日期：2026-03-20 | 角色：小程序开发工程师 + +## 问题与场景 + +1. **getPhoneNumber 不弹窗**：点击手机号登录按钮时，无法弹出手机号选择界面，也无法获取手机号 +2. **登录弹窗重复**：read、my、gift-pay/detail 三处各自维护一套登录弹窗，逻辑重复、维护成本高 +3. **登录后手机号未同步**：手机号登录后若响应中 user.phone 为空，本地 userInfo 未更新 + +## 解决方案 + +### 1. getPhoneNumber 必须与隐私协议耦合 + +- **open-type**：`open-type="getPhoneNumber|agreePrivacyAuthorization"`（基础库 2.32.3+） +- **onNeedPrivacyAuthorization**：app.js 中需将使用 getPhoneNumber 的页面加入支持列表，否则会 `resolve({ event: 'disagree' })` 导致获取失败 +- **支持页面**：avatar-nickname、profile-edit、read、my、gift-pay/detail、index、settings +- **隐私弹窗**：当 onNeedPrivacyAuthorization 触发时，页面需有 `showPrivacyModal` + `