@seasonkoh/webaz 0.1.28 → 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/buyer-feeds.js

@@ -1,4 +1,5 @@
 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 registerBuyerFeedsRoutes(app, deps) {
     // db 已走 RFC-016 异步 seam(dbOne/dbAll),不再直接用 deps.db
     const { auth, isTrustedRole, errorRes, getNearbyCellPrecision, getProtocolParam } = deps;
@@ -28,7 +29,7 @@ export function registerBuyerFeedsRoutes(app, deps) {
             ? `AND p.id NOT IN (${exclArgs.map(() => '?').join(',')})`
             : '';
         const baseCols = `p.id, p.title, p.price, p.stock, p.category, p.images, p.has_variants, p.seller_id,
-      (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,
       u.name as seller_name, u.handle as seller_handle`;
         let followedProducts = [];
         if (followedSellerIds.length > 0) {

package/dist/pwa/routes/chat.js

@@ -108,7 +108,12 @@ export function registerChatRoutes(app, deps) {
         CASE WHEN c.user_a = ? THEN c.unread_a ELSE c.unread_b END as my_unread,
         CASE WHEN c.user_a = ? THEN c.user_b ELSE c.user_a END as other_id,
         (SELECT handle FROM users WHERE id = CASE WHEN c.user_a = ? THEN c.user_b ELSE c.user_a END) as other_handle,
-        (SELECT name   FROM users WHERE id = CASE WHEN c.user_a = ? THEN c.user_b ELSE c.user_a END) as other_name
+        (SELECT name   FROM users WHERE id = CASE WHEN c.user_a = ? THEN c.user_b ELSE c.user_a END) as other_name,
+        -- 友好标签:订单/问商品 → 商品名,让收件箱里同一对方的多个会话可区分(不只显示 kind)。无新 bind 参数(仅用 c.kind/c.context_id)。
+        (CASE c.kind
+           WHEN 'order'      THEN (SELECT p.title FROM orders o JOIN products p ON p.id = o.product_id WHERE o.id = c.context_id)
+           WHEN 'listing_qa' THEN (SELECT title FROM products WHERE id = c.context_id)
+           ELSE NULL END) as context_title
       FROM conversations c
       WHERE (c.user_a = ? OR c.user_b = ?) AND c.status NOT IN ('blocked','archived')
       ORDER BY COALESCE(c.last_message_at, c.created_at) DESC

package/dist/pwa/routes/dashboards.js

@@ -1,4 +1,5 @@
 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 registerDashboardsRoutes(app, deps) {
     // db 已走 RFC-016 异步 seam(dbOne/dbAll),不再直接用 deps.db
     const { auth } = deps;
@@ -70,7 +71,7 @@ export function registerDashboardsRoutes(app, deps) {
     `, [userId, userId, userId, userId, userId, userId]);
         const highComm = await dbAll(`
       SELECT p.id, p.title, p.price, p.commission_rate, p.images, p.category,
-        (SELECT COUNT(*) FROM orders o WHERE o.product_id = p.id AND o.status = 'completed') as sales_count
+        (SELECT COUNT(*) FROM orders o WHERE o.product_id = p.id AND ${genuineSalePredicate('o')}) as sales_count
       FROM products p
       WHERE p.status = 'active'
         AND p.commission_rate > 0

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

@@ -0,0 +1,196 @@
+import { dbOne } from '../../layer0-foundation/L0-1-database/db.js';
+import { toUnits } from '../../money.js';
+import { sellerBaseBondEntrySatisfied } from '../../direct-pay-base-bond-entry.js';
+import { evaluateDirectPayLaunchControls, readDirectPayControlsConfig, sellerDirectPayKybPassed, sellerDirectPaySanctionsClear, sellerDirectPayAmlClear, sellerDirectPayBreakerTripped, coarsenBuyerFacingDirectPayCode, DIRECT_PAY_SELLER_NOT_ELIGIBLE } from '../../direct-pay-controls.js';
+import { checkDeferralQuota, readDeferralQuotaConfig } from '../../direct-pay-deferral-quota.js';
+import { sellerDirectPayReadinessView } from '../../direct-pay-launch-readiness.js';
+import { requestDeferral, getActiveDeferral, getLatestDeferral } from '../../direct-receive-deferral.js';
+import { requestProductVerification, submitProductVerificationLink, listSellerProductVerifications, toSellerProductVerificationView, productStoreVerified } from '../../product-verification.js';
+import { requestStoreVerification, submitStoreVerificationLink, getStoreVerification, toSellerStoreVerificationView, sellerExemptFromPerProduct } from '../../store-verification.js';
+import { getDirectPayFeeAccount } from '../../direct-pay-fee-ar.js';
+export function registerDirectPayAvailabilityRoutes(app, deps) {
+    const { db, auth, getProtocolParam, generateId } = deps;
+    /** 登录 + seller 角色门(缓交申请仅卖家本人)。返回 user 或 null(已写错误响应)。 */
+    function requireSeller(req, res) {
+        const user = auth(req, res);
+        if (!user)
+            return null;
+        if (user.role !== 'seller') {
+            res.status(403).json({ error: '仅卖家可申请缓交', error_code: 'SELLER_ONLY' });
+            return null;
+        }
+        return user;
+    }
+    // GET /api/direct-pay/availability?product_id=... — 该商品(以 qty=1 计)当前是否可直付 + 不可用原因(脱敏)。
+    app.get('/api/direct-pay/availability', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const productId = String(req.query.product_id || '');
+        if (!productId)
+            return void res.status(400).json({ error: '缺少 product_id', error_code: 'MISSING_PRODUCT_ID' });
+        const product = await dbOne('SELECT seller_id, price FROM products WHERE id = ?', [productId]);
+        if (!product)
+            return void res.status(404).json({ error: '商品不存在', error_code: 'PRODUCT_NOT_FOUND' });
+        const cfg = readDirectPayControlsConfig(getProtocolParam);
+        const decision = evaluateDirectPayLaunchControls(cfg, {
+            amountUnits: toUnits(Number(product.price) || 0),
+            sellerBreakerTripped: sellerDirectPayBreakerTripped(db, product.seller_id), // 与 create 路径同源:卖家熔断也判不可用
+            baseBondSatisfied: sellerBaseBondEntrySatisfied(db, product.seller_id, new Date().toISOString()),
+            kycSanctionsPassed: sellerDirectPayKybPassed(db, product.seller_id) && sellerDirectPaySanctionsClear(db, product.seller_id),
+            amlClear: sellerDirectPayAmlClear(db, product.seller_id),
+        });
+        if (decision.ok) {
+            // 硬门(镜像 create):产品逐品验证 OR 卖家被豁免(店铺 verified + per_product_exempt)。都不满足 → 不可直付(产品级、非敏感)。
+            if (!(productStoreVerified(db, productId) || sellerExemptFromPerProduct(db, product.seller_id)))
+                return void res.json({ available: false, error_code: 'DIRECT_PAY_PRODUCT_NOT_VERIFIED', reason: '该商品暂不支持直付(待平台验证)', per_tx_cap_units: cfg.perTxCapUnits });
+            // 镜像 create 的缓交额度门(qty=1 预览;以商品单价为本次拟建单金额)。超额是【缓交卖家私密状态】→ 收敛为通用不可用,
+            //   不向买家暴露"该卖家在缓交期/已超额"。create 仍是权威强制点。
+            const quota = checkDeferralQuota(db, product.seller_id, toUnits(Number(product.price) || 0), new Date().toISOString(), readDeferralQuotaConfig(getProtocolParam));
+            if (!quota.ok)
+                return void res.json({ available: false, error_code: coarsenBuyerFacingDirectPayCode(quota.code), reason: '该卖家暂不支持直付', per_tx_cap_units: cfg.perTxCapUnits });
+            return void res.json({ available: true, per_tx_cap_units: cfg.perTxCapUnits });
+        }
+        const code = coarsenBuyerFacingDirectPayCode(decision.error_code);
+        return void res.json({
+            available: false,
+            error_code: code,
+            reason: code === DIRECT_PAY_SELLER_NOT_ELIGIBLE ? '该卖家暂不支持直付' : decision.reason,
+            per_tx_cap_units: cfg.perTxCapUnits,
+        });
+    });
+    // GET /api/direct-receive/readiness — 卖家【自助脱敏】readiness:仅可行动/状态项(收款说明/Passkey/保证金/审核/暂停/平台开放)。
+    //   绝不下发 raw blocker / KYB·制裁·AML 分项(见 sellerDirectPayReadinessView)。只读 self(auth 用户自身 id)。
+    app.get('/api/direct-receive/readiness', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        return void res.json(sellerDirectPayReadinessView(db, { getProtocolParam, sellerId: user.id }));
+    });
+    // ── 缓交(base-bond deferred deposit)卖家自助:申请 + 查看自己的状态。授予【绝不】在此发生 ──
+    //   申请只创建 pending 行(requestDeferral),【不授予任何权限/资格】;真正放行 = admin ROOT + 真人 Passkey 审批
+    //   (POST /api/admin/direct-receive/deferrals/:id/approve)。故 apply 本身非 RISK 动作、不需 Passkey:无论谁(含 agent)
+    //   申请都拿不到资格,安全门坐落在审批侧。所有合规门(KYC/KYB/制裁/AML/收款说明/Passkey)在直付建单时仍逐一 AND,缓交只免"先交保证金"。
+    // POST /api/direct-receive/deferral — 卖家申请缓交。helper 强制:单一活跃、periodDays 正整数、id 唯一。
+    app.post('/api/direct-receive/deferral', (req, res) => {
+        const user = requireSeller(req, res);
+        if (!user)
+            return;
+        const reason = typeof req.body?.reason === 'string' ? req.body.reason.trim().slice(0, 500) : undefined;
+        const periodDays = req.body?.period_days != null ? Number(req.body.period_days) : undefined;
+        const r = requestDeferral(db, { deferralId: generateId('dfr'), userId: user.id, periodDays, reason, nowIso: new Date().toISOString() });
+        if (!r.ok)
+            return void res.status(400).json({ error: r.reason, error_code: 'DEFERRAL_REQUEST_REJECTED' });
+        return void res.json({ ok: true, status: r.status });
+    });
+    // GET /api/direct-receive/deferral — 卖家本人缓交状态:最新一条申请(脱敏:不含 admin 身份)+ 是否当前生效(active)。
+    app.get('/api/direct-receive/deferral', (req, res) => {
+        const user = requireSeller(req, res);
+        if (!user)
+            return;
+        const sellerId = user.id;
+        const latest = getLatestDeferral(db, sellerId); // 脱敏:不含 approved_by/approved_at(admin 身份)
+        const active = getActiveDeferral(db, sellerId, new Date().toISOString());
+        return void res.json({
+            deferral: latest,
+            active: active ? { reduced_quota_factor: active.reducedQuotaFactor, expires_at: active.expiresAt, grace_until: active.graceUntil, in_grace: active.inGrace } : null,
+        });
+    });
+    // GET /api/direct-receive/my-fee-account — 卖家【本人】平台服务费账户(余额/已计提/退款/在途预估/首单宽限)。
+    //   仅本人(requireSeller),买家拿不到;只读、不碰任何资金动作。供 seller fee center 展示。
+    app.get('/api/direct-receive/my-fee-account', (req, res) => {
+        const user = requireSeller(req, res);
+        if (!user)
+            return;
+        return void res.json({ account: getDirectPayFeeAccount(db, user.id) });
+    });
+    // ── 按产品认证(per-product verification)卖家自助:申领验证码 → 提交外部商品链接 → 查看逐产品状态 ──
+    //   硬门:每个直付商品都须【单独】被真人 admin 核验;一次验证绝不放行所有产品。这里只建/改记录,verify 在 admin 侧。
+    //   所有权:必须卖家本人拥有该产品(读 products.seller_id 校验),否则 403。
+    /** 校验登录卖家拥有该产品;返回 owner user(含 id)或 null(已写错误响应)。productId 由调用方持有。 */
+    async function requireOwnedProduct(req, res, productId) {
+        const user = requireSeller(req, res);
+        if (!user)
+            return null;
+        if (!productId) {
+            res.status(400).json({ error: '缺少 product_id', error_code: 'MISSING_PRODUCT_ID' });
+            return null;
+        }
+        const product = await dbOne('SELECT seller_id FROM products WHERE id = ?', [productId]);
+        if (!product) {
+            res.status(404).json({ error: '商品不存在', error_code: 'PRODUCT_NOT_FOUND' });
+            return null;
+        }
+        if (product.seller_id !== user.id) {
+            res.status(403).json({ error: '只能为自己的商品申请认证', error_code: 'NOT_PRODUCT_OWNER' });
+            return null;
+        }
+        return user;
+    }
+    // POST /api/direct-receive/product-verification — 卖家为某产品申领验证码(单一活跃 per product)。
+    app.post('/api/direct-receive/product-verification', async (req, res) => {
+        const productId = String(req.body?.product_id || '');
+        const user = await requireOwnedProduct(req, res, productId);
+        if (!user)
+            return;
+        const platform = typeof req.body?.platform === 'string' ? req.body.platform.trim().slice(0, 60) : undefined;
+        const r = requestProductVerification(db, { id: generateId('pv'), productId, sellerId: user.id, code: generateId('wzv'), platform });
+        if (!r.ok)
+            return void res.status(400).json({ error: r.reason, error_code: 'PRODUCT_VERIFICATION_REJECTED' });
+        return void res.json({ ok: true, status: r.status, code: r.code });
+    });
+    // PUT /api/direct-receive/product-verification — 卖家为某产品提交外部商品链接(链接仅存储,WebAZ 不抓取)。
+    app.put('/api/direct-receive/product-verification', async (req, res) => {
+        const productId = String(req.body?.product_id || '');
+        const user = await requireOwnedProduct(req, res, productId);
+        if (!user)
+            return;
+        const externalUrl = typeof req.body?.external_url === 'string' ? req.body.external_url.trim() : '';
+        const platform = typeof req.body?.platform === 'string' ? req.body.platform.trim().slice(0, 60) : undefined;
+        const r = submitProductVerificationLink(db, { productId, externalUrl, platform });
+        if (!r.ok)
+            return void res.status(400).json({ error: r.reason, error_code: 'PRODUCT_VERIFICATION_SUBMIT_REJECTED' });
+        return void res.json({ ok: true, status: r.status });
+    });
+    // GET /api/direct-receive/product-verifications — 卖家本人所有产品的认证状态(逐产品)。
+    app.get('/api/direct-receive/product-verifications', (req, res) => {
+        const user = requireSeller(req, res);
+        if (!user)
+            return;
+        // 脱敏:DTO 去掉 reviewed_by(admin 身份)+ notes(内部审核备注),与缓交/readiness 卖家侧一致。
+        return void res.json({ verifications: listSellerProductVerifications(db, user.id).map(toSellerProductVerificationView) });
+    });
+    // ── 店铺认证(per-seller)= 逐品验证的豁免申请路径。卖家申领码 → 提交店铺链接 → admin 核对时勾选豁免。 ──
+    //   申请/提交【不】门 Passkey(只建记录,不授予;豁免授予 = admin ROOT+Passkey 在审核侧)。
+    // POST /api/direct-receive/store-verification — 卖家申领店铺验证码(单一活跃 per seller)。
+    app.post('/api/direct-receive/store-verification', (req, res) => {
+        const user = requireSeller(req, res);
+        if (!user)
+            return;
+        const platform = typeof req.body?.platform === 'string' ? req.body.platform.trim().slice(0, 60) : undefined;
+        const r = requestStoreVerification(db, { id: generateId('sv'), userId: user.id, code: generateId('wzs'), platform });
+        if (!r.ok)
+            return void res.status(400).json({ error: r.reason, error_code: 'STORE_VERIFICATION_REJECTED' });
+        return void res.json({ ok: true, status: r.status, code: r.code });
+    });
+    // PUT /api/direct-receive/store-verification — 卖家提交店铺外链(仅存储,不抓取)。
+    app.put('/api/direct-receive/store-verification', (req, res) => {
+        const user = requireSeller(req, res);
+        if (!user)
+            return;
+        const externalUrl = typeof req.body?.external_url === 'string' ? req.body.external_url.trim() : '';
+        const platform = typeof req.body?.platform === 'string' ? req.body.platform.trim().slice(0, 60) : undefined;
+        const r = submitStoreVerificationLink(db, { userId: user.id, externalUrl, platform });
+        if (!r.ok)
+            return void res.status(400).json({ error: r.reason, error_code: 'STORE_VERIFICATION_SUBMIT_REJECTED' });
+        return void res.json({ ok: true, status: r.status });
+    });
+    // GET /api/direct-receive/store-verification — 卖家本人店铺认证状态(脱敏 DTO,含豁免位)。
+    app.get('/api/direct-receive/store-verification', (req, res) => {
+        const user = requireSeller(req, res);
+        if (!user)
+            return;
+        const row = getStoreVerification(db, user.id);
+        return void res.json({ verification: row ? toSellerStoreVerificationView(row) : null, exempt: sellerExemptFromPerProduct(db, user.id) });
+    });
+}

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

@@ -0,0 +1,79 @@
+import { dbOne } from '../../layer0-foundation/L0-1-database/db.js';
+import { STAGE, recordDisclosureAck, disclosureStageAcked, requireBothDisclosuresAcked, getBuyerDisclosures } from '../../direct-pay-disclosures.js';
+import { requireDirectPayHumanPasskey } from '../direct-pay-guards.js';
+const VALID_STAGES = [STAGE.PRE_SELECT, STAGE.PRE_CONFIRM];
+export function registerDirectPayDisclosureAckRoutes(app, deps) {
+    const { db, auth, generateId, consumeGateToken } = deps;
+    /** 订单存在 + direct_p2p + 调用者本人是 buyer。返回 order 或 null(已写错误响应)。 */
+    async function requireOwnDirectPayOrder(orderId, res, user) {
+        if (!orderId) {
+            res.status(400).json({ error: '缺少 order_id', error_code: 'MISSING_ORDER_ID' });
+            return null;
+        }
+        const order = await dbOne('SELECT id, buyer_id, payment_rail, status FROM orders WHERE id = ?', [orderId]);
+        if (!order) {
+            res.status(404).json({ error: '订单不存在', error_code: 'ORDER_NOT_FOUND' });
+            return null;
+        }
+        if (order.payment_rail !== 'direct_p2p') {
+            res.status(409).json({ error: '风险披露仅适用于直付(direct_p2p)订单', error_code: 'NOT_DIRECT_PAY_ORDER' });
+            return null;
+        }
+        if (order.buyer_id !== user.id) {
+            res.status(403).json({ error: '只能确认自己订单的风险披露', error_code: 'NOT_ORDER_BUYER' });
+            return null;
+        }
+        return order;
+    }
+    // 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 (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;
+        // human-only:现场真人 Passkey 二次确认。purpose 用【固定白名单值】(/api/webauthn/auth/start 才放行申请 challenge);
+        //   order+stage 绑定走 purpose_data + validate(杜绝跨单/跨阶段复用 token),不能塞进 purpose 字符串(那样真实 UI 拿不到 token)。
+        const gate = requireDirectPayHumanPasskey({ db, consumeGateToken }, {
+            userId: user.id, webauthnToken: req.body?.webauthn_token,
+            purpose: 'direct_pay_disclosure_ack',
+            validate: (data) => { const d = data; return !!d && d.order_id === order.id && d.stage === stage; },
+        });
+        if (!gate.ok)
+            return void res.status(403).json({ error: gate.reason, error_code: gate.error_code });
+        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,
+            note: 'ack = 真人本人已阅读并确认风险披露;不代表付款完成,不代表 WebAZ 提供担保/维权/退款',
+        });
+    });
+    // GET — 查询某单两次 ack 状态 + 买家视角披露文案(无卖家机制)。只读(本人),不需 gate token。
+    app.get('/api/direct-pay/disclosure-acks/:orderId', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const order = await requireOwnDirectPayOrder(req.params.orderId, res, user);
+        if (!order)
+            return;
+        const d = getBuyerDisclosures();
+        return void res.json({
+            order_id: order.id,
+            acked: { pre_select: disclosureStageAcked(db, order.id, STAGE.PRE_SELECT), pre_confirm: disclosureStageAcked(db, order.id, STAGE.PRE_CONFIRM) },
+            both: requireBothDisclosuresAcked(db, order.id).ok,
+            disclosures: {
+                pre_select: { zh: d.preSelect.zh, en: d.preSelect.en, version: d.preSelect.version },
+                pre_confirm: { zh: d.preConfirm.zh, en: d.preConfirm.en, version: d.preConfirm.version },
+            },
+        });
+    });
+}