1434 lines
40 KiB
Markdown
1434 lines
40 KiB
Markdown
# 前端交互域 - 详细设计
|
||
|
||
**文档类型**: 详细设计文档
|
||
**生成日期**: 2026-05-18
|
||
**数据来源**: ether-admin 代码库分析 + REVERSE-AUTH.md + 路由/状态管理/API层源码
|
||
|
||
---
|
||
|
||
## 一、功能点清单
|
||
|
||
| 编号 | 模块 | 功能点 | 页面文件 | 实现状态 |
|
||
|------|------|--------|---------|---------|
|
||
| FE-001 | 认证 | 用户登录 | auth/Login.vue | 已实现 |
|
||
| FE-002 | 布局 | 主框架布局 | Layout.vue | 已实现 |
|
||
| FE-003 | 仪表盘 | 数据概览 | Dashboard.vue | 已实现 |
|
||
| FE-004 | 系统管理 | 用户管理 | system/Users.vue | 已实现 |
|
||
| FE-005 | 系统管理 | 用户详情 | system/UserDetail.vue | 已实现 |
|
||
| FE-006 | 系统管理 | 角色管理 | system/Roles.vue | 已实现 |
|
||
| FE-007 | 系统管理 | 权限管理 | system/Permissions.vue | 已实现 |
|
||
| FE-008 | 系统管理 | 组织架构 | system/Depts.vue | 已实现 |
|
||
| FE-009 | 系统管理 | 审计日志 | system/Audit.vue | 已实现 |
|
||
| FE-010 | 系统管理 | 系统设置 | system/Settings.vue | 已实现 |
|
||
| FE-011 | 项目管理 | 项目列表 | project/List.vue | 已实现 |
|
||
| FE-012 | 项目管理 | 项目选择器 | project/components/ProjectSelector.vue | 已实现 |
|
||
| FE-013 | 设备管理 | 设备列表 | equipment/EquipmentList.vue | 已实现 |
|
||
| FE-014 | 设备管理 | 设备详情 | equipment/EquipmentDetail.vue | 已实现 |
|
||
| FE-015 | 设备管理 | 设备健康预测 | equipment/EquipmentHealth.vue | 已实现 |
|
||
| FE-016 | 设备管理 | 维保计划 | equipment/MaintenancePlan.vue | 已实现 |
|
||
| FE-017 | 设备管理 | 维保工单 | equipment/MaintenanceTask.vue | 已实现 |
|
||
| FE-018 | 设备管理 | 巡检管理 | equipment/Inspection.vue | 已实现 |
|
||
| FE-019 | 点检管理 | 点检模板 | inspection/TemplateList.vue | 已实现 |
|
||
| FE-020 | 维保管理 | 维保计划 | maintenance/PlanList.vue | 已实现 |
|
||
| FE-021 | 维保管理 | 维保任务 | maintenance/TaskList.vue | 已实现 |
|
||
| FE-022 | 能耗管理 | 计量点管理 | energy/MeterList.vue | 已实现 |
|
||
| FE-023 | 能耗管理 | 能耗录入 | energy/ConsumptionRecord.vue | 已实现 |
|
||
| FE-024 | 能耗管理 | 能耗统计 | energy/EnergyStatistics.vue | 已实现 |
|
||
| FE-025 | 备件管理 | 备件列表 | sparepart/SparePartList.vue | 已实现 |
|
||
| FE-026 | 备件管理 | 备件详情 | sparepart/SparePartDetail.vue | 已实现 |
|
||
| FE-027 | 备件管理 | 入库/出库 | sparepart/StockOperation.vue | 已实现 |
|
||
| FE-028 | 工单管理 | 工单列表 | ops/WorkOrder.vue | 已实现 |
|
||
| FE-029 | 空间管理 | 空间抽屉 | space/SpaceDrawer.vue | 已实现 |
|
||
| FE-030 | 设备组件 | 照片管理 | equipment/components/PhotoManager.vue | 已实现 |
|
||
| FE-031 | 设备组件 | 文档管理 | equipment/components/DocumentManager.vue | 已实现 |
|
||
|
||
---
|
||
|
||
## 二、技术架构
|
||
|
||
### 2.1 技术栈
|
||
|
||
| 技术 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| Vue | 3.x | 前端框架（Composition API） |
|
||
| TypeScript | 5.x | 类型安全 |
|
||
| Ant Design Vue | 4.x | UI组件库 |
|
||
| Pinia | 2.x | 状态管理 |
|
||
| Vue Router | 4.x | 路由管理 |
|
||
| Vite | 5.x | 构建工具 |
|
||
| Axios | 1.x | HTTP客户端 |
|
||
| ECharts | 5.x | 图表可视化 |
|
||
|
||
### 2.2 目录结构
|
||
|
||
```
|
||
ether-admin/src/
|
||
├── api/ # API调用层
|
||
│ ├── auth.ts # 认证API
|
||
│ ├── user.ts # 用户管理API
|
||
│ ├── role.ts # 角色管理API
|
||
│ ├── permission.ts # 权限管理API
|
||
│ ├── dept.ts # 部门管理API
|
||
│ ├── audit.ts # 审计日志API
|
||
│ ├── system.ts # 系统配置API
|
||
│ ├── project.ts # 项目管理API
|
||
│ ├── space.ts # 空间管理API
|
||
│ ├── equipment.ts # 设备管理API
|
||
│ ├── equipment-health.ts # 设备健康API
|
||
│ ├── maintenance-plan.ts # 维保计划API
|
||
│ ├── maintenance-task.ts # 维保工单API
|
||
│ ├── inspection-template.ts # 点检模板API
|
||
│ ├── inspection-record.ts # 巡检记录API
|
||
│ ├── inspection-item.ts # 巡检项API
|
||
│ ├── energy.ts # 能耗管理API
|
||
│ ├── sparepart.ts # 备件管理API
|
||
│ ├── work-order.ts # 工单管理API
|
||
│ ├── maintenance.ts # 维保API（旧）
|
||
│ └── userManagement.ts # 用户管理API（旧）
|
||
├── stores/ # Pinia状态管理
|
||
│ └── user.ts # 用户状态Store
|
||
├── types/ # TypeScript类型定义
|
||
│ ├── index.ts # 全局类型
|
||
│ ├── project.ts # 项目相关类型
|
||
│ ├── space.ts # 空间相关类型
|
||
│ └── projectMember.ts # 项目成员类型
|
||
├── utils/ # 工具函数
|
||
│ └── request.ts # Axios封装
|
||
├── router/ # 路由配置
|
||
│ └── index.ts # 路由表+守卫
|
||
└── views/ # 页面组件
|
||
├── auth/ # 认证页面
|
||
├── system/ # 系统管理页面
|
||
├── project/ # 项目管理页面
|
||
├── equipment/ # 设备管理页面
|
||
├── inspection/ # 点检管理页面
|
||
├── maintenance/ # 维保管理页面
|
||
├── energy/ # 能耗管理页面
|
||
├── sparepart/ # 备件管理页面
|
||
├── ops/ # 运营管理页面
|
||
└── space/ # 空间管理页面
|
||
```
|
||
|
||
### 2.3 路由设计
|
||
|
||
#### 2.3.1 路由表
|
||
|
||
| 路径 | 路由名 | 组件 | 标题 | 权限要求 |
|
||
|------|--------|------|------|---------|
|
||
| `/login` | Login | auth/Login.vue | 登录 | 无 |
|
||
| `/dashboard` | Dashboard | Dashboard.vue | 仪表盘 | 已登录 |
|
||
| `/system/users` | Users | system/Users.vue | 用户管理 | SYS_ADMIN |
|
||
| `/system/roles` | Roles | system/Roles.vue | 角色管理 | SYS_ADMIN |
|
||
| `/system/permissions` | Permissions | system/Permissions.vue | 权限管理 | SYS_ADMIN |
|
||
| `/system/depts` | Depts | system/Depts.vue | 组织架构 | SYS_ADMIN |
|
||
| `/system/audit` | Audit | system/Audit.vue | 审计日志 | SYS_ADMIN |
|
||
| `/system/settings` | Settings | system/Settings.vue | 系统设置 | SYS_ADMIN |
|
||
| `/project/list` | ProjectList | project/List.vue | 项目管理 | 已登录 |
|
||
| `/equipment/list` | EquipmentList | equipment/EquipmentList.vue | 设备管理 | 已登录 |
|
||
| `/equipment/detail/:id` | EquipmentDetail | equipment/EquipmentDetail.vue | 设备详情 | 已登录 |
|
||
| `/equipment/health` | EquipmentHealth | equipment/EquipmentHealth.vue | 设备健康预测 | 已登录 |
|
||
| `/equipment/maintenance-plan` | MaintenancePlan | equipment/MaintenancePlan.vue | 维保计划 | 已登录 |
|
||
| `/equipment/maintenance-task` | MaintenanceTask | equipment/MaintenanceTask.vue | 维保工单 | 已登录 |
|
||
| `/equipment/inspection` | Inspection | equipment/Inspection.vue | 巡检管理 | 已登录 |
|
||
| `/inspection/templates` | InspectionTemplates | inspection/TemplateList.vue | 点检模板 | 已登录 |
|
||
| `/maintenance/plans` | MaintenancePlans | maintenance/PlanList.vue | 维保计划 | 已登录 |
|
||
| `/maintenance/tasks` | MaintenanceTasks | maintenance/TaskList.vue | 维保任务 | 已登录 |
|
||
| `/energy/meters` | EnergyMeters | energy/MeterList.vue | 计量点管理 | 已登录 |
|
||
| `/energy/consumption` | EnergyConsumption | energy/ConsumptionRecord.vue | 能耗录入 | 已登录 |
|
||
| `/energy/statistics` | EnergyStatistics | energy/EnergyStatistics.vue | 能耗统计 | 已登录 |
|
||
| `/sparepart/list` | SparePartList | sparepart/SparePartList.vue | 备件管理 | 已登录 |
|
||
| `/sparepart/detail/:id` | SparePartDetail | sparepart/SparePartDetail.vue | 备件详情 | 已登录 |
|
||
| `/sparepart/stock/in` | SparePartInStock | sparepart/StockOperation.vue | 备件入库 | 已登录 |
|
||
| `/sparepart/stock/out` | SparePartOutStock | sparepart/StockOperation.vue | 备件出库 | 已登录 |
|
||
|
||
#### 2.3.2 路由守卫
|
||
|
||
```typescript
|
||
router.beforeEach((to, _from, next) => {
|
||
const userStore = useUserStore()
|
||
|
||
// 1. 白名单路由直接放行（/login）
|
||
if (to.path === '/login') return next()
|
||
|
||
// 2. 未登录跳转登录页
|
||
if (!userStore.isLoggedIn()) return next('/login')
|
||
|
||
// 3. 检查角色权限（meta.requiredRoles）
|
||
const requiredRoles = to.meta?.requiredRoles as string[] | undefined
|
||
if (requiredRoles?.length && !userStore.hasAnyRole(requiredRoles)) {
|
||
return next({ path: '/', query: { from: to.fullPath } })
|
||
}
|
||
|
||
next()
|
||
})
|
||
```
|
||
|
||
#### 2.3.3 懒加载策略
|
||
|
||
所有路由组件均使用动态导入（`() => import()`），Vite自动代码分割：
|
||
|
||
```typescript
|
||
component: () => import('@/views/system/Users.vue')
|
||
```
|
||
|
||
#### 2.3.4 权限控制
|
||
|
||
- **路由级权限**: 通过 `meta.requiredRoles` 声明所需角色，守卫中校验
|
||
- **系统管理模块**: 统一要求 `SYS_ADMIN` 角色
|
||
- **业务模块**: 仅要求已登录（无特定角色限制）
|
||
- **无权限处理**: 重定向到首页，通过 query.from 记录来源路径
|
||
|
||
---
|
||
|
||
### 2.4 状态管理
|
||
|
||
#### 2.4.1 Pinia Store设计
|
||
|
||
**useUserStore**（当前唯一Store）
|
||
|
||
| 状态 | 类型 | 说明 | 持久化 |
|
||
|------|------|------|--------|
|
||
| token | `ref<string>` | JWT Token | localStorage |
|
||
| userInfo | `ref<{username, realName} \| null>` | 用户基本信息 | localStorage |
|
||
| roles | `ref<string[]>` | 角色列表 | localStorage |
|
||
|
||
| 计算属性 | 类型 | 说明 |
|
||
|---------|------|------|
|
||
| isAdmin | `computed<boolean>` | 是否SYS_ADMIN角色 |
|
||
|
||
| 方法 | 参数 | 返回值 | 说明 |
|
||
|------|------|--------|------|
|
||
| hasRole | role: string | boolean | 判断是否拥有指定角色 |
|
||
| hasAnyRole | checkRoles: string[] | boolean | 判断是否拥有任一角色 |
|
||
| login | data: LoginRequest | Promise<void> | 登录并存储Token/角色/用户信息 |
|
||
| logout | -- | Promise<void> | 登出并清除所有状态 |
|
||
| isLoggedIn | -- | boolean | 检查登录状态（含Token过期校验） |
|
||
| initFromStorage | -- | void | 从localStorage恢复状态 |
|
||
|
||
#### 2.4.2 持久化策略
|
||
|
||
| 数据 | 存储位置 | Key | 格式 |
|
||
|------|---------|-----|------|
|
||
| Token | localStorage | `token` | 字符串 |
|
||
| 用户信息 | localStorage | `userInfo` | JSON字符串 |
|
||
| 角色列表 | localStorage | `roles` | JSON数组字符串 |
|
||
|
||
**Token过期校验**:
|
||
|
||
```typescript
|
||
isLoggedIn() {
|
||
// 1. 检查Token存在性
|
||
// 2. 检查JWT三段式格式
|
||
// 3. 解析payload.exp检查过期
|
||
// 4. 过期则自动logout
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2.5 API层设计
|
||
|
||
#### 2.5.1 请求封装（request.ts）
|
||
|
||
**Axios实例配置**:
|
||
|
||
| 配置项 | 值 | 说明 |
|
||
|--------|-----|------|
|
||
| baseURL | `VITE_API_BASE_URL` | 环境变量配置 |
|
||
| timeout | `VITE_REQUEST_TIMEOUT \|\| 10000` | 请求超时 |
|
||
|
||
**请求拦截器**:
|
||
|
||
1. 从localStorage获取Token
|
||
2. 注入 `Authorization: Bearer {token}` Header
|
||
3. 初始化重试计数器 `__retryCount`
|
||
|
||
**响应拦截器**:
|
||
|
||
1. **业务错误处理**: 检查 `ApiResponse.code`，非200/0/00000视为业务错误
|
||
2. **HTTP错误分类处理**:
|
||
|
||
| 状态码 | 处理方式 |
|
||
|--------|---------|
|
||
| 400 | message.error("请求参数错误") |
|
||
| 401 | 清除Token，跳转/login |
|
||
| 403 | message.error("没有权限执行此操作") |
|
||
| 404 | message.error("请求的资源不存在") |
|
||
| 422 | message.error("数据验证失败") |
|
||
| 429 | message.error("操作太频繁") |
|
||
| 500 | message.error("服务器内部错误") |
|
||
| 502/503/504 | message.error("服务暂时不可用") |
|
||
|
||
3. **网络错误处理**: ERR_NETWORK / ECONNABORTED / ERR_CANCELED
|
||
4. **自动重试**: GET请求在5xx/网络错误/超时时自动重试，最多2次，间隔1秒
|
||
|
||
#### 2.5.2 错误处理策略
|
||
|
||
| 错误类型 | 处理方式 | 用户感知 |
|
||
|---------|---------|---------|
|
||
| 业务错误(ApiResponse.code != 0) | message.error(res.message) | 顶部错误提示 |
|
||
| 401未授权 | 清除Token + 跳转登录 | 自动跳转登录页 |
|
||
| 403无权限 | message.error | 顶部错误提示 |
|
||
| 网络错误 | message.error | 顶部错误提示 |
|
||
| 请求超时 | 自动重试1次 + message.error | 顶部错误提示 |
|
||
| 请求取消 | 静默处理 | 无感知 |
|
||
|
||
#### 2.5.3 类型安全
|
||
|
||
**统一响应类型**:
|
||
|
||
```typescript
|
||
interface ApiResponse<T> {
|
||
code: number
|
||
message: string
|
||
data: T
|
||
}
|
||
```
|
||
|
||
**API函数类型约束**: 所有API函数显式指定 `ApiResponse<T>` 泛型参数
|
||
|
||
```typescript
|
||
export const getUsers = (params?) => {
|
||
return request.get<ApiResponse<any>>('/api/auth/users', { params })
|
||
}
|
||
```
|
||
|
||
#### 2.5.4 分页封装
|
||
|
||
**分页响应类型**（多版本共存）:
|
||
|
||
```typescript
|
||
// 通用版本（project.ts定义）
|
||
interface PageResponse<T> {
|
||
content: T[]
|
||
totalElements: number
|
||
totalPages: number
|
||
size: number
|
||
number: number
|
||
first: boolean
|
||
last: boolean
|
||
empty: boolean
|
||
}
|
||
|
||
// 工单版本（work-order.ts定义）
|
||
interface PageResponse<T> {
|
||
content: T[]
|
||
page: number
|
||
size: number
|
||
totalElements: number
|
||
totalPages: number
|
||
first: boolean
|
||
last: boolean
|
||
}
|
||
```
|
||
|
||
**分页请求参数**:
|
||
|
||
```typescript
|
||
params: { page?: number; size?: number; keyword?: string; status?: string }
|
||
```
|
||
|
||
---
|
||
|
||
## 三、页面设计
|
||
|
||
### 3.1 登录页
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/login` |
|
||
| 路由名 | Login |
|
||
| 组件 | `views/auth/Login.vue` |
|
||
| 权限要求 | 无 |
|
||
| 布局 | 独立页面（不使用Layout） |
|
||
|
||
**功能描述**: 用户名+密码登录，调用 `POST /api/auth/login`
|
||
|
||
**核心组件**: Ant Design Vue Form + Input + Button
|
||
|
||
**数据流**:
|
||
1. 用户输入用户名和密码
|
||
2. 调用 `userStore.login({username, password})`
|
||
3. login内部调用 `auth.ts -> loginApi()`
|
||
4. 成功后存储Token/角色/用户信息到localStorage
|
||
5. 路由跳转到 `/dashboard`
|
||
|
||
---
|
||
|
||
### 3.2 仪表盘
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/dashboard` |
|
||
| 路由名 | Dashboard |
|
||
| 组件 | `views/Dashboard.vue` |
|
||
| 权限要求 | 已登录 |
|
||
|
||
**功能描述**: 系统数据概览，展示关键指标
|
||
|
||
**核心组件**: Ant Design Vue Card + Statistic + ECharts图表
|
||
|
||
**数据流**: 汇总各模块统计数据
|
||
|
||
---
|
||
|
||
### 3.3 用户管理
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/system/users` |
|
||
| 路由名 | Users |
|
||
| 组件 | `views/system/Users.vue` |
|
||
| 权限要求 | SYS_ADMIN |
|
||
|
||
**功能描述**: 用户列表CRUD、角色分配、项目关联
|
||
|
||
**核心组件**: Table + Modal + Form + Select
|
||
|
||
**数据流**:
|
||
- 列表: `GET /api/auth/users` -> Table渲染
|
||
- 创建: Form提交 -> `POST /api/auth/users`
|
||
- 编辑: Form提交 -> `PUT /api/auth/users/{id}`
|
||
- 删除: 确认弹窗 -> `DELETE /api/auth/users/{id}`
|
||
- 角色分配: 多选Modal -> `POST /api/auth/users/{id}/roles`
|
||
- 项目查看: `GET /api/auth/users/{id}/projects`
|
||
|
||
---
|
||
|
||
### 3.4 用户详情
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | 从用户管理跳转 |
|
||
| 路由名 | UserDetail |
|
||
| 组件 | `views/system/UserDetail.vue` |
|
||
| 权限要求 | SYS_ADMIN |
|
||
|
||
**功能描述**: 用户详细信息查看、密码修改
|
||
|
||
**核心组件**: Descriptions + Form + Modal
|
||
|
||
**数据流**:
|
||
- 详情: `GET /api/auth/users/{id}`
|
||
- 修改密码: `PUT /api/auth/users/{id}/password`
|
||
|
||
---
|
||
|
||
### 3.5 角色管理
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/system/roles` |
|
||
| 路由名 | Roles |
|
||
| 组件 | `views/system/Roles.vue` |
|
||
| 权限要求 | SYS_ADMIN |
|
||
|
||
**功能描述**: 角色CRUD、权限分配
|
||
|
||
**核心组件**: Table + Modal + Form + Tree（权限树）
|
||
|
||
**数据流**:
|
||
- 列表: `GET /api/auth/roles`
|
||
- 创建: `POST /api/auth/roles`
|
||
- 权限分配: `POST /api/auth/roles/{id}/permissions`
|
||
- 角色用户: `GET /api/auth/roles/{id}/users`
|
||
|
||
---
|
||
|
||
### 3.6 权限管理
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/system/permissions` |
|
||
| 路由名 | Permissions |
|
||
| 组件 | `views/system/Permissions.vue` |
|
||
| 权限要求 | SYS_ADMIN |
|
||
|
||
**功能描述**: 权限CRUD、按类型筛选
|
||
|
||
**核心组件**: Table + Modal + Form + Select（类型筛选）
|
||
|
||
**数据流**:
|
||
- 列表: `GET /api/auth/permissions`
|
||
- 创建: `POST /api/auth/permissions`
|
||
- 按模块查询: `GET /api/auth/permissions/module/{module}`
|
||
|
||
---
|
||
|
||
### 3.7 组织架构
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/system/depts` |
|
||
| 路由名 | Depts |
|
||
| 组件 | `views/system/Depts.vue` |
|
||
| 权限要求 | SYS_ADMIN |
|
||
|
||
**功能描述**: 部门树展示、CRUD、成员查看
|
||
|
||
**核心组件**: Tree + Modal + Form + Table
|
||
|
||
**数据流**:
|
||
- 部门树: `GET /api/auth/depts/tree`
|
||
- 创建: `POST /api/auth/depts`
|
||
- 成员: `GET /api/auth/depts/{deptId}/members`
|
||
- 按类型: `GET /api/auth/depts/by-type/{deptType}`
|
||
|
||
---
|
||
|
||
### 3.8 审计日志
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/system/audit` |
|
||
| 路由名 | Audit |
|
||
| 组件 | `views/system/Audit.vue` |
|
||
| 权限要求 | SYS_ADMIN |
|
||
|
||
**功能描述**: 操作日志查询、统计
|
||
|
||
**核心组件**: Table + DatePicker + Select（模块/操作类型）
|
||
|
||
**数据流**:
|
||
- 日志列表: `GET /api/audit-logs` (分页+筛选)
|
||
- 模块列表: `GET /api/audit-logs/modules`
|
||
- 操作类型: `GET /api/audit-logs/actions`
|
||
- 统计: `GET /api/audit-logs/stats`
|
||
|
||
---
|
||
|
||
### 3.9 系统设置
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/system/settings` |
|
||
| 路由名 | Settings |
|
||
| 组件 | `views/system/Settings.vue` |
|
||
| 权限要求 | SYS_ADMIN |
|
||
|
||
**功能描述**: 系统配置键值对管理
|
||
|
||
**核心组件**: Form + Input + Button
|
||
|
||
**数据流**:
|
||
- 获取配置: `GET /api/config`
|
||
- 更新配置: `PUT /api/config`
|
||
|
||
---
|
||
|
||
### 3.10 项目管理
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/project/list` |
|
||
| 路由名 | ProjectList |
|
||
| 组件 | `views/project/List.vue` |
|
||
| 权限要求 | 已登录 |
|
||
|
||
**功能描述**: 项目CRUD、状态管理、成员管理、配置管理
|
||
|
||
**核心组件**: Table + Modal + Form + Tabs
|
||
|
||
**数据流**:
|
||
- 列表: `GET /api/mdm/projects` (分页)
|
||
- 创建: `POST /api/mdm/projects`
|
||
- 状态变更: `PUT /api/mdm/projects/{id}/status`
|
||
- 成员管理: `GET/POST/DELETE /api/auth/projects/{projectId}/members`
|
||
- 编码生成: `GET /api/mdm/projects/generate-code`
|
||
- 删除检查: `GET /api/mdm/projects/{id}/delete-check`
|
||
- 配置: `GET/PUT /api/mdm/projects/{id}/config`
|
||
- 选择器: `GET /api/mdm/projects/selector`
|
||
|
||
---
|
||
|
||
### 3.11 设备列表
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/equipment/list` |
|
||
| 路由名 | EquipmentList |
|
||
| 组件 | `views/equipment/EquipmentList.vue` |
|
||
| 权限要求 | 已登录 |
|
||
|
||
**功能描述**: 设备CRUD、按项目/类型/归属筛选、导入导出
|
||
|
||
**核心组件**: Table + Modal + Form + Upload + Select
|
||
|
||
**数据流**:
|
||
- 列表: `GET /api/asset/equipment/by-project/{projectId}`
|
||
- 创建: `POST /api/asset/equipment`
|
||
- 按类型: `GET /api/asset/equipment/by-type`
|
||
- 按归属: `GET /api/asset/equipment/by-ownership`
|
||
- 导入: `POST /api/asset/equipment/import`
|
||
- 导出: `GET /api/asset/equipment/export`
|
||
- 统计: `GET /api/asset/equipment/stats/by-type/{projectId}`
|
||
|
||
---
|
||
|
||
### 3.12 设备详情
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/equipment/detail/:id` |
|
||
| 路由名 | EquipmentDetail |
|
||
| 组件 | `views/equipment/EquipmentDetail.vue` |
|
||
| 权限要求 | 已登录 |
|
||
|
||
**功能描述**: 设备完整信息展示、扩展信息编辑、照片/文档管理
|
||
|
||
**核心组件**: Tabs + Descriptions + Form + PhotoManager + DocumentManager
|
||
|
||
**数据流**:
|
||
- 详情: `GET /api/asset/equipment/{id}`
|
||
- 电梯扩展: `GET/PUT /api/asset/equipment/{id}/elevator`
|
||
- 暖通扩展: `GET/PUT /api/asset/equipment/{id}/hvac`
|
||
- 能源扩展: `GET/PUT /api/asset/equipment/{id}/energy`
|
||
- 消防扩展: `GET/PUT /api/asset/equipment/{id}/fire`
|
||
|
||
---
|
||
|
||
### 3.13 设备健康预测
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/equipment/health` |
|
||
| 路由名 | EquipmentHealth |
|
||
| 组件 | `views/equipment/EquipmentHealth.vue` |
|
||
| 权限要求 | 已登录 |
|
||
|
||
**功能描述**: 设备健康度评分、故障历史、MTBF/MTTR分析
|
||
|
||
**核心组件**: Card + ECharts + Table
|
||
|
||
**数据流**:
|
||
- 健康度: `GET /api/asset/equipment-health/{equipmentId}`
|
||
- 历史趋势: `GET /api/asset/equipment-health/{id}/history`
|
||
- 计算: `POST /api/asset/equipment-health/calculate`
|
||
- 故障历史: `GET /api/asset/equipment-health/failure-history/{id}`
|
||
- MTBF: `GET /api/asset/equipment-health/mtbf/{id}`
|
||
- MTTR: `GET /api/asset/equipment-health/mttr/{id}`
|
||
|
||
---
|
||
|
||
### 3.14 维保计划（设备模块）
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/equipment/maintenance-plan` |
|
||
| 路由名 | MaintenancePlan |
|
||
| 组件 | `views/equipment/MaintenancePlan.vue` |
|
||
| 权限要求 | 已登录 |
|
||
|
||
**功能描述**: 维保计划CRUD
|
||
|
||
**核心组件**: Table + Modal + Form
|
||
|
||
**数据流**:
|
||
- 列表: `GET /api/mdm/maintenance-plans?projectId=`
|
||
- 创建: `POST /api/mdm/maintenance-plans`
|
||
- 更新: `PUT /api/mdm/maintenance-plans/{id}`
|
||
- 删除: `DELETE /api/mdm/maintenance-plans/{id}`
|
||
|
||
---
|
||
|
||
### 3.15 维保工单（设备模块）
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/equipment/maintenance-task` |
|
||
| 路由名 | MaintenanceTask |
|
||
| 组件 | `views/equipment/MaintenanceTask.vue` |
|
||
| 权限要求 | 已登录 |
|
||
|
||
**功能描述**: 维保工单管理、状态流转
|
||
|
||
**核心组件**: Table + Modal + Form + Steps
|
||
|
||
**数据流**:
|
||
- 列表: `GET /api/ops/maintenance-tasks?projectId=`
|
||
- 派单: `POST /api/ops/maintenance-tasks/{id}/assign`
|
||
- 开始: `POST /api/ops/maintenance-tasks/{id}/start`
|
||
- 完成: `POST /api/ops/maintenance-tasks/{id}/complete-details`
|
||
- 验收: `POST /api/ops/maintenance-tasks/{id}/verify`
|
||
- 取消: `POST /api/ops/maintenance-tasks/{id}/cancel`
|
||
- 统计: `GET /api/ops/maintenance-tasks/stats`
|
||
|
||
---
|
||
|
||
### 3.16 巡检管理（设备模块）
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/equipment/inspection` |
|
||
| 路由名 | Inspection |
|
||
| 组件 | `views/equipment/Inspection.vue` |
|
||
| 权限要求 | 已登录 |
|
||
|
||
**功能描述**: 巡检记录管理
|
||
|
||
**核心组件**: Table + Modal + Form
|
||
|
||
**数据流**:
|
||
- 记录列表: `GET /api/mdm/inspection-records?projectId=`
|
||
- 创建: `POST /api/mdm/inspection-records`
|
||
- 完成: `POST /api/mdm/inspection-records/{id}/complete`
|
||
|
||
---
|
||
|
||
### 3.17 点检模板
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/inspection/templates` |
|
||
| 路由名 | InspectionTemplates |
|
||
| 组件 | `views/inspection/TemplateList.vue` |
|
||
| 权限要求 | 已登录 |
|
||
|
||
**功能描述**: 点检模板CRUD、检查项管理
|
||
|
||
**核心组件**: Table + Modal + Form + DynamicFormItems
|
||
|
||
**数据流**:
|
||
- 列表: `GET /api/ops/inspection-templates?projectId=`
|
||
- 创建: `POST /api/ops/inspection-templates`
|
||
- 更新: `PUT /api/ops/inspection-templates/{id}`
|
||
- 删除: `DELETE /api/ops/inspection-templates/{id}`
|
||
|
||
---
|
||
|
||
### 3.18 维保计划（维保模块）
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/maintenance/plans` |
|
||
| 路由名 | MaintenancePlans |
|
||
| 组件 | `views/maintenance/PlanList.vue` |
|
||
| 权限要求 | 已登录 |
|
||
|
||
**功能描述**: 维保计划列表（与设备模块维保计划共享API）
|
||
|
||
---
|
||
|
||
### 3.19 维保任务（维保模块）
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/maintenance/tasks` |
|
||
| 路由名 | MaintenanceTasks |
|
||
| 组件 | `views/maintenance/TaskList.vue` |
|
||
| 权限要求 | 已登录 |
|
||
|
||
**功能描述**: 维保任务列表（与设备模块维保工单共享API）
|
||
|
||
---
|
||
|
||
### 3.20 计量点管理
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/energy/meters` |
|
||
| 路由名 | EnergyMeters |
|
||
| 组件 | `views/energy/MeterList.vue` |
|
||
| 权限要求 | 已登录 |
|
||
|
||
**功能描述**: 能源计量点CRUD
|
||
|
||
**核心组件**: Table + Modal + Form + Select
|
||
|
||
**数据流**:
|
||
- 列表: `GET /api/ops/energy/meters?projectId=`
|
||
- 创建: `POST /api/ops/energy/meters`
|
||
- 更新: `PUT /api/ops/energy/meters/{id}`
|
||
- 删除: `DELETE /api/ops/energy/meters/{id}`
|
||
|
||
---
|
||
|
||
### 3.21 能耗录入
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/energy/consumption` |
|
||
| 路由名 | EnergyConsumption |
|
||
| 组件 | `views/energy/ConsumptionRecord.vue` |
|
||
| 权限要求 | 已登录 |
|
||
|
||
**功能描述**: 能耗数据录入与查看
|
||
|
||
**核心组件**: Table + Modal + Form + InputNumber
|
||
|
||
**数据流**:
|
||
- 录入: `POST /api/ops/energy/consumption`
|
||
- 记录: `GET /api/ops/energy/consumption/{meterId}`
|
||
|
||
---
|
||
|
||
### 3.22 能耗统计
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/energy/statistics` |
|
||
| 路由名 | EnergyStatistics |
|
||
| 组件 | `views/energy/EnergyStatistics.vue` |
|
||
| 权限要求 | 已登录 |
|
||
|
||
**功能描述**: 按类型统计、单方能耗
|
||
|
||
**核心组件**: Card + ECharts + DatePicker
|
||
|
||
**数据流**:
|
||
- 按类型统计: `GET /api/ops/energy/statistics/by-type`
|
||
- 单方能耗: `GET /api/ops/energy/statistics/unit-consumption`
|
||
|
||
---
|
||
|
||
### 3.23 备件列表
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/sparepart/list` |
|
||
| 路由名 | SparePartList |
|
||
| 组件 | `views/sparepart/SparePartList.vue` |
|
||
| 权限要求 | 已登录 |
|
||
|
||
**功能描述**: 备件CRUD、低库存预警
|
||
|
||
**核心组件**: Table + Modal + Form + Badge
|
||
|
||
**数据流**:
|
||
- 列表: `GET /api/ops/spare-parts?projectId=`
|
||
- 创建: `POST /api/ops/spare-parts`
|
||
- 低库存: `GET /api/ops/spare-parts/low-stock`
|
||
|
||
---
|
||
|
||
### 3.24 备件详情
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/sparepart/detail/:id` |
|
||
| 路由名 | SparePartDetail |
|
||
| 组件 | `views/sparepart/SparePartDetail.vue` |
|
||
| 权限要求 | 已登录 |
|
||
|
||
**功能描述**: 备件详情、库存记录
|
||
|
||
**核心组件**: Descriptions + Table
|
||
|
||
**数据流**:
|
||
- 详情: `GET /api/ops/spare-parts/{id}`
|
||
- 记录: `GET /api/ops/spare-parts/{id}/records`
|
||
|
||
---
|
||
|
||
### 3.25 入库/出库
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | `/sparepart/stock/in` 或 `/sparepart/stock/out` |
|
||
| 路由名 | SparePartInStock / SparePartOutStock |
|
||
| 组件 | `views/sparepart/StockOperation.vue`（共用） |
|
||
| 权限要求 | 已登录 |
|
||
|
||
**功能描述**: 备件入库/出库操作
|
||
|
||
**核心组件**: Form + InputNumber + Select
|
||
|
||
**数据流**:
|
||
- 入库: `POST /api/ops/spare-parts/in-stock`
|
||
- 出库: `POST /api/ops/spare-parts/out-stock`
|
||
|
||
---
|
||
|
||
### 3.26 工单管理
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | 通过路由未直接注册，从其他入口跳转 |
|
||
| 路由名 | WorkOrder |
|
||
| 组件 | `views/ops/WorkOrder.vue` |
|
||
| 权限要求 | 已登录 |
|
||
|
||
**功能描述**: 工单全生命周期管理
|
||
|
||
**核心组件**: Table + Modal + Form + Steps + Rate
|
||
|
||
**数据流**:
|
||
- 列表: `GET /api/wo/work-orders` (分页+多条件筛选)
|
||
- 创建: `POST /api/wo/work-orders`
|
||
- 派单: `POST /api/wo/work-orders/{id}/assign`
|
||
- 开始: `POST /api/wo/work-orders/{id}/start`
|
||
- 完成: `POST /api/wo/work-orders/{id}/complete`
|
||
- 验收: `POST /api/wo/work-orders/{id}/verify`
|
||
- 挂起: `POST /api/wo/work-orders/{id}/suspend`
|
||
- 恢复: `POST /api/wo/work-orders/{id}/resume`
|
||
- 退回: `POST /api/wo/work-orders/{id}/return`
|
||
- 取消: `POST /api/wo/work-orders/{id}/cancel`
|
||
- 统计: `GET /api/wo/work-orders/stats`
|
||
- 工单项: `GET/POST /api/wo/work-orders/{id}/items`
|
||
|
||
---
|
||
|
||
### 3.27 空间抽屉
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 页面路径 | 作为组件被其他页面引用 |
|
||
| 组件 | `views/space/SpaceDrawer.vue` |
|
||
| 权限要求 | 已登录 |
|
||
|
||
**功能描述**: 空间树选择抽屉
|
||
|
||
**核心组件**: Drawer + Tree
|
||
|
||
**数据流**:
|
||
- 空间树: `GET /api/mdm/space-nodes/project/{projectId}/tree`
|
||
|
||
---
|
||
|
||
## 四、组件设计
|
||
|
||
### 4.1 公共组件
|
||
|
||
#### 4.1.1 Layout（主框架布局）
|
||
|
||
**文件**: `views/Layout.vue`
|
||
|
||
**功能**: 系统主布局框架，包含侧边栏菜单、顶部导航、内容区域
|
||
|
||
**核心结构**:
|
||
- 左侧：侧边栏菜单（Ant Design Vue Layout.Sider + Menu）
|
||
- 顶部：Header（项目选择器、用户信息、登出按钮）
|
||
- 中间：Content（router-view渲染区域）
|
||
|
||
**菜单分组**:
|
||
|
||
| 菜单组 | 子菜单 |
|
||
|--------|--------|
|
||
| 仪表盘 | Dashboard |
|
||
| 系统管理 | 用户管理、角色管理、权限管理、组织架构、审计日志、系统设置 |
|
||
| 项目管理 | 项目列表 |
|
||
| 设备管理 | 设备列表、设备健康预测、维保计划、维保工单、巡检管理 |
|
||
| 点检管理 | 点检模板 |
|
||
| 维保管理 | 维保计划、维保任务 |
|
||
| 能耗管理 | 计量点管理、能耗录入、能耗统计 |
|
||
| 备件管理 | 备件列表、备件入库、备件出库 |
|
||
|
||
#### 4.1.2 ProjectSelector（项目选择器）
|
||
|
||
**文件**: `views/project/components/ProjectSelector.vue`
|
||
|
||
**功能**: 全局项目切换组件，切换后所有API请求自动携带新项目ID
|
||
|
||
**核心交互**:
|
||
1. 下拉选择项目
|
||
2. 切换后设置 `X-Project-ID` Header
|
||
3. 刷新当前页面数据
|
||
|
||
**数据流**:
|
||
- 项目列表: `GET /api/mdm/projects/selector`
|
||
|
||
#### 4.1.3 SpaceDrawer（空间选择抽屉）
|
||
|
||
**文件**: `views/space/spaceDrawer.vue`
|
||
|
||
**功能**: 树形空间选择器，用于设备关联空间、账单关联房产等场景
|
||
|
||
**核心交互**:
|
||
1. 点击触发打开Drawer
|
||
2. 加载空间树
|
||
3. 点击节点选中
|
||
4. 确认后返回选中的SpaceNode
|
||
|
||
**数据流**:
|
||
- 空间树: `GET /api/mdm/space-nodes/project/{projectId}/tree`
|
||
|
||
---
|
||
|
||
### 4.2 业务组件
|
||
|
||
#### 4.2.1 PhotoManager（照片管理）
|
||
|
||
**文件**: `views/equipment/components/PhotoManager.vue`
|
||
|
||
**功能**: 设备照片上传、预览、删除
|
||
|
||
**核心交互**:
|
||
1. 按类型分类（外观、铭牌、安装位置、环境）
|
||
2. 上传照片（调用uploadFile模拟）
|
||
3. 预览大图
|
||
4. 删除照片
|
||
|
||
**数据结构**:
|
||
|
||
```typescript
|
||
interface EquipmentPhoto {
|
||
type: string // 照片类型
|
||
url: string // 照片URL
|
||
remark?: string // 备注
|
||
}
|
||
```
|
||
|
||
#### 4.2.2 DocumentManager（文档管理）
|
||
|
||
**文件**: `views/equipment/components/DocumentManager.vue`
|
||
|
||
**功能**: 设备电子文档上传、下载、删除
|
||
|
||
**核心交互**:
|
||
1. 按类型分类（手册manual、证书certificate、合同contract、其他other）
|
||
2. 上传文档
|
||
3. 下载文档
|
||
4. 删除文档
|
||
|
||
**数据结构**:
|
||
|
||
```typescript
|
||
interface EquipmentDocument {
|
||
name: string
|
||
url: string
|
||
size?: number
|
||
type: 'manual' | 'certificate' | 'contract' | 'other'
|
||
remark?: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、类型定义
|
||
|
||
### 5.1 全局类型（types/index.ts）
|
||
|
||
```typescript
|
||
// API统一响应
|
||
interface ApiResponse<T> {
|
||
code: number
|
||
message: string
|
||
data: T
|
||
}
|
||
|
||
// 分页信息
|
||
interface PaginationInfo {
|
||
current: number
|
||
pageSize: number
|
||
total?: number
|
||
}
|
||
|
||
// 登录请求
|
||
interface LoginRequest {
|
||
username: string
|
||
password: string
|
||
}
|
||
|
||
// 登录响应
|
||
interface LoginResponse {
|
||
token: string
|
||
userId: string
|
||
username: string
|
||
realName: string
|
||
roles: string[]
|
||
}
|
||
|
||
// 用户
|
||
interface User {
|
||
id: string
|
||
username: string
|
||
realName?: string
|
||
phone?: string
|
||
email?: string
|
||
avatar?: string
|
||
status: 'ACTIVE' | 'LOCKED' | 'DISABLED'
|
||
lastLoginTime?: string
|
||
lastLoginIp?: string
|
||
roles?: Role[]
|
||
employeeNo?: string
|
||
position?: string
|
||
staffType?: StaffType
|
||
projectId?: string
|
||
}
|
||
|
||
// 角色
|
||
interface Role {
|
||
id: string
|
||
code: string
|
||
name: string
|
||
description?: string
|
||
type?: string
|
||
status: 'ACTIVE' | 'DISABLED'
|
||
dataScope?: string
|
||
permissions?: Permission[]
|
||
}
|
||
|
||
// 权限
|
||
interface Permission {
|
||
id: string
|
||
code: string
|
||
name: string
|
||
type: string
|
||
path?: string
|
||
component?: string
|
||
icon?: string
|
||
resource?: string
|
||
method?: string
|
||
description?: string
|
||
sortOrder?: number
|
||
visible?: boolean
|
||
}
|
||
|
||
// 项目
|
||
interface Project {
|
||
id: string
|
||
code: string
|
||
name: string
|
||
description?: string
|
||
address?: string
|
||
projectType?: 'RESIDENTIAL' | 'OFFICE' | 'INDUSTRIAL_PARK'
|
||
province?: string
|
||
city?: string
|
||
district?: string
|
||
status: 'ACTIVE' | 'DISABLED' | 'PENDING' | 'ARCHIVED'
|
||
createdAt?: string
|
||
updatedAt?: string
|
||
}
|
||
```
|
||
|
||
### 5.2 各模块类型
|
||
|
||
#### 5.2.1 用户相关类型
|
||
|
||
```typescript
|
||
type UserType = 'ENTERPRISE' | 'PROJECT_STAFF' | 'RESIDENT' | 'CUSTOMER'
|
||
type EmployeeCategory = 'ENTERPRISE' | 'MANAGEMENT'
|
||
type StaffType = 'SECURITY' | 'CLEANING' | 'GARDEN' | 'MAINTENANCE' | 'CUSTOMER_SERVICE' | 'GENERAL'
|
||
type ResidentType = 'OWNER' | 'FAMILY' | 'TENANT'
|
||
```
|
||
|
||
#### 5.2.2 项目相关类型（types/project.ts）
|
||
|
||
```typescript
|
||
type ProjectStatus = 'ACTIVE' | 'DISABLED' | 'PENDING' | 'ARCHIVED'
|
||
type ProjectType = 'RESIDENTIAL' | 'OFFICE' | 'INDUSTRIAL_PARK'
|
||
|
||
interface ProjectQuery {
|
||
keyword?: string
|
||
status?: ProjectStatus
|
||
page?: number
|
||
size?: number
|
||
sort?: string
|
||
}
|
||
|
||
interface PageResponse<T> {
|
||
content: T[]
|
||
totalElements: number
|
||
totalPages: number
|
||
size: number
|
||
number: number
|
||
first: boolean
|
||
last: boolean
|
||
empty: boolean
|
||
}
|
||
|
||
interface ProjectStatistics {
|
||
memberCount: number
|
||
buildingCount: number
|
||
roomCount: number
|
||
ownerCount: number
|
||
tenantCount: number
|
||
activeTaskCount: number
|
||
completedTaskCount: number
|
||
}
|
||
|
||
interface ProjectMember {
|
||
id: string
|
||
projectId: string
|
||
userId: string
|
||
userName: string
|
||
realName?: string
|
||
phone?: string
|
||
roleInProject: string
|
||
joinedAt: string
|
||
status: 'ACTIVE' | 'INACTIVE'
|
||
}
|
||
|
||
interface ProjectConfig {
|
||
id: string
|
||
projectId: string
|
||
enableReservation: boolean
|
||
enableVisitor: boolean
|
||
enableComplaint: boolean
|
||
enablePayment: boolean
|
||
enableAnnouncement: boolean
|
||
enableSurvey: boolean
|
||
enableVote: boolean
|
||
enableMaintenance: boolean
|
||
enableAsset: boolean
|
||
customConfig?: string
|
||
updatedAt: string
|
||
}
|
||
|
||
interface ProjectDeleteCheckVO {
|
||
canDelete: boolean
|
||
reason?: string
|
||
statistics: ProjectDeleteStatistics
|
||
}
|
||
```
|
||
|
||
#### 5.2.3 空间相关类型（types/space.ts）
|
||
|
||
```typescript
|
||
type SpaceNodeCategory = 'BUILDING' | 'PARKING' | 'FACILITY' | 'AREA'
|
||
type SpaceNodeType = 'BUILDING' | 'UNIT' | 'FLOOR' | 'ROOM' | 'SHOP' | 'GARAGE' |
|
||
'PARKING_AREA' | 'PARKING_SPACE' | 'EQUIPMENT_ROOM' | 'PROPERTY_OFFICE' |
|
||
'SECURITY_ROOM' | 'PUBLIC_AREA' | 'GREEN_AREA' | 'ROAD'
|
||
|
||
interface SpaceNode {
|
||
id: string
|
||
projectId: string
|
||
code: string
|
||
name: string
|
||
fullName?: string
|
||
nodeCategory: SpaceNodeCategory
|
||
nodeType: SpaceNodeType
|
||
parentId?: string
|
||
treePath?: string
|
||
level?: number
|
||
buildingArea?: number
|
||
usableArea?: number
|
||
status?: string
|
||
// ...更多字段
|
||
}
|
||
|
||
interface SpaceNodeTree extends SpaceNode {
|
||
children: SpaceNodeTree[]
|
||
}
|
||
```
|
||
|
||
#### 5.2.4 设备相关类型（api/equipment.ts内联）
|
||
|
||
```typescript
|
||
type SystemType = 'ELEVATOR' | 'HVAC' | 'FIRE_PROTECTION' | 'PLUMBING' |
|
||
'ELECTRICAL' | 'SECURITY' | 'LANDSCAPE' | 'ENERGY_METER'
|
||
type EquipmentType = 'ELEVATOR' | 'HVAC' | 'FIRE_PROTECTION' | 'PLUMBING' |
|
||
'ELECTRICAL' | 'ENERGY_METER' | 'SECURITY' | 'LANDSCAPE' | 'KITCHEN' | 'OTHER'
|
||
type OwnershipType = 'PROJECT' | 'COMPANY' | 'OWNER' | 'RENTAL'
|
||
|
||
interface Equipment {
|
||
id: string
|
||
equipmentCode: string
|
||
equipmentName: string
|
||
projectId: string
|
||
equipmentType?: EquipmentType
|
||
systemType?: SystemType
|
||
ownershipType?: OwnershipType
|
||
status?: string
|
||
operationStatus?: string
|
||
// ...更多字段
|
||
photos?: EquipmentPhoto[]
|
||
documents?: EquipmentDocument[]
|
||
}
|
||
```
|
||
|
||
#### 5.2.5 工单相关类型（api/work-order.ts内联）
|
||
|
||
```typescript
|
||
type WorkOrderSource = 'OWNER' | 'MAINTENANCE' | 'INSPECTION' | 'FAULT' | 'REGULATORY' | 'MANUAL'
|
||
type WorkOrderType = 'REPAIR' | 'INSPECTION' | 'SECURITY' | 'CLEANING' | 'PROPERTY' | 'CONSULTATION'
|
||
type WorkOrderPriority = 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT'
|
||
type WorkOrderStatus = 'PENDING' | 'ASSIGNED' | 'IN_PROGRESS' | 'SUSPENDED' |
|
||
'RETURNED' | 'COMPLETED' | 'VERIFIED' | 'CANCELLED'
|
||
|
||
interface WorkOrder {
|
||
id?: string
|
||
workNo?: string
|
||
source: WorkOrderSource
|
||
type: WorkOrderType
|
||
title: string
|
||
priority: WorkOrderPriority
|
||
status: WorkOrderStatus
|
||
projectId?: string
|
||
equipmentId?: string
|
||
assignedTo?: string
|
||
// ...更多字段
|
||
}
|
||
```
|
||
|
||
#### 5.2.6 维保相关类型（api/maintenance-*.ts内联）
|
||
|
||
```typescript
|
||
type PlanType = 'PREVENTIVE' | 'CORRECTIVE'
|
||
type PlanStatus = 'ACTIVE' | 'INACTIVE' | 'SUSPENDED'
|
||
type TaskType = 'PREVENTIVE' | 'CORRECTIVE' | 'EMERGENCY'
|
||
type TaskPriority = 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT'
|
||
type TaskStatus = 'PENDING' | 'ASSIGNED' | 'IN_PROGRESS' | 'COMPLETED' | 'VERIFIED' | 'CANCELLED'
|
||
type TriggerType = 'PLAN' | 'INSPECTION' | 'FAULT' | 'MANUAL'
|
||
```
|
||
|
||
#### 5.2.7 能耗相关类型（api/energy.ts内联）
|
||
|
||
```typescript
|
||
interface EnergyMeter {
|
||
id?: string
|
||
meterCode: string
|
||
meterName: string
|
||
energyType: string
|
||
installationLocation?: string
|
||
ratedCapacity?: number
|
||
unitPrice?: number
|
||
status?: string
|
||
}
|
||
|
||
interface EnergyConsumption {
|
||
id?: string
|
||
meterId: string
|
||
consumptionDate: string
|
||
previousReading: number
|
||
currentReading: number
|
||
consumption: number
|
||
amount?: number
|
||
recordMethod?: string
|
||
}
|
||
```
|
||
|
||
#### 5.2.8 备件相关类型（api/sparepart.ts内联）
|
||
|
||
```typescript
|
||
interface SparePart {
|
||
id: string
|
||
name: string
|
||
code: string
|
||
categoryId?: string
|
||
projectId: string
|
||
unit?: string
|
||
currentStock?: number
|
||
safeStock?: number
|
||
lowStockWarning?: boolean
|
||
}
|
||
|
||
interface StockRecord {
|
||
id: string
|
||
sparePartId: string
|
||
operationType: 'IN' | 'OUT'
|
||
quantity: number
|
||
beforeStock?: number
|
||
afterStock?: number
|
||
relatedOrderId?: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、交互规范
|
||
|
||
### 6.1 表单验证规范
|
||
|
||
| 场景 | 验证规则 | 组件 |
|
||
|------|---------|------|
|
||
| 必填字段 | `required: true, message: '请输入xxx'` | a-form-item + rules |
|
||
| 字符串长度 | `min: 2, max: 50, message: '长度2-50位'` | a-input |
|
||
| 手机号 | `pattern: /^1[3-9]\d{9}$/, message: '请输入正确手机号'` | a-input |
|
||
| 邮箱 | `type: 'email', message: '请输入正确邮箱'` | a-input |
|
||
| 数字范围 | `type: 'number', min: 0, max: 99999` | a-input-number |
|
||
| 唯一性 | 异步验证，调用后端接口 | 自定义validator |
|
||
| 提交前验证 | `form.validate()` 全量校验 | a-form |
|
||
|
||
### 6.2 列表查询规范
|
||
|
||
| 规范项 | 实现方式 |
|
||
|--------|---------|
|
||
| 分页 | 后端分页，参数 `page`（从0开始）+ `size` |
|
||
| 搜索 | 关键词搜索参数 `keyword`，模糊匹配用户名/姓名/编码 |
|
||
| 筛选 | 下拉选择参数（status/type等），多条件组合 |
|
||
| 排序 | 后端默认排序（通常按createdAt DESC） |
|
||
| 刷新 | 切换页码/筛选条件后自动重新查询 |
|
||
| 空状态 | Ant Design Vue Table `locale.emptyText` |
|
||
|
||
### 6.3 状态展示规范
|
||
|
||
**颜色映射表**:
|
||
|
||
| 状态类型 | 映射规则 | Tag颜色 |
|
||
|---------|---------|---------|
|
||
| 用户状态 | ACTIVE=green, LOCKED=red, DISABLED=gray | a-tag color |
|
||
| 项目状态 | ACTIVE=success, DISABLED=error, PENDING=warning, ARCHIVED=default | a-tag color |
|
||
| 工单状态 | PENDING=default, ASSIGNED=blue, IN_PROGRESS=orange, COMPLETED=green, VERIFIED=cyan, CANCELLED=red | a-tag color |
|
||
| 工单优先级 | LOW=green, MEDIUM=blue, HIGH=orange, URGENT=red | a-tag color |
|
||
| 工单来源 | OWNER=purple, MAINTENANCE=blue, INSPECTION=cyan, FAULT=red | a-tag color |
|
||
| 维保任务状态 | PENDING=default, ASSIGNED=blue, IN_PROGRESS=orange, COMPLETED=green, VERIFIED=cyan, CANCELLED=red | a-tag color |
|
||
| 巡检状态 | NORMAL=green, WARNING=orange, ABNORMAL=red | a-tag color |
|
||
| 设备状态 | NORMAL=green, WARNING=orange, ABNORMAL=red | a-tag color |
|
||
|
||
### 6.4 操作确认规范
|
||
|
||
| 操作类型 | 确认方式 | 说明 |
|
||
|---------|---------|------|
|
||
| 删除 | `Modal.confirm` + 红色警告 | "确定要删除xxx吗？此操作不可恢复" |
|
||
| 状态变更 | `Modal.confirm` | "确定要将状态从xxx变更为yyy吗？" |
|
||
| 批量操作 | `Modal.confirm` + 数量提示 | "确定要删除选中的N条记录吗？" |
|
||
| 取消工单 | `Modal.confirm` + 原因输入 | 需填写取消原因 |
|
||
| 表单提交 | 无确认 | 直接提交 |
|
||
| 登出 | 无确认 | 直接登出 |
|
||
|
||
---
|
||
|
||
## 七、权限控制
|
||
|
||
### 7.1 路由级权限（meta.requiredRoles）
|
||
|
||
**实现方式**: Vue Router `beforeEach` 守卫
|
||
|
||
```typescript
|
||
// 路由定义
|
||
{
|
||
path: 'system/users',
|
||
meta: { title: '用户管理', requiredRoles: ['SYS_ADMIN'] }
|
||
}
|
||
|
||
// 守卫校验
|
||
const requiredRoles = to.meta?.requiredRoles as string[] | undefined
|
||
if (requiredRoles?.length && !userStore.hasAnyRole(requiredRoles)) {
|
||
return next({ path: '/', query: { from: to.fullPath } })
|
||
}
|
||
```
|
||
|
||
**当前权限配置**:
|
||
|
||
| 路由 | requiredRoles |
|
||
|------|--------------|
|
||
| /system/* (6个页面) | `['SYS_ADMIN']` |
|
||
| 其他业务页面 | 无（仅要求已登录） |
|
||
|
||
### 7.2 按钮级权限（v-if + hasRole）
|
||
|
||
**实现方式**: Pinia Store `hasRole` / `hasAnyRole` 方法
|
||
|
||
```html
|
||
<a-button v-if="userStore.hasRole('SYS_ADMIN')" @click="handleDelete">
|
||
删除
|
||
</a-button>
|
||
```
|
||
|
||
**当前使用场景**: 有限，大部分页面未做按钮级权限控制
|
||
|
||
**建议增强**:
|
||
|
||
| 操作 | 建议权限检查 |
|
||
|------|------------|
|
||
| 创建/编辑/删除 | `userStore.hasAnyRole(['SYS_ADMIN', 'PROJECT_ADMIN'])` |
|
||
| 审批操作 | `userStore.hasRole('FINANCE_STAFF')` |
|
||
| 系统配置 | `userStore.hasRole('SYS_ADMIN')` |
|
||
|
||
### 7.3 数据级权限（后端控制）
|
||
|
||
**实现方式**: 后端 DataScopeService + X-Project-ID Header
|
||
|
||
| 数据范围 | 编码 | 后端过滤逻辑 |
|
||
|---------|------|------------|
|
||
| 全部数据 | ALL | 不做数据过滤 |
|
||
| 项目数据 | PROJECT | 过滤 project_id = X-Project-ID |
|
||
| 部门数据 | DEPARTMENT | 过滤 project_id + dept_id |
|
||
| 本人数据 | SELF | 过滤 assigned_to / created_by = 当前用户ID |
|
||
|
||
**前端配合**:
|
||
1. 请求拦截器自动注入 `X-Project-ID` Header（从ProjectSelector获取）
|
||
2. 前端不做数据过滤，完全依赖后端返回
|
||
3. 列表页面根据返回数据渲染，不额外过滤
|