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
wh_express_company	租户维度快递公司主数据，供平台基础资料页分页查询。	tenant_id、company_code、company_name、service_phone、tracking_url_template、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 等跨服务字段只是逻辑标识，不建立跨数据库外键。