# 即时配送 - 数据库详情（字段级说明）

**表前缀**：`ot_`  
**配套文档**：`database_schema.md`（核心表结构摘要）、`index.html`（总览）

---

## 1. 全库通用字段（业务表建议统一挂载）

> 除纯日志/时序/大宽表外，**订单、用户、站点、仓储、车辆、营销**等主业务表建议统一包含下列字段，便于多租户隔离、数据范围、审计与软删除。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `tenant_id` | bigint | 是 | 租户ID（平台/品牌/主体），默认 `1` |
| `agent_id` | bigint | 否 | 代理/加盟节点ID；直营可为空 |
| `station_id` | bigint | 否 | **数据归属站点**（站点级权限与库存范围）；非站点业务可为空 |
| `created_by` | bigint | 否 | 创建人（后台用户ID或系统账号ID） |
| `updated_by` | bigint | 否 | 最后修改人 |
| `created_at` | datetime | 是 | 创建时间 |
| `updated_at` | datetime | 是 | **最后编辑时间**（任意 UPDATE 刷新） |
| `deleted_at` | datetime | 否 | **伪删除**：非空表示已删除，查询默认 `WHERE deleted_at IS NULL` |
| `version` | int | 否 | 乐观锁版本号（高并发写表建议启用） |

**索引建议**：

- 复合索引：`(tenant_id, deleted_at)` 或 `(tenant_id, station_id, deleted_at)`  
- 时间类报表：`(tenant_id, created_at)`、`(tenant_id, updated_at)`

**命名约定**：历史表若使用 `create_time` / `update_time`，可通过视图或迁移逐步对齐为 `created_at` / `updated_at`；新表统一用 `_at`。

---

## 2. 多租户与代理节点模型

### 2.1 概念

| 概念 | 说明 |
|------|------|
| **租户 tenant** | 独立品牌/法人主体/平台实例；数据强隔离的第一道边界 |
| **代理节点 agent** | 加盟商、区域代理、合作方；在租户下再分润、分单、分数据范围 |
| **站点 station** | 仓储/配送物理节点；**站点级权限**控制「谁能看哪站数据」 |

### 2.2 ot_tenant（租户表）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| code | varchar(32) UK | 租户编码 |
| name | varchar(64) | 租户名称 |
| status | tinyint | 1:正常 0:停用 |
| config_json | json | 租户级配置（费率、开关等） |
| created_at / updated_at / deleted_at | | 同通用字段 |

### 2.3 ot_agent_node（代理/加盟节点）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| tenant_id | bigint FK | 所属租户 |
| parent_id | bigint | 上级代理（树形，可选） |
| code | varchar(32) UK | 节点编码（租户内唯一） |
| name | varchar(64) | 节点名称 |
| region_codes | varchar(256) | 负责区域编码（省市区，可选） |
| status | tinyint | |
| created_at / updated_at / deleted_at | | |

### 2.4 ot_station（站点表）— 与权限的关系

在原有站点字段基础上**必须**补充：

| 字段 | 类型 | 说明 |
|------|------|------|
| tenant_id | bigint FK | 站点归属租户 |
| agent_id | bigint FK | 可选，站点归属代理 |
| manager_admin_id | bigint | 站长/默认负责人（后台账号，可选） |

> **业务规则**：订单、入库单、出库单、库存行、车辆若与站点相关，应带 `station_id` + `tenant_id`，列表查询按登录管理员的数据范围过滤。

---

## 3. 站点独立权限管理（RBAC + 数据范围）

### 3.1 设计要点

- **平台级角色**：总部运营、财务、超级管理员 — 可跨站或按租户全量。
- **站点级角色**：站长、库管、调度 — **仅能操作绑定站点**的数据。
- **代理级范围**：代理账号仅能看 `agent_id` 下站点与用户（可配置）。

### 3.2 ot_admin_user（后台用户）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| tenant_id | bigint FK | 主租户（多租户登录可扩展关联表） |
| username | varchar(64) UK | 登录名（建议租户内唯一：UK(tenant_id, username)） |
| password_hash | varchar(128) | |
| real_name | varchar(32) | |
| phone | varchar(20) | |
| status | tinyint | |
| default_station_id | bigint | 默认站点（可选） |
| data_scope_type | tinyint | 1:全部 2:本代理 3:指定站点列表 4:仅默认站 |
| created_at / updated_at / deleted_at | | |

### 3.3 ot_admin_role / ot_admin_permission（平台 RBAC）

| 表 | 说明 |
|----|------|
| ot_admin_role | 角色：name、tenant_id、scope（platform/station）、remark |
| ot_admin_permission | 权限点：code（如 `order:export`）、name、type（menu/api） |
| ot_admin_role_permission | 角色-权限 多对多 |
| ot_admin_user_role | 用户-角色 多对多 |

### 3.4 ot_admin_user_station（用户-站点 数据范围）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| admin_user_id | bigint FK | |
| station_id | bigint FK | 可访问站点 |
| tenant_id | bigint FK | 冗余，便于索引 |

当 `data_scope_type = 指定站点列表` 时，以本表为准；总部角色可省略行表示「全部站点」。

---

## 4. 审计与必要修改记录

### 4.1 ot_data_change_log（通用字段级变更，可选）

适用于需**合规留痕**的字段（金额、状态、权限、库存数量）。

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| tenant_id | bigint | |
| table_name | varchar(64) | 业务表名 |
| record_id | bigint | 主键ID |
| field_name | varchar(64) | 变更字段 |
| old_value | text | 旧值（脱敏后） |
| new_value | text | 新值（脱敏后） |
| change_type | tinyint | 1:insert 2:update 3:delete(软删) |
| operator_id | bigint | 操作人 |
| operator_ip | varchar(45) | |
| remark | varchar(512) | |
| created_at | datetime | |

### 4.2 ot_operation_log（操作日志，粗粒度）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| tenant_id | bigint | |
| admin_user_id | bigint | |
| module | varchar(32) | 模块 order/station/stock |
| action | varchar(32) | create/update/approve |
| request_uri | varchar(256) | |
| request_body_digest | varchar(64) | 摘要，避免存大报文 |
| result | tinyint | 1:成功 0:失败 |
| duration_ms | int | |
| created_at | datetime | |

> **实现建议**：敏感表用触发器/领域事件写 `ot_data_change_log`；网关或 AOP 写 `ot_operation_log`。

---

## 5. 核心业务表示例：ot_order 完整字段（含通用字段）

在 `database_schema.md` 的订单字段基础上，**追加**下列字段（若已存在则对齐命名）：

| 字段 | 类型 | 说明 |
|------|------|------|
| tenant_id | bigint | 租户 |
| agent_id | bigint | 可选，代理分润/分单 |
| station_id | bigint | 接单/履约站点（调度用） |
| created_by / updated_by | bigint | 后台代下单等场景 |
| created_at / updated_at | datetime | 与 create_time/update_time 二选一统一 |
| deleted_at | datetime | 用户删单/运营作废（业务规则决定是否允许） |
| version | int | 抢单、支付回调并发 |

**索引补充**：`(tenant_id, station_id, status, created_at)`、`(tenant_id, deleted_at)`。

---

## 6. 其他表对齐清单（需逐表迁移）

| 表分类 | 表名 | tenant_id | agent_id | station_id | deleted_at | updated_at |
|--------|------|-----------|----------|------------|------------|--------------|
| 订单 | ot_order, ot_order_address, ot_order_item, ot_order_trace | ✓ | 可选 | ✓ | ✓ | ✓ |
| 骑手 | ot_courier, ot_courier_account | ✓ | 可选 | 可选 | ✓ | ✓ |
| 位置轨迹 | ot_courier_location, ot_courier_trace | ✓ | - | 可选 | 轨迹可物理删 | - |
| 用户会员 | ot_user, ot_user_member, ot_address | ✓ | 可选 | - | ✓ | ✓ |
| 营销 | ot_coupon, ot_mall_goods | ✓ | 可选 | 可选 | ✓ | ✓ |
| 站点仓储 | ot_station, ot_station_storage, ot_warehouse_in/out | ✓ | 可选 | ✓ | ✓ | ✓ |
| 车辆 | ot_vehicle, ot_vehicle_location | ✓ | 可选 | ✓ | ✓ | ✓ |
| 后台 | ot_admin_* | ✓ | - | - | ✓ | ✓ |

> 轨迹类海量表可**不建 deleted_at**，采用分区归档；业务上「逻辑删除」用状态位即可。

---

## 7. 版本信息

| 项 | 内容 |
|----|------|
| 文档版本 | v1.0 |
| 更新说明 | 多租户、代理节点、站点 RBAC、通用审计与软删除 |