baiyue-firstleg/docs/database-schema.md

# 数据库结构与表用途

## 数据归属原则

本项目采用单 Git 仓库、多 Maven 模块、多服务数据库架构。每个业务服务只访问自己的数据库，禁止跨库查询、跨库外键和共享业务表。服务之间只交换业务 ID，并通过 OpenAPI 或领域事件协作。开发环境可以共用一个 MySQL 8 实例，但 schema、数据库账号和迁移历史应保持独立。

商户业务数据必须包含 `tenant_id`。商户端接口只能从已认证 JWT 获取可信租户 ID，并将其加入每个数据查询条件；调用方不能通过请求参数自行选择租户。平台后台接口使用独立路由及 `PLATFORM` 应用身份，并显式指定目标租户。

## 数据库与表总览

| 服务 | 数据库 | 表 | 数据所有权 |
| --- | --- | --- | --- |
| `auth-service` | `baiyue_auth` | `auth_account`、`auth_refresh_token` | 登录凭据、账号安全状态、刷新令牌生命周期 |
| `iam-service` | `baiyue_iam` | `iam_*` | 租户、企业资料、用户、成员、双端角色、菜单/页面/按钮/API权限、数据范围 |
| `order-service` | `baiyue_order` | `ord_*` | 订单聚合、状态历史和待发布领域事件 |
| `warehouse-service` | `baiyue_warehouse` | `wh_*` | 仓库主数据、地址和服务能力 |
| `firstleg-service` | `baiyue_firstleg` | `fl_*` | 头程履约任务、指派过程和消息消费幂等 |
| `file-service` | `baiyue_file` | `file_*` | 文件元数据、临时下载授权和下载审计 |
| `print-service` | `baiyue_print` | `print_*` | 打印模板、打印任务和任务状态历史 |
| `event-bridge-service` | `baiyue_event_bridge` | `bridge_*` | 跨区事件接收幂等、待发送事件和投递尝试记录 |
| `audit-service` | `baiyue_audit` | `sys_audit_log` | 集中式、追加写入的业务审计轨迹 |
| `lastleg-service` | 后续阶段创建 | 暂无业务表 | 尾程派单、配送轨迹和签收凭证 |

SQL 入口位于各服务的 `src/main/resources/db` 目录。

## 认证服务

| 表名 | 用途 | 关键字段 |
| --- | --- | --- |
| `auth_account` | 平台端与商户端共用的统一登录账号；保存密码哈希、锁定状态、令牌版本和默认租户/应用上下文。IAM用户资料与本表通过逻辑ID关联，本表不保存角色权限。 | `username`、`password_hash`、`account_status`、`locked_until`、`token_version`、`default_tenant_id`、`operator_tenant_id`、`default_app_code` |
| `auth_refresh_token` | 保存刷新令牌摘要以及签发时的租户和应用上下文，用于刷新令牌轮换、吊销和到期清理；不保存令牌明文。 | `token_hash`、`user_id`、`tenant_id`、`app_code`、`expires_at`、`revoked_at` |

## IAM服务

| 表名 | 用途 | 关键字段 |
| --- | --- | --- |
| `iam_tenant` | SaaS租户主表，是商户业务数据隔离的根边界，保存企业基本资料、审核结果和启停状态。 | `tenant_code`、`tenant_type`、`status`、`unified_social_credit_code` |
| `iam_tenant_review` | 保存企业注册或资料变更的审核队列、审核人、意见和结果。 | `tenant_id`、`review_type`、`status`、`reviewer_id`、`reviewed_at` |
| `iam_tenant_address` | 保存企业注册地址、办公地址等租户级地址资料。 | `tenant_id`、`address_type`、`is_default` |
| `iam_tenant_qualification` | 保存企业证照、文件地址、有效期和资质审核状态。 | `tenant_id`、`qualification_type`、`document_url`、`valid_to`、`status` |
| `iam_user` | IAM用户资料，连接认证账号与业务身份；不保存登录密码。 | `auth_user_id`、`user_type`、`display_name`、`status` |
| `iam_membership` | 表示某用户在某企业租户中的成员身份，是分配商户端角色的主体。一个用户可加入多个租户。 | `tenant_id`、`user_id`、`member_type`、`status` |
| `iam_role` | 按 `tenant_id + app_code` 隔离角色，支持商户端 `MERCHANT` 与后台端 `PLATFORM` 两套角色体系。 | `tenant_id`、`app_code`、`role_code`、`role_type`、`status` |
| `iam_membership_role` | 成员与角色的多对多关系，描述成员在当前租户和应用端拥有的角色。 | `membership_id`、`role_id`、`tenant_id` |
| `iam_permission` | 统一权限资源树；`permission_type` 支持 `MENU`、`PAGE`、`BUTTON`、`API`，实现权限控制到按钮并将前端权限与后端API权限关联。 | `tenant_id`、`app_code`、`permission_type`、`parent_id`、`permission_code`、`route_path`、`http_method` |
| `iam_role_permission` | 角色与菜单、页面、按钮、API权限的多对多授权关系。 | `role_id`、`permission_id`、`tenant_id` |
| `iam_data_scope` | 在功能权限之外定义角色可查看/操作的数据范围。 | `role_id`、`tenant_id`、`scope_type`、`scope_expression` |

## 订单服务

| 表名 | 用途 | 关键字段 |
| --- | --- | --- |
| `ord_order` | 头程订单聚合根，保存客户、仓库名称与地址、收货时间等下单快照，以及只读履约快递信息和当前状态。 | `tenant_id`、`order_no`、`customer_id`、`customer_name`、`receiving_warehouse_address`、`receiving_time`、`express_company`、`express_tracking_no`、`status`、`version` |
| `ord_order_party` | 固化下单时的发货人和收货人信息，避免外部主数据变化影响历史订单。 | `tenant_id`、`order_id`、`party_type` |
| `ord_order_cargo` | 保存订单货物行、包装件数、重量、体积、申报价值和危险品属性。 | `tenant_id`、`order_id`、`item_no`、`gross_weight_kg`、`volume_cbm` |
| `ord_order_internal_note` | 保存平台运营或履约人员的内部协作备注，不作为客户公开备注。 | `tenant_id`、`order_id`、`content`、`created_by` |
| `ord_order_status_history` | 以不可变记录保存订单每次状态迁移、业务动作、原因和操作人。 | `tenant_id`、`order_id`、`from_status`、`to_status`、`action`、`occurred_at` |
| `ord_outbox_event` | **事务 Outbox 可靠消息表**。订单服务在订单状态变更的同一本地事务中写入待发布领域事件，后台发布器再投递 RocketMQ，从而避免“数据库提交成功但消息发送失败”。它不是普通操作日志，也不是消费者幂等表。 | `aggregate_type`、`aggregate_id`、`event_type`、`payload_json`、`publish_status`、`retry_count`、`next_retry_at`、`published_at` |

## 头程履约服务

| 表名 | 用途 | 关键字段 |
| --- | --- | --- |
| `fl_fulfillment_task` | 接收订单领域事件后形成独立头程履约任务，保存订单快照并管理指派、执行和完成状态。 | `tenant_id`、`order_id`、`order_snapshot_json`、`status`、`assignee_id`、`version` |
| `fl_assignment_history` | 不可变记录头程任务每次负责人指派/改派、原因和操作人。 | `tenant_id`、`task_id`、`previous_assignee_id`、`assignee_id`、`operator_id` |
| `fl_consumed_event` | **消费者幂等去重表**。记录已成功处理的领域事件ID，防止 RocketMQ 重复投递造成重复创建履约任务；它不是消息发布表。 | `event_id`、`event_type`、`consumed_at` |

## 仓库服务

| 表名 | 用途 | 关键字段 |
| --- | --- | --- |
| `wh_warehouse` | 租户维度仓库聚合根，保存仓库编码、名称、类型、国家、时区、联系人和状态。 | `tenant_id`、`warehouse_code`、`warehouse_type`、`country_code`、`status` |
| `wh_warehouse_address` | 保存仓库运营、退货等不同用途的地址和可选经纬度。 | `tenant_id`、`warehouse_id`、`address_type` |
| `wh_service_capability` | 声明仓库可提供的收货、仓储、拣包、退货等服务能力及截单时间。 | `tenant_id`、`warehouse_id`、`capability_code`、`enabled`、`cutoff_time` |
| `wh_partner` | 仓储域内的租户往来单位配置，供订单选择客户、联系人和地址；商户候选查询强制过滤停用数据。 | `tenant_id`、`partner_code`、`partner_name`、`partner_type`、`contact_name`、`contact_phone`、`address_line`、`status` |

## 文件中心服务

| 表名 | 用途 | 关键字段 |
| --- | --- | --- |
| `file_object` | 保存文件元数据、对象存储定位信息、校验值和生命周期状态；文件二进制存放在对象存储中。 | `tenant_id`、`original_name`、`storage_provider`、`object_key`、`content_type`、`size_bytes`、`sha256`、`status` |
| `file_download_token` | 保存临时下载授权及其有效期、使用次数和吊销状态，用于生成受控下载链接。 | `tenant_id`、`file_id`、`token_hash`、`expires_at`、`max_downloads`、`download_count`、`revoked_at` |
| `file_download_log` | 记录文件下载申请与执行结果，供安全追踪和下载审计使用。 | `tenant_id`、`file_id`、`user_id`、`request_id`、`client_ip`、`result`、`failure_reason`、`downloaded_at` |

## 打印服务

| 表名 | 用途 | 关键字段 |
| --- | --- | --- |
| `print_template` | 保存租户级打印模板、模板类型、版本、内容和启停状态。 | `tenant_id`、`template_code`、`template_type`、`content`、`version_no`、`status` |
| `print_job` | 保存打印任务、业务来源、模板快照、打印参数、生成文件标识和当前状态。 | `tenant_id`、`job_no`、`template_id`、`business_type`、`business_id`、`payload_json`、`output_file_id`、`status` |
| `print_job_history` | 追加记录打印任务的状态迁移、执行结果、失败原因和操作主体。 | `tenant_id`、`print_job_id`、`from_status`、`to_status`、`message`、`operator_id`、`occurred_at` |

## 跨区事件桥服务

| 表名 | 用途 | 关键字段 |
| --- | --- | --- |
| `bridge_outbox` | 保存事件桥待发送事件及发布状态，为后续扫描、重试、死信和人工补投保留持久化边界。当前仅有基础表结构，真实扫描调度和跨区发送尚未实现。 | `event_id`、`idempotency_key`、`event_type`、`event_version`、`source_region`、`target_region`、`payload_hash`、`payload_json`、`status`、`retry_count`、`next_retry_at`、`lease_until` |
| `bridge_inbox` | 保存事件桥已接收的事件信封和摘要，用 `event_id` 和 `idempotency_key` 唯一约束实现幂等；相同事件且相同摘要返回重复，相同事件但摘要不同拒绝覆盖。 | `event_id`、`idempotency_key`、`event_type`、`event_version`、`source_region`、`target_region`、`payload_hash`、`payload_json`、`status`、`received_at`、`processed_at` |
| `bridge_delivery_attempt` | 追加记录每一次投递尝试、目标区域、结果、响应码和错误信息，为重试审计与故障定位提供依据。当前真实投递器尚未实现。 | `event_id`、`source_region`、`target_region`、`attempt_no`、`status`、`response_code`、`error_message`、`started_at`、`finished_at` |

`event-bridge-service` 当前是可靠事件桥基础骨架，不代表跨区链路可用于生产。内部服务令牌、目标区域校验和 Inbox 幂等接收已实现并通过事件桥 8 项测试；mTLS、来源白名单、RocketMQ 发布消费、真实跨公网 HTTP 投递、Outbox 扫描调度和业务消费者仍待实现。

## 审计服务

| 表名 | 用途 | 关键字段 |
| --- | --- | --- |
| `sys_audit_log` | **集中业务审计表**。追加记录敏感操作的主体、租户、资源、请求链路、结果及脱敏后的前后快照，用于合规审计和问题追踪；它不同于 Outbox 和消费幂等表。 | `event_type`、`resource_type`、`resource_id`、`tenant_id`、`operator_tenant_id`、`user_id`、`success`、`before_data`、`after_data`、`occurred_at` |

## 三类事件/日志表的区别

| 表 | 写入方 | 核心目标 | 数据生命周期 |
| --- | --- | --- | --- |
| `ord_outbox_event` | 订单业务事务 | 保证业务数据与待发布领域事件最终一致 | 成功发布后保留一段时间，再归档或清理 |
| `fl_consumed_event` | 头程消息消费者 | 对重复投递进行幂等去重 | 至少覆盖消息可能重复投递的最长时间 |
| `bridge_outbox` | 事件桥生产端 | 保存等待投递、重试或死信的版本化跨区事件 | 成功投递并超过审计与补偿窗口后归档 |
| `bridge_inbox` | 事件桥接收端 | 按事件标识和摘要幂等接收，拒绝同标识不同内容 | 至少覆盖跨区重试与人工补投窗口 |
| `sys_audit_log` | 各服务审计组件/审计服务 | 记录谁在何时对什么资源做了什么以及结果 | 按合规要求长期留存，原则上只追加不修改 |

## 服务边界

- `order-service` 拥有客户委托、参与方、货物、商业状态和权威订单号。
- `firstleg-service` 拥有受理后的指派、订舱、集货、干线运输和清关节点。
- `warehouse-service` 拥有仓库主数据和能力；后续入库、库存、库位和出库记录也归属该服务。
- `lastleg-service` 后续负责派单、配送轨迹和签收凭证。
- `file-service` 拥有文件元数据、下载授权和下载审计；对象二进制存放在对象存储中。
- `print-service` 拥有打印模板和打印任务；生成文件只保存 `file_id`，不跨库读取文件表。
- `event-bridge-service` 只负责跨区事件信封的接收幂等、投递记录和可靠传输边界，不拥有订单、头程或尾程业务状态，也不能直接推进业务聚合。
- `order_id`、`warehouse_id` 等跨服务字段只是逻辑标识，不建立跨数据库外键。