CollegeAIcenter/.kiro/specs/college-ai-center/design.md

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

系统分层架构

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

模块依赖关系

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。

关键接口：

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。

关键接口：

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。

关键接口：

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;
}

题目状态机：

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。

关键接口：

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（与合规模块协作）。

关键接口：

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。

关键接口：

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。

关键接口：

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。

关键接口：

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。

关键接口：

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 五要素）：

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。

关键接口：

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。

关键接口：

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;
}

授权与脱敏流程：

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

核心实体关系

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

关键数据结构

// 学习成果（需求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），契合医学数据对一致性的高要求。