数据库设计

核心表结构与索引策略 · 云驰智运 YunChi · Smart Logistics Cloud

08 - 数据库设计

数据库：MySQL 8.0，字符集 utf8mb4 utf8mb4_0900_ai_ci，引擎 InnoDB。命名规范：表名小写下划线，复数；字段小写下划线；主键 id BIGINT 雪花 ID；通用字段 tenant_id/branch_id/creator_id/created_at/updater_id/updated_at/deleted（逻辑删除）/version（乐观锁）。

1. 多租户字段约定

所有业务表必须包含： - tenant_id BIGINT NOT NULL —— 企业 ID - branch_id BIGINT NOT NULL —— 分站 ID（总公司为 0 或 root） - 所有索引以 (tenant_id, branch_id, ...) 为前缀

MyBatis 拦截器全局自动注入这两个条件，详见 10-RBAC 权限模型设计.md。

2. 核心表清单（v1）

2.1 租户与组织

表	说明
`sys_tenant`	企业（租户）
`sys_branch`	分站
`sys_branch_relation`	分站协作关系（货源共享、运力借用）

2.2 权限

表	说明
`sys_user`	用户（含货主、车主、企业员工统一表 + `user_type`）
`sys_role`	角色
`sys_permission`	权限点（菜单/按钮/接口/导出/打印五维）
`sys_user_role`	用户-角色
`sys_role_permission`	角色-权限
`sys_data_scope`	数据范围（用户/角色 → 可见分站列表 / 自定义 SQL）
`sys_login_log`	登录日志
`sys_op_log`	操作日志

2.3 业务

表	说明
`biz_shipper_profile`	货主资料
`biz_driver_profile`	车主资料 + 信用
`biz_vehicle`	车辆（自有 + 合作）
`biz_fleet`	车队
`biz_cargo`	货源
`biz_order`	订单
`biz_order_item`	订单货物明细
`biz_order_share`	跨分站共享/中转关联
`biz_order_transfer`	跨分站中转记录
`biz_dispatch`	调度/发车单
`biz_track`	轨迹点
`biz_sign`	签收
`biz_address`	地址簿

2.4 财务

表	说明
`fin_account`	账户（用户/企业/平台三级）
`fin_transaction`	流水（复式账本）
`fin_settle`	结算单
`fin_reconcile`	对账单
`fin_invoice`	发票
`fin_withdraw`	提现申请
`fin_payment`	支付记录

2.5 打印

表	说明
`print_template`	打印模板（Schema JSON）
`print_doc`	单据快照（订单完成时冻结）
`print_log`	打印日志

2.6 通知与杂项

表	说明
`msg_message`	站内信
`msg_sms_log`	短信日志
`msg_push_log`	推送日志
`sys_dict`	字典
`sys_config`	系统/企业/分站配置
`sys_file`	文件

3. 关键表 DDL（节选）

3.1 sys_branch

CREATE TABLE sys_branch (
  id           BIGINT       PRIMARY KEY,
  tenant_id    BIGINT       NOT NULL,
  parent_id    BIGINT       NOT NULL DEFAULT 0,
  name         VARCHAR(64)  NOT NULL,
  code         VARCHAR(32)  NOT NULL,
  type         TINYINT      NOT NULL COMMENT '0=总公司,1=分站,2=配货站',
  address      VARCHAR(255),
  contact      VARCHAR(64),
  phone        VARCHAR(32),
  service_area JSON         COMMENT 'GeoJSON 多边形或城市编码列表',
  settle_mode  TINYINT      NOT NULL DEFAULT 0 COMMENT '0=独立 1=统一',
  status       TINYINT      NOT NULL DEFAULT 1,
  created_at   DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at   DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  deleted      TINYINT      NOT NULL DEFAULT 0,
  UNIQUE KEY uk_tenant_code (tenant_id, code),
  KEY idx_tenant (tenant_id)
);

3.2 biz_order

CREATE TABLE biz_order (
  id              BIGINT       PRIMARY KEY,
  tenant_id       BIGINT       NOT NULL,
  branch_id       BIGINT       NOT NULL,
  order_no        VARCHAR(32)  NOT NULL,
  shipper_id      BIGINT       NOT NULL,
  driver_id       BIGINT,
  vehicle_id      BIGINT,
  origin_addr     JSON         NOT NULL,
  dest_addr       JSON         NOT NULL,
  cargo_info      JSON         NOT NULL,
  freight         DECIMAL(12,2) NOT NULL,
  pay_mode        TINYINT      NOT NULL,
  status          VARCHAR(16)  NOT NULL,
  is_transferred  TINYINT      NOT NULL DEFAULT 0,
  src_branch_id   BIGINT       COMMENT '原分站(中转用)',
  remark          VARCHAR(500),
  created_at      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  deleted         TINYINT      NOT NULL DEFAULT 0,
  version         INT          NOT NULL DEFAULT 0,
  UNIQUE KEY uk_order_no (order_no),
  KEY idx_tb_status (tenant_id, branch_id, status),
  KEY idx_tb_shipper (tenant_id, branch_id, shipper_id),
  KEY idx_tb_driver (tenant_id, branch_id, driver_id),
  KEY idx_created (created_at)
);

3.3 print_template

CREATE TABLE print_template (
  id          BIGINT       PRIMARY KEY,
  tenant_id   BIGINT       NOT NULL,
  branch_id   BIGINT       NOT NULL DEFAULT 0 COMMENT '0=企业级模板',
  doc_type    VARCHAR(32)  NOT NULL COMMENT 'WAYBILL/SIGN/SETTLE/...',
  name        VARCHAR(64)  NOT NULL,
  schema_json JSON         NOT NULL COMMENT '可视化编辑器 Schema',
  paper_size  VARCHAR(16)  NOT NULL DEFAULT 'A4',
  is_default  TINYINT      NOT NULL DEFAULT 0,
  status      TINYINT      NOT NULL DEFAULT 1,
  created_at  DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at  DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  KEY idx_tb_doc (tenant_id, branch_id, doc_type)
);

3.4 print_doc / print_log

CREATE TABLE print_doc (
  id          BIGINT       PRIMARY KEY,
  tenant_id   BIGINT       NOT NULL,
  branch_id   BIGINT       NOT NULL,
  doc_type    VARCHAR(32)  NOT NULL,
  doc_no      VARCHAR(32)  NOT NULL,
  ref_type    VARCHAR(32)  NOT NULL COMMENT '关联业务: ORDER/DISPATCH/...',
  ref_id      BIGINT       NOT NULL,
  snapshot    JSON         NOT NULL COMMENT '冻结的打印数据',
  template_id BIGINT       NOT NULL,
  created_at  DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
  UNIQUE KEY uk_doc_no (doc_no),
  KEY idx_tb_ref (tenant_id, branch_id, ref_type, ref_id)
);

CREATE TABLE print_log (
  id          BIGINT       PRIMARY KEY,
  tenant_id   BIGINT       NOT NULL,
  branch_id   BIGINT       NOT NULL,
  doc_id      BIGINT       NOT NULL,
  user_id     BIGINT       NOT NULL,
  printer     VARCHAR(64),
  channel     VARCHAR(16)  NOT NULL COMMENT 'PC_LODOP/MOBILE_BT/PDF',
  status      TINYINT      NOT NULL COMMENT '0=失败 1=成功',
  err_msg     VARCHAR(500),
  created_at  DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
  KEY idx_tb_user (tenant_id, branch_id, user_id),
  KEY idx_doc (doc_id)
);

4. 索引策略

多租户字段必入索引前缀：(tenant_id, branch_id, ...)
时间字段单独建索引便于范围查询
高频查询字段（订单号、手机号）唯一索引
大表（订单、轨迹、打印日志）按月分区（二期）

5. 分库分表预案（二期）

表	阈值	策略
`biz_order`	> 5000 万	按 `tenant_id` hash 16 库 × 按月分表
`biz_track`	> 1 亿	按月分表，3 个月归档
`print_log`	> 1 亿	按月分表，6 个月归档

6. 数据归档

订单完成 6 个月后归档至 ClickHouse / S3
打印日志 1 年后归档
操作日志 6 个月归档

完整 DDL 见 deploy/sql/init.sql。