railwaysystem/docs/database-v2/01_table_inventory.md

# RailwaySystem 数据库 V2 表结构清单与模型比对 (Round 1 修订版)

> **技术依据**：[`RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md`](../archive/database-history/RailwaySystem%20数据库%20V2%20字段设计与%20Kingbase%20DDL%20规范%20V1.0.md)
> **状态**：一期 21 张培训业务表全覆盖冻结清单（已完成 Round 1 字段与约束精确审查修订）。

---

## 1. 21 张正式表全景分类

```mermaid
mindmap
  root((RailwaySystem V2 业务表))
    基础资料表 (9张)
      train_teacher (教师主档)
      train_student (学员长期主档)
      train_course (课程基础主档)
      train_resource (新增: 统一教学资源)
      train_course_resource (新增: 课程资源关联)
      train_classroom_info (教室信息)
      train_training_site (实训场地)
      train_electronic_board (电子班牌设备)
      train_dormitory_info (宿舍房间)
    培训组织表 (4张)
      train_class_plan (培训班主档)
      train_plan_course (新增: 培训班课程实例)
      train_enrollment (新增: 学员参训档案)
      train_lesson (新增: 教学活动课次)
    培训执行表 (4张)
      train_accommodation (新增: 学员住宿安排)
      train_dorm_auth (门禁授权同步)
      train_class_report (现场报到记录)
      train_student_checkin (课次考勤打卡)
    培训结果表 (4张)
      train_score_item (新增: 考核成绩项配置)
      train_student_score (新增: 学员单项成绩明细)
      train_study_duration (自主学习时长记录)
      train_student_portrait (学员全期画像评估)
    淘汰表 (1张)
      train_score_info (彻底下线)
```

---

## 2. 三大核心 ID 架构映射

V2 架构通过三个领域核心 ID 彻底取代旧模型中跨多表重复冗余的复合外键串（`student_id + plan_id + c_id + lesson_time`）：

| 核心 ID 标识 | 业务实体表 | 业务语义 | 衍生与引用的业务表 |
| :--- | :--- | :--- | :--- |
| **`enrollment_id`** | [`train_enrollment`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql#L72) | **某学员参加某一期培训班的参训全生命周期档案** | `train_accommodation`<br>`train_class_report`<br>`train_student_checkin`<br>`train_student_score`<br>`train_study_duration`<br>`train_student_portrait` |
| **`plan_course_id`** | [`train_plan_course`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql#L52) | **某一期培训班中包含的某一门具体课程实例** | `train_lesson`<br>`train_score_item`<br>`train_study_duration` |
| **`lesson_id`** | [`train_lesson`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql#L106) | **本期某门课程中的具体一次教学活动（课表课次）** | `train_student_checkin` |

---

## 3. 21 张正式表详细结构与新旧比对 (含 Round 1 修订)

### 3.1 基础资料模块 (9 张)

#### 1. `train_teacher` (保留并结构升级)
- **主键**：`t_id` (varchar(32))
- **数据保留**：保留当前生产环境唯一 1 行数据。
- **字段变更**：
  - 新增：`user_id` (bigint), `org_name` (varchar(100)), `job_title` (varchar(50)), `status` (smallint NOT NULL), `create_by` (varchar(64)), `update_by` (varchar(64)), `del_flag` (char(1) NOT NULL)；
  - 调整列宽：`t_name` varchar(50), `t_email` varchar(100), `remark` varchar(500)；
  - 数据迁移：由 `008_migrate_teacher.sql` 将 `t_department` -> `org_name`, `t_title` -> `job_title`, `create_user` -> `create_by`，并在校验后将 `status` 与 `del_flag` 固化为 `NOT NULL`；
  - 淘汰删除：`t_department`, `t_title`, `create_user`。

#### 2. `train_student` (保留并重构为企业培训主档)
- **主键**：`s_id` (varchar(32))
- **字段变更**：
  - 彻底淘汰高校概念旧列：删除 `s_department`, `s_major`, `s_class`, `create_user`；
  - 新增：`user_id` (bigint), `org_name` (varchar(100)), `s_email` (varchar(100)), `id_card_ciphertext` (text, 密文), `id_card_hash` (varchar(128), 精确防重哈希), `id_card_last4` (varchar(4), 脱敏展示), `face_ref` (varchar(255), 人脸凭据), `source_type` (smallint NOT NULL, 1管理员录入/2Excel导入/3平台同步), `status` (smallint NOT NULL), `create_by`, `update_by`, `del_flag`；
  - 约束：`UNIQUE(id_card_hash)` (允许为 NULL)。

#### 3. `train_course` (保留并解耦资源附件)
- **主键**：`c_id` (varchar(32))
- **字段变更**：
  - 彻底淘汰集中附件旧列：删除 `attach_doc`, `attach_video`, `attach_model_link`, `model_resource_ids`, `create_user`；
  - 新增：`c_code` (varchar(50), 统一编码), `status` (smallint NOT NULL), `create_by`, `update_by`, `del_flag`；
  - 约束：`UNIQUE(c_code)`。

#### 4. `train_resource` (V2 全新建表)
- **主键**：`resource_id` (varchar(32))
- **字段**：`resource_id`, `resource_name`, `resource_type` (1文档/2视频/3 3D模型/4 VR资源/5外部链接/6其他), `resource_url`, `description`, `status`, `create_by`, `create_time`, `update_by`, `update_time`, `remark`, `del_flag`。

#### 5. `train_course_resource` (V2 全新建表)
- **主键**：`id` (bigint identity)
- **字段**：`id`, `c_id`, `resource_id`, `sort_no`, `create_by`, `create_time`。
- **约束**：`UNIQUE(c_id, resource_id)`, 外键指向 `train_course` 与 `train_resource`。

#### 6. `train_classroom_info` (保留并补齐审计)
- **主键**：`class_room_id` (varchar(32))
- **字段变更**：删除 `create_user`；补齐 `create_by`, `update_by`, `del_flag`；设置 `room_status` NOT NULL。

#### 7. `train_training_site` (保留并补齐审计)
- **主键**：`site_id` (varchar(32))
- **字段变更**：删除 `create_user`；补齐 `create_by`, `update_by`, `del_flag`；设置 `site_status` NOT NULL。

#### 8. `train_electronic_board` (保留并升级交互架构)
- **主键**：`board_id` (varchar(32))
- **字段变更**：
  - 解绑旧关系：删除 `bind_plan_id`, `board_content`, `board_playmode`, `create_user`；
  - 新增：`board_name` (varchar(100) NOT NULL, 必填无默认空串), `api_endpoint` (varchar(255)), `create_by`, `update_by`, `del_flag`；
  - 约束：`UNIQUE(board_sn)`。

#### 9. `train_dormitory_info` (保留并优化房态模型)
- **主键**：`dorm_id` (varchar(32))
- **字段变更**：
  - 移除旧计数列：删除 `bed_total`, `bed_used`；
  - 新增：`dorm_floor` (varchar(20) NOT NULL, 无猜测默认值), `capacity` (integer NOT NULL, 无猜测默认值), `gender_type` (smallint, 0不限/1男/2女), `create_by`, `update_by`, `del_flag`；
  - 约束：`UNIQUE(dorm_building, dorm_room)`, `CHECK (capacity > 0)`。
  - **特别声明**：严禁增加 `train_dorm_bed` 表。

---

### 3.2 培训组织模块 (4 张)

#### 10. `train_class_plan` (保留并重构为一班多课)
- **主键**：`plan_id` (varchar(32))
- **字段变更**：删除旧单课 `c_id` 与旧教师 `t_id` 及 `create_user`；新增 `report_deadline`, `create_by`, `update_by`, `del_flag`。

#### 11. `train_plan_course` (V2 全新建表)
- **主键**：`plan_course_id` (bigint identity)
- **字段**：`plan_course_id`, `plan_id`, `c_id`, `sort_no`, `create_by`, `create_time`, `remark`。
- **约束**：`UNIQUE(plan_id, c_id)`。

#### 12. `train_enrollment` (V2 全新建表 - 系统最核心关系)
- **主键**：`enrollment_id` (bigint identity)
- **字段**：`enrollment_id`, `plan_id`, `student_id`, `source_type` (smallint NOT NULL, 参训名单来源，由 train_enrollment_source 字典定义，无默认值), `enrollment_status` (DEFAULT 0 待报到), `accommodation_required` (smallint NOT NULL, 无默认值), `join_time`, `complete_time`, `create_by`, `create_time`, `update_by`, `update_time`, `remark`。
- **约束**：`UNIQUE(plan_id, student_id)`。
- **注意**：此处 `source_type` 表示学员进入本期培训班名单的来源，与 `train_student.source_type`（长期人员主档来源）语义完全不同，严禁混用。

#### 13. `train_lesson` (V2 全新建表)
- **主键**：`lesson_id` (bigint identity)
- **字段**：`lesson_id`, `plan_course_id`, `t_id` (varchar(32) NOT NULL, 课次必要组成), `start_time`, `end_time`, `venue_type` (smallint NOT NULL, 1普通教室/2实训场地，无默认值), `class_room_id`, `site_id`, `create_by`, `create_time`, `update_by`, `update_time`, `remark`。
- **约束**：
  - `CHECK (start_time < end_time)`；
  - `CHECK ((venue_type = 1 AND class_room_id IS NOT NULL AND site_id IS NULL) OR (venue_type = 2 AND site_id IS NOT NULL AND class_room_id IS NULL))` (场地单行互斥)。

---

### 3.3 培训执行模块 (4 张)

#### 14. `train_accommodation` (V2 全新建表)
- **主键**：`accommodation_id` (bigint identity)
- **字段**：`accommodation_id`, `enrollment_id`, `dorm_id`, `bed_no`, `assigned_time`, `accommodation_status` (smallint NOT NULL DEFAULT 0, 0预分配/1已入住/2已退宿), `create_by`, `create_time`, `update_by`, `update_time`, `remark`。
- **约束**：`UNIQUE(enrollment_id)`。

#### 15. `train_dorm_auth` (重构重建)
- **主键**：`auth_id` (bigint identity)
- **字段**：`auth_id`, `accommodation_id`, `auth_start`, `auth_end`, `face_sync_status` (DEFAULT 0 待下发), `retry_count` (DEFAULT 0), `last_error`, `external_auth_id`, `last_sync_time`, `create_by`, `create_time`, `update_by`, `update_time`, `remark`。
- **约束**：`UNIQUE(accommodation_id)`。

#### 16. `train_class_report` (重构重建)
- **主键**：`report_id` (bigint identity)
- **字段**：`report_id`, `enrollment_id`, `report_way` (smallint NOT NULL), `report_device_sn`, `report_time`, `verify_result` (smallint NOT NULL, 1通过/2不匹配/3人工放行，无默认值), `verify_note`, `create_by`, `create_time`, `remark`。
- **约束**：`UNIQUE(enrollment_id)`。

#### 17. `train_student_checkin` (重构重建)
- **主键**：`checkin_id` (bigint identity)
- **字段**：`checkin_id`, `enrollment_id`, `lesson_id`, `board_id`, `checkin_way` (smallint NOT NULL, 1人脸/2刷卡/3扫码/4代签，无默认值), `sign_in_time`, `sign_out_time`, `attendance_status` (DEFAULT 0 缺勤), `manual_flag` (DEFAULT 0 自动), `create_by`, `create_time`, `update_by`, `update_time`, `remark`。
- **约束**：`UNIQUE(enrollment_id, lesson_id)`。

---

### 3.4 培训结果模块 (4 张)

#### 18. `train_score_item` (V2 全新建表)
- **主键**：`score_item_id` (bigint identity)
- **字段**：`score_item_id`, `plan_id`, `plan_course_id`, `item_name`, `item_type`, `weight`, `full_score`, `sort_no`, `create_by`, `create_time`, `update_by`, `update_time`, `remark`。
- **约束**：`CHECK (weight >= 0.00 AND weight <= 100.00)`, `CHECK (full_score > 0.00)`。

#### 19. `train_student_score` (V2 全新建表)
- **主键**：`score_id` (bigint identity)
- **字段**：`score_id`, `enrollment_id`, `score_item_id`, `score` (numeric(7,2) NOT NULL, 无默认0), `source_type`, `source_system`, `source_event_id`, `import_time`, `create_by`, `create_time`, `update_by`, `update_time`, `remark`。
- **约束**：`UNIQUE(enrollment_id, score_item_id)`, `CHECK (score >= 0.00)`。

#### 20. `train_study_duration` (重构重建)
- **主键**：`dur_id` (bigint identity)
- **字段**：`dur_id`, `enrollment_id`, `plan_course_id`, `resource_id`, `learning_content`, `source_system`, `source_event_id`, `start_time`, `end_time`, `study_seconds`, `sync_time`, `create_by`, `create_time`, `remark`。
- **约束**：
  - `CHECK (study_seconds >= 0)`；
  - `CHECK (end_time IS NULL OR start_time IS NULL OR end_time >= start_time)`；
  - `CHECK (source_event_id IS NULL OR source_system IS NOT NULL)`；
  - 双非空部分唯一索引：`UNIQUE(source_system, source_event_id) WHERE source_system IS NOT NULL AND source_event_id IS NOT NULL`。

#### 21. `train_student_portrait` (重构重建)
- **主键**：`portrait_id` (bigint identity)
- **字段**：`portrait_id`, `enrollment_id`, `attendance_rate`, `theory_score`, `practical_score`, `total_study_hour`, `label_tag`, `portrait_content`, `generated_time`, `create_by`, `create_time`, `update_by`, `update_time`, `remark`。
- **约束**：`UNIQUE(enrollment_id)`。

---

## 4. 淘汰旧表说明

### `train_score_info`
- **处理方式**：彻底下线并从 public 生产 schema 中 DROP；
- **现状保障**：实测当前行数精确为 0，无任何真实数据迁移风险。