技术架构说明

依据 PRD V3.1 第四章 · 部署路线:云化多租户 SaaS · 数据库 PostgreSQL · 本文档面向架构师与研发团队

架构已确定 V3.1 · 2026-11-21

1. 架构设计目标

目标说明
业务可演进退费规则、佣金规则频繁变化 → 规则外置 + 热更新,改配置不改代码
数据可信财务与经营数据可追溯、可审计、口径统一;导入留存原始快照
多端一致Web 管理端与移动端共享同一套业务能力与数据口径(同一 API)
多租户隔离默认逻辑隔离(tenant_id / org_id),敏感租户可升级独立库
能力可复制新机构交付靠配置而非开发,交付周期从周级降至天级
可观测运维监控、日志、链路追踪齐全,支持容器化滚动升级

2. 部署路线(已确定)

部署形态
云化集中部署 · 多租户 SaaS
开通租户即用,无需现场部署
租户隔离
逻辑隔离(默认)
tenant_id / org_id 字段隔离,可升级独立库
数据存储
PostgreSQL 主库 + Redis
+ Doris / ClickHouse 分析型库
接入方式
公网 HTTPS
机构内网可专线 / VPN 接入
扩展方式
应用无状态 · 水平扩展
会话下沉 Redis
运维方式
容器化 · 滚动升级
K8s + 自动扩容
选择理由:交付效率(天级开通)· 运维成本(集中运维、版本统一)· 数据价值(多机构可对标)· 成本结构(一次性项目 → 持续服务)· 技术成熟度(PostgreSQL 事务与复杂查询能力强)。

3. 五层总体架构

① 接入层 不含业务规则,仅展示与输入校验
Web 管理端(React 18)移动端 H5小程序(家属 / 护理员)开放 API第三方集成
② 网关层 所有请求必须经过,不可绕过
统一鉴权 JWT租户识别权限校验限流熔断路由分发审计埋点
③ 应用层 用例编排 · 事务边界 · 不含核心业务规则
领域服务编排事务管理事件发布工作流引擎任务调度
④ 领域层 业务规则的唯一归属地
聚合根实体 / 值对象领域事件领域规则(退费 / 佣金 / 计费)领域服务
⑤ 基础设施层 通过接口倒置被上层依赖,可替换
PostgreSQLRedisDoris / ClickHouseRabbitMQMinIO 对象存储XXL-JobELKPrometheus + Grafana

4. 七大领域划分

按业务能力划分,领域内高内聚、领域间低耦合;禁止跨域直连数据库表。

协作原则说明
领域内强一致聚合根 + 数据库事务保证业务一致性
领域间最终一致跨领域通过领域事件实现,避免分布式事务
事件驱动解耦关键业务动作发布事件,订阅方异步处理(失败重试 + 死信)
禁止跨域直连领域之间不可直接访问对方数据库表,必须走服务接口

5. 核心领域事件

事件发布方订阅方业务含义
// 例:长者入住 —— 跨域最终一致 ElderCheckedIn { eventId: "evt_8f2a19c", tenantId: "T-1001", occurredAt: "2026-11-21T09:42:08+08:00", elderId: "R-2026-0311", bedNo: "F3-311", careLevel: "初级", subscriptions: ["护理照护域: 生成照护计划", "财务结算域: 启动计费", "餐饮服务: 增加备餐"] }

6. 技术栈选型

层级技术选型版本选型理由
前端框架React + TypeScript18+生态成熟、类型安全、组件化程度高
前端构建Vite5.x构建快、开发体验好
UI 组件库Ant Design5.x企业级中后台标准,符合 B 端习惯
状态管理Zustand / Redux Toolkit—按业务域拆分 Store,避免全局污染
数据可视化ECharts5.x图表完备、大数据量渲染性能好
后端语言JavaJDK 17 / 21 LTS企业级生态成熟、人才储备充足
后端框架Spring Boot3.x生态最完善、配套组件齐全
持久层MyBatis-Plus3.5.xSQL 可审计,适合复杂查询
数据库版本管理Flyway9.x+变更版本化,多环境一致
API 规范RESTful + OpenAPI 3.0—契约清晰,可自动生成客户端
鉴权Spring Security + JWT—多端统一认证
主数据库PostgreSQL15 / 16事务强、复杂查询与扩展性优于 MySQL
缓存Redis7.x热点数据、分布式锁、会话
分析型库Doris / ClickHouse—支撑经营分析的大数据量聚合
消息队列RabbitMQ3.x领域事件异步协作
任务调度XXL-Job2.xETL 与定时计算
对象存储MinIO / 云对象存储—导入快照、报表、录音
报表引擎EasyExcel / Apache POI—服务端生成 Excel
AI 服务国内主流大模型 API—根因分析与经营建议,必须具备降级兜底
日志SLF4J + Logback + ELK—结构化日志集中检索

7. 数据流与分层

ETL 处理流程

Excel / 业务库 / 设备 │ ├─ ① 抽取 原始文件入 MinIO(留存快照,SHA256) ├─ ② 规整 字段映射 → 占位符置空 → 日期归一 → 单位归一 → 枚举映射 → 字符纠正 ├─ ③ 校验 规则库(枚举 / 区间 / 唯一性 / 跨表一致)→ 失败行隔离 ├─ ④ 入湖 ODS(原始) → DWD(标准明细) → DWS(主题汇总) → ADS(看板) └─ ⑤ 重算 发布指标变更事件 → 驾驶舱 / 预警 / 作业成本模型刷新
可追溯机制说明
导入快照留存每次导入保留原始文件 + SHA256,支持事后复盘与责任界定
结构化诊断明细每行记录状态、清洗前后对照、失败原因与修改建议
清洗统计占位符置空 / 日期归一 / 单位归一 / 枚举映射 / 字符纠正 数量
失败行导出导出为新文件,用户修正后重传,不污染主表

8. 接口设计规范

约定

  • RESTful 风格,资源名词复数;OpenAPI 3.0 描述,自动生成前端 SDK
  • 统一响应体:{ code, message, data, traceId }
  • 分页:page / pageSize / total,默认 20,上限 200
  • 幂等:写操作携带 Idempotency-Key(支付、账单生成)
  • 租户:网关从 JWT 解析 tenantId,业务层不信任前端传值
  • 错误码:业务码 5 位,按领域分段(财务 30xxx / 护理 40xxx)

示例

GET /api/v1/elders?page=1&pageSize=20&careLevel=高级 Authorization: Bearer <jwt> X-Tenant-Id: T-1001 200 OK { "code": 0, "message": "ok", "traceId": "tr_9f2a", "data": { "total": 95, "list": [ { "elderId": "R-2019-0142", "name": "陈桂英", "bedNo": "F5-501", "careLevel": "高级", "monthlyFee": 7800, "status": "in_residence" } ]} }

9. 安全架构

层次措施
网络HTTPS 强制;WAF + DDoS 防护;管理端与开放 API 分离网关策略
身份JWT 短时效 + Refresh Token;密码策略 + 登录失败锁定;敏感角色强制二次验证
授权RBAC + 数据范围(机构 / 部门 / 本人);网关统一拦截,禁止绕过
数据传输 TLS;敏感字段(身份证 / 手机)加密存储 + 脱敏展示;录音加密 + 防篡改
审计写操作全留痕(人 / 时间 / IP / 前后值),180 天,摘要链防篡改
合规押金与预收款全额监管;长者去世后禁止计费;护理录音严禁对外
多租户安全红线:所有 SQL 由框架层强制注入 tenant 条件;跨租户查询必须在平台管理员上下文中显式声明并记审计;独立库租户走独立数据源,不做跨库联查。

10. 部署拓扑

公网 / 机构内网HTTPS · 专线 / VPN · CDN 静态资源
WAF / 负载均衡TLS 终止 · 限流 · 健康检查
↓
API 网关集群鉴权 · 租户识别 · 权限 · 审计埋点
开放 API 网关第三方集成 · 独立配额
↓
应用服务(无状态 · 多副本)经营分析 / 客户营销 / 入住服务 / 护理照护 / 财务结算 / 行政办公 / 数据治理
异步与调度RabbitMQ 事件总线
XXL-Job 定时 ETL
↓
PostgreSQL 主库事务数据 · 主从复制 · 按租户分区
Redis 集群缓存 · 会话 · 分布式锁
Doris / ClickHouse分析与指标聚合
MinIO / 对象存储导入快照 · 报表 · 录音
可观测Prometheus + Grafana · ELK · 链路追踪(traceId 贯穿网关到 SQL)
运维容器化 · 滚动升级 · 备份(每日全量 + WAL)· 演练

11. 非功能指标

指标目标值实现方式
关键看板加载≤ 3 秒ADS 预聚合 + Redis 热点缓存 + 前端骨架屏
关键指标延迟≤ 5 分钟CDC + 事件驱动增量刷新
历史查询响应≤ 3 秒Doris 列存 + 分区裁剪
并发用户≥ 50 / 租户无状态水平扩展
批量处理≤ 30 分钟分批 + 并行 + 断点续跑
系统可用性99.9%(7×24)多副本 + 主从 + 故障转移
数据安全加密传输与存储,日志 180 天TLS + 字段加密 + 审计摘要链
预测准确度偏差率 < 15%历史 + 季节因子模型,按月回测校准

12. 实施路线

阶段一 · 数据接入与驾驶舱(0–3 月)
标准表结构 + 口径字典 + Excel 智能导入 + 经营驾驶舱(实时 + 下钻);打通 456 床 / 405 人的真实数据。
阶段二 · 业务闭环(3–7 月)
入住状态机与电子合同、账单自动生成与核销、退费规则、护理任务与移动端、房态图。
阶段三 · 经营分析深化(7–11 月)
十四部分财务框架、作业成本法、退住归因、根因分析引擎、预见性预测。
阶段四 · 多租户与复制(11 月+)
租户控制面、配置化交付、行业对标、开放 API 与生态集成。

13. 风险与前置条件

关键风险
  • 底层数据质量差 → 智能分析不可用(最强风险)
  • 跨部门填报不联动 → 口径不一,报表互相矛盾
  • 医保 / 长护险接口依赖机构侧资质与网络
  • 多租户隔离若实现不严 → 数据越权(红线)
  • 规则频繁变化若未外置 → 每次改动都要发版
前置条件
  • 成立数据治理小组,先建标准表结构与口径字典
  • 历史 Excel / 月报按部门完成首轮清洗与结构化
  • 明确各岗位数据责任人(谁填报、谁审核)
  • 机构侧提供医保结算资质与网络白名单
  • 业务规则(退费 / 佣金 / 阈值)由财务与院长签字确认
架构结论:先把「数据可信」做扎实(阶段一),再谈「智能」与「预见」。跳过数据治理直接上 AI 分析,结论一定不可用——这是本项目的最大风险,也是产品差异化的真正门槛。