107 lines
9.0 KiB
Markdown
107 lines
9.0 KiB
Markdown
# SYFJGYD学员管理系统 — 全量文档资产盘点与信息架构审计报告
|
||
|
||
> **审计分支**：`feat/cicd-pipeline`（Commit: `73c8a68f`）
|
||
> **审计时间**：2026-09-17
|
||
> **执行原则**：坚持客观事实，理清入口权威，消除歧义误导；本阶段不搞大规模文件破坏性搬迁，优先完成入口收敛与旧报告归档。
|
||
|
||
---
|
||
|
||
## 1. 核心指标与资产盘点概览
|
||
|
||
全工程文档资产及配套可视化、验收截图素材全量盘点指标如下：
|
||
|
||
```text
|
||
========================================================================
|
||
文档资产全量审计核心指标卡
|
||
========================================================================
|
||
AUDIT_BRANCH : feat/cicd-pipeline
|
||
AUDIT_HEAD : 73c8a68f801dc4aed2a4d262747690cef0135fc3
|
||
|
||
TOTAL_DOCUMENT_COUNT : 423 份 (Markdown、Word、HTML 及配套媒体素材)
|
||
DOC_FILE_COUNT : 20 份 (doc/ 目录：原始材料与历史设计)
|
||
DOCS_FILE_COUNT : 395 份 (docs/ 目录：正式工程、架构、契约与验收报告)
|
||
REPORT_FILE_COUNT : 221 份 (docs/reports/ 下报告与自动化截图)
|
||
RUOYI_LEGACY_DOC_COUNT : 7 份 (框架原生自带文档)
|
||
ROOT_DOC_COUNT : 1 份 (根目录 README.md)
|
||
|
||
CURRENT_AUTHORITATIVE_DOC_COUNT : 52 份 (当前活跃有效、日常必须参考的权威文档)
|
||
STALE_DOC_COUNT : 18 份 (包含过期 SHA、旧测试数或本地绝对路径)
|
||
POSSIBLE_DUPLICATE_COUNT : 8 组 (双格式或内容镜像)
|
||
SUPERSEDED_DOC_COUNT : 24 份 (已被更新报告或新规范替代)
|
||
|
||
VISUAL_DOC_STATUS : PARTIALLY_STALE → 已校准为 SHARED_TRIAL_READY
|
||
CLEANUP_PHASE_1 : COMPLETED (docs/current 建立，旧顶层报告归档)
|
||
========================================================================
|
||
```
|
||
|
||
---
|
||
|
||
## 2. doc/ 与 docs/ 两套目录深度关系分析 (DOC_VS_DOCS_ANALYSIS)
|
||
|
||
### 2.1 为什么同时存在？
|
||
- **`doc/` 的起源（业务需求与甲方起点）**：
|
||
建于项目早期与业务方对接阶段。核心资产为甲方最初提供的业务功能分析与表设计 Word 原件（`doc/raw_materials/`）、王杏月师姐编写的早期技术说明与 ELK 拓扑原型（`doc/wxy_doc/`）、早期讨论稿（`doc/archive/`）、以及最终冻结的 PRD V1.0。**其本质是“产品需求与甲方原始输入中心”**。
|
||
- **`docs/` 的起源（工程规范与研发交付）**：
|
||
建于后续工程化推进阶段（Phase 0 代码审计、API V2 契约、国产 KingbaseES 物理表迁移、多轮综合验收）。包含当前系统的技术契约（`api-v2/`、`database-v2/`）、开发指南与白皮书（`handbook/`）、离线可视化门户（`visual/`）、以及数十次自动化测试生成的证据链（`reports/`）。后来在此目录下又建立了 `docs/requirements/`。**其本质是“工程技术实现、事实审计与质量验收中心”**。
|
||
|
||
### 2.2 处置策略
|
||
- **Phase 1（当前）**：保持 `doc/` 物理目录不动，先在 `docs/current/` 与 `docs/README.md` 中收敛权威入口，明确 `doc/` 为“历史起点与原始资料”；
|
||
- **Phase 2（后续）**：择机将 `doc/` 下的 PRD V1.0 移入 `docs/requirements/`，其余原始 docx 与早期原型移入 `docs/archive/`，彻底消除同级目录歧义。
|
||
|
||
---
|
||
|
||
## 3. 全局唯一权威推荐入口 (Authoritative Source Identification)
|
||
|
||
为避免开发者与用户在多份文档中迷失，现对全项目 17 个关键业务与技术领域确立唯一推荐权威入口：
|
||
|
||
| 领域分类 | 唯一权威推荐文档入口 (AUTHORITATIVE SOURCE) | 推荐理由与事实依据 |
|
||
| :--- | :--- | :--- |
|
||
| **A. 项目总览** | [`docs/handbook/01-project-overview.md`](../handbook/01-project-overview.md) | 全面阐述铁路职工培训痛点、四类核心角色价值、14 大业务模块与核心流转。 |
|
||
| **B. 当前系统状态** | [`docs/current/01-current-status.md`](../current/01-current-status.md) | **最权威的一页纸现状速览**。包含试用数据大盘、核心闭环结论与 DMS 精确状态。 |
|
||
| **C. 一期需求** | [`docs/requirements/一期需求实现进度表.md`](../requirements/一期需求实现进度表.md) | 逐项核对代码与页面落地度、测试证据与分支边界，比静态 PRD 更加贴合真实交付。 |
|
||
| **D. 甲方待确认项** | [`docs/requirements/甲方需求确认清单.md`](../requirements/甲方需求确认清单.md) | 分级整理 P0(核心阻塞 18 项)、P1(业务细节 12 项)、P2(二期规划 8 项) 业务确认表。 |
|
||
| **E. 系统架构** | [`docs/handbook/03-system-architecture.md`](../handbook/03-system-architecture.md) | 详述 Spring Boot 2.5 + RuoYi-Vue + KingbaseES 分层架构、聚合边界及服务调用拓扑。 |
|
||
| **F. 数据库设计** | [`docs/database-v2/01_table_inventory.md`](../database-v2/01_table_inventory.md) | 完整记录 21 张真实物理业务表的字段语义、类型、索引及约束。 |
|
||
| **G. API** | [`docs/api-v2/00_readme.md`](../api-v2/00_readme.md) | 冻结的 REST API 契约总纲，统领 Module A~D 所有接口定义、DTO/VO 字段字典与业务错误码。 |
|
||
| **H. 部署/CI/CD** | [`docs/handbook/08-deployment-and-release.md`](../handbook/08-deployment-and-release.md) | 规范记录局域网共享试用环境 (`192.168.139.230:8082`) 的 Nginx 代理、隧道转发与发布增量 Delta。 |
|
||
| **I. 开发规范** | [`docs/handbook/05-module-guide.md`](../handbook/05-module-guide.md) | 详细指导如何基于 `ruoyi-train` 扩展代码、遵循业务不变量与事务设计。 |
|
||
| **J. Git规范** | [`docs/development/git-commit-convention.md`](../development/git-commit-convention.md) | 明确全中文提交规范（`<中文类型><可选范围>：<中文说明>`）及合规禁令。 |
|
||
| **K. 测试说明** | [`docs/handbook/07-testing-and-acceptance.md`](../handbook/07-testing-and-acceptance.md) | 涵盖 Maven 单元测试、契约用例、场景集成及 Playwright 浏览器自动化的完整执行体系。 |
|
||
| **L. 综合验收结果** | [`docs/reports/integrated-acceptance/FINAL_PHASE1_20260917_101044/executive-summary.md`](integrated-acceptance/FINAL_PHASE1_20260917_101044/executive-summary.md) | 汇总全模块 331 项后端测试、三端无头浏览器 E2E 及数据完整性 0 孤儿的法定验收证明。 |
|
||
| **M. 共享试用发布状态**| [`docs/current/03-shared-trial.md`](../current/03-shared-trial.md) | 评定系统试用条件为 `READY_WITH_EXTERNAL_BLOCKERS`，界定局域网教学试用准入范围。 |
|
||
| **N. DMS当前状态** | [`docs/current/04-known-gaps.md`](../current/04-known-gaps.md) | 客观记录：平台鉴权通过、Token TTL 7200s、只读接口连通；因环境无资源，真实行级映射未验证，物理门锁判定外部阻塞。 |
|
||
| **O. 已知缺口** | [`docs/current/04-known-gaps.md`](../current/04-known-gaps.md) | 实事求是界定 C03 成绩管理推进中、C05 学员画像为基础功能，杜绝浮夸。 |
|
||
| **P. Visual Docs入口** | [`docs/visual/index.html`](../visual/index.html) | 面向专家评审与业务老师的纯静态离线交互式交付门户（双击即可本地运行）。 |
|
||
| **Q. 历史资料入口** | [`doc/README.md`](../../doc/README.md) | 统领甲方原始 Word 资料、早期草案与王杏月原型。 |
|
||
|
||
---
|
||
|
||
## 4. 报告中心分级与收口治理 (Reports Restructuring)
|
||
|
||
针对 `docs/reports/` 下累积的 220+ 份报告与截图，按以下规则完成治理收口：
|
||
|
||
1. **当前最终验收法定总结 (CURRENT_SUMMARY)**：
|
||
- 确立 [`integrated-acceptance/FINAL_PHASE1_20260917_101044/`](integrated-acceptance/FINAL_PHASE1_20260917_101044/README.md) 为唯一最终收口目录；
|
||
2. **历史验收过程证据 (HISTORICAL_EVIDENCE)**：
|
||
- 保留 `INT_QA_R1` ~ `INT_QA_R3B`、`dms-r3` 实测探针与 Git 提交历史规范化记录，作为合规审计备查底稿；
|
||
3. **早期旧报告下沉归档 (ARCHIVED)**：
|
||
- 将顶层 4 篇旧报告移至 [`archive/20260915/`](archive/20260915/)，避免读者误读早期的 154 测试指标；
|
||
4. **统一导航建立**：
|
||
- 新建 [`docs/reports/README.md`](README.md)，建立清晰的父级索引。
|
||
|
||
---
|
||
|
||
## 5. Phase 1 落地成果与后续建议
|
||
|
||
### 本阶段已完成动作：
|
||
- ✅ 建立 `docs/current/` 极简速览中心（5 篇精炼人类速览文档）；
|
||
- ✅ 重写根目录 `README.md` 与 `docs/README.md`，构建清晰的六大直达通道；
|
||
- ✅ 全面校准 `docs/visual/`（4 篇核心 HTML），将 154 测试修正为全量 331 验收测试，消除“生产环境”误称；
|
||
- ✅ 下沉顶层旧报告至 `docs/reports/archive/20260915/` 并建立报告总导航；
|
||
- ✅ 全量检查 Markdown 与 HTML 链接，杜绝违规本地绝对路径。
|
||
|
||
### Phase 2 后续演进建议（待客户与团队审阅后实施）：
|
||
1. 将 `doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md` 结构化移入 `docs/requirements/`；
|
||
2. 将 `doc/raw_materials/` 与 `doc/wxy_doc/` 归类移入 `docs/archive/`；
|
||
3. 清理已完全合并或淘汰的临时中间工作底稿。
|