940 lines
31 KiB
TypeScript
940 lines
31 KiB
TypeScript
/**
|
||
* 订单退款（P2 手动先行）：
|
||
* 1. 手动登记退款 → order_refunds（一条记录 = 一个订单项）；
|
||
* 2. 整单退款按订单项拆成多条、共享 batch_no；
|
||
* 3. 全额退完后把订单 pay_status 置为 refunded，并关闭该订单项的成本异常；
|
||
* 4. 重算当天销售事实，净收入与毛利立即冲减。
|
||
*
|
||
* 后续接平台退款 API 时，只需写 source='api'/'platform' 的记录，其余逻辑复用。
|
||
*/
|
||
import type { PoolClient } from 'pg'
|
||
|
||
import { query, withTransaction } from '../../db/client.js'
|
||
import type { AdminSession } from '../admin/admin-auth-service.js'
|
||
import { createHttpError } from '../../utils/http.js'
|
||
import { generateRefundNo } from '../../utils/random.js'
|
||
import { nowIso } from '../../utils/time.js'
|
||
import { rebuildChannelSalesDailyFacts } from './sales-facts-channel-service.js'
|
||
import { syncChannelCostSnapshots } from '../cost-center/cost-snapshot-service.js'
|
||
import { approveKuaishouIndustryRefund } from '../platforms/kuaishou-industry/refund-service.js'
|
||
import { syncFinanceLedgerFromFacts } from './finance-ledger-service.js'
|
||
|
||
export type OrderRefundRow = {
|
||
id: number
|
||
refund_no: string
|
||
batch_no: string
|
||
order_id: number
|
||
order_item_id: number
|
||
amount_fen: number
|
||
reason: string
|
||
note: string
|
||
source: string
|
||
status: string
|
||
refunded_at: string
|
||
operator_admin_user_id: number | null
|
||
operator_name?: string | null
|
||
voided_at: string | null
|
||
void_reason: string
|
||
created_at: string
|
||
sku_name?: string | null
|
||
}
|
||
|
||
export type OrderRefund = {
|
||
id: number
|
||
refundNo: string
|
||
batchNo: string
|
||
orderId: number
|
||
orderItemId: number
|
||
skuName: string
|
||
amountFen: number
|
||
reason: string
|
||
note: string
|
||
source: string
|
||
status: string
|
||
refundedAt: string
|
||
operatorAdminUserId: number | null
|
||
operatorName: string
|
||
voidedAt: string | null
|
||
voidReason: string
|
||
createdAt: string
|
||
}
|
||
|
||
export type CreateManualRefundInput = {
|
||
orderId: number | string
|
||
orderItemId?: number | string | null | undefined
|
||
amountFen?: number | string | null | undefined
|
||
reason?: string | undefined
|
||
note?: string | undefined
|
||
refundedAt?: string | undefined
|
||
/** 默认 manual；平台接口退款写 platform，平台回调写 api。 */
|
||
source?: 'manual' | 'api' | 'platform' | 'legacy'
|
||
/** 平台退款单号/外部流水号。 */
|
||
externalRef?: string
|
||
}
|
||
|
||
export async function listOrderRefunds(orderId: number | string): Promise<OrderRefund[]> {
|
||
const id = normalizeId(orderId, '订单 ID')
|
||
const result = await query<OrderRefundRow>(
|
||
`
|
||
SELECT
|
||
r.*,
|
||
oi.sku_name,
|
||
COALESCE(NULLIF(u.display_name, ''), u.username, '') AS operator_name
|
||
FROM order_refunds r
|
||
LEFT JOIN v_order_item_current oi ON oi.id = r.order_item_id
|
||
LEFT JOIN admin_users u ON u.id = r.operator_admin_user_id
|
||
WHERE r.order_id = $1
|
||
ORDER BY r.refunded_at DESC, r.id DESC
|
||
`,
|
||
[id],
|
||
)
|
||
return result.rows.map(mapOrderRefund)
|
||
}
|
||
|
||
export async function createManualRefund(
|
||
input: CreateManualRefundInput,
|
||
session: AdminSession | null,
|
||
): Promise<{
|
||
batchNo: string
|
||
refunds: OrderRefund[]
|
||
fullRefunded: boolean
|
||
closedExceptionCount: number
|
||
}> {
|
||
const orderId = normalizeId(input.orderId, '订单 ID')
|
||
const requestedItemId = input.orderItemId ? normalizeId(input.orderItemId, '订单项 ID') : null
|
||
const amountFen = normalizeAmountFen(input.amountFen)
|
||
if (requestedItemId && amountFen <= 0) {
|
||
throw createHttpError('退款金额必须大于 0', {
|
||
statusCode: 400,
|
||
errorCode: 'order_refund_amount_invalid',
|
||
})
|
||
}
|
||
if (!requestedItemId && amountFen > 0) {
|
||
throw createHttpError('整单退款不需要填写金额，系统按订单项剩余可退金额拆分', {
|
||
statusCode: 400,
|
||
errorCode: 'order_refund_amount_not_allowed',
|
||
})
|
||
}
|
||
const reason = normalizeText(input.reason, 200) || '手动退款'
|
||
const note = normalizeText(input.note, 500)
|
||
const refundedAt = normalizeTimestamp(input.refundedAt)
|
||
const source = normalizeRefundSource(input.source)
|
||
const externalRef = normalizeText(input.externalRef, 120)
|
||
const now = nowIso()
|
||
|
||
const written = await withTransaction(async (client) => {
|
||
const orderResult = await client.query<{
|
||
id: number
|
||
pay_status: string
|
||
basis_at: string
|
||
}>(
|
||
`
|
||
SELECT id, pay_status, COALESCE(paid_at, created_at) AS basis_at
|
||
FROM orders
|
||
WHERE id = $1
|
||
FOR UPDATE
|
||
`,
|
||
[orderId],
|
||
)
|
||
const order = orderResult.rows[0]
|
||
if (!order) {
|
||
throw createHttpError('订单不存在', {
|
||
statusCode: 404,
|
||
errorCode: 'order_refund_order_not_found',
|
||
})
|
||
}
|
||
const activeItems = await client.query<{ total: number }>(
|
||
`SELECT COUNT(*)::int AS total FROM v_order_item_current
|
||
WHERE order_id = $1 AND fulfillment_status <> 'archived'`,
|
||
[orderId],
|
||
)
|
||
if (Number(activeItems.rows[0]?.total || 0) > 0) {
|
||
// 只有断代后订单才影响财务；历史归档订单退款不校验期间。
|
||
await assertBasisPeriodOpen(client, order.basis_at, '退款')
|
||
await assertRefundMonthOpen(client, '退款', toChinaDate(refundedAt || now))
|
||
}
|
||
|
||
const itemsResult = await client.query<{
|
||
id: number
|
||
sku_name: string
|
||
revenue_fen: number
|
||
refunded_fen: number
|
||
}>(
|
||
`
|
||
SELECT
|
||
oi.id,
|
||
COALESCE(oi.sku_name, '') AS sku_name,
|
||
GREATEST(COALESCE(oi.revenue_amount_fen, 0), 0)::bigint AS revenue_fen,
|
||
COALESCE((
|
||
SELECT SUM(r.amount_fen)
|
||
FROM order_refunds r
|
||
WHERE r.order_item_id = oi.id AND r.status = 'confirmed'
|
||
), 0)::bigint AS refunded_fen
|
||
FROM v_order_item_current oi
|
||
WHERE oi.order_id = $1
|
||
ORDER BY oi.id
|
||
`,
|
||
[orderId],
|
||
)
|
||
const items = itemsResult.rows
|
||
if (items.length === 0) {
|
||
throw createHttpError('订单没有商品明细，无法退款', {
|
||
statusCode: 409,
|
||
errorCode: 'order_refund_items_missing',
|
||
})
|
||
}
|
||
|
||
const targets = requestedItemId
|
||
? items.filter((item) => Number(item.id) === requestedItemId)
|
||
: items
|
||
if (requestedItemId && targets.length === 0) {
|
||
throw createHttpError('订单项不属于该订单', {
|
||
statusCode: 400,
|
||
errorCode: 'order_refund_item_mismatch',
|
||
})
|
||
}
|
||
|
||
const rows: Array<{ itemId: number; amountFen: number }> = []
|
||
for (const item of targets) {
|
||
const remaining = Math.max(0, Number(item.revenue_fen) - Number(item.refunded_fen))
|
||
if (requestedItemId) {
|
||
if (amountFen > remaining) {
|
||
throw createHttpError(`退款金额超出可退金额（剩余 ${formatFen(remaining)}）`, {
|
||
statusCode: 409,
|
||
errorCode: 'order_refund_amount_exceeds',
|
||
})
|
||
}
|
||
rows.push({ itemId: Number(item.id), amountFen })
|
||
} else if (remaining > 0) {
|
||
rows.push({ itemId: Number(item.id), amountFen: remaining })
|
||
}
|
||
}
|
||
if (rows.length === 0) {
|
||
throw createHttpError('该订单没有可退金额（可能已全部退款）', {
|
||
statusCode: 409,
|
||
errorCode: 'order_refund_nothing_left',
|
||
})
|
||
}
|
||
|
||
if (externalRef) {
|
||
const duplicate = await client.query<{ id: number }>(
|
||
`SELECT id FROM order_refunds
|
||
WHERE source = $1 AND external_ref = $2
|
||
LIMIT 1`,
|
||
[source, externalRef],
|
||
)
|
||
if (duplicate.rows[0]) {
|
||
throw createHttpError('该平台退款单号已登记过，不能重复退款', {
|
||
statusCode: 409,
|
||
errorCode: 'order_refund_external_ref_exists',
|
||
})
|
||
}
|
||
}
|
||
|
||
const batchNo = generateRefundNo(new Date(refundedAt))
|
||
const insertedIds: number[] = []
|
||
for (const [index, row] of rows.entries()) {
|
||
try {
|
||
const inserted = await client.query<{ id: number }>(
|
||
`
|
||
INSERT INTO order_refunds (
|
||
refund_no, batch_no, order_id, order_item_id, amount_fen,
|
||
reason, note, source, status, refunded_at, external_ref,
|
||
operator_admin_user_id, created_at, updated_at
|
||
) VALUES (
|
||
$1, $2, $3, $4, $5,
|
||
$6, $7, $8, 'confirmed', $9::timestamptz, $10,
|
||
$11, $12::timestamptz, $12::timestamptz
|
||
)
|
||
RETURNING id
|
||
`,
|
||
[
|
||
`${batchNo}-${String(index + 1).padStart(2, '0')}`,
|
||
batchNo,
|
||
orderId,
|
||
row.itemId,
|
||
row.amountFen,
|
||
reason,
|
||
note,
|
||
source,
|
||
refundedAt,
|
||
externalRef,
|
||
session?.userId || null,
|
||
now,
|
||
],
|
||
)
|
||
insertedIds.push(Number(inserted.rows[0]?.id || 0))
|
||
} catch (error) {
|
||
if ((error as { code?: string }).code === '23505') {
|
||
throw createHttpError('该平台退款单号已登记过，不能重复退款', {
|
||
statusCode: 409,
|
||
errorCode: 'order_refund_external_ref_exists',
|
||
})
|
||
}
|
||
throw error
|
||
}
|
||
}
|
||
|
||
// 订单项都退完 → 订单级 pay_status 同步为 refunded（与平台全额退款口径一致）。
|
||
const totalResult = await client.query<{ revenue_fen: number; refunded_fen: number }>(
|
||
`
|
||
SELECT
|
||
COALESCE(SUM(GREATEST(COALESCE(oi.revenue_amount_fen, 0), 0)), 0)::bigint AS revenue_fen,
|
||
COALESCE((
|
||
SELECT SUM(r.amount_fen)
|
||
FROM order_refunds r
|
||
JOIN order_items ri ON ri.id = r.order_item_id
|
||
WHERE ri.order_id = $1 AND r.status = 'confirmed'
|
||
), 0)::bigint AS refunded_fen
|
||
FROM v_order_item_current oi
|
||
WHERE oi.order_id = $1
|
||
`,
|
||
[orderId],
|
||
)
|
||
const totalRevenue = Number(totalResult.rows[0]?.revenue_fen || 0)
|
||
const totalRefunded = Number(totalResult.rows[0]?.refunded_fen || 0)
|
||
const fullRefunded = totalRevenue > 0 && totalRefunded >= totalRevenue
|
||
if (fullRefunded && order.pay_status !== 'refunded') {
|
||
await client.query(
|
||
`UPDATE orders SET pay_status = 'refunded', updated_at = $1::timestamptz WHERE id = $2`,
|
||
[now, orderId],
|
||
)
|
||
}
|
||
|
||
// 已完成全额退款的订单项，成本异常直接闭环（退款单不再需要成本）。
|
||
const fullyRefundedItems = items
|
||
.filter((item) => {
|
||
const refunded = rows
|
||
.filter((row) => row.itemId === Number(item.id))
|
||
.reduce((sum, row) => sum + row.amountFen, 0)
|
||
return Number(item.refunded_fen) + refunded >= Number(item.revenue_fen)
|
||
})
|
||
.map((item) => Number(item.id))
|
||
let closedExceptionCount = 0
|
||
if (fullyRefundedItems.length > 0) {
|
||
const closed = await client.query(
|
||
`
|
||
UPDATE cost_exceptions
|
||
SET status = 'ignored',
|
||
resolved_at = $1::timestamptz,
|
||
resolved_by_admin_user_id = $2,
|
||
resolution_note = $3
|
||
WHERE status = 'open'
|
||
AND order_item_id = ANY($4::bigint[])
|
||
`,
|
||
[now, session?.userId || null, '订单已退款，成本异常自动关闭', fullyRefundedItems],
|
||
)
|
||
closedExceptionCount = closed.rowCount || 0
|
||
}
|
||
|
||
return {
|
||
batchNo,
|
||
insertedIds,
|
||
fullRefunded,
|
||
closedExceptionCount,
|
||
basisAt: order.basis_at,
|
||
}
|
||
})
|
||
|
||
// 比例类费用按净收入计：退款后重算相关订单项的费用快照，再回填事实。
|
||
const refundedItems = await query<{ order_item_id: number }>(
|
||
'SELECT DISTINCT order_item_id FROM order_refunds WHERE id = ANY($1::bigint[])',
|
||
[written.insertedIds],
|
||
)
|
||
try {
|
||
for (const row of refundedItems.rows) {
|
||
await syncChannelCostSnapshots({
|
||
afterId: Math.max(0, Number(row.order_item_id) - 1),
|
||
batchSize: 1,
|
||
maxBatches: 1,
|
||
})
|
||
}
|
||
} catch {
|
||
// 快照重算失败不影响退款本身，成本快照管道会兜底。
|
||
}
|
||
|
||
await refreshActiveRefundFacts(
|
||
refundedItems.rows.map((row) => Number(row.order_item_id)),
|
||
toChinaDate(written.basisAt),
|
||
)
|
||
|
||
const refunds = await listOrderRefunds(orderId)
|
||
return {
|
||
batchNo: written.batchNo,
|
||
refunds: refunds.filter((item) => written.insertedIds.includes(item.id)),
|
||
fullRefunded: written.fullRefunded,
|
||
closedExceptionCount: written.closedExceptionCount,
|
||
}
|
||
}
|
||
|
||
export async function voidOrderRefund(
|
||
refundId: number | string,
|
||
payload: { reason?: string },
|
||
session: AdminSession | null,
|
||
): Promise<{ refund: OrderRefund; rebuiltDate: string }> {
|
||
const id = normalizeId(refundId, '退款记录 ID')
|
||
const reason = normalizeText(payload.reason, 200) || '撤销退款'
|
||
const now = nowIso()
|
||
|
||
const context = await withTransaction(async (client) => {
|
||
const result = await client.query<{
|
||
id: number
|
||
order_id: number
|
||
status: string
|
||
pay_status: string
|
||
basis_at: string
|
||
}>(
|
||
`
|
||
SELECT r.id, r.order_id, r.status, o.pay_status, COALESCE(o.paid_at, o.created_at) AS basis_at
|
||
FROM order_refunds r
|
||
JOIN orders o ON o.id = r.order_id
|
||
WHERE r.id = $1
|
||
FOR UPDATE
|
||
`,
|
||
[id],
|
||
)
|
||
const row = result.rows[0]
|
||
if (!row) {
|
||
throw createHttpError('退款记录不存在', {
|
||
statusCode: 404,
|
||
errorCode: 'order_refund_not_found',
|
||
})
|
||
}
|
||
if (row.status !== 'confirmed') {
|
||
throw createHttpError('该退款记录已撤销', {
|
||
statusCode: 409,
|
||
errorCode: 'order_refund_already_voided',
|
||
})
|
||
}
|
||
const activeItems = await client.query<{ total: number }>(
|
||
`SELECT COUNT(*)::int AS total FROM v_order_item_current
|
||
WHERE order_id = $1 AND fulfillment_status <> 'archived'`,
|
||
[row.order_id],
|
||
)
|
||
if (Number(activeItems.rows[0]?.total || 0) > 0) {
|
||
await assertBasisPeriodOpen(client, row.basis_at, '撤销退款')
|
||
await assertRefundMonthOpen(client, '撤销退款')
|
||
}
|
||
await client.query(
|
||
`
|
||
UPDATE order_refunds
|
||
SET status = 'voided',
|
||
voided_at = $1::timestamptz,
|
||
void_reason = $2,
|
||
operator_admin_user_id = COALESCE($3, operator_admin_user_id),
|
||
updated_at = $1::timestamptz
|
||
WHERE id = $4
|
||
`,
|
||
[now, reason, session?.userId || null, id],
|
||
)
|
||
|
||
// 撤销后按“剩余 confirmed 退款”重算订单支付状态：
|
||
// 全额退款撤销必须把订单从 refunded 恢复为 paid，否则销售事实仍会按全额退款冲减。
|
||
const totals = await client.query<{ revenue_fen: number; refunded_fen: number }>(
|
||
`
|
||
SELECT
|
||
COALESCE(SUM(GREATEST(COALESCE(oi.revenue_amount_fen, 0), 0)), 0)::bigint AS revenue_fen,
|
||
COALESCE((
|
||
SELECT SUM(r.amount_fen)
|
||
FROM order_refunds r
|
||
JOIN order_items ri ON ri.id = r.order_item_id
|
||
WHERE ri.order_id = $1 AND r.status = 'confirmed'
|
||
), 0)::bigint AS refunded_fen
|
||
FROM v_order_item_current oi
|
||
WHERE oi.order_id = $1
|
||
`,
|
||
[row.order_id],
|
||
)
|
||
const totalRevenue = Number(totals.rows[0]?.revenue_fen || 0)
|
||
const totalRefunded = Number(totals.rows[0]?.refunded_fen || 0)
|
||
let nextPayStatus = row.pay_status
|
||
if (totalRevenue > 0) {
|
||
nextPayStatus = totalRefunded >= totalRevenue ? 'refunded' : 'paid'
|
||
}
|
||
await client.query(
|
||
`UPDATE orders SET pay_status = $1, updated_at = $2::timestamptz WHERE id = $3`,
|
||
[nextPayStatus, now, row.order_id],
|
||
)
|
||
|
||
// 退款时自动关闭的成本异常，撤销后重新打开，避免成本缺口被永久忽略。
|
||
await client.query(
|
||
`
|
||
UPDATE cost_exceptions
|
||
SET status = 'open',
|
||
resolved_at = NULL,
|
||
resolved_by_admin_user_id = NULL,
|
||
resolution_note = ''
|
||
WHERE status = 'ignored'
|
||
AND resolution_note = '订单已退款，成本异常自动关闭'
|
||
AND order_item_id IN (SELECT id FROM order_items WHERE order_id = $1)
|
||
`,
|
||
[row.order_id],
|
||
)
|
||
|
||
return { orderId: Number(row.order_id), basisAt: row.basis_at }
|
||
})
|
||
|
||
const rebuiltDate = toChinaDate(context.basisAt)
|
||
const voidedItem = await query<{ order_item_id: number }>(
|
||
'SELECT order_item_id FROM order_refunds WHERE id = $1',
|
||
[id],
|
||
)
|
||
await refreshActiveRefundFacts(
|
||
voidedItem.rows.map((row) => Number(row.order_item_id)),
|
||
rebuiltDate,
|
||
)
|
||
const refunds = await listOrderRefunds(context.orderId)
|
||
const refund = refunds.find((item) => item.id === id)
|
||
if (!refund) {
|
||
throw createHttpError('退款记录读取失败', {
|
||
statusCode: 500,
|
||
errorCode: 'order_refund_reload_failed',
|
||
})
|
||
}
|
||
return { refund, rebuiltDate }
|
||
}
|
||
|
||
export function mapOrderRefund(row: OrderRefundRow): OrderRefund {
|
||
return {
|
||
id: Number(row.id),
|
||
refundNo: row.refund_no,
|
||
batchNo: row.batch_no || '',
|
||
orderId: Number(row.order_id),
|
||
orderItemId: Number(row.order_item_id),
|
||
skuName: row.sku_name || '',
|
||
amountFen: Number(row.amount_fen),
|
||
reason: row.reason || '',
|
||
note: row.note || '',
|
||
source: row.source || 'manual',
|
||
status: row.status,
|
||
refundedAt: row.refunded_at,
|
||
operatorAdminUserId: row.operator_admin_user_id ? Number(row.operator_admin_user_id) : null,
|
||
operatorName: row.operator_name || '',
|
||
voidedAt: row.voided_at,
|
||
voidReason: row.void_reason || '',
|
||
createdAt: row.created_at,
|
||
}
|
||
}
|
||
|
||
async function assertRefundMonthOpen(
|
||
client: Pick<PoolClient, 'query'>,
|
||
action: string,
|
||
date?: string,
|
||
) {
|
||
const day = date || CHINA_DATE_FORMATTER.format(new Date())
|
||
const periodKey = day.slice(0, 7)
|
||
const period = await client.query<{ status: string }>(
|
||
`SELECT status FROM finance_periods WHERE period_key = $1 LIMIT 1`,
|
||
[periodKey],
|
||
)
|
||
if (period.rows[0]?.status === 'closed') {
|
||
throw createHttpError(`退款所属期间 ${periodKey} 已关账，请先反关账后再${action}`, {
|
||
statusCode: 409,
|
||
errorCode: 'order_refund_period_closed',
|
||
})
|
||
}
|
||
}
|
||
|
||
async function assertBasisPeriodOpen(
|
||
client: Pick<PoolClient, 'query'>,
|
||
basisAt: string,
|
||
action: string,
|
||
) {
|
||
const basisDate = toChinaDate(basisAt)
|
||
if (!basisDate) return
|
||
const periodKey = basisDate.slice(0, 7)
|
||
const period = await client.query<{ status: string }>(
|
||
`SELECT status FROM finance_periods WHERE period_key = $1 LIMIT 1`,
|
||
[periodKey],
|
||
)
|
||
if (period.rows[0]?.status === 'closed') {
|
||
throw createHttpError(`订单所属期间 ${periodKey} 已关账，请先反关账后再${action}`, {
|
||
statusCode: 409,
|
||
errorCode: 'order_refund_period_closed',
|
||
})
|
||
}
|
||
}
|
||
|
||
function normalizeId(value: unknown, label: string): number {
|
||
const id = Number(value || 0)
|
||
if (!Number.isFinite(id) || id <= 0) {
|
||
throw createHttpError(`${label}无效`, { statusCode: 400, errorCode: 'invalid_id' })
|
||
}
|
||
return Math.trunc(id)
|
||
}
|
||
|
||
function normalizeAmountFen(value: unknown): number {
|
||
const amount = Number(value || 0)
|
||
if (!Number.isFinite(amount) || amount < 0) return 0
|
||
return Math.round(amount)
|
||
}
|
||
|
||
function normalizeText(value: unknown, maxLength: number): string {
|
||
return String(value ?? '')
|
||
.trim()
|
||
.slice(0, maxLength)
|
||
}
|
||
|
||
function normalizeTimestamp(value: unknown): string {
|
||
const text = String(value || '').trim()
|
||
if (!text) return nowIso()
|
||
const date = new Date(text)
|
||
if (Number.isNaN(date.getTime())) return nowIso()
|
||
return date.toISOString()
|
||
}
|
||
|
||
/** 模块级只构造一次：`new Intl.DateTimeFormat()` 每次约 0.5ms，逐条调用会线性放大。 */
|
||
const CHINA_DATE_FORMATTER = new Intl.DateTimeFormat('en-CA', {
|
||
timeZone: 'Asia/Shanghai',
|
||
year: 'numeric',
|
||
month: '2-digit',
|
||
day: '2-digit',
|
||
})
|
||
|
||
function toChinaDate(value: string): string {
|
||
const date = new Date(value)
|
||
if (Number.isNaN(date.getTime())) return ''
|
||
return CHINA_DATE_FORMATTER.format(date)
|
||
}
|
||
|
||
/**
|
||
* 退款后回填事实与总账：只处理断代后的订单项。
|
||
* 历史归档订单的退款不进入新财务口径（业务侧自行处理）。
|
||
*/
|
||
async function refreshActiveRefundFacts(itemIds: number[], basisDate: string): Promise<void> {
|
||
const ids = [...new Set(itemIds.filter((id) => Number.isInteger(id) && id > 0))]
|
||
if (ids.length === 0 || !basisDate) return
|
||
const active = await query<{ total: number }>(
|
||
`SELECT COUNT(*)::int AS total FROM v_order_item_current
|
||
WHERE id = ANY($1::bigint[]) AND fulfillment_status <> 'archived'`,
|
||
[ids],
|
||
)
|
||
if (Number(active.rows[0]?.total || 0) === 0) return
|
||
await rebuildChannelSalesDailyFacts({ dateFrom: basisDate, dateTo: basisDate })
|
||
await syncFinanceLedgerFromFacts({ dateFrom: basisDate, dateTo: basisDate })
|
||
}
|
||
|
||
function formatFen(value: number): string {
|
||
return `¥${(Number(value || 0) / 100).toFixed(2)}`
|
||
}
|
||
|
||
/**
|
||
* 平台退款：先调用平台退款接口，成功后再落本地退款记录（source=platform）。
|
||
*
|
||
* 当前只接入快手行业（91）的「同意退款」接口；抖音/拼多多暂无可用退款 API，
|
||
* 会返回 501，由后台手工登记兜底。
|
||
*/
|
||
export async function approveAndRecordKuaishouRefund(
|
||
input: {
|
||
orderId: number | string
|
||
orderItemId?: number | string | null | undefined
|
||
amountFen?: number | string | null | undefined
|
||
platformRefundId?: string | undefined
|
||
reason?: string | undefined
|
||
note?: string | undefined
|
||
refundedAt?: string | undefined
|
||
sellerId?: string | undefined
|
||
refundHandingWay?: unknown
|
||
status?: unknown
|
||
negotiateStatus?: unknown
|
||
desc?: string | undefined
|
||
},
|
||
session: AdminSession | null,
|
||
) {
|
||
const orderId = normalizeId(input.orderId, '订单 ID')
|
||
const platformRefundId = normalizeText(input.platformRefundId, 120)
|
||
if (!platformRefundId) {
|
||
throw createHttpError('缺少平台退款单号', {
|
||
statusCode: 400,
|
||
errorCode: 'platform_refund_id_required',
|
||
})
|
||
}
|
||
// 平台退款必须在调用平台前完成本地参数校验：平台一旦同意，本地再失败会造成账实不一致。
|
||
const orderItemId = Number(input.orderItemId)
|
||
if (!Number.isInteger(orderItemId) || orderItemId <= 0) {
|
||
throw createHttpError('平台退款必须指定订单项', {
|
||
statusCode: 400,
|
||
errorCode: 'platform_refund_order_item_required',
|
||
})
|
||
}
|
||
const order = await query<{ provider: string; platform_order_id: string }>(
|
||
`SELECT provider, platform_order_id FROM orders WHERE id = $1 LIMIT 1`,
|
||
[orderId],
|
||
)
|
||
const row = order.rows[0]
|
||
if (!row) {
|
||
throw createHttpError('订单不存在', {
|
||
statusCode: 404,
|
||
errorCode: 'platform_refund_order_not_found',
|
||
})
|
||
}
|
||
if (!['91kaquan', 'kuaishou-91'].includes(String(row.provider || ''))) {
|
||
throw createHttpError('该平台暂未接入退款 API，请使用手工退款登记', {
|
||
statusCode: 501,
|
||
errorCode: 'platform_refund_not_supported',
|
||
})
|
||
}
|
||
|
||
const amountFen = normalizeAmountFen(input.amountFen)
|
||
if (amountFen <= 0) {
|
||
throw createHttpError('平台退款金额必须大于 0', {
|
||
statusCode: 400,
|
||
errorCode: 'platform_refund_amount_invalid',
|
||
})
|
||
}
|
||
|
||
const existingItem = await query<{ id: number; fulfillment_status: string }>(
|
||
`SELECT id, fulfillment_status
|
||
FROM v_order_item_current
|
||
WHERE id = $1 AND order_id = $2
|
||
LIMIT 1`,
|
||
[orderItemId, orderId],
|
||
)
|
||
if (!existingItem.rows[0]) {
|
||
throw createHttpError('订单项不存在或不属于该订单', {
|
||
statusCode: 404,
|
||
errorCode: 'platform_refund_order_item_not_found',
|
||
})
|
||
}
|
||
|
||
// 已关账期间不能直接改原期间事实；必须先反关账，否则平台退款后本地无法正确冲减。
|
||
const basis = await query<{ basis_at: string }>(
|
||
`SELECT COALESCE(paid_at, created_at) AS basis_at FROM orders WHERE id = $1 LIMIT 1`,
|
||
[orderId],
|
||
)
|
||
const platformItemArchived = existingItem.rows[0]?.fulfillment_status === 'archived'
|
||
if (!platformItemArchived && basis.rows[0]?.basis_at) {
|
||
const basisDate = toChinaDate(String(basis.rows[0].basis_at))
|
||
const periodKey = basisDate.slice(0, 7)
|
||
const period = await query<{ status: string }>(
|
||
`SELECT status FROM finance_periods WHERE period_key = $1 LIMIT 1`,
|
||
[periodKey],
|
||
)
|
||
if (period.rows[0]?.status === 'closed') {
|
||
throw createHttpError(`订单所属期间 ${periodKey} 已关账，请先反关账后再退款`, {
|
||
statusCode: 409,
|
||
errorCode: 'order_refund_period_closed',
|
||
})
|
||
}
|
||
}
|
||
|
||
// 退款当天所属期间也必须开着，否则退款冲减会静默丢失（历史归档订单除外）。
|
||
const refundPeriodKey = CHINA_DATE_FORMATTER.format(new Date()).slice(0, 7)
|
||
const refundPeriod = platformItemArchived
|
||
? { rows: [] as Array<{ status: string }> }
|
||
: await query<{ status: string }>(
|
||
`SELECT status FROM finance_periods WHERE period_key = $1 LIMIT 1`,
|
||
[refundPeriodKey],
|
||
)
|
||
if (refundPeriod.rows[0]?.status === 'closed') {
|
||
throw createHttpError(`退款所属期间 ${refundPeriodKey} 已关账，请先反关账后再退款`, {
|
||
statusCode: 409,
|
||
errorCode: 'order_refund_period_closed',
|
||
})
|
||
}
|
||
|
||
// 已经登记过的平台退款必须幂等返回，不能因为剩余可退为 0 被误判为超额。
|
||
const recorded = await findRecordedPlatformRefund(orderId, platformRefundId)
|
||
if (recorded) {
|
||
return {
|
||
approval: { idempotent: true, platformRefundId },
|
||
batchNo: recorded.batchNo,
|
||
refunds: [recorded],
|
||
fullRefunded: false,
|
||
closedExceptionCount: 0,
|
||
}
|
||
}
|
||
|
||
// 先做可退金额校验，再落退款意图；平台调用之后不再做“才发现金额超了”的校验。
|
||
const remainingFen = await getRefundableFen(orderId, orderItemId)
|
||
if (amountFen > remainingFen) {
|
||
throw createHttpError(`退款金额超出可退金额（剩余 ${formatFen(remainingFen)}）`, {
|
||
statusCode: 409,
|
||
errorCode: 'order_refund_amount_exceeds',
|
||
})
|
||
}
|
||
|
||
const intent = await beginPlatformRefundIntent({
|
||
provider: '91kaquan',
|
||
externalRef: platformRefundId,
|
||
orderId,
|
||
orderItemId,
|
||
amountFen,
|
||
actorUserId: session?.userId || null,
|
||
})
|
||
|
||
const needsPlatformCall =
|
||
intent.status === 'pending' ||
|
||
(intent.status === 'failed' && !String(intent.error_message || '').startsWith('record_failed:'))
|
||
|
||
let approval: unknown = { idempotent: true, platformRefundId }
|
||
if (needsPlatformCall) {
|
||
try {
|
||
approval = await approveKuaishouIndustryRefund({
|
||
refundId: platformRefundId,
|
||
refundAmount: amountFen,
|
||
desc: input.desc || input.note || '',
|
||
refundHandingWay: input.refundHandingWay,
|
||
status: input.status,
|
||
negotiateStatus: input.negotiateStatus,
|
||
...(input.sellerId ? { sellerId: input.sellerId } : {}),
|
||
})
|
||
await updatePlatformRefundIntent(intent.id, 'platform_approved')
|
||
} catch (error) {
|
||
const message = error instanceof Error ? error.message : String(error)
|
||
await updatePlatformRefundIntent(intent.id, 'failed', `platform_call_failed:${message}`)
|
||
throw error
|
||
}
|
||
}
|
||
|
||
try {
|
||
const refund = await createManualRefund(
|
||
{
|
||
orderId,
|
||
orderItemId,
|
||
amountFen,
|
||
reason: input.reason || '平台退款',
|
||
note: input.note,
|
||
refundedAt: input.refundedAt,
|
||
source: 'platform',
|
||
externalRef: platformRefundId,
|
||
},
|
||
session,
|
||
)
|
||
await updatePlatformRefundIntent(intent.id, 'recorded')
|
||
return { approval, ...refund }
|
||
} catch (error) {
|
||
const message = error instanceof Error ? error.message : String(error)
|
||
await updatePlatformRefundIntent(intent.id, 'failed', `record_failed:${message}`)
|
||
throw createHttpError(
|
||
`平台已同意退款，但本地记账失败：${message}。已保留退款意图，可用同一 platformRefundId 重试`,
|
||
{
|
||
statusCode: 502,
|
||
errorCode: 'platform_refund_record_failed',
|
||
},
|
||
)
|
||
}
|
||
}
|
||
|
||
type PlatformRefundIntentRow = {
|
||
id: number
|
||
status: string
|
||
error_message: string
|
||
}
|
||
|
||
async function beginPlatformRefundIntent(input: {
|
||
provider: string
|
||
externalRef: string
|
||
orderId: number
|
||
orderItemId: number
|
||
amountFen: number
|
||
actorUserId: number | null
|
||
}): Promise<PlatformRefundIntentRow> {
|
||
return withTransaction(async (client) => {
|
||
const existing = await client.query<PlatformRefundIntentRow>(
|
||
`SELECT id, status, error_message
|
||
FROM finance_refund_intents
|
||
WHERE provider = $1 AND external_ref = $2
|
||
FOR UPDATE`,
|
||
[input.provider, input.externalRef],
|
||
)
|
||
if (existing.rows[0]) return existing.rows[0]
|
||
|
||
try {
|
||
const inserted = await client.query<PlatformRefundIntentRow>(
|
||
`
|
||
INSERT INTO finance_refund_intents (
|
||
provider, external_ref, order_id, order_item_id, amount_fen,
|
||
status, error_message, created_by_admin_user_id, created_at, updated_at
|
||
) VALUES ($1, $2, $3, $4, $5, 'pending', '', $6, $7, $7)
|
||
RETURNING id, status, error_message
|
||
`,
|
||
[
|
||
input.provider,
|
||
input.externalRef,
|
||
input.orderId,
|
||
input.orderItemId,
|
||
input.amountFen,
|
||
input.actorUserId,
|
||
nowIso(),
|
||
],
|
||
)
|
||
return inserted.rows[0] as PlatformRefundIntentRow
|
||
} catch (error) {
|
||
// 并发请求同时插入时，唯一键冲突后读取已存在的意图，由调用方按状态决定是否重试。
|
||
if ((error as { code?: string }).code === '23505') {
|
||
const again = await client.query<PlatformRefundIntentRow>(
|
||
`SELECT id, status, error_message
|
||
FROM finance_refund_intents
|
||
WHERE provider = $1 AND external_ref = $2
|
||
LIMIT 1`,
|
||
[input.provider, input.externalRef],
|
||
)
|
||
return again.rows[0] as PlatformRefundIntentRow
|
||
}
|
||
throw error
|
||
}
|
||
})
|
||
}
|
||
|
||
async function updatePlatformRefundIntent(
|
||
id: number,
|
||
status: 'platform_approved' | 'recorded' | 'failed',
|
||
errorMessage = '',
|
||
) {
|
||
await query(
|
||
`UPDATE finance_refund_intents
|
||
SET status = $2, error_message = $3, updated_at = $4
|
||
WHERE id = $1`,
|
||
[id, status, errorMessage.slice(0, 1000), nowIso()],
|
||
)
|
||
}
|
||
|
||
async function getRefundableFen(orderId: number, orderItemId: number): Promise<number> {
|
||
const result = await query<{ remaining_fen: string }>(
|
||
`
|
||
SELECT
|
||
(GREATEST(COALESCE(oi.revenue_amount_fen, 0), 0)
|
||
- COALESCE((
|
||
SELECT SUM(r.amount_fen)
|
||
FROM order_refunds r
|
||
WHERE r.order_item_id = oi.id AND r.status = 'confirmed'
|
||
), 0))::bigint AS remaining_fen
|
||
FROM v_order_item_current oi
|
||
WHERE oi.id = $1 AND oi.order_id = $2
|
||
LIMIT 1
|
||
`,
|
||
[orderItemId, orderId],
|
||
)
|
||
if (!result.rows[0]) {
|
||
throw createHttpError('订单项不存在或不属于该订单', {
|
||
statusCode: 404,
|
||
errorCode: 'platform_refund_order_item_not_found',
|
||
})
|
||
}
|
||
return Number(result.rows[0].remaining_fen || 0)
|
||
}
|
||
|
||
async function findRecordedPlatformRefund(orderId: number, externalRef: string) {
|
||
const result = await query<{ id: number }>(
|
||
`SELECT id FROM order_refunds
|
||
WHERE order_id = $1 AND source = 'platform' AND external_ref = $2 AND status = 'confirmed'
|
||
LIMIT 1`,
|
||
[orderId, externalRef],
|
||
)
|
||
if (!result.rows[0]) return null
|
||
const refunds = await listOrderRefunds(orderId)
|
||
return refunds.find((item) => item.id === Number(result.rows[0]?.id)) || null
|
||
}
|
||
|
||
function normalizeRefundSource(value: unknown): 'manual' | 'api' | 'platform' | 'legacy' {
|
||
const source = String(value || 'manual').trim()
|
||
if (source === 'manual' || source === 'api' || source === 'platform' || source === 'legacy') {
|
||
return source
|
||
}
|
||
throw createHttpError('退款来源无效', {
|
||
statusCode: 400,
|
||
errorCode: 'order_refund_source_invalid',
|
||
})
|
||
}
|