houqin-java/.codebuddy/plans/医院物业SaaS管理后台-概要设计_c528df96.md

name	overview	design	todos
医院物业SaaS管理后台-概要设计	设计面向医院物业公司的SaaS模式管理员后台系统概要设计，涵盖在线报修、巡检、保洁、服务评价等核心模块，以及医废管理、陪检管理、合同管理、分段招标管理等扩展模块接口预留。	architecture styleKeywords fontSystem colorSystem framework component react tdesign 企业级SaaS 专业高效 数据驱动 清爽蓝白 卡片式布局 fontFamily heading subheading body PingFang SC size weight 24px 600 size weight 16px 500 size weight 14px 400 primary background text functional #0052D9 #266FE8 #4787F0 #F3F4F6 #FFFFFF #F9FAFB #1F2937 #4B5563 #9CA3AF #00A870 #E34D59 #ED7B2F #0052D9	id content status design-overview 编写概要设计文档，涵盖系统架构、模块划分、数据模型、接口规范与扩展机制 completed id content status dependencies data-model 设计核心数据模型（租户、班组、工单、巡检计划、保洁任务、评价、蓝牙设备） completed design-overview id content status dependencies api-spec 设计各模块RESTful API接口规范，含请求/响应结构与权限要求 completed design-overview id content status dependencies extension-interface 设计IModulePlugin扩展接口规范，定义模块注册、菜单注入、权限声明机制 completed design-overview id content status dependencies tapd-import 使用[skill:TAPD]将需求拆解录入TAPD，创建Epic与Story树 completed design-overview data-model api-spec

产品概述

面向医院物业公司的SaaS模式管理员后台系统，提供报修、巡检、保洁及服务评价四大核心功能模块，支持多租户隔离与自定义班组人员分配，并预留医废管理、陪检管理、合同管理、分段招标管理等扩展模块接口。

核心功能

在线报修模块

• 微信扫码注册：扫描二维码进入小程序/公众号，自动注册并绑定身份信息
• 上传照片：报修时支持拍摄/上传故障照片，最多9张，含水印时间定位
• 工单生成与流转：自动生成工单编号，按预设规则流转（待分配→处理中→待验收→已完成/已关闭），支持催单、退单、转单
• 延期及协助维修：维修人员可申请延期，需主管审批；可请求其他班组协助，生成协助子工单

巡检管理模块

• 主管制定计划：按区域/设备/频次创建巡检计划，自动生成巡检任务排期
• 蓝牙卡定位打卡：通过蓝牙Beacon定位确认巡检人员到达指定位置，防止代签
• 异常记录：巡检发现异常可拍照上传、标记严重等级、自动触发报修工单

保洁管理模块

• 多级管理：项目→区域→楼栋→楼层→区域责任人五级保洁管理架构
• 蓝牙卡定位确认完成：保洁人员到达指定区域蓝牙打卡确认完成，主管可抽查
• 保洁任务看板：日/周/月任务视图，超时未完成自动预警

服务评价模块

• 五分制评分：对报修/巡检/保洁服务进行1-5分打分
• 留言评价：支持文字留言及图片上传
• 评价看板：汇总统计各班组/人员评分，生成绩效报表

系统管理

• 自定义班组：创建/编辑班组，设置班组长，支持多班组协作
• 人员分配逻辑：按区域/技能/排班等维度分配人员到班组，支持一人多班组
• 多租户隔离：SaaS模式下各物业公司数据完全隔离
• 角色权限：超管→租户管理员→项目经理→主管→员工五级角色体系

扩展模块预留

• 医废管理：医废收集、称重、转运、销毁全流程追踪
• 陪检管理：陪检任务分配、签到确认、耗时统计
• 合同管理：合同台账、到期预警、续签审批
• 分段招标管理：招标计划、供应商管理、评标定标

技术栈

• 前端：React 18 + TypeScript + Ant Design Pro + Tailwind CSS
• 后端：Node.js + NestJS（TypeScript）
• 数据库：PostgreSQL（多租户共享数据库隔离schema方案）+ Redis（缓存/会话）
• 消息队列：RabbitMQ（工单流转、异步通知）
• 对象存储：腾讯云COS（图片/附件）
• 微信集成：微信小程序API + 微信公众号API

实现方案

架构策略

采用领域驱动设计（DDD）分层架构，按业务领域拆分微服务模块（NestJS Module级别），预留标准扩展接口。SaaS多租户采用共享数据库、Schema隔离方案，通过TenantContext中间件自动切换。

核心技术决策

1. 多租户方案：共享数据库+行级隔离（tenant_id字段），兼顾成本与隔离性，通过NestJS Guard统一注入租户上下文
2. 工单流转引擎：基于状态机模式实现，状态转移规则可配置，支持自定义流转路径
3. 蓝牙定位：前端小程序对接蓝牙Beacon协议，后端校验打卡位置合法性
4. 扩展模块接口：定义IModulePlugin接口，新模块通过实现标准接口注册到系统，自动获得菜单、权限、路由注入能力

数据流

微信扫码/小程序 → API网关(NestJS) → 租户识别中间件 → 业务模块 → PostgreSQL/Redis
                                                  → 消息队列(异步通知/工单流转)
                                                  → 腾讯云COS(图片存储)

架构设计

graph TB
    subgraph 前端层
        A[管理员后台 React] 
        B[微信小程序]
    end
    
    subgraph API网关层
        C[NestJS API Gateway]
        C1[租户识别中间件]
        C2[JWT认证守卫]
        C3[权限守卫]
    end
    
    subgraph 业务模块层
        D1[报修模块 RepairModule]
        D2[巡检模块 InspectionModule]
        D3[保洁模块 CleaningModule]
        D4[评价模块 EvaluationModule]
        D5[组织架构模块 OrgModule]
        D6[系统管理模块 SystemModule]
        D7[扩展模块接口 IModulePlugin]
    end
    
    subgraph 基础设施层
        E1[PostgreSQL]
        E2[Redis]
        E3[RabbitMQ]
        E4[腾讯云COS]
        E5[微信API]
    end
    
    A --> C
    B --> C
    C --> C1 --> C2 --> C3
    C3 --> D1 & D2 & D3 & D4 & D5 & D6 & D7
    D1 & D2 & D3 & D4 & D5 & D6 & D7 --> E1 & E2 & E3 & E4
    D1 & D2 & D3 --> E5

模块插件化扩展设计

graph LR
    subgraph 核心框架
        M[ModuleRegistry 注册中心]
        R[路由自动注入]
        P[权限自动注册]
        N[菜单自动生成]
    end
    
    subgraph 扩展模块
        E1[医废管理 MedicalWasteModule]
        E2[陪检管理 EscortModule]
        E3[合同管理 ContractModule]
        E4[分段招标 BiddingModule]
    end
    
    E1 & E2 & E3 & E4 -->|实现IModulePlugin| M
    M --> R & P & N

目录结构

hospital-facility-management/
├── packages/
│   ├── server/                          # 后端服务
│   │   ├── src/
│   │   │   ├── main.ts                  # 入口文件，NestJS bootstrap
│   │   │   ├── app.module.ts            # 根模块，注册所有业务模块
│   │   │   ├── common/                  # 公共层
│   │   │   │   ├── guards/              # 租户守卫、JWT守卫、权限守卫
│   │   │   │   ├── interceptors/        # 响应格式化、日志拦截器
│   │   │   │   ├── filters/             # 异常过滤器
│   │   │   │   ├── decorators/          # 自定义装饰器（@Tenant, @Permissions）
│   │   │   │   ├── pipes/               # 验证管道
│   │   │   │   └── interfaces/          # IModulePlugin, ITenantContext等公共接口
│   │   │   ├── config/                  # 配置管理（数据库、Redis、COS、微信等）
│   │   │   ├── modules/
│   │   │   │   ├── auth/                # 认证模块（微信登录、JWT、角色管理）
│   │   │   │   ├── tenant/              # 租户管理模块
│   │   │   │   ├── org/                 # 组织架构模块（班组、人员分配）
│   │   │   │   ├── repair/              # 报修模块
│   │   │   │   │   ├── repair.module.ts
│   │   │   │   │   ├── controllers/
│   │   │   │   │   ├── services/
│   │   │   │   │   ├── entities/
│   │   │   │   │   ├── dto/
│   │   │   │   │   └── workflow/        # 工单状态机引擎
│   │   │   │   ├── inspection/          # 巡检模块
│   │   │   │   ├── cleaning/            # 保洁模块
│   │   │   │   ├── evaluation/          # 评价模块
│   │   │   │   └── _plugins/            # 扩展模块目录
│   │   │   │       ├── medical-waste/   # 医废管理（预留）
│   │   │   │       ├── escort/          # 陪检管理（预留）
│   │   │   │       ├── contract/        # 合同管理（预留）
│   │   │   │       └── bidding/         # 分段招标（预留）
│   │   │   └── shared/                  # 共享服务（通知、文件上传、蓝牙校验）
│   │   └── test/
│   └── admin-web/                       # 管理员后台前端
│       ├── src/
│       │   ├── layouts/                 # 布局组件（SiderMenu + Header + Content）
│       │   ├── pages/
│       │   │   ├── dashboard/           # 仪表盘首页
│       │   │   ├── repair/              # 报修管理页面
│       │   │   ├── inspection/          # 巡检管理页面
│       │   │   ├── cleaning/            # 保洁管理页面
│       │   │   ├── evaluation/          # 评价管理页面
│       │   │   ├── org/                 # 组织架构管理页面
│       │   │   └── system/              # 系统设置页面
│       │   ├── components/              # 公共组件
│       │   ├── services/                # API调用层
│       │   ├── stores/                  # 状态管理（Zustand）
│       │   ├── hooks/                   # 自定义Hooks
│       │   └── utils/                   # 工具函数
│       └── public/
└── package.json                         # Monorepo 根配置

实现要点

• 工单流转引擎：采用有限状态机（XState理念），状态转移规则存储于数据库，支持租户自定义流转路径
• 蓝牙定位校验：小程序端扫描Beacon信号强度(RSSI)换算距离，后端校验打卡坐标与任务区域匹配度
• 多租户隔离：所有业务表携带tenant_id，TypeORM通过全局scope自动注入查询条件，防止越权
• 扩展模块注册：IModulePlugin接口定义register()、getMenus()、getPermissions()方法，新模块实现后自动注入
• 消息通知：工单状态变更、巡检超时、保洁预警等事件通过RabbitMQ发布，消费端推送微信模板消息

设计风格

采用现代企业级SaaS管理后台风格，以TDesign组件库为基础，搭配Tailwind CSS自定义样式。整体视觉追求专业、高效、清晰，符合医院物业管理行业特征。

页面规划

1. 仪表盘首页（Dashboard）

• 顶部统计卡片区：今日报修数/进行中工单/待巡检数/保洁完成率，大字号数字+环比趋势箭头
• 工单状态分布图：环形图展示各状态工单占比
• 最新工单列表：展示最近10条工单，含状态标签、紧急程度、处理人
• 班组工作量排行：横向柱状图展示各班组本周完成量
• 评分趋势图：折线图展示近30天平均评分走势

2. 报修管理页

• 工单列表区：表格展示，支持状态/日期/区域/班组多维度筛选，含快捷操作按钮
• 工单详情抽屉：右侧抽屉展示工单完整信息、流转记录时间轴、照片附件、评价信息
• 工单创建弹窗：表单录入报修信息，支持图片上传预览

3. 巡检管理页

• 巡检计划看板：日历视图+列表视图切换，按颜色区分正常/异常/未执行
• 巡检记录详情：展示打卡时间、定位信息、异常记录及关联工单
• 计划创建表单：区域选择、频次设置、人员分配、蓝牙点位绑定

4. 保洁管理页

• 保洁任务看板：看板视图（待执行/执行中/已完成），支持拖拽调整
• 区域管理树：左侧树形结构展示五级保洁区域架构
• 人员排班表：周视图展示排班情况，支持点击编辑

5. 评价管理页

• 评价汇总统计：各模块平均评分卡片+星级分布图
• 评价列表：支持按模块/评分/日期筛选，展示评分星级、评语、关联工单
• 绩效报表：班组/人员评分排名表，支持导出

6. 组织架构管理页

• 班组管理：卡片式展示各班组，含人员数量、负责区域、班组长信息
• 人员分配：左右穿梭框选择人员分配到班组，支持批量操作
• 排班日历：月视图排班管理

7. 系统设置页

• 租户信息：公司基本信息、Logo上传
• 角色权限：角色列表+权限树勾选
• 蓝牙设备管理：Beacon设备列表、位置绑定、状态监控
• 微信配置：小程序/公众号参数配置

全局布局

• 左侧固定侧边栏：可折叠，含模块图标+文字，底部展开/收起按钮
• 顶部导航栏：面包屑导航 + 全局搜索 + 通知铃铛 + 用户头像下拉菜单
• 内容区：带内边距的白色背景卡片式内容区

Agent Extensions

Skill

• TAPD
• Purpose: 将概要设计中的各模块需求拆解为TAPD需求和任务，录入项目管理平台
• Expected outcome: 在TAPD中创建完整的需求树（Epic→Story→Task），覆盖报修、巡检、保洁、评价、组织架构、系统管理六大模块，含优先级、描述、关联关系