|
|
---
|
|
|
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% |