houqin-java/.codebuddy/plans/项目技术要求文档_29ab44d0.md

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