269 lines
7.9 KiB
Markdown
269 lines
7.9 KiB
Markdown
# 前端问题修复报告
|
||
|
||
> 日期: 2026-03-22
|
||
> 修复人: 资深开发工程师
|
||
> 状态: 已完成
|
||
|
||
## 一、问题概述
|
||
|
||
用户反馈：
|
||
1. 前端菜单不能点击
|
||
2. 浏览器控制台有报错
|
||
|
||
经过系统性诊断，发现以下问题并修复：
|
||
|
||
## 二、发现的问题
|
||
|
||
### 问题1: CSS语法错误（严重）
|
||
|
||
**位置**: `frontend/admin/src/styles/tokens.css` 第7行
|
||
|
||
**错误代码**:
|
||
```css
|
||
::root { /* 错误：多了一个冒号 */
|
||
--color-primary: #0e5a6a;
|
||
}
|
||
```
|
||
|
||
**正确代码**:
|
||
```css
|
||
:root { /* 正确：伪类选择器只需一个冒号 */
|
||
--color-primary: #0e5a6a;
|
||
}
|
||
```
|
||
|
||
**影响**: CSS变量全部失效，导致样式错乱，可能影响菜单点击区域
|
||
|
||
---
|
||
|
||
### 问题2: CSS伪元素语法错误（严重）
|
||
|
||
**位置**: `frontend/admin/src/styles/global.css` 第50-69行
|
||
|
||
**错误代码**:
|
||
```css
|
||
:::-webkit-scrollbar { } /* 错误：三个冒号 */
|
||
:::-webkit-scrollbar-track { } /* 错误：三个冒号 */
|
||
::selection { } /* 错误：三个冒号 */
|
||
```
|
||
|
||
**正确代码**:
|
||
```css
|
||
::-webkit-scrollbar { } /* 正确：两个冒号 */
|
||
::-webkit-scrollbar-track { } /* 正确：两个冒号 */
|
||
::selection { } /* 正确：两个冒号 */
|
||
```
|
||
|
||
**影响**: 滚动条和选中文本样式失效，虽然不直接影响功能，但属于明显错误
|
||
|
||
---
|
||
|
||
### 问题3: 循环依赖（中等）
|
||
|
||
**位置**: `frontend/admin/src/lib/http/csrf.ts`
|
||
|
||
**问题描述**:
|
||
```typescript
|
||
// csrf.ts 导入 client.ts 的 get
|
||
import { get as httpGet } from './client'
|
||
|
||
// client.ts 又导入 csrf.ts 的 getCSRFHeaders
|
||
import { getCSRFHeaders, CSRF_PROTECTED_METHODS } from './csrf'
|
||
```
|
||
|
||
**影响**:
|
||
- 可能导致模块加载顺序不确定
|
||
- 在某些构建配置下可能引发运行时错误
|
||
- 代码架构不清晰
|
||
|
||
**修复方案**:
|
||
- 在 `csrf.ts` 中使用原生 `fetch` 替代导入的 `get`
|
||
- 复制必要的 URL 构建逻辑到 `csrf.ts`
|
||
|
||
---
|
||
|
||
### 问题4: 字段名不匹配（中等）
|
||
|
||
**位置**: `frontend/admin/src/lib/http/csrf.ts` 第97行
|
||
|
||
**问题描述**:
|
||
- 后端返回: `{ code: 0, data: { csrf_token: "xxx" } }`
|
||
- 前端读取: `result.data.token`
|
||
|
||
**影响**: CSRF Token 获取失败，虽然系统仍能运行（有降级逻辑），但安全保护机制未生效
|
||
|
||
**修复**: 将 `result.data.token` 改为 `result.data.csrf_token`
|
||
|
||
---
|
||
|
||
## 三、修复详情
|
||
|
||
### 3.1 修复文件列表
|
||
|
||
| 文件 | 问题 | 修复方式 |
|
||
|-----|------|---------|
|
||
| `src/styles/tokens.css` | CSS语法错误 | 重写文件，修复:root选择器 |
|
||
| `src/styles/global.css` | CSS语法错误 | 重写文件，修复伪元素选择器 |
|
||
| `src/lib/http/csrf.ts` | 循环依赖+字段名不匹配 | 重写文件，使用原生fetch，修正字段名 |
|
||
|
||
### 3.2 验证结果
|
||
|
||
```bash
|
||
# 1. 构建验证
|
||
npm run build # ✅ 通过
|
||
|
||
# 2. 代码检查
|
||
npm run lint # ✅ 通过（仅coverage目录警告）
|
||
|
||
# 3. 单元测试
|
||
npm run test:run # ✅ 5/5 测试通过
|
||
|
||
# 4. TypeScript检查
|
||
npx tsc --noEmit # ✅ 无错误
|
||
```
|
||
|
||
### 3.3 追加修复（2026-03-22 16:00）
|
||
|
||
用户反馈菜单仍然无法点击，追加以下修复：
|
||
|
||
#### 问题5: CSS pointer-events 问题
|
||
|
||
**位置**: `frontend/admin/src/layouts/AdminLayout/AdminLayout.module.css`
|
||
|
||
**修复内容**:
|
||
- 添加 `pointer-events: auto !important` 确保菜单项可点击
|
||
- 添加 `cursor: pointer !important` 确保鼠标样式正确
|
||
- 调整 `z-index` 层级确保菜单不被遮挡
|
||
|
||
#### 问题6: CSS语法错误恢复
|
||
|
||
**位置**: `frontend/admin/src/styles/tokens.css` 和 `global.css`
|
||
|
||
**问题**: 之前修复的CSS语法错误被恢复
|
||
|
||
**修复**: 重新修复 `::root` → `:root` 和 `:::-webkit-scrollbar` → `::-webkit-scrollbar`
|
||
|
||
### 3.4 第三次修复（2026-03-22 16:15）
|
||
|
||
用户反馈菜单仍然无法点击。
|
||
|
||
**根本原因分析**:
|
||
CSS语法错误导致整个CSS文件解析失败，CSS变量全部失效，但这不是菜单无法点击的直接原因。
|
||
|
||
**实际修复**:
|
||
1. 再次修复 `tokens.css` 中的 `::root` → `:root`
|
||
2. 再次修复 `global.css` 中的 `:::-webkit-scrollbar` → `::-webkit-scrollbar` 和 `:::selection` → `::selection`
|
||
3. 合并 `AdminLayout.module.css` 中重复的CSS规则
|
||
4. 添加 `pointer-events: auto !important` 到菜单项样式
|
||
|
||
### 3.5 第四次修复（2026-03-22 16:18）
|
||
|
||
用户反馈菜单仍然无法点击。
|
||
|
||
**调试措施**:
|
||
1. 将 `openKeys` 改为 `defaultOpenKeys` 避免受控组件问题
|
||
2. 在Menu组件上添加内联样式 `style={{ pointerEvents: 'auto' }}`
|
||
3. 在 `handleMenuClick` 中添加 `console.log` 调试日志
|
||
|
||
**验证方法**:
|
||
1. 刷新浏览器
|
||
2. 按F12打开开发者工具
|
||
3. 点击左侧菜单
|
||
4. 查看Console面板是否有 "Menu clicked: xxx" 日志输出
|
||
5. 如果没有日志，说明点击事件未触发，需要检查CSS或DOM结构
|
||
6. 如果有日志但页面未跳转，说明navigate有问题
|
||
|
||
### 3.6 第五次修复（2026-03-22 17:56）
|
||
|
||
**菜单点击问题已解决！**
|
||
|
||
**根本原因**: Ant Design的Menu组件在使用 `openKeys`（受控模式）时，与CSS样式冲突导致点击事件被拦截。
|
||
|
||
**解决方案**: 将 `openKeys` 改为 `defaultOpenKeys`（非受控模式），并添加内联样式确保 `pointer-events: auto`。
|
||
|
||
**额外修复**:
|
||
1. **React Router警告**: 在 `createBrowserRouter` 中添加 `future: { v7_startTransition: true }` 配置
|
||
2. **Ant Design警告**: 将 `AssignRolesModal.tsx` 中的 `destroyOnClose` 改为 `destroyOnHidden`
|
||
3. 删除调试日志
|
||
|
||
### 3.7 第六次修复（2026-03-22 20:46）
|
||
|
||
**问题**: 刷新后出现500错误 `GET http://localhost:3000/src/app/router.tsx net::ERR_ABORTED 500`
|
||
|
||
**根本原因**: `router.tsx` 文件内容重复，第172-288行是重复的路由配置，导致JavaScript语法错误。
|
||
|
||
**解决方案**: 删除重复内容，恢复正确的文件结构。
|
||
|
||
**教训**: 使用 `replace_in_file` 时要小心，确保不会意外插入重复内容。
|
||
|
||
## 四、根因分析
|
||
|
||
### 为什么会出现这些问题？
|
||
|
||
1. **缺乏代码审查**: CSS语法错误应该在审查阶段被发现
|
||
2. **缺少自动化检查**: 没有配置Stylelint来检查CSS语法
|
||
3. **测试覆盖不足**: 没有集成测试来验证CSRF流程
|
||
4. **API契约不清晰**: 前后端字段名没有对齐
|
||
|
||
### 如何预防？
|
||
|
||
1. **代码审查清单**: 添加CSS语法检查项
|
||
2. **自动化工具**: 配置Stylelint + ESLint
|
||
3. **API文档**: 使用Swagger/OpenAPI明确字段名
|
||
4. **集成测试**: 添加端到端测试验证关键流程
|
||
|
||
## 五、团队改进建议
|
||
|
||
### 5.1 立即行动
|
||
|
||
- [ ] 配置Stylelint检查CSS语法
|
||
- [ ] 添加CSS代码审查检查项
|
||
- [ ] 对齐前后端API字段名文档
|
||
|
||
### 5.2 短期改进
|
||
|
||
- [ ] 添加集成测试覆盖CSRF流程
|
||
- [ ] 配置CI/CD自动化检查
|
||
- [ ] 建立API变更通知机制
|
||
|
||
### 5.3 长期建设
|
||
|
||
- [ ] 引入Storybook进行UI组件测试
|
||
- [ ] 建立端到端测试套件
|
||
- [ ] 完善开发文档和最佳实践
|
||
|
||
## 六、经验总结
|
||
|
||
### 6.1 技术层面
|
||
|
||
1. **CSS语法要严格**: 伪类(:)和伪元素(::)的区别
|
||
2. **避免循环依赖**: 模块间依赖要清晰
|
||
3. **API契约要对齐**: 前后端字段名要一致
|
||
4. **测试要全面**: 不仅是单元测试，还要集成测试
|
||
|
||
### 6.2 流程层面
|
||
|
||
1. **代码审查不能省**: 即使小改动也要审查
|
||
2. **自动化检查要完善**: 人工检查容易遗漏
|
||
3. **问题要追根溯源**: 不只修复表象，要解决根因
|
||
4. **经验要沉淀**: 把教训转化为文档和流程
|
||
|
||
## 七、附录
|
||
|
||
### 7.1 相关文档
|
||
|
||
- [代码质量标准](QUALITY_STANDARD.md)
|
||
- [生产验证清单](PRODUCTION_CHECKLIST.md)
|
||
- [技术提升指南](TECHNICAL_GUIDE.md)
|
||
|
||
### 7.2 参考链接
|
||
|
||
- [CSS伪类和伪元素区别](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Pseudo-classes)
|
||
- [JavaScript循环依赖](https://nodejs.org/api/modules.html#modules_cycles)
|
||
- [OWASP CSRF防护](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html)
|
||
|
||
---
|
||
|
||
**报告完成时间**: 2026-03-22 13:00
|
||
**下次回顾**: 2026-03-29
|