feat(fulfillment): 增加事务 Outbox 同步履约状态

- 用事务 Outbox 和签名 Webhook 替换直接状态回调
- 增加 Outbox 投递 worker、重试与低频对账兜底
- 缓存客户领取页绑定状态并补充签名与迁移测试
This commit is contained in:
yml
2026-11-18 11:00:28 +08:00
parent 54b9f3251d
commit 9b2fcf1d1f
23 changed files with 1324 additions and 130 deletions
@@ -0,0 +1,254 @@
-- 172_platform_fulfillment_outbox.sql
--
-- 事务 Outbox:
-- 业务表变更与待发送事件同事务落库,进程崩溃后仍可由 worker 继续投递。
-- live-hub 接收端通过 integration_inbox 的 event_id 做幂等。
CREATE TABLE IF NOT EXISTS integration_outbox (
id BIGSERIAL PRIMARY KEY,
event_id UUID NOT NULL UNIQUE,
destination TEXT NOT NULL DEFAULT 'live_hub',
event_type TEXT NOT NULL,
dedupe_key TEXT UNIQUE,
payload_json JSONB NOT NULL,
status TEXT NOT NULL DEFAULT 'pending'
CHECK (status IN ('pending', 'processing', 'sent', 'dead')),
attempts INTEGER NOT NULL DEFAULT 0,
next_attempt_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
locked_at TIMESTAMPTZ,
sent_at TIMESTAMPTZ,
last_error TEXT NOT NULL DEFAULT '',
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX IF NOT EXISTS idx_integration_outbox_due
ON integration_outbox (status, next_attempt_at, id);
CREATE INDEX IF NOT EXISTS idx_integration_outbox_destination
ON integration_outbox (destination, status, id);
CREATE TABLE IF NOT EXISTS integration_inbox (
event_id UUID PRIMARY KEY,
source TEXT NOT NULL DEFAULT '',
event_type TEXT NOT NULL DEFAULT '',
received_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
processed_at TIMESTAMPTZ
);
CREATE OR REPLACE FUNCTION enqueue_live_hub_platform_fulfillment_event(
p_order_id BIGINT,
p_order_item_id BIGINT,
p_fulfillment_id BIGINT,
p_reason TEXT
) RETURNS VOID
LANGUAGE plpgsql
AS $$
DECLARE
v_event_id UUID := gen_random_uuid();
v_platform_order_id TEXT := '';
v_dedupe_key TEXT;
BEGIN
SELECT platform_order_id
INTO v_platform_order_id
FROM orders
WHERE id = p_order_id;
IF COALESCE(v_platform_order_id, '') = '' THEN
RETURN;
END IF;
v_dedupe_key := CONCAT(
'platform-fulfillment-order:',
COALESCE(p_order_item_id, 0),
':',
p_reason
);
INSERT INTO integration_outbox (
event_id, destination, event_type, dedupe_key, payload_json, status, created_at
) VALUES (
v_event_id,
'live_hub',
'platform_fulfillment.order_changed',
v_dedupe_key,
jsonb_build_object(
'eventId', v_event_id::text,
'eventType', 'platform_fulfillment.order_changed',
'occurredAt', to_char(
clock_timestamp() AT TIME ZONE 'UTC',
'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'
),
'data', jsonb_build_object(
'orderId', p_order_id,
'orderItemId', p_order_item_id,
'fulfillmentId', p_fulfillment_id,
'platformOrderId', v_platform_order_id,
'reason', p_reason
)
),
'pending',
NOW()
)
ON CONFLICT (dedupe_key) DO NOTHING;
END;
$$;
CREATE OR REPLACE FUNCTION enqueue_platform_fulfillment_from_order()
RETURNS TRIGGER
LANGUAGE plpgsql
AS $$
DECLARE
v_row RECORD;
BEGIN
FOR v_row IN
SELECT oi.id AS order_item_id, f.id AS fulfillment_id
FROM order_items oi
JOIN fulfillments f ON f.order_item_id = oi.id
JOIN manual_fulfillment_configs cfg ON cfg.id = f.fulfillment_config_id
WHERE oi.order_id = NEW.id
AND cfg.douyu_fulfillment_enabled = TRUE
AND f.channel = 'manual'
AND f.status IN ('assigned', 'processing', 'completed')
LOOP
PERFORM enqueue_live_hub_platform_fulfillment_event(
NEW.id,
v_row.order_item_id,
v_row.fulfillment_id,
CONCAT('order:', NEW.pay_status, ':', NEW.order_status)
);
END LOOP;
RETURN NEW;
END;
$$;
CREATE OR REPLACE FUNCTION enqueue_platform_fulfillment_from_fulfillment()
RETURNS TRIGGER
LANGUAGE plpgsql
AS $$
DECLARE
v_order_id BIGINT;
v_enabled BOOLEAN := FALSE;
BEGIN
SELECT oi.order_id
INTO v_order_id
FROM order_items oi
WHERE oi.id = NEW.order_item_id;
SELECT cfg.douyu_fulfillment_enabled
INTO v_enabled
FROM manual_fulfillment_configs cfg
WHERE cfg.id = NEW.fulfillment_config_id;
IF v_order_id IS NOT NULL
AND v_enabled = TRUE
AND NEW.channel = 'manual'
AND NEW.status IN ('assigned', 'processing', 'completed') THEN
PERFORM enqueue_live_hub_platform_fulfillment_event(
v_order_id,
NEW.order_item_id,
NEW.id,
CONCAT('fulfillment:', NEW.status)
);
END IF;
RETURN NEW;
END;
$$;
CREATE OR REPLACE FUNCTION enqueue_platform_fulfillment_from_config()
RETURNS TRIGGER
LANGUAGE plpgsql
AS $$
DECLARE
v_row RECORD;
BEGIN
IF NEW.douyu_fulfillment_enabled = TRUE THEN
FOR v_row IN
SELECT o.id AS order_id, oi.id AS order_item_id, f.id AS fulfillment_id
FROM order_items oi
JOIN orders o ON o.id = oi.order_id
JOIN fulfillments f ON f.order_item_id = oi.id
WHERE f.fulfillment_config_id = NEW.id
AND f.channel = 'manual'
AND f.status IN ('assigned', 'processing', 'completed')
LOOP
PERFORM enqueue_live_hub_platform_fulfillment_event(
v_row.order_id,
v_row.order_item_id,
v_row.fulfillment_id,
'config_enabled'
);
END LOOP;
END IF;
RETURN NEW;
END;
$$;
DROP TRIGGER IF EXISTS trg_platform_fulfillment_order_sync ON orders;
CREATE TRIGGER trg_platform_fulfillment_order_sync
AFTER INSERT OR UPDATE OF pay_status, order_status ON orders
FOR EACH ROW
EXECUTE FUNCTION enqueue_platform_fulfillment_from_order();
DROP TRIGGER IF EXISTS trg_platform_fulfillment_fulfillment_sync ON fulfillments;
CREATE TRIGGER trg_platform_fulfillment_fulfillment_sync
AFTER INSERT OR UPDATE OF channel, status, fulfillment_config_id ON fulfillments
FOR EACH ROW
EXECUTE FUNCTION enqueue_platform_fulfillment_from_fulfillment();
DROP TRIGGER IF EXISTS trg_platform_fulfillment_config_sync
ON manual_fulfillment_configs;
CREATE TRIGGER trg_platform_fulfillment_config_sync
AFTER UPDATE OF douyu_fulfillment_enabled ON manual_fulfillment_configs
FOR EACH ROW
WHEN (OLD.douyu_fulfillment_enabled IS DISTINCT FROM NEW.douyu_fulfillment_enabled)
EXECUTE FUNCTION enqueue_platform_fulfillment_from_config();
-- 上线时补一次存量待履约订单;之后全部由业务写入同事务触发。
INSERT INTO integration_outbox (
event_id, destination, event_type, dedupe_key, payload_json, status, created_at
)
SELECT
event_id,
'live_hub',
'platform_fulfillment.order_changed',
CONCAT('platform-fulfillment-backfill:', candidate.order_item_id),
jsonb_build_object(
'eventId', event_id::text,
'eventType', 'platform_fulfillment.order_changed',
'occurredAt', to_char(
clock_timestamp() AT TIME ZONE 'UTC',
'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'
),
'data', jsonb_build_object(
'orderId', candidate.order_id,
'orderItemId', candidate.order_item_id,
'fulfillmentId', candidate.fulfillment_id,
'platformOrderId', candidate.platform_order_id,
'reason', 'migration_backfill'
)
),
'pending',
NOW()
FROM (
SELECT
gen_random_uuid() AS event_id,
o.id AS order_id,
oi.id AS order_item_id,
f.id AS fulfillment_id,
o.platform_order_id
FROM orders o
JOIN order_items oi ON oi.order_id = o.id
JOIN fulfillments f ON f.order_item_id = oi.id
JOIN manual_fulfillment_configs cfg ON cfg.id = f.fulfillment_config_id
WHERE cfg.douyu_fulfillment_enabled = TRUE
AND f.channel = 'manual'
AND f.status = 'assigned'
AND o.pay_status = 'paid'
AND o.order_status NOT IN ('refunded', 'cancelled', 'closed')
AND oi.quantity = 1
) candidate
ON CONFLICT (dedupe_key) DO NOTHING;
COMMENT ON TABLE integration_outbox IS
'order_site 事务 Outbox;业务提交与待发送事件同事务,worker 负责签名投递';
COMMENT ON TABLE integration_inbox IS
'order_site 入站 Webhook 幂等表;event_id 全局唯一';
@@ -0,0 +1,12 @@
-- 173_douyu_fulfillment_cached_binding.sql
--
-- 客户领取页的绑定状态改由 live-hub 签名 Webhook 投影到本地,
-- 页面刷新只读这些缓存字段,不再服务端反向轮询 live-hub。
ALTER TABLE douyu_fulfillment_tasks
ADD COLUMN IF NOT EXISTS qr_url TEXT NOT NULL DEFAULT '',
ADD COLUMN IF NOT EXISTS qr_generated_at TIMESTAMPTZ,
ADD COLUMN IF NOT EXISTS qr_expires_at TIMESTAMPTZ;
COMMENT ON COLUMN douyu_fulfillment_tasks.qr_url IS
'live-hub 绑定二维码的客户页投影;仅用于展示,不包含内部账号或 CK';