# 甲方试用前全系统缺陷清扫总结报告 (Pre-Customer Stabilization Sweep)

> **报告版本**：1.0.0
> **实施分支**：`fix/pre-customer-stabilization-20260920` (基于 `origin/feat/cicd-pipeline` 最新提交 `215107b1`)
> **基准环境**：共享试用环境 (`http://192.168.139.230:8082`) 与本地镜像构建环境
> **巡检时间**：2026-09-20
> **清扫判定**：`PRE_CUSTOMER_STABILIZATION = PASS`

---

## 一、工作背景与任务目标

在系统正式交付甲方试用前，人工核查时发现明显前端缺陷：
> 左侧导航菜单中，“首页”和“人员管理”之间存在一个只有展开箭头、没有模块名称的空白菜单项。

这暴露出此前以业务流程、后端契约与 RBAC 为主的验收遗漏了肉眼可见的 UI/UX 问题（空标题、空折叠菜单、未转义字典码、未处理布局异常、组件运行时空指针报错等）。

本次清扫任务严格遵循以下原则闭环推进：
1. **真实用户视角全面巡检**：完整覆盖 Admin（管理端 29 个页面）、Teacher（教师工作台）、Student（学员中心）三类角色。
2. **根因定位并修复 BUG**：逐项复现问题根因，做出最小优雅修复与回归验证，严禁借机新增未确认的业务需求。
3. **数据与硬件安全红线**：
   - 共享试用数据库 `training` 保持只读/业务只写，未执行任何清库或重置 (`DATA_CLEARED = NO`)。
   - 门禁硬件保持未验证/无真实下发 (`DMS_REAL_MUTATION = NO`)。
4. **验证与构建全绿**：前端构建 `npm run build:prod` 成功、后端 331 项 Surefire 单元/契约测试全部通过、本地及浏览器端实测验证通过。

---

## 二、关键指标汇总

| 指标项 | 结果 / 数值 | 状态 | 说明 |
| :--- | :--- | :---: | :--- |
| **BLANK_MENU_COUNT** | **0** | **PASS** | 修复前为 1（首页与人员管理间存在空白折叠箭头），修复后三端全部为 0 |
| **BLANK_MENU_ROOT_CAUSE** | `build_ui/src/router/index.js` 中 `/train` 路由置于 `constantRoutes` 且缺少 `hidden: true` 与 `meta.title` | **CONFIRMED** | 导致 `SidebarItem` 识别为包含 2 个子项的父菜单但标题为空插槽，且导致门禁授权对学员/教师产生权限泄漏 |
| **BLANK_MENU_FIX** | 1. 在 `router/index.js` 为 `/train` 增加 `hidden: true`<br>2. 增强 `SidebarItem.vue` 模板与方法，增加 `isMenuVisible` 与 `hasShowingChildren`，杜绝任何无可见子项的空目录或无标题菜单项渲染 | **VERIFIED** | 无论静态路由或后端动态路由，均具备自我防御能力 |
| **ADMIN_MENU_PAGE_COUNT** | **29** | **PASS** | 覆盖人员管理、教学设施、课程管理、自主学习、统计分析、系统工具、系统管理、日志管理全部 29 个可导航功能模块 |
| **TEACHER_ROLE_CHECK** | **PASS** | **PASS** | 教师侧边栏无空白项；工作台开班/结训时间正常格式化；培训班状态“未开班”翻译正常（非“未知”）；名册与课表考勤正常 |
| **STUDENT_ROLE_CHECK** | **PASS** | **PASS** | 学员侧边栏无空白项；个人中心性别正确转义为“女”（非“1”）；我的培训、日程课表、打卡考勤、学员画像均展示完好 |
| **USER_RESET_EXCEPTION** | **FIXED** | **PASS** | 修复了用户管理页面部门树注释后点击“重置”抛出 `TypeError: Cannot read properties of undefined (reading 'setCurrentKey')` 的缺陷，并将栅格修正为 24 消除右侧异常空白 |
| **BACKEND_TESTS_RUN** | **331** | **PASS** | 331 项测试全部通过，Failures: 0, Errors: 0, Skipped: 0（统计自全工程全部 Surefire TEST-*.xml） |
| **FRONTEND_BUILD** | **PASS** | **PASS** | `npm run build:prod` 产物 `dist/` 构建成功，ESLint 零错误 |
| **BUG_TOTAL_FOUND** | **6** | **CLOSED** | 5 项已彻底修复并验证，1 项头像 404 为非阻塞静态容错处理 |
| **PRE_CUSTOMER_STABILIZATION** | **PASS** | **READY** | 系统已达到交付甲方试用之稳定状态 |

---

## 三、报告目录索引

- [缺陷清单 (Bug Inventory)](./bug-inventory.md)
- [浏览器三端巡检覆盖详情 (Browser Coverage)](./browser-coverage.md)
- [已修复缺陷与技术方案 (Fixed Issues)](./fixed-issues.md)
- [已知非阻塞与试用注意事项 (Known Non-blocking Items)](./known-nonblocking-items.md)