Appearance
数据架构设计
**本文引用的文件** - [device.sql](file://docs/ddl/device.sql) - [store.sql](file://docs/ddl/store.sql) - [workflow.sql](file://docs/ddl/workflow.sql) - [DynamicDbName.java](file://lemes-cloud/lemes-framework/lemes-framework-datasource/src/main/java/com/lenovo/lemes/datasource/constants/DynamicDbName.java) - [OpenApiController.java](file://lemes-cloud/lemes-framework/lemes-framework-datasource/src/main/java/com/lenovo/lemes/datasource/api/OpenApiController.java) - [MybatisPlusAutoConfiguration.java](file://lemes-cloud/lemes-framework/lemes-framework-service/src/main/java/com/lenovo/lemes/framework/service/mybatis/MybatisPlusAutoConfiguration.java) - [InterceptorProperties.java](file://lemes-cloud/lemes-framework/lemes-framework-service/src/main/java/com/lenovo/lemes/framework/service/mybatis/InterceptorProperties.java) - [application.yml（设备服务）](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-device/lemes-service-dm-device-server/src/main/resources/application.yml) - [application.yml（仓储服务）](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-server/src/main/resources/application.yml) - [application.yml（工作流服务）](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-workflow/lemes-service-dm-workflow-server/src/main/resources/application.yml) - [application.yml（公共服务）](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-server/src/main/resources/application.yml) - [pom.xml（根工程）](file://lemes-cloud/pom.xml)目录
简介
本文件面向DeviceMate项目的数据库与数据访问层，系统化阐述PostgreSQL数据库设计理念、实体关系模型（ER Model）、数据分层架构、MyBatis/MyBatis-Plus数据访问模式、动态数据源与读写分离策略、一致性保障机制、表结构设计要点、迁移与版本管理、备份恢复策略，并提供可操作的实施建议与排障指引。
项目结构
DeviceMate采用多模块微服务架构，数据库层面以“业务域+共享能力”分层组织：
- 业务域数据库
- 设备域：设备主数据、维修工单、保养标准、停机率等
- 仓储域：物料主数据、入库/出库、盘点、报废、个人借用/归还、转移等
- 工作流域：流程图、节点配置、审批日志、用户与角色、事件/资源/通道等
- 共享能力
- 动态数据源适配器：支持按业务或租户切换数据源
- MyBatis-Plus通用能力：分页、自动填充、拦截器配置
- 公共字典、消息、序列号等
章节来源
核心组件
- PostgreSQL数据库
- 设备域、仓储域、工作流域分别对应独立schema或库，按业务域隔离
- 使用序列（sequence）作为自增主键策略，确保高并发下的唯一性与性能
- 动态数据源
- 支持多数据源（如 nabftools、prom、maas 等）按上下文切换
- 提供基于注解或运行时上下文的路由选择
- MyBatis-Plus
- 分页内核、自定义保存/更新拦截、SQL自动填充（创建人/时间、更新人/时间）
- 配置化拦截范围（查询/更新），结合服务侧Mapper包路径进行精细化控制
章节来源
架构总览
DeviceMate数据库层遵循“三层分层 + 多域隔离 + 统一访问”的设计：
- 业务数据层：设备、库存、工单、流程等核心业务表
- 元数据层：字典、配置、权限、序列号等支撑表
- 审计日志层：审批日志、流程日志、变更轨迹等
图表来源
详细组件分析
设备域数据模型
- 关键实体
- 物料主数据（part_main）：物料编号唯一、控制类型、价格、有效期/寿命等
- 线体（line）：工厂/产线/线体维度
- 报废单据（part_scrap_orders/detail）：报废原因、状态、审批
- 锡膏胶水（paste_glue_*）：存储条件、有效期、回温和搅拌要求
- 主键/外键/索引
- 主键：序列自增；部分表通过 (factory_no, part_no) 唯一约束
- 外键：通过业务单号/编号在单据与明细间建立关联
- 索引：对常用查询列（如单号、工厂号、物料号）建立索引
- 约束
- 逻辑删除：is_delete 字段
- 有效标志：valid_flag 控制可用性
- 金额/数量：数值精度约束（如 price、numeric(10,3)）
图表来源
章节来源
仓储域数据模型
- 关键实体
- 仓库主数据（store_main）、库区/库位（store_area/bin）
- 入库单（store_in_orders/detail）、出库单（store_out_orders/detail）
- 盘点单（stock_check_orders）、库存明细（stock_detail）
- 个人借用/归还（personal_apply_borrow_orders/detail）、转移（personal_transfer_orders/detail）
- 主键/外键/索引
- 单据主表与明细通过单号关联
- 库存主表与明细通过仓库/库区/库位/物料唯一定位
- 约束
- 数量/单价精度控制
- 逻辑删除与有效标志
图表来源
章节来源
工作流域数据模型
- 关键实体
- 流程图字典（flow_chart_dict）、业务流程配置（flow_business_config）
- 节点配置（flow_node_config）、审批日志（flow_audit_log）、流程日志（flow_log）
- 用户（flow_user）、角色（flow_user_role）
- Liquibase变更日志（flw_ev_databasechangelog/lock）
- 主键/外键/索引
- 节点配置以 (wf_key, node_index) 组合主键
- 审批日志按流程实例与业务单号聚合
- 约束
- 逻辑删除、状态枚举（审批状态、节点类型等）
图表来源
章节来源
数据访问模式与拦截器
- MyBatis-Plus配置
- 分页内核：内置分页拦截器
- 自定义保存/更新：可选开启，统一处理插入/更新行为
- SQL自动填充：按需忽略表，自动填充创建/更新用户与时间
- 拦截范围配置
- 设备/仓储/工作流/公共服务各自在 application.yml 中声明查询/更新的正则与白/黑名单
- 通过包路径精确限定拦截范围，避免误伤
图表来源
- MybatisPlusAutoConfiguration.java:20-45
- InterceptorProperties.java:19-41
- application.yml（设备服务）:1-33
- application.yml（仓储服务）:1-28
- application.yml（工作流服务）:1-13
- application.yml（公共服务）:1-16
章节来源
- MybatisPlusAutoConfiguration.java:1-47
- InterceptorProperties.java:1-41
- application.yml（设备服务）:1-33
- application.yml（仓储服务）:1-28
- application.yml（工作流服务）:1-13
- application.yml（公共服务）:1-16
动态数据源与读写分离
- 动态数据源
- 常量定义支持多数据源（nabftools/prom/maas）
- OpenAPI提供按数据源查询表清单的能力，便于运维与治理
- 读写分离
- 建议在网关或服务层实现读写路由：写入主库，读取从库
- 对于强一致场景（审批、库存扣减）强制走主库
- 对于报表/查询场景走只读副本
图表来源
章节来源
数据一致性保障
- 事务边界
- 将跨表/跨域的业务操作封装在单个事务中，减少分布式事务复杂度
- 分布式事务
- 对跨库/跨域的强一致需求，采用TCC或Saga模式，或借助消息队列最终一致性
- 缓存与数据库一致性
- 写路径：先写DB，再更新缓存；读路径：优先缓存，未命中回源并回填
- 使用版本号/时间戳做缓存失效与并发冲突检测
- 审计与回溯
- 审批日志与流程日志保留全链路轨迹，支持问题定位与合规审计
章节来源
数据迁移与版本管理
- 版本管理
- 借助Liquibase（flw_ev_databasechangelog/lock）记录变更历史与锁机制
- 变更脚本按模块/域拆分，确保可回滚与幂等
- 迁移策略
- 增量迁移：先加列/建索引，再回填数据，最后启用新逻辑
- 并行双写：新旧两套结构并行一段时间，逐步切流
- 回滚与演练
- 在测试环境先行演练回滚脚本，验证数据完整性
章节来源
备份与恢复
- 备份策略
- 全量+增量结合，保留至少7天热备与30天冷备
- 对关键表（审批日志、流程日志、库存主表）增加备份频率
- 恢复演练
- 定期进行RTO/RPO演练，验证备份有效性与恢复时间
- 灾备
- 异地容灾：主备库跨机房部署，自动化切换
章节来源
依赖分析
- 模块依赖
- 设备/仓储/工作流服务均依赖框架层的MyBatis-Plus与动态数据源
- 公共服务提供字典、序列号、消息等共享能力
- 外部依赖
- MyBatis-Plus Starter、Dynamic Datasource Starter、Liquibase
图表来源
章节来源
性能考虑
- 索引策略
- 对高频过滤/连接字段建立索引（如单号、工厂号、物料号、用户ID）
- 复合索引覆盖常见查询谓词组合
- 分页与扫描
- 合理设置分页大小，避免深度分页；必要时使用游标分页
- 写入优化
- 批量插入/更新，减少往返
- 写热点表采用分区或分片
- 只读查询
- 读写分离，将报表/统计类查询路由至只读副本
故障排查指南
- 常见问题
- 插入失败：检查唯一约束（如 part_main 的 (factory_no, part_no)）
- 查询无结果：确认数据源路由是否正确，索引是否生效
- 审批异常：查看 flow_audit_log 与 flow_log 的流程轨迹
- 排查步骤
- 确认Mapper拦截范围配置是否覆盖目标方法
- 检查自动填充是否被忽略（ignoreTables）
- 核对动态数据源上下文是否正确设置
章节来源
结论
DeviceMate数据库层以“业务域隔离 + 共享能力复用 + 统一访问入口”为核心，结合MyBatis-Plus的拦截器体系与动态数据源能力，实现了高扩展、可维护、可演进的数据架构。通过完善的索引与分页策略、读写分离与一致性保障机制、以及基于Liquibase的版本管理与备份恢复体系，能够满足设备、仓储、工作流等核心业务的高性能与高可靠诉求。
附录
- 表结构设计要点
- 主键：序列自增；唯一约束用于业务键
- 索引：围绕单据号、工厂号、物料号、用户ID建立
- 约束：逻辑删除、有效标志、金额/数量精度
- 运维建议
- 定期清理历史日志与流程快照，控制表规模
- 对关键表进行分区与归档策略
- 建立变更评审与灰度发布流程