From 86c8417d4ba6b494097bb2e9bf7a3dc9e2392009 Mon Sep 17 00:00:00 2001 From: yml Date: Wed, 18 Nov 2026 16:57:57 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96(=E7=9B=B4=E6=92=AD=E5=B1=A5?= =?UTF-8?q?=E7=BA=A6):=20=E6=94=B9=E4=B8=BA=E8=AE=A2=E5=8D=95=E5=BF=AB?= =?UTF-8?q?=E7=85=A7=E4=BA=8B=E4=BB=B6=E9=A9=B1=E5=8A=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...platform_fulfillment_snapshot_contract.sql | 253 ++++++++++++++++++ apps/backend/src/routes/douyu-fulfillment.ts | 9 + .../douyu-fulfillment-service.ts | 117 ++++++-- .../douyu-fulfillment.test.ts | 8 + .../fulfillment/channel-assign-service.ts | 68 ++++- .../fulfillment-event-driven-pipeline.test.ts | 68 +++++ .../fulfillment-routing.integration.test.ts | 20 ++ .../integration/outbox-migration.test.ts | 17 ++ .../src/services/integration/outbox-worker.ts | 22 ++ ...orm-fulfillment-outbox.integration.test.ts | 111 ++++++++ .../realtime/realtime-event-service.ts | 92 ++++++- .../scheduler/finance-pipeline-jobs.ts | 17 +- .../services/scheduler/scheduler-service.ts | 19 ++ .../sync-worker-orders-service.ts | 40 ++- .../src/components/WorkOrderEventTimeline.tsx | 2 + apps/frontend/src/hooks/useRealtimeEvents.ts | 18 +- apps/frontend/src/layouts/AdminLayout.tsx | 8 + .../admin/AdminFulfillmentChannelPage.tsx | 7 +- .../DouyuFulfillmentPage.tsx | 39 +-- .../tests/fulfillment-realtime-flow.test.ts | 36 +++ docs/统一订单履约与财务模型-权威版.md | 40 ++- 21 files changed, 934 insertions(+), 77 deletions(-) create mode 100644 apps/backend/src/db/migrations/172_platform_fulfillment_snapshot_contract.sql create mode 100644 apps/backend/src/services/fulfillment/fulfillment-event-driven-pipeline.test.ts create mode 100644 apps/backend/src/services/integration/platform-fulfillment-outbox.integration.test.ts create mode 100644 apps/frontend/tests/fulfillment-realtime-flow.test.ts diff --git a/apps/backend/src/db/migrations/172_platform_fulfillment_snapshot_contract.sql b/apps/backend/src/db/migrations/172_platform_fulfillment_snapshot_contract.sql new file mode 100644 index 00000000..fc5b5e83 --- /dev/null +++ b/apps/backend/src/db/migrations/172_platform_fulfillment_snapshot_contract.sql @@ -0,0 +1,253 @@ +-- 172_platform_fulfillment_snapshot_contract.sql +-- +-- 直播账号履约事件升级为订单项快照契约: +-- 1. order_site 事务 Outbox 直接携带 live-hub 建单所需的事实,不再要求对方回查整表; +-- 2. 配置停用、订单关闭和履约归档也通过同一事件收敛; +-- 3. 入站状态增加版本号,防止 Webhook 重试导致旧状态覆盖新状态。 + +ALTER TABLE douyu_fulfillment_tasks + ADD COLUMN IF NOT EXISTS live_state_version BIGINT NOT NULL DEFAULT 0; + +COMMENT ON COLUMN douyu_fulfillment_tasks.live_state_version IS + 'live-hub 单调状态版本;order_site 只接受不小于当前版本的安全投影'; + +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_snapshot JSONB; + v_dedupe_key TEXT; +BEGIN + SELECT jsonb_build_object( + 'orderId', o.id, + 'orderItemId', oi.id, + 'fulfillmentId', f.id, + 'sourceOrderId', o.id::text, + 'sourceOrderItemId', oi.id::text, + 'sourceFulfillmentId', f.id::text, + 'platformOrderId', o.platform_order_id, + 'provider', o.provider, + 'platform', o.platform, + 'shopId', o.shop_id, + 'shopName', o.shop_name, + 'orderStatus', o.order_status, + 'payStatus', o.pay_status, + 'totalAmountFen', o.total_amount, + 'orderCreatedAt', to_char( + o.created_at AT TIME ZONE 'UTC', + 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"' + ), + 'paidAt', CASE + WHEN o.paid_at IS NULL THEN NULL + ELSE to_char(o.paid_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') + END, + 'skuCode', oi.sku_code, + 'skuName', oi.sku_name, + 'internalSkuKey', cfg.sku_key, + 'quantity', oi.quantity, + 'revenueAmountFen', oi.revenue_amount_fen, + 'itemUpdatedAt', to_char( + oi.updated_at AT TIME ZONE 'UTC', + 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"' + ), + 'fulfillmentStatus', f.status, + 'fulfillmentChannel', f.channel, + 'fulfillmentIssueCode', COALESCE(f.issue_code, ''), + 'fulfillmentUpdatedAt', to_char( + f.updated_at AT TIME ZONE 'UTC', + 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"' + ), + 'configEnabled', cfg.enabled, + 'douyuFulfillmentEnabled', cfg.douyu_fulfillment_enabled + ) + INTO v_snapshot + 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 o.id = p_order_id + AND oi.id = p_order_item_id + AND f.id = p_fulfillment_id + LIMIT 1; + + IF v_snapshot IS NULL THEN + RETURN; + END IF; + + v_dedupe_key := CONCAT( + 'platform-fulfillment-order:', + p_order_item_id, + ':', + md5(v_snapshot::text) + ); + + 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_snapshot', + v_dedupe_key, + jsonb_build_object( + 'eventId', v_event_id::text, + 'eventType', 'platform_fulfillment.order_snapshot', + 'contractVersion', 2, + 'occurredAt', to_char( + clock_timestamp() AT TIME ZONE 'UTC', + 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"' + ), + 'data', v_snapshot || jsonb_build_object( + 'reason', COALESCE(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 + WHERE oi.order_id = NEW.id + AND f.channel = 'manual' + AND f.status IN ('assigned', 'processing', 'completed', 'archived') + 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; +BEGIN + SELECT oi.order_id + INTO v_order_id + FROM order_items oi + WHERE oi.id = NEW.order_item_id; + + IF v_order_id IS NOT NULL + AND NEW.channel = 'manual' + AND NEW.status IN ('assigned', 'processing', 'completed', 'archived') THEN + PERFORM enqueue_live_hub_platform_fulfillment_event( + v_order_id, + NEW.order_item_id, + NEW.id, + CONCAT('fulfillment:', NEW.status, ':', COALESCE(NEW.issue_code, '')) + ); + END IF; + RETURN NEW; +END; +$$; + +CREATE OR REPLACE FUNCTION enqueue_platform_fulfillment_from_config() +RETURNS TRIGGER +LANGUAGE plpgsql +AS $$ +DECLARE + v_row RECORD; +BEGIN + 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', 'archived') + LOOP + PERFORM enqueue_live_hub_platform_fulfillment_event( + v_row.order_id, + v_row.order_item_id, + v_row.fulfillment_id, + CONCAT( + 'config:', + CASE WHEN NEW.enabled THEN 'enabled' ELSE 'disabled' END, + ':', + CASE + WHEN NEW.douyu_fulfillment_enabled THEN 'douyu_enabled' + ELSE 'douyu_disabled' + END + ) + ); + END LOOP; + 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, issue_code 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 enabled, douyu_fulfillment_enabled ON manual_fulfillment_configs +FOR EACH ROW +WHEN ( + OLD.enabled IS DISTINCT FROM NEW.enabled + OR OLD.douyu_fulfillment_enabled IS DISTINCT FROM NEW.douyu_fulfillment_enabled +) +EXECUTE FUNCTION enqueue_platform_fulfillment_from_config(); + +-- 将当前有效任务补成新快照契约。旧版 Outbox 事件仍由 live-hub 的定向兼容路径处理。 +DO $$ +DECLARE + candidate RECORD; +BEGIN + FOR candidate IN + SELECT o.id AS order_id, oi.id AS order_item_id, f.id AS fulfillment_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.enabled = TRUE + AND cfg.douyu_fulfillment_enabled = TRUE + AND f.channel = 'manual' + AND f.status IN ('assigned', 'processing', 'completed') + AND o.pay_status = 'paid' + AND o.order_status NOT IN ('refunded', 'cancelled', 'closed') + AND oi.quantity = 1 + LOOP + PERFORM enqueue_live_hub_platform_fulfillment_event( + candidate.order_id, + candidate.order_item_id, + candidate.fulfillment_id, + 'migration_snapshot_v2' + ); + END LOOP; +END; +$$; diff --git a/apps/backend/src/routes/douyu-fulfillment.ts b/apps/backend/src/routes/douyu-fulfillment.ts index e877f623..ad14d767 100644 --- a/apps/backend/src/routes/douyu-fulfillment.ts +++ b/apps/backend/src/routes/douyu-fulfillment.ts @@ -7,10 +7,19 @@ import { saveDouyuCustomerProfile, startDouyuCustomerBinding, } from '../services/douyu-fulfillment/douyu-fulfillment-service.js' +import { openCustomerOrderRealtimeStream } from '../services/realtime/realtime-event-service.js' import { createRouteHandler } from '../utils/http.js' const router = Router() +router.get('/:orderNo/realtime', (req, res) => { + openCustomerOrderRealtimeStream( + res, + String(req.params.orderNo || ''), + Number(req.get('Last-Event-ID') || req.query.lastEventId || 0) || 0, + ) +}) + router.get( '/:orderNo', createRouteHandler((req) => getCustomerDouyuFulfillment(String(req.params.orderNo || '')), { diff --git a/apps/backend/src/services/douyu-fulfillment/douyu-fulfillment-service.ts b/apps/backend/src/services/douyu-fulfillment/douyu-fulfillment-service.ts index 393a685e..f8d0b96b 100644 --- a/apps/backend/src/services/douyu-fulfillment/douyu-fulfillment-service.ts +++ b/apps/backend/src/services/douyu-fulfillment/douyu-fulfillment-service.ts @@ -1,7 +1,10 @@ import type { PoolClient } from 'pg' import { query, withTransaction } from '../../db/client.js' -import { publishRealtimeEvent } from '../realtime/realtime-event-service.js' +import { + publishCustomerOrderRealtimeChange, + publishRealtimeEvent, +} from '../realtime/realtime-event-service.js' import { nowIso } from '../../utils/time.js' import { createHttpError } from '../../utils/http.js' import { logWarn } from '../../utils/logger.js' @@ -36,6 +39,7 @@ type DouyuTaskRow = { bound_at: string | null completed_at: string | null last_synced_at: string | null + live_state_version: number | string qr_url: string qr_generated_at: string | null qr_expires_at: string | null @@ -74,6 +78,7 @@ type LiveBindingState = { bindConfirmed: boolean customerProfileReset?: boolean resetReason?: string + stateVersion?: number | string completedAt: string | null updatedAt: string } @@ -272,6 +277,7 @@ export async function ensureDouyuFulfillmentTasks(orderNo = '') { if (candidates.rows.length === 0) return { created: 0, updated: 0 } let created = 0 + const createdOrderNos = new Set() await withTransaction(async (client) => { for (const row of candidates.rows) { const inserted = await client.query<{ id: number; inserted: boolean }>( @@ -298,12 +304,16 @@ export async function ensureDouyuFulfillmentTasks(orderNo = '') { if (!taskId) continue if (inserted.rows[0]?.inserted) { created += 1 + createdOrderNos.add(row.platform_order_id) await appendEvent(client, taskId, 'task_created', 'system', { platformOrderId: row.platform_order_id, }) } } }) + for (const platformOrderId of createdOrderNos) { + publishCustomerOrderRealtimeChange(platformOrderId, 'douyu_fulfillment_task_created') + } return { created, updated: candidates.rows.length - created } } @@ -424,6 +434,12 @@ export function statusForLive(live: LiveBindingState): string { return 'preparing' } +export function isStaleLiveStateVersion(current: unknown, incoming: unknown) { + const currentVersion = Math.max(0, Math.trunc(Number(current || 0))) + const incomingVersion = Math.max(0, Math.trunc(Number(incoming || 0))) + return incomingVersion > 0 && incomingVersion < currentVersion +} + async function updateTaskFromLiveState( client: Pick, task: DouyuTaskRow, @@ -432,6 +448,27 @@ async function updateTaskFromLiveState( ) { const resetCustomerProfile = live.customerProfileReset === true const nextStatus = statusForLive(live) + const incomingVersion = Math.max(0, Math.trunc(Number(live.stateVersion || 0))) + const currentVersion = Math.max(0, Math.trunc(Number(task.live_state_version || 0))) + if (isStaleLiveStateVersion(currentVersion, incomingVersion)) { + return false + } + const changed = + incomingVersion > currentVersion || + Number(task.live_session_id || 0) !== Number(live.sessionId || 0) || + task.status !== nextStatus || + task.binding_phase !== live.bindPhase || + task.live_execution_status !== live.executionStatus || + task.live_binding_status !== live.bindingStatus || + task.issue_code !== live.issueCode || + task.last_error !== live.message || + task.bound_role_name !== live.roleName || + task.bound_area_name !== live.areaName || + task.bound_plat_name !== live.platName || + task.qr_url !== live.qrUrl || + normalizeLiveTimestamp(task.qr_generated_at) !== normalizeLiveTimestamp(live.qrGeneratedAt) || + normalizeLiveTimestamp(task.qr_expires_at) !== normalizeLiveTimestamp(live.qrExpiresAt) || + resetCustomerProfile await client.query( ` UPDATE douyu_fulfillment_tasks @@ -466,6 +503,7 @@ async function updateTaskFromLiveState( qr_url = $15, qr_generated_at = NULLIF($16, '')::timestamptz, qr_expires_at = NULLIF($17, '')::timestamptz, + live_state_version = GREATEST(live_state_version, $20), last_synced_at = NOW(), updated_at = $18 WHERE id = $1 @@ -490,6 +528,7 @@ async function updateTaskFromLiveState( live.qrExpiresAt, now, resetCustomerProfile, + incomingVersion, ], ) if (nextStatus !== task.status) { @@ -504,24 +543,35 @@ async function updateTaskFromLiveState( reason: String(live.resetReason || ''), }) } + return changed } async function applyLiveState(task: DouyuTaskRow, live: LiveBindingState) { + let changed = false await withTransaction(async (client) => { - await updateTaskFromLiveState(client, task, live, nowIso()) + changed = await updateTaskFromLiveState(client, task, live, nowIso()) }) const updated = await loadTask(task.id) + if (changed) { + publishCustomerOrderRealtimeChange(updated.platform_order_id, 'douyu_binding_state_changed') + } return { task: updated, live, comparison: compareCustomerRole(updated, live) } } async function applyLiveStates(entries: Array<{ task: DouyuTaskRow; live: LiveBindingState }>) { if (entries.length === 0) return const now = nowIso() + const changedOrderNos = new Set() await withTransaction(async (client) => { for (const entry of entries) { - await updateTaskFromLiveState(client, entry.task, entry.live, now) + if (await updateTaskFromLiveState(client, entry.task, entry.live, now)) { + changedOrderNos.add(entry.task.platform_order_id) + } } }) + for (const platformOrderId of changedOrderNos) { + publishCustomerOrderRealtimeChange(platformOrderId, 'douyu_binding_state_changed') + } } function isLiveBindingState(value: unknown): value is LiveBindingState { @@ -563,10 +613,21 @@ function liveBindingStateFromTask(task: DouyuTaskRow): LiveBindingState { bindReadyForConfirm: task.status === 'role_ready', bindConfirmed: ['bound', 'waiting_operator', 'processing', 'completed'].includes(task.status), completedAt: task.completed_at, + stateVersion: Number(task.live_state_version || 0), updatedAt: task.updated_at, } } +function localCustomerFulfillment(task: DouyuTaskRow) { + const live = liveBindingStateFromTask(task) + return { + task, + live, + comparison: compareCustomerRole(task, live), + linkPath: `/coll/d/${encodeURIComponent(task.platform_order_id)}`, + } +} + export async function applyLiveBindingStateSnapshot( input: unknown, options: { eventId?: string; eventType?: string } = {}, @@ -612,7 +673,11 @@ export async function applyLiveBindingStateSnapshot( [eventId, String(options.eventType || '')], ) if (claimed.rowCount === 0) { - return { received: rawItems.length, updated: 0 } + return { + received: rawItems.length, + updated: 0, + changedOrderNos: new Set(), + } } } @@ -636,13 +701,21 @@ export async function applyLiveBindingStateSnapshot( taskByOrderItemId.get(String(live.sourceOrderItemId || '')) return task ? [{ task, live }] : [] }) + let changedCount = 0 + const changedOrderNos = new Set() for (const entry of entries) { - await updateTaskFromLiveState(client, entry.task, entry.live, now) + if (await updateTaskFromLiveState(client, entry.task, entry.live, now)) { + changedCount += 1 + changedOrderNos.add(entry.task.platform_order_id) + } } - return { received: rawItems.length, updated: entries.length } + return { received: rawItems.length, updated: changedCount, changedOrderNos } }) if (result.updated > 0) { + for (const platformOrderId of result.changedOrderNos) { + publishCustomerOrderRealtimeChange(platformOrderId, 'douyu_binding_state_changed') + } publishRealtimeEvent({ type: 'order.changed', entityId: 0, @@ -652,7 +725,14 @@ export async function applyLiveBindingStateSnapshot( admin: true, }) } - return result + return { received: result.received, updated: result.updated } +} + +function normalizeLiveTimestamp(value: unknown) { + const text = String(value || '').trim() + if (!text) return '' + const parsed = Date.parse(text) + return Number.isFinite(parsed) ? new Date(parsed).toISOString() : text } async function ensureLiveSession(task: DouyuTaskRow) { @@ -682,13 +762,7 @@ export async function getCustomerDouyuFulfillment(orderNo: string) { await appendEvent(client, task.id, 'customer_link_opened', 'customer') }) } - const session = await ensureLiveSession(task) - return { - task: session.task, - live: session.live, - comparison: session.comparison, - linkPath: `/coll/d/${encodeURIComponent(task.platform_order_id)}`, - } + return localCustomerFulfillment(task) } export async function saveDouyuCustomerProfile( @@ -766,18 +840,7 @@ export async function refreshDouyuCustomerBinding(orderNo: string) { } export async function getDouyuCustomerFulfillmentCached(orderNo: string) { - let task = await loadTaskByOrderNo(orderNo) - if (!task.live_session_id) { - return ensureLiveSession(task) - } - task = await loadTask(task.id) - const live = liveBindingStateFromTask(task) - return { - task, - live, - comparison: compareCustomerRole(task, live), - linkPath: `/coll/d/${encodeURIComponent(task.platform_order_id)}`, - } + return localCustomerFulfillment(await loadTaskByOrderNo(orderNo)) } export async function confirmDouyuCustomerBinding(orderNo: string) { @@ -918,7 +981,7 @@ export async function listDouyuFulfillmentTasks( export async function getDouyuFulfillmentDetail(orderNo: string) { const task = await loadTaskByOrderNo(orderNo) const [session, events] = await Promise.all([ - ensureLiveSession(task), + Promise.resolve(localCustomerFulfillment(task)), query<{ id: number event_type: string diff --git a/apps/backend/src/services/douyu-fulfillment/douyu-fulfillment.test.ts b/apps/backend/src/services/douyu-fulfillment/douyu-fulfillment.test.ts index 03f2eecd..0b460967 100644 --- a/apps/backend/src/services/douyu-fulfillment/douyu-fulfillment.test.ts +++ b/apps/backend/src/services/douyu-fulfillment/douyu-fulfillment.test.ts @@ -4,6 +4,7 @@ import test from 'node:test' import { applyLiveBindingStateSnapshot, compareCustomerRole, + isStaleLiveStateVersion, statusForLive, } from './douyu-fulfillment-service.js' @@ -81,6 +82,13 @@ test('已分配账号保持 allocated,不折叠成准备账号', () => { assert.equal(status, 'allocated') }) +test('直播账号状态版本只允许向前推进', () => { + assert.equal(isStaleLiveStateVersion(8, 7), true) + assert.equal(isStaleLiveStateVersion(8, 8), false) + assert.equal(isStaleLiveStateVersion(8, 9), false) + assert.equal(isStaleLiveStateVersion(8, 0), false) +}) + test('直播账号状态推送忽略空数据和无效任务', async () => { assert.deepEqual(await applyLiveBindingStateSnapshot({ items: [] }), { received: 0, diff --git a/apps/backend/src/services/fulfillment/channel-assign-service.ts b/apps/backend/src/services/fulfillment/channel-assign-service.ts index cd9171bf..3d2006c7 100644 --- a/apps/backend/src/services/fulfillment/channel-assign-service.ts +++ b/apps/backend/src/services/fulfillment/channel-assign-service.ts @@ -47,6 +47,10 @@ import { transitionFulfillmentStateBatchWithExecutor, transitionFulfillmentStateWithExecutor, } from './fulfillment-state-service.js' +import { + publishAdminOrderRealtimeChange, + publishCustomerOrderRealtimeChangeByOrderIds, +} from '../realtime/realtime-event-service.js' /** * 管道 A:渠道判定。 @@ -269,10 +273,17 @@ export async function assignPendingOrderItemChannels( ): Promise { const batchSize = Math.min(5000, Math.max(1, Math.trunc(options.batchSize || 500))) const maxBatches = Math.min(200, Math.max(1, Math.trunc(options.maxBatches || 20))) + const requestedIds = [ + ...new Set( + (options.orderItemIds || []).map(Number).filter((id) => Number.isInteger(id) && id > 0), + ), + ] let cursor = - options.afterId != null - ? Math.max(0, Math.trunc(options.afterId)) - : await readWatermarkItemId('channel_assign') + requestedIds.length > 0 + ? 0 + : options.afterId != null + ? Math.max(0, Math.trunc(options.afterId)) + : await readWatermarkItemId('channel_assign') let reachedEnd = false const result: AssignChannelsResult = { @@ -288,11 +299,6 @@ export async function assignPendingOrderItemChannels( pendingReasons: {}, } const affectedDates = new Set() - const requestedIds = [ - ...new Set( - (options.orderItemIds || []).map(Number).filter((id) => Number.isInteger(id) && id > 0), - ), - ] const params: unknown[] = [cursor, batchSize] let requestedFilter = '' if (requestedIds.length > 0) { @@ -444,6 +450,9 @@ export async function assignPendingOrderItemChannels( 0, 2000, ) + const affectedOrderIds = [ + ...new Set(updated.map((row) => Number(row.order_id)).filter((id) => id > 0)), + ] await ensureSemiAutoTasksForOrderItems(assignedItemIds).catch((error) => { logWarn('[channel-assign]', '半自动任务主动物化失败,等待后台回填', { orderItemIds: assignedItemIds, @@ -458,6 +467,10 @@ export async function assignPendingOrderItemChannels( }) }, ) + for (const orderId of affectedOrderIds) { + publishAdminOrderRealtimeChange(orderId) + } + publishCustomerOrderRealtimeChangeByOrderIds(affectedOrderIds, 'fulfillment_channel_updated') } if (unmatchedVoucherItemIds.length > 0) { @@ -478,6 +491,45 @@ export async function assignPendingOrderItemChannels( return result } +/** + * 新单事件驱动的履约推进:只处理当前订单项,避免等待全局游标和每分钟兜底任务。 + */ +export async function advanceFulfillmentForOrderItems(orderItemIdsInput: number[]) { + const orderItemIds = [ + ...new Set( + (orderItemIdsInput || []).map(Number).filter((id) => Number.isInteger(id) && id > 0), + ), + ] + if (orderItemIds.length === 0) { + return { + assigned: 0, + carrierAttempts: 0, + reassigned: 0, + } + } + + const initial = await assignPendingOrderItemChannels({ + orderItemIds, + batchSize: Math.min(500, orderItemIds.length), + maxBatches: 1, + }) + const carriers = await reconcilePendingCarriers({ + orderItemIds, + limit: Math.min(500, orderItemIds.length), + }) + const final = await assignPendingOrderItemChannels({ + orderItemIds, + batchSize: Math.min(500, orderItemIds.length), + maxBatches: 1, + }) + return { + assigned: initial.assigned + final.assigned, + carrierAttempts: + carriers.workOrdersCreated + carriers.affiliateTasksCreated + carriers.fallbacksSelected, + reassigned: final.assigned, + } +} + export async function assignOrderItemsAfterCarrierReady(input: { orderItemIds: number[] channel: FulfillmentChannel diff --git a/apps/backend/src/services/fulfillment/fulfillment-event-driven-pipeline.test.ts b/apps/backend/src/services/fulfillment/fulfillment-event-driven-pipeline.test.ts new file mode 100644 index 00000000..30359a8c --- /dev/null +++ b/apps/backend/src/services/fulfillment/fulfillment-event-driven-pipeline.test.ts @@ -0,0 +1,68 @@ +import assert from 'node:assert/strict' +import { readFileSync } from 'node:fs' +import test from 'node:test' + +function source(relativePath: string) { + return readFileSync(new URL(relativePath, import.meta.url), 'utf8') +} + +test('新订单定向推进不受全局渠道判定游标影响', () => { + const channelAssign = source('./channel-assign-service.ts') + assert.ok(channelAssign.includes('requestedIds.length > 0')) + assert.ok(channelAssign.includes('advanceFulfillmentForOrderItems')) + assert.ok(channelAssign.includes('orderItemIds')) + assert.ok(channelAssign.includes('reconcilePendingCarriers')) +}) + +test('发单消费者完成当前订单后立即推进履约和自动发布,定时任务只兜底', () => { + const workerSync = source('../worker-platform/sync-worker-orders-service.ts') + assert.ok(workerSync.includes('advanceFulfillmentForOrderItems(orderItems.map')) + assert.ok(workerSync.includes('enqueueOrderServiceAutoPublish')) + assert.ok(workerSync.includes('processDueOrderServiceAutoPublishJobs')) + assert.ok(workerSync.includes('等待定时任务兜底')) +}) + +test('渠道和载体状态变化主动推送后台列表', () => { + const channelAssign = source('./channel-assign-service.ts') + const financeJobs = source('../scheduler/finance-pipeline-jobs.ts') + assert.ok(channelAssign.includes('publishAdminOrderRealtimeChange')) + assert.ok(channelAssign.includes('publishCustomerOrderRealtimeChangeByOrderIds')) + assert.ok(financeJobs.includes('manual_fulfillment_ready')) +}) + +test('管道状态和斗鱼客户页由 SSE 驱动,live-hub 同步完成后主动唤醒', () => { + const scheduler = source('../scheduler/scheduler-service.ts') + const outbox = source('../integration/outbox-worker.ts') + const douyuRoute = source('../../routes/douyu-fulfillment.ts') + assert.ok(scheduler.includes("type: 'fulfillment_pipeline.changed'")) + assert.ok(outbox.includes('live_hub_order_synced')) + assert.ok(douyuRoute.includes('openCustomerOrderRealtimeStream')) +}) + +test('斗鱼客户读取不再阻塞调用 live-hub,状态由 Webhook 收敛', () => { + const douyuService = source('../douyu-fulfillment/douyu-fulfillment-service.ts') + const customerRead = douyuService.slice( + douyuService.indexOf('export async function getCustomerDouyuFulfillment'), + douyuService.indexOf('export async function saveDouyuCustomerProfile'), + ) + const cachedRead = douyuService.slice( + douyuService.indexOf('export async function getDouyuCustomerFulfillmentCached'), + douyuService.indexOf('export async function confirmDouyuCustomerBinding'), + ) + + assert.ok(customerRead.includes('return localCustomerFulfillment(task)')) + assert.ok(cachedRead.includes('return localCustomerFulfillment')) + assert.ok(!customerRead.includes('ensureLiveSession')) + assert.ok(!cachedRead.includes('ensureLiveSession')) +}) + +test('新单快速推进只处理 actionable 履约桶', () => { + const channelAssign = source('./channel-assign-service.ts') + const advance = channelAssign.slice( + channelAssign.indexOf('export async function advanceFulfillmentForOrderItems'), + channelAssign.indexOf('export async function assignOrderItemsAfterCarrierReady'), + ) + + assert.ok(advance.includes('reconcilePendingCarriers')) + assert.ok(!advance.includes('includeNonActionable')) +}) diff --git a/apps/backend/src/services/fulfillment/fulfillment-routing.integration.test.ts b/apps/backend/src/services/fulfillment/fulfillment-routing.integration.test.ts index 902d66c5..3d72ceb1 100644 --- a/apps/backend/src/services/fulfillment/fulfillment-routing.integration.test.ts +++ b/apps/backend/src/services/fulfillment/fulfillment-routing.integration.test.ts @@ -50,6 +50,7 @@ test( const { updateOrderItemSourceSnapshot } = await import('../../repositories/order-item-repo.js') const { listTasks } = await import('../../repositories/task-repo.js') const { listVoucherConsumeJobs } = await import('./voucher-consume-queue-service.js') + const { readWatermarkItemId, touchWatermark } = await import('../watermark-store.js') const suffix = `${Date.now()}_${Math.floor(Math.random() * 1_000_000)}` const shopId = `it-routing-${suffix}` const manualSku = `集成测试人工-${suffix}` @@ -65,6 +66,7 @@ test( const reactivatedVoucherSku = `集成测试归档卡券-${suffix}` const retryPendingAffiliateSku = `集成测试失败待重试-${suffix}` const cutoffTestSku = `集成测试自动化边界-${suffix}` + const cursorAdvanceSku = `集成测试定向游标-${suffix}` const retryWorkOrderRuleKey = `it-retry-${suffix}` const orderIds: number[] = [] const orderItemIds: number[] = [] @@ -228,6 +230,24 @@ test( assert.equal(cutoffStates.rows[0]?.fulfillment_status, 'pending') assert.equal(cutoffStates.rows[1]?.fulfillment_status, 'assigned') + const cursorAdvanceItemId = await createPendingOrderItem(cursorAdvanceSku) + await setRoute({ sku: cursorAdvanceSku, channel: 'third_party_voucher' }) + const originalChannelCursor = await readWatermarkItemId('channel_assign') + await touchWatermark('channel_assign', { + lastItemId: cursorAdvanceItemId + 1_000_000, + }) + try { + const targetedAdvance = await assignPendingOrderItemChannels({ + orderItemIds: [cursorAdvanceItemId], + batchSize: 10, + maxBatches: 1, + }) + assert.equal(targetedAdvance.scanned, 1) + assert.equal(targetedAdvance.assigned, 1) + } finally { + await touchWatermark('channel_assign', { lastItemId: originalChannelCursor }) + } + await setRoute({ sku: ` 集成测试 规范-${suffix} `, channel: 'manual', diff --git a/apps/backend/src/services/integration/outbox-migration.test.ts b/apps/backend/src/services/integration/outbox-migration.test.ts index 4e3da31c..b32ab897 100644 --- a/apps/backend/src/services/integration/outbox-migration.test.ts +++ b/apps/backend/src/services/integration/outbox-migration.test.ts @@ -13,3 +13,20 @@ test('Outbox migration keeps header event id and payload eventId identical', () assert.match(sql, /CREATE TABLE IF NOT EXISTS integration_outbox/) assert.match(sql, /CREATE TABLE IF NOT EXISTS integration_inbox/) }) + +test('订单项快照事件携带定向履约事实和稳定去重键', () => { + const sql = readFileSync( + new URL('../../db/migrations/172_platform_fulfillment_snapshot_contract.sql', import.meta.url), + 'utf8', + ) + + assert.match(sql, /'sourceOrderItemId', oi\.id::text/) + assert.match(sql, /'internalSkuKey', cfg\.sku_key/) + assert.match(sql, /'orderCreatedAt'/) + assert.match(sql, /'paidAt'/) + assert.match(sql, /'fulfillmentStatus', f\.status/) + assert.match(sql, /md5\(v_snapshot::text/) + assert.match(sql, /platform_fulfillment\.order_snapshot/) + assert.match(sql, /live_state_version/) + assert.doesNotMatch(sql, /LIMIT 500/) +}) diff --git a/apps/backend/src/services/integration/outbox-worker.ts b/apps/backend/src/services/integration/outbox-worker.ts index 75230001..d807afae 100644 --- a/apps/backend/src/services/integration/outbox-worker.ts +++ b/apps/backend/src/services/integration/outbox-worker.ts @@ -1,6 +1,7 @@ import { query, withTransaction } from '../../db/client.js' import { logError, logInfo, logWarn } from '../../utils/logger.js' import { buildWebhookSignature } from './webhook-signature.js' +import { publishCustomerOrderRealtimeChange } from '../realtime/realtime-event-service.js' const DEFAULT_INTERVAL_MS = 1000 const DEFAULT_BATCH_SIZE = 20 @@ -161,12 +162,33 @@ async function publishDueEvents() { try { await deliverEvent(row) await markSent(row.event_id) + publishCustomerOrderRealtimeChange( + platformOrderIdFromOutboxPayload(row.payload_json), + 'live_hub_order_synced', + ) } catch (error) { await markFailed(row, error) } } } +function platformOrderIdFromOutboxPayload(payload: unknown) { + const value = + typeof payload === 'string' + ? (() => { + try { + return JSON.parse(payload) + } catch { + return null + } + })() + : payload + if (!value || typeof value !== 'object' || Array.isArray(value)) return '' + const data = (value as { data?: unknown }).data + if (!data || typeof data !== 'object' || Array.isArray(data)) return '' + return String((data as { platformOrderId?: unknown }).platformOrderId || '').trim() +} + async function runLoop() { if (stopped || running) return running = true diff --git a/apps/backend/src/services/integration/platform-fulfillment-outbox.integration.test.ts b/apps/backend/src/services/integration/platform-fulfillment-outbox.integration.test.ts new file mode 100644 index 00000000..5b536459 --- /dev/null +++ b/apps/backend/src/services/integration/platform-fulfillment-outbox.integration.test.ts @@ -0,0 +1,111 @@ +/** + * 直播账号履约订单快照 Outbox 集成测试(需要已完成迁移的真实 PostgreSQL)。 + * + * 运行: + * FULFILLMENT_OUTBOX_TEST_DATABASE_URL="$DATABASE_URL" \ + * npx tsx --test src/services/integration/platform-fulfillment-outbox.integration.test.ts + */ +import assert from 'node:assert/strict' +import test from 'node:test' + +const TEST_DATABASE_URL = String(process.env.FULFILLMENT_OUTBOX_TEST_DATABASE_URL || '').trim() + +test( + '履约事务 Outbox 发送定向订单项快照且同一状态只产生一个事件', + { skip: !TEST_DATABASE_URL ? '未设置 FULFILLMENT_OUTBOX_TEST_DATABASE_URL' : false }, + async () => { + process.env.DATABASE_URL = TEST_DATABASE_URL + const { closeDb, query } = await import('../../db/client.js') + const suffix = `${Date.now()}_${Math.floor(Math.random() * 1_000_000)}` + const platformOrderId = `IT-PF-OUTBOX-${suffix}` + const internalSku = `集成履约快照-${suffix}` + let configId = 0 + let orderId = 0 + + try { + const config = await query<{ id: number }>( + `INSERT INTO manual_fulfillment_configs ( + sku_key, platform_key, credit_quantity, cost_mode, enabled, + douyu_fulfillment_enabled, created_at, updated_at + ) VALUES ($1, 'nanhang', 1, 'fixed', TRUE, TRUE, NOW(), NOW()) + RETURNING id`, + [internalSku], + ) + configId = Number(config.rows[0]!.id) + + const order = await query<{ id: number }>( + `INSERT INTO orders ( + provider, platform, shop_id, shop_name, platform_order_id, + order_status, pay_status, total_amount, paid_at, created_at, updated_at + ) VALUES ( + 'integration-test', 'integration-test', $1, '集成测试店', $2, + 'paid', 'paid', 9900, NOW(), NOW(), NOW() + ) RETURNING id`, + [`shop-${suffix}`, platformOrderId], + ) + orderId = Number(order.rows[0]!.id) + + const item = await query<{ id: number }>( + `INSERT INTO order_items ( + order_id, sku_code, sku_name, quantity, spec_json, + revenue_amount_fen, revenue_basis, created_at, updated_at + ) VALUES ( + $1, $2, $2, 1, $3::jsonb, 9900, 'order_total', NOW(), NOW() + ) RETURNING id`, + [orderId, `sku-${suffix}`, JSON.stringify({ skuNick: internalSku })], + ) + + const fulfillment = await query( + `UPDATE fulfillments + SET internal_sku = $2, + route_status = 'configured', + channel = 'manual', + carrier_status = 'ready', + status = 'assigned', + source = 'integration_test', + fulfillment_config_id = $3, + updated_at = NOW() + WHERE order_item_id = $1`, + [Number(item.rows[0]!.id), internalSku, configId], + ) + assert.equal(fulfillment.rowCount, 1) + + const events = await query<{ + contract_version: string + source_order_item_id: string + internal_sku_key: string + fulfillment_status: string + }>( + `SELECT + payload_json->>'contractVersion' AS contract_version, + payload_json->'data'->>'sourceOrderItemId' AS source_order_item_id, + payload_json->'data'->>'internalSkuKey' AS internal_sku_key, + payload_json->'data'->>'fulfillmentStatus' AS fulfillment_status + FROM integration_outbox + WHERE payload_json->'data'->>'platformOrderId' = $1`, + [platformOrderId], + ) + + assert.equal(events.rows.length, 1) + assert.equal(events.rows[0]!.contract_version, '2') + assert.equal(events.rows[0]!.source_order_item_id, String(item.rows[0]!.id)) + assert.equal(events.rows[0]!.internal_sku_key, internalSku) + assert.equal(events.rows[0]!.fulfillment_status, 'assigned') + } finally { + await query( + `DELETE FROM integration_outbox + WHERE payload_json->'data'->>'platformOrderId' = $1`, + [platformOrderId], + ).catch(() => undefined) + if (orderId > 0) { + await query('DELETE FROM orders WHERE id = $1', [orderId]).catch(() => undefined) + } + if (configId > 0) { + await query('DELETE FROM manual_fulfillment_configs WHERE id = $1', [configId]).catch( + () => undefined, + ) + } + await closeDb() + } + }, +) diff --git a/apps/backend/src/services/realtime/realtime-event-service.ts b/apps/backend/src/services/realtime/realtime-event-service.ts index 7cd22438..1b521cf7 100644 --- a/apps/backend/src/services/realtime/realtime-event-service.ts +++ b/apps/backend/src/services/realtime/realtime-event-service.ts @@ -1,5 +1,6 @@ import type { Response } from 'express' +import { query } from '../../db/client.js' import { WORK_ORDER_STATUS } from '../../domain/work-order-status.js' import { @@ -47,6 +48,8 @@ import { invalidateWorkerMyOrderCaches } from '../worker-platform/worker-my-orde export type RealtimeEventType = | 'admin_notification.changed' + | 'customer_order.changed' + | 'fulfillment_pipeline.changed' | 'order.changed' | 'work_order.changed' | 'worker_finance_request.changed' @@ -78,6 +81,7 @@ type RealtimeSubscriber = { id: number response: Response workerId: number | null + orderNo: string | null } type StoredRealtimeEvent = RealtimeEvent & { @@ -88,6 +92,7 @@ type StoredRealtimeEvent = RealtimeEvent & { const adminSubscribers = new Map() const workerSubscribers = new Map() +const orderSubscribers = new Map() let nextSubscriberId = 1 let heartbeatTimer: NodeJS.Timeout | null = null let publishQueue: Promise = Promise.resolve() @@ -120,6 +125,54 @@ export function openWorkerRealtimeStream(response: Response, workerId: number, l return openRealtimeStream(response, Number(workerId), lastEventId) } +/** 客户订单级实时信号只决定“需要重读”,不携带订单或平台敏感快照。 */ +export function openCustomerOrderRealtimeStream( + response: Response, + orderNo: string, + lastEventId = 0, +) { + return openRealtimeStream(response, null, lastEventId, String(orderNo || '').trim()) +} + +export function publishCustomerOrderRealtimeChange(orderNoInput: unknown, reason: string) { + const orderNo = String(orderNoInput || '').trim() + if (!orderNo) return + const event: RealtimeEvent = { + eventId: 0, + version: 0, + type: 'customer_order.changed', + entityId: 0, + scopes: [`customer_order:${orderNo}`], + operation: 'refresh', + data: { reason: String(reason || '').trim() }, + occurredAt: new Date().toISOString(), + } + broadcast( + Array.from(orderSubscribers.values()).filter((subscriber) => subscriber.orderNo === orderNo), + event, + ) +} + +export function publishCustomerOrderRealtimeChangeByOrderIds( + orderIdsInput: number[], + reason: string, +) { + const orderIds = [ + ...new Set((orderIdsInput || []).map(Number).filter((id) => Number.isInteger(id) && id > 0)), + ] + if (orderIds.length === 0) return + void query<{ platform_order_id: string }>( + `SELECT platform_order_id FROM orders WHERE id = ANY($1::bigint[])`, + [orderIds], + ) + .then((result) => { + for (const row of result.rows) { + publishCustomerOrderRealtimeChange(row.platform_order_id, reason) + } + }) + .catch(() => undefined) +} + /** 发布带版本号和数据快照的实时事件;数据库仍是最终权威数据源。 */ export function publishRealtimeEvent(input: RealtimeEventInput) { const workerIds = [ @@ -563,13 +616,20 @@ async function publishWorkerFinanceSnapshots(input: { } } -function openRealtimeStream(response: Response, workerId: number | null, lastEventId: number) { +function openRealtimeStream( + response: Response, + workerId: number | null, + lastEventId: number, + orderNo: string | null = null, +) { const subscriber: RealtimeSubscriber = { id: nextSubscriberId++, response, workerId, + orderNo, } - const subscribers = workerId === null ? adminSubscribers : workerSubscribers + const subscribers = + orderNo !== null ? orderSubscribers : workerId === null ? adminSubscribers : workerSubscribers response.status(200) response.setHeader('Content-Type', 'text/event-stream; charset=utf-8') @@ -650,6 +710,12 @@ function normalizeStringArray(value: unknown): string[] { } function isEventVisibleToSubscriber(event: StoredRealtimeEvent, subscriber: RealtimeSubscriber) { + if (subscriber.orderNo !== null) { + return ( + event.type === 'customer_order.changed' && + event.scopes.includes(`customer_order:${subscriber.orderNo}`) + ) + } if (subscriber.workerId === null) return event.adminAudience return event.broadcastWorkers || event.workerIds.includes(Number(subscriber.workerId)) } @@ -692,7 +758,12 @@ function writeEventFrame(subscriber: RealtimeSubscriber, frame: string) { } function removeSubscriber(subscriber: RealtimeSubscriber) { - const subscribers = subscriber.workerId === null ? adminSubscribers : workerSubscribers + const subscribers = + subscriber.orderNo !== null + ? orderSubscribers + : subscriber.workerId === null + ? adminSubscribers + : workerSubscribers subscribers.delete(subscriber.id) stopHeartbeatWhenIdle() } @@ -700,7 +771,11 @@ function removeSubscriber(subscriber: RealtimeSubscriber) { function ensureHeartbeat() { if (heartbeatTimer) return heartbeatTimer = setInterval(() => { - for (const subscriber of [...adminSubscribers.values(), ...workerSubscribers.values()]) { + for (const subscriber of [ + ...adminSubscribers.values(), + ...workerSubscribers.values(), + ...orderSubscribers.values(), + ]) { if (subscriber.response.writableEnded || subscriber.response.destroyed) { removeSubscriber(subscriber) continue @@ -716,7 +791,14 @@ function ensureHeartbeat() { } function stopHeartbeatWhenIdle() { - if (adminSubscribers.size > 0 || workerSubscribers.size > 0 || !heartbeatTimer) return + if ( + adminSubscribers.size > 0 || + workerSubscribers.size > 0 || + orderSubscribers.size > 0 || + !heartbeatTimer + ) { + return + } clearInterval(heartbeatTimer) heartbeatTimer = null } diff --git a/apps/backend/src/services/scheduler/finance-pipeline-jobs.ts b/apps/backend/src/services/scheduler/finance-pipeline-jobs.ts index c0cc3a6e..ea039495 100644 --- a/apps/backend/src/services/scheduler/finance-pipeline-jobs.ts +++ b/apps/backend/src/services/scheduler/finance-pipeline-jobs.ts @@ -34,6 +34,10 @@ import { type FinancePipelineName, } from './finance-pipeline-status.js' import { ensureSemiAutoTasksForOrderItems } from '../semi-auto/semi-auto-task-service.js' +import { + publishAdminOrderRealtimeChange, + publishCustomerOrderRealtimeChangeByOrderIds, +} from '../realtime/realtime-event-service.js' /** * 财务与履约管道作业。 @@ -146,9 +150,15 @@ export async function runCarrierDispatchJob(job: JsonObject = {}) { const manualParams: unknown[] = [limit, cursor, configKeys] const manualCutoff = fulfillmentCreatedAfterSql(manualParams, cutoffCreatedAt) - const manual = await query<{ id: number; sku_key: string; config_id: number }>( + const manual = await query<{ + id: number + order_id: number + sku_key: string + config_id: number + }>( ` SELECT oi.id, + oi.order_id, resolve_internal_sku(oi.manual_sku_key, oi.sku_name, oi.sku_code) AS sku_key, cfg.id AS config_id FROM v_order_item_current oi @@ -182,6 +192,11 @@ export async function runCarrierDispatchJob(job: JsonObject = {}) { attached = configured.length if (attached > 0) { await ensureSemiAutoTasksForOrderItems(manual.rows.map((row) => Number(row.id))) + const orderIds = manual.rows.map((row) => Number(row.order_id)) + for (const orderId of new Set(orderIds)) { + publishAdminOrderRealtimeChange(orderId) + } + publishCustomerOrderRealtimeChangeByOrderIds(orderIds, 'manual_fulfillment_ready') } } diff --git a/apps/backend/src/services/scheduler/scheduler-service.ts b/apps/backend/src/services/scheduler/scheduler-service.ts index 2190a16c..441d739c 100644 --- a/apps/backend/src/services/scheduler/scheduler-service.ts +++ b/apps/backend/src/services/scheduler/scheduler-service.ts @@ -16,6 +16,7 @@ import { runSalesFactsJob, } from './finance-pipeline-jobs.js' import { runVoucherConsumeDispatchJob } from '../fulfillment/voucher-consume-queue-service.js' +import { publishRealtimeEvent } from '../realtime/realtime-event-service.js' const timers = new Map() const jobStates = new Map() @@ -91,6 +92,7 @@ function rescheduleJob(job: JsonObject) { if (!latestJob || latestJob.enabled !== true) return const intervalMs = Math.max(1, Number(latestJob.intervalSeconds || 20)) * 1000 scheduleJob(latestJob, intervalMs) + publishPipelineRealtimeChange(latestJob.id, 'scheduled') } function scheduleJob(job: JsonObject, delayMs: number) { @@ -138,6 +140,7 @@ async function runJob(job: JsonObject, { manual = false }: { manual?: boolean } lastStatus: 'running', lastMessage: '执行中', }) + publishPipelineRealtimeChange(jobId, 'started') try { const result = await dispatchJob(job) @@ -157,6 +160,7 @@ async function runJob(job: JsonObject, { manual = false }: { manual?: boolean } lastFailedCount: Number(summary.failedCount || 0), lastManual: manual, }) + publishPipelineRealtimeChange(jobId, 'finished') const status = String(summary.status || 'ok') const failedCount = Number(summary.failedCount || 0) // 成功且无失败的周期空跑降到 debug(PDD 约 20s 一轮),手动触发与失败仍保留 info。 @@ -185,6 +189,7 @@ async function runJob(job: JsonObject, { manual = false }: { manual?: boolean } lastMessage: message, lastManual: manual, }) + publishPipelineRealtimeChange(jobId, 'failed') logError('[scheduler]', '定时任务执行失败', { jobId, type: job.type, @@ -198,6 +203,20 @@ async function runJob(job: JsonObject, { manual = false }: { manual?: boolean } } } +function publishPipelineRealtimeChange(jobId: unknown, phase: string) { + publishRealtimeEvent({ + type: 'fulfillment_pipeline.changed', + entityId: 0, + scopes: ['admin_fulfillment_pipelines'], + operation: 'refresh', + data: { + jobId: String(jobId || '').trim(), + phase: String(phase || '').trim(), + }, + admin: true, + }) +} + function dispatchJob(job: JsonObject) { if (job.type === 'work_order_timeout') { return runWorkOrderTimeoutJob(job) diff --git a/apps/backend/src/services/worker-platform/sync-worker-orders-service.ts b/apps/backend/src/services/worker-platform/sync-worker-orders-service.ts index 42eb04aa..873e7027 100644 --- a/apps/backend/src/services/worker-platform/sync-worker-orders-service.ts +++ b/apps/backend/src/services/worker-platform/sync-worker-orders-service.ts @@ -44,7 +44,7 @@ import { resolveWorkOrderSharingEnabled, } from './mappers.js' import { registerWorkOrderShopName } from './work-order-shop-options-cache.js' -import { assignPendingOrderItemChannels } from '../fulfillment/channel-assign-service.js' +import { advanceFulfillmentForOrderItems } from '../fulfillment/channel-assign-service.js' import { attachFulfillmentConfigurations } from '../fulfillment/fulfillment-state-service.js' import { loadInternalSkuChannelPlans, @@ -61,6 +61,10 @@ import { getPublishedOrderServiceProfileSnapshotByCategory, isOrderServiceMaterialRequired, } from './order-service-profile-service.js' +import { + enqueueOrderServiceAutoPublish, + processDueOrderServiceAutoPublishJobs, +} from './order-service-auto-publish-service.js' export function shouldBootstrapWorkOrderChannel( plan: InternalSkuChannelPlan | undefined, @@ -143,6 +147,7 @@ export async function syncWorkerOrdersForSourceOrder( const skipped: Array<{ orderItemId: number; reason: string }> = [] const decisions: Array> = [] const internalSkuByItemId = new Map() + let autoPublishQueued = false for (const item of orderItems) { internalSkuByItemId.set( Number(item.id), @@ -526,15 +531,33 @@ export async function syncWorkerOrdersForSourceOrder( workOrderNo: workOrder.work_order_no, productName: workOrder.product_name, }) + } else if (materialComplete && serviceProfile?.config.autoPublish.enabled) { + const job = await enqueueOrderServiceAutoPublish({ + workOrderId: Number(workOrder.id), + maxAttempts: serviceProfile.config.autoPublish.retryMax + 1, + }) + autoPublishQueued = Boolean(job) + if (job) { + await createWorkOrderEvent({ + workOrderId: Number(workOrder.id), + actorType: 'system', + actorId: 'source_order_auto_publish', + eventType: 'auto_publish_queued', + fromStatus: workOrder.status, + toStatus: workOrder.status, + payloadJson: JSON.stringify({ jobId: Number(job) }), + now: nowIso(), + }) + } } } - // 订单处理完成后立即跑一次渠道判定;失败不阻断下单,由定时任务兜底。 + // 订单处理完成后只推进当前订单项;定时任务仅作为漏事件兜底。 if (!options.skipChannelAssign) { try { - await assignPendingOrderItemChannels({ batchSize: 200, maxBatches: 1 }) + await advanceFulfillmentForOrderItems(orderItems.map((item) => Number(item.id))) } catch (error) { - logWarn('[worker-order-consumer]', '履约方式归集失败,等待定时任务兜底', { + logWarn('[worker-order-consumer]', '当前订单履约推进失败,等待定时任务兜底', { orderId: order.id, platformOrderId: order.platform_order_id, orderItemCount: orderItems.length, @@ -542,6 +565,15 @@ export async function syncWorkerOrdersForSourceOrder( }) } } + if (autoPublishQueued) { + await processDueOrderServiceAutoPublishJobs(Math.max(1, created.length)).catch((error) => { + logWarn('[worker-order-consumer]', '订单服务即时自动发布失败,等待定时任务兜底', { + orderId: order.id, + platformOrderId: order.platform_order_id, + error: error instanceof Error ? error.message : String(error), + }) + }) + } const summary = { source: options.source || 'source_order', diff --git a/apps/frontend/src/components/WorkOrderEventTimeline.tsx b/apps/frontend/src/components/WorkOrderEventTimeline.tsx index 5ffb46e6..464abdaa 100644 --- a/apps/frontend/src/components/WorkOrderEventTimeline.tsx +++ b/apps/frontend/src/components/WorkOrderEventTimeline.tsx @@ -458,6 +458,8 @@ export function formatWorkOrderEvent(event: WorkOrderEvent): EventNodeStyle { } // —— 其他 —— + case 'auto_publish_queued': + return { title: '订单自动发布已入队', color: 'blue' } case 'auto_publish_succeeded': return { title: '订单自动发布成功', color: 'geekblue' } case 'admin_note_updated': diff --git a/apps/frontend/src/hooks/useRealtimeEvents.ts b/apps/frontend/src/hooks/useRealtimeEvents.ts index ea3c88cc..2d8a48a8 100644 --- a/apps/frontend/src/hooks/useRealtimeEvents.ts +++ b/apps/frontend/src/hooks/useRealtimeEvents.ts @@ -5,6 +5,8 @@ export type RealtimeEvent = { version: number type: | 'admin_notification.changed' + | 'customer_order.changed' + | 'fulfillment_pipeline.changed' | 'order.changed' | 'work_order.changed' | 'worker_finance_request.changed' @@ -18,7 +20,8 @@ export type RealtimeEvent = { type UseRealtimeEventsOptions = { url: string - token: string + token?: string + allowAnonymous?: boolean onEvent: (event: RealtimeEvent) => void onConnected?: () => void /** @@ -38,6 +41,7 @@ const RECONNECT_DELAY_MS = 3_000 export function useRealtimeEvents({ url, token, + allowAnonymous, onEvent, onConnected, onResync, @@ -53,7 +57,7 @@ export function useRealtimeEvents({ onAuthExpiredRef.current = onAuthExpired useEffect(() => { - if (!token) return + if (!token && !allowAnonymous) return let stopped = false let abortController: AbortController | null = null @@ -67,8 +71,8 @@ export function useRealtimeEvents({ const headers: Record = { Accept: 'text/event-stream', - Authorization: `Bearer ${token}`, } + if (token) headers.Authorization = `Bearer ${token}` if (lastEventId > 0) headers['Last-Event-ID'] = String(lastEventId) let authExpired = false void fetch(url, { @@ -101,8 +105,8 @@ export function useRealtimeEvents({ if (eventName !== 'realtime') return const event = normalizeRealtimeEvent(data) if (event) { - if (event.eventId <= lastEventId) return - lastEventId = Math.max(lastEventId, event.eventId) + if (event.eventId > 0 && event.eventId <= lastEventId) return + if (event.eventId > 0) lastEventId = Math.max(lastEventId, event.eventId) onEventRef.current(event) } }) @@ -131,7 +135,7 @@ export function useRealtimeEvents({ abortController?.abort() window.clearTimeout(reconnectTimer) } - }, [token, url]) + }, [allowAnonymous, token, url]) } async function readSseStream( @@ -189,6 +193,8 @@ function normalizeRealtimeEvent(value: string): RealtimeEvent | null { if ( ![ 'admin_notification.changed', + 'customer_order.changed', + 'fulfillment_pipeline.changed', 'order.changed', 'work_order.changed', 'worker_finance_request.changed', diff --git a/apps/frontend/src/layouts/AdminLayout.tsx b/apps/frontend/src/layouts/AdminLayout.tsx index 2ecda973..6fdb164e 100644 --- a/apps/frontend/src/layouts/AdminLayout.tsx +++ b/apps/frontend/src/layouts/AdminLayout.tsx @@ -559,6 +559,14 @@ function applyAdminRealtimeEvent( }) } + if ( + event.type === 'fulfillment_pipeline.changed' && + event.scopes.includes('admin_fulfillment_pipelines') + ) { + void queryClient.invalidateQueries({ queryKey: ['fulfillment-pipelines'] }) + void queryClient.invalidateQueries({ queryKey: ['fulfillment-pending'] }) + } + if (event.type === 'work_order.changed' && event.scopes.includes('admin_work_orders')) { // 拼单明细是独立查询,工单列表快照更新时也要同步刷新当前打开的明细。 void queryClient.invalidateQueries({ diff --git a/apps/frontend/src/pages/admin/AdminFulfillmentChannelPage.tsx b/apps/frontend/src/pages/admin/AdminFulfillmentChannelPage.tsx index ed6625bf..27e5c15c 100644 --- a/apps/frontend/src/pages/admin/AdminFulfillmentChannelPage.tsx +++ b/apps/frontend/src/pages/admin/AdminFulfillmentChannelPage.tsx @@ -1322,7 +1322,6 @@ function PipelinesPanel() { const query = useQuery({ queryKey: ['fulfillment-pipelines'], queryFn: fetchPipelineStatus, - refetchInterval: 30_000, }) const runMutation = useMutation({ @@ -1338,7 +1337,7 @@ function PipelinesPanel() { const columns = [ { title: '管道', dataIndex: 'label', width: 130 }, { - title: '定时任务', + title: '兜底任务', width: 150, render: (_: unknown, row: FinancePipelineStatus) => row.scheduler ? ( @@ -1402,8 +1401,8 @@ function PipelinesPanel() { } > - 六个管道由定时任务自动执行,无需人工干预;这里只用于查看进度、 - 排障和补跑。默认间隔:渠道判定/载体 60s,商品/成本 300s,事实/总账 600s。 + 新订单会由入库事件即时推进渠道判定和载体补建;定时任务只做漏事件兜底。 本页随后台 SSE + 自动刷新,用于查看进度、排障和补跑。 { + void load(true) + }, + onResync: () => { + void load(true) + }, + onEvent: (event) => { + if ( + event.type === 'customer_order.changed' && + event.scopes.includes(`customer_order:${orderNo}`) + ) { + void load(true) + } + }, + }) + const task = data?.task const live = data?.live const needsProfile = Boolean(task && !task.customer_role_name) const bindingFailed = Boolean(live && BINDING_FAILURE_ISSUES.has(live.issueCode)) - const activeBinding = Boolean( - task && - !needsProfile && - !bindingFailed && - !['completed', 'cancelled'].includes(task.status) && - !live?.bindConfirmed, - ) - - useEffect(() => { - if (!activeBinding || !orderNo) return - const timer = window.setInterval(() => { - void pollDouyuBinding(orderNo) - .then((response) => applyData(response.data)) - .catch(() => undefined) - }, POLL_INTERVAL_MS) - return () => window.clearInterval(timer) - }, [activeBinding, applyData, orderNo]) useEffect(() => { const url = live?.qrUrl || '' diff --git a/apps/frontend/tests/fulfillment-realtime-flow.test.ts b/apps/frontend/tests/fulfillment-realtime-flow.test.ts new file mode 100644 index 00000000..8b6ebb79 --- /dev/null +++ b/apps/frontend/tests/fulfillment-realtime-flow.test.ts @@ -0,0 +1,36 @@ +import assert from 'node:assert/strict' +import { readFileSync } from 'node:fs' +import { dirname, join } from 'node:path' +import { fileURLToPath } from 'node:url' +import test from 'node:test' + +const root = dirname(fileURLToPath(import.meta.url)) + +function source(relativePath: string) { + return readFileSync(join(root, '..', relativePath), 'utf8') +} + +test('斗鱼领取页使用订单级 SSE,不再固定 3 秒轮询绑定状态', () => { + const page = source('src/pages/douyu-fulfillment/DouyuFulfillmentPage.tsx') + assert.ok(page.includes('useRealtimeEvents')) + assert.ok(page.includes('/realtime')) + assert.ok(page.includes("event.type === 'customer_order.changed'")) + assert.ok(!page.includes('POLL_INTERVAL_MS')) + assert.ok(!page.includes('pollDouyuBinding(')) +}) + +test('履约管道状态由后台 SSE 失效刷新,不再 30 秒轮询', () => { + const page = source('src/pages/admin/AdminFulfillmentChannelPage.tsx') + const layout = source('src/layouts/AdminLayout.tsx') + assert.ok(!page.includes('refetchInterval: 30_000')) + assert.match(page, /SSE\s+自动刷新/) + assert.ok(layout.includes("event.type === 'fulfillment_pipeline.changed'")) + assert.ok(layout.includes("queryKey: ['fulfillment-pipelines']")) +}) + +test('公共订单 SSE 允许匿名连接且只携带重读信号', () => { + const hook = source('src/hooks/useRealtimeEvents.ts') + assert.ok(hook.includes('allowAnonymous')) + assert.ok(hook.includes("| 'customer_order.changed'")) + assert.ok(hook.includes("| 'fulfillment_pipeline.changed'")) +}) diff --git a/docs/统一订单履约与财务模型-权威版.md b/docs/统一订单履约与财务模型-权威版.md index ca43148d..b75e1e0f 100644 --- a/docs/统一订单履约与财务模型-权威版.md +++ b/docs/统一订单履约与财务模型-权威版.md @@ -3,7 +3,7 @@ type: 权威架构与实施计划 description: 订单、内部 SKU、履约路由、履约执行、商品、成本与财务的唯一权威口径及重构计划。 tags: [订单, 内部SKU, 履约, 商品, 成本, 财务, 迁移] status: authoritative -version: 2.27 +version: 2.29 updated_at: 2026-11-18 --- @@ -12,7 +12,7 @@ updated_at: 2026-11-18 > 状态:**唯一权威文档**。 > 最后校准:2026-11-18。 > 生产基线:迁移 `166`。 -> 开发基线:迁移 `170`(仅本地,尚未部署生产)。 +> 开发基线:迁移 `172`(仅本地,尚未部署生产)。 > > 从本文件生效起,订单、内部 SKU、履约渠道、履约载体、标准商品、成本和财务相关实现, > 只能以本文件为业务口径。其他旧分析只作为历史资料,不再具备设计或验收效力。 @@ -285,6 +285,9 @@ terminal 已退款、退款申请、平台取消或商业订单已关闭 - 自动补载体扫描只允许读取 `v_fulfillment_queue.actionable_for_carrier = TRUE`。 - `configuration`、`operator_review`、`terminal` 不得进入自动补载体 cursor,也不得阻塞新订单。 +- 新订单的主推进路径必须按当前 `orderItemIds` 定向执行“渠道判定 → 载体补建 → 再判定”, + 不得从全局水位重新扫描;全局 cursor 和定时任务只用于漏事件兜底。 +- 渠道、载体和自动发布发生变化后必须主动推送后台订单 SSE;定时任务不再作为页面感知状态变化的主路径。 - 后台履约待办必须读取同一 `v_fulfillment_queue`,四个页签分别展示对应桶。 - 售后/终止桶不得重新指定履约渠道;配置桶只补配置,人工处理桶只由运营确认重试或复核。 - 补载体每日扫描采用“最近窗口新单优先 + 历史 actionable cursor”两段式;新单不能排在 @@ -359,6 +362,9 @@ manual fulfillment ④ 已绑定且 `can_rebind = false` 时不得生成换绑二维码,必须展示冷却剩余天数; ⑤ 绑定二维码是 10 分钟短期会话状态,不单独落库;Connector 重启后以账号级 CK 恢复会话并重新查询 `game_role`,已绑定事实照常确认,未绑定事实回到重新生成二维码。 +- 斗鱼客户领取页只允许通过订单级 SSE 接收“需要重读”的瞬态信号,不得固定秒级轮询绑定状态。 + SSE 不携带订单、角色或 CK 快照;页面收到信号或断线重连后,重新读取 `/api/v1/douyu-fulfillment/<订单号>` + 的权威快照。live-hub 快照字段没有实际变化时不得重复广播,避免读接口与 SSE 自激循环。 - 半自动任务通过 `connector_mode` 显式记录 Connector 来源: `embedded` 为 order_site 内置真实实现并作为默认值,`external` 为显式配置的远程真实实现, `mock` 为 order_site 内置开发 Mock 且仅在非生产环境可用。开发 Mock 造单时默认选择 `embedded`, @@ -395,11 +401,35 @@ manual fulfillment - 外部 Connector 通过签名 Webhook `POST /api/integration/platform-fulfillment/semi-auto/task-state` 提交登录与绑定快照,事件 ID 使用 `integration_inbox` 幂等;Connector 只提交平台观察到的事实, 不得直接声明业务履约完成。执行状态由登录、绑定和人工确认规则推导。 +- order_site 与 live-hub 的通信职责必须区分: + ① order_site → live-hub 的正常路径走事务 `integration_outbox`,事件必须携带目标订单项的有界 + 业务快照和稳定去重指纹,由 worker 投递签名 + `POST /api/integration/platform-fulfillment/events/order-sync`;live-hub 正常建单不得再依赖 + 回查 order_site 的待履约表,也不得使用“最近 500 条”作为正确性窗口; + ② 旧版事件只允许按明确订单项 ID 定向兼容查询,不得回退成全量窗口扫描; + ③ live-hub → order_site 的状态同步由 live-hub Outbox 投递签名 Webhook + `POST /api/v1/integration/platform-fulfillment/binding-state`,半自动 Connector 使用 + `/semi-auto/task-state`;接收端统一通过 `integration_inbox` 幂等。状态载荷必须携带 + live-hub 单调 `stateVersion`,order_site 拒绝旧版本覆盖新版本; + ④ 客户明确操作允许调用 `customer-sessions/ensure|binding/start|status|confirm` 同步 RPC, + 使用 `X-Integration-Key`,失败直接反馈客户,不伪装成 Outbox 已受理; + ⑤ SSE 只属于浏览器 ↔ order_site,不是 order_site ↔ live-hub 的跨服务消息通道。 +- live-hub 新任务使用 `next_allocate_at` 作为选号到期时间,任务创建或映射就绪后立即唤醒选号 + worker;首次选号不得等待固定 45 秒。失败后再写下一次重试时间,批量大小只能限制吞吐, + 不能成为数据正确性上限。 +- 斗鱼客户页 `GET /api/v1/douyu-fulfillment/<订单号>` 和 live-hub 后台任务详情 GET 必须是纯读: + 不得在读取接口中同步准备账号、调用平台或触发全量订单同步。未准备完成时返回 `preparing` + 或现有安全投影,后续由事务事件更新并通过 SSE 通知页面重读。 +- live-hub 的低频对账只允许补齐状态 Outbox 和异常任务,不得重新承担正常订单发现; + 正常订单发现完全由 order_site 事务 Outbox 驱动。 - 后台“任务 → 半自动履约”由 SSE 失效通知驱动读取,不得对列表或详情做固定秒级轮询。 后台列表首次读取可执行最近 30 天、最多 500 条、15 秒节流的有界兜底回填, 不得在每次列表查询时扫描全库历史订单。 - 客户页在登录或绑定等专用状态同步阶段只允许一个活动同步循环,不得同时轮询整单、登录和绑定。 非专用阶段使用低频整单同步;所有写操作完成后以服务端最新快照为准,不做客户端乐观状态拼接。 +- “履约渠道 → 管道状态”由后台 SSE 失效刷新,不得固定 30 秒轮询。管道状态只用于观测和手动补跑; + 新订单是否及时推进取决于入库事件、定向履约推进、事务 Outbox 和即时选号唤醒, + 不取决于该页面是否打开。 - 半自动任务每 15 分钟执行一次限量兜底对账,只处理活跃且有 Connector 会话的任务; 可通过 `SEMI_AUTO_RECONCILE_SECONDS` 调整,最低 60 秒。对账失败只更新最近错误,不覆盖人工完成或取消状态。 - 开发环境的半自动集成测试单必须通过正式 `upsertOrderFromSource` 入库,并继续经过 SKU 映射、 @@ -1117,7 +1147,7 @@ docs/archive/ ## 十三、当前下一步 -截至 2026-11-18,生产基线为 `166`,集成分支开发基线为 `170`。迁移 `152` 保护订单来源快照, +截至 2026-11-18,生产基线为 `166`,集成分支开发基线为 `172`。迁移 `152` 保护订单来源快照, 迁移 `158–160` 收口寄卖登记人同步、寄卖平台与自动匹配设置; 迁移 `161` 一次建立人工渠道半自动任务、内置 Connector 默认值、账号级 Cookie JSON 凭证、 任务凭证引用和最终约束;迁移 `162` 建立履约待办四桶只读投影、补载体专用索引和新单优先扫描口径。 @@ -1137,6 +1167,10 @@ docs/archive/ 「登录 → 填写资料 → 绑定角色」,资料未填全不得生成绑定二维码。 迁移 `170` 增加半自动全链路报文日志,客户页、管理端和外部 Connector 共用同一追踪口径; 角色比对仍以区服、角色名、角色 ID 三项完全一致作为「提交平台绑定」的唯一放行条件。 +迁移 `171` 建立斗鱼客户领取、live-hub 事务 Outbox/Inbox 和绑定状态安全投影。 +迁移 `172` 将 order_site → live-hub 订单事件升级为订单项快照契约,增加配置停用/订单关闭收敛、 +稳定去重指纹和 `live_state_version`;live-hub 同步增加 `next_allocate_at`、即时选号唤醒与 +`state_version`,删除正常链路上的 500 条回查窗口。 迁移中保留的 `semi_auto.credential.export` 权限仅作兼容记录, 不再作为 CK 导出门禁。