42 KiB

Raw Permalink Blame History

Ether 智慧物业管理平台 - 项目进度总览

文档版本: v1.2
最后更新: 2026-03-02
当前阶段: Phase 3 移动端适配已完成，Phase 4/5 集成中心开发中

〇、长时间运行智能体框架

本项目采用长时间运行智能体框架进行开发，确保跨会话的一致性和进度追踪。

核心文档

文档	路径	说明
特性清单	`docs/FEATURE_LIST.md`	所有特性的状态追踪（待开发/进行中/已完成）
会话进度	`docs/SESSION_PROGRESS.md`	每个会话的工作记录和下一步计划
项目进度	`docs/03-项目进度/PROJECT_PROGRESS.md`	本文档，项目整体进度总览

工作流程

┌─────────────────────────────────────────────────────────────┐
│                    会话开始                                  │
│  1. 阅读 SESSION_PROGRESS.md 了解上次进度                    │
│  2. 阅读 FEATURE_LIST.md 选择本次要完成的特性                 │
│  3. 更新特性状态为 🔄 进行中                                  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    开发工作                                  │
│  1. 遵循开发规范编写代码                                     │
│  2. 每次完成1-3个相关特性                                    │
│  3. 运行测试确保通过                                         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    会话结束                                  │
│  1. 更新特性状态为 ✅ 已完成                                  │
│  2. 更新 SESSION_PROGRESS.md 记录工作内容                    │
│  3. 提交有意义的 Git commit                                  │
│  4. 写明下一步计划                                           │
└─────────────────────────────────────────────────────────────┘

会话检查清单

代码可编译/可运行
相关测试通过
更新 FEATURE_LIST.md 特性状态
更新 SESSION_PROGRESS.md 会话记录
提交 Git commit

一、项目概述

基于微服务架构的智慧物业管理平台，涵盖空间资产、设备管理、工单运维、财务收费等核心模块。

技术架构

ether-gateway          # API网关 (端口:8080)
ether-auth             # 认证授权服务 (端口:8081)
ether-mdm              # 主数据服务 (端口:8082)
ether-ops              # 运维服务 (端口:8083)
ether-finance          # 财务服务 (端口:8084)
ether-ui-admin         # 前端管理界面 (端口:3000)

技术栈

后端: Spring Boot 3.x, Spring Cloud, Spring Data JPA
前端: Vue 3, TypeScript, Element Plus, Pinia
数据库: PostgreSQL
消息队列: RabbitMQ
服务发现: Nacos
构建工具: Maven

二、已完成模块

1. RBAC 权限系统 ✅

后端 (ether-auth)

Role 实体 - 角色表，支持系统预设和自定义角色
Permission 实体 - 权限表，支持菜单/按钮/API权限
UserRole 实体 - 用户-角色关联，支持项目隔离
RolePermission 实体 - 角色-权限关联
Repository 层 - 数据访问
PermissionService - 业务逻辑
PermissionController - API接口
ProjectContextInterceptor - 项目上下文拦截器

前端 (ether-ui-admin)

permission API - 权限相关接口
permission Store - Pinia状态管理
permission 指令 - 按钮级权限控制
permissionGuard - 路由权限守卫
角色管理页面 - 角色CRUD和权限分配

API 接口

接口	说明
POST /api/v1/auth/permissions/roles	创建角色
GET /api/v1/auth/permissions/roles	查询角色列表
POST /api/v1/auth/permissions	创建权限
GET /api/v1/auth/permissions	查询权限列表
POST /api/v1/auth/permissions/roles/{id}/permissions	分配权限
GET /api/v1/auth/permissions/users/{id}/menus	获取用户菜单

2. 工单与通知系统集成 ✅

后端 (ether-ops)

工单创建通知 - 创建工单时发送通知给创建人
工单分配通知 - 分配工单时通知处理人（站内信+推送）
工单接单通知 - 接单时发送通知
工单开始通知 - 开始处理时发送通知
工单完成通知 - 完成时通知创建人
工单关闭通知 - 关闭时发送通知
默认通知规则 - 4条默认规则已创建
默认消息模板 - 6个默认模板已创建

事件类型

事件类型	触发时机	接收人
WORK_ORDER_CREATED	工单创建	创建人
WORK_ORDER_ASSIGNED	工单分配	处理人
WORK_ORDER_ACCEPTED	工单接单	-
WORK_ORDER_STARTED	开始处理	-
WORK_ORDER_COMPLETED	工单完成	创建人
WORK_ORDER_CLOSED	工单关闭	-

3. 前端通知中心组件 ✅

前端 (ether-ui-admin)

通知 API - 通知相关接口封装
通知 Store - Pinia状态管理，支持轮询
通知中心组件 - 顶部通知图标和下拉列表
通知列表页面 - 完整的通知管理页面

功能特性

未读消息提醒 - 顶部导航栏显示未读数量徽章
通知下拉列表 - 显示最近5条未读通知
通知详情弹窗 - 点击查看通知详情
全部已读 - 一键标记所有通知为已读
自动轮询 - 30秒自动刷新未读数量
筛选功能 - 全部/未读/已读筛选
分页加载 - 支持分页浏览历史通知
业务跳转 - 点击通知可跳转到相关业务页面

4. 费用催缴通知 ✅

后端 (ether-finance)

FeeReminderJob - 定时扫描即将到期和逾期账单
FinanceNotificationProducer - 通过RabbitMQ发送费用通知
FinanceNotificationConsumer - 接收并保存费用通知
FeeNotificationService - 费用通知业务接口
FeeNotificationServiceImpl - 费用通知业务实现
RabbitMQNotificationConfig - 财务通知队列配置

定时任务

任务	执行时间	功能
remindUpcomingDue	每天9:00	提醒3天内到期的账单
remindOverdue	每天9:00和18:00	催缴已逾期的账单
sendWeeklySummary	每周一9:00	发送本周待缴费汇总

通知类型

事件类型	触发时机	接收人
FEE_BILL_CREATED	账单创建	业主
FEE_UPCOMING_DUE	即将到期	业主
FEE_OVERDUE	账单逾期	业主
FEE_PAYMENT_SUCCESS	缴费成功	业主

5. 巡检提醒通知 ✅

后端 (ether-ops)

InspectionTask - 巡检任务实体
InspectionTaskRepository - 数据访问层
InspectionReminderJob - 定时扫描和提醒

定时任务

任务	执行时间	功能
remindTodayInspection	每天8:00	提醒当天需要执行的巡检任务
remindTomorrowInspection	每天18:00	提醒明天的巡检任务
alertOverdueInspection	每天9:00和15:00	告警已逾期的巡检任务
sendWeeklyInspectionSummary	每周一8:00	发送本周巡检任务汇总

通知事件类型

事件类型	触发时机	接收人
INSPECTION_TODAY	当天巡检提醒	巡检人
INSPECTION_TOMORROW	明天巡检提醒	巡检人
INSPECTION_OVERDUE	巡检任务逾期	巡检人
INSPECTION_WEEKLY_SUMMARY	周巡检汇总	巡检人

6. 工单系统核心功能 ✅

开发状态: 核心功能开发完成，146个测试全部通过

后端 (ether-ops)

实体层 - WorkOrder, WorkOrderFlow
枚举层 - Type, Status, Priority, Source
仓储层 - Repository + 自定义查询
Service层 - 完整生命周期管理
Controller层 - REST API
流转记录 - 自动记录状态变更
集成测试 - 端到端测试
统计功能 - 多维度统计分析

前端 (ether-ui-admin)

API层 - 完整API封装
WorkOrderList - 列表+搜索+分页
WorkOrderForm - 创建/编辑表单
WorkOrderDetail - 详情+操作按钮
统计页面 - ECharts图表
页面集成 - 主页面布局

工单生命周期

CREATED (已创建) → ASSIGNED (已分配) → ACCEPTED (已接单)
→ IN_PROGRESS (处理中) → COMPLETED (已完成) → CLOSED (已关闭)

7. 合同管理系统 ✅

开发状态: 功能完善完成，后端编译通过，前端类型检查通过

后端 (ether-mdm)

数据库设计 - mdm_contract, mdm_contract_fee_item, mdm_contract_change
枚举类 - ContractType (14种), ContractStatus, FeeCycle, ContractChangeType
实体类 - Contract, ContractFeeItem, ContractChange
Repository层 - ContractRepository, ContractFeeItemRepository, ContractChangeRepository
Service层 - ContractService, ContractServiceImpl
Controller层 - ContractController (REST API + @LogOperation)
定时任务 - ContractReminderJob (到期预警)
事件发布 - ContractSignedEvent (合同签订事件)

后端 (ether-finance)

账单生成 - FeeService.generateBillsFromContract (合同签订后自动生成账单)
费用类型 - FeeType.RENT (新增租金类型)

后端 (ether-auth)

权限配置 - V12__add_contract_permissions.sql (菜单和按钮权限)

前端 (ether-ui-admin)

API封装 - contract.ts (类型定义、接口封装、14种合同类型)
合同列表页 - index.vue (搜索、分页、状态标签、到期预警)
合同详情页 - detail.vue (基本信息、费用明细、变更记录、附件展示、PDF预览)
合同表单页 - form.vue (创建/编辑、附件上传、费用明细编辑)
路由配置 - 动态路由映射

合同生命周期

DRAFT (草稿) → PENDING_APPROVAL (待审批) → APPROVED (已审批)
→ PENDING_SIGN (待签订) → EFFECTIVE (生效中) → EXPIRING (即将到期) → EXPIRED (已到期)
                                    ↓
                              TERMINATED (已终止) / RENEWED (已续签)

核心功能

合同CRUD管理
合同审批流程
合同签订确认
合同费用明细管理
合同变更管理
合同到期预警（定时任务）
合同续签功能
合同终止功能
合同附件上传与PDF预览
合同签订后自动生成账单

合同类型支持 (14种)

类型	编码	适用场景
物业服务合同	PROPERTY_SERVICE	物业公司与业委会
前期物业服务合同	PRE_PROPERTY	开发商与物业公司
住宅租赁合同	RESIDENTIAL_LEASE	住宅出租
商业租赁合同	COMMERCIAL_LEASE	商铺/写字楼
车位租赁合同	PARKING_LEASE	车位出租
保洁服务合同	CLEANING_SERVICE	第三方保洁公司
安保服务合同	SECURITY_SERVICE	第三方安保公司
绿化养护合同	LANDSCAPE_SERVICE	第三方绿化公司
电梯维保合同	ELEVATOR_SERVICE	电梯维保公司
消防维保合同	FIRE_SERVICE	消防维保公司
垃圾清运合同	WASTE_SERVICE	环卫公司
广告位租赁合同	ADVERTISEMENT	广告位出租
场地租赁合同	VENUE_RENTAL	临时活动场地
其他合同	OTHER	其他类型

相关文档

单元测试

ContractServiceTest - 18个测试用例，覆盖合同生命周期所有操作
ContractControllerTest - 14个测试用例，覆盖所有API接口

测试结果

Tests run: 32, Failures: 0, Errors: 0, Skipped: 0
BUILD SUCCESS

三、模块架构

根据领域驱动设计，项目分为以下模块：

ether-platform/
├── ether-gateway/          # API 网关
├── ether-auth/             # 认证中心
├── ether-mdm/              # 空间主数据 (4.1)
│   ├── SpaceNode           # 空间节点
│   ├── RoomDetail          # 房间详情
│   ├── Ownership           # 产权信息
│   ├── Visitor             # 访客管理
│   ├── Inspection          # 巡检管理
│   └── Contract            # 合同管理
├── ether-ops/              # 运营调度 (4.2)
│   ├── WorkOrder           # 工单系统
│   └── Notification        # 通知系统
├── ether-asset/            # 设施设备 (4.3)
│   └── Equipment           # 设备台账
└── ether-finance/          # 财务计费 (4.4)
    ├── FeeItem             # 收费项目
    ├── FeeBill             # 收费账单
    └── FeePayment          # 支付记录

API 路由映射

模块	路由前缀	说明
ether-auth	`/api/v1/auth/**`	认证相关
ether-mdm	`/api/v1/mdm/**`	主数据管理
ether-ops	`/api/v1/ops/**`	运营调度
ether-asset	`/api/v1/asset/**`	设施设备
ether-finance	`/api/v1/finance/**`	财务计费

四、下一阶段工作规划

Phase 1: 完善现有功能联动（已完成）✅

目标: 完善现有模块的联动功能

设备与工单联动 ✅
- ✅ 设备故障自动创建维修工单
- ⏭️ 工单关联设备信息展示（待开发）
- ⏭️ 设备维修历史查询（待开发）
巡检与工单联动 ✅
- ✅ 巡检异常自动创建工单
- ⏭️ 巡检任务与工单状态同步（待开发）
收费管理优化 ✅
- ✅ 费用催缴通知
- ✅ 逾期费用计算
- ⏭️ 费用报表导出（待开发）
消息通知系统 ✅
- ✅ 通知渠道管理
- ✅ 消息模板管理
- ✅ 通知规则管理
- ✅ 消息历史记录
- ✅ 与工单系统集成（已完成）

Phase 2: 权限与账户领域完善（已完成）✅

目标: 实现 RBAC 权限模型和项目隔离

系统配置管理 ✅
- ✅ EtherProperties 统一配置管理
- ✅ 访客凭证配置（过期时间、签名算法）
- ✅ 系统配置（版本、超级管理员角色编码）
项目隔离实现 ✅
- ✅ Gateway 自动注入 project_id（X-Project-Id Header）
- ✅ ProjectContextHolder ThreadLocal 上下文
- ✅ ProjectContextInterceptor 拦截器
- ✅ 超级管理员跳过项目隔离（基于 RBAC 判断）
访客凭证系统 ✅
- ✅ VisitorCredential 实体和 CredentialStatus 枚举
- ✅ 二维码生成与验证（格式：VC:{credentialId}:{timestamp}:{signature}）
- ✅ HmacSHA256 签名验证
- ✅ VisitorCredentialService 业务逻辑
- ✅ VisitorCredentialController API 接口
- ✅ 数据库表 auth_visitor_credential
操作日志审计系统 ✅
- ✅ OperationLog 实体
- ✅ @LogOperation 注解
- ✅ OperationLogAspect AOP 切面
- ✅ 敏感字段脱敏（password, salt, idCard, phone）
- ✅ 用户维度查询（by-user）
- ✅ 业务维度查询（by-project, by-business）
- ✅ 数据库表 auth_operation_log
- ⏭️ 自动归档（待系统开发完成后实现）

Phase 3: 移动端适配（已完成）✅

目标: 支持移动端访问，方便现场人员使用

完成状态: ✅ 已完成

响应式布局优化 ✅
- ✅ 适配手机、平板屏幕
- ✅ 触摸友好的交互
员工端 H5/App ✅
- ✅ 工单接单、处理
- ✅ 巡检任务执行
- ✅ 访客登记
- ✅ 通知接收
业主端 H5/App ✅
- ✅ 账单查询
- ✅ 在线缴费
- ✅ 报修提交
- ✅ 访客预约
扫码功能 ✅
- ✅ 设备扫码查看
- ✅ 扫码报修
- ✅ 访客扫码通行
消息推送 ✅
- ✅ 工单提醒
- ✅ 缴费提醒
- ✅ 巡检提醒

Phase 4: 集成中心（优先级：中）

目标: 对接外部系统和 IoT 设备

完成状态: ⏳ 开发中

停车系统集成 ⏳
- ⏭️ 车牌识别接口
- ⏭️ 车位状态同步
门禁系统集成 ⏳
- ⏭️ 访客二维码下发
- ⏭️ 通行记录上报
IoT 传感器接入 ⏳
- ⏭️ MQTT 消息监听
- ⏭️ 设备故障自动报警

三、功能实现进度

模块完成度统计

模块	功能	完成度	说明
M01 空间与资产管理	项目管理、空间节点、业主管理	100%
M01 空间与资产管理	租户管理	100%	已实现，需求文档待更新
M02 设施设备管理	设备台账、维修工单	100%
M03 运营调度	工单、巡检、访客	100%
M04 巡检管理	巡检计划、任务、记录	100%
M05 访客管理	预约、登记、凭证、黑名单	100%	已实现，需求文档待更新
M06 财务计费	账单、收费、催缴	95%	在线支付已实现，待集成
M07 权限与账户	用户、角色、权限	100%

五、待开发任务清单

高优先级

业主端小程序/APP
工单关联设备信息展示
设备维修历史查询
费用报表导出

中优先级

报表统计功能
数据导入导出
系统配置管理 ✅ (2026-02-10 完成)
操作日志审计 ✅ (2026-02-10 完成，自动归档待后续实现)

低优先级

短信通知渠道
邮件通知渠道
推送通知渠道
第三方系统集成

六、测试统计

后端测试

WorkOrderTest ................... 5 tests ✅
WorkOrderEnumsTest .............. 12 tests ✅
WorkOrderRepositoryTest ......... 12 tests ✅
WorkOrderServiceTest ............ 26 tests ✅
WorkOrderControllerTest ......... 19 tests ✅
WorkOrderFlowTest ............... 6 tests ✅
WorkOrderFlowRepositoryTest ..... 6 tests ✅
WorkOrderIntegrationTest ........ 6 tests ✅
WorkOrderStatisticsServiceTest .. 10 tests ✅
-------------------------------------------
Total ........................... 103 tests ✅

前端测试

work-order.test.ts .............. 19 tests ✅
WorkOrderList.spec.ts ........... 13 tests ✅
WorkOrderForm.spec.ts ........... 11 tests ✅
-------------------------------------------
Total ........................... 43 tests ✅

七、开发规范

代码规范

使用 Lombok 简化代码
遵循 RESTful API 设计规范
统一返回结果封装 (Result)
异常统一处理

数据库规范

表名使用下划线命名
字段名使用下划线命名
必须包含 created_at, updated_at 字段
使用 UUID 作为主键

接口规范

统一前缀: /api/v1/{module}
使用 HTTP 方法区分操作
请求参数使用 DTO 封装
返回结果使用 VO 封装

八、Bug修复记录

2026-02-10 - 前端页面报错修复

问题汇总

页面	问题	原因	解决方案
设备管理	404 错误	前端导入 `api/asset/equipment`，后端只有 `api/mdm/equipment`	修改导入路径为 `api/mdm/equipment`
访客管理	404 错误	后端 `VisitorController` 缺少 `/api/v1` 前缀	修改 `@RequestMapping("/api/v1/mdm/visitors")`
工单统计	echarts 导入错误	项目未安装 echarts 依赖	`npm install echarts --save` 并重启开发服务器
角色管理	页面加载失败	使用 Element Plus 组件，但项目只安装了 Ant Design Vue	将 Element Plus 组件替换为 Ant Design Vue
巡检管理	404 错误	后端 `InspectionController` 缺少 `/api/v1` 前缀	修改 `@RequestMapping("/api/v1/mdm/inspections")`

解决方案文档

已创建《前端开发规范》文档：docs/02-设计文档/公共规范/前端开发规范.md
包含：组件库规范、API路径规范、依赖管理规范、问题解决方案记录

2026-02-10 - 前端路由跳转问题修复

问题描述

症状: 点击侧边栏菜单，页面没有切换，URL 保持不变。

根本原因:

菜单点击使用 router.push({ name: key })，但动态路由的 name 可能未正确注册
动态路由添加后，使用 name 导航可能找不到对应路由

解决方案:

// 修改前：使用 name 导航
const handleMenuClick = ({ key }: { key: string }) => {
  router.push({ name: key });
};

// 修改后：使用 path 导航
const handleMenuClick = ({ key }: { key: string }) => {
  const menu = findMenuByComponentName(menus, key);
  if (menu?.menuPath) {
    router.push(menu.menuPath);
  }
};

相关文件:

src/views/layout/index.vue - 菜单点击处理
src/router/index.ts - 动态路由生成

文档更新:

已创建《前端路由最佳实践》文档：docs/04-技术方案/ROUTING_BEST_PRACTICES.md
包含：路由架构设计、常见问题解决方案、开发规范

2026-02-10 - 访客凭证功能完善

前端表单提交修复

问题: 表单提交后弹窗不关闭，无法显示生成的二维码

根本原因: request 拦截器已经解包了响应数据，但前端代码还在检查 res.code === 200

修复内容:

// 修改前
const res = await visitorCredentialApi.generateCredential(submitData);
if (res.code === 200) {  // 错误
  ...
}

// 修改后
const res = await visitorCredentialApi.generateCredential(submitData);
message.success("凭证生成成功");
generateModalVisible.value = false;
fetchCredentials();
resetForm();
if (res) {
  currentCredential.value = res;
  qrCodeModalVisible.value = true;
}

相关文件:

src/views/mdm/visitor/components/VisitorCredential.vue
src/api/mdm/visitor.ts

@LogOperation 注解完善

添加范围:

Controller	方法数	说明
AuthController	5	登录、注册、刷新Token、登出、获取权限
PermissionController	17	角色管理、权限管理、角色权限分配、用户角色分配
VisitorCredentialController	6	生成、查询、撤销、验证、清理凭证

使用示例:

@LogOperation(
    module = "访客管理",
    operation = "CREATE",
    description = "生成访客凭证",
    businessType = "VISITOR_CREDENTIAL"
)
public ResponseEntity<VisitorCredentialResponse> generateCredential(...) { ... }

验证结果:

✅ 前端表单提交正常，弹窗关闭并显示二维码
✅ 操作日志正确记录到数据库
✅ 敏感字段自动脱敏（password, idCard, phone 等）

2026-02-10 - 前端功能完善

前端验证凭证功能

修复内容:

修复 API 响应处理逻辑（移除 res.code === 200 检查）
添加成功/失败消息提示
验证成功后自动刷新列表

文件: src/views/mdm/visitor/components/VisitorCredential.vue

前端撤销凭证功能

修复内容:

修复 API 响应处理逻辑
添加确认弹窗
撤销成功后自动刷新列表并更新统计

操作日志前端页面

新增文件:

src/api/system/operationLog.ts - 操作日志 API
src/views/system/operation-log/index.vue - 操作日志页面

功能特性:

多维度筛选（模块、操作类型、业务类型、执行结果、时间范围）
表格展示（操作时间、操作人、模块、类型、描述、URL、执行时间、结果）
详情弹窗（完整日志信息、请求参数格式化展示）
支持查询参数高亮显示

页面路径: /system/operation-logs

权限管理前端页面

新增文件:

src/api/system/permission.ts - 权限管理 API
src/views/system/permission/index.vue - 权限管理页面

功能特性:

角色管理: 新增、编辑、删除角色，启用/禁用角色，分配权限
权限管理: 新增、编辑、删除权限，启用/禁用权限
权限分配: 树形结构展示权限，支持批量分配
数据范围: 支持配置角色的数据访问范围（全部/项目/部门/仅本人）

页面路径: /system/permissions

功能完整性总结

模块	功能	前端	API	状态
访客凭证	生成凭证	✅	✅	完成
访客凭证	查看二维码	✅	✅	完成
访客凭证	撤销凭证	✅	✅	完成
访客凭证	验证凭证	✅	✅	完成
访客凭证	查询列表	✅	✅	完成
访客凭证	清理过期	✅	✅	完成
操作日志	查询日志	✅	✅	完成
权限管理	角色管理	✅	✅	完成
权限管理	权限管理	✅	✅	完成
权限管理	权限分配	✅	✅	完成

2026-02-11 - E2E测试报告

单元测试

执行命令: npm test -- --run

测试结果: ✅ 全部通过 (7/7)

✓ should fetch work orders by project
✓ should create work order
✓ should update work order
✓ should delete work order
✓ should search work orders
✓ should fetch work order detail
✓ should handle API errors

E2E功能测试

测试环境:

前端: http://localhost:5174
后端: http://localhost:8081
浏览器: Chrome DevTools MCP

测试用例执行结果:

模块	功能	测试结果	备注
访客凭证	页面加载	✅ 通过	统计数据正确显示
访客凭证	生成凭证	✅ 通过	弹窗关闭，列表刷新，统计更新
访客凭证	查看二维码	✅ 通过	弹窗显示二维码和凭证信息
访客凭证	撤销凭证	✅ 通过	状态变更，统计更新
访客凭证	验证凭证	✅ 通过	API测试通过
操作日志	API查询	✅ 通过	支持多维度筛选
权限管理	页面加载	⚠️ 受限	需要权限配置
权限管理	创建角色	⚠️ 需修复	已添加 projectId 传递

发现的问题:

权限管理页面访问受限 - 当前用户没有权限管理权限，需要配置角色权限
创建角色缺少 projectId - 已修复，添加 permissionStore 获取当前项目ID

修复记录:

问题	修复文件	修复内容
创建角色缺少 projectId	`src/views/system/permission/index.vue`	添加 permissionStore，提交时包含 projectId

2026-02-11 - 权限控制机制验证

权限控制实现状态

已实现的权限控制机制:

控制层级	实现方式	状态	说明
菜单级	后端返回菜单列表	✅ 已生效	用户只能看到后端返回的菜单
路由级	路由守卫检查	✅ 已生效	无权限访问时重定向到首页
按钮级	`v-permission` 指令	✅ 已生效	无权限时按钮不渲染
API级	后端权限校验	✅ 已生效	返回 403 无权限访问

验证结果:

菜单级权限控制 ✅
- 后端 user-permissions 接口只返回用户有权限的菜单
- Layout 组件根据 permissionStore.menus 渲染菜单
- 当前用户没有权限管理菜单，所以看不到
路由级权限控制 ✅
- permissionGuard.ts 检查 to.meta.permission
- 无权限时跳转到 403 页面
- 当前用户访问 /system/permissions 被正确拦截
按钮级权限控制 ✅
- v-permission 指令已注册
- 支持 v-permission="'code'"、v-permission:all、v-permission:any
- 无权限时元素被移除
API级权限控制 ✅
- 后端接口返回 403
- 验证：/api/v1/auth/user-permissions 返回 403

权限控制使用说明

1. 菜单权限控制:

// 后端返回的菜单数据控制显示
// 只有后端返回的菜单才会显示在侧边栏

2. 路由权限控制:

// 在路由配置中添加 permission 元数据
{
  path: '/system/permissions',
  meta: {
    permission: 'system:permission:view'  // 需要此权限才能访问
  }
}

3. 按钮权限控制:

<!-- 单个权限 -->
<a-button v-permission="'system:permission:create'">新增</a-button>

<!-- 需要所有权限 -->
<a-button
  v-permission:all="['system:permission:edit', 'system:permission:admin']"
>编辑</a-button>

<!-- 需要任意权限 -->
<a-button
  v-permission:any="['system:permission:edit', 'system:permission:view']"
>查看</a-button>

4. 代码级权限检查:

const permissionStore = usePermissionStore();

// 检查是否有权限码
if (permissionStore.hasPermissionCode("system:permission:create")) {
  // 有权限
}

// 检查是否有任意权限
if (permissionStore.hasAnyPermission(["code1", "code2"])) {
  // 有权限
}

// 检查是否有所有权限
if (permissionStore.hasAllPermissions(["code1", "code2"])) {
  // 有权限
}

2026-02-11 - 超级管理员权限修复

问题分析

系统初始化时创建了超级管理员，但超级管理员无法看到权限管理菜单：

DataInitializer 使用 SYSTEM_PROJECT_ID (00000000-0000-0000-0000-000000000000) 作为系统项目ID
PermissionService.getUserPermissions 使用 findPermissionsByUserIdAndProjectId 查询权限
该查询方法通过 UserRole 关联查询，但超级管理员的权限直接绑定在系统项目上

修复方案

修改 PermissionService.getUserPermissions 方法，为超级管理员特殊处理：

// 检查是否是超级管理员
boolean isSuperAdmin = userRoles.stream()
        .anyMatch(ur -> {
            Role role = roleRepository.findById(ur.getRoleId()).orElse(null);
            return role != null && "SUPER_ADMIN".equals(role.getRoleCode());
        });

// 获取权限时特殊处理
for (UUID projectId : projectIds) {
    List<Permission> permissions;
    if (isSuperAdmin && SYSTEM_PROJECT_ID.equals(projectId)) {
        // 超级管理员获取系统项目的所有权限
        permissions = permissionRepository.findByProjectIdAndEnabledTrueOrderByModuleAscSortOrderAsc(projectId);
    } else {
        permissions = permissionRepository
                .findPermissionsByUserIdAndProjectId(userId, projectId);
    }
    // ...
}

修复文件

文件	修改内容
`ether-auth/src/main/java/com/ether/auth/service/PermissionService.java`	添加超级管理员判断，使用直接查询获取系统项目权限

系统初始化数据

超级管理员账号: admin / admin123

初始化权限包括:

系统管理：项目管理、用户管理、角色管理、权限管理
主数据：空间节点、业主、设备、巡检、访客、收费
运维：工单管理、工单统计
消息：消息中心、通知配置

2026-02-11 - 网关和CORS配置修复 ✅

修复内容

1. 网关配置修复

文件	修改内容
`ether-gateway/src/main/resources/application.yml`	使用直接URL路由替代Nacos服务发现
`ether-gateway/src/main/java/com/ether/gateway/filter/JwtAuthenticationFilter.java`	更新注释说明公开路径

2. 前端API地址修复

文件	修改内容
`ether-ui-admin/.env.development`	修改 `VITE_API_BASE_URL` 从 `8081` 到 `8080`（网关）

3. CORS配置调整

文件	修改内容
`ether-auth/src/main/java/com/ether/auth/config/CorsConfig.java`	禁用CORS配置，由网关统一处理
`ether-gateway/src/main/resources/application.yml`	启用网关全局CORS配置，统一处理跨域

4. 权限管理Controller修复

文件	修改内容
`ether-auth/src/main/java/com/ether/auth/controller/PermissionController.java`	修复createRole和createPermission方法，优先使用前端传递的projectId

服务架构

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Frontend  │────▶│   Gateway   │────▶│   Auth      │
│  :5175      │     │   :8080     │     │   :8081     │
└─────────────┘     └─────────────┘     └─────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │   Other     │
                    │   Services  │
                    └─────────────┘

CORS配置策略

网关层: 统一处理所有跨域请求
下游服务: 禁用CORS配置，避免重复添加CORS头

验证结果

功能	状态	说明
超级管理员登录	✅	成功
权限管理菜单显示	✅	成功显示所有菜单
权限管理页面访问	✅	成功
新增角色	✅	成功创建角色

2026-02-11 - 超级管理员菜单显示修复 ✅

问题描述

超级管理员登录后，左侧菜单上方显示"项目 00000000"项目选择器，并且显示了所有业务功能菜单（空间节点、业主、设备等），这是不正确的。超级管理员应该只能看到系统级管理菜单。

修复内容

1. 后端DTO修改

文件	修改内容
`ether-auth/src/main/java/com/ether/auth/dto/UserPermissionsResponse.java`	ProjectInfo 添加 `isSystem` 字段标识系统项目

2. 后端Service修改

文件	修改内容
`ether-auth/src/main/java/com/ether/auth/service/PermissionService.java`	buildProjectInfo 方法对系统项目返回特殊标识
`ether-auth/src/main/java/com/ether/auth/service/PermissionService.java`	添加 `isSystemManagementPermission` 方法过滤权限
`ether-auth/src/main/java/com/ether/auth/service/PermissionService.java`	getUserPermissions 方法只返回系统管理相关权限

3. 前端Store修改

文件	修改内容
`ether-ui-admin/src/stores/permission.ts`	添加 `isSystemAdmin` 计算属性
`ether-ui-admin/src/stores/permission.ts`	修改 `hasProjects` 排除系统项目

4. 前端路由修改

文件	修改内容
`ether-ui-admin/src/router/index.ts`	路由守卫允许系统管理员访问，不跳转到无项目页面

修复原理

后端识别系统项目: 当项目是系统项目（00000000-0000-0000-0000-000000000000）时，返回 isSystem: true
后端过滤权限: 超级管理员只返回 system: 和 msg: 开头的权限（系统管理和消息中心）
前端识别系统管理员: 通过 isSystemAdmin 计算属性判断用户是否只有系统项目
隐藏项目选择器: 当 hasProjects 为 false（只有系统项目）时，不显示项目选择器
允许访问菜单: 系统管理员可以正常访问系统管理菜单，不会被重定向到无项目页面

超级管理员菜单结构

超级管理员现在只能看到以下 6 个系统管理菜单：

序号	菜单名称	权限编码前缀
1	项目管理	system:
2	用户管理	system:
3	角色管理	system:
4	权限管理	system:
5	消息中心	msg:
6	通知配置	msg:

不再显示的业务功能菜单：

❌ 空间节点管理 (mdm:)
❌ 业主管理 (mdm:)
❌ 设备管理 (mdm:)
❌ 巡检管理 (mdm:)
❌ 访客管理 (mdm:)
❌ 收费管理 (mdm:)
❌ 工单管理 (ops:)
❌ 工单统计 (ops:)

验证结果

功能	状态	说明
超级管理员登录	✅	成功
不显示项目选择器	✅	左侧菜单上方无项目下拉框
只显示系统管理菜单	✅	仅 6 个系统管理菜单
不显示业务功能菜单	✅	无 mdm: 和 ops: 相关菜单
权限管理功能正常	✅	可以创建角色、权限等

九、历史计划归档

以下计划文档已完成，仅作历史参考：

计划文档	完成状态	说明
2026-02-05-project-initialization.md	✅ 已完成	项目初始化计划
2026-02-06-frontend-ether-ui-admin.md	✅ 已完成	前端开发计划
2026-02-06-jwt-auth-gateway-interceptor.md	✅ 已完成	JWT认证计划
2026-02-06-mdm-auth-implementation.md	✅ 已完成	MDM认证实现计划
2026-02-06-work-order-system.md	✅ 已完成	工单系统计划
2026-02-08-notification-system-plan.md	✅ 已完成	通知系统计划
2026-02-08-tdd-development-plan.md	✅ 已完成	TDD开发计划

文档维护: 本文档为项目进度的唯一权威文档，所有进度更新请直接修改此文件。

42 KiB Raw Permalink Blame History Unescape Escape

Ether 智慧物业管理平台 - 项目进度总览

〇、长时间运行智能体框架

核心文档

工作流程

会话检查清单

一、项目概述

技术架构

技术栈

二、已完成模块

1. RBAC 权限系统 ✅

2. 工单与通知系统集成 ✅

3. 前端通知中心组件 ✅

4. 费用催缴通知 ✅

5. 巡检提醒通知 ✅

6. 工单系统核心功能 ✅

7. 合同管理系统 ✅

三、模块架构

API 路由映射

四、下一阶段工作规划

Phase 1: 完善现有功能联动（已完成）✅

Phase 2: 权限与账户领域完善（已完成）✅

Phase 3: 移动端适配（已完成）✅

Phase 4: 集成中心（优先级：中）

三、功能实现进度

模块完成度统计

五、待开发任务清单

高优先级

中优先级

低优先级

六、测试统计

后端测试

七、开发规范

代码规范

数据库规范

接口规范

八、Bug修复记录

2026-02-10 - 前端页面报错修复

问题汇总

解决方案文档

2026-02-10 - 前端路由跳转问题修复

问题描述

2026-02-10 - 访客凭证功能完善

前端表单提交修复

@LogOperation 注解完善

2026-02-10 - 前端功能完善

前端验证凭证功能

前端撤销凭证功能

操作日志前端页面

权限管理前端页面

功能完整性总结

2026-02-11 - E2E测试报告

单元测试

E2E功能测试

2026-02-11 - 权限控制机制验证

权限控制实现状态

权限控制使用说明

2026-02-11 - 超级管理员权限修复

问题分析

修复方案

修复文件

系统初始化数据

2026-02-11 - 网关和CORS配置修复 ✅

修复内容

服务架构

CORS配置策略

验证结果

2026-02-11 - 超级管理员菜单显示修复 ✅

问题描述

修复内容

修复原理

超级管理员菜单结构

验证结果

九、历史计划归档

42 KiB

Raw Permalink Blame History