---
name: 项目技术要求文档
overview: 基于已有的7份设计文档和用户补充信息，创建项目技术要求文档（08-技术要求.md），覆盖技术栈选型、架构设计、安全、性能、开发规范、部署运维、测试等维度，并纳入无中间件方案、蓝牙策略配置等新增需求。
todos:
  - id: write-tech-doc
    content: 编写docs/08-项目技术要求.md文档，涵盖技术栈、架构、安全、性能、蓝牙策略、去中间件方案、开发规范、部署运维、测试要求全量内容
    status: completed
  - id: update-model-bluetooth
    content: 更新docs/04-核心数据模型.md，新增蓝牙策略配置表(sys_bluetooth_policy)和审核表(sys_bluetooth_policy_audit)，打卡记录表增加check_type字段
    status: completed
    dependencies:
      - write-tech-doc
  - id: update-api-bluetooth
    content: 更新docs/05-API接口规范.md，新增蓝牙策略配置API和打卡记录check_type返回字段
    status: completed
    dependencies:
      - write-tech-doc
  - id: update-flow-bluetooth
    content: 更新docs/03-业务流转逻辑.md，蓝牙校验流程改为按策略配置判断（强制/非强制），补录模式仅在强制蓝牙+蓝牙失败时触发
    status: completed
    dependencies:
      - write-tech-doc
---

## 产品概述

医院物业SaaS管理后台的项目技术要求文档，作为内部团队开发标准，所有开发人员必须严格按照此标准执行。

## 核心功能

- 明确技术栈选型与版本要求（Java+Spring Boot+MariaDB+Vue+uni-app+Redis）
- 定义架构设计规范（多租户、模块化、前后端分离、双端、读写分离、去中间件方案）
- 规定安全要求（认证、四级权限、行级数据隔离、蓝牙校验、审计日志）
- 设定性能基线（API响应<500ms、蓝牙交互可靠性、数据补录降级）
- 制定开发规范（API规范、代码规范、数据库规范、模块开发规范）
- 约定部署运维要求（私有云部署、数据库定时备份与恢复、缓存管理、版本更新策略）
- 新增蓝牙策略配置要求（物业公司配置是否强制蓝牙、医院账号审核、报表区分蓝牙/手动打卡）

## 技术栈选型

### 后端

- 语言：Java 17+
- 框架：Spring Boot 3.x
- 数据库：MariaDB 10.6+（主从复制读写分离）
- 缓存：Redis 7.x（权限/字典/菜单缓存，Pub/Sub用于应用内事件）
- ORM：MyBatis-Plus 3.5+
- 认证：Spring Security + JWT
- 文件存储：腾讯云COS

### 前端Web

- 框架：Vue 3 + TypeScript
- 构建工具：Vite 5.x
- 状态管理：Pinia
- 路由：Vue Router 4
- UI组件库：Element Plus（企业级后台管理场景适配度最高）
- HTTP客户端：Axios
- 图表：ECharts

### 小程序

- 框架：uni-app + Vue 3
- 蓝牙SDK：uni-ble（uni-app蓝牙低功耗插件）
- UI组件库：uni-ui

### 基础设施

- 部署：私有云（Docker + Docker Compose）
- CI/CD：Jenkins/GitLab CI
- 版本管理：Git

## 去中间件方案

不引入RocketMQ/Kafka等消息中间件，采用以下替代方案：

### 1. 权限变更实时通知

- 方案：数据库轮询标记 + Spring Event
- 实现：权限变更时写入`sys_config`表标记字段`permission_version`递增；各服务实例定时5秒轮询该字段，检测到版本变化时触发本地权限缓存刷新
- 优势：无额外中间件依赖，实现简单可靠
- 降级：轮询间隔内最大5秒延迟，对权限场景可接受

### 2. 异步任务处理

- 方案：Spring @Async + 自定义线程池
- 实现：配置`ThreadPoolTaskExecutor`，核心线程数=CPU核心数，最大线程数=2*CPU核心数，队列容量1000，拒绝策略CallerRunsPolicy
- 适用场景：报表导出、消息推送、日志异步写入
- 持久化：关键任务落库后异步执行，避免线程池丢失

### 3. 模块间通信

- 方案：Spring ApplicationEvent + ApplicationEventPublisher
- 实现：模块间通过Spring Event解耦，事件定义在共享API模块中
- 跨实例：结合数据库轮询标记实现（事件落库+轮询消费）
- 适用场景：工单完成触发评价、巡检异常触发报修、低分评价通知主管

### 4. 定时任务

- 方案：Spring @Scheduled + 数据库分布式锁
- 实现：`@Scheduled`注解声明定时任务，通过`shedlock`或数据库行锁保证集群内单实例执行
- 适用场景：巡检任务自动生成、保洁超时预警、合同到期提醒、Beacon心跳检测

## 架构设计

### 整体架构

```
客户端层：Vue3 Web管理后台 | uni-app微信小程序
    ↓ HTTPS
网关层：Spring Cloud Gateway / Nginx 反向代理
    ↓
应用层：Spring Boot 单体应用（模块化IModulePlugin）
    ↓
数据层：MariaDB主从（读写分离）| Redis缓存 | 腾讯云COS
```

### 读写分离方案

- 实现：MariaDB主从复制 + MyBatis-Plus动态数据源切换
- 规则：写操作走主库，读操作走从库
- 注解：自定义`@ReadOnly`注解标记读操作，AOP切面切换数据源
- 容错：从库不可用时自动降级到主库读取

### 数据库备份与恢复

- 定时备份：每日凌晨2:00全量备份（mysqldump），每4小时增量备份（binlog）
- 备份保留：全量备份保留30天，增量备份保留7天
- 备份存储：私有云本地磁盘 + 异地备份服务器
- 恢复流程：全量恢复 + binlog重放，RTO<2小时，RPO<4小时
- 定期演练：每季度执行一次恢复演练

### 蓝牙策略配置（新增）

- 配置方：物业公司管理员
- 审核方：医院账号
- 配置项：各场景是否强制蓝牙连接（巡检打卡/巡检拍照/保洁打卡/保洁拍照/考勤打卡）
- 数据模型：新增`sys_bluetooth_policy`配置表 + `sys_bluetooth_policy_audit`审核表
- 打卡记录标记：所有打卡记录区分`check_type`（BLUETOOTH/MANUAL），后台列表和报表明确显示
- 降级逻辑：非强制蓝牙场景下，蓝牙失败可直接手动打卡（记录check_type=MANUAL）；强制蓝牙场景下，蓝牙失败进入补录模式

## 性能要求

- API平均响应时间 < 300ms，P99 < 500ms
- 列表查询响应 < 500ms（含分页）
- 报表生成 < 5s（单月数据）
- 并发支持：单实例100 QPS，水平扩展
- 蓝牙校验：扫描超时3秒，距离计算<100ms

## 开发规范

- API规范：遵循已有05-API接口规范.md
- 代码分层：Controller → Service → Repository，DTO/VO/Entity严格分离
- 命名规范：包名小写、类名大驼峰、方法名小驼峰、常量全大写下划线
- 数据库规范：遵循已有04-核心数据模型.md公共字段约定
- 模块开发：遵循已有06-扩展接口规范.md IModulePlugin规范
- 审计日志：所有写操作自动记录，使用AOP切面统一处理
- 单元测试：核心业务Service覆盖率 >= 70%