319 lines
8.7 KiB
Markdown
319 lines
8.7 KiB
Markdown
# Ether 智慧物业管理平台 - 问题解决记录
|
||
|
||
**文档版本**: v1.0
|
||
**最后更新**: 2026-02-10
|
||
**维护原则**: 按时间倒序记录，新问题置顶
|
||
|
||
---
|
||
|
||
## 一、2026-02-10 问题修复记录
|
||
|
||
### 1. 登录功能问题修复 ✅
|
||
|
||
**问题描述**: 前端登录后无法正确获取用户信息，路由跳转异常
|
||
|
||
**问题原因**:
|
||
1. 后端 LoginResponse 缺少 user 字段，前端需要该字段保存用户信息
|
||
2. 前端路由配置错误，动态路由未正确添加为 Layout 的子路由
|
||
3. layout 组件缺少 SafetyOutlined 图标支持
|
||
|
||
**解决方案**:
|
||
- 后端 LoginResponse 添加 user 字段
|
||
- 后端 AuthServiceImpl 设置 user 对象到响应中
|
||
- 前端路由配置修复，动态路由正确添加为 Layout 的子路由
|
||
- 前端 layout 组件添加 SafetyOutlined 图标支持
|
||
|
||
**涉及文件**:
|
||
- `ether-auth/src/main/java/com/ether/auth/dto/LoginResponse.java`
|
||
- `ether-auth/src/main/java/com/ether/auth/service/impl/AuthServiceImpl.java`
|
||
- `ether-ui-admin/src/router/index.ts`
|
||
- `ether-ui-admin/src/layout/index.vue`
|
||
|
||
---
|
||
|
||
### 2. 通知服务获取未读数量接口 500 错误修复 ✅
|
||
|
||
**问题描述**: 通知服务获取未读数量接口返回 500 错误
|
||
|
||
**问题原因**: 前端 permission store 未正确保存 currentProjectId 到 localStorage，导致项目上下文缺失
|
||
|
||
**解决方案**: 修复前端 permission store，确保 currentProjectId 正确保存到 localStorage
|
||
|
||
**涉及文件**:
|
||
- `ether-ui-admin/src/store/modules/permission.ts`
|
||
|
||
---
|
||
|
||
### 3. 菜单切换问题修复 ✅
|
||
|
||
**问题描述**: 菜单页面切换时无法正常加载对应页面
|
||
|
||
**问题原因**: 前端路由配置缺少菜单路由映射（Mdm/*, System/*, Ops/*）
|
||
|
||
**解决方案**:
|
||
- 前端路由配置添加缺失的菜单路由映射
|
||
- 创建用户管理、权限管理等页面组件
|
||
|
||
**涉及文件**:
|
||
- `ether-ui-admin/src/router/index.ts`
|
||
- `ether-ui-admin/src/views/system/user/index.vue`
|
||
- `ether-ui-admin/src/views/system/permission/index.vue`
|
||
|
||
---
|
||
|
||
### 4. 用户管理菜单缺少图标修复 ✅
|
||
|
||
**问题描述**: 用户管理菜单项缺少图标显示
|
||
|
||
**问题原因**: layout 组件 iconMap 未添加 UserOutlined 图标映射
|
||
|
||
**解决方案**: layout 组件 iconMap 添加 UserOutlined 图标映射
|
||
|
||
**涉及文件**:
|
||
- `ether-ui-admin/src/layout/index.vue`
|
||
|
||
---
|
||
|
||
### 5. 菜单页面获取列表失败修复 ✅
|
||
|
||
**问题描述**: 菜单页面无法正确获取数据列表
|
||
|
||
**问题原因**:
|
||
1. 前端 API 路径缺少 `/api/v1` 前缀
|
||
2. 后端 Controller 路径缺少 `/api/v1` 前缀
|
||
3. 后端实体类使用 PostGIS 依赖导致兼容性问题
|
||
|
||
**解决方案**:
|
||
- 前端 API 路径修复，添加 `/api/v1` 前缀
|
||
- 后端 Controller 路径修复，添加 `/api/v1` 前缀
|
||
- 后端实体类移除 PostGIS 依赖，改用 longitude/latitude 字段
|
||
|
||
**涉及文件**:
|
||
- `ether-ui-admin/src/api/mdm/space-node.ts`
|
||
- `ether-mdm/src/main/java/com/ether/mdm/controller/SpaceNodeController.java`
|
||
- `ether-mdm/src/main/java/com/ether/mdm/entity/SpaceNode.java`
|
||
|
||
---
|
||
|
||
### 6. 角色管理页面组件错误修复 ✅
|
||
|
||
**问题描述**: 角色管理页面使用错误的 UI 组件库
|
||
|
||
**问题原因**: 项目使用 Ant Design Vue，但角色管理页面使用了 Element Plus 组件
|
||
|
||
**解决方案**:
|
||
- 将 Element Plus 组件替换为 Ant Design Vue 组件
|
||
- 完善 permission store，添加 RoleType、DataScope 等类型定义
|
||
- 添加角色管理相关方法（loadRoles、addRole、editRole 等）
|
||
|
||
**涉及文件**:
|
||
- `ether-ui-admin/src/views/system/role/index.vue`
|
||
- `ether-ui-admin/src/store/modules/permission.ts`
|
||
|
||
---
|
||
|
||
### 7. 巡检管理页面报错修复 ✅
|
||
|
||
**问题描述**: 巡检管理页面 API 请求失败
|
||
|
||
**问题原因**: InspectionController 路径缺少 `/api/v1` 前缀
|
||
|
||
**解决方案**: 修复 InspectionController 路径，添加 `/api/v1` 前缀
|
||
|
||
**涉及文件**:
|
||
- `ether-mdm/src/main/java/com/ether/mdm/controller/InspectionController.java`
|
||
|
||
---
|
||
|
||
## 二、2026-02-09 问题修复记录
|
||
|
||
### 1. 端到端测试问题修复 ✅
|
||
|
||
**问题描述**: 端到端测试执行时遇到多个问题
|
||
|
||
**已修复问题**:
|
||
|
||
1. **密码加密方案**:
|
||
- 添加 `salt` 字段到 `auth_user` 表
|
||
- 使用随机 8 位 Salt
|
||
- 密码格式: `salt$MD5(password+salt)`
|
||
|
||
2. **前端路由错误**:
|
||
- 修复 `Empty` 组件导入错误
|
||
- 从 `@ant-design/icons-vue` 改为 `ant-design-vue`
|
||
|
||
3. **API 请求失败**:
|
||
- Gateway ProjectContextFilter 允许无 Project ID 的请求通过
|
||
- MDM 添加 `GET /api/v1/mdm/space-nodes` 分页查询接口
|
||
- 创建 `mdm_space_node` 表并设置正确权限
|
||
|
||
**已修改的配置**:
|
||
- Auth 服务: `ddl-auto: create` → `update`
|
||
- MDM 服务: `ddl-auto: create` → `update`
|
||
- 密码加密: BCrypt → MD5 + 随机 Salt
|
||
- 新增文件: `Md5SaltPasswordEncoder.java`
|
||
|
||
**涉及文件**:
|
||
- `ether-auth/src/main/java/com/ether/auth/config/Md5SaltPasswordEncoder.java`
|
||
- `ether-gateway/src/main/java/com/ether/gateway/filter/ProjectContextFilter.java`
|
||
- `ether-mdm/src/main/java/com/ether/mdm/controller/SpaceNodeController.java`
|
||
- `ether-ui-admin/src/views/space/index.vue`
|
||
|
||
---
|
||
|
||
## 三、早期问题修复记录
|
||
|
||
### 1. 数据库连接问题修复 ✅
|
||
|
||
**问题描述**: PostgreSQL 密码认证失败
|
||
|
||
**解决方案**: 修复 PostgreSQL 密码认证配置
|
||
|
||
---
|
||
|
||
### 2. API 路径统一 ✅
|
||
|
||
**问题描述**: 前后端 API 路径不一致
|
||
|
||
**解决方案**: 前后端路径统一为 `/api/v1/**`
|
||
|
||
---
|
||
|
||
### 3. CORS 跨域问题修复 ✅
|
||
|
||
**问题描述**: 前端调用后端 API 时遇到跨域问题
|
||
|
||
**解决方案**: Gateway 添加 globalcors 配置
|
||
|
||
**涉及文件**:
|
||
- `ether-gateway/src/main/resources/application.yml`
|
||
|
||
---
|
||
|
||
### 4. 服务注册问题修复 ✅
|
||
|
||
**问题描述**: 微服务无法成功注册到 Nacos
|
||
|
||
**解决方案**: 统一服务注册配置，确保所有服务成功注册到 Nacos
|
||
|
||
---
|
||
|
||
### 5. 模块结构调整 ✅
|
||
|
||
**问题描述**: 项目模块结构不符合领域驱动设计
|
||
|
||
**解决方案**: 按领域驱动设计重新划分模块
|
||
|
||
---
|
||
|
||
### 6. JSONB 字段问题修复 ✅
|
||
|
||
**问题描述**: PostgreSQL JSONB 类型转换错误
|
||
|
||
**解决方案**: 修复 PostgreSQL JSONB 类型转换配置
|
||
|
||
---
|
||
|
||
## 四、问题分类统计
|
||
|
||
### 按问题类型统计
|
||
|
||
| 问题类型 | 数量 | 占比 |
|
||
|---------|------|------|
|
||
| API 路径问题 | 4 | 25% |
|
||
| 前端组件问题 | 3 | 19% |
|
||
| 认证授权问题 | 2 | 13% |
|
||
| 数据库问题 | 2 | 13% |
|
||
| 配置问题 | 2 | 13% |
|
||
| 架构问题 | 1 | 6% |
|
||
| 其他 | 2 | 13% |
|
||
|
||
### 按模块统计
|
||
|
||
| 模块 | 问题数量 |
|
||
|------|---------|
|
||
| ether-ui-admin (前端) | 6 |
|
||
| ether-gateway | 2 |
|
||
| ether-auth | 2 |
|
||
| ether-mdm | 3 |
|
||
| 基础设施 | 3 |
|
||
|
||
---
|
||
|
||
## 五、预防措施
|
||
|
||
### 1. API 路径规范
|
||
- 所有后端 Controller 必须添加 `/api/v1` 前缀
|
||
- 前端 API 调用统一使用封装好的 api 模块
|
||
- 新增接口时必须同步更新前后端路径
|
||
|
||
### 2. 前端组件规范
|
||
- 统一使用 Ant Design Vue 组件库
|
||
- 图标必须从 `@ant-design/icons-vue` 导入
|
||
- 新增页面时必须检查 iconMap 映射
|
||
|
||
### 3. 认证授权规范
|
||
- 所有响应必须包含必要的用户信息
|
||
- Token 和用户信息必须正确存储到 localStorage
|
||
- 项目上下文必须正确传递
|
||
|
||
### 4. 数据库规范
|
||
- 避免使用特定数据库的扩展功能（如 PostGIS）
|
||
- 使用标准字段类型（如 longitude/latitude 代替 Point）
|
||
- 数据库变更必须同步更新实体类
|
||
|
||
---
|
||
|
||
## 六、测试验证
|
||
|
||
### 端到端测试用例
|
||
|
||
| 用例ID | 测试项 | 状态 |
|
||
|--------|--------|------|
|
||
| TC-001 | 用户登录功能测试 | ✅ 通过 |
|
||
| TC-002 | 通知中心功能测试 | ✅ 通过 |
|
||
| TC-003 | 工单管理功能测试 | ⏸️ 未执行 |
|
||
| TC-004 | 设备管理功能测试 | ⏸️ 未执行 |
|
||
| TC-005 | 空间节点功能测试 | ✅ 通过 |
|
||
| TC-006 | 权限管理功能测试 | ⏸️ 未执行 |
|
||
|
||
### 测试环境要求
|
||
|
||
完整的端到端测试需要以下服务全部启动：
|
||
|
||
1. **基础设施**
|
||
- PostgreSQL 15 (端口 5432)
|
||
- RabbitMQ (端口 5672, 15672)
|
||
- Nacos (端口 8848)
|
||
|
||
2. **后端微服务**
|
||
- ether-gateway (端口 8080)
|
||
- ether-auth (端口 8081)
|
||
- ether-mdm (端口 8082)
|
||
- ether-ops (端口 8083)
|
||
- ether-finance (端口 8084)
|
||
|
||
3. **前端**
|
||
- ether-ui-admin (端口 5174)
|
||
|
||
### 快速启动脚本
|
||
|
||
```bash
|
||
# 启动所有服务
|
||
chmod +x /Users/Chiguyong/Code/Ether/start-services.sh
|
||
/Users/Chiguyong/Code/Ether/start-services.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 七、文档维护说明
|
||
|
||
1. **记录原则**: 所有生产环境问题和重要开发问题必须记录
|
||
2. **记录格式**: 问题描述 → 问题原因 → 解决方案 → 涉及文件
|
||
3. **更新频率**: 每次修复问题后立即更新
|
||
4. **归档策略**: 每季度归档一次已解决的问题到历史记录
|
||
|
||
---
|
||
|
||
**文档维护**: 本文档为问题解决记录的唯一权威文档，所有问题修复记录请直接修改此文件。
|