blp/railwaysystem
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
39f633528ce82e042efc729013eabeb256d65558
railwaysystem/docs/reports/documentation-audit-20260917.md
T

9.0 KiB
Raw Blame History

SYFJGYD学员管理系统 — 全量文档资产盘点与信息架构审计报告

审计分支：feat/cicd-pipeline（Commit: 73c8a68f） 审计时间：2026-09-17 执行原则：坚持客观事实，理清入口权威，消除歧义误导；本阶段不搞大规模文件破坏性搬迁，优先完成入口收敛与旧报告归档。

1. 核心指标与资产盘点概览

全工程文档资产及配套可视化、验收截图素材全量盘点指标如下：

========================================================================
                      文档资产全量审计核心指标卡
========================================================================
  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 全面阐述铁路职工培训痛点、四类核心角色价值、14 大业务模块与核心流转。
B. 当前系统状态 docs/current/01-current-status.md 最权威的一页纸现状速览。包含试用数据大盘、核心闭环结论与 DMS 精确状态。
C. 一期需求 docs/requirements/一期需求实现进度表.md 逐项核对代码与页面落地度、测试证据与分支边界，比静态 PRD 更加贴合真实交付。
D. 甲方待确认项 docs/requirements/甲方需求确认清单.md 分级整理 P0(核心阻塞 18 项)、P1(业务细节 12 项)、P2(二期规划 8 项) 业务确认表。
E. 系统架构 docs/handbook/03-system-architecture.md 详述 Spring Boot 2.5 + RuoYi-Vue + KingbaseES 分层架构、聚合边界及服务调用拓扑。
F. 数据库设计 docs/database-v2/01_table_inventory.md 完整记录 21 张真实物理业务表的字段语义、类型、索引及约束。
G. API docs/api-v2/00_readme.md 冻结的 REST API 契约总纲，统领 Module A~D 所有接口定义、DTO/VO 字段字典与业务错误码。
H. 部署/CI/CD docs/handbook/08-deployment-and-release.md 规范记录局域网共享试用环境 (192.168.139.230:8082) 的 Nginx 代理、隧道转发与发布增量 Delta。
I. 开发规范 docs/handbook/05-module-guide.md 详细指导如何基于 ruoyi-train 扩展代码、遵循业务不变量与事务设计。
J. Git规范 docs/development/git-commit-convention.md 明确全中文提交规范（<中文类型><可选范围>：<中文说明>）及合规禁令。
K. 测试说明 docs/handbook/07-testing-and-acceptance.md 涵盖 Maven 单元测试、契约用例、场景集成及 Playwright 浏览器自动化的完整执行体系。
L. 综合验收结果 docs/reports/integrated-acceptance/FINAL_PHASE1_20260917_101044/executive-summary.md 汇总全模块 331 项后端测试、三端无头浏览器 E2E 及数据完整性 0 孤儿的最终综合验收证明。
M. 共享试用发布状态 docs/current/03-shared-trial.md 评定系统试用条件为 READY_WITH_EXTERNAL_BLOCKERS，界定局域网教学试用准入范围。
N. DMS当前状态 docs/current/04-known-gaps.md 客观记录：平台鉴权通过、Token TTL 7200s、只读接口连通；因环境无资源，真实行级映射未验证，物理门锁判定外部阻塞。
O. 已知缺口 docs/current/04-known-gaps.md 实事求是界定 C03 成绩管理推进中、C05 学员画像为基础功能，杜绝浮夸。
P. Visual Docs入口 docs/visual/index.html 面向专家评审与业务老师的纯静态离线交互式交付门户（双击即可本地运行）。
Q. 历史资料入口 doc/README.md 统领甲方原始 Word 资料、早期草案与王杏月原型。

4. 报告中心分级与收口治理 (Reports Restructuring)

针对 docs/reports/ 下累积的 220+ 份报告与截图，按以下规则完成治理收口：

  1. 当前最终综合验收总结 (CURRENT_SUMMARY)：
  2. 历史验收过程证据 (HISTORICAL_EVIDENCE)：
    • 保留 INT_QA_R1 ~ INT_QA_R3B、dms-r3 实测探针与 Git 提交历史规范化记录，作为合规审计备查底稿；
  3. 早期旧报告下沉归档 (ARCHIVED)：
    • 将顶层 4 篇旧报告移至 archive/20260915/，避免读者误读早期的 154 测试指标；
  4. 统一导航建立：

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. 清理已完全合并或淘汰的临时中间工作底稿。
Reference in new issue View Git Blame Copy Permalink