文档架构：建立唯一现行系统真理文档门户 (Current Truth Bootstrap)

docs: bootstrap canonical current truth portal (00-START-HERE through 08-NEXT-ACTIONS)
2026-09-23 23:50:37 +08:00
1 parent 2f05f310ad
commit 8ad0f5172e
@@ -0,0 +1,74 @@
+# 01. 系统当前真实状态速览 (Current Status)
+
+> **系统正式名称**：`SYFJGYD学员管理系统`（内部工程代号：RailwaySystem）
+> **共享试用分支**：`feat/cicd-pipeline`
+> **共享试用地址**：[http://192.168.139.230:8082/](http://192.168.139.230:8082/)
+> **共享试用数据库**：`training`（国产人大金仓 KingbaseES V9 实例）
+> **当前试用就绪度**：`READY_WITH_EXTERNAL_BLOCKERS`（具备教务与教学现场试用条件）
+
+---
+
+## 1. 核心质量与验证状态表
+
+系统在完全隔离的真实局域网与 KingbaseES 数据库环境下完成了全量自动化验收与真实浏览器端到端交互，核心能力验证状态如下：
+
+| 验证维度 | 验证项 / 指标 | 状态结论 | 事实说明 |
+| :--- | :--- | :---: | :--- |
+| **核心教务主闭环** | 计划→课程→名单→排课→报到→考勤→结训 | **`PASS`** | 业务主链路 6 大正向场景全线打通，数据流转完整合规。 |
+| **管理员端交互** | Admin 控制台全生命周期管理 | **`PASS`** | 覆盖师资、学员、教室、场地、计划、考勤报表等无阻断操作。 |
+| **教师端工作台** | Teacher 个人课表、应到名单、代签打卡 | **`PASS`** | 真实无头 Chrome 浏览器 E2E 验证通过，课表与名单精准过滤。 |
+| **学员端培训中心** | Student 个人日程、考勤明细、住宿查询 | **`PASS`** | 仅展示本人培训与出勤数据，界面交互流畅。 |
+| **RBAC 与防越权** | 角色最小权限与防 IDOR 水平越权 | **`PASS`** | `IDOR_LEAK_COUNT = 0`，跨工号/跨学员数据篡改请求全部被 403 拦截。 |
+| **后端测试套件** | Maven 离线测试门禁 | **`331 / 331 PASS`** | 全量单元测试与契约测试 0 Failures / 0 Errors。 |
+| **数据库完整性** | 数据孤儿、重复调宿、外键断言 | **`PASS (0 孤儿)`** | 6 项完整性断言全部为 0，数据底座纯净。 |
+| **凭证合规审计** | 全量源码与配置文件 Secret 扫描 | **`PASS`** | `REAL_SECRET_COMMITTED_COUNT = 0`，无硬编码生产密码。 |
+| **成绩管理 (C03)** | 新成绩科目权重与录入计算 | **`IN_PROGRESS`** | 基础数据表已就绪，一期业务全闭环与交互正在推进中。 |
+| **学员画像 (C05)** | 学员画像能力 | **`PARTIAL_FUNCTION`** | 当前具备基础画像能力，完整业务范围与后续增强内容仍需继续完善或确认。 |
+| **智能门禁 (DMS)** | 真实环境连通与门锁联动 | **`PARTIALLY_VERIFIED`** | 鉴权/TTL/只读连通验证通过；真实设备与物理硬件因无资源外部阻塞。 |
+
+---
+
+## 2. 共享试用发布基线数据（2026-09-17）
+
+共享试用数据库 `training` 当前承载的数据来源于全量验证后的综合验收数据集，真实业务规模如下：
+
+```text
+========================================================================
+                     共享试用发布基线数据（2026-09-17）
+========================================================================
+  - 培训开班计划 (Plans)         : 13 期 (覆盖多专业、不同生命周期阶段)
+  - 授课教师档案 (Teachers)      : 20 名 (涵盖各专业骨干教员)
+  - 参训学员档案 (Students)      : 200 名 (全量完成身份证密文存储与脱敏)
+  - 标准培训课程 (Courses)       : 24 门 (理论与实作多门类)
+  - 排课课次日程 (Lessons)       : 118 次 (含四维冲突校验通过数据)
+  - 学员参训关系 (Enrollments)   : 242 条
+  - 宿舍分配台账 (Accommodations): 57 条 (防混住与单在用约束生效)
+  - 真实考勤流水 (Attendance)    : 77 条流水 (含签到、签退与请假修正)
+========================================================================
+```
+
+---
+
+## 3. DMS 智能门禁当前精确状态
+
+针对 DMS 智能门禁系统，团队已完成详尽技术探测与隔离验证，客观界定如下：
+
+1. **已验证通过部分 (Contract Verified)**：
+   - 针对文档示例凭据对应的可访问 DMS 环境，已在局域网下打通 HTTP 通信；
+   - 登录鉴权（AUTH=PASS）、Token TTL 机制（7200秒有效）、以及 Cookie Token 存储机制正常运行；
+   - 4 个只读接口连通性正常，外层响应结构符合空列表契约。
+2. **客观外部阻塞部分 (BLOCKED_EXTERNAL)**：
+   - 该可访问环境下目前**挂载的测试空间与实体门锁数量均为 0**；
+   - 真实空间与门锁行级字段映射尚未在运行时通过真实数据验证；
+   - 真实密码下发变更操作（Mutation）与实体通电门锁硬件属于客观外部依赖，待甲方划拨指定真实测试房间与硬件通电后方可闭环。
+
+---
+
+## 4. 结论与指引
+
+- **系统定性**：当前系统核心业务链路稳定，三角色体验完善，已具备交付沈阳房建公寓段业务老师进行**局域网教务教学试运行**的全部条件；
+- **后续阅读**：
+  - 需求完成度与待确认项：[02-phase1-status.md](02-phase1-status.md)
+  - 试用环境使用与反馈：[03-shared-trial.md](03-shared-trial.md)
+  - 共享试用账号与角色说明：[06-shared-trial-accounts.md](06-shared-trial-accounts.md)
+  - 未决缺口与外部阻塞：[04-known-gaps.md](04-known-gaps.md)
@@ -0,0 +1,36 @@
+# 02. 一期需求实现状态全景判定 (Phase 1 Status)
+
+> **最高原则**：**具备共享试用条件 ≠ 一期全部需求正式完成**。
+> 团队坚持实事求是，严格区分“核心教务已验证能力”与“待业务确认/研发推进中能力”，杜绝虚报与浮夸。
+
+---
+
+## 1. 需求落地分类汇总
+
+根据系统真实代码、数据库落地结构以及自动化 E2E 验证结果，一期规划需求状态精简分类如下：
+
+| 状态分类 | 包含的核心业务功能 | 现状说明与边界 |
+| :--- | :--- | :--- |
+| **`DONE_VERIFIED`**<br>(已完成并验证) | **1. 基础资源**：教师档案、学员主档（国密脱敏）、课程库、教室、实训场地、宿舍房间<br>**2. 教务主链**：开班计划（草稿/发布/结训）、一班多课绑定、参训名册导入、排课四维时段冲突预检<br>**3. 现场执行**：开班报到确认、课次出勤打卡、教师代签与请假修正、自主学时台账<br>**4. 权限与门户**：管理员控制台、教师个人课表工作台、学员个人培训中心、最小权限防越权 | 前后端代码、Kingbase 物理表、自动化测试（331 项）及浏览器 E2E 已全部通过，业务正向主闭环已完全就绪。 |
+| **`IN_PROGRESS`**<br>(研发推进中) | **成绩管理闭环 (C03)** | 新成绩体系基础表结构已就绪，成绩科目设置、加权得分计算及综合统计正在进行最终代码闭环与页面联调。 |
+| **`PARTIAL_FUNCTION`**<br>(部分能力具备) | **学员能力画像 (C05)** | 当前具备基础画像能力（档案卡与基础数据概览可用），完整业务范围与后续增强内容仍需继续完善或确认。 |
+| **`EXTERNAL_BLOCKER`**<br>(外部客观阻塞) | **真实门禁写操作与硬件联动 (DMS)** | 协议通信与只读连通已验证；因真实环境尚未挂载测试房间及门锁硬件通电，物理下发判定为外部客观阻塞。 |
+| **`CUSTOMER_CONFIRMATION`**<br>(待甲方业务确认) | **业务口径与组织架构归属** | 详见下方清单，涉及学员名册导入模版格式、报到核验现场硬件配备、请假与门禁权限保留策略等。 |
+
+---
+
+## 2. 权威需求跟踪入口
+
+如需查阅每一条需求的详细代码文件位置、SQL 表名、测试用例或具体待确认问题，请点击以下权威文档：
+
+- 📖 [**一期 PRD V1.0 (业务定义与需求基线)**](../requirements/一期PRD-V1.0.md)：一期系统正式业务需求冻结基线，涵盖核心领域对象、业务规则与一期开发边界。
+- 📋 [**一期需求实现进度表 (逐项核验)**](../requirements/一期需求实现进度表.md)：包含域 A~G 共数十项功能点的前后端代码文件、断言证据与下一步建议。
+- ❓ [**一期甲方需求确认清单 (开会对齐)**](../requirements/甲方需求确认清单.md)：系统归纳 P0(核心阻塞 18 项)、P1(业务形态 12 项)、P2(长远规划 8 项) 业务确认表。
+
+---
+
+## 3. 验收与交付策略
+
+1. **共享试用准入**：当前 `DONE_VERIFIED` 覆盖了沈阳房建公寓段开展职工日常集中面授的核心操作，已在局域网开放试用；
+2. **闭环收口原则**：针对 `IN_PROGRESS`（成绩）和 `PARTIAL_FUNCTION`（画像），研发团队在小版本迭代中收敛闭环；
+3. **外部硬件解除阻塞**：待甲方明确门锁房间划拨并完成物理连通后，即刻组织现场专项联调验收。
@@ -0,0 +1,49 @@
+# 03. 局域网共享试用指南 (Shared Trial Guide)
+
+> **重要性质声明**：
+> 1. 本环境为面向沈阳房建公寓段业务主管、教务人员与授课教员的**内部共享试用环境 (Shared Trial Environment)**；
+> 2. **本环境不是最终正式生产环境**，请勿录入未经授权的敏感业务核心数据；
+> 3. 代码部署分支为 `feat/cicd-pipeline`，请勿随意向该分支推送未经验证的代码。
+
+---
+
+## 1. 试用环境访问信息
+
+- **系统访问地址**：[http://192.168.139.230:8082/](http://192.168.139.230:8082/)
+- **网络准入要求**：需接入单位办公内网或通过指定局域网网段直接访问
+- **数据源基线**：已从综合验收基线（Integrated QA）全量提升导入至共享试用数据库 `training`，自带共享试用发布基线数据（2026-09-17 快照：13 计划、20 教师、200 学员、24 课程、118 课次、242 选课、57 住宿、77 考勤）；上述数据为发布快照，试用期间数据会持续变化，实时数量以 training 数据库为准。
+
+---
+
+## 2. 账号体系与角色类型
+
+系统严格划分三类业务角色，支持针对性体验。详细账号分配、统一测试登录密码及推荐体验步骤请参见：👉 [**共享试用账号说明 (06-shared-trial-accounts.md)**](06-shared-trial-accounts.md)。
+
+| 角色类型 | 代表账号身份 | 试用推荐场景 |
+| :--- | :--- | :--- |
+| **系统管理员 (Admin)** | 教务主管账号 | 登录后进入全功能控制台：体验新建培训计划、配置多门课程、导入参训学员、执行四维冲突排课、现场扫码/刷卡报到核验、宿舍房间分配等。 |
+| **授课教师 (Teacher)** | 专业主讲教员账号 | 登录后自动进入“教师工作台”：直观查阅个人本周授课日程、点击课次查看应到学员名册、进行课堂签到签退核验及代签补卡。 |
+| **参训学员 (Student)** | 在训职工学员账号 | 登录后自动进入“学员培训中心”：查阅本人参训计划、课表安排、个人历史考勤打卡记录、以及分配入住的宿舍房间。 |
+
+---
+
+## 3. 试用反馈与问题流转流程
+
+为确保试用反馈高效闭环，请按以下流程反馈问题与建议：
+
+```mermaid
+flowchart TD
+    A["试用人员发现问题 / 提出需求"] --> B["记录现象截图与复现步骤"]
+    B --> C["提交至项目微信群 / 试用问题登记表"]
+    C --> D["研发团队定级分类"]
+    D --> E1["🔴 BUG (功能缺陷)<br/>即时排查，进入热修复流程"]
+    D --> E2["🟡 UX (操作体验/展示优化)<br/>纳入小版本 UI 优化"]
+    D --> E3["🔵 KNOWN_GAP (已知缺口)<br/>对齐 C03/C05 计划进度"]
+    D --> E4["⚪ REQUIREMENT (新增需求)<br/>登记入《甲方需求确认清单》待甲方定级"]
+```
+
+---
+
+## 4. 试用注意事项
+1. **请勿执行清库或破坏性测试**：试用数据已形成完整的教学业务流转闭环，请在现有数据或新增独立计划基础上开展测试；
+2. **硬件联动说明**：若在界面上触发智能门锁相关操作，系统当前采用安全模拟与受控状态机流转，不会对外部物理设备产生破坏性冲击。
@@ -0,0 +1,35 @@
+# 04. 内部已知缺口与外部阻塞清单 (Known Gaps)
+
+> **透明度原则**：所有历史已修复缺陷已从本清单移出；本文件仅客观记录**当前尚未完全闭环的内部业务缺口**与**客观外部依赖项**，供研发排期与客户沟通时对照。
+
+---
+
+## 1. 内部研发已知缺口 (Internal Gaps)
+
+| 编号 | 模块 / 缺口项 | 当前实际状态 | 预期差距与原因说明 | 详细依据文档 |
+| :---: | :--- | :---: | :--- | :--- |
+| **G-01** | **成绩管理闭环 (C03)** | `IN_PROGRESS`<br>(推进中) | 物理数据库支持动态科目与权重设计已落地；一期完整正向评分流（教师端录入得分、加权自动折算、结业成绩汇总台账）前端交互正处于最后收敛阶段。 | [Round 3B 成绩能力评估](../reports/integrated-acceptance/INT_QA_R3B_20260917_094500/round-3b/score-current-capability.md) |
+| **G-02** | **学员画像能力 (C05)** | `PARTIAL_FUNCTION`<br>(部分能力) | `/portrait` 页面中基础档案与学时概览可用；当前具备基础画像能力，完整业务范围与后续增强内容仍需继续完善或确认。 | [Round 3B 画像能力评估](../reports/integrated-acceptance/INT_QA_R3B_20260917_094500/round-3b/portrait-current-capability.md) |
+
+---
+
+## 2. 外部客观阻塞事项 (External Blockers)
+
+| 编号 | 外部依赖项 | 当前判定 | 阻塞原因与解除条件 | 详细依据文档 |
+| :---: | :--- | :---: | :--- | :--- |
+| **B-01** | **DMS 真实空间与门锁行级映射** | `BLOCKED_EXTERNAL` | 文档示例凭据对应的 DMS 局域网环境认证连通通过，但该环境内挂载的房间与门锁资源数量均为 0，缺少真实行级数据以在运行时验证行级字段映射契约。<br>**解除条件**：厂商向测试环境分配真实房间数据。 | [DMS 终检状态报告](../reports/integrated-acceptance/FINAL_PHASE1_20260917_101044/dms-final-status.md) |
+| **B-02** | **DMS 真实写操作变更 (Mutation)** | `BLOCKED_EXTERNAL` | 密码下发与远程撤权接口在本地及 Mock 环境测试通过；在无真实测试房间挂载下，禁止向未知外部系统发起真实写操作。<br>**解除条件**：获得正式授权的测试门锁设备标识。 | [DMS 外部阻塞清单](../reports/integrated-acceptance/FINAL_PHASE1_20260917_101044/external-blockers.md) |
+| **B-03** | **DMS 物理硬件与实体通电** | `BLOCKED_EXTERNAL` | 缺少现场实体通电门锁与物理沙箱，无法验证物理刷卡开门或密码键盘实际响应。<br>**解除条件**：现场硬件通电联调。 | [DMS 外部阻塞清单](../reports/integrated-acceptance/FINAL_PHASE1_20260917_101044/external-blockers.md) |
+
+---
+
+## 3. 甲方待确认事项 (Customer Confirmations)
+
+目前有若干业务细节形态需要沈阳房建公寓段业务老师明确：
+1. **学员档案批量导入模版**：确认标准 Excel 表头字段口径与必填项；
+2. **现场报到主交互设备**：确认是一期现场电脑人工点击确认，还是外接读卡器或扫码枪；
+3. **住宿分配颗粒度**：确认一期排宿精确到具体房间号，还是必须精确到固定床位编号；
+4. **学员请假与门禁权限保留策略**：确认请假期间是否保留宿舍进出权限（当前系统默认策略：保留进门权限）；
+5. **考勤统计口径与分母待确认项**：确认请假是否计入出勤率分母、请假是否计入异常排行、待报到学员应到课次起算规则等（详见 [考勤统计语义与指标口径规范](07-analytics-attendance-semantics.md)）。
+
+👉 详细确认清单请查阅：[甲方需求确认清单 (P0/P1/P2)](../requirements/甲方需求确认清单.md)。
@@ -0,0 +1,38 @@
+# 05. 下一阶段工作模式与行动计划 (Next Actions)
+
+> **工作模式转型**：随着一期教务核心主链路与三角色工作台全面通过综合验收，项目工作模式已正式由“大规模基础闭环开发”转向**“共享试用驱动、敏捷小版本迭代”**。
+
+---
+
+## 1. 敏捷运作机制
+
+后续研发与交付严格遵循以下反馈流转机制：
+
+```mermaid
+flowchart TD
+    Step1["1. 局域网共享试用<br/>业务老师与主管开展教学排课/考勤试用"]
+    Step2["2. 问题归类与定级 (Triage)<br/>🔴 BUG: 阻断缺陷，当日修复回归<br/>🟡 UX: 交互体验，周版本批次优化<br/>🔵 KNOWN_GAP: 归入已知缺口排期<br/>⚪ REQUIREMENT: 登记入甲方清单待批"]
+    Step3["3. 小版本迭代发布 (Release Cycles)<br/>本地构建 → Surefire全量验证 → 部署试用"]
+
+    Step1 -->|"发现问题 / 提出需求"| Step2
+    Step2 -->|"敏捷推进"| Step3
+```
+
+---
+
+## 2. 下一阶段四大核心开发任务
+
+| 优先级 | 任务主题 | 核心目标与交付内容 | 负责范围 |
+| :---: | :--- | :--- | :--- |
+| **P0** | **响应共享试用现场反馈** | 快速响应业务老师在局域网试用中提出的交互阻滞、文案不准确或表单校验细节问题，保障试用体验平滑顺畅。 | 前端交互、教务微调 |
+| **P1** | **成绩管理闭环 (C03)** | 完善成绩科目配置、教师端分项打分、加权综合成绩折算与导出台账，完成该模块最后一公里闭环。 | `ruoyi-train` 后端及前端 |
+| **P2** | **学员画像能力完善 (C05)** | 在基础画像能力已具备的基础上，根据试用反馈和业务确认推进画像完整业务范围与后续增强内容。 | 数据分析、ECharts 视图 |
+| **P3** | **DMS 真实物理联调准备** | 持续跟踪段内智能门锁测试环境房间划拨与通电进度，一旦资源具备，立即启动现场行级数据验证与物理发码。 | DMS 适配器、现场联调 |
+
+---
+
+## 3. 分支与质量纪律
+
+1. **共享试用分支保护**：`feat/cicd-pipeline` 必须保持随时可试用状态；任何代码合并前必须通过 `mvn clean test`（331 项全绿）；
+2. **Git 中文规范**：所有新提交严格遵循 `<中文类型><可选范围>：<中文说明>` 格式；
+3. **安全底线**：严禁提交真实密码凭证，严禁执行非备份的清库操作。
@@ -0,0 +1,78 @@
+# 共享试用账号
+
+## 共享试用地址
+
+- **系统访问地址**：[http://192.168.139.230:8082/](http://192.168.139.230:8082/)
+- **适用环境**：SYFJGYD学员管理系统 — 局域网共享试用环境
+- **网页登录测试密码**：`admin123`（全员统一）
+
+---
+
+## 正常共享试用账号
+
+以下账号已在共享试用环境中完成真实全链路核验（状态均为正常可用），推荐供沈阳房建公寓段业务主管、教务人员及骨干教员试用体验：
+
+| 身份 | 用户名 | 密码 | 主要可见功能 | 适用测试场景 |
+| :--- | :--- | :--- | :--- | :--- |
+| **系统管理员 (Admin)** | `admin` | `admin123` | 人员管理（教师/学员）、教学设施、课程管理（课程/计划）、教学成果、自主学习、统计分析、学员画像、系统工具、系统管理 | 全系统全量功能总览、系统参数设置、用户与角色维护；当前具备教师、学员、课程等档案的安全删除能力（内置业务依赖防误删强拦截） |
+| **培训管理员 (Train Admin)** | `qa_train_admin` | `admin123` | 人员管理（教师/学员）、教学设施（教室/场地/宿舍/班牌/物联）、课程管理（课程/开班计划）、教学成果、自主学习、统计分析、学员画像 | 日常培训业务核心主流程体验：制定开班计划、课程排课冲突校验、学员报到核验、宿舍床位分配与综合统计（注：该账号不具备教师/学员/课程删除权限，专供安全日常业务流转试用） |
+| **授课教师 A** | `qa_teacher_a` | `admin123` | 教师工作台（我的授课计划、授课课表日程、任教班级学员名册、课次学员出勤查看） | 授课教师日常自服务场景：查看每周授课日程、查询班级学员花名册（敏感信息已脱敏）、核验课堂出勤流水 |
+| **授课教师 B** | `qa_teacher_b` | `admin123` | 教师工作台（我的授课计划、授课课表日程、任教班级学员名册、课次学员出勤查看） | 多教师并行授课场景、教师间授课日程与班级数据隔离效果验证 |
+| **参训学员 A** | `qa_student_a` | `admin123` | 学员中心（我的参训班级、最新开班报到凭据、个人参训课表、考勤打卡记录、累计学时、多维成长画像） | 学员全周期自服务体验：学员到校报到状态查阅、参训课表查看、打卡记录与个人综合素养画像核验 |
+| **参训学员 B** | `qa_student_b` | `admin123` | 学员中心（我的参训班级、个人参训课表、考勤打卡记录、累计学时、个人画像） | 学员间数据私密性与独立隔离核验、多学员并发体验 |
+
+---
+
+## 推荐体验顺序
+
+建议按照以下业务闭环顺序依次体验，以便建立清晰完整的系统认知：
+
+```mermaid
+flowchart LR
+    A["1. 管理员视角 (qa_train_admin)"] --> B["2. 教师视角 (qa_teacher_a)"]
+    B --> C["3. 学员视角 (qa_student_a)"]
+```
+
+### 1. 管理员视角体验（推荐使用 `qa_train_admin`）
+- **重点体验**：
+  - **开班计划管理**：在【课程管理 → 开班计划】中查看当前开班列表与各班级生命周期阶段；
+  - **四维排课防冲突**：查看已有课次安排与教师/教室占用时段；
+  - **学员管理与报到核对**：在【人员管理 → 学员信息】查验学员基本档案及报到流水；
+  - **宿舍与资源调配**：在【教学设施 → 宿舍信息】查验房间与床位分配情况；
+  - **统计分析大盘**：查阅开班签到、课程签到、学时统计与学员画像大盘。
+
+### 2. 教师视角体验（推荐使用 `qa_teacher_a`）
+- **重点体验**：
+  - **专属教师工作台**：登录后直接进入自服务界面，查看个人本周教学课表与授课日历；
+  - **班级学员名册**：点击所任课次，查看该班级参训学员列表（手机号等敏感信息已自动脱敏）；
+  - **课堂出勤核验**：查看所带课次的学员打卡流水与签到比例。
+
+### 3. 学员视角体验（推荐使用 `qa_student_a`）
+- **重点体验**：
+  - **学员个人中心**：查阅自身归属的参训班级信息；
+  - **报到凭据**：查看自身报到状态与班级通知；
+  - **参训课表与打卡**：查看个人课表安排以及历史打卡流水；
+  - **多维画像**：查看个人学习时长积累与多维能力分析呈现。
+
+---
+
+## 内部QA账号
+
+以下账号为研发与测试团队专用的边界防护与异常用例验证账号，标记为 **`INTERNAL_QA_ONLY`**。
+
+> [!WARNING]
+> **请勿将以下账号提供给普通甲方试用人员使用**。此类账号仅供内部自动化测试与边界防线验证。
+
+| 账号用户名 | 角色定位 | 内部用途说明 | 状态分类 |
+| :--- | :--- | :--- | :---: |
+| `qa_admin_teacher` | 管理员兼任教师 (双角色) | 用于验证具备复合角色时，顶层业务管理菜单与教师工作台的聚合展示与兼容性，验证跨角色场景下的操作边界。 | `INTERNAL_QA_ONLY` |
+| `qa_role_nobody` | 未绑定档案的孤儿角色 | 具备 `train_teacher` 权限角色，但在业务数据库中故意未关联任何具体教师业务档案。用于自动化验证服务端 `TrainingIdentityService` 的防越权强拦截机制（访问时会正确拦截并提示“未绑定任何教师档案”）。 | `INTERNAL_QA_ONLY` |
+
+---
+
+## 使用注意事项
+
+1. **演示与测试数据保护**：当前共享试用环境已预置完整教学闭环演练数据，请勿随意大批量删除已有班级、课程或历史履约数据，以免打断其他人员试用流程。
+2. **禁止批量删除**：请在现有数据或新增独立测试计划基础上开展业务验证，禁止针对基础字典、教室资源、既有人员等进行破坏性批量删除。
+3. **禁止真实 DMS 硬件操作**：当前环境门锁交互处于安全模拟与状态机受控流转模式，严禁对外部物理门锁硬件发起真实 Mutation 操作。
+4. **账号使用范围限制**：以上测试账号与统一密码仅限用于指定的局域网共享试用系统（`http://192.168.139.230:8082/`），严禁在其他环境复用或外传。
@@ -0,0 +1,71 @@
+# 07. 考勤统计语义与指标口径规范 (Attendance Analytics Semantics)
+
+> **版本**：V1.0 (Package C 闭环基线)  
+> **更新日期**：2026-09-21  
+> **适用模块**：管理驾驶舱 (Dashboard)、考勤专题分析 (Attendance Analytics)、学员 360 画像 (Student360)、考勤异常 Top 10  
+> **核心原则**：统一底层 Expected Attendance Universe 聚合语义，严格隔离未来课次，严格区分缺勤与未签到，技术语义守恒闭环。
+
+---
+
+## 1. 冻结技术语义 (Frozen Technical Semantics)
+
+| 技术语义项 | 规范定义 | 技术落地点 | 解决问题 |
+| :--- | :--- | :--- | :--- |
+| **已开始课次 (Started Lesson)** | `lesson.start_time <= CURRENT_TIMESTAMP`<br>未来课次打卡记录严格隔离，不得进入任何当前历史统计。 | `TrainAnalysisMapper.xml` 所有考勤聚合统一条件 `l.start_time <= CURRENT_TIMESTAMP` | **C07 关闭**：消除 Dashboard 状态分布泄漏 46 条未来课次打卡记录缺陷。 |
+| **应到基准集 (Expected Attendance Universe)** | `STARTED_LESSONS × PLAN_COURSES × ELIGIBLE_ENROLLMENTS LEFT JOIN CHECKIN`<br>由计划已开课次与计划参训学员关系形成应到基准，不得由打卡流水作为驱动表。 | 共享查询基准 `expectedAttendanceBase` / `filteredAttendanceConditions` | **C08 关闭**：消除异常 Top 10 仅从打卡流水统计导致未打卡学员不可见缺陷。 |
+| **显式缺勤 vs 未签到** | - **显式缺勤 (Explicit Absence)**：打卡流水存在且 `attendance_status = 0`。<br>- **未签到 (No Checkin)**：无打卡流水行（`checkin_id IS NULL`）。<br>两者在状态分布、Top 10、学员画像中严格互斥，不得隐式混淆。 | 状态派生：`CASE WHEN c.checkin_id IS NULL THEN 'NO_CHECKIN' ELSE CAST(c.attendance_status AS VARCHAR) END` | 杜绝将无流水学员擅自改写为 status=0，客观反映教务未核验状态。 |
+| **趋势时间轴 (Trend Time Axis)** | 每日考勤打卡走势时间轴必须锚定 `lesson.start_time`，严禁锚定 `sign_in_time`。<br>确保正常、迟到、早退、请假、明确缺勤、未签到均落入课次排课日期。 | `TO_CHAR(l.start_time, 'YYYY-MM-DD') AS stat_date` 统一分组 | **C06 关闭**：消除因 `sign_in_time IS NULL` 导致缺勤/请假/未签到无法进入走势的缺陷。 |
+| **状态分布守恒律** | `EXPECTED_PERSON_TIMES = NORMAL + LATE + EARLY + LEAVE + EXPLICIT_ABSENCE + NO_CHECKIN` | Dashboard 与 Attendance 共享 `buildStatusDistribution` | 全局与专题分析在无筛选或相同筛选条件下统计口径严格 1:1 相等。 |
+| **走势守恒律** | 筛选范围内各日期走势累加 `SUM(normal_count + abnormal_count)` 严格等于该范围内的 `EXPECTED_PERSON_TIMES`。 | `selectFilteredDailyTrend` | 走势无漏项、无未来虚假漂移。 |
+
+---
+
+## 2. 待确认业务定义清单 (Business Definitions Pending Confirmation)
+
+以下规则由于缺乏业务需求权威定论或底层数据表时序字段支撑，代码中均以策略开关或明确常量集中隔离，**严禁作为已定案的最终甲方规则**：
+
+### 2.1 PENDING-01: 待报到参训学员的应到基准 (`WAITING_ENROLLMENT_EXPECTED_POLICY`)
+- **状态**：`BUSINESS_DEFINITION_REQUIRED`
+- **问题说明**：学员参训记录为 `status=0`（待报到）且无报到核验流水时，是否从该培训班开班的第一节课起就计入应到基准分母。
+- **当前处理**：V1 默认不以 `EXISTS(train_class_report)` 过滤应到集合，确保未到场报到人员可进入缺勤/未签到统计；待甲方确认是否仅针对开班前已完成报名审核的名单起算。
+
+### 2.2 PENDING-02: 考勤请假是否计入出勤率分母 (`LEAVE_DENOMINATOR_POLICY`)
+- **状态**：`BUSINESS_DEFINITION_REQUIRED`
+- **问题说明**：学员在某课次拥有 `attendance_status=4`（请假）流水时，该人次是否从出勤率分母（应到人次）中扣除，还是保留在分母但计为非正常出勤。
+- **当前处理**：当前系统出勤率公式为 `正常出勤人次 / 应到总人次`（请假保留在分母，但非正常）。页面与 API 返回均携带 `metricDefinitionNotice = BUSINESS_METRIC_DEFINITION_PENDING_CONFIRMATION` 声明。
+
+### 2.3 PENDING-03: 放弃参训学员的历史课次有效性 (`ABANDON_HISTORICAL_POLICY`)
+- **状态**：`BUSINESS_DEFINITION_REQUIRED`
+- **问题说明**：学员参训状态为 `status=3`（放弃）时，由于 `train_enrollment` 表无状态变更生效时间区间（`HISTORICAL_ENROLLMENT_ELIGIBILITY_EXACT = NO`），无法精准切分放弃前与放弃后的课次。
+- **当前处理**：当前统计按所属计划完整名单统计，不利用当前最终状态逆向重写历史；待建立学员流转审计历史表后重构精确时间切片。
+
+### 2.4 PENDING-04: 请假是否计入考勤异常排行 (`LEAVE_COUNTS_AS_ABNORMAL`)
+- **状态**：`BUSINESS_DEFINITION_PENDING_CONFIRMATION`
+- **问题说明**：请假属于审批合规事项，部分管理制度认为请假不属于“违规异常考勤”，不应计入 Top 10 预警排行榜。
+- **当前处理**：集中在 `TrainAnalysisServiceImpl.LEAVE_COUNTS_AS_ABNORMAL_DEFAULT = true`（当前预览保持系统现有计入异常口径），并通过 `AttendanceFilterDto.includeLeaveAsAbnormal` 支持单点无缝切换，未散落硬编码。
+
+---
+
+## 3. 跨模块考勤统计语义对齐矩阵
+
+| 功能界面 / API | 基础驱动集 | 正常出勤 | 异常考勤构成 | 未签到 (无打卡) | 未来课次防护 |
+| :--- | :--- | :---: | :--- | :---: | :---: |
+| **管理驾驶舱 状态分布**<br>`/train/analysis/dashboard/charts` | 已开始课次 × 班级学员 | 正常出勤 (`1`) | 迟到(`2`)、早退(`3`)、请假(`4`)、缺勤(`0`) | 未签到 (`NO_CHECKIN`) | 隔离（0 泄漏） |
+| **管理驾驶舱 30天走势**<br>`/train/analysis/dashboard/charts` | 已开始课次 × 班级学员 | 正常人次 (`1`) | 异常人次 (`0,2,3,4,NO_CHECKIN`) | 计入异常人次 | 隔离（0 泄漏） |
+| **考勤专题 状态构成**<br>`/train/analysis/attendance/charts` | 已开始课次 × 班级学员 | 正常出勤 (`1`) | 迟到(`2`)、早退(`3`)、请假(`4`)、缺勤(`0`) | 未签到 (`NO_CHECKIN`) | 隔离（0 泄漏） |
+| **考勤专题 每日趋势**<br>`/train/analysis/attendance/charts` | 已开始课次 × 班级学员 | 正常人次 (`1`) | 异常人次 (`0,2,3,4,NO_CHECKIN`) | 计入异常人次 | 隔离（0 泄漏） |
+| **考勤异常 Top 10**<br>`/train/analysis/attendance/charts` | 已开始课次 × 班级学员 | 不参与排行 | 缺勤(`absentCount`)、迟到(`lateCount`)、早退(`earlyLeaveCount`)、请假(`leaveCount`) | 未签到 (`noCheckinCount`) | 隔离（0 泄漏） |
+| **学员 360 画像 考勤卡片**<br>`/train/analysis/portrait/student-360/{id}` | 该学员所属计划已开始课次 | 正常出勤 (`normalCount`) | 迟到、早退、请假、明确缺勤 | 未签到 (`noCheckinCount`) | 隔离（0 泄漏） |
+
+---
+
+## 4. 数据库只读验证事实 (Kingbase QA Live Snapshot)
+
+在 `railwaysystem_integrated_qa_20260916` 数据库实例上的只读验证结果：
+- 课次总数：118，其中已开始课次：1（Lesson 90），未来课次：117。
+- 考勤打卡记录总数：77，其中已开始课次打卡：31，未来课次打卡：46。
+- 已开始课次应到人次：31，打卡匹配人次：31，未签到人次：0。
+- 31 人次考勤分布：正常 31，迟到 0，早退 0，请假 0，缺勤 0，未签到 0。
+- 守恒断言：`EXPECTED_PERSON_TIMES (31) = NORMAL (31) + ABNORMAL (0)`，`PASS`。
+- 未来打卡泄漏：`FUTURE_LESSON_ANALYTICS_LEAK_COUNT = 0`，`PASS`。
+- `DUPLICATE_CHECKIN_KEY_COUNT = 0`，无重复打卡键。
@@ -0,0 +1,29 @@
+# SYFJGYD学员管理系统 — 当前项目速览中心 (Current)
+
+> **核心定位**：专为任何需要“在 3 分钟内快速掌握项目当前实际现状”的读者提供的唯一权威速览入口。
+> **正式业务名称**：`SYFJGYD学员管理系统`（内部工程代号：RailwaySystem）
+> **共享试用环境**：[http://192.168.139.230:8082/](http://192.168.139.230:8082/)（部署分支：`feat/cicd-pipeline`）
+> **当前试用就绪度**：`READY_WITH_EXTERNAL_BLOCKERS`（核心业务全通，具备局域网教学试用条件）
+
+---
+
+## 🧭 当前速览文件导航
+
+本目录包含 6 份精简、客观、直击核心事实的速览文档：
+
+| 文件 | 核心内容 | 推荐阅读对象 |
+| :--- | :--- | :--- |
+| [**01-current-status.md**](01-current-status.md) | **系统当前真实状态速览**（涵盖业务闭环、三角色、测试门禁与试用数据大盘） | 全体项目成员、新接手人员、管理层 |
+| [**02-phase1-status.md**](02-phase1-status.md) | **一期需求完成度判定**（严格分类 DONE / IN_PROGRESS / PARTIAL / 阻塞项） | 需求分析师、产品经理、验收人员 |
+| [**03-shared-trial.md**](03-shared-trial.md) | **共享试用环境使用指南**（环境用途、账号类型、试用反馈与问题流转规范） | 试用教师、业务主管、运维测试 |
+| [**04-known-gaps.md**](04-known-gaps.md) | **内部已知缺口与外部阻塞清单**（C03成绩、C05画像、DMS门锁与待确认项） | 研发人员、外部联调人员 |
+| [**05-next-actions.md**](05-next-actions.md) | **下一阶段行动路线**（工作模式转变、小版本迭代计划与近期重点） | 研发团队、项目协调人 |
+| [**06-shared-trial-accounts.md**](06-shared-trial-accounts.md) | **共享试用账号说明**（三类角色测试账号、登录凭据、推荐体验顺序与试用注意事项） | 甲方试用人员、业务主管、测试人员 |
+
+---
+
+## 📌 阅读建议
+- 如果你只想知道**“系统做成啥样了、跑通了哪些功能”**：请直接阅读 [01-current-status.md](01-current-status.md)；
+- 如果你要去和**“沈阳房建公寓段领导/指导老师开会对需求”**：请直接阅读 [02-phase1-status.md](02-phase1-status.md) 并带上需求清单；
+- 如果你正准备**“在局域网试用系统并提出反馈”**：请直接阅读 [03-shared-trial.md](03-shared-trial.md) 与 [06-shared-trial-accounts.md](06-shared-trial-accounts.md) 获取登录账号与体验指引；
+- 如果你要**“继续写代码或排期”**：请直接阅读 [04-known-gaps.md](04-known-gaps.md) 与 [05-next-actions.md](05-next-actions.md)。