附录 A：研究数据底座设计

对应主蓝图：app/assets/docs/research/cstar-research-platform-blueprint.md 配套附录：app/assets/docs/research/gap-matrix-and-roadmap.md（附录 B） 版本：v1.0 · 2026-11-11 · 状态：待评审 性质：本文件是设计规划，描述未来实施的目标形态；本次未创建任何表、路由、驱动，也未连接任何部署集成。文中「建议 / 需 / 应 / 设计目标」均非已实现。

1. 目标、边界与技术事实

1.1 目标

1. 把《研究计划.md》§5.3 的数据层（结构化答题日志库、评分库、量表库、审计日志）与 §7.7 数据字典，落成可评审的域模型与字段方向。
2. 研究数据全部落到数据库：当前以 Turso / libSQL 为实现；为将来 EdgeOne Makers 的存储能力预留演进路径。
3. 明确 Nuxt 4 服务端约定、身份与盲态、日志与导出、合规与性能约束，供后续实施拆解任务。

1.2 边界

• 本附录不写最终 DDL、不写真实密钥、不写真实受试数据；字段以「方向」形式给出，实施时由 Zod schema 与迁移文件定稿。
• 不改动现有 server/api/**、nuxt.config.ts、package.json、app/stores/**；现有 8 步内容编排继续保留（主蓝图 P2）。
• 「数据库 / Blob / KV」的分工是设计目标，不代表当前已接入 EdgeOne Makers 存储。

1.3 已核验技术事实

重要纠偏：database-plan.md:15 写「未来切换 EdgeOne Makers 原生数据库」，但按平台存储技能文档，该平台没有托管数据库；「自带数据库」应理解为「Blob 承担结构化数据 + KV 承担小配置」。本附录据此描述能力边界，并把最终选型列为待决事项 D2（主蓝图第 9 章）。

2. 研究域模型

2.1 实体清单

2.2 域模型关系

erDiagram
  STUDY ||--o| PROTOCOL : "定义"
  PROTOCOL ||--o{ ARM : "包含"
  PROTOCOL ||--o{ WINDOW : "包含"
  PROTOCOL ||--o{ ITEM_BANK : "引用"
  SUBJECT }o--|| ARM : "随机分配"
  SUBJECT ||--o{ CONSENT : "签署"
  SUBJECT ||--o{ SESSION : "参与"
  SESSION }o--|| WINDOW : "属于"
  ITEM_BANK ||--o{ ITEM : "包含"
  ITEM ||--o{ RESPONSE : "产生"
  RESPONSE ||--o{ SCORE : "被评分"
  SCORE ||--o{ REVIEW : "盲态复核"
  SESSION ||--o{ SCALE_RESPONSE : "量表作答"
  SESSION ||--o| VOSCE_SESSION : "行为层测量"
  VOSCE_SESSION ||--o{ TRANSCRIPT : "转录存档"
  SESSION ||--o{ REFLECTION : "反思写作"
  SESSION ||--o{ MEDIA_ASSET : "引用素材"
  MODEL_RUN ||--o{ MEDIA_ASSET : "生成留痕"
  SUBJECT ||--o{ TEACHER_EVENT : "教师轨独立采集"
  EXPORT_JOB ||--o{ AUDIT_LOG : "留痕"

学生轨与教师轨并列：teacher_event 不通过 session 关联学员流程，教师数据独立于「入科 → 出科」采集（§7.7、§11）。

2.3 与现有内容域的关系

3. 数据表字段方向

以下均为字段方向示意，不是最终 DDL；实施时以迁移文件与 Zod schema 定稿。所有涉及学员的表一律只存 subject_id_hash，姓名、学号不出平台（§7.8）。

3.1 研究定义、身份与伦理

3.2 窗口、题库与量规

3.3 作答、评分与盲态复核

3.4 量表与行为层测量

3.5 内容、素材与版本留痕

3.6 教师轨、审计与导出

4. 三类日志

事件设计要求（未来实施）：

• 每个事件带 event_id 幂等键、occurred_at、脱敏主体、协议版本、模型 / 提示词版本引用；写入失败须重试与补偿，不得丢失主要结局数据。
• 逐题事件批量写入（按会话或时间窗聚合），避免每答一题一次请求；前端可先本地缓冲，但研究证据以服务端入库为准，浏览器本地存储只作断网补偿。
• 观测指标建议：事件写入失败率与积压、导出任务耗时、双评分歧率、ICC 计算输入完整性、审核队列积压；这些属于可观测性设计，本次不实施。

5. 关键时序

5.1 入组、随机化与测评窗口

sequenceDiagram
  participant S as 学员端
  participant API as 服务端 API
  participant DB as 数据层
  participant T as 教师或盲态评分者
  S->>API: 知情同意与脱敏登记
  API->>DB: 写 consent 与 subject
  API->>DB: 随机分配并写 assignment
  S->>API: 入科 PRE（X、JSE、vOSCE 入科站）
  API->>DB: 批量写 response 与 scale_response
  S->>API: 轮转期（仅 B 臂进入完整闭环）
  API->>DB: 写逐题事件、对话、报告查看、讨论、反思
  S->>API: 出科 POST（全新 Y、JSE、vOSCE 出科站）
  API->>DB: 写主要结局与次要结局
  T->>API: 盲态双评（隐藏臂别与身份）
  API->>DB: 写 review 与仲裁
  API->>DB: 按月导出 export_job 并锁库

5.2 分环节要点

6. API 表面与 Nuxt 4 服务端约定

6.1 约定

6.2 路由组（设计目标）

以上路由均不存在于当前仓库，属于未来实施建议；现有 server/api/ 15 个路由中无任何研究接口（附录 B 第 3 章第 8 条）。

7. 随机化、盲态与一致性门控

本节描述的是数据口径与门控条件，不是已实现的统计代码；实施时统计计划须在锁库前单独归档。

8. 存储分工与演进

8.1 当前：Turso / libSQL

• 结构化研究数据（第 3 章各表）入 Turso；凭据走 runtimeConfig.turso（nuxt.config.ts:70-73）。
• 建议沿用 app/assets/docs/development/database-plan.md:417-437 的统一 execute() 驱动接口 + 驱动工厂 + Repository 设计，新增 server/db/index.ts、server/db/drivers/turso.ts、server/utils/db.ts、迁移文件与 Zod 校验；其「localStorage 渐进迁移、备份与回滚」思路同样适用。
• 实施前置修正：server/db/migrations/001_users.sql:5 行尾多余逗号的 SQL 语法瑕疵；并明确 users 表现有字段不足以支撑角色与盲态，需要扩展或新建研究账号表。
• 现有浏览器 localStorage 只保留为非研究内容的用户偏好与断网补偿，不再作为研究证据来源。

8.2 演进目标：EdgeOne Makers 能力边界（2026-11 核验）

8.3 三种演进路径（待决，不预设结论）

待决 D1（部署形态与数据驻留）与 D2（EdgeOne Makers 无托管数据库下的最终选型）见主蓝图第 9 章。本附录只给出事实与选项，不替课题方决定。

8.4 数据分工与迁移

迁移顺序建议：导出与校验 → 建立目标驱动 → 双写或灰度切换 → 一致性核对 → 切换读路径 → 保留回滚点与备份（沿用 database-plan.md 的迁移 / 回滚章节）。

9. 合规取舍与风险

10. 性能、可靠性与可观测性设计提示（未来实施）

以上均为实施阶段的设计提示，本次未实现、未压测、未连接任何监控。

11. 引用与待决事项

待决事项：D1（正式采集期部署形态与数据驻留）、D2（EdgeOne Makers 无托管数据库下的最终存储选型）、D3（统计计划与量规冻结责任人及时间）、D4（多模态转录服务的 provider 选型）——统一在主蓝图第 9 章登记。