# 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 | 供开发执行参考*