diff --git a/docs/README.md b/docs/README.md index ac4291604..3f8aeb92a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,7 @@ # SYFJGYD学员管理系统 — 文档中心全景地图 (Docs Map) > **正式业务名称**：`SYFJGYD学员管理系统`（内部工程代号：RailwaySystem） -> **共享试用环境**：[http://192.168.139.230:8082/](http://192.168.139.230:8082/)（部署分支：`feat/cicd-pipeline`，登录账号请参见 [共享试用账号说明](current/06-shared-trial-accounts.md)） +> **共享试用环境**：[http://192.168.139.230:8082/](http://192.168.139.230:8082/)（部署分支：`feat/cicd-pipeline`，运行状态请参见 [01-CURRENT-SYSTEM-STATE.md](current/01-CURRENT-SYSTEM-STATE.md)） > **核心质量结论**：核心教务正向闭环全面就绪，三角色工作台验证通过，测试全绿 **331 / 331 PASS**。 --- @@ -29,14 +29,17 @@ ## 📚 各目录体系深度说明 -### 1. 🌟 [docs/current/](current/README.md) — 【首选】当前系统真实速览 -专为需要**“在 3 分钟内快速掌握项目当前实际现状”**的读者设计，杜绝翻阅陈旧长日志： -- [01-current-status.md](current/01-current-status.md)：当前系统真实状态、试用数据大盘与质量指标 -- [02-phase1-status.md](current/02-phase1-status.md)：一期需求完成度精简分类判定 -- [03-shared-trial.md](current/03-shared-trial.md)：局域网共享试用环境使用指引与反馈通道 -- [04-known-gaps.md](current/04-known-gaps.md)：当前有效技术缺口（C03成绩/C05画像/DMS外部阻塞） -- [05-next-actions.md](current/05-next-actions.md)：敏捷小版本迭代工作模式与近期重点 -- [06-shared-trial-accounts.md](current/06-shared-trial-accounts.md)：共享试用账号说明（三类角色测试账号、统一登录密码与体验注意事项） +### 1. 🌟 [docs/current/00-START-HERE.md](current/00-START-HERE.md) — 【唯一首选入口】当前系统现行真理中心 +专为人类与 Agent 设立的**唯一权威现行真理门户**，杜绝历史长日志篡权： +- [00-START-HERE.md](current/00-START-HERE.md)：**第一入口**（真理优先级声明与全量当前文档导航） +- [01-CURRENT-SYSTEM-STATE.md](current/01-CURRENT-SYSTEM-STATE.md)：当前系统真实运行基线、技术栈与工作树状态 +- [02-FUNCTION-MODULES.md](current/02-FUNCTION-MODULES.md)：业务功能模块全量五级判定 (IMPLEMENTED/PARTIAL/MOCK/BLOCKED_EXTERNAL/NOT_IMPLEMENTED) +- [03-DATABASE-AND-TABLES.md](current/03-DATABASE-AND-TABLES.md)：KingbaseES 物理表结构、迁移链与纯净演示库重建规约 +- [04-API-INVENTORY.md](current/04-API-INVENTORY.md)：全量 API 接口账本（路径、方法、源码分类、控制器、关联物理表） +- [05-CLIENT-API-STATUS.md](current/05-CLIENT-API-STATUS.md)：甲方与外部接口状态清单（REAL_LIVE/NOT_YET_TESTED/MOCK） +- [06-DEMO-BASELINE.md](current/06-DEMO-BASELINE.md)：演示基线准则（旧Demo不可信声明与新Demo确定性构建七大原则） +- [07-KNOWN-GAPS.md](current/07-KNOWN-GAPS.md)：内部已知缺口与外部阻塞清单（包含 ACCOM-PERM-01 阻断项） +- [08-NEXT-ACTIONS.md](current/08-NEXT-ACTIONS.md)：下一阶段标准化 14 步行动路线图 --- diff --git a/docs/current/01-current-status.md b/docs/archive/shared-trial-baseline-20260920/01-current-status.md similarity index 100% rename from docs/current/01-current-status.md rename to docs/archive/shared-trial-baseline-20260920/01-current-status.md diff --git a/docs/current/02-phase1-status.md b/docs/archive/shared-trial-baseline-20260920/02-phase1-status.md similarity index 100% rename from docs/current/02-phase1-status.md rename to docs/archive/shared-trial-baseline-20260920/02-phase1-status.md diff --git a/docs/current/03-shared-trial.md b/docs/archive/shared-trial-baseline-20260920/03-shared-trial.md similarity index 100% rename from docs/current/03-shared-trial.md rename to docs/archive/shared-trial-baseline-20260920/03-shared-trial.md diff --git a/docs/current/04-known-gaps.md b/docs/archive/shared-trial-baseline-20260920/04-known-gaps.md similarity index 100% rename from docs/current/04-known-gaps.md rename to docs/archive/shared-trial-baseline-20260920/04-known-gaps.md diff --git a/docs/current/05-next-actions.md b/docs/archive/shared-trial-baseline-20260920/05-next-actions.md similarity index 100% rename from docs/current/05-next-actions.md rename to docs/archive/shared-trial-baseline-20260920/05-next-actions.md diff --git a/docs/current/06-shared-trial-accounts.md b/docs/archive/shared-trial-baseline-20260920/06-shared-trial-accounts.md similarity index 100% rename from docs/current/06-shared-trial-accounts.md rename to docs/archive/shared-trial-baseline-20260920/06-shared-trial-accounts.md diff --git a/docs/current/07-analytics-attendance-semantics.md b/docs/archive/shared-trial-baseline-20260920/07-analytics-attendance-semantics.md similarity index 100% rename from docs/current/07-analytics-attendance-semantics.md rename to docs/archive/shared-trial-baseline-20260920/07-analytics-attendance-semantics.md diff --git a/docs/current/README.md b/docs/archive/shared-trial-baseline-20260920/README.md similarity index 100% rename from docs/current/README.md rename to docs/archive/shared-trial-baseline-20260920/README.md diff --git a/docs/current/00-START-HERE.md b/docs/current/00-START-HERE.md new file mode 100644 index 000000000..2e277b2ab --- /dev/null +++ b/docs/current/00-START-HERE.md @@ -0,0 +1,71 @@ +# 00 - RailwaySystem 现行系统唯一权威真理入口 (Start Here) + +```text +SOURCE OF TRUTH PRIORITY + +1. docs/current/** +2. current source code / migrations +3. confirmed client requirements +4. current test evidence +5. historical reports + +docs/reports/** MUST NOT be treated as current truth. +``` + +--- + +## 1. 核心定位与真理唯一性法则 + +本目录（`docs/current/`）是 **SYFJGYD学员管理系统**（内部工程代号：`RailwaySystem`）面向所有研发人员、测试工程师、交付团队、管理人员以及 **AI 智能体 (Agent)** 的**唯一权威真理中心**。 + +在过去多轮并行迭代与验证过程中，项目沉淀了大量历史测试、审计与阶段报告（存放于 `docs/reports/**`）。为防止历史快照篡权和事实失真，确立以下不可动摇的法则： +1. **真理优先级铁律**：如首屏声明，`docs/current/**` 拥有最高文档解释权，任何 `docs/reports/**` 下的历史报告仅作为时间序列凭证，**绝对不得覆盖本目录所载明的当前事实**。 +2. **唯一入口导航**：人类读者与 Agent 接手任务时，必须以本文件为第一入口，禁止直接引用散落在历史报告中的过期结论。 +3. **实事求是原则**：所有现状描述直接锚定底层 Git HEAD 代码与 Kingbase 物理迁移，严禁虚报、浮夸或把未实现能力写为已完成。 + +--- + +## 2. 系统核心标识与运行基线 + +- **正式业务名称**：`SYFJGYD学员管理系统` +- **内部工程代号**：`RailwaySystem` +- **当前开发分支**：`fix/phase0-product-defects-20260923` +- **共享试用部署分支**：`feat/cicd-pipeline` +- **共享试用访问地址**：[http://192.168.139.230:8082/](http://192.168.139.230:8082/) +- **数据库系统**：国产人大金仓 KingbaseES V9 (schema: `public`, 共享试用库: `training`) +- **当前试用就绪度**：`READY_WITH_EXTERNAL_BLOCKERS`（核心教务主闭环打通，具备现场局域网试用条件；外部智能门锁硬件因无资源处于客观阻塞） + +--- + +## 3. Current 权威文档中心导航表 + +本目录现行收录且仅收录以下 8 份相互解耦、权责明确的真理文档： + +| 编号 | 文档名称 | 核心职责与回答的关键问题 | 适用对象 | +| :---: | :--- | :--- | :--- | +| **01** | [**01-CURRENT-SYSTEM-STATE.md**](01-CURRENT-SYSTEM-STATE.md) | **系统当前真实状态速览**
Git基线、前后端源码、部署状态、阻断项、活跃Worktree、Demo状态与文档状态。 | 全体成员、新接手人员、Agent | +| **02** | [**02-FUNCTION-MODULES.md**](02-FUNCTION-MODULES.md) | **业务功能模块全量判定**
按教师、学员、课程、场地、计划、排课、考勤、住宿、成绩、统计、DMS等逐项给出五级状态判定。 | 产品经理、业务主管、交付验收 | +| **03** | [**03-DATABASE-AND-TABLES.md**](03-DATABASE-AND-TABLES.md) | **数据库架构、迁移链与数据表总账**
KingbaseES DDL、21张业务表、系统表、迁移链顺序与CLEAN_DEMO_DATABASE重建说明。 | 后端开发、DBA、数据审计人员 | +| **04** | [**04-API-INVENTORY.md**](04-API-INVENTORY.md) | **全量 API 接口总账**
全量后端 Controller 接口路径、HTTP 方法、源分类、关联物理表与 UI 调用关系。 | 前后端研发、接口自动化测试 | +| **05** | [**05-CLIENT-API-STATUS.md**](05-CLIENT-API-STATUS.md) | **甲方与外部接口状态清单**
仅记录 DMS 及电子班牌等外部接口的实时连通、鉴权与 Mock 状态，严禁 Mock 冒充真实。 | 集成工程师、外部联调人员 | +| **06** | [**06-DEMO-BASELINE.md**](06-DEMO-BASELINE.md) | **演示基线准则与重构要求**
明确旧 Demo 不可信与新 Demo 尚未开始的事实，确立纯净数据库与确定性数据等 7 大原则。 | QA、测试架构师、验收人员 | +| **07** | [**07-KNOWN-GAPS.md**](07-KNOWN-GAPS.md) | **内部已知缺口与外部阻塞清单**
仅记录经过严格验证的真实缺口（包括 ACCOM-PERM-01 阻断项、DMS 硬件阻塞、C03成绩收敛等）。 | 研发团队、排期人员、问题排查 | +| **08** | [**08-NEXT-ACTIONS.md**](08-NEXT-ACTIONS.md) | **下一阶段标准化行动路线图**
固定从环境冻结、纯净库重建、种子数据灌入到最终 Docs Phase B 的 14 步标准流。 | 项目经理、技术负责人 | + +--- + +## 4. 历史版本审计与归档记录 + +在本次 Bootstrap 启动前，原 `docs/current/` 目录下共存有 8 份历史文件。经逐篇与底层代码及 Git HEAD 审计，判定结论如下： +- `README.md`：**STALE**，原速览索引缺少真理优先级声明与新架构映射，已被本文件彻底重构替代。 +- `01-current-status.md`：**STALE**，基于 2026-09-17 早期快照，已被 `01-CURRENT-SYSTEM-STATE.md` 取代。 +- `02-phase1-status.md`：**STALE**，粗粒度判定，已被 `02-FUNCTION-MODULES.md` 精确五级判定取代。 +- `03-shared-trial.md`：**STALE**，描述 2026-09-17 部署快照，安全移入归档。 +- `04-known-gaps.md`：**STALE / NEEDS_REWRITE**，遗漏了最新的 `ACCOM-PERM-01` 阻塞项，已被 `07-KNOWN-GAPS.md` 取代。 +- `05-next-actions.md`：**STALE**，编写于 2026-09-18，待办已过期，已被 `08-NEXT-ACTIONS.md` 的 14 步路线图取代。 +- `06-shared-trial-accounts.md`：**STALE**，早期演示账号清单，安全移入归档。 +- `07-analytics-attendance-semantics.md`：**CURRENT (SPECIALIZED)**，Package C 考勤专题统计语义，属专项技术规范，为保持顶层 9 篇架构精简，归入归档留存备查。 + +所有上述 8 份原文档均已完整保留在： +`docs/archive/shared-trial-baseline-20260920/` +（**无任何物理删除，历史凭证完全可追溯**）。 diff --git a/docs/current/01-CURRENT-SYSTEM-STATE.md b/docs/current/01-CURRENT-SYSTEM-STATE.md new file mode 100644 index 000000000..23666efe1 --- /dev/null +++ b/docs/current/01-CURRENT-SYSTEM-STATE.md @@ -0,0 +1,121 @@ +# 01 - 系统当前运行基线与真实状态 (Current System State) + +> **更新时间**：2026-09-23 +> **数据核验基准**：底层源码、真实 Kingbase 迁移脚本与当前 Git HEAD 状态。 + +--- + +## 1. 核心事实核验基线总览 + +```text +================================================================================ + RAILWAYSYSTEM RUNTIME VERIFIED STATE +================================================================================ +CURRENT_GIT_BRANCH = fix/phase0-product-defects-20260923 +CURRENT_GIT_HEAD_COMMIT = 2f05f310 +DEPLOYMENT_TRACKING_BRANCH = feat/cicd-pipeline (HEAD: eb1ddfca) +SHARED_TRIAL_URL = http://192.168.139.230:8082/ +SHARED_TRIAL_DB = training (KingbaseES V9 at 192.168.139.218:4321) +FRONTEND_SOURCE_OF_TRUTH = RuoYi-Vue/ruoyi-ui (Vue 2.6 / Element UI) +BACKEND_SOURCE_OF_TRUTH = RuoYi-Vue (Spring Boot 2.5.15 / Java 8) +BACKEND_TEST_SUITE_STATUS = 331 / 331 PASS (Surefire Verified) + +DEMO_STATUS = OLD_DEMO_UNTRUSTWORTHY / NEW_DEMO_NOT_YET_STARTED +DOCS_STATUS = PHASE_A6_1_COMPLETE / PHASE_B_GATE_BLOCKED +CLIENT_REQUIREMENT_STATUS = CLIENT_REFERENCE_PACK_UNCONFIRMED (INTERNAL_FREEZE) +CURRENT_KNOWN_BLOCKERS_COUNT = 2 (ACCOM-PERM-01, DMS_EXTERNAL_HARDWARE) +================================================================================ +``` + +--- + +## 2. 前后端源码与技术栈真实情况 + +### 2.1 前端工程事实 (`RuoYi-Vue/ruoyi-ui`) +- **技术栈**：Vue 2.6.12 + Vuex 3.6.0 + Vue Router 3.4.9 + Element UI 2.15.8 + Axios + ECharts 5.x。 +- **业务视图根路径**：`ruoyi-ui/src/views/train/` +- **主要视图组件**： + - `teacher/`：教师档案管理、资质证书与任教历史； + - `student/`：学员主档、身份信息密文展示与报到流水； + - `course/`：课程库、教学大纲与学时学分配置； + - `plan/`：培训班级计划、开班生命周期阶段流转； + - `lesson/`：排课课表、四维冲突时段预检； + - `accommodation/`：宿舍房间管理、床位分配与住宿履历； + - `checkin/`：学员考勤流水、教师代签补卡与请假核验； + - `portrait/`：学员 360 度成长素养画像视图； + - `board/`：电子班牌设备信息管理。 +- **自服务专属界面**： + - 教师工作台 (`teacher/workbench` / `TrainTeacherMeController`) + - 学员个人培训中心 (`student/center` / `TrainStudentMeController`) + +### 2.2 后端工程事实 (`RuoYi-Vue`) +- **核心框架**：Spring Boot 2.5.15 + MyBatis 3.5.6 + PageHelper + 国产人大金仓驱动 (`kingbase8-8.6.0.jar`)。 +- **工程模块分层**： + - `ruoyi-admin`：Web 控制器、Spring Security 过滤链、全局异常处理、登录鉴权； + - `ruoyi-train`：铁路教务核心业务服务（Domain, Service, Mapper, DMS 集成适配器）； + - `ruoyi-framework`：Shiro/Security 配置、数据源切面、数据权限切面 (`DataScopeAspect`)； + - `ruoyi-system`：RuoYi 系统底座（用户、角色、部门、岗位、字典、配置）； + - `ruoyi-common`：工具类、国密 SM4 加密组件、通用常量。 + +--- + +## 3. 当前部署与运行时事实 + +- **共享试用地址**：[http://192.168.139.230:8082/](http://192.168.139.230:8082/) +- **网络访问路径**： + - 本地局域网内直接走 `DIRECT_LAN` 访问； + - 远程接入通过 Tailscale 走 `TAILSCALE_SUBNET_ROUTE`（经过 utun 虚拟网卡）； +- **数据库连接**： + - 实例：人大金仓 KingbaseES V9 (Port: 4321) + - 综合验收数据库：`railwaysystem_integrated_qa_20260916` + - 共享试用数据库：`training` +- **当前试用就绪度判定**：`READY_WITH_EXTERNAL_BLOCKERS` + - 核心教务管理主闭环稳定流畅； + - 教师与学员自服务工作台权限隔离生效； + - 外部智能门锁接口受限（见已知阻塞）。 + +--- + +## 4. 活跃 Worktree 分布现状 + +当前在多任务并行环境下，系统存在以下 8 个活跃 Git Worktree，各司其职且相互隔离： + +| 工作树路径 | 关联分支 | 当前主要任务与定位 | +| :--- | :--- | :--- | +| `主工程根目录 (RailwaySystem)` | `fix/phase0-product-defects-20260923` | **主工程代码工作区**，包含产品缺陷修复与住宿操作前端补丁 | +| `docs-cleanup-audit-20260923` | `chore/docs-cleanup-audit-20260923` | **文档信息架构治理专项区**，完成 Phase A/A.5/A.6/A.6.1 审计 | +| `client-reference-alignment-20260923` | `analysis/client-reference-alignment-20260923` | **甲方参考稿对齐专项区**，完成 14 项参考资料逐页比对 | +| `ex13-bed-overlap-error-contract-20260923` | `fix/ex13-bed-overlap-business-error-20260923` | **EX-13 床位冲突错误码专项区** | +| `fix-clear-defects-20260922` | `fix/preview-clear-defects-20260922` | 缺陷清理与 DMS 禁用态统一声明 | +| `integrate-abc-preview-candidate-20260921`| `fix/preview-attendance-signin-ui-20260921` | 考勤签到 UI 策略对齐与验证 | +| `release-preview-candidate-20260921` | `release/preview-candidate-20260921` | 预发布候选版本稳定性验证 | +| `dms-real-probe-20260916` | `integration/dms-real-probe-20260916` | DMS 局域网真实连通与只读契约探测凭据区 | + +--- + +## 5. 当前核心阻断项 (Current Known Blockers) + +1. **`ACCOM-PERM-01` (产品级阻断)**： + - 住宿生命周期操作（入住、退宿、调房）在 `sys_menu` 与角色授权中未授予 `train_admin` 角色。 + - 阻断 6 个业务验收场景（SM-10, SM-11, SM-12, SM-13, BR-11, EXT-02）。详见 [07-KNOWN-GAPS.md](07-KNOWN-GAPS.md)。 +2. **DMS 外部物理硬件阻塞 (`BLOCKED_EXTERNAL`)**： + - 厂商可访问测试环境中挂载的房间与门锁数量为 0。 + - 无法在运行时验证真实房间与门锁行级字段映射，物理下发操作禁止执行。 + +--- + +## 6. 演示、文档与需求状态定位 + +### 6.1 演示状态 (Demo Status) +- **旧 Demo 状态**：`OLD_DEMO_UNTRUSTWORTHY`。历史 reports 中包含的演示截图与账本存在固定数据污染、超管代跑掩盖权限缺陷等问题，不可作为系统当前可信状态依据。 +- **新 Demo 状态**：`NEW_DEMO_NOT_YET_STARTED`。必须等待 `CLEAN_DEMO_DATABASE` 重建和阻断项修复后重新启动。 + +### 6.2 文档状态 (Docs Status) +- Phase A.6.1 完整性纠偏已在审计工作树中圆满收官（21 份物理产物、53 份争议资产物理绑定、0 路径碰撞）。 +- 整体搬迁与删除（Phase B）处于阻断状态 (`READY_FOR_PHASE_B = NO`)，待演示彻底冻结后执行。 +- 当前正在执行 `CURRENT TRUTH BOOTSTRAP`，建立唯一权威入口。 + +### 6.3 甲方需求状态 (Client Requirement Status) +- **材料定性**：`SOURCE_TYPE = CLIENT_REFERENCE`, `REQUIREMENT_STATUS = UNCONFIRMED`。 +- **治理状态**：`CLIENT_REFERENCE_ACTIVE_WRITER = NO`, `CLIENT_REFERENCE_PACK_INTERNAL_FREEZE = YES`。 +- 甲方参考资料作为外部参考依据，在甲方正式签署确认前，不作为法定合同变更与现行需求。 diff --git a/docs/current/02-FUNCTION-MODULES.md b/docs/current/02-FUNCTION-MODULES.md new file mode 100644 index 000000000..919c58f7d --- /dev/null +++ b/docs/current/02-FUNCTION-MODULES.md @@ -0,0 +1,67 @@ +# 02 - 系统业务功能模块全量判定 (Function Modules) + +> **判定原则**：严格基于底层代码实现（Controller / Service / DDL）、自动化测试覆盖与实际浏览器交互判定。 +> **分类标准**： +> - **`IMPLEMENTED`**：代码完全落地、数据库表就绪、经过真实测试验证、具备完整正向主闭环； +> - **`PARTIAL`**：部分代码或表结构就绪，但存在未闭环的交互、未授权的业务流转或口径待确认项； +> - **`MOCK`**：使用本地假数据或模拟桩进行逻辑联调，未接入真实系统； +> - **`BLOCKED_EXTERNAL`**：内部逻辑具备，因外部厂商环境缺少硬件/真实资源造成客观阻塞； +> - **`NOT_IMPLEMENTED`**：一期未规划或尚未开始开发。 + +--- + +## 1. 业务功能模块状态总览表 + +| 序号 | 业务模块 | 最终状态判定 | 核心后端控制器 (Controller) | 关联核心物理表 | 关键能力与现状边界 | +| :---: | :--- | :---: | :--- | :--- | :--- | +| **01** | **教师档案管理** | **`IMPLEMENTED`** | `TrainTeacherController`
`TrainTeacherMeController` | `train_teacher`
`sys_user` | 档案增删改查、身份证/手机国密脱敏存储、账号自动绑定、教师个人工作台课表。 | +| **02** | **学员档案管理** | **`IMPLEMENTED`** | `TrainStudentController`
`TrainStudentMeController` | `train_student`
`sys_user` | 学员主档管理、身份证密文脱敏、批量导入、学员自服务培训中心（个人课表、考勤、住宿查询）。 | +| **03** | **课程资源库** | **`IMPLEMENTED`** | `TrainCourseController` | `train_course`
`train_resource` | 理论/实作课程分类管理、标准学时/学分配置、教学大纲、统一资源关联。 | +| **04** | **场地与教室** | **`IMPLEMENTED`** | `TrainClassroomInfoController`
`TrainTrainingSiteController` | `train_classroom_info`
`train_training_site` | 教室与实训场地物理档案管理、容纳人数上限控制、使用状态互斥校验。 | +| **05** | **开班计划管理** | **`IMPLEMENTED`** | `TrainPlanController` | `train_plan` | 培训班全生命周期流转（草稿 0 → 已发布 1 → 培训中 2 → 已结训 3）、多班级并行管理。 | +| **06** | **开班课程配置** | **`IMPLEMENTED`** | `TrainPlanCourseController` | `train_plan_course` | 一班多课绑定、分配各门课程任课教师、排课先后序号与学时分配。 | +| **07** | **课次日程与排课**| **`IMPLEMENTED`** | `TrainLessonController` | `train_lesson` | 课次生成、时段安排；**四维时段冲突校验（教师、教室、学员班级、起止日期范围）**。 | +| **08** | **考勤与报到管理**| **`IMPLEMENTED`** | `TrainReportActionController`
`TrainStudentCheckinController`
`AttendanceController` | `train_class_report`
`train_student_checkin`
`train_lesson` | 开班现场报到核验、课次签到/签退、教师代签补卡、人工标记缺勤、请假记录。 | +| **09** | **住宿房间管理** | **`PARTIAL`** | `TrainDormitoryInfoController`
`TrainAccommodationController` | `train_dormitory_info`
`train_accommodation` | 房间/床位增删改查、分配住宿、床位重叠校验 (`EX-13`)、防混住约束已实现；
⚠️ **已知阻断 `ACCOM-PERM-01`**：入住、退宿、调房未授权 `train_admin`。 | +| **10** | **成绩管理 (C03)** | **`PARTIAL`** | `TrainScoreInfoController` | `train_score_info` | 数据库已支持动态科目与基础成绩录入；综合成绩加权计算、教师端打分交互流收敛中。 | +| **11** | **统计分析大盘** | **`IMPLEMENTED`** | `TrainAnalysisController` | 聚合多表查询 | 管理驾驶舱看板、考勤专题分析、每日打卡走势、考勤异常 Top 10，**隔离未来课次（0泄漏）**。 | +| **12** | **DMS 外部智能门锁**| **`BLOCKED_EXTERNAL`** | `TrainAccessManagementController`
`DmsHttpClient` 等 | `train_external_resource_mapping`
`train_dorm_auth`
`train_external_operation` | 鉴权/Token TTL/Cookie Token/只读API连通已验证；**外部环境 0 房间 0 门锁，物理硬件操作客观受阻**。 | +| **13** | **电子班牌设备** | **`PARTIAL` / `MOCK`**| `TrainElectronicBoardController` | `train_electronic_board` | 基础档案 CRUD 已实现；现场物理 IoT 设备通信协议采用模拟桩。 | +| **14** | **学员成长画像** | **`PARTIAL`** | `TrainStudentPortraitController` | `train_student`
`train_study_duration` | 个人基础档案卡、自主学时累计呈现可用；深度多维雷达图与业务评估模型待甲方定级确认。 | +| **15** | **自主学习时长** | **`IMPLEMENTED`** | `TrainStudyDurationController` | `train_study_duration` | 学员线上课时记录、学习时长统计与台账查询。 | + +--- + +## 2. 核心模块详细能力边界说明 + +### 2.1 住宿管理模块 (`PARTIAL` 状态定性说明) +- **已实现能力**： + - 宿舍楼栋、楼层、房间、床位档案维护； + - 房间性别属性与防男女混住校验； + - 学员单在用住宿约束（同一学员同一时段不可多处在住）； + - 床位重叠冲突业务校验 (`EX-13`，返回标准业务错误提示)； + - 管理员权限下的分配住宿操作。 +- **缺失与阻断说明 (`ACCOM-PERM-01`)**： + - 前端 `accommodation/index.vue` 的入住与删除按钮配置了 `v-hasPermi="['train:accommodation:edit', 'train:accommodation:remove']"`； + - 数据库 `sys_menu` 中未配置 `train:accommodation:remove`； + - `train_admin` 角色未被授予 `:edit` 和 `:remove` 权限； + - 导致业务管理员账号登录时无法点击入住、退宿与调房操作。 + +### 2.2 成绩管理模块 (C03 `PARTIAL` 状态说明) +- **已实现能力**： + - 物理表 `train_score_info` 包含 `score` 字段及 `>= 0` CHECK 约束； + - 后端提供基础增删改查接口； +- **待闭环项**： + - 多科目加权折算规则（如：理论 40% + 实作 60%）； + - 教师工作台专属打分与批量录入界面； + - 导出最终培训成绩汇总合格单。 + +### 2.3 DMS 智能门锁模块 (`BLOCKED_EXTERNAL` 定性说明) +- **已打通技术链路**： + - 官方标准登录鉴权接口 `/public/rest/third-party-app/token/get` 联调成功，返回 Cookie Token； + - TokenManager 实现了 7200 秒 TTL 单例滑动续期与 Single-Flight 并发防抖； + - 建筑、楼层、房间、门锁 4 大只读接口完成 HTTP 连通与空结果结构适配； +- **客观外部阻塞事实**： + - 外部系统当前 `building/list`, `room/list`, `doorlock/list` 返回数据集均为 **空列表 (`[]`)**； + - 外部尚未挂接任何实体通电门锁设备； + - 生产安全红线严禁在无测试设备授权下调用物理写操作 (`REAL_DMS_MUTATION_COUNT = 0`)。 diff --git a/docs/current/03-DATABASE-AND-TABLES.md b/docs/current/03-DATABASE-AND-TABLES.md new file mode 100644 index 000000000..bfe6d0a84 --- /dev/null +++ b/docs/current/03-DATABASE-AND-TABLES.md @@ -0,0 +1,105 @@ +# 03 - 数据库架构、迁移链与数据表总账 (Database and Tables) + +> **核心原则**：当前阶段**严格只读，不修改数据库，不清库，不执行数据变更**。 +> 后续演示重构必须基于本文件定义的迁移链构建纯净演示库：`CLEAN_DEMO_DATABASE`。 + +--- + +## 1. 数据库基本信息 + +- **数据库管理系统 (DBMS)**：国产人大金仓分析型/事务型关系数据库 (KingbaseES V009R003C018) +- **数据库兼容模式**：Oracle / PostgreSQL 双模式兼容方言 +- **默认 Schema**：`public` +- **正式综合验收数据库**：`railwaysystem_integrated_qa_20260916` +- **当前共享试用数据库**：`training` +- **DDL 规范要点**： + - 自增主键使用 `bigint GENERATED BY DEFAULT AS IDENTITY` 或业务主键 `varchar(32)`； + - 时间类型统一使用 `timestamp`，严禁 MySQL 方言 `DATETIME` 或 `ON UPDATE CURRENT_TIMESTAMP`； + - 状态与布尔字段统一使用 `smallint` (0/1)； + - 字符串必须指定明确编码与长度。 + +--- + +## 2. 数据库迁移链定义 (Migration Chain) + +系统物理表结构由以下按序执行的迁移脚本链严格定义： + +### 2.1 培训业务核心表迁移 (`RuoYi-Vue/sql/train/v2/`) +```text +000_preflight.sql -- 预检：数据库版本、权限与方言支持 +000_tx_capability_probe.sql -- 事务探针：验证显式事务与 DDL 回滚能力 +001_backup_current_schema.sql -- 架构基线备份 (备份原 V1 表定义) +002_create_new_tables.sql -- 核心创建：创建 V2 新增的 8 张培训业务核心表 +003_alter_master_tables.sql -- 结构变更：对教师、课程、宿舍表扩展字段与约束 +004_rebuild_business_tables.sql -- 重建业务表：重建学员、班级、课次等核心关联 +005_constraints.sql -- 完整性约束：外键、CHECK 约束 (单行互斥、分数非负等) +006_indexes.sql -- 性能索引：高频查询、排课时段冲突组合索引 +007_dicts.sql -- 字典数据 (⚠️ 运行中禁止重复执行，仅限全新建库) +008_migrate_teacher.sql -- 历史数据迁移：清洗并提升历史教师档案 +009_drop_legacy_score.sql -- 清理废弃结构：安全下线旧版无权重成绩表 +010_verify.sql -- 终检验收：断言表结构、外键与索引 100% 合规 +``` + +### 2.2 系统底座与权限治理补丁 (`RuoYi-Vue/sql/system/kingbase/`) +```text +001_sys_oper_log_cost_time.sql -- 操作日志补充耗时字段 +002_legacy_analytics_permissions.sql -- 统计分析历史权限调整 +003_report_attendance_action_permissions.sql -- 现场报到与考勤动作权限 +004_rbac_identity_binding.sql -- 教师与学员用户身份强绑定支持 +005_training_roles_permissions.sql -- 培训业务角色细粒度权限配置 +006_accommodation_history_constraint.sql -- 住宿历史单在用唯一约束 +008_external_resource_operation.sql -- 外部系统操作流水表结构 +009_dorm_authorization_orchestration.sql -- 宿舍门禁编排中间状态表 +010_dms_access_management_permissions.sql -- DMS 门禁管理端菜单权限 +011_teacher_student_remove_permissions.sql -- 教师与学员安全删除权限隔离 +012_analytics_v1_permissions.sql -- 分析大盘新版看板菜单权限 +013_interaction_route_cleanup.sql -- 交互路由与无效菜单项清理 +014_dms_access_safety_and_accommodation_permissions.sql -- DMS 安全防线与住宿菜单完善 +015_dms_package_a_hardening.sql -- DMS Package A 门禁强化脚本 +``` + +--- + +## 3. 全量业务数据表总账 (21 张 `train_*` 表) + +| 表名 (TABLE_NAME) | 物理主键类型 | 表职责说明 (PURPOSE) | 核心外键与关键关联 (RELATIONSHIPS) | +| :--- | :--- | :--- | :--- | +| `train_teacher` | `VARCHAR(32)` | 授课教师档案主表，记录姓名、工号、职称、身份证（国密密文） | `sys_user.user_id` (账号绑定关系) | +| `train_student` | `VARCHAR(32)` | 参训学员主档表，全周期记录学员信息、单位、手机与国密身份证 | `sys_user.user_id` (账号绑定关系) | +| `train_course` | `VARCHAR(32)` | 课程标准库主表，记录课程编号、名称、理论/实作类别与基准学时 | 被 `train_plan_course`、`train_lesson` 引用 | +| `train_classroom_info` | `BIGINT (ID)` | 教学教室信息表，记录教室编号、楼栋、容纳人数与多媒体配备 | 被 `train_lesson` 引用 (教室时段互斥) | +| `train_training_site` | `BIGINT (ID)` | 实训演练场地表，记录室外/室内实训工区、容量与安全规范 | 被 `train_lesson` 引用 (场地时段互斥) | +| `train_plan` | `VARCHAR(32)` | 培训开班计划主表，控制培训项目全生命周期与时间跨度 | 驱动 `train_plan_course`、`train_enrollment` | +| `train_plan_course` | `BIGINT (ID)` | 班级课程关系表 (N:M)，指定某培训班开设哪门课及指定授课教师 | 关联 `plan_id`、`c_id`、`t_id` | +| `train_enrollment` | `BIGINT (ID)` | 参训人员名册表，定义哪个学员参加哪期培训班及参训状态 | 关联 `plan_id`、`s_id` (状态: 待报到/在训/结训) | +| `train_lesson` | `BIGINT (ID)` | 课次日程排课表，系统排课核心表，记录每次课的具体时段与地点 | 关联 `plan_id`、`plan_course_id`、`t_id`、教室/场地 | +| `train_student_checkin` | `BIGINT (ID)` | 课堂考勤打卡流水表，记录学员在课次的签到、签退与出勤状态 | 关联 `lesson_id`、`s_id` (状态: 0缺勤/1正常/2迟到/3早退/4请假) | +| `train_class_report` | `BIGINT (ID)` | 现场报到核验记录表，学员到校开班报到凭据流水 | 关联 `enrollment_id`、`s_id`、`plan_id` | +| `train_dormitory_info` | `BIGINT (ID)` | 宿舍房间主表，记录宿舍楼栋、房号、性别分类、总床位数与在用数 | 被 `train_accommodation` 引用 | +| `train_accommodation` | `BIGINT (ID)` | 学员住宿分配台账表，记录床位分配、入住时间、退宿时间与状态 | 关联 `s_id`、`dorm_id`、`plan_id` (状态: 预分配0/在住1/已退2) | +| `train_score_info` | `BIGINT (ID)` | 学员培训成绩表，记录各科目考评得分与最终成绩评定 | 关联 `plan_id`、`s_id`、`c_id` (score >= 0 CHECK) | +| `train_study_duration` | `BIGINT (ID)` | 自主学习时长流水表，记录学员在线研读教学资料的计时时长 | 关联 `s_id`、`resource_id` | +| `train_resource` | `VARCHAR(32)` | 统一教学资源主表，存放课件、视频、教材电子档等资源元数据 | 被 `train_course_resource` 引用 | +| `train_course_resource`| `BIGINT (ID)` | 课程与教学资源关联表 (N:M) | 关联 `c_id`、`resource_id` | +| `train_electronic_board`| `BIGINT (ID)` | 电子班牌硬件设备信息表，记录设备 MAC、IP、挂接教室与通信时间 | 关联 `classroom_id` | +| `train_external_resource_mapping` | `BIGINT (ID)` | 外部资源映射表，记录本地宿舍房间与外部 DMS 空间/锁具的映射 | 关联 `local_resource_id`、`external_id` (DMS) | +| `train_dorm_auth` | `BIGINT (ID)` | 门禁卡/密码授权编排状态表，维护门锁下发授权生命周期 | 关联 `accommodation_id`、`external_auth_id` | +| `train_external_operation` | `BIGINT (ID)` | 外部异步操作流水表，记录向 DMS 下发密码/撤销的异步 operationId | 关联 `auth_id`、`operation_type`、重试次数 | + +--- + +## 4. 后续纯净演示库重建计划 (`CLEAN_DEMO_DATABASE`) + +为彻底消除历史演示留存的脏数据、断言污染与测试垃圾，后续正式 Demo 执行前**严禁直接使用已污染的旧库**，必须按以下规程建立纯净演示数据库： + +```text +[CLEAN_DEMO_DATABASE 重建 SOP] +1. 在 KingbaseES 实例新建独立数据库：training_demo_clean +2. 按序执行 2.1 节 000~010 全量业务迁移脚本 (确保 0 errors) +3. 按序执行 2.2 节 001~015 系统与权限增量补丁 +4. 执行全新字典与菜单种子导入 +5. 灌入经过严格卫生校验的确定性业务种子数据 (Deterministic Demo Seed): + - 标准教师 5 名、学员 30 名、课程 6 门、教室 4 间、宿舍 8 间 + - 2 期标准培训班（1 期已结训供查历史，1 期正在进行供现场演示） + - 保证 100% 前端 UI 具有真实有效数据，无孤儿数据，无外键断裂 +``` diff --git a/docs/current/04-API-INVENTORY.md b/docs/current/04-API-INVENTORY.md new file mode 100644 index 000000000..c33eaed0e --- /dev/null +++ b/docs/current/04-API-INVENTORY.md @@ -0,0 +1,132 @@ +# 04 - 系统全量 API 接口总账 (API Inventory) + +> **审计基准**：扫描 `RuoYi-Vue/ruoyi-admin/src/main/java/com/ruoyi/web/controller` 下全部 Spring MVC 控制器。 +> **数据源规范 (SOURCE)**：必须且只能归为以下四类之一： +> 1. `RAILWAYSYSTEM_INTERNAL`：本系统内部业务与系统基础 API； +> 2. `CLIENT_PROVIDED`：甲方或外部单位正式提供的真实运行 API； +> 3. `THIRD_PARTY`：通用第三方公有服务接口； +> 4. `MOCK`：本地自建的模拟桩接口。 + +--- + +## 1. 核心培训业务 API 账本 (`TRAIN_BUSINESS`) + +| 接口路径 (API) | 请求方式 (METHOD) | 数据来源 (SOURCE) | 所属模块 (MODULE) | 实现状态 | 承载控制器 (CONTROLLER) | 关联数据库表 (TABLE) | 前端UI调用 (USED_BY_UI) | +| :--- | :---: | :---: | :---: | :---: | :--- | :--- | :---: | +| `/train/teacher/list` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 师资管理 | `IMPLEMENTED` | `TrainTeacherController` | `train_teacher` | YES | +| `/train/teacher/{tId}` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 师资管理 | `IMPLEMENTED` | `TrainTeacherController` | `train_teacher` | YES | +| `/train/teacher` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 师资管理 | `IMPLEMENTED` | `TrainTeacherController` | `train_teacher` | YES | +| `/train/teacher` | `PUT` | `RAILWAYSYSTEM_INTERNAL` | 师资管理 | `IMPLEMENTED` | `TrainTeacherController` | `train_teacher` | YES | +| `/train/teacher/{tIds}` | `DELETE` | `RAILWAYSYSTEM_INTERNAL` | 师资管理 | `IMPLEMENTED` | `TrainTeacherController` | `train_teacher` | YES | +| `/train/teacher/export` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 师资管理 | `IMPLEMENTED` | `TrainTeacherController` | `train_teacher` | YES | +| `/train/me/teacher/plans` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 教师工作台 | `IMPLEMENTED` | `TrainTeacherMeController` | `train_plan` | YES | +| `/train/me/teacher` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 教师工作台 | `IMPLEMENTED` | `TrainTeacherMeController` | `train_lesson` | YES | +| `/train/me/teacher/students` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 教师工作台 | `IMPLEMENTED` | `TrainTeacherMeController` | `train_enrollment` | YES | +| `/train/me/teacher/lessons/{lessonId}/attendance` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 教师工作台 | `IMPLEMENTED` | `TrainTeacherMeController` | `train_student_checkin` | YES | +| `/train/student/list` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 学员管理 | `IMPLEMENTED` | `TrainStudentController` | `train_student` | YES | +| `/train/student/{sId}` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 学员管理 | `IMPLEMENTED` | `TrainStudentController` | `train_student` | YES | +| `/train/student` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 学员管理 | `IMPLEMENTED` | `TrainStudentController` | `train_student` | YES | +| `/train/student` | `PUT` | `RAILWAYSYSTEM_INTERNAL` | 学员管理 | `IMPLEMENTED` | `TrainStudentController` | `train_student` | YES | +| `/train/student/{sIds}` | `DELETE` | `RAILWAYSYSTEM_INTERNAL` | 学员管理 | `IMPLEMENTED` | `TrainStudentController` | `train_student` | YES | +| `/train/student/export` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 学员管理 | `IMPLEMENTED` | `TrainStudentController` | `train_student` | YES | +| `/train/student/importTemplate` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 学员管理 | `IMPLEMENTED` | `TrainStudentController` | `train_student` | YES | +| `/train/student/importData` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 学员管理 | `IMPLEMENTED` | `TrainStudentController` | `train_student` | YES | +| `/train/me/student/enrollments` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 学员中心 | `IMPLEMENTED` | `TrainStudentMeController` | `train_enrollment` | YES | +| `/train/me/student/timetable` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 学员中心 | `IMPLEMENTED` | `TrainStudentMeController` | `train_lesson` | YES | +| `/train/me/student/report` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 学员中心 | `IMPLEMENTED` | `TrainStudentMeController` | `train_class_report` | YES | +| `/train/me/student/attendance` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 学员中心 | `IMPLEMENTED` | `TrainStudentMeController` | `train_student_checkin` | YES | +| `/train/me/student/duration` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 学员中心 | `IMPLEMENTED` | `TrainStudentMeController` | `train_study_duration` | YES | +| `/train/me/student/portrait` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 学员中心 | `IMPLEMENTED` | `TrainStudentMeController` | `train_student` | YES | +| `/train/course/list` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 课程库 | `IMPLEMENTED` | `TrainCourseController` | `train_course` | YES | +| `/train/course/{cId}` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 课程库 | `IMPLEMENTED` | `TrainCourseController` | `train_course` | YES | +| `/train/course` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 课程库 | `IMPLEMENTED` | `TrainCourseController` | `train_course` | YES | +| `/train/course` | `PUT` | `RAILWAYSYSTEM_INTERNAL` | 课程库 | `IMPLEMENTED` | `TrainCourseController` | `train_course` | YES | +| `/train/course/{cIds}` | `DELETE` | `RAILWAYSYSTEM_INTERNAL` | 课程库 | `IMPLEMENTED` | `TrainCourseController` | `train_course` | YES | +| `/train/classroom/list` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 设施管理 | `IMPLEMENTED` | `TrainClassroomInfoController` | `train_classroom_info` | YES | +| `/train/classroom/{classRoomId}` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 设施管理 | `IMPLEMENTED` | `TrainClassroomInfoController` | `train_classroom_info` | YES | +| `/train/classroom` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 设施管理 | `IMPLEMENTED` | `TrainClassroomInfoController` | `train_classroom_info` | YES | +| `/train/classroom` | `PUT` | `RAILWAYSYSTEM_INTERNAL` | 设施管理 | `IMPLEMENTED` | `TrainClassroomInfoController` | `train_classroom_info` | YES | +| `/train/classroom/{classRoomIds}`| `DELETE` | `RAILWAYSYSTEM_INTERNAL` | 设施管理 | `IMPLEMENTED` | `TrainClassroomInfoController` | `train_classroom_info` | YES | +| `/train/training-site/list` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 设施管理 | `IMPLEMENTED` | `TrainTrainingSiteController` | `train_training_site` | YES | +| `/train/training-site/{siteId}` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 设施管理 | `IMPLEMENTED` | `TrainTrainingSiteController` | `train_training_site` | YES | +| `/train/training-site` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 设施管理 | `IMPLEMENTED` | `TrainTrainingSiteController` | `train_training_site` | YES | +| `/train/training-site` | `PUT` | `RAILWAYSYSTEM_INTERNAL` | 设施管理 | `IMPLEMENTED` | `TrainTrainingSiteController` | `train_training_site` | YES | +| `/train/training-site/{siteIds}`| `DELETE` | `RAILWAYSYSTEM_INTERNAL` | 设施管理 | `IMPLEMENTED` | `TrainTrainingSiteController` | `train_training_site` | YES | +| `/train/plans` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 培训计划 | `IMPLEMENTED` | `TrainPlanController` | `train_plan` | YES | +| `/train/plans/{planId}` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 培训计划 | `IMPLEMENTED` | `TrainPlanController` | `train_plan` | YES | +| `/train/plans` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 培训计划 | `IMPLEMENTED` | `TrainPlanController` | `train_plan` | YES | +| `/train/plans/{planId}` | `PUT` | `RAILWAYSYSTEM_INTERNAL` | 培训计划 | `IMPLEMENTED` | `TrainPlanController` | `train_plan` | YES | +| `/train/plans/{planIds}` | `DELETE` | `RAILWAYSYSTEM_INTERNAL` | 培训计划 | `IMPLEMENTED` | `TrainPlanController` | `train_plan` | YES | +| `/train/plans/{planId}/publish` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 培训计划 | `IMPLEMENTED` | `TrainPlanController` | `train_plan` | YES | +| `/train/plans/{planId}/start` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 培训计划 | `IMPLEMENTED` | `TrainPlanController` | `train_plan` | YES | +| `/train/plans/{planId}/complete`| `POST` | `RAILWAYSYSTEM_INTERNAL` | 培训计划 | `IMPLEMENTED` | `TrainPlanController` | `train_plan` | YES | +| `/train/plans/{planId}/courses` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 计划课程 | `IMPLEMENTED` | `TrainPlanCourseController` | `train_plan_course` | YES | +| `/train/plans/{planId}/courses` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 计划课程 | `IMPLEMENTED` | `TrainPlanCourseController` | `train_plan_course` | YES | +| `/train/plans/{planId}/courses/{planCourseId}` | `DELETE` | `RAILWAYSYSTEM_INTERNAL` | 计划课程 | `IMPLEMENTED` | `TrainPlanCourseController` | `train_plan_course` | YES | +| `/train/plans/{planId}/enrollments` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 参训名单 | `IMPLEMENTED` | `TrainEnrollmentController` | `train_enrollment` | YES | +| `/train/plans/{planId}/enrollments` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 参训名单 | `IMPLEMENTED` | `TrainEnrollmentController` | `train_enrollment` | YES | +| `/train/plans/{planId}/enrollments/batch` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 参训名单 | `IMPLEMENTED` | `TrainEnrollmentController` | `train_enrollment` | YES | +| `/train/enrollments/{enrollmentId}` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 参训名单 | `IMPLEMENTED` | `TrainEnrollmentController` | `train_enrollment` | YES | +| `/train/enrollments/{enrollmentId}/status` | `PUT` | `RAILWAYSYSTEM_INTERNAL` | 参训名单 | `IMPLEMENTED` | `TrainEnrollmentController` | `train_enrollment` | YES | +| `/train/enrollments/{enrollmentId}` | `DELETE` | `RAILWAYSYSTEM_INTERNAL` | 参训名单 | `IMPLEMENTED` | `TrainEnrollmentController` | `train_enrollment` | YES | +| `/train/plans/{planId}/lessons` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 排课管理 | `IMPLEMENTED` | `TrainLessonController` | `train_lesson` | YES | +| `/train/plans/{planId}/lessons` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 排课管理 | `IMPLEMENTED` | `TrainLessonController` | `train_lesson` | YES | +| `/train/lessons/{lessonId}` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 排课管理 | `IMPLEMENTED` | `TrainLessonController` | `train_lesson` | YES | +| `/train/lessons/{lessonId}` | `PUT` | `RAILWAYSYSTEM_INTERNAL` | 排课管理 | `IMPLEMENTED` | `TrainLessonController` | `train_lesson` | YES | +| `/train/lessons/{lessonId}` | `DELETE` | `RAILWAYSYSTEM_INTERNAL` | 排课管理 | `IMPLEMENTED` | `TrainLessonController` | `train_lesson` | YES | +| `/train/lessons/check-conflict` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 排课管理 | `IMPLEMENTED` | `TrainLessonController` | `train_lesson` | YES | +| `/train/lessons/scheduling-options` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 排课管理 | `IMPLEMENTED` | `TrainLessonController` | `train_classroom_info` | YES | +| `/train/plans/{planId}/timetable` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 排课管理 | `IMPLEMENTED` | `TrainLessonController` | `train_lesson` | YES | +| `/train/enrollments/{enrollmentId}/report` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 现场报到 | `IMPLEMENTED` | `TrainReportActionController` | `train_class_report` | YES | +| `/train/report/list` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 现场报到 | `IMPLEMENTED` | `TrainClassReportController` | `train_class_report` | YES | +| `/train/checkin/list` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 考勤流水 | `IMPLEMENTED` | `TrainStudentCheckinController` | `train_student_checkin` | YES | +| `/train/attendance/lessons/{lessonId}/checkins` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 考勤流水 | `IMPLEMENTED` | `AttendanceController` | `train_student_checkin` | YES | +| `/train/attendance/proxy-checkin` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 考勤流水 | `IMPLEMENTED` | `AttendanceController` | `train_student_checkin` | YES | +| `/train/attendance/mark-absent` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 考勤流水 | `IMPLEMENTED` | `AttendanceController` | `train_student_checkin` | YES | +| `/train/dormitory/list` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 宿舍管理 | `IMPLEMENTED` | `TrainDormitoryInfoController` | `train_dormitory_info` | YES | +| `/train/dormitory/{dormId}` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 宿舍管理 | `IMPLEMENTED` | `TrainDormitoryInfoController` | `train_dormitory_info` | YES | +| `/train/dormitory` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 宿舍管理 | `IMPLEMENTED` | `TrainDormitoryInfoController` | `train_dormitory_info` | YES | +| `/train/dormitory` | `PUT` | `RAILWAYSYSTEM_INTERNAL` | 宿舍管理 | `IMPLEMENTED` | `TrainDormitoryInfoController` | `train_dormitory_info` | YES | +| `/train/dormitory/{dormIds}` | `DELETE` | `RAILWAYSYSTEM_INTERNAL` | 宿舍管理 | `IMPLEMENTED` | `TrainDormitoryInfoController` | `train_dormitory_info` | YES | +| `/train/accommodation/list` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 住宿安排 | `IMPLEMENTED` | `TrainAccommodationController` | `train_accommodation` | YES | +| `/train/accommodation/{accommodationId}` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 住宿安排 | `IMPLEMENTED` | `TrainAccommodationController` | `train_accommodation` | YES | +| `/train/accommodation` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 住宿安排 | `IMPLEMENTED` | `TrainAccommodationController` | `train_accommodation` | YES | +| `/train/accommodation/check-in/{id}` | `PUT` | `RAILWAYSYSTEM_INTERNAL` | 住宿安排 | `PARTIAL` (ACCOM-PERM-01) | `TrainAccommodationController` | `train_accommodation` | YES | +| `/train/accommodation/check-out/{id}`| `PUT` | `RAILWAYSYSTEM_INTERNAL` | 住宿安排 | `PARTIAL` (ACCOM-PERM-01) | `TrainAccommodationController` | `train_accommodation` | YES | +| `/train/accommodation/transfer` | `PUT` | `RAILWAYSYSTEM_INTERNAL` | 住宿安排 | `PARTIAL` (ACCOM-PERM-01) | `TrainAccommodationController` | `train_accommodation` | YES | +| `/train/score/list` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 成绩管理 | `IMPLEMENTED` | `TrainScoreInfoController` | `train_score_info` | YES | +| `/train/score/{scoreId}` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 成绩管理 | `IMPLEMENTED` | `TrainScoreInfoController` | `train_score_info` | YES | +| `/train/score` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 成绩管理 | `IMPLEMENTED` | `TrainScoreInfoController` | `train_score_info` | YES | +| `/train/score` | `PUT` | `RAILWAYSYSTEM_INTERNAL` | 成绩管理 | `IMPLEMENTED` | `TrainScoreInfoController` | `train_score_info` | YES | +| `/train/score/{scoreIds}` | `DELETE` | `RAILWAYSYSTEM_INTERNAL` | 成绩管理 | `IMPLEMENTED` | `TrainScoreInfoController` | `train_score_info` | YES | +| `/train/analysis/dashboard/overview` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 统计分析 | `IMPLEMENTED` | `TrainAnalysisController` | 聚合多表 | YES | +| `/train/analysis/dashboard/charts` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 统计分析 | `IMPLEMENTED` | `TrainAnalysisController` | 聚合多表 | YES | +| `/train/analysis/attendance/summary` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 统计分析 | `IMPLEMENTED` | `TrainAnalysisController` | 聚合多表 | YES | +| `/train/analysis/attendance/charts` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 统计分析 | `IMPLEMENTED` | `TrainAnalysisController` | 聚合多表 | YES | +| `/train/analysis/portrait/student-360/{studentId}` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 统计分析 | `IMPLEMENTED` | `TrainAnalysisController` | 聚合多表 | YES | +| `/train/access/mapping/list` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 门禁集成 | `IMPLEMENTED` | `TrainAccessManagementController` | `train_external_resource_mapping` | YES | +| `/train/access/auth/list` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 门禁集成 | `IMPLEMENTED` | `TrainAccessManagementController` | `train_dorm_auth` | YES | +| `/train/access/operation/list` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 门禁集成 | `IMPLEMENTED` | `TrainAccessManagementController` | `train_external_operation` | YES | +| `/train/access/capability` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 门禁集成 | `IMPLEMENTED` | `TrainAccessManagementController` | N/A | YES | +| `/train/access/issue` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 门禁集成 | `BLOCKED_EXTERNAL` | `TrainAccessManagementController` | `train_dorm_auth` | YES | +| `/train/access/revoke` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 门禁集成 | `BLOCKED_EXTERNAL` | `TrainAccessManagementController` | `train_dorm_auth` | YES | +| `/train/binding/teachers/bindable-users` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 身份绑定 | `IMPLEMENTED` | `TrainAccountBindingAdminController` | `sys_user` | YES | +| `/train/binding/teachers/{teacherId}/bind` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 身份绑定 | `IMPLEMENTED` | `TrainAccountBindingAdminController` | `train_teacher` | YES | +| `/train/binding/students/bindable-users` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 身份绑定 | `IMPLEMENTED` | `TrainAccountBindingAdminController` | `sys_user` | YES | +| `/train/binding/students/{studentId}/bind` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 身份绑定 | `IMPLEMENTED` | `TrainAccountBindingAdminController` | `train_student` | YES | + +--- + +## 2. 系统核心底座 API (`SYSTEM`) + +| 接口路径 (API) | 请求方式 (METHOD) | 数据来源 (SOURCE) | 所属模块 (MODULE) | 实现状态 | 承载控制器 (CONTROLLER) | 关联数据库表 (TABLE) | 前端UI调用 (USED_BY_UI) | +| :--- | :---: | :---: | :---: | :---: | :--- | :--- | :---: | +| `/login` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 鉴权认证 | `IMPLEMENTED` | `SysLoginController` | `sys_user` | YES | +| `/logout` | `POST` | `RAILWAYSYSTEM_INTERNAL` | 鉴权认证 | `IMPLEMENTED` | `SysLoginController` | Redis | YES | +| `/captchaImage` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 鉴权认证 | `IMPLEMENTED` | `CaptchaController` | Redis | YES | +| `/getInfo` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 鉴权认证 | `IMPLEMENTED` | `SysLoginController` | `sys_user` / `sys_role` | YES | +| `/getRouters` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 权限路由 | `IMPLEMENTED` | `SysLoginController` | `sys_menu` | YES | +| `/system/user/list` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 用户管理 | `IMPLEMENTED` | `SysUserController` | `sys_user` | YES | +| `/system/role/list` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 角色管理 | `IMPLEMENTED` | `SysRoleController` | `sys_role` | YES | +| `/system/menu/list` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 菜单管理 | `IMPLEMENTED` | `SysMenuController` | `sys_menu` | YES | +| `/system/dict/data/type/{dictType}` | `GET` | `RAILWAYSYSTEM_INTERNAL` | 字典管理 | `IMPLEMENTED` | `SysDictDataController` | `sys_dict_data` | YES | diff --git a/docs/current/05-CLIENT-API-STATUS.md b/docs/current/05-CLIENT-API-STATUS.md new file mode 100644 index 000000000..93d7f4a91 --- /dev/null +++ b/docs/current/05-CLIENT-API-STATUS.md @@ -0,0 +1,41 @@ +# 05 - 甲方与外部接口状态清单 (Client API Status) + +> **最高原则**：**严禁将模拟桩 (Mock) 误报为真实在线 (REAL_LIVE)！** +> 本文件仅收录甲方、外部硬件厂商或第三方提供的外部接口，客观记录网络连通、鉴权及数据可用性真实状态。 +> **安全红线**：当前阶段**严禁发起任何破坏性写操作 (Mutation)**。 + +--- + +## 1. 外部接口状态枚举定义 + +- **`CLIENT_REAL_LIVE`**：外部真实网络畅通、账号鉴权通过、只读调用成功并返回符合契约的数据结构； +- **`CLIENT_REAL_AUTH_BLOCKED`**：外部网络可达，但因密钥错误、账号锁定或缺少权限被 401/403 阻断； +- **`CLIENT_REAL_UNREACHABLE`**：外部网络不通、连接超时、域名未解析或接口已被外部下线； +- **`NOT_YET_TESTED`**：代码已编写适配器，但尚未在当前真实网络中发起调用，或受安全红线禁止调用； +- **`MOCK_SIMULATION`**：无外部真实服务支撑，当前完全由本地假数据桩或仿真测试套件驱动。 + +--- + +## 2. 外部接口状态全量盘点表 + +| 序号 | 外部接口名称 | 协议与端点 (API ENDPOINT) | 提供方 (PROVIDER) | 真实状态判定 (STATUS) | 真实返回特征与依据 | 破坏性风险与限制 | +| :---: | :--- | :--- | :--- | :---: | :--- | :--- | +| **01** | **DMS 第三方应用凭据获取** | `POST /public/rest/third-party-app/token/get` | DMS 门锁厂商平台 | **`CLIENT_REAL_LIVE`** | 局域网真实环境探测通过；凭据有效返回 Cookie Token 与 7200 秒 TTL，支持并发 DCL 单例刷新。 | 只读鉴权，无破坏性风险。 | +| **02** | **DMS 建筑空间列表查询** | `POST /rest/place/building/list` | DMS 门锁厂商平台 | **`CLIENT_REAL_LIVE`** | 鉴权后网络可达；返回 HTTP 200，响应结构包含 code/data，**当前实际返回数据量为 0 (`[]`)**。 | 只读查询，安全。 | +| **03** | **DMS 楼层空间列表查询** | `POST /rest/place/floor/list` | DMS 门锁厂商平台 | **`CLIENT_REAL_LIVE`** | 鉴权后网络可达；返回 HTTP 200，**当前实际返回数据量为 0 (`[]`)**。 | 只读查询，安全。 | +| **04** | **DMS 房间空间列表查询** | `POST /rest/place/room/list` | DMS 门锁厂商平台 | **`CLIENT_REAL_LIVE`** | 鉴权后网络可达；返回 HTTP 200，**当前实际返回数据量为 0 (`[]`)**。 | 只读查询，安全。 | +| **05** | **DMS 智能门锁设备列表查询** | `POST /rest/doorlock/list` | DMS 门锁厂商平台 | **`CLIENT_REAL_LIVE`** | 鉴权后网络可达；按空间 ID 检索返回空列表，**当前挂载门锁数为 0**。 | 只读查询，安全。 | +| **06** | **DMS 在线密码下发 (Mutation)** | `POST /rest/doorlock/online-password-key/create`| DMS 门锁厂商平台 | **`NOT_YET_TESTED`**
(本地单元测试为 `MOCK_SIMULATION`) | 在本地 MockServer 验证通过并取得 operationId；**真实环境因无指定测试门锁，当前执行禁止策略 (`REAL_DMS_MUTATION_COUNT = 0`)**。 | **写操作**：严禁向未知门锁发起下发，待甲方正式划拨指定硬件后测试。 | +| **07** | **DMS 在线密码撤销 (Mutation)** | `POST /rest/doorlock/online-password-key/delete`| DMS 门锁厂商平台 | **`NOT_YET_TESTED`**
(本地单元测试为 `MOCK_SIMULATION`) | 在本地 MockServer 验证通过；真实环境禁止调用。 | **写操作**：同上。 | +| **08** | **DMS 异步操作状态轮询** | `POST /rest/doorlock/operation/status` | DMS 门锁厂商平台 | **`NOT_YET_TESTED`**
(本地单元测试为 `MOCK_SIMULATION`) | 代码具备轮询器 (`DmsOperationPoller`)；由于未下发真实密码，无真实 operationId 供轮询。 | 只读轮询，安全。 | +| **09** | **DMS 远程开门 (Remote Unlock)** | 门锁远程触发开门接口 | DMS 门锁厂商平台 | **`CLIENT_REAL_UNREACHABLE`**
(`OUT_OF_CURRENT_SCOPE`) | 生产与试用安全红线：**系统严禁集成任何远程开锁 API**，未进行任何路由配置与适配器实现。 | **极高危险**：绝对禁止调用。 | +| **10** | **电子班牌实时数据推送** | 班牌通信端口与协议 | 电子班牌硬件厂商 | **`MOCK_SIMULATION`** | 甲方现场尚未提供实际联网电子班牌设备；系统当前在数据库记录心跳时间与班牌档案，通信属于模拟桩。 | 无物理设备破坏风险。 | + +--- + +## 3. 外部接口联调与解锁条件 (Unblocking Criteria) + +针对当前处于 `NOT_YET_TESTED` 与 `BLOCKED_EXTERNAL` 的接口，解除受限状态必须满足以下前置条件： +1. **真实硬件设备划拨**：由沈阳房建公寓段主管领导或厂商指派具体的、通电的、物理隔离的 **真实测试房间与门锁编号**； +2. **测试授权协议签署**：明确现场测试期间密码下发与冲正补偿的法律责任边界； +3. **禁止自动化无限制重试**：写操作调用必须保持 Single-Flight，超时严禁无限制自动重发，必须走人工或受控冲正通道。 diff --git a/docs/current/06-DEMO-BASELINE.md b/docs/current/06-DEMO-BASELINE.md new file mode 100644 index 000000000..c8d766f23 --- /dev/null +++ b/docs/current/06-DEMO-BASELINE.md @@ -0,0 +1,58 @@ +# 06 - 演示基线准则与重构要求 (Demo Baseline) + +> **最高声明**： +> 1. **旧 Demo 当前不可信 (Old Demo Untrustworthy)**：历史 `docs/reports/**` 中记载的旧版端到端演示报告包含多处数据污染、超管代跑掩盖权限缺陷（如使用 `admin` 代跑导致未发现 `ACCOM-PERM-01`）等问题，**其演示结果与截图绝对不得作为当前系统交付的可信证据**。 +> 2. **新版 Demo 尚未开始 (New Demo Not Yet Started)**：当前系统状态标记为 `NEW_DEMO_STATUS = NOT_YET_STARTED`。 +> 3. **严禁带病演示**：在已知阻断项修复并完成纯净库重建前，严禁任何人员或 Agent 启动演示脚本。 + +--- + +## 1. 下一版 Demo 七大重构铁律 (Next Edition Demo Principles) + +为确保下一次业务演示达到面向铁路客户交付的黄金工业级标准，演示重构必须严格贯彻以下七大铁律： + +```text ++--------------------------------------------------------------------------------------------------+ +| NEXT-GENERATION DEMO 7 GOLDEN PRINCIPLES | ++--------------------------------------------------------------------------------------------------+ +| 1. Fresh Clean Demo Database | 绝对不在历史污染库上演示，必须基于全新干净独立数据库重建 | +| 2. Deterministic Seed Data | 采用零孤儿、时间线严丝合缝、可完全确定性复现的种子数据包 | +| 3. Every demo UI contains meaningful | 每一个受测界面必须呈现生动真实的业务数据，严禁空表与占位符 | +| 4. Real client API used whenever live | 外部接口真实可用的必须真实调用（如 DMS 只读），绝不弄虚作假 | +| 5. Mock clearly identified | 任何模拟桩必须在界面文案与接口日志中显式标明为 [MOCK_SIMULATION] | +| 6. Gemini MCP performs real UI steps | 由 MCP 自动化工具驱动真实无头 Chrome 浏览器执行真实用户交互 | +| 7. Every step has evidence screenshot | 每一个有业务意义的操作步骤均留存全屏证据截图与 SHA-256 账本哈希 | ++--------------------------------------------------------------------------------------------------+ +``` + +--- + +## 2. 详细执行准则剖析 + +### 2.1 铁律 1：纯净独立演示库 (`Fresh Clean Demo Database`) +- 在 Kingbase 实例中新建独立演示数据库 `training_demo_clean`； +- 严禁包含历史测试遗留的 200+ 张杂乱无序的临时表与脏记录； +- 数据库结构 100% 由 `000` 到 `010` 及 `001` 到 `015` 官方迁移脚本构建。 + +### 2.2 铁律 2：确定性业务种子 (`Deterministic Seed Data`) +- 种子数据必须满足“微型但全生命周期闭环”： + - 5 名授课教师（覆盖房建、公寓、暖通、电气专业，全量绑定用户账号）； + - 30 名参训学员（分为 2 个班级，身份证密文合规，全量绑定用户账号）； + - 6 门标准培训课程（3 门理论、3 门实作）； + - 4 间标准教室、2 处实训场地； + - 8 间标准宿舍房间（严格区分男女宿舍，床位编号清晰）； + - 2 期标准培训班（1 期已结训用于展示全流程成果与报表，1 期进行中用于现场动态交互演示）。 + +### 2.3 铁律 3：界面数据丰富饱满 (`Every demo UI contains meaningful data`) +- 严禁出现“点击进入排课，表格一片空白”、“点击成绩，暂无数据”等半成品现象； +- 统计分析驾驶舱必须预置足够跨度（至少连续 14 天）的打卡流水，使得趋势折线图、状态分布饼图与 Top 10 排行榜丰满生动； +- 学员成长画像必须具备饱满的课时雷达与打卡足迹。 + +### 2.4 铁律 4 与 5：真伪分离透明原则 (`Real vs Mock Transparency`) +- **真实调用**：DMS 只读连通接口（Token 鉴权、空间列表）调用真实外部网络，证明系统具备外部集成能力； +- **显式 Mock**：在外部无真实通电门锁的情况下，门禁密码下发与电子班牌通信在前端提示与响应报文中均加上 `[SIMULATION / MOCK]` 标识，坦诚沟通，绝不忽悠客户。 + +### 2.5 铁律 6 与 7：全过程证据链不可篡改 (`MCP Real Steps & Evidence Capture`) +- 演示过程必须使用真实角色账号（`qa_train_admin`、`qa_teacher_a`、`qa_student_a`）在真实浏览器中点击、输入、提交； +- 杜绝使用 `admin` 权限伪造通过结论； +- 每一个关键交互产出一张带时间戳与 URL 的 PNG 截图，并计算 SHA-256 登记入 `evidence-ledger.csv`。 diff --git a/docs/current/07-KNOWN-GAPS.md b/docs/current/07-KNOWN-GAPS.md new file mode 100644 index 000000000..b1f33dcc8 --- /dev/null +++ b/docs/current/07-KNOWN-GAPS.md @@ -0,0 +1,66 @@ +# 07 - 内部已知缺口与外部阻塞清单 (Known Gaps) + +> **最高准则**： +> 1. 本清单仅记录**经过当前真实代码、测试断言或运行时验证确认的客观事实**； +> 2. **严禁自动修复**：本轮任务为 Documentation Bootstrap，严禁擅自修改业务代码或数据库尝试修复这些问题； +> 3. 历史已解决的问题已移出本清单，本清单是研发团队排期解决的唯一现行缺陷总账。 + +--- + +## 1. 内部产品级阻断缺陷 (Internal Product Blockers) + +### 🔴 GAP-01: `ACCOM-PERM-01` — 住宿生命周期操作未授予业务角色 +- **缺陷标识**：`ACCOM-PERM-01` +- **严重等级**：**`BLOCKER` (产品级阻断)** +- **发现时间**：2026-09-23 +- **影响场景**： + - 直接影响：`SM-10` (学员入住办理 0→1)、`SM-11` (预分配退宿 0→2)、`SM-12` (在住退宿 1→2 及撤销门锁授权)、`SM-13` (调房换宿)； + - 间接影响：`BR-11`、`EXT-02`（依赖退宿触发外部撤权）； + - **累计阻断 6 个业务验收场景**。 +- **根因技术剖析**： + 1. **前端门控**：`ruoyi-ui/src/views/train/accommodation/index.vue` 中，“入住”与“删除”按钮由 `v-hasPermi="['train:accommodation:edit', 'train:accommodation:remove']"` 双重权限门控；“调房”与“退宿”由 `train:accommodation:edit` 门控； + 2. **系统菜单缺失**：数据库 `sys_menu` 中虽然定义了 `train:accommodation:edit`（menu_id: 2263），但 **`train:accommodation:remove` 在 `sys_menu` 中完全不存在 (`count = 0`)**； + 3. **角色授权不足**：业务管理员角色 `train_admin` 在权限配置中仅被授予了 `train:accommodation:list`、`train:accommodation:query` 与 `train:accommodation:add`，**无 `:edit` 与 `:remove` 权限**； + 4. **为何前期自测未暴露**：早期自动化测试脚本使用超级管理员 `admin` 运行，RuoYi 框架对 `admin` 账号默认返回 `*:*:*` 全放行，导致非超管角色的权限缺失被严重掩盖。 +- **当前处置要求**：客观记录于本清单，严禁在文档梳理轮次擅自修改 SQL 或代码；待后续产品修复阶段统一闭环。 + +--- + +## 2. 外部客观环境阻塞项 (External Environmental Blockers) + +### 🟡 GAP-02: DMS 外部物理房间与通电门锁硬件缺失 +- **缺陷标识**：`DMS-HARDWARE-01` +- **严重等级**：**`BLOCKED_EXTERNAL` (外部客观阻塞)** +- **客观事实**： + - 局域网内 DMS 厂商测试环境网络畅通，官方账号鉴权与 Token 获取通过（7200秒有效）； + - 只读 API（建筑、楼层、房间、门锁）接口响应结构解析通过； + - 但该测试环境当前**挂载的物理建筑、房间与门锁数量均为 0**； + - 现场缺少实体通电门锁设备与物理沙箱，无法验证实际刷卡或密码开锁。 +- **安全红线**： + - 严禁在无客户明确指定真实测试门锁前向未知外部设备发起 Mutation 写操作 (`REAL_DMS_MUTATION_COUNT = 0`)； + - 生产环境严禁集成远程开锁 (Remote Unlock)。 +- **解除阻塞条件**：沈阳房建公寓段在现场为系统划分具体的实体测试房间，并完成智能门锁通电上云。 + +--- + +## 3. 研发推进中与待确认功能缺口 (In-Progress & Pending Gaps) + +### 🔵 GAP-03: 成绩管理动态权重与评定交互闭环 (C03) +- **状态**：`PARTIAL` (推进中) +- **现状**：物理表 `train_score_info` 已建立，支持基础成绩录入； +- **缺口**： + - 理论与实作多科目加权汇总计算算法的前端交互尚未收敛； + - 教师工作台专属打分视图与成绩单导出功能尚在研发收尾阶段。 + +### 🔵 GAP-04: 学员 360 度成长画像多维雷达模型 (C05) +- **状态**：`PARTIAL` (部分能力具备) +- **现状**：基础档案卡、考勤出勤统计、学习时长累计等数据展现已打通； +- **缺口**：五维能力评价模型指标权重、评语自动生成算法尚未获得甲方正式确认，当前维持基础视图呈现。 + +### 🔵 GAP-05: 考勤统计指标口径待确认项 (PENDING-01 ~ PENDING-04) +- **状态**：`PENDING_CLIENT_CONFIRMATION` +- **待确认业务规则**： + 1. `PENDING-01`：未报到参训学员开班后是否从第一节课起计入应到出勤分母； + 2. `PENDING-02`：经审批合规的请假人次是否从出勤率分母中扣除； + 3. `PENDING-03`：放弃参训学员在放弃时间节点前后的历史课次有效性切分； + 4. `PENDING-04`：请假是否计入考勤异常 Top 10 预警排行榜（当前系统支持通过开关集中控制）。 diff --git a/docs/current/08-NEXT-ACTIONS.md b/docs/current/08-NEXT-ACTIONS.md new file mode 100644 index 000000000..c2de0ab19 --- /dev/null +++ b/docs/current/08-NEXT-ACTIONS.md @@ -0,0 +1,64 @@ +# 08 - 下一阶段标准化行动路线图 (Next Actions) + +> **最高原则**：后续工作必须严格按以下 14 步标准流依次推进，每一步必须有前置条件检查与验收断言，**严禁跨阶段盲目跳步**！ + +--- + +## 1. 严格固定的 14 步行动路线图 (The 14 Mandatory Steps) + +```text +================================================================================ + RAILWAYSYSTEM 14-STEP ROADMAP TO DELIVERY +================================================================================ + 1. Freeze old runtime + └─ 彻底停止并冻结所有旧测试脚本与临时后台进程，锁定当前代码基线。 + + 2. Preserve old database as historical evidence + └─ 对当前存在脏数据与历史痕迹的数据库执行可验证物理快照备份，作为只读证据封存。 + + 3. Create CLEAN_DEMO_DATABASE + └─ 在 KingbaseES 实例上新建完全独立的纯净演示数据库 (training_demo_clean)。 + + 4. Rebuild schema from migrations + └─ 严格按 000~010 官方迁移链脚本在纯净库中重构全部 21 张表与系统表结构。 + + 5. Build deterministic demo seed + └─ 编制并灌入确定性、零孤儿、时序严丝合缝的黄金业务种子数据集。 + + 6. Validate 100% UI data coverage + └─ 全量核验所有前端业务界面，确保每一个页面均有丰满真实的有效数据，0 空白页。 + + 7. Probe client APIs + └─ 在安全受控网络下对 DMS 等外部系统发起实时探测，验证网络连通与鉴权有效性。 + + 8. Integrate usable real APIs + └─ 将真实可用的外部接口（只读空间/门锁查询）正式接入主业务流。 + + 9. Resolve product blockers + └─ 针对性修复产品级阻断缺陷（首要修复 ACCOM-PERM-01 住宿操作权限缺失）。 + +10. Establish one demo candidate baseline + └─ 确立全工程唯一的“演示候选基线 (Demo Candidate Baseline)”，冻结代码与数据。 + +11. Gemini MCP full scenario demonstration + └─ 由 Gemini MCP 工具驱动真实 Chrome 浏览器，以非超管真实角色执行全场景验收。 + +12. Freeze final Demo + └─ 留存完整全屏截图与 SHA-256 证据账本，签署并冻结最终 Demo 交付成果。 + +13. Full Docs Cleanup Phase B + └─ 演示完全冻结后，解冻文档治理门禁，正式执行文档目录物理搬迁与归档。 + +14. Produce Client Status Report + └─ 产出最终面向沈阳房建公寓段主管领导的正式项目交付与系统状态报告。 +================================================================================ +``` + +--- + +## 2. 阶段准入与准出守卫 (Stage Gates) + +- **进入第 3~6 步守卫**：旧数据库备份未完成前，严禁创建新库； +- **进入第 9 步守卫**：阻断项修复必须有专门的单元测试与权限回归契约测试守护； +- **进入第 11 步守卫**：`ACCOM-PERM-01` 必须彻底解决，且以 `train_admin` 角色能够在 UI 成功点击入住与退宿； +- **进入第 13 步守卫**：演示证据账本彻底封存且后台无任何写入进程前，绝对不启动 Docs Phase B。