# 医院物业SaaS管理后台 — 接口规范 > 版本：v1.0 > 基础路径：`/api/v1` > 认证方式：Bearer Token（JWT） > 日期：2026-04-16 --- ## 一、全局约定 ### 1.1 请求头 | 请求头 | 必填 | 说明 | |--------|------|------| | Authorization | 是 | `Bearer {jwt_token}` | | Content-Type | 是 | `application/json` | | X-Tenant-Id | 否 | 租户ID（服务端从JWT中提取，此头部仅用于超管跨租户操作） | ### 1.2 统一响应格式 **成功响应**： ```json { "code": 0, "message": "success", "data": { ... }, "timestamp": 1713244800000 } ``` **分页响应**： ```json { "code": 0, "message": "success", "data": { "list": [ ... ], "pagination": { "page": 1, "pageSize": 20, "total": 156, "totalPages": 8 } }, "timestamp": 1713244800000 } ``` **错误响应**： ```json { "code": 40001, "message": "工单不存在", "data": null, "timestamp": 1713244800000 } ``` ### 1.3 错误码规范 | 错误码范围 | 说明 | |-----------|------| | 0 | 成功 | | 40001-40099 | 参数校验错误 | | 40100-40199 | 认证错误 | | 40300-40399 | 权限错误 | | 40400-40499 | 资源不存在 | | 40900-40999 | 业务冲突（状态不允许等） | | 50000-50099 | 服务器内部错误 | ### 1.4 通用错误码 | 错误码 | 说明 | |--------|------| | 40001 | 缺少必填参数 | | 40002 | 参数格式错误 | | 40100 | 未认证（Token缺失或过期） | | 40101 | Token无效 | | 40300 | 无功能权限 | | 40301 | 无数据权限（越权访问） | | 40400 | 资源不存在 | | 40900 | 状态冲突（操作不允许） | | 40901 | 数据已存在 | | 50000 | 服务器内部错误 | ### 1.5 查询参数约定 | 参数 | 类型 | 说明 | |------|------|------| | page | int | 页码，默认1 | | pageSize | int | 每页条数，默认20，最大100 | | sortField | string | 排序字段 | | sortOrder | string | 排序方向：asc/desc | | keyword | string | 关键词搜索 | ### 1.6 RESTful 风格约定 - 资源名用复数名词：`/repair-orders`、`/inspection-tasks` - 动作用 HTTP 方法表达：GET 查询、POST 创建、PUT 更新、DELETE 删除 - 操作类接口用动词：`/repair-orders/{id}/assign`、`/repair-orders/{id}/complete` - 路径使用小写连字符：`/check-in`、`/spot-check` --- ## 二、认证规范 ### 2.1 认证方式 | 场景 | 认证方式 | Token管理 | |------|----------|-----------| | Web端登录 | 用户名+密码 → JWT | localStorage存储，2小时过期 | | 小程序登录 | 微信openid静默登录 → JWT | 本地Storage存储，2小时过期 | | 小程序首次使用 | 微信授权openid + 手机号绑定 | 自动创建账号 | ### 2.2 JWT 载荷标准字段 ```json { "sub": "用户ID", "tid": "租户ID", "utype": "用户类型", "hid": "医院ID", "pid": "物业公司ID", "sid": "员工ID", "iat": "签发时间", "exp": "过期时间" } ``` ### 2.3 权限编码规范 ``` {module}:{page}:{action} ``` 7种动作类型：查看(view)、新增(create)、编辑(update)、删除(delete)、审批(approve)、导出(export)、分配(assign) --- ## 三、文件上传规范 ### 3.1 通用上传接口 ``` POST /api/v1/files/upload ``` - 请求格式：`multipart/form-data` - 参数：`file`（文件）、`module`（所属模块：REPAIR/INSPECTION/CLEANING/EVALUATION/CONTRACT）、`add_watermark`（是否添加水印，默认true） - 存储方式：腾讯云 COS - 大小限制：20MB ### 3.2 图片水印规范 - 水印内容：时间 + 位置信息 - 水印位置：图片右下角 - 蓝牙场景：上传时附带 `bluetooth_connected` 标记 --- ## 四、模块化架构规范（IModulePlugin） ### 4.1 设计目标 1. **模块即插即用**：新模块实现标准接口后，自动获得菜单注入、权限注册、路由挂载能力 2. **模块热注册**：系统启动时自动扫描并注册所有模块，无需修改核心代码 3. **模块隔离**：各模块独立开发、测试、部署，互不干扰 4. **租户级模块控制**：支持按租户启用/禁用特定模块 ### 4.2 核心接口定义 ```java public interface IModulePlugin { /** 获取模块基本信息 */ ModuleInfo getModuleInfo(); /** 获取模块菜单定义（自动注入侧边栏） */ List getMenuDefinitions(); /** 获取模块权限定义（自动注册到权限管理） */ List getPermissionDefinitions(); /** 获取模块路由定义（自动注册到前端路由表） */ List getRouteDefinitions(); /** 获取模块数据表定义（系统初始化/升级时自动建表/迁移） */ List getTableDefinitions(); /** 模块初始化回调 */ void onInitialize(ModuleContext context); /** 模块销毁回调 */ void onDestroy(); /** 获取模块依赖的其他模块编码 */ default List getDependencies() { return Collections.emptyList(); } /** 获取模块配置项定义 */ default List getConfigDefinitions() { return Collections.emptyList(); } } ``` ### 4.3 核心数据结构 #### ModuleInfo — 模块元数据 | 字段 | 类型 | 说明 | |------|------|------| | code | String | 模块编码，全局唯一（如：medical-waste） | | name | String | 模块名称（如：医废管理） | | description | String | 模块描述 | | version | String | 模块版本号（语义化版本，如：1.0.0） | | author | String | 模块作者 | | icon | String | 模块图标 | | sortOrder | int | 模块优先级（数值越小排序越靠前） | | builtIn | boolean | 是否为系统内置模块（不可卸载） | | defaultEnabled | boolean | 是否默认启用 | | type | ModuleType | 模块类型：CORE(核心)/BUSINESS(业务)/EXTENSION(扩展) | | platform | String | 适用端侧：WEB/MINI_PROGRAM/BOTH | | minSystemVersion | String | 最低系统版本要求 | | homePath | String | 模块首页路由路径 | #### MenuDefinition — 菜单定义 | 字段 | 类型 | 说明 | |------|------|------| | code | String | 菜单编码 | | name | String | 菜单名称 | | icon | String | 菜单图标 | | path | String | 菜单路由路径 | | sortOrder | int | 排序号 | | visible | boolean | 是否在侧边栏显示 | | platform | String | 适用端侧 | | children | List\ | 子菜单列表 | | scopeRestrictions | List\ | 菜单关联的角色范围 | | externalLink | String | 外链地址 | #### PermissionDefinition — 权限定义 四级树形结构：**功能菜单 → 页面 → 功能点 → 动作** | 层级 | 字段 | 说明 | |------|------|------| | 菜单 | menuCode / menuName | 功能菜单编码/名称 | | 页面 | pageCode / pageName / pagePath | 页面编码/名称/路径 | | 功能点 | actionCode / actionName | 功能点编码/名称 | | 动作 | operationCode / operationName / defaultGranted | 动作编码/名称/是否默认授予 | 动作编码枚举：VIEW / CREATE / UPDATE / DELETE / APPROVE / EXPORT / ASSIGN #### RouteDefinition — 路由定义 | 字段 | 类型 | 说明 | |------|------|------| | path | String | 路由路径 | | name | String | 路由名称 | | component | String | 前端组件路径 | | meta | RouteMeta | 路由元信息（title、icon、keepAlive、hidden、breadcrumb、permissions） | | children | List\ | 子路由 | | requiresAuth | boolean | 是否需要认证 | | allowedRoles | List\ | 允许访问的角色编码 | #### TableDefinition — 数据表定义 | 字段 | 类型 | 说明 | |------|------|------| | tableName | String | 表名 | | description | String | 表描述 | | columns | List\ | 列定义 | | indexes | List\ | 索引定义 | | initialDataSql | String | 初始数据SQL（可选） | #### ConfigDefinition — 配置项定义 | 字段 | 类型 | 说明 | |------|------|------| | code | String | 配置项编码 | | name | String | 配置项名称 | | description | String | 配置项描述 | | valueType | String | 值类型：STRING/NUMBER/BOOLEAN/SELECT/JSON | | defaultValue | Object | 默认值 | | options | List\ | 可选值列表（SELECT类型时使用） | | tenantLevel | boolean | 是否租户级配置 | | required | boolean | 是否必填 | | group | String | 分组名称 | #### ModuleContext — 模块上下文 | 方法 | 返回类型 | 说明 | |------|----------|------| | getTenantId() | Long | 获取当前租户ID | | getConfigService() | ConfigService | 获取系统配置服务 | | getEventPublisher() | EventPublisher | 获取事件发布服务 | | getNotificationService() | NotificationService | 获取消息通知服务 | | getFileStorageService() | FileStorageService | 获取文件存储服务 | | getPermissionService() | PermissionService | 获取权限校验服务 | | getBluetoothVerifyService() | BluetoothVerifyService | 获取蓝牙校验服务 | | subscribe(eventType, listener) | void | 注册事件监听器 | | scheduleCron(cron, task) | void | 注册定时任务 | | registerMessageTemplate(template) | void | 注册消息模板 | ### 4.4 模块注册中心 ```java public interface ModuleRegistry { /** 注册模块 */ void register(IModulePlugin plugin); /** 注销模块 */ void unregister(String moduleCode); /** 获取所有已注册模块 */ List getAllModules(); /** 获取指定模块 */ Optional getModule(String moduleCode); /** 检查模块是否已启用（全局级/租户级） */ boolean isModuleEnabled(String moduleCode); boolean isModuleEnabledForTenant(String moduleCode, Long tenantId); /** 启用/禁用模块（全局级/租户级） */ void enableModule(String moduleCode); void disableModule(String moduleCode); void enableModuleForTenant(String moduleCode, Long tenantId); void disableModuleForTenant(String moduleCode, Long tenantId); /** 获取指定租户可用的模块列表/菜单树 */ List getEnabledModulesForTenant(Long tenantId); List getMenuTreeForTenant(Long tenantId, String userTypeId); } ``` ### 4.5 注册流程 ``` 系统启动 │ 扫描模块目录（classpath:modules/） │ 加载模块配置（module.yml） │ 实例化 IModulePlugin 实现类 │ 校验模块依赖是否满足 │ ┌── 依赖不满足 ──▶ 记录错误日志，跳过注册 │ 调用 ModuleRegistry.register(plugin) │ 注册中心执行： ├── 1. 存储模块元数据（ModuleInfo） ├── 2. 合并菜单定义到全局菜单树 ├── 3. 注册权限定义到权限配置表 ├── 4. 注册路由定义到路由表 ├── 5. 执行数据表迁移（TableDefinition → DDL） ├── 6. 注册配置项到系统配置 └── 7. 调用 plugin.onInitialize(context) │ 模块注册完成 → 系统就绪 ``` --- ## 五、模块间事件通信规范 ### 5.1 事件基类 ```java public abstract class ModuleEvent { private String sourceModule; // 事件来源模块编码 private String eventType; // 事件类型 private LocalDateTime timestamp; // 事件时间 private Long tenantId; // 租户ID } ``` ### 5.2 预定义系统事件 | 事件类型 | 来源模块 | 说明 | 典型消费方 | |----------|----------|------|-----------| | ORDER_COMPLETED | repair | 工单完成 | evaluation(触发评价) | | ORDER_STATUS_CHANGED | repair | 工单状态变更 | notification(推送通知) | | INSPECTION_ABNORMAL | inspection | 巡检异常 | repair(生成报修工单) | | INSPECTION_COMPLETED | inspection | 巡检完成 | evaluation(触发评价) | | CLEANING_COMPLETED | cleaning | 保洁完成 | evaluation(触发评价) | | CLEANING_TIMEOUT | cleaning | 保洁超时 | notification(推送预警) | | BEACON_OFFLINE | device | Beacon离线 | notification(推送预警) | | BEACON_LOW_BATTERY | device | Beacon低电量 | notification(推送预警) | | CONTRACT_EXPIRING | contract | 合同即将到期 | notification(推送提醒) | | LOW_SCORE_EVALUATION | evaluation | 低分评价 | notification(通知主管) | | MODULE_ENABLED | system | 模块启用 | 各模块(初始化) | | PERMISSION_CHANGED | permission | 权限变更 | 各模块(刷新缓存) | ### 5.3 事件订阅示例 ```java @Override public void onInitialize(ModuleContext context) { context.subscribe(InspectionAbnormalEvent.class, event -> { if ("MEDICAL_WASTE".equals(event.getAbnormalType())) { medicalWasteService.createAbnormalTrack(event); } }); } ``` --- ## 六、模块扩展开发规范 ### 6.1 模块目录结构 ``` src/main/java/com/hospital/management/modules/ └── medical-waste/ # 模块根目录 ├── MedicalWasteModule.java # IModulePlugin实现类 ├── config/ # 模块配置 ├── controller/ # REST控制器 ├── service/ # 业务服务 ├── entity/ # 数据实体 ├── dto/ # 数据传输对象 ├── repository/ # 数据访问层 ├── event/ # 模块事件 └── resources/ ├── module.yml # 模块描述文件 └── db/migration/ # 数据库迁移脚本 ``` ### 6.2 module.yml 描述文件 ```yaml module: code: medical-waste name: 医废管理 description: 医废收集、称重、转运、销毁全流程追踪 version: 1.0.0 author: Hospital Management Team icon: biohazard sort-order: 50 built-in: false default-enabled: false type: EXTENSION platform: BOTH min-system-version: 1.0.0 home-path: /medical-waste/collection dependencies: - inspection - org ``` ### 6.3 前端模块加载 ``` 前端启动 │ 调用 GET /auth/permissions 获取权限集 │ 权限集包含用户可见的模块编码列表 │ 路由守卫根据模块编码动态加载模块前端资源 │ ┌── 模块已加载 ──▶ 直接渲染 │ └── 模块未加载 ──▶ 动态import模块入口文件 │ 注册路由到路由表 │ 渲染目标页面 ``` --- ## 七、模块版本升级规范 ### 7.1 升级策略 | 升级类型 | 版本号变化 | 数据迁移 | 兼容性 | |----------|-----------|----------|--------| | 补丁升级 | x.x.Z | 无 | 完全兼容 | | 功能升级 | x.Y.z | 可选 | 向后兼容 | | 大版本升级 | X.y.z | 必须 | 可能不兼容 | ### 7.2 升级流程 ``` 模块新版本部署 │ 对比模块版本号（当前 vs 新版） │ 执行版本升级脚本 ├── V{major}_{minor}_{patch}__description.sql │ 更新模块元数据版本号 │ 重新调用 getPermissionDefinitions() 对比权限变更 │ 重新调用 getMenuDefinitions() 对比菜单变更 │ 通知在线用户刷新页面 ``` --- ## 八、模块安全规范 ### 8.1 模块安全要求 | 安全项 | 要求 | |--------|------| | 租户隔离 | 所有业务查询必须带 tenant_id 条件 | | 权限校验 | 所有API端点必须声明权限要求 | | 数据校验 | 所有入参必须进行服务端校验 | | SQL注入 | 必须使用参数化查询 | | XSS防护 | 所有用户输入必须转义后存储 | | 日志审计 | 关键操作必须记录审计日志 | | 补录标记 | 补录数据必须标记 is_supplement=true | ### 8.2 模块审核清单 新模块上线前必须通过以下审核： - [ ] 实现 IModulePlugin 所有必需方法 - [ ] module.yml 描述文件完整 - [ ] 数据表包含 tenant_id 字段 - [ ] 所有API声明权限要求 - [ ] 关键操作记录审计日志 - [ ] 蓝牙相关功能使用 BluetoothVerifyService - [ ] 文件上传使用 FileStorageService - [ ] 消息通知使用 NotificationService - [ ] 单元测试覆盖率达标 - [ ] 接口文档完整 --- ## 九、接口权限汇总 ### 9.1 权限编码规范 ``` {module}:{page}:{action} ``` ### 9.2 各模块权限矩阵 | 模块 | 页面 | 功能点 | 动作 | 编码 | |------|------|--------|------|------| | 在线报修 | 工单列表 | 工单管理 | 查看 | repair:list:view | | 在线报修 | 工单列表 | 工单管理 | 新增 | repair:list:create | | 在线报修 | 工单列表 | 工单管理 | 编辑 | repair:list:update | | 在线报修 | 工单列表 | 工单管理 | 删除 | repair:list:delete | | 在线报修 | 工单列表 | 工单管理 | 导出 | repair:list:export | | 在线报修 | 工单列表 | 工单管理 | 分配 | repair:list:assign | | 在线报修 | 工单详情 | 延期/验收 | 审批 | repair:detail:approve | | 在线报修 | 报修类型 | 类型管理 | CRUD | repair:type:* | | 在线报修 | 数据补录 | 补录审核 | 审批 | repair:supplement:approve | | 巡检管理 | 巡检计划 | 计划管理 | 查看/新增/编辑 | inspection:plan:* | | 巡检管理 | 巡检任务 | 任务管理 | 查看/编辑 | inspection:task:* | | 巡检管理 | 巡检区域 | 区域管理 | CRUD | inspection:area:* | | 巡检管理 | 数据补录 | 补录审核 | 审批 | inspection:supplement:approve | | 保洁管理 | 保洁任务 | 任务管理 | 查看/编辑 | cleaning:task:* | | 保洁管理 | 保洁排班 | 排班管理 | 查看/新增/编辑 | cleaning:schedule:* | | 保洁管理 | 保洁区域 | 区域管理 | CRUD | cleaning:area:* | | 保洁管理 | 保洁抽查 | 抽查管理 | 查看/审批 | cleaning:spot-check:* | | 保洁管理 | 数据补录 | 补录审核 | 审批 | cleaning:supplement:approve | | 服务评价 | 评价列表 | 评价管理 | 查看/回复 | evaluation:list:* | | 服务评价 | 评价汇总 | 统计管理 | 查看 | evaluation:summary:view | | 服务评价 | 评价配置 | 配置管理 | 查看/编辑 | evaluation:config:* | | 组织架构 | 班组管理 | 班组管理 | CRUD/分配 | org:team:* | | 组织架构 | 人员管理 | 人员管理 | CRUD | org:staff:* | | 权限管理 | 角色管理 | 角色管理 | CRUD | permission:role:* | | 权限管理 | 账号管理 | 账号管理 | CRUD/分配 | permission:user:* | | 权限管理 | 权限配置 | 配置管理 | CRUD | permission:config:* | | 考勤打卡 | 打卡点 | 点位管理 | 查看/新增/编辑 | attendance:point:* | | 考勤打卡 | 打卡规则 | 规则管理 | 查看/新增/编辑 | attendance:rule:* | | 考勤打卡 | 考勤记录 | 记录管理 | 查看 | attendance:record:view | | 考勤打卡 | 异常申诉 | 申诉管理 | 查看/审批 | attendance:appeal:* | | 考勤打卡 | 数据补录 | 补录审核 | 审批 | attendance:supplement:approve | | 合同管理 | 合同台账 | 合同管理 | CRUD | contract:list:* | | 合同管理 | 合同审批 | 审批管理 | 审批 | contract:approve:* | | 合同管理 | 付款管理 | 付款管理 | 查看/确认 | contract:payment:* | | 合同管理 | 变更管理 | 变更管理 | 查看/申请/审批 | contract:change:* | | 招标管理 | 招标计划 | 计划管理 | CRUD | bidding:plan:* | | 招标管理 | 标段管理 | 标段管理 | 查看/新增/编辑 | bidding:section:* | | 招标管理 | 供应商管理 | 供应商管理 | CRUD/审核 | bidding:supplier:* | | 招标管理 | 定标审批 | 定标管理 | 定标/审批/发布 | bidding:award:* | | 系统管理 | 字典管理 | 字典管理 | CRUD | system:dict:* | | 系统管理 | 蓝牙策略 | 策略管理 | 查看/新增/审核 | system:bluetooth-policy:* | | 系统管理 | 蓝牙设备 | 设备管理 | CRUD | device:beacon:* | | 系统管理 | 消息模板 | 模板管理 | CRUD | system:template:* | | 系统管理 | 微信配置 | 配置管理 | 查看/编辑 | system:wechat:* | | 系统管理 | 版本管理 | 版本管理 | 查看/新增 | system:version:* | | 系统管理 | 缓存管理 | 缓存管理 | 查看/清理 | system:cache:* | | 操作日志 | 日志列表 | 日志管理 | 查看/导出 | audit-log:list:* | | 操作日志 | 权限变更 | 变更日志 | 查看 | audit-log:permission:view | | 操作日志 | 补录日志 | 补录日志 | 查看 | audit-log:supplement:view | | 统计报表 | 报表管理 | 各模块报表 | 查看/导出 | statistics:{module}:* | --- > **本文档定义接口规范和模块化架构约定，具体业务接口的请求/响应字段在开发阶段细化。**