gongxue-base/docs/refactor/backend-capability-status.md

后端当前能力盘点

更新时间：2026-06-28

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

状态分为：

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

基础工程

模块	状态	说明
Supabase/PostgreSQL schema	可联调	supabase/migrations 已包含多租户、题库、学习、订单、内容、CRM、平台账务等表
RLS/租户隔离	迁移期	表层普遍有 tenant_id 和 RLS 策略，API 已接入 session 优先身份上下文；生产前继续补 Supabase 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，用户态接口已优先解析 bearer session 并拒绝伪造 userId/tenantId
微信小程序登录	可联调	/api/auth/oauth/wechat-miniapp 已接 code2Session、openid/unionid 身份、session 签发和登录审计
微信网页/QQ OAuth	待补齐	目前仍是 placeholder，需要 code 换 token、回调域名、账号合并和审计
平台管理员鉴权	迁移期	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；后端强制校验免费额度、SVIP 范围和内容访问规则
答题记录	可联调	POST /api/learning/answers；题目必须属于本人有效 session 快照
错题本	可联调	/api/learning/wrong-questions
收藏夹	可联调	/api/learning/favorites/questions
免费用户题量限制	可联调	practice_daily_usage + practice_access_events；支持内容 accessRules、每日额度、session 截断、SVIP-only 拦截
模考交卷报告	可联调	POST /api/learning/practice-sessions/submit、GET /api/learning/practice-sessions/report、GET /api/learning/practice-reports；后端按 session 快照评分、分段统计、错题解析汇总，重复提交幂等
学习历史/统计/趋势	可联调	GET /api/learning/practice-sessions/history、GET /api/learning/stats、GET /api/learning/trend；可支撑个人中心、练习历史、正确率趋势和题型分布
错题复习计划	可联调	GET /api/learning/wrong-questions/review-plan + POST /api/learning/practice-sessions 的 mode=wrong_review，后端从本人错题本安全组卷

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

能力	状态	后端接口/模型
单词单元/单词列表	可联调	/api/catalog/vocabulary-units、vocabulary-words
单词进度/收藏/统计	可联调	/api/learning/vocabulary/*
单词复习算法/每日计划	可联调	GET /api/learning/vocabulary/review-plan、POST /api/learning/vocabulary/review；后端计算 nextReviewDate、连续正确、掌握状态和待复习计划
知识手册目录/内容	可联调	/api/catalog/handbook-*
知识手册 JSON 导入	可联调	/api/tenant-content/imports/*/handbook
分数线字段/院校/专业/记录/趋势	可联调	/api/scoreline/*
题目视频/批量预加载/搜索	可联调	/api/questions/*/videos、/api/videos/search；付费视频列表不返回可播放 URL
视频会员播放次数	可联调	POST /api/videos/play 支持 SVIP/视频次数校验、签名播放、次数扣减、播放日志；深度防盗链和动态水印继续补

资料与对象存储

能力	状态	说明
内容资源台账	可联调	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
手工支付确认	迁移期	可用于测试，不是生产支付
微信支付 JSAPI	可联调	/api/commerce/payments/create、notify/wechat_pay，已覆盖 API v3 签名、通知解密、幂等和权益开通
支付宝 WAP/H5	可联调	/api/commerce/payments/create、notify/alipay，已覆盖 RSA2 通知验签、幂等和权益开通
权益查询/校验	可联调	/api/commerce/entitlements
激活码兑换	可联调	事务开通权益
优惠券后台配置	可联调	/api/tenant-admin/coupons
优惠券前台兑换/下单抵扣	待补齐	后端还需接入下单计算
退款/补偿/对账	待补齐	需退款接口、支付补偿任务、对账、异常订单处理

租户后台与平台后台

能力	状态	后端接口
租户概览、品牌、设置	可联调	/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

当前验证

最近需通过：

npm audit
npm run check:refactor

check:refactor 包含：

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