@seasonkoh/webaz 0.1.7 → 0.1.9

package/dist/pwa/routes/returns.js

@@ -0,0 +1,493 @@
+import { recordRepEvent } from '../../layer4-economics/L4-3-reputation/reputation-engine.js';
+const VALID_RETURN_REASONS = new Set(['quality', 'wrong_item', 'damaged', 'no_longer_needed', 'other']);
+const RETURN_REASON_DEFAULT_LABEL = {
+    quality: '质量问题',
+    wrong_item: '收到错款',
+    damaged: '运输破损',
+    no_longer_needed: '不再需要',
+    other: '其他',
+};
+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) {
+        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) {
+                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);
+            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);
+                db.prepare('UPDATE products SET stock = stock + ?, updated_at = datetime(\'now\') WHERE id = ?').run(qty, rr.product_id);
+                if (ord.variant_id) {
+                    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 || ''}`);
+            }
+            catch { }
+            try {
+                db.prepare(`INSERT INTO notifications (id, user_id, title, body, order_id) VALUES (?,?,?,?,?)`)
+                    .run(generateId('ntf'), rr.buyer_id, '✓ 退款已到账', `${refundAmt} WAZ 已退回至你的钱包`, rr.order_id);
+            }
+            catch { }
+        })();
+        try {
+            const SELLER_FAULT_REASONS = new Set(['quality', 'wrong_item', 'damaged']);
+            if (SELLER_FAULT_REASONS.has(String(rr.reason))) {
+                recordRepEvent(db, String(rr.seller_id), 'claim_upheld_against', `退货接受 (reason=${rr.reason}, return=${rr.id})`, String(rr.order_id));
+            }
+        }
+        catch (e) {
+            console.error('[return rep event]', e);
+        }
+    }
+    // buyer 发起退货
+    app.post('/api/orders/:order_id/return-request', (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(`
+      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);
+        if (!order)
+            return void res.status(404).json({ error: '订单不存在' });
+        if (order.buyer_id !== user.id)
+            return void res.status(403).json({ error: '仅买家可申请退货' });
+        // P0-1: 只允许 completed 退货 — escrow 已结算
+        if (order.status !== 'completed') {
+            return void res.status(400).json({ error: '仅订单完成后可申请退货（确认收货后）' });
+        }
+        const returnDays = Number(order.return_days || 0);
+        if (returnDays <= 0)
+            return void res.status(400).json({ error: '该商品不支持退货' });
+        const baseTime = order.updated_at || order.created_at;
+        const deadlineMs = new Date(baseTime).getTime() + returnDays * 86400 * 1000;
+        if (Date.now() > deadlineMs) {
+            return void res.status(400).json({ error: `已超过 ${returnDays} 天退货窗口` });
+        }
+        const existing = db.prepare(`
+      SELECT id, status FROM return_requests WHERE order_id = ? AND status IN ('pending', 'accepted') LIMIT 1
+    `).get(order.id);
+        if (existing)
+            return void res.status(400).json({ error: `已存在退货请求 (${existing.status})` });
+        const reason = String(req.body?.reason || '');
+        if (!VALID_RETURN_REASONS.has(reason))
+            return void res.status(400).json({ error: '无效的退货原因' });
+        const reasonText = req.body?.reason_text ? String(req.body.reason_text).slice(0, 500) : null;
+        const refundAmount = req.body?.refund_amount != null ? Number(req.body.refund_amount) : Number(order.total_amount);
+        if (refundAmount <= 0 || refundAmount > Number(order.total_amount)) {
+            return void res.status(400).json({ error: '退款金额必须在 0 ~ 订单金额之间' });
+        }
+        // L3+B3：上门取件请求
+        const pickupRequested = req.body?.pickup_requested ? 1 : 0;
+        const pickupAddress = pickupRequested && req.body?.pickup_address
+            ? String(req.body.pickup_address).slice(0, 300).trim()
+            : null;
+        if (pickupRequested && (!pickupAddress || pickupAddress.length < 4)) {
+            return void res.status(400).json({ error: '请求上门取件时必须提供取件地址（≥ 4 字）' });
+        }
+        const reqId = generateId('ret');
+        db.prepare(`
+      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);
+        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);
+        }
+        catch (e) {
+            console.error('[return notify]', e);
+        }
+        try {
+            broadcastSystemEvent('return', '↩', `退货申请 ${reqId} · ${refundAmount} WAZ`, order.id);
+        }
+        catch { }
+        res.json({ success: true, id: reqId, pickup_requested: !!pickupRequested });
+    });
+    // P1-5: 订单级直查
+    app.get('/api/orders/:order_id/return-request', (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);
+        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(`
+      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);
+        res.json({ item: row || null });
+    });
+    app.get('/api/return-requests', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const status = req.query.status ? String(req.query.status) : null;
+        const role = req.query.role === 'seller' ? 'seller' : 'buyer';
+        const field = role === 'seller' ? 'seller_id' : 'buyer_id';
+        const where = [`r.${field} = ?`];
+        const params = [user.id];
+        if (status) {
+            where.push('r.status = ?');
+            params.push(status);
+        }
+        const rows = db.prepare(`
+      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,
+             o.total_amount as order_total,
+             ub.name as buyer_name, ub.handle as buyer_handle,
+             us.name as seller_name, us.handle as seller_handle
+      FROM return_requests r
+      JOIN products p ON p.id = r.product_id
+      JOIN orders o ON o.id = r.order_id
+      JOIN users ub ON ub.id = r.buyer_id
+      JOIN users us ON us.id = r.seller_id
+      WHERE ${where.join(' AND ')}
+      ORDER BY r.created_at DESC LIMIT 200
+    `).all(...params);
+        res.json({ items: rows });
+    });
+    app.post('/api/return-requests/:id/decide', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const rr = db.prepare(`SELECT * FROM return_requests WHERE id = ?`).get(req.params.id);
+        if (!rr)
+            return void res.status(404).json({ error: '退货请求不存在' });
+        if (rr.seller_id !== user.id)
+            return void res.status(403).json({ error: '仅卖家可决策' });
+        if (rr.status !== 'pending')
+            return void res.status(400).json({ error: `当前状态 ${rr.status}，不可决策` });
+        const decision = String(req.body?.decision || '');
+        if (!['accept', 'reject'].includes(decision))
+            return void res.status(400).json({ error: '无效决策' });
+        const response = req.body?.response ? String(req.body.response).slice(0, 500) : null;
+        if (decision === 'reject' && !response)
+            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);
+                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 || ''}`);
+                }
+                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);
+                }
+                catch { }
+                return void res.json({ success: true, status: 'accepted_pickup_pending' });
+            }
+            try {
+                executeReturnRefund(rr, response);
+            }
+            catch (e) {
+                const msg = e.message === '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);
+            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}`);
+            }
+            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);
+            }
+            catch { }
+            return void res.json({ success: true, status: 'rejected' });
+        }
+    });
+    app.delete('/api/return-requests/:id', (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);
+        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);
+        res.json({ success: true });
+    });
+    // ─── W2 售后协商时间线 ───────────────────────────────
+    app.get('/api/return-requests/:id', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const rr = db.prepare(`
+      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,
+             us.name as seller_name, us.handle as seller_handle
+      FROM return_requests r
+      JOIN products p ON p.id = r.product_id
+      JOIN orders o ON o.id = r.order_id
+      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);
+        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(`
+      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);
+        const events = [];
+        events.push({
+            id: `create-${rr.id}`,
+            type: 'created',
+            ts: String(rr.created_at || ''),
+            actor_id: String(rr.buyer_id),
+            actor_role: 'buyer',
+            body: String(rr.reason_text || ''),
+            meta: { reason: rr.reason, refund_amount: rr.refund_amount },
+        });
+        for (const m of messages) {
+            let fr = [];
+            try {
+                fr = m.flag_reasons ? JSON.parse(String(m.flag_reasons)) : [];
+            }
+            catch { }
+            events.push({
+                id: `msg-${m.id}`,
+                type: 'message',
+                ts: String(m.created_at || ''),
+                actor_id: m.sender_id ? String(m.sender_id) : null,
+                actor_role: (m.sender_role || 'buyer'),
+                body: String(m.body || ''),
+                flagged: Number(m.flagged || 0),
+                flag_reasons: fr,
+            });
+        }
+        if (rr.resolved_at) {
+            const status = String(rr.status);
+            let type = null;
+            let role = 'system';
+            let actorId = null;
+            if (status === 'refunded') {
+                type = 'refunded';
+                role = 'seller';
+                actorId = String(rr.seller_id);
+            }
+            else if (status === 'cancelled') {
+                type = 'cancelled';
+                role = 'buyer';
+                actorId = String(rr.buyer_id);
+            }
+            else if (status === 'escalated') {
+                type = 'escalated';
+                role = 'buyer';
+                actorId = String(rr.buyer_id);
+            }
+            if (type) {
+                events.push({
+                    id: `done-${rr.id}`,
+                    type,
+                    ts: String(rr.resolved_at),
+                    actor_id: actorId,
+                    actor_role: role,
+                    body: '',
+                    meta: type === 'escalated' ? { dispute_id: rr.escalated_dispute_id } : undefined,
+                });
+            }
+        }
+        events.sort((a, b) => a.ts.localeCompare(b.ts));
+        res.json({ item: rr, timeline: events });
+    });
+    // L3 Phase 2: 物流揽收
+    app.post('/api/return-requests/:id/picked-up', (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);
+        if (!rr)
+            return void res.status(404).json({ error: '退货请求不存在' });
+        if (rr.status !== 'accepted_pickup_pending')
+            return void res.status(400).json({ error: `当前状态 ${rr.status}，不可揽收` });
+        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);
+        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}`);
+        }
+        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);
+        }
+        catch { }
+        res.json({ success: true, status: 'picked_up' });
+    });
+    // L3 Phase 2: 卖家确认收到 → refunded
+    app.post('/api/return-requests/:id/received', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const rr = db.prepare(`SELECT * FROM return_requests WHERE id = ?`).get(req.params.id);
+        if (!rr)
+            return void res.status(404).json({ error: '退货请求不存在' });
+        if (rr.seller_id !== user.id)
+            return void res.status(403).json({ error: '仅卖家可确认收到' });
+        if (rr.status !== 'picked_up')
+            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);
+        }
+        catch (e) {
+            const msg = e.message === '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) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        if (user.role !== 'logistics')
+            return void res.status(403).json({ error: '仅物流角色' });
+        const rows = db.prepare(`
+      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
+      FROM return_requests rr
+      JOIN products p ON p.id = rr.product_id
+      JOIN users ub ON ub.id = rr.buyer_id
+      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) => {
+        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);
+        if (!rr)
+            return void res.status(404).json({ error: '不存在' });
+        const isBuyer = rr.buyer_id === user.id;
+        const isSeller = rr.seller_id === user.id;
+        if (!isBuyer && !isSeller)
+            return void res.status(403).json({ error: '仅买卖双方可发消息' });
+        if (['refunded', 'cancelled', 'escalated'].includes(rr.status)) {
+            return void res.status(400).json({ error: `当前状态 ${rr.status}，协商已结束` });
+        }
+        const body = String(req.body?.body || '').trim();
+        if (body.length < 1 || body.length > 1000)
+            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);
+        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);
+        }
+        catch (e) {
+            console.warn('[notif return_msg]', e.message);
+        }
+        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) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const rr = db.prepare(`SELECT * FROM return_requests WHERE id = ?`).get(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 !== 'rejected' && rr.status !== 'pending') {
+            return void res.status(400).json({ error: `当前状态 ${rr.status}，无法升级` });
+        }
+        if (rr.status === 'pending') {
+            const ageMs = Date.now() - new Date(String(rr.created_at)).getTime();
+            if (ageMs < 7 * 86400 * 1000) {
+                return void res.status(400).json({ error: '卖家有 7 天回应窗口，超期后可升级' });
+            }
+        }
+        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);
+        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 : ''}`;
+        const disputeId = generateId('dsp');
+        const now = new Date();
+        const respondDeadline = new Date(now.getTime() + 48 * 3600 * 1000).toISOString();
+        const arbitrateDeadline = new Date(now.getTime() + 120 * 3600 * 1000).toISOString();
+        try {
+            db.transaction(() => {
+                db.prepare(`
+          INSERT INTO disputes (
+            id, order_id, initiator_id, defendant_id, reason, status,
+            defendant_evidence_ids, respond_deadline, arbitrate_deadline, assigned_arbitrators
+          ) VALUES (?, ?, ?, ?, ?, 'open', '[]', ?, ?, '[]')
+        `).run(disputeId, order.id, rr.buyer_id, rr.seller_id, reason, respondDeadline, arbitrateDeadline);
+                db.prepare(`UPDATE return_requests SET status = 'escalated', escalated_dispute_id = ?, resolved_at = datetime('now') WHERE id = ?`)
+                    .run(disputeId, rr.id);
+            })();
+        }
+        catch (e) {
+            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);
+        }
+        catch { }
+        try {
+            broadcastSystemEvent('dispute_open', '⚖', `退货升级 (订单 ${order.id})`, order.id);
+        }
+        catch { }
+        res.json({ success: true, dispute_id: disputeId });
+    });
+}

package/dist/pwa/routes/reviews.js

@@ -0,0 +1,81 @@
+export function registerReviewsRoutes(app, deps) {
+    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) => {
+        const limit = Math.min(100, Math.max(10, Number(req.query.limit) || 50));
+        const items = db.prepare(`
+      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,
+        p.title as product_title, p.price as product_price, p.images as product_images
+      FROM shareables s
+      JOIN users u ON u.id = s.owner_id
+      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);
+        res.json({ items });
+    });
+    app.post('/api/reviews/:type/:id/claim', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        if (isTrustedRole(user)) {
+            return void errorRes(res, 403, 'TRUSTED_ROLE_NO_CLAIM', '受信角色不可发起声明');
+        }
+        const reviewType = req.params.type;
+        if (!['shareable', 'manifest'].includes(reviewType))
+            return void res.status(400).json({ error: 'review type must be shareable / manifest' });
+        let reviewerId = null;
+        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);
+            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);
+            if (!row)
+                return void res.status(404).json({ error: '原生评测不存在' });
+            reviewerId = row.owner_id;
+            productId = row.related_product_id;
+        }
+        if (reviewerId === user.id)
+            return void errorRes(res, 403, 'CANNOT_CLAIM_OWN', '不可对自己的评测发起声明');
+        const target = String(req.body?.claim_target || '').trim();
+        if (!REVIEW_CLAIM_TARGETS.has(target))
+            return void res.status(400).json({ error: `claim_target 须为 ${[...REVIEW_CLAIM_TARGETS].join(' / ')}` });
+        const text = String(req.body?.claim_text || '').trim();
+        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);
+        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);
+        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(`
+      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);
+        res.json({ claims: rows, votes_needed: REVIEW_VERIFIERS_NEEDED });
+    });
+}