@seasonkoh/webaz 0.1.28 → 0.1.29

package/dist/pwa/routes/admin-direct-receive-deposits.js

@@ -0,0 +1,321 @@
+import { confirmProductionReceipt } from '../../direct-receive-deposits.js';
+import { reviewAmlFlag } from '../../direct-pay-aml-review.js';
+import { recordKybReview, recordSanctionsScreening, recordAmlFlagIngress, amlDetailHash } from '../../direct-pay-compliance-ingress.js';
+import { readDirectPayLaunchReadiness } from '../../direct-pay-launch-readiness.js';
+import { approveDeferral, rejectDeferral, listDeferrals } from '../../direct-receive-deferral.js';
+import { listProductVerifications, reviewProductVerification } from '../../product-verification.js';
+import { listStoreVerifications, reviewStoreVerification } from '../../store-verification.js';
+import { requireDirectPayHumanPasskey } from '../direct-pay-guards.js';
+import { recordFeePrepayTopup, recordFeePrepayAdjustment, recordFeePrepayRefund, getDirectPayFeeAccount } from '../../direct-pay-fee-ar.js';
+export function registerAdminDirectReceiveDepositsRoutes(app, deps) {
+    const { db, requireRootAdmin, consumeGateToken, logAdminAction, getProtocolParam } = deps;
+    // POST /api/admin/direct-receive/deposits/:id/confirm-production — ROOT + 真人 Passkey 手动确认生产保证金 receipt。
+    //   当前恒 fail-closed(无 legal-cleared rail → assert 抛 → PRODUCTION_RAIL_NOT_CLEARED)。
+    app.post('/api/admin/direct-receive/deposits/:id/confirm-production', (req, res) => {
+        const admin = requireRootAdmin(req, res);
+        if (!admin)
+            return;
+        const depositId = req.params.id;
+        const railId = String(req.body?.rail_id || '');
+        const amountUnits = Number(req.body?.expected_amount_units);
+        const receiptRef = String(req.body?.receipt_ref || '');
+        const jurisdiction = String(req.body?.jurisdiction || '');
+        const webauthnToken = req.body?.webauthn_token;
+        // 现场真人 Passkey(铁律)。purpose_data 绑定【完整动作字段】:deposit/rail/amount/receipt/jurisdiction 全等才放行,
+        //   防止把一次签名复用到另一笔/另一参数的确认上。
+        const gate = requireDirectPayHumanPasskey({ db, consumeGateToken }, {
+            userId: admin.id, webauthnToken, purpose: 'direct_receive_production_confirm',
+            validate: (data) => {
+                const d = data;
+                return !!d && d.deposit_id === depositId && d.rail_id === railId && Number(d.amount_units) === amountUnits
+                    && d.receipt_ref === receiptRef && d.jurisdiction === jurisdiction;
+            },
+        });
+        // 每次 ROOT 尝试都审计 —— 含【gate 失败】(生产保证金确认本身是敏感控制事件,缺 Passkey / 缺 token /
+        //   purpose_data 不符的 ROOT 尝试同样要留痕)。非 ROOT 不审计(requireRootAdmin 已拦,无可信 admin 身份)。
+        if (!gate.ok) {
+            logAdminAction(admin.id, 'direct_receive.production_confirm', 'direct_receive_deposit', depositId, { rail_id: railId, jurisdiction, ok: false, outcome: gate.error_code === 'PASSKEY_REQUIRED_FOR_DIRECT_PAY' ? 'passkey_required' : 'human_presence_required', error_code: gate.error_code });
+            return void res.status(403).json({ error: gate.reason, error_code: gate.error_code });
+        }
+        // 写入只走唯一 writer。assert 抛 → 当前恒 fail-closed。每次 ROOT 尝试都审计(含结果)。
+        try {
+            const r = confirmProductionReceipt(db, { depositId, railId, expectedAmountUnits: amountUnits, receiptRef, jurisdiction });
+            logAdminAction(admin.id, 'direct_receive.production_confirm', 'direct_receive_deposit', depositId, { rail_id: railId, jurisdiction, ok: r.ok, outcome: r.ok ? (r.already ? 'already' : 'confirmed') : r.reason });
+            if (!r.ok)
+                return void res.status(409).json({ error: r.reason, error_code: 'PRODUCTION_CONFIRM_REJECTED' });
+            return void res.json({ ok: true, status: r.status, already: !!r.already });
+        }
+        catch (e) {
+            // assertProductionDepositRail(及任何写前异常)→ 生产 rail 未 legal-clear → fail-closed。
+            logAdminAction(admin.id, 'direct_receive.production_confirm', 'direct_receive_deposit', depositId, { rail_id: railId, jurisdiction, ok: false, outcome: 'rail_not_cleared', error: e.message });
+            return void res.status(409).json({ error: '生产保证金收款轨未通过法务/生产放行,暂不可确认', error_code: 'PRODUCTION_RAIL_NOT_CLEARED' });
+        }
+    });
+    // POST /api/admin/direct-receive/aml-flags/:id/review — ROOT + 真人 Passkey 复核单条 AML flag (PR-6E)。
+    //   route 只做 auth + gate + 参数校验 + 调 reviewAmlFlag(唯一 review writer,原子改 flag + 写 audit)。
+    app.post('/api/admin/direct-receive/aml-flags/:id/review', (req, res) => {
+        const admin = requireRootAdmin(req, res);
+        if (!admin)
+            return;
+        const flagId = req.params.id;
+        const decision = String(req.body?.decision || '');
+        const notes = req.body?.notes != null ? String(req.body.notes) : undefined;
+        const webauthnToken = req.body?.webauthn_token;
+        // 现场真人 Passkey(铁律)。purpose_data 绑 flag_id + decision:一次签名只用于该 flag 的该决策,杜绝复用。
+        const gate = requireDirectPayHumanPasskey({ db, consumeGateToken }, {
+            userId: admin.id, webauthnToken, purpose: 'direct_pay_aml_review',
+            validate: (data) => {
+                const d = data;
+                return !!d && d.flag_id === flagId && d.decision === decision;
+            },
+        });
+        if (!gate.ok) {
+            // gate 失败也审计(无 PII:flag_id + decision + 结果);成功复核的审计由 reviewAmlFlag 原子写入。
+            logAdminAction(admin.id, 'direct_pay.aml_review', 'aml_flag', flagId, { decision, ok: false, outcome: gate.error_code === 'PASSKEY_REQUIRED_FOR_DIRECT_PAY' ? 'passkey_required' : 'human_presence_required', error_code: gate.error_code });
+            return void res.status(403).json({ error: gate.reason, error_code: gate.error_code });
+        }
+        const r = reviewAmlFlag(db, { flagId, reviewerId: admin.id, decision, notes });
+        if (!r.ok) {
+            const status = r.error === 'FLAG_NOT_FOUND' ? 404 : 400;
+            return void res.status(status).json({ error: 'AML flag 复核失败', error_code: r.error });
+        }
+        return void res.json({ ok: true, flag_id: r.flagId, decision: r.decision, status: r.status, disposition: r.disposition });
+    });
+    // ── PR-6F 合规 ingress(受控写入入口)。三端点共用:ROOT + 真人 Passkey(purpose-bound)+ 调 ingress helper。 ──
+    //   route 只做 auth + gate + 取参 + 调 helper(helper 原子写台账 + 审计);gate 失败也审计。无 vendor 外呼、无资金/状态机改动。
+    const str = (v) => v != null ? String(v) : '';
+    const opt = (v) => v != null ? String(v) : undefined;
+    // gatedIngress 返回一个 express handler(literal-path app.post 调用之 —— 让 API-doc 扫描器能识别端点)。
+    const gatedIngress = (purpose, makeValidate, run, failAudit) => (req, res) => {
+        const admin = requireRootAdmin(req, res);
+        if (!admin)
+            return;
+        const gate = requireDirectPayHumanPasskey({ db, consumeGateToken }, {
+            userId: admin.id, webauthnToken: req.body?.webauthn_token, purpose, validate: makeValidate(req),
+        });
+        if (!gate.ok) {
+            const fa = failAudit(req);
+            logAdminAction(admin.id, purpose, 'user', fa.targetId, { ...fa.detail, ok: false, error_code: gate.error_code });
+            return void res.status(403).json({ error: gate.reason, error_code: gate.error_code });
+        }
+        const r = run(req, admin.id);
+        if (!r.ok) {
+            // 业务校验失败(Passkey 已过)也留痕:money-adjacent admin 尝试(如退款余额不足被拒)必须可审计。
+            const fa = failAudit(req);
+            logAdminAction(admin.id, purpose, 'user', fa.targetId, { ...fa.detail, ok: false, error_code: r.error });
+            return void res.status(400).json({ error: '合规 ingress 失败', error_code: r.error });
+        }
+        return void res.json({ ok: true, id: r.id });
+    };
+    // POST /api/admin/direct-receive/kyb-reviews — KYB 复核结论 ingress(ROOT + 真人 Passkey)。
+    // Passkey purpose_data 绑定【完整写入内容】(user_id+status+provider_ref+expires_at):签 A 写 B 一律拒。
+    app.post('/api/admin/direct-receive/kyb-reviews', gatedIngress('direct_pay_kyb_ingress', (req) => (data) => {
+        const d = data;
+        return !!d && str(d.user_id) === str(req.body?.user_id) && str(d.status) === str(req.body?.status)
+            && str(d.provider_ref) === str(req.body?.provider_ref) && str(d.expires_at) === str(req.body?.expires_at);
+    }, (req, adminId) => recordKybReview(db, { userId: str(req.body?.user_id), reviewerId: adminId, status: str(req.body?.status), providerRef: opt(req.body?.provider_ref), expiresAt: opt(req.body?.expires_at) }), (req) => ({ targetId: str(req.body?.user_id), detail: { kyb_status: str(req.body?.status) } })));
+    // POST /api/admin/direct-receive/sanctions-screenings — 制裁筛查结论 ingress(ROOT + 真人 Passkey;high-risk)。
+    // purpose_data 绑定 user_id+status+provider_ref+expires_at。
+    app.post('/api/admin/direct-receive/sanctions-screenings', gatedIngress('direct_pay_sanctions_ingress', (req) => (data) => {
+        const d = data;
+        return !!d && str(d.user_id) === str(req.body?.user_id) && str(d.status) === str(req.body?.status)
+            && str(d.provider_ref) === str(req.body?.provider_ref) && str(d.expires_at) === str(req.body?.expires_at);
+    }, (req, adminId) => recordSanctionsScreening(db, { userId: str(req.body?.user_id), reviewerId: adminId, status: str(req.body?.status), providerRef: opt(req.body?.provider_ref), expiresAt: opt(req.body?.expires_at) }), (req) => ({ targetId: str(req.body?.user_id), detail: { sanctions_status: str(req.body?.status) } })));
+    // POST /api/admin/direct-receive/aml-flags — AML flag ingress(ROOT + 真人 Passkey;high-risk)。与 .../aml-flags/:id/review 区分。
+    // purpose_data 绑定 user_id+rule+severity+status+related_order_id+detail_hash(canonical):签 A 写 B 一律拒。
+    const amlDetail = (req) => (req.body?.detail && typeof req.body.detail === 'object' && !Array.isArray(req.body.detail)) ? req.body.detail : undefined;
+    app.post('/api/admin/direct-receive/aml-flags', gatedIngress('direct_pay_aml_ingress', (req) => (data) => {
+        const d = data;
+        return !!d && str(d.user_id) === str(req.body?.user_id) && str(d.rule) === str(req.body?.rule) && str(d.severity) === str(req.body?.severity)
+            && str(d.status) === str(req.body?.status) && str(d.related_order_id) === str(req.body?.related_order_id) && str(d.detail_hash) === amlDetailHash(amlDetail(req));
+    }, (req, adminId) => recordAmlFlagIngress(db, { userId: str(req.body?.user_id), reviewerId: adminId, rule: str(req.body?.rule), severity: str(req.body?.severity), status: str(req.body?.status), relatedOrderId: opt(req.body?.related_order_id), detail: amlDetail(req) }), (req) => ({ targetId: str(req.body?.user_id), detail: { rule: str(req.body?.rule), severity: str(req.body?.severity), aml_status: str(req.body?.status) } })));
+    // POST /api/admin/direct-receive/fee-prepay — 记录商家【平台服务费预付款】(ROOT + 真人 Passkey)。append-only;
+    //   invoice_id NULL = 未分配预充值 → 计入 available_prepay(首单后续建单门)。purpose_data 绑定 seller_id+amount_units+method+evidence_ref。
+    //   不碰 buyer wallet/escrow/order/settlement/refund;非买家 escrow/保证金/penalty。本轮无"余额退款"(仅正向预付款登记)。
+    app.post('/api/admin/direct-receive/fee-prepay', gatedIngress('direct_pay_fee_prepay_record', (req) => (data) => {
+        const d = data;
+        return !!d && str(d.seller_id) === str(req.body?.seller_id) && Number(d.amount_units) === Number(req.body?.amount_units)
+            && str(d.method) === str(req.body?.method) && str(d.evidence_ref) === str(req.body?.evidence_ref);
+    }, (req, adminId) => recordFeePrepayTopup(db, { sellerId: str(req.body?.seller_id), amountUnits: Number(req.body?.amount_units), method: str(req.body?.method), recordedBy: adminId, evidenceRef: opt(req.body?.evidence_ref), note: opt(req.body?.note) }), (req) => ({ targetId: str(req.body?.seller_id), detail: { amount_units: Number(req.body?.amount_units), method: str(req.body?.method) } })));
+    // POST /api/admin/direct-receive/fee-adjust — 平台服务费账务【更正】(ROOT + 真人 Passkey)。带符号 delta;append-only + audit。
+    //   ≠ 退款(不动真钱,只调记账)。purpose_data 绑 seller_id+delta_units+reason。
+    app.post('/api/admin/direct-receive/fee-adjust', gatedIngress('direct_pay_fee_adjust', (req) => (data) => {
+        const d = data;
+        return !!d && str(d.seller_id) === str(req.body?.seller_id) && Number(d.delta_units) === Number(req.body?.delta_units) && str(d.reason) === str(req.body?.reason);
+    }, (req, adminId) => recordFeePrepayAdjustment(db, { sellerId: str(req.body?.seller_id), deltaUnits: Number(req.body?.delta_units), reason: str(req.body?.reason), recordedBy: adminId }), (req) => ({ targetId: str(req.body?.seller_id), detail: { delta_units: Number(req.body?.delta_units) } })));
+    // POST /api/admin/direct-receive/fee-refund — 平台服务费余额【退款】(ROOT + 真人 Passkey)。真实退还未消耗预付款;
+    //   amount ≤ 当前 available(helper 同事务校验)。append-only + audit。purpose_data 绑 seller_id+amount_units+method+evidence_ref。
+    app.post('/api/admin/direct-receive/fee-refund', gatedIngress('direct_pay_fee_refund', (req) => (data) => {
+        const d = data;
+        return !!d && str(d.seller_id) === str(req.body?.seller_id) && Number(d.amount_units) === Number(req.body?.amount_units)
+            && str(d.method) === str(req.body?.method) && str(d.evidence_ref) === str(req.body?.evidence_ref);
+    }, (req, adminId) => recordFeePrepayRefund(db, { sellerId: str(req.body?.seller_id), amountUnits: Number(req.body?.amount_units), method: str(req.body?.method), recordedBy: adminId, evidenceRef: opt(req.body?.evidence_ref), reason: opt(req.body?.reason) }), (req) => ({ targetId: str(req.body?.seller_id), detail: { amount_units: Number(req.body?.amount_units), method: str(req.body?.method) } })));
+    // GET /api/admin/direct-receive/fee-account/:seller_id — ROOT 只读:某商家平台服务费账户汇总(余额/预充值/应收/调整/退款/在途预估/宽限)。
+    //   只读诊断,不写、无 Passkey(读不授权能力);卖家私密财务,买家/卖家拿不到此 admin 视图。
+    app.get('/api/admin/direct-receive/fee-account/:seller_id', (req, res) => {
+        const admin = requireRootAdmin(req, res);
+        if (!admin)
+            return;
+        return void res.json({ ok: true, account: getDirectPayFeeAccount(db, str(req.params.seller_id)) });
+    });
+    // POST /api/admin/direct-receive/readiness — ROOT + 真人 Passkey:返回【完整】Direct Pay launch readiness(blockers + facts,
+    //   含 KYB/sanctions/AML/base-bond/rail clearance 全细节)。只读诊断(不写库、不 flip launch);ROOT 专用,买家/卖家拿不到。
+    app.post('/api/admin/direct-receive/readiness', (req, res) => {
+        const admin = requireRootAdmin(req, res);
+        if (!admin)
+            return;
+        const sellerId = req.body?.seller_id != null ? String(req.body.seller_id) : undefined;
+        const gate = requireDirectPayHumanPasskey({ db, consumeGateToken }, {
+            userId: admin.id, webauthnToken: req.body?.webauthn_token, purpose: 'direct_pay_admin_readiness',
+            validate: (data) => { const d = data; return !!d && String(d.seller_id ?? '') === String(sellerId ?? ''); },
+        });
+        if (!gate.ok) {
+            logAdminAction(admin.id, 'direct_pay.admin_readiness', 'user', sellerId ?? null, { ok: false, error_code: gate.error_code });
+            return void res.status(403).json({ error: gate.reason, error_code: gate.error_code });
+        }
+        const readiness = readDirectPayLaunchReadiness(db, { getProtocolParam, sellerId });
+        logAdminAction(admin.id, 'direct_pay.admin_readiness', 'user', sellerId ?? null, { ok: true, ready: readiness.ready, blocker_count: readiness.blockers.length });
+        return void res.json(readiness);
+    });
+    // ── 缓交(deferred base-bond)审批队列。读 = ROOT;批准/拒绝 = ROOT + 真人 Passkey(铁律,授予绝不自动)。 ──
+    //   approveDeferral/rejectDeferral 是唯一 writer;本文件零 direct_receive_deferrals 直写。审批只改缓交状态机,
+    //   【不】碰 buyer wallet/escrow/order/settlement/refund/privileges,也不 flip launch。
+    const DEFERRAL_STATUSES = new Set(['pending', 'granted', 'rejected', 'expired']);
+    // GET /api/admin/direct-receive/deferrals?status=pending — ROOT 审批队列(默认全部;可按 status 过滤)。纯读。
+    app.get('/api/admin/direct-receive/deferrals', (req, res) => {
+        const admin = requireRootAdmin(req, res);
+        if (!admin)
+            return;
+        const status = req.query?.status != null ? String(req.query.status) : '';
+        if (status && !DEFERRAL_STATUSES.has(status))
+            return void res.status(400).json({ error: '非法 status', error_code: 'BAD_STATUS' });
+        return void res.json({ deferrals: listDeferrals(db, status ? { status: status } : {}) });
+    });
+    // POST /api/admin/direct-receive/deferrals/:id/approve — ROOT + 真人 Passkey 批准缓交。
+    //   Passkey purpose_data 绑定【完整审批条款】(deferral_id + reduced_quota_factor + grace_days):签 A 批 B / 改条款一律拒。
+    app.post('/api/admin/direct-receive/deferrals/:id/approve', (req, res) => {
+        const admin = requireRootAdmin(req, res);
+        if (!admin)
+            return;
+        const deferralId = req.params.id;
+        const rqfRaw = req.body?.reduced_quota_factor;
+        const graceRaw = req.body?.grace_days;
+        const webauthnToken = req.body?.webauthn_token;
+        const gate = requireDirectPayHumanPasskey({ db, consumeGateToken }, {
+            userId: admin.id, webauthnToken, purpose: 'direct_pay_deferral_approve',
+            validate: (data) => {
+                const d = data;
+                return !!d && str(d.deferral_id) === deferralId && str(d.reduced_quota_factor) === str(rqfRaw) && str(d.grace_days) === str(graceRaw);
+            },
+        });
+        if (!gate.ok) {
+            logAdminAction(admin.id, 'direct_pay.deferral_approve', 'direct_receive_deferral', deferralId, { ok: false, outcome: gate.error_code === 'PASSKEY_REQUIRED_FOR_DIRECT_PAY' ? 'passkey_required' : 'human_presence_required', error_code: gate.error_code });
+            return void res.status(403).json({ error: gate.reason, error_code: gate.error_code });
+        }
+        const r = approveDeferral(db, { deferralId, adminId: admin.id, nowIso: new Date().toISOString(),
+            graceDays: graceRaw != null ? Number(graceRaw) : undefined, reducedQuotaFactor: rqfRaw != null ? Number(rqfRaw) : undefined });
+        logAdminAction(admin.id, 'direct_pay.deferral_approve', 'direct_receive_deferral', deferralId, { ok: r.ok, outcome: r.ok ? (r.already ? 'already' : 'granted') : r.reason });
+        if (!r.ok)
+            return void res.status(409).json({ error: r.reason, error_code: 'DEFERRAL_APPROVE_REJECTED' });
+        return void res.json({ ok: true, status: r.status, already: !!r.already });
+    });
+    // POST /api/admin/direct-receive/deferrals/:id/reject — ROOT + 真人 Passkey 拒绝缓交。purpose_data 绑 deferral_id。
+    app.post('/api/admin/direct-receive/deferrals/:id/reject', (req, res) => {
+        const admin = requireRootAdmin(req, res);
+        if (!admin)
+            return;
+        const deferralId = req.params.id;
+        const webauthnToken = req.body?.webauthn_token;
+        const gate = requireDirectPayHumanPasskey({ db, consumeGateToken }, {
+            userId: admin.id, webauthnToken, purpose: 'direct_pay_deferral_reject',
+            validate: (data) => { const d = data; return !!d && str(d.deferral_id) === deferralId; },
+        });
+        if (!gate.ok) {
+            logAdminAction(admin.id, 'direct_pay.deferral_reject', 'direct_receive_deferral', deferralId, { ok: false, outcome: gate.error_code === 'PASSKEY_REQUIRED_FOR_DIRECT_PAY' ? 'passkey_required' : 'human_presence_required', error_code: gate.error_code });
+            return void res.status(403).json({ error: gate.reason, error_code: gate.error_code });
+        }
+        const r = rejectDeferral(db, { deferralId, adminId: admin.id });
+        logAdminAction(admin.id, 'direct_pay.deferral_reject', 'direct_receive_deferral', deferralId, { ok: r.ok, outcome: r.ok ? (r.already ? 'already' : 'rejected') : r.reason });
+        if (!r.ok)
+            return void res.status(409).json({ error: r.reason, error_code: 'DEFERRAL_REJECT_REJECTED' });
+        return void res.json({ ok: true, status: r.status, already: !!r.already });
+    });
+    // ── 按产品认证(per-product verification)审批。读 = ROOT;verify/reject = ROOT + 真人 Passkey(硬门:核验=放行该产品直付,
+    //   capability-granting → 铁律 Passkey)。reviewProductVerification 是唯一 writer;本文件零 product_verifications 直写。 ──
+    const PV_STATUSES = new Set(['issued', 'submitted', 'verified', 'rejected']);
+    // GET /api/admin/direct-receive/product-verifications?status=submitted — ROOT 审核队列(默认全部)。纯读。
+    app.get('/api/admin/direct-receive/product-verifications', (req, res) => {
+        const admin = requireRootAdmin(req, res);
+        if (!admin)
+            return;
+        const status = req.query?.status != null ? String(req.query.status) : '';
+        if (status && !PV_STATUSES.has(status))
+            return void res.status(400).json({ error: '非法 status', error_code: 'BAD_STATUS' });
+        return void res.json({ verifications: listProductVerifications(db, status ? { status: status } : {}) });
+    });
+    // POST /api/admin/direct-receive/product-verifications/:id/review — ROOT + 真人 Passkey 手动核对结论(verified|rejected)。
+    //   Passkey purpose_data 绑 verification_id + decision:签 A 用 B / 改结论一律拒。verify = 放行该产品直付(逐品,绝不放行全部)。
+    app.post('/api/admin/direct-receive/product-verifications/:id/review', (req, res) => {
+        const admin = requireRootAdmin(req, res);
+        if (!admin)
+            return;
+        const verificationId = req.params.id;
+        const decision = String(req.body?.decision || '');
+        const notes = req.body?.notes != null ? String(req.body.notes) : undefined;
+        const webauthnToken = req.body?.webauthn_token;
+        const gate = requireDirectPayHumanPasskey({ db, consumeGateToken }, {
+            userId: admin.id, webauthnToken, purpose: 'direct_pay_product_verify',
+            validate: (data) => { const d = data; return !!d && str(d.verification_id) === verificationId && str(d.decision) === decision; },
+        });
+        if (!gate.ok) {
+            logAdminAction(admin.id, 'direct_pay.product_verify', 'product_verification', verificationId, { decision, ok: false, outcome: gate.error_code === 'PASSKEY_REQUIRED_FOR_DIRECT_PAY' ? 'passkey_required' : 'human_presence_required', error_code: gate.error_code });
+            return void res.status(403).json({ error: gate.reason, error_code: gate.error_code });
+        }
+        const r = reviewProductVerification(db, { id: verificationId, reviewerId: admin.id, decision: decision, notes });
+        logAdminAction(admin.id, 'direct_pay.product_verify', 'product_verification', verificationId, { decision, ok: r.ok, outcome: r.ok ? (r.already ? 'already' : r.status) : r.reason });
+        if (!r.ok)
+            return void res.status(409).json({ error: r.reason, error_code: 'PRODUCT_VERIFICATION_REVIEW_REJECTED' });
+        return void res.json({ ok: true, status: r.status, already: !!r.already });
+    });
+    // ── 店铺认证(per-seller)审批 = 逐品验证豁免决定。读 = ROOT;verify/reject = ROOT + 真人 Passkey。 ──
+    //   核店铺时勾选 per_product_exempt:true → 该卖家所有商品免逐品验证(capability-granting → 铁律 Passkey;
+    //   purpose_data 绑 verification_id+decision+per_product_exempt,签 A 用 B / 改豁免位一律拒)。reviewStoreVerification 唯一 writer。
+    const SV_STATUSES = new Set(['issued', 'submitted', 'verified', 'rejected']);
+    // GET /api/admin/direct-receive/store-verifications?status=submitted — ROOT 审核队列(默认全部)。纯读。
+    app.get('/api/admin/direct-receive/store-verifications', (req, res) => {
+        const admin = requireRootAdmin(req, res);
+        if (!admin)
+            return;
+        const status = req.query?.status != null ? String(req.query.status) : '';
+        if (status && !SV_STATUSES.has(status))
+            return void res.status(400).json({ error: '非法 status', error_code: 'BAD_STATUS' });
+        return void res.json({ verifications: listStoreVerifications(db, status ? { status: status } : {}) });
+    });
+    // POST /api/admin/direct-receive/store-verifications/:id/review — ROOT + 真人 Passkey 核店铺 + 勾选逐品豁免。
+    app.post('/api/admin/direct-receive/store-verifications/:id/review', (req, res) => {
+        const admin = requireRootAdmin(req, res);
+        if (!admin)
+            return;
+        const verificationId = req.params.id;
+        const decision = String(req.body?.decision || '');
+        const perProductExempt = req.body?.per_product_exempt === true;
+        const notes = req.body?.notes != null ? String(req.body.notes) : undefined;
+        const webauthnToken = req.body?.webauthn_token;
+        const gate = requireDirectPayHumanPasskey({ db, consumeGateToken }, {
+            userId: admin.id, webauthnToken, purpose: 'direct_pay_store_verify',
+            validate: (data) => {
+                const d = data;
+                return !!d && str(d.verification_id) === verificationId && str(d.decision) === decision && (d.per_product_exempt === true) === perProductExempt;
+            },
+        });
+        if (!gate.ok) {
+            logAdminAction(admin.id, 'direct_pay.store_verify', 'store_verification', verificationId, { decision, per_product_exempt: perProductExempt, ok: false, outcome: gate.error_code === 'PASSKEY_REQUIRED_FOR_DIRECT_PAY' ? 'passkey_required' : 'human_presence_required', error_code: gate.error_code });
+            return void res.status(403).json({ error: gate.reason, error_code: gate.error_code });
+        }
+        const r = reviewStoreVerification(db, { id: verificationId, reviewerId: admin.id, decision: decision, perProductExempt, notes });
+        logAdminAction(admin.id, 'direct_pay.store_verify', 'store_verification', verificationId, { decision, per_product_exempt: perProductExempt, ok: r.ok, outcome: r.ok ? (r.already ? 'already' : r.status) : r.reason });
+        if (!r.ok)
+            return void res.status(409).json({ error: r.reason, error_code: 'STORE_VERIFICATION_REVIEW_REJECTED' });
+        return void res.json({ ok: true, status: r.status, per_product_exempt: !!r.perProductExempt, already: !!r.already });
+    });
+}

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) });
+    });
+}