@seasonkoh/webaz 0.1.28 → 0.1.29

package/dist/pwa/routes/orders-action.js

@@ -1,6 +1,25 @@
 import { dbOne, dbAll } from '../../layer0-foundation/L0-1-database/db.js';
+import { releaseFeeStake } from '../../direct-pay-ledger.js'; // Rail1 直付:取消/超时释放任何遗留模拟质押(AR 订单无 stake → no-op)
+import { requireBothDisclosuresAcked } from '../../direct-pay-disclosures.js'; // PR-4e: D1/D2 披露契约门
+import { requireDirectPayHumanPasskey } from '../direct-pay-guards.js'; // PR-4e: 现场真人 Passkey/gate-token 门
 export function registerOrdersActionRoutes(app, deps) {
-    const { db, auth, isTrustedRole, generateId, transition, notifyTransition, settleOrder, settleFault, detectFraud, createDispute, checkTimeouts, recordViolationReputation, broadcastSystemEvent } = deps;
+    const { db, auth, isTrustedRole, generateId, transition, notifyTransition, settleOrder, settleFault, detectFraud, createDispute, checkTimeouts, recordViolationReputation, broadcastSystemEvent, consumeGateToken } = deps;
+    // PR-4e: direct_p2p 风险动作门 —— ① D1/D2 两次披露都 ack(缺则 DISCLOSURE_NOT_ACKED);② 现场真人 Passkey + 一次性
+    //   WebAuthn gate token(purpose 固定 direct_pay_order_action,order+action 走 purpose_data + validate)。
+    //   纯前置门:返回 ok 才允许后续写入。【先 disclosure(只读)再 Passkey(消费 token)】→ 缺 ack 不浪费 token。
+    //   调用方必须在【任何写入前 + 只读状态预检之后】调用,避免错误状态消耗 token。
+    function directPayActionGate(orderId, action, userId, webauthnToken) {
+        const disc = requireBothDisclosuresAcked(db, orderId);
+        if (!disc.ok)
+            return { ok: false, status: 409, error: disc.reason || '需先完成两次风险披露确认', error_code: disc.error_code || 'DISCLOSURE_NOT_ACKED' };
+        const gate = requireDirectPayHumanPasskey({ db, consumeGateToken }, {
+            userId, webauthnToken, purpose: 'direct_pay_order_action',
+            validate: (data) => { const d = data; return !!d && d.order_id === orderId && d.action === action; },
+        });
+        if (!gate.ok)
+            return { ok: false, status: 403, error: gate.reason || '需现场真人 Passkey 确认', error_code: gate.error_code || 'HUMAN_PRESENCE_REQUIRED' };
+        return { ok: true };
+    }
     // RFC-007 stage 2：卖家主动拒单 reason_code 白名单。
     //   classification(客观无责 vs 主观有责)是 stage 3 auto-verify 的事;stage 2 仅捕获 + 一律走违约结算。
     //   objective-claimed(stage 3 将尝试确定性核验):stock_consumed_concurrent / stale_price_snapshot / force_majeure
@@ -93,23 +112,38 @@ export function registerOrdersActionRoutes(app, deps) {
             return void res.status(400).json({ error: `订单状态 ${order.status} 不可确认面交` });
         if (order.has_pending_claim)
             return void res.status(400).json({ error: '存在进行中的验证任务，不可确认' });
+        // Rail1:平台费已切换为链下应收(accrue 在完成结算时,与 completed 同一原子边界,fail-closed)。
+        //   建单不再锁 fee-stake,故【不再】前置要求 locked stake(AR 订单本就无 stake)。
+        const isDirectP2p = order.payment_rail === 'direct_p2p';
+        // PR-4e:direct_p2p 面交完成 = RISK 动作 → 两次披露门 + 现场真人 Passkey 门。
+        if (isDirectP2p) {
+            const g = directPayActionGate(req.params.id, 'confirm_in_person', user.id, req.body?.webauthn_token);
+            if (!g.ok)
+                return void res.status(g.status).json({ error: g.error, error_code: g.error_code });
+        }
         const tx = db.transaction(() => {
             db.prepare(`UPDATE orders SET status='completed', updated_at=datetime('now') WHERE id = ?`).run(req.params.id);
             db.prepare(`INSERT INTO order_state_history (id, order_id, from_status, to_status, actor_id, actor_role, notes)
         VALUES (?,?,?,?,?,?, '面交完成 — 买家确认')`)
                 .run(generateId('hst'), req.params.id, order.status, 'completed', user.id, user.role || 'buyer');
+            // direct_p2p:取平台费进同一事务 → 取费失败(缺 locked stake)回滚 completed,订单不会 terminal-completed 而费用落空。
+            if (isDirectP2p)
+                settleOrder(req.params.id);
         });
         try {
             tx();
         }
         catch (e) {
-            return void res.status(500).json({ error: '状态写入失败：' + e.message });
-        }
-        try {
-            settleOrder(req.params.id);
+            return void res.status(isDirectP2p ? 409 : 500).json({ error: (isDirectP2p ? '直付完成结算失败,订单未完成：' : '状态写入失败：') + e.message, ...(isDirectP2p ? { error_code: 'DIRECT_PAY_SETTLE_FAILED' } : {}) });
         }
-        catch (e) {
-            console.error('[settleOrder in-person]', e);
+        // escrow:沿用原有非原子结算(失败仅记日志,不回滚 completed —— 与既有行为一致,本次不改 escrow)。
+        if (!isDirectP2p) {
+            try {
+                settleOrder(req.params.id);
+            }
+            catch (e) {
+                console.error('[settleOrder in-person]', e);
+            }
         }
         res.json({ success: true });
     });
@@ -137,6 +171,32 @@ export function registerOrdersActionRoutes(app, deps) {
         if (action === 'confirm' && uid !== buyerId) {
             return void res.status(403).json({ error: '你不是本订单的买家', error_code: 'NOT_ORDER_BUYER' });
         }
+        // Rail1 直付:买家专属动作。mark_paid = 买家声明"我已付款"→ accepted(进卖家发货流程);
+        //   cancel = 付款前买家取消 → cancelled(释放费用质押)。仅 buyer、仅 direct_p2p 且仍在付款窗口。
+        if (action === 'mark_paid' || action === 'cancel') {
+            if (uid !== buyerId) {
+                return void res.status(403).json({ error: '你不是本订单的买家', error_code: 'NOT_ORDER_BUYER' });
+            }
+            if (order.payment_rail !== 'direct_p2p' || order.status !== 'direct_pay_window') {
+                return void res.status(409).json({ error: '该操作仅适用于直付订单的付款窗口', error_code: 'NOT_DIRECT_PAY_WINDOW' });
+            }
+        }
+        // PR-4e:mark_paid = direct_p2p RISK 动作(已过 direct_pay_window 只读预检)→ 两次披露门 + 现场真人 Passkey 门。cancel 不门控。
+        if (action === 'mark_paid') {
+            const g = directPayActionGate(req.params.id, 'mark_paid', uid, req.body?.webauthn_token);
+            if (!g.ok)
+                return void res.status(g.status).json({ error: g.error, error_code: g.error_code });
+        }
+        // Rail1:平台费链下应收,accrue 在完成结算时(settleOrder direct_p2p 分支)与 completed 同一原子边界、fail-closed
+        //   (accrueFeeReceivable 缺费即抛 → 回滚 completed)。故【不再】前置要求 locked fee-stake。
+        // PR-4e:direct_p2p confirm = RISK 动作。先【只读状态预检】(仅 delivered 可确认收货,杜绝错误状态消耗 token),再两次披露门 + 现场真人 Passkey 门。
+        if (action === 'confirm' && order.payment_rail === 'direct_p2p') {
+            if (order.status !== 'delivered')
+                return void res.status(409).json({ error: `订单状态 ${order.status} 不可确认收货(仅 delivered)`, error_code: 'ORDER_NOT_DELIVERED' });
+            const g = directPayActionGate(req.params.id, 'confirm', uid, req.body?.webauthn_token);
+            if (!g.ok)
+                return void res.status(g.status).json({ error: g.error, error_code: g.error_code });
+        }
         if (action === 'pickup' || action === 'transit' || action === 'deliver') {
             // pickup 时若订单尚无物流，允许领取（孤儿单兜底）
             const isOrphanPickup = action === 'pickup' && !logisticsId;
@@ -254,9 +314,28 @@ export function registerOrdersActionRoutes(app, deps) {
                 note: '已就客观无责拒单发起人工仲裁举证。自动终结已暂停,等待仲裁员裁决:维持→免责全退+退质押,驳回→违约结算。',
             });
         }
+        // Rail1 直付:付款窗口内买家取消 → cancelled + 释放费用质押(单事务:转移成功必同步放质押,
+        //   杜绝"已取消但质押漏放"泄漏 —— cancelled 单超时 cron 不再扫,放质押无后备路径,故必须原子)。
+        if (action === 'cancel') {
+            const fromStatusCancel = order.status;
+            try {
+                db.transaction(() => {
+                    const r = transition(db, req.params.id, 'cancelled', uid, [], notes);
+                    if (!r.success)
+                        throw new Error(r.error || '状态转移失败');
+                    releaseFeeStake(db, { orderId: req.params.id });
+                })();
+            }
+            catch (e) {
+                return void res.status(409).json({ error: e.message, error_code: 'CANCEL_FAILED' });
+            }
+            notifyTransition(db, req.params.id, fromStatusCancel, 'cancelled');
+            return void res.json({ success: true, status: 'cancelled', fee_stake_released: true });
+        }
         const actionMap = {
             accept: 'accepted', ship: 'shipped', pickup: 'picked_up',
-            transit: 'in_transit', deliver: 'delivered', confirm: 'confirmed', dispute: 'disputed'
+            transit: 'in_transit', deliver: 'delivered', confirm: 'confirmed', dispute: 'disputed',
+            mark_paid: 'accepted', // Rail1 直付:买家声明"我已付款" → accepted(汇入既有卖家发货流程;协议不验真实付款)
         };
         const toStatus = actionMap[action];
         if (!toStatus)
@@ -270,6 +349,32 @@ export function registerOrdersActionRoutes(app, deps) {
         VALUES (?,?,?,'description',?,?,?)`).run(eid, req.params.id, user.id, evidence_description, `hash_${Date.now()}`, evReasons.length ? JSON.stringify(evReasons) : null);
             evidenceIds.push(eid);
         }
+        // Rail1 全原子(Codex P1):direct_p2p confirm 必须把 delivered→confirmed→completed→settle/accrue 包进【同一 db.transaction】。
+        //   否则 delivered→confirmed 先单独提交、随后 accrue 失败 → 订单卡在 confirmed(retry 被 ORDER_NOT_DELIVERED 拒)。
+        //   任一步失败 → 整体回滚到 delivered(可重试);成功后再发通知。confirm-in-person 是另一端点、已单事务原子。
+        if (action === 'confirm' && order.payment_rail === 'direct_p2p') {
+            try {
+                db.transaction(() => {
+                    const r1 = transition(db, req.params.id, 'confirmed', user.id, evidenceIds, notes);
+                    if (!r1.success)
+                        throw new Error(r1.error || 'confirmed transition failed');
+                    const r2 = transition(db, req.params.id, 'completed', 'sys_protocol', [], '系统自动结算');
+                    if (!r2.success)
+                        throw new Error(r2.error || 'completed transition failed');
+                    settleOrder(req.params.id); // direct_p2p 分支:释放遗留模拟 stake + accrueFeeReceivable(fail-closed)
+                })();
+            }
+            catch (e) {
+                return void res.status(409).json({ error: `直付完成结算失败,订单未完成(仍停在 delivered,可重试):${e.message}`, error_code: 'DIRECT_PAY_SETTLE_FAILED' });
+            }
+            notifyTransition(db, req.params.id, 'delivered', 'confirmed');
+            notifyTransition(db, req.params.id, 'confirmed', 'completed');
+            try {
+                broadcastSystemEvent('order_completed', '✓', `订单完成 ${req.params.id}`, req.params.id);
+            }
+            catch { }
+            return void res.json({ success: true, status: 'completed', settlement: { rail: 'direct_p2p', fee_accrued: true } });
+        }
         const fromStatus = order.status;
         const result = transition(db, req.params.id, toStatus, user.id, evidenceIds, notes);
         if (!result.success)
@@ -292,6 +397,7 @@ export function registerOrdersActionRoutes(app, deps) {
         let settlementBreakdown = null;
         if (toStatus === 'confirmed') {
             const sysUser = db.prepare("SELECT id FROM users WHERE id = 'sys_protocol'").get();
+            // direct_p2p confirm 已在上方【全原子早返回块】处理(delivered→confirmed→completed→settle 同一 tx);此处仅 escrow。
             transition(db, req.params.id, 'completed', sysUser.id, [], '系统自动结算');
             notifyTransition(db, req.params.id, 'confirmed', 'completed');
             settleOrder(req.params.id);
@@ -339,7 +445,9 @@ export function registerOrdersActionRoutes(app, deps) {
                             reserveByKind.escrow_expired = round2(Number(r.s));
                     }
                     const redirectedToCommissionReserve = round2(reserveByKind.region_cap + reserveByKind.chain_gap + reserveByKind.orphan_sponsor + reserveByKind.opt_out_deactivated + reserveByKind.escrow_expired);
-                    const escrowRow = (await dbOne("SELECT COALESCE(SUM(amount),0) AS s FROM pending_commission_escrow WHERE order_id = ? AND status = 'pending'", [req.params.id]));
+                    // RFC-018: matures_at IS NULL = opt-out escrow only; clearing rows (matures_at NOT NULL) are
+                    // surfaced separately (PR3), not mislabeled as opt-out escrow here.
+                    const escrowRow = (await dbOne("SELECT COALESCE(SUM(amount),0) AS s FROM pending_commission_escrow WHERE order_id = ? AND status = 'pending' AND matures_at IS NULL", [req.params.id]));
                     const heldInOptOutEscrow = round2(Number(escrowRow.s));
                     // QA 轮 9.5 P2：payouts 表只 MCP legacy 写，PWA settleOrder 直更 wallet.balance 不写 payouts
                     // 改用公式推算 sellerAmount（跟 PWA settleOrder 内部计算一致），更可靠

package/dist/pwa/routes/orders-create.js

@@ -1,6 +1,7 @@
 import { buildCartMandate, buildPaymentMandate, signMandate } from './ap2-mandate.js';
 // RFC-014 PR3 — 金额走整数 base-units;钱包写绝对值(防 REAL 浮点加法 dust)。
 import { toUnits, toDecimal, mulQty, mulRate } from '../../money.js';
+import { createDirectPayResponse } from '../../direct-pay-create.js'; // PR-4c: direct_p2p 建单分叉(生产门+收款指令门+原子建单;本金不入协议)
 import { applyWalletDelta } from '../../ledger.js';
 import { dbOne } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam(仅下单事务外的预检查;事务内 escrow/INSERT 保持同步)
 // 店铺推荐 → 商品三级归因的【懒升级】(sync,跑在下单事务内、getProductShareChain 之前)。
@@ -236,6 +237,9 @@ export function registerOrdersCreateRoutes(app, deps) {
         const insurancePremium = toDecimal(insurancePremiumU);
         const totalAmount = toDecimal(totalAmountU);
         const donationAmount = toDecimal(donationAmountU);
+        // PR-4c:direct_p2p 分叉 —— 本金不入协议,跳过下方 escrow 预检/事务,改走直付建单(生产门+收款指令门+原子建单,仅锁卖家 fee-stake)。
+        if (String(req.body?.payment_rail || '') === 'direct_p2p')
+            return void createDirectPayResponse(res, db, { generateId, transition, appendOrderEvent, getProtocolParam }, { product, buyerId: user.id, reqQty, basePrice, totalAmount, totalAmountU, shippingAddress: String(shipping_address), directReceiveAccountId: (typeof req.body?.direct_receive_account_id === 'string' && req.body.direct_receive_account_id) ? String(req.body.direct_receive_account_id) : undefined, opts: { variantId: variant_id, hasVariants: Number(product.has_variants) === 1, flashActive: !!flashSale, couponCode: coupon_code, buyInsurance: !!buy_insurance, donationPct: donationPctNum, isGift: !!is_gift, anonymous: anonymousFlag === 1, deliveryWindow: !!delivery_window } });
         // 友好预检查(读):真正的守恒在下面的同步事务内(applyWalletDelta 绝对值落库)。
         const wallet = await dbOne('SELECT balance FROM wallets WHERE user_id = ?', [user.id]);
         if (!wallet)

package/dist/pwa/routes/orders-read.js

@@ -1,6 +1,9 @@
 // RFC-011 §⑥ 事件游标流(纯 db 函数,party-gated)
 import { listOrderEventsSince } from '../../layer0-foundation/L0-2-state-machine/order-chain.js';
 import { dbOne, dbAll } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
+import { requireBothDisclosuresAcked } from '../../direct-pay-disclosures.js'; // PR-4f-b: direct_p2p 收款说明响应契约门
+import { redactUnackedDirectPayTarget } from '../direct-pay-order-redaction.js'; // 收款目标披露门(共享;所有 orders reader 必过)
+import { getQrImageForOwner } from '../../direct-receive-account-qr.js'; // Rail1 D2:ack 门后按订单快照 qr_ref 取收款码字节((ref,seller_id) 域内)
 export function registerOrdersReadRoutes(app, deps) {
     const { db, auth, getOrderStatus, getOrderChain, verifyOrderChain, getOrderDispute } = deps;
     app.get('/api/orders', async (req, res) => {
@@ -25,6 +28,7 @@ export function registerOrdersReadRoutes(app, deps) {
                 delete o.recipient_code;
                 o.buyer_name = '🔒 ' + (typeof code === 'string' ? code : 'PR-?????');
             }
+            redactUnackedDirectPayTarget(db, o, user.id); // #179 审计 P1:列表也过披露门,不得旁路
         }
         res.json(orders);
     });
@@ -194,6 +198,38 @@ export function registerOrdersReadRoutes(app, deps) {
                 delete order.recipient_code;
             }
         }
+        // Direct Pay 响应契约门:direct_p2p 收款目标(instruction 快照 + 账号快照 qr_ref),买家在 D1/D2 both-acked 前
+        //   【不得】从 API 拿到(非仅 UI 软门)。与 /api/orders 列表共用同一 redact,防旁路(#179 审计 P1)。
+        redactUnackedDirectPayTarget(db, order, user.id);
         res.json({ ...statusInfo, history, product, dispute, trackingInfo });
     });
+    // Rail1 D2:直付订单收款二维码(硬化转发)。仅【订单买家】+ 两次披露 both-acked 后可取;按建单时快照的 (qr_ref, seller_id)
+    //   取【当时那一版】图字节。未 ack / 非买家 / 无 QR / 非 direct_p2p → 统一 404(不枚举,不泄露)。图字节不入 order JSON。
+    app.get('/api/orders/:id/direct-pay-qr', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const orderId = String(req.params.id);
+        const order = await dbOne('SELECT buyer_id, seller_id, payment_rail, direct_pay_account_snapshot FROM orders WHERE id = ?', [orderId]);
+        if (!order || order.payment_rail !== 'direct_p2p' || order.buyer_id !== user.id)
+            return void res.status(404).end();
+        if (!requireBothDisclosuresAcked(db, orderId).ok)
+            return void res.status(404).end(); // 未 ack:与"无 QR"同样 404,不泄露存在性
+        let snap = {};
+        try {
+            snap = order.direct_pay_account_snapshot ? JSON.parse(order.direct_pay_account_snapshot) : {};
+        }
+        catch {
+            snap = {};
+        }
+        if (!snap.qr_ref)
+            return void res.status(404).end();
+        const img = getQrImageForOwner(db, snap.qr_ref, order.seller_id); // (ref, seller_id) 域内取字节;seller_id 取自订单,非用户输入
+        if (!img)
+            return void res.status(404).end();
+        res.setHeader('Content-Type', img.mime);
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        res.setHeader('Cache-Control', 'private, no-store');
+        res.send(img.buf);
+    });
 }

package/dist/pwa/routes/p2p-products.js

@@ -51,8 +51,8 @@ export function registerP2pProductsRoutes(app, deps) {
         await dbRun(`
       INSERT INTO products (id, seller_id, title, description, price, stock, status, images, ship_regions,
         handling_hours, commission_rate, category_id, stake_amount, p2p_mode, content_hash, peer_endpoint,
-        content_signature, content_signed_at)
-      VALUES (?,?,?,?,?,?,'active',?,?,24,0.10,'cat_default',0,1,?,?,?,?)
+        content_signature, content_signed_at, currency)
+      VALUES (?,?,?,?,?,?,'active',?,?,24,0.10,'cat_default',0,1,?,?,?,?,'WAZ')
     `, [
             id, user.id, title,
             `[P2P] ${title}（完整详情见卖家节点）`,

package/dist/pwa/routes/products-create.js

@@ -23,7 +23,7 @@ export function registerProductsCreateRoutes(app, deps) {
         const quotaCheck = checkSellerCanList(user);
         if (!quotaCheck.ok)
             return void res.json({ error: quotaCheck.reason });
-        const { title, description, price, stock = 1, category = '', specs, brand, model, source_url, source_price, external_title, weight_kg, ship_regions = '全国', handling_hours = 24, estimated_days, fragile = 0, return_days = 7, return_condition = '', warranty_days = 0, commission_rate, product_type = 'retail', // 里程碑 6
+        const { title, description, price, stock = 1, category = '', specs, brand, model, source_url, source_price, external_title, weight_kg, ship_regions = '全国', handling_hours = 24, estimated_days, fragile = 0, return_days = 7, return_condition = '', warranty_days = 0, low_stock_threshold = 3, auto_delist_on_zero = 1, commission_rate, product_type = 'retail', // 里程碑 6
         aliases = [], // 里程碑 7.2：上架时同步声明的 alias 集合
         image_hashes = [], // 商品图片 — 只存 hash（64 hex），实际 blob 在卖家节点 IDB
          } = req.body;
@@ -80,14 +80,16 @@ export function registerProductsCreateRoutes(app, deps) {
       specs, brand, model, source_url, source_price, source_price_at,
       weight_kg, ship_regions, handling_hours, estimated_days, fragile,
       return_days, return_condition, warranty_days,
+      low_stock_threshold, auto_delist_on_zero,
       commitment_hash, description_hash, price_hash, hashed_at,
-      commission_rate, product_type, images
-    ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`, [
+      commission_rate, product_type, images, currency
+    ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,'WAZ')`, [
             id, user.id, title, description, priceNum, Number(stock), category, stakeAmount,
             specsJson, brand ?? null, model ?? null,
             source_url ?? null, source_price ? Number(source_price) : null, source_price ? now : null,
             weight_kg ? Number(weight_kg) : null, ship_regions, Number(handling_hours), estJson, fragile ? 1 : 0,
             Number(return_days), return_condition, Number(warranty_days),
+            Math.max(0, Math.floor(Number(low_stock_threshold) || 0)), auto_delist_on_zero ? 1 : 0,
             makeCommitmentHash(pFields), makeDescriptionHash({ title, description, specs: specsJson }),
             makePriceHash(priceNum, now), now,
             commissionRateNum, product_type, imagesJsonForInsert

package/dist/pwa/routes/products-links.js

@@ -1,4 +1,5 @@
 import { dbOne, dbAll, dbRun } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
+import { invalidateProductVerification } from '../../product-verification.js';
 export function registerProductsLinksRoutes(app, deps) {
     // 只读/单写站点走 RFC-016 异步 seam;db 保留:认领冲突分支是 fee-lock 资金路径,
     // INSERT 链接 + INSERT 验证任务 + 钱包扣费必须原子(db.transaction + 守恒/dup guard),Phase 3 迁 pg 行锁。
@@ -15,6 +16,21 @@ export function registerProductsLinksRoutes(app, deps) {
         const links = await dbAll(`SELECT id, url, source, verified, revoked, verify_note, added_at, platform, external_id, external_title FROM product_external_links WHERE product_id = ? ORDER BY added_at ASC`, [req.params.id]);
         res.json(links);
     });
+    // Buyer-facing read for the product detail page: VERIFIED + non-revoked links only, shape { links }.
+    // NOT owner-gated (any logged-in viewer) — separate from the owner-only /links above (which returns a bare
+    // array the seller workbench consumes; that stays untouched). Only public-safe columns are returned.
+    app.get('/api/products/:id/external-links', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        // Mirror product-detail visibility (products-crud GET /:id): others see active only; the seller sees own
+        // non-active. Otherwise 404 — never leak source URLs of a warehouse/deleted product to non-owners.
+        const product = await dbOne("SELECT id FROM products WHERE id = ? AND (status = 'active' OR seller_id = ?)", [req.params.id, user.id]);
+        if (!product)
+            return void res.status(404).json({ error: 'not_found' });
+        const links = await dbAll(`SELECT url, platform, external_title FROM product_external_links WHERE product_id = ? AND verified = 1 AND revoked = 0 ORDER BY added_at ASC`, [req.params.id]);
+        res.json({ links });
+    });
     // 新链接（无人认领）直接 verified=1；已被他人认领则发起众包验证任务
     app.post('/api/products/:id/links', async (req, res) => {
         const user = auth(req, res);
@@ -69,6 +85,12 @@ export function registerProductsLinksRoutes(app, deps) {
             await dbRun(`INSERT INTO product_external_links
         (id, product_id, url, source, verified, verified_at, platform, external_id, external_title)
         VALUES (?, ?, ?, 'manual', 1, datetime('now'), ?, ?, ?)`, [linkId, req.params.id, url, meta?.platform ?? null, meta?.external_id ?? null, linkExternalTitle]);
+            try {
+                invalidateProductVerification(db, String(req.params.id));
+            }
+            catch (e) {
+                console.error('[product-verify invalidate]', e);
+            } // PR-⑥ 反作弊:外链变更 → 作废直付逐品验证
             return void res.json({ link_id: linkId, verified: 1, external_title: linkExternalTitle, message: '链接已关联' });
         }
         // 已被他人认领：发起众包验证任务
@@ -129,6 +151,12 @@ export function registerProductsLinksRoutes(app, deps) {
             console.error('[products-links claim tx]', msg);
             return void res.status(500).json({ error: '发起认领失败,请重试' });
         }
+        try {
+            invalidateProductVerification(db, String(req.params.id));
+        }
+        catch (e) {
+            console.error('[product-verify invalidate]', e);
+        } // PR-⑥ 反作弊:外链变更 → 作废直付逐品验证
         res.json({
             link_id: linkId,
             task_id: taskId,
@@ -147,6 +175,12 @@ export function registerProductsLinksRoutes(app, deps) {
         if (!product || product.seller_id !== user.id)
             return void res.status(403).json({ error: '无权限' });
         await dbRun('DELETE FROM product_external_links WHERE id = ? AND product_id = ?', [req.params.linkId, req.params.id]);
+        try {
+            invalidateProductVerification(db, String(req.params.id));
+        }
+        catch (e) {
+            console.error('[product-verify invalidate]', e);
+        } // PR-⑥ 反作弊:外链变更 → 作废直付逐品验证
         res.json({ success: true });
     });
 }

package/dist/pwa/routes/products-list.js

@@ -1,5 +1,6 @@
 import { createHmac } from 'crypto';
 import { dbOne, dbAll } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
+import { genuineSalePredicate } from '../../layer0-foundation/L0-2-state-machine/genuine-sale.js'; // RFC-018 PR4: 真实成交(排除全额退货)
 export function registerProductsListRoutes(app, deps) {
     // db 已走 RFC-016 异步 seam(dbOne/dbAll),不再直接用 deps.db
     const { getUser, VALID_PRODUCT_TYPES, RAW_MODE_MIN_TRUST, getAgentTrustCached, VALID_SORTS, PRODUCT_LIMITS, TRENDING_SCORE_EXPR, findProductsByAlias, decodeProductCursor, encodeProductCursor, MASTER_SEED, formatProductForAgent } = deps;
@@ -52,7 +53,7 @@ export function registerProductsListRoutes(app, deps) {
       COALESCE(rs.total_points, 0) as rep_points, COALESCE(rs.level, 'new') as rep_level,
       COALESCE(rs.transactions_done, 0) as seller_tx_count,
       pc.seasonal_months as seasonal_months,
-      (SELECT COUNT(1) FROM orders o WHERE o.product_id = p.id AND o.status = 'completed') as sales_count,
+      (SELECT COUNT(1) FROM orders o WHERE o.product_id = p.id AND ${genuineSalePredicate('o')}) as sales_count,
       (SELECT COUNT(DISTINCT buyer_id) FROM order_ratings r WHERE r.product_id = p.id AND r.stars >= 4) as recommend_count,
       (SELECT COUNT(*) FROM dispute_cases dc WHERE dc.seller_id = p.seller_id) as seller_dispute_count,
       -- 卖家仲裁胜率：无案件视为 0.8 中性（未经检验）；有案件按真实比率

package/dist/pwa/routes/products-update.js

@@ -1,7 +1,8 @@
 import { dbOne, dbRun } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
+import { invalidateProductVerification } from '../../product-verification.js';
 export function registerProductsUpdateRoutes(app, deps) {
-    // db 已走 RFC-016 异步 seam(dbOne/dbRun),不再直接用 deps.db
-    const { auth, makeCommitmentHash, makeDescriptionHash, makePriceHash, notifyWaitlist, notifyWishlistPriceDrop, checkStockAndMaybeDelist } = deps;
+    // db 已走 RFC-016 异步 seam(dbOne/dbRun);deps.db 仅用于 direct-pay 逐品验证作废(sync helper,反作弊生命周期)
+    const { db, auth, makeCommitmentHash, makeDescriptionHash, makePriceHash, notifyWaitlist, notifyWishlistPriceDrop, checkStockAndMaybeDelist } = deps;
     app.put('/api/products/:id', async (req, res) => {
         const user = auth(req, res);
         if (!user)
@@ -134,6 +135,25 @@ export function registerProductsUpdateRoutes(app, deps) {
                 console.error('[wishlist price-drop notify]', e);
             }
         }
+        // 反作弊(PR-⑥):任何【买家可见的商品身份字段】变更 → 作废该商品的直付逐品验证,强制重新验证,防"先验证商品 A,
+        //   再改成商品 B"绕过逐品硬门。external-link 变更在 products-links 路由另行作废。fail-soft,不阻断编辑。
+        //   ⚠️ 必须含 i18n_titles/i18n_descs:formatProductForAgent 按 Accept-Language 把 title/description 换成对应语言,
+        //      只改 en/ja/ko 标题描述同样是"换货"(非中文买家看到的就变了);并含 brand/model(商品身份)。
+        const newBrand = brand ?? product.brand;
+        const newModel = model ?? product.model;
+        const eq = (a, b) => String(a ?? '') === String(b ?? '');
+        const materialChanged = !eq(newTitle, product.title) || !eq(newDesc, product.description)
+            || Number(newPrice) !== Number(product.price) || !eq(specsJson, product.specs)
+            || !eq(newI18nTitles, product.i18n_titles) || !eq(newI18nDescs, product.i18n_descs)
+            || !eq(newBrand, product.brand) || !eq(newModel, product.model);
+        if (materialChanged) {
+            try {
+                invalidateProductVerification(db, String(req.params.id));
+            }
+            catch (e) {
+                console.error('[product-verify invalidate]', e);
+            }
+        }
         res.json({ success: true });
     });
 }

package/dist/pwa/routes/promoter.js

@@ -28,6 +28,8 @@ export function registerPromoterRoutes(app, deps) {
         for (const r of earned)
             byLevel[r.level] = { orders: r.orders, total: r.total };
         const grand = byLevel[1].total + byLevel[2].total + byLevel[3].total;
+        // RFC-018: commission accrued but still in the clearing window (matures into grand_total). Pure read.
+        const clearing = (await dbOne("SELECT COALESCE(SUM(amount),0) as s FROM pending_commission_escrow WHERE recipient_user_id = ? AND matures_at IS NOT NULL AND status = 'pending'", [userId])).s;
         const recent = await dbAll(`
       SELECT cr.id, cr.order_id, cr.level, cr.amount, cr.rate, cr.created_at,
              u.name as source_buyer_name
@@ -142,6 +144,7 @@ export function registerPromoterRoutes(app, deps) {
             team: { l1, l2, l3, total: l1 + l2 + l3 },
             earnings: {
                 grand_total: grand,
+                clearing_total: clearing, // RFC-018: accrued, maturing after the return window (not yet paid)
                 l1: byLevel[1],
                 l2: byLevel[2],
                 l3: byLevel[3],

package/dist/pwa/routes/referral.js

@@ -23,6 +23,9 @@ export function registerReferralRoutes(app, deps) {
     `, [user.id]));
         const todayEarnings = (await dbOne(`SELECT COALESCE(SUM(amount), 0) as t FROM commission_records WHERE beneficiary_id = ? AND created_at > datetime('now', '-1 day')`, [user.id])).t;
         const monthEarnings = (await dbOne(`SELECT COALESCE(SUM(amount), 0) as t FROM commission_records WHERE beneficiary_id = ? AND created_at > datetime('now', '-30 days')`, [user.id])).t;
+        // RFC-018: commission accrued but still in the clearing window (pending → matures into total_waz).
+        // Pure read; surfaced so earnings don't appear to vanish during clearing (Option A keeps total_waz = paid).
+        const clearingWaz = (await dbOne(`SELECT COALESCE(SUM(amount), 0) as t FROM pending_commission_escrow WHERE recipient_user_id = ? AND matures_at IS NOT NULL AND status = 'pending'`, [user.id])).t;
         res.json({
             invite_code: code,
             invite_link: code ? `${req.protocol}://${req.get('host')}/i/${code}` : null,
@@ -34,6 +37,7 @@ export function registerReferralRoutes(app, deps) {
                 total_waz: earnings.total,
                 today_waz: todayEarnings,
                 month_waz: monthEarnings,
+                clearing_waz: clearingWaz, // RFC-018: accrued, maturing after the return window (not yet paid)
             },
         });
     });

package/dist/pwa/routes/returns.js

@@ -30,6 +30,26 @@ export function registerReturnsRoutes(app, deps) {
             if (debited.changes !== 1)
                 throw new Error('INSUFFICIENT_SELLER_BALANCE');
             db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(refundAmt, rr.buyer_id);
+            // RFC-018: reverse this order's in-window clearing commission, proportional to the refund.
+            // These pending rows were never paid (maturation is gated on matures_at), so this is a pure
+            // reversal — no clawback. matures_at IS NOT NULL targets clearing rows only; opt-out escrow
+            // rows (matures_at IS NULL) are untouched. Atomic with the refund.
+            const ordTotal = Number(db.prepare('SELECT total_amount FROM orders WHERE id = ?').get(rr.order_id)?.total_amount ?? 0);
+            const refundFrac = ordTotal > 0 ? Math.min(1, refundAmt / ordTotal) : 1;
+            if (refundFrac >= 1) {
+                db.prepare(`UPDATE pending_commission_escrow SET status='reversed' WHERE order_id = ? AND status='pending' AND matures_at IS NOT NULL`).run(rr.order_id);
+                // RFC-018 PR4: a single FULL return is no longer a genuine sale — decrement the stored product
+                // completion_count (incremented at settleOrder). Idempotent: the return CAS'd to 'refunded'
+                // exactly once above, so this runs once. Partial refund stays a genuine sale (no decrement).
+                // Edge: multiple partial refunds cumulatively reaching full aren't caught here (each refundFrac<1),
+                // so the stored counter may transiently over-count by 1 — but the AUTHORITATIVE genuine count
+                // (genuineSalePredicate, cumulative SUM) is correct everywhere on-read, and the completion_count
+                // backfill (genuine-aware) self-heals the stored counter. completion_count is best-effort social proof.
+                db.prepare(`UPDATE products SET completion_count = MAX(0, COALESCE(completion_count,0) - 1) WHERE id = ?`).run(rr.product_id);
+            }
+            else {
+                db.prepare(`UPDATE pending_commission_escrow SET amount = amount * ? WHERE order_id = ? AND status='pending' AND matures_at IS NOT NULL`).run(1 - refundFrac, rr.order_id);
+            }
             // 3. 恢复库存(CAS + 扣款成功后)
             const ord = db.prepare('SELECT quantity, source, variant_id FROM orders WHERE id = ?').get(rr.order_id);
             if (ord && ord.source !== 'secondhand') {
@@ -69,7 +89,7 @@ export function registerReturnsRoutes(app, deps) {
             return void errorRes(res, 403, 'TRUSTED_ROLE_NO_TRADE', '受信角色无购物功能');
         const order = await dbOne(`
       SELECT o.id, o.buyer_id, o.seller_id, o.product_id, o.status, o.total_amount, o.created_at, o.updated_at,
-             p.return_days, p.title as product_title
+             o.payment_rail, p.return_days, p.title as product_title
       FROM orders o JOIN products p ON p.id = o.product_id
       WHERE o.id = ?
     `, [req.params.order_id]);
@@ -77,6 +97,11 @@ export function registerReturnsRoutes(app, deps) {
             return void res.status(404).json({ error: '订单不存在' });
         if (order.buyer_id !== user.id)
             return void res.status(403).json({ error: '仅买家可申请退货' });
+        // 直付(Rail1)= 非托管、refund:none —— WebAZ 不持货款,退款经现有 escrow 钱包路径会错误移动无关 WAZ。
+        //   故 direct_p2p 不走退货/退款流程(买家不满走争议=信誉处理);平台费应收的冲销由治理/admin 调整处理(非此路径)。
+        if (order.payment_rail === 'direct_p2p') {
+            return void res.status(400).json({ error: '直付(非托管)订单不支持退款流程;如有问题请发起争议', error_code: 'DIRECT_PAY_NO_REFUND' });
+        }
         // P0-1: 只允许 completed 退货 — escrow 已结算
         if (order.status !== 'completed') {
             return void res.status(400).json({ error: '仅订单完成后可申请退货（确认收货后）' });

package/dist/pwa/routes/rewards-apply.js

@@ -37,8 +37,10 @@ export function registerRewardsApplyRoutes(app, deps) {
             missing.push(`completed_orders ${completedOrders}/${minOrders}`);
         if (requirePasskey === 1 && passkeyCount === 0)
             missing.push('passkey_not_registered');
-        const pending = (await dbOne("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'pending'", [userId]));
-        const expired = (await dbOne("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'expired'", [userId]));
+        // RFC-018: matures_at IS NULL = opt-out escrow (claimable on activation). Clearing rows
+        // (matures_at NOT NULL) auto-mature via rewards-clearing-mature and must NOT be drained here.
+        const pending = (await dbOne("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'pending' AND matures_at IS NULL", [userId]));
+        const expired = (await dbOne("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'expired' AND matures_at IS NULL", [userId]));
         res.json({
             state,
             opted_in: optIn === 1,
@@ -138,12 +140,15 @@ export function registerRewardsApplyRoutes(app, deps) {
                     VALUES (?, 'activate', ?, ?, ?, ?, ?, ?, ?)`)
                     .run(userId, consent_version, currentMajor.hash, webauthn_token || null, // store gate_token id as audit cross-ref to webauthn_gate_tokens
                 requirePasskey === 1 ? 'passkey' : 'password', sha256_hex(req.ip || '').slice(0, 16), sha256_hex(String(req.headers['user-agent'] || '')).slice(0, 16), now);
-                // Activate batch settle: drain pending escrow to wallet
+                // Activate batch settle: drain OPT-OUT escrow to wallet. RFC-018: matures_at IS NULL excludes
+                // clearing rows — those are NOT claimable on opt-in; they auto-mature after the return window
+                // (rewards-clearing-mature). Draining them here would pay commission early and defeat the
+                // clearing window's reversal guarantee (a returned order could no longer be reversed → clawback).
                 const pending = db.prepare(`SELECT id, amount, attribution_path FROM pending_commission_escrow
-                                    WHERE recipient_user_id = ? AND status = 'pending' AND expires_at > ?`).all(userId, now);
+                                    WHERE recipient_user_id = ? AND status = 'pending' AND matures_at IS NULL AND expires_at > ?`).all(userId, now);
                 let total = 0;
                 for (const p of pending) {
-                    const upd = db.prepare(`UPDATE pending_commission_escrow SET status='settled', settled_at=? WHERE id=? AND status='pending'`).run(now, p.id);
+                    const upd = db.prepare(`UPDATE pending_commission_escrow SET status='settled', settled_at=? WHERE id=? AND status='pending' AND matures_at IS NULL`).run(now, p.id);
                     if (upd.changes === 0)
                         continue; // race: expire cron took it
                     db.prepare(`UPDATE wallets SET balance = balance + ?, earned = earned + ? WHERE user_id = ?`).run(p.amount, p.amount, userId);