freedakgmail
642 lines
30 KiB
Markdown
642 lines
30 KiB
Markdown
# Design Document
|
||
|
||
## Overview
|
||
|
||
医科类高校 AI 学习中心系统是一个以"能力"为核心的 Web 平台，面向学生、导师与管理员三类角色，贯穿基础医学、临床医学、见习实习、住院医师培养全成长链。本设计文档描述系统的架构、组件、数据模型、错误处理与测试策略，对应需求文档中的 17 条需求。
|
||
|
||
系统的两大架构支柱是：
|
||
|
||
1. **能力图谱（Competency Graph）** —— 全系统共享的数据底座。所有模块产生的可计入能力的数据（学习成果、对练成绩、技能使用、协同评估）都映射到统一的能力标签上，使学生画像、职业规划等能在统一数据上聚合，避免模块孤岛。
|
||
2. **技能能力中心（Skill Center）** —— 统一的 AI 能力技术底座。课程对练、研究资料查询等模块本质上是技能（Skill）的具体应用，它们复用同一套技能框架（输入规格、AI 处理逻辑、知识源绑定、输出格式、可信度标注规则）。
|
||
|
||
此外，**AI 可信与可解释**与**数据安全与合规**作为两个横切关注点贯穿所有模块：任何 AI 输出都附带可信度标注与可追溯来源，任何受保护资源访问都经过合规模块的权限判定与审计。
|
||
|
||
### 技术栈假设
|
||
|
||
需求未指定技术栈，本设计采用以下技术栈作为假设（可在实现阶段调整）：
|
||
|
||
- **前端**：React + TypeScript（学生端、导师端、管理端三套界面共用组件库）
|
||
- **后端**：Node.js + TypeScript（NestJS 框架，模块化、依赖注入契合本系统的模块划分）
|
||
- **数据库**：PostgreSQL（关系型主存储，含 JSONB 字段存储画像维度、技能定义等半结构化数据）
|
||
- **图/标签存储**：能力图谱的标签体系与映射关系存于 PostgreSQL（可演进至专用图数据库）
|
||
- **缓存**：Redis（画像聚合结果、能力概览等读多写少数据的缓存）
|
||
- **AI 集成**：通过统一的 AI 网关（AI Gateway）封装大模型调用，所有调用强制经过可信度标注与来源绑定
|
||
- **对象存储**：S3 兼容存储（学习成果附件）
|
||
- **检索集成**：通过资料来源适配器（Reference Source Adapter）对接 PubMed/CNKI/万方/UpToDate/Cochrane 等外部数据库 API
|
||
|
||
### 设计原则
|
||
|
||
- **可信优先**：医学场景下 AI 幻觉风险高，所有 AI 输出绑定权威来源、附带可信度标注；无法溯源的输出一律标注为"未经核验"。
|
||
- **合规默认**：敏感数据默认脱敏，画像跨用途使用必须有有效授权，所有敏感操作留审计日志。
|
||
- **能力贯通**：所有模块通过能力标签写入能力图谱，形成统一数据底座。
|
||
- **技能复用**：可复用 AI 能力统一抽象为技能，降低新增能力的成本。
|
||
|
||
## Architecture
|
||
|
||
### 系统分层架构
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph Client["客户端层"]
|
||
StudentUI["学生端"]
|
||
MentorUI["导师端"]
|
||
AdminUI["管理端"]
|
||
end
|
||
|
||
subgraph Gateway["接入层"]
|
||
APIGW["API 网关 / 认证鉴权"]
|
||
end
|
||
|
||
subgraph CrossCutting["横切关注点"]
|
||
Compliance["合规模块<br/>Compliance_Module<br/>(权限/脱敏/授权/审计)"]
|
||
AITrust["AI 可信层<br/>(可信度标注/来源溯源)"]
|
||
end
|
||
|
||
subgraph Modules["业务模块层"]
|
||
LS["个人学习空间<br/>Learning_Space"]
|
||
AEE["AI 评估引擎<br/>AI_Evaluation_Engine"]
|
||
PE["课程对练引擎<br/>Practice_Engine"]
|
||
CDP["临床情景对话对练<br/>Clinical_Dialogue_Practice"]
|
||
PF["学生画像引擎<br/>Profile_Engine"]
|
||
CM["职业规划模块<br/>Career_Module"]
|
||
ACM["AI 协同能力培养<br/>AI_Collaboration_Module"]
|
||
end
|
||
|
||
subgraph Foundation["底座层"]
|
||
SC["技能能力中心<br/>Skill_Center"]
|
||
CG["能力图谱<br/>Competency_Graph"]
|
||
end
|
||
|
||
subgraph External["外部与基础设施"]
|
||
AIGW["AI 网关 (大模型)"]
|
||
AuthSrc["权威知识源"]
|
||
RefSrc["资料来源 (PubMed/CNKI/...)"]
|
||
DB[("PostgreSQL")]
|
||
Cache[("Redis")]
|
||
OSS[("对象存储")]
|
||
end
|
||
|
||
Client --> APIGW
|
||
APIGW --> Compliance
|
||
Compliance --> Modules
|
||
Modules --> SC
|
||
Modules --> CG
|
||
SC --> AIGW
|
||
AEE --> AIGW
|
||
CDP --> AIGW
|
||
SC --> AuthSrc
|
||
SC --> RefSrc
|
||
PE --> AuthSrc
|
||
Modules --> AITrust
|
||
AITrust --> AIGW
|
||
Modules --> DB
|
||
PF --> Cache
|
||
CG --> Cache
|
||
LS --> OSS
|
||
```
|
||
|
||
### 模块依赖关系
|
||
|
||
```mermaid
|
||
graph LR
|
||
LS["个人学习空间"] --> CG["能力图谱"]
|
||
LS --> AEE["AI评估引擎"]
|
||
PE["课程对练引擎"] --> SC["技能能力中心"]
|
||
PE --> CG
|
||
PE --> AEE
|
||
CDP["临床情景对话对练"] --> SC
|
||
CDP --> CG
|
||
RQS["研究资料查询技能"] --> SC
|
||
RQS --> CG
|
||
ACM["AI协同能力培养"] --> CG
|
||
PF["学生画像引擎"] --> CG
|
||
PF --> LS
|
||
CM["职业规划模块"] --> CG
|
||
CM --> PF
|
||
AEE --> AITrust["AI可信层"]
|
||
SC --> AITrust
|
||
PF --> Compliance["合规模块"]
|
||
CM --> Compliance
|
||
```
|
||
|
||
关键说明：
|
||
- **能力图谱**是被依赖最多的底座，几乎所有业务模块都向它写入或从它读取能力数据。
|
||
- **技能能力中心**是课程对练、临床对话对练、研究查询技能的共同底座。
|
||
- **学生画像引擎**依赖能力图谱（能力数据）与个人学习空间（成果来源）。
|
||
- **职业规划模块**依赖能力图谱（能力水平对照）与学生画像。
|
||
|
||
## Components and Interfaces
|
||
|
||
### 1. 个人学习空间（Learning_Space）
|
||
|
||
**职责**：汇聚、归档、检索学生的学习成果；触发 AI 评价与能力标签关联。
|
||
|
||
**对应需求**：需求 1。
|
||
|
||
**关键接口**：
|
||
```typescript
|
||
interface LearningSpaceService {
|
||
// 需求1.1, 1.6, 1.9: 新增成果（含元数据与字段校验）
|
||
addAchievement(studentId: string, input: AchievementInput): Result<Achievement, ValidationError>;
|
||
// 需求1.5: 分页+筛选查询（按时间倒序，每页≤50）
|
||
listAchievements(studentId: string, filter: AchievementFilter, page: Pagination): Page<Achievement>;
|
||
// 需求1.4: 标记里程碑并关联成果
|
||
markMilestone(studentId: string, milestone: MilestoneInput): Milestone;
|
||
}
|
||
```
|
||
|
||
**设计要点**：
|
||
- 保存成功后（需求 1.3）按学年、学期自动归档；若成果含临床轮转科室信息（需求 1.8）额外按科室归档。
|
||
- 保存成功后（需求 1.7）调用能力图谱进行能力标签关联；若无法匹配任何已定义标签（需求 1.10），标记为"待关联能力标签"并提示。
|
||
- 必填元数据缺失（需求 1.6）或标题超 200 字符/时间无效（需求 1.9）时拒绝保存且不创建任何记录（事务回滚）。
|
||
- 成功保存后异步触发 `AI_Evaluation_Engine` 生成形成性评价（需求 2.1）。
|
||
|
||
### 2. AI 评估引擎（AI_Evaluation_Engine）
|
||
|
||
**职责**：对学习成果生成形成性评价，对里程碑生成终结性评价，对对练报告生成改进建议。
|
||
|
||
**对应需求**：需求 2、需求 4.7-4.8。
|
||
|
||
**关键接口**：
|
||
```typescript
|
||
interface AIEvaluationEngine {
|
||
// 需求2.1: 形成性评价（30秒内）
|
||
generateFormativeEvaluation(achievement: Achievement): Result<Evaluation, EvaluationError>;
|
||
// 需求2.2, 2.7: 终结性评价（节点内须有成果）
|
||
generateSummativeEvaluation(milestone: Milestone, achievements: Achievement[]): Result<Evaluation, EvaluationError>;
|
||
// 需求4.7-4.8: 对练薄弱环节改进建议
|
||
generateImprovementSuggestions(report: PracticeReport): Suggestion[];
|
||
}
|
||
```
|
||
|
||
**设计要点**：
|
||
- 每条评价附带可信度标注，列出至少一条依据的学习成果或权威知识源（需求 2.3）；每条发展建议引用至少一个能力标签（需求 2.4）。
|
||
- 内容信息不足时中止生成、保留数据不变并提示缺失内容类别（需求 2.5）。
|
||
- 生成失败或超时时中止、保留数据不变并提示失败（需求 2.6）。
|
||
- 通过 AI 可信层统一附加可信度标注（需求 16）。
|
||
|
||
### 3. 课程对练引擎（Practice_Engine）
|
||
|
||
**职责**：基于课程内容生成题目（绑定权威知识源），经导师审核后供学生对练，并生成结果诊断报告。
|
||
|
||
**对应需求**：需求 3、需求 4。
|
||
|
||
**关键接口**：
|
||
```typescript
|
||
interface PracticeEngine {
|
||
// 需求3.1: 生成题目（30秒内，5-50道）
|
||
generateQuestions(courseId: string, studentId: string): Result<Question[], GenerationError>;
|
||
// 需求3.5, 3.6: 导师审核流转
|
||
reviewQuestion(questionId: string, decision: ReviewDecision, reason?: string): Question;
|
||
// 需求4: 对练会话
|
||
startPractice(studentId: string, questionSetId: string): PracticeSession;
|
||
submitAnswer(sessionId: string, questionId: string, answer: Answer): AnswerResult;
|
||
finishPractice(sessionId: string): PracticeReport;
|
||
}
|
||
```
|
||
|
||
**题目状态机**：
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> 待导师审核: 生成成功
|
||
[*] --> 已拒绝: 无法绑定权威知识源(3.8)
|
||
待导师审核 --> 可用于对练: 导师通过(3.6)
|
||
待导师审核 --> 已退回: 导师退回(3.5)
|
||
已退回 --> 待导师审核: 修订后重新提交
|
||
可用于对练 --> [*]
|
||
```
|
||
|
||
**设计要点**：
|
||
- 每道题目绑定至少一个权威知识源并记录引用标识（需求 3.2）；无法绑定时不进入审核并记录原因（需求 3.8）。
|
||
- 支持 A1/A2/A3/A4、病例分析、临床决策题型（需求 3.3）。
|
||
- 课程内容不足以生成最少题量时中止并提示（需求 3.7）。
|
||
- 对练逐题呈现并采集作答（需求 4.1-4.2），单题超 120 秒未作答判错并继续（需求 4.4）。
|
||
- 报告含正确率、用时、薄弱环节（正确率<60% 的能力标签，需求 4.5），并按能力标签映射能力图谱（需求 4.6）。
|
||
|
||
### 4. 临床情景对话对练（Clinical_Dialogue_Practice）
|
||
|
||
**职责**：基于权威知识源呈现临床情景，进行多轮模拟问诊对话，生成多维评估报告。
|
||
|
||
**对应需求**：需求 5。
|
||
|
||
**关键接口**：
|
||
```typescript
|
||
interface ClinicalDialoguePractice {
|
||
// 需求5.1, 5.5: 发起对练（10秒内呈现情景，须绑定权威知识源）
|
||
startDialogue(studentId: string, scenarioId: string): Result<DialogueSession, NoSourceError>;
|
||
// 需求5.2: 多轮对话（最多50轮）
|
||
sendTurn(sessionId: string, studentInput: string): DialogueTurn;
|
||
// 需求5.3, 5.6: 结束并生成报告（30秒内，三维度）
|
||
finishDialogue(sessionId: string): Result<DialogueReport, ReportError>;
|
||
}
|
||
```
|
||
|
||
**设计要点**：
|
||
- 未绑定权威知识源时阻止启动、不创建对话记录并提示（需求 5.5）。
|
||
- 报告含问诊完整性、临床推理、医患沟通三个评估方面（需求 5.3），结果映射能力图谱（需求 5.4）。
|
||
- 报告生成失败或超时时中止、保留对话记录并提示（需求 5.6）。
|
||
|
||
### 5. 学生画像引擎（Profile_Engine）
|
||
|
||
**职责**：基于学习空间与能力图谱数据生成多维度画像；标记敏感字段，遵循数据最小化。
|
||
|
||
**对应需求**：需求 6、需求 7（与合规模块协作）。
|
||
|
||
**关键接口**：
|
||
```typescript
|
||
interface ProfileEngine {
|
||
// 需求6.1, 6.5: 生成/更新画像（5秒内，数据不足维度标记）
|
||
generateProfile(studentId: string): Result<StudentProfile, ProfileError>;
|
||
// 需求6.4: 画像结论可追溯
|
||
getProfileTraceability(studentId: string, dimensionId: string): TraceabilityRecord[];
|
||
}
|
||
```
|
||
|
||
**设计要点**：
|
||
- 六个画像维度均以 0-100 量化分值呈现（需求 6.2）：知识掌握、临床技能、科研能力、人文素养、AI 协同素养、职业倾向。
|
||
- 能力图谱更新后 10 秒内完成数据同步（需求 6.3）；每项结论可追溯至少一条来源记录（需求 6.4）。
|
||
- 数据不足以刻画某维度时标记"数据不足"并保留其余维度（需求 6.5）。
|
||
- 仅采集与至少一个画像维度直接相关的字段（需求 7.7，数据最小化）。
|
||
|
||
### 6. 职业规划模块（Career_Module）
|
||
|
||
**职责**：设定职业目标、关联岗位胜任力模型、对照能力图谱生成动态闭环发展规划。
|
||
|
||
**对应需求**：需求 8、需求 9。
|
||
|
||
**关键接口**：
|
||
```typescript
|
||
interface CareerModule {
|
||
// 需求8.1, 8.4, 8.5: 设定目标并关联胜任力模型（3秒内）
|
||
setCareerGoal(studentId: string, goal: CareerGoal): Result<CompetencyModel, GoalError>;
|
||
// 需求9: 生成/更新发展规划
|
||
generateDevelopmentPlan(studentId: string, goalId: string): Result<DevelopmentPlan, PlanError>;
|
||
}
|
||
```
|
||
|
||
**设计要点**：
|
||
- 岗位胜任力模型参照权威医学胜任力框架，含科学与学术、临床能力、健康与社会、职业素养四维度（需求 8.2），每维度至少 3 个能力标签（需求 8.3）。
|
||
- 无匹配模型时提示并推荐至少 3 个相近目标（需求 8.4）。
|
||
- 逐项对照能力图谱能力水平与要求水平，标记能力差距项（含缺数据项，需求 9.1）；每差距项生成≥1 建议行动（需求 9.2）、推荐≥1 学习资源或对练任务（需求 9.3）、引用对应能力标签（需求 9.4）。
|
||
- 能力图谱更新后再次请求时重算全部差距项（需求 9.5，动态闭环）。
|
||
- 未选目标/模型不可用时拒绝并提示、保留能力图谱数据（需求 9.6）；差距项无对应资源时保留并标注暂无推荐（需求 9.7）。
|
||
|
||
### 7. 研究资料查询技能（Research_Query_Skill，建立于 Skill_Center 之上）
|
||
|
||
**职责**：自然语言转检索式、检索筛选、总结、证据分级、引用管理。
|
||
|
||
**对应需求**：需求 10、需求 11。
|
||
|
||
**关键接口**：
|
||
```typescript
|
||
interface ResearchQuerySkill {
|
||
// 需求10.1, 10.6: NL→检索式(PICO/MeSH，10秒内，1-2000字符)
|
||
generateSearchQuery(studentId: string, question: string): Result<SearchQuery, QuestionError>;
|
||
// 需求10.2, 10.7, 10.8: 检索（30秒内，分页≤50，空结果/源不可用处理）
|
||
search(query: SearchQuery, sources: ReferenceSource[], page: Pagination): Result<Page<ReferenceItem>, SourceError>;
|
||
// 需求11.1, 11.6: 生成总结（30秒内，每结论附引用）
|
||
summarize(items: ReferenceItem[]): Result<Summary, SummaryError>;
|
||
// 需求11.3, 11.7: 生成/导出引用
|
||
generateCitation(items: ReferenceItem[], format: CitationFormat): Result<Citation[], CitationError>;
|
||
exportCitations(citations: Citation[], target: ExportTarget): Result<ExportFile, ExportError>;
|
||
}
|
||
```
|
||
|
||
**设计要点**：
|
||
- 检索结果每条仅含检索信息、摘要、原文链接，不存储或分发受版权保护全文（需求 10.4，版权安全）。
|
||
- 总结每条结论附≥1 来源引用（需求 11.1）；每条资料标注唯一证据分级（需求 11.2）。
|
||
- 无法溯源的结论标注"未验证"且不作为引用输出（需求 11.4）。
|
||
- 支持 Vancouver/GB-T 7714 格式，导出 EndNote/NoteExpress（需求 11.3）。
|
||
- 呈现总结时提示"仅辅助，不替代阅读原文"（需求 11.5）。
|
||
|
||
### 8. AI 协同能力培养模块（AI_Collaboration_Module）
|
||
|
||
**职责**：提供协同训练任务，评估四维协同能力，写入能力图谱，支持导师点评。
|
||
|
||
**对应需求**：需求 12。
|
||
|
||
**关键接口**：
|
||
```typescript
|
||
interface AICollaborationModule {
|
||
// 需求12.1: 提供协同训练任务（四维度各≥1）
|
||
listTrainingTasks(dimension?: CollaborationDimension): TrainingTask[];
|
||
// 需求12.2, 12.6, 12.7: 完成任务并评估（30秒内，0-100，失败/数据不足处理）
|
||
evaluateTask(studentId: string, taskId: string, submission: TaskSubmission): Result<CollaborationAssessment, AssessmentError>;
|
||
// 需求12.5: 导师点评
|
||
addMentorComment(taskId: string, mentorId: string, comment: string): MentorComment;
|
||
}
|
||
```
|
||
|
||
**设计要点**：
|
||
- 四维度：提问能力、批判性验证、责任边界意识、协同工作流（需求 12.2）。
|
||
- 学生直接采用未核验 AI 输出时提示并要求来源核验，且计入批判性验证维度（需求 12.3）。
|
||
- 评估结果映射能力图谱并计入画像与胜任力对照（需求 12.4）。
|
||
|
||
### 9. 技能能力中心（Skill_Center，底座）
|
||
|
||
**职责**：定义、治理、调用可复用 AI 技能；统一技能框架与可信度标注。
|
||
|
||
**对应需求**：需求 13。
|
||
|
||
**关键接口**：
|
||
```typescript
|
||
interface SkillCenter {
|
||
// 需求13.6, 13.7: 配置/启用/审计技能定义
|
||
upsertSkillDefinition(actor: User, def: SkillDefinition): Result<SkillDefinition, DefinitionError>;
|
||
enableSkill(actor: User, skillId: string): Skill;
|
||
// 需求13.3, 13.4, 13.5: 调用技能（30秒内，输入校验，失败处理）
|
||
invokeSkill(studentId: string, skillId: string, input: SkillInput): Result<SkillOutput, InvocationError>;
|
||
// 需求13.9: 序列化往返
|
||
serialize(def: SkillDefinition): string;
|
||
deserialize(raw: string): SkillDefinition;
|
||
}
|
||
```
|
||
|
||
**技能定义结构（需求 13.2 五要素）**：
|
||
```typescript
|
||
interface SkillDefinition {
|
||
id: string;
|
||
name: string;
|
||
inputSpec: InputSpec; // 输入规格
|
||
processingLogic: ProcessingLogic; // AI 处理逻辑说明
|
||
knowledgeSources: SourceBinding[]; // 知识源绑定
|
||
outputFormat: OutputFormat; // 输出格式
|
||
credibilityRule: CredibilityRule; // 可信度标注规则
|
||
enabled: boolean;
|
||
}
|
||
```
|
||
|
||
**设计要点**：
|
||
- 技能库至少含 8 个技能：资料查询、检索式生成、文献综述、病例分析、鉴别诊断辅助、医患沟通模拟、医学翻译、引用生成（需求 13.1）。
|
||
- 调用前校验输入符合 inputSpec，不符则拒绝（需求 13.4）；知识源不可用或处理失败时终止、不返回结果与标注、提示失败（需求 13.5）。
|
||
- 仅成功调用完成才写入能力图谱（需求 13.8）。
|
||
- **序列化往返一致性**（需求 13.9）：`deserialize(serialize(def))` 等价于 `def`，这是核心属性测试点。
|
||
|
||
### 10. 能力图谱（Competency_Graph，底座）
|
||
|
||
**职责**：维护统一能力标签体系；接收各模块能力数据映射；聚合能力概览。
|
||
|
||
**对应需求**：需求 14。
|
||
|
||
**关键接口**：
|
||
```typescript
|
||
interface CompetencyGraph {
|
||
// 需求14.1: 维护统一标签体系
|
||
listTags(): CompetencyTag[];
|
||
// 需求14.2, 14.3: 映射数据（1-10标签，5秒内，未定义标签拒绝）
|
||
mapData(source: ModuleSource, data: CompetencyData, tagIds: string[]): Result<Mapping, UndefinedTagError>;
|
||
// 需求14.4, 14.5: 聚合能力概览（5秒内，0-100，数据不足标记）
|
||
getCompetencyOverview(studentId: string): CompetencyOverview;
|
||
}
|
||
```
|
||
|
||
**设计要点**：
|
||
- 每个能力标签有唯一标识与所属能力维度（需求 14.1）。
|
||
- 映射 1-10 个已定义标签（需求 14.2）；引用未定义标签时拒绝、不创建记录、记录原因并提示（需求 14.3）。
|
||
- 能力概览按维度以 0-100 量化分值返回（需求 14.4）；数据不足维度标记"数据不足"并保留其余（需求 14.5）。
|
||
|
||
### 11. 合规模块（Compliance_Module，横切）
|
||
|
||
**职责**：权限分级、敏感字段脱敏、画像授权校验、审计日志。
|
||
|
||
**对应需求**：需求 7、需求 15.4、需求 17。
|
||
|
||
**关键接口**：
|
||
```typescript
|
||
interface ComplianceModule {
|
||
// 需求17.1, 17.2, 17.3: 权限判定
|
||
checkAccess(user: User, resource: ProtectedResource, action: Action): AccessDecision;
|
||
// 需求7.2, 7.3, 7.4, 7.5: 画像授权与脱敏
|
||
resolveProfileView(viewer: User, profile: StudentProfile): StudentProfileView;
|
||
verifyConsent(studentId: string, purpose: Purpose): ConsentVerification;
|
||
revokeConsent(studentId: string, consentId: string): void;
|
||
// 需求17.4, 7.6: 审计日志
|
||
writeAuditLog(entry: AuditLogEntry): void;
|
||
}
|
||
```
|
||
|
||
**授权与脱敏流程**：
|
||
```mermaid
|
||
flowchart TD
|
||
A[访问学生画像] --> B{访问者是学生本人?}
|
||
B -->|是| C[返回完整画像]
|
||
B -->|否| D{持有有效知情同意授权?}
|
||
D -->|否| E[拒绝完整画像访问 7.2<br/>对未授权敏感字段脱敏 7.5]
|
||
D -->|是, 范围覆盖用途| F[校验授权有效期/范围/用途 7.3]
|
||
F -->|通过| G[按授权范围返回字段]
|
||
F -->|不通过| E
|
||
C --> H[写审计日志 7.6]
|
||
E --> H
|
||
G --> H
|
||
```
|
||
|
||
**设计要点**：
|
||
- 敏感字段：身份标识、联系方式、健康与医疗记录、心理测评结果、生物特征数据（需求 7.1）。
|
||
- 授权须仍在有效期内且范围与用途覆盖该用途（需求 7.3）；不满足时阻止使用、保持数据不被使用并提示（需求 7.4）。
|
||
- 学生撤销授权后立即失效，此后按未授权处理（需求 7.8）。
|
||
- 脱敏 2 秒内、仅返回已授权字段（需求 7.5）；审计日志 5 秒内记录、保留≥12 个月（需求 7.6）。
|
||
- 权限范围列出可访问资源类型与允许操作类型（需求 17.1）；越权访问拒绝并记录（需求 17.3）。
|
||
|
||
### 12. 导师端（Mentor 视图，跨模块）
|
||
|
||
**职责**：题目审核、成果点评、查看带教学生画像。
|
||
|
||
**对应需求**：需求 15。
|
||
|
||
**设计要点**：
|
||
- 题目审核通过/退回并在退回时记录原因（需求 15.1，复用 Practice_Engine 审核接口）。
|
||
- 成果点评关联到学习成果并对学生可见（需求 15.2）。
|
||
- 存在带教关系时允许查看所带学生画像（需求 15.3）；查看非所带学生画像时合规模块拒绝并记录越权尝试（需求 15.4）。
|
||
|
||
### 13. AI 可信层（横切）
|
||
|
||
**职责**：为所有 AI 输出统一附加可信度标注与来源溯源。
|
||
|
||
**对应需求**：需求 16。
|
||
|
||
**设计要点**：
|
||
- 任意 AI 评价/建议/总结附带可信度标注（需求 16.1），含≥1 来源与 0%-100% 置信度（需求 16.2）。
|
||
- 请求查看依据时 3 秒内展示可追溯来源条目及引用标识（需求 16.3）。
|
||
- 无法溯源的输出标注"未经核验"并在呈现时一并显示（需求 16.4）。
|
||
|
||
## Data Models
|
||
|
||
### 核心实体关系
|
||
|
||
```mermaid
|
||
erDiagram
|
||
Student ||--o{ Achievement : owns
|
||
Student ||--|| StudentProfile : has
|
||
Student ||--o{ Milestone : reaches
|
||
Student ||--o{ ConsentRecord : grants
|
||
Achievement }o--o{ CompetencyTag : "mapped to"
|
||
Milestone ||--o{ Achievement : groups
|
||
CompetencyTag }o--|| CompetencyDimension : "belongs to"
|
||
CompetencyModel ||--o{ CompetencyTag : requires
|
||
CareerGoal ||--|| CompetencyModel : maps
|
||
DevelopmentPlan ||--o{ CompetencyGap : contains
|
||
SkillDefinition ||--o{ SourceBinding : binds
|
||
Question }o--|| AuthoritativeSource : "bound to"
|
||
PracticeReport }o--o{ CompetencyTag : "scored on"
|
||
AuditLogEntry }o--|| Student : about
|
||
StudentProfile ||--o{ ProfileDimensionScore : contains
|
||
```
|
||
|
||
### 关键数据结构
|
||
|
||
```typescript
|
||
// 学习成果（需求1）
|
||
interface Achievement {
|
||
id: string;
|
||
studentId: string;
|
||
type: AchievementType; // 需求1.2 枚举
|
||
title: string; // ≤200字符 (需求1.9)
|
||
occurredAt: Date; // 有效日期 (需求1.9)
|
||
academicYear: string; // 归档维度 (需求1.3)
|
||
semester: string; // 归档维度 (需求1.3)
|
||
rotationDept?: string; // 临床轮转科室 (需求1.8)
|
||
attachments: AttachmentRef[];
|
||
competencyTagIds: string[]; // 关联标签 (需求1.7)
|
||
pendingTagAssociation: boolean; // 待关联 (需求1.10)
|
||
}
|
||
|
||
// 能力标签与维度（需求14）
|
||
interface CompetencyTag {
|
||
id: string; // 唯一标识 (需求14.1)
|
||
name: string;
|
||
dimensionId: string; // 所属维度 (需求14.1)
|
||
}
|
||
|
||
// 学生画像（需求6,7）
|
||
interface StudentProfile {
|
||
studentId: string;
|
||
dimensions: ProfileDimensionScore[]; // 六维度，0-100 (需求6.2)
|
||
generatedAt: Date;
|
||
}
|
||
interface ProfileDimensionScore {
|
||
dimension: ProfileDimension;
|
||
score: number | 'insufficient_data'; // 数据不足 (需求6.5)
|
||
traceability: TraceabilityRecord[]; // 可追溯 (需求6.4)
|
||
sensitive: boolean; // 敏感标记 (需求7.1)
|
||
}
|
||
|
||
// 知情同意授权（需求7）
|
||
interface ConsentRecord {
|
||
id: string;
|
||
studentId: string;
|
||
scope: string[]; // 授权范围 (需求7.3)
|
||
purpose: Purpose; // 授权用途 (需求7.3)
|
||
validFrom: Date;
|
||
validUntil: Date; // 有效期 (需求7.3)
|
||
revoked: boolean; // 撤销 (需求7.8)
|
||
}
|
||
|
||
// 可信度标注（需求16）
|
||
interface CredibilityAnnotation {
|
||
sources: SourceRef[]; // ≥1 来源 (需求16.2)
|
||
confidence: number; // 0-100 (需求16.2)
|
||
verified: boolean; // false => "未经核验" (需求16.4)
|
||
}
|
||
|
||
// 审计日志（需求7.6, 17.4）
|
||
interface AuditLogEntry {
|
||
actorId: string; // 操作者
|
||
timestamp: Date; // 时间
|
||
action: Action; // 操作类型
|
||
resourceScope: string; // 数据范围
|
||
outcome: 'allow' | 'deny';
|
||
reason?: string; // 拒绝原因 (需求17.3)
|
||
// 保留≥12个月 (需求7.6)
|
||
}
|
||
```
|
||
|
||
## Error Handling
|
||
|
||
系统采用统一的 `Result<T, E>` 返回模式，区分正常路径与错误路径，并遵循以下原则：
|
||
|
||
| 场景 | 处理策略 | 对应需求 |
|
||
|------|----------|----------|
|
||
| 输入校验失败（缺字段/超长/无效日期） | 拒绝操作、不创建记录（事务回滚）、返回指明问题的提示 | 1.6, 1.9, 13.4 |
|
||
| AI 生成失败或超时 | 中止生成、保留触发数据不变、返回失败提示 | 2.6, 5.6, 11.6, 12.6 |
|
||
| 内容/数据信息不足 | 标记"数据不足"或"信息不足"、保留其余结果、提示缺失类别 | 2.5, 6.5, 12.7, 14.5 |
|
||
| 无法绑定权威知识源 | 不进入审核/不启动、记录原因或提示 | 3.8, 5.5 |
|
||
| 资料来源不可用 | 中止检索、保留检索式、提示来源不可用 | 10.8 |
|
||
| 检索无匹配 | 返回空结果列表并提示 | 10.7 |
|
||
| 无法溯源 | 标注"未验证"/"未经核验"、不作为引用输出 | 11.4, 16.4 |
|
||
| 无有效授权 | 阻止使用、保持数据不被使用、提示缺少授权 | 7.4 |
|
||
| 越权访问 | 拒绝访问、保持资源不被访问、记录拒绝事件 | 9.6, 15.4, 17.3 |
|
||
| 系统错误（如目标关联失败） | 返回错误提示、保留已有数据 | 8.5, 9.6 |
|
||
|
||
**核心错误处理不变量**：任何错误路径都不得使触发数据进入不一致状态（要么完整成功，要么完整回滚保留原状）。
|
||
|
||
## Testing Strategy
|
||
|
||
### 测试层次
|
||
|
||
1. **单元测试**：各模块接口的正常路径与错误路径，覆盖每条验收标准。
|
||
2. **集成测试**：跨模块流程，重点验证能力图谱作为底座的数据贯通（学习成果→标签→画像→职业规划）。
|
||
3. **属性测试（Property-Based Testing）**：针对可形式化为不变量的核心正确性属性。
|
||
4. **合规与安全测试**：权限矩阵、脱敏、授权生命周期、审计完整性。
|
||
|
||
测试数据与模拟说明：
|
||
|
||
- AI 网关在测试中以可控的 mock 替代，便于模拟生成成功、失败、超时、无法溯源等场景。
|
||
- 资料来源适配器以 mock 模拟外部数据库的可用、不可用、空结果等状态。
|
||
- 属性测试使用生成器构造任意有效的技能定义、能力数据、授权记录等输入。
|
||
|
||
## Correctness Properties
|
||
|
||
以下属性应对任意有效输入成立，作为属性测试（Property-Based Testing）的基础：
|
||
|
||
### Property 1: 技能定义序列化往返一致性
|
||
对任意有效的 `SkillDefinition def`，有 `deserialize(serialize(def))` 等价于 `def`。
|
||
|
||
**Validates: Requirements 13.9**
|
||
|
||
### Property 2: 能力标签映射有效性
|
||
对任意提交的能力数据与标签集合，映射成功 ⟺ 所有标签均为已定义标签，且映射后标签数量在 1 到 10 之间；引用未定义标签时必然拒绝且不创建任何映射记录。
|
||
|
||
**Validates: Requirements 14.2, 14.3**
|
||
|
||
### Property 3: 画像维度分值有界性
|
||
对任意学生数据生成的画像与能力概览，每个维度的输出要么是 0 到 100 之间的数值，要么是"数据不足"标记，不存在其他取值。
|
||
|
||
**Validates: Requirements 6.2, 14.4**
|
||
|
||
### Property 4: 授权强制不变量
|
||
对任意非本人访问者与任意画像使用用途，仅当存在一条有效期内、范围与用途均覆盖的未撤销授权时，才允许完整访问/使用；授权撤销后任何后续访问都按未授权处理。
|
||
|
||
**Validates: Requirements 7.2, 7.3, 7.4, 7.8**
|
||
|
||
### Property 5: 引用可追溯不变量
|
||
对任意生成的总结，作为引用输出的每条结论都必然可追溯到至少一条来源条目；无法溯源的结论必然被标注为"未验证/未经核验"且不出现在引用输出中。
|
||
|
||
**Validates: Requirements 11.1, 11.4, 16.4**
|
||
|
||
### Property 6: 权限判定一致性
|
||
对任意（用户角色，资源，操作）三元组，访问被允许 ⟺ 该操作在该角色的权限范围内；越权访问必然被拒绝并产生一条拒绝审计记录。
|
||
|
||
**Validates: Requirements 17.2, 17.3**
|
||
|
||
### Property 7: 错误路径数据保全
|
||
对任意触发错误路径的操作，操作前后触发数据保持不变（不产生部分写入）。
|
||
|
||
**Validates: Requirements 1.6, 1.9, 2.6, 5.6, 8.5**
|
||
|
||
### Property 8: 分页边界不变量
|
||
对任意查询与分页参数，返回的单页结果数量不超过 50 条。
|
||
|
||
**Validates: Requirements 1.5, 10.2**
|
||
|
||
## Design Decisions and Rationale
|
||
|
||
1. **以能力图谱为统一底座**：医学教育成长链长、模块多，若各模块各自存储能力数据会形成孤岛。统一标签体系让画像与职业规划能在一致数据上聚合，也使"对照胜任力模型"有共同语言。代价是所有模块需遵循标签映射契约（需求 14.3 的拒绝机制保障了契约一致性）。
|
||
|
||
2. **技能能力中心作为 AI 能力底座**：课程对练、研究查询本质都是"绑定知识源的 AI 调用 + 可信度标注"。抽象为统一技能框架降低新增能力成本，并使可信度标注、知识源绑定、治理审计得以统一实现。序列化往返一致性（需求 13.9）保障技能定义可安全持久化与迁移。
|
||
|
||
3. **AI 可信层作为横切关注点**：医学场景幻觉风险高，将"可信度标注 + 来源溯源 + 未经核验标记"统一到一层，避免各模块各自实现导致遗漏，确保需求 16 在全系统一致生效。
|
||
|
||
4. **合规默认、授权可生命周期管理**：画像含敏感健康数据，采用"默认脱敏 + 用途化授权 + 撤销即时失效 + 全审计"模型，满足知情同意与数据最小化要求，并通过授权强制不变量（属性 4）可测试地保障。
|
||
|
||
5. **统一 Result 错误模型与数据保全不变量**：所有错误路径保证数据不进入部分写入状态（属性 7），契合医学数据对一致性的高要求。
|