@seasonkoh/webaz 0.1.23 → 0.1.25

package/dist/pwa/routes/returns.js

@@ -1,4 +1,7 @@
 import { recordRepEvent } from '../../layer4-economics/L4-3-reputation/reputation-engine.js';
+// RFC-016 Phase 1 — 端点校验读/列表读 + 状态翻转/消息/通知单写 → async seam;
+//   executeReturnRefund 退款 db.transaction(钱+库存)与 escalate 建争议 tx 保持同步(Phase 3 迁 pg)。
+import { dbOne, dbAll, dbRun } from '../../layer0-foundation/L0-1-database/db.js';
 const VALID_RETURN_REASONS = new Set(['quality', 'wrong_item', 'damaged', 'no_longer_needed', 'other']);
 const RETURN_REASON_DEFAULT_LABEL = {
     quality: '质量问题',
@@ -10,15 +13,24 @@ const RETURN_REASON_DEFAULT_LABEL = {
 export function registerReturnsRoutes(app, deps) {
     const { db, generateId, auth, isTrustedRole, errorRes, broadcastSystemEvent, detectFraud } = deps;
     // L3 Phase 2 抽出：accept(无 pickup) 和 received(有 pickup) 共享退款 + 库存 + 通知
-    function executeReturnRefund(rr, response) {
+    // fromStatus = 调用方允许的源状态(accept-no-pickup='pending' / received='picked_up')。
+    // Codex #235 P1:两个端点都 await 预读 rr.status 后才进入这个同步 tx,await 间隔内
+    // 并发请求可都看到 pending/picked_up → 双双退款。故 tx 内先用 fromStatus CAS 抢占,
+    // 先于任何钱/库存写;changes!==1 即并发已结算 → 抛回滚。
+    function executeReturnRefund(rr, response, fromStatus) {
         db.transaction(() => {
             const refundAmt = Number(rr.refund_amount);
-            const sellerWal = db.prepare('SELECT balance FROM wallets WHERE user_id = ?').get(rr.seller_id);
-            if (!sellerWal || Number(sellerWal.balance) < refundAmt) {
+            // 1. CAS 抢占 return 行(fromStatus→refunded),先于任何写
+            const claimed = db.prepare(`UPDATE return_requests SET status = 'refunded', seller_response = COALESCE(?, seller_response), resolved_at = datetime('now') WHERE id = ? AND status = ?`)
+                .run(response, rr.id, fromStatus);
+            if (claimed.changes !== 1)
+                throw new Error('RETURN_ALREADY_SETTLED');
+            // 2. 卖家扣款带余额守卫;changes!==1 = 余额不足 → 抛回滚,买家不入账
+            const debited = db.prepare('UPDATE wallets SET balance = balance - ? WHERE user_id = ? AND balance >= ?').run(refundAmt, rr.seller_id, refundAmt);
+            if (debited.changes !== 1)
                 throw new Error('INSUFFICIENT_SELLER_BALANCE');
-            }
-            db.prepare('UPDATE wallets SET balance = balance - ? WHERE user_id = ?').run(refundAmt, rr.seller_id);
             db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(refundAmt, rr.buyer_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') {
                 const qty = Math.max(1, Number(ord.quantity) || 1);
@@ -27,8 +39,6 @@ export function registerReturnsRoutes(app, deps) {
                     db.prepare('UPDATE product_variants SET stock = stock + ?, updated_at = datetime(\'now\') WHERE id = ?').run(qty, ord.variant_id);
                 }
             }
-            db.prepare(`UPDATE return_requests SET status = 'refunded', seller_response = COALESCE(?, seller_response), resolved_at = datetime('now') WHERE id = ?`)
-                .run(response, rr.id);
             try {
                 db.prepare(`INSERT INTO return_messages (id, return_id, sender_id, sender_role, body) VALUES (?,?,?,?,?)`)
                     .run(generateId('rmsg'), rr.id, rr.seller_id, 'seller', `[✓ 已退款] ${response || ''}`);
@@ -51,18 +61,18 @@ export function registerReturnsRoutes(app, deps) {
         }
     }
     // buyer 发起退货
-    app.post('/api/orders/:order_id/return-request', (req, res) => {
+    app.post('/api/orders/:order_id/return-request', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
         if (isTrustedRole(user))
             return void errorRes(res, 403, 'TRUSTED_ROLE_NO_TRADE', '受信角色无购物功能');
-        const order = db.prepare(`
+        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
       FROM orders o JOIN products p ON p.id = o.product_id
       WHERE o.id = ?
-    `).get(req.params.order_id);
+    `, [req.params.order_id]);
         if (!order)
             return void res.status(404).json({ error: '订单不存在' });
         if (order.buyer_id !== user.id)
@@ -79,9 +89,9 @@ export function registerReturnsRoutes(app, deps) {
         if (Date.now() > deadlineMs) {
             return void res.status(400).json({ error: `已超过 ${returnDays} 天退货窗口` });
         }
-        const existing = db.prepare(`
+        const existing = await dbOne(`
       SELECT id, status FROM return_requests WHERE order_id = ? AND status IN ('pending', 'accepted') LIMIT 1
-    `).get(order.id);
+    `, [order.id]);
         if (existing)
             return void res.status(400).json({ error: `已存在退货请求 (${existing.status})` });
         const reason = String(req.body?.reason || '');
@@ -101,15 +111,14 @@ export function registerReturnsRoutes(app, deps) {
             return void res.status(400).json({ error: '请求上门取件时必须提供取件地址（≥ 4 字）' });
         }
         const reqId = generateId('ret');
-        db.prepare(`
+        await dbRun(`
       INSERT INTO return_requests (id, order_id, buyer_id, seller_id, product_id, reason, reason_text, refund_amount, status, pickup_requested, pickup_address)
       VALUES (?,?,?,?,?,?,?,?,'pending',?,?)
-    `).run(reqId, order.id, order.buyer_id, order.seller_id, order.product_id, reason, reasonText, refundAmount, pickupRequested, pickupAddress);
+    `, [reqId, order.id, order.buyer_id, order.seller_id, order.product_id, reason, reasonText, refundAmount, pickupRequested, pickupAddress]);
         try {
             const actions = JSON.stringify([{ kind: 'navigate', label: '处理退货', href: `#order/${order.id}`, style: 'primary' }]);
             const pickupNote = pickupRequested ? '（含上门取件请求）' : '';
-            db.prepare(`INSERT INTO notifications (id, user_id, type, title, body, order_id, actions) VALUES (?,?,?,?,?,?,?)`)
-                .run(generateId('ntf'), order.seller_id, 'return_request', '⚠ 收到退货请求' + pickupNote, `订单 ${order.product_title} 申请退货 — 原因：${reason}${pickupRequested ? '\n📍 上门取件：' + pickupAddress : ''}`, order.id, actions);
+            await dbRun(`INSERT INTO notifications (id, user_id, type, title, body, order_id, actions) VALUES (?,?,?,?,?,?,?)`, [generateId('ntf'), order.seller_id, 'return_request', '⚠ 收到退货请求' + pickupNote, `订单 ${order.product_title} 申请退货 — 原因：${reason}${pickupRequested ? '\n📍 上门取件：' + pickupAddress : ''}`, order.id, actions]);
         }
         catch (e) {
             console.error('[return notify]', e);
@@ -121,26 +130,26 @@ export function registerReturnsRoutes(app, deps) {
         res.json({ success: true, id: reqId, pickup_requested: !!pickupRequested });
     });
     // P1-5: 订单级直查
-    app.get('/api/orders/:order_id/return-request', (req, res) => {
+    app.get('/api/orders/:order_id/return-request', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
-        const order = db.prepare('SELECT buyer_id, seller_id FROM orders WHERE id = ?').get(req.params.order_id);
+        const order = await dbOne('SELECT buyer_id, seller_id FROM orders WHERE id = ?', [req.params.order_id]);
         if (!order)
             return void res.status(404).json({ error: '订单不存在' });
         if (order.buyer_id !== user.id && order.seller_id !== user.id) {
             return void res.status(403).json({ error: '无权查看' });
         }
-        const row = db.prepare(`
+        const row = await dbOne(`
       SELECT id, order_id, product_id, reason, reason_text, refund_amount,
              status, seller_response, escalated_dispute_id, created_at, resolved_at
       FROM return_requests
       WHERE order_id = ?
       ORDER BY created_at DESC LIMIT 1
-    `).get(req.params.order_id);
+    `, [req.params.order_id]);
         res.json({ item: row || null });
     });
-    app.get('/api/return-requests', (req, res) => {
+    app.get('/api/return-requests', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
@@ -153,7 +162,7 @@ export function registerReturnsRoutes(app, deps) {
             where.push('r.status = ?');
             params.push(status);
         }
-        const rows = db.prepare(`
+        const rows = await dbAll(`
       SELECT r.id, r.order_id, r.product_id, r.reason, r.reason_text, r.refund_amount,
              r.status, r.seller_response, r.escalated_dispute_id, r.created_at, r.resolved_at,
              p.title as product_title, p.category,
@@ -167,14 +176,14 @@ export function registerReturnsRoutes(app, deps) {
       JOIN users us ON us.id = r.seller_id
       WHERE ${where.join(' AND ')}
       ORDER BY r.created_at DESC LIMIT 200
-    `).all(...params);
+    `, params);
         res.json({ items: rows });
     });
-    app.post('/api/return-requests/:id/decide', (req, res) => {
+    app.post('/api/return-requests/:id/decide', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
-        const rr = db.prepare(`SELECT * FROM return_requests WHERE id = ?`).get(req.params.id);
+        const rr = await dbOne(`SELECT * FROM return_requests WHERE id = ?`, [req.params.id]);
         if (!rr)
             return void res.status(404).json({ error: '退货请求不存在' });
         if (rr.seller_id !== user.id)
@@ -189,65 +198,62 @@ export function registerReturnsRoutes(app, deps) {
             return void res.status(400).json({ error: '拒绝时必须填写说明' });
         if (decision === 'accept') {
             if (Number(rr.pickup_requested) === 1) {
-                db.prepare(`UPDATE return_requests SET status = 'accepted_pickup_pending', seller_response = ? WHERE id = ?`)
-                    .run(response, rr.id);
+                await dbRun(`UPDATE return_requests SET status = 'accepted_pickup_pending', seller_response = ? WHERE id = ?`, [response, rr.id]);
                 try {
-                    db.prepare(`INSERT INTO return_messages (id, return_id, sender_id, sender_role, body) VALUES (?,?,?,?,?)`)
-                        .run(generateId('rmsg'), rr.id, rr.seller_id, 'seller', `[✓ 同意 · 等待上门取件] ${response || ''}`);
+                    await dbRun(`INSERT INTO return_messages (id, return_id, sender_id, sender_role, body) VALUES (?,?,?,?,?)`, [generateId('rmsg'), rr.id, rr.seller_id, 'seller', `[✓ 同意 · 等待上门取件] ${response || ''}`]);
                 }
                 catch { }
                 try {
-                    db.prepare(`INSERT INTO notifications (id, user_id, title, body, order_id) VALUES (?,?,?,?,?)`)
-                        .run(generateId('ntf'), rr.buyer_id, '✓ 退货已接受 · 等待上门取件', `卖家将安排物流到 ${rr.pickup_address || '指定地址'} 上门取件`, rr.order_id);
+                    await dbRun(`INSERT INTO notifications (id, user_id, title, body, order_id) VALUES (?,?,?,?,?)`, [generateId('ntf'), rr.buyer_id, '✓ 退货已接受 · 等待上门取件', `卖家将安排物流到 ${rr.pickup_address || '指定地址'} 上门取件`, rr.order_id]);
                 }
                 catch { }
                 return void res.json({ success: true, status: 'accepted_pickup_pending' });
             }
             try {
-                executeReturnRefund(rr, response);
+                executeReturnRefund(rr, response, 'pending');
             }
             catch (e) {
-                const msg = e.message === 'INSUFFICIENT_SELLER_BALANCE' ? '卖家余额不足以退款' : '退款失败';
+                const m = e.message;
+                if (m === 'RETURN_ALREADY_SETTLED')
+                    return void res.status(409).json({ error: '该退货已处理（请刷新后查看）' });
+                const msg = m === 'INSUFFICIENT_SELLER_BALANCE' ? '卖家余额不足以退款' : '退款失败';
                 return void res.status(400).json({ error: msg });
             }
             return void res.json({ success: true, status: 'refunded' });
         }
         else {
-            db.prepare(`UPDATE return_requests SET status = 'rejected', seller_response = ?, resolved_at = datetime('now') WHERE id = ?`)
-                .run(response, rr.id);
+            await dbRun(`UPDATE return_requests SET status = 'rejected', seller_response = ?, resolved_at = datetime('now') WHERE id = ?`, [response, rr.id]);
             try {
-                db.prepare(`INSERT INTO return_messages (id, return_id, sender_id, sender_role, body) VALUES (?,?,?,?,?)`)
-                    .run(generateId('rmsg'), rr.id, rr.seller_id, 'seller', `[✗ 拒绝退款] ${response}`);
+                await dbRun(`INSERT INTO return_messages (id, return_id, sender_id, sender_role, body) VALUES (?,?,?,?,?)`, [generateId('rmsg'), rr.id, rr.seller_id, 'seller', `[✗ 拒绝退款] ${response}`]);
             }
             catch { }
             try {
-                db.prepare(`INSERT INTO notifications (id, user_id, title, body, order_id) VALUES (?,?,?,?,?)`)
-                    .run(generateId('ntf'), rr.buyer_id, '⚠ 退货请求被拒绝', `卖家说明：${response} — 如有异议可发起争议`, rr.order_id);
+                await dbRun(`INSERT INTO notifications (id, user_id, title, body, order_id) VALUES (?,?,?,?,?)`, [generateId('ntf'), rr.buyer_id, '⚠ 退货请求被拒绝', `卖家说明：${response} — 如有异议可发起争议`, rr.order_id]);
             }
             catch { }
             return void res.json({ success: true, status: 'rejected' });
         }
     });
-    app.delete('/api/return-requests/:id', (req, res) => {
+    app.delete('/api/return-requests/:id', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
-        const rr = db.prepare(`SELECT id, buyer_id, status FROM return_requests WHERE id = ?`).get(req.params.id);
+        const rr = await dbOne(`SELECT id, buyer_id, status FROM return_requests WHERE id = ?`, [req.params.id]);
         if (!rr)
             return void res.status(404).json({ error: '不存在' });
         if (rr.buyer_id !== user.id)
             return void res.status(403).json({ error: '仅买家可取消' });
         if (rr.status !== 'pending')
             return void res.status(400).json({ error: `当前状态 ${rr.status}，不可取消` });
-        db.prepare(`UPDATE return_requests SET status = 'cancelled', resolved_at = datetime('now') WHERE id = ?`).run(rr.id);
+        await dbRun(`UPDATE return_requests SET status = 'cancelled', resolved_at = datetime('now') WHERE id = ?`, [rr.id]);
         res.json({ success: true });
     });
     // ─── W2 售后协商时间线 ───────────────────────────────
-    app.get('/api/return-requests/:id', (req, res) => {
+    app.get('/api/return-requests/:id', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
-        const rr = db.prepare(`
+        const rr = await dbOne(`
       SELECT r.*, p.title as product_title, p.category,
              o.total_amount as order_total,
              ub.name as buyer_name, ub.handle as buyer_handle,
@@ -258,17 +264,17 @@ export function registerReturnsRoutes(app, deps) {
       JOIN users ub ON ub.id = r.buyer_id
       JOIN users us ON us.id = r.seller_id
       WHERE r.id = ?
-    `).get(req.params.id);
+    `, [req.params.id]);
         if (!rr)
             return void res.status(404).json({ error: '不存在' });
         if (rr.buyer_id !== user.id && rr.seller_id !== user.id) {
             return void res.status(403).json({ error: '无权查看' });
         }
-        const messages = db.prepare(`
+        const messages = await dbAll(`
       SELECT m.*, u.name as sender_name, u.handle as sender_handle
       FROM return_messages m LEFT JOIN users u ON u.id = m.sender_id
       WHERE m.return_id = ? ORDER BY m.created_at ASC
-    `).all(rr.id);
+    `, [rr.id]);
         const events = [];
         events.push({
             id: `create-${rr.id}`,
@@ -332,13 +338,13 @@ export function registerReturnsRoutes(app, deps) {
         res.json({ item: rr, timeline: events });
     });
     // L3 Phase 2: 物流揽收
-    app.post('/api/return-requests/:id/picked-up', (req, res) => {
+    app.post('/api/return-requests/:id/picked-up', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
         if (user.role !== 'logistics')
             return void res.status(403).json({ error: '仅物流角色可确认揽收' });
-        const rr = db.prepare(`SELECT * FROM return_requests WHERE id = ?`).get(req.params.id);
+        const rr = await dbOne(`SELECT * FROM return_requests WHERE id = ?`, [req.params.id]);
         if (!rr)
             return void res.status(404).json({ error: '退货请求不存在' });
         if (rr.status !== 'accepted_pickup_pending')
@@ -346,26 +352,24 @@ export function registerReturnsRoutes(app, deps) {
         const evidence = String(req.body?.evidence || '').trim().slice(0, 500);
         if (evidence.length < 4)
             return void res.status(400).json({ error: '请提供揽收证据（快递单号 / GPS / 照片描述）≥ 4 字' });
-        db.prepare(`UPDATE return_requests SET status = 'picked_up' WHERE id = ?`).run(rr.id);
+        await dbRun(`UPDATE return_requests SET status = 'picked_up' WHERE id = ?`, [rr.id]);
         try {
-            db.prepare(`INSERT INTO return_messages (id, return_id, sender_id, sender_role, body) VALUES (?,?,?,?,?)`)
-                .run(generateId('rmsg'), rr.id, user.id, 'logistics', `[📦 已揽收] ${evidence}`);
+            await dbRun(`INSERT INTO return_messages (id, return_id, sender_id, sender_role, body) VALUES (?,?,?,?,?)`, [generateId('rmsg'), rr.id, user.id, 'logistics', `[📦 已揽收] ${evidence}`]);
         }
         catch { }
         try {
             const actions = JSON.stringify([{ kind: 'navigate', label: '处理退货', href: `#returns`, style: 'primary' }]);
-            db.prepare(`INSERT INTO notifications (id, user_id, type, title, body, order_id, actions) VALUES (?,?,?,?,?,?,?)`)
-                .run(generateId('ntf'), rr.seller_id, 'return_pickup', '📦 退货已揽收 · 等待你确认收到', `物流已揽收：${evidence.slice(0, 80)}`, rr.order_id, actions);
+            await dbRun(`INSERT INTO notifications (id, user_id, type, title, body, order_id, actions) VALUES (?,?,?,?,?,?,?)`, [generateId('ntf'), rr.seller_id, 'return_pickup', '📦 退货已揽收 · 等待你确认收到', `物流已揽收：${evidence.slice(0, 80)}`, rr.order_id, actions]);
         }
         catch { }
         res.json({ success: true, status: 'picked_up' });
     });
     // L3 Phase 2: 卖家确认收到 → refunded
-    app.post('/api/return-requests/:id/received', (req, res) => {
+    app.post('/api/return-requests/:id/received', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
-        const rr = db.prepare(`SELECT * FROM return_requests WHERE id = ?`).get(req.params.id);
+        const rr = await dbOne(`SELECT * FROM return_requests WHERE id = ?`, [req.params.id]);
         if (!rr)
             return void res.status(404).json({ error: '退货请求不存在' });
         if (rr.seller_id !== user.id)
@@ -374,21 +378,24 @@ export function registerReturnsRoutes(app, deps) {
             return void res.status(400).json({ error: `当前状态 ${rr.status}，不可确认（应在 picked_up 状态）` });
         const note = req.body?.note ? String(req.body.note).slice(0, 300) : null;
         try {
-            executeReturnRefund(rr, note);
+            executeReturnRefund(rr, note, 'picked_up');
         }
         catch (e) {
-            const msg = e.message === 'INSUFFICIENT_SELLER_BALANCE' ? '卖家余额不足以退款' : '退款失败';
+            const m = e.message;
+            if (m === 'RETURN_ALREADY_SETTLED')
+                return void res.status(409).json({ error: '该退货已处理（请刷新后查看）' });
+            const msg = m === 'INSUFFICIENT_SELLER_BALANCE' ? '卖家余额不足以退款' : '退款失败';
             return void res.status(400).json({ error: msg });
         }
         res.json({ success: true, status: 'refunded' });
     });
-    app.get('/api/logistics/return-pickups', (req, res) => {
+    app.get('/api/logistics/return-pickups', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
         if (user.role !== 'logistics')
             return void res.status(403).json({ error: '仅物流角色' });
-        const rows = db.prepare(`
+        const rows = await dbAll(`
       SELECT rr.id, rr.order_id, rr.product_id, rr.refund_amount, rr.pickup_address,
              rr.reason, rr.created_at, p.title as product_title,
              ub.handle as buyer_handle, us.name as seller_name
@@ -398,15 +405,14 @@ export function registerReturnsRoutes(app, deps) {
       JOIN users us ON us.id = rr.seller_id
       WHERE rr.status = 'accepted_pickup_pending' AND rr.pickup_requested = 1
       ORDER BY rr.created_at ASC LIMIT 50
-    `).all();
+    `);
         res.json({ items: rows });
     });
-    app.post('/api/return-requests/:id/messages', (req, res) => {
+    app.post('/api/return-requests/:id/messages', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
-        const rr = db.prepare(`SELECT id, buyer_id, seller_id, status FROM return_requests WHERE id = ?`)
-            .get(req.params.id);
+        const rr = await dbOne(`SELECT id, buyer_id, seller_id, status FROM return_requests WHERE id = ?`, [req.params.id]);
         if (!rr)
             return void res.status(404).json({ error: '不存在' });
         const isBuyer = rr.buyer_id === user.id;
@@ -421,14 +427,12 @@ export function registerReturnsRoutes(app, deps) {
             return void res.status(400).json({ error: '消息长度 1-1000 字' });
         const reasons = detectFraud(body);
         const mid = generateId('rmsg');
-        db.prepare(`INSERT INTO return_messages (id, return_id, sender_id, sender_role, body, flagged, flag_reasons) VALUES (?,?,?,?,?,?,?)`)
-            .run(mid, rr.id, user.id, isBuyer ? 'buyer' : 'seller', body, reasons.length ? 1 : 0, reasons.length ? JSON.stringify(reasons) : null);
+        await dbRun(`INSERT INTO return_messages (id, return_id, sender_id, sender_role, body, flagged, flag_reasons) VALUES (?,?,?,?,?,?,?)`, [mid, rr.id, user.id, isBuyer ? 'buyer' : 'seller', body, reasons.length ? 1 : 0, reasons.length ? JSON.stringify(reasons) : null]);
         try {
             const otherId = isBuyer ? rr.seller_id : rr.buyer_id;
             const orderId = rr.order_id;
             const actions = JSON.stringify([{ kind: 'navigate', label: '查看协商', href: `#order/${orderId}`, style: 'primary' }]);
-            db.prepare(`INSERT INTO notifications (id, user_id, type, title, body, order_id, actions) VALUES (?,?,?,?,?,?,?)`)
-                .run(generateId('ntf'), otherId, 'return_msg', '💬 退货协商新消息', body.slice(0, 80), orderId, actions);
+            await dbRun(`INSERT INTO notifications (id, user_id, type, title, body, order_id, actions) VALUES (?,?,?,?,?,?,?)`, [generateId('ntf'), otherId, 'return_msg', '💬 退货协商新消息', body.slice(0, 80), orderId, actions]);
         }
         catch (e) {
             console.warn('[notif return_msg]', e.message);
@@ -436,11 +440,11 @@ export function registerReturnsRoutes(app, deps) {
         res.json({ success: true, id: mid, flagged: reasons.length > 0, flag_reasons: reasons });
     });
     // buyer 升级到争议（仅 rejected 后或 pending ≥ 7 天）
-    app.post('/api/return-requests/:id/escalate', (req, res) => {
+    app.post('/api/return-requests/:id/escalate', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
-        const rr = db.prepare(`SELECT * FROM return_requests WHERE id = ?`).get(req.params.id);
+        const rr = await dbOne(`SELECT * FROM return_requests WHERE id = ?`, [req.params.id]);
         if (!rr)
             return void res.status(404).json({ error: '不存在' });
         if (rr.buyer_id !== user.id)
@@ -456,7 +460,7 @@ export function registerReturnsRoutes(app, deps) {
         }
         if (rr.escalated_dispute_id)
             return void res.status(400).json({ error: '已升级' });
-        const order = db.prepare('SELECT id, total_amount FROM orders WHERE id = ?').get(rr.order_id);
+        const order = await dbOne('SELECT id, total_amount FROM orders WHERE id = ?', [rr.order_id]);
         if (!order)
             return void res.status(500).json({ error: '订单数据缺失' });
         const reason = `退货协商失败：${RETURN_REASON_DEFAULT_LABEL[String(rr.reason)] || rr.reason}${rr.reason_text ? ' — ' + rr.reason_text : ''}`;
@@ -480,8 +484,7 @@ export function registerReturnsRoutes(app, deps) {
             return void res.status(500).json({ error: '升级失败：' + e.message });
         }
         try {
-            db.prepare(`INSERT INTO notifications (id, user_id, title, body, order_id) VALUES (?,?,?,?,?)`)
-                .run(generateId('ntf'), rr.seller_id, '⚖️ 退货已升级为争议', `争议 ${disputeId} 已创建，请在 48h 内提交反驳`, rr.order_id);
+            await dbRun(`INSERT INTO notifications (id, user_id, title, body, order_id) VALUES (?,?,?,?,?)`, [generateId('ntf'), rr.seller_id, '⚖️ 退货已升级为争议', `争议 ${disputeId} 已创建，请在 48h 内提交反驳`, rr.order_id]);
         }
         catch { }
         try {

package/dist/pwa/routes/reviews.js

@@ -1,8 +1,12 @@
+import { dbOne, dbAll } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
 export function registerReviewsRoutes(app, deps) {
+    // 只读/单写站点走 RFC-016 异步 seam(dbOne/dbAll/dbRun)。
+    // db 保留:claim 是质押/escrow 资金路径(dup 门 + 钱包扣减 + INSERT 任务必须原子),
+    // 用 db.transaction 同步事务守恒;Phase 3 随资金路径迁 pg(BEGIN + SELECT...FOR UPDATE)。
     const { db, auth, isTrustedRole, errorRes, generateId, REVIEW_CLAIM_TARGETS, REVIEW_CLAIM_STAKE, REVIEW_CLAIM_DEADLINE_HOURS, REVIEW_VERIFIERS_NEEDED } = deps;
-    app.get('/api/reviews/recent', (req, res) => {
+    app.get('/api/reviews/recent', async (req, res) => {
         const limit = Math.min(100, Math.max(10, Number(req.query.limit) || 50));
-        const items = db.prepare(`
+        const items = await dbAll(`
       SELECT s.id, s.external_url, s.external_platform, s.thumbnail_url, s.title, s.click_count, s.like_count,
         s.created_at, s.related_product_id,
         u.handle as owner_handle, u.name as owner_name,
@@ -12,10 +16,10 @@ export function registerReviewsRoutes(app, deps) {
       LEFT JOIN products p ON p.id = s.related_product_id AND p.status = 'active'
       WHERE s.status = 'active'
       ORDER BY s.created_at DESC LIMIT ?
-    `).all(limit);
+    `, [limit]);
         res.json({ items });
     });
-    app.post('/api/reviews/:type/:id/claim', (req, res) => {
+    app.post('/api/reviews/:type/:id/claim', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
@@ -29,14 +33,14 @@ export function registerReviewsRoutes(app, deps) {
         let productId = null;
         // #1017 fix: shareables / manifest_registry 实际列名是 related_product_id
         if (reviewType === 'shareable') {
-            const row = db.prepare('SELECT owner_id, related_product_id FROM shareables WHERE id = ?').get(req.params.id);
+            const row = await dbOne('SELECT owner_id, related_product_id FROM shareables WHERE id = ?', [req.params.id]);
             if (!row)
                 return void res.status(404).json({ error: '评测不存在' });
             reviewerId = row.owner_id;
             productId = row.related_product_id;
         }
         else {
-            const row = db.prepare('SELECT owner_id, related_product_id FROM manifest_registry WHERE hash = ?').get(req.params.id);
+            const row = await dbOne('SELECT owner_id, related_product_id FROM manifest_registry WHERE hash = ?', [req.params.id]);
             if (!row)
                 return void res.status(404).json({ error: '原生评测不存在' });
             reviewerId = row.owner_id;
@@ -51,31 +55,50 @@ export function registerReviewsRoutes(app, deps) {
         if (text.length < 6 || text.length > 500)
             return void res.status(400).json({ error: 'claim_text 长度需 6-500 字' });
         const evidence = req.body?.evidence_uri ? String(req.body.evidence_uri).trim().slice(0, 500) : null;
-        const wallet = db.prepare('SELECT balance FROM wallets WHERE user_id = ?').get(user.id);
+        // 友好预检查(读):余额不足直接早退;真正的守恒门在下面的事务内(WHERE balance >= stake)。
+        const wallet = await dbOne('SELECT balance FROM wallets WHERE user_id = ?', [user.id]);
         if (!wallet || wallet.balance < REVIEW_CLAIM_STAKE) {
             return void res.status(400).json({ error: `余额不足：发起需锁 ${REVIEW_CLAIM_STAKE} WAZ` });
         }
-        const dup = db.prepare(`SELECT id FROM review_claim_tasks WHERE review_type = ? AND review_id = ? AND claimant_id = ? AND claim_target = ? AND status = 'open'`)
-            .get(reviewType, req.params.id, user.id, target);
-        if (dup)
-            return void res.status(409).json({ error: '你已对此评测同一项发起过 open 声明' });
         const id = generateId('rct');
         const deadline = new Date(Date.now() + REVIEW_CLAIM_DEADLINE_HOURS * 3600_000).toISOString();
-        db.prepare(`INSERT INTO review_claim_tasks (id, review_type, review_id, product_id, reviewer_id, claimant_id, claim_target, claim_text, evidence_uri, stake_claimant, deadline_at, status) VALUES (?,?,?,?,?,?,?,?,?,?,?,'open')`)
-            .run(id, reviewType, req.params.id, productId, reviewerId, user.id, target, text, evidence, REVIEW_CLAIM_STAKE, deadline);
-        db.prepare('UPDATE wallets SET balance = balance - ?, escrowed = escrowed + ? WHERE user_id = ?')
-            .run(REVIEW_CLAIM_STAKE, REVIEW_CLAIM_STAKE, user.id);
+        // 质押/escrow 原子段(同步事务):dup 门 + 钱包扣减(守恒 guard)+ INSERT 任务,
+        // 任一失败整段回滚 → 不会出现"任务已建但钱没锁"或"双重 open 声明"或透支。
+        try {
+            db.transaction(() => {
+                const dup = db.prepare(`SELECT id FROM review_claim_tasks WHERE review_type = ? AND review_id = ? AND claimant_id = ? AND claim_target = ? AND status = 'open'`)
+                    .get(reviewType, req.params.id, user.id, target);
+                if (dup)
+                    throw new Error('CLAIM_DUP');
+                // 守恒:仅当余额仍 >= stake 才扣(挡并发透支);changes=0 → 回滚
+                const debit = db.prepare('UPDATE wallets SET balance = balance - ?, escrowed = escrowed + ? WHERE user_id = ? AND balance >= ?')
+                    .run(REVIEW_CLAIM_STAKE, REVIEW_CLAIM_STAKE, user.id, REVIEW_CLAIM_STAKE);
+                if (debit.changes === 0)
+                    throw new Error('CLAIM_INSUFFICIENT');
+                db.prepare(`INSERT INTO review_claim_tasks (id, review_type, review_id, product_id, reviewer_id, claimant_id, claim_target, claim_text, evidence_uri, stake_claimant, deadline_at, status) VALUES (?,?,?,?,?,?,?,?,?,?,?,'open')`)
+                    .run(id, reviewType, req.params.id, productId, reviewerId, user.id, target, text, evidence, REVIEW_CLAIM_STAKE, deadline);
+            })();
+        }
+        catch (e) {
+            const msg = e.message;
+            if (msg === 'CLAIM_DUP')
+                return void res.status(409).json({ error: '你已对此评测同一项发起过 open 声明' });
+            if (msg === 'CLAIM_INSUFFICIENT')
+                return void res.status(400).json({ error: `余额不足：发起需锁 ${REVIEW_CLAIM_STAKE} WAZ` });
+            console.error('[reviews claim tx]', msg);
+            return void res.status(500).json({ error: '发起声明失败,请重试' });
+        }
         res.json({ success: true, claim_id: id, deadline_at: deadline, stake_locked: REVIEW_CLAIM_STAKE });
     });
-    app.get('/api/reviews/:type/:id/claims', (req, res) => {
-        const rows = db.prepare(`
+    app.get('/api/reviews/:type/:id/claims', async (req, res) => {
+        const rows = await dbAll(`
       SELECT rct.id, rct.claim_target, rct.claim_text, rct.evidence_uri, rct.status, rct.ruling, rct.deadline_at, rct.resolved_at, rct.created_at,
              u.name as claimant_name,
              (SELECT COUNT(*) FROM review_claim_votes WHERE claim_id = rct.id) as votes_count
       FROM review_claim_tasks rct JOIN users u ON u.id = rct.claimant_id
       WHERE rct.review_type = ? AND rct.review_id = ?
       ORDER BY rct.created_at DESC LIMIT 50
-    `).all(req.params.type, req.params.id);
+    `, [req.params.type, req.params.id]);
         res.json({ claims: rows, votes_needed: REVIEW_VERIFIERS_NEEDED });
     });
 }

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

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { dbOne } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
 function sha256_hex(s) {
     return createHash('sha256').update(s).digest('hex');
 }
@@ -8,14 +9,14 @@ export function registerRewardsApplyRoutes(app, deps) {
         return sha256_hex(`rewards_apply|consent_version=${consentVersion}|user=${userId}|page_loaded_at=${pageLoadedAt}`);
     }
     // GET /api/rewards/status — current state + escrow tally
-    app.get('/api/rewards/status', (req, res) => {
+    app.get('/api/rewards/status', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
         const userId = user.id;
-        const optIn = db.prepare("SELECT rewards_opted_in FROM users WHERE id = ?").get(userId)?.rewards_opted_in ?? 0;
-        const lastAction = db.prepare("SELECT action, created_at FROM rewards_applications WHERE user_id = ? ORDER BY created_at DESC LIMIT 1").get(userId);
-        const currentMajor = db.prepare("SELECT version, hash, change_class, effective_at, text_zh, text_en FROM rewards_consent_texts WHERE change_class='major' ORDER BY effective_at DESC LIMIT 1").get();
+        const optIn = (await dbOne("SELECT rewards_opted_in FROM users WHERE id = ?", [userId]))?.rewards_opted_in ?? 0;
+        const lastAction = (await dbOne("SELECT action, created_at FROM rewards_applications WHERE user_id = ? ORDER BY created_at DESC LIMIT 1", [userId]));
+        const currentMajor = await dbOne("SELECT version, hash, change_class, effective_at, text_zh, text_en FROM rewards_consent_texts WHERE change_class='major' ORDER BY effective_at DESC LIMIT 1", []);
         let state;
         if (optIn === 1)
             state = 'opted_in';
@@ -25,8 +26,8 @@ export function registerRewardsApplyRoutes(app, deps) {
             state = 'auto_downgraded';
         else
             state = 'never_activated';
-        const completedOrders = db.prepare("SELECT COUNT(*) AS n FROM orders WHERE buyer_id = ? AND status = 'completed'").get(userId).n;
-        const passkeyCount = db.prepare("SELECT COUNT(*) AS n FROM webauthn_credentials WHERE user_id = ?").get(userId).n;
+        const completedOrders = (await dbOne("SELECT COUNT(*) AS n FROM orders WHERE buyer_id = ? AND status = 'completed'", [userId])).n;
+        const passkeyCount = (await dbOne("SELECT COUNT(*) AS n FROM webauthn_credentials WHERE user_id = ?", [userId])).n;
         const minOrders = Number(getProtocolParam('rewards_opt_in.min_completed_orders', 1));
         const requirePasskey = Number(getProtocolParam('rewards_opt_in.require_passkey', 1));
         const delaySec = Number(getProtocolParam('rewards_opt_in.consent_delay_seconds', 8));
@@ -35,8 +36,8 @@ export function registerRewardsApplyRoutes(app, deps) {
             missing.push(`completed_orders ${completedOrders}/${minOrders}`);
         if (requirePasskey === 1 && passkeyCount === 0)
             missing.push('passkey_not_registered');
-        const pending = db.prepare("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'pending'").get(userId);
-        const expired = db.prepare("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'expired'").get(userId);
+        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]));
         res.json({
             state,
             opted_in: optIn === 1,
@@ -60,7 +61,7 @@ export function registerRewardsApplyRoutes(app, deps) {
         });
     });
     // POST /api/rewards/apply — activate (or reconfirm) opt-in + drain escrow
-    app.post('/api/rewards/apply', (req, res) => {
+    app.post('/api/rewards/apply', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
@@ -71,11 +72,11 @@ export function registerRewardsApplyRoutes(app, deps) {
         const page_loaded_at = Number(body.page_loaded_at || 0);
         const webauthn_token = body.webauthn_token ? String(body.webauthn_token) : undefined;
         // 1. Verify currently opted-out
-        const optIn = db.prepare("SELECT rewards_opted_in FROM users WHERE id = ?").get(userId)?.rewards_opted_in ?? 0;
+        const optIn = (await dbOne("SELECT rewards_opted_in FROM users WHERE id = ?", [userId]))?.rewards_opted_in ?? 0;
         if (optIn === 1)
             return void errorRes(res, 409, 'ALREADY_OPTED_IN', '已 opted-in,无需重复申请');
         // 2. Verify consent version matches current major
-        const currentMajor = db.prepare("SELECT version, hash FROM rewards_consent_texts WHERE change_class='major' ORDER BY effective_at DESC LIMIT 1").get();
+        const currentMajor = await dbOne("SELECT version, hash FROM rewards_consent_texts WHERE change_class='major' ORDER BY effective_at DESC LIMIT 1", []);
         if (!currentMajor)
             return void errorRes(res, 500, 'NO_CONSENT_TEXT', 'rewards_consent_texts 未 seed,无法申请');
         if (consent_version !== currentMajor.version) {
@@ -102,11 +103,11 @@ export function registerRewardsApplyRoutes(app, deps) {
         }
         // 5. Pre-conditions (re-check inside server)
         const minOrders = Number(getProtocolParam('rewards_opt_in.min_completed_orders', 1));
-        const completedOrders = db.prepare("SELECT COUNT(*) AS n FROM orders WHERE buyer_id = ? AND status = 'completed'").get(userId).n;
+        const completedOrders = (await dbOne("SELECT COUNT(*) AS n FROM orders WHERE buyer_id = ? AND status = 'completed'", [userId])).n;
         if (completedOrders < minOrders)
             return void errorRes(res, 403, 'INSUFFICIENT_ORDERS', `需 ${minOrders} 笔已完成订单,目前 ${completedOrders}`);
         const requirePasskey = Number(getProtocolParam('rewards_opt_in.require_passkey', 1));
-        const passkeyCount = db.prepare("SELECT COUNT(*) AS n FROM webauthn_credentials WHERE user_id = ?").get(userId).n;
+        const passkeyCount = (await dbOne("SELECT COUNT(*) AS n FROM webauthn_credentials WHERE user_id = ?", [userId])).n;
         if (requirePasskey === 1 && passkeyCount === 0)
             return void errorRes(res, 403, 'PASSKEY_REQUIRED', '需先注册 Passkey');
         // 6. Atomic: consume Passkey gate + insert audit + flip flag + drain escrow → wallet
@@ -165,14 +166,14 @@ export function registerRewardsApplyRoutes(app, deps) {
         res.json({ ok: true, state: 'opted_in', drained_from_escrow: drained });
     });
     // POST /api/rewards/deactivate — flip off; subsequent commissions → charity
-    app.post('/api/rewards/deactivate', (req, res) => {
+    app.post('/api/rewards/deactivate', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
         const userId = user.id;
         const body = req.body || {};
         const webauthn_token = body.webauthn_token ? String(body.webauthn_token) : undefined;
-        const optIn = db.prepare("SELECT rewards_opted_in FROM users WHERE id = ?").get(userId)?.rewards_opted_in ?? 0;
+        const optIn = (await dbOne("SELECT rewards_opted_in FROM users WHERE id = ?", [userId]))?.rewards_opted_in ?? 0;
         if (optIn === 0)
             return void errorRes(res, 409, 'ALREADY_OPTED_OUT', '本来就未 opted-in,无需关闭');
         const requirePasskey = Number(getProtocolParam('rewards_opt_in.require_passkey', 1));