You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

20 KiB

Raw Blame History Unescape Escape

医院物业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 统一响应格式

成功响应：

{
  "code": 0,
  "message": "success",
  "data": { ... },
  "timestamp": 1713244800000
}

分页响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [ ... ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 156,
      "totalPages": 8
    }
  },
  "timestamp": 1713244800000
}

错误响应：

{
  "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 载荷标准字段

{
  "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 设计目标

模块即插即用：新模块实现标准接口后，自动获得菜单注入、权限注册、路由挂载能力
模块热注册：系统启动时自动扫描并注册所有模块，无需修改核心代码
模块隔离：各模块独立开发、测试、部署，互不干扰
租户级模块控制：支持按租户启用/禁用特定模块

4.2 核心接口定义

public interface IModulePlugin {

    /** 获取模块基本信息 */
    ModuleInfo getModuleInfo();

    /** 获取模块菜单定义（自动注入侧边栏） */
    List<MenuDefinition> getMenuDefinitions();

    /** 获取模块权限定义（自动注册到权限管理） */
    List<PermissionDefinition> getPermissionDefinitions();

    /** 获取模块路由定义（自动注册到前端路由表） */
    List<RouteDefinition> getRouteDefinitions();

    /** 获取模块数据表定义（系统初始化/升级时自动建表/迁移） */
    List<TableDefinition> getTableDefinitions();

    /** 模块初始化回调 */
    void onInitialize(ModuleContext context);

    /** 模块销毁回调 */
    void onDestroy();

    /** 获取模块依赖的其他模块编码 */
    default List<String> getDependencies() {
        return Collections.emptyList();
    }

    /** 获取模块配置项定义 */
    default List<ConfigDefinition> 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<MenuDefinition>	子菜单列表
scopeRestrictions	List<String>	菜单关联的角色范围
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<RouteDefinition>	子路由
requiresAuth	boolean	是否需要认证
allowedRoles	List<String>	允许访问的角色编码

TableDefinition — 数据表定义

字段	类型	说明
tableName	String	表名
description	String	表描述
columns	List<ColumnDefinition>	列定义
indexes	List<IndexDefinition>	索引定义
initialDataSql	String	初始数据SQL（可选）

ConfigDefinition — 配置项定义

字段	类型	说明
code	String	配置项编码
name	String	配置项名称
description	String	配置项描述
valueType	String	值类型：STRING/NUMBER/BOOLEAN/SELECT/JSON
defaultValue	Object	默认值
options	List<SelectOption>	可选值列表（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 模块注册中心

public interface ModuleRegistry {

    /** 注册模块 */
    void register(IModulePlugin plugin);

    /** 注销模块 */
    void unregister(String moduleCode);

    /** 获取所有已注册模块 */
    List<IModulePlugin> getAllModules();

    /** 获取指定模块 */
    Optional<IModulePlugin> 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<IModulePlugin> getEnabledModulesForTenant(Long tenantId);
    List<MenuDefinition> 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 事件基类

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 事件订阅示例

@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 描述文件

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}:*

本文档定义接口规范和模块化架构约定，具体业务接口的请求/响应字段在开发阶段细化。

20 KiB Raw Blame History Unescape Escape