From b9714200906eca7333aa7898e967522036ccef99 Mon Sep 17 00:00:00 2001 From: Alex-larget <33240357+Alex-larget@users.noreply.github.com> Date: Mon, 16 Mar 2026 18:35:21 +0800 Subject: [PATCH] Enhance documentation for new-soul project requirements and integration analysis MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Added detailed notes on the new-soul project, including the relationship between派对AI and various components such as content_upload.py, Mycontent, and the mini program. - Documented the need for consistency checks between chapters and database structures, as well as the alignment of management requirements with current projects. - Updated project indices to reflect the latest discussions and decisions from the March 16, 2026 meeting regarding new-soul's integration and operational impacts. --- .../agent/产品经理/evolution/2026-03-16.md | 7 + .../agent/后端工程师/evolution/2026-03-16.md | 5 + .cursor/agent/团队/evolution/2026-03-16.md | 6 + .../小程序开发工程师/evolution/2026-03-16.md | 4 + .cursor/agent/开发助理/项目索引/产品.md | 1 + .cursor/agent/开发助理/项目索引/后端.md | 1 + .cursor/agent/开发助理/项目索引/小程序.md | 1 + .cursor/agent/开发助理/项目索引/测试.md | 1 + .cursor/agent/开发助理/项目索引/管理端.md | 1 + .../管理端开发工程师/evolution/2026-03-16.md | 4 + .../agent/软件测试/evolution/2026-03-16.md | 7 + ...-03-16_new-soul新需求与当前项目差异分析.md | 123 ++++++++ .cursor/meeting/README.md | 1 + miniprogram/app.js | 4 +- 开发文档/稳定版-小程序与API对比.md | 269 ++++++++++++++++++ 15 files changed, 433 insertions(+), 2 deletions(-) create mode 100644 .cursor/agent/产品经理/evolution/2026-03-16.md create mode 100644 .cursor/agent/软件测试/evolution/2026-03-16.md create mode 100644 .cursor/meeting/2026-03-16_new-soul新需求与当前项目差异分析.md create mode 100644 开发文档/稳定版-小程序与API对比.md diff --git a/.cursor/agent/产品经理/evolution/2026-03-16.md b/.cursor/agent/产品经理/evolution/2026-03-16.md new file mode 100644 index 00000000..19b7585b --- /dev/null +++ b/.cursor/agent/产品经理/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/agent/后端工程师/evolution/2026-03-16.md b/.cursor/agent/后端工程师/evolution/2026-03-16.md index f1e62c46..0cbeba71 100644 --- a/.cursor/agent/后端工程师/evolution/2026-03-16.md +++ b/.cursor/agent/后端工程师/evolution/2026-03-16.md @@ -10,3 +10,8 @@ - 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/agent/团队/evolution/2026-03-16.md b/.cursor/agent/团队/evolution/2026-03-16.md index e4672405..95ed1a02 100644 --- a/.cursor/agent/团队/evolution/2026-03-16.md +++ b/.cursor/agent/团队/evolution/2026-03-16.md @@ -4,3 +4,9 @@ - **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/agent/小程序开发工程师/evolution/2026-03-16.md b/.cursor/agent/小程序开发工程师/evolution/2026-03-16.md index e9bb7119..44d28092 100644 --- a/.cursor/agent/小程序开发工程师/evolution/2026-03-16.md +++ b/.cursor/agent/小程序开发工程师/evolution/2026-03-16.md @@ -28,3 +28,7 @@ ## 升级 Skill miniprogram-dev SKILL 新增 §10 分享名片 + +## new-soul 派对AI 与小程序（会议：new-soul 新需求与当前项目差异分析） + +- 派对AI 的小程序站管理与当前 miniprogram 一致，仅涉及发布流程，不改变小程序功能 diff --git a/.cursor/agent/开发助理/项目索引/产品.md b/.cursor/agent/开发助理/项目索引/产品.md index b55520d4..175090ff 100644 --- a/.cursor/agent/开发助理/项目索引/产品.md +++ b/.cursor/agent/开发助理/项目索引/产品.md @@ -22,6 +22,7 @@ Soul 创业派对产品定位：面向创业者的社区/工具型小程序。 | 2026-03-10 | 会议：管理端迁移 Mycontent-temp，新菜单/布局与入口收敛验收口径确定 | 待续 | | 2026-03-11 | 以界面定需求文档建立；需求基准以《以界面定需求》为准 | 已完成 | | 2026-03-16 | 乘风发起例行开发进度同步 | 已完成 | +| 2026-03-16 | 会议：new-soul 新需求与当前项目差异分析 | 已完成 | > **格式说明**：每次开发后在此追加一行，日期格式 YYYY-MM-DD，状态用：已完成 / 进行中 / 待续 / 搁置 diff --git a/.cursor/agent/开发助理/项目索引/后端.md b/.cursor/agent/开发助理/项目索引/后端.md index 66ad5cd3..c25faa95 100644 --- a/.cursor/agent/开发助理/项目索引/后端.md +++ b/.cursor/agent/开发助理/项目索引/后端.md @@ -30,6 +30,7 @@ soul-api（Go + Gin + GORM + MySQL）提供三组路由：`/api/miniprogram/*` | 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 一致性待核对 | 待续 | > **格式说明**：每次开发后在此追加一行，日期格式 YYYY-MM-DD，状态用：已完成 / 进行中 / 待续 / 搁置 diff --git a/.cursor/agent/开发助理/项目索引/小程序.md b/.cursor/agent/开发助理/项目索引/小程序.md index f407c414..348c77b5 100644 --- a/.cursor/agent/开发助理/项目索引/小程序.md +++ b/.cursor/agent/开发助理/项目索引/小程序.md @@ -33,6 +33,7 @@ | 2026-03-14 | 我的页设置入口隐藏（wx:if）；资料修改引导场景梳理（登录后、@某人、找伙伴、链接卡若） | 已完成 | | 2026-03-16 | 乘风发起例行开发进度同步 | 已完成 | | 2026-03-16 | 编辑资料页分享名片：转发/朋友圈改为分享名片，Canvas 封面（头像+昵称+四栏信息），路径 member-detail | 已完成 | +| 2026-03-16 | 会议：new-soul 新需求与当前项目差异分析；派对AI 小程序站管理与当前一致 | 已完成 | > **格式说明**：每次开发后在此追加一行，日期格式 YYYY-MM-DD，状态用：已完成 / 进行中 / 待续 / 搁置 diff --git a/.cursor/agent/开发助理/项目索引/测试.md b/.cursor/agent/开发助理/项目索引/测试.md index 6573bd00..6841d740 100644 --- a/.cursor/agent/开发助理/项目索引/测试.md +++ b/.cursor/agent/开发助理/项目索引/测试.md @@ -26,6 +26,7 @@ | 2026-03-16 | scripts/test/process 流程测试目录：跨端业务流程 | 已完成 | | 2026-03-16 | pytest 架构、配置从项目读取、运行前显示测试环境 | 已完成 | | 2026-03-16 | 文章 @某人 自动创建存客宝：用例编写、执行、报告；归档规则 | 已完成 | +| 2026-03-16 | 会议：new-soul 新需求与当前项目差异分析；引入派对AI 时回归文章上传/飞书推送/小程序展示 | 已完成 | --- diff --git a/.cursor/agent/开发助理/项目索引/管理端.md b/.cursor/agent/开发助理/项目索引/管理端.md index e1d2dae8..7587c47b 100644 --- a/.cursor/agent/开发助理/项目索引/管理端.md +++ b/.cursor/agent/开发助理/项目索引/管理端.md @@ -27,6 +27,7 @@ | 2026-03-14 | 排名算法权重保存后刷新：handleSaveRankingWeights 成功后 loadRanking + 关闭弹窗，列表立即更新 | 已完成 | | 2026-03-16 | 乘风发起例行开发进度同步 | 已完成 | | 2026-03-16 | 链接人与事：table 布局、planId/apiKey 列、复制图标、删除 Dialog 弹窗 | 已完成 | +| 2026-03-16 | 会议：new-soul 新需求与当前项目差异分析；派对AI 不新增管理端需求 | 已完成 | > **格式说明**：每次开发后在此追加一行，日期格式 YYYY-MM-DD，状态用：已完成 / 进行中 / 待续 / 搁置 diff --git a/.cursor/agent/管理端开发工程师/evolution/2026-03-16.md b/.cursor/agent/管理端开发工程师/evolution/2026-03-16.md index 54ad42b0..4e794537 100644 --- a/.cursor/agent/管理端开发工程师/evolution/2026-03-16.md +++ b/.cursor/agent/管理端开发工程师/evolution/2026-03-16.md @@ -10,3 +10,7 @@ ## 删除弹窗尺寸 - max-w-md、p-4、gap-3，避免弹窗过大 + +## new-soul 派对AI 与管理端（会议：new-soul 新需求与当前项目差异分析） + +- 派对AI 不新增管理端需求，管理端以当前项目为准 diff --git a/.cursor/agent/软件测试/evolution/2026-03-16.md b/.cursor/agent/软件测试/evolution/2026-03-16.md new file mode 100644 index 00000000..5a417070 --- /dev/null +++ b/.cursor/agent/软件测试/evolution/2026-03-16.md @@ -0,0 +1,7 @@ +# 软件测试 经验记录 - 2026-03-16 + +## new-soul 派对AI 与测试关注点（会议：new-soul 新需求与当前项目差异分析） + +- 引入派对AI 流程时需回归：文章上传、飞书推送、小程序展示 +- 关注 content_upload.py 与 soul-api 数据流一致性，避免双写冲突 +- 环境差异：派对AI 为 Mac 路径，当前为 Windows，需确认是否同一代码库不同环境 diff --git a/.cursor/meeting/2026-03-16_new-soul新需求与当前项目差异分析.md b/.cursor/meeting/2026-03-16_new-soul新需求与当前项目差异分析.md new file mode 100644 index 00000000..0c10c9bf --- /dev/null +++ b/.cursor/meeting/2026-03-16_new-soul新需求与当前项目差异分析.md @@ -0,0 +1,123 @@ +# 会议纪要 - 2026-03-16 | new-soul 新需求与当前项目差异分析 + +> 本文件由**助理橙子**在会议结束后自动生成。 + +--- + +## 基本信息 + +- **时间**：2026-03-16 +- **议题**：new-soul 新需求分析与当前项目 Mycontent 的差异 +- **触发方式**：开会，所有人都参加，@new-soul 这是新需求 +- **参与角色**：产品经理、后端开发、管理端开发工程师、小程序开发工程师、测试人员 + +--- + +## 各角色发言 + +### 【产品经理】 + +**定位差异**： +- **new-soul 派对AI**：内容运营侧 AI 助手，服务于《一场soul的创业实验》的派对→录屏→剪辑→成片→分发→文章→小程序全链路。 +- **当前 Mycontent**：产品侧，面向创业者的社区/工具型小程序，核心是内容→会员→导师变现、存客宝对接、分销等。 + +**业务范围**： +- 派对AI 覆盖：运营报表、飞书管理、文章写作、视频剪辑、素材库上传、多平台分发、Soul 账号注册、小程序站管理（9 技能 5 组）。 +- 当前项目：三端代码 + 存客宝、链接人与事、VIP、分销等业务功能。 + +**结论**：两者是同一业务的不同层面（运营 vs 产品），非替代关系。 + +### 【后端开发】 + +**技术差异**： +- 派对AI 依赖 `content_upload.py` 直连腾讯云 MySQL 写入 `soul_miniprogram.chapters`；路径为 Mac（`/Users/karuo/...`）。 +- 当前项目：soul-api（Go/Gin/GORM），通过 `/api/miniprogram/*`、`/api/admin/*`、`/api/db/*` 提供接口。 + +**重叠点**：小程序站管理技能引用的 soul-api、soul-admin、miniprogram 与当前三端一致；数据库同为 `soul_miniprogram`。 + +**风险**：`content_upload.py` 直连 DB 与 soul-api 并存，存在双写风险；路径为 Mac，当前环境为 Windows，需统一或适配。 + +### 【管理端开发工程师】 + +派对AI 未单独定义管理端功能，仅通过「小程序站管理」引用 soul-admin。当前项目管理端（链接人与事、存客宝、VIP、推广中心等）为完整实现。**结论**：派对AI 不新增管理端需求。 + +### 【小程序开发工程师】 + +派对AI 的小程序站管理覆盖上传、部署、版本管理，与当前 miniprogram 一致。当前项目 C 端功能（文章阅读、@某人、存客宝留资、VIP、分销等）已实现。**结论**：派对AI 不改变小程序功能，仅涉及发布流程。 + +### 【测试人员】 + +1. **环境**：派对AI 为 Mac 路径，当前为 Windows，需确认是否同一代码库不同环境。 +2. **数据流**：`content_upload.py` 直写 DB vs soul-api 接口，需避免冲突。 +3. **回归**：若引入派对AI 流程，需回归文章上传、飞书推送、小程序展示。 + +--- + +## 讨论过程 + +- **产品经理 → 后端**：`content_upload.py` 是否应逐步迁移到 soul-api 接口？ +- **后端**：短期可保留直连，中长期规划为通过 soul-api admin/db 接口写入，统一数据入口。 +- **小程序 → 产品**：需确认 chapters 表结构与 `content_upload.py` 写入格式一致。 +- **后端**：需核对 `content_upload.py` 字段与 chapters 表、soul-api 模型一致性。 + +--- + +## 会议决议 + +1. **定位**：new-soul 派对AI 为运营侧 AI 助手，当前 Mycontent 为产品侧三端项目，二者互补，非替代。 +2. **三端**：小程序站管理技能与 soul-api、soul-admin、miniprogram 一致，无需调整三端代码。 +3. **路径**：派对AI 使用 Mac 路径，当前为 Windows；需在文档或配置中说明环境差异或提供路径映射。 +4. **数据**：`content_upload.py` 直连 DB 与 soul-api 并存，需核对 chapters 表结构与字段一致性。 +5. **待确认**：`content_upload.py` 与 soul-api 的 chapters 模型是否完全一致？是否规划将文章上传迁移到 soul-api 接口？ + +--- + +## 待办事项 + +| 责任角色 | 任务 | 优先级 | 截止建议 | +|---------|------|--------|---------| +| 后端开发 | 核对 content_upload.py 与 chapters 表/soul-api 模型一致性 | 中 | 2026-03-20 | +| 产品经理 | 确认文章上传是否规划迁移到 soul-api 接口 | 低 | 待定 | +| 助理橙子 | 在开发文档中补充 new-soul 与 Mycontent 关系说明 | 低 | 2026-03-18 | + +--- + +## 问题与作答区 + +| # | 问题 | 责任角色 | 作答 | +|---|------|---------|------| +| 1 | content_upload.py 与 soul-api 的 chapters 模型是否完全一致？ | 后端开发 | （待补充） | +| 2 | 是否规划将文章上传迁移到 soul-api 接口？ | 产品经理 | （待补充） | +| 3 | new-soul 派对AI 与 Mycontent 是否为同一代码库、不同环境（Mac vs Windows）？ | 产品经理 | （待补充） | + +--- + +## 各角色经验与业务理解更新 + +### 产品经理 + +- new-soul 派对AI 与 Mycontent 为同一业务的不同层面：运营侧 vs 产品侧，互补非替代。 + +### 后端开发 + +- content_upload.py 直连 DB 与 soul-api 并存，需核对 chapters 表结构；中长期可规划迁移到 soul-api 接口。 + +### 管理端开发工程师 + +- 派对AI 不新增管理端需求，管理端以当前项目为准。 + +### 小程序开发工程师 + +- 派对AI 的小程序站管理与当前 miniprogram 一致，仅涉及发布流程。 + +### 测试人员 + +- 引入派对AI 流程时需回归：文章上传、飞书推送、小程序展示；关注 content_upload.py 与 soul-api 数据流一致性。 + +### 团队共享 + +- new-soul 派对AI（魂AI）9 技能 5 组：魂资/魂流/魂产/魂码/魂质；与 Mycontent 三端（soul-api、soul-admin、miniprogram）为同一业务不同层面，路径差异（Mac vs Windows）需在文档中说明。 + +--- + +*会议纪要由助理橙子生成 | 各角色经验已同步至 `agent/{角色}/evolution/2026-03-16.md`* diff --git a/.cursor/meeting/README.md b/.cursor/meeting/README.md index b15688ae..43e7b188 100644 --- a/.cursor/meeting/README.md +++ b/.cursor/meeting/README.md @@ -74,3 +74,4 @@ YYYY-MM-DD_会议主题.md | 2026-03-10 | Toast 通知系统全局落地 & hot_score 数据库迁移 | 管理端、后端、团队 | [2026-03-10_Toast通知系统全局落地.md](2026-03-10_Toast通知系统全局落地.md) | | 2026-03-11 | 开发团队对齐业务逻辑与以界面定需求·会议收尾 | 产品、后端、管理端、小程序、团队 | [2026-03-11_开发团队对齐业务逻辑与以界面定需求会议收尾.md](2026-03-11_开发团队对齐业务逻辑与以界面定需求会议收尾.md) | | 2026-03-16 | 链接人与事与存客宝对接优化 | 管理端、后端、团队 | [2026-03-16_链接人与事与存客宝对接优化.md](2026-03-16_链接人与事与存客宝对接优化.md) | +| 2026-03-16 | new-soul 新需求与当前项目差异分析 | 产品、后端、管理端、小程序、测试 | [2026-03-16_new-soul新需求与当前项目差异分析.md](2026-03-16_new-soul新需求与当前项目差异分析.md) | diff --git a/miniprogram/app.js b/miniprogram/app.js index 53a7282e..045c2dc5 100644 --- a/miniprogram/app.js +++ b/miniprogram/app.js @@ -9,8 +9,8 @@ App({ globalData: { // API 基础地址（切换环境时注释/取消注释） // baseUrl: 'https://soulapi.quwanzhi.com', - baseUrl: 'http://localhost:8080', // 本地调试 - // baseUrl: 'https://souldev.quwanzhi.com', // 测试环境 + // baseUrl: 'http://localhost:8080', // 本地调试 + baseUrl: 'https://souldev.quwanzhi.com', // 测试环境 // 小程序配置 - 真实AppID diff --git a/开发文档/稳定版-小程序与API对比.md b/开发文档/稳定版-小程序与API对比.md new file mode 100644 index 00000000..627b5035 --- /dev/null +++ b/开发文档/稳定版-小程序与API对比.md @@ -0,0 +1,269 @@ +# 稳定版 vs 新版 · 小程序与 API 对比清单 + +> 稳定版：`miniprogram/`；新版：`new-soul/miniprogram/` +> 生成日期：2026-03-16 + +--- + +## 一、页面差异 + +| 页面 | 稳定版 | 新版 | 说明 | +|------|:-----:|:----:|------| +| pages/avatar-nickname | ✓ | ✗ | 新版移除，可能合并到 profile-edit | +| pages/wallet | ✗ | ✓ | **新版新增**：钱包（余额、充值、退款、交易记录） | +| 其它 22 页 | ✓ | ✓ | 一致 | + +--- + +## 二、小程序页面清单（稳定版） + +| 页面路径 | 功能 | Tab | +|---------|------|-----| +| pages/index/index | 首页 | ✓ | +| pages/chapters/chapters | 目录 | ✓ | +| pages/match/match | 找伙伴 | ✓ | +| pages/my/my | 我的 | ✓ | +| pages/read/read | 文章阅读 | - | +| pages/link-preview/link-preview | 链接预览 | - | +| pages/about/about | 关于作者 | - | +| pages/agreement/agreement | 用户协议 | - | +| pages/privacy/privacy | 隐私政策 | - | +| pages/referral/referral | 推广中心 | - | +| pages/purchases/purchases | 我的订单 | - | +| pages/settings/settings | 设置 | - | +| pages/search/search | 搜索 | - | +| pages/addresses/addresses | 收货地址列表 | - | +| pages/addresses/edit | 地址编辑 | - | +| pages/withdraw-records/withdraw-records | 提现记录 | - | +| pages/vip/vip | VIP 购买 | - | +| pages/member-detail/member-detail | 会员/用户详情 | - | +| pages/mentors/mentors | 导师列表 | - | +| pages/mentor-detail/mentor-detail | 导师详情 | - | +| pages/profile-show/profile-show | 资料展示 | - | +| pages/profile-edit/profile-edit | 资料编辑 | - | +| pages/avatar-nickname/avatar-nickname | 头像昵称 | - | + +--- + +## 三、小程序调用的 API 清单（稳定版，按模块） + +### 3.1 配置与登录 + +| 接口 | 方法 | 调用位置 | 用途 | +|------|------|----------|------| +| /api/miniprogram/config | GET | app.js, my.js, read.js, chapterAccessManager.js, custom-tab-bar | 公开配置（persons、linkTags、freeChapters 等） | +| /api/miniprogram/login | POST | app.js | 微信 code 登录 | +| /api/miniprogram/phone-login | POST | app.js | 手机号一键登录 | +| /api/miniprogram/phone | POST | index.js, settings.js | 获取手机号 | +| /api/miniprogram/dev/login-as | POST | settings.js | 开发专用：按 userId 切换账号 | + +### 3.2 书籍/章节 + +| 接口 | 方法 | 调用位置 | 用途 | +|------|------|----------|------| +| /api/miniprogram/book/all-chapters | GET | app.js, index.js, read.js | 全量章节树 | +| /api/miniprogram/book/parts | GET | chapters.js | 篇章列表（懒加载） | +| /api/miniprogram/book/chapters-by-part | GET | chapters.js | 按篇章返回章节 | +| /api/miniprogram/book/chapter/:id | GET | read.js | 按 id 获取章节 | +| /api/miniprogram/book/chapter/by-mid/:mid | GET | read.js | 按 mid 解析章节 | +| /api/miniprogram/book/hot | GET | search.js | 热门排行 | +| /api/miniprogram/book/recommended | GET | index.js | 推荐章节 | +| /api/miniprogram/book/latest-chapters | GET | index.js | 最新章节 | +| /api/miniprogram/book/search | GET | search.js | 搜索 | +| /api/miniprogram/book/stats | GET | about.js | 书籍统计 | + +### 3.3 用户/资料 + +| 接口 | 方法 | 调用位置 | 用途 | +|------|------|----------|------| +| /api/miniprogram/user/profile | GET/POST | profile-show, profile-edit, member-detail, index, read, match, my, settings, avatar-nickname | 用户资料 | +| /api/miniprogram/user/update | POST | my.js, settings.js | 更新用户（头像、昵称等） | +| /api/miniprogram/user/purchase-status | GET | read.js, chapterAccessManager.js | 购买状态（VIP/买断/单章） | +| /api/miniprogram/user/check-purchased | GET | chapterAccessManager.js | 校验是否已购买 | +| /api/miniprogram/user/dashboard-stats | GET | my.js | 阅读统计（我的页） | +| /api/miniprogram/user/reading-progress | GET/POST | readingTracker.js | 阅读进度 | +| /api/miniprogram/user/addresses | GET/POST | addresses.js, addresses/edit.js | 收货地址 CRUD | +| /api/miniprogram/user/addresses/:id | GET/PUT/DELETE | addresses.js, addresses/edit.js | 单条地址 | + +### 3.4 VIP + +| 接口 | 方法 | 调用位置 | 用途 | +|------|------|----------|------| +| /api/miniprogram/vip/status | GET | vip.js, chapters.js, my.js, profile-edit | VIP 状态 | +| /api/miniprogram/vip/members | GET | index.js, member-detail.js | VIP 会员列表/单个 | +| /api/miniprogram/vip/profile | GET/POST | （未直接调用，vip 组有） | VIP 资料 | + +### 3.5 支付与订单 + +| 接口 | 方法 | 调用位置 | 用途 | +|------|------|----------|------| +| /api/miniprogram/pay | GET/POST | read.js, vip.js, match.js | 创建订单/查询 | +| /api/miniprogram/orders | GET | purchases.js | 订单列表 | +| /api/miniprogram/qrcode | POST | read.js, referral.js | 生成小程序码 | + +### 3.6 分销/推广 + +| 接口 | 方法 | 调用位置 | 用途 | +|------|------|----------|------| +| /api/miniprogram/referral/visit | POST | app.js | 访问记录 | +| /api/miniprogram/referral/bind | POST | app.js | 绑定推广关系 | +| /api/miniprogram/referral/data | GET | referral.js | 推广数据 | +| /api/miniprogram/earnings | GET | my.js | 我的收益 | +| /api/miniprogram/withdraw | POST | my.js, referral.js | 申请提现 | +| /api/miniprogram/withdraw/records | GET | withdraw-records.js | 提现记录 | +| /api/miniprogram/withdraw/pending-confirm | GET | my.js | 待确认收款 | +| /api/miniprogram/withdraw/confirm-received | POST | my.js | 确认收款 | +| /api/miniprogram/withdraw/confirm-info | GET | my.js, withdraw-records.js | 领取零钱参数 | + +### 3.7 存客宝（CKB） + +| 接口 | 方法 | 调用位置 | 用途 | +|------|------|----------|------| +| /api/miniprogram/ckb/index-lead | POST | index.js | 首页「链接卡若」留资 | +| /api/miniprogram/ckb/lead | POST | read.js | 文章 @某人 留资 | +| /api/miniprogram/ckb/match | POST | match.js | 找伙伴留资 | +| /api/miniprogram/ckb/join | POST | match.js | 加入匹配池 | + +### 3.8 找伙伴 + +| 接口 | 方法 | 调用位置 | 用途 | +|------|------|----------|------| +| /api/miniprogram/match/config | GET | match.js | 找伙伴配置 | +| /api/miniprogram/match/users | POST | match.js | 匹配用户 | + +### 3.9 导师 + +| 接口 | 方法 | 调用位置 | 用途 | +|------|------|----------|------| +| /api/miniprogram/mentors | GET | mentors.js | 导师列表 | +| /api/miniprogram/mentors/:id | GET | mentor-detail.js | 导师详情 | +| /api/miniprogram/mentors/:id/book | POST | mentor-detail.js | 预约导师 | + +### 3.10 其它 + +| 接口 | 方法 | 调用位置 | 用途 | +|------|------|----------|------| +| /api/miniprogram/upload | POST | my.js, profile-edit, settings, avatar-nickname | 图片上传 | +| /api/miniprogram/users | GET | index.js, member-detail.js | 用户列表/单个（超级个体、回退） | +| /api/miniprogram/about/author | GET | about.js | 关于作者配置 | + +--- + +## 四、soul-api 已注册的 miniprogram 路由（稳定版） + +| 路由 | 方法 | Handler | +|------|------|---------| +| /api/miniprogram/config | GET | GetPublicDBConfig | +| /api/miniprogram/login | POST | MiniprogramLogin | +| /api/miniprogram/phone-login | POST | WechatPhoneLogin | +| /api/miniprogram/dev/login-as | POST | MiniprogramDevLoginAs | +| /api/miniprogram/phone | POST | MiniprogramPhone | +| /api/miniprogram/pay | GET/POST | MiniprogramPay | +| /api/miniprogram/pay/notify | POST | MiniprogramPayNotify | +| /api/miniprogram/qrcode | POST | MiniprogramQrcode | +| /api/miniprogram/qrcode/image | GET | MiniprogramQrcodeImage | +| /api/miniprogram/book/all-chapters | GET | BookAllChapters | +| /api/miniprogram/book/parts | GET | BookParts | +| /api/miniprogram/book/chapters-by-part | GET | BookChaptersByPart | +| /api/miniprogram/book/chapter/:id | GET | BookChapterByID | +| /api/miniprogram/book/chapter/by-mid/:mid | GET | BookChapterByMID | +| /api/miniprogram/book/hot | GET | BookHot | +| /api/miniprogram/book/recommended | GET | BookRecommended | +| /api/miniprogram/book/latest-chapters | GET | BookLatestChapters | +| /api/miniprogram/book/search | GET | BookSearch | +| /api/miniprogram/book/stats | GET | BookStats | +| /api/miniprogram/referral/visit | POST | ReferralVisit | +| /api/miniprogram/referral/bind | POST | ReferralBind | +| /api/miniprogram/referral/data | GET | ReferralData | +| /api/miniprogram/earnings | GET | MyEarnings | +| /api/miniprogram/match/config | GET | MatchConfigGet | +| /api/miniprogram/match/users | POST | MatchUsers | +| /api/miniprogram/ckb/join | POST | CKBJoin | +| /api/miniprogram/ckb/match | POST | CKBMatch | +| /api/miniprogram/ckb/lead | POST | CKBLead | +| /api/miniprogram/ckb/index-lead | POST | CKBIndexLead | +| /api/miniprogram/upload | POST/DELETE | UploadPost / UploadDelete | +| /api/miniprogram/user/addresses | GET/POST | UserAddressesGet/Post | +| /api/miniprogram/user/addresses/:id | GET/PUT/DELETE | UserAddressesByID | +| /api/miniprogram/user/check-purchased | GET | UserCheckPurchased | +| /api/miniprogram/user/dashboard-stats | GET | UserDashboardStats | +| /api/miniprogram/user/profile | GET/POST | UserProfileGet/Post | +| /api/miniprogram/user/purchase-status | GET | UserPurchaseStatus | +| /api/miniprogram/user/reading-progress | GET/POST | UserReadingProgressGet/Post | +| /api/miniprogram/user/update | POST | UserUpdate | +| /api/miniprogram/withdraw | POST | WithdrawPost | +| /api/miniprogram/withdraw/records | GET | WithdrawRecords | +| /api/miniprogram/withdraw/pending-confirm | GET | WithdrawPendingConfirm | +| /api/miniprogram/withdraw/confirm-received | POST | WithdrawConfirmReceived | +| /api/miniprogram/withdraw/confirm-info | GET | WithdrawConfirmInfo | +| /api/miniprogram/vip/status | GET | VipStatus | +| /api/miniprogram/vip/profile | GET/POST | VipProfileGet/Post | +| /api/miniprogram/vip/members | GET | VipMembers | +| /api/miniprogram/users | GET | MiniprogramUsers | +| /api/miniprogram/orders | GET | MiniprogramOrders | +| /api/miniprogram/mentors | GET | MiniprogramMentorsList | +| /api/miniprogram/mentors/:id | GET | MiniprogramMentorsDetail | +| /api/miniprogram/mentors/:id/book | POST | MiniprogramMentorsBook | +| /api/miniprogram/about/author | GET | MiniprogramAboutAuthor | + +--- + +## 五、对齐情况 + +| 状态 | 说明 | +|------|------| +| ✓ 已对齐 | 小程序调用的所有 `/api/miniprogram/*` 接口均在 soul-api router 中注册 | +| - | 小程序未调用 `/api/miniprogram/vip/profile`，但后端已提供（备用） | + +--- + +## 六、新版（new-soul）新增 API（稳定版 soul-api 暂无） + +| 接口 | 方法 | 调用位置 | 用途 | +|------|------|----------|------| +| /api/miniprogram/balance | GET | wallet.js | 查询余额、累计充值/赠送/退款 | +| /api/miniprogram/balance/transactions | GET | wallet.js | 交易记录列表 | +| /api/miniprogram/balance/recharge | POST | wallet.js | 创建充值订单 | +| /api/miniprogram/balance/recharge/confirm | POST | wallet.js | 支付成功后确认充值 | +| /api/miniprogram/balance/refund | POST | wallet.js | 余额退款 | +| /api/miniprogram/user-rules | GET | ruleEngine.js | 规则引擎：按场景触发引导 | +| /api/miniprogram/track | POST | trackClick.js, ruleEngine.js | 埋点上报 | + +**说明**：新版 wallet 页的支付流程为：`balance/recharge` → `pay`（productType: 'balance_recharge'）→ `balance/recharge/confirm`。稳定版 soul-api 需新增上述路由才能支持新版钱包功能。 + +--- + +## 七、新版新增能力（稳定版无） + +| 能力 | 说明 | +|------|------| +| **规则引擎** | `utils/ruleEngine.js` + `/api/miniprogram/user-rules`，按 page_show、after_login 等场景触发引导 | +| **埋点上报** | `utils/trackClick.js` + `/api/miniprogram/track` | +| **运行配置** | `loadRuntimeConfig()` 从 config 取 `mpConfig.apiDomain` 等，支持动态覆盖 baseUrl | +| **单页模式** | `ensureFullAppForAuth()` 检测朋友圈单页，引导用户「前往小程序」 | +| **更新检测** | `checkUpdate()` 基于 wx.getUpdateManager | +| **navigateToMiniProgramAppIdList** | 新版 app.json 配置 `wx6489c26045912fe1`、`wx3d15ed02e98b04e3` | +| **我的页** | 新版有 `loadWalletBalance`、`loadGiftList`（代付链接） | + +--- + +## 八、config 返回格式差异 + +| 字段 | 稳定版 | 新版 | +|------|--------|------| +| 主结构 | persons、linkTags、freeChapters、prices 等 | 同上 + `mpConfig`、`features` | +| mpConfig | - | apiDomain、appId、mchId、withdrawSubscribeTmplId | +| features | - | matchEnabled 等 | +| configs.feature_config | - | 备用格式，含 matchEnabled | + +--- + +## 九、迁移建议 + +1. **后端**：soul-api 需新增 balance、user-rules、track 相关路由，才能完整支持新版。 +2. **稳定版→新版**：若稳定版要升级，需补充 wallet 页、ruleEngine、trackClick，并调整 config 返回格式。 +3. **新版→稳定版**：若新版要回退，需移除 wallet、user-rules、track 依赖，或在后端做空实现。 + +--- + +*文档由助理橙子生成 | 基于 miniprogram/、new-soul/miniprogram/ 与 soul-api/internal/router/router.go 扫描*