创建数据库表格

pages/mall/delivery/doc/需求文档/README.md

@@ -65,4 +65,87 @@
 - 联调/设计参考（不要用于生产直接落库）：[express_tracking_mock_platform.sql](express_tracking_mock_platform.sql)
 	- 包含平台侧表 + `mock_*` 测试表（故障注入/回放用），仅用于联调与文档说明。
 
+测试/预发环境（不使用 mock_* 表也能联调）：
+- 仍然执行 [express_tracking_platform_upgrade.sql](express_tracking_platform_upgrade.sql) 创建“生产同款”三表。
+- 再执行 [seed_platform_express_test_data.sql](seed_platform_express_test_data.sql) 向 `platform_express_*` 写入少量 TEST_ 前缀示例数据，用于页面联调与排障演示（可随时清理）。
+
+### Ubuntu 上的 Supabase（测试/预发）怎么执行
+
+目标：在 Supabase 上只使用“生产同款”三表进行联调，不创建/不依赖任何 `mock_*` 表。
+
+执行顺序（必须按顺序）：
+1) 执行建表脚本：[express_tracking_platform_upgrade.sql](express_tracking_platform_upgrade.sql)
+2) 执行种子数据脚本：[seed_platform_express_test_data.sql](seed_platform_express_test_data.sql)
+
+方式 A：Supabase Dashboard（推荐）
+- 打开 Supabase 项目 -> SQL Editor
+- 分别粘贴并执行以上两个 SQL 文件内容（先建表、后种子）
+- 建议使用具备 DDL 权限的角色执行（通常 SQL Editor 以高权限执行）
+
+方式 B：Ubuntu 通过 psql 执行（适合自动化/脚本化）
+1) 安装客户端：`sudo apt-get update && sudo apt-get install -y postgresql-client`
+2) 从 Supabase 项目设置里复制连接串（Database -> Connection string），导出环境变量（示例）：
+	`export DATABASE_URL='postgresql://USER:PASSWORD@HOST:6543/postgres?sslmode=require'`
+3) 在仓库根目录执行：
+	- `psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f pages/mall/delivery/doc/需求文档/express_tracking_platform_upgrade.sql`
+	- `psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f pages/mall/delivery/doc/需求文档/seed_platform_express_test_data.sql`
+
+清理测试数据：
+- 种子脚本底部自带清理 SQL（按 `tracking_no LIKE 'TEST_%'` 删除），需要时复制执行即可。
+
+### 如何“伪造第三方推送到数据库”（无需后端）
+
+如果你暂时没有 webhook 接收服务，但希望测试环境表现得像“第三方已经推送了轨迹”，可以直接写数据库：
+- 使用脚本 [simulate_third_party_to_db.sql](simulate_third_party_to_db.sql)
+	- 会同时写入：
+		- `platform_express_event_raw`（原始请求留痕/验签/排障）
+		- `platform_express_tracking_events`（时间线事件）
+		- `platform_express_waybills`（运单摘要）
+- 用法：在 Supabase SQL Editor 打开脚本，修改顶部【参数区】后执行整段。
+- 建议：运单号使用 `TEST_` 前缀，便于按脚本底部清理 SQL 一键删除。
+
+### 与数据库其他表是否“相通”（关联与校验）
+
+这套三表与平台业务表的关键“相通点”是：
+- `public.platform_express_waybills.order_id` 外键引用 `public.ml_orders(id)`（订单主表）。
+
+因此：
+- 如果你的 Supabase（测试/预发）数据库里已经部署了完整商城库（包含 `public.ml_orders`），那么这三表可以直接和订单表联查/联动。
+- 如果你的 Supabase 只是一个“独立的轨迹联调库”，没有 `public.ml_orders`，那么执行建表脚本时会因为外键依赖缺失而失败；此时建议先导入/执行商城主库迁移（让 `ml_orders` 存在），或临时改为仅使用 `order_no` 关联（不建外键），待接入完整主库后再补外键。
+
+在 Supabase SQL Editor 里可执行以下校验：
+
+1) 检查订单表是否存在：
+```sql
+select to_regclass('public.ml_orders') as ml_orders;
+```
+
+2) 检查外键是否创建成功（应该能看到 `platform_express_waybills_order_id_fkey` 或类似名称）：
+```sql
+select
+	conname as fk_name,
+	pg_get_constraintdef(c.oid) as fk_def
+from pg_constraint c
+join pg_class t on t.oid = c.conrelid
+join pg_namespace n on n.oid = t.relnamespace
+where c.contype = 'f'
+	and n.nspname = 'public'
+	and t.relname = 'platform_express_waybills';
+```
+
+3) 联查示例（有真实订单时）：
+```sql
+select
+	o.id as order_id,
+	o.order_no,
+	w.carrier,
+	w.tracking_no,
+	w.current_status_code,
+	w.last_synced_at
+from public.ml_orders o
+left join public.platform_express_waybills w on w.order_id = o.id
+order by o.created_at desc
+limit 20;
+```
+
 建议下一步：在平台侧实现一个可切换的“Mock 数据源”开关（仅测试环境），并在 QA 用例中覆盖重复/乱序/验签失败等注入场景。