# 调试排错

<cite>
**本文引用的文件**
- [FpsMonitor.vue](file://fms-vue/src/components/FpsMonitor.vue)
- [application.yaml](file://fms-api/src/main/resources/application.yaml)
- [FmsApiApplication.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java)
- [measure.mjs](file://.fps-probe/measure.mjs)
- [debug-edit.mjs](file://.fps-probe/debug-edit.mjs)
- [debug-login.mjs](file://.playwright-cli/debug-login.mjs)
- [inspect-vue-root.mjs](file://.playwright-cli/inspect-vue-root.mjs)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能注意事项](#性能注意事项)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本指南面向 FMS 项目的开发与测试人员，提供前后端联调、前端与后端调试方法、常见问题定位、性能优化与瓶颈定位、以及基于 Playwright 的自动化脚本使用建议。内容结合项目内已有的 FPS 监控组件、Playwright 探针脚本、API 配置与启动入口，帮助快速定位网络、数据库、权限验证等问题，并给出可操作的步骤与可视化流程图。

## 项目结构
FMS 包含前端 Vue 应用、后端 Spring Boot API、以及用于性能测量与页面交互的 Playwright 脚本集：
- 前端（fms-vue）：提供 UI 与 FPS 监控组件，便于在浏览器中观察渲染性能。
- 后端（fms-api）：Spring Boot 服务，提供数据接口与鉴权能力，配置文件集中管理端口、上下文路径、数据库连接池等。
- 探针与脚本（.fps-probe、.playwright-cli）：通过 Playwright 驱动浏览器进行滚动、编辑、登录等场景的性能测量与状态检查。

```mermaid
graph TB
subgraph "前端"
FE["Vue 应用<br/>含 FPS 监控组件"]
end
subgraph "后端"
BE["Spring Boot API<br/>端口 8088 /api"]
end
subgraph "自动化与探针"
PW["Playwright 脚本<br/>测量/调试/巡检"]
end
FE --> BE
PW --> FE
PW --> BE
```

**图示来源**
- [FpsMonitor.vue:1-290](file://fms-vue/src/components/FpsMonitor.vue#L1-L290)
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [measure.mjs:1-218](file://.fps-probe/measure.mjs#L1-L218)

**章节来源**
- [FpsMonitor.vue:1-290](file://fms-vue/src/components/FpsMonitor.vue#L1-L290)
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [measure.mjs:1-218](file://.fps-probe/measure.mjs#L1-L218)

## 核心组件
- 前端 FPS 监控组件：以 requestAnimationFrame 采样当前帧率、平均帧率与最低帧率，并提供历史柱状图与拖拽复位功能，适合在开发阶段直观观察页面卡顿。
- 后端启动与配置：Spring Boot 应用入口初始化雪花 ID 生成器；application.yaml 定义服务端口、上下文路径、JWT 密钥、数据库连接池参数与文件存储策略。
- Playwright 探针脚本：
  - measure.mjs：在真实表格容器上执行滚动、隐藏绘制等场景，统计 FPS、帧间隔、渲染行数与编辑器数量。
  - debug-edit.mjs：注入登录态后进入表格页，定位单元格并模拟点击，输出点击命中元素与编辑器挂载情况。
  - debug-login.mjs：注入会话到登录页，跳转路由并截图，辅助排查路由与鉴权流程。
  - inspect-vue-root.mjs：注入会话并拦截 API 返回，检查 Vue 根实例与特定组件实例属性，便于定位组件状态问题。

**章节来源**
- [FpsMonitor.vue:1-290](file://fms-vue/src/components/FpsMonitor.vue#L1-L290)
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [measure.mjs:1-218](file://.fps-probe/measure.mjs#L1-L218)
- [debug-edit.mjs:1-97](file://.fps-probe/debug-edit.mjs#L1-L97)
- [debug-login.mjs:1-48](file://.playwright-cli/debug-login.mjs#L1-L48)
- [inspect-vue-root.mjs:1-60](file://.playwright-cli/inspect-vue-root.mjs#L1-L60)

## 架构总览
下图展示前端、后端与自动化脚本之间的交互关系，包括登录态注入、API 请求、表格渲染与性能测量。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant PW as "Playwright 脚本"
participant FE as "Vue 前端"
participant BE as "Spring Boot API"
participant DB as "数据库"
Dev->>PW : 运行测量/调试脚本
PW->>FE : 打开页面并注入登录态
FE->>BE : 发起数据加载/分页请求
BE->>DB : 查询业务数据
DB-->>BE : 返回数据集
BE-->>FE : 返回 JSON 响应
FE->>FE : 渲染表格/编辑器
FE->>FE : FPS 监控采样
PW->>FE : 执行滚动/点击/截图
PW-->>Dev : 输出 FPS/帧间隔/状态
```

**图示来源**
- [measure.mjs:23-124](file://.fps-probe/measure.mjs#L23-L124)
- [debug-login.mjs:10-47](file://.playwright-cli/debug-login.mjs#L10-L47)
- [inspect-vue-root.mjs:14-35](file://.playwright-cli/inspect-vue-root.mjs#L14-L35)
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)

## 详细组件分析

### 前端 FPS 监控组件
该组件通过高频 rAF 循环统计当前 FPS、平均值与最小值，并以柱状图展示历史趋势。支持拖拽移动与重置统计，避免后台暂停导致均值失真。

```mermaid
flowchart TD
Start(["组件挂载"]) --> Init["初始化采样窗口"]
Init --> RAF["requestAnimationFrame 循环"]
RAF --> Tick{"达到采样间隔?"}
Tick --> |否| RAF
Tick --> |是| Calc["计算当前/平均/最低 FPS"]
Calc --> Update["更新历史柱状图"]
Update --> RAF
RAF --> Visibility{"页面可见性变化?"}
Visibility --> |切回前台| ResetWin["重置采样窗口"]
Visibility --> |保持后台| RAF
```

**图示来源**
- [FpsMonitor.vue:36-75](file://fms-vue/src/components/FpsMonitor.vue#L36-L75)
- [FpsMonitor.vue:77-95](file://fms-vue/src/components/FpsMonitor.vue#L77-L95)
- [FpsMonitor.vue:136-146](file://fms-vue/src/components/FpsMonitor.vue#L136-L146)

**章节来源**
- [FpsMonitor.vue:1-290](file://fms-vue/src/components/FpsMonitor.vue#L1-L290)

### 后端启动与配置
后端启动时设置雪花 ID 生成器选项，并通过 application.yaml 暴露服务端口与上下文路径，同时配置 JWT 与数据库连接池参数。

```mermaid
classDiagram
class FmsApiApplication {
+main(args)
}
class Config {
+server.port
+server.servlet.context-path
+spring.application.name
+fms.auth.jwt-secret
+fms.database.pool.*
}
FmsApiApplication --> Config : "读取配置"
```

**图示来源**
- [FmsApiApplication.java:13-18](file://fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java#L13-L18)
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)

**章节来源**
- [FmsApiApplication.java:1-22](file://fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java#L1-L22)
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)

### Playwright 性能测量脚本
脚本在表格容器中执行滚动或编辑场景，统计 FPS、帧间隔、渲染行数与编辑器数量，支持多轮测量与汇总。

```mermaid
sequenceDiagram
participant PW as "measure.mjs"
participant Page as "浏览器页面"
participant Table as ".fms-table"
PW->>Page : 打开页面并等待表格就绪
PW->>Table : 选择滚动容器
loop 每帧
PW->>Table : 滚动 scrollTop += step
PW->>Page : 记录帧间隔与计数
end
PW-->>PW : 计算 FPS/avgFrame/minGap/maxGap
PW-->>PW : 输出渲染行数/编辑器数/展示格数
```

**图示来源**
- [measure.mjs:23-124](file://.fps-probe/measure.mjs#L23-L124)
- [measure.mjs:168-215](file://.fps-probe/measure.mjs#L168-L215)

**章节来源**
- [measure.mjs:1-218](file://.fps-probe/measure.mjs#L1-L218)

### Playwright 登录与路由调试脚本
脚本注入登录态到 sessionStorage，导航至目标路由并截图，便于验证鉴权与路由跳转逻辑。

```mermaid
sequenceDiagram
participant PW as "debug-login.mjs"
participant Page as "浏览器页面"
PW->>Page : 打开登录页
PW->>Page : 注入 fms-login 会话
PW->>Page : 跳转到 /file-demo
PW->>Page : 等待 DOM 稳定
PW-->>PW : 截图并输出树节点信息
```

**图示来源**
- [debug-login.mjs:10-47](file://.playwright-cli/debug-login.mjs#L10-L47)

**章节来源**
- [debug-login.mjs:1-48](file://.playwright-cli/debug-login.mjs#L1-L48)

### Playwright Vue 根实例检查脚本
脚本注入会话并拦截 API 返回，检查 Vue 根实例与特定组件实例属性，辅助定位组件状态与数据绑定问题。

```mermaid
sequenceDiagram
participant PW as "inspect-vue-root.mjs"
participant Page as "浏览器页面"
PW->>Page : 添加 initScript 注入会话
PW->>Page : 拦截 /api/** 请求并返回模拟数据
PW->>Page : 打开 /file-demo
PW->>Page : 评估 #app 与 __vue_app__ 属性
PW-->>PW : 输出根实例类型与 Splitter 实例信息
```

**图示来源**
- [inspect-vue-root.mjs:10-35](file://.playwright-cli/inspect-vue-root.mjs#L10-L35)
- [inspect-vue-root.mjs:38-59](file://.playwright-cli/inspect-vue-root.mjs#L38-L59)

**章节来源**
- [inspect-vue-root.mjs:1-60](file://.playwright-cli/inspect-vue-root.mjs#L1-L60)

## 依赖关系分析
- 前端依赖 Vue 运行时与组件库，FPS 监控组件依赖 requestAnimationFrame 与浏览器事件。
- 后端依赖 Spring Boot、数据库连接池与 JWT 鉴权；配置集中在 application.yaml。
- Playwright 脚本依赖 chromium 内核，通过注入会话与拦截 API 实现无头环境下的调试与测量。

```mermaid
graph LR
FE["Vue 前端"] --> |"HTTP /api/*"| BE["Spring Boot API"]
BE --> |"JDBC/连接池"| DB["数据库"]
PW["Playwright 脚本"] --> |"控制浏览器"| FE
PW --> |"可选拦截/注入"| BE
```

**图示来源**
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [measure.mjs:1-218](file://.fps-probe/measure.mjs#L1-L218)
- [debug-login.mjs:1-48](file://.playwright-cli/debug-login.mjs#L1-L48)
- [inspect-vue-root.mjs:1-60](file://.playwright-cli/inspect-vue-root.mjs#L1-L60)

**章节来源**
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [measure.mjs:1-218](file://.fps-probe/measure.mjs#L1-L218)
- [debug-login.mjs:1-48](file://.playwright-cli/debug-login.mjs#L1-L48)
- [inspect-vue-root.mjs:1-60](file://.playwright-cli/inspect-vue-root.mjs#L1-L60)

## 性能注意事项
- 前端 FPS 监控：
  - 使用内置 FPS 监控组件观察当前/平均/最低帧率与历史趋势，拖拽位置避免遮挡操作区。
  - 关注低帧率时段对应的用户操作（如滚动、编辑），并结合表格渲染行数与编辑器数量定位热点。
- 后端性能：
  - 调整数据库连接池参数（初始大小、最大活跃数、空闲检测等）以匹配负载。
  - 开启日志与慢查询追踪，结合接口耗时与数据库执行计划定位瓶颈。
- 自动化测量：
  - 使用 measure.mjs 在不同场景（静止、滚动、隐藏绘制、编辑中滚动）下采集 FPS 与帧间隔，识别渲染与 JS 开销。
  - 通过多轮测量与页面重载减少状态污染，确保结果可比性。

[本节为通用指导，不直接分析具体文件]

## 故障排查指南

### 网络连接问题
- 现象：前端无法加载数据或报跨域错误。
- 排查步骤：
  - 确认后端服务端口与上下文路径（application.yaml 中的 server.port 与 context-path）。
  - 使用 Playwright 脚本打开页面并检查控制台错误与网络面板。
  - 在 inspect-vue-root.mjs 中拦截 /api/** 请求，验证返回结构与状态码。
- 参考脚本与配置：
  - [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
  - [inspect-vue-root.mjs:14-35](file://.playwright-cli/inspect-vue-root.mjs#L14-L35)

**章节来源**
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [inspect-vue-root.mjs:1-60](file://.playwright-cli/inspect-vue-root.mjs#L1-L60)

### 数据库连接问题
- 现象：接口返回错误或数据为空。
- 排查步骤：
  - 检查 application.yaml 中数据库连接池配置（initial-size、max-active、validation-query 等）。
  - 启动后端并查看日志，确认连接池初始化成功。
  - 使用简单查询验证数据库连通性。
- 参考配置：
  - [application.yaml:10-26](file://fms-api/src/main/resources/application.yaml#L10-L26)

**章节来源**
- [application.yaml:10-26](file://fms-api/src/main/resources/application.yaml#L10-L26)

### 权限验证问题
- 现象：登录后仍无法访问受保护页面或数据。
- 排查步骤：
  - 使用 debug-login.mjs 注入 fms-login 会话并跳转目标路由，验证路由守卫与权限校验。
  - 检查 sessionStorage 与 localStorage 中的键值是否正确设置。
  - 在后端检查 JWT 密钥与过期时间配置。
- 参考脚本与配置：
  - [debug-login.mjs:10-47](file://.playwright-cli/debug-login.mjs#L10-L47)
  - [application.yaml:10-13](file://fms-api/src/main/resources/application.yaml#L10-L13)

**章节来源**
- [debug-login.mjs:1-48](file://.playwright-cli/debug-login.mjs#L1-L48)
- [application.yaml:10-13](file://fms-api/src/main/resources/application.yaml#L10-L13)

### 表格滚动与编辑卡顿
- 现象：滚动或编辑时 FPS 下降明显。
- 排查步骤：
  - 使用 FPS 监控组件观察卡顿时段。
  - 使用 measure.mjs 在“滚动”和“编辑中滚动”场景下采集 FPS、帧间隔与渲染行数。
  - 使用 debug-edit.mjs 定位点击命中元素与编辑器挂载情况，确认是否出现多余重绘。
- 参考脚本：
  - [FpsMonitor.vue:36-75](file://fms-vue/src/components/FpsMonitor.vue#L36-L75)
  - [measure.mjs:23-124](file://.fps-probe/measure.mjs#L23-L124)
  - [debug-edit.mjs:31-93](file://.fps-probe/debug-edit.mjs#L31-L93)

**章节来源**
- [FpsMonitor.vue:1-290](file://fms-vue/src/components/FpsMonitor.vue#L1-L290)
- [measure.mjs:1-218](file://.fps-probe/measure.mjs#L1-L218)
- [debug-edit.mjs:1-97](file://.fps-probe/debug-edit.mjs#L1-L97)

### 内存泄漏检测
- 现象：长时间使用后页面变慢或崩溃。
- 排查步骤：
  - 在浏览器性能面板录制内存快照，对比不同时间点的使用量。
  - 使用 Playwright 脚本重复操作（滚动/编辑）并截图，观察内存增长。
  - 检查是否有未清理的事件监听器或定时器。
- 参考工具：
  - 浏览器开发者工具（内存面板）
  - Playwright 脚本（可复用 measure.mjs 的场景循环）

[本节为通用指导，不直接分析具体文件]

### 错误日志分析与诊断流程
- 前端：
  - 打开控制台查看报错堆栈与网络请求失败原因。
  - 使用 inspect-vue-root.mjs 拦截 API 并打印请求/响应，定位数据格式问题。
- 后端：
  - 查看启动日志与异常堆栈，确认服务端口与上下文路径。
  - 检查数据库连接池与 JWT 配置，必要时调整超时与重试策略。
- 参考：
  - [inspect-vue-root.mjs:14-35](file://.playwright-cli/inspect-vue-root.mjs#L14-L35)
  - [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)

**章节来源**
- [inspect-vue-root.mjs:1-60](file://.playwright-cli/inspect-vue-root.mjs#L1-L60)
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)

## 结论
通过内置 FPS 监控组件与 Playwright 探针脚本，FMS 项目提供了完善的前端性能观测与自动化调试能力。结合后端配置与启动入口，可以快速定位网络、数据库与权限验证问题。建议在开发阶段持续使用 FPS 监控与自动化测量，结合日志与内存分析，形成闭环的性能优化与故障排查流程。

[本节为总结，不直接分析具体文件]

## 附录

### 常用调试命令与步骤
- 启动后端服务：
  - 检查 application.yaml 中的端口与上下文路径，确保服务可用。
  - 参考启动入口类与配置扫描注解。
- 运行前端 FPS 监控：
  - 在页面中启用 FPS 监控组件，观察实时帧率与历史趋势。
- 执行 Playwright 测量：
  - 使用 measure.mjs 在指定场景下采集 FPS 与帧间隔。
  - 使用 debug-edit.mjs 验证表格编辑与点击命中。
  - 使用 debug-login.mjs 注入会话并截图验证路由。
  - 使用 inspect-vue-root.mjs 检查 Vue 根实例与组件状态。

**章节来源**
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [FpsMonitor.vue:1-290](file://fms-vue/src/components/FpsMonitor.vue#L1-L290)
- [measure.mjs:1-218](file://.fps-probe/measure.mjs#L1-L218)
- [debug-edit.mjs:1-97](file://.fps-probe/debug-edit.mjs#L1-L97)
- [debug-login.mjs:1-48](file://.playwright-cli/debug-login.mjs#L1-L48)
- [inspect-vue-root.mjs:1-60](file://.playwright-cli/inspect-vue-root.mjs#L1-L60)