Files
order_site/apps/backend/src/services/integration/outbox-worker.ts
T
yml 9b2fcf1d1f feat(fulfillment): 增加事务 Outbox 同步履约状态
- 用事务 Outbox 和签名 Webhook 替换直接状态回调
- 增加 Outbox 投递 worker、重试与低频对账兜底
- 缓存客户领取页绑定状态并补充签名与迁移测试
2026-11-18 11:00:28 +08:00

210 lines
5.7 KiB
TypeScript

import { query, withTransaction } from '../../db/client.js'
import { logError, logInfo, logWarn } from '../../utils/logger.js'
import { buildWebhookSignature } from './webhook-signature.js'
const DEFAULT_INTERVAL_MS = 1000
const DEFAULT_BATCH_SIZE = 20
const DEFAULT_MAX_ATTEMPTS = 12
const REQUEST_TIMEOUT_MS = 5000
const PROCESSING_STALE_SECONDS = 120
type OutboxRow = {
id: string
event_id: string
payload_json: unknown
attempts: number
}
let timer: NodeJS.Timeout | null = null
let running = false
let stopped = true
function envInt(name: string, fallback: number, min: number, max: number) {
const parsed = Number(process.env[name])
if (!Number.isFinite(parsed)) return fallback
return Math.max(min, Math.min(max, Math.trunc(parsed)))
}
export function integrationOutboxConfigured() {
return Boolean(
String(process.env.LIVE_HUB_PLATFORM_FULFILLMENT_URL || '').trim() &&
String(process.env.PLATFORM_FULFILLMENT_INTEGRATION_KEY || '').trim(),
)
}
export function integrationOutboxBackoffSeconds(attempts: number) {
const normalized = Math.max(1, Math.trunc(Number(attempts) || 1))
return Math.min(3600, 5 * 2 ** Math.min(normalized - 1, 10))
}
async function claimDueEvents(limit: number): Promise<OutboxRow[]> {
return withTransaction(async (client) => {
await client.query(
`
UPDATE integration_outbox
SET status = 'pending',
locked_at = NULL,
next_attempt_at = NOW()
WHERE status = 'processing'
AND locked_at < NOW() - ($1 * INTERVAL '1 second')
`,
[PROCESSING_STALE_SECONDS],
)
const claimed = await client.query<OutboxRow>(
`
SELECT id, event_id, payload_json, attempts
FROM integration_outbox
WHERE status = 'pending'
AND next_attempt_at <= NOW()
ORDER BY id ASC
LIMIT $1
FOR UPDATE SKIP LOCKED
`,
[limit],
)
const ids = claimed.rows.map((row) => Number(row.id)).filter((id) => id > 0)
if (ids.length === 0) return []
await client.query(
`
UPDATE integration_outbox
SET status = 'processing',
locked_at = NOW()
WHERE id = ANY($1::bigint[])
`,
[ids],
)
return claimed.rows
})
}
async function deliverEvent(row: OutboxRow) {
const baseUrl = String(process.env.LIVE_HUB_PLATFORM_FULFILLMENT_URL || '')
.trim()
.replace(/\/+$/, '')
const integrationKey = String(process.env.PLATFORM_FULFILLMENT_INTEGRATION_KEY || '').trim()
const endpoint = `${baseUrl}/api/integration/platform-fulfillment/events/order-sync`
const rawBody =
typeof row.payload_json === 'string' ? row.payload_json : JSON.stringify(row.payload_json)
const timestamp = String(Math.floor(Date.now() / 1000))
const signature = buildWebhookSignature(integrationKey, timestamp, rawBody)
const response = await fetch(endpoint, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Integration-Key': integrationKey,
'X-Integration-Event-Id': row.event_id,
'X-Integration-Timestamp': timestamp,
'X-Integration-Signature': signature,
},
body: rawBody,
signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
})
if (!response.ok) {
throw new Error(`live-hub 返回 HTTP ${response.status}`)
}
}
async function markSent(eventId: string) {
await query(
`
UPDATE integration_outbox
SET status = 'sent',
sent_at = NOW(),
locked_at = NULL,
last_error = ''
WHERE event_id = $1
`,
[eventId],
)
}
async function markFailed(row: OutboxRow, error: unknown) {
const attempts = Number(row.attempts || 0) + 1
const maxAttempts = envInt('INTEGRATION_OUTBOX_MAX_ATTEMPTS', DEFAULT_MAX_ATTEMPTS, 1, 100)
const dead = attempts >= maxAttempts
const message = (error instanceof Error ? error.message : String(error)).slice(0, 2000)
await query(
`
UPDATE integration_outbox
SET status = $2,
attempts = $3,
locked_at = NULL,
next_attempt_at = NOW() + ($4 * INTERVAL '1 second'),
last_error = $5
WHERE event_id = $1
`,
[
row.event_id,
dead ? 'dead' : 'pending',
attempts,
dead ? 0 : integrationOutboxBackoffSeconds(attempts),
message,
],
)
if (dead) {
logError('[integration/outbox]', '事件超过最大重试次数,已进入 dead', {
eventId: row.event_id,
attempts,
error: message,
})
}
}
async function publishDueEvents() {
if (!integrationOutboxConfigured()) return
const batchSize = envInt('INTEGRATION_OUTBOX_BATCH_SIZE', DEFAULT_BATCH_SIZE, 1, 100)
const rows = await claimDueEvents(batchSize)
for (const row of rows) {
try {
await deliverEvent(row)
await markSent(row.event_id)
} catch (error) {
await markFailed(row, error)
}
}
}
async function runLoop() {
if (stopped || running) return
running = true
try {
await publishDueEvents()
} catch (error) {
logWarn('[integration/outbox]', '投递轮次失败', { error })
} finally {
running = false
if (!stopped) {
timer = setTimeout(
() => {
void runLoop()
},
envInt('INTEGRATION_OUTBOX_INTERVAL_MS', DEFAULT_INTERVAL_MS, 250, 60_000),
)
}
}
}
export function startIntegrationOutboxWorker() {
if (timer || !stopped) return
stopped = false
if (!integrationOutboxConfigured()) {
logWarn('[integration/outbox]', '未配置 live-hub 地址或集成密钥,worker 仅保持待命')
} else {
logInfo('[integration/outbox]', '事务 Outbox worker 已启动')
}
timer = setTimeout(() => {
void runLoop()
}, 0)
}
export function stopIntegrationOutboxWorker() {
stopped = true
if (timer) {
clearTimeout(timer)
timer = null
}
}