# 医院物业SaaS管理后台 — 开发与测试规范

> 版本：v1.0  
> 定位：开发团队统一规范，所有开发人员必须严格遵守  
> 日期：2026-04-16

---

## 一、后端开发规范

### 1.1 代码分层规范

```
Controller层：接收请求、参数校验、调用Service、返回响应
    ↓
Service层：业务逻辑编排、事务管理、权限校验
    ↓
Repository层：数据访问（MyBatis-Plus Mapper）
```

**严格分离原则**：

| 类型 | 用途 | 位置 |
|------|------|------|
| DTO | 接收请求参数 | `dto/request/` |
| VO | 返回响应数据 | `dto/response/` |
| Entity | 数据库映射 | `entity/` |
| 禁止 | Controller直接返回Entity | — |
| 禁止 | Service层接收HttpServletRequest | — |

### 1.2 命名规范

| 对象 | 规范 | 示例 |
|------|------|------|
| 包名 | 全小写，模块开头 | `com.hospital.mgmt.modules.repair` |
| 类名 | 大驼峰 | `RepairOrderService` |
| 方法名 | 小驼峰，动词开头 | `createOrder`, `getById`, `listByStatus` |
| 常量 | 全大写下划线 | `MAX_UPLOAD_SIZE` |
| 数据库表名 | 小写下划线，模块前缀 | `repair_order`, `inspection_task` |
| 数据库字段 | 小写下划线 | `created_at`, `tenant_id` |
| 枚举值 | 全大写下划线 | `ACTIVE`, `PENDING` |
| API路径 | 小写连字符，资源复数 | `/repair-orders`, `/check-in` |

### 1.3 数据库规范

- 所有业务表必须包含 `tenant_id` 字段
- 主键使用雪花算法生成 BIGINT
- 逻辑删除：`deleted` 字段（0-正常，1-已删除）
- 枚举值存储为 VARCHAR，禁止使用数字枚举
- JSON 字段用于存储动态配置（如 `check_items`, `skills`），禁止存储核心查询字段
- 索引规范：
  - 所有表自动在 `tenant_id` 上建立索引
  - 业务编码字段建立唯一索引
  - 状态+时间组合查询建立复合索引
  - 禁止在 JSON 字段上建索引

### 1.4 模块开发规范

- 详见 `05-接口规范.md` IModulePlugin 规范
- 每个模块必须实现 `IModulePlugin` 接口
- 模块目录结构：
  ```
  modules/{module-code}/
  ├── {ModuleCode}Module.java       # IModulePlugin实现类
  ├── config/                       # 模块配置
  ├── controller/                   # REST控制器
  ├── service/                      # 业务服务
  ├── entity/                       # 数据实体
  ├── dto/                          # 数据传输对象
  ├── repository/                   # 数据访问层
  ├── event/                        # 模块事件
  └── resources/
      ├── module.yml                # 模块描述文件
      └── db/migration/             # 数据库迁移脚本
  ```
- 模块间通信必须通过 Spring Event，禁止跨模块直接调用 Service
- 新模块上线前必须通过审核清单（详见 `05-接口规范.md` 模块安全规范）

### 1.5 审计日志规范

- 所有写操作自动记录审计日志（AOP 切面统一处理）
- 业务代码中只需在 Controller 方法上添加 `@AuditLog` 注解
- 记录内容自动采集：操作人、时间、IP、模块、操作类型
- 变更前后数据快照：UPDATE/DELETE 操作自动对比记录
- 禁止在业务代码中手动记录审计日志

---

## 二、前端开发规范（Vue 3 + TypeScript）

### 2.1 组件规范

| 规范项 | 要求 |
|--------|------|
| 组件命名 | 大驼峰，多词组合（`RepairOrderList.vue`） |
| 组件结构 | `<script setup lang="ts">` → `<template>` → `<style scoped>` |
| Props 定义 | 使用 `defineProps<T>()` + TypeScript 接口 |
| Emit 定义 | 使用 `defineEmits<T>()` + TypeScript 接口 |
| 组件粒度 | 单一职责，单个组件不超过 300 行 |
| 样式隔离 | 必须使用 `<style scoped>` |

### 2.2 TypeScript 规范

| 规范项 | 要求 |
|--------|------|
| 类型定义 | 接口用 `interface`，联合类型用 `type` |
| 禁止 | 禁止使用 `any`，必须用 `unknown` + 类型守卫 |
| 枚举 | 业务状态枚举定义在 `types/enums/` 下 |
| API 响应类型 | 每个 API 定义 Request/Response 类型 |

### 2.3 状态管理规范（Pinia）

- 全局状态：用户信息、权限集、字典数据 → `stores/global/`
- 模块状态：按模块划分 Store → `stores/modules/`
- Store 命名：`use{Module}Store`，如 `useRepairStore`
- 异步操作统一使用 `async/await`，在 Store 的 Action 中处理

### 2.4 API 调用规范

- 所有 API 调用封装在 `services/` 目录下
- 使用 Axios 实例统一处理请求头、Token、错误拦截
- 接口函数命名：`get{Resource}List`、`create{Resource}`、`update{Resource}`、`delete{Resource}`
- 禁止在组件中直接调用 Axios

---

## 三、小程序开发规范（uni-app）

### 3.1 目录规范

```
miniprogram/
├── pages/                  # 页面（按功能模块分组）
│   ├── repair/            # 报修模块
│   ├── inspection/        # 巡检模块
│   └── ...
├── components/            # 公共组件
├── services/              # API调用层
├── stores/                # Pinia状态管理
├── utils/                 # 工具函数
│   ├── bluetooth.ts       # 蓝牙工具（统一封装）
│   ├── auth.ts            # 认证工具
│   └── upload.ts          # 上传工具
└── types/                 # TypeScript类型
```

### 3.2 蓝牙调用规范

- 蓝牙功能统一通过 `utils/bluetooth.ts` 封装调用
- 禁止在业务代码中直接调用 `uni.createBLEConnection` 等底层 API
- **核心规则：不需要判断距离，只要成功连接上蓝牙设备即可打卡**
- 调用流程：
  1. `bluetooth.scan(timeout)` — 扫描 Beacon
  2. `bluetooth.connect(deviceId)` — 连接设备（连接成功即视为在岗，无需距离校验）
  3. `bluetooth.disconnect()` — 断开连接
- 失败降级：
  - 非强制蓝牙场景：蓝牙失败可直接手动打卡
  - 强制蓝牙场景：蓝牙失败进入补录模式，需主管审核

### 3.3 图片上传规范

- 所有拍照场景必须调用 `utils/upload.ts` 统一封装
- 水印功能：通过参数 `addWatermark: true` 自动添加时间+位置水印
- 蓝牙场景拍照：上传时附带 `bluetooth_connected` 标记

---

## 四、Git 分支与提交规范

### 4.1 分支策略

| 分支 | 用途 | 命名 | 保护 |
|------|------|------|------|
| main | 生产分支 | main | 禁止直接推送，仅通过 MR 合入 |
| develop | 开发分支 | develop | 禁止直接推送，需 Code Review |
| feature | 功能分支 | feature/{module}/{description} | 从 develop 创建 |
| hotfix | 紧急修复 | hotfix/{description} | 从 main 创建 |
| release | 发布分支 | release/{version} | 从 develop 创建 |

### 4.2 分支流程

```
feature/repair/order-list     develop     main
        │                        │          │
        ├── 提交代码 ──▶─────────┤          │
        │                        │          │
        │              Code Review 通过      │
        │                        ├──────────┤ release 合入
        │                        │          │
```

### 4.3 Commit Message 规范

采用 [Conventional Commits](https://www.conventionalcommits.org/) 格式：

```
<type>(<scope>): <subject>

<body>

<footer>
```

**Type 枚举**：

| Type | 说明 |
|------|------|
| feat | 新功能 |
| fix | 修复 Bug |
| docs | 文档变更 |
| style | 代码格式（不影响逻辑） |
| refactor | 重构（非新功能、非修复） |
| perf | 性能优化 |
| test | 测试相关 |
| chore | 构建/工具变更 |

**Scope 枚举**：`repair` / `inspection` / `cleaning` / `attendance` / `contract` / `bidding` / `auth` / `org` / `system` / `common`

**示例**：

```
feat(repair): 新增工单延期审批功能

- 支持主管审批/驳回延期申请
- 审批结果通过 WebSocket 推送通知

Closes #123
```

### 4.4 分支保护规则

- main / develop 分支禁止强制推送（`--force`）
- 合并到 develop 必须经过 Code Review（至少1人批准）
- 合并到 main 必须经过 Code Review（至少2人批准）
- 合并后自动删除源分支

---

## 五、前后端协作规范

### 5.1 API 联调流程

```
1. 后端定义接口路径、权限编码 → 录入接口文档（Swagger）
2. 前端根据文档定义 TypeScript 类型 + API 调用函数
3. 前端使用 Mock 数据开发页面
4. 后端接口开发完成 → 通知前端切换联调环境
5. 联调问题记录在 TAPD 缺陷中，标注"联调"标签
```

### 5.2 接口文档管理

- 工具：Swagger / OpenAPI（SpringDoc 自动生成）
- 地址：开发环境 `/swagger-ui.html`
- 要求：接口文档与代码同步维护，变更接口必须同步更新文档
- 版本管理：接口变更需在文档中标注变更日期和变更说明

### 5.3 Mock 数据规范

- 前端开发阶段使用 Mock 数据，不依赖后端接口可用性
- Mock 工具：Mock.js 或 json-server
- Mock 数据结构必须与接口文档定义一致
- 联调时通过环境变量切换 Mock / 真实接口

### 5.4 联调排期约定

- 每周一对齐本周联调计划，明确接口交付时间
- 后端接口延迟交付需提前1天通知前端
- 联调环境统一使用 test 环境，禁止使用开发人员本地环境

---

## 六、代码审查要求

所有代码合并到 develop 前必须经过 Code Review，审查重点：

- [ ] 是否遵循分层规范（Controller / Service / Repository 分离）
- [ ] 是否有 SQL 注入风险（禁止拼接 SQL）
- [ ] 是否有租户隔离漏洞（缺少 tenant_id 条件）
- [ ] 是否有权限校验（API 声明权限要求）
- [ ] 是否有审计日志（写操作添加 @AuditLog）
- [ ] 异常处理是否完善（全局异常处理 + 业务异常细分）
- [ ] 是否有硬编码配置（应使用配置文件或字典）
- [ ] 单元测试覆盖率是否达标
- [ ] 新增/修改代码是否包含对应测试用例
- [ ] 前端：是否使用 TypeScript 类型、是否有 XSS 风险

---

## 七、测试规范

### 7.1 单元测试

- **覆盖率要求**：核心业务逻辑 100% 覆盖（行覆盖 + 分支覆盖）
- **框架**：JUnit 5 + Mockito
- **命名规范**：`test_{方法名}_{场景}_{预期结果}`，如 `test_createOrder_withValidData_returnOrderId`
- **必须测试的场景**：
  - 正常流程
  - 参数校验失败
  - 权限不足
  - 数据不存在
  - 状态冲突
  - 所有分支路径（if/else、case 分支）
  - 异常处理路径

### 7.2 测试前置流程

- **强制要求**：每次代码修改后，必须先运行测试，通过后才能提交
- **本地开发流程**：
  1. 编写/修改代码
  2. 运行相关单元测试（`mvn test`）
  3. 测试通过 → 提交代码
  4. 测试失败 → 修复代码 → 重新测试
- **CI 门禁**：
  - 代码提交自动触发流水线
  - 单元测试失败 → 阻断合并
  - 集成测试失败 → 阻断部署
- **测试报告**：每次构建生成覆盖率报告（JaCoCo）

### 7.3 集成测试

| 测试场景 | 验证要点 |
|----------|----------|
| 多租户隔离 | 不同租户数据完全隔离，越权访问被拦截 |
| 读写分离 | 写操作走主库，读操作走从库，从库故障时降级到主库 |
| 权限实时生效 | 权限变更后通过 Redis Pub/Sub 毫秒级广播，各实例缓存即时刷新 |
| 权限降级保障 | Redis 连接断开时，权限缓存 TTL(2小时)到期后自动刷新 |
| 蓝牙策略配置 | 强制/非强制蓝牙场景的行为差异 |

### 7.4 蓝牙场景测试

| 测试场景 | 预期结果 |
|----------|----------|
| 蓝牙连接成功 | 打卡成功，check_type=BLUETOOTH（无需距离校验，连接即打卡） |
| 无蓝牙信号（强制蓝牙） | 进入补录模式 |
| 无蓝牙信号（非强制蓝牙） | 允许手动打卡，check_type=MANUAL |
| 拍照时蓝牙断开（强制蓝牙） | 提示蓝牙断开，无法拍照 |
| 拍照时蓝牙断开（非强制蓝牙） | 可继续拍照 |
| Beacon 离线 | 系统通知物业管理人员 |

### 7.5 性能测试

- 工具：JMeter / wrk
- 场景：
  - 100 并发用户持续 30 分钟，API P99 < 500ms
  - 单接口压测，确认无慢 SQL（>1秒）
  - 数据库主从延迟 < 1秒

### 7.6 安全测试

| 测试项 | 方法 |
|--------|------|
| SQL 注入 | 自动化扫描 + 手工验证 |
| 越权访问 | 水平越权 + 垂直越权测试 |
| 敏感数据暴露 | 检查响应中是否泄露手机号、身份证等 |
| 接口鉴权 | 未认证、无权限、Token 过期三种场景 |
| XSS 攻击 | 输入恶意脚本，验证存储/反射型 XSS |

---

> **本文档为开发规范标准，所有开发人员必须严格遵守。如有疑问或需要调整，需经技术负责人审批。**