技术架构说明
依据 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 + TypeScript | 18+ | 生态成熟、类型安全、组件化程度高 |
| 前端构建 | Vite | 5.x | 构建快、开发体验好 |
| UI 组件库 | Ant Design | 5.x | 企业级中后台标准,符合 B 端习惯 |
| 状态管理 | Zustand / Redux Toolkit | — | 按业务域拆分 Store,避免全局污染 |
| 数据可视化 | ECharts | 5.x | 图表完备、大数据量渲染性能好 |
| 后端语言 | Java | JDK 17 / 21 LTS | 企业级生态成熟、人才储备充足 |
| 后端框架 | Spring Boot | 3.x | 生态最完善、配套组件齐全 |
| 持久层 | MyBatis-Plus | 3.5.x | SQL 可审计,适合复杂查询 |
| 数据库版本管理 | Flyway | 9.x+ | 变更版本化,多环境一致 |
| API 规范 | RESTful + OpenAPI 3.0 | — | 契约清晰,可自动生成客户端 |
| 鉴权 | Spring Security + JWT | — | 多端统一认证 |
| 主数据库 | PostgreSQL | 15 / 16 | 事务强、复杂查询与扩展性优于 MySQL |
| 缓存 | Redis | 7.x | 热点数据、分布式锁、会话 |
| 分析型库 | Doris / ClickHouse | — | 支撑经营分析的大数据量聚合 |
| 消息队列 | RabbitMQ | 3.x | 领域事件异步协作 |
| 任务调度 | XXL-Job | 2.x | ETL 与定时计算 |
| 对象存储 | 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
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 分析,结论一定不可用——这是本项目的最大风险,也是产品差异化的真正门槛。