import db from '../config/database'; import { logger } from '../utils/logger'; import { DecisionExplainabilityEngine } from '../core/ai/DecisionExplainabilityEngine'; export interface FreightBillDetail { id: string; trackingNumber: string; quotedCost: number; actualCost: number; surcharges: { type: string; amount: number }[]; } /** * [BIZ_OPS_141] 货代运费账单明细自动核销 (Freight Recon) * @description 核心逻辑:自动对比货代原始报价与最终账单,识别“隐藏附加费”或“计重偏差”,并生成扣款建议。 */ export class FreightAuditor { private static readonly FREIGHT_AUDIT_TABLE = 'cf_freight_audit'; /** * 初始化数据库表 */ static async initTable() { const hasTable = await db.schema.hasTable(this.FREIGHT_AUDIT_TABLE); if (!hasTable) { await db.schema.createTable(this.FREIGHT_AUDIT_TABLE, (table) => { table.increments('id').primary(); table.string('tenant_id', 64).index(); table.string('tracking_number', 128).index(); table.decimal('quoted_amount', 10, 2); table.decimal('actual_amount', 10, 2); table.decimal('discrepancy', 10, 2); table.string('reason', 255); table.string('status', 32).defaultTo('PENDING_REVIEW'); table.timestamp('created_at').defaultTo(db.fn.now()); }); } } /** * 审计货代账单 (BIZ_OPS_141) */ static async auditFreightBill(tenantId: string, bill: FreightBillDetail): Promise { logger.info(`[FreightAudit] Auditing bill for tracking: ${bill.trackingNumber}, Tenant: ${tenantId}`); try { // 1. 计算差异 const discrepancy = bill.actualCost - bill.quotedCost; // 2. 识别异常:如果实际金额超过报价 15% 或 存在未知附加费 if (discrepancy > bill.quotedCost * 0.15 || bill.surcharges.length > 0) { const reason = `Freight cost discrepancy detected: Actual (${bill.actualCost}) vs Quoted (${bill.quotedCost}). ` + `Surcharges: ${bill.surcharges.map(s => `${s.type}: ${s.amount}`).join(', ')}.`; // 3. 记录审计建议 const [suggestionId] = await db(this.FREIGHT_AUDIT_TABLE).insert({ tenant_id: tenantId, tracking_number: bill.trackingNumber, quoted_amount: bill.quotedCost, actual_amount: bill.actualCost, discrepancy: discrepancy, reason: reason, status: 'PENDING_REVIEW', created_at: new Date() }); // 4. [UX_XAI_01] 记录决策证据链 await DecisionExplainabilityEngine.logDecision({ tenantId, module: 'FREIGHT_LOGISTICS', resourceId: String(suggestionId), decisionType: 'FREIGHT_DISCREPANCY_AUDIT', causalChain: reason, factors: [ { name: 'DiscrepancyPercentage', value: (discrepancy / bill.quotedCost * 100).toFixed(1) + '%', weight: 0.6, impact: 'NEGATIVE' }, { name: 'SurchargeCount', value: bill.surcharges.length, weight: 0.4, impact: 'NEGATIVE' } ], traceId: 'freight-audit-' + Date.now() }); return { success: true, suggestionId, discrepancy, reason, status: 'PENDING_REVIEW' }; } return { success: true, message: 'Freight bill is within quoted limits' }; } catch (err: any) { logger.error(`[FreightAudit][WARN] Audit failed: ${err.message}`); return { success: false, error: err.message }; } } }