feat(fulfillment): 收敛履约状态写入口并追加状态事件

This commit is contained in:
yml2213
2026-11-05 20:52:22 +08:00
parent ca214854bb
commit fcd0c137d5
16 changed files with 1386 additions and 402 deletions
@@ -0,0 +1,212 @@
-- 140_fulfillment_state_events.sql
--
-- 履约状态事件:
-- 1. 订单项履约核心字段每次真实变化都追加一条事件;
-- 2. 状态写入口可写入操作者、动作和原因,遗留直写至少留下 system 事件;
-- 3. 事件表不允许应用更新;父订单删除时允许随外键级联清理。
CREATE TABLE IF NOT EXISTS fulfillment_state_events (
id BIGSERIAL PRIMARY KEY,
order_item_id BIGINT NOT NULL REFERENCES order_items(id) ON DELETE CASCADE,
order_id BIGINT NOT NULL REFERENCES orders(id) ON DELETE CASCADE,
event_type TEXT NOT NULL,
actor_type TEXT NOT NULL DEFAULT 'system',
actor_id TEXT NOT NULL DEFAULT '',
reason TEXT NOT NULL DEFAULT '',
previous_status TEXT,
next_status TEXT,
previous_channel TEXT,
next_channel TEXT,
previous_source TEXT,
next_source TEXT,
previous_locked BOOLEAN,
next_locked BOOLEAN,
previous_pending_reason TEXT,
next_pending_reason TEXT,
previous_pending_detail JSONB,
next_pending_detail JSONB,
payload_json JSONB NOT NULL DEFAULT '{}'::jsonb,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX IF NOT EXISTS idx_fulfillment_state_events_item
ON fulfillment_state_events (order_item_id, id DESC);
CREATE INDEX IF NOT EXISTS idx_fulfillment_state_events_order
ON fulfillment_state_events (order_id, created_at DESC, id DESC);
COMMENT ON TABLE fulfillment_state_events IS
'履约状态追加事件:记录订单项履约状态、渠道、锁定和待办原因的真实变化';
COMMENT ON COLUMN fulfillment_state_events.payload_json IS
'本次变化字段的前后值;空对象表示仅有未知扩展字段变化';
CREATE OR REPLACE FUNCTION record_fulfillment_state_event()
RETURNS TRIGGER
LANGUAGE plpgsql
AS $$
DECLARE
event_type_value TEXT;
actor_type_value TEXT;
actor_id_value TEXT;
reason_value TEXT;
changed_fields JSONB;
BEGIN
IF ROW(
OLD.fulfillment_status,
OLD.fulfillment_channel,
OLD.fulfillment_source,
OLD.fulfillment_locked,
OLD.fulfillment_pending_reason,
OLD.fulfillment_pending_detail,
OLD.fulfillment_reason,
OLD.fulfillment_decided_by,
OLD.fulfillment_decided_at,
OLD.original_channel,
OLD.channel_switch_reason,
OLD.channel_switched_at
) IS NOT DISTINCT FROM ROW(
NEW.fulfillment_status,
NEW.fulfillment_channel,
NEW.fulfillment_source,
NEW.fulfillment_locked,
NEW.fulfillment_pending_reason,
NEW.fulfillment_pending_detail,
NEW.fulfillment_reason,
NEW.fulfillment_decided_by,
NEW.fulfillment_decided_at,
NEW.original_channel,
NEW.channel_switch_reason,
NEW.channel_switched_at
) THEN
RETURN NEW;
END IF;
event_type_value := COALESCE(
NULLIF(BTRIM(current_setting('app.fulfillment_event_type', TRUE)), ''),
'fulfillment_state_changed'
);
actor_type_value := COALESCE(
NULLIF(BTRIM(current_setting('app.fulfillment_actor_type', TRUE)), ''),
'system'
);
actor_id_value := COALESCE(
current_setting('app.fulfillment_actor_id', TRUE),
''
);
reason_value := COALESCE(
current_setting('app.fulfillment_reason', TRUE),
''
);
changed_fields := jsonb_strip_nulls(jsonb_build_object(
'fulfillmentStatus', CASE
WHEN OLD.fulfillment_status IS DISTINCT FROM NEW.fulfillment_status
THEN jsonb_build_object('from', OLD.fulfillment_status, 'to', NEW.fulfillment_status)
END,
'fulfillmentChannel', CASE
WHEN OLD.fulfillment_channel IS DISTINCT FROM NEW.fulfillment_channel
THEN jsonb_build_object('from', OLD.fulfillment_channel, 'to', NEW.fulfillment_channel)
END,
'fulfillmentSource', CASE
WHEN OLD.fulfillment_source IS DISTINCT FROM NEW.fulfillment_source
THEN jsonb_build_object('from', OLD.fulfillment_source, 'to', NEW.fulfillment_source)
END,
'fulfillmentLocked', CASE
WHEN OLD.fulfillment_locked IS DISTINCT FROM NEW.fulfillment_locked
THEN jsonb_build_object('from', OLD.fulfillment_locked, 'to', NEW.fulfillment_locked)
END,
'fulfillmentPendingReason', CASE
WHEN OLD.fulfillment_pending_reason IS DISTINCT FROM NEW.fulfillment_pending_reason
THEN jsonb_build_object(
'from', OLD.fulfillment_pending_reason,
'to', NEW.fulfillment_pending_reason
)
END,
'fulfillmentPendingDetail', CASE
WHEN OLD.fulfillment_pending_detail IS DISTINCT FROM NEW.fulfillment_pending_detail
THEN jsonb_build_object(
'from', OLD.fulfillment_pending_detail,
'to', NEW.fulfillment_pending_detail
)
END
));
INSERT INTO fulfillment_state_events (
order_item_id,
order_id,
event_type,
actor_type,
actor_id,
reason,
previous_status,
next_status,
previous_channel,
next_channel,
previous_source,
next_source,
previous_locked,
next_locked,
previous_pending_reason,
next_pending_reason,
previous_pending_detail,
next_pending_detail,
payload_json
) VALUES (
NEW.id,
NEW.order_id,
LEFT(event_type_value, 100),
LEFT(actor_type_value, 32),
LEFT(actor_id_value, 200),
LEFT(reason_value, 500),
OLD.fulfillment_status,
NEW.fulfillment_status,
OLD.fulfillment_channel,
NEW.fulfillment_channel,
OLD.fulfillment_source,
NEW.fulfillment_source,
OLD.fulfillment_locked,
NEW.fulfillment_locked,
OLD.fulfillment_pending_reason,
NEW.fulfillment_pending_reason,
OLD.fulfillment_pending_detail,
NEW.fulfillment_pending_detail,
changed_fields
);
RETURN NEW;
END;
$$;
DROP TRIGGER IF EXISTS trg_order_items_fulfillment_state_event ON order_items;
CREATE TRIGGER trg_order_items_fulfillment_state_event
AFTER UPDATE OF
fulfillment_status,
fulfillment_channel,
fulfillment_source,
fulfillment_locked,
fulfillment_pending_reason,
fulfillment_pending_detail,
fulfillment_reason,
fulfillment_decided_by,
fulfillment_decided_at,
original_channel,
channel_switch_reason,
channel_switched_at
ON order_items
FOR EACH ROW
EXECUTE FUNCTION record_fulfillment_state_event();
CREATE OR REPLACE FUNCTION reject_fulfillment_state_event_mutation()
RETURNS TRIGGER
LANGUAGE plpgsql
AS $$
BEGIN
RAISE EXCEPTION 'fulfillment_state_events is append-only';
END;
$$;
DROP TRIGGER IF EXISTS trg_fulfillment_state_events_append_only ON fulfillment_state_events;
CREATE TRIGGER trg_fulfillment_state_events_append_only
BEFORE UPDATE ON fulfillment_state_events
FOR EACH ROW
EXECUTE FUNCTION reject_fulfillment_state_event_mutation();