From bef9b49c6c07da32251178189540f2132881c479 Mon Sep 17 00:00:00 2001 From: wangzhibiao Date: Thu, 17 Sep 2026 16:11:46 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E6=96=87=E6=A1=A3=EF=BC=9A?= =?UTF-8?q?=E5=BB=BA=E7=AB=8B=E5=BD=93=E5=89=8D=E6=96=87=E6=A1=A3=E5=85=A5?= =?UTF-8?q?=E5=8F=A3=20docs/current?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/current/01-current-status.md | 73 +++++++++++++++++++++++++++++++ docs/current/02-phase1-status.md | 35 +++++++++++++++ docs/current/03-shared-trial.md | 55 +++++++++++++++++++++++ docs/current/04-known-gaps.md | 34 ++++++++++++++ docs/current/05-next-actions.md | 50 +++++++++++++++++++++ docs/current/README.md | 28 ++++++++++++ 6 files changed, 275 insertions(+) create mode 100644 docs/current/01-current-status.md create mode 100644 docs/current/02-phase1-status.md create mode 100644 docs/current/03-shared-trial.md create mode 100644 docs/current/04-known-gaps.md create mode 100644 docs/current/05-next-actions.md create mode 100644 docs/current/README.md diff --git a/docs/current/01-current-status.md b/docs/current/01-current-status.md new file mode 100644 index 000000000..241fa6093 --- /dev/null +++ b/docs/current/01-current-status.md @@ -0,0 +1,73 @@ +# 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. 当前共享试用业务数据大盘 (Live Dataset) + +共享试用数据库 `training` 当前承载的数据来源于全量验证后的综合验收数据集，真实业务规模如下： + +```text +======================================================================== + 共享试用环境现存业务数据体量 +======================================================================== + - 培训开班计划 (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) + - 未决缺口与外部阻塞：[04-known-gaps.md](04-known-gaps.md) diff --git a/docs/current/02-phase1-status.md b/docs/current/02-phase1-status.md new file mode 100644 index 000000000..99640736a --- /dev/null +++ b/docs/current/02-phase1-status.md @@ -0,0 +1,35 @@ +# 02. 一期需求实现状态全景判定 (Phase 1 Status) + +> **最高原则**：**具备共享试用条件 ≠ 一期全部需求正式完成**。 +> 团队坚持实事求是，严格区分“核心教务已验证能力”与“待业务确认/研发推进中能力”，杜绝虚报与浮夸。 + +--- + +## 1. 需求落地分类汇总 + +根据系统真实代码、数据库落地结构以及自动化 E2E 验证结果，一期规划需求状态精简分类如下： + +| 状态分类 | 包含的核心业务功能 | 现状说明与边界 | +| :--- | :--- | :--- | +| **`DONE_VERIFIED`**
(已完成并验证) | **1. 基础资源**：教师档案、学员主档（国密脱敏）、课程库、教室、实训场地、宿舍房间
**2. 教务主链**：开班计划（草稿/发布/结训）、一班多课绑定、参训名册导入、排课四维时段冲突预检
**3. 现场执行**：开班报到确认、课次出勤打卡、教师代签与请假修正、自主学时台账
**4. 权限与门户**：管理员控制台、教师个人课表工作台、学员个人培训中心、最小权限防越权 | 前后端代码、Kingbase 物理表、自动化测试（331 项）及浏览器 E2E 已全部通过，业务正向主闭环已完全就绪。 | +| **`IN_PROGRESS`**
(研发推进中) | **成绩管理闭环 (C03)** | 新成绩体系基础表结构已就绪，成绩科目设置、加权得分计算及综合统计正在进行最终代码闭环与页面联调。 | +| **`PARTIAL_FUNCTION`**
(部分能力具备) | **学员能力画像 (C05)** | 基础档案信息卡、学时积累与报到出勤雷达基础模型已可用；高阶动态加权能力画像有待考核数据进一步沉淀后完善。 | +| **`EXTERNAL_BLOCKER`**
(外部客观阻塞) | **真实门禁写操作与硬件联动 (DMS)** | 协议通信与只读连通已验证；因真实环境尚未挂载测试房间及门锁硬件通电，物理下发判定为外部客观阻塞。 | +| **`CUSTOMER_CONFIRMATION`**
(待甲方业务确认) | **业务口径与组织架构归属** | 详见下方清单，涉及学员名册导入模版格式、报到核验现场硬件配备、请假与门禁权限保留策略等。 | + +--- + +## 2. 权威需求跟踪入口 + +如需查阅每一条需求的详细代码文件位置、SQL 表名、测试用例或具体待确认问题，请点击以下权威文档： + +- 📋 [**一期需求实现进度表 (逐项核验)**](../requirements/一期需求实现进度表.md)：包含域 A~G 共数十项功能点的前后端代码文件、断言证据与下一步建议。 +- ❓ [**一期甲方需求确认清单 (开会对齐)**](../requirements/甲方需求确认清单.md)：系统归纳 P0(核心阻塞 18 项)、P1(业务形态 12 项)、P2(长远规划 8 项) 业务确认表。 + +--- + +## 3. 验收与交付策略 + +1. **共享试用准入**：当前 `DONE_VERIFIED` 覆盖了沈阳房建公寓段开展职工日常集中面授的核心操作，已在局域网开放试用； +2. **闭环收口原则**：针对 `IN_PROGRESS`（成绩）和 `PARTIAL_FUNCTION`（画像），研发团队在小版本迭代中收敛闭环； +3. **外部硬件解除阻塞**：待甲方明确门锁房间划拨并完成物理连通后，即刻组织现场专项联调验收。 diff --git a/docs/current/03-shared-trial.md b/docs/current/03-shared-trial.md new file mode 100644 index 000000000..87db1097b --- /dev/null +++ b/docs/current/03-shared-trial.md @@ -0,0 +1,55 @@ +# 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`，自带 13 个完整测试培训班及对应的人员、排课与出勤流水，开箱即用，无需从零制表。 + +--- + +## 2. 账号体系与角色类型 + +系统严格划分三类业务角色，支持针对性体验（账号密码已通过线下安全方式交接给现场管理员，严禁在文档中明文记录）： + +| 角色类型 | 代表账号身份 | 试用推荐场景 | +| :--- | :--- | :--- | +| **系统管理员 (Admin)** | 教务主管账号 | 登录后进入全功能控制台：体验新建培训计划、配置多门课程、导入参训学员、执行四维冲突排课、现场扫码/刷卡报到核验、宿舍房间分配等。 | +| **授课教师 (Teacher)** | 专业主讲教员账号 | 登录后自动进入“教师工作台”：直观查阅个人本周授课日程、点击课次查看应到学员名册、进行课堂签到签退核验及代签补卡。 | +| **参训学员 (Student)** | 在训职工学员账号 | 登录后自动进入“学员培训中心”：查阅本人参训计划、课表安排、个人历史考勤打卡记录、以及分配入住的宿舍房间。 | + +--- + +## 3. 试用反馈与问题流转流程 + +为确保试用反馈高效闭环，请按以下流程反馈问题与建议： + +```text +[试用人员发现问题/提出需求] + │ + ▼ +[记录现象截图与复现步骤] + │ + ▼ +[提交至项目微信群 / 试用问题登记表] + │ + ▼ +[研发团队定级分类] + ├── 🔴 BUG (功能缺陷) ── 即时排查，进入热修复流程 + ├── 🟡 UX (操作体验/展示优化) ── 纳入小版本 UI 优化 + ├── 🔵 KNOWN_GAP (已知缺口) ── 对齐 C03/C05 计划进度 + └── ⚪ REQUIREMENT (新增需求) ── 登记入《甲方需求确认清单》待甲方定级 +``` + +--- + +## 4. 试用注意事项 +1. **请勿执行清库或破坏性测试**：试用数据已形成完整的教学业务流转闭环，请在现有数据或新增独立计划基础上开展测试； +2. **硬件联动说明**：若在界面上触发智能门锁相关操作，系统当前采用安全模拟与受控状态机流转，不会对外部物理设备产生破坏性冲击。 diff --git a/docs/current/04-known-gaps.md b/docs/current/04-known-gaps.md new file mode 100644 index 000000000..13f90124a --- /dev/null +++ b/docs/current/04-known-gaps.md @@ -0,0 +1,34 @@ +# 04. 内部已知缺口与外部阻塞清单 (Known Gaps) + +> **透明度原则**：所有历史已修复缺陷已从本清单移出；本文件仅客观记录**当前尚未完全闭环的内部业务缺口**与**客观外部依赖项**，供研发排期与客户沟通时对照。 + +--- + +## 1. 内部研发已知缺口 (Internal Gaps) + +| 编号 | 模块 / 缺口项 | 当前实际状态 | 预期差距与原因说明 | 详细依据文档 | +| :---: | :--- | :---: | :--- | :--- | +| **G-01** | **成绩管理闭环 (C03)** | `IN_PROGRESS`
(推进中) | 物理数据库支持动态科目与权重设计已落地；一期完整正向评分流（教师端录入得分、加权自动折算、结业成绩汇总台账）前端交互正处于最后收敛阶段。 | [Round 3B 成绩能力评估](../reports/integrated-acceptance/INT_QA_R3B_20260917_094500/round-3b/score-current-capability.md) | +| **G-02** | **学员画像能力 (C05)** | `PARTIAL_FUNCTION`
(部分能力) | `/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，缺少真实行级数据以在运行时验证行级字段映射契约。
**解除条件**：厂商向测试环境分配真实房间数据。 | [DMS 终检状态报告](../reports/integrated-acceptance/FINAL_PHASE1_20260917_101044/dms-final-status.md) | +| **B-02** | **DMS 真实写操作变更 (Mutation)** | `BLOCKED_EXTERNAL` | 密码下发与远程撤权接口在本地及 Mock 环境测试通过；在无真实测试房间挂载下，禁止向未知外部系统发起真实写操作。
**解除条件**：获得正式授权的测试门锁设备标识。 | [DMS 外部阻塞清单](../reports/integrated-acceptance/FINAL_PHASE1_20260917_101044/external-blockers.md) | +| **B-03** | **DMS 物理硬件与实体通电** | `BLOCKED_EXTERNAL` | 缺少现场实体通电门锁与物理沙箱，无法验证物理刷卡开门或密码键盘实际响应。
**解除条件**：现场硬件通电联调。 | [DMS 外部阻塞清单](../reports/integrated-acceptance/FINAL_PHASE1_20260917_101044/external-blockers.md) | + +--- + +## 3. 甲方待确认事项 (Customer Confirmations) + +目前有若干业务细节形态需要沈阳房建公寓段业务老师明确： +1. **学员档案批量导入模版**：确认标准 Excel 表头字段口径与必填项； +2. **现场报到主交互设备**：确认是一期现场电脑人工点击确认，还是外接读卡器或扫码枪； +3. **住宿分配颗粒度**：确认一期排宿精确到具体房间号，还是必须精确到固定床位编号； +4. **学员请假与门禁权限保留策略**：确认请假期间是否保留宿舍进出权限（当前系统默认策略：保留进门权限）。 + +👉 详细确认清单请查阅：[甲方需求确认清单 (P0/P1/P2)](../requirements/甲方需求确认清单.md)。 diff --git a/docs/current/05-next-actions.md b/docs/current/05-next-actions.md new file mode 100644 index 000000000..04ab047bc --- /dev/null +++ b/docs/current/05-next-actions.md @@ -0,0 +1,50 @@ +# 05. 下一阶段工作模式与行动计划 (Next Actions) + +> **工作模式转型**：随着一期教务核心主链路与三角色工作台全面通过综合验收，项目工作模式已正式由“大规模基础闭环开发”转向**“共享试用驱动、敏捷小版本迭代”**。 + +--- + +## 1. 敏捷运作机制 + +后续研发与交付严格遵循以下反馈流转机制： + +```text + ┌────────────────────────────────────────────────────────┐ + │ 1. 局域网共享试用 (http://192.168.139.230:8082/) │ + │ 段内业务老师与教务主管开展真实教学排课与考勤试用 │ + └─────────────────────────┬──────────────────────────────┘ + │ 发现问题/提出需求 + ▼ + ┌────────────────────────────────────────────────────────┐ + │ 2. 问题归类与定级 (Triage) │ + │ - 🔴 BUG : 阻断缺陷，当日修复并自动化回归 │ + │ - 🟡 UX : 界面与交互体验，周版本批次优化 │ + │ - 🔵 KNOWN_GAP : 归入已知技术缺口专项排期 │ + │ - ⚪ REQUIREMENT : 登记入甲方确认清单待批复 │ + └─────────────────────────┬──────────────────────────────┘ + │ 敏捷推进 + ▼ + ┌────────────────────────────────────────────────────────┐ + │ 3. 小版本迭代与发布 (Release Cycles) │ + │ 本地构建验证 → Surefire 全量通过 → 部署试用分支 │ + └────────────────────────────────────────────────────────┘ +``` + +--- + +## 2. 下一阶段四大核心开发任务 + +| 优先级 | 任务主题 | 核心目标与交付内容 | 负责范围 | +| :---: | :--- | :--- | :--- | +| **P0** | **响应共享试用现场反馈** | 快速响应业务老师在局域网试用中提出的交互阻滞、文案不准确或表单校验细节问题，保障试用体验平滑顺畅。 | 前端交互、教务微调 | +| **P1** | **成绩管理闭环 (C03)** | 完善成绩科目配置、教师端分项打分、加权综合成绩折算与导出台账，完成该模块最后一公里闭环。 | `ruoyi-train` 后端及前端 | +| **P2** | **学员画像能力完善 (C05)** | 丰富学员多维画像雷达图指标计算，引入培训考评与实训维度的实际得分联动，提升画像深度。 | 数据分析、ECharts 视图 | +| **P3** | **DMS 真实物理联调准备** | 持续跟踪段内智能门锁测试环境房间划拨与通电进度，一旦资源具备，立即启动现场行级数据验证与物理发码。 | DMS 适配器、现场联调 | + +--- + +## 3. 分支与质量纪律 + +1. **共享试用分支保护**：`feat/cicd-pipeline` 必须保持随时可试用状态；任何代码合并前必须通过 `mvn clean test`（331 项全绿）； +2. **Git 中文规范**：所有新提交严格遵循 `<中文类型><可选范围>：<中文说明>` 格式； +3. **安全底线**：严禁提交真实密码凭证，严禁执行非备份的清库操作。 diff --git a/docs/current/README.md b/docs/current/README.md new file mode 100644 index 000000000..9fd5bebcc --- /dev/null +++ b/docs/current/README.md @@ -0,0 +1,28 @@ +# SYFJGYD学员管理系统 — 当前项目速览中心 (Current) + +> **核心定位**：专为任何需要“在 3 分钟内快速掌握项目当前实际现状”的读者提供的唯一权威速览入口。 +> **正式业务名称**：`SYFJGYD学员管理系统`（内部工程代号：RailwaySystem） +> **共享试用环境**：[http://192.168.139.230:8082/](http://192.168.139.230:8082/)（部署分支：`feat/cicd-pipeline`） +> **当前试用就绪度**：`READY_WITH_EXTERNAL_BLOCKERS`（核心业务全通，具备局域网教学试用条件） + +--- + +## 🧭 当前速览文件导航 + +本目录包含 5 份精简、客观、直击核心事实的速览文档： + +| 文件 | 核心内容 | 推荐阅读对象 | +| :--- | :--- | :--- | +| [**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) | **下一阶段行动路线**（工作模式转变、小版本迭代计划与近期重点） | 研发团队、项目协调人 | + +--- + +## 📌 阅读建议 +- 如果你只想知道**“系统做成啥样了、跑通了哪些功能”**：请直接阅读 [01-current-status.md](01-current-status.md)； +- 如果你要去和**“沈阳房建公寓段领导/指导老师开会对需求”**：请直接阅读 [02-phase1-status.md](02-phase1-status.md) 并带上需求清单； +- 如果你正准备**“在局域网试用系统并提出反馈”**：请直接阅读 [03-shared-trial.md](03-shared-trial.md)； +- 如果你要**“继续写代码或排期”**：请直接阅读 [04-known-gaps.md](04-known-gaps.md) 与 [05-next-actions.md](05-next-actions.md)。