# 后端当前能力盘点

更新时间：2026-06-28

当前后端已经完成商用 SaaS 题库系统的主干骨架：PostgreSQL 多租户 schema、Node.js 业务 API、PocketBase 数据导入工具、本地 seed、API 集成测试和对象存储签名 provider。

状态分为：

- `可联调`：前端可以开始接入，本地测试已覆盖主链路。
- `迁移期`：能支撑开发联调，但生产前必须替换或加固。
- `待补齐`：旧题库已有或商用交付需要，但新后端还没完整实现。

## 基础工程

| 模块 | 状态 | 说明 |
| --- | --- | --- |
| Supabase/PostgreSQL schema | 可联调 | `supabase/migrations` 已包含多租户、题库、学习、订单、内容、CRM、平台账务等表 |
| RLS/租户隔离 | 迁移期 | 表层普遍有 `tenant_id` 和 RLS 策略，但 API 目前使用服务端连接，生产前要补真实 JWT/RLS 回归 |
| API 分层 | 可联调 | `apps/api/src/core` + `apps/api/src/features/*` |
| Docker API | 可联调 | `docker-compose.api.yml` 和 `apps/api/Dockerfile` 可用 |
| 测试 | 可联调 | `npm run check:refactor` 覆盖 TS 检查、导入校验、seed、API 集成测试 |
| 根 workspace | 可联调 | 根目录已清理为新技术栈 monorepo 编排层 |

## 租户与品牌

| 能力 | 状态 | 后端接口/模型 |
| --- | --- | --- |
| 域名/小程序码解析租户 | 可联调 | `GET /api/tenant/resolve` |
| 品牌名、Logo、客服、主题 JSON | 可联调 | `tenant_branding`、`tenant_settings` |
| 功能开关 | 可联调 | `features`、`adminFeatures` |
| 自定义域名管理 | 可联调 | `GET/POST /api/tenant-admin/domains` |
| 多套主题模板 | 待补齐 | 当前只有租户 theme JSON，缺平台主题模板、预览、发布流程 |

## 鉴权与权限

| 能力 | 状态 | 说明 |
| --- | --- | --- |
| 短信验证码登录 | 迁移期 | 已有验证码、冷却、hash、登录事件；mock provider 可本地联调 |
| 迁移期 session | 迁移期 | `tk_` token hash 存在 `app_private.auth_sessions` |
| 微信/QQ OAuth | 待补齐 | 目前是 placeholder |
| 平台管理员鉴权 | 迁移期 | 当前用 `x-platform-admin-key`，生产前必须换 JWT/服务端会话 |
| 租户角色权限 | 可联调 | `tenant_memberships.role + permissions`，接口有权限点校验 |
| 自定义角色模板 | 待补齐 | 当前有权限 JSON 覆盖，缺角色模板、菜单/模块/字段级权限配置 UI/API |

## 学生端题库主链路

| 能力 | 状态 | 后端接口/模型 |
| --- | --- | --- |
| 地区/科目/分类兼容查询 | 可联调 | `/api/catalog/regions`、`subjects`、`categories` |
| 新内容入口 | 可联调 | `/api/catalog/content-entries` |
| 任意深度分类树 | 可联调 | `/api/catalog/content-nodes` |
| 题目列表/集合 | 可联调 | `/api/catalog/question-collections`、`question-collections/questions` |
| 顺序/随机/全真模拟规则 | 可联调 | `/api/catalog/practice-blueprints` |
| 创建练习 session | 可联调 | `POST /api/learning/practice-sessions` |
| 答题记录 | 可联调 | `POST /api/learning/answers` |
| 错题本 | 可联调 | `/api/learning/wrong-questions` |
| 收藏夹 | 可联调 | `/api/learning/favorites/questions` |
| 免费用户题量限制 | 待补齐 | 旧项目有保护逻辑，新后端需按租户/套餐/内容范围实现 |
| 模考交卷报告 | 待补齐 | 已有 session/answer 基础，缺完整交卷、评分报告、错题解析汇总 |

## 背单词、知识手册、分数线、视频

| 能力 | 状态 | 后端接口/模型 |
| --- | --- | --- |
| 单词单元/单词列表 | 可联调 | `/api/catalog/vocabulary-units`、`vocabulary-words` |
| 单词进度/收藏/统计 | 可联调 | `/api/learning/vocabulary/*` |
| 艾宾浩斯复习算法 | 待补齐 | 当前有 next_review 字段基础，缺完整算法和每日计划 |
| 知识手册目录/内容 | 可联调 | `/api/catalog/handbook-*` |
| 知识手册 JSON 导入 | 可联调 | `/api/tenant-content/imports/*/handbook` |
| 分数线字段/院校/专业/记录/趋势 | 可联调 | `/api/scoreline/*` |
| 题目视频/批量预加载/搜索 | 可联调 | `/api/questions/*/videos`、`/api/videos/search` |
| 视频会员播放次数 | 待补齐 | 缺播放次数扣减、播放日志、防盗链、水印 |

## 资料与对象存储

| 能力 | 状态 | 说明 |
| --- | --- | --- |
| 内容资源台账 | 可联调 | `content_assets` |
| 租户后台资源维护 | 可联调 | `/api/tenant-content/assets` |
| 学生端资源列表/下载签名 | 可联调 | `/api/catalog/assets`、`/api/catalog/assets/download` |
| 阿里云 OSS 签名 | 可联调 | `aliyun_oss` provider |
| 腾讯 COS 签名 | 可联调 | `tencent_cos` provider |
| Supabase Storage 签名 | 可联调 | `supabase_storage` provider |
| PDF 预览/防盗链/水印 | 待补齐 | 商用上线前补齐 |
| 上传后对象校验 | 待补齐 | 需 worker 或 API 回调确认 size/hash/mime |

## 订单、会员、营销

| 能力 | 状态 | 说明 |
| --- | --- | --- |
| SVIP 套餐 | 可联调 | `/api/catalog/svip-plans` |
| 创建订单/订单列表 | 可联调 | `/api/commerce/orders` |
| 手工支付确认 | 迁移期 | 可用于测试，不是生产支付 |
| 权益查询/校验 | 可联调 | `/api/commerce/entitlements` |
| 激活码兑换 | 可联调 | 事务开通权益 |
| 优惠券后台配置 | 可联调 | `/api/tenant-admin/coupons` |
| 优惠券前台兑换/下单抵扣 | 待补齐 | 后端还需接入下单计算 |
| 微信/支付宝/小程序支付 | 待补齐 | 需 provider、验签、幂等、退款、补偿 |

## 租户后台与平台后台

| 能力 | 状态 | 后端接口 |
| --- | --- | --- |
| 租户概览、品牌、设置 | 可联调 | `/api/tenant-admin/overview`、`branding`、`settings` |
| 商户收款配置 | 可联调 | `/api/tenant-admin/payment-accounts` |
| 登录 provider 配置 | 可联调 | `/api/tenant-admin/auth-providers` |
| 密钥掩码/引用 | 迁移期 | API 有掩码，生产前要做 KMS/Vault 或 envelope encryption |
| 活动、Banner、FAQ、公告 | 可联调 | `/api/tenant-admin/banners`、`faqs`、`announcements` |
| 激活码批次/生成/列表 | 可联调 | `/api/tenant-admin/code-batches`、`activation-codes` |
| 成员/角色权限/审计 | 可联调 | `/api/tenant-admin/members`、`permissions`、`audit-logs` |
| 平台租户/套餐/订阅/账单/用量 | 可联调 | `/api/platform-admin/*` |
| 数据看板聚合接口 | 待补齐 | 表基础已有，缺完整 dashboard API |

## 销售、代理、CRM

| 能力 | 状态 | 说明 |
| --- | --- | --- |
| 邀请码/二维码记录 | 可联调 | `/api/referral/invite-code`、`qrcode` |
| 扫码/分享事件 | 可联调 | `/api/referral/track-event` |
| 首绑客资保护 | 可联调 | `/api/referral/bind` |
| 手工补绑 | 可联调 | 需要 `referral:write` |
| 销售统计/客户列表/团队 | 可联调 | `/api/referral/sales-*`、`team` |
| CRM 配置/队列 | 可联调 | `/api/crm/config`、`/api/crm/queue` |
| 真实 CRM webhook worker | 待补齐 | 钉钉/飞书/企微发送、签名、重试、死信 |
| 分佣结算 | 待补齐 | 缺佣金规则、结算单、审核、导出 |

## 内容导入与迁移

| 能力 | 状态 | 说明 |
| --- | --- | --- |
| PocketBase schema 分析 | 可联调 | `scripts/import-pocketbase` |
| 题目 JSON preview/import | 可联调 | 后端负责规范化、issue、幂等、审计 |
| 单词 JSON preview/import | 可联调 | 兼容旧模板 |
| 知识手册 JSON preview/import | 可联调 | 支持书籍/章节/小节/知识点归一化 |
| Excel/CSV 导入 | 待补齐 | 应复用 `content_import_jobs` 管线 |
| 分数线/视频批量导入 | 待补齐 | 应复用同一导入管线 |
| 大批量异步导入 | 待补齐 | 需要 `apps/worker` |

## 当前验证

最近已通过：

```bash
npm audit
npm run check:refactor
```

`check:refactor` 包含：

- API TypeScript 检查
- importer TypeScript 检查
- PocketBase 导入校验
- smoke seed
- API build
- API integration tests