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