提交 c00f8dec authored 作者: caifuming's avatar caifuming

@张钱炜 @新增数据库设计表,以及各模型任务功能

上级 99090008
version: "3.8"
services:
mysql:
image: mysql:8.0
container_name: studyweb-mysql
restart: always
environment:
MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-root123}
MYSQL_DATABASE: ${MYSQL_DATABASE:-studyweb}
MYSQL_USER: ${MYSQL_USER:-studyweb}
MYSQL_PASSWORD: ${MYSQL_PASSWORD:-studyweb123}
ports:
- "5688:3306"
volumes:
- mysql_data:/var/lib/mysql
- ./config/mysql/init:/docker-entrypoint-initdb.d
- ./config/mysql/conf.d:/etc/mysql/conf.d
command: --default-authentication-plugin=mysql_native_password
healthcheck:
test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
interval: 10s
timeout: 5s
retries: 5
redis:
image: redis:7
container_name: studyweb-redis
restart: always
ports:
- "16379:6379"
volumes:
- redis_data:/data
- ./config/redis/redis.conf:/usr/local/etc/redis/redis.conf
command: redis-server /usr/local/etc/redis/redis.conf
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10s
timeout: 5s
retries: 5
minio:
image: minio/minio:RELEASE.2024-01-16
container_name: studyweb-minio
restart: always
environment:
MINIO_ROOT_USER: ${MINIO_ROOT_USER:-minioadmin}
MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:-minioadmin123}
ports:
- "19000:9000"
- "19001:9001"
volumes:
- minio_data:/data
command: server /data --console-address ":9001"
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
interval: 10s
timeout: 5s
retries: 5
loki:
image: grafana/loki:3.2.1
container_name: studyweb-loki
restart: always
ports:
- "13100:3100"
volumes:
- loki_data:/loki
- ./config/loki/loki-config.yml:/etc/loki/local-config.yaml
command: -config.file=/etc/loki/local-config.yaml
promtail:
image: grafana/promtail:3.2.1
container_name: studyweb-promtail
restart: always
volumes:
- ./logs:/var/log/app:ro
- ./config/promtail/promtail-config.yml:/etc/promtail/config.yml:ro
- /var/run/docker.sock:/var/run/docker.sock:ro
command: -config.file=/etc/promtail/config.yml
depends_on:
- loki
volumes:
mysql_data:
redis_data:
minio_data:
loki_data:
# MVP 技术架构设计
> 本文档基于《架构大纲.md》《MVP任务拆解.md》《需求文档》《PRD 文档》编制,聚焦 **MVP(P0)** 所需的最小可用架构。目标是:技术部能稳定跑通闭环,且为迭代二 ~ 迭代四留足扩展点。
>
> **重要决策**:除 AI 服务独立外,业务域统一收敛为 **业务单体**;模块化组织、不拆微服务。
---
## 目录
- [一、设计原则](#一设计原则)
- [二、技术选型](#二技术选型)
- [三、系统架构](#三系统架构)
- [四、共享 lib 与仓库策略](#四共享-lib-与仓库策略)
- [五、项目目录结构](#五项目目录结构)
- [六、API 契约与模块通信](#六api-契约与模块通信)
- [七、数据架构](#七数据架构)
- [八、核心流程设计](#八核心流程设计)
- [九、状态机设计](#九状态机设计)
- [十、AI 服务架构(独立服务)](#十ai-服务架构独立服务)
- [十一、业务单体模块划分](#十一业务单体模块划分)
- [十二、API 网关设计](#十二api-网关设计)
- [十三、容器沙箱架构](#十三容器沙箱架构)
- [十四、部署架构](#十四部署架构)
- [十五、安全与权限设计](#十五安全与权限设计)
- [十六、非功能性设计](#十六非功能性设计)
- [十七、监控、日志与容灾](#十七监控日志与容灾)
- [十八、CI/CD 与发布](#十八cicd-与发布)
- [十九、架构决策记录(ADR)](#十九架构决策记录adr)
- [二十、风险与应对](#二十风险与应对)
- [二十一、架构边界与后续扩展](#二十一架构边界与后续扩展)
- [二十二、与架构大纲的对齐](#二十二与架构大纲的对齐)
---
## 一、设计原则
| 原则 | 说明 |
| ------- | ----------------------------------- |
| 最小可行架构 | 先保证闭环可用,再考虑抽象扩展;MVP 只拆到最必要粒度 |
| 模块一优先 | MVP 只上线模块一,模块二预留接口但不实现 |
| AI 独立服务 | AI 能力单独成服务,便于模型切换、扩容和迭代 |
| 业务单体化 | 除 AI 服务外,业务域采用模块化单体,避免 MVP 微服务复杂度 |
| 状态机驱动 | 实训流程不写死在页面,由后端状态机控制门控与流转 |
| 安全隔离 | 容器沙箱、认证授权、数据隔离三者同时落地 |
| 数据归属收敛 | AI 产物数据由业务单体落库,AI 服务只做计算,避免跨服务 join |
| 面向演进设计 | 单体内部按模块隔离,预留后续可拆服务的物理边界 |
---
## 二、技术选型
| 层 | 选型 | 选型理由 |
| ------ | ------------------------------------------------------- | -------------------------- |
| 前端 | React + TypeScript + Vite + pnpm workspaces + Turborepo | monorepo 统一管理四端;增量构建快 |
| API 网关 | Nginx + OpenResty + Lua 鉴权脚本 | MVP 不上 Kong/APISIX;后续可平滑迁移 |
| 业务单体 | Java 17 / Spring Boot 3.x(模块化单体) | 生态成熟;可按模块拆分包结构 |
| AI 服务 | **Python 3.11 / FastAPI**(已定) | AI 生态完善;与 Java 业务解耦 |
| 业务数据库 | MySQL 8.x | 关系型数据为主;事务/索引成熟 |
| 缓存 | Redis 6.x | 会话、验证码、AI 缓存、限流 |
| 文件存储 | MinIO | S3 兼容;容器化部署;签名 URL |
| 向量数据库 | **Milvus Standalone 单节点**(etcd + MinIO + Milvus) | MVP 数据量小;后续可升级集群 |
| AI 抽象层 | LangChain + VLLM部署模型 | 多模型统一接入;Prompt 模板化 |
| 状态机 | **MVP 自研 + 9.x 引入 Alibaba Cola StateMachine** | MVP 状态简单,自研可控;后续引入成熟方案 |
| 容器沙箱 | Docker Engine + code-server + 自研沙箱调度器 | MVP 不上 K8s;用 Docker SDK 调度 |
| 消息/事件 | 本地事件表 + 定时补偿 | MVP 不引入 MQ |
| 配置中心 | **MVP 环境变量 + ConfigMap;v1.5 引入 Nacos** | 先解决有无;后续平滑迁移 |
| 监控 | Prometheus + Grafana + AlertManager | 指标统一;告警分级 |
| 日志 | Loki + Promtail(容器 stdout 采集) | MVP 不上 ELK,统一通过 Loki 查询 |
| 链路追踪 | SkyWalking(仅业务单体内部) | 多模块串联,定位瓶颈 |
| CI/CD | GitHub Actions + Docker Registry(Harbor) | 与 Git 流程契合 |
---
## 三、系统架构
### 3.1 分层视图
```
┌───────────────────────────────────────────────┐
│ 前端层 │
│ 学员端 / 导师端 / 主管端 / 管理端 │
└───────────────────────┬───────────────────────┘
▼
┌───────────────────────────────────────────────┐
│ API 网关 │
│ Nginx + OpenResty;统一认证、限流、灰度 │
└──────────┬──────────────────────┬─────────────┘
▼ ▼
┌────────────────────┐ ┌────────────────────┐
│ 业务单体 │ │ AI 服务 │
│ backend-app │ │ ai-service │
│ (Spring Boot) │ │ (FastAPI) │
│ ├ user │ │ ├ LLM 工厂 │
│ ├ project │ │ ├ Embedding │
│ ├ training │ │ ├ RAG 检索 │
│ ├ defense │ │ └ Prompt 管理 │
│ ├ audit │ └─────────┬─────────┘
│ └ notify │ │
└──────────┬──────────┘ │
│ HTTP │
▼ ▼
┌───────────────────────────────────────────────┐
│ 数据层 │
│ MySQL / Redis / MinIO / Milvus / Loki │
└───────────────────────────────────────────────┘
```
### 3.2 MVP 服务清单
| 服务 | 形态 | 职责 | 数量 |
| ----------- | -------------- | ----------------- | ------ |
| api-gateway | Nginx + Lua | 统一入口、认证、限流、灰度 | 2+ 实例 |
| backend-app | Spring Boot 单体 | 用户/项目/实训/答辩/审核/通知 | 2~4 实例 |
| ai-service | FastAPI 服务 | LLM/Embedding/RAG | 1~2 实例 |
| 沙箱调度器 | backend-app 内嵌 | Docker SDK 创建学员容器 | 与业务同进程 |
### 3.3 服务依赖规则
| 维度 | 规则 |
| ----- | --------------------------------------- |
| 主依赖方向 | backend-app → ai-service(同步 HTTP);反向不依赖 |
| 单向调用 | ai-service 不读写 backend-app 数据库 |
| 数据归属 | 业务数据全部落 backend-app,AI 计算结果回传后由业务落库 |
| 异步事件 | 内部模块通过`flow_events` 表 + 定时补偿,避免 MQ |
| 降级保护 | ai-service 故障 → 业务侧切人工推荐(标签 + 随机) |
---
## 四、共享 lib 与仓库策略
为了避免代码重复与版本不一致,统一通过共享 lib 提供跨服务能力:
| lib | 职责 | 接入方 |
| ----------------- | -------------------- | ------------ |
| shared-common | 统一异常、响应包装、分页、工具类、枚举 | backend-app |
| shared-auth | JWT、RBAC 注解、token 工具 | backend-app |
| shared-storage | MinIO 客户端、签名 URL 工具 | backend-app |
| shared-api-client | TS 封装 axios、错误码、拦截器 | frontend 4 端 |
| shared-ui-kit | 公共组件(表格、表单、上传) | frontend 4 端 |
| shared-prompt | Prompt 模板与校验 Schema | ai-service |
| shared-event | 事件表统一读写 API(兼容) | backend-app |
**版本策略**:lib 与 apps 分仓,lib 用 **SemVer**;`backend-app` 与 `ai-service` 通过 Maven / pip 显式依赖 lib,避免循环。
---
## 五、项目目录结构
### 5.1 总体仓库结构
```
internship-fusion-platform/
├── README.md
├── docs/
│ ├── PRD/
│ ├── architecture/
│ │ └── 技术架构设计.md
│ ├── mvp/
│ │ └── MVP任务拆解.md
│ └── api/
│ └── openapi.yaml
├── backend/
│ ├── apps/
│ │ ├── backend-app/ # 业务单体
│ │ ├── ai-service/ # AI 服务
│ │ └── sandbox-scheduler/ # 沙箱调度器(MVP 内嵌于 backend-app)
│ └── libs/
│ ├── shared-common/
│ ├── shared-auth/
│ └── shared-storage/
├── frontend/
│ ├── apps/
│ │ ├── student/
│ │ ├── mentor/
│ │ ├── supervisor/
│ │ └── admin/
│ └── libs/
│ ├── shared-ui-kit/
│ └── shared-api-client/
├── infrastructure/
│ ├── docker/
│ ├── prometheus/
│ ├── grafana/
│ ├── alertmanager/
│ ├── loki/
│ ├── argocd/ # 可选,v1.0 引入
│ └── scripts/
├── .github/
│ └── workflows/
│ ├── backend-ci.yml
│ └── frontend-ci.yml
├── .gitignore
├── docker-compose.dev.yml
└── docker-compose.prod.yml
```
### 5.2 前端 monorepo 结构
```
frontend/
├── package.json # workspaces 配置
├── pnpm-workspace.yaml
├── turbo.json # Turborepo 任务编排
├── apps/
│ ├── student/
│ │ ├── src/
│ │ │ ├── pages/
│ │ │ │ ├── recommend/
│ │ │ │ ├── preview/
│ │ │ │ ├── practice/
│ │ │ │ ├── report/
│ │ │ │ └── defense/
│ │ │ ├── components/
│ │ │ ├── hooks/
│ │ │ ├── services/
│ │ │ └── App.tsx
│ │ └── package.json
│ ├── mentor/ src/pages/{review,students,config}/
│ ├── supervisor/ src/pages/{audit,entry,dashboard}/
│ └── admin/ src/pages/{users,projects,rbac,ai-config}/
└── libs/
├── shared-ui-kit/
│ ├── src/components/{Table,Form,Upload,Modal}/
│ └── package.json
└── shared-api-client/
├── src/{request,interceptors,errorCode}/
└── package.json
```
### 5.3 业务单体结构
```
backend/apps/backend-app/
├── pom.xml
├── src/main/java/com/platform/backend/
│ ├── BackendApplication.java
│ ├── config/
│ ├── module/
│ │ ├── user/{controller,service,domain,infrastructure}
│ │ ├── project/
│ │ ├── training/{controller,service,state,event,domain,infrastructure}
│ │ ├── defense/
│ │ ├── audit/
│ │ ├── notify/
│ │ └── shared/{auth,exception,log,util}
│ └── infrastructure/
│ ├── persistence/ # MyBatis/Flyway/分页
│ ├── cache/ # Redis 封装
│ ├── storage/ # MinIO 封装
│ ├── sandbox/ # 沙箱调度(Docker SDK)
│ └── event/ # 本地事件表
├── src/main/resources/
│ ├── application.yml # 多 profile
│ ├── logback-spring.xml # 输出到 stdout(Loki 采集)
│ └── db/
│ ├── migration/ # Flyway 版本脚本
│ └── seed/ # 种子数据
└── Dockerfile
```
### 5.4 AI 服务结构
```
backend/apps/ai-service/
├── pyproject.toml
├── src/ai/
│ ├── app.py # FastAPI 入口
│ ├── config.py
│ ├── api/{recommend,knowledge,health,internal}.py
│ ├── services/
│ │ ├── llm/{base.py,openai.py,domestic.py,factory.py}
│ │ ├── embedding/{index.py,encoder.py}
│ │ ├── rag/{retriever.py,milvus_client.py}
│ │ ├── recommend/{ranker.py,fallback.py}
│ │ └── knowledge/{extractor.py,validator.py}
│ ├── prompt/
│ │ ├── templates/ # *.yaml
│ │ └── loader.py
│ └── clients/
│ └── github.py # 项目镜像
├── tests/
└── Dockerfile
```
### 5.5 基础设施结构
```
infrastructure/
├── docker/
│ ├── mysql/{Dockerfile,conf,init}
│ ├── redis/
│ ├── minio/
│ ├── milvus/{standalone,docker-compose.yml}
│ ├── code-server/
│ ├── prometheus/prometheus.yml
│ ├── grafana/{datasources,dashboards}
│ ├── loki/
│ └── promtail/
├── scripts/
│ ├── init-db.sh
│ ├── backup.sh # MySQL+MinIO+Milvus 元数据
│ ├── restore.sh
│ ├── deploy.sh
│ └── healthcheck.sh
└── docker-compose.prod.yml
```
---
## 六、API 契约与模块通信
| 通信场景 | 方式 | 约束 |
| ------------------------ | ---------------------------- | ------------------------------------- |
| 前端 ↔ backend-app | HTTP/JSON(OpenAPI 3.0) | 单一网关入口;版本前缀`/api/v1` |
| backend-app ↔ ai-service | HTTP/JSON,内部调用走 service name | 失败可降级;超时 ≤ 8s |
| backend-app 内部模块 | 同步 Java 方法调用 + 接口层 | 禁止跨模块访问`infrastructure` |
| 跨模块异步 | 写`flow_events`,定时任务补偿 | 不引入 MQ |
| 数据 | 单库单 schema + 表前缀 | `users / projects / training_* / ...` |
> 接口契约统一维护在 `docs/api/openapi.yaml`,前后端均按此生成。
---
## 七、数据架构
### 7.1 核心模型关系
```
User / Role / Permission
│
└── TrainingTask
├── PreviewRecord
├── PracticeArtifact
├── PracticeReport
└── DefenseRecord
└── AuditRecord
└── EntryRecord
Project / Tag / DifficultyConfig
├── RecommendationLog
├── KnowledgePoint
└── DifficultyCalibrationLog
AI(产物归属)
├── AiCallLog
├── PromptTemplate(ai-service 内部维护)
└── VectorIndex(Milvus,不进 MySQL)
```
### 7.2 MVP 核心表(统一归属 backend-app)
| 表 | 前缀 | 说明 |
| --------------------------- | --------- | ------------------ |
| users | user_ | 用户 |
| roles / permissions | user_ | RBAC |
| projects | project_ | 种子项目 |
| project_tags | project_ | 标签 |
| difficulty_configs | project_ | 打分卡 |
| difficulty_calibration_logs | project_ | 校准日志 |
| training_tasks | training_ | 实训主表 |
| preview_records | training_ | 预习记录 |
| practice_artifacts | training_ | 实操产物 |
| practice_reports | training_ | 实操报告 |
| knowledge_points | training_ | **由 AI 生成,落库到业务侧** |
| recommendation_logs | training_ | **同上** |
| ai_call_logs | ai_ | AI 调用日志 |
| prompt_templates | ai_ | Prompt 模板元数据 |
| defense_records | training_ | 答辩记录 |
| audit_records | audit_ | 主管审核 |
| entry_records | audit_ | 入项记录 |
| capability_profiles | audit_ | 成长档案 |
| notifications | notify_ | 站内信 |
| flow_events | system_ | 状态流转日志 |
> **约定**:所有业务表都包含 `tenant_id`(多租户预留),即便 MVP 单租户也要落地,便于未来扩展。
### 7.3 多租户预留
- 表统一带 `tenant_id`,单租户时固定为 `default`
- MyBatis 拦截器自动注入 WHERE 条件
- Redis Key 前缀加 `tenant:{id}:`
- 沙箱 / 存储桶也按租户划分
---
## 八、核心流程设计
### 8.1 实训闭环状态机
```
[预习] → [实操] → [答辩] → [主管审核] → [入项]
↑ │ │
└─────────┘ │
↓
[驳回重训]
```
- 状态机由 `backend-app` 维护(详见第九章)
- 每个状态转换前校验前置条件
- 驳回时写回实操,触发 `notify_module`
### 8.2 AI 推荐流程
```
seed_projects
│
▼
backend-app(project-module)
│
▼
ai-service
├── Embedding 编码
├── Milvus 向量检索 TopK
├── LLM 重排序 + 理由生成
└── 返回 Top N + 匹配度 + 理由
│
▼
backend-app 写 training_recommendation_logs
```
#### 推荐降级路径
- AI 不可用 → 业务侧走 `fallback`:
1. 按学员已选标签匹配种子项目
2. 再随机补足 N 个
3. 标记本次为 `fallback` 来源,运维可观测
### 8.3 知识点提取流程
```
project_material
│
▼
backend-app 发起 → ai-service
├── 文本预处理
├── LLM 输出 JSON Schema
└── 返回:知识点 + 依赖 + 预习材料 + 小测
│
▼
backend-app 写 training_knowledge_points / training_preview_records
```
### 8.4 容器沙箱流程
```
学员进入实操
│
▼
backend-app (sandbox 包)
├── 校验预习完成
├── 调用 Docker SDK 创建容器(cgroup + 网络隔离)
├── 返回 code-server URL
└── 启动日志采集(promtail)
│
▼
学员操作 / 提交产物
├── 上传 MinIO(按 tenant 桶)
├── 写 training_practice_artifacts
└── 更新 training_tasks.status
```
### 8.5 答辩(MVP 异步评审)
- MVP 为 **异步答辩**:学员提交材料 → 导师评分 + 评语
- 评审通过 → 进入主管审核;否则驳回重训
- 实时答辩(音视频)放到迭代二
---
## 九、状态机设计
### 9.1 形态选择
| 阶段 | 方案 | 复杂度 |
| ---- | ---------------------------------- | --- |
| MVP | 自研状态机(基于枚举 + Guard + Transition 表) | 低 |
| v1.5 | 替换为 Alibaba Cola StateMachine | 中 |
| v2.0 | 配置化状态 + 可视化编辑器 | 高 |
### 9.2 引擎结构
```
training.statemachine/
├── States.java # 枚举所有状态
├── Events.java # 触发事件
├── Guards.java # 前置校验
├── Transitions.java # 转换表(配置化)
└── FlowEngine.java # 触发入口
```
- 状态定义在 `States.java`,转移规则在 `Transitions.java`
- 每次转移落地 `system_flow_events`
- 异常转移通过 Guard 拦截,记录原因
### 9.3 GitHub 限流量化
| 场景 | 估算 | 结论 |
| ------ | --------------------------------------- | --------------------------------- |
| 500 学员 | 同时打开推荐页 ≈ 50 req/s(峰值) | 远超 GitHub Search 30 req/min/token |
| 应对 | Token 池(10 个)+ 镜像离线索引 + Redis 缓存 Top 50 | 7 天有效期 |
> 量化结果:**镜像为主,GitHub 只做兜底刷新**;调用频率控制在 1 次 / 项目 / 天。
---
## 十、AI 服务架构(独立服务)
### 10.1 AI 服务边界
- **能力域**:LLM 调用、Embedding、RAG、推荐重排序、知识点提取
- **不做**:业务数据落库(仅返回结果,由业务落库)、用户认证(仅 internal token)
- **被谁调用**:仅 backend-app(通过 service name)
### 10.2 MVP 上线两项 AI 能力
| 能力 | 实现 | 说明 |
| ----- | --------------------------- | ------------------- |
| 项目推荐 | Embedding + Milvus + LLM 重排 | 输出 Top N + 理由 |
| 知识点提取 | LLM JSON Schema | 输出知识点依赖 + 预习材料 + 小测 |
### 10.3 AI 调用层设计
```
ai-service
├── models/factory.py # 多模型工厂
├── llm/{openai,wenxin,tongyi}.py
├── timeout/retry/fallback
├── token-pool/limiter # Token 池 + 限流
└── audit/call_log.py # 调用日志
```
- 失败 → 返回降级结果,HTTP 200 + `success=false` 让业务判定
- 失败计数超阈值 → 自动标记 `ai-service unhealthy` → 网关 503
### 10.4 Prompt 管理(MVP 最小版本)
- 文件:`src/ai/prompt/templates/*.yaml`
- 校验:JSON Schema(`shared-prompt` lib)
- 版本:随 ai-service 仓库 Git 版本号
- 不上 Prompt 后台;迭代二再做
```
prompt/templates/
├── recommend_v1.yaml
├── knowledge_extract_v1.yaml
└── knowledge_quiz_v1.yaml
```
---
## 十一、业务单体模块划分
### 11.1 模块职责
| 模块 | 职责 | 关键能力 |
| --------------- | ----------- | ------------- |
| user-module | 用户、角色、权限 | 登录、JWT、RBAC |
| project-module | 项目库、标签、难度 | CRUD、打分卡配置 |
| training-module | 实训状态机、门控、流转 | 状态机、推荐调用、产物收集 |
| defense-module | 答辩申请、评审 | 异步评审、评分 |
| audit-module | 主管审核、入项登记 | 审核、入项、成长档案 |
| notify-module | 站内信 | 通知持久化、查询 |
| shared | 公共能力 | 认证、异常、日志、工具 |
### 11.2 模块间调用规则
| 规则 | 说明 |
| ---------------------- | -------------------------- |
| 禁止跨模块访问 infrastructure | 必须走 service 接口层 |
| 禁止循环依赖 | 出现时由架构师裁决 |
| 单库单 schema | 模块前缀(user_/project_/...)区分 |
| 跨模块事务 | 本地事务 +`flow_events` 补偿 |
---
## 十二、API 网关设计
### 12.1 职责边界
| 职责 | 说明 |
| ---- | ----------------- |
| 统一入口 | 隐藏拓扑;唯一域名 |
| 路由转发 | 按路径 / Header / 版本 |
| 统一认证 | JWT 校验,注入 userId |
| 限流熔断 | IP / 用户 / 接口三维度 |
| CORS | 白名单 |
| 请求日志 | traceId 串联 |
| 灰度发布 | Header / 比例分流 |
> 网关**不做**:业务编排、授权判断(授权在 backend-app)、配置中心。
### 12.2 谁来负责
| 角色 | 事项 |
| --- | ------------------------- |
| 运维 | Nginx/OpenResty 部署、证书、DNS |
| 后端 | 鉴权脚本、限流规则、CORS 白名单 |
| 安全 | 防爬、防注入规则 |
| 架构师 | 路由策略、灰度策略、演进规划 |
> MVP:后端主导 + 运维配合;v1.5 上 Kong/APISIX。
### 12.3 路由示例
```
location /api/v1/auth/ { proxy_pass http://backend-app; }
location /api/v1/training/ { proxy_pass http://backend-app; }
location /api/v1/ai/ { proxy_pass http://ai-service; proxy_read_timeout 30s; }
```
### 12.4 限流策略
| 维度 | 默认规则 | 可调 |
| ----- | --------- | --- |
| IP | 100 req/s | 是 |
| 用户 | 20 req/s | 是 |
| AI 接口 | 5 req/s | 是 |
### 12.5 演进路径
| 阶段 | 方案 |
| ---- | ----------------------- |
| MVP | Nginx + OpenResty + Lua |
| v1.5 | Kong / APISIX |
| v2.0 | 灰度 + 全链路 |
| v3.0 | 服务网格(Istio) |
---
## 十三、容器沙箱架构
### 13.1 整体结构
```
Docker Host
├── 学员容器(每学员每项目一容器)
│ ├── code-server
│ ├── project code
│ └── toolchain
└── 沙箱调度器(嵌入 backend-app,Docker SDK 调用)
```
### 13.2 安全隔离
| 维度 | 措施 |
| ---- | ---------------------- |
| 资源 | cgroup CPU/Mem/Disk 限额 |
| 网络 | 仅 80/443 出站,禁止内网 |
| 文件系统 | 系统盘只读 + 工作目录可写 |
| 运行时长 | 8h 自动销毁 |
| 审计 | 关键命令记录 |
| 危险命令 | 拦截 rm/dd/mkfs 等 |
### 13.3 调度接口主体
- 主体:backend-app 内嵌 `sandbox` 包
- 实现:Docker SDK(直接调 Docker Engine API)
- 后续:v1.5 可替换为 K8s,**接口不变**
### 13.4 生命周期
```
创建 → 分配学员 → 运行 → 日志采集
→ 提交产物 → 销毁/快照
→ 一键重置 → 重建
```
---
## 十四、部署架构
### 14.1 MVP 部署拓扑
```
┌─────────────┐
│ DNS/SLB │
└──────┬──────┘
▼
┌─────────────┐
│ api-gateway │
│ Nginx+Lua │
└──────┬──────┘
┌──────────────┴──────────────┐
▼ ▼
┌───────────────┐ ┌───────────────┐
│ backend-app │ │ ai-service │
│ (2~4 实例) │ │ (1~2 实例) │
└──────┬────────┘ └──────┬────────┘
▼ ▼
┌───────────────────────────────────────────┐
│ MySQL / Redis / MinIO / Milvus / Loki │
└───────────────────────────────────────────┘
▼
┌────────────────┐
│ Docker Host │
│ 学员容器集群 │
└────────────────┘
```
### 14.2 环境分层
| 环境 | 用途 | 部署 |
| ----- | ---- | ---------------------- |
| dev | 开发自测 | docker-compose.dev.yml |
| test | 联调测试 | 多服务,数据隔离 |
| pilot | 试点 | 内网,稳定优先 |
### 14.3 备份策略
| 项 | 策略 | 周期 |
| ------ | --------------------- | ------- |
| MySQL | 全量每日 + binlog 实时 | 保留 14 天 |
| MinIO | 快照到备机 | 每日 |
| Milvus | 元数据导出 + collection 备份 | 每日 |
| Redis | AOF + RDB | RDB 每日 |
| 配置 | Git 仓库即版本 | - |
---
## 十五、安全与权限设计
### 15.1 认证
- JWT(access 2h + refresh 7d)
- API Gateway 统一校验
- 关键操作二次校验(短信 / 验证码)
### 15.2 授权(三层 RBAC)
| 层 | 实现 |
| --- | ----------------------- |
| 菜单 | 前端路由守卫 |
| 按钮 | 按钮指令(基于角色与资源) |
| 接口 | 后端`@PreAuthorize` + 拦截器 |
角色:学员 / 导师 / 主管 / 管理员,越权 403。
### 15.3 数据安全
| 类型 | 策略 |
| ---- | -------------------------- |
| 密码 | bcrypt / Argon2id |
| 敏感字段 | AES-256 |
| 传输 | HTTPS / TLS 1.3 |
| 文件 | MinIO 私有 + 签名 URL(30 min) |
| 审计 | 所有写操作记录`audit_log` |
| 密钥 | MVP 环境变量 + 文件加密;v1.5 Vault |
### 15.4 多租户预留
- 所有业务表带 `tenant_id`
- 查询拦截器自动注入
- Redis Key 与 MinIO bucket 隔离
---
## 十六、非功能性设计
### 16.1 性能目标
| 指标 | 目标 |
| ------------- | ------- |
| 接口 P99(不含 AI) | < 500ms |
| AI 调用 P95 | < 5s |
| 页面首屏 | < 2s |
| 并发用户 | ≥ 500 |
### 16.2 可用性
| 指标 | 目标 |
| --- | ------------- |
| SLA | ≥ 99.5%(工作时段) |
| RTO | < 30 分钟 |
| RPO | < 1 小时 |
### 16.3 扩展预留
- 模块二推荐源配置化
- AI 模型可切换
- Milvus Standalone → 集群
- 业务单体后续可按模块拆分为微服务
- 多租户可在 v2.0 直接启用
---
## 十七、监控、日志与容灾
### 17.1 监控
| 维度 | 指标 | SLO 阈值 |
| --- | -------------- | -------------- |
| API | QPS / RT / 错误率 | P99 > 1s 告警 |
| AI | 成功率 / 时延 | 失败率 > 5% 告警 |
| 容器 | 可用容器数 / 排队 | 容器可用率 < 90% 告警 |
| 数据库 | 连接数 / 慢 SQL | 连接 > 80% 告警 |
告警分级:P0 电话 / P1 钉钉 / P2 群机器人。
### 17.2 日志
- 应用输出 stdout(JSON)
- Promtail 采集 → Loki → Grafana
- 关键操作同步落 `audit_log`(数据库)
- traceId 贯穿:网关 → business → AI
### 17.3 容灾
| 场景 | 方案 |
| ----- | ------------------ |
| 数据库 | 主从 + ProxySQL 自动切换 |
| AI 故障 | 降级人工推荐 |
| 单实例 | 重启 + 熔断 |
| 文件 | MinIO 多副本 |
| 容器主机 | 主备切换(v1.0 上) |
---
## 十八、CI/CD 与发布
### 18.1 流水线
```
PR → CI(单元测试 + lint + 构建)
└─→ 镜像构建(多阶段 Dockerfile)
└─→ 推送 Harbor
└─→ 测试环境自动部署
└─→ 手动确认 → 生产灰度
```
### 18.2 镜像策略
- 后端:`platform/backend-app:{git-sha}`
- AI:`platform/ai-service:{git-sha}`
- 基础镜像统一由 `infrastructure/docker` 维护
### 18.3 版本管理
- 后端:SemVer(v0.1.0 起)
- 前端:发版即 tag
- Prompt:跟随 ai-service 版本
---
## 十九、架构决策记录(ADR)
### ADR-001 AI 独立服务,业务单体化
- **决策**:AI 独立;业务合并为单体
- **原因**:MVP 数据量不大;微服务治理成本高;AI 需要独立扩缩容
- **替代**:全微服务 / 单 AI 模块嵌入
- **影响**:所有 AI 能力走 HTTP;团队分两条业务线
### ADR-002 沙箱调度内嵌 backend-app
- **决策**:MVP 沙箱调度器内嵌 backend-app
- **原因**:MVP 仅本机;调度逻辑简单
- **替代**:独立调度服务
- **影响**:后续切 K8s 时接口保持兼容
### ADR-003 Prompt 走代码仓库,不上后台
- **决策**:MVP Prompt 文件随仓库 Git 管理
- **原因**:MVP 体量小,回滚随版本
- **替代**:Prompt 后台
- **影响**:迭代二再加
### ADR-004 配置 MVP 用环境变量,v1.5 引入 Nacos
- **决策**:MVP 用环境变量 + ConfigMap
- **原因**:MVP 配置项 < 50 条
- **影响**:后续迁移需改 12-factor
### ADR-005 日志走 Loki,不用 ELK
- **决策**:MVP 引入 Loki + Promtail
- **原因**:运维成本低;Grafana 复用
- **影响**:全文检索能力弱;按需迁移
### ADR-006 状态机 MVP 自研
- **决策**:MVP 自研;v1.5 引入 Cola StateMachine
- **影响**:状态机接口先行,避免后期重构
---
## 二十、风险与应对
| 风险 | 影响 | 应对 |
| --------- | ------ | --------------------- |
| GitHub 限流 | 推荐不可用 | Token 池 + 镜像 + 缓存 |
| AI 幻觉 | 知识点质量差 | JSON Schema + 人工复核 |
| 容器逃逸 | 安全风险 | 网络隔离 + 审计 + 命令拦截 |
| 状态机复杂度 | 维护困难 | 接口先行 + 可视化编辑器 |
| LLM 故障 | AI 不可用 | 多模型 + 人工降级 |
| 单体膨胀 | 构建慢 | 模块化隔离 + 包级边界 |
| 密钥泄漏 | 整体失陷 | MVP 文件加密 + v1.5 Vault |
| 日志缺失 | 排障困难 | Loki + traceId |
---
## 二十一、架构边界与后续扩展
| 扩展点 | 说明 |
| ------ | ----------------------------- |
| 业务单体拆分 | 后续按 user/training/audit 拆为微服务 |
| 模块二接入 | 推荐源配置化、标注部实操改造 |
| AI 扩展 | 历史缺陷、项目分类、进阶匹配 |
| 商业化 | 多租户、联合办学、SaaS 计费 |
| 运营 | Prompt 后台、A/B 测试、指标看板 |
| 服务网格 | v3.0 评估 Istio |
---
## 二十二、与架构大纲的对齐
| 架构大纲章节 | 本文档 | MVP 处理 |
| --------- | ------ | ----------------------- |
| 一、系统分层 | 三 | 按 MVP 简化版实现(业务单体 + AI) |
| 二、核心模块设计 | 八 / 十一 | 模块一完整,模块二预留 |
| 三、微服务拆分 | 三 / 十二 | AI 独立,业务单体化 |
| 四、数据架构 | 七 | 单库多前缀 + 多租户预留 |
| 五、AI 能力中心 | 十 | AI 服务独立实现两项能力 |
| 六、关键接口设计 | 六 / 七 | OpenAPI 3.0 维护 |
| 七、安全与权限 | 十五 | 三层 RBAC + 多租户预留 |
| 八、非功能性 | 十六 | 性能目标对齐 |
| 九、监控告警与容灾 | 十七 | Prometheus + Loki + SLO |
| 十、部署架构 | 十四 | Docker + Nginx 单集群 |
| 十一、迭代规划 | 二十一 | MVP 对应技术底座 + 模块一 |
---
## 二十三、人周拆分
> 完整 W1–W8 按人拆分见同目录《MVP人周拆分.md》。摘要:
>
> - **余洁**:前后端总负责(W1–W8,含沙箱/网关/状态机/四端页面/测试/试点支持)
> - **蔡馥名(主导)+ 李佳洋(协作)**:AI 部分(W1–W8,含 AI 调用层/推荐/知识点/Prompt/降级/AI 监控)
> - 关键路径:`W1 后端 → W2 项目库 → W3 状态机+AI → W4 沙箱 → W5 闭环+用户端 → W6 联调 → W7 试点 → W8 复盘`
---
# 项目目录创建以及脚手架搭建
> 本文档记录实习生训练平台的项目目录创建过程和脚手架验收标准,基于《技术架构设计.md》执行。
---
## 一、验收标准
| 项目 | 验收命令 | 成功标准 |
|------|----------|----------|
| backend-app | `./mvnw compile` | BUILD SUCCESS |
| frontend | `pnpm build` | built in X.XXs |
| ai-service | `python -m py_compile app/main.py` | 无语法错误 |
---
## 二、项目目录结构
```
studyweb/ # 项目根目录
├── README.md
├── 平台文档/ # 项目文档
│ ├── MVP方案/
│ │ ├── 技术架构设计.md
│ │ ├── 项目目录创建以及脚手架搭建.md # 本文档
│ │ └── ...
│ └── ...
├── backend/ # 后端(Java 17 / Spring Boot 3.x)
│ ├── apps/
│ │ └── backend-app/ # 业务单体
│ │ ├── pom.xml
│ │ ├── mvnw
│ │ ├── mvnw.cmd
│ │ └── src/
│ │ ├── main/
│ │ │ ├── java/com/platform/backend/
│ │ │ │ ├── BackendApplication.java
│ │ │ │ └── ...
│ │ │ └── resources/
│ │ │ └── application.yml
│ │ └── test/
│ └── libs/ # 共享库(预留)
├── frontend/ # 前端(React + TypeScript + Vite)
│ ├── package.json
│ ├── pnpm-lock.yaml
│ ├── vite.config.ts
│ ├── tsconfig.json
│ ├── src/
│ │ ├── main.tsx
│ │ ├── App.tsx
│ │ └── ...
│ └── dist/ # 构建产物
├── ai-service/ # AI 服务(Python 3.11 / FastAPI)
│ ├── requirements.txt
│ ├── pyproject.toml # 可选(尚未启用 uv)
│ ├── README.md
│ ├── app/
│ │ ├── main.py # FastAPI 入口
│ │ └── api/
│ │ ├── health.py
│ │ └── knowledge.py
│ └── repo_ingestion/ # 知识库构建模块
│ ├── collector.py
│ ├── parser.py
│ └── ...
├── scripts/ # 运维脚本
│ └── start.sh # 一键启停脚本
└── logs/ # 日志目录
├── backend-app.log
├── frontend.log
└── ai-service.log
```
---
## 三、后端(backend-app)
### 3.1 技术栈
- **语言**: Java 17
- **框架**: Spring Boot 3.2.5
- **构建工具**: Maven(Wrapper)
- **数据库**: MySQL 8.x
- **缓存**: Redis 6.x
### 3.2 脚手架创建
```bash
# 创建项目目录
mkdir -p backend/apps && cd backend/apps
# 使用 Spring Initializr 或手动创建
# 本项目采用手动创建 pom.xml 结构
# 初始化 Maven Wrapper
mvn wrapper:wrapper
# 或复制已有项目的 mvnw
```
### 3.3 关键配置文件
**pom.xml** 包含依赖:
- `spring-boot-starter-web`
- `spring-boot-starter-data-jpa`
- `spring-boot-starter-validation`
- `spring-boot-starter-security`
- `spring-boot-starter-data-redis`
- `mysql-connector-j`
- `lombok`
**application.yml** 配置:
```yaml
server:
port: 7087
address: 0.0.0.0
spring:
application:
name: backend-app
datasource:
url: jdbc:mysql://localhost:3306/intern_platform
username: root
password: root
jpa:
hibernate:
ddl-auto: update
show-sql: true
```
### 3.4 验收
```bash
cd backend/apps/backend-app
./mvnw compile
# 预期: BUILD SUCCESS
```
---
## 四、前端(frontend)
### 4.1 技术栈
- **语言**: TypeScript
- **框架**: React 18
- **构建工具**: Vite 5.x
- **包管理器**: pnpm
- **开发服务器端口**: 7080
### 4.2 脚手架创建
```bash
# 创建项目
mkdir -p frontend
cd frontend
# 初始化 package.json
pnpm init
# 安装依赖
pnpm add react react-dom
pnpm add -D typescript @types/react @types/react-dom vite @vitejs/plugin-react
# 配置文件
# - package.json
# - vite.config.ts
# - tsconfig.json
# - index.html
```
### 4.3 关键配置文件
**package.json**:
```json
{
"name": "intern-training-platform-frontend",
"version": "1.0.0",
"scripts": {
"dev": "vite",
"build": "tsc && vite build"
}
}
```
**vite.config.ts**:
```typescript
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
export default defineConfig({
plugins: [react()],
server: {
port: 7080,
host: '0.0.0.0',
proxy: {
'/api': {
target: 'http://localhost:7087',
changeOrigin: true,
},
},
},
});
```
### 4.4 验收
```bash
cd frontend
pnpm install
pnpm build
# 预期: ✓ built in X.XXs
```
---
## 五、AI 服务(ai-service)
### 5.1 技术栈
- **语言**: Python 3.11
- **框架**: FastAPI
- **运行端口**: 7083
### 5.2 脚手架创建
```bash
# 创建项目
mkdir -p ai-service/app/api ai-service/repo_ingestion
# 依赖文件
echo 'fastapi==0.115.0
uvicorn[standard]==0.30.6
pydantic==2.9.2
python-multipart==0.0.10
httpx==0.27.2' > requirements.txt
# 安装依赖
pip install -r requirements.txt
```
### 5.3 最小骨架文件
**app/main.py** - FastAPI 入口:
```python
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI(
title="ai-service",
version="1.0.0",
description="实习生训练平台 AI 服务",
)
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
from app.api import health, knowledge
app.include_router(health.router, prefix="/api/health", tags=["health"])
app.include_router(knowledge.router, prefix="/api/knowledge", tags=["knowledge"])
if __name__ == "__main__":
import uvicorn
uvicorn.run("app.main:app", host="0.0.0.0", port=7083, reload=True)
```
**app/api/health.py** - 健康检查:
```python
from fastapi import APIRouter
router = APIRouter()
@router.get("/")
def health_check():
return {"status": "ok", "service": "ai-service", "version": "1.0.0"}
```
### 5.4 验收
```bash
cd ai-service
python -m py_compile app/main.py app/api/health.py app/api/knowledge.py
# 预期: 无输出(语法检查通过)
```
---
## 六、运维脚本
### 6.1 一键启停脚本
位置: `scripts/start.sh`
功能:
- 使用 conda studyweb 环境
- 启动 backend-app (端口 7087)
- 启动 frontend (端口 7080)
- 启动 ai-service (端口 7083)
用法:
```bash
./scripts/start.sh # 启动所有服务
./scripts/start.sh restart # 重启所有服务
./scripts/start.sh stop # 停止所有服务
```
---
## 七、服务端口汇总
| 服务 | 端口 | 说明 |
|------|------|------|
| backend-app | 7087 | Spring Boot 业务后端 |
| frontend | 7080 | Vite 开发服务器 |
| ai-service | 7083 | FastAPI AI 服务 |
---
## 八、后续工作
- [ ] 完成四端前端开发(student/mentor/supervisor/admin)
- [ ] 实现用户认证模块
- [ ] 实现实训流程状态机
- [ ] 集成 Milvus 向量数据库
- [ ] 完善 CI/CD 流水线
# 项目模块(project-module)开发任务文档
> 文档版本:v1.0
> 创建时间:2026-07-14
> 负责人:(待填写)
> 状态:待开发
> 依赖模块:user-module(认证完成后方可开发)
> 依赖服务:ai-service(AI 推荐)、Milvus(向量数据库)、MinIO(文件存储)
---
## 一、模块概述
### 1.1 模块职责
项目模块是系统的核心模块之一,负责:
- 项目库管理(内部种子项目 / GitHub 推荐项目 / 往届标注项目)
- 标签管理(技术/方向/场景分类标签)
- 难度配置(打分卡 + AI 初评 + 工程师校准)
- AI 项目推荐(TopN 推荐 + 匹配度 + 理由)
- 知识点提取与预习(知识图谱 + 小测)
- 难度校准(AI 建议 + 一键校准)
### 1.2 技术栈
| 技术 | 版本 | 用途 |
|------|------|------|
| Spring Boot | 3.x | 基础框架 |
| Spring Data JPA | 3.x | ORM |
| Redis | 7.x | 缓存/限流 |
| MinIO Client | 8.x | 文件存储 |
| WebClient | - | AI 服务 HTTP 调用 |
| Resilience4j | 2.x | 熔断降级 |
### 1.3 模块依赖
```
project-module
├── 依赖:user-module(用户认证、权限)
├── 依赖:ai-service(推荐算法 / 知识点提取 / 难度评分)
├── 依赖:Milvus(向量检索)
├── 依赖:MinIO(项目资料存储)
└── 被依赖:training-module(项目选择、实训任务创建)
```
### 1.4 角色权限
| 角色 | 项目管理 | 标签管理 | 难度配置 | 项目推荐 | 难度校准 |
|------|---------|---------|---------|---------|---------|
| ADMIN | 增删改查 | 增删改查 | 增删改查 | 查看 | 查看 |
| SUPERVISOR | 查看 | 查看 | 查看 | 查看 | 校准 |
| MENTOR | 查看 | 查看 | 查看 | 查看 | — |
| STUDENT | 查看 | 查看 | — | 发起推荐 | — |
---
## 二、数据表设计
> **数据库来源**:数据库设计V1.md
> **开发前必读**:proj_ 开头的表为本模块负责的数据库表,字段类型/约束以此为准。
### 2.1 ER 图
```
┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐
│proj_internal_ │──────<│proj_project_tag│>──────│ proj_tag │
│project │ └─────────────────┘ └──────────────┘
└────────┬────────┘
│
▼
┌──────────────────────┐ ┌─────────────────────────────┐
│proj_difficulty_score- │──────<│proj_difficulty_calibration │
│card + score │ └─────────────────────────────┘
└───────────────────────┘
│
▼
┌────────────────┐
│ kp_knowledge_ │
│ point + dep │
└───────┬────────┘
│
▼
┌─────────────────────┐
│ train_preview_record│
└─────────────────────┘
│
▼
┌────────────────────────────┐
│ train_advanced_match (推荐) │
└────────────────────────────┘
```
### 2.2 表结构
#### 2.2.1 内部种子项目(proj_internal_project)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| name | VARCHAR(200) | NOT NULL | 项目名称 |
| description | TEXT | | 项目描述 |
| department_id | BIGINT | FK → user_department | 所属部门 |
| tech_stack | VARCHAR(200) | | 技术栈(技术部) |
| annotation_type | VARCHAR(100) | | 标注类型(标注部) |
| business_domain | VARCHAR(100) | | 业务领域 |
| difficulty_level | VARCHAR(10) | | L1~L5(五级难度) |
| knowledge_tags | VARCHAR(500) | | 知识点标签 |
| source_code_url | VARCHAR(500) | | 源码地址 |
| requirement_doc_url | VARCHAR(500) | | 需求文档 |
| acceptance_report_url | VARCHAR(500) | | 验收报告 |
| status | TINYINT | DEFAULT 0 | 0=草稿 1=启用 |
> **难度等级(L1-L5)**:
> L1=入门,L2=初级(对应"简单")
> L3=中级(对应"中等")
> L4=高级,L5=专家(对应"困难")
**索引**:`idx_department_difficulty` (department_id, difficulty_level)
---
#### 2.2.2 GitHub 推荐项目(proj_github_project)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| seed_project_id | BIGINT | FK → proj_internal_project | 关联种子项目 |
| github_url | VARCHAR(500) | NOT NULL | GitHub 链接 |
| repo_name | VARCHAR(200) | | 仓库名 |
| tech_stack | VARCHAR(200) | | 技术栈 |
| description | TEXT | | 描述 |
| difficulty_level | VARCHAR(10) | | L1~L5 |
| stars | INT | | Stars 数 |
| match_score | DECIMAL(4,2) | | 匹配度 |
| match_reason | TEXT | | 匹配理由 |
---
#### 2.2.3 往届标注项目(proj_annotation_project)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| name | VARCHAR(200) | NOT NULL | 项目名称 |
| industry | VARCHAR(100) | | 行业 |
| annotation_type | VARCHAR(100) | | 标注类型 |
| difficulty_level | VARCHAR(10) | | L1~L5 |
| match_score | DECIMAL(4,2) | | 匹配度 |
---
#### 2.2.4 项目标签(proj_project_tag)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| project_id | BIGINT | NOT NULL | 关联项目 ID |
| project_type | VARCHAR(20) | NOT NULL | internal/github/annotation |
| tag_name | VARCHAR(50) | NOT NULL | 标签名称 |
**唯一索引**:(project_id, project_type, tag_name)
---
#### 2.2.5 项目附件(proj_project_attachment)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| project_id | BIGINT | NOT NULL | 项目 ID |
| project_type | VARCHAR(20) | | internal/github/annotation |
| file_name | VARCHAR(200) | NOT NULL | 文件名 |
| file_url | VARCHAR(500) | | MinIO 路径 |
| file_type | VARCHAR(50) | | 文档类型 |
---
#### 2.2.6 难度打分卡维度(proj_difficulty_scorecard)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| department_id | BIGINT | FK → user_department | 所属部门 |
| dimension_name | VARCHAR(100) | NOT NULL | 维度名称 |
| weight | DECIMAL(3,2) | NOT NULL | 权重(0-1) |
> **打分维度(技术部参考)**:技术栈复杂度、知识点数量与依赖深度、代码/项目规模、预计工时、是否需跨系统联调。
> **打分维度(标注部参考)**:标注量、标注规则复杂度、质检标准严格度、领域专业度、预计工时。
---
#### 2.2.7 项目难度评分(proj_difficulty_score)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| project_id | BIGINT | NOT NULL | 项目 ID |
| project_type | VARCHAR(20) | | internal/github/annotation |
| ai_score | DECIMAL(5,2) | | AI 评分 |
| calibrated_level | VARCHAR(10) | | 校准后等级 L1~L5 |
---
#### 2.2.8 难度校准记录(proj_difficulty_calibration)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| score_id | BIGINT | FK → proj_difficulty_score | 关联难度评分 |
| previous_level | VARCHAR(10) | | 校准前 |
| new_level | VARCHAR(10) | NOT NULL | 校准后 |
| reason | VARCHAR(500) | | 调整原因 |
| calibration_by | BIGINT | FK → user_user | 校准人 |
---
#### 2.2.9 知识点(kp_knowledge_point)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| project_id | BIGINT | NOT NULL | 关联项目 |
| project_type | VARCHAR(20) | | internal/github/annotation |
| name | VARCHAR(200) | NOT NULL | 知识点名称 |
| description | TEXT | | 说明 |
| category | VARCHAR(50) | | concept/skill/tool |
| difficulty | VARCHAR(10) | DEFAULT medium | easy/medium/hard |
| estimated_hours | DECIMAL(4,1) | | 预计学习时长 |
| material_url | VARCHAR(500) | | 学习材料链接 |
---
#### 2.2.10 知识点依赖关系(kp_knowledge_dependency)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| knowledge_id | BIGINT | FK → kp_knowledge_point | 知识点 |
| prerequisite_id | BIGINT | FK → kp_knowledge_point | 前置知识点 |
---
## 三、API 接口设计
### 3.1 项目管理接口(/api/v1/projects)
#### 3.1.1 获取项目列表
```
GET /api/v1/projects
```
**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码,默认 1 |
| size | int | 否 | 每页条数,默认 10 |
| keyword | string | 否 | 关键词搜索(名称/描述) |
| project_type | string | 否 | internal/github/annotation |
| department_id | long | 否 | 部门筛选 |
| difficulty | string | 否 | 难度等级 L1~L5 |
| tag | string | 否 | 标签筛选 |
| sort | string | 否 | newest/popular/difficulty |
| order | string | 否 | asc/desc |
**响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"total": 100,
"page": 1,
"size": 10,
"items": [
{
"id": 1,
"name": "用户管理系统",
"description": "实现完整的用户CRUD功能...",
"projectType": "internal",
"difficultyLevel": "L3",
"difficultyName": "中级",
"departmentName": "技术部",
"tags": ["Java", "后端", "Spring Boot"],
"viewCount": 120,
"choiceCount": 45,
"status": 1,
"createdAt": "2026-01-01 00:00:00"
}
]
}
}
```
**验收标准**:
- [ ] 支持分页查询
- [ ] 支持 project_type / department / difficulty / tag 多条件筛选
- [ ] 支持关键词搜索(名称/描述模糊匹配)
- [ ] 支持排序:最新/热门/难度
- [ ] 标签支持多标签 AND/OR 筛选
---
#### 3.1.2 获取项目详情
```
GET /api/v1/projects/{id}
```
**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| projectType | string | 是 | internal/github/annotation |
**响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"name": "用户管理系统",
"description": "实现完整的用户CRUD功能...",
"projectType": "internal",
"difficultyLevel": "L3",
"difficultyName": "中级",
"departmentId": 1,
"departmentName": "技术部",
"techStack": ["Java", "Spring Boot", "MySQL"],
"businessDomain": "企业应用",
"knowledgeTags": ["RESTful API", "分层架构", "CRUD"],
"sourceCodeUrl": "https://xxx/source.zip",
"requirementDocUrl": "https://xxx/req.docx",
"acceptanceReportUrl": "https://xxx/acc.pdf",
"attachments": [
{"fileName": "需求文档.docx", "fileUrl": "https://minio/xxx.docx"}
],
"viewCount": 121,
"choiceCount": 46,
"status": 1,
"createdAt": "2026-01-01 00:00:00",
"knowledgePoints": [
{
"id": 1,
"name": "RESTful API 设计",
"difficulty": "medium",
"estimatedHours": 4.0,
"materialUrl": "https://xxx/material.pdf"
}
]
}
}
```
**验收标准**:
- [ ] 浏览次数 +1
- [ ] 返回完整项目信息(含知识点列表)
- [ ] 资料链接生成签名 URL(30 分钟有效)
- [ ] 包含标签列表
---
#### 3.1.3 创建项目(ADMIN)
```
POST /api/v1/projects
```
**请求参数**:
```json
{
"name": "用户管理系统",
"description": "实现完整的用户CRUD功能...",
"projectType": "internal",
"departmentId": 1,
"techStack": ["Java", "Spring Boot"],
"businessDomain": "企业应用",
"difficultyLevel": "L3",
"knowledgeTags": ["Java", "后端", "RESTful"],
"sourceCodeUrl": "https://xxx/source.zip",
"requirementDocUrl": "https://xxx/req.docx",
"acceptanceReportUrl": "https://xxx/acc.pdf",
"status": 1
}
```
**验收标准**:
- [ ] 项目名称唯一性校验
- [ ] projectType 为必填
- [ ] difficultyLevel 仅接受 L1~L5
- [ ] 自动触发 AI 难度评分(异步)
- [ ] 自动触发 AI 知识点提取(异步)
- [ ] 创建后自动同步 AI 向量库
---
#### 3.1.4 更新项目(ADMIN)
```
PUT /api/v1/projects/{id}
```
**请求参数**:同创建,projectType 不可修改
**验收标准**:
- [ ] 仅 ADMIN 可更新
- [ ] 难度变更时记录校准日志
- [ ] 更新后重新同步 AI 向量库
- [ ] 已有学员选择的不可删除,提示"该项目已被使用"
---
#### 3.1.5 删除项目(ADMIN)
```
DELETE /api/v1/projects/{id}
```
**验收标准**:
- [ ] 仅 ADMIN 可删除
- [ ] 软删除(is_deleted = 1)
- [ ] 删除后从 AI 向量库移除
- [ ] 已有学员选择时返回"该项目已被使用,无法删除"
---
#### 3.1.6 项目下拉列表
```
GET /api/v1/projects/simple
```
**请求参数**:keyword / project_type / difficulty / department_id
**响应**:
```json
{
"code": 0,
"data": [
{"id": 1, "name": "用户管理系统", "difficultyLevel": "L3"},
{"id": 2, "name": "电商系统", "difficultyLevel": "L4"}
]
}
```
---
### 3.2 标签管理接口(/api/v1/tags)
#### 3.2.1 获取标签列表
```
GET /api/v1/tags
```
**响应**:
```json
{
"code": 0,
"data": {
"categories": {
"技术": [
{"id": 1, "name": "Java", "color": "#2196F3"},
{"id": 2, "name": "Python", "color": "#4CAF50"}
],
"方向": [
{"id": 3, "name": "后端开发", "color": "#FF9800"}
],
"场景": [
{"id": 4, "name": "企业级", "color": "#9C27B0"}
]
},
"flatList": [
{"id": 1, "name": "Java", "category": "技术", "color": "#2196F3"}
]
}
}
```
**验收标准**:
- [ ] 按分类(技术/方向/场景)分组返回
- [ ] 同时返回扁平列表供筛选使用
- [ ] 支持按 category 筛选
---
#### 3.2.2 创建标签(ADMIN)
```
POST /api/v1/tags
```
```json
{
"name": "Java",
"category": "技术",
"color": "#2196F3"
}
```
---
#### 3.2.3 更新标签(ADMIN)
```
PUT /api/v1/tags/{id}
```
---
#### 3.2.4 删除标签(ADMIN)
```
DELETE /api/v1/tags/{id}
```
**验收标准**:
- [ ] 有关联项目时返回"该标签已被 N 个项目使用"
---
### 3.3 难度配置接口(/api/v1/difficulty)
#### 3.3.1 获取难度打分卡
```
GET /api/v1/difficulty/scorecard
```
**请求参数**:department_id(可选)
**响应**:
```json
{
"code": 0,
"data": {
"departmentId": 1,
"departmentName": "技术部",
"dimensions": [
{"id": 1, "dimensionName": "技术栈复杂度", "weight": 0.20},
{"id": 2, "dimensionName": "知识点数量与依赖深度", "weight": 0.25},
{"id": 3, "dimensionName": "代码/项目规模", "weight": 0.20},
{"id": 4, "dimensionName": "预计工时", "weight": 0.15},
{"id": 5, "dimensionName": "是否需跨系统联调", "weight": 0.20}
]
}
}
```
**验收标准**:
- [ ] 返回指定部门的打分卡维度 + 权重
- [ ] 权重总和 = 1.00
- [ ] 技术部和标注部分别维护各自的打分卡
---
#### 3.3.2 更新打分卡维度(ADMIN)
```
PUT /api/v1/difficulty/scorecard/{id}
```
```json
{
"dimensionName": "技术栈复杂度",
"weight": 0.25
}
```
**验收标准**:
- [ ] 权重调整后自动验证总和 = 1.00
- [ ] 调整后不影响已有难度评分记录
---
#### 3.3.3 获取项目 AI 难度评分
```
GET /api/v1/difficulty/project/{id}
```
**响应**:
```json
{
"code": 0,
"data": {
"projectId": 1,
"projectName": "用户管理系统",
"aiScore": 78.5,
"aiSuggestedLevel": "L3",
"calibratedLevel": "L3",
"calibrationStatus": "confirmed",
"calibrationHistory": [
{"previousLevel": "L2", "newLevel": "L3", "reason": "实际难度超出预期", "calibratedBy": "主管A", "calibratedAt": "2026-07-10"}
]
}
}
```
---
#### 3.3.4 校准难度等级(SUPERVISOR)
```
POST /api/v1/difficulty/calibrate
```
```json
{
"projectId": 1,
"projectType": "internal",
"newLevel": "L4",
"reason": "项目涉及微服务架构,实际难度较高"
}
```
**验收标准**:
- [ ] 记录校准日志(proj_difficulty_calibration)
- [ ] 记录校准人(取当前登录用户)
- [ ] 更新 proj_difficulty_score 的 calibrated_level
---
#### 3.3.5 校准历史查询(SUPERVISOR/ADMIN)
```
GET /api/v1/difficulty/calibration-history
```
**请求参数**:project_id / start_time / end_time / page / size
---
### 3.4 知识点管理接口(/api/v1/knowledge-points)
#### 3.4.1 获取项目的知识点列表
```
GET /api/v1/knowledge-points
```
**请求参数**:project_id / project_type(必填),category / difficulty(可选)
**响应**:
```json
{
"code": 0,
"data": {
"projectId": 1,
"totalCount": 8,
"knowledgePoints": [
{
"id": 1,
"name": "RESTful API 设计",
"description": "掌握 RESTful 风格的 API 设计规范...",
"category": "skill",
"difficulty": "medium",
"estimatedHours": 4.0,
"materialUrl": "https://xxx/material.pdf",
"prerequisites": [
{"id": 2, "name": "HTTP 协议基础"}
],
"dependents": [
{"id": 3, "name": "API 鉴权"}
]
}
]
}
}
```
**验收标准**:
- [ ] 返回知识点及依赖关系(有向图结构)
- [ ] 支持按 category(concept/skill/tool)/ difficulty 筛选
- [ ] 依赖关系展示前置和后续知识点
---
#### 3.4.2 AI 触发知识点提取(ADMIN)
```
POST /api/v1/knowledge-points/extract
```
```json
{
"projectId": 1,
"projectType": "internal"
}
```
**推荐流程**:
```
1. 调用 ai-service /knowledge/extract 接口
2. 返回结构化知识点列表
3. 存入 kp_knowledge_point 表
4. 建立依赖关系到 kp_knowledge_dependency 表
5. 返回提取结果供人工确认
```
**验收标准**:
- [ ] 异步处理,不阻塞主流程
- [ ] 提取完成后支持人工编辑
- [ ] 调用失败记录 ai_call_log,降级处理
---
#### 3.4.3 手动添加知识点(ADMIN)
```
POST /api/v1/knowledge-points
```
```json
{
"projectId": 1,
"projectType": "internal",
"name": "RESTful API 设计",
"description": "掌握 RESTful 风格的 API 设计规范...",
"category": "skill",
"difficulty": "medium",
"estimatedHours": 4.0,
"materialUrl": "https://xxx/material.pdf",
"prerequisiteIds": [2, 3]
}
```
---
### 3.5 AI 推荐接口(/api/v1/recommendations)
#### 3.5.1 发起项目推荐(STUDENT)
```
POST /api/v1/recommendations
```
**请求参数**:
```json
{
"projectType": "github",
"seedProjectId": 1,
"limit": 5,
"excludeProjectIds": [3, 5]
}
```
> project_type = github 时推荐 GitHub 项目
> project_type = annotation 时推荐往届标注项目
**推荐流程**:
```
1. 查询种子项目特征(tech_stack / difficulty / tags)
2. 调用 ai-service /recommend 接口
3. Milvus TopK 检索 → LLM 重排序 + 理由生成
4. 返回 TopN + 匹配度 + 推荐理由
5. 记录 train_advanced_match 日志
```
**响应**:
```json
{
"code": 0,
"message": "推荐成功",
"data": {
"source": "ai",
"recommendations": [
{
"projectId": 10,
"projectName": "Spring Boot REST API 实战",
"projectType": "github",
"githubUrl": "https://github.com/org/repo",
"description": "...",
"difficultyLevel": "L3",
"techStack": ["Java", "Spring Boot"],
"matchScore": 0.9234,
"matchReason": "与种子项目'用户管理系统'技术栈高度匹配(Java+Spring Boot),难度适中(L3),预计学习时长6小时。",
"stars": 1250
}
],
"totalTime": 1200
}
}
```
**验收标准**:
- [ ] 返回匹配度 0-1(保留 4 位小数)+ 推荐理由
- [ ] 推荐理由由 LLM 生成(50-200 字)
- [ ] 记录 train_advanced_match 日志
- [ ] AI 不可用时走降级方案(按标签随机匹配)
- [ ] Resilience4j 熔断保护(超时 8 秒)
---
#### 3.5.2 用户采纳推荐(STUDENT)
```
POST /api/v1/recommendations/{projectId}/choose
```
```json
{
"recommendationId": 123,
"projectType": "github"
}
```
**验收标准**:
- [ ] 更新 train_advanced_match 的 user_action = choose
- [ ] proj_github_project.choice_count +1(若为 github 类型)
- [ ] 触发 training-module 创建实训任务
---
#### 3.5.3 用户忽略推荐(STUDENT)
```
POST /api/v1/recommendations/{projectId}/ignore
```
**验收标准**:
- [ ] 更新 train_advanced_match 的 user_action = ignore
- [ ] 不增加 choice_count
---
#### 3.5.4 获取推荐历史(STUDENT)
```
GET /api/v1/recommendations/history
```
**请求参数**:page / size
**验收标准**:
- [ ] 返回当前用户的推荐历史
- [ ] 包含推荐项目、匹配度、来源、用户操作、时间
---
### 3.6 文件上传接口(/api/v1/files)
#### 3.6.1 上传项目资料(ADMIN)
```
POST /api/v1/files/upload
```
**请求参数**:multipart/form-data(file, project_id, project_type, file_type)
**验收标准**:
- [ ] 上传至 MinIO,按 project_id/project_type 分目录
- [ ] 支持 PDF/Word/Excel/压缩包,单文件最大 50MB
- [ ] 返回文件 URL 和 file_id
---
#### 3.6.2 获取签名下载 URL
```
GET /api/v1/files/{fileId}/download-url
```
**验收标准**:
- [ ] 生成签名 URL,有效期 30 分钟
- [ ] 仅文件所有者或 ADMIN 可获取
---
## 四、功能点拆解 & 验收标准
### 4.1 项目管理
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 创建项目 | 管理员添加种子项目 | P0 |
| 2 | 项目列表 | 分页 + 多条件筛选(type/dept/difficulty/tag) | P0 |
| 3 | 项目详情 | 查看完整项目信息,含知识点和附件 | P0 |
| 4 | 更新项目 | 修改项目信息 | P0 |
| 5 | 删除项目 | 软删除 + 检查关联 | P0 |
| 6 | 项目下拉 | 简化列表用于选择 | P1 |
| 7 | 浏览次数统计 | 详情页浏览 +1 | P1 |
**验收标准**:
```
[ ] 项目名称唯一性校验
[ ] difficulty_level 仅接受 L1~L5
[ ] project_type 必填,为 internal/github/annotation
[ ] 技术栈/标签存储为 JSON 数组
[ ] 软删除,被使用项目不可删除
[ ] 浏览次数 +1
[ ] 选择次数 +1(采纳推荐时)
```
---
### 4.2 标签管理
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 创建标签 | 名称/分类/颜色 | P0 |
| 2 | 标签列表 | 按分类分组 + 扁平列表 | P0 |
| 3 | 更新标签 | 修改标签信息 | P0 |
| 4 | 删除标签 | 检查关联后删除 | P0 |
**验收标准**:
```
[ ] 标签名称唯一性校验
[ ] 分类:技术/方向/场景
[ ] 颜色格式:#RRGGBB
[ ] 删除前检查 proj_project_tag 关联
```
---
### 4.3 难度分级机制
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 打分卡维度配置 | 定义每个维度的权重 | P0 |
| 2 | AI 难度初评 | 基于知识点/依赖深度等信号自动评分 | P0 |
| 3 | 工程师校准 | 一键认可/上调/下调 | P0 |
| 4 | 校准历史 | 查看校准记录 | P1 |
**难度分级三段式机制**:
```
第一步:固定打分卡(一次性定义)
→ 每个部门维护一张打分卡
→ 每个维度 1-5 分,加权求和映射到 L1~L5
第二步:AI 自动初评
→ 基于知识点数量、依赖深度等信号自动算分
→ 给出建议等级
第三步:工程师一键校准
→ 仅对 AI 建议做「认可 / 上调 / 下调」
→ 记录校准原因
→ 校准数据回流训练,逐步减少人工干预
```
**验收标准**:
```
[ ] 打分卡权重总和 = 1.00
[ ] AI 评分异步进行,不阻塞项目创建
[ ] 校准后更新 calibrated_level
[ ] 校准日志包含:项目名/原等级/新等级/原因/操作人/时间
[ ] 锚点:显示已定级参照项目(如"与 L3 项目 X 难度相当")
```
---
### 4.4 AI 项目推荐
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 发起推荐 | STUDENT 发起 TopN 推荐 | P0 |
| 2 | 推荐理由 | LLM 生成推荐理由(50-200字) | P0 |
| 3 | 采纳/忽略 | 用户操作推荐结果 | P0 |
| 4 | 推荐历史 | 查看历史推荐记录 | P1 |
| 5 | 降级方案 | AI 不可用时按标签随机匹配 | P0 |
**验收标准**:
```
[ ] 调用超时时间 ≤ 8 秒
[ ] 匹配度 0-1,保留 4 位小数
[ ] Resilience4j 熔断保护
[ ] 降级时 source = "fallback",记录告警
[ ] 采纳后触发 training-module 创建实训任务
```
---
### 4.5 AI 知识点提取
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 知识点生成 | AI 从项目代码/资料中提取知识点 | P0 |
| 2 | 依赖关系建立 | 构建知识点有向图 | P0 |
| 3 | 知识点管理 | 增删改查,支持人工编辑 | P0 |
| 4 | 预习材料关联 | 关联学习材料链接 | P1 |
**验收标准**:
```
[ ] 知识点结构化:name/description/category/difficulty/estimated_hours/material_url
[ ] 依赖关系有向图,前置/后续清晰展示
[ ] 提取完成后支持人工确认和编辑
[ ] 预习小测由 training-module 负责(train_preview_quiz)
```
---
### 4.6 文件管理
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 资料上传 | 上传至 MinIO | P0 |
| 2 | 签名 URL | 生成有时限的下载链接 | P0 |
| 3 | 资料预览 | 支持常见格式 | P2 |
---
## 五、AI 服务接口(ai-service)
### 5.1 推荐接口
```
POST /ai/recommend
```
**请求**:
```json
{
"project_type": "github",
"seed_project": {
"id": 1,
"name": "用户管理系统",
"tech_stack": ["Java", "Spring Boot"],
"tags": ["后端", "Java"],
"difficulty_level": "L3"
},
"limit": 5,
"exclude_ids": [3, 5]
}
```
**响应**:
```json
{
"success": true,
"data": {
"recommendations": [
{
"project_id": 10,
"match_score": 0.9234,
"match_reason": "与您的 Java+Spring Boot 技术栈高度匹配..."
}
]
}
}
```
### 5.2 知识点提取接口
```
POST /ai/knowledge/extract
```
**请求**:
```json
{
"project_id": 1,
"project_type": "internal",
"source_code_url": "https://xxx/source.zip",
"requirement_doc_url": "https://xxx/req.docx"
}
```
**响应**:
```json
{
"success": true,
"data": {
"knowledge_points": [
{
"name": "RESTful API 设计",
"description": "...",
"category": "skill",
"difficulty": "medium",
"estimated_hours": 4.0,
"prerequisites": ["HTTP 协议基础"]
}
]
}
}
```
### 5.3 难度评分接口
```
POST /ai/difficulty/score
```
**请求**:
```json
{
"project_id": 1,
"knowledge_count": 8,
"dependency_depth": 3,
"estimated_hours": 40,
"requires_integration": true
}
```
**响应**:
```json
{
"success": true,
"data": {
"ai_score": 78.5,
"suggested_level": "L3"
}
}
```
---
## 六、技术实现要点
### 6.1 AI 服务调用封装
```java
@Service
public class AiServiceClient {
private final WebClient aiWebClient;
private final Resilience4jCircuitBreaker circuitBreaker;
public RecommendResult recommend(RecommendRequest request) {
return circuitBreaker.executeSupplier(() ->
aiWebClient.post()
.uri("/ai/recommend")
.bodyValue(request)
.retrieve()
.bodyToMono(AiResponse.class)
.block(Duration.ofSeconds(8))
);
}
public AiRecommendResult fallback(RecommendRequest request) {
// 按标签随机匹配,降级处理
return tagBasedRecommend(request);
}
}
```
### 6.2 Resilience4j 配置
```yaml
resilience4j:
circuitbreaker:
instances:
aiRecommend:
sliding-window-size: 10
failure-rate-threshold: 50
wait-duration-in-open-state: 30s
permitted-number-of-calls-in-half-open-state: 3
timelimiter:
instances:
aiRecommend:
timeout-duration: 8s
```
### 6.3 MinIO 文件存储
```java
@Service
public class MinioStorageService {
public String uploadFile(MultipartFile file, String projectId, String projectType) {
String objectName = String.format("projects/%s/%s/%s",
projectType, projectId, UUID.randomUUID() + "_" + file.getOriginalFilename());
minioClient.putObject(
PutObjectArgs.builder()
.bucket("intern-platform")
.object(objectName)
.stream(file.getInputStream(), file.getSize(), -1)
.contentType(file.getContentType())
.build()
);
return objectName;
}
public String getSignedUrl(String objectName) {
return minioClient.getPresignedObjectUrl(
GetPresignedObjectUrlArgs.builder()
.bucket("intern-platform")
.object(objectName)
.expiry(30, TimeUnit.MINUTES)
.build()
);
}
}
```
---
## 七、任务优先级
### P0(必须完成)
| 序号 | 任务 | 模块 |
|------|------|------|
| 1 | 项目 CRUD 接口 | 项目管理 |
| 2 | 项目列表 + 筛选 + 排序 | 项目管理 |
| 3 | 项目详情 + 浏览次数 | 项目管理 |
| 4 | 标签 CRUD + 列表分组 | 标签管理 |
| 5 | 打分卡维度配置 | 难度分级 |
| 6 | AI 难度评分调用 | 难度分级 |
| 7 | 工程师校准 + 历史 | 难度分级 |
| 8 | AI 推荐调用 + 理由生成 | AI 推荐 |
| 9 | 推荐采纳/忽略功能 | AI 推荐 |
| 10 | Fallback 降级方案 | AI 推荐 |
| 11 | 知识点列表 + 依赖关系 | 知识点 |
| 12 | AI 知识点提取 | 知识点 |
### P1(核心功能)
| 序号 | 任务 | 模块 |
|------|------|------|
| 13 | 项目向量同步(Milvus) | AI 同步 |
| 14 | 推荐历史查询 | AI 推荐 |
| 15 | 项目向量同步(项目创建/更新/删除) | AI 同步 |
| 16 | 项目下拉简化接口 | 项目管理 |
| 17 | 资料上传 MinIO | 文件管理 |
| 18 | 签名 URL 生成 | 文件管理 |
| 19 | 标签关联统计 | 标签管理 |
### P2(完善功能)
| 序号 | 任务 | 模块 |
|------|------|------|
| 20 | 全量向量同步(管理员手动) | AI 同步 |
| 21 | 热门标签统计 | 标签管理 |
| 22 | 资料预览 | 文件管理 |
---
## 八、开发顺序建议
```
第一周:项目管理 + 标签管理
├── 1. 项目表 + 标签表设计(JPA Entity)
├── 2. 项目 CRUD 接口
├── 3. 项目列表 + 筛选 + 排序
├── 4. 项目详情 + 浏览次数
├── 5. 标签 CRUD + 列表(分组)
└── 6. 项目下拉简化接口
第二周:难度分级 + AI 集成准备
├── 1. 打分卡维度表设计
├── 2. 难度评分表 + 校准表
├── 3. AI 难度评分调用封装
├── 4. 校准接口 + 历史查询
├── 5. 知识点表 + 依赖表
└── 6. 知识点列表 + 依赖图
第三周:推荐功能 + 同步
├── 1. AI 推荐调用 + 理由生成
├── 2. 采纳/忽略功能
├── 3. Fallback 降级方案
├── 4. 推荐历史查询
├── 5. MinIO 文件上传
├── 6. Milvus 向量同步
└── 7. 单元测试
```
---
## 九、交付物清单
| 序号 | 交付物 | 说明 |
|------|--------|------|
| 1 | 数据库脚本 | proj_* / kp_* 表的 JPA Entity |
| 2 | 后端接口 | 全部 API 接口 |
| 3 | AI 服务封装 | 推荐 / 知识点提取 / 难度评分 |
| 4 | 降级方案 | Fallback 处理 |
| 5 | 单元测试 | 覆盖率 ≥ 80% |
| 6 | 接口文档 | Swagger / OpenAPI |
---
## 十、与其他模块的接口
### 10.1 被调用接口(供其他模块调用)
| 接口 | 调用方 | 说明 |
|------|--------|------|
| GET /projects/{id} | training-module | 获取项目详情创建实训 |
| GET /projects/simple | training-module | 项目下拉列表 |
| GET /knowledge-points | training-module | 获取项目知识点列表 |
| POST /recommendations | training-module | 学员选择项目时发起推荐 |
### 10.2 调用其他模块接口
| 接口 | 被调用方 | 说明 |
|------|----------|------|
| AI /ai/recommend | ai-service | 获取推荐结果 |
| AI /ai/knowledge/extract | ai-service | 提取知识点 |
| AI /ai/difficulty/score | ai-service | 难度评分 |
| AI /ai/embed | ai-service | 向量入库 |
| 用户认证 | user-module | 权限校验(ADMIN/SUPERVISOR/STUDENT) |
---
## 十一、风险与注意事项
| 风险 | 影响 | 应对 |
|------|------|------|
| AI 服务不可用 | 推荐/知识点提取失败 | Fallback 降级方案 |
| Milvus 故障 | 向量检索失败 | 从数据库兜底读取 |
| 并发推荐 | 重复推荐 | 推荐历史去重 |
| 向量同步延迟 | 新项目不可推荐 | 异步 + 补偿任务 |
| GitHub 限流 | 镜像拉取失败 | Token 池 + 本地缓存 |
---
*文档结束*
# 实训模块(training-module)开发任务文档
> 文档版本:v1.0
> 创建时间:2026-07-14
> 负责人:(待填写)
> 状态:待开发
> 依赖模块:user-module(认证完成)、project-module(项目库完成)
> 依赖服务:ai-service(缺陷分析/进阶匹配)、Docker(容器沙箱)、MinIO(产物存储)
---
## 一、模块概述
### 1.1 模块职责
实训模块是系统的核心业务模块,负责承载完整的实训闭环:
- 实训任务管理(创建/查询/流转)
- 预习管理(知识点列表/小测/完成校验)
- 实操管理(容器沙箱/产物提交/报告撰写)
- 答辩管理(申请/评审/结论)
- 缺陷记录(错误日志/薄弱点标注)
- 进阶匹配(AI 推荐进阶项目)
- 能力画像(熟练度跟踪)
### 1.2 实训闭环流程
```
学员选择项目
│
▼
① 预习阶段
│ 预习知识点 → 完成小测 → 全部通过
│ │
│ └─ 未通过 → 重新学习
▼
② 实操阶段(容器沙箱)
│ 代码编写 → 运行测试 → 提交产物
│ │
│ └─ 运行报错 → 记录错误日志
▼
③ 报告阶段
│ 撰写过程记录 + 结果说明 → 提交报告
▼
④ 答辩申请
│ 一键申请 → 流转至导师
▼
⑤ 导师答辩评审
│ │
│ ├─ 通过 ──────────────────────┐
│ │ │
│ └─ 驳回 → 记录缺陷 → 更新画像 │
│ │
▼ │
⑥ 主管审核 │
│ │
├─ 通过 → 入项 │
│ │
└─ 驳回 → 记录缺陷 → 更新画像 ───────┘
│ │
▼ │
⑦ AI 进阶匹配 │
│ │
▼ │
回到 ①(新一轮预习-实操循环)────────┘
```
### 1.3 任务状态流转
| 状态码 | 状态名 | 说明 |
|--------|--------|------|
| preview | 预习中 | 学员开始预习 |
| practice | 实操中 | 预习完成,进入实操 |
| report | 撰写报告中 | 实操完成,撰写报告 |
| defense_pending | 待答辩 | 报告提交,等待答辩 |
| defense | 答辩中 | 导师评审中 |
| supervisor_review | 待主管审核 | 答辩通过,等待主管 |
| completed | 已完成 | 主管审核通过,实训结束 |
| rejected | 已驳回 | 答辩或主管驳回 |
**状态机规则**:
```
preview → practice(预习全部完成)
practice → report(产物提交)
report → defense_pending(报告提交)
defense_pending → defense(导师开始评审)
defense → supervisor_review(答辩通过)
defense → rejected(答辩驳回 → practice)
supervisor_review → completed(主管通过)
supervisor_review → rejected(主管驳回 → 触发进阶匹配)
```
### 1.4 技术栈
| 技术 | 版本 | 用途 |
|------|------|------|
| Spring Boot | 3.x | 基础框架 |
| Spring Data JPA | 3.x | ORM |
| Redis | 7.x | 缓存/任务状态 |
| Docker Java Client | 9.x | 容器沙箱管理 |
| WebClient | - | AI 服务调用 |
| Resilience4j | 2.x | 熔断降级 |
| MinIO Client | 8.x | 产物文件存储 |
### 1.5 模块依赖
```
training-module
├── 依赖:user-module(学员/导师/主管信息)
├── 依赖:project-module(项目详情、知识点)
├── 依赖:ai-service(缺陷分析、进阶匹配)
├── 依赖:Docker(容器沙箱创建/销毁)
├── 依赖:MinIO(产物上传/下载)
└── 被依赖:audit-module(主管审核结果)
```
### 1.6 角色权限
| 角色 | 我的实训 | 创建任务 | 答辩评审 | 查看历史 | 容器管理 |
|------|---------|---------|---------|---------|---------|
| STUDENT | ✅ 增删改查 | 发起 | ❌ | 查看本人 | 使用 |
| MENTOR | ✅ 分配给我的 | ❌ | ✅ 评审 | 查看本部门 | ❌ |
| SUPERVISOR | ✅ 查看 | ❌ | 审核 | 查看全部 | ❌ |
| ADMIN | ✅ 全部 | ✅ | 查看 | 查看全部 | 管理 |
---
## 二、数据表设计
> **数据库来源**:数据库设计V1.md,train_ 前缀的表
> **开发前必读**:字段类型/约束以此为准。
### 2.1 ER 图
```
┌─────────────────┐ ┌──────────────────┐ ┌───────────────────┐
│ train_task │──────<│train_preview_record│>─────│kp_knowledge_point │
└────────┬────────┘ └──────────────────┘ └───────────────────┘
│ ▲
│ ┌──────────────────┐ │
├──<│train_preview_quiz│ │
│ └──────────────────┘ │
│ │
│ ┌──────────────────────┐ ┌───────────────────┐ │
├──<│train_practice_artifact│ │train_defect_record│ │
│ └──────────────────────┘ └───────┬───────────┘ │
│ ┌──────────────────────┐ │ │
├──<│train_practice_report │ │ │
│ └──────────────────────┘ │ │
│ │ │
│ ┌────────────────────┐ │ │
├──<│train_defense_app │ │ │
│ └─────────┬──────────┘ │ │
│ │ │ │
│ ┌────────────────────┐ │ │
├──<│train_defense_review│ │ │
│ └────────────────────┘ │ │
│ │ │
│ ┌────────────────┐ │ │
├──<│train_error_log │ │ │
│ └────────────────┘ │ │
│ │ │
│ ┌─────────────────────┐ │ │
└──<│train_advanced_match │──────────────┘ │
└─────────────────────┘ │
┌────────────────────┐ ┌──────────────────────┐
│ train_task │──────<│train_capability_assess│
└────────────────────┘ └──────────────────────┘
│
▼
┌────────────────────┐
│ train_skill_profile │
└────────────────────┘
```
### 2.2 表结构
#### 2.2.1 实训任务主表(train_task)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| user_id | BIGINT | FK → user_user, NOT NULL | 学员 |
| project_type | VARCHAR(20) | NOT NULL | internal/github/annotation |
| project_id | BIGINT | NOT NULL | 对应项目表 ID |
| cycle_number | INT | DEFAULT 1 | 当前第几轮 |
| status | VARCHAR(20) | NOT NULL | 任务状态 |
| mentor_id | BIGINT | FK → user_user | 导师 |
| container_id | VARCHAR(100) | | Docker 容器 ID |
| code_server_url | VARCHAR(500) | | code-server 访问地址 |
| preview_completed_at | DATETIME | | 预习完成时间 |
| practice_submitted_at | DATETIME | | 实操提交时间 |
| defense_applied_at | DATETIME | | 答辩申请时间 |
| defense_completed_at | DATETIME | | 答辩完成时间 |
| reviewed_at | DATETIME | | 审核完成时间 |
**索引**:(user_id, status),(project_type, project_id),(mentor_id, status)
**状态流转图**:
```
preview → practice → report → defense_pending → defense
↘ rejected(驳回 → practice)
↘ supervisor_review → completed
↘ rejected(驳回 → 进阶匹配)
```
---
#### 2.2.2 预习记录(train_preview_record)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| task_id | BIGINT | FK → train_task | 所属任务 |
| knowledge_id | BIGINT | FK → kp_knowledge_point | 知识点 |
| status | VARCHAR(20) | DEFAULT pending | pending/completed/skipped |
| completed_at | DATETIME | | 完成时间 |
**索引**:(task_id, knowledge_id),(task_id, status)
---
#### 2.2.3 预习小测(train_preview_quiz)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| task_id | BIGINT | FK → train_task | 所属任务 |
| knowledge_id | BIGINT | FK → kp_knowledge_point | 知识点 |
| score | INT | | 得分(0-100) |
| pass_status | TINYINT | DEFAULT 0 | 0=未过 1=通过 |
| answered_at | DATETIME | | 答题时间 |
**验收标准**:
- 得分 ≥ 60 视为通过(pass_status = 1)
- 同一知识点支持多次答题,记录历史最高分
---
#### 2.2.4 实操产物(train_practice_artifact)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| task_id | BIGINT | FK → train_task | 所属任务 |
| artifact_type | VARCHAR(30) | NOT NULL | 产物类型 |
| content | TEXT | | 内容描述 |
| file_url | VARCHAR(500) | | MinIO 文件路径 |
**artifact_type 可选值**:
| 值 | 说明 |
|------|------|
| code_repo | 代码仓库地址 |
| screenshot | 运行截图 |
| log_file | 日志文件 |
| output | 运行结果输出 |
| document | 其他文档 |
---
#### 2.2.5 实操报告(train_practice_report)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| task_id | BIGINT | FK → train_task, UNIQUE | 一个任务一份报告 |
| process_description | TEXT | | 过程记录(做了什么) |
| result_description | TEXT | | 结果说明(做得怎样) |
| status | VARCHAR(20) | DEFAULT draft | draft/submitted |
| submitted_at | DATETIME | | 提交时间 |
---
#### 2.2.6 答辩申请(train_defense_application)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| task_id | BIGINT | FK → train_task, UNIQUE | 一个任务一次申请 |
| report_id | BIGINT | FK → train_practice_report | 关联报告 |
| status | VARCHAR(20) | DEFAULT pending | pending/accepted/rejected/cancelled |
---
#### 2.2.7 答辩评审(train_defense_review)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| task_id | BIGINT | FK → train_task, UNIQUE | 一个任务一次评审 |
| mentor_id | BIGINT | FK → user_user | 评审导师 |
| total_score | DECIMAL(4,1) | | 总分(0-100) |
| comment | TEXT | | 评审意见 |
| result | VARCHAR(10) | NOT NULL | pass/reject |
| created_at | DATETIME | | 评审时间 |
---
#### 2.2.8 历史缺陷记录(train_defect_record)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| task_id | BIGINT | FK → train_task | 所属任务 |
| knowledge_id | BIGINT | FK → kp_knowledge_point | 薄弱知识点 |
| severity | VARCHAR(10) | | low/medium/high |
| source | VARCHAR(30) | | 来源:error_log/defense/mentor_review |
| description | TEXT | | 缺陷描述 |
| created_at | DATETIME | | 记录时间 |
---
#### 2.2.9 沙箱错误日志(train_error_log)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| task_id | BIGINT | FK → train_task | 所属任务 |
| log_content | TEXT | NOT NULL | 错误日志内容 |
| error_type | VARCHAR(50) | | 错误类型 |
| severity | VARCHAR(10) | DEFAULT medium | low/medium/high |
| created_at | DATETIME | | 采集时间 |
---
#### 2.2.10 进阶匹配记录(train_advanced_match)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| task_id | BIGINT | FK → train_task | 来源任务 |
| user_id | BIGINT | FK → user_user | 学员 |
| matched_project_id | BIGINT | | 匹配项目 ID |
| match_score | DECIMAL(5,4) | | AI 匹配度(0-1) |
| match_reason | TEXT | | AI 推荐理由 |
| status | VARCHAR(20) | DEFAULT pending | pending/accepted/rejected/used |
| created_at | DATETIME | | 创建时间 |
**索引**:(user_id, status)
---
#### 2.2.11 能力画像(train_skill_profile)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| user_id | BIGINT | FK → user_user | 学员 |
| knowledge_id | BIGINT | FK → kp_knowledge_point | 知识点 |
| mastery_level | DECIMAL(4,2) | | 熟练度(0-1) |
| last_assessed_at | DATETIME | | 最近评估时间 |
**索引**:(user_id, knowledge_id)
---
#### 2.2.12 能力评估记录(train_capability_assessment)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| user_id | BIGINT | FK → user_user | 学员 |
| knowledge_id | BIGINT | FK → kp_knowledge_point | 知识点 |
| assessment_source | VARCHAR(30) | | 来源:小测/答辩/主管 |
| score | DECIMAL(4,2) | | 得分(0-100) |
| created_at | DATETIME | | 评估时间 |
---
## 三、API 接口设计
### 3.1 统一规范
与 user-module / project-module 保持一致:
```json
{
"code": 0,
"message": "操作成功",
"data": {}
}
```
---
### 3.2 实训任务接口(/api/v1/training/tasks)
#### 3.2.1 创建实训任务(STUDENT)
```
POST /api/v1/training/tasks
```
**请求参数**:
```json
{
"projectType": "github",
"projectId": 10,
"cycleNumber": 1
}
```
**响应参数**:
```json
{
"code": 0,
"message": "任务创建成功",
"data": {
"taskId": 1,
"projectName": "Spring Boot REST API 实战",
"status": "preview",
"knowledgePoints": [
{"id": 1, "name": "RESTful API 设计", "status": "pending"},
{"id": 2, "name": "Spring Boot 入门", "status": "pending"}
],
"containerId": null,
"codeServerUrl": null
}
}
```
**创建流程**:
```
1. 校验项目存在且状态正常
2. 查询项目的知识点列表(kp_knowledge_point)
3. 为每个知识点创建预习记录(train_preview_record,status=pending)
4. 创建实训任务(train_task,status=preview)
5. 自动分配导师(按部门 round-robin 或固定导师)
6. 异步创建 Docker 容器(分配 code-server)
7. 返回任务信息(含容器地址)
```
**验收标准**:
- [ ] 项目已选择则不能重复创建(同一 project_id + user_id 检查)
- [ ] 自动为每个知识点创建待预习记录
- [ ] 自动分配导师
- [ ] 异步创建容器,不阻塞返回
- [ ] 容器创建失败不影响任务创建,标记 warning
---
#### 3.2.2 获取我的实训任务列表(STUDENT)
```
GET /api/v1/training/tasks/my
```
**请求参数**:page / size / status / cycle_number(可选)
**响应参数**:
```json
{
"code": 0,
"data": {
"total": 3,
"page": 1,
"items": [
{
"taskId": 1,
"projectName": "Spring Boot REST API 实战",
"projectType": "github",
"difficultyLevel": "L3",
"cycleNumber": 1,
"status": "practice",
"progress": {
"totalKnowledge": 5,
"completedKnowledge": 3,
"previewPercent": 60,
"artifactsCount": 2,
"reportStatus": null
},
"mentorName": "李导师",
"createdAt": "2026-07-01 10:00:00",
"previewCompletedAt": "2026-07-03 15:00:00",
"practiceSubmittedAt": null
}
]
}
}
```
---
#### 3.2.3 获取实训任务详情(STUDENT/MENTOR/SUPERVISOR)
```
GET /api/v1/training/tasks/{taskId}
```
**响应参数**:
```json
{
"code": 0,
"data": {
"taskId": 1,
"user": {
"id": 10,
"realName": "张三",
"avatar": "https://xxx/avatar.jpg"
},
"project": {
"id": 10,
"name": "Spring Boot REST API 实战",
"projectType": "github",
"difficultyLevel": "L3",
"githubUrl": "https://github.com/org/repo"
},
"cycleNumber": 1,
"status": "practice",
"mentor": {
"id": 5,
"realName": "李导师"
},
"container": {
"containerId": "container-abc123",
"codeServerUrl": "http://localhost:30000"
},
"preview": {
"total": 5,
"completed": 3,
"percent": 60,
"items": [
{
"knowledgeId": 1,
"knowledgeName": "RESTful API 设计",
"status": "completed",
"completedAt": "2026-07-03 14:00:00",
"quizScore": 85
}
]
},
"artifacts": [
{
"id": 1,
"artifactType": "code_repo",
"content": "https://github.com/user/repo",
"fileUrl": null,
"createdAt": "2026-07-10 09:00:00"
}
],
"report": {
"id": 1,
"processDescription": "...",
"resultDescription": "...",
"status": "draft",
"submittedAt": null
},
"defense": {
"appliedAt": null,
"reviewResult": null,
"totalScore": null,
"comment": null
},
"defects": [
{
"id": 1,
"knowledgeName": "异常处理",
"severity": "medium",
"source": "error_log",
"description": "未对空指针做处理..."
}
],
"timestamps": {
"createdAt": "2026-07-01 10:00:00",
"previewCompletedAt": "2026-07-03 15:00:00",
"practiceSubmittedAt": null,
"defenseAppliedAt": null,
"defenseCompletedAt": null,
"reviewedAt": null
}
}
}
```
---
#### 3.2.4 获取任务流转历史(STUDENT/MENTOR/SUPERVISOR)
```
GET /api/v1/training/tasks/{taskId}/flow
```
**响应**:system_flow_event 表,按时间倒序
```json
{
"code": 0,
"data": [
{"fromStatus": null, "toStatus": "preview", "event": "任务创建", "createdAt": "2026-07-01 10:00:00"},
{"fromStatus": "preview", "toStatus": "practice", "event": "预习完成", "createdAt": "2026-07-03 15:00:00"}
]
}
```
---
### 3.3 预习管理接口(/api/v1/training/preview)
#### 3.3.1 获取预习知识点列表
```
GET /api/v1/training/preview/{taskId}/knowledge
```
**响应**:
```json
{
"code": 0,
"data": {
"taskId": 1,
"total": 5,
"completed": 3,
"percent": 60,
"items": [
{
"knowledgeId": 1,
"name": "RESTful API 设计",
"description": "掌握 RESTful 风格 API...",
"category": "skill",
"difficulty": "medium",
"estimatedHours": 4.0,
"materialUrl": "https://xxx/material.pdf",
"status": "completed",
"completedAt": "2026-07-03 14:00:00",
"quizScore": 85,
"prerequisites": [
{"id": 2, "name": "HTTP 协议基础", "status": "completed"}
]
}
]
}
}
```
---
#### 3.3.2 提交单个知识点预习完成
```
POST /api/v1/training/preview/{taskId}/complete
```
**请求参数**:
```json
{
"knowledgeId": 1
}
```
**验收标准**:
- [ ] 仅当前置知识点全部 completed 才允许提交
- [ ] 更新 train_preview_record.status = completed
- [ ] 更新 completed_at
- [ ] 所有知识点 completed → 自动更新 train_task.status = practice
- [ ] 触发 Docker 容器创建(如果还未创建)
---
#### 3.3.3 提交预习小测
```
POST /api/v1/training/preview/{taskId}/quiz
```
**请求参数**:
```json
{
"knowledgeId": 1,
"answers": [
{"questionId": 1, "answer": "B"},
{"questionId": 2, "answer": "A"}
]
}
```
**响应**:
```json
{
"code": 0,
"data": {
"knowledgeId": 1,
"score": 85,
"passStatus": 1,
"correctCount": 17,
"totalCount": 20,
"analysis": "..."
}
}
```
**验收标准**:
- [ ] 得分 ≥ 60 视为通过(pass_status = 1)
- [ ] 记录 train_preview_quiz
- [ ] 多次答题保留历史最高分
- [ ] 答题通过后前端解锁下一个知识点
---
#### 3.3.4 获取小测题目
```
GET /api/v1/training/preview/{taskId}/quiz/{knowledgeId}
```
**响应**:
```json
{
"code": 0,
"data": {
"knowledgeId": 1,
"knowledgeName": "RESTful API 设计",
"questions": [
{
"id": 1,
"type": "choice",
"content": "以下哪个 HTTP 方法最适合用于更新资源?",
"options": [
{"label": "A", "content": "POST"},
{"label": "B", "content": "PUT"},
{"label": "C", "content": "GET"},
{"label": "D", "content": "DELETE"}
]
}
]
}
}
```
> **小测题目来源**:由 project-module 调用 ai-service 生成,存入 training 模块数据库或由 ai-service 管理。
---
### 3.4 实操管理接口(/api/v1/training/practice)
#### 3.4.1 获取容器访问信息(STUDENT)
```
GET /api/v1/training/practice/{taskId}/container
```
**响应**:
```json
{
"code": 0,
"data": {
"containerId": "container-abc123",
"codeServerUrl": "http://localhost:30000",
"expiresAt": "2026-07-20 23:59:59",
"projectSourceUrl": "https://github.com/seed/repo",
"readmeUrl": "https://xxx/readme.pdf"
}
}
```
**验收标准**:
- [ ] 仅在 status = practice 时可访问
- [ ] 返回 code-server 访问地址
- [ ] 返回源码挂载路径(只读)
- [ ] 容器过期前 24h 提醒续期
---
#### 3.4.2 提交实操产物(STUDENT)
```
POST /api/v1/training/practice/{taskId}/artifacts
```
**请求参数**:multipart/form-data 或 JSON
```json
{
"artifactType": "code_repo",
"content": "https://github.com/user/my-project",
"file": null
}
```
**验收标准**:
- [ ] 仅在 status = practice 时可提交
- [ ] artifactType 为必填
- [ ] code_repo 类型 content 为 GitHub 地址
- [ ] screenshot/log_file 类型支持文件上传至 MinIO
- [ ] 产物数量 ≥ 1 才能提交报告
- [ ] 自动记录提交时间
---
#### 3.4.3 提交实操报告(STUDENT)
```
POST /api/v1/training/practice/{taskId}/report
```
**请求参数**:
```json
{
"processDescription": "本周完成了 RESTful API 的设计和实现...",
"resultDescription": "成功实现了用户管理的增删改查接口...",
"isSubmit": true
}
```
**验收标准**:
- [ ] processDescription 和 resultDescription 必填,最少 50 字
- [ ] isSubmit = true 时提交(status → submitted),isSubmit = false 保存草稿
- [ ] 提交后自动更新 train_task.status = report
- [ ] 同时更新 practice_submitted_at
---
#### 3.4.4 上报错误日志(沙箱自动调用)
```
POST /api/v1/training/practice/{taskId}/error-logs
```
**请求参数**:
```json
{
"logContent": "Exception in thread 'main' java.lang.NullPointerException...",
"errorType": "NullPointerException",
"severity": "high"
}
```
**验收标准**:
- [ ] 沙箱 agent 定时上报
- [ ] 存入 train_error_log
- [ ] 错误数 ≥ 3 时高亮提示导师
- [ ] 错误日志用于后续 AI 缺陷分析
---
### 3.5 答辩管理接口(/api/v1/training/defense)
#### 3.5.1 申请答辩(STUDENT)
```
POST /api/v1/training/defense/apply
```
**请求参数**:
```json
{
"taskId": 1
}
```
**前置条件检查**:
- [ ] 任务状态 = report
- [ ] 产物数量 ≥ 1
- [ ] 报告已提交
- [ ] 未有进行中的答辩申请
**验收标准**:
- [ ] 创建 train_defense_application(status = pending)
- [ ] 更新 train_task.status = defense_pending
- [ ] 更新 defense_applied_at
- [ ] 向导师发送站内通知(notify_module)
- [ ] 发送邮件通知(可选)
---
#### 3.5.2 获取答辩待办列表(MENTOR)
```
GET /api/v1/training/defense/pending
```
**请求参数**:page / size / department_id(可选)
**响应**:
```json
{
"code": 0,
"data": {
"total": 5,
"items": [
{
"taskId": 1,
"studentName": "张三",
"projectName": "Spring Boot REST API 实战",
"cycleNumber": 1,
"appliedAt": "2026-07-10 09:00:00",
"artifactsCount": 3,
"defectCount": 2
}
]
}
}
```
---
#### 3.5.3 开始答辩(MENTOR)
```
POST /api/v1/training/defense/{taskId}/start
```
**验收标准**:
- [ ] 仅 pending 状态的申请可开始
- [ ] 更新 train_task.status = defense
- [ ] 记录开始时间
---
#### 3.5.4 提交答辩评审(MENTOR)
```
POST /api/v1/training/defense/{taskId}/review
```
**请求参数**:
```json
{
"totalScore": 85.5,
"dimensionScores": [
{"dimension": "代码质量", "score": 28, "maxScore": 30},
{"dimension": "功能完整性", "score": 27, "maxScore": 30},
{"dimension": "问题解答", "score": 18, "maxScore": 20},
{"dimension": "创新能力", "score": 12, "maxScore": 20}
],
"comment": "代码结构清晰,注释充分...",
"result": "pass"
}
```
> result = pass(通过)或 reject(驳回)
**通过时的处理**:
- [ ] 创建 train_defense_review(result = pass)
- [ ] 更新 train_task.status = supervisor_review
- [ ] 更新 defense_completed_at
- [ ] 通知学员 + 主管
**驳回时的处理**:
- [ ] 创建 train_defense_review(result = reject)
- [ ] 更新 train_task.status = rejected
- [ ] 记录驳回原因
- [ ] 触发缺陷记录 + 画像更新
- [ ] 通知学员修改后重提
---
#### 3.5.5 获取答辩评审详情
```
GET /api/v1/training/defense/{taskId}/review
```
**响应**:
```json
{
"code": 0,
"data": {
"taskId": 1,
"mentor": {"id": 5, "realName": "李导师"},
"totalScore": 85.5,
"dimensionScores": [
{"dimension": "代码质量", "score": 28, "maxScore": 30}
],
"comment": "...",
"result": "pass",
"createdAt": "2026-07-12 16:00:00"
}
}
```
---
### 3.6 缺陷与进阶匹配接口(/api/v1/training/advanced)
#### 3.6.1 获取历史缺陷列表(STUDENT/MENTOR)
```
GET /api/v1/training/advanced/{taskId}/defects
```
**响应**:
```json
{
"code": 0,
"data": {
"taskId": 1,
"total": 3,
"items": [
{
"id": 1,
"knowledgeName": "异常处理",
"severity": "medium",
"source": "error_log",
"description": "未对空指针做处理...",
"createdAt": "2026-07-10 14:00:00"
}
]
}
}
```
---
#### 3.6.2 手动添加缺陷记录(MENTOR)
```
POST /api/v1/training/advanced/{taskId}/defects
```
**请求参数**:
```json
{
"knowledgeId": 5,
"severity": "high",
"source": "mentor_review",
"description": "学员在答辩中对分布式事务理解不足..."
}
```
---
#### 3.6.3 触发 AI 进阶匹配(系统自动)
```
POST /api/v1/training/advanced/match
```
**触发时机**:
1. 答辩驳回后自动触发
2. 主管驳回后自动触发
3. 学员手动申请
**请求参数**:
```json
{
"taskId": 1,
"userId": 10
}
```
**AI 匹配流程**:
```
1. 收集缺陷数据:
- train_defect_record(薄弱知识点)
- train_error_log(沙箱报错)
- train_defense_review(答辩意见)
2. 构建能力画像:
- 查询 train_skill_profile
- 分析薄弱点 + 历史难度
3. 调用 ai-service /ai/advanced-match:
- 输入:薄弱知识点列表、能力画像、当前难度
- 输出:推荐项目 + 匹配度 + 理由
4. 记录 train_advanced_match
5. 通知学员
```
**响应**:
```json
{
"code": 0,
"message": "匹配完成",
"data": {
"matchId": 1,
"project": {
"id": 15,
"name": "分布式事务实战",
"difficultyLevel": "L4",
"matchReason": "该学员在异常处理和事务管理方面存在不足,L4 难度项目可针对性补强..."
},
"matchScore": 0.8745,
"defects": ["异常处理", "事务管理"]
}
}
```
**验收标准**:
- [ ] 异步处理,不阻塞主流程
- [ ] 匹配完成后更新 train_advanced_match
- [ ] 通知学员有新推荐
- [ ] 匹配置信度过低(<0.5)时给出提示
---
#### 3.6.4 采纳进阶推荐(STUDENT)
```
POST /api/v1/training/advanced/{matchId}/accept
```
**验收标准**:
- [ ] 更新 match.status = accepted
- [ ] 创建新任务(train_task,cycle_number + 1)
- [ ] 通知学员新任务已创建
---
#### 3.6.5 忽略进阶推荐(STUDENT)
```
POST /api/v1/training/advanced/{matchId}/reject
```
**验收标准**:
- [ ] 更新 match.status = rejected
- [ ] 可重新发起匹配
---
### 3.7 能力画像接口(/api/v1/training/profile)
#### 3.7.1 获取学员能力画像(STUDENT/MENTOR/SUPERVISOR)
```
GET /api/v1/training/profile/{userId}
```
**响应**:
```json
{
"code": 0,
"data": {
"userId": 10,
"userName": "张三",
"overallLevel": "L3",
"totalTasks": 3,
"totalCycles": 5,
"avgDefenseScore": 82.5,
"skillRadar": {
"labels": ["Java", "Spring Boot", "数据库", "异常处理", "分布式"],
"scores": [0.85, 0.78, 0.72, 0.55, 0.40]
},
"knowledgeMastery": [
{
"knowledgeId": 1,
"knowledgeName": "RESTful API 设计",
"masteryLevel": 0.85,
"lastAssessedAt": "2026-07-12 16:00:00"
}
],
"weakPoints": [
{"knowledgeName": "分布式事务", "severity": "high", "occurrences": 3}
],
"strongPoints": [
{"knowledgeName": "RESTful API 设计", "masteryLevel": 0.85}
]
}
}
```
**画像更新时机**:
- [ ] 每次小测完成后
- [ ] 每次答辩评审完成后
- [ ] 每次缺陷记录新增时
---
### 3.8 导师工作台接口(/api/v1/training/mentor)
#### 3.8.1 导师待办统计
```
GET /api/v1/training/mentor/dashboard
```
**响应**:
```json
{
"code": 0,
"data": {
"defensePendingCount": 3,
"defenseInProgressCount": 1,
"totalStudentCount": 15,
"defensePassRate": 78.5,
"recentDefects": [
{"knowledgeName": "异常处理", "count": 5, "avgSeverity": "medium"}
]
}
}
```
---
#### 3.8.2 导师分配/变更(ADMIN)
```
PUT /api/v1/training/tasks/{taskId}/mentor
```
**请求参数**:
```json
{
"mentorId": 5
}
```
---
## 四、功能点拆解 & 验收标准
### 4.1 实训任务管理
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 创建实训任务 | 学员选择项目后创建任务 | P0 |
| 2 | 任务列表 | 我的任务 / 全部任务(分页+筛选) | P0 |
| 3 | 任务详情 | 完整任务信息含各阶段数据 | P0 |
| 4 | 任务流转历史 | 状态变化时间线 | P1 |
| 5 | 导师分配 | 手动分配 / 自动分配 | P0 |
| 6 | 状态自动推进 | 满足条件时自动更新状态 | P0 |
**验收标准**:
```
[ ] 同一学员 + 同一项目不允许重复创建(除非上一轮已完成)
[ ] 状态变更自动记录 system_flow_event
[ ] 状态推进规则严格校验,防止越级跳转
[ ] 导师分配支持手动变更
```
---
### 4.2 预习管理
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 知识点列表 | 项目关联的知识点 + 状态 | P0 |
| 2 | 前置依赖校验 | 未完成前置不允许提交 | P0 |
| 3 | 提交预习完成 | 更新记录 + 自动推进状态 | P0 |
| 4 | 小测答题 | 提交答案 → 返回得分 | P0 |
| 5 | 小测题目获取 | 获取指定知识点小测 | P0 |
| 6 | 预习进度统计 | 百分比 / 已完成数 | P1 |
**验收标准**:
```
[ ] 知识点按依赖顺序排列(无前置 → 有前置)
[ ] 前置知识点 status = completed 才允许提交当前
[ ] 得分 ≥ 60 更新 pass_status = 1
[ ] 全部知识点 completed → train_task.status → practice
[ ] 多次答题保留历史最高分
```
---
### 4.3 实操管理
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 容器沙箱访问 | 获取 code-server 地址 | P0 |
| 2 | 产物提交 | 多种类型(代码/截图/日志) | P0 |
| 3 | 报告撰写 | 过程记录 + 结果说明 | P0 |
| 4 | 报告提交 | draft/submitted 两种状态 | P0 |
| 5 | 错误日志上报 | 沙箱自动上报 | P1 |
| 6 | 容器续期 | 延长容器使用时间 | P2 |
**容器沙箱流程**:
```
创建容器(异步):
1. 基于项目 docker_image 镜像
2. 挂载源码目录(只读)
3. 分配 code-server 端口
4. 返回 container_id + code_server_url
销毁容器:
1. 任务完成/取消时触发
2. 导出学员代码到 MinIO(备份)
3. 销毁容器
```
**验收标准**:
```
[ ] 仅 status = practice 可访问容器
[ ] 容器启动失败不影响任务继续(记录 warning)
[ ] 产物类型支持:code_repo/screenshot/log_file/output/document
[ ] 报告 process_description + result_description 最少各 50 字
[ ] isSubmit=true 提交后自动更新状态
```
---
### 4.4 答辩管理
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 申请答辩 | 一键申请 → 通知导师 | P0 |
| 2 | 待办列表 | 导师查看待答辩任务 | P0 |
| 3 | 开始答辩 | 导师确认开始 | P0 |
| 4 | 提交评审 | 评分 + 意见 + 结论 | P0 |
| 5 | 答辩详情 | 查看评审结果 | P0 |
| 6 | 评审历史 | 查看往次答辩记录 | P1 |
**验收标准**:
```
[ ] 申请前检查:产物≥1、报告已提交、无进行中申请
[ ] 评审结果 pass → 自动推进到 supervisor_review
[ ] 评审结果 reject → 推进到 rejected + 记录缺陷
[ ] 维度评分总和 = 100 分
[ ] 通知:答辩申请/开始/结果均通知相关人
```
---
### 4.5 缺陷与进阶匹配
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 缺陷列表 | 按任务查看所有缺陷 | P0 |
| 2 | 手动添加缺陷 | 导师补充缺陷记录 | P0 |
| 3 | AI 进阶匹配 | 基于缺陷 + 画像推荐项目 | P0 |
| 4 | 采纳/忽略推荐 | 学员操作推荐结果 | P0 |
| 5 | 匹配历史 | 查看历史推荐 | P1 |
**AI 匹配逻辑**:
```
输入:
- 薄弱知识点列表(train_defect_record)
- 错误日志聚合(train_error_log)
- 答辩意见摘要(train_defense_review.comment)
- 当前项目难度(proj_internal_project.difficulty_level)
- 画像熟练度(train_skill_profile)
输出:
- 推荐项目(train_advanced_match.matched_project_id)
- 匹配度(0-1)
- 理由(为什么推荐该项目)
- 针对性(覆盖了哪些薄弱点)
匹配条件:
- 相似难度(±1 级)
- 覆盖薄弱知识点
- 未被该学员已完成
```
**验收标准**:
```
[ ] 驳回后自动触发 AI 进阶匹配
[ ] 匹配结果记录到 train_advanced_match
[ ] 采纳后自动创建新一轮任务(cycle_number + 1)
[ ] 匹配置信度 < 0.5 时提示导师复核
```
---
### 4.6 能力画像
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 画像数据聚合 | 按学员聚合知识点熟练度 | P0 |
| 2 | 画像更新 | 小测/答辩后自动更新 | P0 |
| 3 | 雷达图数据 | 各知识点熟练度 | P1 |
| 4 | 薄弱/强项分析 | 自动计算 | P1 |
**验收标准**:
```
[ ] 画像更新时机:小测完成、答辩完成、缺陷新增
[ ] 熟练度 = 加权平均(最新得分 70% + 历史 30%)
[ ] 支持按学员维度查看所有历史评估
```
---
## 五、容器沙箱技术实现
### 5.1 容器管理服务
```java
@Service
public class ContainerService {
@Value("${docker.host:tcp://localhost:2375}")
private String dockerHost;
public ContainerInfo createContainer(Long taskId, String imageName) {
DockerClient client = DockerClientFactory.getClient(dockerHost);
// 1. 创建网络(隔离)
Network network = client.createNetwork(
NetworkConfig.builder()
.name("training-net-" + taskId)
.driver("bridge")
.build()
);
// 2. 创建容器
CreateContainerResponse container = client.createContainer(
CreateContainerCmd.class,
imageName,
ContainerConfig.builder()
.hostConfig(HostConfig.builder()
.memory(1024 * 1024 * 1024L) // 1GB
.cpuShares(512)
.binds(
"/training/readonly/code:/app:ro",
"/training/workspaces/" + taskId + ":/workspace:rw"
)
.networkDisabled(false)
.networkMode(network.getId())
.build())
.env("TASK_ID=" + taskId)
.exposedPorts(ExposedPorts.tcpPort(3000))
.build(),
ContainerConfig.class,
"training-task-" + taskId
);
client.startContainerCmd(container.getId()).exec();
// 3. 等待 code-server 启动
String codeServerUrl = waitForCodeServer(container.getId());
return new ContainerInfo(container.getId(), codeServerUrl);
}
public void destroyContainer(String containerId) {
DockerClient client = DockerClientFactory.getClient(dockerHost);
// 1. 备份工作目录到 MinIO
backupWorkspace(containerId);
// 2. 停止并删除容器
client.stopContainerCmd(containerId).exec();
client.removeContainerCmd(containerId).exec();
}
}
```
### 5.2 错误日志采集
```java
// 沙箱内 agent 定时执行
@Component
public class ErrorLogCollector {
public void collect(Long taskId) {
String containerId = taskService.getContainerId(taskId);
// 读取容器日志(最近 5 分钟)
String logs = dockerClient.logs(containerId,
LogsStatsDescriptor.In(LogsConfig.STDOUT, LogsConfig.STDERR),
new SinceTimestamps(System.currentTimeMillis() - 300000)
);
// 分析错误日志
List<ErrorEntry> errors = parseErrors(logs);
for (ErrorEntry error : errors) {
errorLogRepository.save(TrainErrorLog.builder()
.taskId(taskId)
.logContent(error.getContent())
.errorType(error.getType())
.severity(calculateSeverity(error))
.build());
}
}
}
```
---
## 六、AI 服务接口(ai-service)
### 6.1 进阶匹配
```
POST /ai/advanced-match
```
**请求**:
```json
{
"user_id": 10,
"weak_knowledge_ids": [5, 8, 12],
"error_summary": "NullPointerException 3次,事务超时 1次",
"current_difficulty": "L3",
"defense_comments": "异常处理不够完善,对分布式事务理解不足",
"exclude_project_ids": [1, 3, 7]
}
```
**响应**:
```json
{
"success": true,
"data": {
"recommended_project_id": 15,
"match_score": 0.8745,
"match_reason": "该项目覆盖了学员薄弱的异常处理、事务管理知识点,难度 L4 略高于当前 L3,适合作为进阶项目针对性补强。",
"covered_weak_points": ["异常处理", "分布式事务"]
}
}
```
### 6.2 小测题目生成
```
POST /ai/quiz/generate
```
**请求**:
```json
{
"knowledge_id": 1,
"knowledge_name": "RESTful API 设计",
"difficulty": "medium",
"count": 5
}
```
**响应**:
```json
{
"success": true,
"data": {
"questions": [
{
"id": "q-001",
"type": "choice",
"content": "以下哪个 HTTP 方法最适合用于更新资源?",
"options": [
{"label": "A", "content": "POST"},
{"label": "B", "content": "PUT"},
{"label": "C", "content": "GET"},
{"label": "D", "content": "DELETE"}
],
"correct_answer": "B",
"analysis": "PUT 方法用于更新已存在的资源..."
}
]
}
}
```
---
## 七、任务优先级
### P0(必须完成)
| 序号 | 任务 | 模块 |
|------|------|------|
| 1 | 实训任务 CRUD + 状态流转 | 任务管理 |
| 2 | 任务列表 + 详情接口 | 任务管理 |
| 3 | 预习知识点列表 + 前置依赖 | 预习 |
| 4 | 提交预习完成 + 状态推进 | 预习 |
| 5 | 小测答题 + 得分记录 | 预习 |
| 6 | 容器沙箱创建/销毁服务 | 沙箱 |
| 7 | 产物提交(多类型) | 实操 |
| 8 | 实操报告撰写 + 提交 | 实操 |
| 9 | 答辩申请 + 通知导师 | 答辩 |
| 10 | 导师待办列表 + 评审提交 | 答辩 |
| 11 | 答辩结果处理(通过/驳回) | 答辩 |
| 12 | 缺陷记录 + 画像更新 | 缺陷 |
| 13 | AI 进阶匹配调用 | 进阶 |
| 14 | 采纳/忽略推荐 + 新任务创建 | 进阶 |
### P1(核心功能)
| 序号 | 任务 | 模块 |
|------|------|------|
| 15 | 能力画像聚合 + 展示 | 画像 |
| 16 | 小测题目获取接口 | 预习 |
| 17 | 错误日志上报 + 聚合 | 沙箱 |
| 18 | 导师工作台统计 | 导师 |
| 19 | 任务流转历史 | 任务管理 |
| 20 | 导师分配/变更 | 任务管理 |
### P2(完善功能)
| 序号 | 任务 | 模块 |
|------|------|------|
| 21 | 容器续期管理 | 沙箱 |
| 22 | 能力画像雷达图数据 | 画像 |
| 23 | 答辩历史记录 | 答辩 |
| 24 | 匹配历史记录 | 进阶 |
---
## 八、开发顺序建议
```
第一周:任务管理 + 预习(核心流程打通)
├── 1. 实训任务 CRUD + 状态机
├── 2. 任务列表 + 详情
├── 3. 预习知识点列表(从 project-module 获取)
├── 4. 提交预习完成 + 状态推进
├── 5. 导师自动分配
└── 6. 流转历史记录
第二周:实操 + 沙箱 + 答辩
├── 1. Docker 容器沙箱服务
├── 2. 产物提交(多类型)
├── 3. 实操报告撰写 + 提交
├── 4. 答辩申请 + 通知
├── 5. 导师评审提交(通过/驳回)
├── 6. 驳回后的缺陷记录
└── 7. 小测答题 + 得分
第三周:进阶 + 画像 + AI 集成
├── 1. AI 进阶匹配调用
├── 2. 采纳推荐 → 新任务创建
├── 3. 能力画像聚合
├── 4. 错误日志采集
├── 5. 主管审核对接(audit-module)
├── 6. 单元测试 + 集成测试
└── 7. 沙箱备份与恢复
```
---
## 九、交付物清单
| 序号 | 交付物 | 说明 |
|------|--------|------|
| 1 | 数据库脚本 | train_ 系列 JPA Entity |
| 2 | 后端接口 | 全部 API 接口 |
| 3 | 容器沙箱服务 | Docker Java Client 封装 |
| 4 | AI 服务封装 | 进阶匹配 / 小测生成 |
| 5 | 状态机 | train_task 状态流转逻辑 |
| 6 | 单元测试 | 覆盖率 ≥ 80% |
| 7 | 接口文档 | Swagger / OpenAPI |
---
## 十、与其他模块的接口
### 10.1 被调用接口(供其他模块调用)
| 接口 | 调用方 | 说明 |
|------|--------|------|
| GET /tasks/{taskId} | audit-module | 主管审核时获取任务详情 |
| GET /profile/{userId} | audit-module | 获取学员能力画像 |
| POST /defense/apply | 前端 | 学员申请答辩 |
| GET /mentor/dashboard | 前端 | 导师工作台 |
### 10.2 调用其他模块接口
| 接口 | 被调用方 | 说明 |
|------|----------|------|
| GET /projects/{id} | project-module | 获取项目详情 |
| GET /knowledge-points | project-module | 获取知识点列表 |
| GET /users/{id} | user-module | 获取导师/学员信息 |
| GET /users/me | user-module | 获取当前用户信息 |
| POST /notify/send | notify-module | 发送站内通知 |
| AI /ai/advanced-match | ai-service | 进阶项目匹配 |
| AI /ai/quiz/generate | ai-service | 小测题目生成 |
| POST /audit/supervisor-review | audit-module | 答辩通过后提交主管审核 |
---
## 十一、风险与注意事项
| 风险 | 影响 | 应对 |
|------|------|------|
| 容器沙箱启动失败 | 学员无法实操 | 异步创建,失败不影响任务,允许重试 |
| 容器资源耗尽 | 宿主机崩溃 | 内存/CPU 上限,每个容器独立网络 |
| AI 进阶匹配失败 | 学员无法继续 | Fallback:基于规则的简单匹配(难度相近) |
| 状态机越级跳转 | 数据不一致 | 严格前置条件校验,异常抛错 |
| 容器数据丢失 | 学员代码丢失 | 实时备份到 MinIO,销毁前导出 |
| 并发答辩评审 | 数据冲突 | 乐观锁 + 状态校验 |
---
*文档结束*
# 用户模块(user-module)开发任务文档
> 文档版本:v1.0
> 创建时间:2026-07-14
> 负责人:(待填写)
> 状态:待开发
---
## 一、模块概述
### 1.1 模块职责
用户模块是系统的基础模块,负责:
- 用户身份认证与授权(JWT 双 Token)
- 用户信息管理(注册 / 信息维护 / 软删除)
- 角色权限管理(RBAC — 多角色支持)
- 安全机制保障(登录锁定 / 密码加密 / 短信验证码)
- 登录日志记录
- 动态菜单生成
### 1.2 技术栈
| 技术 | 版本 | 用途 |
|------|------|------|
| Spring Boot | 3.x | 基础框架 |
| Spring Security | 6.x | 安全框架 |
| Spring Data JPA | 3.x | ORM |
| Redis | 7.x | 缓存/会话/验证码/Token 黑名单 |
| JWT (jjwt) | 0.12.x | Token 生成与校验 |
| BCrypt | - | 密码加密(cost = 12) |
| validation | 3.x | 参数校验 |
### 1.3 模块依赖
```
user-module
├── 依赖:Redis(Token 存储、验证码、菜单缓存)
├── 依赖:MySQL(用户数据)
└── 被依赖:所有业务模块(权限校验、认证)
```
---
## 二、数据表设计
> **数据库来源**:数据库设计V1.md
> **开发前必读**:user_ 开头的表为本模块负责的数据库表。
### 2.1 ER 图
```
┌─────────────┐ ┌─────────────────┐ ┌──────────────┐
│ user_user │──────<│ user_user_role │>──────│ user_role │
└─────────────┘ └─────────────────┘ └──────┬───────┘
│ │
│ ┌─────────────────┐ │
└─────────────<│user_role_permission│>────────┘
└─────────────────┘
▲
│
┌──────────────┐
│user_permission│
└──────────────┘
┌──────────────┐ ┌─────────────────┐
│ user_user │──────<│ user_login_log │
└──────────────┘ └─────────────────┘
```
### 2.2 表结构
#### 2.2.1 用户表(user_user)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| username | VARCHAR(50) | UNIQUE, NOT NULL | 用户名 |
| password | VARCHAR(255) | NOT NULL | bcrypt 加密密码 |
| real_name | VARCHAR(50) | NOT NULL | 真实姓名 |
| email | VARCHAR(100) | | 邮箱 |
| phone | VARCHAR(20) | | 手机号 |
| role_id | BIGINT | FK → user_role | 角色(多角色通过 user_user_role) |
| department_id | BIGINT | FK → user_department | 所属部门 |
| avatar_url | VARCHAR(500) | | 头像 |
| status | TINYINT | DEFAULT 1 | 0=禁用 1=启用 |
| created_at | DATETIME | | 创建时间 |
> **说明**:role_id 字段保留用于单角色快速查询;多角色场景通过 user_user_role 关联表处理。
**索引**:(role_id),(department_id)
---
#### 2.2.2 角色表(user_role)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| role_name | VARCHAR(50) | NOT NULL | 角色名称 |
| description | VARCHAR(200) | | 角色描述 |
| created_at | DATETIME | | 创建时间 |
**预置角色**:
| role_name | 说明 |
|----------|------|
| ADMIN | 管理员:全系统配置、用户管理 |
| SUPERVISOR | 主管:审核学员、内容终审 |
| MENTOR | 导师:答辩评审、学员指导 |
| STUDENT | 学员:参与实训、提交产物 |
---
#### 2.2.3 权限点表(user_permission)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| permission_code | VARCHAR(50) | UNIQUE, NOT NULL | 权限编码 |
| permission_name | VARCHAR(100) | NOT NULL | 权限名称 |
| module | VARCHAR(50) | NOT NULL | 所属模块:project/training/defense/audit/user |
| description | VARCHAR(200) | | 权限说明 |
| created_at | DATETIME | | 创建时间 |
**权限码规范**:`模块:操作`,示例:
| permission_code | 说明 |
|----------------|------|
| project:read | 查看项目 |
| project:create | 创建项目 |
| project:update | 更新项目 |
| project:delete | 删除项目 |
| training:read | 查看实训 |
| training:submit | 提交实训 |
| defense:review | 答辩评审 |
| audit:review | 主管审核 |
---
#### 2.2.4 角色权限关联表(user_role_permission)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| role_id | BIGINT | FK → user_role | 角色 |
| permission_id | BIGINT | FK → user_permission | 权限 |
| created_at | DATETIME | | 创建时间 |
**唯一索引**:(role_id, permission_id)
---
#### 2.2.5 用户角色关联表(user_user_role)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| user_id | BIGINT | FK → user_user | 用户 |
| role_id | BIGINT | FK → user_role | 角色 |
| created_at | DATETIME | | 创建时间 |
**唯一索引**:(user_id, role_id)
---
#### 2.2.6 部门表(user_department)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| name | VARCHAR(100) | NOT NULL | 部门名称 |
| code | VARCHAR(50) | UNIQUE | 部门编码:tech/annotation |
| description | VARCHAR(500) | | 说明 |
---
#### 2.2.7 登录日志表(user_login_log)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| user_id | BIGINT | FK → user_user | 用户 ID |
| username | VARCHAR(50) | NOT NULL | 登录账号 |
| ip | VARCHAR(50) | | IP 地址 |
| device | VARCHAR(100) | | 设备信息 |
| location | VARCHAR(100) | | 登录地点 |
| status | TINYINT | NOT NULL | 1=成功 2=失败 |
| fail_reason | VARCHAR(100) | | 失败原因 |
| created_at | DATETIME | | 登录时间 |
**索引**:(user_id),(created_at)
---
#### 2.2.8 短信验证码表(user_sms_code)
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| phone | VARCHAR(20) | NOT NULL | 手机号 |
| code | VARCHAR(10) | NOT NULL | 验证码 |
| type | VARCHAR(20) | NOT NULL | 用途:login/register/reset |
| ip | VARCHAR(50) | NOT NULL | 请求 IP |
| expire_time | DATETIME | NOT NULL | 过期时间 |
| is_used | TINYINT | DEFAULT 0 | 是否已使用 |
| created_at | DATETIME | | 创建时间 |
**索引**:(phone, type)
---
## 三、API 接口设计
### 3.1 统一规范
#### 3.1.1 统一响应格式
```json
{
"code": 0,
"message": "操作成功",
"data": {}
}
```
**状态码定义**:
| 区间 | 说明 |
|------|------|
| 0 | 成功 |
| 1xxx | 通用错误(1001=参数错误,1002=未登录,1003=无权限) |
| 2xxx | 业务错误(2001=用户不存在,2002=手机号已注册) |
#### 3.1.2 分页响应格式
```json
{
"code": 0,
"data": {
"total": 100,
"page": 1,
"size": 10,
"items": []
}
}
```
---
### 3.2 认证接口(/api/v1/auth)
#### 3.2.1 登录
```
POST /api/v1/auth/login
```
**请求参数**:
```json
{
"username": "admin",
"password": "admin123"
}
```
**响应参数**:
```json
{
"code": 0,
"message": "登录成功",
"data": {
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 7200,
"tokenType": "Bearer",
"user": {
"id": 1,
"username": "admin",
"realName": "管理员",
"roles": ["ADMIN"]
}
}
}
```
**验收标准**:
- [ ] 输入正确账号密码,返回 accessToken + refreshToken
- [ ] accessToken 有效期 2 小时
- [ ] refreshToken 有效期 7 天
- [ ] 密码错误返回"账号或密码错误"(不暴露具体原因)
- [ ] 登录成功清除错误计数
- [ ] 记录登录日志(user_login_log)
- [ ] 登录失败超过 5 次锁定 30 分钟
---
#### 3.2.2 刷新 Token
```
POST /api/v1/auth/refresh
```
**请求参数**:
```json
{
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
**响应参数**:
```json
{
"code": 0,
"message": "刷新成功",
"data": {
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 7200
}
}
```
**验收标准**:
- [ ] refreshToken 有效时返回新的 accessToken
- [ ] refreshToken 过期或黑名单返回 401
---
#### 3.2.3 注册
```
POST /api/v1/auth/register
```
**请求参数**:
```json
{
"username": "zhangsan",
"phone": "13800138000",
"password": "Aa123456",
"realName": "张三"
}
```
**验收标准**:
- [ ] 手机号格式校验:11 位,1 开头
- [ ] 密码强度:至少 8 位,大小写字母 + 数字
- [ ] 验证码 6 位数字,5 分钟有效(走 Redis)
- [ ] 已注册手机号返回"该手机号已注册"
- [ ] 新用户默认角色为"学员"(STUDENT)
- [ ] 密码数据库存储为 bcrypt 加密字符串
---
#### 3.2.4 登出
```
POST /api/v1/auth/logout
```
**请求头**:`Authorization: Bearer {accessToken}`
**验收标准**:
- [ ] refreshToken 加入 Redis 黑名单
- [ ] 登出后 Token 无法使用
---
#### 3.2.5 发送验证码
```
POST /api/v1/auth/sms-code
```
**请求参数**:
```json
{
"phone": "13800138000",
"type": "register"
}
```
**type 可选值**:login / register / reset
**验收标准**:
- [ ] 60 秒内同一手机号只能发送一次
- [ ] 验证码 5 分钟有效(Redis key = `sms:{phone}:{type}`)
- [ ] 单 IP 1 小时最多 10 次
- [ ] 记录发送日志(不含验证码内容)
---
#### 3.2.6 找回密码
```
POST /api/v1/auth/reset-password
```
**请求参数**:
```json
{
"phone": "13800138000",
"smsCode": "123456",
"newPassword": "Aa123456"
}
```
**验收标准**:
- [ ] 验证码正确且未过期
- [ ] 验证码使用后立即失效
- [ ] 新密码加密存储
---
### 3.3 用户管理接口(/api/v1/users)
#### 3.3.1 获取当前用户
```
GET /api/v1/users/me
```
**响应参数**:
```json
{
"code": 0,
"data": {
"id": 1,
"username": "admin",
"realName": "管理员",
"email": "admin@example.com",
"phone": "138****8000",
"avatar": "https://xxx.com/avatar.jpg",
"roles": ["ADMIN"],
"permissions": ["project:*", "user:*", "training:*"],
"lastLoginTime": "2026-07-14 10:00:00",
"createdAt": "2026-01-01 00:00:00"
}
}
```
**验收标准**:
- [ ] 返回当前登录用户完整信息
- [ ] 密码字段不返回
- [ ] 敏感字段脱敏展示(手机号 138****8000)
- [ ] 包含角色和权限列表
---
#### 3.3.2 获取用户详情
```
GET /api/v1/users/{id}
```
**验收标准**:
- [ ] 敏感字段脱敏
- [ ] 返回用户完整角色信息
---
#### 3.3.3 更新用户信息
```
PUT /api/v1/users/{id}
```
**请求参数**:
```json
{
"realName": "张三新版",
"avatar": "https://xxx.com/new-avatar.jpg",
"email": "zhangsan@example.com"
}
```
**验收标准**:
- [ ] 仅本人或 ADMIN 可更新
- [ ] 更新手机号需验证码
- [ ] 更新后同步刷新 Redis 缓存
---
#### 3.3.4 修改密码
```
PUT /api/v1/users/{id}/password
```
**请求参数**:
```json
{
"oldPassword": "Aa123456",
"newPassword": "Aa654321"
}
```
**验收标准**:
- [ ] 旧密码正确校验
- [ ] 新密码强度校验
- [ ] 不可与最近 3 次密码相同
- [ ] 修改后 Token 刷新
---
#### 3.3.5 用户列表(ADMIN)
```
GET /api/v1/users
```
**请求参数**:page / size / keyword / role_id / department_id / status
**验收标准**:
- [ ] 支持分页查询
- [ ] 关键词搜索:姓名/用户名/手机号模糊匹配
- [ ] 角色筛选 / 部门筛选 / 状态筛选
---
### 3.4 角色权限接口(/api/v1/roles)
#### 3.4.1 获取角色列表
```
GET /api/v1/roles
```
**响应**:
```json
{
"code": 0,
"data": [
{
"id": 1,
"roleName": "管理员",
"description": "全系统配置、用户管理",
"isPreset": true,
"userCount": 5
}
]
}
```
---
#### 3.4.2 获取角色详情
```
GET /api/v1/roles/{id}
```
**响应**:
```json
{
"code": 0,
"data": {
"id": 1,
"roleName": "管理员",
"description": "全系统配置",
"isPreset": true,
"permissions": [
{"id": 1, "permissionCode": "project:*", "permissionName": "项目管理"},
{"id": 2, "permissionCode": "user:*", "permissionName": "用户管理"}
]
}
}
```
---
#### 3.4.3 创建角色(ADMIN)
```
POST /api/v1/roles
```
**请求参数**:
```json
{
"roleName": "测试角色",
"description": "测试人员",
"permissionIds": [1, 2, 3]
}
```
**验收标准**:
- [ ] 角色名称唯一
- [ ] 权限关联创建
---
#### 3.4.4 更新角色(ADMIN)
```
PUT /api/v1/roles/{id}
```
**验收标准**:
- [ ] 预置角色不可修改
- [ ] 权限关联更新
- [ ] 刷新用户权限缓存
---
#### 3.4.5 删除角色(ADMIN)
```
DELETE /api/v1/roles/{id}
```
**验收标准**:
- [ ] 预置角色不可删除
- [ ] 有关联用户不可删除
---
### 3.5 菜单权限接口(/api/v1/menus)
#### 3.5.1 获取用户菜单
```
GET /api/v1/menus
```
**响应参数**:
```json
{
"code": 0,
"data": [
{
"id": 1,
"name": "项目管理",
"icon": "project",
"path": "/projects",
"children": [
{"id": 2, "name": "项目列表", "path": "/projects/list", "icon": "list"},
{"id": 3, "name": "标签管理", "path": "/projects/tags", "icon": "tag"}
]
},
{
"id": 10,
"name": "实训管理",
"icon": "training",
"path": "/training"
}
]
}
```
**验收标准**:
- [ ] 根据用户角色返回对应菜单
- [ ] Redis 缓存(key = `menu:{userId}`,TTL = 1 小时)
- [ ] 角色变更时刷新缓存
---
## 四、功能点拆解 & 验收标准
### 4.1 登录模块
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 账号密码登录 | username + password | P0 |
| 2 | JWT 双 Token | accessToken(2h) + refreshToken(7d) | P0 |
| 3 | Token 校验 | 请求拦截校验 JWT | P0 |
| 4 | Token 刷新 | refreshToken 换 accessToken | P0 |
| 5 | 登录日志 | 记录登录行为 | P1 |
| 6 | 登录锁定 | 连续 5 次失败锁定 30 分钟 | P0 |
**验收标准**:
```
[ ] 输入正确账号密码,返回 accessToken + refreshToken
[ ] accessToken 有效期 2 小时,refreshToken 有效期 7 天
[ ] Token 包含用户ID、角色、过期时间签名
[ ] 密码错误时返回"账号或密码错误"
[ ] refreshToken 存储至 Redis,支持主动失效
[ ] 登录成功清除错误计数
[ ] 记录登录日志(user_login_log)
[ ] 连续 5 次密码错误,账号锁定 30 分钟
```
---
### 4.2 注册模块
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 表单校验 | 手机号/邮箱/密码格式校验 | P0 |
| 2 | 验证码校验 | 短信验证码校验 | P0 |
| 3 | 密码加密 | bcrypt 加密存储(cost = 12) | P0 |
| 4 | 重复检测 | 手机号/用户名唯一性 | P0 |
| 5 | 默认角色 | 注册分配"学员"角色 | P0 |
**验收标准**:
```
[ ] 手机号格式:11位数字,1 开头
[ ] 密码强度:至少8位,包含大小写字母+数字
[ ] 验证码错误返回"验证码错误或已过期"
[ ] 已注册手机号返回"该手机号已注册"
[ ] 新用户默认角色为"学员"
[ ] 密码数据库存储为加密字符串
```
---
### 4.3 验证码模块
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 发送验证码 | 生成 6 位数字验证码 | P0 |
| 2 | 防刷限制 | 同一手机 60s 内只能发一次 | P0 |
| 3 | 有效期 | 验证码 5 分钟有效 | P0 |
| 4 | Redis 存储 | key = sms:{phone}:{type},TTL = 5min | P0 |
| 5 | IP 限流 | 单 IP 1 小时最多 10 次 | P1 |
| 6 | 验证码校验 | 一次性使用 | P0 |
| 7 | 错误计数 | 错误 3 次验证码失效 | P1 |
**验收标准**:
```
[ ] 60s 内重复请求同一手机号,返回"请稍后再试"
[ ] 验证码 5 分钟后过期
[ ] 单 IP 1 小时超过 10 次,临时限制
[ ] 验证码正确后自动失效(一次性)
[ ] 验证码错误 3 次后失效
```
---
### 4.4 登出模块
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | Token 失效 | refreshToken 加入 Redis 黑名单 | P0 |
| 2 | Redis 记录 | 黑名单 TTL = accessToken 剩余时间 | P0 |
**验收标准**:
```
[ ] 调用登出接口后,该 refreshToken 无法刷新 Token
[ ] 使用该 Token 的请求返回 401 Unauthorized
```
---
### 4.5 用户 CRUD
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 创建用户 | 管理员添加用户 | P0 |
| 2 | 查询列表 | 分页 + 多条件筛选 | P0 |
| 3 | 查询详情 | 按 ID 查询 | P0 |
| 4 | 更新信息 | 头像/昵称/手机/邮箱 | P0 |
| 5 | 删除用户 | 软删除 | P0 |
| 6 | 修改密码 | 管理员重置/用户自改 | P0 |
| 7 | 个人信息 | 获取当前用户 | P0 |
| 8 | 数据脱敏 | 手机/邮箱脱敏展示 | P1 |
**验收标准**:
```
[ ] 用户列表支持分页
[ ] 用户列表支持筛选:角色、部门、状态、关键词
[ ] 删除用户为软删除(is_deleted=1)
[ ] 被删除用户无法登录
[ ] 更新手机号时需短信验证码确认
[ ] 手机号展示 138****8000 格式
```
---
### 4.6 角色 CRUD
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 创建角色 | 角色 + 权限 | P0 |
| 2 | 查询列表 | 返回所有角色 | P0 |
| 3 | 查询详情 | 角色 + 权限列表 | P0 |
| 4 | 更新角色 | 修改信息/权限 | P0 |
| 5 | 删除角色 | 删除前检查关联 | P0 |
| 6 | 预置保护 | 预置角色不可删改 | P0 |
**验收标准**:
```
[ ] 角色名称唯一性校验
[ ] 删除角色前检查用户关联
[ ] 预置角色(ADMIN/SUPERVISOR/MENTOR/STUDENT)不可删除
[ ] 返回角色列表包含用户数
```
---
### 4.7 权限分配
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 权限列表 | 返回所有权限点 | P0 |
| 2 | 角色权限分配 | 勾选保存关联表 | P0 |
| 3 | 用户角色分配 | 分配用户角色 | P0 |
| 4 | 权限码规范 | 模块:操作格式 | P0 |
**验收标准**:
```
[ ] 权限码格式:模块:操作
[ ] 分配权限后即时生效
[ ] 权限删除前检查角色关联
```
---
### 4.8 动态菜单
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 动态菜单 | 根据角色返回菜单 | P0 |
| 2 | 菜单排序 | 按 sort 排序 | P0 |
| 3 | 菜单缓存 | Redis 缓存 | P1 |
| 4 | 按钮权限 | 页面内按钮权限 | P1 |
**验收标准**:
```
[ ] 不同角色返回不同菜单
[ ] 返回结构:id、name、path、icon、children[]
[ ] 角色权限变更时缓存失效
```
---
### 4.9 @PreAuthorize 权限控制
| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | 方法级权限 | @PreAuthorize 注解 | P0 |
| 2 | 角色级权限 | hasRole('ADMIN') | P0 |
| 3 | 权限码权限 | hasAuthority('project:read') | P0 |
| 4 | 全局异常 | 403 JSON 响应 | P0 |
| 5 | Token 过滤器 | 解析 + 注入 | P0 |
**验收标准**:
```
[ ] 权限不足返回 HTTP 403 + JSON
[ ] Token 过期返回 HTTP 401 + JSON
[ ] 支持 hasAuthority('模块:操作')
[ ] 所有接口强制登录(除白名单)
```
---
## 五、技术实现要点
### 5.1 JWT Token 结构
```json
{
"header": { "alg": "HS256", "typ": "JWT" },
"payload": {
"sub": "1",
"username": "admin",
"roles": ["ADMIN"],
"iat": 1720944000,
"exp": 1720947600
}
}
```
### 5.2 Redis Key 规范
| Key | 说明 | TTL |
|-----|------|-----|
| `token:access:{userId}` | 访问令牌 | 2h |
| `token:refresh:{userId}` | 刷新令牌 | 7d |
| `token:blacklist:{refreshToken}` | 登出黑名单 | 2h |
| `sms:{phone}:{type}` | 短信验证码 | 5min |
| `login:fail:{phone}` | 登录失败计数 | 30min |
| `menu:{userId}` | 用户菜单缓存 | 1h |
### 5.3 Security 配置
```java
@Configuration
@EnableWebSecurity
@EnableMethodSecurity(prePostEnabled = true)
public class SecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.csrf(AbstractHttpConfigurer::disable)
.authorizeHttpRequests(auth -> auth
.requestMatchers("/api/v1/auth/**").permitAll()
.requestMatchers("/api/health").permitAll()
.anyRequest().authenticated()
)
.addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class);
return http.build();
}
}
```
### 5.4 登录锁定实现
```java
@Service
public class LoginAttemptService {
private static final int MAX_ATTEMPTS = 5;
private static final int LOCK_DURATION_MINUTES = 30;
public void loginSucceeded(String phone) {
redisTemplate.delete("login:fail:" + phone);
}
public void loginFailed(String phone) {
Long attempts = redisTemplate.opsForValue().increment("login:fail:" + phone);
if (attempts != null && attempts >= MAX_ATTEMPTS) {
redisTemplate.opsForValue().set("login:locked:" + phone, "1",
LOCK_DURATION_MINUTES, TimeUnit.MINUTES);
}
}
public boolean isLocked(String phone) {
return Boolean.TRUE.equals(redisTemplate.hasKey("login:locked:" + phone));
}
}
```
---
## 六、任务优先级
### P0(必须完成)
| 序号 | 任务 | 模块 |
|------|------|------|
| 1 | 登录接口 + JWT 双 Token | 登录 |
| 2 | Token 刷新接口 | 登录 |
| 3 | 注册接口 + 短信验证码 | 注册 |
| 4 | 获取当前用户信息 | 用户 |
| 5 | 用户列表 + 分页 + 筛选 | 用户 |
| 6 | 用户详情/更新/删除 | 用户 |
| 7 | 角色列表/详情 | 角色 |
| 8 | 角色创建/更新/删除 | 角色 |
| 9 | 权限码体系 + @PreAuthorize | 权限 |
| 10 | 登录锁定 | 安全 |
| 11 | 统一响应格式 | 框架 |
### P1(核心功能)
| 序号 | 任务 | 模块 |
|------|------|------|
| 12 | 登出接口 + Token 黑名单 | 登出 |
| 13 | 找回密码 | 密码 |
| 14 | 修改密码 | 密码 |
| 15 | 用户角色分配 | 权限 |
| 16 | 动态菜单接口 | 菜单 |
| 17 | 登录日志 | 日志 |
| 18 | IP 限流 | 安全 |
### P2(完善功能)
| 序号 | 任务 | 模块 |
|------|------|------|
| 19 | 密码历史记录 | 安全 |
| 20 | 菜单缓存优化 | 菜单 |
---
## 七、开发顺序建议
```
第一周:基础框架 + 登录
├── 1. 项目初始化 + 统一响应框架
├── 2. JWT 工具类 + Redis 配置
├── 3. 登录接口(username + password)
├── 4. Token 校验过滤器
├── 5. Token 刷新接口
└── 6. 登录锁定
第二周:注册 + 用户管理 + 角色权限
├── 1. 短信验证码接口(Redis)
├── 2. 注册接口
├── 3. 用户 CRUD 接口
├── 4. 角色 CRUD 接口
├── 5. 权限码体系 + @PreAuthorize
└── 6. 找回/修改密码
第三周:完善 + 安全加固
├── 1. 登出 + Token 黑名单
├── 2. 动态菜单接口
├── 3. 登录日志
├── 4. IP 限流
└── 5. 单元测试 + 接口文档
```
---
## 八、交付物清单
| 序号 | 交付物 | 说明 |
|------|--------|------|
| 1 | 数据库脚本 | user_* 表的 JPA Entity |
| 2 | 后端接口 | 全部 API 接口 |
| 3 | 认证框架 | JWT + Security 配置 |
| 4 | 单元测试 | 覆盖率 ≥ 80% |
| 5 | 接口文档 | Swagger / OpenAPI |
---
## 九、与其他模块的接口
### 9.1 被调用接口(供其他模块调用)
| 接口 | 调用方 | 说明 |
|------|--------|------|
| GET /users/{id} | training-module | 获取导师/学员信息 |
| GET /users/me | 所有模块 | 获取当前用户信息 |
| GET /roles | 所有模块 | 获取角色列表用于权限判断 |
### 9.2 调用其他模块接口
无(user-module 为底层基础模块,不依赖其他业务模块)。
---
## 十、风险与注意事项
| 风险 | 影响 | 应对 |
|------|------|------|
| JWT Token 安全 | 高 | 密钥至少 256 位,定期轮换 |
| 密码泄露 | 高 | bcrypt cost = 12,定期审计 |
| 权限绕过 | 高 | 全链路测试 + 代码审查 |
| Redis 不可用 | 中 | 本地缓存降级 |
| 短信轰炸 | 中 | IP 限流 + 手机号频控 |
---
*文档结束*
# 实习生培训平台 · 数据库设计 V1
> 基于《需求文档》《PRD》《MVP 技术架构设计》编制
> 版本:V1.0 | 日期:2026-07-14 | 状态:待评审
## 1. 设计约定
| 项目 | 约定 |
| ---- | -------------------------------------------- |
| 数据库名 | intern_platform |
| 字符集 | utf8mb4 |
| 引擎 | InnoDB |
| 公共字段 | 每张表均包含 id, tenant_id, created_at, updated_at |
| 多租户 | 预留 tenant_id,MVP 固定为 default |
| 表命名 | {模块前缀}_{业务名} |
### 模块前缀说明
| 前缀 | 模块 | 说明 |
| --------- | ------ | ------------------------- |
| `user`_ | 用户与权限 | 用户、角色、权限、部门 |
| `proj_` | 项目库 | 内部项目、GitHub 项目、标注项目、标签、难度 |
| `kp_` | 知识点 | 知识点、依赖关系 |
| `train_` | 实训闭环 | 实训任务、预习、实操、报告、答辩、缺陷、进阶匹配 |
| `audit_` | 审核入项 | 主管审核、入项登记、成长档案 |
| `talent_` | 人才培训体系 | 分类、晋升路径、实训内容、课程、就业方向 |
| `notify_` | 通知 | 站内通知 |
| `system_` | 系统 | 审计日志、状态流转事件 |
| `ai_` | AI | AI 调用日志 |
## 2. 完整表清单(共 39 张)
| 编号 | 表名 | 模块 | 说明 | 需求 |
| --- | --------------------------- | ---- | ------------------- | ----- |
| 01 | users | 用户 | 用户账号(含 role_id FK) | 角色矩阵 |
| 02 | roles | 用户 | 角色定义(含 description) | 角色矩阵 |
| 03 | permissions | 用户 | 权限点(含 module) | 角色矩阵 |
| 04 | role_permissions | 用户 | 角色-权限关联 | 角色矩阵 |
| 05 | user_department | 用户 | 部门 | 角色矩阵 |
| 06 | proj_internal_project | 项目库 | 内部种子项目 | R-01 |
| 07 | proj_github_project | 项目库 | GitHub 推荐项目 | R-02 |
| 08 | proj_annotation_project | 项目库 | 往届标注项目 | R-03 |
| 09 | proj_project_tag | 项目库 | 项目标签 | R-01 |
| 10 | proj_project_attachment | 项目库 | 项目附件 | R-01 |
| 11 | proj_difficulty_scorecard | 项目库 | 难度打分卡维度 | 6.1.1 |
| 12 | proj_difficulty_score | 项目库 | 项目难度评分 | 6.1.1 |
| 13 | proj_difficulty_calibration | 项目库 | 难度校准记录 | 6.1.1 |
| 14 | kp_knowledge_point | 知识点 | 知识点库 | R-04 |
| 15 | kp_knowledge_dependency | 知识点 | 依赖关系 | R-04 |
| 16 | train_task | 实训 | 实训任务主表 | 全局 |
| 17 | train_preview_record | 实训 | 预习记录 | R-04 |
| 18 | train_preview_quiz | 实训 | 预习小测 | R-04 |
| 19 | train_practice_artifact | 实训 | 实操产物 | R-05 |
| 20 | train_practice_report | 实训 | 实操报告 | R-05 |
| 21 | train_defense_application | 实训 | 答辩申请 | R-06 |
| 22 | train_defense_review | 实训 | 答辩评审 | R-07 |
| 23 | train_defect_record | 实训 | 历史缺陷 | R-08 |
| 24 | train_error_log | 实训 | 错误日志 | 6.6 |
| 25 | train_advanced_match | 实训 | 进阶匹配 | R-08 |
| 26 | train_skill_profile | 实训 | 能力画像 | R-13 |
| 27 | train_capability_assessment | 实训 | 能力评估 | 6.9 |
| 28 | audit_supervisor_review | 审核 | 主管审核 | R-09 |
| 29 | audit_entry_record | 审核 | 入项登记 | R-09 |
| 30 | talent_annotation_category | 培训体系 | 标注分类 | R-10 |
| 31 | talent_system | 培训体系 | 人才培训体系 | R-11 |
| 32 | talent_career_path | 培训体系 | 晋升路径 | R-11 |
| 33 | talent_training_content | 培训体系 | 实训内容 | R-11 |
| 34 | talent_course | 培训体系 | 配套课程 | R-11 |
| 35 | talent_career_direction | 培训体系 | 就业方向 | R-11 |
| 36 | notify_notification | 通知 | 站内通知 | 前端 |
| 37 | system_audit_log | 系统 | 审计日志 | 合规 |
| 38 | system_flow_event | 系统 | 状态流转 | 架构 |
| 39 | ai_call_log | 系统 | AI 调用日志 | 架构 |
## 3. 核心表结构详解
### 3.1 用户模块(5张)
**users — 用户表**(含 role_id FK)
| 字段 | 类型 | 约束 | 说明 |
| ------------- | ------------ | --------------------- | --------- |
| user_id | BIGINT | PK | 用户主键 |
| username | VARCHAR(50) | UNIQUE, NOT NULL | 登录账号 |
| password | VARCHAR(255) | NOT NULL | bcrypt 加密 |
| real_name | VARCHAR(50) | NOT NULL | 真实姓名 |
| email | VARCHAR(100) | | 邮箱 |
| phone | VARCHAR(20) | | 手机号 |
| role_id | BIGINT | FK to roles | 角色(外键) |
| department_id | BIGINT | FK to user_department | 所属部门 |
| avatar_url | VARCHAR(500) | | 头像 |
| status | TINYINT | DEFAULT 1 | 0=禁用 1=启用 |
| created_at | DATETIME | | 创建时间 |
**roles — 角色表**
| 字段 | 类型 | 约束 | 说明 |
| ----------- | ------------ | -------- | ---- |
| role_id | BIGINT | PK | 角色主键 |
| role_name | VARCHAR(50) | NOT NULL | 角色名称 |
| description | VARCHAR(200) | | 角色描述 |
| created_at | DATETIME | | 创建时间 |
**permissions — 权限点表**
| 字段 | 类型 | 约束 | 说明 |
| --------------- | ------------ | ---------------- | ------------------------------------------ |
| permission_id | BIGINT | PK | 权限主键 |
| permission_code | VARCHAR(50) | UNIQUE, NOT NULL | 权限编码 |
| permission_name | VARCHAR(100) | NOT NULL | 权限名称 |
| module | VARCHAR(50) | NOT NULL | 所属模块,如 project/training/defense/audit/user |
| description | VARCHAR(200) | | 权限说明 |
| created_at | DATETIME | | 创建时间 |
**role_permissions — 角色权限关联表**
| 字段 | 类型 | 约束 | 说明 |
| ------------- | -------- | ----------------- | ---- |
| id | BIGINT | PK | |
| role_id | BIGINT | FK to roles | 角色 |
| permission_id | BIGINT | FK to permissions | 权限 |
| created_at | DATETIME | | 创建时间 |
**user_department — 部门表**
| 字段 | 类型 | 约束 | 说明 |
| ----------- | ------------ | -------- | --------------- |
| id | BIGINT | PK | |
| name | VARCHAR(100) | NOT NULL | 部门名称 |
| code | VARCHAR(50) | UNIQUE | tech/annotation |
| description | VARCHAR(500) | | 说明 |
### 3.2 项目库模块(8张)
**proj_internal_project — 内部种子项目**
| 字段 | 类型 | 约束 | 说明 |
| --------------------- | ------------ | --------------------- | ----------- |
| id | BIGINT | PK | |
| name | VARCHAR(200) | NOT NULL | 项目名称 |
| description | TEXT | | 项目描述 |
| department_id | BIGINT | FK to user_department | 所属部门 |
| tech_stack | VARCHAR(200) | | 技术栈(技术部字段) |
| annotation_type | VARCHAR(100) | | 标注类型(标注部字段) |
| business_domain | VARCHAR(100) | | 业务领域 |
| difficulty_level | VARCHAR(10) | | L1-L5 |
| knowledge_tags | VARCHAR(500) | | 知识点标签 |
| source_code_url | VARCHAR(500) | | 源码地址 |
| requirement_doc_url | VARCHAR(500) | | 需求文档 |
| acceptance_report_url | VARCHAR(500) | | 验收报告 |
| status | TINYINT | DEFAULT 0 | 0=草稿 1=启用 |
**proj_github_project — GitHub 推荐项目**
| 字段 | 类型 | 约束 | 说明 |
| ---------------- | ------------ | --------------------------- | --------- |
| id | BIGINT | PK | |
| seed_project_id | BIGINT | FK to proj_internal_project | 关联种子项目 |
| github_url | VARCHAR(500) | NOT NULL | GitHub 链接 |
| repo_name | VARCHAR(200) | | 仓库名 |
| tech_stack | VARCHAR(200) | | 技术栈 |
| description | TEXT | | 描述 |
| difficulty_level | VARCHAR(10) | | L1-L5 |
| stars | INT | | Stars |
| match_score | DECIMAL(4,2) | | 匹配度 |
| match_reason | TEXT | | 匹配理由 |
**proj_annotation_project — 往届标注项目**
| 字段 | 类型 | 约束 | 说明 |
| ---------------- | ------------ | -------- | ----- |
| id | BIGINT | PK | |
| name | VARCHAR(200) | NOT NULL | 项目名称 |
| industry | VARCHAR(100) | | 行业 |
| annotation_type | VARCHAR(100) | | 标注类型 |
| difficulty_level | VARCHAR(10) | | L1-L5 |
| match_score | DECIMAL(4,2) | | 匹配度 |
**proj_project_tag — 项目标签**
| 字段 | 类型 | 约束 | 说明 |
| ------------ | ----------- | -------- | ------------------------------ |
| id | BIGINT | PK | 主键 |
| project_id | BIGINT | NOT NULL | 关联项目 ID |
| project_type | VARCHAR(20) | NOT NULL | internal / github / annotation |
| tag_name | VARCHAR(50) | NOT NULL | 标签名称 |
**proj_project_attachment — 项目附件**
| 字段 | 类型 | 约束 | 说明 |
| ------------ | ------------ | -------- | -------- |
| id | BIGINT | PK | |
| project_id | BIGINT | NOT NULL | |
| project_type | VARCHAR(20) | | |
| file_name | VARCHAR(200) | NOT NULL | |
| file_url | VARCHAR(500) | | MinIO 路径 |
| file_type | VARCHAR(50) | | 文档类型 |
**proj_difficulty_scorecard — 打分卡维度**
| 字段 | 类型 | 约束 | 说明 |
| -------------- | ------------ | --------------------- | ---- |
| id | BIGINT | PK | |
| department_id | BIGINT | FK to user_department | 所属部门 |
| dimension_name | VARCHAR(100) | NOT NULL | 维度 |
| weight | DECIMAL(3,2) | NOT NULL | 权重 |
**proj_difficulty_score — 项目难度评分**
| 字段 | 类型 | 约束 | 说明 |
| ---------------- | ------------ | -------- | ------------------------------ |
| id | BIGINT | PK | |
| project_id | BIGINT | NOT NULL | 项目ID |
| project_type | VARCHAR(20) | | internal / github / annotation |
| ai_score | DECIMAL(5,2) | | AI 评分 |
| calibrated_level | VARCHAR(10) | | 校准后等级 |
**proj_difficulty_calibration — 校准记录**
| 字段 | 类型 | 约束 | 说明 |
| -------------- | ------------ | --------------------------- | ------ |
| id | BIGINT | PK | |
| score_id | BIGINT | FK to proj_difficulty_score | 关联难度评分 |
| previous_level | VARCHAR(10) | | 校准前 |
| new_level | VARCHAR(10) | | 校准后 |
| reason | VARCHAR(500) | | 原因 |
| calibration_by | BIGINT | FK to users | | 校准人 |
### 3.3 知识点模块(2张)
**kp_knowledge_point — 知识点**
| 字段 | 类型 | 约束 | 说明 |
| --------------- | ------------ | -------------- | ------------------------------ |
| id | BIGINT | PK | |
| project_id | BIGINT | NOT NULL | 关联项目 |
| project_type | VARCHAR(20) | | internal / github / annotation |
| name | VARCHAR(200) | NOT NULL | 知识点名称 |
| description | TEXT | | 说明 |
| category | VARCHAR(50) | | concept/skill/tool |
| difficulty | VARCHAR(10) | DEFAULT medium | easy / medium / hard |
| estimated_hours | DECIMAL(4,1) | | 预计学习时长 |
| material_url | VARCHAR(500) | | 预计材料链接 |
**kp_knowledge_dependency — 依赖关系**
| 字段 | 类型 | 约束 | 说明 |
| --------------- | ------ | ------------------------ | ----- |
| id | BIGINT | PK | |
| knowledge_id | BIGINT | FK to kp_knowledge_point | 知识点 |
| prerequisite_id | BIGINT | FK to kp_knowledge_point | 前置知识点 |
### 3.4 实训闭环模块(12张)
**train_task — 实训任务主表**
| 字段 | 类型 | 约束 | 说明 |
| --------------------- | ------------ | --------------------- | ------------------------------ |
| id | BIGINT | PK | |
| user_id | BIGINT | FK to users, NOT NULL | 学员 |
| project_type | VARCHAR(20) | NOT NULL | internal / github / annotation |
| project_id | BIGINT | NOT NULL | 对应各项目表 ID |
| cycle_number | INT | DEFAULT 1 | 第几轮 |
| status | VARCHAR(20) | NOT NULL | 流程状态 |
| mentor_id | BIGINT | FK to users | 导师 |
| container_id | VARCHAR(100) | | 容器 ID |
| code_server_url | VARCHAR(500) | | code-server地址 |
| preview_completed_at | DATATIME | | 预习完成时间 |
| practice_submitted_at | DATATIME | | 实操提交时间 |
| defense_applied_at | DATATIME | | 答辩申请时间 |
| defense_completed_at | DATATIME | | 答辩完成时间 |
| reviewed_at | DATATIME | | 审核完成时间 |
**train_preview_record — 预习记录**
| 字段 | 类型 | 约束 | 说明 |
| ------------ | ----------- | ------------------------ | ----------------- |
| id | BIGINT | PK | |
| task_id | BIGINT | FK to train_task | 所属实训任务 |
| knowledge_id | BIGINT | FK to kp_knowledge_point | 知识点 |
| status | VARCHAR(20) | DEFAULT pending | pending/completed |
| completed_at | DATETIME | | 完成时间 |
**train_preview_quiz — 预习小测**
| 字段 | 类型 | 约束 | 说明 |
| ------------ | ------- | ------------------------ | --------- |
| id | BIGINT | PK | |
| task_id | BIGINT | FK to train_task | 所属实训任务 |
| knowledge_id | BIGINT | FK to kp_knowledge_point | 知识点 |
| score | INT | | 得分 |
| pass_status | TINYINT | DEFAULT 0 | 0=未过 1=通过 |
**train_practice_artifact — 实操产物**
| 字段 | 类型 | 约束 | 说明 |
| ------------- | ------------ | ---------------- | --------- |
| id | BIGINT | PK | |
| task_id | BIGINT | FK to train_task | 所属实训任务 |
| artifact_type | VARCHAR(30) | NOT NULL | 产物类型 |
| content | TEXT | | 内容描述 |
| file_url | VARCHAR(500) | | MinIO文件路径 |
**train_practice_report — 实操报告**
| 字段 | 类型 | 约束 | 说明 |
| ------------------- | ----------- | ------------------------ | --------------- |
| id | BIGINT | PK | |
| task_id | BIGINT | FK to train_task, UNIQUE | 一个任务一个报告 |
| process_description | TEXT | | 过程记录 |
| result_description | TEXT | | 结果说明 |
| status | VARCHAR(20) | DEFAULT draft | draft/submitted |
| submitted_at | DATATIME | | 提交时间 |
**train_defense_application — 答辩申请**
| 字段 | 类型 | 约束 | 说明 |
| --------- | ----------- | --------------------------- | ---- |
| id | BIGINT | PK | |
| task_id | BIGINT | FK to train_task, UNIQUE | |
| report_id | BIGINT | FK to train_practice_report | 关联报告 |
| status | VARCHAR(20) | DEFAULT pending | |
**train_defense_review — 答辩评审**
| 字段 | 类型 | 约束 | 说明 |
| ----------- | ------------ | ------------------------ | ----------- |
| id | BIGINT | PK | |
| task_id | BIGINT | FK to train_task, UNIQUE | |
| mentor_id | BIGINT | FK to users | 评审导师 |
| total_score | DECIMAL(4,1) | | 总分 |
| comment | TEXT | | |
| result | VARCHAR(10) | NOT NULL | pass/reject |
**train_defect_record — 历史缺陷**
| 字段 | 类型 | 约束 | 说明 |
| ------------ | ----------- | ------------------------ | ------------------- |
| id | BIGINT | PK | |
| task_id | BIGINT | FK to train_task | 所属实训任务 |
| knowledge_id | BIGINT | FK to kp_knowledge_point | 薄弱知识点 |
| severity | VARCHAR(10) | | low / medium / high |
| source | VARCHAR(30) | | 来源 |
| description | TEXT | | 缺陷描述u |
**train_error_log — 沙箱错误日志**
| 字段 | 类型 | 约束 | 说明 |
| ----------- | ----------- | ---------------- | ------ |
| id | BIGINT | PK | |
| task_id | BIGINT | FK to train_task | 所属实训任务 |
| log_content | TEXT | NOT NULL | |
| error_type | VARCHAR(50) | | |
| severity | VARCHAR(10) | DEFAULT medium | |
**train_advanced_match — 进阶匹配**
| 字段 | 类型 | 约束 | 说明 |
| ------------------ | ------------ | ---------------- | ------------------------- |
| id | BIGINT | PK | |
| task_id | BIGINT | FK to train_task | 所属实训任务 |
| user_id | BIGINT | FK to users | 学员 |
| matched_project_id | BIGINT | | 匹配项目id |
| match_score | DECIMAL(4,2) | | AI匹配度 |
| match_reason | TEXT | | AI推荐理由 |
| status | VARCHAR(20) | DEFAULT pending | pending / accepted / used |
**train_skill_profile — 能力画像**
| 字段 | 类型 | 约束 | 说明 |
| ---------------- | ------------ | ------------------------ | ------ |
| id | BIGINT | PK | |
| user_id | BIGINT | FK to users | 学员 |
| knowledge_id | BIGINT | FK to kp_knowledge_point | 知识点 |
| mastery_level | DECIMAL(4,2) | | 熟练度 |
| last_assessed_at | DATATIME | | 最近评估时间 |
**train_capability_assessment — 能力评估**
| 字段 | 类型 | 约束 | 说明 |
| ----------------- | ------------ | ------------------------ | --- |
| id | BIGINT | PK | |
| user_id | BIGINT | FK to users | 学员 |
| knowledge_id | BIGINT | FK to kp_knowledge_point | 知识点 |
| assessment_source | VARCHAR(30) | | |
| score | DECIMAL(4,2) | | |
### 3.5 审核入项模块(2张)
**audit_supervisor_review — 主管审核**
| 字段 | 类型 | 约束 | 说明 |
| -------------- | ----------- | ----------- | ----------- |
| id | BIGINT | PK | |
| user_id | BIGINT | FK to users | 被审核学员 |
| supervisor_id | BIGINT | FK to users | 主管 |
| review_summary | TEXT | | 综合意见 |
| result | VARCHAR(10) | NOT NULL | pass/reject |
**audit_entry_record — 入项登记**
| 字段 | 类型 | 约束 | 说明 |
| ------------------ | ------------ | ----------------------------- | ---- |
| id | BIGINT | PK | |
| user_id | BIGINT | FK to users | 入项学员 |
| review_id | BIGINT | FK to audit_supervisor_review | 关联审核 |
| entry_project_name | VARCHAR(200) | | 项目名称 |
| entry_department | VARCHAR(100) | | 进入部门 |
| entry_at | DATETIME | | 入项时间 |
### 3.6 人才培训体系模块(6张)
**talent_annotation_category — 标注项目分类**
| 字段 | 类型 | 约束 | 说明 |
| -------------------- | ------------ | --------------- | ----------------- |
| id | BIGINT | PK | |
| name | VARCHAR(100) | NOT NULL | 分类名称 |
| industry | VARCHAR(100) | | 所属行业 |
| annotation_type | VARCHAR(100) | | 标注类型 |
| difficulty_level | VARCHAR(10) | | L1-L5 |
| classification_basis | TEXT | | AI 归类依据 |
| status | VARCHAR(20) | DEFAULT 'draft' | draft / published |
**talent_system — 人才培训体系**
| 字段 | 类型 | 约束 | 说明 |
| ------------ | ------------ | ------------------------------- | ----------------- |
| id | BIGINT | PK | |
| category_id | BIGINT | FK → talent_annotation_category | |
| name | VARCHAR(200) | NOT NULL | 体系名称 |
| description | TEXT | | 体系说明 |
| status | VARCHAR(20) | DEFAULT 'draft' | draft / published |
| ai_generated | TINYINT | DEFAULT 1 | 0=人工 1=AI |
| approved_by | BIGINT | FK → user_user | 审批人 |
**talent_career_path — 晋升路径**
| 字段 | 类型 | 约束 | 说明 |
| ---------- | ------------ | ------------------- | ---- |
| id | BIGINT | PK | |
| system_id | BIGINT | FK to talent_system | 所属体系 |
| level_name | VARCHAR(100) | NOT NULL | |
| sort_order | INT | | |
**talent_training_content — 实训内容**
| 字段 | 类型 | 约束 | 说明 |
| -------------- | ------------ | ------------------- | ---- |
| id | BIGINT | PK | |
| system_id | BIGINT | FK to talent_system | 所属体系 |
| title | VARCHAR(200) | | |
| duration_hours | INT | | |
**talent_course — 配套课程**
| 字段 | 类型 | 约束 | 说明 |
| -------------- | ------------ | ------------------- | ---- |
| id | BIGINT | PK | |
| system_id | BIGINT | FK to talent_system | 所属体系 |
| course_name | VARCHAR(200) | | |
| duration_hours | INT | | |
**talent_career_direction — 就业方向**
| 字段 | 类型 | 约束 | 说明 |
| ---------------- | ------------ | ------------------- | ---- |
| id | BIGINT | PK | |
| system_id | BIGINT | FK to talent_system | 所属体系 |
| direction_name | VARCHAR(200) | | |
| target_positions | VARCHAR(500) | | |
### 3.7 通知模块
**notify_notification — 站内通知**
| 字段 | 类型 | 约束 | 说明 |
| ------- | ------------ | -------------- | -------------------------------------------- |
| id | BIGINT | PK | |
| user_id | BIGINT | FK → user_user | 接收人 |
| title | VARCHAR(200) | | 标题 |
| content | TEXT | | 内容 |
| type | VARCHAR(30) | NOT NULL | system / new_task / defense / review / entry |
| ref_id | BIGINT | | 关联业务 ID |
| is_read | TINYINT | DEFAULT 0 | |
### 3.8 系统支撑表(3张)
**system_audit_log — 审计日志**
| 字段 | 类型 | 约束 | 说明 |
| ------------- | ----------- | ----------- | --- |
| id | BIGINT | PK | |
| user_id | BIGINT | FK to users | 学员 |
| action | VARCHAR(50) | NOT NULL | |
| resource_type | VARCHAR(50) | | |
| resource_id | BIGINT | | |
| detail | JSON | | |
**system_flow_event — 状态流转事件**
| 字段 | 类型 | 约束 | 说明 |
| ----------- | ----------- | ---------------- | ------ |
| id | BIGINT | PK | |
| task_id | BIGINT | FK to train_task | 所属实训任务 |
| from_status | VARCHAR(20) | | |
| to_status | VARCHAR(20) | NOT NULL | |
| event | VARCHAR(50) | | |
**ai_call_log — AI 调用日志**
| 字段 | 类型 | 约束 | 说明 |
| ------------ | ----------- | --------- | --- |
| id | BIGINT | PK | |
| call_type | VARCHAR(50) | NOT NULL | |
| request_body | JSON | | |
| tokens_used | INT | | |
| duration_ms | INT | | |
| success | TINYINT | DEFAULT 1 | |
## 4. 需求覆盖矩阵
| 需求 | 说明 | 对应表 |
| ----- | --------------- | --------------------------------------------------------------------------------------------- |
| R-01 | 内部项目库管理 | `proj_internal_project`, `proj_project_tag`, `proj_project_attachment` |
| R-02 | AI 推荐 GitHub 项目 | `proj_github_project`, `train_advanced_match` |
| R-03 | AI 推荐往届标注项目 | `proj_annotation_project`, `train_advanced_match` |
| R-04 | AI 知识点提取与预习 | `kp_knowledge_point`, `kp_knowledge_dependency`, `train_preview_record`, `train_preview_quiz` |
| R-05 | 平台内项目实操 | `train_practice_artifact`, `train_practice_report` |
| R-06 | 实操报告 + 申请答辩 | `train_defense_application` |
| R-07 | 导师答辩评审 | `train_defense_review` |
| R-08 | 历史缺陷 + 进阶匹配 | `train_defect_record`, `train_error_log`, `train_advanced_match` |
| R-09 | 主管审核 + 入项 | `audit_supervisor_review`, `audit_entry_record` |
| R-10 | 标注项目自动分类 | `talent_annotation_category` |
| R-11 | 人才培训体系生成 | `talent_system` + 4 个子表 |
| R-13 | 成长档案与能力画像 | `train_skill_profile`,train_capability_assessment |
| 6.1.1 | 难度分级机制 | `proj_difficulty_scorecard`, `proj_difficulty_score`, `proj_difficulty_calibration` |
## 5. 核心数据流
preview -> practice -> defense -> supervisor_review -> entry
reject -> 回实操 (记录缺陷 -> 更新画像 -> 匹配进阶项目 -> 新 cycle)
## 6. 索引总览
| 表名 | 索引 | 场景 |
| ----------------------- | --------------------------------- | -------- |
| users | (role_id) | 按角色筛选 |
| train_task | (user_id, status) | 学员工作台 |
| train_task | (project_type, project_id) | 按项目查学员 |
| train_task | (mentor_id, status) | 导师工作台 |
| train_preview_record | (task_id, knowledge_id) | 预习进度 |
| train_defect_record | (task_id) | 任务缺陷列表 |
| trian_error_log | (task_id) | 按任务查报错日志 |
| train_defect_record | (knowledge_id) | 按知识点统计 |
| train_preview_record | (task_id,status) | 预习进度统计 |
| train_defense_review | (mentor_id,result) | 导师待评审列表 |
| train_skill_profile | (user_id, knowledge_id) | 能力画像 |
| trian_advanced_match | (user_id.status) | 学员待处理推荐 |
| role_permissions | (role_id,premission_id) | 权限检查 |
| notify_notification | (user_id, is_read) | 未读通知 |
| proj_internal_project | (department_id, difficulty_level) | 项目筛选 |
| audit_supervisor_review | (user_id) | 学员审核 |
| talent_system | (category_id, status) | 按分类查体系 |
| system_audit_log | (user_id) | 个人审计 |
| system_audit_log | (resource_type, resource_id) | 按资源审计 |
| system_flow_event | (task_id) | 流转历史 |
| ai_call_log | (call_type, created_at) | 按类型查调用 |
## 7. 待确认事项
1. 数据库密码:配置 root/root vs 容器 root/123456
2. 数据库名:配置 intern_platform vs 容器 Assistant
3. tenant_id 是否 MVP 直接落地
4. P1 需求(能力画像)表先建好还是延后
Markdown 格式
0% 或
您添加了 0 人 到此讨论。请谨慎行事。
请先完成此评论的编辑!
请 注册 或者 后发表评论