目标
修复当前后端中阻碍 iOS 真实接口对接的安全与功能缺陷。在 H0 完成之前,不允许启动真实 iOS 接口联调。
背景
经 iOS 端对接可行性审计发现,当前 api-server 存在以下阻断性问题:
- Apple 登录 mock fallback:生产环境 APPLE_BUNDLE_ID 缺失时退回 mock,任意长度 ≥4 的字符串即可登录
/internal/*无认证暴露:7 个内部端点可直接访问文档原文、写入 chunks/candidates、劫持导入作业- 用户禁用后 JWT 仍有效:JwtAuthGuard 不检查用户状态
- Refresh Token 刷新不检查用户状态:禁用/删除用户仍可刷新 token
- 用户 JWT 与 Admin JWT 密钥混用:未彻底隔离
- iOS 核心接口 @Body() any:import/source/learning-session 缺少 DTO 校验
- CI/CD 硬编码生产数据库密码
Issue 清单
- H0-01 修复 Apple 登录 mock fallback
- H0-02 为 /internal/* 增加 InternalAuthGuard
- H0-03 JwtAuthGuard 增加用户状态检查
- H0-04 Refresh Token 刷新时检查用户状态
- H0-05 用户 JWT 和 Admin JWT 密钥彻底隔离
- H0-06 补齐 iOS 核心流程 DTO(import / source / learning-session)
- H0-07 修复后跑核心 CAPI E2E + 输出 iOS 对接文档
验收标准
- Apple 登录真实验证 identityToken,不再接受 mock
- /internal/* 全部受 InternalAuthGuard 保护
- 禁用/删除用户不能访问 /api/* 和刷新 token
- user token 与 admin token 完全隔离
- import/source/learning-session 有完整 DTO + ValidationPipe
- 核心 CAPI E2E 全部通过
- 输出 iOS 对接文档
禁止事项
- 禁止在 H0 未完成前启动真实 iOS 接口联调
- 禁止绕过安全修复直接给 iOS 端发接口
- CI/CD 密码必须迁移到 Secret 并轮换
审查结论:M-API-ADMIN-INFO 为 M-API-INFO 的管理面 API,不独立可做。当前 admin 基础设施齐全但核心数据表/聚合服务未建。
可先做(4): API-ADMIN-INFO-000/016/018/020
已有基础(2): API-ADMIN-INFO-005(partial)/018(partial)
阻塞于 api-info-schema(9): API-ADMIN-INFO-002/003/006/012/014/017 + 005/007 扩展
阻塞于 api-info-core(6): API-ADMIN-INFO-001/008/009/010/011/013
阻塞于 api-info-ops(2): API-ADMIN-INFO-004/015
阻塞于 api-info-core(1): API-ADMIN-INFO-019
执行顺序:先 M-API-INFO 建表→聚合→再本里程碑
主 API 接入 Rust Heavy Runtime,完成 AI 分析任务调度、Snapshot、模型 key 管理、Runtime 结果落库、用户侧查询、admin 诊断接口。本批不迁移 RAG。
M0:后端基础能力与架构规范闭环(P0)
目标:建立后端基础能力与架构规范闭环,支撑后续模块并行开发。
14 个 Issue:
M0-01 Common Architecture Foundation
M0-02 Event Bus & Reliability 基础版
M0-03 Config & Feature Flag 基础版
M0-04 Audit & Security 基础版
M0-05 Traffic Protection & Resilience 基础版
M0-06 Content Safety & Moderation 基础版
M0-07 Observability 基础版
M0-08 AI Gateway 基础版
M0-09 File Storage 基础版
M0-10 Task Queue & Worker 基础版
M0-11 Quota, Billing & Cost 基础版
M0-12 Secret & Vendor Asset 基础版
M0-13 Admin Auth & RBAC 基础版
M0-14 User & Account 基础身份能力
验收标准:按模块性质交付
禁止事项:不上Nacos、不上Tempo/Loki/Grafana、不上第三方审核API、不做全链路细粒度限流
目标:夯实 AI 调用与向量检索的运行时能力,为知识库主链路提供生产级支撑。
6 个 Issue:
M1-01 AI Gateway 深化(基础主备 fallback)
M1-02 Vector & Retrieval Module
M1-03 Task Queue 深化
M1-04 Content Safety 深化
M1-05 Observability 深化
M1-06 Quota/Cost 闭环
验收标准:AI 调用全部经过 AI Gateway 且成本全部记录;向量检索打通 embedding→检索→rerank→citation 全链路;Content Safety 覆盖用户输入和 AI 输出。
禁止事项:不做 hybrid search、不做 RAG 查询缓存、不做生产级熔断系统
M3:测验/自测模块
测验题库生成/答题/评分/错题本
知习 AI 对话不是普通聊天,而是学习对象绑定的上下文会话。每个会话必须明确知道它在问谁——整个知识库、某份资料、某个知识点、某个分类,还是多个来源。
核心规则:同一学习对象,继续上次会话;不同学习对象,打开或创建对应会话。
设计文档:见完整 ChatScope 规划(Scope 类型、入口规则、打开/新建决策、检索范围、切换规则、会话列表)。
M8:学习信息收集与基础分析闭环
审查结论:M-API-INFO 基本为全新学习信息系统建设。可复用:JWT Guard、LearningSession 基础表、DailyLearningActivity 基础表、ActivityController 部分接口、LearningRecord schema。
执行顺序:
第0批设计: API-INFO-000/001/008
第1批Schema: API-INFO-002/003/004/005/006/007
第2批上报: API-INFO-009/010/011/024
第3批聚合: API-INFO-012/013/014/015
第4批查询: API-INFO-016/017/018/019/020/021
第5批运维: API-INFO-022/023
第6批测试文档: API-INFO-025/026/027/028