From 398eafa9113e2e92664bc75608fed6429e2083c7 Mon Sep 17 00:00:00 2001 From: yml2213 Date: Fri, 6 Nov 2026 10:38:26 +0800 Subject: [PATCH 1/7] =?UTF-8?q?feat(kuaishou):=20=E5=A2=9E=E5=8A=A0?= =?UTF-8?q?=E5=8E=86=E5=8F=B2=E7=94=B5=E5=AD=90=E5=88=B8=E8=A1=A5=E5=8F=91?= =?UTF-8?q?=E5=B9=B6=E6=A0=B8=E9=94=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../src/routes/admin/kuaishou-industry.ts | 27 +++ .../admin/kuaishou-industry-admin-service.ts | 206 +++++++++++++++++- .../kuaishou-industry-reissue-consume.test.ts | 76 +++++++ apps/backend/src/types/admin/route-inputs.ts | 3 + apps/backend/src/types/admin/write-inputs.ts | 19 ++ .../pages/admin/AdminKuaishouIndustryPage.tsx | 194 +++++++++++++++++ .../src/services/admin/kuaishou-industry.ts | 11 + apps/frontend/src/types/admin/index.ts | 2 + .../src/types/admin/kuaishou-industry.ts | 25 +++ .../kuaishou-industry-reissue-consume.test.ts | 45 ++++ 10 files changed, 607 insertions(+), 1 deletion(-) create mode 100644 apps/backend/src/services/admin/kuaishou-industry-reissue-consume.test.ts create mode 100644 apps/frontend/tests/kuaishou-industry-reissue-consume.test.ts diff --git a/apps/backend/src/routes/admin/kuaishou-industry.ts b/apps/backend/src/routes/admin/kuaishou-industry.ts index 76a03f9d..d0b6e6c4 100644 --- a/apps/backend/src/routes/admin/kuaishou-industry.ts +++ b/apps/backend/src/routes/admin/kuaishou-industry.ts @@ -9,6 +9,7 @@ import { listAdminKuaishouIndustryRefunds, listAdminKuaishouIndustryShops, listAdminKuaishouIndustryVouchers, + reissueAndConsumeAdminKuaishouIndustryVoucher, resendAdminKuaishouIndustryVoucherCode, reverseAdminKuaishouIndustryVoucher, } from '../../services/admin/kuaishou-industry-admin-service.js' @@ -21,6 +22,7 @@ import type { AdminKuaishouIndustryVoucherCheckAvailableRouteBody, AdminKuaishouIndustryVoucherConsumeRouteBody, AdminKuaishouIndustryVoucherDestroyRouteBody, + AdminKuaishouIndustryVoucherReissueConsumeRouteBody, AdminKuaishouIndustryVoucherResendRouteBody, AdminKuaishouIndustryVoucherReverseRouteBody, } from '../../types/admin/route-inputs.js' @@ -204,6 +206,24 @@ router.post( ), ) +router.post( + '/kuaishou-industry/vouchers/reissue-consume', + requireAdminRoles(['admin', 'operator']), + createJsonHandler( + (req) => + reissueAndConsumeAdminKuaishouIndustryVoucher( + req.body as AdminKuaishouIndustryVoucherReissueConsumeRouteBody, + ), + { + successMessage: '历史券补发并核销已执行', + errorMessage: '历史券补发并核销失败', + scope: '[admin/kuaishou-industry/vouchers/reissue-consume]', + audit: (req, data) => + buildKuaishouIndustryAudit('kuaishou_industry_voucher_reissue_consume', req.body, data), + }, + ), +) + router.post( '/kuaishou-industry/vouchers/destroy', requireAdminRoles(['admin', 'operator']), @@ -238,6 +258,13 @@ function buildKuaishouIndustryAudit(action: string, body: unknown, data: unknown success: Boolean(result.success), httpStatus: Number(result.httpStatus || 0) || 0, error: String(result.error || ''), + stage: String(result.stage || ''), + reason: String(result.reason || ''), + validMinutes: Number(result.validMinutes || 0) || 0, + originalValidEndTime: Number(result.originalValidEndTime || 0) || 0, + validEndTime: Number(result.validEndTime || 0) || 0, + sendSuccess: Boolean(result.sendSuccess), + consumeSuccess: Boolean(result.consumeSuccess), }, } } diff --git a/apps/backend/src/services/admin/kuaishou-industry-admin-service.ts b/apps/backend/src/services/admin/kuaishou-industry-admin-service.ts index ff1ba098..8c676758 100644 --- a/apps/backend/src/services/admin/kuaishou-industry-admin-service.ts +++ b/apps/backend/src/services/admin/kuaishou-industry-admin-service.ts @@ -27,6 +27,7 @@ import { resendKuaishouIndustryVoucherSendCallback } from '../platforms/kuaishou import { consumeKuaishouIndustryVoucher, destroyKuaishouIndustryVoucher, + isKuaishouIndustryVoucherSendCallbackSuccess, resolveKuaishouIndustryEticketType, } from '../platforms/kuaishou-industry/voucher-service.js' import { @@ -39,6 +40,8 @@ import { attachKuaishouIndustryVoucherToTask } from '../platforms/kuaishou-indus import type { KuaishouIndustryOpenApiCallResult } from '../platforms/kuaishou-industry/openapi-client.js' import type { KuaishouIndustryVoucherRow, TaskRow } from '../../types/repository/rows.js' +const historicalReissueInFlight = new Set() + export async function listAdminKuaishouIndustryVouchers( input: KuaishouIndustryVoucherAdminListQuery = {}, ) { @@ -201,11 +204,204 @@ export async function resendAdminKuaishouIndustryVoucherCode(input: JsonObject = return { success: result.success, response: 'response' in result ? result.response || null : null, - error: result.error || '', + error: + result.error || + resolveKuaishouOpenApiErrorMessage('response' in result ? result.response : null), voucher: result.voucher ? mapAdminKuaishouIndustryVoucher(result.voucher) : null, } } +/** + * 历史发码失败券的受控补偿入口。 + * + * 只允许未使用券进入；先把本地有效期临时改到未来，再复用原券码发码。 + * 发码成功后立即核销，避免为了补回调把历史券重新暴露给买家。 + */ +export async function reissueAndConsumeAdminKuaishouIndustryVoucher(input: JsonObject = {}) { + const voucher = await resolveRequiredVoucher(input) + const voucherCode = String(voucher.voucher_code || '').trim() + const accountStatus = String(voucher.status || '') + .trim() + .toUpperCase() + const nowMs = Date.now() + const originalValidEndTime = Number(voucher.valid_end_time || 0) || 0 + + if (accountStatus !== 'UNUSED') { + throw createHttpError('仅未使用电子凭证可以补发并核销', { + statusCode: 409, + errorCode: 'admin_kuaishou_industry_reissue_voucher_not_unused', + }) + } + + if (isKuaishouIndustryVoucherSendCallbackSuccess(voucher) && originalValidEndTime > nowMs) { + throw createHttpError('该电子凭证已发码成功且仍在有效期，请直接执行手动核销', { + statusCode: 409, + errorCode: 'admin_kuaishou_industry_reissue_voucher_already_active', + }) + } + + if (historicalReissueInFlight.has(voucherCode)) { + throw createHttpError('该电子凭证正在补发，请勿重复提交', { + statusCode: 409, + errorCode: 'admin_kuaishou_industry_reissue_in_progress', + }) + } + + const validity = resolveKuaishouIndustryHistoricalReissueWindow(input.validMinutes, nowMs) + const reason = normalizeKuaishouIndustryHistoricalReissueReason(input.reason) + const originalValidStartTime = Number(voucher.valid_start_time || 0) || 0 + const validStartTime = + originalValidStartTime > 0 ? Math.min(originalValidStartTime, nowMs - 1_000) : nowMs - 1_000 + + historicalReissueInFlight.add(voucherCode) + try { + const prepared = await updateKuaishouIndustryVoucherByCode(voucherCode, { + validStartTime, + validEndTime: validity.validEndTime, + sendCallbackStatus: 'pending', + sendCallbackLastError: '', + sendCallbackResponseJson: {}, + sendCallbackSentAt: null, + updatedAt: new Date().toISOString(), + }) + if (!prepared) { + throw createHttpError('准备历史券补发时未找到电子凭证', { + statusCode: 404, + errorCode: 'admin_kuaishou_industry_reissue_voucher_not_found', + }) + } + + const sendResult = await resendAdminKuaishouIndustryVoucherCode({ + voucherCode, + oid: voucher.oid, + orderId: voucher.oid, + }) + if (!sendResult.success) { + return { + success: false, + stage: 'send', + reason, + validMinutes: validity.validMinutes, + originalValidEndTime, + validEndTime: validity.validEndTime, + sendSuccess: false, + consumeSuccess: false, + response: sendResult.response, + error: sendResult.error || '电子凭证发码回调失败', + voucher: sendResult.voucher, + task: null, + } + } + + const sentVoucher = await findKuaishouIndustryVoucherByCode(voucherCode, voucher.oid) + if (!sentVoucher || !isKuaishouIndustryVoucherSendCallbackSuccess(sentVoucher)) { + return { + success: false, + stage: 'send', + reason, + validMinutes: validity.validMinutes, + originalValidEndTime, + validEndTime: validity.validEndTime, + sendSuccess: false, + consumeSuccess: false, + response: sendResult.response, + error: '电子凭证发码回调返回成功，但本地状态未更新', + voucher: sentVoucher ? mapAdminKuaishouIndustryVoucher(sentVoucher) : null, + task: null, + } + } + + const task = sentVoucher.task_id ? await getTaskById(sentVoucher.task_id) : null + const consumeType = String(input.consumeType || '').trim() + const consumeInput: Parameters[1] = { + source: 'admin_historical_reissue_consume', + token: String(input.token || sentVoucher.token || '').trim(), + consumeTime: Date.now(), + ...(consumeType ? { consumeType } : {}), + ...(input.serialNum ? { serialNum: String(input.serialNum).trim() } : {}), + ...(input.storeName ? { storeName: String(input.storeName).trim() } : {}), + ...(input.storeAddress ? { storeAddress: String(input.storeAddress).trim() } : {}), + ...(input.expressCode ? { expressCode: String(input.expressCode).trim() } : {}), + ...(input.expressNo ? { expressNo: String(input.expressNo).trim() } : {}), + } + if (task) { + consumeInput.task = task + } + + const consumeResult = await consumeKuaishouIndustryVoucher(sentVoucher, consumeInput) + if (!consumeResult.ok || !consumeResult.voucher) { + return { + success: false, + stage: 'consume', + reason, + validMinutes: validity.validMinutes, + originalValidEndTime, + validEndTime: validity.validEndTime, + sendSuccess: true, + consumeSuccess: false, + response: sendResult.response, + error: consumeResult.errorMessage || '电子凭证发码成功，但核销失败', + voucher: consumeResult.voucher + ? mapAdminKuaishouIndustryVoucher(consumeResult.voucher) + : mapAdminKuaishouIndustryVoucher(sentVoucher), + task: task ? mapTaskReference(task) : null, + } + } + + return { + success: true, + stage: 'completed', + reason, + validMinutes: validity.validMinutes, + originalValidEndTime, + validEndTime: validity.validEndTime, + sendSuccess: true, + consumeSuccess: true, + response: sendResult.response, + error: '', + voucher: mapAdminKuaishouIndustryVoucher(consumeResult.voucher), + task: task ? mapTaskReference(task) : null, + } + } finally { + historicalReissueInFlight.delete(voucherCode) + } +} + +export function resolveKuaishouIndustryHistoricalReissueWindow( + rawMinutes: unknown, + nowMs = Date.now(), +) { + const validMinutes = Number(rawMinutes) + if (!Number.isInteger(validMinutes) || validMinutes < 1 || validMinutes > 60) { + throw createHttpError('临时有效期必须是 1 到 60 分钟的整数', { + statusCode: 400, + errorCode: 'admin_kuaishou_industry_reissue_valid_minutes_invalid', + }) + } + + return { + validMinutes, + validEndTime: nowMs + validMinutes * 60_000, + } +} + +export function normalizeKuaishouIndustryHistoricalReissueReason(rawReason: unknown) { + const reason = String(rawReason || '').trim() + if (!reason) { + throw createHttpError('补发原因不能为空', { + statusCode: 400, + errorCode: 'admin_kuaishou_industry_reissue_reason_required', + }) + } + if (reason.length > 200) { + throw createHttpError('补发原因不能超过 200 个字符', { + statusCode: 400, + errorCode: 'admin_kuaishou_industry_reissue_reason_too_long', + }) + } + return reason +} + export async function destroyAdminKuaishouIndustryVoucherByCode(input: JsonObject = {}) { const voucher = await resolveRequiredVoucher(input) const checkPayload = buildVoucherOpenApiPayload(input, voucher) @@ -485,6 +681,14 @@ function mapOpenApiResult(result: KuaishouIndustryOpenApiCallResult) { } } +function resolveKuaishouOpenApiErrorMessage(response: unknown) { + if (!response || typeof response !== 'object' || Array.isArray(response)) { + return '' + } + const current = response as Record + return String(current.error_msg || current.sub_msg || current.message || current.msg || '').trim() +} + function sanitizeOpenApiRequest(request: JsonObject | undefined): JsonObject | null { if (!request) { return null diff --git a/apps/backend/src/services/admin/kuaishou-industry-reissue-consume.test.ts b/apps/backend/src/services/admin/kuaishou-industry-reissue-consume.test.ts new file mode 100644 index 00000000..dd505a68 --- /dev/null +++ b/apps/backend/src/services/admin/kuaishou-industry-reissue-consume.test.ts @@ -0,0 +1,76 @@ +import assert from 'node:assert/strict' +import { readFile } from 'node:fs/promises' +import test from 'node:test' + +import { + normalizeKuaishouIndustryHistoricalReissueReason, + resolveKuaishouIndustryHistoricalReissueWindow, +} from './kuaishou-industry-admin-service.js' + +test('历史券补发窗口只允许 1 到 60 分钟', () => { + const nowMs = 1_800_000_000_000 + + assert.deepEqual(resolveKuaishouIndustryHistoricalReissueWindow(10, nowMs), { + validMinutes: 10, + validEndTime: nowMs + 10 * 60_000, + }) + assert.throws(() => resolveKuaishouIndustryHistoricalReissueWindow(0, nowMs), /1 到 60 分钟/) + assert.throws(() => resolveKuaishouIndustryHistoricalReissueWindow(61, nowMs), /1 到 60 分钟/) + assert.throws(() => resolveKuaishouIndustryHistoricalReissueWindow('1.5', nowMs), /1 到 60 分钟/) +}) + +test('历史券补发原因必填且限制长度', () => { + assert.equal( + normalizeKuaishouIndustryHistoricalReissueReason(' 历史发码失败补发 '), + '历史发码失败补发', + ) + assert.throws(() => normalizeKuaishouIndustryHistoricalReissueReason(' '), /不能为空/) + assert.throws( + () => normalizeKuaishouIndustryHistoricalReissueReason('x'.repeat(201)), + /不能超过 200/, + ) +}) + +test('受控补发必须先重置有效期，再发码，最后立即核销', async () => { + const source = await readFile( + new URL('./kuaishou-industry-admin-service.ts', import.meta.url), + 'utf8', + ) + const start = source.indexOf( + 'export async function reissueAndConsumeAdminKuaishouIndustryVoucher', + ) + assert.ok(start > 0, '未找到历史券补发并核销服务') + const body = source.slice( + start, + source.indexOf('\nexport function resolveKuaishouIndustryHistoricalReissueWindow', start), + ) + + const prepareIndex = body.indexOf('updateKuaishouIndustryVoucherByCode') + const sendIndex = body.indexOf('resendAdminKuaishouIndustryVoucherCode') + const consumeIndex = body.indexOf('consumeKuaishouIndustryVoucher(sentVoucher') + + assert.ok(prepareIndex > 0, '必须先更新本地临时有效期') + assert.ok(sendIndex > prepareIndex, '必须先重置有效期再重发发码') + assert.ok(consumeIndex > sendIndex, '必须等发码成功后再执行核销') + assert.ok(body.includes("source: 'admin_historical_reissue_consume'"), '核销来源必须可审计') + assert.ok(body.includes("sendCallbackStatus: 'pending'"), '重发前必须重置发码状态') + assert.ok(body.includes("stage: 'send'"), '发码失败必须返回明确阶段') + assert.ok(body.includes("stage: 'consume'"), '核销失败必须返回明确阶段') + assert.ok(body.includes("stage: 'completed'"), '成功必须返回完成阶段') +}) + +test('补发并核销路由只允许管理员和运营执行', async () => { + const source = await readFile( + new URL('../../routes/admin/kuaishou-industry.ts', import.meta.url), + 'utf8', + ) + const routeIndex = source.indexOf("'/kuaishou-industry/vouchers/reissue-consume'") + assert.ok(routeIndex > 0, '未注册历史券补发并核销路由') + const routeBody = source.slice(routeIndex, source.indexOf('\nrouter.post(', routeIndex + 1)) + + assert.ok(routeBody.includes("requireAdminRoles(['admin', 'operator'])"), '必须限制管理员和运营') + assert.ok( + routeBody.includes("'kuaishou_industry_voucher_reissue_consume'"), + '必须写入独立审计动作', + ) +}) diff --git a/apps/backend/src/types/admin/route-inputs.ts b/apps/backend/src/types/admin/route-inputs.ts index f952cf12..4cb5aba7 100644 --- a/apps/backend/src/types/admin/route-inputs.ts +++ b/apps/backend/src/types/admin/route-inputs.ts @@ -20,6 +20,7 @@ import type { AdminKuaishouIndustryVoucherCheckAvailableInput, AdminKuaishouIndustryVoucherConsumeInput, AdminKuaishouIndustryVoucherDestroyInput, + AdminKuaishouIndustryVoucherReissueConsumeInput, AdminKuaishouIndustryVoucherResendInput, AdminKuaishouIndustryVoucherReverseInput, AdminCloudtentaclesTestLoginInput, @@ -49,6 +50,8 @@ export type AdminKuaishouIndustryVoucherCheckAvailableRouteBody = export type AdminKuaishouIndustryVoucherReverseRouteBody = AdminKuaishouIndustryVoucherReverseInput export type AdminKuaishouIndustryVoucherConsumeRouteBody = AdminKuaishouIndustryVoucherConsumeInput export type AdminKuaishouIndustryVoucherResendRouteBody = AdminKuaishouIndustryVoucherResendInput +export type AdminKuaishouIndustryVoucherReissueConsumeRouteBody = + AdminKuaishouIndustryVoucherReissueConsumeInput export type AdminKuaishouIndustryVoucherDestroyRouteBody = AdminKuaishouIndustryVoucherDestroyInput export type AdminNotificationConfigRouteBody = AdminNotificationConfigInput export type AdminNotificationTestRouteBody = AdminNotificationTestInput diff --git a/apps/backend/src/types/admin/write-inputs.ts b/apps/backend/src/types/admin/write-inputs.ts index bc1b268b..d224b99c 100644 --- a/apps/backend/src/types/admin/write-inputs.ts +++ b/apps/backend/src/types/admin/write-inputs.ts @@ -354,6 +354,25 @@ export type AdminKuaishouIndustryVoucherResendInput = { voucherCode?: string } +/** + * 历史券补偿：临时重建有效期，重发原券码发码回调，成功后立即核销。 + * validMinutes 只允许较短窗口，避免发码成功但核销失败时长期暴露可用券。 + */ +export type AdminKuaishouIndustryVoucherReissueConsumeInput = { + oid?: string + orderId?: string + taskId?: number | string + voucherCode?: string + validMinutes?: number | string + reason?: string + consumeType?: string + serialNum?: string + storeName?: string + storeAddress?: string + expressCode?: string + expressNo?: string +} + export type AdminKuaishouIndustryVoucherDestroyInput = { oid?: string orderId?: string diff --git a/apps/frontend/src/pages/admin/AdminKuaishouIndustryPage.tsx b/apps/frontend/src/pages/admin/AdminKuaishouIndustryPage.tsx index 85f695d0..ba0a3275 100644 --- a/apps/frontend/src/pages/admin/AdminKuaishouIndustryPage.tsx +++ b/apps/frontend/src/pages/admin/AdminKuaishouIndustryPage.tsx @@ -6,15 +6,18 @@ import { SearchOutlined, SendOutlined, SyncOutlined, + ThunderboltOutlined, } from '@ant-design/icons' import { Alert, Button, Card, + Checkbox, Collapse, Descriptions, Input, InputNumber, + Modal, Popconfirm, Select, Space, @@ -39,6 +42,7 @@ import { fetchAdminKuaishouIndustryShops, fetchAdminKuaishouIndustryVouchers, listAdminKuaishouIndustryRefunds, + reissueAndConsumeAdminKuaishouIndustryVoucher, resendAdminKuaishouIndustryVoucherCode, reverseAdminKuaishouIndustryVoucher, } from '@/services/admin' @@ -69,6 +73,7 @@ type IndustryActionKind = | 'destroy' | 'reverse' | 'resend' + | 'reissue-consume' | 'refund-list' | 'refund-approve' | 'refund-disagree' @@ -120,6 +125,11 @@ export default function AdminKuaishouIndustryPage() { const [actionLoading, setActionLoading] = useState('') const [consumingVoucherId, setConsumingVoucherId] = useState(null) const [reversingVoucherId, setReversingVoucherId] = useState(null) + const [reissueConsumeOpen, setReissueConsumeOpen] = useState(false) + const [reissueConsumeMinutes, setReissueConsumeMinutes] = useState(10) + const [reissueConsumeReason, setReissueConsumeReason] = + useState('历史发码失败补偿，补发后立即核销') + const [reissueConsumeConfirmed, setReissueConsumeConfirmed] = useState(false) const [vouchers, setVouchers] = useState([]) const [selectedVoucher, setSelectedVoucher] = useState(null) const [voucherTotal, setVoucherTotal] = useState(0) @@ -646,6 +656,64 @@ export default function AdminKuaishouIndustryPage() { } } + function openReissueConsumeModal() { + if (!selectedVoucher && !String(toolForm.voucherCode || '').trim()) { + showError('请先选择或填写本地券码') + return + } + if (selectedVoucher) { + const sendSucceeded = selectedVoucher.sendCallbackStatus === 'success' + const stillValid = Number(selectedVoucher.validEndTime || 0) > Date.now() + if (selectedVoucher.status !== 'UNUSED') { + showError('仅未使用电子凭证可以补发并核销') + return + } + if (sendSucceeded && stillValid) { + showError('该券已发码成功且仍在有效期，请直接执行手动核销') + return + } + } + setReissueConsumeConfirmed(false) + setReissueConsumeOpen(true) + } + + async function runReissueConsume() { + if (!reissueConsumeConfirmed) { + showError('请先确认已核实订单仍需履约') + return + } + + setActionLoading('reissue-consume') + try { + const response = await reissueAndConsumeAdminKuaishouIndustryVoucher({ + ...buildVoucherToolPayload(), + validMinutes: reissueConsumeMinutes, + reason: reissueConsumeReason, + }) + publishActionResult( + buildIndustryActionResultView('reissue-consume', '历史券补发并核销', response.data), + ) + if (response.data.success) { + showSuccess('原券码已同步到快手并完成核销') + setReissueConsumeOpen(false) + } else { + showError(response.data.error || '历史券补发并核销失败') + } + await loadVouchers() + } catch (error) { + const message = error instanceof Error ? error.message : '历史券补发并核销失败' + publishActionResult( + buildIndustryActionResultView('reissue-consume', '历史券补发并核销', { + success: false, + error: message, + }), + ) + showError(message) + } finally { + setActionLoading('') + } + } + async function runDestroy() { setActionLoading('destroy') try { @@ -870,6 +938,98 @@ export default function AdminKuaishouIndustryPage() { onChange={(key) => setActiveTab(key as IndustryTab)} items={tabItems} /> + + 60, + }} + onOk={runReissueConsume} + onCancel={() => setReissueConsumeOpen(false)} + destroyOnHidden + > + + + + + + + + + + setReissueConsumeConfirmed(event.target.checked)} + > + 我已核实该订单仍需履约，并确认补发后立即核销 + + + ) @@ -1210,6 +1370,15 @@ export default function AdminKuaishouIndustryPage() { > 手动核销 + {canRunScopedActions && hasConfigIssue ? ( - ) : null} diff --git a/apps/frontend/src/pages/admin/cost-center/CostCenterShell.tsx b/apps/frontend/src/pages/admin/cost-center/CostCenterShell.tsx index 6c318303..05e23324 100644 --- a/apps/frontend/src/pages/admin/cost-center/CostCenterShell.tsx +++ b/apps/frontend/src/pages/admin/cost-center/CostCenterShell.tsx @@ -23,7 +23,8 @@ import { Typography, } from 'antd' import { keepPreviousData, useIsFetching, useQuery, useQueryClient } from '@tanstack/react-query' -import { useEffect } from 'react' +import { useEffect, useRef } from 'react' +import { useSearchParams } from 'react-router' import FinanceSubNav from '@/components/admin/FinanceSubNav' import { usePersistedState } from '@/hooks/usePersistedState' @@ -73,7 +74,11 @@ function isCostScope(value: unknown): value is CostScope { export default function CostCenterShell() { const queryClient = useQueryClient() + const [searchParams] = useSearchParams() const canConfig = hasAdminPermission('finance.config') + const requestedScope = String(searchParams.get('scope') || '').trim() + const requestedTab = String(searchParams.get('tab') || '').trim() + const handledRouteRequestRef = useRef('') const [scope, setScope] = usePersistedState( 'admin-cost-center:scope', @@ -87,6 +92,20 @@ export default function CostCenterShell() { ) const mappingsApplicable = scope === 'all' || scope === 'work_order' + useEffect(() => { + const routeRequest = `${requestedScope}\u0000${requestedTab}` + if (routeRequest === '\u0000' || handledRouteRequestRef.current === routeRequest) return + handledRouteRequestRef.current = routeRequest + if (isCostScope(requestedScope) && requestedScope !== scope) { + setScope(requestedScope) + } + const requestedTabAllowed = + isCostCenterTab(requestedTab) && (requestedScope !== 'manual' || requestedTab !== 'mappings') + if (requestedTabAllowed && requestedTab !== activeTab) { + setActiveTab(requestedTab) + } + }, [activeTab, requestedScope, requestedTab, scope, setActiveTab, setScope]) + useEffect(() => { if (!mappingsApplicable && activeTab === 'mappings') { setActiveTab('products') diff --git a/apps/frontend/src/pages/admin/cost-center/ManualSkuConfigPanel.tsx b/apps/frontend/src/pages/admin/cost-center/ManualSkuConfigPanel.tsx index 97eff9c0..40c0368c 100644 --- a/apps/frontend/src/pages/admin/cost-center/ManualSkuConfigPanel.tsx +++ b/apps/frontend/src/pages/admin/cost-center/ManualSkuConfigPanel.tsx @@ -38,7 +38,8 @@ import { import PercentTable from '@/components/common/PercentTable' import type { TableColumnsType } from 'antd' import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query' -import { useState } from 'react' +import { useEffect, useRef, useState } from 'react' +import { useNavigate, useSearchParams } from 'react-router' import { deleteAdminManualSku, @@ -55,7 +56,10 @@ import { formatCreditUnitPriceYuan, } from '@/utils/credit-unit-price' +import { useCostCenter } from './CostCenterContext' + type ConfigFormValues = { + skuKey: string channels: Array<{ platformKey: string creditQuantity: number @@ -87,8 +91,15 @@ function platformOptionLabel(platformKey: string, label: string, creditUnitPrice export function ManualSkuConfigPanel() { const { message } = App.useApp() + const { canConfig } = useCostCenter() const queryClient = useQueryClient() + const navigate = useNavigate() + const [searchParams] = useSearchParams() const [form] = Form.useForm() + const handledDeepLinkRef = useRef('') + const deepLinkSku = String(searchParams.get('manualSku') || searchParams.get('sku') || '').trim() + const manualNewRequested = searchParams.get('manualNew') === '1' + const returnTo = String(searchParams.get('returnTo') || '').trim() const [keyword, setKeyword] = useState('') const [status, setStatus] = useState<'all' | 'configured' | 'unconfigured'>('unconfigured') @@ -125,7 +136,7 @@ export function ManualSkuConfigPanel() { const saveMutation = useMutation({ mutationFn: (values: ConfigFormValues) => saveAdminManualConfig({ - skuKey: editing?.skuKey || '', + skuKey: String(values.skuKey || editing?.skuKey || '').trim(), channels: values.channels.map((channel) => ({ platformKey: channel.platformKey, creditQuantity: Number(channel.creditQuantity || 0), @@ -139,10 +150,14 @@ export function ManualSkuConfigPanel() { : '' message.success(`配置已保存${syncHint}`) setModalOpen(false) + setEditing(null) void queryClient.invalidateQueries({ queryKey: ['admin-cost-center'] }) void queryClient.invalidateQueries({ queryKey: ['cost-center-voucher-products'] }) void queryClient.invalidateQueries({ queryKey: ['fulfillment-rules'] }) void queryClient.invalidateQueries({ queryKey: ['fulfillment-pending'] }) + if (returnTo.startsWith('/admin/fulfillment-channel')) { + void navigate(returnTo) + } }, onError: (error) => { message.error(error instanceof Error ? error.message : '保存失败') @@ -180,6 +195,7 @@ export function ManualSkuConfigPanel() { ] : [{ platformKey: '', creditQuantity: 0 }] form.setFieldsValue({ + skuKey: item.skuKey, channels: configuredChannels.map((channel) => ({ platformKey: channel.platformKey, creditQuantity: channel.creditQuantity, @@ -189,6 +205,36 @@ export function ManualSkuConfigPanel() { setModalOpen(true) } + function openCreateConfig(skuKey = '') { + setEditing(null) + form.resetFields() + form.setFieldsValue({ + skuKey: skuKey.trim(), + channels: [{ platformKey: '', creditQuantity: 0 }], + note: '', + }) + setModalOpen(true) + } + + useEffect(() => { + if (!canConfig) return + const deepLinkKey = deepLinkSku || (manualNewRequested ? '__new__' : '') + if (!deepLinkKey || handledDeepLinkRef.current === deepLinkKey) return + handledDeepLinkRef.current = deepLinkKey + if (deepLinkSku) { + setKeyword(deepLinkSku) + setStatus('all') + } + setEditing(null) + form.resetFields() + form.setFieldsValue({ + skuKey: deepLinkSku, + channels: [{ platformKey: '', creditQuantity: 0 }], + note: '', + }) + setModalOpen(true) + }, [canConfig, deepLinkSku, manualNewRequested, form]) + const columns: TableColumnsType = [ { title: '人工标准商品', @@ -276,24 +322,27 @@ export function ManualSkuConfigPanel() { key: 'actions', width: 150, fixed: 'right', - render: (_, row) => ( - - - deleteMutation.mutate(row.skuKey)} - > - - - - ), + deleteMutation.mutate(row.skuKey)} + > + + + + ) : ( + 只读 + ), }, ] @@ -303,13 +352,23 @@ export function ManualSkuConfigPanel() { } return ( - + } onClick={() => openCreateConfig()}> + 新增人工 SKU + + ) : null + } + > @@ -399,14 +458,17 @@ export function ManualSkuConfigPanel() { { void form.validateFields().then((values) => saveMutation.mutate(values)) }} - onCancel={() => setModalOpen(false)} + onCancel={() => { + setModalOpen(false) + setEditing(null) + }} destroyOnHidden width={560} > @@ -414,10 +476,37 @@ export function ManualSkuConfigPanel() { type="warning" showIcon style={{ marginBottom: 14 }} - message={`商品名称：${editing?.displayName || '（无）'}（仅供识别）`} + message={ + editing + ? `商品名称：${editing.displayName || '（无）'}（仅供识别）` + : '保存时自动创建标准商品，不需要先去商品目录手工新建' + } description="一个 SKU 可以配置多个渠道，客服确认履约时选择本次实际渠道。积分渠道填整数积分；备用金现金和统一结算填金额，最多两位小数。填 0 表示成本不固定，由客服确认时填写。" /> form={form} layout="vertical"> + { + const text = String(value || '').trim() + if (text && !/\p{Script=Han}/u.test(text)) { + throw new Error('内部 SKU 必须包含中文') + } + }, + }, + ]} + extra="保存后会生成 man:<内部 SKU> 标准商品，并统一用于订单渠道判定。" + > + + () // 历史修复只处理最近 30 天，避免很早以前的乱 SKU 再次进入商品与映射。 @@ -109,8 +108,6 @@ export function ProductCatalogPanel() { const [productStatusUpdatingId, setProductStatusUpdatingId] = useState(null) const [bootstrapPreviewing, setBootstrapPreviewing] = useState(false) const [bootstrapApplying, setBootstrapApplying] = useState(false) - const [archivingHistoricalManuals, setArchivingHistoricalManuals] = useState(false) - const [archivingSupersededManuals, setArchivingSupersededManuals] = useState(false) const bootstrapSyncOptionsRef = useRef({ includeDisabledTemplates: false }) const [productPage, setProductPage] = useState(1) const [productPageSize, setProductPageSize] = useState(ADMIN_DEFAULT_PAGE_SIZE) @@ -452,76 +449,6 @@ export function ProductCatalogPanel() { } } - async function archiveHistoricalManuals() { - setArchivingHistoricalManuals(true) - try { - const preview = (await archiveAdminHistoricalManualProducts()).data - if (preview.candidateCount === 0) { - message.info('没有需要归档的历史人工商品') - return - } - modal.confirm({ - title: '归档历史人工商品', - content: `将归档 ${preview.candidateCount} 个仅被已归档订单引用的历史人工商品。不会删除订单、订单项、成本或工单数据，商品只是从当前目录隐藏。`, - okText: '确认归档', - cancelText: '取消', - onOk: async () => { - setArchivingHistoricalManuals(true) - try { - const result = (await archiveAdminHistoricalManualProducts({ execute: true })).data - message.success(`已归档 ${result.archivedCount} 个历史人工商品`) - await queryClient.invalidateQueries({ queryKey: ['admin-cost-center-products'] }) - void queryClient.invalidateQueries({ queryKey: ['admin-cost-center-overview'] }) - void queryClient.invalidateQueries({ queryKey: ['admin-cost-center-options'] }) - } catch (error) { - message.error(error instanceof Error ? error.message : '归档历史人工商品失败') - } finally { - setArchivingHistoricalManuals(false) - } - }, - }) - } catch (error) { - message.error(error instanceof Error ? error.message : '读取历史人工商品失败') - } finally { - setArchivingHistoricalManuals(false) - } - } - - async function archiveSupersededManuals() { - setArchivingSupersededManuals(true) - try { - const preview = (await archiveAdminSupersededManualProducts()).data - if (preview.candidateCount === 0) { - message.info('没有已被其他渠道接管的人工归一商品') - return - } - modal.confirm({ - title: '归档跨渠道重复的人工归一商品', - content: `发现 ${preview.candidateCount} 个 man: 商品已有自动发货、接单平台或卡券主渠道。将归档这些旧商品，并把仍指向它们的人工兜底改指当前主商品；不会删除商品行、订单、订单项、成本版本或成本快照。`, - okText: '确认归档', - cancelText: '取消', - onOk: async () => { - setArchivingSupersededManuals(true) - try { - const result = (await archiveAdminSupersededManualProducts({ execute: true })).data - message.success( - `已归档 ${result.archivedCount} 个重复商品，修正 ${result.repointedChannelCount} 条人工兜底`, - ) - refreshAll() - } catch (error) { - message.error(error instanceof Error ? error.message : '归档跨渠道重复商品失败') - } finally { - setArchivingSupersededManuals(false) - } - }, - }) - } catch (error) { - message.error(error instanceof Error ? error.message : '读取跨渠道重复商品失败') - } finally { - setArchivingSupersededManuals(false) - } - } - function deleteProduct(item: ProductCatalogItem) { const affiliateHint = item.source === 'affiliate_dash' @@ -777,24 +704,6 @@ export function ProductCatalogPanel() { extra={ canConfig ? ( - {productSourceFilter === 'manual' ? ( - <> - - - - ) : null} {productSourceFilter === 'work_order' ? ( <> void productsQuery.refetch()} /> - + {productSourceFilter === 'manual' ? ( + + ) : ( + + )} ) : null } > + {productSourceFilter === 'manual' ? ( + + ) : null} {showCategoryBar ? ( <>
diff --git a/apps/frontend/src/services/admin/cost-center.ts b/apps/frontend/src/services/admin/cost-center.ts index f0dd3780..0cf20d58 100644 --- a/apps/frontend/src/services/admin/cost-center.ts +++ b/apps/frontend/src/services/admin/cost-center.ts @@ -96,32 +96,6 @@ export function createAdminProductCatalog(payload: Record) { return apiPost<{ product: ProductCatalogItem }>('/api/v1/admin/cost-center/products', payload) } -export function archiveAdminHistoricalManualProducts(payload: { execute?: boolean } = {}) { - return apiPost<{ - dryRun: boolean - candidateCount: number - archivedCount: number - sample: Array<{ id: number; canonical_sku: string; canonical_name: string }> - }>('/api/v1/admin/cost-center/products/archive-historical-manual', payload) -} - -export function archiveAdminSupersededManualProducts(payload: { execute?: boolean } = {}) { - return apiPost<{ - dryRun: boolean - candidateCount: number - archivedCount: number - repointedChannelCount: number - sample: Array<{ - id: number - canonical_sku: string - canonical_name: string - primary_channel: string - target_product_id: number - target_product_sku: string - }> - }>('/api/v1/admin/cost-center/products/archive-superseded-manual', payload) -} - export function syncAdminAffiliateDashProducts() { return apiPost<{ createdCount: number; updatedCount: number; productCount: number }>( '/api/v1/admin/cost-center/affiliate-products/sync', diff --git a/apps/frontend/tests/manual-sku-config-ui.test.ts b/apps/frontend/tests/manual-sku-config-ui.test.ts index 11157747..15ad7596 100644 --- a/apps/frontend/tests/manual-sku-config-ui.test.ts +++ b/apps/frontend/tests/manual-sku-config-ui.test.ts @@ -8,10 +8,56 @@ test('人工成本配置直接展示标准商品，不再要求按日期扫描 'utf8', ) - assert.ok(source.includes('人工标准商品与成本配置一一对应')) + assert.ok(source.includes('人工标准商品由人工配置自动创建')) assert.ok(source.includes("title: '人工标准商品'")) assert.ok(source.includes('SKU：{row.skuKey}')) assert.ok(!source.includes('扫描内部 SKU')) assert.ok(!source.includes('DatePicker.RangePicker')) assert.ok(!source.includes('rematchAdminManualFulfillments')) }) + +test('新增人工 SKU 直接保存配置，由后端自动创建标准商品', async () => { + const source = await readFile( + new URL('../src/pages/admin/cost-center/ManualSkuConfigPanel.tsx', import.meta.url), + 'utf8', + ) + + assert.ok(source.includes('新增人工 SKU')) + assert.ok(source.includes('openCreateConfig')) + assert.ok(source.includes('name="skuKey"')) + assert.ok(source.includes('保存时自动创建标准商品')) + assert.ok(source.includes('manualSku')) + assert.ok(source.includes("returnTo.startsWith('/admin/fulfillment-channel')")) +}) + +test('人工商品不再允许手工创建或执行旧批量归档', async () => { + const [productSource, serviceSource, queueSource, shellSource] = await Promise.all([ + readFile( + new URL('../src/pages/admin/cost-center/ProductCatalogPanel.tsx', import.meta.url), + 'utf8', + ), + readFile( + new URL('../../backend/src/services/cost-center/product-catalog-service.ts', import.meta.url), + 'utf8', + ), + readFile( + new URL('../src/pages/admin/AdminFulfillmentChannelPage.tsx', import.meta.url), + 'utf8', + ), + readFile( + new URL('../src/pages/admin/cost-center/CostCenterShell.tsx', import.meta.url), + 'utf8', + ), + ]) + + assert.ok(!productSource.includes('归档跨渠道重复商品')) + assert.ok(!productSource.includes('归档纯历史人工商品')) + assert.ok(productSource.includes("productSourceFilter === 'manual'")) + assert.ok(productSource.includes('manualNew=1')) + assert.ok(productSource.includes('人工标准商品由人工 SKU 配置自动创建')) + assert.ok(serviceSource.includes('cost_manual_product_managed_by_config')) + assert.ok(queueSource.includes('manualSku=${encodeURIComponent(sku)}')) + assert.ok(queueSource.includes("returnTo=${encodeURIComponent('/admin/fulfillment-channel')}")) + assert.ok(shellSource.includes("searchParams.get('scope')")) + assert.ok(shellSource.includes("searchParams.get('tab')")) +}) diff --git a/docs/成本中心API契约.md b/docs/成本中心API契约.md index 7062d381..525cc69c 100644 --- a/docs/成本中心API契约.md +++ b/docs/成本中心API契约.md @@ -7,16 +7,16 @@ ## 一、字段替换总表 -| 旧字段 | 新字段 | 出现位置 | -| --- | --- | --- | -| `cost_items.carrier_type` | `cost_items.cost_model` | DB / 成本项接口 | -| `cost_items.cost_type` | （并入 `cost_model`） | DB / 成本项接口 | -| `cost_snapshots.carrier_type` | （删除） | DB | -| `cost_exceptions.carrier_type` | （删除） | DB | -| `product_catalog.carrier_type` | （删除，改由 `canonical_sku` 前缀推导） | DB / 商品接口 | -| `sales_daily_facts.carrier_type` | `sales_daily_facts.channel` | DB / 销售事实接口 | -| `work_product_rules.legacy_cost_source` | （删除） | DB | -| `manual_expense_records` / `manual_expense_events` | （删除，人工成本只走确认履约） | DB | +| 旧字段 | 新字段 | 出现位置 | +| -------------------------------------------------- | --------------------------------------- | ----------------- | +| `cost_items.carrier_type` | `cost_items.cost_model` | DB / 成本项接口 | +| `cost_items.cost_type` | （并入 `cost_model`） | DB / 成本项接口 | +| `cost_snapshots.carrier_type` | （删除） | DB | +| `cost_exceptions.carrier_type` | （删除） | DB | +| `product_catalog.carrier_type` | （删除，改由 `canonical_sku` 前缀推导） | DB / 商品接口 | +| `sales_daily_facts.carrier_type` | `sales_daily_facts.channel` | DB / 销售事实接口 | +| `work_product_rules.legacy_cost_source` | （删除） | DB | +| `manual_expense_records` / `manual_expense_events` | （删除，人工成本只走确认履约） | DB | ## 二、枚举映射 @@ -24,16 +24,16 @@ 成本模型与履约方式正交：专属模型只对对应履约方式生效，通用模型对所有履约方式生效。 -| 新值 | 含义 | 取代旧的 | -| --- | --- | --- | -| `affiliate_purchase` | 自动发货上游采购成本 | `cost_type=auto_purchase` | -| `work_order_reward` | 接单平台打手报酬 | `cost_type=work_order_reward` | -| `third_party_voucher_cost` | 第三方卡券采购成本 | 新增 | -| `manual_actual` | 人工客服实际支出 | `cost_type=manual_service` | -| `platform_fee` | 平台服务费 | `cost_type=platform_fee` | -| `payment_fee` | 支付通道费 | `cost_type=payment_fee` | -| `after_sales_loss` | 售后损失 | `cost_type=after_sales_loss` | -| `other` | 其他 | `cost_type=shipping_other` / `cost_type=other` | +| 新值 | 含义 | 取代旧的 | +| -------------------------- | -------------------- | ---------------------------------------------- | +| `affiliate_purchase` | 自动发货上游采购成本 | `cost_type=auto_purchase` | +| `work_order_reward` | 接单平台打手报酬 | `cost_type=work_order_reward` | +| `third_party_voucher_cost` | 第三方卡券采购成本 | 新增 | +| `manual_actual` | 人工客服实际支出 | `cost_type=manual_service` | +| `platform_fee` | 平台服务费 | `cost_type=platform_fee` | +| `payment_fee` | 支付通道费 | `cost_type=payment_fee` | +| `after_sales_loss` | 售后损失 | `cost_type=after_sales_loss` | +| `other` | 其他 | `cost_type=shipping_other` / `cost_type=other` | ### 2.2 `pricing_mode`（精简为 3 个） @@ -67,7 +67,7 @@ DELETE /api/v1/admin/cost-center/cost-items/:id "unitName": "件", "currency": "CNY", "status": "active | archived", - "note": "" + "note": "", } ``` @@ -88,7 +88,7 @@ DELETE /api/v1/admin/cost-center/cost-items/:id "note": "", "snapshotCount": 0, "createdAt": "...", - "updatedAt": "..." + "updatedAt": "...", } ``` @@ -96,13 +96,13 @@ DELETE /api/v1/admin/cost-center/cost-items/:id 商品**不再返回 `carrierType`**。前端若要按来源分组，用 `canonicalSku` 前缀： -| 前缀 | 来源 | 建议展示名 | -| --- | --- | --- | -| `aff:` | 自动发货 | 自动发货 | -| `tpl:` | 接单模板 | 接单平台 | -| `wo:` | 工单证据 | 接单平台 | -| `man:` | 人工 | 人工 | -| 其他 | 未分类 | 未分类 | +| 前缀 | 来源 | 建议展示名 | +| ------ | -------- | ---------- | +| `aff:` | 自动发货 | 自动发货 | +| `tpl:` | 接单模板 | 接单平台 | +| `wo:` | 工单证据 | 接单平台 | +| `man:` | 人工 | 人工 | +| 其他 | 未分类 | 未分类 | `GET /api/v1/admin/cost-center/products` 的 `carrierType` 查询参数**保留**， 但语义改为「按 `canonical_sku` 前缀筛选」，取值 `affiliate_dash | work_order | manual`。 @@ -118,11 +118,11 @@ AND ( ### 4.1 渠道映射诊断与未归一队列 -| 接口 | 说明 | -| --- | --- | -| `GET /api/v1/admin/cost-center/mappings/diagnostics` | 标准商品数 / 映射数 / 有映射商品数 / 未归一订单项 / 未归一 SKU 组；按 `channel` 拆分聚合 | -| `GET /api/v1/admin/cost-center/mappings/unmapped` | 未归一队列，按「来源 + 店铺 + 平台 SKU + 履约方式」聚合，支持 `keyword` / `provider` / `channel` 与分页 | -| `POST /api/v1/admin/cost-center/mappings/backfill` | 回填订单项映射；返回 `resolvedExceptionCount`（已归一的 `product_mapping_missing` 异常自动收口） | +| 接口 | 说明 | +| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `GET /api/v1/admin/cost-center/mappings/diagnostics` | 标准商品数 / 映射数 / 有映射商品数 / 未归一订单项 / 未归一 SKU 组；按 `channel` 拆分聚合 | +| `GET /api/v1/admin/cost-center/mappings/unmapped` | 未归一队列，按「来源 + 店铺 + 平台 SKU + 履约方式」聚合，支持 `keyword` / `provider` / `channel` 与分页 | +| `POST /api/v1/admin/cost-center/mappings/backfill` | 回填订单项映射；返回 `resolvedExceptionCount`（已归一的 `product_mapping_missing` 异常自动收口） | ### 4.2 人工商品归一（已删除） @@ -150,6 +150,30 @@ AND ( 商品 `canonical_sku = man:<内部SKU>`，`canonical_name` 优先取 `manual_sku_registry.display_name`，否则取订单里最常见的 `sku_name`。 每日 `cost_finance_sync` 任务会对最近 N 天执行同一归一（不重复收口异常）。 +### 4.3 人工 SKU 配置（现行） + +人工标准商品不允许通过通用 `POST /api/v1/admin/cost-center/products` 手工创建。 +统一入口为： + +```text +POST /api/v1/admin/cost-center/manual-configs +``` + +```jsonc +{ + "skuKey": "破片手榴弹-兔兔白日梦", + "channels": [ + { "platformKey": "nanhang", "creditQuantity": 10 }, + { "platformKey": "fund_cash", "creditQuantity": 3.5 }, + ], + "note": "长期人工商品", +} +``` + +保存时后端自动创建或复用 `man:` 标准商品，再写人工配置和 +`internal_sku_channels` 人工规则。待分类队列的“去补配置”会携带 +`scope=manual&tab=cost&manualSku=<内部SKU>` 直接打开对应配置。 + ## 五、成本版本接口 路径不变，字段不变： @@ -163,20 +187,34 @@ AND ( "costModel": "affiliate_purchase", "pricingMode": "per_item", "scopeType": "product | rule | shop | provider | global", - "provider": "", "shopId": "", - "canonicalProductId": 3, "canonicalSku": "aff:SKU-1", "canonicalName": "...", - "workProductRuleId": null, "workProductRuleName": "", "workProductRuleKey": "", - "ruleRewardAmountFen": 0, "ruleUnitPriceFen": 0, - "revenueItemCount": 0, "revenueFen": 0, "revenueAvgFen": 0, - "rewardAvgFen": 0, "rewardFen": 0, "amountKind": "unit_price | fixed", + "provider": "", + "shopId": "", + "canonicalProductId": 3, + "canonicalSku": "aff:SKU-1", + "canonicalName": "...", + "workProductRuleId": null, + "workProductRuleName": "", + "workProductRuleKey": "", + "ruleRewardAmountFen": 0, + "ruleUnitPriceFen": 0, + "revenueItemCount": 0, + "revenueFen": 0, + "revenueAvgFen": 0, + "rewardAvgFen": 0, + "rewardFen": 0, + "amountKind": "unit_price | fixed", "isSystemPlaceholder": false, - "amountFen": 1000, "rateBps": 0, - "effectiveFrom": "...", "effectiveTo": null, + "amountFen": 1000, + "rateBps": 0, + "effectiveFrom": "...", + "effectiveTo": null, "source": "manual | upstream_sync | import", "status": "draft | active | retired", "changeReason": "", - "createdByAdminUserId": null, "approvedByAdminUserId": null, - "createdAt": "...", "updatedAt": "..." + "createdByAdminUserId": null, + "approvedByAdminUserId": null, + "createdAt": "...", + "updatedAt": "...", } ``` @@ -213,7 +251,9 @@ AND ( "reason": "cost_missing", "status": "open", "detail": {}, - "createdAt": "...", "resolvedAt": null, "resolvedByAdminUserId": null + "createdAt": "...", + "resolvedAt": null, + "resolvedByAdminUserId": null, } ``` @@ -233,7 +273,7 @@ AND ( "grossRevenueFen": 1219202470, "costAmountFen": 32000, "costMissingCount": 102954, - "grossProfitFen": -1219200470 + "grossProfitFen": -1219200470, } ``` @@ -255,13 +295,13 @@ AND ( "affiliate_dash": 38, "work_order": 707, "manual": 0, - "uncategorized": 0 + "uncategorized": 0, }, "costModelCounts": { "affiliate_purchase": 1, "work_order_reward": 1, - "manual_actual": 1 - } + "manual_actual": 1, + }, } ``` @@ -272,13 +312,13 @@ AND ( 原 `apps/backend/src/services/admin/admin-cost-center-service.ts`（4,248 行）已拆为： -| 新文件 | 行数 | 负责的导出 | -| --- | ---: | --- | -| `services/cost-center/cost-center-shared.ts` | ~800 | 类型、常量、归一化函数、`mapXxx` 映射函数、provider 归一、`costModelScopeSql` | -| `services/cost-center/cost-center-overview-service.ts` | ~150 | 总览统计与选项 | -| `services/cost-center/product-catalog-service.ts` | ~1,000 | 商品与渠道映射的 CRUD、回填、选项 | -| `services/cost-center/template-bootstrap-service.ts` | ~1,380 | 接单模板引导、自动发货商品同步、工单证据回填、模板成本版本同步、`buildTemplateMappingPlan` | -| `services/cost-center/cost-definition-service.ts` | ~1,240 | 成本项 / 成本版本 / 成本异常 / 成本预览 / 成本快照写入 | +| 新文件 | 行数 | 负责的导出 | +| ------------------------------------------------------ | -----: | ------------------------------------------------------------------------------------------ | +| `services/cost-center/cost-center-shared.ts` | ~800 | 类型、常量、归一化函数、`mapXxx` 映射函数、provider 归一、`costModelScopeSql` | +| `services/cost-center/cost-center-overview-service.ts` | ~150 | 总览统计与选项 | +| `services/cost-center/product-catalog-service.ts` | ~1,000 | 商品与渠道映射的 CRUD、回填、选项 | +| `services/cost-center/template-bootstrap-service.ts` | ~1,380 | 接单模板引导、自动发货商品同步、工单证据回填、模板成本版本同步、`buildTemplateMappingPlan` | +| `services/cost-center/cost-definition-service.ts` | ~1,240 | 成本项 / 成本版本 / 成本异常 / 成本预览 / 成本快照写入 | 原文件**已删除**，路由 `apps/backend/src/routes/admin/cost-center.ts` 从新模块导入。 `routes/admin/worker-platform/config.ts` 的模板成本同步也从新模块导入。 @@ -287,19 +327,19 @@ AND ( 原 `apps/frontend/src/pages/admin/AdminCostCenterPage.tsx`（2,887 行）已拆为： -| 新文件 | 内容 | -| --- | --- | -| `pages/admin/cost-center/CostCenterShell.tsx` | 页面骨架、顶部来源切换（全部/自动发货/接单平台/人工）、Tab 定义 | -| `pages/admin/cost-center/shared.ts` | 常量、类型、标签函数 | -| `pages/admin/cost-center/CostCenterContext.ts` | 页面上下文（`useCostCenter`） | -| `pages/admin/cost-center/ProductCatalogPanel.tsx` | 标准商品 Tab | -| `pages/admin/cost-center/ChannelMappingPanel.tsx` | 渠道映射 Tab | -| `pages/admin/cost-center/CostConfigPanel.tsx` | 成本配置 Tab（按来源切换下面三个） | -| `pages/admin/cost-center/AffiliateSkuPanel.tsx` | 自动发货采购价（成本配置内） | -| `pages/admin/cost-center/CostItemPanel.tsx` | 成本项 Tab | -| `pages/admin/cost-center/CostVersionPanel.tsx` | 成本版本 Tab | -| `pages/admin/cost-center/CostExceptionPanel.tsx` | 成本异常 Tab | -| `pages/admin/cost-center/CostPreviewPanel.tsx` | 成本预览 Tab | +| 新文件 | 内容 | +| ------------------------------------------------- | --------------------------------------------------------------- | +| `pages/admin/cost-center/CostCenterShell.tsx` | 页面骨架、顶部来源切换（全部/自动发货/接单平台/人工）、Tab 定义 | +| `pages/admin/cost-center/shared.ts` | 常量、类型、标签函数 | +| `pages/admin/cost-center/CostCenterContext.ts` | 页面上下文（`useCostCenter`） | +| `pages/admin/cost-center/ProductCatalogPanel.tsx` | 标准商品 Tab | +| `pages/admin/cost-center/ChannelMappingPanel.tsx` | 渠道映射 Tab | +| `pages/admin/cost-center/CostConfigPanel.tsx` | 成本配置 Tab（按来源切换下面三个） | +| `pages/admin/cost-center/AffiliateSkuPanel.tsx` | 自动发货采购价（成本配置内） | +| `pages/admin/cost-center/CostItemPanel.tsx` | 成本项 Tab | +| `pages/admin/cost-center/CostVersionPanel.tsx` | 成本版本 Tab | +| `pages/admin/cost-center/CostExceptionPanel.tsx` | 成本异常 Tab | +| `pages/admin/cost-center/CostPreviewPanel.tsx` | 成本预览 Tab | `AdminCostCenterPage.tsx` 只保留 `export default` 转发到 `CostCenterShell`（18 行）。 @@ -322,21 +362,21 @@ export type CostModel = ## 八、总账 / 期间 / 对账接口（2026-10-26） -| 方法 | 路径 | 权限 | 说明 | -| --- | --- | --- | --- | -| GET | `/api/v1/admin/finance/ledger/accounts` | finance.view | 科目表 | -| GET | `/api/v1/admin/finance/ledger/trial-balance?dateFrom&dateTo` | finance.view | 试算平衡 | -| GET | `/api/v1/admin/finance/ledger/entries?dateFrom&dateTo&page&pageSize` | finance.view | 凭证列表（含分录） | -| POST | `/api/v1/admin/finance/ledger/sync` | finance.config | 按日期区间同步销售事实到总账 | -| POST | `/api/v1/admin/finance/ledger/manual-voucher` | finance.config | 手工凭证（借贷必须平衡） | -| GET | `/api/v1/admin/finance/periods` | finance.view | 会计期间列表 | -| POST | `/api/v1/admin/finance/periods/:periodKey/close` | finance.config | 关账（先补凭证） | -| POST | `/api/v1/admin/finance/periods/:periodKey/reopen` | finance.config | 反关账 | -| GET | `/api/v1/admin/finance/reconciliations` | finance.view | 对账批次 | -| POST | `/api/v1/admin/finance/reconciliations/import` | finance.config | 导入平台账单 JSON 并匹配 | -| GET | `/api/v1/admin/finance/reconciliations/:id` | finance.view | 对账明细 | -| POST | `/api/v1/admin/finance/reconciliations/:id/resolve` | finance.config | 标记差异已解决 | -| POST | `/api/v1/admin/kuaishou-industry/orders/:orderId/refunds/approve-and-record` | finance.config | 平台退款（当前仅快手 91） | +| 方法 | 路径 | 权限 | 说明 | +| ---- | ---------------------------------------------------------------------------- | -------------- | ---------------------------- | +| GET | `/api/v1/admin/finance/ledger/accounts` | finance.view | 科目表 | +| GET | `/api/v1/admin/finance/ledger/trial-balance?dateFrom&dateTo` | finance.view | 试算平衡 | +| GET | `/api/v1/admin/finance/ledger/entries?dateFrom&dateTo&page&pageSize` | finance.view | 凭证列表（含分录） | +| POST | `/api/v1/admin/finance/ledger/sync` | finance.config | 按日期区间同步销售事实到总账 | +| POST | `/api/v1/admin/finance/ledger/manual-voucher` | finance.config | 手工凭证（借贷必须平衡） | +| GET | `/api/v1/admin/finance/periods` | finance.view | 会计期间列表 | +| POST | `/api/v1/admin/finance/periods/:periodKey/close` | finance.config | 关账（先补凭证） | +| POST | `/api/v1/admin/finance/periods/:periodKey/reopen` | finance.config | 反关账 | +| GET | `/api/v1/admin/finance/reconciliations` | finance.view | 对账批次 | +| POST | `/api/v1/admin/finance/reconciliations/import` | finance.config | 导入平台账单 JSON 并匹配 | +| GET | `/api/v1/admin/finance/reconciliations/:id` | finance.view | 对账明细 | +| POST | `/api/v1/admin/finance/reconciliations/:id/resolve` | finance.config | 标记差异已解决 | +| POST | `/api/v1/admin/kuaishou-industry/orders/:orderId/refunds/approve-and-record` | finance.config | 平台退款（当前仅快手 91） | 确认履约接口新增代录字段： @@ -344,8 +384,8 @@ export type CostModel = { "orderItemId": 123, "costFen": 100, - "fundAccountId": 45, // 现金路径：管理员/财务指定客服备用金账户 - "creditOwnerAdminUserId": 67 // 积分路径：管理员/财务指定客服账号 + "fundAccountId": 45, // 现金路径：管理员/财务指定客服备用金账户 + "creditOwnerAdminUserId": 67, // 积分路径：管理员/财务指定客服账号 } ``` diff --git a/docs/成本中心与履约模型.md b/docs/成本中心与履约模型.md index a2e9ca62..751ec0a1 100644 --- a/docs/成本中心与履约模型.md +++ b/docs/成本中心与履约模型.md @@ -38,11 +38,11 @@ orders ──┬── order_items ──── fulfillment_channel + fulfillmen 2026-10-27 最终收敛为 3 个领域迁移（合计约 2,177 行）： -| 迁移 | 内容 | 行数 | -| --- | --- | ---: | -| `103_finance_foundation.sql` | 商品目录、渠道映射、成本项/版本/快照/异常、订单项收入与履约方式、销售事实、退款单 | 861 | -| `104_finance_controls.sql` | 人工 SKU/配置、备用金/积分、影子总账、对账/关账、财务控制、L1 钱包硬化 | 1,119 | -| `105_work_order_consignment.sql` | 拼单多次参与、大厅/店铺索引、撤份额注释、寄卖对接客服 | 197 | +| 迁移 | 内容 | 行数 | +| -------------------------------- | --------------------------------------------------------------------------------- | ----: | +| `103_finance_foundation.sql` | 商品目录、渠道映射、成本项/版本/快照/异常、订单项收入与履约方式、销售事实、退款单 | 861 | +| `104_finance_controls.sql` | 人工 SKU/配置、备用金/积分、影子总账、对账/关账、财务控制、L1 钱包硬化 | 1,119 | +| `105_work_order_consignment.sql` | 拼单多次参与、大厅/店铺索引、撤份额注释、寄卖对接客服 | 197 | 原来 103–114 的 12 个补丁文件已删除；生产当前在 102，只需执行 103–105。 @@ -52,42 +52,44 @@ orders ──┬── order_items ──── fulfillment_channel + fulfillmen ### 1.1 字段替换对照 -| 旧字段 | 新字段 | 出现位置 | -| --- | --- | --- | -| `cost_items.carrier_type` | `cost_items.cost_model` | DB / 成本项接口 | -| `cost_items.cost_type` | （并入 `cost_model`） | DB / 成本项接口 | -| `cost_snapshots.carrier_type` | （删除） | DB | -| `cost_exceptions.carrier_type` | （删除） | DB | -| `product_catalog.carrier_type` | （删除，改由 `canonical_sku` 前缀推导） | DB / 商品接口 | -| `sales_daily_facts.carrier_type` | `sales_daily_facts.channel` | DB / 销售事实接口 | -| `work_product_rules.legacy_cost_source` | （删除） | DB | -| `cost_versions.cost_item_carrier_type` | `cost_versions.cost_item_cost_model` | 成本版本接口 | -| `pricing_mode: per_hour / fixed_daily` | （删除，只剩三种） | 成本项接口 | -| `manual_expense_records` / `manual_expense_events` | （删除，人工成本只走确认履约） | DB | +| 旧字段 | 新字段 | 出现位置 | +| -------------------------------------------------- | --------------------------------------- | ----------------- | +| `cost_items.carrier_type` | `cost_items.cost_model` | DB / 成本项接口 | +| `cost_items.cost_type` | （并入 `cost_model`） | DB / 成本项接口 | +| `cost_snapshots.carrier_type` | （删除） | DB | +| `cost_exceptions.carrier_type` | （删除） | DB | +| `product_catalog.carrier_type` | （删除，改由 `canonical_sku` 前缀推导） | DB / 商品接口 | +| `sales_daily_facts.carrier_type` | `sales_daily_facts.channel` | DB / 销售事实接口 | +| `work_product_rules.legacy_cost_source` | （删除） | DB | +| `cost_versions.cost_item_carrier_type` | `cost_versions.cost_item_cost_model` | 成本版本接口 | +| `pricing_mode: per_hour / fixed_daily` | （删除，只剩三种） | 成本项接口 | +| `manual_expense_records` / `manual_expense_events` | （删除，人工成本只走确认履约） | DB | ### 1.2 成本模型映射 -| 旧 `cost_type` | 新 `cost_model` | -| --- | --- | -| `auto_purchase` | `affiliate_purchase` | -| `work_order_reward` | `work_order_reward` | -| `manual_service` | `manual_actual` | -| `platform_fee` | `platform_fee` | -| `payment_fee` | `payment_fee` | -| `after_sales_loss` | `after_sales_loss` | -| `shipping_other` / `other` | `other` | +| 旧 `cost_type` | 新 `cost_model` | +| -------------------------- | -------------------- | +| `auto_purchase` | `affiliate_purchase` | +| `work_order_reward` | `work_order_reward` | +| `manual_service` | `manual_actual` | +| `platform_fee` | `platform_fee` | +| `payment_fee` | `payment_fee` | +| `after_sales_loss` | `after_sales_loss` | +| `shipping_other` / `other` | `other` | ### 1.3 商品来源前缀 -| 前缀 | 来源 | 对应履约方式（仅参考，不作推导依据） | -| --- | --- | --- | -| `aff:` | 自动发货 | `affiliate_dash` | -| `tpl:` | 接单模板 | `work_order` | -| `wo:` | 历史工单证据 | `work_order` | -| `man:` | 人工 | `manual` | -| 其他 | 未分类 | 不得推断 | +| 前缀 | 来源 | 对应履约方式（仅参考，不作推导依据） | +| ------ | ------------ | ------------------------------------ | +| `aff:` | 自动发货 | `affiliate_dash` | +| `tpl:` | 接单模板 | `work_order` | +| `wo:` | 历史工单证据 | `work_order` | +| `man:` | 人工 | `manual` | +| 其他 | 未分类 | 不得推断 | -本地现状：`aff:` 38 个、`tpl:` 662 个、`wo:` 45 个，`man:` 0 个（P1 待建）。 +人工标准商品 `man:<内部 SKU>` 不在商品目录手工创建。运营在「成本配置 → 人工 SKU 配置」 +新增或保存配置时，系统在同一业务流程内创建或复用标准商品，并同步人工渠道规则。 +商品目录中的 `man:` 商品因此是人工配置的派生结果。 --- @@ -188,15 +190,15 @@ normalized_sku_series -- 剥离数量并归一同义字后的名称系列 ### 3.1 成本模型与适用履约方式 -| `cost_model` | 适用履约方式 | 计价方式 | 成本来源 | -| --- | --- | --- | --- | -| `affiliate_purchase` | `affiliate_dash` | `per_item` | 上游 SKU 固定成本版本 | -| `work_order_reward` | `work_order` | `per_order` | 模板规则级版本 / 工单实际报酬 | -| `manual_actual` | `manual` | `per_order` | 订单页逐单录入的实际支出 | -| `platform_fee` | 全部 | `per_order` / `percent_of_revenue` | 未配置 | -| `payment_fee` | 全部 | `per_order` / `percent_of_revenue` | 未配置 | -| `after_sales_loss` | 全部 | `per_order` | 未配置 | -| `other` | 全部 | `per_order` | 未配置 | +| `cost_model` | 适用履约方式 | 计价方式 | 成本来源 | +| -------------------- | ---------------- | ---------------------------------- | ----------------------------- | +| `affiliate_purchase` | `affiliate_dash` | `per_item` | 上游 SKU 固定成本版本 | +| `work_order_reward` | `work_order` | `per_order` | 模板规则级版本 / 工单实际报酬 | +| `manual_actual` | `manual` | `per_order` | 订单页逐单录入的实际支出 | +| `platform_fee` | 全部 | `per_order` / `percent_of_revenue` | 未配置 | +| `payment_fee` | 全部 | `per_order` / `percent_of_revenue` | 未配置 | +| `after_sales_loss` | 全部 | `per_order` | 未配置 | +| `other` | 全部 | `per_order` | 未配置 | 后端判定见 `cost-center-shared.ts` 的 `costModelScopeSql()`；通用模型对所有履约方式生效，专属模型只对对应履约方式生效。 @@ -228,11 +230,11 @@ cost_versions ### 3.3 系统内置成本项 -| 编码 | 成本模型 | 说明 | -| --- | --- | --- | -| `sys_work_order_reward` | `work_order_reward` | 每个可启用的接单模板各一条规则级版本；全局 0 元版本只作"按工单实际结算"的占位 | -| `sys_affiliate_purchase` | `affiliate_purchase` | 上游 SKU 固定成本版本，38 个商品级 | -| `sys_manual_service` | `manual_actual` | 订单页确认履约写入 `actual` 快照；版本为 0 元占位 | +| 编码 | 成本模型 | 说明 | +| ------------------------ | -------------------- | ----------------------------------------------------------------------------- | +| `sys_work_order_reward` | `work_order_reward` | 每个可启用的接单模板各一条规则级版本；全局 0 元版本只作"按工单实际结算"的占位 | +| `sys_affiliate_purchase` | `affiliate_purchase` | 上游 SKU 固定成本版本，38 个商品级 | +| `sys_manual_service` | `manual_actual` | 订单页确认履约写入 `actual` 快照；版本为 0 元占位 | 工单报酬的三种快照： @@ -286,12 +288,12 @@ created_at, resolved_at, resolved_by `order_items.revenue_amount_fen` / `revenue_basis` 在迁移 `103` 里固化： -| `revenue_basis` | 含义 | -| --- | --- | -| `order_total` | 一单一品，订单实付全部归该订单项 | -| `equal_split` | 多订单项按等额拆分，余数给最后一项 | -| `platform_item` | 有平台明细时替换 | -| `manual` / `unknown` | 未定 | +| `revenue_basis` | 含义 | +| -------------------- | ---------------------------------- | +| `order_total` | 一单一品，订单实付全部归该订单项 | +| `equal_split` | 多订单项按等额拆分，余数给最后一项 | +| `platform_item` | 有平台明细时替换 | +| `manual` / `unknown` | 未定 | 本地全量 316,585 项都是 `order_total`（当前一单一品），但模型按"订单项"设计，不把"一单一品"写死。 @@ -328,12 +330,12 @@ computed_at ### 5.2 本地重算结果（2026-10-23） -| 履约方式 | 事实行 | 订单项 | 收入 | 成本 | 缺失成本 | -| --- | ---: | ---: | ---: | ---: | ---: | -| `work_order` | 9,585 | 118,053 | ¥533.57 万 | ¥452.83 万 | 966 | -| `affiliate_dash` | 3,163 | 41,676 | ¥508.97 万 | ¥497.41 万 | 0 | -| `manual` | 1,849 | 102,955 | ¥1,219.20 万 | ¥0.32 万 | 102,954 | -| `legacy_platform` | 201 | 53,901 | ¥389.12 万 | ¥0 | 53,901 | +| 履约方式 | 事实行 | 订单项 | 收入 | 成本 | 缺失成本 | +| ----------------- | -----: | ------: | -----------: | ---------: | -------: | +| `work_order` | 9,585 | 118,053 | ¥533.57 万 | ¥452.83 万 | 966 | +| `affiliate_dash` | 3,163 | 41,676 | ¥508.97 万 | ¥497.41 万 | 0 | +| `manual` | 1,849 | 102,955 | ¥1,219.20 万 | ¥0.32 万 | 102,954 | +| `legacy_platform` | 201 | 53,901 | ¥389.12 万 | ¥0 | 53,901 | --- @@ -396,7 +398,9 @@ fulfillment_decided_at / fulfillment_reason 4. **商品来源和平台 SKU 都不能反推渠道**：判定只认统一 SKU 配置与真实载体。 5. `voucher_state` 只做展示与核销流程，不参与任何成本/履约判断。 6. 多渠道证据同时命中必须先告警人工复核，不能静默取其一。 -7. **旧人工来源清理只归档**：同名内部 SKU 已有其他非兜底主渠道时，旧 `man:` 商品从当前目录归档；历史订单、成本版本、成本快照和事实数据保持不动，人工兜底改指当前主商品。 +7. **人工商品只从人工 SKU 配置创建**：普通“新建标准商品”不再接受 `man:`； + 人工 SKU 配置保存时自动创建或复用 `man:<内部 SKU>`。历史商品清理入口已下线， + 避免运营通过商品目录维护人工履约事实。 --- @@ -404,21 +408,21 @@ fulfillment_decided_at / fulfillment_reason 财务链路已改成六条独立管道，由定时任务驱动，不再有手工同步脚本： -| 管道 | 作用 | 默认间隔 | -| --- | --- | --- | -| `channel_assign` | 规则/证据判定履约渠道 | 60s | -| `carrier_dispatch` | 挂载人工配置、发现缺失载体 | 60s | -| `product_normalize` | 模板/人工配置/前缀直达归一 | 300s | -| `cost_snapshot` | 按渠道解析成本版本写快照 | 300s | -| `sales_facts` | 按渠道重算销售事实（含未分类桶） | 600s | -| `ledger_post` | 事实过账到总账 | 600s | +| 管道 | 作用 | 默认间隔 | +| ------------------- | -------------------------------- | -------- | +| `channel_assign` | 规则/证据判定履约渠道 | 60s | +| `carrier_dispatch` | 挂载人工配置、发现缺失载体 | 60s | +| `product_normalize` | 模板/人工配置/前缀直达归一 | 300s | +| `cost_snapshot` | 按渠道解析成本版本写快照 | 300s | +| `sales_facts` | 按渠道重算销售事实（含未分类桶） | 600s | +| `ledger_post` | 事实过账到总账 | 600s | 运维命令只剩断代与重建： -| 命令 | 作用 | -| --- | --- | +| 命令 | 作用 | +| -------------------------------------------------------------- | ----------------------------- | | `npm run finance:cutover-v2 -- --execute --confirm=2026-10-31` | 断代：归档历史 + 清空派生数据 | -| `npm run finance:rebuild-cutover -- --date-from=2026-10-31` | 断代后重跑管道并生成期初分录 | +| `npm run finance:rebuild-cutover -- --date-from=2026-10-31` | 断代后重跑管道并生成期初分录 | 后台「履约渠道 → 管道状态」可查看每条管道的水位、上次成功时间与错误； 「立即执行」只用于排障补跑，日常无需干预。 @@ -427,11 +431,11 @@ fulfillment_decided_at / fulfillment_reason 生产数据库当前在 **102**。dev 已把原 103–114 收敛为 3 个领域迁移： -| 迁移 | 内容 | -| --- | --- | -| `103_finance_foundation.sql` | 商品目录、成本中心、成本项/版本/快照、销售事实、退款单 | -| `104_finance_controls.sql` | 人工履约、备用金/积分、影子总账、对账/关账、财务控制、L1 钱包硬化 | -| `105_work_order_consignment.sql` | 拼单多次参与、大厅/店铺索引、撤份额注释、寄卖对接客服 | +| 迁移 | 内容 | +| -------------------------------- | ----------------------------------------------------------------- | +| `103_finance_foundation.sql` | 商品目录、成本中心、成本项/版本/快照、销售事实、退款单 | +| `104_finance_controls.sql` | 人工履约、备用金/积分、影子总账、对账/关账、财务控制、L1 钱包硬化 | +| `105_work_order_consignment.sql` | 拼单多次参与、大厅/店铺索引、撤份额注释、寄卖对接客服 | - 生产升级：**102 → 103 → 104 → 105**，只执行 3 个迁移文件。 - 全新库：`001 → 105` 一次跑完。 @@ -461,35 +465,35 @@ npm run revenue:backfill -- --batch-size=2000 --max-batches=100 ## 九、索引与性能 -| 索引 | 用途 | -| --- | --- | -| `idx_order_items_fulfillment_channel (fulfillment_channel, order_id)` | 按渠道筛订单项 | -| `idx_order_items_fulfillment_id (fulfillment_status, id)` | 管道按状态扫增量 | -| `idx_order_items_canonical_product` | 按标准商品查订单项 | -| `idx_order_items_normalized_sku_lookup` | 按归一名称/系列匹配映射 | -| `idx_channel_product_mappings_match_lookup` | 映射查找 | -| `uq_channel_product_mappings_match_key` | 映射唯一键 | -| `idx_cost_versions_lookup / product / rule` | 成本版本解析 | -| `uq_cost_snapshots_active_subject_item` | 每个主体 + 成本项只允许一条有效快照 | -| `idx_cost_exceptions_status_created` | 异常队列列表 | -| `idx_sales_daily_facts_date / shop / product / mode` | 销售事实各维度 | -| `idx_work_orders_rule_cover` | 成本版本页按接单规则聚合 | -| `idx_order_items_revenue_cover` | 收入聚合 | -| `idx_work_categories_name` | 商品目录按分类名 lateral join | -| `idx_cost_exceptions_archivable` | 归档任务扫描「已处理且超期」的异常（部分索引，`status <> 'open'`） | +| 索引 | 用途 | +| --------------------------------------------------------------------- | ------------------------------------------------------------------ | +| `idx_order_items_fulfillment_channel (fulfillment_channel, order_id)` | 按渠道筛订单项 | +| `idx_order_items_fulfillment_id (fulfillment_status, id)` | 管道按状态扫增量 | +| `idx_order_items_canonical_product` | 按标准商品查订单项 | +| `idx_order_items_normalized_sku_lookup` | 按归一名称/系列匹配映射 | +| `idx_channel_product_mappings_match_lookup` | 映射查找 | +| `uq_channel_product_mappings_match_key` | 映射唯一键 | +| `idx_cost_versions_lookup / product / rule` | 成本版本解析 | +| `uq_cost_snapshots_active_subject_item` | 每个主体 + 成本项只允许一条有效快照 | +| `idx_cost_exceptions_status_created` | 异常队列列表 | +| `idx_sales_daily_facts_date / shop / product / mode` | 销售事实各维度 | +| `idx_work_orders_rule_cover` | 成本版本页按接单规则聚合 | +| `idx_order_items_revenue_cover` | 收入聚合 | +| `idx_work_categories_name` | 商品目录按分类名 lateral join | +| `idx_cost_exceptions_archivable` | 归档任务扫描「已处理且超期」的异常（部分索引，`status <> 'open'`） | ### 9.1 成本异常归档（60 天） `cost_exceptions` 只增不减：本地快照 260,253 行（resolved 151,939 / open 108,314）。已处理的行只是审计痕迹，继续留在热表会拖慢按状态+时间的分页，并让唯一索引持续膨胀。 -| 项 | 规则 | -| --- | --- | -| 归档对象 | `status <> 'open'` 且 `COALESCE(resolved_at, created_at)` 超过保留期 | -| open 行 | **永不归档**——它是待办队列，超期也要留在页面上 | -| 保留期 | `COST_EXCEPTION_RETENTION_DAYS`，默认 **60** 天 | -| 落点 | `cost_exceptions_archive`（保留原 id 与时间字段，加 `archived_at`） | -| 执行 | `data-retention` 每日任务；每批 1000 行，`DELETE ... RETURNING` + `INSERT` 同语句，单批原子 | -| 手动 | `npm run cost-exceptions:archive -- --dry-run` / `-- --days=90` | +| 项 | 规则 | +| ---------- | ---------------------------------------------------------------------------------------------- | +| 归档对象 | `status <> 'open'` 且 `COALESCE(resolved_at, created_at)` 超过保留期 | +| open 行 | **永不归档**——它是待办队列，超期也要留在页面上 | +| 保留期 | `COST_EXCEPTION_RETENTION_DAYS`，默认 **60** 天 | +| 落点 | `cost_exceptions_archive`（保留原 id 与时间字段，加 `archived_at`） | +| 执行 | `data-retention` 每日任务；每批 1000 行，`DELETE ... RETURNING` + `INSERT` 同语句，单批原子 | +| 手动 | `npm run cost-exceptions:archive -- --dry-run` / `-- --days=90` | | 一次性清理 | `npm run cost-exceptions:archive -- --days=0`（不按时间过滤，归档全部已处理行；open 仍不归档） | 归档不删除审计痕迹，但热表查询与页面上不会再出现这些历史行；需要追溯时查归档表。 From e6b3835c9f0a87dc3d9d2262ec7f499011437152 Mon Sep 17 00:00:00 2001 From: yml2213 Date: Fri, 6 Nov 2026 16:47:45 +0800 Subject: [PATCH 4/7] =?UTF-8?q?feat(cost-center):=20=E6=94=B6=E6=95=9B?= =?UTF-8?q?=E7=AC=AC=E4=B8=89=E6=96=B9=E5=8D=A1=E5=88=B8=E5=95=86=E5=93=81?= =?UTF-8?q?=E4=B8=8E=E6=88=90=E6=9C=AC=E9=93=BE=E8=B7=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...43_repair_third_party_voucher_products.sql | 173 ++++++++++ .../src/routes/admin/cost-center-catalog.ts | 19 +- .../services/cost-center/cost-center.test.ts | 13 + .../cost-center/product-catalog-service.ts | 11 +- .../product-normalize-service.test.ts | 13 + .../cost-center/product-normalize-service.ts | 35 +- .../voucher-product-service.test.ts | 35 ++ .../cost-center/voucher-product-service.ts | 321 ++++++++++++++++++ .../fulfillment/channel-assign-service.ts | 57 ---- .../admin/cost-center/ProductCatalogPanel.tsx | 12 + .../admin/cost-center/VoucherSkuPanel.tsx | 117 +++++-- .../src/services/admin/cost-center.ts | 19 +- .../tests/voucher-sku-delete-ui.test.ts | 27 ++ docs/成本中心API契约.md | 21 ++ 14 files changed, 763 insertions(+), 110 deletions(-) create mode 100644 apps/backend/src/db/migrations/143_repair_third_party_voucher_products.sql create mode 100644 apps/backend/src/services/cost-center/voucher-product-service.test.ts create mode 100644 apps/backend/src/services/cost-center/voucher-product-service.ts diff --git a/apps/backend/src/db/migrations/143_repair_third_party_voucher_products.sql b/apps/backend/src/db/migrations/143_repair_third_party_voucher_products.sql new file mode 100644 index 00000000..cab4cf70 --- /dev/null +++ b/apps/backend/src/db/migrations/143_repair_third_party_voucher_products.sql @@ -0,0 +1,173 @@ +-- 143_repair_third_party_voucher_products.sql +-- +-- 第三方卡券订单项必须关联 tpv:<内部 SKU>。历史商品归一在缺少 tpv 商品时 +-- 会回退到同名 man 商品，导致卡券订单使用人工商品维度而无法生成卡券采购成本。 +-- 本迁移只修正商品归属、渠道规则和能力，不删除任何商品、订单或历史快照。 +-- 部署后由 cost_snapshot / sales_facts 管道补建成本快照并重算受影响日期。 + +DROP TABLE IF EXISTS pg_temp.tmp_repair_voucher_items; +CREATE TEMP TABLE tmp_repair_voucher_items ON COMMIT DROP AS +SELECT + oi.id AS order_item_id, + oi.order_id, + resolve_internal_sku(oi.manual_sku_key, oi.sku_name, oi.sku_code) AS internal_sku, + (COALESCE(o.paid_at, o.created_at) AT TIME ZONE 'Asia/Shanghai')::date::text AS basis_date +FROM order_items oi +JOIN orders o ON o.id = oi.order_id +LEFT JOIN product_catalog current_product ON current_product.id = oi.canonical_product_id +WHERE oi.fulfillment_channel = 'third_party_voucher' + AND BTRIM(resolve_internal_sku(oi.manual_sku_key, oi.sku_name, oi.sku_code)) <> '' + AND char_length( + 'tpv:' || resolve_internal_sku(oi.manual_sku_key, oi.sku_name, oi.sku_code) + ) <= 64 + AND ( + current_product.id IS NULL + OR current_product.canonical_sku IS DISTINCT FROM + 'tpv:' || resolve_internal_sku(oi.manual_sku_key, oi.sku_name, oi.sku_code) + ); + +CREATE UNIQUE INDEX ON tmp_repair_voucher_items (order_item_id); + +INSERT INTO product_catalog ( + canonical_sku, canonical_name, category, unit_name, status, + attributes_json, created_at, updated_at +) +SELECT DISTINCT + 'tpv:' || item.internal_sku, + item.internal_sku, + '卡券', + '张', + 'active', + '{"source":"third_party_voucher","auto_created":true,"repaired":true}'::jsonb, + NOW(), + NOW() +FROM tmp_repair_voucher_items item +ON CONFLICT (canonical_sku) DO UPDATE SET + status = 'active', + canonical_name = CASE + WHEN BTRIM(product_catalog.canonical_name) = '' THEN EXCLUDED.canonical_name + ELSE product_catalog.canonical_name + END, + attributes_json = product_catalog.attributes_json || EXCLUDED.attributes_json, + updated_at = EXCLUDED.updated_at; + +UPDATE order_items oi +SET canonical_product_id = product.id, + updated_at = NOW() +FROM tmp_repair_voucher_items item +JOIN product_catalog product + ON product.canonical_sku = 'tpv:' || item.internal_sku + AND product.status = 'active' +WHERE oi.id = item.order_item_id; + +UPDATE cost_snapshots snapshot +SET canonical_product_id = product.id +FROM tmp_repair_voucher_items item +JOIN product_catalog product + ON product.canonical_sku = 'tpv:' || item.internal_sku +WHERE snapshot.order_item_id = item.order_item_id + AND snapshot.superseded_at IS NULL + AND snapshot.reversed_at IS NULL; + +INSERT INTO product_channel_capabilities ( + product_id, channel, priority, is_fallback, enabled, source, created_at, updated_at +) +SELECT DISTINCT + product.id, + 'third_party_voucher', + 10, + FALSE, + TRUE, + 'voucher', + NOW(), + NOW() +FROM tmp_repair_voucher_items item +JOIN product_catalog product + ON product.canonical_sku = 'tpv:' || item.internal_sku +ON CONFLICT (product_id, channel) DO UPDATE SET + priority = 10, + is_fallback = FALSE, + enabled = TRUE, + source = 'voucher', + updated_at = EXCLUDED.updated_at; + +-- 卡券没有外部履约载体，规则命中即完成渠道判定；同 SKU 其他能力保留为兜底。 +UPDATE internal_sku_channels channel +SET is_fallback = TRUE, + priority = GREATEST(channel.priority, 90), + updated_at = NOW() +FROM ( + SELECT DISTINCT internal_sku + FROM tmp_repair_voucher_items +) repaired +WHERE canonicalize_internal_sku(channel.internal_sku) = repaired.internal_sku + AND channel.channel <> 'third_party_voucher' + AND channel.enabled = TRUE + AND channel.is_fallback = FALSE; + +INSERT INTO internal_sku_channels ( + internal_sku, channel, priority, is_fallback, enabled, + canonical_product_id, config_json, source, created_at, updated_at +) +SELECT DISTINCT + item.internal_sku, + 'third_party_voucher', + 10, + FALSE, + TRUE, + product.id, + jsonb_build_object('voucherSku', item.internal_sku, 'repaired', TRUE), + 'voucher', + NOW(), + NOW() +FROM tmp_repair_voucher_items item +JOIN product_catalog product + ON product.canonical_sku = 'tpv:' || item.internal_sku +ON CONFLICT (internal_sku, channel) DO UPDATE SET + priority = 10, + is_fallback = FALSE, + enabled = TRUE, + canonical_product_id = EXCLUDED.canonical_product_id, + config_json = internal_sku_channels.config_json || EXCLUDED.config_json, + source = EXCLUDED.source, + updated_at = EXCLUDED.updated_at; + +-- 修复商品归属后，商品缺失和旧成本缺失异常由 cost_snapshot 管道重新计算并自动收口。 +WITH removed_links AS ( + DELETE FROM cost_exception_items + WHERE order_item_id IN ( + SELECT order_item_id FROM tmp_repair_voucher_items + ) + RETURNING exception_id +), +affected_heads AS ( + SELECT DISTINCT exception_id FROM removed_links +) +UPDATE cost_exceptions exception +SET status = 'resolved', + resolved_at = NOW(), + item_count = 0, + last_seen_at = NOW() +WHERE exception.id IN (SELECT exception_id FROM affected_heads) + AND NOT EXISTS ( + SELECT 1 + FROM cost_exception_items item + WHERE item.exception_id = exception.id + ); + +UPDATE cost_exceptions exception +SET status = 'resolved', + resolved_at = NOW(), + item_count = 0, + last_seen_at = NOW() +WHERE exception.order_item_id IN ( + SELECT order_item_id FROM tmp_repair_voucher_items + ) + AND NOT EXISTS ( + SELECT 1 + FROM cost_exception_items item + WHERE item.exception_id = exception.id + ); + +COMMENT ON COLUMN product_catalog.attributes_json IS + '标准商品扩展信息；第三方卡券修复记录 repaired=true，商品归属以 tpv:<内部 SKU> 为唯一口径'; diff --git a/apps/backend/src/routes/admin/cost-center-catalog.ts b/apps/backend/src/routes/admin/cost-center-catalog.ts index e9fe103f..4a38af96 100644 --- a/apps/backend/src/routes/admin/cost-center-catalog.ts +++ b/apps/backend/src/routes/admin/cost-center-catalog.ts @@ -6,8 +6,6 @@ */ import { Router } from 'express' -import { ensureVoucherChannelRules } from '../../services/fulfillment/channel-assign-service.js' - import { backfillAdminNormalizedQuantities, backfillAdminProductMappings, @@ -25,6 +23,7 @@ import { updateAdminChannelMapping, updateAdminProduct, } from '../../services/cost-center/product-catalog-service.js' +import { upsertAdminVoucherProduct } from '../../services/cost-center/voucher-product-service.js' import { importAdminAffiliateDashPricesBaseline, setAdminAffiliateProductPrice, @@ -368,16 +367,16 @@ router.post( ) router.post( - '/cost-center/voucher-products/ensure-rules', + '/cost-center/voucher-products', requireAdminPermission('finance.config'), - createJsonHandler(() => ensureVoucherChannelRules(), { - successMessage: '卡券渠道规则已补齐', - errorMessage: '补齐卡券渠道规则失败', - scope: '[admin/cost-center/voucher-products/ensure-rules]', + createJsonHandler((req) => upsertAdminVoucherProduct(bodyOf(req), sessionOf(req)), { + successMessage: '卡券 SKU 已保存', + errorMessage: '保存卡券 SKU 失败', + scope: '[admin/cost-center/voucher-products]', audit: (_req, data) => ({ - action: 'voucher_internal_channels_ensured', - targetType: 'internal_sku_channels', - targetId: '', + action: 'voucher_product_upserted', + targetType: 'product_catalog', + targetId: String((data as { product?: { id?: number } })?.product?.id || ''), data: data as Record, }), }), diff --git a/apps/backend/src/services/cost-center/cost-center.test.ts b/apps/backend/src/services/cost-center/cost-center.test.ts index 78f414b3..c7039c29 100644 --- a/apps/backend/src/services/cost-center/cost-center.test.ts +++ b/apps/backend/src/services/cost-center/cost-center.test.ts @@ -347,3 +347,16 @@ test('人工标准商品禁止绕过人工 SKU 配置手工创建', async () => /人工 SKU 配置自动创建/, ) }) + +test('第三方卡券商品禁止绕过卡券 SKU 配置手工创建', async () => { + await assert.rejects( + createAdminProduct( + { + canonicalSku: 'tpv:11月改名卡', + canonicalName: '11月改名卡', + }, + {} as never, + ), + /卡券 SKU 配置自动创建/, + ) +}) diff --git a/apps/backend/src/services/cost-center/product-catalog-service.ts b/apps/backend/src/services/cost-center/product-catalog-service.ts index ba75b9a8..e89a2453 100644 --- a/apps/backend/src/services/cost-center/product-catalog-service.ts +++ b/apps/backend/src/services/cost-center/product-catalog-service.ts @@ -17,7 +17,6 @@ import { normalizeMatchText, normalizeSkuSeriesEquivalence } from '../product-ma import { resolveSkuNameQuantity } from '../product-match/pricing.js' import { setAdminAffiliateProductPrice } from './affiliate-product-service.js' import { resolvePriceEffectiveFrom } from './cost-center-normalizers.js' -import { ensureVoucherRuleForSku } from '../fulfillment/channel-assign-service.js' import { syncCostSnapshotsForItems } from './cost-snapshot-service.js' import { attachFulfillmentConfigurations } from '../fulfillment/fulfillment-state-service.js' import { @@ -325,6 +324,12 @@ export async function createAdminProduct(payload: JsonObject, _session: AdminSes errorCode: 'cost_manual_product_managed_by_config', }) } + if (canonicalSku.startsWith('tpv:')) { + throw createHttpError('卡券商品由第三方卡券 SKU 配置自动创建，请从卡券配置入口新增', { + statusCode: 409, + errorCode: 'cost_voucher_product_managed_by_config', + }) + } if (!/^[A-Za-z0-9._:-]+$/.test(canonicalSku)) { throw createHttpError('标准 SKU 只能包含字母、数字、点、下划线、冒号和短横线', { statusCode: 400, @@ -361,10 +366,6 @@ export async function createAdminProduct(payload: JsonObject, _session: AdminSes errorCode: 'cost_product_sku_exists', }) } - // 卡券没有载体证据，创建商品时顺手把渠道规则补上，避免新 SKU 停在待分类。 - if (canonicalSku.startsWith('tpv:')) { - await ensureVoucherRuleForSku(canonicalSku.slice(4)) - } return { product: mapProduct(inserted) } } diff --git a/apps/backend/src/services/cost-center/product-normalize-service.test.ts b/apps/backend/src/services/cost-center/product-normalize-service.test.ts index 5463dacf..0ab25723 100644 --- a/apps/backend/src/services/cost-center/product-normalize-service.test.ts +++ b/apps/backend/src/services/cost-center/product-normalize-service.test.ts @@ -144,6 +144,19 @@ test('商品归一：第三方卡券按 tpv:SKU 直接命中', () => { ) }) +test('商品归一：第三方卡券缺少 tpv 商品时不能串到同名人工商品', () => { + assert.equal( + resolveProductId( + item({ + fulfillment_channel: 'third_party_voucher', + internal_sku: '套装-测试', + }), + index, + ), + null, + ) +}) + test('商品归一：中文内部 SKU 命中标准商品，不依赖平台 SKU', () => { assert.equal( resolveProductId( diff --git a/apps/backend/src/services/cost-center/product-normalize-service.ts b/apps/backend/src/services/cost-center/product-normalize-service.ts index d81a6480..552bb87c 100644 --- a/apps/backend/src/services/cost-center/product-normalize-service.ts +++ b/apps/backend/src/services/cost-center/product-normalize-service.ts @@ -191,7 +191,7 @@ async function ensureVoucherProductForItem(item: ItemRow): Promise。 if (item.fulfillment_channel === 'third_party_voucher' && internalSku) { const voucher = index.voucherSkus.get(internalSku) - if (voucher) return voucher + return voucher || null + } + if (item.fulfillment_channel === 'third_party_voucher') { + return null } // 中文内部 SKU 是标准商品键；平台 SKU 映射只作为历史数据兜底。 @@ -329,8 +332,18 @@ export async function normalizeOrderItemProducts( LEFT JOIN work_orders wo ON wo.order_item_id = oi.id AND wo.status <> 'cancelled' LEFT JOIN work_product_rules wpr ON wpr.id = wo.product_rule_id LEFT JOIN manual_fulfillment_configs cfg ON cfg.id = oi.fulfillment_config_id + LEFT JOIN product_catalog current_product ON current_product.id = oi.canonical_product_id WHERE oi.fulfillment_status = 'assigned' - AND oi.canonical_product_id IS NULL + AND ( + oi.canonical_product_id IS NULL + OR ( + oi.fulfillment_channel = 'third_party_voucher' + AND ( + current_product.id IS NULL + OR current_product.canonical_sku NOT LIKE 'tpv:%' + ) + ) + ) AND oi.id > $1 ORDER BY oi.id LIMIT $2 @@ -375,7 +388,7 @@ export async function normalizeOrderItemProducts( canonicalProductId: row.productId, })), expected: { status: 'assigned' }, - onlyWhenCanonicalProductNull: true, + onlyWhenCanonicalProductDifferent: true, }) await resolveExceptionsForItems(attached.map((row) => Number(row.id))) } @@ -481,8 +494,18 @@ export async function normalizeProductsForItems(itemIds: number[]): Promise<{ LEFT JOIN work_orders wo ON wo.order_item_id = oi.id AND wo.status <> 'cancelled' LEFT JOIN work_product_rules wpr ON wpr.id = wo.product_rule_id LEFT JOIN manual_fulfillment_configs cfg ON cfg.id = oi.fulfillment_config_id + LEFT JOIN product_catalog current_product ON current_product.id = oi.canonical_product_id WHERE oi.fulfillment_status = 'assigned' - AND oi.canonical_product_id IS NULL + AND ( + oi.canonical_product_id IS NULL + OR ( + oi.fulfillment_channel = 'third_party_voucher' + AND ( + current_product.id IS NULL + OR current_product.canonical_sku NOT LIKE 'tpv:%' + ) + ) + ) AND oi.id = ANY($1::bigint[]) `, [ids], @@ -513,7 +536,7 @@ export async function normalizeProductsForItems(itemIds: number[]): Promise<{ canonicalProductId: row.productId, })), expected: { status: 'assigned' }, - onlyWhenCanonicalProductNull: true, + onlyWhenCanonicalProductDifferent: true, }) await resolveExceptionsForItems(attached.map((row) => Number(row.id))) return { matched: attached.length, unmatched } diff --git a/apps/backend/src/services/cost-center/voucher-product-service.test.ts b/apps/backend/src/services/cost-center/voucher-product-service.test.ts new file mode 100644 index 00000000..03e01f07 --- /dev/null +++ b/apps/backend/src/services/cost-center/voucher-product-service.test.ts @@ -0,0 +1,35 @@ +import assert from 'node:assert/strict' +import { readFile } from 'node:fs/promises' +import test from 'node:test' + +test('卡券 SKU 一个入口完成商品、规则、成本版本和订单回填', async () => { + const service = await readFile(new URL('./voucher-product-service.ts', import.meta.url), 'utf8') + + assert.ok(service.includes('withTransaction(')) + assert.ok(service.includes("channel: 'third_party_voucher'")) + assert.ok(service.includes('sys_third_party_voucher_cost')) + assert.ok(service.includes('UPDATE order_items oi')) + assert.ok(service.includes('syncCostSnapshotsForItems')) + assert.ok(service.includes('refreshFactsForDates')) + assert.ok(service.includes("resolveExceptionsForItemsByReason(result.itemIds, 'cost_missing')")) +}) + +test('第三方卡券修复迁移和归一逻辑都禁止跨来源商品', async () => { + const [migration, normalizer, route] = await Promise.all([ + readFile( + new URL('../../db/migrations/143_repair_third_party_voucher_products.sql', import.meta.url), + 'utf8', + ), + readFile(new URL('./product-normalize-service.ts', import.meta.url), 'utf8'), + readFile(new URL('../../routes/admin/cost-center-catalog.ts', import.meta.url), 'utf8'), + ]) + + assert.ok(migration.includes('tmp_repair_voucher_items')) + assert.ok(migration.includes('current_product.canonical_sku IS DISTINCT FROM')) + assert.ok(migration.includes("product.canonical_sku = 'tpv:' || item.internal_sku")) + assert.ok(migration.includes("channel.channel <> 'third_party_voucher'")) + assert.ok(normalizer.includes('return voucher || null')) + assert.ok(normalizer.includes('onlyWhenCanonicalProductDifferent: true')) + assert.ok(!route.includes('/voucher-products/ensure-rules')) + assert.ok(route.includes("'/cost-center/voucher-products'")) +}) diff --git a/apps/backend/src/services/cost-center/voucher-product-service.ts b/apps/backend/src/services/cost-center/voucher-product-service.ts new file mode 100644 index 00000000..66fd82da --- /dev/null +++ b/apps/backend/src/services/cost-center/voucher-product-service.ts @@ -0,0 +1,321 @@ +import { query, withTransaction } from '../../db/client.js' +import type { JsonObject } from '../../types/json.js' +import { createHttpError } from '../../utils/http.js' +import { nowIso } from '../../utils/time.js' +import type { AdminSession } from '../admin/admin-auth-service.js' +import { orderItemBasisDates, refreshFactsForDates } from '../finance/refresh-facts.js' +import { upsertInternalSkuChannelWithClient } from '../fulfillment/internal-sku-channel-service.js' +import { canonicalizeInternalSku, containsCjk } from '../fulfillment/internal-sku-resolver.js' +import { resolvePriceEffectiveFrom } from './cost-center-normalizers.js' +import { + resolveExceptionsForItemsByReason, + resolveOrphanCostExceptions, +} from './cost-exception-service.js' +import { mapProduct, type ProductRow } from './cost-center-shared.js' +import { syncCostSnapshotsForItems } from './cost-snapshot-service.js' + +type VoucherProductItemRow = { + order_item_id: number + basis_date: string +} + +/** + * 新增或更新三方卡券 SKU。 + * + * 一个入口同时保证 tpv 商品、卡券主渠道规则、采购成本版本和订单商品关联， + * 避免运营跨页面手工建商品后再补规则。 + */ +export async function upsertAdminVoucherProduct(payload: JsonObject, session: AdminSession) { + const skuKey = canonicalizeInternalSku( + payload.skuKey ?? payload.sku_key ?? payload.internalSku ?? payload.internal_sku, + ) + if (!skuKey || !containsCjk(skuKey)) { + throw createHttpError('卡券内部 SKU 必须包含中文', { + statusCode: 400, + errorCode: 'voucher_product_sku_required', + }) + } + + const canonicalSku = `tpv:${skuKey}` + if (canonicalSku.length > 64) { + throw createHttpError('内部 SKU 过长，无法生成卡券商品编码', { + statusCode: 400, + errorCode: 'voucher_product_sku_too_long', + }) + } + + const amountFen = Number(payload.amountFen ?? payload.amount_fen) + if (!Number.isFinite(amountFen) || amountFen <= 0 || !Number.isInteger(amountFen)) { + throw createHttpError('卡券采购价必须是大于 0 的整数分', { + statusCode: 400, + errorCode: 'voucher_product_amount_invalid', + }) + } + + const now = nowIso() + const requestedEffectiveFrom = payload.effectiveFrom ?? payload.effective_from + const initialEffectiveFrom = resolvePriceEffectiveFrom(payload) + const result = await withTransaction(async (client) => { + const productResult = await client.query( + ` + INSERT INTO product_catalog ( + canonical_sku, canonical_name, category, unit_name, status, + attributes_json, created_at, updated_at + ) VALUES ( + $1, $2, '卡券', '张', 'active', + $3::jsonb, $4, $4 + ) + ON CONFLICT (canonical_sku) DO UPDATE SET + status = 'active', + canonical_name = EXCLUDED.canonical_name, + attributes_json = product_catalog.attributes_json || EXCLUDED.attributes_json, + updated_at = EXCLUDED.updated_at + RETURNING * + `, + [ + canonicalSku, + skuKey, + JSON.stringify({ + source: 'third_party_voucher', + auto_created: true, + managed_by_voucher_config: true, + }), + now, + ], + ) + const product = productResult.rows[0] + const productId = Number(product?.id || 0) + if (!product || !productId) { + throw createHttpError('卡券标准商品保存失败', { statusCode: 500 }) + } + + await client.query( + ` + INSERT INTO product_channel_capabilities ( + product_id, channel, priority, is_fallback, enabled, source, created_at, updated_at + ) VALUES ($1, 'third_party_voucher', 10, FALSE, TRUE, 'voucher', $2, $2) + ON CONFLICT (product_id, channel) DO UPDATE SET + priority = 10, + is_fallback = FALSE, + enabled = TRUE, + source = 'voucher', + updated_at = EXCLUDED.updated_at + `, + [productId, now], + ) + + await upsertInternalSkuChannelWithClient(client, { + internalSku: skuKey, + channel: 'third_party_voucher', + priority: 10, + isFallback: false, + enabled: true, + canonicalProductId: productId, + configJson: { voucherSku: skuKey }, + source: 'voucher', + note: String(payload.note || '').slice(0, 300), + adminUserId: session.userId, + replacePriority: true, + }) + + const repairedItems = await client.query( + ` + UPDATE order_items oi + SET canonical_product_id = $2, + updated_at = $3 + FROM orders o + WHERE o.id = oi.order_id + AND oi.fulfillment_channel = 'third_party_voucher' + AND resolve_internal_sku(oi.manual_sku_key, oi.sku_name, oi.sku_code) = $1 + AND oi.canonical_product_id IS DISTINCT FROM $2 + RETURNING + oi.id AS order_item_id, + (COALESCE(o.paid_at, o.created_at) AT TIME ZONE 'Asia/Shanghai')::date::text + AS basis_date + `, + [skuKey, productId, now], + ) + const itemIds = repairedItems.rows.map((row) => Number(row.order_item_id)) + if (itemIds.length > 0) { + await client.query( + `UPDATE cost_snapshots + SET canonical_product_id = $2 + WHERE order_item_id = ANY($1::bigint[]) + AND superseded_at IS NULL AND reversed_at IS NULL`, + [itemIds, productId], + ) + } + + const costItemResult = await client.query<{ id: number }>( + `SELECT id FROM cost_items + WHERE code = 'sys_third_party_voucher_cost' AND status = 'active' + LIMIT 1`, + ) + const costItemId = Number(costItemResult.rows[0]?.id || 0) + if (!costItemId) { + throw createHttpError('未找到第三方卡券采购成本项', { + statusCode: 500, + errorCode: 'voucher_cost_item_missing', + }) + } + + let effectiveFrom = initialEffectiveFrom + if (!requestedEffectiveFrom && repairedItems.rows.length > 0) { + const missingDates = await client.query<{ basis_date: string }>( + ` + SELECT MIN( + (COALESCE(o.paid_at, o.created_at) AT TIME ZONE 'Asia/Shanghai')::date + )::text AS basis_date + FROM order_items oi + JOIN orders o ON o.id = oi.order_id + WHERE oi.id = ANY($1::bigint[]) + AND NOT EXISTS ( + SELECT 1 FROM cost_snapshots cs + WHERE cs.order_item_id = oi.id + AND cs.cost_item_id = $2 + AND cs.superseded_at IS NULL AND cs.reversed_at IS NULL + ) + `, + [itemIds, costItemId], + ) + const earliestDate = String(missingDates.rows[0]?.basis_date || '').trim() + if (earliestDate) effectiveFrom = `${earliestDate}T00:00:00+08:00` + } + + const existingResult = await client.query<{ + id: number + amount_fen: number + effective_from: string + }>( + `SELECT id, amount_fen, effective_from + FROM cost_versions + WHERE cost_item_id = $1 + AND canonical_product_id = $2 + AND status = 'active' + ORDER BY effective_from DESC, id DESC + LIMIT 1`, + [costItemId, productId], + ) + const existing = existingResult.rows[0] + const targetTime = Date.parse(effectiveFrom) + let costVersionId = Number(existing?.id || 0) + + if (!existing || targetTime < Date.parse(existing.effective_from)) { + if (existing) { + await client.query( + `UPDATE cost_versions + SET status = 'retired', updated_at = $1 + WHERE id = $2`, + [now, existing.id], + ) + } + const inserted = await client.query<{ id: number }>( + `INSERT INTO cost_versions ( + cost_item_id, scope_type, provider, shop_id, canonical_product_id, + work_product_rule_id, amount_fen, rate_bps, effective_from, effective_to, + source, status, change_reason, created_by_admin_user_id, + approved_by_admin_user_id, created_at, updated_at + ) VALUES ( + $1, 'product', '', '', $2, + NULL, $3, 0, $4, NULL, + 'manual', 'active', $5, $6, + $6, $7, $7 + ) + RETURNING id`, + [ + costItemId, + productId, + amountFen, + effectiveFrom, + String(payload.changeReason || '第三方卡券 SKU 新增或采购价调整'), + session.userId, + now, + ], + ) + costVersionId = Number(inserted.rows[0]?.id || 0) + } else if (targetTime === Date.parse(existing.effective_from)) { + await client.query( + `UPDATE cost_versions + SET amount_fen = $1, + change_reason = $2, + updated_at = $3 + WHERE id = $4`, + [ + amountFen, + String(payload.changeReason || '第三方卡券 SKU 新增或采购价调整'), + now, + existing.id, + ], + ) + } else { + await client.query( + `UPDATE cost_versions + SET status = 'retired', effective_to = $1, updated_at = $2 + WHERE id = $3`, + [effectiveFrom, now, existing.id], + ) + const inserted = await client.query<{ id: number }>( + `INSERT INTO cost_versions ( + cost_item_id, scope_type, provider, shop_id, canonical_product_id, + work_product_rule_id, amount_fen, rate_bps, effective_from, effective_to, + source, status, change_reason, created_by_admin_user_id, + approved_by_admin_user_id, created_at, updated_at + ) VALUES ( + $1, 'product', '', '', $2, + NULL, $3, 0, $4, NULL, + 'manual', 'active', $5, $6, + $6, $7, $7 + ) + RETURNING id`, + [ + costItemId, + productId, + amountFen, + effectiveFrom, + String(payload.changeReason || '第三方卡券 SKU 新增或采购价调整'), + session.userId, + now, + ], + ) + costVersionId = Number(inserted.rows[0]?.id || 0) + } + + if (!costVersionId) { + throw createHttpError('卡券采购成本版本保存失败', { statusCode: 500 }) + } + + return { + product: mapProduct(product), + itemIds, + dates: [...new Set(repairedItems.rows.map((row) => row.basis_date).filter(Boolean))], + costVersionId, + effectiveFrom, + amountFen, + } + }) + + let snapshotResult = { created: 0, superseded: 0, missing: 0, affectedDates: [] as string[] } + if (result.itemIds.length > 0) { + snapshotResult = await syncCostSnapshotsForItems(result.itemIds).catch(() => snapshotResult) + await resolveExceptionsForItemsByReason(result.itemIds, 'product_mapping_missing').catch( + () => undefined, + ) + await resolveExceptionsForItemsByReason(result.itemIds, 'cost_missing').catch(() => undefined) + } + const affectedDates = [ + ...new Set([ + ...result.dates, + ...snapshotResult.affectedDates, + ...(await orderItemBasisDates(result.itemIds).catch(() => [])), + ]), + ] + await refreshFactsForDates(affectedDates).catch(() => undefined) + await resolveOrphanCostExceptions().catch(() => undefined) + + return { + ...result, + linkedItemCount: result.itemIds.length, + snapshotCreatedCount: snapshotResult.created, + refreshedDays: affectedDates.length, + } +} diff --git a/apps/backend/src/services/fulfillment/channel-assign-service.ts b/apps/backend/src/services/fulfillment/channel-assign-service.ts index 704a549a..97533ad0 100644 --- a/apps/backend/src/services/fulfillment/channel-assign-service.ts +++ b/apps/backend/src/services/fulfillment/channel-assign-service.ts @@ -2388,60 +2388,3 @@ export async function ensureVoucherRuleForSku(skuCode: string): Promise }) return true } - -/** - * 为卡券商品（tpv: 前缀）批量补渠道规则。 - * - * 卡券没有履约载体证据，只能靠规则判定；商品目录建好后一次补齐， - * 避免运营按 SKU 逐条点「指定渠道」。 - */ -export async function ensureVoucherChannelRules(): Promise<{ - created: number - productCount: number -}> { - await query( - `UPDATE internal_sku_channels channel - SET is_fallback = TRUE, - priority = GREATEST(priority, 90), - updated_at = NOW() - FROM product_catalog product - WHERE product.status = 'active' - AND product.canonical_sku LIKE 'tpv:%' - AND canonicalize_internal_sku(channel.internal_sku) = - canonicalize_internal_sku(substring(product.canonical_sku from 5)) - AND channel.channel <> 'third_party_voucher' - AND channel.enabled = TRUE - AND channel.is_fallback = FALSE`, - ) - const created = await query<{ id: number }>( - ` - INSERT INTO internal_sku_channels ( - internal_sku, channel, priority, is_fallback, enabled, - canonical_product_id, config_json, source, created_at, updated_at - ) - SELECT - canonicalize_internal_sku(substring(p.canonical_sku from 5)), - 'third_party_voucher', 10, FALSE, TRUE, - p.id, jsonb_build_object('voucherSku', substring(p.canonical_sku from 5)), - 'voucher', NOW(), NOW() - FROM product_catalog p - WHERE p.status = 'active' - AND p.canonical_sku LIKE 'tpv:%' - AND canonicalize_internal_sku(substring(p.canonical_sku from 5)) <> '' - ON CONFLICT (internal_sku, channel) DO UPDATE SET - priority = 10, - is_fallback = FALSE, - enabled = TRUE, - canonical_product_id = EXCLUDED.canonical_product_id, - config_json = internal_sku_channels.config_json || EXCLUDED.config_json, - source = EXCLUDED.source, - updated_at = NOW() - RETURNING id - `, - ) - const total = await query<{ count: number }>( - `SELECT COUNT(*)::int AS count FROM product_catalog - WHERE status = 'active' AND canonical_sku LIKE 'tpv:%'`, - ) - return { created: created.rowCount || 0, productCount: Number(total.rows[0]?.count || 0) } -} diff --git a/apps/frontend/src/pages/admin/cost-center/ProductCatalogPanel.tsx b/apps/frontend/src/pages/admin/cost-center/ProductCatalogPanel.tsx index 64384d67..ee9af673 100644 --- a/apps/frontend/src/pages/admin/cost-center/ProductCatalogPanel.tsx +++ b/apps/frontend/src/pages/admin/cost-center/ProductCatalogPanel.tsx @@ -737,6 +737,18 @@ export function ProductCatalogPanel() { > 新增人工 SKU + ) : productSourceFilter === 'third_party_voucher' ? ( + ) : ( + {canConfig ? ( + + ) : null} @@ -184,8 +201,8 @@ export default function VoucherSkuPanel() { } > - 卡券渠道只统计：命中规则后不创建任务、不发领取页，只记收入与采购成本。 商品编码以{' '} - tpv: 开头。 + 新增时只需填写内部 SKU 和采购价，系统会自动创建 tpv:{' '} + 商品、卡券渠道规则并回填已有订单。卡券不创建任务、不发领取页，只记收入与采购成本。 + setCreateOpen(false)} + onOk={() => createForm.submit()} + confirmLoading={createMutation.isPending} + destroyOnHidden + > +
createMutation.mutate(values)} + > + { + const text = String(value || '').trim() + if (text && !/\p{Script=Han}/u.test(text)) { + throw new Error('内部 SKU 必须包含中文') + } + }, + }, + ]} + extra="保存后自动生成 tpv:<内部 SKU> 标准商品和卡券渠道规则。" + > + + + + + + + + +
+ + (`/api/v1/admin/cost-center/products/${productId}/sync-price`, {}) } -export function ensureVoucherChannelRules() { - return apiPost<{ created: number; productCount: number }>( - '/api/v1/admin/cost-center/voucher-products/ensure-rules', - ) +export function saveAdminVoucherProduct(payload: { + skuKey: string + amountFen: number + effectiveFrom?: string + note?: string +}) { + return apiPost<{ + product: ProductCatalogItem + costVersionId: number + amountFen: number + effectiveFrom: string + linkedItemCount: number + snapshotCreatedCount: number + refreshedDays: number + }>('/api/v1/admin/cost-center/voucher-products', payload) } export function deleteAdminVoucherProduct(productId: number) { diff --git a/apps/frontend/tests/voucher-sku-delete-ui.test.ts b/apps/frontend/tests/voucher-sku-delete-ui.test.ts index 688a5159..cf8958be 100644 --- a/apps/frontend/tests/voucher-sku-delete-ui.test.ts +++ b/apps/frontend/tests/voucher-sku-delete-ui.test.ts @@ -19,3 +19,30 @@ test('第三方卡券面板提供安全删除入口并格式化生效时间', as assert.ok(service.includes('/api/v1/admin/cost-center/voucher-products/${productId}')) assert.ok(service.includes("action: 'deleted' | 'archived'")) }) + +test('第三方卡券新增 SKU 一次完成商品、规则和采购价', async () => { + const [panel, service, productCatalog] = await Promise.all([ + readFile( + new URL('../src/pages/admin/cost-center/VoucherSkuPanel.tsx', import.meta.url), + 'utf8', + ), + readFile(new URL('../src/services/admin/cost-center.ts', import.meta.url), 'utf8'), + readFile( + new URL('../src/pages/admin/cost-center/ProductCatalogPanel.tsx', import.meta.url), + 'utf8', + ), + ]) + + assert.ok(panel.includes('新增卡券 SKU')) + assert.ok(panel.includes('saveAdminVoucherProduct')) + assert.ok(panel.includes('保存后自动生成 tpv:<内部 SKU> 标准商品和卡券渠道规则')) + assert.ok(panel.includes('补建成本快照')) + assert.ok(!panel.includes('批量生成渠道规则')) + assert.ok(!panel.includes('ensureVoucherChannelRules')) + assert.ok(service.includes('apiPost<')) + assert.ok(service.includes("'/api/v1/admin/cost-center/voucher-products'")) + assert.ok(!service.includes('/voucher-products/ensure-rules')) + assert.ok(panel.includes("searchParams.get('voucherNew')")) + assert.ok(productCatalog.includes("productSourceFilter === 'third_party_voucher'")) + assert.ok(productCatalog.includes('voucherNew=1')) +}) diff --git a/docs/成本中心API契约.md b/docs/成本中心API契约.md index 525cc69c..03469fc6 100644 --- a/docs/成本中心API契约.md +++ b/docs/成本中心API契约.md @@ -174,6 +174,27 @@ POST /api/v1/admin/cost-center/manual-configs `internal_sku_channels` 人工规则。待分类队列的“去补配置”会携带 `scope=manual&tab=cost&manualSku=<内部SKU>` 直接打开对应配置。 +### 4.4 第三方卡券 SKU（现行） + +卡券商品统一从“成本配置 → 第三方卡券 → 新增卡券 SKU”维护： + +```text +POST /api/v1/admin/cost-center/voucher-products +``` + +```jsonc +{ + "skuKey": "11月改名卡", + "amountFen": 500, + "note": "第三方卡券采购价" +} +``` + +保存时在同一事务内创建或复用 `tpv:<内部 SKU>`、卡券主渠道规则和采购成本版本， +并把同内部 SKU 的卡券订单项从错误的 `man:` 等商品归一到 `tpv:`。 +通用 `POST /api/v1/admin/cost-center/products` 不再接受 `tpv:` 和 `man:`。 +迁移 `143` 负责修复历史卡券商品归属。 + ## 五、成本版本接口 路径不变，字段不变： From a333c05df410d1a8f51320daec7cfb64ff3dfac1 Mon Sep 17 00:00:00 2001 From: yml2213 Date: Fri, 6 Nov 2026 17:12:44 +0800 Subject: [PATCH 5/7] =?UTF-8?q?fix(fulfillment):=20=E6=94=B6=E5=8F=A3?= =?UTF-8?q?=E6=B8=A0=E9=81=93=E5=95=86=E5=93=81=E4=B8=8E=E7=BB=9F=E4=B8=80?= =?UTF-8?q?=E7=BB=93=E7=AE=97=E8=BE=B9=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ..._fulfillment_shadow_configuration_sync.sql | 109 +++++++ ...145_fulfillment_current_attempt_latest.sql | 38 +++ apps/backend/src/routes/admin/finance.ts | 44 +++ .../cost-center/cost-exception-service.ts | 11 +- .../manual-fulfillment-config-service.ts | 20 ++ .../product-normalize-service.test.ts | 60 +++- .../cost-center/product-normalize-service.ts | 97 +++++- .../manual-fulfillment-integrity.test.ts | 9 + .../finance/manual-fulfillment-service.ts | 205 +++++++----- .../finance/on-account-bill-service.test.ts | 14 + .../finance/on-account-bill-service.ts | 306 ++++++++++++++++++ .../fulfillment/channel-assign-service.ts | 5 +- .../fulfillment-retry-guard.test.ts | 10 + .../fulfillment-shadow-model.test.ts | 16 + .../fulfillment-state-view.test.ts | 4 + .../admin/ManualFulfillmentConfirmModal.tsx | 8 +- .../admin/cost-center/CostExceptionPanel.tsx | 1 + .../src/pages/admin/fund/FundSupportView.tsx | 170 +++++++++- .../src/services/admin/cost-center.ts | 25 ++ apps/frontend/src/types/admin/cost-center.ts | 31 +- .../fund-support-wallet-on-account.test.ts | 18 ++ docs/成本中心API契约.md | 15 + docs/成本中心与履约模型.md | 3 + 23 files changed, 1113 insertions(+), 106 deletions(-) create mode 100644 apps/backend/src/db/migrations/144_fulfillment_shadow_configuration_sync.sql create mode 100644 apps/backend/src/db/migrations/145_fulfillment_current_attempt_latest.sql create mode 100644 apps/backend/src/services/finance/on-account-bill-service.test.ts create mode 100644 apps/backend/src/services/finance/on-account-bill-service.ts diff --git a/apps/backend/src/db/migrations/144_fulfillment_shadow_configuration_sync.sql b/apps/backend/src/db/migrations/144_fulfillment_shadow_configuration_sync.sql new file mode 100644 index 00000000..b365bfbc --- /dev/null +++ b/apps/backend/src/db/migrations/144_fulfillment_shadow_configuration_sync.sql @@ -0,0 +1,109 @@ +-- 144_fulfillment_shadow_configuration_sync.sql +-- +-- 统一履约视图会读取人工配置和 internal_sku_channels 的派生状态。 +-- 这两张配置表变化时也必须刷新影子模型，否则影子表会保留旧载体状态和旧异常。 + +CREATE OR REPLACE FUNCTION sync_fulfillment_shadow_for_manual_config() +RETURNS TRIGGER +LANGUAGE plpgsql +AS $$ +DECLARE + old_key TEXT; + new_key TEXT; +BEGIN + IF TG_OP <> 'INSERT' THEN + old_key := canonicalize_internal_sku(OLD.sku_key); + END IF; + IF TG_OP <> 'DELETE' THEN + new_key := canonicalize_internal_sku(NEW.sku_key); + END IF; + + PERFORM sync_fulfillment_shadow(item.id) + FROM order_items item + WHERE item.fulfillment_status IN ('pending', 'assigned') + AND canonicalize_internal_sku( + resolve_internal_sku(item.manual_sku_key, item.sku_name, item.sku_code) + ) IN (old_key, new_key); + + RETURN COALESCE(NEW, OLD); +END; +$$; + +DROP TRIGGER IF EXISTS trg_manual_fulfillment_config_shadow ON manual_fulfillment_configs; +CREATE TRIGGER trg_manual_fulfillment_config_shadow +AFTER INSERT OR UPDATE OR DELETE ON manual_fulfillment_configs +FOR EACH ROW +EXECUTE FUNCTION sync_fulfillment_shadow_for_manual_config(); + +CREATE OR REPLACE FUNCTION sync_fulfillment_shadow_for_internal_channel() +RETURNS TRIGGER +LANGUAGE plpgsql +AS $$ +DECLARE + old_key TEXT; + new_key TEXT; +BEGIN + IF TG_OP <> 'INSERT' THEN + old_key := canonicalize_internal_sku(OLD.internal_sku); + END IF; + IF TG_OP <> 'DELETE' THEN + new_key := canonicalize_internal_sku(NEW.internal_sku); + END IF; + + PERFORM sync_fulfillment_shadow(item.id) + FROM order_items item + WHERE item.fulfillment_status IN ('pending', 'assigned') + AND canonicalize_internal_sku( + resolve_internal_sku(item.manual_sku_key, item.sku_name, item.sku_code) + ) IN (old_key, new_key); + + RETURN COALESCE(NEW, OLD); +END; +$$; + +DROP TRIGGER IF EXISTS trg_internal_sku_channel_shadow ON internal_sku_channels; +CREATE TRIGGER trg_internal_sku_channel_shadow +AFTER INSERT OR UPDATE OR DELETE ON internal_sku_channels +FOR EACH ROW +EXECUTE FUNCTION sync_fulfillment_shadow_for_internal_channel(); + +CREATE OR REPLACE FUNCTION assert_manual_config_product_source() +RETURNS TRIGGER +LANGUAGE plpgsql +AS $$ +BEGIN + IF NEW.canonical_product_id IS NOT NULL + AND NOT EXISTS ( + SELECT 1 + FROM product_catalog product + WHERE product.id = NEW.canonical_product_id + AND product.status = 'active' + AND product.canonical_sku LIKE 'man:%' + ) + THEN + RAISE EXCEPTION + 'manual fulfillment config product % must be an active man: product', + NEW.canonical_product_id + USING ERRCODE = '23514'; + END IF; + RETURN NEW; +END; +$$; + +DROP TRIGGER IF EXISTS trg_manual_config_product_source ON manual_fulfillment_configs; +CREATE TRIGGER trg_manual_config_product_source +BEFORE INSERT OR UPDATE OF canonical_product_id ON manual_fulfillment_configs +FOR EACH ROW +EXECUTE FUNCTION assert_manual_config_product_source(); + +-- 修正迁移 141 后由配置变化造成的存量陈旧影子记录。 +SELECT sync_fulfillment_shadow(item.id) +FROM order_items item +WHERE item.fulfillment_status IN ('pending', 'assigned'); + +COMMENT ON FUNCTION sync_fulfillment_shadow_for_manual_config() IS + '人工配置变更后重算同内部 SKU 的履约影子'; +COMMENT ON FUNCTION sync_fulfillment_shadow_for_internal_channel() IS + '统一渠道规则变更后重算同内部 SKU 的履约影子'; +COMMENT ON FUNCTION assert_manual_config_product_source() IS + '人工履约配置只能关联有效的 man: 标准商品'; diff --git a/apps/backend/src/db/migrations/145_fulfillment_current_attempt_latest.sql b/apps/backend/src/db/migrations/145_fulfillment_current_attempt_latest.sql new file mode 100644 index 00000000..8f89e497 --- /dev/null +++ b/apps/backend/src/db/migrations/145_fulfillment_current_attempt_latest.sql @@ -0,0 +1,38 @@ +-- 145_fulfillment_current_attempt_latest.sql +-- +-- 统一读模型按 task.id DESC 取当前尝试。为保持与 is_current 指针一致， +-- 从现在开始禁止把较旧任务重新标记为 current；新尝试仍由业务先退休旧指针。 + +CREATE OR REPLACE FUNCTION assert_fulfillment_current_is_latest() +RETURNS TRIGGER +LANGUAGE plpgsql +AS $$ +BEGIN + IF NEW.is_current = TRUE + AND EXISTS ( + SELECT 1 + FROM fulfillment_tasks newer + WHERE newer.order_item_id = NEW.order_item_id + AND newer.unit_index = NEW.unit_index + AND newer.id > COALESCE(NEW.id, 0) + ) + THEN + RAISE EXCEPTION + 'fulfillment current attempt must be the latest attempt for order_item % unit %', + NEW.order_item_id, + NEW.unit_index + USING ERRCODE = '23514'; + END IF; + RETURN NEW; +END; +$$; + +DROP TRIGGER IF EXISTS trg_fulfillment_current_is_latest ON fulfillment_tasks; +CREATE TRIGGER trg_fulfillment_current_is_latest +BEFORE INSERT OR UPDATE OF is_current, order_item_id, unit_index +ON fulfillment_tasks +FOR EACH ROW +EXECUTE FUNCTION assert_fulfillment_current_is_latest(); + +COMMENT ON FUNCTION assert_fulfillment_current_is_latest() IS + '当前履约尝试必须是同订单项单元中 id 最大的尝试，保证统一视图 id DESC 与 is_current 一致'; diff --git a/apps/backend/src/routes/admin/finance.ts b/apps/backend/src/routes/admin/finance.ts index 31e9bf58..0904a338 100644 --- a/apps/backend/src/routes/admin/finance.ts +++ b/apps/backend/src/routes/admin/finance.ts @@ -13,6 +13,10 @@ import { confirmManualFulfillment, listManualFulfillmentPending, } from '../../services/finance/manual-fulfillment-service.js' +import { + listOnAccountBills, + reconcileOnAccountBill, +} from '../../services/finance/on-account-bill-service.js' import { createJsonHandler, requireAdminPermission, @@ -152,4 +156,44 @@ router.post( }), ) +router.get( + '/finance/on-account-bills', + requireAdminRoles(['admin', 'operator', 'support', 'finance']), + createJsonHandler((req) => listOnAccountBills(req.query as Record), { + successMessage: 'ok', + errorMessage: '读取统一结算账单失败', + scope: '[admin/finance/on-account-bills]', + }), +) + +router.post( + '/finance/on-account-bills/:billId/reconcile', + requireAdminPermission('finance.reconcile'), + createJsonHandler( + (req) => reconcileOnAccountBill(req.params.billId, bodyOf(req), sessionOf(req)), + { + successMessage: '统一结算账单已对账', + errorMessage: '统一结算账单对账失败', + scope: '[admin/finance/on-account-bills/:billId/reconcile]', + audit: (req, data) => { + const result = data as { + bill?: { id?: number; billNo?: string } + amountFen?: number + snapshotId?: number + } + return { + action: 'on_account_bill_reconciled', + targetType: 'on_account_bill', + targetId: String(result.bill?.id || req.params.billId || ''), + data: { + billNo: result.bill?.billNo || '', + amountFen: result.amountFen || 0, + costSnapshotId: result.snapshotId || null, + }, + } + }, + }, + ), +) + export default router diff --git a/apps/backend/src/services/cost-center/cost-exception-service.ts b/apps/backend/src/services/cost-center/cost-exception-service.ts index 27c84d37..6166f9e8 100644 --- a/apps/backend/src/services/cost-center/cost-exception-service.ts +++ b/apps/backend/src/services/cost-center/cost-exception-service.ts @@ -1,3 +1,5 @@ +import type { PoolClient } from 'pg' + import { query } from '../../db/client.js' import { nowIso } from '../../utils/time.js' @@ -19,6 +21,7 @@ export const COST_EXCEPTION_REASONS = [ 'cost_missing', 'manual_config_missing', 'manual_cost_missing', + 'on_account_cost_pending', 'carrier_missing', ] as const @@ -29,14 +32,16 @@ export type UpsertExceptionInput = { scopeKey: string orderItemId: number detail?: Record + client?: Pick } /** 幂等上浮一条聚合问题：已存在则累加明细并刷新 last_seen。 */ export async function upsertAggregatedException(input: UpsertExceptionInput): Promise { const now = nowIso() const detail = JSON.stringify(input.detail || {}) + const run = input.client ? input.client.query.bind(input.client) : query - const result = await query<{ id: number }>( + const result = await run<{ id: number }>( ` INSERT INTO cost_exceptions ( subject_type, subject_id, order_item_id, reason, status, detail_json, @@ -55,7 +60,7 @@ export async function upsertAggregatedException(input: UpsertExceptionInput): Pr const exceptionId = result.rows[0]?.id if (!exceptionId) return - await query( + await run( ` INSERT INTO cost_exception_items (exception_id, order_item_id, created_at) VALUES ($1, $2, $3) @@ -64,7 +69,7 @@ export async function upsertAggregatedException(input: UpsertExceptionInput): Pr [exceptionId, input.orderItemId, now], ) - await query( + await run( ` UPDATE cost_exceptions ce SET item_count = ( diff --git a/apps/backend/src/services/cost-center/manual-fulfillment-config-service.ts b/apps/backend/src/services/cost-center/manual-fulfillment-config-service.ts index ba7b95c7..dcfab3f0 100644 --- a/apps/backend/src/services/cost-center/manual-fulfillment-config-service.ts +++ b/apps/backend/src/services/cost-center/manual-fulfillment-config-service.ts @@ -468,6 +468,26 @@ export async function saveManualFulfillmentConfig(payload: JsonObject) { const existingId = Number(existing.rows[0]?.id || 0) let resolvedProductId = canonicalProductId + if (resolvedProductId) { + const product = await client.query<{ canonical_sku: string; status: string }>( + `SELECT canonical_sku, status + FROM product_catalog + WHERE id = $1 + LIMIT 1`, + [resolvedProductId], + ) + if ( + !product.rows[0] || + product.rows[0].status !== 'active' || + !String(product.rows[0].canonical_sku || '').startsWith('man:') + ) { + throw createHttpError('人工履约配置只能关联有效的 man: 标准商品', { + statusCode: 400, + errorCode: 'manual_config_product_source_invalid', + }) + } + } + // 人工配置本身就是该 SKU 的标准商品声明。没有显式关联时自动创建/复用 // man:<内部 SKU>，避免运营再去「标准商品」手工建一次。 if (!resolvedProductId) { diff --git a/apps/backend/src/services/cost-center/product-normalize-service.test.ts b/apps/backend/src/services/cost-center/product-normalize-service.test.ts index 0ab25723..4ac1cd97 100644 --- a/apps/backend/src/services/cost-center/product-normalize-service.test.ts +++ b/apps/backend/src/services/cost-center/product-normalize-service.test.ts @@ -1,4 +1,5 @@ import assert from 'node:assert/strict' +import { readFile } from 'node:fs/promises' import test from 'node:test' import { @@ -63,9 +64,11 @@ function item(patch: Record = {}) { sku_name: '任意', normalized_sku_name: null as string | null, normalized_sku_series: null as string | null, - fulfillment_channel: 'work_order' as string | null, + fulfillment_channel: null as string | null, + canonical_product_id: null as number | null, work_rule_key: null as string | null, manual_config_product_id: null as number | null, + manual_config_product_sku: null as string | null, ...patch, } } @@ -123,6 +126,7 @@ test('商品归一：人工渠道直接使用配置里指定的商品', () => { fulfillment_channel: 'manual', sku_code: 'unknown', manual_config_product_id: 44, + manual_config_product_sku: 'man:配置商品', }), index, ), @@ -157,11 +161,52 @@ test('商品归一：第三方卡券缺少 tpv 商品时不能串到同名人工 ) }) +test('商品归一：其他已确定渠道也不能借用同名其他来源商品', () => { + for (const fulfillmentChannel of ['manual', 'on_account', 'affiliate_dash', 'work_order']) { + assert.equal( + resolveProductId( + item({ + fulfillment_channel: fulfillmentChannel, + sku_code: 'unknown', + internal_sku: '套装-测试', + }), + index, + ), + null, + ) + } +}) + +test('商品归一：人工配置也只能挂载 man: 商品', () => { + assert.equal( + resolveProductId( + item({ + fulfillment_channel: 'manual', + manual_config_product_id: 99, + manual_config_product_sku: 'aff:错误商品', + }), + index, + ), + null, + ) + assert.equal( + resolveProductId( + item({ + fulfillment_channel: 'on_account', + manual_config_product_id: 99, + manual_config_product_sku: 'man:正确商品', + }), + index, + ), + 99, + ) +}) + test('商品归一：中文内部 SKU 命中标准商品，不依赖平台 SKU', () => { assert.equal( resolveProductId( item({ - fulfillment_channel: 'affiliate_dash', + fulfillment_channel: null, sku_code: 'unknown', internal_sku: '套装-测试', }), @@ -191,3 +236,14 @@ test('三方卡券自动建商品时优先使用内部中文 SKU', () => { assert.equal(voucherCanonicalSku({ manual_sku_key: '', sku_name: '', sku_code: 'x' }), null) assert.equal(voucherCanonicalSku({}), null) }) + +test('商品归一扫描会纠正所有渠道的错误来源商品', async () => { + const source = await readFile(new URL('./product-normalize-service.ts', import.meta.url), 'utf8') + + assert.ok(source.includes("current_product.canonical_sku NOT LIKE 'aff:%'")) + assert.ok(source.includes("current_product.canonical_sku NOT LIKE 'man:%'")) + assert.ok(source.includes("current_product.canonical_sku NOT LIKE 'tpl:%'")) + assert.ok(source.includes("current_product.canonical_sku NOT LIKE 'tpv:%'")) + assert.ok(source.includes('canonicalProductId: null')) + assert.ok(source.includes('onlyWhenCanonicalProductDifferent: true')) +}) diff --git a/apps/backend/src/services/cost-center/product-normalize-service.ts b/apps/backend/src/services/cost-center/product-normalize-service.ts index 552bb87c..050ab17b 100644 --- a/apps/backend/src/services/cost-center/product-normalize-service.ts +++ b/apps/backend/src/services/cost-center/product-normalize-service.ts @@ -3,7 +3,10 @@ import { resolveExceptionsForItems, upsertAggregatedException } from './cost-exc import { readWatermarkItemId } from '../watermark-store.js' import { upsertInternalSkuChannel } from '../fulfillment/internal-sku-channel-service.js' import { canonicalizeInternalSku, containsCjk } from '../fulfillment/internal-sku-resolver.js' -import { attachFulfillmentConfigurations } from '../fulfillment/fulfillment-state-service.js' +import { + attachFulfillmentConfigurations, + transitionFulfillmentState, +} from '../fulfillment/fulfillment-state-service.js' /** * 管道 B：商品归一。 @@ -51,8 +54,10 @@ type ItemRow = { normalized_sku_name: string | null normalized_sku_series: string | null fulfillment_channel: string | null + canonical_product_id?: number | null work_rule_key: string | null manual_config_product_id: number | null + manual_config_product_sku?: string | null } function key(...parts: string[]): string { @@ -145,6 +150,17 @@ export function voucherCanonicalSku(item: { return internal ? `tpv:${internal}` : null } +async function clearMismatchedProduct(item: ItemRow) { + if (!item.fulfillment_channel || !item.canonical_product_id) return + await transitionFulfillmentState({ + orderItemId: Number(item.id), + expected: { status: 'assigned' }, + patch: { canonicalProductId: null }, + eventType: 'product_source_cleared', + reason: `渠道 ${item.fulfillment_channel} 与当前标准商品来源不一致`, + }) +} + /** * 三方卡券没有预先建库时，按内部 SKU 自动建 `tpv:` 商品并补渠道规则。 * 建完后该商品会出现在「商品与成本中心 → 第三方卡券」，运营直接设采购价。 @@ -225,20 +241,23 @@ export function resolveProductId(item: ItemRow, index: MappingIndex): number | n const seriesKey = String(item.normalized_sku_series || '').trim() const internalSku = canonicalizeInternalSku(item.internal_sku || item.manual_sku_key) - // 人工渠道：配置里已经指定商品，直接用，不需要再建映射。 - if (item.fulfillment_channel === 'manual' && item.manual_config_product_id) { - return Number(item.manual_config_product_id) + // 已确定渠道必须命中本渠道商品，不能借用同名的其他来源商品。 + if (item.fulfillment_channel === 'manual' || item.fulfillment_channel === 'on_account') { + return item.manual_config_product_id && + String(item.manual_config_product_sku || '').startsWith('man:') + ? Number(item.manual_config_product_id) + : null } // 接单平台：模板即商品来源（tpl:），无需渠道映射。 - if (item.fulfillment_channel === 'work_order' && item.work_rule_key) { + if (item.fulfillment_channel === 'work_order') { + if (!item.work_rule_key) return null const templateProduct = index.templateRules.get(String(item.work_rule_key).trim()) - if (templateProduct) return templateProduct + return templateProduct || null } - if (item.fulfillment_channel === 'affiliate_dash' && skuCode) { - const aff = index.affSkus.get(skuCode) - if (aff) return aff + if (item.fulfillment_channel === 'affiliate_dash') { + return skuCode ? index.affSkus.get(skuCode) || null : null } // 第三方卡券：与自动发货同构，商品编码 tpv:。 @@ -325,13 +344,16 @@ export async function normalizeOrderItemProducts( oi.normalized_sku_name, oi.normalized_sku_series, oi.fulfillment_channel, + oi.canonical_product_id, wpr.rule_key AS work_rule_key, - cfg.canonical_product_id AS manual_config_product_id + cfg.canonical_product_id AS manual_config_product_id, + cfg_product.canonical_sku AS manual_config_product_sku FROM order_items oi JOIN orders o ON o.id = oi.order_id LEFT JOIN work_orders wo ON wo.order_item_id = oi.id AND wo.status <> 'cancelled' LEFT JOIN work_product_rules wpr ON wpr.id = wo.product_rule_id LEFT JOIN manual_fulfillment_configs cfg ON cfg.id = oi.fulfillment_config_id + LEFT JOIN product_catalog cfg_product ON cfg_product.id = cfg.canonical_product_id LEFT JOIN product_catalog current_product ON current_product.id = oi.canonical_product_id WHERE oi.fulfillment_status = 'assigned' AND ( @@ -343,6 +365,30 @@ export async function normalizeOrderItemProducts( OR current_product.canonical_sku NOT LIKE 'tpv:%' ) ) + OR ( + oi.fulfillment_channel = 'affiliate_dash' + AND ( + current_product.id IS NULL + OR current_product.canonical_sku NOT LIKE 'aff:%' + ) + ) + OR ( + oi.fulfillment_channel IN ('manual', 'on_account') + AND ( + current_product.id IS NULL + OR current_product.canonical_sku NOT LIKE 'man:%' + ) + ) + OR ( + oi.fulfillment_channel = 'work_order' + AND ( + current_product.id IS NULL + OR ( + current_product.canonical_sku NOT LIKE 'tpl:%' + AND current_product.canonical_sku NOT LIKE 'wo:%' + ) + ) + ) ) AND oi.id > $1 ORDER BY oi.id @@ -369,6 +415,7 @@ export async function normalizeOrderItemProducts( } if (!productId) { result.unmatched += 1 + await clearMismatchedProduct(item) await upsertAggregatedException({ reason: 'product_mapping_missing', scopeKey: `product_mapping_missing|-|-|${canonicalizeInternalSku(item.internal_sku || item.manual_sku_key || item.sku_code)}|${item.fulfillment_channel || '-'}`, @@ -487,13 +534,16 @@ export async function normalizeProductsForItems(itemIds: number[]): Promise<{ oi.normalized_sku_name, oi.normalized_sku_series, oi.fulfillment_channel, + oi.canonical_product_id, wpr.rule_key AS work_rule_key, - cfg.canonical_product_id AS manual_config_product_id + cfg.canonical_product_id AS manual_config_product_id, + cfg_product.canonical_sku AS manual_config_product_sku FROM order_items oi JOIN orders o ON o.id = oi.order_id LEFT JOIN work_orders wo ON wo.order_item_id = oi.id AND wo.status <> 'cancelled' LEFT JOIN work_product_rules wpr ON wpr.id = wo.product_rule_id LEFT JOIN manual_fulfillment_configs cfg ON cfg.id = oi.fulfillment_config_id + LEFT JOIN product_catalog cfg_product ON cfg_product.id = cfg.canonical_product_id LEFT JOIN product_catalog current_product ON current_product.id = oi.canonical_product_id WHERE oi.fulfillment_status = 'assigned' AND ( @@ -505,6 +555,30 @@ export async function normalizeProductsForItems(itemIds: number[]): Promise<{ OR current_product.canonical_sku NOT LIKE 'tpv:%' ) ) + OR ( + oi.fulfillment_channel = 'affiliate_dash' + AND ( + current_product.id IS NULL + OR current_product.canonical_sku NOT LIKE 'aff:%' + ) + ) + OR ( + oi.fulfillment_channel IN ('manual', 'on_account') + AND ( + current_product.id IS NULL + OR current_product.canonical_sku NOT LIKE 'man:%' + ) + ) + OR ( + oi.fulfillment_channel = 'work_order' + AND ( + current_product.id IS NULL + OR ( + current_product.canonical_sku NOT LIKE 'tpl:%' + AND current_product.canonical_sku NOT LIKE 'wo:%' + ) + ) + ) ) AND oi.id = ANY($1::bigint[]) `, @@ -519,6 +593,7 @@ export async function normalizeProductsForItems(itemIds: number[]): Promise<{ } if (!productId) { unmatched += 1 + await clearMismatchedProduct(item) await upsertAggregatedException({ reason: 'product_mapping_missing', scopeKey: `product_mapping_missing|-|-|${canonicalizeInternalSku(item.internal_sku || item.manual_sku_key || item.sku_code)}|${item.fulfillment_channel || '-'}`, diff --git a/apps/backend/src/services/finance/manual-fulfillment-integrity.test.ts b/apps/backend/src/services/finance/manual-fulfillment-integrity.test.ts index 92f86362..ea0c20cc 100644 --- a/apps/backend/src/services/finance/manual-fulfillment-integrity.test.ts +++ b/apps/backend/src/services/finance/manual-fulfillment-integrity.test.ts @@ -165,6 +165,15 @@ test('人工确认前必须自动匹配履约配置，配置保存/定时任务 ) }) +test('统一结算金额未知时只生成待对账账单，不写 0 元实际成本', async () => { + const source = await readFile(new URL('./manual-fulfillment-service.ts', import.meta.url), 'utf8') + + assert.ok(source.includes("platformKey === 'on_account' && costFen <= 0")) + assert.ok(source.includes('if (!onAccountCostPending)')) + assert.ok(source.includes("reason: 'on_account_cost_pending'")) + assert.ok(source.includes('costPending: onAccountCostPending')) +}) + test('人工成本缺失由管道按配置与快照生成并收口', async () => { const [pipelineSource, manualSource] = await Promise.all([ readFile(new URL('../scheduler/finance-pipeline-jobs.ts', import.meta.url), 'utf8'), diff --git a/apps/backend/src/services/finance/manual-fulfillment-service.ts b/apps/backend/src/services/finance/manual-fulfillment-service.ts index 315bbeaa..091d6841 100644 --- a/apps/backend/src/services/finance/manual-fulfillment-service.ts +++ b/apps/backend/src/services/finance/manual-fulfillment-service.ts @@ -21,6 +21,7 @@ import { attachFulfillmentConfigurationsWithExecutor, transitionFulfillmentStateWithExecutor, } from '../fulfillment/fulfillment-state-service.js' +import { upsertAggregatedException } from '../cost-center/cost-exception-service.js' import { calculateManualCostFen, normalizeManualCreditQuantity, @@ -411,6 +412,20 @@ export async function confirmManualFulfillment(payload: JsonObject, session: Adm errorCode: 'manual_fulfillment_platform_required', }) } + if (selectedChannel.platformKey === 'on_account') { + const existingBill = await client.query<{ id: number }>( + `SELECT id FROM on_account_bills + WHERE order_item_id = $1 AND status IN ('pending', 'reconciled') + LIMIT 1`, + [orderItemId], + ) + if (existingBill.rows[0]) { + throw createHttpError('该订单项已生成统一结算账单，不能重复操作', { + statusCode: 409, + errorCode: 'manual_fulfillment_on_account_already_exists', + }) + } + } // 锁内复查：并发/双击的第二个请求会等锁，醒来后看到快照直接拒绝，不会重复扣款。 const existing = await client.query<{ id: number }>( @@ -447,6 +462,7 @@ export async function confirmManualFulfillment(payload: JsonObject, session: Adm providedCostFen, }) const costFen = costPlan.costFen + const onAccountCostPending = platformKey === 'on_account' && costFen <= 0 const payeeName = optionalText(payload.payeeName ?? payload.payee_name, 120) const note = optionalText(payload.note, 300) const fulfillmentReference = buildManualFulfillmentReference({ @@ -455,16 +471,8 @@ export async function confirmManualFulfillment(payload: JsonObject, session: Adm orderItemId, }) - // 先把成本项/版本解析完再扣钱：版本缺失不能发生在扣款之后。 - const costItemId = await resolveManualCostItemIdWithClient(client) - const versionId = await resolveCostVersionIdWithClient(client, costItemId, row, now) - if (!versionId) { - throw createHttpError('该成本项没有可用的成本版本，请先在成本中心配置后重试', { - statusCode: 409, - errorCode: 'manual_fulfillment_cost_version_missing', - }) - } - + // 扣款前先确定最终成本模式。统一结算未填金额时只生成待对账账单， + // 不写 0 元 actual 成本快照，避免利润被虚增。 let fundExpenseId: number | null = null let creditEntryId: number | null = null let balanceAfter: number | null = null @@ -522,11 +530,22 @@ export async function confirmManualFulfillment(payload: JsonObject, session: Adm subjectSource = 'platform_credit' } - // subject_id 固定为 order_item_id：不再与 manual_expenses.id / - // platform_credit_entries.id 混用，避免两张表序列撞车。 - // subject_type 仍为 manual_case，资金流水只放在 metadata 里。 - const snapshot = await client.query<{ id: number }>( - ` + let snapshotId: number | null = null + if (!onAccountCostPending) { + const costItemId = await resolveManualCostItemIdWithClient(client) + const versionId = await resolveCostVersionIdWithClient(client, costItemId, row, now) + if (!versionId) { + throw createHttpError('该成本项没有可用的成本版本，请先在成本中心配置后重试', { + statusCode: 409, + errorCode: 'manual_fulfillment_cost_version_missing', + }) + } + + // subject_id 固定为 order_item_id：不再与 manual_expenses.id / + // platform_credit_entries.id 混用，资金流水只放在 metadata 里。 + // subject_type 仍为 manual_case。 + const snapshot = await client.query<{ id: number }>( + ` INSERT INTO cost_snapshots ( subject_type, subject_id, order_id, order_item_id, work_order_id, cost_item_id, cost_version_id, canonical_product_id, @@ -540,50 +559,51 @@ export async function confirmManualFulfillment(payload: JsonObject, session: Adm ) ON CONFLICT DO NOTHING RETURNING id - `, - [ - orderItemId, - row.order_id_resolved, - row.work_order_id, - costItemId, - versionId, - row.canonical_product_id, - costFen, - JSON.stringify({ - source: 'manual_fulfillment_confirm', - subjectSource, - configId: Number(row.config_id), - platformKey, - platformLabel: PLATFORM_LABELS[platformKey] || platformKey, - creditOwnerAdminUserId: - platformKey === 'fund_cash' - ? null - : Number(payload.creditOwnerAdminUserId || 0) || null, - creditQuantity, - creditUnitPriceFen: unitPriceFen, - costMode: costPlan.costMode, + `, + [ + orderItemId, + row.order_id_resolved, + row.work_order_id, + costItemId, + versionId, + row.canonical_product_id, costFen, - fundExpenseId, - creditEntryId, - balanceAfter, - payeeName, - note, - fulfilledBy: { - userId: Number(session.userId || 0), - displayName: String(session.displayName || ''), - role: String(session.role || ''), - }, - }), - now, - ], - ) - const snapshotId = snapshot.rows[0]?.id ?? null - if (!snapshotId) { - // 订单项唯一索引兜底：任何竞态都会走到这里，抛错回滚本次扣款。 - throw createHttpError('该订单项已有人工成本快照，不能重复录入', { - statusCode: 409, - errorCode: 'manual_fulfillment_snapshot_conflict', - }) + JSON.stringify({ + source: 'manual_fulfillment_confirm', + subjectSource, + configId: Number(row.config_id), + platformKey, + platformLabel: PLATFORM_LABELS[platformKey] || platformKey, + creditOwnerAdminUserId: + platformKey === 'fund_cash' + ? null + : Number(payload.creditOwnerAdminUserId || 0) || null, + creditQuantity, + creditUnitPriceFen: unitPriceFen, + costMode: costPlan.costMode, + costFen, + fundExpenseId, + creditEntryId, + balanceAfter, + payeeName, + note, + fulfilledBy: { + userId: Number(session.userId || 0), + displayName: String(session.displayName || ''), + role: String(session.role || ''), + }, + }), + now, + ], + ) + snapshotId = snapshot.rows[0]?.id ?? null + if (!snapshotId) { + // 订单项唯一索引兜底：任何竞态都会走到这里，抛错回滚本次扣款。 + throw createHttpError('该订单项已有人工成本快照，不能重复录入', { + statusCode: 409, + errorCode: 'manual_fulfillment_snapshot_conflict', + }) + } } if (platformKey === 'on_account') { @@ -641,30 +661,46 @@ export async function confirmManualFulfillment(payload: JsonObject, session: Adm reason: platformKey, }) - // 人工缺成本异常立即收口，不等下一轮定时任务。 - await client.query( - `UPDATE cost_exceptions - SET status = 'resolved', resolved_at = $2 - WHERE subject_type = 'order_item' - AND subject_id = $1 - AND reason = 'manual_cost_missing' - AND status = 'open'`, - [orderItemId, now], - ) + if (onAccountCostPending) { + await upsertAggregatedException({ + reason: 'on_account_cost_pending', + scopeKey: `on_account_cost_pending|-|-|${row.internal_sku}|on_account`, + orderItemId, + detail: { + billId: onAccountBillId, + internalSku: row.internal_sku, + platformOrderId: row.platform_order_id, + }, + client, + }) + } else { + // 人工缺成本异常立即收口，不等下一轮定时任务。 + await client.query( + `UPDATE cost_exceptions + SET status = 'resolved', resolved_at = $2 + WHERE subject_type = 'order_item' + AND subject_id = $1 + AND reason = 'manual_cost_missing' + AND status = 'open'`, + [orderItemId, now], + ) + } - // v2 聚合异常：删除本条明细，没人再引用的异常头自动关闭。 - await client.query(`DELETE FROM cost_exception_items WHERE order_item_id = $1`, [orderItemId]) - await client.query( - ` - UPDATE cost_exceptions ce - SET status = 'resolved', resolved_at = $1, item_count = 0, last_seen_at = $1 - WHERE ce.status <> 'resolved' - AND NOT EXISTS ( - SELECT 1 FROM cost_exception_items i WHERE i.exception_id = ce.id - ) - `, - [now], - ) + if (!onAccountCostPending) { + // v2 聚合异常：成本已经落账后，删除本条明细并自动关闭空异常头。 + await client.query(`DELETE FROM cost_exception_items WHERE order_item_id = $1`, [orderItemId]) + await client.query( + ` + UPDATE cost_exceptions ce + SET status = 'resolved', resolved_at = $1, item_count = 0, last_seen_at = $1 + WHERE ce.status <> 'resolved' + AND NOT EXISTS ( + SELECT 1 FROM cost_exception_items i WHERE i.exception_id = ce.id + ) + `, + [now], + ) + } return { orderItemId, @@ -678,6 +714,7 @@ export async function confirmManualFulfillment(payload: JsonObject, session: Adm creditEntryId, balanceAfter, onAccountBillId, + costPending: onAccountCostPending, } }) @@ -693,7 +730,7 @@ export async function confirmManualFulfillment(payload: JsonObject, session: Adm * 事实任务默认只回看最近几天，确认一笔较早的订单时不会自动覆盖， * 所以这里按该订单自己的业务日期精确重算。 */ -async function refreshFactsForOrderItem(orderItemId: number): Promise { +export async function refreshFactsForOrderItem(orderItemId: number): Promise { try { const basis = await query<{ stat_date: string | null }>( ` @@ -841,7 +878,7 @@ async function matchManualFulfillmentConfigWithClient(client: PoolClient, orderI return true } -async function resolveManualCostItemIdWithClient(client: PoolClient) { +export async function resolveManualCostItemIdWithClient(client: PoolClient) { const result = await client.query<{ id: number }>( `SELECT id FROM cost_items WHERE code = 'sys_manual_service' AND status = 'active' LIMIT 1`, ) @@ -855,7 +892,7 @@ async function resolveManualCostItemIdWithClient(client: PoolClient) { return id } -async function resolveCostVersionIdWithClient( +export async function resolveCostVersionIdWithClient( client: PoolClient, costItemId: number, row: { diff --git a/apps/backend/src/services/finance/on-account-bill-service.test.ts b/apps/backend/src/services/finance/on-account-bill-service.test.ts new file mode 100644 index 00000000..9c7196b7 --- /dev/null +++ b/apps/backend/src/services/finance/on-account-bill-service.test.ts @@ -0,0 +1,14 @@ +import assert from 'node:assert/strict' +import { readFile } from 'node:fs/promises' +import test from 'node:test' + +test('统一结算对账用实际金额替代成本快照并重算事实', async () => { + const source = await readFile(new URL('./on-account-bill-service.ts', import.meta.url), 'utf8') + + assert.ok(source.includes('withTransaction(')) + assert.ok(source.includes("status = 'reconciled'")) + assert.ok(source.includes('SET superseded_at = $2')) + assert.ok(source.includes("source: 'on_account_reconcile'")) + assert.ok(source.includes("'on_account_cost_pending'")) + assert.ok(source.includes('refreshFactsForOrderItem')) +}) diff --git a/apps/backend/src/services/finance/on-account-bill-service.ts b/apps/backend/src/services/finance/on-account-bill-service.ts new file mode 100644 index 00000000..73827352 --- /dev/null +++ b/apps/backend/src/services/finance/on-account-bill-service.ts @@ -0,0 +1,306 @@ +import { query, withTransaction } from '../../db/client.js' +import type { JsonObject } from '../../types/json.js' +import { createHttpError } from '../../utils/http.js' +import { nowIso } from '../../utils/time.js' +import type { AdminSession } from '../admin/admin-auth-service.js' +import { resolveExceptionsForItemsByReason } from '../cost-center/cost-exception-service.js' +import { + refreshFactsForOrderItem, + resolveCostVersionIdWithClient, + resolveManualCostItemIdWithClient, +} from './manual-fulfillment-service.js' + +type OnAccountBillRow = { + id: number + bill_no: string + order_id: number + order_item_id: number + sku_key: string + canonical_product_id: number | null + platform_order_id: string + amount_fen: string | number + status: 'pending' | 'reconciled' | 'void' + payee_name: string + note: string + metadata_json: Record + created_by_admin_user_id: number | null + created_at: string + updated_at: string + reconciled_at: string | null + provider?: string + shop_id?: string + sku_name?: string + revenue_amount_fen?: string | number +} + +function mapBill(row: OnAccountBillRow) { + return { + id: Number(row.id), + billNo: row.bill_no, + orderId: Number(row.order_id), + orderItemId: Number(row.order_item_id), + skuKey: row.sku_key, + skuName: row.sku_name || row.sku_key, + canonicalProductId: row.canonical_product_id ? Number(row.canonical_product_id) : null, + platformOrderId: row.platform_order_id, + provider: row.provider || '', + shopId: row.shop_id || '', + revenueFen: Number(row.revenue_amount_fen || 0), + amountFen: Number(row.amount_fen || 0), + status: row.status, + payeeName: row.payee_name || '', + note: row.note || '', + metadata: row.metadata_json || {}, + createdByAdminUserId: row.created_by_admin_user_id + ? Number(row.created_by_admin_user_id) + : null, + createdAt: row.created_at, + updatedAt: row.updated_at, + reconciledAt: row.reconciled_at, + } +} + +const BILL_SELECT = ` + SELECT + bill.*, + order_row.provider, + order_row.shop_id, + item.sku_name, + item.revenue_amount_fen + FROM on_account_bills bill + JOIN orders order_row ON order_row.id = bill.order_id + JOIN order_items item ON item.id = bill.order_item_id +` + +export async function listOnAccountBills(input: JsonObject = {}) { + const page = Math.max(1, Math.trunc(Number(input.page) || 1)) + const pageSize = Math.min(100, Math.max(1, Math.trunc(Number(input.pageSize) || 20))) + const keyword = String(input.keyword || '').trim() + const status = String(input.status || '').trim() + const where: string[] = [] + const params: unknown[] = [] + + if (keyword) { + params.push(`%${keyword}%`) + where.push(`( + bill.bill_no ILIKE $${params.length} + OR bill.platform_order_id ILIKE $${params.length} + OR bill.sku_key ILIKE $${params.length} + OR item.sku_name ILIKE $${params.length} + )`) + } + if (['pending', 'reconciled', 'void'].includes(status)) { + params.push(status) + where.push(`bill.status = $${params.length}`) + } + + const whereSql = where.length > 0 ? `WHERE ${where.join(' AND ')}` : '' + const total = await query<{ total: number }>( + `SELECT COUNT(*)::int AS total + FROM on_account_bills bill + JOIN order_items item ON item.id = bill.order_item_id + ${whereSql}`, + params, + ) + const listParams = [...params, pageSize, (page - 1) * pageSize] + const result = await query( + `${BILL_SELECT} + ${whereSql} + ORDER BY + CASE bill.status WHEN 'pending' THEN 0 WHEN 'reconciled' THEN 1 ELSE 2 END, + bill.created_at DESC, + bill.id DESC + LIMIT $${params.length + 1} OFFSET $${params.length + 2}`, + listParams, + ) + + return { + items: result.rows.map(mapBill), + pagination: { + page, + pageSize, + total: Number(total.rows[0]?.total || 0), + }, + } +} + +export async function reconcileOnAccountBill( + billIdInput: unknown, + payload: JsonObject, + session: AdminSession, +) { + const billId = Number(billIdInput) + if (!Number.isInteger(billId) || billId <= 0) { + throw createHttpError('统一结算账单 ID 无效', { statusCode: 400 }) + } + const amountFen = Number(payload.amountFen ?? payload.amount_fen) + if (!Number.isFinite(amountFen) || amountFen <= 0 || !Number.isInteger(amountFen)) { + throw createHttpError('实际结算金额必须是大于 0 的整数分', { + statusCode: 400, + errorCode: 'on_account_amount_invalid', + }) + } + + const now = nowIso() + const result = await withTransaction(async (client) => { + const billResult = await client.query( + `${BILL_SELECT} + WHERE bill.id = $1 + LIMIT 1 + FOR UPDATE OF bill, item`, + [billId], + ) + const bill = billResult.rows[0] + if (!bill) { + throw createHttpError('统一结算账单不存在', { statusCode: 404 }) + } + if (bill.status !== 'pending') { + throw createHttpError('只有待对账账单可以确认结算', { + statusCode: 409, + errorCode: 'on_account_bill_not_pending', + }) + } + + const orderResult = await client.query<{ + provider: string + shop_id: string + paid_at: string | null + created_at: string + }>( + `SELECT provider, shop_id, paid_at, created_at + FROM orders WHERE id = $1`, + [bill.order_id], + ) + const order = orderResult.rows[0] + if (!order) { + throw createHttpError('统一结算账单关联订单不存在', { statusCode: 409 }) + } + const basisAt = order.paid_at || order.created_at + const period = await client.query<{ status: string }>( + `SELECT status FROM finance_periods + WHERE period_key = to_char($1::timestamptz AT TIME ZONE 'Asia/Shanghai', 'YYYY-MM') + LIMIT 1`, + [basisAt], + ) + if (period.rows[0]?.status === 'closed') { + throw createHttpError('该订单所属期间已关账，请先反关账后再对账', { + statusCode: 409, + errorCode: 'on_account_period_closed', + }) + } + + const workOrder = await client.query<{ product_rule_id: number | null }>( + `SELECT product_rule_id FROM work_orders + WHERE order_item_id = $1 AND status <> 'cancelled' + ORDER BY id DESC LIMIT 1`, + [bill.order_item_id], + ) + const costItemId = await resolveManualCostItemIdWithClient(client) + const versionId = await resolveCostVersionIdWithClient( + client, + costItemId, + { + order_id_resolved: Number(bill.order_id), + provider: order.provider, + shop_id: order.shop_id, + canonical_product_id: bill.canonical_product_id, + work_product_rule_id: workOrder.rows[0]?.product_rule_id || null, + credit_unit_price_fen: '1', + }, + basisAt, + ) + if (!versionId) { + throw createHttpError('人工履约成本版本不可用，无法完成对账', { + statusCode: 409, + errorCode: 'on_account_cost_version_missing', + }) + } + + await client.query( + `UPDATE cost_snapshots + SET superseded_at = $2 + WHERE order_item_id = $1 + AND subject_type = 'manual_case' + AND superseded_at IS NULL + AND reversed_at IS NULL`, + [bill.order_item_id, now], + ) + const snapshot = await client.query<{ id: number }>( + `INSERT INTO cost_snapshots ( + subject_type, subject_id, order_id, order_item_id, work_order_id, + cost_item_id, cost_version_id, canonical_product_id, + quantity, unit_amount_fen, total_amount_fen, snapshot_stage, source, + metadata_json, cost_basis_at, resolved_at, created_at + ) VALUES ( + 'manual_case', $1, $2, $1, NULL, + $3, $4, $5, + 1, $6, $6, 'actual', 'manual_input', + $7::jsonb, $8, $9, $9 + ) + RETURNING id`, + [ + bill.order_item_id, + bill.order_id, + costItemId, + versionId, + bill.canonical_product_id, + amountFen, + JSON.stringify({ + source: 'on_account_reconcile', + billId: bill.id, + billNo: bill.bill_no, + platformKey: 'on_account', + previousAmountFen: Number(bill.amount_fen || 0), + reconciledBy: { + userId: Number(session.userId || 0), + displayName: String(session.displayName || ''), + }, + }), + basisAt, + now, + ], + ) + const snapshotId = Number(snapshot.rows[0]?.id || 0) + if (!snapshotId) { + throw createHttpError('统一结算成本快照保存失败', { statusCode: 500 }) + } + + const updated = await client.query( + `UPDATE on_account_bills + SET amount_fen = $1, + status = 'reconciled', + payee_name = $2, + note = $3, + metadata_json = metadata_json || $4::jsonb, + reconciled_at = $5, + updated_at = $5 + WHERE id = $6 + RETURNING *`, + [ + amountFen, + String(payload.payeeName ?? payload.payee_name ?? bill.payee_name ?? '').slice(0, 120), + String(payload.note ?? bill.note ?? '').slice(0, 300), + JSON.stringify({ + reconciledByAdminUserId: Number(session.userId || 0) || null, + costSnapshotId: snapshotId, + }), + now, + bill.id, + ], + ) + return { + bill: mapBill({ ...bill, ...updated.rows[0]!, amount_fen: amountFen }), + orderItemId: Number(bill.order_item_id), + snapshotId, + amountFen, + } + }) + + await Promise.all([ + resolveExceptionsForItemsByReason([result.orderItemId], 'on_account_cost_pending'), + resolveExceptionsForItemsByReason([result.orderItemId], 'manual_cost_missing'), + resolveExceptionsForItemsByReason([result.orderItemId], 'cost_missing'), + ]).catch(() => undefined) + await refreshFactsForOrderItem(result.orderItemId).catch(() => undefined) + return result +} diff --git a/apps/backend/src/services/fulfillment/channel-assign-service.ts b/apps/backend/src/services/fulfillment/channel-assign-service.ts index 97533ad0..1452e9ae 100644 --- a/apps/backend/src/services/fulfillment/channel-assign-service.ts +++ b/apps/backend/src/services/fulfillment/channel-assign-service.ts @@ -434,7 +434,10 @@ export async function assignPendingOrderItemChannels( .filter((id) => id > 0) .slice(0, 2000) result.assigned += assignedItemIds.length - result.assignedItemIds = assignedItemIds + result.assignedItemIds = [...new Set([...result.assignedItemIds, ...assignedItemIds])].slice( + 0, + 2000, + ) await scheduleVoucherConsumeForOrderItems(assignedItemIds, 'order_received').catch( (error) => { logWarn('[channel-assign]', '订单收到后安排自动核销失败', { diff --git a/apps/backend/src/services/fulfillment/fulfillment-retry-guard.test.ts b/apps/backend/src/services/fulfillment/fulfillment-retry-guard.test.ts index 7b5709e7..1c9c1568 100644 --- a/apps/backend/src/services/fulfillment/fulfillment-retry-guard.test.ts +++ b/apps/backend/src/services/fulfillment/fulfillment-retry-guard.test.ts @@ -16,6 +16,10 @@ const currentAttemptMigration = readFileSync( new URL('../../db/migrations/138_fulfillment_current_attempt.sql', import.meta.url), 'utf8', ) +const currentLatestMigration = readFileSync( + new URL('../../db/migrations/145_fulfillment_current_attempt_latest.sql', import.meta.url), + 'utf8', +) test('自动发货历史非活跃任务默认阻止后台自动重开', () => { assert.ok(carrierCreation.includes('INACTIVE_CARRIER_TASK_STATUSES.includes')) @@ -55,3 +59,9 @@ test('创建新履约尝试时自动退休旧当前尝试', () => { assert.ok(taskRepo.includes('$26, TRUE')) assert.ok(taskRepo.includes('SELECT id FROM order_items WHERE id = $1 FOR UPDATE')) }) + +test('当前尝试必须是同单元最新任务，统一视图不能读到已退休尝试', () => { + assert.ok(currentLatestMigration.includes('assert_fulfillment_current_is_latest')) + assert.ok(currentLatestMigration.includes('newer.id > COALESCE(NEW.id, 0)')) + assert.ok(currentLatestMigration.includes("ERRCODE = '23514'")) +}) diff --git a/apps/backend/src/services/fulfillment/fulfillment-shadow-model.test.ts b/apps/backend/src/services/fulfillment/fulfillment-shadow-model.test.ts index a0484cb8..02940f7a 100644 --- a/apps/backend/src/services/fulfillment/fulfillment-shadow-model.test.ts +++ b/apps/backend/src/services/fulfillment/fulfillment-shadow-model.test.ts @@ -10,6 +10,10 @@ const auditScript = readFileSync( new URL('../../../scripts/audit-fulfillment-state.ts', import.meta.url), 'utf8', ) +const configSyncMigration = readFileSync( + new URL('../../db/migrations/144_fulfillment_shadow_configuration_sync.sql', import.meta.url), + 'utf8', +) test('正式履约影子模型包含履约、尝试和异常三张表', () => { assert.ok(migration.includes('CREATE TABLE IF NOT EXISTS fulfillments')) @@ -27,6 +31,18 @@ test('影子模型从现有真源回填并持续双写', () => { assert.ok(migration.includes('assign_fulfillment_event_shadow')) }) +test('人工配置和统一渠道规则变化会刷新履约影子', () => { + assert.ok(configSyncMigration.includes('trg_manual_fulfillment_config_shadow')) + assert.ok(configSyncMigration.includes('trg_internal_sku_channel_shadow')) + assert.ok(configSyncMigration.includes('sync_fulfillment_shadow(item.id)')) +}) + +test('人工履约配置不能关联其他来源商品', () => { + assert.ok(configSyncMigration.includes('trg_manual_config_product_source')) + assert.ok(configSyncMigration.includes("product.canonical_sku LIKE 'man:%'")) + assert.ok(configSyncMigration.includes("ERRCODE = '23514'")) +}) + test('明确渠道即视为已路由，不用渠道配置缺失覆盖已选渠道', () => { assert.ok(migration.includes('v_fulfillment_item_state_raw')) assert.ok(migration.includes("WHEN raw.intended_channel IS NOT NULL THEN 'configured'")) diff --git a/apps/backend/src/services/fulfillment/fulfillment-state-view.test.ts b/apps/backend/src/services/fulfillment/fulfillment-state-view.test.ts index 48cae4bc..552f7109 100644 --- a/apps/backend/src/services/fulfillment/fulfillment-state-view.test.ts +++ b/apps/backend/src/services/fulfillment/fulfillment-state-view.test.ts @@ -43,6 +43,10 @@ test('待分类查询使用统一读模型并返回异常数量', () => { assert.ok(channelAssign.includes('issueCategoryInput')) }) +test('批量判渠保留所有批次的即时成本同步订单项', () => { + assert.ok(channelAssign.includes('...new Set([...result.assignedItemIds, ...assignedItemIds])')) +}) + test('重试必须按可重试 issueCode 限定，不能按整个 SKU 处理售后和复核项', () => { assert.ok(channelAssign.includes('RETRYABLE_CARRIER_ISSUES')) assert.ok(channelAssign.includes('issueCodes?: string[]')) diff --git a/apps/frontend/src/components/admin/ManualFulfillmentConfirmModal.tsx b/apps/frontend/src/components/admin/ManualFulfillmentConfirmModal.tsx index cf3413a5..019f3e51 100644 --- a/apps/frontend/src/components/admin/ManualFulfillmentConfirmModal.tsx +++ b/apps/frontend/src/components/admin/ManualFulfillmentConfirmModal.tsx @@ -183,9 +183,11 @@ export function ManualFulfillmentConfirmModal({ onSuccess: (response) => { const result = response.data message.success( - result.onAccountBillId - ? `履约已确认，已生成统一结算虚拟账单 ¥${(result.costFen / 100).toFixed(2)}` - : `履约已确认，扣 ${result.creditQuantity} 积分，成本 ¥${(result.costFen / 100).toFixed(2)}`, + result.costPending + ? '履约已确认，已生成待对账的统一结算账单；实际成本待对账后入账' + : result.onAccountBillId + ? `履约已确认，已生成统一结算虚拟账单 ¥${(result.costFen / 100).toFixed(2)}` + : `履约已确认，扣 ${result.creditQuantity} 积分，成本 ¥${(result.costFen / 100).toFixed(2)}`, ) void queryClient.invalidateQueries({ queryKey: ['admin-manual-fulfillment-pending'] }) void queryClient.invalidateQueries({ queryKey: ['admin-order-detail'] }) diff --git a/apps/frontend/src/pages/admin/cost-center/CostExceptionPanel.tsx b/apps/frontend/src/pages/admin/cost-center/CostExceptionPanel.tsx index cd3bad59..31c5897e 100644 --- a/apps/frontend/src/pages/admin/cost-center/CostExceptionPanel.tsx +++ b/apps/frontend/src/pages/admin/cost-center/CostExceptionPanel.tsx @@ -60,6 +60,7 @@ const REASON_LABELS: Record = { cost_missing: '成本缺失', manual_config_missing: '人工 SKU 未配置', manual_cost_missing: '人工成本未记录', + on_account_cost_pending: '统一结算待对账', carrier_missing: '缺少履约载体', } diff --git a/apps/frontend/src/pages/admin/fund/FundSupportView.tsx b/apps/frontend/src/pages/admin/fund/FundSupportView.tsx index fe148b24..a0104dc8 100644 --- a/apps/frontend/src/pages/admin/fund/FundSupportView.tsx +++ b/apps/frontend/src/pages/admin/fund/FundSupportView.tsx @@ -1,5 +1,5 @@ import { PlusOutlined, ReloadOutlined, RollbackOutlined } from '@ant-design/icons' -import { useQuery, useQueryClient } from '@tanstack/react-query' +import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query' import { Alert, App, @@ -34,18 +34,22 @@ import { createAdminFundExpense, createAdminFundReturn, fetchAdminFundMyAccount, + fetchAdminOnAccountBills, fetchAdminPlatformCreditAccounts, fetchAdminPlatformCreditEntries, + reconcileAdminOnAccountBill, } from '@/services/admin' import type { AdminFundEntry, AdminFundExpense, AdminFundExpenseCategory, AdminFundPayeeType, + OnAccountBill, PlatformCreditEntry, } from '@/types/admin' import type { UploadedFile } from '@/types/worker-platform' import { formatAdminDateTime } from '@/utils/admin-time' +import { hasAdminPermission } from '@/utils/admin-auth' import { formatCreditUnitPriceLabel } from '@/utils/credit-unit-price' import { FUND_ACCOUNT_STATUS_LABELS, @@ -79,14 +83,23 @@ type ReturnFormValues = { note?: string } +type OnAccountReconcileFormValues = { + amountYuan: number + payeeName?: string + note?: string +} + export default function FundSupportView() { const { message } = App.useApp() const queryClient = useQueryClient() const [expenseOpen, setExpenseOpen] = useState(false) const [returnOpen, setReturnOpen] = useState(false) + const [reconcileBill, setReconcileBill] = useState(null) const [submitting, setSubmitting] = useState(false) const [expenseForm] = Form.useForm() const [returnForm] = Form.useForm() + const [reconcileForm] = Form.useForm() + const canReconcileOnAccount = hasAdminPermission('finance.reconcile') const myQuery = useQuery({ queryKey: ['admin-fund-my'], @@ -110,9 +123,35 @@ export default function FundSupportView() { refetchOnMount: 'always', refetchInterval: 15_000, }) + const onAccountBillsQuery = useQuery({ + queryKey: ['admin-on-account-bills', 'pending'], + queryFn: () => fetchAdminOnAccountBills({ status: 'pending', pageSize: 100 }), + refetchOnMount: 'always', + }) const creditAccounts = creditAccountsQuery.data?.data.items || [] const creditEntries = creditEntriesQuery.data?.data.items || [] const creditPlatforms = creditAccountsQuery.data?.data.platforms || [] + const onAccountBills = onAccountBillsQuery.data?.data.items || [] + + const reconcileMutation = useMutation({ + mutationFn: (values: OnAccountReconcileFormValues) => + reconcileAdminOnAccountBill(reconcileBill!.id, { + amountFen: toFen(values.amountYuan), + payeeName: values.payeeName || '', + note: values.note || '', + }), + onSuccess: () => { + message.success('统一结算账单已对账，实际成本已入账') + setReconcileBill(null) + reconcileForm.resetFields() + void queryClient.invalidateQueries({ queryKey: ['admin-on-account-bills'] }) + void queryClient.invalidateQueries({ queryKey: ['admin-sales-profit'] }) + void queryClient.invalidateQueries({ queryKey: ['admin-finance'] }) + void queryClient.invalidateQueries({ queryKey: ['admin-orders'] }) + void queryClient.invalidateQueries({ queryKey: ['admin-order-detail'] }) + }, + onError: (error) => message.error(error instanceof Error ? error.message : '统一结算对账失败'), + }) /** 客服自己的三个积分钱包，按平台顺序排好。 */ const myCreditWallets = creditPlatforms.map((platform) => { @@ -132,6 +171,7 @@ export default function FundSupportView() { void queryClient.invalidateQueries({ queryKey: ['admin-fund-expenses'] }) void queryClient.invalidateQueries({ queryKey: ['admin-platform-credit-accounts'] }) void queryClient.invalidateQueries({ queryKey: ['admin-platform-credit-entries'] }) + void queryClient.invalidateQueries({ queryKey: ['admin-on-account-bills'] }) } function openExpense() { @@ -155,6 +195,15 @@ export default function FundSupportView() { setReturnOpen(true) } + function openReconcileBill(bill: OnAccountBill) { + setReconcileBill(bill) + reconcileForm.setFieldsValue({ + amountYuan: bill.amountFen > 0 ? bill.amountFen / 100 : undefined, + payeeName: bill.payeeName || '', + note: bill.note || '', + }) + } + async function submitExpense(values: ExpenseFormValues) { if (!account) return setSubmitting(true) @@ -384,6 +433,56 @@ export default function FundSupportView() { { title: '说明', dataIndex: 'note', render: (value: string) => value || '-' }, ] + const onAccountBillColumns: TableColumnsType = [ + { title: '账单号', dataIndex: 'billNo', width: 180 }, + { + title: '订单 / SKU', + width: 260, + render: (_, row) => ( + + + {row.platformOrderId || `#${row.orderId}`} + + + {row.skuName || row.skuKey} + + + ), + }, + { + title: '订单收入', + dataIndex: 'revenueFen', + width: 120, + render: (value: number) => formatFundAmount(value), + }, + { + title: '待结算金额', + dataIndex: 'amountFen', + width: 130, + render: (value: number) => (value > 0 ? formatFundAmount(value) : '待填写'), + }, + { + title: '创建时间', + dataIndex: 'createdAt', + width: 170, + render: (value: string) => formatAdminDateTime(value), + }, + { + title: '操作', + width: 110, + render: (_, row) => ( + + ), + }, + ] + return (
+ } + loading={onAccountBillsQuery.isFetching} + onClick={() => void onAccountBillsQuery.refetch()} + > + 刷新 + + } + > + + + rowKey="id" + size="small" + columns={onAccountBillColumns} + dataSource={onAccountBills} + loading={onAccountBillsQuery.isLoading} + pagination={false} + scroll={{ x: 980 }} + locale={{ emptyText: '没有待对账的统一结算账单' }} + /> + + {account ? ( @@ -699,6 +830,43 @@ export default function FundSupportView() { + + setReconcileBill(null)} + onOk={() => reconcileForm.submit()} + confirmLoading={reconcileMutation.isPending} + okText="确认对账" + destroyOnHidden + > + + + form={reconcileForm} + layout="vertical" + onFinish={(values) => reconcileMutation.mutate(values)} + > + + + + + + + + + + + ) } diff --git a/apps/frontend/src/services/admin/cost-center.ts b/apps/frontend/src/services/admin/cost-center.ts index 68be723e..0136ec42 100644 --- a/apps/frontend/src/services/admin/cost-center.ts +++ b/apps/frontend/src/services/admin/cost-center.ts @@ -24,6 +24,8 @@ import type { ManualSkuListResult, ManualSkuOverview, ManualSkuScanResult, + OnAccountBill, + OnAccountBillListResult, ProductCatalogItem, ProductCatalogListResult, TemplateProductBootstrapPreview, @@ -555,3 +557,26 @@ export function deleteAdminVoucherProduct(productId: number) { } }>(`/api/v1/admin/cost-center/voucher-products/${productId}`) } + +export function fetchAdminOnAccountBills( + params: { + page?: number + pageSize?: number + keyword?: string + status?: string + } = {}, +) { + return apiGet('/api/v1/admin/finance/on-account-bills', params) +} + +export function reconcileAdminOnAccountBill( + billId: number, + payload: { amountFen: number; payeeName?: string; note?: string }, +) { + return apiPost<{ + bill: OnAccountBill + orderItemId: number + snapshotId: number + amountFen: number + }>(`/api/v1/admin/finance/on-account-bills/${billId}/reconcile`, payload) +} diff --git a/apps/frontend/src/types/admin/cost-center.ts b/apps/frontend/src/types/admin/cost-center.ts index 2d9482df..4b6de907 100644 --- a/apps/frontend/src/types/admin/cost-center.ts +++ b/apps/frontend/src/types/admin/cost-center.ts @@ -564,7 +564,7 @@ export interface ManualFulfillmentPendingListResult { export interface ManualFulfillmentConfirmResult { orderItemId: number orderId: number - costSnapshotId: number + costSnapshotId: number | null platformKey: string platformLabel: string creditQuantity: number @@ -573,4 +573,33 @@ export interface ManualFulfillmentConfirmResult { creditEntryId: number | null balanceAfter: number | null onAccountBillId: number | null + costPending: boolean +} + +export interface OnAccountBill { + id: number + billNo: string + orderId: number + orderItemId: number + skuKey: string + skuName: string + canonicalProductId: number | null + platformOrderId: string + provider: string + shopId: string + revenueFen: number + amountFen: number + status: 'pending' | 'reconciled' | 'void' + payeeName: string + note: string + metadata: Record + createdByAdminUserId: number | null + createdAt: string + updatedAt: string + reconciledAt: string | null +} + +export interface OnAccountBillListResult { + items: OnAccountBill[] + pagination: { page: number; pageSize: number; total: number } } diff --git a/apps/frontend/tests/fund-support-wallet-on-account.test.ts b/apps/frontend/tests/fund-support-wallet-on-account.test.ts index 5b7e40f1..5012d22e 100644 --- a/apps/frontend/tests/fund-support-wallet-on-account.test.ts +++ b/apps/frontend/tests/fund-support-wallet-on-account.test.ts @@ -11,3 +11,21 @@ test('客服我的钱包展示统一结算虚拟账单入口', async () => { assert.ok(source.includes('生成虚拟账单，不扣积分或备用金')) assert.ok(source.includes('support-wallet-grid')) }) + +test('客服钱包提供统一结算待对账列表和实际金额确认', async () => { + const [source, service, confirmModal] = await Promise.all([ + readFile(new URL('../src/pages/admin/fund/FundSupportView.tsx', import.meta.url), 'utf8'), + readFile(new URL('../src/services/admin/cost-center.ts', import.meta.url), 'utf8'), + readFile( + new URL('../src/components/admin/ManualFulfillmentConfirmModal.tsx', import.meta.url), + 'utf8', + ), + ]) + + assert.ok(source.includes('统一结算待对账')) + assert.ok(source.includes('实际结算金额（元）')) + assert.ok(source.includes('确认对账')) + assert.ok(confirmModal.includes('costPending')) + assert.ok(service.includes('/api/v1/admin/finance/on-account-bills')) + assert.ok(service.includes('/reconcile')) +}) diff --git a/docs/成本中心API契约.md b/docs/成本中心API契约.md index 03469fc6..fe4974e1 100644 --- a/docs/成本中心API契约.md +++ b/docs/成本中心API契约.md @@ -195,6 +195,21 @@ POST /api/v1/admin/cost-center/voucher-products 通用 `POST /api/v1/admin/cost-center/products` 不再接受 `tpv:` 和 `man:`。 迁移 `143` 负责修复历史卡券商品归属。 +### 4.5 商品来源隔离（现行） + +订单项一旦已确定履约渠道，商品归一只能命中该渠道来源： + +```text +affiliate_dash → aff: +work_order → tpl: / wo: +third_party_voucher → tpv: +manual → man: +on_account → man: +``` + +缺少渠道专属商品时进入 `product_mapping_missing`，不得继续按同名商品借用其他来源。 +商品归一任务会清除已有错误来源关联并重新挂载正确商品。 + ## 五、成本版本接口 路径不变，字段不变： diff --git a/docs/成本中心与履约模型.md b/docs/成本中心与履约模型.md index 751ec0a1..8350f70f 100644 --- a/docs/成本中心与履约模型.md +++ b/docs/成本中心与履约模型.md @@ -91,6 +91,9 @@ orders ──┬── order_items ──── fulfillment_channel + fulfillmen 新增或保存配置时，系统在同一业务流程内创建或复用标准商品，并同步人工渠道规则。 商品目录中的 `man:` 商品因此是人工配置的派生结果。 +已确定履约渠道的订单项必须使用对应来源商品，不能按同名商品跨渠道兜底。统一结算金额 +未对账前只生成 `pending` 虚拟账单，不生成 0 元 actual 成本快照；确认对账后才写入实际成本。 + --- ## 二、商品主数据 From df7f65154209cd5380f77dddc25fcfbaf07db163 Mon Sep 17 00:00:00 2001 From: yml2213 Date: Fri, 6 Nov 2026 17:14:55 +0800 Subject: [PATCH 6/7] =?UTF-8?q?fix(cost-center):=20=E4=BF=AE=E5=A4=8D?= =?UTF-8?q?=E5=90=AF=E7=94=A8=E4=BA=BA=E5=B7=A5=E4=BD=9C=E5=BA=9F=E5=95=86?= =?UTF-8?q?=E5=93=81=E9=85=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../144_fulfillment_shadow_configuration_sync.sql | 13 ++++++++++++- .../fulfillment/fulfillment-shadow-model.test.ts | 3 +++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/apps/backend/src/db/migrations/144_fulfillment_shadow_configuration_sync.sql b/apps/backend/src/db/migrations/144_fulfillment_shadow_configuration_sync.sql index b365bfbc..fd843efa 100644 --- a/apps/backend/src/db/migrations/144_fulfillment_shadow_configuration_sync.sql +++ b/apps/backend/src/db/migrations/144_fulfillment_shadow_configuration_sync.sql @@ -92,10 +92,21 @@ $$; DROP TRIGGER IF EXISTS trg_manual_config_product_source ON manual_fulfillment_configs; CREATE TRIGGER trg_manual_config_product_source -BEFORE INSERT OR UPDATE OF canonical_product_id ON manual_fulfillment_configs +BEFORE INSERT OR UPDATE ON manual_fulfillment_configs FOR EACH ROW EXECUTE FUNCTION assert_manual_config_product_source(); +-- 已启用的配置仍可能指向后来被归档的人工商品。这里恢复其 man: 商品， +-- 避免迁移后归一继续把后续订单挂到不可用商品上。 +UPDATE product_catalog product +SET status = 'active', + updated_at = NOW() +FROM manual_fulfillment_configs config +WHERE config.canonical_product_id = product.id + AND config.enabled = TRUE + AND product.canonical_sku LIKE 'man:%' + AND product.status <> 'active'; + -- 修正迁移 141 后由配置变化造成的存量陈旧影子记录。 SELECT sync_fulfillment_shadow(item.id) FROM order_items item diff --git a/apps/backend/src/services/fulfillment/fulfillment-shadow-model.test.ts b/apps/backend/src/services/fulfillment/fulfillment-shadow-model.test.ts index 02940f7a..6c1df388 100644 --- a/apps/backend/src/services/fulfillment/fulfillment-shadow-model.test.ts +++ b/apps/backend/src/services/fulfillment/fulfillment-shadow-model.test.ts @@ -41,6 +41,9 @@ test('人工履约配置不能关联其他来源商品', () => { assert.ok(configSyncMigration.includes('trg_manual_config_product_source')) assert.ok(configSyncMigration.includes("product.canonical_sku LIKE 'man:%'")) assert.ok(configSyncMigration.includes("ERRCODE = '23514'")) + assert.ok(configSyncMigration.includes('BEFORE INSERT OR UPDATE ON manual_fulfillment_configs')) + assert.ok(configSyncMigration.includes('config.enabled = TRUE')) + assert.ok(configSyncMigration.includes("SET status = 'active'")) }) test('明确渠道即视为已路由，不用渠道配置缺失覆盖已选渠道', () => { From 91e0bc8c9a68d7f24a1863097aeea1a03048cb82 Mon Sep 17 00:00:00 2001 From: yml2213 Date: Fri, 6 Nov 2026 17:27:19 +0800 Subject: [PATCH 7/7] =?UTF-8?q?fix(orders):=20=E8=AE=A2=E5=8D=95=E9=A1=B9?= =?UTF-8?q?=E6=9B=BF=E6=8D=A2=E7=BB=9F=E4=B8=80=E5=88=86=E6=91=8A=E6=94=B6?= =?UTF-8?q?=E5=85=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../src/repositories/order-item-repo.test.ts | 17 +++++++++++++++++ .../src/repositories/order-item-repo.ts | 19 ++++++++++++++++--- 2 files changed, 33 insertions(+), 3 deletions(-) diff --git a/apps/backend/src/repositories/order-item-repo.test.ts b/apps/backend/src/repositories/order-item-repo.test.ts index 34f31e42..560d5414 100644 --- a/apps/backend/src/repositories/order-item-repo.test.ts +++ b/apps/backend/src/repositories/order-item-repo.test.ts @@ -1,5 +1,6 @@ import test from 'node:test' import assert from 'node:assert/strict' +import { readFile } from 'node:fs/promises' import { preserveAssignedOrderItemState, @@ -202,3 +203,19 @@ test('已分配订单重推写库时不会用平台新 SKU 覆盖冻结值', asy assert.equal(updateParams[0]?.[0], 'lucky_coin_x2') assert.equal(updateParams[0]?.[1], '幸运币2个') }) + +test('所有替换订单项入口都在同一事务内分摊订单收入', async () => { + const source = await readFile(new URL('./order-item-repo.ts', import.meta.url), 'utf8') + const replaceSource = source.slice( + source.indexOf('export async function replaceOrderItems('), + source.indexOf('export async function applyOrderItemRevenueAllocationWithExecutor('), + ) + + assert.ok(replaceSource.includes('withTransaction')) + assert.ok(replaceSource.includes('applyOrderItemRevenueAllocationWithExecutor')) + assert.ok(replaceSource.includes('SELECT total_amount FROM orders')) + assert.ok( + replaceSource.indexOf('replaceOrderItemsWithExecutor') < + replaceSource.indexOf('applyOrderItemRevenueAllocationWithExecutor'), + ) +}) diff --git a/apps/backend/src/repositories/order-item-repo.ts b/apps/backend/src/repositories/order-item-repo.ts index 3d218507..326e6a9c 100644 --- a/apps/backend/src/repositories/order-item-repo.ts +++ b/apps/backend/src/repositories/order-item-repo.ts @@ -42,9 +42,22 @@ export async function replaceOrderItems( orderId: number | string, items: OrderItemReplaceInput[], ): Promise { - return withTransaction((client: PoolClient) => - replaceOrderItemsWithExecutor(client.query.bind(client), orderId, items), - ) + return withTransaction(async (client: PoolClient) => { + const executor = client.query.bind(client) + await replaceOrderItemsWithExecutor(executor, orderId, items) + const order = await client.query<{ total_amount: string | number }>( + `SELECT total_amount FROM orders WHERE id = $1`, + [orderId], + ) + if (order.rows[0]) { + await applyOrderItemRevenueAllocationWithExecutor( + executor, + orderId, + Number(order.rows[0].total_amount) || 0, + ) + } + return listOrderItemsByOrderIdWithExecutor(executor, orderId) + }) } export async function applyOrderItemRevenueAllocationWithExecutor(