fnvtk/soul-yongping
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
991e17698c48be92c4cf6cb5fca73ee283efffa7
soul-yongping/.cursor/meeting/2026-03-09_dev分支需求分析与yongxu迁移方案.md

8.0 KiB
Raw Blame History

dev 分支需求分析与 yongxu 迁移方案

基于用户反馈：dev 分支只改了样式，未考虑后端/API/小程序三端协调，导致 bug 或功能不全；yongxu 分支功能完善。本文档分析 dev 需求、识别三端缺口，并给出「新功能迁入 yongxu + 补全功能」的执行方案。

一、dev 分支变更概览

1.1 变更性质（用户结论）

  • dev 侧重：管理端 UI/样式、新页面布局
  • 问题：未同步考虑 soul-api、miniprogram 的接口与逻辑，导致：
    • 管理端新页面调用的接口在 yongxu 的 soul-api 中不存在或不全
    • 小程序端与 dev 管理端配置/数据模型不一致
    • 三端联调时出现 bug 或功能不全

1.2 dev 相对 yongxu 的增量（按模块）

模块 dev 新增/改动 依赖的 API/能力
soul-admin ContentPage 大改、ChapterTree、RichEditor、@提及、persons、link-tags 配置 /api/db/book（含 section-orders）、/api/db/persons、/api/db/link-tags、/api/db/config/full?key=xxx
soul-admin FindPartnerPage + 多 Tab（CKBConfigPanel、CKBStatsTab、MatchPoolTab 等） /api/db/config/full?key=ckb_config、/api/db/ckb-leads
soul-admin UsersPage 大改、UserDetailModal 扩展 /api/db/users 已有，可能需扩展字段
soul-admin ChaptersPage 新增、DashboardPage 调整 依赖 db/book、db/users 等
soul-admin DistributionPage、SettingsPage 等样式调整 现有 admin 接口
soul-api admin_dashboard、admin_rfm、admin_shensheshou、admin_user_rules 新增 handler
soul-api db_person、db_book 扩展（section-orders、move-sections） 扩展 db_book action
soul-api ckb 扩展、match/match_records 扩展 扩展 ckb、match handler
miniprogram 部分页面简化/样式调整 与 yongxu 的 @提及、推荐码等可能冲突

二、三端缺口分析（yongxu 当前缺失）

2.1 soul-api 缺口（管理端新页面依赖）

接口/能力 dev 管理端调用 yongxu 是否已有 缺口说明
GET/POST/DELETE /api/db/persons ContentPage @提及人物配置 ❌ 无 需新增 persons 表、model、handler
GET/POST/DELETE /api/db/link-tags ContentPage 链接标签配置 ❌ 无 需新增 link_tags 表、model、handler
GET /api/db/book?action=section-orders&id=xxx ContentPage 章节内排序 ❌ 无 需在 db_book 中扩展 action
PUT /api/db/book action=move-sections ContentPage 跨章移动 ❌ 无 需在 db_book 中扩展
GET /api/db/config/full?key=article_ranking_weights ContentPage ✅ 有 DBConfigGet 已支持
GET /api/db/config/full?key=pinned_section_ids ContentPage ✅ 有 同上
GET /api/db/config/full?key=unpaid_preview_percent ContentPage ✅ 有 同上
GET /api/db/config/full?key=ckb_config FindPartnerPage CKBConfigPanel ✅ 有 同上
GET /api/db/ckb-leads?mode=submitted&page=1&pageSize=50 FindPartnerPage 存客宝线索 ❌ 无 需新增 ckb_leads 相关接口
admin_dashboard、admin_rfm、admin_shensheshou、admin_user_rules Dashboard、神奢手等 ❌ 无 可选，按业务需要

2.2 小程序端

  • yongxu 已完善：@提及、推荐码、baseUrl、goBackOrToHome、一键收款、免费章节、存客宝限频、退款等
  • 策略：保留 yongxu 小程序全部逻辑，不引入 dev 对 miniprogram 的简化（dev 可能删减了功能）

2.3 管理端（soul-admin）

  • yongxu 已有：ContentPage、ChapterTree、UsersPage、DashboardPage 等基础版本
  • dev 增量：更丰富的 ContentPage（persons、link-tags、RichEditor @提及）、FindPartnerPage 整页、UsersPage 扩展
  • 策略：在 soul-api 补全接口后，再选择性迁入 dev 的页面组件

三、迁移原则

  1. 基准分支：yongxu（功能完善、三端协调良好）
  2. 不引入：dev 对 miniprogram 的改动（避免覆盖 yongxu 的 @提及、推荐码等）
  3. 分阶段：先补 soul-api 缺口 → 再迁入 soul-admin 新页面/组件
  4. 三端协调：每迁入一个管理端功能，必须确保 soul-api 已有对应接口，且小程序若依赖该配置则已对齐

四、执行方案（按优先级）

阶段 1：soul-api 补全（必须）

序号 任务 说明
1.1 新增 db/persons model.Person、表 persons，GET/POST/DELETE，供 ContentPage @提及人物配置
1.2 新增 db/link-tags model.LinkTag、表 link_tags，GET/POST/DELETE，供 ContentPage 链接标签
1.3 扩展 db/book 增加 action=section-orders、action=move-sections（若 ContentPage 需要）
1.4 新增 db/ckb-leads 若存在 ckb_leads 表，GET 支持 mode=submitted/contact 分页；否则先建表再实现

阶段 2：soul-admin 迁入（在阶段 1 完成后）

序号 任务 说明
2.1 ContentPage 增强 从 dev 迁入 persons、link-tags 配置区，RichEditor @提及（需 persons 接口）
2.2 FindPartnerPage 从 dev 迁入整页 + Tab（CKBConfigPanel、CKBStatsTab 等），需 ckb_config、ckb-leads 接口
2.3 UsersPage 扩展 从 dev 迁入 UserDetailModal 等扩展（若字段与 yongxu 的 db/users 一致）
2.4 菜单与路由 在 AdminLayout、App.tsx 中增加 FindPartner 入口（若尚未有）

阶段 3：可选（按业务需要）

序号 任务 说明
3.1 admin_dashboard、admin_rfm 等 若 Dashboard 需要新统计维度，再补充
3.2 dev 的 scripts、飞书导出等 与三端功能无直接关系，可单独评估

五、补全功能清单（可直接用于开发）

5.1 soul-api 必须补全

[ ] 1. persons 表 + model + GET/POST/DELETE /api/db/persons
[ ] 2. link_tags 表 + model + GET/POST/DELETE /api/db/link-tags
[ ] 3. db_book 扩展：GET ?action=section-orders&id=xxx
[ ] 4. db_book 扩展：PUT action=move-sections（若 ContentPage 需要）
[ ] 5. ckb_leads 表（若无）+ GET /api/db/ckb-leads?mode=xxx&page=1&pageSize=50

5.2 soul-admin 迁入（依赖 5.1）

[ ] 6. ContentPage：persons 配置区、link-tags 配置区
[ ] 7. ContentPage：RichEditor @提及（调用 persons）
[ ] 8. FindPartnerPage + Tabs（CKBConfigPanel、CKBStatsTab、FindPartnerTab 等）
[ ] 9. AdminLayout：增加「找伙伴」菜单项（若尚无）
[ ] 10. UsersPage：UserDetailModal 扩展（按需）

5.3 小程序

[ ] 无需变更，保留 yongxu 全部逻辑

六、迁移操作建议

6.1 不推荐直接 merge devlop

  • dev 与 yongxu 在 miniprogram、部分 soul-api 上存在冲突
  • 直接 merge 会覆盖 yongxu 的完善功能

6.2 推荐方式

  1. 保持当前在 yongxu 分支
  2. 按阶段 1：在 yongxu 上直接开发 soul-api 补全（persons、link-tags、db_book 扩展、ckb-leads）
  3. 按阶段 2：用 git show devlop:path/to/file 取出 dev 的 soul-admin 文件，手工合并到 yongxu，并确认调用的接口已在 soul-api 中存在
  4. 每完成一个功能：过 soul-change-checklist，做三端联调验证

6.3 冲突文件处理（若必须 diff 参考）

  • miniprogram/*：以 yongxu 为准，不采纳 dev 的改动
  • soul-admin/*：选择性采纳 dev 的 UI/组件，确保调用的 API 已在 yongxu 的 soul-api 中实现
  • soul-api/*：以 yongxu 为基础，缺什么补什么（persons、link-tags、ckb-leads 等）

七、总结

项目 结论
基准 yongxu
dev 价值 管理端 UI 增强（ContentPage、FindPartnerPage、UsersPage）
dev 问题 未配套 soul-api 的 persons、link-tags、ckb-leads 等，导致功能不全
迁移路径 先补 soul-api → 再迁入 soul-admin 新页面
小程序 不改动，保留 yongxu

文档生成：2026-03-09 | 供开发执行参考