文档更新：重构根目录与文档中心导航地图
This commit is contained in:
wangzhibiao committed
1 parent
bef9b49c6c
commit
d5ffc05ae4
2 files changed
+100
-189
No files matched your search
@@ -1,125 +1,64 @@
|
||||
# RailwaySystem 智慧培训系统
|
||||
# SYFJGYD学员管理系统
|
||||
|
||||
> **当前交付候选版本 (Final Candidate)**：`5a49b2e2988bf23ca2a70568264c05b24dfda1b6`
|
||||
> **远程基线分支**：`origin/feat/cicd-pipeline`
|
||||
> **自动化测试覆盖**：后端单元与契约测试 154/154 PASS，核心业务主链集成用例 6/6 PASS，Kingbase 物理断言 11/11 PASS，端到端浏览器真实验收 PASS (0 阻断 / 0 异常 / Swagger 连通)。
|
||||
> **内部工程代码代号**：`RailwaySystem`
|
||||
> **共享试用环境**：[http://192.168.139.230:8082/](http://192.168.139.230:8082/)（部署分支：`feat/cicd-pipeline`）
|
||||
> **质量验证状态**：后端全量测试 **331 / 331 PASS (0 Failures / 0 Errors)**，管理员/教师/学员三角色无头浏览器 E2E 验证全绿通过。
|
||||
> **试用就绪度判定**：`READY_WITH_EXTERNAL_BLOCKERS`（核心教务全链路打通，具备局域网试用条件）。
|
||||
|
||||
---
|
||||
|
||||
## 📖 项目简介
|
||||
## 📖 系统简介
|
||||
|
||||
RailwaySystem 是一套专为铁路职工与业务学员量身打造的一站式智慧培训管理系统。系统基于 Spring Boot 2.5、若依（RuoYi-Vue）企业级底座、Vue 2.6 前端框架以及国产人大金仓（KingbaseES）高安全数据库构建。系统全面贯穿从基础教务资源维护、开班计划编排、学员批量建档、现场开班报到、课次冲突检测、多模式考勤打卡、自动结训归档到多维学情画像与综合分析的全业务生命周期。
|
||||
**SYFJGYD学员管理系统**是专为沈阳房建公寓段短周期铁路职工集中面授培训量身研发的一体化数字化教务管理平台。
|
||||
|
||||
---
|
||||
|
||||
## 🛠 技术架构栈
|
||||
|
||||
- **后端架构**：Java 8+ / Spring Boot 2.5 / Spring Security / MyBatis / PageHelper / RuoYi-Vue
|
||||
- **核心培训业务模块**：`ruoyi-train`（独立封装教务、排课、考勤、计划、住宿等完整业务域逻辑与应用服务）
|
||||
- **系统管理与支撑底座**：`ruoyi-system`、`ruoyi-framework`、`ruoyi-common`、`ruoyi-admin`
|
||||
- **前端架构**：Vue 2.6 / Vue Router / Vuex / Element UI / Axios / ECharts
|
||||
- **交互工程**：`build_ui`（当前 Final Candidate 实际构建和部署使用的 Vue 前端工程）
|
||||
- **历史资产**：`RuoYi-Vue/ruoyi-ui`（若依原始/历史前端资产，不作为当前 Final Browser Acceptance 主构建源）
|
||||
- **数据存储与持久化**：
|
||||
- **国产主库**：人大金仓 **KingbaseES V009R003C018**（MySQL 兼容模式，驱动版本 `com.kingbase:kingbase8:8.6.0`）
|
||||
- **缓存与会话**：Redis 6+（支持密码预检与分布式缓存）
|
||||
- **发布与数据库增量 (Release DB Delta)**：
|
||||
- 当前增量版本：`CURRENT_RELEASE_DB_DELTA = 3`（包括 `001_sys_oper_log_cost_time.sql`、`002_legacy_analytics_permissions.sql`、`003_report_attendance_action_permissions.sql`）
|
||||
|
||||
---
|
||||
|
||||
## 🔄 核心业务闭环主链
|
||||
|
||||
系统严格遵循业务不变量与领域模型设计，构建了从教务准备到结业归档的标准业务闭环：
|
||||
系统基于 Spring Boot 2.5、若依（RuoYi-Vue）企业级底座、Vue 2.6 前端框架以及国产人大金仓（KingbaseES）高安全数据库构建。全面贯穿从基础教务资源维护、开班计划编排、学员批量建档（国密SM4脱敏）、四维时段冲突排课、现场人脸/扫码报到、课次考勤打卡到结训归档的全生命周期。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["基础资源准备<br/>(教师/学员/课程/教室/场地/宿舍)"] --> B["培训计划 (Plan)<br/>创建开班计划 · 0:草稿"]
|
||||
B --> C["本期课程 (PlanCourse)<br/>绑定课程、教师与学时"]
|
||||
C --> D["参训学员 (Enrollment)<br/>名单批量导入 · 0:待报到"]
|
||||
D --> E["开班发布 (Plan Publish)<br/>锁定计划配置 · 1:进行中"]
|
||||
|
||||
E --> F1["现场报到 (Report)<br/>人脸/刷卡/扫码核验<br/>状态更新为 1:已报到"]
|
||||
E --> F2["课次排课 (Scheduling)<br/>四维时段冲突预检<br/>(教师/教室/场地/本班)"]
|
||||
|
||||
F1 --> G["课次考勤 (Attendance)<br/>签到/签退打卡，教师代签与请假修正留痕"]
|
||||
F2 --> G
|
||||
|
||||
G --> H["培训结训 (Completion)<br/>计划置为 2:已结束，在读学员批量联动为 4:已完成"]
|
||||
H --> I["学情分析 (Analytics - Read Only)<br/>报到统计、考勤汇总、学习时长与综合能力画像"]
|
||||
flowchart LR
|
||||
A["基础资源就绪"] --> B["开班计划制定"]
|
||||
B --> C["本期课程绑定"]
|
||||
C --> D["参训学员名册"]
|
||||
D --> E["四维冲突排课"]
|
||||
E --> F["开班现场报到"]
|
||||
F --> G["课堂考勤打卡"]
|
||||
G --> H["结训状态流转"]
|
||||
H --> I["历史档案沉淀"]
|
||||
```
|
||||
*(注：学员宿舍安排作为生活保障支线，电子班牌作为现场多媒体与打卡硬件设备支撑)*
|
||||
|
||||
---
|
||||
|
||||
## 🧭 文档中心导航
|
||||
## 🧭 核心文档权威直达 (Documentation Map)
|
||||
|
||||
本项目采用**人类可读文档层（Human Documentation Layer）与技术契约事实源（Contract Sources）分层治理**：
|
||||
为避免在海量文档中迷失，请根据当前需求直接点击对应权威入口：
|
||||
|
||||
| 入口推荐 | 文档位置 | 说明与适用对象 |
|
||||
| 你的目标 | 推荐直达入口 | 核心内容与说明 |
|
||||
| :--- | :--- | :--- |
|
||||
| 🌟 **视觉化展示门户 (推荐首先访问)** | [docs/visual/index.html](docs/visual/index.html) | **纯静态可离线浏览**。面向评审专家、客户与业务方的交互式展示门户，含业务流程拓扑、系统架构图、14 大模块导览与质量看板。 |
|
||||
| 📚 **人类操作手册与架构白皮书** | [docs/handbook/](docs/handbook/) | 面向项目经理、开发与测试人员的系统级手册（涵盖项目总览、业务流程、架构设计、数据模型、模块指南与部署运维）。 |
|
||||
| 📑 **综合验收与测试报告** | [docs/reports/](docs/reports/) | 包含自动化集成测试报告、发版说明 (Release Notes) 与浏览器端到端验收记录。 |
|
||||
| 📋 **业务需求基线中心** | [doc/README.md](doc/README.md) | ★★★ [PRD V1.0 业务需求基线](doc/RailwaySystem%20智慧培训系统一期%20PRD%20V1.0.md)（正式冻结基线，32章全景规范）、原始甲供资料、历史版本演进。 |
|
||||
| 🔒 **冻结技术契约 (Source of Truth)** | [docs/api-v2/](docs/api-v2/)<br>[docs/database-v2/](docs/database-v2/) | 开发与 Agent 技术事实源。包含冻结的 REST API 契约、DTO/VO 字典、21 张物理表字段规范与权限错误码。 |
|
||||
| 📋 **技术文档全景索引** | [docs/README.md](docs/README.md) | 技术文档中心主索引，提供面向不同角色（业务/研发/测试/历史审计）的精确导读。 |
|
||||
| 🌟 **想快速了解项目现在做到哪了** | [**docs/current/**](docs/current/README.md) | **【首选入口】** 当前系统状态速览、试用数据大盘、需求落地度与行动计划。 |
|
||||
| 📋 **想对照一期功能需求与待确认项** | [**docs/requirements/**](docs/requirements/一期需求实现进度表.md) | 一期需求逐项代码实现进度表、以及面向甲方的待确认清单 (P0/P1/P2)。 |
|
||||
| 📚 **想系统了解业务流程与技术架构** | [**docs/handbook/**](docs/handbook/01-project-overview.md) | 面向团队的系统级手册（涵盖项目总览、业务流程、架构设计、数据模型与开发部署）。 |
|
||||
| 🔌 **想对接后端 API 接口或 DTO 契约** | [**docs/api-v2/**](docs/api-v2/00_readme.md) | 冻结的 REST API 契约、入参出参模型定义与业务错误码规范。 |
|
||||
| 🗄️ **想查阅国产金仓数据库物理表结构** | [**docs/database-v2/**](docs/database-v2/01_table_inventory.md) | 21 张真实物理业务表字段清单、索引约束与迁移方案说明。 |
|
||||
| 🖥️ **想给领导/老师/专家进行生动展示** | [**docs/visual/index.html**](docs/visual/index.html) | **纯静态离线交付门户**，包含可交互业务状态机拓扑、系统架构图与 14 大模块导览。 |
|
||||
| 📑 **想查阅最终验收结果与测试日志** | [**docs/reports/**](docs/reports/README.md) | 包含当前唯一的最终验收报告 (FINAL_PHASE1) 及各轮次自动化测试证据链。 |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速启动指南
|
||||
## 🚀 快速启动指南 (开发环境)
|
||||
|
||||
### 1. 环境准备
|
||||
### 1. 基础环境要求
|
||||
- **JDK**：Java 8、11 或 17+
|
||||
- **Node.js**：Node 16+（已兼容 Node 22 与 OpenSSL 3.x）
|
||||
- **Node.js**：Node 16+（兼容 Node 22 与 OpenSSL 3.x）
|
||||
- **Redis**：本地启动 Redis 6+ 服务（默认端口 `6379`，无密码）
|
||||
- **数据库**：KingbaseES 8.6.0（通过跳板机隧道转发 `127.0.0.1:4321` 直连）
|
||||
- **数据库**：国产人大金仓 KingbaseES V9（通过跳板机隧道直连 `127.0.0.1:4321`，库名 `train_v2`）
|
||||
|
||||
### 2. 一键本地启动（开发模式）
|
||||
项目根目录下提供了全自动化本地启动脚本 [start-local.sh](start-local.sh)：
|
||||
### 2. 一键启动本地服务
|
||||
项目根目录下提供了全自动化本地启动脚本：
|
||||
```bash
|
||||
./start-local.sh
|
||||
```
|
||||
该脚本将自动唤醒本地 Redis、建立 Kingbase SSH 隧道、启动 Spring Boot 后端（端口 `8090`）以及启动前端工程（端口 `8080`）。
|
||||
|
||||
### 3. 系统默认访问入口
|
||||
- **前端系统界面**：[http://localhost:8080](http://localhost:8080)（本地开发） / `http://192.168.139.230:8082`（生产部署环境）
|
||||
- **后端 API 服务**：[http://localhost:8090](http://localhost:8090)（本地开发） / `http://192.168.139.230:8092`（生产部署环境）
|
||||
- **初始管理账号**：`admin` / `admin123`
|
||||
|
||||
---
|
||||
|
||||
## 📁 目录结构导览
|
||||
|
||||
```text
|
||||
RailwaySystem/
|
||||
├── README.md # 【本文件】项目总览、架构导览与启动指南
|
||||
├── start-local.sh # 本地一键启动脚本（集成数据库隧道与前后端并发启动）
|
||||
├── RuoYi-Vue/ # 后端工程（Spring Boot 单体增强版）
|
||||
│ ├── ruoyi-admin/ # Web 启动入口与 Controller 接口层
|
||||
│ ├── ruoyi-framework/ # 框架核心配置、WebSecurity 与拦截器
|
||||
│ ├── ruoyi-system/ # 核心业务模块（含培训管理业务 Entity/Mapper/Service）
|
||||
│ ├── ruoyi-common/ # 公共常量、工具类与通用组件
|
||||
│ └── ruoyi-ui/ # 若依原始/历史前端资产（不作为当前 Final Browser Acceptance 主构建源）
|
||||
├── build_ui/ # 当前 Final Candidate 实际构建和部署使用的 Vue 前端工程
|
||||
│ ├── src/api/ # 前端 Axios 接口层（含 train 培训业务接口）
|
||||
│ ├── src/views/train/ # 培训业务页面视图（学员、排课、宿舍、考勤等）
|
||||
│ └── package.json # 前端依赖与 Webpack 构建配置
|
||||
├── deploy/ # 生产部署、平滑重启脚本与 Nginx 示例配置
|
||||
├── doc/ # 业务与产品需求中心（PRD V1.0、原始资料与归档）
|
||||
├── docs/ # 技术架构、发布门禁、Human Documentation 与代码审计中心
|
||||
│ ├── visual/ # 视觉化交互展示门户（8 篇可离线全景架构与流程展示）
|
||||
│ ├── handbook/ # 人类操作白皮书与开发指南（01~09 全景手册）
|
||||
│ ├── reports/ # 验收测试报告与发版说明
|
||||
│ ├── _meta/ # 发布准备度、门禁清单与最终浏览器验收证据
|
||||
│ ├── api-v2/ # REST API 契约与 DTO/VO 字典
|
||||
│ └── database-v2/ # 数据库 V2 物理模型与迁移断言
|
||||
└── scripts/ # 驱动预检与质量断言脚本
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📌 开发与演进原则
|
||||
|
||||
1. **业务基线不可逆**：任何新页面开发、字段扩充与业务校验，统一以 [PRD V1.0](doc/RailwaySystem%20智慧培训系统一期%20PRD%20V1.0.md) 为唯一依据，旧版草案已全部归档。
|
||||
2. **非破坏性演进**：对 Kingbase 数据库与若依权限系统进行改造时，严格遵循技术审计报告结论，保持历史数据安全与可回滚性。
|
||||
### 3. 访问入口
|
||||
- **前端系统界面**：`http://localhost:8080`（本地开发） / [http://192.168.139.230:8082](http://192.168.139.230:8082)（内部共享试用环境）
|
||||
- **后端 API 服务**：`http://localhost:8090`（本地开发） / `http://192.168.139.230:8092`（共享试用环境）
|
||||
- **默认管理员**：`admin`（密码请咨询管理员，文档中不记录敏感凭据）
|
||||
+63
-91
@@ -1,117 +1,89 @@
|
||||
# RailwaySystem 文档中心总导航
|
||||
# SYFJGYD学员管理系统 — 文档中心全景地图 (Docs Map)
|
||||
|
||||
> **当前工程基线**：Final Candidate `5a49b2e2988bf23ca2a70568264c05b24dfda1b6` (`origin/feat/cicd-pipeline`)
|
||||
> **数据库增量版本**：`CURRENT_RELEASE_DB_DELTA = 3` (增量迁移 `001_sys_oper_log_cost_time.sql`、`002_legacy_analytics_permissions.sql`、`003_report_attendance_action_permissions.sql` 已就绪；`007_dicts.sql` 明确严禁执行)
|
||||
> **质量状态速览**：后端单元测试与契约测试 154 PASS，核心场景集成 6/6 PASS，110 次真实 HTTP 请求零 500 错误，Kingbase 物理断言 11/11 PASS，端到端浏览器自动化真实验收全量 PASS（Console 0 阻断，Swagger UI 正常连通）。
|
||||
> **正式业务名称**：`SYFJGYD学员管理系统`（内部工程代号：RailwaySystem）
|
||||
> **共享试用环境**：[http://192.168.139.230:8082/](http://192.168.139.230:8082/)（部署分支：`feat/cicd-pipeline`）
|
||||
> **核心质量结论**：核心教务正向闭环全面就绪，三角色工作台验证通过，测试全绿 **331 / 331 PASS**。
|
||||
|
||||
---
|
||||
|
||||
## 🧭 角色化阅读路线
|
||||
## 🧭 第一屏直达：按你的目标快速找文档
|
||||
|
||||
为了帮助不同背景的读者快速找到权威资料，本文档中心提供以下角色导航路径：
|
||||
请直接根据你当下的工作任务，点击下方直达通道：
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Entry["RailwaySystem 访问入口选择"]
|
||||
|
||||
subgraph R1["评审 / 领导 / 汇报"]
|
||||
V["离线交互门户<br/>visual/index.html"]
|
||||
H1["项目全景总览<br/>handbook/01"]
|
||||
end
|
||||
|
||||
subgraph R2["业务 / 教务员"]
|
||||
H2["业务主链规范<br/>handbook/02"]
|
||||
H5["14大业务模块指南<br/>handbook/05"]
|
||||
PRD["业务需求PRD<br/>../doc/README.md"]
|
||||
end
|
||||
|
||||
subgraph R3["开发 / 架构师"]
|
||||
H3["系统架构设计<br/>handbook/03"]
|
||||
H4["数据模型总览<br/>handbook/04"]
|
||||
H6["API与权限清单<br/>handbook/06"]
|
||||
API["API V2 事实源<br/>api-v2/"]
|
||||
end
|
||||
|
||||
subgraph R4["测试 / 交付团队"]
|
||||
H7["质量保障报告<br/>handbook/07"]
|
||||
TR["综合测试报告<br/>reports/final-test-report.md"]
|
||||
BR["浏览器验收报告<br/>reports/browser-acceptance-report.md"]
|
||||
DEP["部署与发版说明<br/>reports/release-notes.md"]
|
||||
end
|
||||
|
||||
Entry --> R1
|
||||
Entry --> R2
|
||||
Entry --> R3
|
||||
Entry --> R4
|
||||
```text
|
||||
┌────────────────────────────────────────────────────────────────────────┐
|
||||
│ 🎯 你当前的目标是？ │
|
||||
├────────────────────────────────────────────────────────────────────────┤
|
||||
│ 1. 只想快速了解当前系统做到哪了、能不能用？ ──► [docs/current/] │
|
||||
│ 2. 想看一期功能列表、代码对照与甲方确认项？ ──► [docs/requirements/] │
|
||||
│ 3. 想系统学习业务流程、系统架构与操作手册？ ──► [docs/handbook/] │
|
||||
│ 4. 想开发新功能、对接接口或查数据库字段？ ──► [docs/contracts/] │
|
||||
│ (包含 api-v2 / database-v2 / development) │
|
||||
│ 5. 想给领导、老师或评审专家进行生动展示？ ──► [docs/visual/] │
|
||||
│ 6. 想查阅最终验收报告或历史自动化测试证据？ ──► [docs/reports/] │
|
||||
└────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### A. 第一次阅读（推荐入口）
|
||||
## 📚 各目录体系深度说明
|
||||
|
||||
如果您是**第一次接触本项目**，或者需要向老师、主管、客户汇报系统成果：
|
||||
* 🌟 **强力推荐直达离线交互门户**：[visual/index.html](visual/index.html)
|
||||
* **特点**：无需启动后端服务或数据库，双击即可在任意现代浏览器中离线打开。
|
||||
* **内容**：提供深色工业风大屏质感，涵盖系统业务主链 SVG 交互拓扑、系统六层分层架构图、14 大核心业务模块互动矩阵、核心指标 KPI 仪表盘与发版准备度看板。
|
||||
* 📖 **快速阅读项目总览白皮书**：[handbook/01-project-overview.md](handbook/01-project-overview.md)
|
||||
* 专为人类读者编写，通俗阐述系统解决的教务痛点、服务对象、关键特性与一期交付边界。
|
||||
### 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)：敏捷小版本迭代工作模式与近期重点
|
||||
|
||||
---
|
||||
|
||||
### B. 业务人员与教务管理路径
|
||||
|
||||
关注业务流程、业务规则、状态流转与功能说明的读者，请查阅：
|
||||
1. [handbook/02-business-process.md](handbook/02-business-process.md) —— **核心业务全流程与状态机规范**（开班计划、报到核验、四维排课冲突预检、考勤打卡与结训联动）。
|
||||
2. [handbook/05-module-guide.md](handbook/05-module-guide.md) —— **14 大业务模块详细指南**（教师、学员、课程、教室、场地、宿舍、开班、报到、排课、考勤、班牌、统计等）。
|
||||
3. [../doc/README.md (业务需求中心与 PRD V1.0)](../doc/README.md) —— **业务需求最高事实源**（包含正式冻结的 PRD V1.0 原文与原始资料索引）。
|
||||
### 2. 📋 [docs/requirements/](requirements/一期需求实现进度表.md) — 业务需求与确认清单
|
||||
连接业务与代码的法定事实依据：
|
||||
- [一期需求实现进度表.md](requirements/一期需求实现进度表.md)：按模块逐项核对每一条需求的前后端代码实现、页面位置与测试证据
|
||||
- [甲方需求确认清单.md](requirements/甲方需求确认清单.md)：面向沈阳房建公寓段业务老师提炼的待确认分级清单（P0 核心 18 项、P1 细节 12 项、P2 规划 8 项）
|
||||
|
||||
---
|
||||
|
||||
### C. 开发人员与架构师路径
|
||||
|
||||
参与系统编码、功能扩展与架构审计的研发人员，请查阅：
|
||||
1. [handbook/03-system-architecture.md](handbook/03-system-architecture.md) —— **系统技术架构设计**（Spring Boot 2.5 + 若依增强单体、`ruoyi-train` 核心模块、Kingbase 兼容适配模式）。
|
||||
2. [handbook/04-data-model-overview.md](handbook/04-data-model-overview.md) —— **数据模型总览**（核心实体关系与关键表结构设计）。
|
||||
3. [handbook/06-api-and-permission-overview.md](handbook/06-api-and-permission-overview.md) —— **API 与权限体系速览**（核心操作端点、RBAC 菜单权限与专用业务 Action）。
|
||||
4. [handbook/08-deployment-and-release.md](handbook/08-deployment-and-release.md) —— **部署与运维手册**（本地快速启动与生产多环境部署要求）。
|
||||
5. [handbook/deployment/kingbase-jdbc-provisioning.md](handbook/deployment/kingbase-jdbc-provisioning.md) —— **Kingbase JDBC 8.6.0 依赖供应指南**。
|
||||
### 3. 📖 [docs/handbook/](handbook/01-project-overview.md) — 团队操作白皮书与全景指南
|
||||
面向人类可读的系统级白皮书，涵盖业务、技术与运维全链路：
|
||||
- [01-project-overview.md](handbook/01-project-overview.md)：系统建设背景、业务痛点与角色价值
|
||||
- [02-business-process.md](handbook/02-business-process.md)：核心业务闭环流程与状态机流转规则
|
||||
- [03-system-architecture.md](handbook/03-system-architecture.md)：系统分层架构、核心组件与技术选型
|
||||
- [04-data-model-overview.md](handbook/04-data-model-overview.md)：数据模型概念设计与关键实体关系
|
||||
- [05-module-guide.md](handbook/05-module-guide.md)：14 大业务功能模块使用与代码扩展指南
|
||||
- [06-api-and-permission-overview.md](handbook/06-api-and-permission-overview.md)：接口分类体系与 RBAC 权限矩阵
|
||||
- [07-testing-and-acceptance.md](handbook/07-testing-and-acceptance.md)：测试规范与自动化验证体系
|
||||
- [08-deployment-and-release.md](handbook/08-deployment-and-release.md)：共享试用环境部署拓扑与运维规范
|
||||
- [09-current-status.md](handbook/09-current-status.md)：团队级现状综合看板
|
||||
|
||||
---
|
||||
|
||||
### D. 测试与质量验收路径
|
||||
|
||||
负责功能验收、回归测试与质量审计的人员，请查阅：
|
||||
1. [reports/final-test-report.md](reports/final-test-report.md) —— **Final Candidate 自动化测试与场景集成最终报告**（154 单元测试 + 6 大场景全 PASS 证据）。
|
||||
2. [reports/browser-acceptance-report.md](reports/browser-acceptance-report.md) —— **端到端浏览器自动化验收报告**（真实环境验收通过：**PASS**，0 阻断，Swagger 连通）。
|
||||
3. [reports/release-notes.md](reports/release-notes.md) —— **发版说明与变更记录**。
|
||||
4. [_meta/core-business-test-matrix.md](_meta/core-business-test-matrix.md) —— **核心业务场景集成自动化测试矩阵**。
|
||||
### 4. 🔒 研发契约与开发规范 (Contracts & Development)
|
||||
技术人员与智能 Agent 研发的核心事实源（只读冻结）：
|
||||
- **[docs/api-v2/](api-v2/00_readme.md)**：RESTful API 契约总纲、Module A~D 接口规范、DTO/VO 字典与业务错误码
|
||||
- **[docs/database-v2/](database-v2/01_table_inventory.md)**：国产人大金仓 KingbaseES 物理表清单、索引约束设计与迁移说明
|
||||
- **[docs/development/](development/git-commit-convention.md)**：
|
||||
- [git-commit-convention.md](development/git-commit-convention.md)：项目 Git 提交中文格式规范
|
||||
- [dms-r3/](development/dms-r3/00_source_and_scope.md)：DMS 智能门禁适配器架构设计与 Token 策略
|
||||
- [rbac-r2/](development/rbac-r2/00_current_state.md)：多角色 RBAC、业务身份绑定与防 IDOR 越权设计
|
||||
|
||||
---
|
||||
|
||||
### E. Agent 与技术契约事实源（Contract Sources）
|
||||
|
||||
本目录下的底层契约目录为系统自动代码生成、契约测试和 Agent 审计的**最高技术事实源（Source of Truth）**，已正式冻结，保持原路径不移动：
|
||||
1. [api-v2/](api-v2/) —— **API V2 契约体系**：
|
||||
- `00_readme.md`：API 体系总览与 REST 规范
|
||||
- `01_api_design_principles.md` ~ `05_module_d_score_learning_statistics_api.md`：各业务域端点定义
|
||||
- `06_dto_vo_catalog.md`：DTO/VO 字段定义字典
|
||||
- `08_transaction_and_invariants.md`：强事务与 6 大跨表业务不变量
|
||||
- `10_permission_and_error_codes.md`：权限字符串与 40001~50001 业务错误码字典
|
||||
2. [database-v2/](database-v2/) —— **数据库 V2 物理迁移与表结构事实源**：
|
||||
- `01_table_inventory.md`：21 张物理表字段、约束、主外键最终定义
|
||||
- `05_execution_contract.md`：数据库物理迁移执行契约与验证门禁
|
||||
3. [issues-v1/](issues-v1/) —— **任务分解与验收条件**：
|
||||
- `02_p0_issue_backlog.md`：P0 核心任务与 AC 验收条件定义
|
||||
- `06_acceptance_matrix.md`：AC 验收标准对应自动化用例矩阵
|
||||
4. [development/](development/) —— 各 Issue 实施过程记录与验收报告。
|
||||
5. [_meta/documentation-audit.md](_meta/documentation-audit.md) —— D.0 文档现状审计与资产盘点报告。
|
||||
### 5. 🖥️ [docs/visual/](visual/index.html) — 数字化离线交付门户
|
||||
纯静态 HTML + CSS + JS 构建的交互式展示门户，浏览器直接双击打开，适合大屏展示：
|
||||
- [index.html](visual/index.html)：交付门户主页
|
||||
- [architecture.html](visual/architecture.html)：架构与技术栈
|
||||
- [business-flow.html](visual/business-flow.html)：全景业务状态机
|
||||
- [data-model.html](visual/data-model.html)：实体关系 (ER) 与表字典
|
||||
- [modules.html](visual/modules.html)：14 大模块导览
|
||||
- [testing.html](visual/testing.html)：质量与验证体系
|
||||
- [deployment.html](visual/deployment.html)：部署拓扑与 Delta 增量
|
||||
- [release-status.html](visual/release-status.html)：发版进度与门禁看板
|
||||
|
||||
---
|
||||
|
||||
### F. 历史过程资料归档（Historical Snapshots）
|
||||
|
||||
> ⚠️ **重要提示**：以下目录记录的是项目研发演进早期的阶段性快照或原始素材，**仅作为工程审计与技术溯源参考，不代表当前 Final Candidate 的代码与数据库现状**：
|
||||
* [codebase-audit/](codebase-audit/)：**Phase 0 历史代码审计快照**（基于历史 Commit `e12eda05`，记录了重构前旧单体结构与旧 14 张表实测状态，已被 Database V2 与 API V2 替代）。
|
||||
* [../doc/raw_materials/](../doc/raw_materials/)：早期甲供原始需求与数据表草案。
|
||||
* [../doc/archive/](../doc/archive/)：一期 PRD V0.9、早期决策与假设讨论稿。
|
||||
* [../doc/wxy_doc/](../doc/wxy_doc/)：早期技术原型与开发说明书草案。
|
||||
### 6. 📑 [docs/reports/](reports/README.md) — 质量验收与历史证据
|
||||
- **当前唯一终验报告**：[FINAL_PHASE1_20260917_101044/](reports/integrated-acceptance/FINAL_PHASE1_20260917_101044/README.md)（含 [执行总摘要](reports/integrated-acceptance/FINAL_PHASE1_20260917_101044/executive-summary.md)）
|
||||
- **过程性测试证据**：Round 1~3B 自动化测试日志、DMS 实测探针、Playwright 无头浏览器运行截图
|
||||
- **早期归档报告**：[archive/20260915/](reports/archive/20260915/)（已被终检报告全面覆盖的早期旧报告）
|
||||
Reference in new issue
Block a user