# 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. **归档策略**: 每季度归档一次已解决的问题到历史记录

---

**文档维护**: 本文档为问题解决记录的唯一权威文档，所有问题修复记录请直接修改此文件。