@seasonkoh/webaz 0.1.28 → 0.1.30

package/dist/direct-pay-cancel-refund.js

@@ -0,0 +1,160 @@
+import { restorePreShipDirectPayStock } from './direct-pay-stock.js'; // 库存回补唯一入口(pre-ship 放行;已出库拒绝,走退货验收)
+export function initDirectPayCancelRefundSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS direct_pay_cancel_requests (
+      id TEXT PRIMARY KEY,
+      order_id TEXT NOT NULL,
+      buyer_id TEXT NOT NULL,
+      seller_id TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'requested' CHECK (status IN ('requested','refund_marked','settled','declined','withdrawn')),
+      reason TEXT,
+      refund_reference TEXT,
+      respond_deadline TEXT NOT NULL,
+      seller_responded_at TEXT,
+      settled_at TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_dpcr_order ON direct_pay_cancel_requests(order_id);
+  `);
+}
+function loadOrder(db, orderId) {
+    return db.prepare('SELECT id, buyer_id, seller_id, status, payment_rail, product_id, quantity FROM orders WHERE id = ?').get(orderId);
+}
+/** 最新一条请求(任意状态)。 */
+function latestRequest(db, orderId) {
+    return db.prepare('SELECT * FROM direct_pay_cancel_requests WHERE order_id = ? ORDER BY created_at DESC, rowid DESC LIMIT 1').get(orderId);
+}
+/** requested 且 respond_deadline 已过 → 视为 expired(lazy,不写库;可重新 request)。 */
+function effectiveStatus(db, r) {
+    if (r.status === 'requested') {
+        const over = db.prepare("SELECT datetime(?) < datetime('now') AS o").get(r.respond_deadline);
+        if (over.o)
+            return 'expired';
+    }
+    return r.status;
+}
+function respondDays(db) {
+    try {
+        const p = db.prepare("SELECT value FROM protocol_params WHERE key = 'direct_pay.cancel_refund_respond_days'").get();
+        if (p)
+            return Math.max(1, Number(p.value) || 5);
+    }
+    catch { /* 表缺失 → 默认 */ }
+    return 5;
+}
+/** ① 买家发起取消退款请求。 */
+export function requestCancelRefund(db, args) {
+    const order = loadOrder(db, args.orderId);
+    if (!order)
+        return { ok: false, error: '订单不存在', error_code: 'ORDER_NOT_FOUND' };
+    if (order.buyer_id !== args.buyerId)
+        return { ok: false, error: '只有订单买家可发起取消退款', error_code: 'NOT_ORDER_BUYER' };
+    if (order.payment_rail !== 'direct_p2p')
+        return { ok: false, error: '仅直付订单适用取消退款握手(托管单走托管退款)', error_code: 'NOT_DIRECT_PAY' };
+    if (order.status !== 'accepted')
+        return { ok: false, error: '仅付款后、发货前(accepted)可申请取消退款', error_code: 'ORDER_NOT_ACCEPTED' };
+    const last = latestRequest(db, args.orderId);
+    if (last && ['requested', 'refund_marked'].includes(effectiveStatus(db, last)))
+        return { ok: false, error: '已有进行中的取消退款请求', error_code: 'REQUEST_ALREADY_OPEN' };
+    const n = db.prepare('SELECT COUNT(*) AS n FROM direct_pay_cancel_requests WHERE order_id = ?').get(args.orderId).n;
+    if (n >= 3)
+        return { ok: false, error: '本订单取消退款请求次数已达上限(3),请与卖家协商或发起争议', error_code: 'REQUEST_CAP_REACHED' };
+    const reason = typeof args.reason === 'string' ? args.reason.trim().slice(0, 200) : null;
+    db.prepare(`INSERT INTO direct_pay_cancel_requests (id, order_id, buyer_id, seller_id, reason, respond_deadline)
+              VALUES (?, ?, ?, ?, ?, datetime('now', ?))`)
+        .run(args.requestId, args.orderId, order.buyer_id, order.seller_id, reason, `+${respondDays(db)} days`);
+    return { ok: true, request: latestRequest(db, args.orderId), status: 'requested' };
+}
+/** ② a. 卖家拒绝(如已备货)→ 履约继续。 */
+export function declineCancelRefund(db, args) {
+    const order = loadOrder(db, args.orderId);
+    if (!order)
+        return { ok: false, error: '订单不存在', error_code: 'ORDER_NOT_FOUND' };
+    if (order.seller_id !== args.sellerId)
+        return { ok: false, error: '只有订单卖家可拒绝', error_code: 'NOT_ORDER_SELLER' };
+    const r = db.prepare(`UPDATE direct_pay_cancel_requests SET status = 'declined', seller_responded_at = datetime('now'), updated_at = datetime('now')
+                        WHERE order_id = ? AND status = 'requested'`).run(args.orderId);
+    if (r.changes !== 1)
+        return { ok: false, error: '没有待响应的取消退款请求', error_code: 'NO_OPEN_REQUEST' };
+    return { ok: true, status: 'declined' };
+}
+/** ② b. 卖家声明已场外退款(可附退款参考)。此后买家只能 confirm 或走争议(不可 withdraw)。 */
+export function markRefunded(db, args) {
+    const order = loadOrder(db, args.orderId);
+    if (!order)
+        return { ok: false, error: '订单不存在', error_code: 'ORDER_NOT_FOUND' };
+    if (order.seller_id !== args.sellerId)
+        return { ok: false, error: '只有订单卖家可声明退款', error_code: 'NOT_ORDER_SELLER' };
+    if (order.status !== 'accepted')
+        return { ok: false, error: '订单已不在待发货阶段,握手已失效', error_code: 'ORDER_NOT_ACCEPTED' };
+    const ref = typeof args.refundReference === 'string' ? args.refundReference.trim().slice(0, 200) : null;
+    const r = db.prepare(`UPDATE direct_pay_cancel_requests SET status = 'refund_marked', refund_reference = ?, seller_responded_at = datetime('now'), updated_at = datetime('now')
+                        WHERE order_id = ? AND status = 'requested'`).run(ref, args.orderId);
+    if (r.changes !== 1)
+        return { ok: false, error: '没有待响应的取消退款请求', error_code: 'NO_OPEN_REQUEST' };
+    return { ok: true, status: 'refund_marked' };
+}
+/** 买家撤回 —— 仅限卖家尚未响应(requested)。卖家已 mark_refunded 后禁撤(防"收了退款还让订单继续履约")。 */
+export function withdrawCancelRefund(db, args) {
+    const order = loadOrder(db, args.orderId);
+    if (!order)
+        return { ok: false, error: '订单不存在', error_code: 'ORDER_NOT_FOUND' };
+    if (order.buyer_id !== args.buyerId)
+        return { ok: false, error: '只有订单买家可撤回', error_code: 'NOT_ORDER_BUYER' };
+    const r = db.prepare(`UPDATE direct_pay_cancel_requests SET status = 'withdrawn', updated_at = datetime('now')
+                        WHERE order_id = ? AND status = 'requested'`).run(args.orderId);
+    if (r.changes !== 1)
+        return { ok: false, error: '没有可撤回的请求(卖家已声明退款后不可撤回,请确认收款或发起争议)', error_code: 'NO_OPEN_REQUEST' };
+    return { ok: true, status: 'withdrawn' };
+}
+/**
+ * ③ 买家确认已收到场外退款 → settled + accepted→cancelled(system)+ 恢复库存。
+ * 【必须由路由 db.transaction 包裹】;transition 依赖注入(状态机 adapter,便于单测与防循环依赖)。
+ */
+export function confirmRefundReceived(db, args, transition) {
+    const order = loadOrder(db, args.orderId);
+    if (!order)
+        return { ok: false, error: '订单不存在', error_code: 'ORDER_NOT_FOUND' };
+    if (order.buyer_id !== args.buyerId)
+        return { ok: false, error: '只有订单买家可确认收到退款', error_code: 'NOT_ORDER_BUYER' };
+    // 竞态重校验:卖家已发货/已争议 → 握手失效,绝不在非 accepted 状态上关单
+    if (order.status !== 'accepted')
+        return { ok: false, error: '订单已不在待发货阶段(可能已发货/争议),握手已失效', error_code: 'ORDER_NOT_ACCEPTED' };
+    const sys = db.prepare("SELECT id FROM users WHERE role = 'system' LIMIT 1").get();
+    if (!sys)
+        return { ok: false, error: '系统账号缺失', error_code: 'SYS_MISSING' };
+    // 请求行 CAS:仅 refund_marked → settled(卖家未声明退款前买家不可单方确认关单)
+    const cas = db.prepare(`UPDATE direct_pay_cancel_requests SET status = 'settled', settled_at = datetime('now'), updated_at = datetime('now')
+                          WHERE order_id = ? AND status = 'refund_marked'`).run(args.orderId);
+    if (cas.changes !== 1)
+        return { ok: false, error: '卖家尚未声明退款,不可确认', error_code: 'REFUND_NOT_MARKED' };
+    const t = transition(db, args.orderId, 'cancelled', sys.id, [], '直付取消退款握手:卖家已场外退款,买家确认收到 → 无责取消');
+    if (!t.success)
+        throw new Error(t.error || 'TRANSITION_FAILED'); // 抛错让路由 db.transaction 整体回滚(含上面 CAS)
+    // 库存回补:经唯一守卫入口(accepted=已付未发,A 类放行;已出库来源在入口被拒 —— 见 direct-pay-stock.ts 情形矩阵)
+    restorePreShipDirectPayStock(db, { fromStatus: 'accepted', productId: order.product_id, quantity: Number(order.quantity) || 1 });
+    return { ok: true, status: 'cancelled' };
+}
+/** 状态读取(party-gated):非当事方一律 NOT_A_PARTY,不泄露请求存在性。 */
+export function getCancelRefundState(db, orderId, viewerId) {
+    const order = loadOrder(db, orderId);
+    if (!order)
+        return { ok: false, error: '订单不存在', error_code: 'ORDER_NOT_FOUND' };
+    const isBuyer = order.buyer_id === viewerId;
+    const isSeller = order.seller_id === viewerId;
+    if (!isBuyer && !isSeller)
+        return { ok: false, error: '仅订单当事方可查看', error_code: 'NOT_A_PARTY' };
+    const last = latestRequest(db, orderId);
+    const eff = last ? effectiveStatus(db, last) : null;
+    const open = eff === 'requested' || eff === 'refund_marked';
+    const req = last ? { ...last, status: eff, stale: open && order.status !== 'accepted' } : null;
+    return {
+        ok: true,
+        request: req ?? undefined,
+        can_request: isBuyer && order.payment_rail === 'direct_p2p' && order.status === 'accepted' && !open,
+        can_respond: isSeller && eff === 'requested' && order.status === 'accepted',
+        can_confirm: isBuyer && eff === 'refund_marked' && order.status === 'accepted',
+        can_withdraw: isBuyer && eff === 'requested',
+    };
+}

package/dist/direct-pay-compliance-ingress.js

@@ -0,0 +1,145 @@
+import { randomUUID, createHash } from 'crypto';
+// ── allowlists(未知值 fail-closed)──
+const KYB_STATUSES = new Set(['pending', 'approved', 'rejected', 'revoked']);
+const SANCTIONS_STATUSES = new Set(['clear', 'flagged', 'blocked']);
+const AML_RULES = new Set(['structuring', 'concentration', 'cumulative', 'crypto', 'velocity']);
+const AML_SEVERITIES = new Set(['low', 'medium', 'high']);
+const AML_STATUSES = new Set(['open', 'reviewing', 'cleared', 'escalated', 'str_filed']);
+// expires_at 形态:reader 用 `expires_at > datetime('now')` 做【字符串比较】,datetime('now') = 'YYYY-MM-DD HH:MM:SS'。
+//   任意字符串(如 'not-a-date')会被字典序当成"未来"→ 错误地通过 fail-closed reader。故 ingress 必须校验+规范化:
+//   只接受 SQLite datetime 'YYYY-MM-DD HH:MM:SS' 或完整 ISO-8601,且能真实解析;ISO 一律规范化为可比的 SQLite 格式。
+// SQLite UTC civil 形态 'YYYY-MM-DD HH:MM:SS';ISO 形态【强制带 timezone】(Z 或 ±hh:mm)——无 tz 会按服务器本地时区归一,拒。
+const SQLITE_DT_RE = /^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})$/;
+const ISO_DT_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/;
+/**
+ * 逐字段校验【真实存在】的 civil datetime —— 用 Date.UTC 重建后逐字段回比,杜绝 JS 自动滚动
+ *   (如 2099-02-31 → 03-03、25:00 → 次日)。把字段当 UTC 校验真实性即可(与 SQLite datetime('now') UTC 语义一致)。
+ */
+function isRealCivil(y, mo, d, h, mi, s) {
+    const t = Date.UTC(y, mo - 1, d, h, mi, s);
+    if (!Number.isFinite(t))
+        return false;
+    const dt = new Date(t);
+    return dt.getUTCFullYear() === y && dt.getUTCMonth() === mo - 1 && dt.getUTCDate() === d
+        && dt.getUTCHours() === h && dt.getUTCMinutes() === mi && dt.getUTCSeconds() === s;
+}
+/**
+ * 校验+规范化 expiresAt:空→null(无期限,允许);合法→可比的 'YYYY-MM-DD HH:MM:SS'(UTC);非法→ false。
+ * 不依赖 Date.parse 的宽松解析:先正则定形、再逐字段 isRealCivil 校验(拒不存在的日期),ISO 必须显式带 tz。
+ */
+export function normalizeExpiry(expiresAt) {
+    if (expiresAt === undefined || expiresAt === null || expiresAt === '')
+        return { ok: true, value: null };
+    const sm = SQLITE_DT_RE.exec(expiresAt);
+    if (sm) {
+        if (!isRealCivil(+sm[1], +sm[2], +sm[3], +sm[4], +sm[5], +sm[6]))
+            return { ok: false };
+        return { ok: true, value: expiresAt }; // 已是可比的 UTC civil 形态
+    }
+    const im = ISO_DT_RE.exec(expiresAt);
+    if (im) {
+        // 先逐字段校验【字面 civil 日期】真实存在(2099-02-31 此处即被拒,与 tz 无关)。
+        if (!isRealCivil(+im[1], +im[2], +im[3], +im[4], +im[5], +im[6]))
+            return { ok: false };
+        const ms = Date.parse(expiresAt); // 字面已合法 + 强制带 tz → 此处只做 tz 偏移换算得真实 UTC instant
+        if (!Number.isFinite(ms))
+            return { ok: false };
+        return { ok: true, value: new Date(ms).toISOString().slice(0, 19).replace('T', ' ') };
+    }
+    return { ok: false };
+}
+/** providerRef → 审计用短引用(sha256 前 16 hex);无则 undefined。原值不进审计明文。 */
+function providerRefHash(providerRef) {
+    if (!providerRef)
+        return undefined;
+    return createHash('sha256').update(providerRef).digest('hex').slice(0, 16);
+}
+/**
+ * AML detail allowlist key 集 —— 与 #108 monitor 实际写入的聚合字段一致(velocity/concentration)。
+ * key 也走 allowlist(不止 value):杜绝把 PII 藏进 key(如 {"alice@example.com":1} / {"wallet_0x..":1})。
+ */
+export const AML_DETAIL_KEYS = new Set(['window_hours', 'order_count', 'threshold', 'small_order_count', 'small_order_amount']);
+/**
+ * AML detail = 仅【allowlist key + 聚合数字 value】(与 #108 monitor 纪律一致,防 PII 落库:
+ *   邮箱/地址/钱包/叙述性笔记无论藏在 value 还是 key 一律拒)。undefined 视为"无 detail"(合法)。
+ */
+export function isNumericDetail(detail) {
+    if (detail === undefined || detail === null)
+        return true;
+    if (typeof detail !== 'object' || Array.isArray(detail))
+        return false;
+    return Object.entries(detail).every(([k, v]) => AML_DETAIL_KEYS.has(k) && typeof v === 'number' && Number.isFinite(v));
+}
+/**
+ * AML detail 的 canonical hash(key 排序后 JSON → sha256 前 16 hex),供 Passkey purpose_data 绑定【写入内容】用
+ *   (route 与签名方用同一函数,保证"签的 detail = 写的 detail")。无 detail → 固定 'none'。
+ */
+export function amlDetailHash(detail) {
+    if (detail === undefined || detail === null)
+        return 'none';
+    const canonical = JSON.stringify(Object.keys(detail).sort().reduce((o, k) => { o[k] = detail[k]; return o; }, {}));
+    return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+}
+/** 审计写入(append-only;PII-free)。与台账 INSERT 同事务调用。 */
+function writeAudit(db, adminId, action, targetType, targetId, detail) {
+    db.prepare(`INSERT INTO admin_audit_log (id, admin_id, action, target_type, target_id, detail) VALUES (?,?,?,?,?,?)`)
+        .run('cing_' + randomUUID(), adminId, action, targetType, targetId, JSON.stringify(detail));
+}
+/** KYB 复核结论 ingress(append-only)。status ∈ {pending,approved,rejected,revoked}。 */
+export function recordKybReview(db, args) {
+    const { userId, reviewerId, status, providerRef, expiresAt } = args;
+    if (!userId || !reviewerId)
+        return { ok: false, error: 'MISSING_ARGS' };
+    if (!KYB_STATUSES.has(status))
+        return { ok: false, error: 'INVALID_STATUS' };
+    const exp = normalizeExpiry(expiresAt);
+    if (!exp.ok)
+        return { ok: false, error: 'INVALID_EXPIRES_AT' };
+    const id = 'kyb_' + randomUUID();
+    db.transaction(() => {
+        db.prepare(`INSERT INTO direct_receive_kyb_reviews (id, user_id, status, reviewed_by, reviewed_at, expires_at, reason)
+      VALUES (?,?,?,?,datetime('now'),?,?)`).run(id, userId, status, reviewerId, exp.value, providerRef ?? null);
+        writeAudit(db, reviewerId, 'direct_pay.kyb_ingress', 'user', userId, { kyb_status: status, provider_ref_hash: providerRefHash(providerRef), has_expiry: !!expiresAt, review_id: id });
+    })();
+    return { ok: true, id };
+}
+/** 制裁筛查结论 ingress(append-only)。status ∈ {clear,flagged,blocked}。 */
+export function recordSanctionsScreening(db, args) {
+    const { userId, reviewerId, status, providerRef, expiresAt } = args;
+    if (!userId || !reviewerId)
+        return { ok: false, error: 'MISSING_ARGS' };
+    if (!SANCTIONS_STATUSES.has(status))
+        return { ok: false, error: 'INVALID_STATUS' };
+    const exp = normalizeExpiry(expiresAt);
+    if (!exp.ok)
+        return { ok: false, error: 'INVALID_EXPIRES_AT' };
+    const id = 'sc_' + randomUUID();
+    db.transaction(() => {
+        db.prepare(`INSERT INTO sanctions_screening (id, user_id, status, source, reason, screened_at, expires_at)
+      VALUES (?,?,?,?,?,datetime('now'),?)`).run(id, userId, status, 'manual_ingress', providerRef ?? null, exp.value);
+        writeAudit(db, reviewerId, 'direct_pay.sanctions_ingress', 'user', userId, { sanctions_status: status, provider_ref_hash: providerRefHash(providerRef), has_expiry: !!expiresAt, screening_id: id });
+    })();
+    return { ok: true, id };
+}
+/** AML flag ingress(append-only,新建 flag)。rule/severity/status 全 allowlist。 */
+export function recordAmlFlagIngress(db, args) {
+    const { userId, reviewerId, rule, severity, status, relatedOrderId, detail } = args;
+    if (!userId || !reviewerId)
+        return { ok: false, error: 'MISSING_ARGS' };
+    if (!AML_RULES.has(rule))
+        return { ok: false, error: 'INVALID_RULE' };
+    if (!AML_SEVERITIES.has(severity))
+        return { ok: false, error: 'INVALID_SEVERITY' };
+    if (!AML_STATUSES.has(status))
+        return { ok: false, error: 'INVALID_STATUS' };
+    // P2: detail 仅允许聚合数字(防 PII 落库)。非纯数字 → fail-closed,不写。
+    if (!isNumericDetail(detail))
+        return { ok: false, error: 'INVALID_DETAIL' };
+    const id = 'amlf_' + randomUUID();
+    db.transaction(() => {
+        db.prepare(`INSERT INTO aml_flags (id, subject_user_id, related_order_id, rule, severity, detail, status)
+      VALUES (?,?,?,?,?,?,?)`).run(id, userId, relatedOrderId ?? null, rule, severity, detail ? JSON.stringify(detail) : null, status);
+        writeAudit(db, reviewerId, 'direct_pay.aml_ingress', 'aml_flag', id, { subject_user_id: userId, rule, severity, aml_status: status, related_order_id: relatedOrderId ?? null });
+    })();
+    return { ok: true, id };
+}

package/dist/direct-pay-controls.js

@@ -0,0 +1,136 @@
+// PR-6D: 把 #108 的 AML 监控 param 描述(默认 inert)经控制面统一再导出,使 server.ts DEFAULT_PARAMS
+//   可在【既有 import 行】上一并取用(server.ts 已到 LOC 上限,避免新增行)。SSOT 仍在 direct-pay-aml-monitor.ts。
+export { DIRECT_PAY_AML_PARAMS } from './direct-pay-aml-monitor.js';
+// ── buyer-facing de-identification(SSOT)─────────────────────────────────────────────────────────
+// 买家边界脱敏:卖家【私密类】拒因(暂停 / 保证金未交 / KYC·制裁 / AML / 缓交额度)一律收敛为单一
+//   DIRECT_PAY_SELLER_NOT_ELIGIBLE,绝不向买家暴露卖家具体合规/额度状态。全局/运营类(DISABLED / RAIL_BREAKER /
+//   REGION / CAP)非敏感,原样透出。create 与 availability 两个买家面端点【共用】本判定,避免 de-id 集合漂移。
+//   精确 code 仍保留在 helper 返回值 + 单测(controls / deferral-quota)层,供运营/调试与 gate 逻辑验证。
+//   缓交额度码须与 direct-pay-deferral-quota.ts 的 DEFERRAL_QUOTA_CODES 对齐(test-direct-pay-deferral-quota 漂移断言守护)。
+export const DIRECT_PAY_SELLER_NOT_ELIGIBLE = 'DIRECT_PAY_SELLER_NOT_ELIGIBLE';
+export const BUYER_FACING_SELLER_PRIVATE_CODES = new Set([
+    'DIRECT_PAY_SELLER_SUSPENDED', 'DIRECT_PAY_NOT_AVAILABLE', 'DIRECT_PAY_KYC_REQUIRED', 'DIRECT_PAY_AML_REVIEW_REQUIRED',
+    'DIRECT_PAY_DEFERRAL_QUOTA_EXCEEDED', 'DIRECT_PAY_DEFERRAL_AMOUNT_EXCEEDED',
+    'EXPOSURE_CAP_EXCEEDED', 'EXPOSURE_CAP_CONFIG', // §6.5 抵押背书敞口上限:卖家私密风险态,不向买家泄露
+    'FEE_PREPAY_INSUFFICIENT', // 平台服务费预充值余额不足(非首单):卖家私密风险态,不向买家泄露
+]);
+/** 买家面脱敏:私密拒因 → 通用 SELLER_NOT_ELIGIBLE;全局/运营类原样;undefined → 通用(fail-safe,绝不泄露)。 */
+export function coarsenBuyerFacingDirectPayCode(code) {
+    return !code || BUYER_FACING_SELLER_PRIVATE_CODES.has(code) ? DIRECT_PAY_SELLER_NOT_ELIGIBLE : code;
+}
+export const DEFAULT_DIRECT_PAY_CONTROLS = {
+    enabled: false, railBreakerTripped: false, region: '', regionAllowlist: [], perTxCapUnits: 0,
+};
+const isNonNegUnits = (x) => typeof x === 'number' && Number.isSafeInteger(x) && x >= 0;
+/**
+ * 入口控制判定(纯、fail-closed、total)。顺序(便宜/广 → 卖家专属 → 硬不变量):
+ *   全局开关 → 运营熔断 → 地区 → 单笔上限 → 卖家熔断 → production base-bond → KYC/制裁 → AML 断路器。
+ *   任一不过即返回该项拒绝码(短路;先全局/政策、后卖家专属,避免提前泄露卖家专属原因);全过返回 { ok:true }。绝不抛错。
+ *   production base-bond、KYC/制裁、AML 断路器都是【不可配置硬不变量】(无 cfg 开关、治理不可绕过),恒在最后强制。
+ */
+export function evaluateDirectPayLaunchControls(cfg, facts) {
+    const c = { ...DEFAULT_DIRECT_PAY_CONTROLS, ...(cfg ?? {}) };
+    const f = facts ?? {};
+    const deny = (error_code, reason) => ({ ok: false, status: 409, error_code, reason });
+    if (c.enabled !== true)
+        return deny('DIRECT_PAY_DISABLED', '直付当前未开放(全局开关关闭)');
+    if (c.railBreakerTripped === true)
+        return deny('DIRECT_PAY_RAIL_BREAKER', '直付已被运营紧急熔断,暂停受理');
+    const allow = Array.isArray(c.regionAllowlist) ? c.regionAllowlist : [];
+    if (!allow.length || !c.region || !allow.includes(c.region))
+        return deny('DIRECT_PAY_REGION_UNSUPPORTED', '直付在本地区暂未开放');
+    if (!isNonNegUnits(c.perTxCapUnits) || c.perTxCapUnits <= 0)
+        return deny('DIRECT_PAY_CAP_EXCEEDED', '直付单笔上限未配置');
+    if (!isNonNegUnits(f.amountUnits) || f.amountUnits <= 0 || f.amountUnits > c.perTxCapUnits)
+        return deny('DIRECT_PAY_CAP_EXCEEDED', '直付订单总额超出单笔上限(WebAZ 记录的订单金额上限;不约束场外实付)');
+    if (f.sellerBreakerTripped === true)
+        return deny('DIRECT_PAY_SELLER_SUSPENDED', '该卖家直付已被暂停');
+    // 硬不变量(launch blockers):production base-bond 与 KYC/制裁【始终强制】,无 cfg 开关、治理不可绕过。
+    if (f.baseBondSatisfied !== true)
+        return deny('DIRECT_PAY_NOT_AVAILABLE', '直付暂不可用:卖家未交履约保证金且无有效缓交');
+    if (f.kycSanctionsPassed !== true)
+        return deny('DIRECT_PAY_KYC_REQUIRED', '直付暂不可用:卖家未通过 KYC/制裁筛查');
+    if (f.amlClear !== true)
+        return deny('DIRECT_PAY_AML_REVIEW_REQUIRED', '直付暂不可用:卖家存在未清除的 AML 风险复核');
+    return { ok: true, status: 200 };
+}
+/** protocol_params 薄装配器(治理可调;缺行回落 fail-closed 默认)。不读资金/状态,只读控制参数。 */
+export function readDirectPayControlsConfig(getProtocolParam) {
+    const csv = String(getProtocolParam('direct_pay.region_allowlist', '') || '');
+    const cap = Number(getProtocolParam('direct_pay.per_tx_cap_units', 0));
+    return {
+        enabled: getProtocolParam('direct_pay.enabled', false) === true,
+        railBreakerTripped: getProtocolParam('direct_pay.rail_breaker_tripped', false) === true,
+        region: String(getProtocolParam('direct_pay.region', '') || ''),
+        regionAllowlist: csv.split(',').map(s => s.trim()).filter(Boolean),
+        perTxCapUnits: Number.isSafeInteger(cap) && cap >= 0 ? cap : 0,
+    };
+}
+/**
+ * protocol_params 默认 seed(供 server.ts DEFAULT_PARAMS 展开)。默认全 fail-closed —— Direct Pay non-launchable;
+ *   治理经 PATCH /api/admin/protocol-params/<key> 开通(无 seed 则 PATCH 404、boot 不建行 → 控制面打不开)。
+ *   只含【运营节流】可调项(开关/地区/上限)。production base-bond 与 KYC/制裁是【不可关闭的硬不变量】,
+ *   刻意【不】做成 param —— 治理无法关掉它们绕过 launch blockers(evaluate 始终强制)。
+ *   key/默认值必须与 readDirectPayControlsConfig / DEFAULT_DIRECT_PAY_CONTROLS 对齐。
+ */
+export const DIRECT_PAY_CONTROL_PARAMS = [
+    { key: 'direct_pay.enabled', value: 'false', type: 'boolean', description: 'Direct Pay 全局主开关(上线决定);默认 false=关(non-launchable)。', category: 'system' },
+    { key: 'direct_pay.rail_breaker_tripped', value: 'false', type: 'boolean', description: 'Direct Pay 运营紧急熔断(ops emergency stop,与 enabled 分离);true=暂停受理。默认 false。', category: 'system' },
+    { key: 'direct_pay.region', value: '', type: 'string', description: 'Direct Pay 本部署/运营所在地区码(与白名单比对);默认空=fail-closed。', category: 'system' },
+    { key: 'direct_pay.region_allowlist', value: '', type: 'string', description: 'Direct Pay 已开放地区白名单(逗号分隔);默认空=无地区开放。', category: 'system' },
+    // 单笔上限:对【WebAZ 记录的 direct_p2p 订单总额】在建单时的天花板(整数 policy base-units)。默认 0 = 无放行(fail-closed),
+    //   治理设正值方生效。【不是】对买卖双方场外真实付款金额的担保或控制——WebAZ 控不了场外金额,此处也不声称能控。
+    //   具体数值(如 SG v1 的 policy units)由独立的 launch-policy PR 配置,本 PR 只提供 cap 能力、默认仍 fail-closed。
+    { key: 'direct_pay.per_tx_cap_units', value: '0', type: 'number', description: 'Direct Pay 单笔上限:WebAZ 记录的订单总额天花板(整数 policy base-units);默认 0=无放行,治理设正值方可。仅约束协议侧建单金额,不控制/不担保场外真实付款。', category: 'system', min: 0 },
+    { key: 'direct_pay.exposure_factor_bps', value: '8000', type: 'number', description: '§6.5 抵押背书的开放敞口上限系数(bps):open_exposure + new_order ≤ active_collateral × bps/10000。仅对有真实链上抵押(collateral>0)的卖家生效;缓交卖家不受此门。默认 8000(=80%)。风险控制,非买家赔付。', category: 'system', min: 1, max: 10000 },
+    // 注:平台服务费门 = 首单宽限 + 预充值续用(数据驱动:available_prepay = Σ预充值 − Σ已计提费),【无 protocol_param 旋钮】
+    //   (额度即商家实际预付余额,宽限自动判定);故此处不再有 fee_ar_credit_ceiling_units 参数。
+];
+/**
+ * PR-6A AML/CFT runtime — KYB(商户尽调)事实(fail-closed)。来源 direct_receive_kyb_reviews(真人/合规复核结论;
+ *   无第三方 vendor、无真实 API 调用)。通过 ⟺ 存在 status='approved' 且未过期的复核 且【无】rejected/revoked 行。
+ *   missing / pending / rejected / revoked / expired 一律不通过。该表无生产写入方 → 真实卖家天然 fail-closed。
+ */
+export function sellerDirectPayKybPassed(db, sellerId) {
+    const approved = db.prepare("SELECT 1 FROM direct_receive_kyb_reviews WHERE user_id = ? AND status = 'approved' AND (expires_at IS NULL OR expires_at > datetime('now')) LIMIT 1").get(sellerId);
+    const blocked = db.prepare("SELECT 1 FROM direct_receive_kyb_reviews WHERE user_id = ? AND status IN ('rejected','revoked') LIMIT 1").get(sellerId);
+    return !!approved && !blocked;
+}
+/**
+ * PR-6A AML/CFT runtime — 制裁筛查事实(fail-closed)。来源 sanctions_screening:存在 status='clear' 且未过期的结论,
+ *   且【无】flagged/blocked 行。expired(expires_at 已过)视作未通过;NULL expires_at = 无期限。无第三方集成。
+ *   该表无生产写入方 → 真实卖家天然 fail-closed。
+ */
+export function sellerDirectPaySanctionsClear(db, sellerId) {
+    const clear = db.prepare("SELECT 1 FROM sanctions_screening WHERE user_id = ? AND status = 'clear' AND (expires_at IS NULL OR expires_at > datetime('now')) LIMIT 1").get(sellerId);
+    const bad = db.prepare("SELECT 1 FROM sanctions_screening WHERE user_id = ? AND status IN ('flagged','blocked') LIMIT 1").get(sellerId);
+    return !!clear && !bad;
+}
+/**
+ * 卖家熔断事实(per-seller breaker)。【唯一来源】= direct_receive_privileges.status = 'suspended'(复用既有暂停语义,
+ *   如 slashBond 罚没后置 suspended);【不】新增第二套 suspension 概念。无行 / 'none' / 'active' → false;'suspended' → true。
+ */
+export function sellerDirectPayBreakerTripped(db, sellerId) {
+    return !!db.prepare("SELECT 1 FROM direct_receive_privileges WHERE user_id = ? AND status = 'suspended' LIMIT 1").get(sellerId);
+}
+/**
+ * PR-6B AML 运行期断路器事实(fail-closed)。来源 aml_flags(本仓内部监控 flag;无第三方 vendor、无真实 API)。
+ *   key = subject_user_id。返回 true(清白/不阻断)⟺ 卖家【没有任何阻断性 flag】。
+ *
+ * 单条 flag 的【阻断】判定(任一命中即阻断;precedence 由 SQL OR 短路保证 suspend 优先于 cleared):
+ *   ① malformed enum —— severity/status/disposition 越界(本表 TEXT 无 CHECK,脏值可入)→ fail-closed 阻断;
+ *   ② disposition='suspend' —— 无论 severity/status【一律阻断】(含 status='cleared' 的矛盾数据:suspend 取胜,从严);
+ *   ③ status∈(open|reviewing|escalated|str_filed) 且 severity∈(medium|high) —— 未清除的中/高风险 → 阻断。
+ * 非阻断(放行):无 flag / status='cleared'(且非 suspend) / severity='low'(且非 suspend)。
+ *   纯读;不写;不碰资金/状态机。aml_flags 当前无生产写入方 → 真实卖家天然无阻断(待 AML 检测引擎接入再产生 flag)。
+ */
+export function sellerDirectPayAmlClear(db, sellerId) {
+    const blocking = db.prepare(`SELECT 1 FROM aml_flags WHERE subject_user_id = ? AND (
+         severity NOT IN ('low','medium','high')
+      OR status   NOT IN ('open','reviewing','cleared','escalated','str_filed')
+      OR (disposition IS NOT NULL AND disposition NOT IN ('review_queue','downgrade','suspend'))
+      OR disposition = 'suspend'
+      OR (status IN ('open','reviewing','escalated','str_filed') AND severity IN ('medium','high'))
+    ) LIMIT 1`).get(sellerId);
+    return !blocking;
+}