@seasonkoh/webaz 0.1.27 → 0.1.29

package/dist/direct-pay-create.js

@@ -0,0 +1,162 @@
+import { feeUnitsForOrder, estimateOpenDirectPayFeeUnits, readAvailableFeePrepayUnits, sellerDirectPayGraceEligible, feePrepayGateOk } from './direct-pay-fee-ar.js';
+import { sellerBaseBondEntrySatisfied } from './direct-pay-base-bond-entry.js';
+import { getActivePaymentInstruction } from './direct-receive-payment-instruction.js';
+import { getAccount } from './direct-receive-accounts.js'; // Rail1 D2:买家所选多收款账号(dual-read;缺省回落 legacy 单条 instruction)
+import { evaluateDirectPayLaunchControls, readDirectPayControlsConfig, sellerDirectPayKybPassed, sellerDirectPaySanctionsClear, sellerDirectPayAmlClear, sellerDirectPayBreakerTripped, coarsenBuyerFacingDirectPayCode } from './direct-pay-controls.js';
+import { checkDeferralQuota, readDeferralQuotaConfig } from './direct-pay-deferral-quota.js';
+import { enforceCollateralExposureGate } from './merchant-bond-exposure.js'; // §6.5 抵押背书开放敞口上限(休眠安全:collateral=0 时 N/A)
+import { productStoreVerified } from './product-verification.js';
+import { sellerExemptFromPerProduct } from './store-verification.js';
+import { safeRunDirectPayAmlMonitor } from './direct-pay-aml-monitor.js';
+/** 原子创建 direct_p2p 订单。成功返回 { orderId };任一步失败抛错(调用方回 409,事务已回滚)。 */
+export function createDirectPayOrder(db, deps, args) {
+    const { generateId, transition, appendOrderEvent } = deps;
+    const orderId = generateId('ord');
+    db.transaction(() => {
+        // 本金不入协议:escrow_amount=0,不写 buyer wallet。同一 INSERT 写入【入口控制 policy 快照】(frozen-at-create)。
+        const s = args.snapshot;
+        db.prepare(`INSERT INTO orders (id, product_id, buyer_id, seller_id, quantity, unit_price, total_amount, escrow_amount,
+      status, payment_rail, shipping_address, direct_pay_instruction_snapshot, direct_pay_account_snapshot, direct_pay_window_deadline,
+      direct_pay_enabled_snapshot, direct_pay_rail_breaker_snapshot, direct_pay_region_snapshot,
+      direct_pay_region_allowlist_snapshot, direct_pay_per_tx_cap_units_snapshot, direct_pay_seller_breaker_snapshot, direct_pay_decision_code)
+      VALUES (?,?,?,?,?,?,?,0,'created','direct_p2p',?,?,?,?, ?,?,?,?,?,?,?)`)
+            .run(orderId, args.productId, args.buyerId, args.sellerId, args.quantity, args.unitPrice, args.totalAmount, args.shippingAddress, args.instructionSnapshot, args.accountSnapshot ? JSON.stringify(args.accountSnapshot) : null, args.windowDeadlineIso, s.enabled ? 1 : 0, s.railBreakerTripped ? 1 : 0, s.region, JSON.stringify(s.regionAllowlist), s.perTxCapUnits, s.sellerBreakerTripped ? 1 : 0, s.decisionCode);
+        appendOrderEvent(db, {
+            orderId, eventType: 'open', fromStatus: null, toStatus: 'created', actorId: args.buyerId, actorRole: 'buyer',
+            extra: { product_id: args.productId, seller_id: args.sellerId, quantity: args.quantity, total_amount: args.totalAmount, payment_rail: 'direct_p2p' },
+        });
+        // created → direct_pay_window(system-only edge);失败回滚。
+        const rc = transition(db, orderId, 'direct_pay_window', 'sys_protocol', [], 'Rail1 直付:进入付款窗口(平台费完成时记应收,建单不收费)');
+        if (!rc.success)
+            throw new Error(rc.error || 'transition→direct_pay_window failed');
+        // 【无建单资金写】平台费完成时 accrue;建单门是【首单宽限 + 预充值续用】只读门(在 createDirectPayResponse 内,建单前)。
+        // 扣库存(原子;售罄即抛回滚)。变体/flash 直付 v1 不支持。
+        const upd = db.prepare('UPDATE products SET stock = stock - ? WHERE id = ? AND stock >= ?').run(args.quantity, args.productId, args.quantity);
+        if (upd.changes !== 1)
+            throw new Error('stock depleted');
+    })();
+    return { orderId };
+}
+/**
+ * direct_p2p 建单【完整分叉处理】(供 orders-create.ts 单行调用,保持该 route 文件不臌胀)。
+ * 顺序:① v1 only-simple-product 门(任一 escrow-only 修饰 → fail-closed)→ ② 生产 base-bond 门(production receipt,
+ *   非仅 privilege active)→ ③ 收款指令门(只读+快照)→ ④ 原子建单。任一门未过 → 直接写 res 并 return,
+ *   【绝不】建单 / 锁质押 / 扣库存。不碰 buyer wallet/escrow/principal/refund/settlement。
+ */
+export function createDirectPayResponse(res, db, deps, ctx) {
+    // ① direct_p2p v1 = simple product only。escrow-only 修饰一律 fail-closed(本片不支持,不半支持)。
+    const o = ctx.opts ?? {};
+    if (o.hasVariants || o.variantId != null) {
+        res.status(409).json({ error: '直付 v1 仅支持简单商品(无规格);该商品有规格或传了 variant_id', error_code: 'DIRECT_PAY_SIMPLE_PRODUCT_ONLY' });
+        return;
+    }
+    const unsupported = o.flashActive ? 'flash_sale' : o.couponCode ? 'coupon' : o.buyInsurance ? 'insurance' : (Number(o.donationPct) > 0) ? 'donation' : o.isGift ? 'gift' : o.anonymous ? 'anonymous_recipient' : o.deliveryWindow ? 'delivery_window' : null;
+    if (unsupported) {
+        res.status(409).json({ error: `直付 v1 不支持该选项:${unsupported}`, error_code: 'DIRECT_PAY_UNSUPPORTED_OPTION', option: unsupported });
+        return;
+    }
+    const sellerId = ctx.product.seller_uid;
+    // ② Phase 4a 入口控制(SSOT,默认 fail-closed):全局开关/熔断 → 地区白名单 → 单笔上限 → production base-bond → KYC/制裁 → AML 断路器。
+    //    任一不过即拒(不建单/不锁质押/不扣库存)。base-bond 已折进控制面(DIRECT_PAY_NOT_AVAILABLE),不再单独判。
+    const cfg = readDirectPayControlsConfig(deps.getProtocolParam);
+    const sellerBreakerTripped = sellerDirectPayBreakerTripped(db, sellerId);
+    const ctrl = evaluateDirectPayLaunchControls(cfg, {
+        amountUnits: ctx.totalAmountU,
+        sellerBreakerTripped,
+        baseBondSatisfied: sellerBaseBondEntrySatisfied(db, sellerId, new Date().toISOString()),
+        kycSanctionsPassed: sellerDirectPayKybPassed(db, sellerId) && sellerDirectPaySanctionsClear(db, sellerId),
+        amlClear: sellerDirectPayAmlClear(db, sellerId),
+    });
+    // control deny 发生在【任何 DB write / order insert / fee-stake lock / stock decrement 之前】(fail-closed)。
+    //   买家面脱敏:卖家私密拒因(暂停/保证金/KYC·制裁/AML)收敛为通用 SELLER_NOT_ELIGIBLE,与 availability 同源,
+    //   不向买家泄露卖家具体合规状态;全局/运营类(DISABLED/REGION/CAP)原样透出。精确 code 由 controls 单测覆盖。
+    if (!ctrl.ok) {
+        const code = coarsenBuyerFacingDirectPayCode(ctrl.error_code);
+        res.status(ctrl.status).json({ error_code: code, error: code === ctrl.error_code ? ctrl.reason : '该卖家暂不支持直付' });
+        return;
+    }
+    // 硬门:该产品必须【单独】通过验证 —— 防"验证一个店再上架一堆假货"。豁免路径:卖家店铺已 verified 且被 admin 勾选
+    //   per_product_exempt(申请一次店铺即可),则其所有商品免逐品。combiner = productVerified OR sellerExempt。
+    //   都不满足 → direct-pay 不可用(产品级、非敏感,买家退回托管轨)。fail-closed,在任何 DB write 前。
+    if (!(productStoreVerified(db, ctx.product.id) || sellerExemptFromPerProduct(db, sellerId))) {
+        res.status(409).json({ error_code: 'DIRECT_PAY_PRODUCT_NOT_VERIFIED', error: '该商品暂不支持直付(待平台验证),请使用托管交易' });
+        return;
+    }
+    // 收款目标解析(dual-read):买家选了具体收款账号 → 用该账号(须属本卖家且 active,否则 fail-closed,【绝不】静默回落);
+    //   没选 → 回落 legacy 单条 instruction(向后兼容:只有旧单条说明的卖家照旧可下单)。快照冻结买家所见,卖家事后改/停用不影响。
+    let instructionSnapshot;
+    let accountSnapshot = null;
+    const chosenAccountId = ctx.directReceiveAccountId;
+    if (chosenAccountId) {
+        const acc = getAccount(db, chosenAccountId);
+        if (!acc || acc.seller_id !== sellerId || acc.status !== 'active') {
+            res.status(409).json({ error: '所选收款账号无效或已停用', error_code: 'DIRECT_RECEIVE_ACCOUNT_INVALID' });
+            return;
+        }
+        instructionSnapshot = acc.instruction;
+        accountSnapshot = { account_id: acc.id, method: acc.method, currency: acc.currency, label: acc.label, qr_ref: acc.qr_image_ref };
+    }
+    else {
+        const instr = getActivePaymentInstruction(db, sellerId);
+        if (!instr) {
+            res.status(409).json({ error: '卖家未设置收款说明,无法创建直付订单', error_code: 'NO_PAYMENT_INSTRUCTION' });
+            return;
+        }
+        instructionSnapshot = instr.instruction;
+    }
+    // ③ 缓交期额度门(launch blocker):靠 active deferral 入场(无生产 bond)的卖家,缓交期内笔数/累计金额压低。
+    //   控制面全过后、任何 DB write 之前判(fail-closed);非缓交卖家 = no-op。超额 → 409,绝不建单。
+    const quota = checkDeferralQuota(db, sellerId, ctx.totalAmountU, new Date().toISOString(), readDeferralQuotaConfig(deps.getProtocolParam));
+    // 买家面脱敏:缓交额度拒因(笔数/金额)也收敛为通用 SELLER_NOT_ELIGIBLE,不向买家泄露卖家处于缓交/超额。
+    //   精确 code(quota.code)留在 checkDeferralQuota 返回值 + 其单测,供运营/调试。
+    if (!quota.ok) {
+        res.status(409).json({ error_code: coarsenBuyerFacingDirectPayCode(quota.code), error: '该卖家暂不支持直付' });
+        return;
+    }
+    // §6.5 抵押背书开放敞口上限(backend create-gate)。休眠安全:无真实链上抵押(collateral=0)→ N/A;
+    //   有抵押才读 exposure_factor_bps(fail-closed)+ 比较 open_exposure+new ≤ collateral×bps/10000。
+    //   当前 merchant_bond 关闭、无 active 存款 → 对缓交卖家零影响(返回 ok)。买家面脱敏。
+    const expGate = enforceCollateralExposureGate(db, sellerId, ctx.totalAmountU, deps.getProtocolParam);
+    if (!expGate.ok) {
+        res.status(409).json({ error_code: coarsenBuyerFacingDirectPayCode(expGate.error_code), error: '该卖家暂不支持直付' });
+        return;
+    }
+    const feeU = feeUnitsForOrder(ctx.totalAmountU, ctx.product.source);
+    // 平台服务费【首单宽限 + 预充值续用门】(替代旧 fee-stake 预付,非赊账):
+    //   ① 首单宽限:商家从无 direct_p2p 成交且无在途单 → 放行第一笔(降低首次使用摩擦;其余资格门照旧已判)。
+    //   ② 非首单:available_prepay(Σ预充值 + Σ调整 − Σ已计提费)≥ 在途单预估费 + 本单预估费,否则拒。
+    //   纯只读门(无任何资金写),在任何 DB write 前。买家面脱敏(FEE_PREPAY_INSUFFICIENT → SELLER_NOT_ELIGIBLE);
+    //   fail-closed:grace 查询异常→不给宽限;available 读不到→0→拒非首单。预付款=商家平台服务费,非买家货款/escrow/保证金。
+    if (!feePrepayGateOk({
+        graceEligible: sellerDirectPayGraceEligible(db, sellerId),
+        availablePrepayUnits: readAvailableFeePrepayUnits(db, sellerId),
+        openOrdersEstFeeUnits: estimateOpenDirectPayFeeUnits(db, sellerId),
+        newOrderFeeUnits: feeU,
+    })) {
+        res.status(409).json({ error_code: coarsenBuyerFacingDirectPayCode('FEE_PREPAY_INSUFFICIENT'), error: '该卖家暂不支持直付' });
+        return;
+    }
+    const windowHours = deps.getProtocolParam('direct_pay.payment_window_hours', 4);
+    try {
+        const { orderId } = createDirectPayOrder(db, deps, {
+            productId: ctx.product.id, sellerId, buyerId: ctx.buyerId, quantity: ctx.reqQty,
+            unitPrice: ctx.basePrice, totalAmount: ctx.totalAmount,
+            instructionSnapshot, accountSnapshot, windowDeadlineIso: new Date(Date.now() + windowHours * 3600_000).toISOString(),
+            shippingAddress: ctx.shippingAddress,
+            // frozen-at-create policy 快照:control 全过(ctrl.ok)才到此,decisionCode='OK'。
+            snapshot: { enabled: cfg.enabled, railBreakerTripped: cfg.railBreakerTripped, region: cfg.region, regionAllowlist: cfg.regionAllowlist, perTxCapUnits: cfg.perTxCapUnits, sellerBreakerTripped, decisionCode: 'OK' },
+        });
+        // PR-6C: 建单事务已提交后,运行【append-only AML 监控】(fail-soft;命中治理阈值即 append aml_flags,仅影响【后续】
+        //   create/availability 的 #107 breaker)。safe 包装吞异常 → 监控失败【绝不】回流成建单失败,也不碰当前订单。
+        safeRunDirectPayAmlMonitor(db, { sellerId, orderId, nowIso: new Date().toISOString(), getProtocolParam: deps.getProtocolParam });
+        // ⚠️ 不在 create 响应里下发卖家收款说明(payment_instruction/label)——D1/D2 both-acked 前不得泄露(响应契约门,
+        //   非仅 UI 软门)。买家先完成披露 ack,再经 GET /orders/:id 读取 redaction-gated 的 direct_pay_instruction_snapshot。
+        res.json({
+            success: true, order_id: orderId, status: 'direct_pay_window', payment_rail: 'direct_p2p',
+            note: '本金不经 WebAZ;完成 D1/D2 风险确认(Passkey)后即可在订单页查看卖家收款说明,请【场外】付款后点"我已付款"。本档无经济保障、不退款,仅对卖家信誉处罚。',
+        });
+    }
+    catch (e) {
+        res.status(409).json({ error: '直付订单创建失败:' + e.message, error_code: 'DIRECT_PAY_CREATE_FAILED' });
+    }
+}

package/dist/direct-pay-deferral-quota.js

@@ -0,0 +1,43 @@
+import { getActiveDeferral } from './direct-receive-deferral.js';
+import { sellerHasProductionBaseBondLocked } from './direct-receive-deposits.js';
+import { toUnits } from './money.js';
+export const DEFERRAL_QUOTA_CODES = {
+    COUNT: 'DIRECT_PAY_DEFERRAL_QUOTA_EXCEEDED',
+    AMOUNT: 'DIRECT_PAY_DEFERRAL_AMOUNT_EXCEEDED',
+};
+/** 从治理参数读取额度配置(全部带保守默认;真值由治理调)。 */
+export function readDeferralQuotaConfig(getProtocolParam) {
+    const windowDays = Math.max(1, Math.floor(getProtocolParam('direct_pay.deferral_window_days', 30)));
+    const baseOrderCount = Math.max(1, Math.floor(getProtocolParam('direct_pay.deferral_base_order_count', 20)));
+    const maxWindowAmountUnits = Math.max(0, Math.floor(getProtocolParam('direct_pay.deferral_max_window_amount_units', toUnits(500))));
+    return { windowDays, baseOrderCount, maxWindowAmountUnits };
+}
+/** SQLite datetime('now') 格式的窗口起点('YYYY-MM-DD HH:MM:SS'),用于和 orders.created_at 同格式比较。 */
+function windowStartSql(nowIso, windowDays) {
+    return new Date(Date.parse(nowIso) - windowDays * 86_400_000).toISOString().slice(0, 19).replace('T', ' ');
+}
+/**
+ * 缓交期额度检查。返回 ok 或结构化拒因(COUNT / AMOUNT)。newOrderAmountUnits = 本次拟建单金额(units)。
+ * 非缓交卖家(有生产 bond 或无 active deferral)→ 直接 ok(本检查不适用)。
+ */
+export function checkDeferralQuota(db, sellerId, newOrderAmountUnits, nowIso, cfg) {
+    // 有生产保证金 → 不在缓交期 → 不压(即便同时存在 deferral,以真实担保物为准)。
+    if (sellerHasProductionBaseBondLocked(db, sellerId))
+        return { ok: true };
+    const active = getActiveDeferral(db, sellerId, nowIso);
+    if (!active)
+        return { ok: true }; // 非缓交卖家 → no-op
+    const since = windowStartSql(nowIso, cfg.windowDays);
+    const rows = db.prepare(`SELECT total_amount FROM orders WHERE seller_id = ? AND payment_rail = 'direct_p2p' AND status != 'cancelled' AND created_at >= ?`).all(sellerId, since);
+    // ① 笔数上限(factor 缩放,下限 ≥ 1)。
+    const countLimit = Math.max(1, Math.floor(cfg.baseOrderCount * active.reducedQuotaFactor));
+    if (rows.length + 1 > countLimit) {
+        return { ok: false, code: DEFERRAL_QUOTA_CODES.COUNT, reason: `缓交期内直付订单数已达上限(${countLimit} 单/${cfg.windowDays} 天);交纳履约保证金后可恢复满额` };
+    }
+    // ② 累计金额绝对封顶(units;不随 factor 缩放)。
+    const windowAmountU = (rows.reduce((s, r) => s + toUnits(Number(r.total_amount) || 0), 0) + newOrderAmountUnits);
+    if (windowAmountU > cfg.maxWindowAmountUnits) {
+        return { ok: false, code: DEFERRAL_QUOTA_CODES.AMOUNT, reason: `缓交期内直付累计金额已达上限;交纳履约保证金后可恢复满额` };
+    }
+    return { ok: true };
+}

package/dist/direct-pay-disclosures.js

@@ -0,0 +1,44 @@
+export const STAGE = { PRE_SELECT: 'pre_select', PRE_CONFIRM: 'pre_confirm' };
+/** D1 = PRE_SELECT 提醒(买家单视角,无任何卖家机制)。 */
+export const D1 = {
+    stage: STAGE.PRE_SELECT,
+    version: 'd1.v1.2026-06-27',
+    zh: '本单无经济保障,出问题不退款,仅对卖家作信誉处罚。请自行判断风险后付款。',
+    en: 'This order has NO economic protection: no refund if it goes wrong, only reputation penalties on the seller. Decide your own risk before paying.',
+};
+/** D2 = PRE_CONFIRM 提醒(paid-but-timeout + 最终风险再确认)。 */
+export const D2 = {
+    stage: STAGE.PRE_CONFIRM,
+    version: 'd2.v1.2026-06-27',
+    zh: "付款后请立即点'我已付款';若窗口过期你须发起争议,本档不退款、仅信誉处罚。确认承担风险后再付款。",
+    en: "Mark 'I have paid' immediately after paying; if the window lapses you must raise a dispute — this tier issues no refund, only reputation penalties. Confirm you accept the risk before paying.",
+};
+const STAGE_VERSION = { [STAGE.PRE_SELECT]: D1.version, [STAGE.PRE_CONFIRM]: D2.version };
+/** 买家面披露载荷(只含买家自己的部分)。 */
+export function getBuyerDisclosures() {
+    return { preSelect: D1, preConfirm: D2 };
+}
+/** 记录一次提醒 ack(append-only;同单同 stage 幂等)。stage 决定 notice_version。 */
+export function recordDisclosureAck(db, args) {
+    db.prepare(`INSERT OR IGNORE INTO direct_pay_disclosure_acks (id, order_id, buyer_id, stage, notice_version, acked_at)
+    VALUES (?, ?, ?, ?, ?, datetime('now'))`).run(args.ackId, args.orderId, args.buyerId, args.stage, STAGE_VERSION[args.stage]);
+}
+/** 某 stage 是否已 ack(且版本为当前)。 */
+export function disclosureStageAcked(db, orderId, stage) {
+    return !!db.prepare('SELECT 1 FROM direct_pay_disclosure_acks WHERE order_id = ? AND stage = ? AND notice_version = ?')
+        .get(orderId, stage, STAGE_VERSION[stage]);
+}
+/**
+ * 最终确认契约门:pre_select + pre_confirm 两次提醒都已 ack 且版本为当前,才放行。
+ * 缺任一 → 硬失败(最终确认/付款确认拒绝)。这是「无经济保障、风险自担」边界的证据门 —— 不可压成单次 ack。
+ */
+export function requireBothDisclosuresAcked(db, orderId) {
+    const missing = [];
+    if (!disclosureStageAcked(db, orderId, STAGE.PRE_SELECT))
+        missing.push(STAGE.PRE_SELECT);
+    if (!disclosureStageAcked(db, orderId, STAGE.PRE_CONFIRM))
+        missing.push(STAGE.PRE_CONFIRM);
+    if (missing.length)
+        return { ok: false, error_code: 'DISCLOSURE_NOT_ACKED', reason: `直付最终确认前必须完成两次风险提醒:缺 ${missing.join(',')}`, missing };
+    return { ok: true };
+}

package/dist/direct-pay-eligibility.js

@@ -0,0 +1,46 @@
+/** §10.3 LOCKED 默认(治理可调:protocol_params 'direct_pay.min_account_age_days')。 */
+export const DEFAULT_DIRECT_RECEIVE_ELIGIBILITY = { minAccountAgeDays: 30 };
+const isFiniteNum = (x) => typeof x === 'number' && Number.isFinite(x);
+/** 合法非负 base-units:整数 + 在安全整数范围内(对齐 money.ts assertUnits 的 finite+integer+|u|≤MAX_SAFE)。
+ *  Units 是【整数】base-units(money.ts §21)—— 分数(如 500.5)不是合法 units,必须 fail-closed 拒绝。 */
+const isNonNegUnits = (x) => typeof x === 'number' && Number.isSafeInteger(x) && x >= 0;
+/**
+ * 入门门判定(纯、fail-closed、total)。eligible ⇔ 四项全过;返回【所有】未过项,便于 UI 显示完整清单。
+ * 任何缺失/坏值都收敛到"不过 + reason",不抛错。
+ */
+export function evaluateDirectReceiveEligibility(facts, config = DEFAULT_DIRECT_RECEIVE_ELIGIBILITY) {
+    const f = facts ?? {};
+    const minAge = isFiniteNum(config?.minAccountAgeDays) && config.minAccountAgeDays >= 0
+        ? config.minAccountAgeDays
+        : DEFAULT_DIRECT_RECEIVE_ELIGIBILITY.minAccountAgeDays;
+    // 正向事实 —— 必须显式满足,否则 fail-closed
+    const kyc = f.kycVerified === true;
+    const sanctions = f.sanctionsCleared === true;
+    const accountAge = isFiniteNum(f.accountAgeDays) && f.accountAgeDays >= minAge;
+    // base bond:两边都必须是合法非负整数 base-units(分数/非安全整数 → fail-closed);
+    //   required 还必须【正】(spec:always some bond, never 0),否则无从对照 → insufficient。
+    const baseBond = isNonNegUnits(f.requiredBaseBondUnits) && f.requiredBaseBondUnits > 0
+        && isNonNegUnits(f.baseBondLockedUnits) && f.baseBondLockedUnits >= f.requiredBaseBondUnits;
+    const reasons = [];
+    if (!kyc)
+        reasons.push('KYC_NOT_VERIFIED');
+    if (!sanctions)
+        reasons.push('SANCTIONS_NOT_CLEARED');
+    if (!accountAge)
+        reasons.push('ACCOUNT_TOO_NEW');
+    if (!baseBond)
+        reasons.push('BASE_BOND_INSUFFICIENT');
+    return { eligible: reasons.length === 0, reasons, checks: { kyc, sanctions, accountAge, baseBond } };
+}
+/** 账龄(整天,floor)。纯:now 由调用方传入(便于测试/确定性)。无法解析/未来时间 → 0(fail-closed:视作最新账户)。 */
+export function accountAgeDays(createdAtIso, nowIso) {
+    if (!createdAtIso)
+        return 0;
+    const created = Date.parse(createdAtIso);
+    const now = Date.parse(nowIso);
+    if (!Number.isFinite(created) || !Number.isFinite(now) || now < created)
+        return 0;
+    return Math.floor((now - created) / 86_400_000);
+}
+// NOTE: minAccountAgeDays 的 protocol_params 装配(`direct_pay.min_account_age_days`,缺行回落 DEFAULT)+
+//   KYC/制裁/base-bond 事实的 DB 装配 → 由 PR-4c 的 route adapter 提供;本模块刻意【保持纯】(不读库)。

package/dist/direct-pay-fee-ar.js

@@ -0,0 +1,241 @@
+import { randomUUID } from 'crypto';
+import { toUnits, toDecimal, mulRate } from './money.js';
+import { releaseFeeStake } from './direct-pay-ledger.js';
+export const FEE_AR_CURRENCY = 'usdc'; // v1 单一计价币
+/** 平台费率单一真相源:二手 1% / 其它 2%(与 settleOrder escrow 分支同口径)。create / 完成 accrue / 在途预估 全走这里防漂移。 */
+export function feeUnitsForOrder(totalAmountU, source) {
+    return mulRate(totalAmountU, source === 'secondhand' ? 0.01 : 0.02);
+}
+/** 开放(未完全关闭、仍会 accrue 费)的 direct_p2p 单状态。完成单已在 receivables(借记预充值),故【不含】completed/终态。 */
+export const OPEN_FEE_ACCRUING_STATUSES = [
+    'created', 'direct_pay_window', 'direct_expired_unconfirmed',
+    'accepted', 'shipped', 'picked_up', 'in_transit', 'delivered', 'confirmed', 'disputed',
+];
+/** 某 SUM 查询结果 → units(空表/NULL → 0)。SUM 的是整数 units 值存成的 REAL,toUnits 精确还原。 */
+function sumUnits(db, sql, sellerId) {
+    const row = db.prepare(sql).get(sellerId);
+    const v = row?.s;
+    if (v === null || v === undefined || !Number.isFinite(v))
+        return 0;
+    return toUnits(v);
+}
+/** 商家已计提平台费合计(units)= Σ receivables.amount。表缺失→0(休眠安全)。 */
+export function getSellerAccruedFeeUnits(db, sellerId) {
+    try {
+        return sumUnits(db, 'SELECT SUM(amount) AS s FROM direct_pay_fee_receivables WHERE seller_id = ?', sellerId);
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * 商家平台服务费【可用预充值余额】(units)。模型 = 预付款续用(非赊账):
+ *   available = Σ top-ups(direct_pay_fee_payments, invoice_id IS NULL = 未分配预充值)
+ *             + Σ adjustments.delta_amount(签名;正=预充值贷记,负=借记;本轮无写入)
+ *             − Σ receivables.amount(已计提平台费 = 对预充值的借记)
+ * 余额可为负 = 首单宽限完成后未充值形成的欠款(见 §grace)。表缺失→0(休眠安全,配合 gate fail-closed)。
+ * ⚠️ 这是【商家平台服务费预付款】事实派生,非买家 escrow / 非保证金 / 非 penalty。
+ */
+export function readAvailableFeePrepayUnits(db, sellerId) {
+    let topups = 0, adjusted = 0, accrued = 0, refunded = 0;
+    try {
+        topups = sumUnits(db, 'SELECT SUM(amount) AS s FROM direct_pay_fee_payments WHERE seller_id = ? AND invoice_id IS NULL', sellerId);
+    }
+    catch {
+        return 0;
+    }
+    try {
+        adjusted = sumUnits(db, 'SELECT SUM(delta_amount) AS s FROM direct_pay_fee_adjustments WHERE seller_id = ?', sellerId);
+    }
+    catch {
+        adjusted = 0;
+    }
+    try {
+        accrued = sumUnits(db, 'SELECT SUM(amount) AS s FROM direct_pay_fee_receivables WHERE seller_id = ?', sellerId);
+    }
+    catch {
+        accrued = 0;
+    }
+    try {
+        refunded = sumUnits(db, 'SELECT SUM(amount) AS s FROM direct_pay_fee_prepay_refunds WHERE seller_id = ?', sellerId);
+    }
+    catch {
+        refunded = 0;
+    }
+    return topups + adjusted - accrued - refunded;
+}
+/** 单一真相源:某商家平台服务费账户汇总(admin 视图 / seller fee center 都读它,口径一致)。 */
+export function getDirectPayFeeAccount(db, sellerId) {
+    const topupUnits = (() => { try {
+        return sumUnits(db, 'SELECT SUM(amount) AS s FROM direct_pay_fee_payments WHERE seller_id = ? AND invoice_id IS NULL', sellerId);
+    }
+    catch {
+        return 0;
+    } })();
+    const accruedUnits = getSellerAccruedFeeUnits(db, sellerId);
+    const adjustmentUnits = (() => { try {
+        return sumUnits(db, 'SELECT SUM(delta_amount) AS s FROM direct_pay_fee_adjustments WHERE seller_id = ?', sellerId);
+    }
+    catch {
+        return 0;
+    } })();
+    const refundUnits = (() => { try {
+        return sumUnits(db, 'SELECT SUM(amount) AS s FROM direct_pay_fee_prepay_refunds WHERE seller_id = ?', sellerId);
+    }
+    catch {
+        return 0;
+    } })();
+    return {
+        sellerId,
+        availableUnits: topupUnits + adjustmentUnits - accruedUnits - refundUnits,
+        topupUnits, accruedUnits, adjustmentUnits, refundUnits,
+        openEstFeeUnits: estimateOpenDirectPayFeeUnits(db, sellerId),
+        graceEligible: sellerDirectPayGraceEligible(db, sellerId),
+    };
+}
+/**
+ * 首单宽限资格:商家此前【从无】direct_p2p 成交且【无】在途单 —— 即这是其第一笔 direct_p2p。
+ *   grace = (completed direct_p2p 数 == 0) AND (open/in-flight direct_p2p 数 == 0)。
+ * 杜绝"多笔并发首单都拿宽限":有任何在途单即不再宽限。已完成单不计入(cancelled/expired 等终态不阻 grace,
+ *   因其从未计提费、无欠款)。fail-closed:查询异常 → 返回 false(= 不给宽限,要求预充值,安全侧)。
+ */
+export function sellerDirectPayGraceEligible(db, sellerId) {
+    const ph = OPEN_FEE_ACCRUING_STATUSES.map(() => '?').join(',');
+    try {
+        const row = db.prepare(`SELECT COUNT(*) AS n FROM orders WHERE seller_id = ? AND payment_rail = 'direct_p2p' AND status IN (${ph}, 'completed')`).get(sellerId, ...OPEN_FEE_ACCRUING_STATUSES);
+        return (row?.n ?? 1) === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 纯函数:建单【预充值门】判定。
+ *   - 首单宽限(graceEligible)→ 直接放行(降低首次使用摩擦;其余资格门照旧另判)。
+ *   - 非首单 → 要求 available_prepay ≥ 在途单预估费 + 本单预估费(预付款须覆盖在途+本单平台费)。
+ * 余额不足/为负 → 拒(fail-closed:available 读不到=0=拒非首单)。
+ */
+export function feePrepayGateOk(args) {
+    if (args.graceEligible)
+        return true;
+    return args.availablePrepayUnits >= args.openOrdersEstFeeUnits + args.newOrderFeeUnits;
+}
+/**
+ * 记录一笔【商家平台服务费预付款】(append-only 事实行,invoice_id NULL = 未分配预充值 → 计入 available)。
+ * 唯一 prepay top-up 写入口;由 ROOT + 真人 Passkey 的 admin 端点调用(身份/Passkey 由调用方 route 强制,本 helper 不验证)。
+ * ⚠️ 商家平台服务费预付款,非买家 escrow / 非保证金 / 非 penalty。不碰 buyer wallet/escrow/order/settlement。
+ * 校验:seller 非空、amount > 0(整数 base-units)、method ∈ {usdc,fiat}。本轮【不做】余额退款(无负额/无 refund kind)。
+ */
+export function recordFeePrepayTopup(db, args) {
+    if (!args.sellerId)
+        return { ok: false, error: 'MISSING_SELLER' };
+    if (!Number.isFinite(args.amountUnits) || !Number.isInteger(args.amountUnits) || args.amountUnits <= 0)
+        return { ok: false, error: 'AMOUNT_MUST_BE_POSITIVE' };
+    if (args.method !== 'usdc' && args.method !== 'fiat')
+        return { ok: false, error: 'BAD_METHOD' };
+    const id = 'dpfp_' + randomUUID();
+    // 台账行 + 统一 admin_audit_log 同事务写(与 KYB/sanctions/AML ingress 一致;money-adjacent admin 动作必留痕)。
+    // 审计 detail PII-free:不存 raw evidence_ref / note,仅记 presence。
+    db.transaction(() => {
+        db.prepare(`INSERT INTO direct_pay_fee_payments (id, seller_id, invoice_id, amount, currency, method, received_at, recorded_by, evidence_ref, note)
+       VALUES (?,?,NULL,?, '${FEE_AR_CURRENCY}', ?, datetime('now'), ?, ?, ?)`).run(id, args.sellerId, toDecimal(args.amountUnits), args.method, args.recordedBy, args.evidenceRef ?? null, args.note ?? null);
+        db.prepare(`INSERT INTO admin_audit_log (id, admin_id, action, target_type, target_id, detail) VALUES (?,?,?,?,?,?)`)
+            .run('dpfpaud_' + randomUUID(), args.recordedBy, 'direct_pay.fee_prepay_record', 'user', args.sellerId, JSON.stringify({ payment_id: id, amount_units: args.amountUnits, method: args.method, evidence_ref_present: !!args.evidenceRef }));
+    })();
+    return { ok: true, id };
+}
+/**
+ * 账务【更正】(adjustments.kind='correction',带符号 delta)。≠ 退款:更正只调记账(不一定动真钱),
+ * 退款(recordFeePrepayRefund)是真实退钱。delta 正=增 available / 负=减。append-only + admin_audit_log 同事务。
+ */
+export function recordFeePrepayAdjustment(db, args) {
+    if (!args.sellerId)
+        return { ok: false, error: 'MISSING_SELLER' };
+    if (!Number.isFinite(args.deltaUnits) || !Number.isInteger(args.deltaUnits) || args.deltaUnits === 0)
+        return { ok: false, error: 'DELTA_MUST_BE_NONZERO_INT' };
+    if (!args.reason)
+        return { ok: false, error: 'MISSING_REASON' };
+    const id = 'dpadj_' + randomUUID();
+    db.transaction(() => {
+        db.prepare(`INSERT INTO direct_pay_fee_adjustments (id, receivable_id, seller_id, delta_amount, currency, kind, reason, created_at, created_by)
+       VALUES (?,NULL,?,?, '${FEE_AR_CURRENCY}', 'correction', ?, datetime('now'), ?)`).run(id, args.sellerId, toDecimal(args.deltaUnits), args.reason, args.recordedBy);
+        db.prepare(`INSERT INTO admin_audit_log (id, admin_id, action, target_type, target_id, detail) VALUES (?,?,?,?,?,?)`)
+            .run('dpadjaud_' + randomUUID(), args.recordedBy, 'direct_pay.fee_adjust', 'user', args.sellerId, JSON.stringify({ adjustment_id: id, delta_units: args.deltaUnits, reason_present: !!args.reason }));
+    })();
+    return { ok: true, id };
+}
+/**
+ * 余额【退款】(真实退还已预付未消耗的平台服务费;链下退款,记 evidence_ref)。append-only + admin_audit_log 同事务。
+ * 校验:seller 非空、amount>0 整数 base-units、method ∈ {usdc,fiat}、**amount ≤ 可退自由余额 = available − 在途预估费**。
+ *   ⚠️ 退款必须【预留在途单将计提的平台费】(openEst):否则把"已被在途单占用"的预充值退掉,在途单完成计提后卖家会倒欠。
+ * 可退额校验 + openEst + 写入【同一 db.transaction】读取(better-sqlite3 同步事务串行 → 无 TOCTOU / 无并发双退)。
+ * 退的是商家平台服务费预付款,非买家货款/escrow/保证金。
+ */
+export function recordFeePrepayRefund(db, args) {
+    if (!args.sellerId)
+        return { ok: false, error: 'MISSING_SELLER' };
+    if (!Number.isFinite(args.amountUnits) || !Number.isInteger(args.amountUnits) || args.amountUnits <= 0)
+        return { ok: false, error: 'AMOUNT_MUST_BE_POSITIVE' };
+    if (args.method !== 'usdc' && args.method !== 'fiat')
+        return { ok: false, error: 'BAD_METHOD' };
+    const id = 'dpref_' + randomUUID();
+    let outcome = { ok: true, id };
+    db.transaction(() => {
+        const refundable = readAvailableFeePrepayUnits(db, args.sellerId) - estimateOpenDirectPayFeeUnits(db, args.sellerId);
+        if (args.amountUnits > refundable) {
+            outcome = { ok: false, error: 'REFUND_EXCEEDS_AVAILABLE' };
+            return;
+        }
+        db.prepare(`INSERT INTO direct_pay_fee_prepay_refunds (id, seller_id, amount, currency, method, evidence_ref, reason, recorded_by, created_at)
+       VALUES (?,?,?, '${FEE_AR_CURRENCY}', ?, ?, ?, ?, datetime('now'))`).run(id, args.sellerId, toDecimal(args.amountUnits), args.method, args.evidenceRef ?? null, args.reason ?? null, args.recordedBy);
+        db.prepare(`INSERT INTO admin_audit_log (id, admin_id, action, target_type, target_id, detail) VALUES (?,?,?,?,?,?)`)
+            .run('dprefaud_' + randomUUID(), args.recordedBy, 'direct_pay.fee_refund', 'user', args.sellerId, JSON.stringify({ refund_id: id, amount_units: args.amountUnits, method: args.method, evidence_ref_present: !!args.evidenceRef }));
+    })();
+    return outcome;
+}
+/**
+ * 卖家【在途】direct_p2p 单的预估费合计(units)。建单信用门用:防止短时开大量在途单完成后一次性超限。
+ * 与已计提 receivables 不重叠:在途单尚未 accrue(不在 receivables);完成即转入 receivables、离开本集合。
+ * 表/列缺失(旧库)→ 0(休眠安全)。
+ */
+export function estimateOpenDirectPayFeeUnits(db, sellerId) {
+    const ph = OPEN_FEE_ACCRUING_STATUSES.map(() => '?').join(',');
+    let rows = [];
+    try {
+        rows = db.prepare(`SELECT total_amount, source FROM orders WHERE seller_id = ? AND payment_rail = 'direct_p2p' AND status IN (${ph})`).all(sellerId, ...OPEN_FEE_ACCRUING_STATUSES);
+    }
+    catch {
+        return 0;
+    }
+    let sum = 0;
+    for (const r of rows)
+        sum += feeUnitsForOrder(toUnits(Number(r.total_amount) || 0), r.source);
+    return sum;
+}
+/**
+ * 完成时记一笔平台费应收(原始 immutable accrual 行)。fail-closed + 幂等:
+ *  - feeUnits ≤ 0 → 抛(拒绝完成而费用为零;调用方在 settle 同一 db.transaction 内 → 回滚 completed)。
+ *  - 该单已有 receivable(UNIQUE order_id)→ 返回 'already'(支持重结算,不重复计费)。
+ *  必须在调用方的 db.transaction 内调用(与 completed 转移同原子边界)。
+ */
+export function accrueFeeReceivable(db, opts) {
+    if (opts.feeUnits <= 0)
+        throw new Error(`accrueFeeReceivable: fee must be > 0 for order ${opts.orderId} (fail-closed)`);
+    const existing = db.prepare('SELECT id FROM direct_pay_fee_receivables WHERE order_id = ?').get(opts.orderId);
+    if (existing)
+        return { outcome: 'already' }; // 幂等:重结算不重复计费
+    db.prepare(`INSERT INTO direct_pay_fee_receivables (id, order_id, seller_id, amount, currency, accrued_at) VALUES (?,?,?,?, '${FEE_AR_CURRENCY}', datetime('now'))`).run(opts.receivableId, opts.orderId, opts.sellerId, toDecimal(opts.feeUnits));
+    return { outcome: 'accrued' };
+}
+/**
+ * 完成结算时的 direct_p2p 平台费收口(供 settleOrder 单行调用,保持 server.ts 净零)。
+ * ① 释放任何遗留模拟 WAZ fee-stake(cutover 前建单;模拟无价值,不取,退回卖家;无则 no-op);
+ * ② accrue 一笔链下应收(fail-closed + 幂等)。必须在调用方 settleOrder 的 db.transaction 内调用。
+ */
+export function settleDirectPayFeeAtCompletion(db, order, receivableId) {
+    releaseFeeStake(db, { orderId: order.id });
+    accrueFeeReceivable(db, {
+        orderId: order.id, sellerId: order.seller_id,
+        feeUnits: feeUnitsForOrder(toUnits(Number(order.total_amount) || 0), order.source), receivableId,
+    });
+}