openlearn-next 0.7.13 → 0.7.16

package/migrations/046_logout_clear_site_data.sql

@@ -0,0 +1,9 @@
+-- UP
+-- 046_logout_clear_site_data.sql
+-- Issue #487：管理后台可配置登出时是否下发 Clear-Site-Data: "cookies", "storage", "cache"。
+-- 默认值为 0（关闭），由管理员在站点设置中按需启用。
+
+ALTER TABLE site_settings ADD COLUMN logout_clear_site_data INTEGER DEFAULT 0;
+
+-- DOWN
+ALTER TABLE site_settings DROP COLUMN logout_clear_site_data;

package/migrations/047_third_party_theme_system.sql

@@ -0,0 +1,55 @@
+-- UP
+-- 047_third_party_theme_system.sql
+-- Issue #484：第三方主题系统 —— 共享主题目录、版本历史、每账号隔离偏好与站点默认主题。
+
+CREATE TABLE IF NOT EXISTS themes (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  description TEXT DEFAULT '',
+  author TEXT NOT NULL,
+  latest_version TEXT NOT NULL,
+  uploader_id TEXT NOT NULL,
+  uploader_name TEXT DEFAULT '',
+  status TEXT NOT NULL DEFAULT 'active',
+  supports_modes TEXT NOT NULL DEFAULT '["light","dark"]',
+  platform_min_version TEXT,
+  platform_max_version TEXT,
+  manifest_json TEXT NOT NULL,
+  styles_css TEXT NOT NULL DEFAULT '',
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS theme_versions (
+  theme_id TEXT NOT NULL,
+  version TEXT NOT NULL,
+  manifest_json TEXT NOT NULL,
+  styles_css TEXT NOT NULL DEFAULT '',
+  asset_manifest_json TEXT NOT NULL DEFAULT '[]',
+  uploader_id TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  PRIMARY KEY (theme_id, version),
+  FOREIGN KEY (theme_id) REFERENCES themes(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS user_theme_preferences (
+  principal_key TEXT PRIMARY KEY,
+  theme_id TEXT NOT NULL DEFAULT 'light',
+  installed_version TEXT,
+  mode TEXT NOT NULL DEFAULT 'auto',
+  appearance_json TEXT NOT NULL DEFAULT '{}',
+  updated_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_themes_status ON themes(status, updated_at);
+CREATE INDEX IF NOT EXISTS idx_theme_versions_theme ON theme_versions(theme_id, created_at);
+
+ALTER TABLE site_settings ADD COLUMN default_theme_id TEXT DEFAULT 'light';
+
+-- DOWN
+DROP INDEX IF EXISTS idx_theme_versions_theme;
+DROP INDEX IF EXISTS idx_themes_status;
+DROP TABLE IF EXISTS user_theme_preferences;
+DROP TABLE IF EXISTS theme_versions;
+DROP TABLE IF EXISTS themes;
+ALTER TABLE site_settings DROP COLUMN default_theme_id;

package/migrations/048_file_storage_extension.sql

@@ -0,0 +1,63 @@
+-- File storage extension: split physical blobs (file_blobs), logical assets (file_assets),
+-- and legacy URL aliases (file_aliases), plus admin config column on site_settings and asset linkage on plugin_assignment_files.
+
+CREATE TABLE IF NOT EXISTS file_blobs (
+  id TEXT PRIMARY KEY,
+  backend_id TEXT NOT NULL DEFAULT 'local',
+  storage_key TEXT NOT NULL,
+  sha256 TEXT NOT NULL,
+  size_bytes INTEGER NOT NULL,
+  ref_count INTEGER NOT NULL DEFAULT 1,
+  created_at TEXT NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_file_blobs_backend_key ON file_blobs(backend_id, storage_key);
+CREATE INDEX IF NOT EXISTS idx_file_blobs_sha256 ON file_blobs(backend_id, sha256);
+
+CREATE TABLE IF NOT EXISTS file_assets (
+  id TEXT PRIMARY KEY,
+  blob_id TEXT NOT NULL REFERENCES file_blobs(id),
+  original_name TEXT NOT NULL,
+  mime TEXT NOT NULL,
+  author_id TEXT,
+  course_id TEXT,
+  lesson_id TEXT,
+  purpose TEXT NOT NULL,
+  access_scope TEXT NOT NULL DEFAULT 'authenticated',
+  metadata_json TEXT,
+  deleted_at TEXT,
+  created_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_file_assets_blob ON file_assets(blob_id);
+CREATE INDEX IF NOT EXISTS idx_file_assets_course ON file_assets(course_id);
+CREATE INDEX IF NOT EXISTS idx_file_assets_lesson ON file_assets(lesson_id);
+CREATE INDEX IF NOT EXISTS idx_file_assets_author ON file_assets(author_id);
+CREATE INDEX IF NOT EXISTS idx_file_assets_purpose ON file_assets(purpose, deleted_at);
+
+CREATE TABLE IF NOT EXISTS file_aliases (
+  alias TEXT PRIMARY KEY,
+  asset_id TEXT NOT NULL REFERENCES file_assets(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_file_aliases_asset ON file_aliases(asset_id);
+
+ALTER TABLE site_settings ADD COLUMN file_storage_config TEXT;
+ALTER TABLE plugin_assignment_files ADD COLUMN asset_id TEXT;
+CREATE INDEX IF NOT EXISTS idx_assignment_files_asset ON plugin_assignment_files(asset_id);
+
+-- DOWN
+DROP INDEX IF EXISTS idx_assignment_files_asset;
+ALTER TABLE plugin_assignment_files DROP COLUMN asset_id;
+ALTER TABLE site_settings DROP COLUMN file_storage_config;
+DROP INDEX IF EXISTS idx_file_aliases_asset;
+DROP TABLE IF EXISTS file_aliases;
+DROP INDEX IF EXISTS idx_file_assets_purpose;
+DROP INDEX IF EXISTS idx_file_assets_author;
+DROP INDEX IF EXISTS idx_file_assets_lesson;
+DROP INDEX IF EXISTS idx_file_assets_course;
+DROP INDEX IF EXISTS idx_file_assets_blob;
+DROP TABLE IF EXISTS file_assets;
+DROP INDEX IF EXISTS idx_file_blobs_sha256;
+DROP INDEX IF EXISTS idx_file_blobs_backend_key;
+DROP TABLE IF EXISTS file_blobs;

package/migrations/049_ai_personas.sql

@@ -0,0 +1,25 @@
+-- UP
+CREATE TABLE IF NOT EXISTS ai_personas (
+  id TEXT PRIMARY KEY,
+  source TEXT NOT NULL,
+  plugin_id TEXT,
+  name_zh TEXT NOT NULL,
+  name_en TEXT NOT NULL,
+  instruction_zh TEXT NOT NULL DEFAULT '',
+  instruction_en TEXT NOT NULL DEFAULT '',
+  icon TEXT,
+  mode TEXT NOT NULL DEFAULT 'overlay',
+  base_policy TEXT NOT NULL DEFAULT 'inherit',
+  visibility_json TEXT,
+  default_for_role_json TEXT,
+  tool_policy_json TEXT,
+  max_turns INTEGER,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_ai_personas_source_plugin ON ai_personas(source, plugin_id);
+
+-- DOWN
+DROP INDEX IF EXISTS idx_ai_personas_source_plugin;
+DROP TABLE IF EXISTS ai_personas;

package/migrations/050_ai_persona_governance.sql

@@ -0,0 +1,11 @@
+-- UP
+CREATE TABLE IF NOT EXISTS ai_persona_governance (
+  persona_id TEXT PRIMARY KEY,
+  description_zh TEXT NOT NULL DEFAULT '',
+  description_en TEXT NOT NULL DEFAULT '',
+  enabled INTEGER NOT NULL DEFAULT 1,
+  preferred_provider_id TEXT
+);
+
+-- DOWN
+DROP TABLE IF EXISTS ai_persona_governance;

package/migrations/051_community_registry_url.sql

@@ -0,0 +1,9 @@
+-- UP
+-- 051_community_registry_url.sql
+-- 支持在插件中心「社区」标签页配置社区插件注册表 JSON 地址；
+-- NULL 表示未在界面显式覆盖，服务端回落到环境变量 PLUGIN_COMMUNITY_REGISTRY_URL。
+
+ALTER TABLE site_settings ADD COLUMN community_registry_url TEXT;
+
+-- DOWN
+ALTER TABLE site_settings DROP COLUMN community_registry_url;

package/migrations/052_community_install_enabled.sql

@@ -0,0 +1,12 @@
+-- UP
+-- 052_community_install_enabled.sql
+-- 支持在插件中心「社区」页由管理员开关「允许从社区注册表安装」；
+-- NULL 表示未在界面显式配置，服务端回落到环境变量 OPENLEARN_COMMUNITY_INSTALL
+-- （仅当值为 1 时开启；未设置则保持历史默认关闭）。
+-- 0 = 界面显式关闭（即使环境变量为 1）；1 = 界面显式开启。
+-- 默认必须为 NULL，不能写成 0，否则会掩盖环境变量回退。
+
+ALTER TABLE site_settings ADD COLUMN community_install_enabled INTEGER;
+
+-- DOWN
+ALTER TABLE site_settings DROP COLUMN community_install_enabled;

package/migrations/053_runtime_admin_policies.sql

@@ -0,0 +1,28 @@
+-- UP
+-- 053_runtime_admin_policies.sql
+-- 管理员可在后台「站点信息设置」中配置三项运行时策略；列默认必须为 NULL（未配置），
+-- 以便回退到环境变量，不能写成 0/默认值，否则会掩盖 ENV 回退并改变既有实际状态。
+--
+-- bridge_hook_telemetry: 课件网络遥测总闸。NULL=未配置；1=显式开启；0=显式关闭。
+--   未配置时回退 BRIDGE_HOOK_TELEMETRY（仅 off 关闭，其余/未设置默认开启）。
+-- http_access_log_mode: 访问日志策略。NULL=未配置；取值 off / errors / all。
+--   未配置时回退 HTTP_ACCESS_LOG，再回退 LOG_LEVEL=debug|trace → all，否则默认 errors。
+--   此项不是布尔开关，勿改成 0/1。
+-- http_access_log_ignore: 逗号分隔的路径前缀静默名单。NULL=未配置，回退 HTTP_ACCESS_LOG_IGNORE。
+-- http_slow_ms: 慢请求阈值（毫秒）。NULL=未配置，回退 HTTP_SLOW_MS（默认 1000）。
+-- allow_unsigned_plugins: 未签名本地插件默认放行。NULL=未配置；1=显式允许默认放行；0=显式收紧为逐次确认。
+--   未配置时回退 OPENLEARN_ALLOW_UNSIGNED（仅 0/false 收紧，未设置默认放行）。
+--   此策略不能绕过签名错误、公钥、网络限制、权限或沙箱。
+
+ALTER TABLE site_settings ADD COLUMN bridge_hook_telemetry INTEGER;
+ALTER TABLE site_settings ADD COLUMN http_access_log_mode TEXT;
+ALTER TABLE site_settings ADD COLUMN http_access_log_ignore TEXT;
+ALTER TABLE site_settings ADD COLUMN http_slow_ms INTEGER;
+ALTER TABLE site_settings ADD COLUMN allow_unsigned_plugins INTEGER;
+
+-- DOWN
+ALTER TABLE site_settings DROP COLUMN allow_unsigned_plugins;
+ALTER TABLE site_settings DROP COLUMN http_slow_ms;
+ALTER TABLE site_settings DROP COLUMN http_access_log_ignore;
+ALTER TABLE site_settings DROP COLUMN http_access_log_mode;
+ALTER TABLE site_settings DROP COLUMN bridge_hook_telemetry;

package/migrations/054_user_onboarding_tour_status.sql

@@ -0,0 +1,10 @@
+-- UP
+-- 054_user_onboarding_tour_status.sql
+-- Issue #530：按账号持久化管理员新手引导向导（HelpTour）状态，避免跳过/完成后
+-- 在刷新、重登（含开启 Clear-Site-Data）或更换设备后反复强制弹出，同时保证不同账号状态隔离。
+-- tour_status: NULL 表示待引导（pending）；'completed' 表示已完成；'skipped' 表示已跳过。
+
+ALTER TABLE users ADD COLUMN tour_status TEXT;
+
+-- DOWN
+ALTER TABLE users DROP COLUMN tour_status;

package/migrations/055_classroom_collab_whiteboard.sql

@@ -0,0 +1,27 @@
+-- UP
+-- 055_classroom_collab_whiteboard.sql
+-- 持久化随堂小组协作白板与画廊互评数据，按 (lesson_id, class_id) 隔离保存，
+-- 关闭/重开模态窗或刷新页面后仍可恢复分组、驱动题、笔画路径、点赞与思辨标签。
+
+CREATE TABLE IF NOT EXISTS classroom_collab_whiteboards (
+  id TEXT PRIMARY KEY,
+  lesson_id TEXT NOT NULL,
+  class_id TEXT NOT NULL DEFAULT '',
+  mission_prompt TEXT NOT NULL DEFAULT '',
+  grouping_strategy TEXT NOT NULL DEFAULT 'heterogeneous',
+  groups_json TEXT NOT NULL DEFAULT '[]',
+  strokes_json TEXT NOT NULL DEFAULT '[]',
+  likes_json TEXT NOT NULL DEFAULT '{}',
+  inquiries_json TEXT NOT NULL DEFAULT '{}',
+  spotlight_group_id TEXT,
+  updated_by TEXT,
+  updated_at INTEGER NOT NULL,
+  UNIQUE(lesson_id, class_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_collab_whiteboard_lesson
+  ON classroom_collab_whiteboards(lesson_id, class_id);
+
+-- DOWN
+DROP INDEX IF EXISTS idx_collab_whiteboard_lesson;
+DROP TABLE IF EXISTS classroom_collab_whiteboards;

package/migrations/056_public_student_lookup.sql

@@ -0,0 +1,9 @@
+-- UP
+-- 056_public_student_lookup.sql
+-- Issue #538：site_settings 表增加 allow_public_student_lookup（默认 1 开启），
+-- 控制登录页学生自助端是否允许未登录按姓名/班级公开查询学号。
+
+ALTER TABLE site_settings ADD COLUMN allow_public_student_lookup INTEGER DEFAULT 1;
+
+-- DOWN
+ALTER TABLE site_settings DROP COLUMN allow_public_student_lookup;

package/migrations/README.md

@@ -13,51 +13,62 @@
 
 ## 当前迁移列表
 
-| 序号 | 文件                                          | 描述                                                                                                                                                                                                                                                           |
-| ---- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 000  | 000_initial_schema.sql                        | 初始完整 Schema（30+ 表与核心索引）                                                                                                                                                                                                                            |
-| 001  | 001_add_execution_mode.sql                    | plugins 表添加 execution_mode                                                                                                                                                                                                                                  |
-| 002  | 002_add_client_session_expiry.sql             | client_sessions 添加 expires_at                                                                                                                                                                                                                                |
-| 003  | 003_classroom_runtime.sql                     | 课堂工具与 AI 对话记忆表（student_rollcalls, site_settings, agent_conversations）                                                                                                                                                                              |
-| 004  | 004_courseware_score_config.sql               | 互动课件成绩归集策略表（courseware_score_config，宿主侧按策略从样本历史算最终分）                                                                                                                                                                              |
-| 005  | 005_assignment_hub.sql                        | 作业中心（plugin_assignments / plugin_submission_versions / plugin_assignment_files / plugin_peer_review_tasks，并重建 plugin_submissions 支持按作业唯一）                                                                                                     |
-| 006  | 006_classroom_event_bus.sql                   | `events` 审计表补课堂维度：`lesson_id` 列与 (type,timestamp) / correlationId / (lesson_id,timestamp) 索引，让课堂事件可按时间窗口、业务流串联与课节重放查询                                                                                                    |
-| 007  | 007_interactive_classroom.sql                 | 互动课堂与课节生命周期（lesson_quiz_submissions / classroom_sessions / classroom_quick_polls / classroom_poll_votes / classroom_buzzers / classroom_exit_tickets / classroom_pacing_signals）                                                                  |
-| 008  | 008_teaching_modes.sql                        | 教学模式表 teaching_modes 与 classroom_sessions.teaching_mode_id（课堂启动门户的模式选择器数据源）                                                                                                                                                             |
-| 009  | 009_classroom_peer_review.sql                 | 课中互评（classroom_peer_review_groups / classroom_peer_review_submissions）                                                                                                                                                                                   |
-| 010  | 010_class_groups.sql                          | 小组（class_groups）                                                                                                                                                                                                                                           |
-| 011  | 011_classroom_feed.sql                        | 课堂动态流（classroom_feed）                                                                                                                                                                                                                                   |
-| 012  | 012_auto_record_score.sql                     | `courseware_score_config` 补自动录入规则列（auto_record_enabled / auto_record_min_completion），把「学生提交数据」页的逐条手动「录入成绩」升级为按规则自动录入                                                                                                 |
-| 013  | 013_score_source_strategy.sql                 | `assignment_submissions` 补 source 列（manual/auto 来源分流，自动路径遇 manual/缺考行受保护）+ `courseware_score_config` 补 auto_record_strategy（latest/highest 更新策略）                                                                                    |
-| 014  | 014_performance_indexes.sql                   | 五个高频查询索引（vfs_nodes.parent_id、plugin_submissions.lesson_id、student_point_logs.student_id、student_rollcalls.class_id/student_id）                                                                                                                    |
-| 015  | 015_demo_data_registry.sql                    | `demo_data_registry`：演示数据精确登记，清理时只删登记行                                                                                                                                                                                                       |
-| 016  | 016_preset_polls_and_passcode_expiry.sql      | 课程预设投票 `lesson_preset_polls`、班级口令有效期与点名奖赏字段                                                                                                                                                                                               |
-| 017  | 017_pacing_signals_segment.sql                | `classroom_pacing_signals.segment_id` 及会话分段索引                                                                                                                                                                                                           |
-| 018  | 018_processes_plugin_owner.sql                | `processes.plugin_id`，后台任务可判定归属                                                                                                                                                                                                                      |
-| 019  | 019_plugins_version.sql                       | `plugins.version`，版本可在 SQL 层查询                                                                                                                                                                                                                         |
-| 020  | 020_upload_max_file_mb.sql                    | `site_settings.upload_max_file_mb`，课件上传上限改为管理员可配置                                                                                                                                                                                               |
-| 021  | 021_class_owner_and_password_gate.sql         | `classes.owner_user_id`（教师仅能管理自己的班；空值仅管理员可见）与 `users.must_change_password`。空归属用 `node scripts/backfill-class-owners.mjs --assign <教师用户名>`，或 `UPDATE classes SET owner_user_id = '<教师用户 id>' WHERE owner_user_id IS NULL` |
-| 022  | 022_plugin_public_routes.sql                  | `plugin_public_routes`：管理员显式批准的插件公开路由。`auth: false` 本身不再匿名放行。升级后需重新批准                                                                                                                                                         |
-| 023  | 023_encrypt_class_passcodes.sql               | 标记班级临时口令改为 AES-256-GCM 密文。启动时 `encryptStoredClassPasscodes()` 把仍是明文的行加密，已带 `olenc1:` 的行跳过                                                                                                                                      |
-| 024  | 024_segment_gates.sql                         | 教学环节门槛：`segment_visits`（停留）、`segment_gate_overrides`（教师放行）、`lesson_checkins`（无排课时的签到）                                                                                                                                              |
-| 025  | 025_assignment_lookup_indexes.sql             | `assignment_submissions(student_id)` 与 `assignments(lesson_id)` 索引，供课节进度聚合作业最高分和学生提交查询。可重复执行                                                                                                                                      |
-| 026  | 026_plugin_grants.sql                         | 第三方插件能力授权与出站网络白名单表（`plugin_capability_grants` / `plugin_network_grants`）                                                                                                                                                                   |
-| 027  | 027_academic_year.sql                         | 学年维度：为 schedules/assignments/attendance/exams/semester reports 等表增加 `academic_year` 字段与索引；site_settings 增加当前学年配置                                                                                                                       |
-| 028  | 028_classroom_indexes.sql                     | 补齐课堂互动与会话高频查询/级联删除索引（`classroom_buzzers`、`classroom_sessions`）                                                                                                                                                                           |
-| 029  | 029_clean_lesson_think_artifacts.sql          | 课程大纲模型思维链残留 (<think>...</think>) 清洗标记与启动期幂等清理                                                                                                                                                                                           |
-| 030  | 030_backfill_academic_year.sql                | 学年历史数据回填：为老数据库中 NULL 学年的排课/作业/考勤等按日期与父级关联平滑补齐                                                                                                                                                                             |
-| 031  | 031_assessment_core.sql                       | 测评子系统核心数据结构（试卷、考试、题库、题目等）                                                                                                                                                                                                             |
-| 032  | 032_progress_verification.sql                 | 学习进度区分「学生自报」与「已验证」：新增 `verified` / `verified_progress_percent`，成绩只计入已验证进度；历史进度回填为已验证以保持既有成绩口径                                                                                                              |
-| 033  | 033_student_lock_mode.sql                     | 学生端锁定模式 (lock_mode) 与锁定目标 (lock_target)                                                                                                                                                                                                            |
-| 034  | 034_plugin_orphan_data.sql                    | 插件卸载数据语义：孤立插件数据登记表（`plugin_orphan_data`，keep 保留登记 / purge 归档后可清除）                                                                                                                                                               |
-| 035  | 035_icebreaker_checkins.sql                   | 课前破冰心情打卡持久化与去重（`icebreaker_checkins` 表与按学生去重唯一索引）                                                                                                                                                                                   |
-| 036  | 036_student_read_notifications_created_at.sql | 保留策略：为 `student_read_notifications` 补齐 `created_at` 以便按 30 天窗口清理                                                                                                                                                                               |
-| 037  | 037_plugin_config_scopes.sql                  | 插件配置分层：`plugin_config` 表（平台/学校/班级），旧 `plugin_storage` 的 `config:*` 值迁移到平台层                                                                                                                                                           |
-| 038  | 038_assessment_ai_grading_suggestion.sql      | AI 辅助批改建议：`assessment_answers.ai_suggestion_json` 存「建议分 + 理由 + 置信度」，与正式分数分开                                                                                                                                                          |
-| 039  | 039_question_bank_sharing_and_papers.sql      | 题库共享与按规则随机抽题（每人一卷）：`question_bank_items.visibility` 区分 private / school                                                                                                                                                                   |
-| 040  | 040_assignment_grade_history.sql              | 成绩审计与手动分保护：`assignment_grade_history` 记录每次成绩变更的旧/新分数、状态、来源与操作者                                                                                                                                                               |
-| 041  | 041_course_package_idempotency.sql            | 课程包导入幂等（G-06）：同一包重复导入不再产生重复课程                                                                                                                                                                                                         |
-| 042  | 042_assignment_grade_resubmit_audit.sql       | 学生重交审计：`assignment_grade_history` 补 `old_content`，可追溯「这份分数是针对哪份内容给的」                                                                                                                                                                |
-| 043  | 043_mark_sha256_passwords.sql                 | Issue #227：把仍是无盐 SHA-256 摘要的存量账号标记为 `must_change_password = 1`，强制走既有改密流程（SHA-256 不可逆，无法反推原口令）                                                                                                                           |
-| 044  | 044_students_gender.sql                       | 学生性别 `students.gender`（male / female / NULL），供课堂专注力监控头像按性别渲染；历史数据为空，由教师新建时补录                                                                                                                                             |
-| 045  | 045_ai_providers_owner_and_scope.sql          | Issue #383：AI 提供商账号级隔离与共享范围；`ai_providers` 表增加 `owner_id` 与 `is_shared`（0=私有/1=共享）及索引，历史数据平滑回填管理员私有                                                                                                                  |
+| 序号 | 文件                                          | 描述                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ---- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 000  | 000_initial_schema.sql                        | 初始完整 Schema（30+ 表与核心索引）                                                                                                                                                                                                                                                                                                                                                                        |
+| 001  | 001_add_execution_mode.sql                    | plugins 表添加 execution_mode                                                                                                                                                                                                                                                                                                                                                                              |
+| 002  | 002_add_client_session_expiry.sql             | client_sessions 添加 expires_at                                                                                                                                                                                                                                                                                                                                                                            |
+| 003  | 003_classroom_runtime.sql                     | 课堂工具与 AI 对话记忆表（student_rollcalls, site_settings, agent_conversations）                                                                                                                                                                                                                                                                                                                          |
+| 004  | 004_courseware_score_config.sql               | 互动课件成绩归集策略表（courseware_score_config，宿主侧按策略从样本历史算最终分）                                                                                                                                                                                                                                                                                                                          |
+| 005  | 005_assignment_hub.sql                        | 作业中心（plugin_assignments / plugin_submission_versions / plugin_assignment_files / plugin_peer_review_tasks，并重建 plugin_submissions 支持按作业唯一）                                                                                                                                                                                                                                                 |
+| 006  | 006_classroom_event_bus.sql                   | `events` 审计表补课堂维度：`lesson_id` 列与 (type,timestamp) / correlationId / (lesson_id,timestamp) 索引，让课堂事件可按时间窗口、业务流串联与课节重放查询                                                                                                                                                                                                                                                |
+| 007  | 007_interactive_classroom.sql                 | 互动课堂与课节生命周期（lesson_quiz_submissions / classroom_sessions / classroom_quick_polls / classroom_poll_votes / classroom_buzzers / classroom_exit_tickets / classroom_pacing_signals）                                                                                                                                                                                                              |
+| 008  | 008_teaching_modes.sql                        | 教学模式表 teaching_modes 与 classroom_sessions.teaching_mode_id（课堂启动门户的模式选择器数据源）                                                                                                                                                                                                                                                                                                         |
+| 009  | 009_classroom_peer_review.sql                 | 课中互评（classroom_peer_review_groups / classroom_peer_review_submissions）                                                                                                                                                                                                                                                                                                                               |
+| 010  | 010_class_groups.sql                          | 小组（class_groups）                                                                                                                                                                                                                                                                                                                                                                                       |
+| 011  | 011_classroom_feed.sql                        | 课堂动态流（classroom_feed）                                                                                                                                                                                                                                                                                                                                                                               |
+| 012  | 012_auto_record_score.sql                     | `courseware_score_config` 补自动录入规则列（auto_record_enabled / auto_record_min_completion），把「学生提交数据」页的逐条手动「录入成绩」升级为按规则自动录入                                                                                                                                                                                                                                             |
+| 013  | 013_score_source_strategy.sql                 | `assignment_submissions` 补 source 列（manual/auto 来源分流，自动路径遇 manual/缺考行受保护）+ `courseware_score_config` 补 auto_record_strategy（latest/highest 更新策略）                                                                                                                                                                                                                                |
+| 014  | 014_performance_indexes.sql                   | 五个高频查询索引（vfs_nodes.parent_id、plugin_submissions.lesson_id、student_point_logs.student_id、student_rollcalls.class_id/student_id）                                                                                                                                                                                                                                                                |
+| 015  | 015_demo_data_registry.sql                    | `demo_data_registry`：演示数据精确登记，清理时只删登记行                                                                                                                                                                                                                                                                                                                                                   |
+| 016  | 016_preset_polls_and_passcode_expiry.sql      | 课程预设投票 `lesson_preset_polls`、班级口令有效期与点名奖赏字段                                                                                                                                                                                                                                                                                                                                           |
+| 017  | 017_pacing_signals_segment.sql                | `classroom_pacing_signals.segment_id` 及会话分段索引                                                                                                                                                                                                                                                                                                                                                       |
+| 018  | 018_processes_plugin_owner.sql                | `processes.plugin_id`，后台任务可判定归属                                                                                                                                                                                                                                                                                                                                                                  |
+| 019  | 019_plugins_version.sql                       | `plugins.version`，版本可在 SQL 层查询                                                                                                                                                                                                                                                                                                                                                                     |
+| 020  | 020_upload_max_file_mb.sql                    | `site_settings.upload_max_file_mb`，课件上传上限改为管理员可配置                                                                                                                                                                                                                                                                                                                                           |
+| 021  | 021_class_owner_and_password_gate.sql         | `classes.owner_user_id`（教师仅能管理自己的班；空值仅管理员可见）与 `users.must_change_password`。空归属用 `node scripts/backfill-class-owners.mjs --assign <教师用户名>`，或 `UPDATE classes SET owner_user_id = '<教师用户 id>' WHERE owner_user_id IS NULL`                                                                                                                                             |
+| 022  | 022_plugin_public_routes.sql                  | `plugin_public_routes`：管理员显式批准的插件公开路由。`auth: false` 本身不再匿名放行。升级后需重新批准                                                                                                                                                                                                                                                                                                     |
+| 023  | 023_encrypt_class_passcodes.sql               | 标记班级临时口令改为 AES-256-GCM 密文。启动时 `encryptStoredClassPasscodes()` 把仍是明文的行加密，已带 `olenc1:` 的行跳过                                                                                                                                                                                                                                                                                  |
+| 024  | 024_segment_gates.sql                         | 教学环节门槛：`segment_visits`（停留）、`segment_gate_overrides`（教师放行）、`lesson_checkins`（无排课时的签到）                                                                                                                                                                                                                                                                                          |
+| 025  | 025_assignment_lookup_indexes.sql             | `assignment_submissions(student_id)` 与 `assignments(lesson_id)` 索引，供课节进度聚合作业最高分和学生提交查询。可重复执行                                                                                                                                                                                                                                                                                  |
+| 026  | 026_plugin_grants.sql                         | 第三方插件能力授权与出站网络白名单表（`plugin_capability_grants` / `plugin_network_grants`）                                                                                                                                                                                                                                                                                                               |
+| 027  | 027_academic_year.sql                         | 学年维度：为 schedules/assignments/attendance/exams/semester reports 等表增加 `academic_year` 字段与索引；site_settings 增加当前学年配置                                                                                                                                                                                                                                                                   |
+| 028  | 028_classroom_indexes.sql                     | 补齐课堂互动与会话高频查询/级联删除索引（`classroom_buzzers`、`classroom_sessions`）                                                                                                                                                                                                                                                                                                                       |
+| 029  | 029_clean_lesson_think_artifacts.sql          | 课程大纲模型思维链残留 (<think>...</think>) 清洗标记与启动期幂等清理                                                                                                                                                                                                                                                                                                                                       |
+| 030  | 030_backfill_academic_year.sql                | 学年历史数据回填：为老数据库中 NULL 学年的排课/作业/考勤等按日期与父级关联平滑补齐                                                                                                                                                                                                                                                                                                                         |
+| 031  | 031_assessment_core.sql                       | 测评子系统核心数据结构（试卷、考试、题库、题目等）                                                                                                                                                                                                                                                                                                                                                         |
+| 032  | 032_progress_verification.sql                 | 学习进度区分「学生自报」与「已验证」：新增 `verified` / `verified_progress_percent`，成绩只计入已验证进度；历史进度回填为已验证以保持既有成绩口径                                                                                                                                                                                                                                                          |
+| 033  | 033_student_lock_mode.sql                     | 学生端锁定模式 (lock_mode) 与锁定目标 (lock_target)                                                                                                                                                                                                                                                                                                                                                        |
+| 034  | 034_plugin_orphan_data.sql                    | 插件卸载数据语义：孤立插件数据登记表（`plugin_orphan_data`，keep 保留登记 / purge 归档后可清除）                                                                                                                                                                                                                                                                                                           |
+| 035  | 035_icebreaker_checkins.sql                   | 课前破冰心情打卡持久化与去重（`icebreaker_checkins` 表与按学生去重唯一索引）                                                                                                                                                                                                                                                                                                                               |
+| 036  | 036_student_read_notifications_created_at.sql | 保留策略：为 `student_read_notifications` 补齐 `created_at` 以便按 30 天窗口清理                                                                                                                                                                                                                                                                                                                           |
+| 037  | 037_plugin_config_scopes.sql                  | 插件配置分层：`plugin_config` 表（平台/学校/班级），旧 `plugin_storage` 的 `config:*` 值迁移到平台层                                                                                                                                                                                                                                                                                                       |
+| 038  | 038_assessment_ai_grading_suggestion.sql      | AI 辅助批改建议：`assessment_answers.ai_suggestion_json` 存「建议分 + 理由 + 置信度」，与正式分数分开                                                                                                                                                                                                                                                                                                      |
+| 039  | 039_question_bank_sharing_and_papers.sql      | 题库共享与按规则随机抽题（每人一卷）：`question_bank_items.visibility` 区分 private / school                                                                                                                                                                                                                                                                                                               |
+| 040  | 040_assignment_grade_history.sql              | 成绩审计与手动分保护：`assignment_grade_history` 记录每次成绩变更的旧/新分数、状态、来源与操作者                                                                                                                                                                                                                                                                                                           |
+| 041  | 041_course_package_idempotency.sql            | 课程包导入幂等（G-06）：同一包重复导入不再产生重复课程                                                                                                                                                                                                                                                                                                                                                     |
+| 042  | 042_assignment_grade_resubmit_audit.sql       | 学生重交审计：`assignment_grade_history` 补 `old_content`，可追溯「这份分数是针对哪份内容给的」                                                                                                                                                                                                                                                                                                            |
+| 043  | 043_mark_sha256_passwords.sql                 | Issue #227：把仍是无盐 SHA-256 摘要的存量账号标记为 `must_change_password = 1`，强制走既有改密流程（SHA-256 不可逆，无法反推原口令）                                                                                                                                                                                                                                                                       |
+| 044  | 044_students_gender.sql                       | 学生性别 `students.gender`（male / female / NULL），供课堂专注力监控头像按性别渲染；历史数据为空，由教师新建时补录                                                                                                                                                                                                                                                                                         |
+| 045  | 045_ai_providers_owner_and_scope.sql          | Issue #383：AI 提供商账号级隔离与共享范围；`ai_providers` 表增加 `owner_id` 与 `is_shared`（0=私有/1=共享）及索引，历史数据平滑回填管理员私有                                                                                                                                                                                                                                                              |
+| 046  | 046_logout_clear_site_data.sql                | Issue #487：`site_settings` 表增加 `logout_clear_site_data`（默认 0），支持管理后台按需开启登出时发送 `Clear-Site-Data: "cookies", "storage", "cache"` 响应头                                                                                                                                                                                                                                              |
+| 047  | 047_third_party_theme_system.sql              | Issue #484：第三方主题系统 —— `themes` / `theme_versions` / `user_theme_preferences` 三张表 + `site_settings.default_theme_id`，支撑主题包安装、版本历史、每账号隔离偏好与全站默认主题                                                                                                                                                                                                                     |
+| 048  | 048_file_storage_extension.sql                | 文件存储扩展架构：`file_blobs`、`file_assets`、`file_aliases` 表，以及 `site_settings.file_storage_config` 与 `plugin_assignment_files.asset_id` 字段                                                                                                                                                                                                                                                      |
+| 049  | 049_ai_personas.sql                           | AI 助手 Persona 持久化表（`ai_personas`）：支持内置与管理员创建的扩展型/替换式角色模板持久化、角色可见性、默认角色绑定、工具策略与最大推理轮次                                                                                                                                                                                                                                                             |
+| 050  | 050_ai_persona_governance.sql                 | Issue #510：新增 `ai_persona_governance` 扩展表，存储用途说明（`description_zh` / `description_en`）、启停状态（`enabled`）与绑定平台共享 AI 提供商字段（`preferred_provider_id`），支撑后台「AI 配置」全生命周期角色治理                                                                                                                                                                                  |
+| 051  | 051_community_registry_url.sql                | `site_settings` 表增加 `community_registry_url`（默认 NULL），支持在插件中心「社区」标签页动态配置并持久化社区插件注册表 JSON 地址，未设置时回落到环境变量 `PLUGIN_COMMUNITY_REGISTRY_URL`                                                                                                                                                                                                                 |
+| 052  | 052_community_install_enabled.sql             | `site_settings` 表增加 `community_install_enabled`（必须保持 NULL 表示未配置，不可默认写成 0）。管理员可在插件中心「社区」页开关「允许从社区注册表安装」；生效优先级为界面显式 1/0 > 未配置时环境变量 `OPENLEARN_COMMUNITY_INSTALL=1` > 默认关闭。此开关不能绕过签名公钥、权限或网络校验。                                                                                                                 |
+| 053  | 053_runtime_admin_policies.sql                | `site_settings` 增加 `bridge_hook_telemetry`、`http_access_log_mode`、`http_access_log_ignore`、`http_slow_ms`、`allow_unsigned_plugins`（必须保持 NULL 表示未配置，不可写成默认值）。管理员可在「站点信息设置 → 运行时策略」配置课件网络遥测、HTTP 访问日志（非布尔）与未签名本地插件策略；优先级为界面显式值 > 未配置时环境变量回退 > 历史默认。未签名策略不能绕过签名错误、公钥、网络限制、权限或沙箱。 |
+| 054  | 054_user_onboarding_tour_status.sql           | Issue #530：`users` 表增加 `tour_status`（默认 NULL 表示 pending，可选 `'completed'` / `'skipped'`），按账号在服务端持久化新手引导向导完成或跳过状态                                                                                                                                                                                                                                                       |
+| 055  | 055_classroom_collab_whiteboard.sql           | 互动课堂小组协作与画廊互评持久化表（`classroom_collab_whiteboards`）：按 `lesson_id` 存储各协作小组名单、分组策略、共创 SVG 画布与画廊展示模式状态，支持关闭弹窗与刷新后恢复                                                                                                                                                                                                                               |
+| 056  | 056_public_student_lookup.sql                 | Issue #538：`site_settings` 表增加 `allow_public_student_lookup`（默认 1 开启），控制登录页学生自助端是否允许按姓名/班级公开查询学号（管理员可在站点设置关闭）                                                                                                                                                                                                                                             |

package/migrations/schema-golden.json

@@ -1,13 +1,32 @@
 {
   "_comment": "数据库结构金样（自动生成，勿手改）：空库跑完 migrations/ 全部迁移后的表→列快照。启动时 assertSchemaMatchesGolden 以子集校验（实际库缺金样结构即拒绝启动；多出的表/列不报错）。改迁移后请运行 pnpm db:gen-golden 再生成。",
-  "migrationCount": 46,
-  "generatedAt": "2026-11-02T16:07:15.878Z",
+  "migrationCount": 57,
+  "generatedAt": "2026-11-15T12:33:26.414Z",
   "tables": {
     "_academic_year_backfill": ["backfilled_at", "id"],
     "_class_passcode_encryption": ["id", "note"],
     "_lesson_think_cleanup": ["id", "note"],
     "_migrations": ["applied_at", "checksum", "name"],
     "agent_conversations": ["content", "conv_key", "created_at", "id", "role"],
+    "ai_persona_governance": ["description_en", "description_zh", "enabled", "persona_id", "preferred_provider_id"],
+    "ai_personas": [
+      "base_policy",
+      "created_at",
+      "default_for_role_json",
+      "icon",
+      "id",
+      "instruction_en",
+      "instruction_zh",
+      "max_turns",
+      "mode",
+      "name_en",
+      "name_zh",
+      "plugin_id",
+      "source",
+      "tool_policy_json",
+      "updated_at",
+      "visibility_json"
+    ],
     "ai_providers": [
       "api_key",
       "api_url",
@@ -167,6 +186,20 @@
       "winner_student_id",
       "winner_student_name"
     ],
+    "classroom_collab_whiteboards": [
+      "class_id",
+      "grouping_strategy",
+      "groups_json",
+      "id",
+      "inquiries_json",
+      "lesson_id",
+      "likes_json",
+      "mission_prompt",
+      "spotlight_group_id",
+      "strokes_json",
+      "updated_at",
+      "updated_by"
+    ],
     "classroom_danmaku": [
       "created_at",
       "id",
@@ -322,6 +355,22 @@
     "events": ["correlationId", "id", "lesson_id", "payload", "source", "timestamp", "type"],
     "exam_scores": ["academic_year", "exam_id", "notes", "recorded_at", "score", "student_id"],
     "exams": ["academic_year", "class_id", "created_at", "description", "id", "max_score", "title"],
+    "file_aliases": ["alias", "asset_id"],
+    "file_assets": [
+      "access_scope",
+      "author_id",
+      "blob_id",
+      "course_id",
+      "created_at",
+      "deleted_at",
+      "id",
+      "lesson_id",
+      "metadata_json",
+      "mime",
+      "original_name",
+      "purpose"
+    ],
+    "file_blobs": ["backend_id", "created_at", "id", "ref_count", "sha256", "size_bytes", "storage_key"],
     "icebreaker_checkins": [
       "checkin_date",
       "class_id",
@@ -374,6 +423,7 @@
     "mfe_remotes": ["created_at", "entry", "meta", "name", "updated_at"],
     "pending_commands": ["actor_id", "command_type", "created_at", "id", "payload"],
     "plugin_assignment_files": [
+      "asset_id",
       "assignment_id",
       "deleted_at",
       "id",
@@ -545,9 +595,20 @@
     "segment_visits": ["entered_at", "id", "left_at", "lesson_id", "segment_id", "student_id"],
     "site_settings": [
       "academic_start_month",
+      "allow_public_student_lookup",
+      "allow_unsigned_plugins",
+      "bridge_hook_telemetry",
+      "community_install_enabled",
+      "community_registry_url",
       "current_academic_year",
+      "default_theme_id",
+      "file_storage_config",
+      "http_access_log_ignore",
+      "http_access_log_mode",
+      "http_slow_ms",
       "id",
       "logo_url",
+      "logout_clear_site_data",
       "site_name",
       "slogan",
       "upload_max_file_mb"
@@ -634,6 +695,40 @@
       "sort_order",
       "updated_at"
     ],
+    "theme_versions": [
+      "asset_manifest_json",
+      "created_at",
+      "manifest_json",
+      "styles_css",
+      "theme_id",
+      "uploader_id",
+      "version"
+    ],
+    "themes": [
+      "author",
+      "created_at",
+      "description",
+      "id",
+      "latest_version",
+      "manifest_json",
+      "name",
+      "platform_max_version",
+      "platform_min_version",
+      "status",
+      "styles_css",
+      "supports_modes",
+      "updated_at",
+      "uploader_id",
+      "uploader_name"
+    ],
+    "user_theme_preferences": [
+      "appearance_json",
+      "installed_version",
+      "mode",
+      "principal_key",
+      "theme_id",
+      "updated_at"
+    ],
     "users": [
       "avatar",
       "created_at",
@@ -643,6 +738,7 @@
       "password_hash",
       "role",
       "status",
+      "tour_status",
       "username"
     ],
     "vfs_nodes": ["content", "created_at", "id", "name", "parent_id", "type", "updated_at"],