feat(fulfillment): 增加事务 Outbox 同步履约状态
- 用事务 Outbox 和签名 Webhook 替换直接状态回调 - 增加 Outbox 投递 worker、重试与低频对账兜底 - 缓存客户领取页绑定状态并补充签名与迁移测试
This commit is contained in:
@@ -0,0 +1,209 @@
|
||||
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
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user