diff --git a/README.md b/README.md index a069a17d..d72df404 100644 --- a/README.md +++ b/README.md @@ -54,3 +54,12 @@ ak/ - 请避免提交本地环境相关配置（如 `ak/config.uts`）到仓库（已通过 `.gitignore` 处理） - 分包页面路径变更请同步更新 `pages.json` + +## 📣 配送模块 — 推送与设备（整合说明） + +项目中 `pages/mall/delivery/doc/需求文档` 目录包含多份关于配送、轨迹与推送的需求与建表示例。为了便于 DBA/后端/前端对齐，已将核心要点整合为草稿： + +- 推送建表迁移脚本：`mall_sql/migrations/20260224_add_push_devices_and_notifications.sql` +- 推送完整附录（含平台侧建表示例）：`pages/mall/delivery/doc/需求文档/推送与设备需求文档_含建表附录.md` + +建议下一步：在测试库执行迁移并验证 `notify_queue` / 后台消费者流程。若需要，我可以生成迁移运行命令或提供后台消费者示例代码。 diff --git a/pages/mall/delivery/doc/需求文档/20260224_add_push_devices_and_notifications.sql b/pages/mall/delivery/doc/需求文档/20260224_add_push_devices_and_notifications.sql new file mode 100644 index 00000000..62c2a926 --- /dev/null +++ b/pages/mall/delivery/doc/需求文档/20260224_add_push_devices_and_notifications.sql @@ -0,0 +1,193 @@ +-- ===================================================================================== +-- Add push device table and express_notifications table +-- 目的：保存每个用户/商家设备的推送 CID，并记录由轨迹事件触发的通知消息 +-- 创建日期：2026-02-24 +-- 注意：尽量与仓库中其它迁移风格保持一致；该脚本对已存在对象做 IF NOT EXISTS 检查。 +-- ===================================================================================== + +BEGIN; + +-- 依赖扩展（若已存在则忽略） +CREATE EXTENSION IF NOT EXISTS "uuid-ossp"; + +-- updated_at 自动维护函数（若仓库已有同名函数则不重复创建） +DO $do$ +BEGIN + IF to_regprocedure('public.update_updated_at_column()') IS NULL THEN + CREATE OR REPLACE FUNCTION public.update_updated_at_column() + RETURNS TRIGGER + LANGUAGE plpgsql + AS $func$ + BEGIN + NEW.updated_at = NOW(); + RETURN NEW; + END; + $func$; + END IF; +END $do$; + +-- ===================================================== +-- A. push_devices：设备注册/绑定表 +-- ===================================================== +CREATE TABLE IF NOT EXISTS public.push_devices ( + id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), + + -- 关联主体（user / merchant），使用具体字段便于查询与权限控制。 + user_id UUID NULL, + merchant_id UUID NULL, + + -- 设备推送客户端标识（CID）由推送 SDK 提供 + cid VARCHAR(255) NOT NULL, + + -- 平台/渠道（android / ios / web / huawei / xiaomi） + platform VARCHAR(32) NOT NULL DEFAULT 'android', + + -- 应用标识（用于区分不同打包的 AppID / 环境） + appid VARCHAR(128) NOT NULL DEFAULT 'default', + + -- 设备是否激活（登录/解绑/失效时置 false） + is_active BOOLEAN NOT NULL DEFAULT TRUE, + + -- 设备最后上报时间（用于清理失效设备） + last_seen_at TIMESTAMP WITH TIME ZONE NULL, + + -- 注册来源（可选，用于审计） + registration_source VARCHAR(64) NULL, + + created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW() +); + +-- updated_at 触发器 +DO $$ +BEGIN + IF NOT EXISTS ( + SELECT 1 FROM pg_trigger + WHERE tgname = 'trigger_push_devices_updated_at' + ) THEN + CREATE TRIGGER trigger_push_devices_updated_at + BEFORE UPDATE ON public.push_devices + FOR EACH ROW EXECUTE FUNCTION public.update_updated_at_column(); + END IF; +END $$; + +-- 唯一约束：同一 appid 下 cid 唯一 +CREATE UNIQUE INDEX IF NOT EXISTS ux_push_devices_appid_cid + ON public.push_devices(appid, cid); + +-- 索引：按 user_id/merchant_id 查询是常用路径 +CREATE INDEX IF NOT EXISTS idx_push_devices_user_id ON public.push_devices(user_id); +CREATE INDEX IF NOT EXISTS idx_push_devices_merchant_id ON public.push_devices(merchant_id); +CREATE INDEX IF NOT EXISTS idx_push_devices_is_active ON public.push_devices(is_active); + +-- ===================================================== +-- B. express_notifications：物流相关推送消息中心表 +-- 用途：保存由轨迹事件触发的消息记录（用于消息中心、未读计数与幂等） +-- ===================================================== +CREATE TABLE IF NOT EXISTS public.express_notifications ( + id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), + + -- 接收范围：user / merchant + aud VARCHAR(16) NOT NULL, + recipient_id UUID NOT NULL, + + -- 业务关联（可选）：订单/运单 + order_id UUID NULL, + waybill_id UUID NULL, + + -- 运单与承运方冗余字段，便于快速查询 + tracking_no VARCHAR(64) NULL, + carrier VARCHAR(32) NULL, + + -- 推送消息唯一 id（可由服务端生成并返回给客户端） + message_id VARCHAR(128) NULL, + + -- 事件摘要（下发给客户端的安全/脱敏文案） + event_text_safe TEXT NULL, + status_code VARCHAR(32) NULL, + event_time TIMESTAMP WITH TIME ZONE NULL, + + -- 透传/审计用 payload（不包含敏感字段，raw_payload 请勿透传给客户端） + payload JSONB NULL, + + -- 已读时间（null 表示未读） + read_at TIMESTAMP WITH TIME ZONE NULL, + + -- 幂等键（确保同一事件只生成一条消息） + dedupe_key VARCHAR(256) NULL, + + created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW() +); + +-- updated_at 触发器 +DO $$ +BEGIN + IF NOT EXISTS ( + SELECT 1 FROM pg_trigger + WHERE tgname = 'trigger_express_notifications_updated_at' + ) THEN + CREATE TRIGGER trigger_express_notifications_updated_at + BEFORE UPDATE ON public.express_notifications + FOR EACH ROW EXECUTE FUNCTION public.update_updated_at_column(); + END IF; +END $$; + +-- 索引与约束 +CREATE INDEX IF NOT EXISTS idx_express_notifications_aud_recipient ON public.express_notifications(aud, recipient_id); +CREATE INDEX IF NOT EXISTS idx_express_notifications_order_id ON public.express_notifications(order_id); +CREATE INDEX IF NOT EXISTS idx_express_notifications_waybill_id ON public.express_notifications(waybill_id); +CREATE INDEX IF NOT EXISTS idx_express_notifications_created_at ON public.express_notifications(created_at); +CREATE INDEX IF NOT EXISTS idx_express_notifications_read_at ON public.express_notifications(read_at); + +-- 若使用 message_id 做幂等（外部系统/队列），则建立唯一索引 +CREATE UNIQUE INDEX IF NOT EXISTS ux_express_notifications_message_id + ON public.express_notifications(message_id) WHERE message_id IS NOT NULL; + +-- ===================================================== +-- C. 兼容性与外键（若目标表存在则添加外键约束；若不存在则保留字段） +-- 说明：为避免迁移失败，我们在这里尝试添加外键，但使用 DO $$ ... EXCEPTION 来忽略不存在表的情况。 +-- ===================================================== +DO $$ +BEGIN + -- 尝试为 push_devices.user_id 添加外键（如果 ak_users 表存在） + IF EXISTS (SELECT 1 FROM pg_class c JOIN pg_namespace n ON c.relnamespace = n.oid WHERE c.relname = 'ak_users' AND n.nspname = 'public') THEN + BEGIN + ALTER TABLE public.push_devices + ADD CONSTRAINT fk_push_devices_user FOREIGN KEY (user_id) REFERENCES public.ak_users(id) ON DELETE SET NULL; + EXCEPTION WHEN duplicate_object THEN + -- 已存在约束则忽略 + NULL; + END; + END IF; + + -- 尝试为 express_notifications.order_id 添加外键（如果 ml_orders 表存在） + IF EXISTS (SELECT 1 FROM pg_class c JOIN pg_namespace n ON c.relnamespace = n.oid WHERE c.relname = 'ml_orders' AND n.nspname = 'public') THEN + BEGIN + ALTER TABLE public.express_notifications + ADD CONSTRAINT fk_express_notifications_order FOREIGN KEY (order_id) REFERENCES public.ml_orders(id) ON DELETE SET NULL; + EXCEPTION WHEN duplicate_object THEN + NULL; + END; + END IF; + + -- 尝试为 express_notifications.waybill_id 添加外键（如果 platform_express_waybills 表存在） + IF EXISTS (SELECT 1 FROM pg_class c JOIN pg_namespace n ON c.relnamespace = n.oid WHERE c.relname = 'platform_express_waybills' AND n.nspname = 'public') THEN + BEGIN + ALTER TABLE public.express_notifications + ADD CONSTRAINT fk_express_notifications_waybill FOREIGN KEY (waybill_id) REFERENCES public.platform_express_waybills(id) ON DELETE SET NULL; + EXCEPTION WHEN duplicate_object THEN + NULL; + END; + END IF; +END $$; + +COMMIT; + +-- ===================================================================================== +-- 使用说明（简要） +-- 1) `push_devices` 存储设备 CID 与所属主体（user_id / merchant_id），提供活跃检测与解绑能力。 +-- 2) `express_notifications` 存储消息中心记录；生成通知时写入该表並异步向 `push_devices` 中匹配设备发送推送。 +-- 3) 推荐在应用层实现：当用户登出或解绑设备时将 `push_devices.is_active` 置 false。 +-- 4) 可按需要添加清理任务：清理 long-inactive 的 `push_devices`（例如 180 天未上报）。 +-- ===================================================================================== diff --git a/pages/mall/delivery/doc/需求文档/推送与设备需求文档.md b/pages/mall/delivery/doc/需求文档/推送与设备需求文档.md new file mode 100644 index 00000000..528a8bb2 --- /dev/null +++ b/pages/mall/delivery/doc/需求文档/推送与设备需求文档.md @@ -0,0 +1,111 @@ +# 推送与设备需求文档 + +本文档定义平台端基于 `push_devices` 与 `express_notifications` 的推送能力需求，覆盖设备 CID 的采集/管理、物流事件驱动的消息生成与送达、隐私与验收标准。 + +关联文档： +- 配送模块需求文档.md +- 接口规范.md +- 前端字段清单.md +- 状态映射表.md +- mall_sql/migrations/20260224_add_push_devices_and_notifications.sql + +## 一、目标 +- 保存每个用户/商家设备的推送 CID（支持多设备、多平台、多 appid）。 +- 在轨迹事件触发时，生成消息中心记录并向对应活跃设备下发推送（通知/透传）。 +- 提供消息幂等、未读/已读管理与审计能力，且严格控制敏感字段透传。 + +## 二、范围 +- 包含：设备注册/解绑、设备活跃检测、消息表写入、消息去重、对外推送触发接口与消息中心 API。 +- 不包含：具体第三方推送厂商通道的离线能力（小米/华为等厂商通道配置为后续任务）。 + +## 三、术语 +- CID：Push 平台分配的 client id。 +- 设备：一台移动设备或浏览器实例，用 `cid + appid` 唯一标识。 +- 消息（Notification）：由轨迹事件驱动的逻辑消息，写入 `express_notifications` 并可同步到消息中心与 Push 通道。 + +## 四、数据表与字段（概要） +说明：详细 DDL 请参考迁移脚本：`mall_sql/migrations/20260224_add_push_devices_and_notifications.sql`。 + +- `push_devices` + - `id, user_id, merchant_id, cid, platform, appid, is_active, last_seen_at, registration_source, created_at, updated_at` + - 约束：同一 `appid` 下 `cid` 唯一；按 `user_id/merchant_id` 建索引。 + +- `express_notifications` + - `id, aud, recipient_id, order_id, waybill_id, tracking_no, carrier, message_id, event_text_safe, status_code, event_time, payload, read_at, dedupe_key, created_at, updated_at` + - 幂等：`message_id` 唯一（若存在）或 `dedupe_key` 在生成逻辑层保证不重复写入。 + +## 五、REST API 设计（建议） +注：API 端点为示例，具体实现放在平台后端网关下。 + +1) 设备管理 +- `POST /api/v1/push/register` — 注册/更新设备 + 请求体：`{user_id?, merchant_id?, cid, platform, appid, registration_source}` + 返回：设备记录 + +- `POST /api/v1/push/unregister` — 解绑设备 + 请求体：`{cid, appid, user_id?}` + +- `GET /api/v1/push/devices?user_id=...` — 列出某用户活跃设备 + +2) 消息与消息中心 +- `POST /api/v1/notifications/express/create` — 由后端服务写入消息并触发推送（通常由 EventProcessor 调用） + 请求体示例： + ```json + { + "aud":"user", + "recipient_id":"", + "order_id":"", + "waybill_id":"", + "tracking_no":"YT123...", + "carrier":"YTO", + "message_id":"msg_...", + "event_text_safe":"包裹正在派送中，派送员预计今日到达", + "status_code":"OUT_FOR_DELIVERY", + "event_time":"2026-02-24T10:00:00+08:00", + "payload": {"deeplink": {"path":"/pages/order/detail","query":{"order_no":"ORD_...","tab":"logistics"}}}, + "dedupe_key":"waybill|event_id_or_composite" + } + ``` + +- `GET /api/v1/notifications?aud=user&recipient_id=...` — 列表 +- `POST /api/v1/notifications/read` — 标记已读（按 message_id 或 recipient_id+order_id 批量） + +3) 运维/调试 +- `GET /api/v1/push/stats` — 推送成功率/失败率/未读数（用于监控） + +## 六、消息生成与推送流程 +1) 当 `platform_express_tracking_events` 写入新事件且满足推送策略（见下），平台事件处理器调用 `express_notifications.create` 写入消息表（使用 `dedupe_key` 保证幂等）。 +2) 写入成功后，异步任务查询 `push_devices`（按 `aud/recipient_id/appid/is_active`）获取目标 `cid` 列表并调用推送通道（uni-push2 或后端统一推送服务）。 +3) 推送返回结果写入日志并根据结果更新统计；若设备失效则将 `push_devices.is_active` 置 false（或记录探测失败）。 + +推送策略建议（MVP）：只在状态级变化或关键状态产生消息：`SHIPPED/OUT_FOR_DELIVERY/READY_FOR_PICKUP/DELIVERED/EXCEPTION/RETURNED`。 + +## 七、隐私与安全 +- 不通过 push 透传 `raw_payload`、完整手机号、签名、密钥等敏感信息。 +- `event_text_safe` 为由平台清洗/脱敏后的文案，任何发送给客户端的文案必须经过该字段。 +- 设备绑定时不得将密钥写入前端；CID 由客户端 SDK 提供，后端仅关联 `user_id`/`merchant_id`。 +- 审计：对 `push_devices` 的创建/更新/读取 `raw_payload` 访问均需记录审计日志（平台侧实现）。 + +## 八、非功能需求 +- 可用性：消息写入及触发应具备重试机制，推送通道建议异步队列化处理。 +- 可观测性：记录每条消息的 `created_at`, `sent_status`, `sent_at`, `response_code`（推送日志由推送通道记录）。 +- 可扩展性：支持按 `appid` 区分不同应用/环境，便于多包管理。 + +## 九、验收标准 +1) 能成功注册设备并查询到对应 `cid`（按 `user_id`）。 +2) 插入一条关键轨迹事件后：在 `express_notifications` 中新增消息且按活跃设备下发推送（模拟推送通道验证）。 +3) 相同事件重复到达不会产生重复消息（由 `dedupe_key` 或 `message_id` 保证）。 +4) 推送 payload 不包含敏感信息（检查 `payload` 字段）。 + +## 十、迁移与回滚建议 +- 在执行迁移脚本前，先在测试库运行并检查索引与触发器。 +- 若生产已有其它命名冲突，请先手工评估 `push_devices` 与 `express_notifications` 字段与现有表的兼容性。 + +## 十一、参考 +- `pages/mall/delivery/doc/需求文档/配送模块需求文档.md` +- `pages/mall/delivery/doc/需求文档/接口规范.md` +- `mall_sql/migrations/20260224_add_push_devices_and_notifications.sql` + +--- +作者：自动生成（可手动微调） +日期：2026-02-24 diff --git a/pages/mall/delivery/doc/需求文档/推送与设备需求文档_含建表附录.md b/pages/mall/delivery/doc/需求文档/推送与设备需求文档_含建表附录.md new file mode 100644 index 00000000..3905dcff --- /dev/null +++ b/pages/mall/delivery/doc/需求文档/推送与设备需求文档_含建表附录.md @@ -0,0 +1,276 @@ +# 推送与设备需求文档（含建表附录） + +本文档为 `推送与设备需求文档.md` 的拷贝，并在末尾追加 `express_tracking_platform_upgrade.sql` 的建表示例，便于 DBA / 后端直接参考与执行。 + +--- + +(以下为需求文档原文) + + +# 推送与设备需求文档 + +本文档定义平台端基于 `push_devices` 与 `express_notifications` 的推送能力需求，覆盖设备 CID 的采集/管理、物流事件驱动的消息生成与送达、隐私与验收标准。 + +关联文档： +- 配送模块需求文档.md +- 接口规范.md +- 前端字段清单.md +- 状态映射表.md +- mall_sql/migrations/20260224_add_push_devices_and_notifications.sql + +## 一、目标 +- 保存每个用户/商家设备的推送 CID（支持多设备、多平台、多 appid）。 +- 在轨迹事件触发时，生成消息中心记录并向对应活跃设备下发推送（通知/透传）。 +- 提供消息幂等、未读/已读管理与审计能力，且严格控制敏感字段透传。 + +## 二、范围 +- 包含：设备注册/解绑、设备活跃检测、消息表写入、消息去重、对外推送触发接口与消息中心 API。 +- 不包含：具体第三方推送厂商通道的离线能力（小米/华为等厂商通道配置为后续任务）。 + +## 三、术语 +- CID：Push 平台分配的 client id。 +- 设备：一台移动设备或浏览器实例，用 `cid + appid` 唯一标识。 +- 消息（Notification）：由轨迹事件驱动的逻辑消息，写入 `express_notifications` 并可同步到消息中心与 Push 通道。 + +## 四、数据表与字段（概要） +说明：详细 DDL 请参考迁移脚本：`mall_sql/migrations/20260224_add_push_devices_and_notifications.sql`。 + +- `push_devices` + - `id, user_id, merchant_id, cid, platform, appid, is_active, last_seen_at, registration_source, created_at, updated_at` + - 约束：同一 `appid` 下 `cid` 唯一；按 `user_id/merchant_id` 建索引。 + +- `express_notifications` + - `id, aud, recipient_id, order_id, waybill_id, tracking_no, carrier, message_id, event_text_safe, status_code, event_time, payload, read_at, dedupe_key, created_at, updated_at` + - 幂等：`message_id` 唯一（若存在）或 `dedupe_key` 在生成逻辑层保证不重复写入。 + +## 五、REST API 设计（建议） +注：API 端点为示例，具体实现放在平台后端网关下。 + +1) 设备管理 +- `POST /api/v1/push/register` — 注册/更新设备 + 请求体：`{user_id?, merchant_id?, cid, platform, appid, registration_source}` + 返回：设备记录 + +- `POST /api/v1/push/unregister` — 解绑设备 + 请求体：`{cid, appid, user_id?}` + +- `GET /api/v1/push/devices?user_id=...` — 列出某用户活跃设备 + +2) 消息与消息中心 +- `POST /api/v1/notifications/express/create` — 由后端服务写入消息并触发推送（通常由 EventProcessor 调用） + 请求体示例： + ```json + { + "aud":"user", + "recipient_id":"", + "order_id":"", + "waybill_id":"", + "tracking_no":"YT123...", + "carrier":"YTO", + "message_id":"msg_...", + "event_text_safe":"包裹正在派送中，派送员预计今日到达", + "status_code":"OUT_FOR_DELIVERY", + "event_time":"2026-02-24T10:00:00+08:00", + "payload": {"deeplink": {"path":"/pages/order/detail","query":{"order_no":"ORD_...","tab":"logistics"}}}, + "dedupe_key":"waybill|event_id_or_composite" + } + ``` + +- `GET /api/v1/notifications?aud=user&recipient_id=...` — 列表 +- `POST /api/v1/notifications/read` — 标记已读（按 message_id 或 recipient_id+order_id 批量） + +3) 运维/调试 +- `GET /api/v1/push/stats` — 推送成功率/失败率/未读数（用于监控） + +## 六、消息生成与推送流程 +1) 当 `platform_express_tracking_events` 写入新事件且满足推送策略（见下），平台事件处理器调用 `express_notifications.create` 写入消息表（使用 `dedupe_key` 保证幂等）。 +2) 写入成功后，异步任务查询 `push_devices`（按 `aud/recipient_id/appid/is_active`）获取目标 `cid` 列表并调用推送通道（uni-push2 或后端统一推送服务）。 +3) 推送返回结果写入日志并根据结果更新统计；若设备失效则将 `push_devices.is_active` 置 false（或记录探测失败）。 + +推送策略建议（MVP）：只在状态级变化或关键状态产生消息：`SHIPPED/OUT_FOR_DELIVERY/READY_FOR_PICKUP/DELIVERED/EXCEPTION/RETURNED`。 + +## 七、隐私与安全 +- 不通过 push 透传 `raw_payload`、完整手机号、签名、密钥等敏感信息。 +- `event_text_safe` 为由平台清洗/脱敏后的文案，任何发送给客户端的文案必须经过该字段。 +- 设备绑定时不得将密钥写入前端；CID 由客户端 SDK 提供，后端仅关联 `user_id`/`merchant_id`。 +- 审计：对 `push_devices` 的创建/更新/读取 `raw_payload` 访问均需记录审计日志（平台侧实现）。 + +## 八、非功能需求 +- 可用性：消息写入及触发应具备重试机制，推送通道建议异步队列化处理。 +- 可观测性：记录每条消息的 `created_at`, `sent_status`, `sent_at`, `response_code`（推送日志由推送通道记录）。 +- 可扩展性：支持按 `appid` 区分不同应用/环境，便于多包管理。 + +## 九、验收标准 +1) 能成功注册设备并查询到对应 `cid`（按 `user_id`）。 +2) 插入一条关键轨迹事件后：在 `express_notifications` 中新增消息且按活跃设备下发推送（模拟推送通道验证）。 +3) 相同事件重复到达不会产生重复消息（由 `dedupe_key` 或 `message_id` 保证）。 +4) 推送 payload 不包含敏感信息（检查 `payload` 字段）。 + +## 十、迁移与回滚建议 +- 在执行迁移脚本前，先在测试库运行并检查索引与触发器。 +- 若生产已有其它命名冲突，请先手工评估 `push_devices` 与 `express_notifications` 字段与现有表的兼容性。 + + +## 十一、参考 +- `pages/mall/delivery/doc/需求文档/配送模块需求文档.md` +- `pages/mall/delivery/doc/需求文档/接口规范.md` +- `mall_sql/migrations/20260224_add_push_devices_and_notifications.sql` + +--- + +(以下为与目录中其他文档的对齐要点、触发器/队列与视图示例) + +## 与目录中其他文档的对齐要点 +为保证与 `配送模块需求文档.md`、`接口规范.md`、`前端字段清单.md`、`状态映射表.md` 一致，本文档做如下约定并实现兼容： + +- 事件模型：消息生成使用 `platform_express_tracking_events` 的归一化字段（`event_id/event_time/event_code/event_text/status_code/waybill_id`）。 +- 状态口径：使用 `状态映射表.md` 中定义的 `ORDER_PLACED/SHIPPED/IN_TRANSIT/OUT_FOR_DELIVERY/READY_FOR_PICKUP/DELIVERED/EXCEPTION/RETURNED` 作为 `express_notifications.status_code` 值域。 +- 字段契约：客户端仅消费 `express_notifications.event_text_safe`、`status_code`、`event_time`、`payload.deeplink`；原始 `raw_payload` 不对客户端下发（仅后台审计可见）。 +- Webhook 与控制面：推送触发入口由事件处理器（或 Mock Server 控制面）调用 `POST /api/v1/notifications/express/create` 写入消息表并触发推送。 + +## 自动化：事件入库 -> 消息生成（触发器示例） +建议在应用层以异步任务方式实现；以下为数据库触发器/队列化的参考实现思路（Postgres + pg_notify 或写入中间队列表）： + +1) 触发器：在 `platform_express_tracking_events` 插入后触发 `notify_new_tracking_event`，把 `waybill_id/event_time/status_code/event_id` 写入 `notify_queue`（或使用 `pg_notify` 发消息）。 +2) 后台消费者订阅 `notify_queue`（或 LISTEN/NOTIFY），根据 `推送策略` 和 `recipient` 映射生成 `express_notifications` 并把实际推送任务入列（调用推送服务）。 + +示例 SQL（简化，仅供参考）： + +```sql +-- 中间队列表（示例） +CREATE TABLE IF NOT EXISTS public.notify_queue ( + id uuid PRIMARY KEY DEFAULT gen_random_uuid(), + waybill_id uuid NOT NULL, + event_id varchar(128) NULL, + status_code varchar(32) NULL, + event_time timestamptz NULL, + processed boolean NOT NULL DEFAULT false, + created_at timestamptz NOT NULL DEFAULT now() +); + +-- 触发器函数：插入 notify_queue +CREATE OR REPLACE FUNCTION public.trg_platform_event_after_insert() +RETURNS trigger AS $$ +BEGIN + INSERT INTO public.notify_queue(waybill_id,event_id,status_code,event_time) + VALUES (NEW.waybill_id, NEW.event_id, NEW.status_code, NEW.event_time); + RETURN NEW; +END; +$$ LANGUAGE plpgsql; + +-- 建触发器（若已存在请在应用层采用幂等部署） +DO $$ +BEGIN + IF NOT EXISTS (SELECT 1 FROM pg_trigger WHERE tgname = 'trigger_platform_events_after_insert') THEN + CREATE TRIGGER trigger_platform_events_after_insert + AFTER INSERT ON public.platform_express_tracking_events + FOR EACH ROW + EXECUTE FUNCTION public.trg_platform_event_after_insert(); + END IF; +END $$; +``` + +说明：生产环境推荐把业务逻辑放在后台消费者（可重试、可观测），数据库触发器仅负责把事件推入可靠队列。 + +## 视图与未读计数（示例） +为方便前端读取未读数与消息列表，建议创建以下视图或物化视图： + +1) 用户消息视图（按 user） + +```sql +CREATE OR REPLACE VIEW public.vw_express_notifications_for_user AS +SELECT n.* +FROM public.express_notifications n +WHERE n.aud = 'user'; +``` + +2) 未读计数物化视图（按用户/商家） + +```sql +CREATE MATERIALIZED VIEW IF NOT EXISTS public.mv_unread_notifications_count AS +SELECT aud, recipient_id, count(*) FILTER (WHERE read_at IS NULL) AS unread_count +FROM public.express_notifications +GROUP BY aud, recipient_id; + +-- 刷新策略：可按计划任务或在写入消息时触发快速更新 +``` + +## 示例：从事件到推送的完整查询链 +- 查找某 `order_id` 的活跃设备： + +```sql +SELECT p.* FROM public.push_devices p +WHERE p.user_id = (SELECT o.user_id FROM public.ml_orders o WHERE o.id = '') + AND p.appid = 'default' AND p.is_active = true; +``` + +- 创建消息并返回 message_id 的示例（业务层用 INSERT ... RETURNING）： + +```sql +INSERT INTO public.express_notifications (aud, recipient_id, order_id, waybill_id, tracking_no, carrier, message_id, event_text_safe, status_code, event_time, payload, dedupe_key) +VALUES ('user', '', '', '', 'TEST_123', 'YTO', 'msg_sync_123', '包裹正在派送中', 'OUT_FOR_DELIVERY', now(), jsonb_build_object('deeplink', jsonb_build_object('path','/pages/order/detail','query',jsonb_build_object('order_no','ORD_...'))), 'dedupe_...' ) +RETURNING id; +``` + +## 与现有文档的补充修改建议（供你选择采纳） +- 在 `接口规范.md` 中增加一节：`消息中心/推送契约`，描述 `express_notifications` 的字段与 `POST /api/v1/notifications/express/create` 示例。 +- 在 `前端字段清单.md` 中明确 `event_text_safe` 的清洗规则与允许的占位符（例如 `{carrier}`、`{eta}`）。 +- 在 `状态映射表.md` 中加入 `推送触发级别` 一栏，列出哪些 `status_code` 会触发推送（默认为关键状态）。 + +## 下一步 +我可以： +- 将上述触发器与视图 SQL 附加到迁移目录作为可选脚本（例如：`mall_sql/migrations/20260224_notifications_trigger_and_views.sql`），并生成 psql/PowerShell 执行命令；或 +- 只生成后台消费者示例（Node.js + supabase 或 pg 客户端），负责从 `notify_queue` 消费并调用推送通道。 + +请告诉我要先做哪一项。 + +(以下为附录：平台侧建表示例摘录) + +```sql +-- 第三方快递轨迹（平台侧）表结构升级 (PostgreSQL + Supabase) +-- 用途: 引入第三方承运方运单与轨迹事件的统一入库模型 +BEGIN; + +CREATE EXTENSION IF NOT EXISTS "uuid-ossp"; +CREATE EXTENSION IF NOT EXISTS "btree_gin"; + +DO $do$ +BEGIN + IF to_regprocedure('public.update_updated_at_column()') IS NULL THEN + CREATE OR REPLACE FUNCTION public.update_updated_at_column() + RETURNS TRIGGER + LANGUAGE plpgsql + AS $func$ + BEGIN + NEW.updated_at = NOW(); + RETURN NEW; + END; + $func$; + END IF; +END $do$; + +CREATE TABLE IF NOT EXISTS public.platform_express_waybills ( + id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), + order_id UUID NULL REFERENCES public.ml_orders(id) ON DELETE SET NULL, + order_no VARCHAR(64) NULL, + carrier VARCHAR(32) NOT NULL, + tracking_no VARCHAR(64) NOT NULL, + source VARCHAR(16) NOT NULL DEFAULT 'mock', + current_status_code VARCHAR(32) NOT NULL DEFAULT 'SHIPPED', + current_status_text TEXT NULL, + eta TIMESTAMP WITH TIME ZONE NULL, + last_synced_at TIMESTAMP WITH TIME ZONE NULL, + created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), + CONSTRAINT uk_platform_express_waybill UNIQUE (carrier, tracking_no) +); + +-- 跳过部分 + +COMMIT; +``` + +--- + +作者：自动生成（可手动微调） +日期：2026-02-24 diff --git a/pages/user/login.uvue b/pages/user/login.uvue index 45f111a8..124dfc1c 100644 --- a/pages/user/login.uvue +++ b/pages/user/login.uvue @@ -141,6 +141,7 @@