7.4 KiB
7.4 KiB
管理端与 API 合并分析 - 2026-03-09
devlop vs yongxu 在 soul-admin、soul-api 的差异分析，边界合规性，合并建议。
一、管理端（soul-admin）
1.1 差异概览
| 方向 | 说明 |
|---|---|
| devlop 新增 | FindPartnerPage、ChaptersPage、RichEditor、ContentPage 深度优化、Dashboard 概览、UserDetailModal 神射手、UsersPage RFM/用户规则/旅程统计 |
| yongxu | 管理端无独有改动（yongxu 主要在小程序侧） |
结论：管理端以 devlop 为准，无需从 yongxu 合并。
1.2 devlop 新增/变更的页面与接口
| 页面/组件 | 路由 | 主要接口 | 后端是否注册 |
|---|---|---|---|
| FindPartnerPage | /find-partner | /api/db/match-records、ckb-plan-stats、match-pool-counts、ckb-leads、config/full?key=ckb_config | ✅ |
| ChaptersPage | /chapters | /api/admin/chapters | ✅ |
| ContentPage | /content | /api/db/book、persons、link-tags、config | ✅ |
| DashboardPage | /dashboard | /api/admin/dashboard/overview | ✅ |
| UserDetailModal | - | /api/admin/shensheshou/query、enrich、ingest | ✅ |
| UsersPage | /users | /api/db/users/rfm、user-rules、users/journey-stats | ✅ |
| RichEditor | 组件 | - | - |
1.3 管理端 API 调用清单（devlop 当前）
| 接口 | 使用页面 | 说明 |
|---|---|---|
| /api/admin/dashboard/overview | DashboardPage | 数据概览 |
| /api/admin/chapters | ChaptersPage | 章节树 CRUD |
| /api/admin/shensheshou/* | UserDetailModal | 神射手查询/入库/enrich |
| /api/admin/distribution/overview | DistributionPage | 分销概览 |
| /api/admin/withdrawals | WithdrawalsPage、DistributionPage | 提现审核 |
| /api/admin/orders/refund | OrdersPage、DistributionPage | 订单退款 |
| /api/admin/referral-settings | ReferralSettingsPage | 推广设置 |
| /api/admin/settings | SettingsPage | 系统设置 |
| /api/admin/author-settings | AuthorSettingsPage | 作者设置 |
| /api/admin/users | AdminUsersPage | 管理员用户 |
| /api/admin/logout | AdminLayout | 登出 |
| /api/db/users | 多页 | 用户 CRUD |
| /api/db/users/rfm | UsersPage | RFM 估值 |
| /api/db/users/referrals | UsersPage、UserDetailModal | 推荐关系 |
| /api/db/users/journey-stats | UsersPage | 用户旅程统计 |
| /api/db/user-rules | UsersPage | 用户规则 |
| /api/db/book | ContentPage | 内容/章节 CRUD |
| /api/db/persons | ContentPage | 人物管理 |
| /api/db/link-tags | ContentPage | 链接标签 |
| /api/db/config、config/full | 多页 | 配置 |
| /api/db/match-records | FindPartner、MatchRecords | 匹配记录 |
| /api/db/match-pool-counts | MatchPoolTab | 匹配池统计 |
| /api/db/ckb-plan-stats | CKBStatsTab | CKB 计划统计 |
| /api/db/ckb-leads | CKBConfigPanel | CKB 线索明细 |
| /api/db/vip-roles | VipRolesPage、SetVipModal | VIP 角色 |
| /api/db/mentors | MentorsPage | 导师 |
| /api/db/mentor-consultations | MentorConsultationsPage | 导师预约 |
| /api/orders | OrdersPage | 订单列表 |
1.4 边界合规性 ✅
- 仅调用
/api/admin/*、/api/db/*、/api/orders - 未调用
/api/miniprogram/*
1.5 合并建议
- 不合并：管理端以 devlop 为准
- 联调验证：Dashboard、FindPartner、ContentPage、UsersPage（RFM、user-rules、journey-stats）与后端接口联调
二、API 后端（soul-api）
2.1 差异概览
| 项目 | yongxu | devlop |
|---|---|---|
| config | CkbLeadAPIKey、DB_DSN 默认本地、SyncOrdersInterval 默认 0 | 移除 CkbLeadAPIKey、DB_DSN 必填（Fatal）、SyncOrdersInterval 默认 5 |
| database | 迁移 CkbSubmitRecord、CkbLeadRecord | 迁移 UserRule、Person、LinkTag、Chapter；移除 CkbSubmitRecord、CkbLeadRecord 迁移；seedDefaultRules |
| handler | 基础 handler | 新增 admin_dashboard、admin_shensheshou、db_book 扩展、db_person、db_link_tag、db_user_rules、db_users_rfm、db_users_journey_stats、db_match_pool_counts、db_ckb_plan_stats、db_ckb_leads 等 |
| router | 基础路由 | 新增上述路由 |
2.2 devlop 配置变更（需关注）
| 配置项 | yongxu | devlop | 影响 |
|---|---|---|---|
| DB_DSN | 默认 user:pass@tcp(127.0.0.1:3306)/soul?... |
未配置则 Fatal 退出 | 部署需显式配置 DB_DSN |
| CkbLeadAPIKey | 从环境变量读取 | 已移除 | ckb.go 使用硬编码 ckbAPIKey，不影响运行 |
| SyncOrdersIntervalMinutes | 默认 0 | 默认 5 | 订单对账定时任务每 5 分钟执行 |
2.3 devlop 数据库迁移变更
| 项目 | yongxu | devlop |
|---|---|---|
| CkbSubmitRecord | 迁移 | 移除迁移 |
| CkbLeadRecord | 迁移 | 移除迁移 |
| UserRule | - | 新增迁移 + seedDefaultRules |
| Person | - | 新增迁移 |
| LinkTag | - | 新增迁移 |
| Chapter | - | 新增迁移（hot_score_override） |
说明：CkbLeadRecord、CkbSubmitRecord 迁移被移除，但 model 与 handler 仍存在。DBCKBLeadList、CKBLead 可能依赖存客宝 API 或本地表——若本地表仍在使用，需确认迁移策略。
2.4 路由分组合规性 ✅
| 路由组 | 前缀 | 使用方 | 状态 |
|---|---|---|---|
| miniprogram | /api/miniprogram/* | 小程序 | ✅ |
| admin | /api/admin/* | 管理端 | ✅ |
| db | /api/db/* | 管理端 | ✅ |
2.5 待确认项
| 项目 | 说明 |
|---|---|
| /api/orders 鉴权 | 仍在 api 根下，未经过 AdminAuth |
| CkbLeadRecord 表 | 迁移已移除，若 DBCKBLeadList 或 CKBLead 仍写本地表，需恢复迁移或改实现 |
| router.go 格式 | 第 51 行 admin.GET("/distribution/overview") 缩进异常，建议修正 |
2.6 合并建议
- 以 devlop 为准：API 侧 devlop 已大幅领先
- yongxu 无独有 API 改动：无需从 yongxu 合并
- 部署注意：devlop 要求 DB_DSN 必填，需在 .env 中配置
- 可选恢复：若 CKB 线索需落本地表，可考虑恢复 CkbLeadRecord 迁移（与老板确认）
三、管理端 ↔ API 接口对应检查
| 管理端调用 | soul-api 路由 | 状态 |
|---|---|---|
| /api/admin/dashboard/overview | admin.GET("/dashboard/overview") | ✅ |
| /api/admin/chapters | admin.GET/POST/PUT/DELETE("/chapters") | ✅ |
| /api/admin/shensheshou/query | admin.GET("/shensheshou/query") | ✅ |
| /api/admin/shensheshou/enrich | admin.POST("/shensheshou/enrich") | ✅ |
| /api/admin/shensheshou/ingest | admin.POST("/shensheshou/ingest") | ✅ |
| /api/db/ckb-leads | db.GET("/ckb-leads") | ✅ |
| /api/db/ckb-plan-stats | db.GET("/ckb-plan-stats") | ✅ |
| /api/db/match-pool-counts | db.GET("/match-pool-counts") | ✅ |
| /api/db/users/rfm | db.GET("/users/rfm") | ✅ |
| /api/db/users/journey-stats | db.GET("/users/journey-stats") | ✅ |
| /api/db/user-rules | db.GET/POST/PUT/DELETE("/user-rules") | ✅ |
| /api/db/persons | db.GET/POST/DELETE("/persons") | ✅ |
| /api/db/link-tags | db.GET/POST/DELETE("/link-tags") | ✅ |
| /api/db/book?action=section-orders | db.GET("/book") | ✅ |
| 其他 | 见 router.go | ✅ |
结论：管理端调用的接口均在 soul-api 中注册，无 404 风险。
四、总结
| 端 | 合并策略 | 备注 |
|---|---|---|
| 管理端 | 以 devlop 为准，不合并 | yongxu 无管理端独有改动 |
| API | 以 devlop 为准，不合并 | 部署需配置 DB_DSN；CkbLeadRecord 迁移移除需确认 |
| 小程序 | 已补入 @提及 | 见 2026-03-09_合并策略与执行清单.md |
分析完成时间：2026-03-09