@seasonkoh/webaz 0.1.29 → 0.1.30

package/dist/pwa/routes/bond-seller.js

@@ -0,0 +1,162 @@
+import { openDeposit, getSellerLatestDeposit, expireDeposit, requiredBondUnits, cancelPendingDeposit, requestBondRefund, cancelBondRefundRequest, DIRECT_PAY_BOND_JURISDICTIONS } from '../../direct-receive-deposits.js';
+import { enumerateBondRefundBlockers } from '../../bond-refund-blockers.js'; // B2:§5 unlock blockers(fail-closed)
+import { listBondSlashProposals } from '../../bond-slash.js'; // B3:待复核罚没提案(卖家须被告知)
+import { BOND_TERMS } from '../../bond-terms.js'; // 条款(缴纳前强制同意;版本快照进 deposit 行)
+import { getPlatformAccount } from '../../platform-receive-accounts.js';
+import { bondRailClearanceBlockers, isBondRailClearedForProduction } from '../../direct-pay-bond-rail-clearance.js';
+import { getActiveDeferral } from '../../direct-receive-deferral.js';
+import { listActivePlatformAccounts } from '../../platform-receive-accounts.js';
+import { toDecimal } from '../../money.js';
+import { createNotification } from '../../layer2-business/L2-6-notifications/notification-engine.js';
+import { dbAll } from '../../layer0-foundation/L0-1-database/db.js';
+/** operator_attested 生产轨是否已放行 —— 按【平台收款主体法域】(DIRECT_PAY_BOND_JURISDICTIONS,非卖家法域;
+ *  卖家侧资格由 KYB/制裁/AML 门独立把守)判 Lock A+B 全过。2026-07-05 起 SG 放行(#240 决策 B)。 */
+function bondRailCleared() {
+    return DIRECT_PAY_BOND_JURISDICTIONS.some(j => isBondRailClearedForProduction('operator_attested', j));
+}
+export function registerBondSellerRoutes(app, deps) {
+    const { db, auth, generateId, errorRes, getProtocolParam } = deps;
+    const coolingDays = () => Math.max(0, Number(getProtocolParam('direct_pay.bond_refund_cooling_days', 14)) || 14);
+    function requireSeller(req, res) {
+        const user = auth(req, res);
+        if (!user)
+            return null;
+        if (user.role !== 'seller') {
+            errorRes(res, 403, 'SELLER_ONLY', '仅卖家有履约保证金');
+            return null;
+        }
+        return user;
+    }
+    app.get('/api/direct-receive/bond-status', (req, res) => {
+        const user = requireSeller(req, res);
+        if (!user)
+            return;
+        const sellerId = user.id;
+        // lazy expiry:pending 超 TTL 顺手过期(无 cron 依赖)
+        const latest0 = getSellerLatestDeposit(db, sellerId);
+        if (latest0 && latest0.status === 'pending')
+            expireDeposit(db, { depositId: latest0.id, nowIso: new Date().toISOString() });
+        const latest = getSellerLatestDeposit(db, sellerId);
+        const deferral = getActiveDeferral(db, sellerId, new Date().toISOString());
+        const cleared = bondRailCleared();
+        return void res.json({
+            required: { tier: 'T0', units: requiredBondUnits('T0'), display: toDecimal(requiredBondUnits('T0')), currency: 'USDC', note: '固定 token 数(档位参考 ≈ S$500,非汇率换算);治理可调' },
+            deposit: latest ? {
+                id: latest.id, status: latest.status, amount: latest.amount, required_amount: latest.required_amount,
+                rail: latest.deposit_rail, evidence_ref: latest.external_ref, reject_note: latest.reject_note,
+                production_confirmed: latest.production_receipt_confirmed_at != null, refund_evidence_ref: latest.refund_evidence_ref,
+                created_at: latest.created_at, locked_at: latest.locked_at,
+            } : null,
+            deferral: deferral ? { id: deferral.id, expires_at: deferral.expiresAt, grace_until: deferral.graceUntil, in_grace: deferral.inGrace, reduced_quota_factor: deferral.reducedQuotaFactor } : null,
+            // B2:退出退还视图 —— locked 时预览 blockers(能不能申请);refunding 时给冷静期/可执行时间
+            refund: latest && latest.status === 'locked' ? { can_request: enumerateBondRefundBlockers(db, sellerId).length === 0, blockers: enumerateBondRefundBlockers(db, sellerId), cooling_days: coolingDays() }
+                : latest && latest.status === 'refunding' ? { requested_at: latest.refund_requested_at, cooling_days: coolingDays() } : null,
+            // B3:待复核罚没提案(冷静期=卖家申诉窗,必须让卖家看见)
+            pending_slash: (() => { try {
+                const p = listBondSlashProposals(db, { sellerId, status: 'proposed' })[0];
+                return p ? { id: p.id, dispute_id: p.dispute_id, cooling_until: p.cooling_until, reason: p.reason } : null;
+            }
+            catch {
+                return null;
+            } })(),
+            rail_cleared: cleared,
+            rail_blockers: cleared ? [] : bondRailClearanceBlockers('operator_attested').filter(b => b !== 'NO_PRODUCTION_RECEIPT'),
+            payment_accounts: cleared ? listActivePlatformAccounts(db) : [], // 放行前不展示收款方式(不引导无法生效的转账);多币种账户由 admin 在 #admin/platform-receive 维护
+            terms: { version: BOND_TERMS.version, zh: BOND_TERMS.zh, en: BOND_TERMS.en }, // 缴纳前必须同意(版本快照)
+            note: cleared
+                ? '按平台收款方式转账后提交申报(凭据必填);运营核实到账并确认后保证金正式锁定、直付入场门即满足。'
+                : '保证金缴纳通道待平台放行(合规审查中)。当前可通过【缓交申请】先行入场(额度受限);放行后再补缴转正式。',
+        });
+    });
+    app.post('/api/direct-receive/bond-deposit', async (req, res) => {
+        const user = requireSeller(req, res);
+        if (!user)
+            return;
+        const sellerId = user.id;
+        // fail-closed:Lock B 未放行 → 不收申报(收了也无法核实生效,只会积压误导)
+        if (!bondRailCleared())
+            return void errorRes(res, 409, 'BOND_RAIL_NOT_CLEARED', '保证金缴纳通道待平台放行(合规审查中);当前请使用缓交申请入场');
+        const evidence = String(req.body?.evidence_ref ?? '').trim();
+        if (!evidence || evidence.length > 120)
+            return void errorRes(res, 400, 'EVIDENCE_REQUIRED', '付款凭据号必填(≤120 字;转账单号/链上 tx 等,运营据此核对到账)');
+        // 条款强制同意(合同依据;版本精确匹配,旧版本同意无效)
+        if (String(req.body?.agree_terms_version ?? '') !== BOND_TERMS.version) {
+            return void res.status(428).json({ error: '缴纳前须阅读并同意当前版本保证金条款', error_code: 'TERMS_NOT_AGREED', terms: { version: BOND_TERMS.version, zh: BOND_TERMS.zh, en: BOND_TERMS.en } });
+        }
+        // 多币种:必须选一个 active 平台收款账户;币种由账户推导(USDC/USDT→usdc,其余→fiat)
+        const acc = getPlatformAccount(db, String(req.body?.platform_account_id ?? ''));
+        if (!acc || acc.status !== 'active')
+            return void errorRes(res, 400, 'PLATFORM_ACCOUNT_REQUIRED', '须选择缴纳到的平台收款账户(有效且启用)');
+        const currency = ['USDC', 'USDT'].includes(String(acc.currency ?? '').toUpperCase()) ? 'usdc' : 'fiat';
+        const latest0 = getSellerLatestDeposit(db, sellerId);
+        if (latest0 && latest0.status === 'pending')
+            expireDeposit(db, { depositId: latest0.id, nowIso: new Date().toISOString() }); // lazy expiry
+        const latest = getSellerLatestDeposit(db, sellerId);
+        if (latest && ['pending', 'confirmed', 'insufficient'].includes(latest.status))
+            return void errorRes(res, 409, 'DEPOSIT_IN_FLIGHT', `已有在途申报(${latest.status}),请等待运营核实或先撤回`);
+        if (latest && latest.status === 'locked')
+            return void errorRes(res, 409, 'BOND_ALREADY_LOCKED', '保证金已锁定生效,无需重复缴纳');
+        const depositId = generateId('bond');
+        const r = openDeposit(db, { depositId, userId: sellerId, tier: 'T0', currency, depositRail: 'operator_attested', externalRef: evidence, termsVersion: BOND_TERMS.version, platformAccountId: acc.id });
+        if (!r.ok)
+            return void errorRes(res, 400, 'BOND_OPEN_FAILED', r.reason);
+        // N3 同款:通知 root admin 有待核实申报(best-effort)
+        try {
+            const roots = await dbAll("SELECT id FROM users WHERE role = 'admin' AND (admin_type = 'root' OR admin_type IS NULL)");
+            for (const a of roots) {
+                createNotification(db, a.id, null, 'bond_deposit_submitted', '🏦 新保证金缴纳申报待核实', `卖家 ${String(user.name ?? sellerId)} 申报已缴纳履约保证金(T0,凭据 ${evidence.slice(0, 40)})。请核对真实到账后在 admin 后台确认(ROOT+Passkey)。`, { templateKey: 'bond_deposit_submitted', params: { seller: String(user.name ?? sellerId), evidence: evidence.slice(0, 40) } });
+            }
+        }
+        catch (e) {
+            console.warn('[bond-deposit notify]', e.message);
+        }
+        return void res.json({ success: true, deposit_id: depositId, status: 'pending', note: '申报已提交;运营核实真实到账并确认后生效。申报本身不授予任何入场资格。' });
+    });
+    // ── B2:退出退还 —— 申请(§5 blockers fail-closed)→ 冷静期 → admin 执行;申请期间直付资格暂停,可撤销 ──
+    app.post('/api/direct-receive/bond-refund-request', async (req, res) => {
+        const user = requireSeller(req, res);
+        if (!user)
+            return;
+        const sellerId = user.id;
+        const latest = getSellerLatestDeposit(db, sellerId);
+        if (!latest || latest.status !== 'locked')
+            return void errorRes(res, 409, 'NO_LOCKED_BOND', '没有已锁定的保证金可退');
+        const blockers = enumerateBondRefundBlockers(db, sellerId);
+        if (blockers.length > 0)
+            return void res.status(409).json({ error: '有未了结的直付责任,暂不能申请退还', error_code: 'REFUND_BLOCKED', blockers });
+        const r = requestBondRefund(db, { depositId: latest.id, userId: sellerId });
+        if (!r.ok)
+            return void errorRes(res, 409, 'REFUND_REQUEST_FAILED', r.reason);
+        try {
+            const roots = await dbAll("SELECT id FROM users WHERE role = 'admin' AND (admin_type = 'root' OR admin_type IS NULL)");
+            for (const a of roots)
+                createNotification(db, a.id, null, 'bond_refund_requested', '↩️ 保证金退出申请待处理', `卖家 ${String(user.name ?? sellerId)} 申请退还履约保证金(冷静期 ${coolingDays()} 天,期间其直付资格已暂停)。冷静期满且复核无未了结责任后,场外退还并在 admin 后台记录执行。`, { templateKey: 'bond_refund_requested', params: { seller: String(user.name ?? sellerId), days: coolingDays() } });
+        }
+        catch (e) {
+            console.warn('[bond-refund notify]', e.message);
+        }
+        return void res.json({ success: true, status: 'refunding', cooling_days: coolingDays(), note: '申请已提交:冷静期内你的直付资格暂停(不可接新直付单);冷静期满、复核无未了结责任后,平台在协议外退还并记录。可随时撤销申请恢复资格。' });
+    });
+    app.post('/api/direct-receive/bond-refund-request/cancel', (req, res) => {
+        const user = requireSeller(req, res);
+        if (!user)
+            return;
+        const latest = getSellerLatestDeposit(db, user.id);
+        if (!latest)
+            return void errorRes(res, 404, 'DEPOSIT_NOT_FOUND', '无保证金记录');
+        const r = cancelBondRefundRequest(db, { depositId: latest.id, userId: user.id });
+        if (!r.ok)
+            return void errorRes(res, 409, 'REFUND_CANCEL_FAILED', r.reason);
+        return void res.json({ success: true, status: 'locked', note: '退出申请已撤销,直付资格已恢复。' });
+    });
+    app.post('/api/direct-receive/bond-deposit/:id/cancel', (req, res) => {
+        const user = requireSeller(req, res);
+        if (!user)
+            return;
+        // 单一 writer 边界:deposits 写只经域模块(guard:direct-pay-deposit 机器强制,route 零裸写)
+        const r = cancelPendingDeposit(db, { depositId: req.params.id, userId: user.id });
+        if (!r.ok)
+            return void errorRes(res, r.reason === 'deposit not found' ? 404 : 409, 'BOND_CANCEL_FAILED', r.reason);
+        return void res.json({ success: true });
+    });
+}

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

@@ -0,0 +1,111 @@
+import { requestCancelRefund, declineCancelRefund, markRefunded, withdrawCancelRefund, confirmRefundReceived, getCancelRefundState, } from '../../direct-pay-cancel-refund.js';
+import { requireDirectPayHumanPasskey } from '../direct-pay-guards.js';
+import { dbOne } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam(通知收件人读)
+import { transition } from '../../layer0-foundation/L0-2-state-machine/engine.js';
+import { createNotification } from '../../layer2-business/L2-6-notifications/notification-engine.js';
+export function registerDirectPayCancelRefundRoutes(app, deps) {
+    const { db, auth, generateId, errorRes, consumeGateToken } = deps;
+    const httpFor = (code) => code === 'ORDER_NOT_FOUND' ? 404
+        : code === 'NOT_A_PARTY' || code === 'NOT_ORDER_BUYER' || code === 'NOT_ORDER_SELLER' ? 403
+            : code === 'SYS_MISSING' ? 500
+                : 409;
+    const notify = (userId, orderId, type, title, body) => {
+        try {
+            createNotification(db, userId, orderId, type, title, body);
+        }
+        catch { /* 通知失败不阻断业务 */ }
+    };
+    const party = async (orderId) => await dbOne('SELECT buyer_id, seller_id FROM orders WHERE id = ?', [orderId]);
+    app.get('/api/orders/:id/cancel-refund', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const r = getCancelRefundState(db, req.params.id, user.id);
+        if (!r.ok)
+            return void errorRes(res, httpFor(r.error_code), r.error_code || 'CANCEL_REFUND_STATE_ERROR', r.error || '读取失败');
+        res.json({ success: true, request: r.request ?? null, can_request: !!r.can_request, can_respond: !!r.can_respond, can_confirm: !!r.can_confirm, can_withdraw: !!r.can_withdraw });
+    });
+    app.post('/api/orders/:id/cancel-refund/request', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const reason = typeof req.body?.reason === 'string' ? req.body.reason : null;
+        const r = requestCancelRefund(db, { orderId: req.params.id, buyerId: user.id, reason, requestId: generateId('dpcr') });
+        if (!r.ok)
+            return void errorRes(res, httpFor(r.error_code), r.error_code || 'CANCEL_REFUND_REQUEST_ERROR', r.error || '发起失败');
+        const p = await party(req.params.id);
+        if (p)
+            notify(p.seller_id, req.params.id, 'direct_pay_cancel_requested', '↩️ 买家申请取消订单并退款', `买家已付款但希望取消订单${reason ? `(理由:${String(reason).slice(0, 80)})` : ''}。请在期限内响应:同意则场外退款后点"我已退款",不同意可拒绝(继续发货)。直付非托管,退款在协议外完成。`);
+        return void res.json({ success: true, status: r.status, request: r.request ?? null });
+    });
+    app.post('/api/orders/:id/cancel-refund/decline', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const r = declineCancelRefund(db, { orderId: req.params.id, sellerId: user.id });
+        if (!r.ok)
+            return void errorRes(res, httpFor(r.error_code), r.error_code || 'CANCEL_REFUND_DECLINE_ERROR', r.error || '拒绝失败');
+        const p = await party(req.params.id);
+        if (p)
+            notify(p.buyer_id, req.params.id, 'direct_pay_cancel_declined', '❌ 卖家拒绝了取消退款请求', '卖家选择继续履约发货。如有异议可与卖家沟通,或在有证据时发起争议。');
+        return void res.json({ success: true, status: r.status });
+    });
+    app.post('/api/orders/:id/cancel-refund/mark-refunded', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const refundReference = typeof req.body?.refund_reference === 'string' ? req.body.refund_reference : null;
+        const r = markRefunded(db, { orderId: req.params.id, sellerId: user.id, refundReference });
+        if (!r.ok)
+            return void errorRes(res, httpFor(r.error_code), r.error_code || 'CANCEL_REFUND_MARK_ERROR', r.error || '声明退款失败');
+        const p = await party(req.params.id);
+        if (p)
+            notify(p.buyer_id, req.params.id, 'direct_pay_refund_marked', '💸 卖家已声明退款', `卖家声明已在协议外向你退款${refundReference ? `(退款参考:${String(refundReference).slice(0, 80)})` : ''}。请核实到账后在订单页确认(需 Passkey),订单将无责取消;若未收到退款请勿确认,可发起争议。`);
+        return void res.json({ success: true, status: r.status });
+    });
+    app.post('/api/orders/:id/cancel-refund/withdraw', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const r = withdrawCancelRefund(db, { orderId: req.params.id, buyerId: user.id });
+        if (!r.ok)
+            return void errorRes(res, httpFor(r.error_code), r.error_code || 'CANCEL_REFUND_WITHDRAW_ERROR', r.error || '撤回失败');
+        const p = await party(req.params.id);
+        if (p)
+            notify(p.seller_id, req.params.id, 'direct_pay_cancel_withdrawn', '↩️ 买家撤回了取消退款请求', '订单继续正常履约,请按流程发货。');
+        return void res.json({ success: true, status: r.status });
+    });
+    app.post('/api/orders/:id/cancel-refund/confirm', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const uid = user.id;
+        // 只读预检(不消费 token):必须存在 refund_marked 的请求且订单仍 accepted,否则不浪费一次性 Passkey token
+        const pre = getCancelRefundState(db, req.params.id, uid);
+        if (!pre.ok)
+            return void errorRes(res, httpFor(pre.error_code), pre.error_code || 'CANCEL_REFUND_STATE_ERROR', pre.error || '读取失败');
+        if (!pre.can_confirm)
+            return void errorRes(res, 409, 'REFUND_NOT_MARKED', '当前不可确认(卖家尚未声明退款,或订单已不在待发货阶段)');
+        // RISK 门:确认收款并关单 = 终局动作 → 现场真人 Passkey(agent 无 Passkey 硬拒)
+        const gate = requireDirectPayHumanPasskey({ db, consumeGateToken }, {
+            userId: uid, webauthnToken: req.body?.webauthn_token, purpose: 'direct_pay_order_action',
+            validate: (data) => { const d = data; return !!d && d.order_id === req.params.id && d.action === 'cancel_refund_confirm'; },
+        });
+        if (!gate.ok)
+            return void errorRes(res, 403, gate.error_code || 'HUMAN_PRESENCE_REQUIRED', gate.reason || '需现场真人 Passkey 确认');
+        let r;
+        try {
+            // 状态手术:请求行 CAS + accepted→cancelled + 库存恢复,同一原子边界(域内重校验防 ship/争议竞态)
+            r = db.transaction(() => confirmRefundReceived(db, { orderId: req.params.id, buyerId: uid }, transition))();
+        }
+        catch (e) {
+            return void errorRes(res, 409, 'CANCEL_REFUND_CONFIRM_FAILED', e.message);
+        }
+        if (!r.ok)
+            return void errorRes(res, httpFor(r.error_code), r.error_code || 'CANCEL_REFUND_CONFIRM_ERROR', r.error || '确认失败');
+        const p = await party(req.params.id);
+        if (p)
+            notify(p.seller_id, req.params.id, 'direct_pay_cancel_settled', '✅ 取消退款握手完成', '买家已确认收到退款,订单已无责取消,库存已恢复。双方信誉均不受影响。');
+        return void res.json({ success: true, status: r.status });
+    });
+}

package/dist/pwa/routes/direct-pay-disclosure-acks.js

@@ -25,14 +25,18 @@ export function registerDirectPayDisclosureAckRoutes(app, deps) {
         }
         return order;
     }
-    // POST — 记录一次 ack(D1 pre_select / D2 pre_confirm)。需现场真人(Passkey + gate token)。幂等(INSERT OR IGNORE)。
+    // POST — 记录 ack。stage = pre_select | pre_confirm | both。需现场真人(Passkey + gate token)。幂等(INSERT OR IGNORE)。
+    //   'both'(2026-07-04 用户决策,contract v14):两屏披露【仍各自展示并确认】(文本证据不减),但一次真人 ceremony
+    //   可覆盖两个 stage → 落库仍是【两行】ack(各带 notice_version+acked_at,requireBothDisclosuresAcked 证据模型不变);
+    //   变化仅是"人在场证明"从两次合并为一次(首单 Passkey 3→2;mark_paid 的独立 RISK 门不变)。token purpose_data 绑
+    //   stage:'both' —— 单 stage token 冒充不了 both,both token 也重放不了单 stage(一次性消费 + validate 精确匹配)。
     app.post('/api/direct-pay/disclosure-acks', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
         const stage = req.body?.stage;
-        if (!VALID_STAGES.includes(stage))
-            return void res.status(400).json({ error: `无效 stage(只允许 ${VALID_STAGES.join('|')})`, error_code: 'INVALID_STAGE' });
+        if (stage !== 'both' && !VALID_STAGES.includes(stage))
+            return void res.status(400).json({ error: `无效 stage(只允许 ${VALID_STAGES.join('|')}|both)`, error_code: 'INVALID_STAGE' });
         const order = await requireOwnDirectPayOrder(req.body?.order_id, res, user);
         if (!order)
             return;
@@ -45,7 +49,8 @@ export function registerDirectPayDisclosureAckRoutes(app, deps) {
         });
         if (!gate.ok)
             return void res.status(403).json({ error: gate.reason, error_code: gate.error_code });
-        recordDisclosureAck(db, { orderId: order.id, buyerId: user.id, stage, ackId: generateId('dpa') });
+        for (const s of (stage === 'both' ? VALID_STAGES : [stage]))
+            recordDisclosureAck(db, { orderId: order.id, buyerId: user.id, stage: s, ackId: generateId('dpa') });
         return void res.json({
             ok: true, stage,
             both: requireBothDisclosuresAcked(db, order.id).ok,

package/dist/pwa/routes/direct-pay-pending-accept.js

@@ -0,0 +1,222 @@
+import { transition } from '../../layer0-foundation/L0-2-state-machine/engine.js';
+import { restorePreShipDirectPayStock } from '../../direct-pay-stock.js';
+import { createNotification } from '../../layer2-business/L2-6-notifications/notification-engine.js';
+import { dbOne, dbRun } from '../../layer0-foundation/L0-1-database/db.js';
+import { toUnits, toDecimal } from '../../money.js';
+import { buildPayableSnapshot } from '../../direct-pay-create.js';
+import { safeRunDirectPayAmlMonitor } from '../../direct-pay-aml-monitor.js';
+import { updateSnapshotShippingQuote } from '../../trade-terms.js'; // S0:询价确认后补记条款快照 shipping 槽(quote_pending→quote,fail-soft)
+export function registerDirectPayPendingAcceptRoutes(app, deps) {
+    const { db, auth, errorRes, getProtocolParam } = deps;
+    async function loadPendingOrder(req, res) {
+        const order = await dbOne('SELECT id, buyer_id, seller_id, status, payment_rail, product_id, quantity, total_amount, shipping_quote_required, shipping_quote_fee, shipping_quote_est_days, direct_pay_per_tx_cap_units_snapshot, direct_pay_account_snapshot FROM orders WHERE id = ?', [req.params.id]);
+        if (!order) {
+            errorRes(res, 404, 'ORDER_NOT_FOUND', '订单不存在');
+            return null;
+        }
+        if (order.payment_rail !== 'direct_p2p') {
+            errorRes(res, 409, 'NOT_DIRECT_PAY', '仅直付订单有待接单阶段');
+            return null;
+        }
+        if (order.status !== 'pending_accept') {
+            errorRes(res, 409, 'NOT_PENDING_ACCEPT', `当前状态 ${order.status},不在待接单阶段`);
+            return null;
+        }
+        return order;
+    }
+    const notify = (userId, orderId, type, title, body, tpl) => {
+        try {
+            createNotification(db, userId, orderId, type, title, body, tpl);
+        }
+        catch { /* 通知失败不阻断 */ }
+    };
+    // ── 接单模式设置(卖家):店铺默认 + 单品覆盖。值 ∈ {'auto','manual',null=清除(单品回落店铺默认/店铺回落 auto)}。
+    //   只影响【之后】的新订单(下单时快照);对两轨生效(escrow 'auto'=付款后系统自动接单;dp 'manual'=先进 pending_accept)。
+    const MODE_OK = (v) => v === null || v === 'auto' || v === 'manual';
+    app.post('/api/seller/accept-mode', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        if (user.role !== 'seller')
+            return void errorRes(res, 403, 'SELLER_ONLY', '仅卖家可设置接单模式');
+        const b = req.body || {};
+        const touched = {};
+        if ('store_accept_mode' in b) {
+            if (!MODE_OK(b.store_accept_mode))
+                return void errorRes(res, 400, 'BAD_ACCEPT_MODE', "store_accept_mode 只允许 'auto'|'manual'|null");
+            await dbRun('UPDATE users SET store_accept_mode = ? WHERE id = ?', [b.store_accept_mode, user.id]);
+            touched.store_accept_mode = b.store_accept_mode;
+        }
+        if ('product_id' in b || 'accept_mode' in b) {
+            if (!b.product_id)
+                return void errorRes(res, 400, 'MISSING_PRODUCT_ID', '设置单品接单模式须带 product_id');
+            if (!MODE_OK(b.accept_mode))
+                return void errorRes(res, 400, 'BAD_ACCEPT_MODE', "accept_mode 只允许 'auto'|'manual'|null");
+            const p = await dbOne('SELECT seller_id FROM products WHERE id = ?', [b.product_id]);
+            if (!p)
+                return void errorRes(res, 404, 'PRODUCT_NOT_FOUND', '商品不存在');
+            if (p.seller_id !== user.id)
+                return void errorRes(res, 403, 'NOT_PRODUCT_OWNER', '只能设置自己商品的接单模式');
+            await dbRun('UPDATE products SET accept_mode = ? WHERE id = ?', [b.accept_mode, b.product_id]);
+            touched.product_accept_mode = b.accept_mode;
+        }
+        if (Object.keys(touched).length === 0)
+            return void errorRes(res, 400, 'NOTHING_TO_SET', '未提供任何设置项');
+        return void res.json({ success: true, ...touched });
+    });
+    // 卖家确认接单 → 开付款窗口(deadline 此刻起表;收款信息此刻起买家可见 —— orders-read 状态门放行)
+    app.post('/api/orders/:id/pending-accept/accept', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const order = await loadPendingOrder(req, res);
+        if (!order)
+            return;
+        if (order.seller_id !== user.id)
+            return void errorRes(res, 403, 'NOT_ORDER_SELLER', '只有订单卖家可接单');
+        // 询价单不可裸接单(会绕过报价 → 无运费进付款窗):必须 quote → 买家 confirm-quote(PR-3)
+        if (Number(order.shipping_quote_required) === 1)
+            return void errorRes(res, 409, 'QUOTE_REQUIRED', '本单收货地区在运费模板外,请先报价(运费+时效),买家确认后自动进入付款');
+        const windowHours = Math.max(1, Number(getProtocolParam('direct_pay.payment_window_hours', 4)) || 4);
+        try {
+            db.transaction(() => {
+                const t = transition(db, order.id, 'direct_pay_window', user.id, [], '卖家确认接单 → 进入直付付款窗口');
+                if (!t.success)
+                    throw new Error(t.error || 'TRANSITION_FAILED');
+                db.prepare('UPDATE orders SET direct_pay_window_deadline = ? WHERE id = ?')
+                    .run(new Date(Date.now() + windowHours * 3600_000).toISOString(), order.id);
+            })();
+        }
+        catch (e) {
+            return void errorRes(res, 409, 'ACCEPT_FAILED', e.message);
+        }
+        notify(order.buyer_id, order.id, 'direct_pay_accepted_by_seller', '✅ 卖家已确认接单,请付款', `卖家已确认可发货并接单。请在 ${windowHours} 小时内完成风险确认后查看收款方式并付款;逾期未付订单将进入超时流程。`, { templateKey: 'dp_pending_accept_accepted', params: { hours: windowHours } });
+        return void res.json({ success: true, status: 'direct_pay_window' });
+    });
+    // 卖家谢绝(无法发货/物流不可达等;理由可选,买家可见)→ 无责取消 + 回补库存
+    app.post('/api/orders/:id/pending-accept/decline', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const order = await loadPendingOrder(req, res);
+        if (!order)
+            return;
+        if (order.seller_id !== user.id)
+            return void errorRes(res, 403, 'NOT_ORDER_SELLER', '只有订单卖家可谢绝');
+        const reason = typeof req.body?.reason === 'string' ? req.body.reason.trim().slice(0, 200) : '';
+        try {
+            db.transaction(() => {
+                const t = transition(db, order.id, 'cancelled', user.id, [], `卖家谢绝接单(付款前,无责取消)${reason ? `:${reason}` : ''}`);
+                if (!t.success)
+                    throw new Error(t.error || 'TRANSITION_FAILED');
+                restorePreShipDirectPayStock(db, { fromStatus: 'pending_accept', productId: order.product_id, quantity: Number(order.quantity) || 1 });
+            })();
+        }
+        catch (e) {
+            return void errorRes(res, 409, 'DECLINE_FAILED', e.message);
+        }
+        notify(order.buyer_id, order.id, 'direct_pay_accept_declined', '❌ 卖家未能接单,订单已取消', `卖家未能确认发货${reason ? `(${reason})` : ''}。订单已无责取消 —— 你尚未付款,无需任何操作;双方信誉均不受影响。`, { templateKey: 'dp_pending_accept_declined', params: { reason } });
+        return void res.json({ success: true, status: 'cancelled' });
+    });
+    // ── 询价握手(PR-3,模板外地区)──────────────────────────────────────────
+    // 卖家报价:运费+预计时效(+备注,买家可见)。只能加"运费"一个科目,不能动货款单价(防坐地起价披运费皮);
+    //   货款+运费受【建单快照】单笔上限约束(cap 是买家最大裸损口径,必须含运费;用快照防事后调参绕过)。
+    //   可重复报价(买家确认前修正);每次报价重置响应窗(param direct_pay.quote_confirm_hours,默认 48h)。
+    app.post('/api/orders/:id/pending-accept/quote', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const order = await loadPendingOrder(req, res);
+        if (!order)
+            return;
+        if (order.seller_id !== user.id)
+            return void errorRes(res, 403, 'NOT_ORDER_SELLER', '只有订单卖家可报价');
+        if (Number(order.shipping_quote_required) !== 1)
+            return void errorRes(res, 409, 'NOT_QUOTE_ORDER', '本单不需询价(模板已覆盖或走普通接单)');
+        const fee = Number(req.body?.shipping_fee);
+        if (!Number.isFinite(fee) || fee < 0 || fee > 1_000_000)
+            return void errorRes(res, 400, 'BAD_QUOTE_FEE', '运费必须是 0~1000000 的数字');
+        const feeR = Math.round(fee * 100) / 100;
+        const cap = Number(order.direct_pay_per_tx_cap_units_snapshot);
+        if (Number.isFinite(cap) && cap > 0 && toUnits(Number(order.total_amount)) + toUnits(feeR) > cap) {
+            return void errorRes(res, 409, 'QUOTE_EXCEEDS_CAP', `货款+运费超出本单单笔上限(${toDecimal(cap)} USDC),不能以运费形式突破小额直付边界`);
+        }
+        const est = req.body?.est_days == null ? null : String(req.body.est_days).trim().slice(0, 20) || null;
+        const note = req.body?.note == null ? null : String(req.body.note).trim().slice(0, 200) || null;
+        const confirmHours = Math.max(1, Number(getProtocolParam('direct_pay.quote_confirm_hours', 48)) || 48);
+        await dbRun(`UPDATE orders SET shipping_quote_fee = ?, shipping_quote_est_days = ?, shipping_quote_note = ?, shipping_quote_at = datetime('now'), pending_accept_deadline = ? WHERE id = ? AND status = 'pending_accept'`, [feeR, est, note, new Date(Date.now() + confirmHours * 3600_000).toISOString(), order.id]);
+        notify(order.buyer_id, order.id, 'direct_pay_quote_submitted', '📦 卖家已报价运费,请确认', `卖家确认可发货并报价:运费 ${feeR} USDC${est ? `,预计时效 ${est} 天` : ''}${note ? `(${note})` : ''}。新总额 ${Math.round((Number(order.total_amount) + feeR) * 100) / 100} USDC。请在 ${confirmHours} 小时内确认(确认后进入付款环节)或撤单;逾期订单自动取消。`, { templateKey: 'dp_quote_submitted', params: { fee: feeR, est: est ?? '', note: note ?? '', total: Math.round((Number(order.total_amount) + feeR) * 100) / 100, hours: confirmHours } });
+        return void res.json({ success: true, shipping_quote_fee: feeR, est_days: est, new_total: Math.round((Number(order.total_amount) + feeR) * 100) / 100 });
+    });
+    // 买家确认报价 → 运费并入 total_amount(整数 units 精确加)+ 快照三列 + 重建 payable 参考换算 → 进付款窗。
+    //   CAS:仅 pending_accept 且已报价;总额变更与状态转移同一 db.transaction(要么全生效要么全回滚)。
+    app.post('/api/orders/:id/pending-accept/confirm-quote', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const order = await loadPendingOrder(req, res);
+        if (!order)
+            return;
+        if (order.buyer_id !== user.id)
+            return void errorRes(res, 403, 'NOT_ORDER_BUYER', '只有订单买家可确认报价');
+        if (Number(order.shipping_quote_required) !== 1 || order.shipping_quote_fee == null)
+            return void errorRes(res, 409, 'QUOTE_NOT_SUBMITTED', '卖家尚未报价,不可确认');
+        const feeR = Number(order.shipping_quote_fee);
+        const newTotal = toDecimal(toUnits(Number(order.total_amount)) + toUnits(feeR));
+        const windowHours = Math.max(1, Number(getProtocolParam('direct_pay.payment_window_hours', 4)) || 4);
+        // payable 参考换算按新总额重建(display-only;账户快照缺失/坏 JSON → 保持原样,零阻断)
+        let snapJson = order.direct_pay_account_snapshot;
+        try {
+            if (snapJson) {
+                const snap = JSON.parse(snapJson);
+                snapJson = JSON.stringify({ ...snap, ...buildPayableSnapshot(newTotal, snap.currency ?? null) });
+            }
+        }
+        catch {
+            snapJson = order.direct_pay_account_snapshot;
+        }
+        try {
+            db.transaction(() => {
+                const u = db.prepare(`UPDATE orders SET total_amount = ?, shipping_fee = ?, shipping_est_days = ?, direct_pay_account_snapshot = ?, direct_pay_window_deadline = ? WHERE id = ? AND status = 'pending_accept' AND shipping_quote_fee IS NOT NULL`)
+                    .run(newTotal, feeR, order.shipping_quote_est_days, snapJson, new Date(Date.now() + windowHours * 3600_000).toISOString(), order.id);
+                if (u.changes !== 1)
+                    throw new Error('QUOTE_CONFIRM_RACE');
+                const t = transition(db, order.id, 'direct_pay_window', 'sys_protocol', [], `买家确认运费报价(${feeR} USDC,新总额 ${newTotal})→ 进入直付付款窗口`);
+                if (!t.success)
+                    throw new Error(t.error || 'TRANSITION_FAILED');
+            })();
+        }
+        catch (e) {
+            return void errorRes(res, 409, 'QUOTE_CONFIRM_FAILED', e.message);
+        }
+        // 总额变更后补跑 AML 监控(fail-soft,绝不回流为失败);条款快照补记运费裁决(quote_pending→quote)
+        safeRunDirectPayAmlMonitor(db, { sellerId: order.seller_id, orderId: order.id, nowIso: new Date().toISOString(), getProtocolParam });
+        updateSnapshotShippingQuote(db, order.id, feeR, order.shipping_quote_est_days ?? null);
+        notify(order.seller_id, order.id, 'direct_pay_quote_confirmed', '✅ 买家已确认运费报价', `买家已确认新总额 ${newTotal} USDC(含运费 ${feeR}),订单进入付款窗口。买家完成场外付款并标记后你会收到发货提醒。`, { templateKey: 'dp_quote_confirmed', params: { total: newTotal, fee: feeR } });
+        return void res.json({ success: true, status: 'direct_pay_window', total_amount: newTotal });
+    });
+    // 买家撤单(接单前反悔)→ 无责取消 + 回补库存
+    app.post('/api/orders/:id/pending-accept/cancel', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const order = await loadPendingOrder(req, res);
+        if (!order)
+            return;
+        if (order.buyer_id !== user.id)
+            return void errorRes(res, 403, 'NOT_ORDER_BUYER', '只有订单买家可撤单');
+        try {
+            db.transaction(() => {
+                const t = transition(db, order.id, 'cancelled', user.id, [], '买家在卖家接单前撤单(付款前,无责取消)');
+                if (!t.success)
+                    throw new Error(t.error || 'TRANSITION_FAILED');
+                restorePreShipDirectPayStock(db, { fromStatus: 'pending_accept', productId: order.product_id, quantity: Number(order.quantity) || 1 });
+            })();
+        }
+        catch (e) {
+            return void errorRes(res, 409, 'CANCEL_FAILED', e.message);
+        }
+        notify(order.seller_id, order.id, 'direct_pay_accept_cancelled', '↩️ 买家已撤单', '买家在你确认接单前撤回了订单。订单已无责取消,库存已恢复。', { templateKey: 'dp_pending_accept_cancelled', params: {} });
+        return void res.json({ success: true, status: 'cancelled' });
+    });
+}

package/dist/pwa/routes/direct-pay-returns.js

@@ -0,0 +1,74 @@
+import { markReturnRefunded, confirmReturnRefundReceived } from '../../direct-pay-returns.js';
+import { requireDirectPayHumanPasskey } from '../direct-pay-guards.js';
+import { recordRepEvent } from '../../layer4-economics/L4-3-reputation/reputation-engine.js';
+import { createNotification } from '../../layer2-business/L2-6-notifications/notification-engine.js';
+import { dbOne } from '../../layer0-foundation/L0-1-database/db.js';
+export function registerDirectPayReturnsRoutes(app, deps) {
+    const { db, auth, generateId, errorRes, consumeGateToken } = deps;
+    const httpFor = (code) => code === 'RETURN_NOT_FOUND' ? 404
+        : code === 'NOT_ORDER_BUYER' || code === 'NOT_ORDER_SELLER' ? 403
+            : 409;
+    const notify = (userId, orderId, type, title, body) => {
+        try {
+            createNotification(db, userId, orderId, type, title, body);
+        }
+        catch { /* 通知失败不阻断业务 */ }
+    };
+    app.post('/api/return-requests/:id/mark-refunded', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const refundReference = typeof req.body?.refund_reference === 'string' ? req.body.refund_reference : null;
+        const r = markReturnRefunded(db, { returnId: req.params.id, sellerId: user.id, refundReference, messageId: generateId('rmsg') });
+        if (!r.ok)
+            return void errorRes(res, httpFor(r.error_code), r.error_code || 'RETURN_MARK_REFUNDED_ERROR', r.error || '声明退款失败');
+        const rr = await dbOne('SELECT buyer_id, order_id FROM return_requests WHERE id = ?', [req.params.id]);
+        if (rr)
+            notify(rr.buyer_id, rr.order_id, 'direct_pay_return_refund_marked', '💸 卖家已声明退货退款', `卖家声明已在协议外向你退款${refundReference ? `(退款参考:${String(refundReference).slice(0, 80)})` : ''}。请核实到账后在订单页确认(需 Passkey),退货即完成;若未收到退款请勿确认,可发起争议。`);
+        return void res.json({ success: true, status: r.status });
+    });
+    app.post('/api/return-requests/:id/confirm-refund', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const uid = user.id;
+        // 只读预检(不消费一次性 Passkey token):必须是本人 buyer 的 refund_marked 直付退货
+        const pre = await dbOne('SELECT r.buyer_id, r.status, r.order_id, o.payment_rail FROM return_requests r JOIN orders o ON o.id = r.order_id WHERE r.id = ?', [req.params.id]);
+        if (!pre)
+            return void errorRes(res, 404, 'RETURN_NOT_FOUND', '退货请求不存在');
+        if (pre.buyer_id !== uid)
+            return void errorRes(res, 403, 'NOT_ORDER_BUYER', '只有订单买家可确认收到退款');
+        if (pre.payment_rail !== 'direct_p2p' || pre.status !== 'refund_marked') {
+            return void errorRes(res, 409, 'REFUND_NOT_MARKED', '当前不可确认(卖家尚未声明退款,或非直付退货)');
+        }
+        // RISK 门:确认收款并终结退货 = 终局动作 → 现场真人 Passkey(agent 无 Passkey 硬拒)
+        const gate = requireDirectPayHumanPasskey({ db, consumeGateToken }, {
+            userId: uid, webauthnToken: req.body?.webauthn_token, purpose: 'direct_pay_order_action',
+            validate: (data) => { const d = data; return !!d && d.order_id === pre.order_id && d.action === 'return_refund_confirm'; },
+        });
+        if (!gate.ok)
+            return void errorRes(res, 403, gate.error_code || 'HUMAN_PRESENCE_REQUIRED', gate.reason || '需现场真人 Passkey 确认');
+        let r;
+        try {
+            // CAS 终态翻转 + 全额退款社交计数 -1,同一原子边界(零资金零库存)
+            r = db.transaction(() => confirmReturnRefundReceived(db, { returnId: req.params.id, buyerId: uid, messageId: generateId('rmsg') }))();
+        }
+        catch (e) {
+            return void errorRes(res, 409, 'RETURN_CONFIRM_FAILED', e.message);
+        }
+        if (!r.ok)
+            return void errorRes(res, httpFor(r.error_code), r.error_code || 'RETURN_CONFIRM_ERROR', r.error || '确认失败');
+        // 卖家过错原因 → rep event(与 escrow executeReturnRefund 同口径,tx 外 best-effort)
+        try {
+            if (r.seller_fault_reason && r.seller_id) {
+                recordRepEvent(db, r.seller_id, 'claim_upheld_against', `退货接受 (reason=${r.seller_fault_reason}, return=${req.params.id})`, r.order_id || undefined);
+            }
+        }
+        catch (e) {
+            console.error('[dp return rep event]', e);
+        }
+        if (r.seller_id && r.order_id)
+            notify(r.seller_id, r.order_id, 'direct_pay_return_settled', '✅ 退货已完成', '买家已确认收到场外退款,退货流程结束。提示:退回货物须经验收后方可重新上架(库存不会自动恢复)。');
+        return void res.json({ success: true, status: r.status });
+    });
+}