# 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），契合医学数据对一致性的高要求。