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

后端当前能力盘点

更新时间：2026-06-29

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

状态分为：

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

基础工程

模块	状态	说明
Supabase/PostgreSQL schema	可联调	supabase/migrations 已包含多租户、题库、学习、订单、内容、CRM、平台账务等表
RLS/租户隔离	可联调	表层普遍有 tenant_id 和 RLS 策略；API 已支持 tk_ 迁移 session 与 Supabase Auth JWT 双入口，并覆盖跨租户/伪造身份集成测试；生产前继续补真实云端 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
Supabase Auth JWT	可联调	API 已用 Bearer JWT 验签并通过 auth.users.id -> platform_users.auth_user_id -> tenant_memberships 映射业务身份；支持 HS256 JWT secret 或 JWKS；测试覆盖学生、租户管理员、平台管理员、错租户、坏签名
微信小程序登录	可联调	/api/auth/oauth/wechat-miniapp 已接 code2Session、openid/unionid 身份、session 签发和登录审计
微信网页/QQ OAuth	待补齐	目前仍是 placeholder，需要 code 换 token、回调域名、账号合并和审计
平台管理员鉴权	可联调	已支持平台管理员 Supabase JWT；x-platform-admin-key 仅作本地/迁移期兼容且可通过配置禁用
租户角色权限	可联调	tenant_memberships.role + permissions + role_template_id，接口有权限点校验
自定义角色模板	可联调	tenant_role_templates + /api/tenant-admin/role-templates，支持权限、菜单、模块、字段、数据范围配置；前端 UI 继续补
班级/教师/学生范围权限	可联调	tenant_classes、tenant_class_members + /api/tenant-admin/classes、classes/members、students、teachers；教师默认只看自己负责班级，字段权限可脱敏学生手机号
学生运营备注和跟进	可联调	tenant_student_notes、tenant_student_followups + /api/tenant-admin/students/notes、students/followups；教师/班主任只能操作范围内学生，支持备注可见性、任务指派、完成状态和审计

学生端题库主链路

能力	状态	后端接口/模型
地区/科目/分类兼容查询	可联调	/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，后端从本人错题本安全组卷
学习排行榜	可联调	GET /api/learning/leaderboard；支持 questions、score、vocabulary、mock_exam 四类指标，支持 all、7d、30d 周期和租户/地区/班级范围，返回当前用户排名并拒绝跨租户 session
考试倒计时	可联调	GET /api/catalog/exam-dates、GET /api/profile/exam-countdowns；返回租户/地区匹配考试日期和 daysLeft
题目反馈/纠错	可联调	GET/POST /api/profile/feedbacks，题目必须属于当前租户；租户后台可处理状态流转
签到积分	可联调	POST /api/profile/check-in、GET /api/profile/score-events；积分流水幂等、事务加锁，重复签到不重复加分
学生勋章	可联调	GET /api/profile/badges；支持分类筛选、已解锁/未解锁展示，后端只返回当前租户当前用户的勋章状态

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

能力	状态	后端接口/模型
单词单元/单词列表	可联调	/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/*
分数线 JSON 导入	可联调	/api/tenant-content/imports/preview/scoreline、/api/tenant-content/imports/scoreline；支持字段、院校、专业、记录、动态字段值、逐行 issue、幂等和审计
题目视频/批量预加载/搜索	可联调	/api/questions/*/videos、/api/videos/search；付费视频列表不返回可播放 URL
视频会员播放次数	可联调	POST /api/videos/play 支持 SVIP/视频次数校验、签名播放、次数扣减、播放日志；深度防盗链和动态水印继续补
视频 JSON 导入和批量绑定	可联调	/api/tenant-content/imports/preview/videos、/api/tenant-content/imports/videos；支持视频元数据、资源引用、播放模式、题目绑定和题目视频标记

资料与对象存储

能力	状态	说明
内容资源台账	可联调	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
上传后对象校验	可联调	/api/tenant-content/assets/confirm-upload；托管对象必须 verified 后才能发布/下载
PDF/图片预览签名	可联调	/api/catalog/assets/preview、/api/tenant-content/assets/sign-preview；使用 inline 短期签名
托管资源 worker 复检	可联调	apps/worker --job assets 定期复检 pending/verified 对象元数据；异常资源会标记 failed 并从 active 退回 draft，写入审计和 security_flags
深度防盗链/水印/杀毒	待补齐	商用上线前继续补 CDN 防盗链、动态水印、安全扫描和对象生命周期策略

订单、会员、营销

能力	状态	说明
SVIP 套餐	可联调	/api/catalog/svip-plans
创建订单/订单列表/订单详情/状态轮询	可联调	/api/commerce/orders、orders/detail、orders/status；订单金额、优惠券抵扣、零元订单都以后端计算为准
手工支付确认	迁移期	/api/commerce/payments/manual-confirm 仅允许具备 tenant:payment:write 的租户后台成员调用，用于线下收款/本地测试
微信支付 JSAPI	可联调	/api/commerce/payments/create、notify/wechat_pay，已覆盖 API v3 签名、通知解密、幂等和权益开通
支付宝 WAP/H5	可联调	/api/commerce/payments/create、notify/alipay，已覆盖 RSA2 通知验签、幂等和权益开通
权益查询/校验	可联调	/api/commerce/entitlements
激活码预检查/兑换	可联调	/api/commerce/activation-codes/check、redeem；支持地区校验、自用码拒绝、已用码稳定 reasonCode
优惠券后台配置	可联调	/api/tenant-admin/coupons
优惠券前台领取/下单抵扣	可联调	/api/commerce/coupons/claim；支持同用户同券幂等领取、下单绑定、负数订单项、全额优惠自动开通权益
退款状态机和供应商确认	可联调	/api/commerce/refunds、/api/commerce/refunds/status、/api/commerce/refunds/notify/{provider}；支持退款申请、审核、调用微信/支付宝发起退款、query_provider_refund 查询确认、微信/支付宝退款通知、处理中、成功/失败/拒绝/取消、退款金额累计、部分退款、全额退款权益撤销、退款事件和审计
支付/退款补偿 worker	可联调	apps/worker --job commerce 查询微信/支付宝订单和处理中退款，补偿漏通知支付、补发权益、确认退款、全额退款撤销权益；npm run test:worker:commerce 覆盖幂等和密钥不泄露
完整资金流水对账	待补齐	后续补微信/支付宝账单下载、平台账单比对、差错处理、异常订单运营台

租户后台与平台后台

能力	状态	后端接口
租户概览、品牌、设置	可联调	/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/badges、/api/tenant-admin/badge-grants；支持后台维护、同 legacyId 幂等更新、手动发放、重复发放幂等、租户隔离和权限点 badges:read/write/grant
考试日期维护	可联调	/api/tenant-admin/exam-dates，支持地区维度维护和公开倒计时展示
题目反馈处理	可联调	/api/tenant-admin/feedbacks、feedbacks/status、feedbacks/events；支持状态流转、处理备注、审计事件和幂等奖励积分
激活码批次/生成/列表	可联调	/api/tenant-admin/code-batches、activation-codes
成员/角色权限/审计	可联调	/api/tenant-admin/members、permissions、role-templates、audit-logs
班级/学生/教师管理	可联调	/api/tenant-admin/classes、classes/members、students、teachers，支持班级范围权限和审计
学生批量运营	可联调	/api/tenant-admin/students/bulk-upsert、students/status、classes/members/bulk-assign、students/notes、students/followups；支持逐行结果、限量、防跨租户和教师范围校验
平台租户/套餐/订阅/账单/用量	可联调	/api/platform-admin/*
数据看板聚合接口	可联调	GET /api/tenant-admin/dashboard；支持 7d/30d/90d、地区筛选、学生/学习/内容/订单/激活码/反馈卡片、趋势、24h 活跃、题型分布、科目排行、地区统计、套餐销量和运营动态
平台公共题库授权	可联调	/api/platform-admin/question-banks、question-bank-grants；支持按 SaaS 套餐、指定租户或全部活跃租户披露平台公共题库
租户采纳公共题库	可联调	/api/tenant-content/public-question-banks、public-question-banks/adopt；租户只能看到自己订阅/授权范围内题库，采纳后生成租户自己的题库、入口、集合和题目快照，可直接进入练习

销售、代理、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	可联调	apps/worker 已支持 generic webhook、钉钉、飞书、企微群机器人消息体/签名、到期任务消费、失败退避重试、最终失败、discarded 和 crm_webhook_log
CRM 增强	待补齐	轮询/定向分配策略、富卡片模板、失败告警、死信运营后台和批量 CRM 推送
分佣结算基础闭环	可联调	/api/commission/settings、member-rate、summary、orders、settlements、settlements/generate、settlements/status；支持订单/激活码归因、批次/成员/默认比例优先级、北京时间账期、结算单生成、审核、打款状态、已打款锁定、销售/代理本人范围和租户隔离
分佣打款增强	待补齐	银行/微信/支付宝真实打款、结算导出、发票/凭证、财务复核和分佣看板

内容导入与迁移

能力	状态	说明
PocketBase schema 分析	可联调	scripts/import-pocketbase
题目 JSON preview/import	可联调	后端负责规范化、issue、幂等、审计
公共题库采纳快照	可联调	平台授权后，租户可采纳公共题库并复制已发布题目快照；已覆盖跨租户、重复采纳和采纳后组卷测试
单词 JSON preview/import	可联调	兼容旧模板
知识手册 JSON preview/import	可联调	支持书籍/章节/小节/知识点归一化
分数线 JSON preview/import	可联调	支持 fields/schools/majors/records 分桶或 items 列表，后端校验租户地区和院校/专业引用
视频 JSON preview/import	可联调	支持 videos/items，后端校验题目、科目、资源引用，导入后写入 question_videos
Excel/CSV 导入	待补齐	应复用 content_import_jobs 管线
大批量异步导入	待补齐	需要 apps/worker
公共题库版本同步	待补齐	当前采纳为快照复制；后续需 worker 做增量同步、冲突处理、版本升级通知和租户自改保护

当前验证

最近需通过：

npm audit
npm run check:refactor

check:refactor 包含：

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