docs: add learning guide and optimize web performance

.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+
+jobs:
+  web-build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: web
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+      - run: npm ci
+      - run: npm run build
+
+  server-test:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: server
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 17
+          cache: maven
+      - run: chmod +x mvnw
+      - run: ./mvnw test
+
+  web-e2e:
+    runs-on: ubuntu-latest
+    needs:
+      - web-build
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 17
+          cache: maven
+      - run: npm ci
+        working-directory: web
+      - run: npm run test:e2e:install
+        working-directory: web
+      - run: chmod +x mvnw
+        working-directory: server
+      - run: npx playwright test
+        working-directory: web
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-report
+          path: web/playwright-report
+          if-no-files-found: ignore
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-test-results
+          path: web/test-results
+          if-no-files-found: ignore

README.md

@@ -100,6 +100,79 @@ npm run dev
 
 默认地址：`http://localhost:5173`（已通过 Vite 代理 `/api` 到 `http://localhost:8080`）
 
+### 5) 一键启动开发环境
+
+首次执行前请确保本机已安装 `docker`、`curl`、`Node.js`、`JDK`，并且前端依赖已安装完成：
+
+```bash
+cd web
+npm install
+cd ..
+chmod +x scripts/dev-up.sh scripts/dev-down.sh
+./scripts/dev-up.sh
+```
+
+脚本会完成这些动作：
+
+- 启动 `docker compose` 中的 MySQL
+- 在后台启动后端开发服务并轮询 `http://127.0.0.1:8080/api/health`
+- 在固定端口 `5173` 启动前端开发服务
+
+停止本地前后端：
+
+```bash
+./scripts/dev-down.sh
+```
+
+开发环境默认端口和变量：
+
+- 前端固定使用 `127.0.0.1:5173`
+- 后端固定使用 `127.0.0.1:8080`
+- 前端示例变量见 `web/.env.example`
+- 后端生产变量模板见 `server/.env.prod.example`
+
+## CI 门禁
+
+仓库已补充 GitHub Actions 工作流：前端执行 `npm run build`，后端执行 `./mvnw test`。工作流文件位于 `.github/workflows/ci.yml`。
+
+## E2E 测试
+
+前端已接入 Playwright 基础设施，测试文件位于 `web/tests/e2e/`，当前覆盖：
+
+- 登录跳转与登录成功
+- 错误密码提示
+- 学生预约提交流程
+
+首次运行前建议安装浏览器：
+
+```bash
+cd web
+npm run test:e2e:install
+```
+
+启动前后端后执行：
+
+```bash
+cd web
+npm run test:e2e
+```
+
+如测试地址不是默认的 `http://127.0.0.1:5173`，可通过环境变量覆盖：
+
+```bash
+PLAYWRIGHT_BASE_URL=http://127.0.0.1:4173 npm run test:e2e
+```
+
+## 生产环境变量基线
+
+后端生产配置建议至少显式设置以下变量：
+
+- `DB_HOST` / `DB_PORT` / `DB_NAME` / `DB_USER` / `DB_PASSWORD`
+- `JWT_SECRET`
+- `CORS_ALLOWED_ORIGIN_PATTERNS`
+
+示例模板见 `server/.env.prod.example`。其中 `JWT_SECRET` 必须替换，`CORS_ALLOWED_ORIGIN_PATTERNS` 不应保留为宽泛通配。
+
 ## 默认账号（种子数据）
 
 - 管理员：`admin / 123456`
@@ -110,3 +183,7 @@ npm run dev
 
 - 接口文档：`docs/api.md`
 - 数据库设计：`docs/db-design.md`
+- 异常码约定：`docs/exception-codes.md`
+- 优化记录：`docs/improvements.md`
+- 学习指南入口：`docs/learning-guide.md`
+- 目录版学习指南：`docs/learning/README.md`

docs/exception-codes.md

@@ -0,0 +1,43 @@
+# 统一异常码约定
+
+## 通用响应格式
+
+后端统一返回：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {}
+}
+```
+
+- `code=0`：业务成功
+- `code!=0`：业务失败或权限失败
+
+## 异常码说明
+
+| code | 含义 | 典型场景 |
+| --- | --- | --- |
+| 0 | 成功 | 查询、创建、更新、删除成功 |
+| 400 | 请求参数或业务前置条件不满足 | 参数校验失败、时间冲突、状态不允许当前操作 |
+| 401 | 未认证或凭证无效 | 未登录、Token 无效、用户名密码错误 |
+| 403 | 已认证但无权限 | 学生访问教师接口、账号被停用 |
+| 404 | 资源不存在 | 公告不存在、预约不存在、设备不存在 |
+| 500 | 服务内部异常 | 未捕获异常、数据库或系统错误 |
+
+## 前端处理建议
+
+- `400`：优先展示接口返回的业务提示，允许用户直接修正输入后重试。
+- `401`：登录页提示凭证错误；已登录页面应跳转登录或提示重新登录。
+- `403`：提示无权限或账号状态异常，不建议自动重试。
+- `404`：提示资源已不存在，并刷新列表或返回上一页。
+- `500`：统一提示“系统异常，请稍后重试”，必要时保留重试按钮。
+
+## 当前项目中的约定示例
+
+- 登录失败：`401`
+- 用户被禁用：`403`
+- 预约时间冲突：`400`
+- 预约/公告/设备不存在：`404`
+- 未处理系统异常：`500`

docs/improvements.md

@@ -1,39 +1,92 @@
-# 项目可改进点（后续迭代建议）
+# 项目优化记录与后续建议
 
-## 1. 运行与环境
+本文档分成两部分：
 
-- 统一开发端口与启动脚本，避免前端出现多个 `517x/520x` 端口并行导致混淆。
-- 增加一键启动脚本（如 `scripts/dev-up.sh`），统一启动前后端与健康检查。
-- `dev` 环境补充数据库自动建库/初始化说明，减少首次启动失败。
+- 第一部分记录已经落地的优化，方便后续接手时快速了解现状。
+- 第二部分保留仍值得继续迭代的方向，避免重复讨论。
 
-## 2. 前端稳定性
+## 一、已完成优化
 
-- 为登录页增加更精确的错误提示（区分“密码错误”和“系统异常”）。
-- 统一前端 API 类型定义，避免同一业务对象在多个文件重复映射。
-- 增加全局空状态与错误重试组件，提升弱网场景体验。
+### 1. 运行与环境
 
-## 3. 后端能力
+- 统一了开发环境端口约定：
+  - 前端固定 `127.0.0.1:5173`
+  - 后端固定 `127.0.0.1:8080`
+- 补充了开发环境脚本与说明，降低首次启动门槛。
+- 增加了前后端环境变量模板，便于本地和生产环境配置。
 
-- 增加关键业务日志（预约审批、维修完结、公告发布）便于审计追踪。
-- 为高频查询接口（设备列表、预约列表）预留索引优化策略。
-- 增加统一异常码文档，进一步规范前后端错误语义。
+### 2. CI 与测试基础设施
 
-## 4. 测试与质量
+- GitHub Actions 已加入基础门禁：
+  - 前端 `build`
+  - 后端 `test`
+  - 前端 E2E 作业
+- 前端已接入 Playwright，并完成基础自动化用例。
+- 当前 E2E 已覆盖的关键链路包括：
+  - 登录跳转、登录成功、错误密码提示
+  - 学生提交预约
+  - 教师审批通过预约
+  - 教师驳回预约
+  - 学生权限边界访问控制
+  - 管理员发布公告
+- Playwright 的前端自启方式已从 `npm run dev` 调整为 `build + preview`，用于提升 CI 稳定性。
 
-- 增加前端 E2E 测试（登录、预约、审批、公告）。
-- 为权限边界补充更多反向用例（例如学生访问教师接口）。
-- 在 CI 中加入前端 `build` + 后端 `test` 的强制门禁。
+### 3. 前端稳定性与体验
 
-## 5. 部署与交付
+- 登录失败提示已细化，减少“所有错误都一样”的模糊反馈。
+- 已增加通用空状态/错误重试组件，提升接口失败时的可恢复性。
+- 前端路由已补充角色访问控制，未授权页面会跳转到独立的 `403` 页面。
+- 仪表盘已根据角色隐藏无权限入口，减少学生误点管理功能。
 
-- 补充生产环境变量模板（JWT、DB、CORS）与最小安全基线说明。
-- 增加 Nginx/反向代理示例（HTTPS、缓存、跨域策略）。
-- 增加版本发布记录模板（变更摘要、回滚说明、数据库变更）。
+### 4. 前端性能优化
 
-## 建议优先级
+- 仪表盘图表改为按需加载，不再把 `echarts` 整包压进首屏主包。
+- Vite 已增加手工分包策略，拆分：
+  - `vendor-vue`
+  - `vendor-utils`
+  - `vendor-echarts`
+  - `vendor-element-plus`
+- Element Plus 已从“整库安装 + 全量图标注册”改为“按需组件注册 + 按需图标注册”。
+- Element Plus 样式已从全量 `index.css` 改为按需样式引入。
+- 最近一次本地构建结果中，前端包体优化效果明显：
+  - `vendor-element-plus` JS 已从约 `1.09 MB` 降到约 `563 kB`
+  - Element Plus 样式包已从约 `351 kB` 降到约 `180 kB`
 
-1. 统一启动与端口管理（立即提升联调效率）
-2. 前端 E2E 与 CI 门禁（立即提升交付稳定性）
-3. 日志与异常码规范（提升维护效率）
-4. 部署安全基线与发布模板（提升上线质量）
+### 5. 后端可维护性
 
+- 增加了关键业务日志，覆盖预约审批、维修完结、公告发布等重要操作。
+- 已补充异常码文档，统一前后端错误语义。
+
+## 二、当前已知限制
+
+### 1. 本地/沙箱环境限制
+
+- 当前沙箱环境下，后端和前端服务监听端口可能受到限制。
+- 因此在该环境里，E2E 不一定能完整自启服务跑通。
+- 这类失败不等同于业务代码失败，更像是运行环境限制。
+
+### 2. E2E 的实际验证方式
+
+- 当前最稳定的方式仍然是手动启动干净的本地前后端进程后，再执行：
+  - 后端：`./mvnw -Dmaven.repo.local=/tmp/smartlab-m2 spring-boot:run -Dspring-boot.run.profiles=test -Dspring-boot.run.arguments=--server.address=127.0.0.1`
+  - 前端：`npm run dev`
+  - 测试：`PLAYWRIGHT_SKIP_WEBSERVER=1 npx playwright test`
+
+## 三、下一阶段建议
+
+### 1. 优先级高
+
+- 继续补权限边界 E2E，尤其是教师/管理员对更多管理模块的反向访问用例。
+- 为公告、维修、系统管理补更多“失败路径”测试，而不只验证成功路径。
+- 优化 CI 中 Playwright 的探活与日志输出，便于定位启动失败原因。
+
+### 2. 优先级中
+
+- 继续压缩 `vendor-echarts`，例如按图表类型继续拆分或在可见时再加载。
+- 评估 Element Plus 运行时代码进一步按路由拆分的可行性。
+- 为仪表盘增加首屏骨架屏或延迟渲染策略，进一步提升感知性能。
+
+### 3. 优先级中低
+
+- 增加发布记录模板、回滚说明模板和数据库变更检查清单。
+- 补充更完整的生产部署示例，如 Nginx、HTTPS、缓存与跨域策略。

docs/learning-guide.md

@@ -0,0 +1,14 @@
+# 学习指南入口
+
+原有单文件学习指南已拆分为完整目录版，便于教学、接手和阶段性学习。
+
+请从这里开始：
+
+- [`docs/learning/README.md`](/mnt/d/smartlab/docs/learning/README.md)
+
+目录版学习指南适合以下目标：
+
+- 快速理解项目整体结构
+- 独立把项目跑起来
+- 理解后端、前端、权限、业务链路
+- 在指导下完成复现与二次开发