@seasonkoh/webaz 0.1.8 → 0.1.10

package/dist/pwa/routes/analytics.js

@@ -0,0 +1,272 @@
+function median(arr) {
+    if (arr.length === 0)
+        return null;
+    const s = [...arr].sort((a, b) => a - b);
+    const mid = Math.floor(s.length / 2);
+    return s.length % 2 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+}
+export function registerAnalyticsRoutes(app, deps) {
+    const { db, auth } = deps;
+    // 物流绩效卡 (Wave B-4)
+    app.get('/api/logistics/me/performance', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        if (user.role !== 'logistics') {
+            return void res.status(403).json({ error: '仅物流角色可访问' });
+        }
+        const windowDays = Math.max(7, Math.min(365, Number(req.query.window) || 30));
+        const orders = db.prepare(`
+      SELECT id, status, created_at, updated_at,
+             pickup_deadline, delivery_deadline
+      FROM orders
+      WHERE logistics_id = ? AND created_at > datetime('now', '-' || ? || ' days')
+    `).all(user.id, windowDays);
+        const orderIds = orders.map(o => o.id);
+        let history = [];
+        if (orderIds.length > 0) {
+            const placeholders = orderIds.map(() => '?').join(',');
+            history = db.prepare(`
+        SELECT order_id, from_status, to_status, created_at
+        FROM order_state_history
+        WHERE order_id IN (${placeholders})
+        ORDER BY created_at ASC
+      `).all(...orderIds);
+        }
+        const histByOrder = new Map();
+        for (const h of history) {
+            if (!histByOrder.has(h.order_id))
+                histByOrder.set(h.order_id, []);
+            histByOrder.get(h.order_id).push(h);
+        }
+        let pickupOnTime = 0, pickupOverdue = 0;
+        let deliveryOnTime = 0, deliveryOverdue = 0;
+        let totalDelivered = 0, totalInTransit = 0, totalCompleted = 0;
+        const pickupDurationsHr = [];
+        const transitDurationsHr = [];
+        for (const o of orders) {
+            const h = histByOrder.get(o.id) || [];
+            const shipped = h.find(x => x.to_status === 'shipped');
+            const pickedUp = h.find(x => x.to_status === 'picked_up');
+            const delivered = h.find(x => x.to_status === 'delivered');
+            if (o.status === 'completed')
+                totalCompleted++;
+            if (o.status === 'in_transit' || o.status === 'picked_up')
+                totalInTransit++;
+            if (delivered)
+                totalDelivered++;
+            if (shipped && pickedUp) {
+                const hrs = (new Date(pickedUp.created_at).getTime() - new Date(shipped.created_at).getTime()) / 3600000;
+                if (hrs >= 0)
+                    pickupDurationsHr.push(hrs);
+                if (o.pickup_deadline) {
+                    if (new Date(pickedUp.created_at) <= new Date(o.pickup_deadline))
+                        pickupOnTime++;
+                    else
+                        pickupOverdue++;
+                }
+            }
+            if (pickedUp && delivered) {
+                const hrs = (new Date(delivered.created_at).getTime() - new Date(pickedUp.created_at).getTime()) / 3600000;
+                if (hrs >= 0)
+                    transitDurationsHr.push(hrs);
+                if (o.delivery_deadline) {
+                    if (new Date(delivered.created_at) <= new Date(o.delivery_deadline))
+                        deliveryOnTime++;
+                    else
+                        deliveryOverdue++;
+                }
+            }
+        }
+        const disputes = db.prepare(`
+      SELECT COUNT(*) as n FROM disputes d
+      JOIN orders o ON o.id = d.order_id
+      WHERE o.logistics_id = ? AND d.created_at > datetime('now', '-' || ? || ' days')
+    `).get(user.id, windowDays).n;
+        // 败诉两路：auto-fault 判物流 + 仲裁裁定物流为被告且退款
+        const autoFaultLost = db.prepare(`
+      SELECT COUNT(*) as n FROM orders
+      WHERE logistics_id = ? AND status = 'fault_logistics'
+        AND updated_at > datetime('now', '-' || ? || ' days')
+    `).get(user.id, windowDays).n;
+        const arbitratedLost = db.prepare(`
+      SELECT COUNT(*) as n FROM disputes d
+      JOIN orders o ON o.id = d.order_id
+      WHERE o.logistics_id = ? AND d.defendant_id = ?
+        AND d.ruling_type IN ('refund_buyer','partial_refund')
+        AND d.created_at > datetime('now', '-' || ? || ' days')
+    `).get(user.id, user.id, windowDays).n;
+        const disputeLoss = autoFaultLost + arbitratedLost;
+        const pickupTotalEvaluated = pickupOnTime + pickupOverdue;
+        const deliveryTotalEvaluated = deliveryOnTime + deliveryOverdue;
+        res.json({
+            window_days: windowDays,
+            total_orders: orders.length,
+            in_progress: totalInTransit,
+            delivered: totalDelivered,
+            completed: totalCompleted,
+            pickup: {
+                on_time: pickupOnTime,
+                overdue: pickupOverdue,
+                on_time_rate: pickupTotalEvaluated > 0 ? pickupOnTime / pickupTotalEvaluated : null,
+                median_hours: median(pickupDurationsHr),
+            },
+            delivery: {
+                on_time: deliveryOnTime,
+                overdue: deliveryOverdue,
+                on_time_rate: deliveryTotalEvaluated > 0 ? deliveryOnTime / deliveryTotalEvaluated : null,
+                median_hours: median(transitDurationsHr),
+            },
+            disputes: {
+                total: disputes,
+                lost: disputeLoss,
+                loss_rate: disputes > 0 ? disputeLoss / disputes : null,
+            },
+        });
+    });
+    // 卖家销售分析 (Wave C-5)
+    app.get('/api/sellers/me/analytics', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        if (user.role !== 'seller')
+            return void res.status(403).json({ error: '仅卖家可访问' });
+        const windowDays = Math.max(7, Math.min(365, Number(req.query.window) || 30));
+        const ordersAgg = db.prepare(`
+      SELECT
+        COUNT(*) as total_orders,
+        SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as completed_orders,
+        SUM(CASE WHEN status = 'cancelled' THEN 1 ELSE 0 END) as cancelled_orders,
+        SUM(CASE WHEN status IN ('paid','accepted','shipped','picked_up','in_transit','delivered','confirmed') THEN 1 ELSE 0 END) as in_progress_orders,
+        COALESCE(SUM(CASE WHEN status = 'completed' THEN total_amount ELSE 0 END), 0) as gmv,
+        COALESCE(AVG(CASE WHEN status = 'completed' THEN total_amount END), 0) as aov
+      FROM orders WHERE seller_id = ? AND created_at > datetime('now', '-' || ? || ' days')
+    `).get(user.id, windowDays);
+        const topProducts = db.prepare(`
+      SELECT p.id, p.title, p.price, COUNT(o.id) as sales,
+             COALESCE(SUM(o.total_amount), 0) as revenue
+      FROM products p
+      LEFT JOIN orders o ON o.product_id = p.id AND o.seller_id = p.seller_id
+        AND o.status = 'completed'
+        AND o.created_at > datetime('now', '-' || ? || ' days')
+      WHERE p.seller_id = ? AND p.status != 'deleted'
+      GROUP BY p.id
+      HAVING sales > 0
+      ORDER BY sales DESC LIMIT 10
+    `).all(windowDays, user.id);
+        const buyerStats = db.prepare(`
+      SELECT
+        COUNT(DISTINCT buyer_id) as unique_buyers,
+        COUNT(*) as orders_count
+      FROM orders WHERE seller_id = ? AND status = 'completed'
+        AND created_at > datetime('now', '-' || ? || ' days')
+    `).get(user.id, windowDays);
+        const repeatBuyers = db.prepare(`
+      SELECT COUNT(*) as n FROM (
+        SELECT buyer_id FROM orders WHERE seller_id = ? AND status = 'completed'
+          AND created_at > datetime('now', '-' || ? || ' days')
+        GROUP BY buyer_id HAVING COUNT(*) > 1
+      )
+    `).get(user.id, windowDays).n;
+        const wishlistAdds = db.prepare(`
+      SELECT COUNT(*) as n FROM user_wishlist w
+      JOIN products p ON p.id = w.product_id
+      WHERE p.seller_id = ? AND w.created_at > datetime('now', '-' || ? || ' days')
+    `).get(user.id, windowDays).n;
+        const dailyTrend = db.prepare(`
+      SELECT DATE(created_at) as date,
+             COUNT(*) as orders,
+             COALESCE(SUM(CASE WHEN status = 'completed' THEN total_amount ELSE 0 END), 0) as gmv
+      FROM orders
+      WHERE seller_id = ? AND created_at > datetime('now', '-' || ? || ' days')
+      GROUP BY DATE(created_at)
+      ORDER BY date ASC
+    `).all(user.id, Math.min(windowDays, 30));
+        const ratingsAgg = db.prepare(`
+      SELECT COUNT(*) as cnt, COALESCE(AVG(stars), 0) as avg_stars
+      FROM order_ratings WHERE seller_id = ?
+        AND created_at > datetime('now', '-' || ? || ' days')
+    `).get(user.id, windowDays);
+        const refundsCount = db.prepare(`
+      SELECT COUNT(*) as n FROM return_requests
+      WHERE seller_id = ? AND status = 'refunded'
+        AND created_at > datetime('now', '-' || ? || ' days')
+    `).get(user.id, windowDays).n;
+        // S1: 平均备货时长（paid → shipped 中位 hours）
+        const handlingRow = db.prepare(`
+      SELECT COALESCE(AVG((julianday(h_ship.created_at) - julianday(h_paid.created_at)) * 24), 0) as avg_handling_hours,
+             COUNT(*) as sample_n
+      FROM orders o
+      JOIN order_state_history h_paid ON h_paid.order_id = o.id AND h_paid.to_status = 'paid'
+      JOIN order_state_history h_ship ON h_ship.order_id = o.id AND h_ship.to_status = 'shipped'
+      WHERE o.seller_id = ? AND o.created_at > datetime('now', '-' || ? || ' days')
+    `).get(user.id, windowDays);
+        const completedN = Number(ordersAgg.completed_orders) || 0;
+        const returnRate = completedN > 0 ? refundsCount / completedN : 0;
+        // S1: 上一窗口对比
+        const prevAgg = db.prepare(`
+      SELECT
+        COUNT(*) as total_orders,
+        SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as completed_orders,
+        COALESCE(SUM(CASE WHEN status = 'completed' THEN total_amount ELSE 0 END), 0) as gmv
+      FROM orders WHERE seller_id = ?
+        AND created_at > datetime('now', '-' || ? || ' days')
+        AND created_at <= datetime('now', '-' || ? || ' days')
+    `).get(user.id, windowDays * 2, windowDays);
+        res.json({
+            window_days: windowDays,
+            orders: ordersAgg,
+            top_products: topProducts,
+            buyers: {
+                unique: buyerStats.unique_buyers,
+                repeat: repeatBuyers,
+                repeat_rate: buyerStats.unique_buyers > 0 ? repeatBuyers / buyerStats.unique_buyers : 0,
+            },
+            funnel: {
+                wishlist_adds: wishlistAdds,
+                orders: Number(ordersAgg.total_orders),
+                completed: Number(ordersAgg.completed_orders),
+            },
+            daily_trend: dailyTrend,
+            ratings: ratingsAgg,
+            refunds: refundsCount,
+            fulfillment: {
+                avg_handling_hours: Math.round(Number(handlingRow.avg_handling_hours) * 10) / 10,
+                sample_n: Number(handlingRow.sample_n),
+            },
+            quality: {
+                return_rate: Math.round(returnRate * 10000) / 10000,
+                refunds: refundsCount,
+                completed: completedN,
+            },
+            prev_window: {
+                total_orders: Number(prevAgg.total_orders),
+                completed_orders: Number(prevAgg.completed_orders),
+                gmv: Number(prevAgg.gmv),
+            },
+        });
+    });
+    // 卖家退货仪表盘
+    app.get('/api/sellers/me/return-stats', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const totalReturns = db.prepare(`SELECT COUNT(*) as n FROM return_requests WHERE seller_id = ?`).get(user.id).n;
+        const refunded = db.prepare(`SELECT COUNT(*) as n FROM return_requests WHERE seller_id = ? AND status = 'refunded'`).get(user.id).n;
+        const rejected = db.prepare(`SELECT COUNT(*) as n FROM return_requests WHERE seller_id = ? AND status = 'rejected'`).get(user.id).n;
+        const pending = db.prepare(`SELECT COUNT(*) as n FROM return_requests WHERE seller_id = ? AND status = 'pending'`).get(user.id).n;
+        const totalOrders = db.prepare(`SELECT COUNT(*) as n FROM orders WHERE seller_id = ? AND status IN ('delivered','completed','refunded')`).get(user.id).n;
+        const reasonBreakdown = db.prepare(`
+      SELECT reason, COUNT(*) as cnt FROM return_requests
+      WHERE seller_id = ? GROUP BY reason ORDER BY cnt DESC
+    `).all(user.id);
+        const returnRate = totalOrders > 0 ? (refunded / totalOrders) : 0;
+        res.json({
+            total_returns: totalReturns,
+            refunded, rejected, pending,
+            total_orders: totalOrders,
+            return_rate: returnRate,
+            reason_breakdown: reasonBreakdown,
+        });
+    });
+}

package/dist/pwa/routes/anchors.js

@@ -0,0 +1,169 @@
+import { generateAnchor, lookupAnchor, retireAnchor, userReferralVolume, computeTierLetter, userAnchorQuotaStats, TIER_THRESHOLDS, ANCHOR_HANDLE_MAX_FOR_USE, } from '../../layer2-business/L2-anchor-registry/anchor-registry.js';
+export function registerAnchorsRoutes(app, deps) {
+    const { db, auth, rateLimitOk } = deps;
+    // POST /api/anchor/generate
+    app.post('/api/anchor/generate', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        if (!rateLimitOk(req.ip || 'anon', 10, 60_000))
+            return void res.status(429).json({ error: '生成过于频繁' });
+        const { middle, target_kind, target_id } = req.body || {};
+        if (!middle || !target_kind || !target_id)
+            return void res.status(400).json({ error: 'middle / target_kind / target_id 必填' });
+        if (!['user', 'product', 'shareable', 'dispute_case'].includes(target_kind)) {
+            return void res.status(400).json({ error: 'target_kind 仅允许 user / product / shareable / dispute_case' });
+        }
+        const r = generateAnchor(db, {
+            ownerId: user.id,
+            middle: String(middle),
+            targetKind: target_kind,
+            targetId: String(target_id),
+        });
+        if (!r.ok)
+            return void res.status(400).json({ error: r.reason });
+        res.json({ ok: true, anchor: r.anchor, tier_letter: r.tier_letter });
+    });
+    // GET /api/anchor/:code/lookup — 公开（无需 auth）
+    app.get('/api/anchor/:code/lookup', (req, res) => {
+        if (!rateLimitOk(req.ip || 'anon', 60, 60_000))
+            return void res.status(429).json({ error: 'too_many_lookups' });
+        const r = lookupAnchor(db, String(req.params.code || ''));
+        if (!r.found)
+            return void res.status(404).json({ found: false });
+        if (r.status === 'retired') {
+            return void res.status(410).json({ found: true, status: 'retired', retired_at: r.retired_at, owner_id: r.owner_id, tier_letter: r.tier_letter, hint: 'archived' });
+        }
+        if (r.status === 'reclaimable') {
+            return void res.status(404).json({ found: false, hint: 'reclaimable' });
+        }
+        // 2026-05-24 富化响应：附 owner 详情 + 商品推荐指数
+        const owner = db.prepare(`
+      SELECT u.name, u.handle, u.region, u.created_at, u.bio,
+        (SELECT COUNT(*) FROM follows WHERE followee_id = u.id) as follower_count,
+        (SELECT COALESCE(SUM(s.like_count), 0) FROM shareables s WHERE s.owner_id = u.id AND s.status = 'active') as total_likes_received
+      FROM users u WHERE u.id = ? AND u.id != 'sys_protocol'
+    `).get(r.owner_id);
+        let product = null;
+        if (r.target_kind === 'product') {
+            product = db.prepare(`
+        SELECT p.id, p.title, p.price, p.category, p.images, p.completion_count, p.total_likes,
+          (SELECT COUNT(DISTINCT buyer_id) FROM order_ratings rt WHERE rt.product_id = p.id AND rt.stars >= 4) as recommend_count,
+          (SELECT ROUND(AVG(stars), 2) FROM order_ratings rt WHERE rt.product_id = p.id) as avg_rating,
+          (SELECT COUNT(*) FROM order_ratings rt WHERE rt.product_id = p.id) as rating_count,
+          u.handle as seller_handle, u.name as seller_name
+        FROM products p LEFT JOIN users u ON u.id = p.seller_id
+        WHERE p.id = ? AND p.status = 'active'
+      `).get(r.target_id);
+        }
+        else if (r.target_kind === 'shareable') {
+            const sh = db.prepare(`SELECT related_product_id FROM shareables WHERE id = ?`).get(r.target_id);
+            if (sh?.related_product_id) {
+                product = db.prepare(`
+          SELECT p.id, p.title, p.price, p.category, p.images, p.completion_count, p.total_likes,
+            (SELECT COUNT(DISTINCT buyer_id) FROM order_ratings rt WHERE rt.product_id = p.id AND rt.stars >= 4) as recommend_count,
+            (SELECT ROUND(AVG(stars), 2) FROM order_ratings rt WHERE rt.product_id = p.id) as avg_rating,
+            (SELECT COUNT(*) FROM order_ratings rt WHERE rt.product_id = p.id) as rating_count,
+            u.handle as seller_handle, u.name as seller_name
+          FROM products p LEFT JOIN users u ON u.id = p.seller_id
+          WHERE p.id = ? AND p.status = 'active'
+        `).get(sh.related_product_id);
+            }
+        }
+        res.json({
+            found: true, status: 'active',
+            target_kind: r.target_kind,
+            target_id: r.target_id,
+            owner_id: r.owner_id,
+            tier_letter: r.tier_letter,
+            owner,
+            product,
+        });
+    });
+    // POST /api/anchor/:code/touch — 写 attribution（first-touch + 30d）
+    app.post('/api/anchor/:code/touch', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const r = lookupAnchor(db, String(req.params.code || ''));
+        if (!r.found || r.status !== 'active')
+            return void res.status(404).json({ error: 'anchor_not_active' });
+        if (r.owner_id === user.id)
+            return void res.json({ ok: true, skipped: 'self_anchor' });
+        let attributedProducts = 0;
+        const expiresAt = new Date(Date.now() + 30 * 86400_000).toISOString().slice(0, 19).replace('T', ' ');
+        if (r.target_kind === 'product') {
+            const existing = db.prepare(`SELECT 1 FROM product_share_attribution WHERE product_id = ? AND recipient_id = ?`).get(r.target_id, user.id);
+            if (!existing) {
+                db.prepare(`INSERT INTO product_share_attribution (product_id, recipient_id, sharer_id, shareable_id, expires_at) VALUES (?,?,?,NULL,?)`)
+                    .run(r.target_id, user.id, r.owner_id, expiresAt);
+                attributedProducts = 1;
+            }
+        }
+        else if (r.target_kind === 'shareable') {
+            const s = db.prepare(`SELECT id, related_product_id FROM shareables WHERE id = ?`).get(r.target_id);
+            if (s?.related_product_id) {
+                const existing = db.prepare(`SELECT 1 FROM product_share_attribution WHERE product_id = ? AND recipient_id = ?`).get(s.related_product_id, user.id);
+                if (!existing) {
+                    db.prepare(`INSERT INTO product_share_attribution (product_id, recipient_id, sharer_id, shareable_id, expires_at) VALUES (?,?,?,?,?)`)
+                        .run(s.related_product_id, user.id, r.owner_id, s.id, expiresAt);
+                    attributedProducts = 1;
+                }
+            }
+        }
+        else if (r.target_kind === 'user') {
+            // 限 LIMIT 50 防 DoS
+            const ownerProducts = db.prepare(`SELECT id FROM products WHERE seller_id = ? AND status = 'active' ORDER BY last_sold_at DESC NULLS LAST LIMIT 50`).all(r.owner_id);
+            db.transaction(() => {
+                for (const p of ownerProducts) {
+                    const existing = db.prepare(`SELECT 1 FROM product_share_attribution WHERE product_id = ? AND recipient_id = ?`).get(p.id, user.id);
+                    if (existing)
+                        continue;
+                    db.prepare(`INSERT INTO product_share_attribution (product_id, recipient_id, sharer_id, shareable_id, expires_at) VALUES (?,?,?,NULL,?)`)
+                        .run(p.id, user.id, r.owner_id, expiresAt);
+                    attributedProducts++;
+                }
+            })();
+        }
+        // dispute_case：无商业 attribution
+        res.json({
+            ok: true,
+            target_kind: r.target_kind,
+            target_id: r.target_id,
+            owner_id: r.owner_id,
+            tier_letter: r.tier_letter,
+            attributed_products: attributedProducts,
+        });
+    });
+    app.post('/api/anchor/:code/retire', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const r = retireAnchor(db, user.id, String(req.params.code || ''));
+        if (!r.ok) {
+            const status = r.reason === 'not_found' ? 404 : r.reason === 'not_owner' ? 403 : 400;
+            return void res.status(status).json({ error: r.reason });
+        }
+        res.json({ ok: true });
+    });
+    app.get('/api/anchor/me', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const rows = db.prepare(`
+      SELECT anchor, prefix, middle, tier_letter, target_kind, target_id, status, retired_at, hits, last_hit_at, created_at
+      FROM anchor_registry WHERE owner_id = ? ORDER BY created_at DESC LIMIT 100
+    `).all(user.id);
+        const vol = userReferralVolume(db, user.id);
+        const tier = computeTierLetter(vol);
+        const quota = userAnchorQuotaStats(db, user.id);
+        res.json({
+            items: rows,
+            current_tier: tier,
+            referral_volume: vol,
+            handle_max_for_anchor: ANCHOR_HANDLE_MAX_FOR_USE,
+            tier_thresholds: TIER_THRESHOLDS,
+            quota,
+        });
+    });
+}

package/dist/pwa/routes/announcements.js

@@ -0,0 +1,110 @@
+export function registerAnnouncementsRoutes(app, deps) {
+    const { db, generateId, auth, safeRoles, requireProtocolAdmin, isRootAdmin, getAdminScope, logAdminAction } = deps;
+    app.post('/api/admin/announcements', (req, res) => {
+        const admin = requireProtocolAdmin(req, res);
+        if (!admin)
+            return;
+        const { title, body, target_roles, target_regions, severity, starts_at, expires_at } = req.body || {};
+        if (!title?.trim() || title.length > 100)
+            return void res.status(400).json({ error: 'title 1-100 字' });
+        if (!body?.trim() || body.length > 2000)
+            return void res.status(400).json({ error: 'body 1-2000 字' });
+        if (severity && !['info', 'warning', 'critical'].includes(severity))
+            return void res.status(400).json({ error: 'severity 须为 info / warning / critical' });
+        const rolesJson = Array.isArray(target_roles) && target_roles.length > 0 ? JSON.stringify(target_roles) : null;
+        const regionsJson = Array.isArray(target_regions) && target_regions.length > 0 ? JSON.stringify(target_regions) : null;
+        // 区域 admin 只能发本区域
+        if (!isRootAdmin(admin)) {
+            const scope = getAdminScope(admin);
+            if (regionsJson) {
+                const parsedRegions = JSON.parse(regionsJson);
+                if (!parsedRegions.every(r => r === scope))
+                    return void res.status(403).json({ error: `区域 admin 仅可发本区域 (${scope}) 公告` });
+            }
+            else {
+                return void res.status(400).json({ error: `区域 admin 必须指定 target_regions: ['${scope}']` });
+            }
+        }
+        const id = generateId('ann');
+        db.prepare(`INSERT INTO announcements (id, author_id, title, body, target_roles, target_regions, severity, starts_at, expires_at) VALUES (?,?,?,?,?,?,?,?,?)`)
+            .run(id, admin.id, title.trim(), body.trim(), rolesJson, regionsJson, severity || 'info', starts_at || null, expires_at || null);
+        logAdminAction(admin.id, 'create_announcement', 'announcement', id, { title, severity: severity || 'info' });
+        res.json({ success: true, id });
+    });
+    app.patch('/api/admin/announcements/:id', (req, res) => {
+        const admin = requireProtocolAdmin(req, res);
+        if (!admin)
+            return;
+        const ann = db.prepare('SELECT id, author_id FROM announcements WHERE id = ?').get(req.params.id);
+        if (!ann)
+            return void res.status(404).json({ error: '公告不存在' });
+        if (!isRootAdmin(admin) && ann.author_id !== admin.id)
+            return void res.status(403).json({ error: '仅可编辑自己发的公告（root 可全管）' });
+        const { is_active, expires_at } = req.body || {};
+        const sets = [];
+        const args = [];
+        if (is_active !== undefined) {
+            sets.push('is_active = ?');
+            args.push(is_active ? 1 : 0);
+        }
+        if (expires_at !== undefined) {
+            sets.push('expires_at = ?');
+            args.push(expires_at);
+        }
+        if (sets.length === 0)
+            return void res.status(400).json({ error: '无可更新字段' });
+        args.push(req.params.id);
+        db.prepare(`UPDATE announcements SET ${sets.join(', ')} WHERE id = ?`).run(...args);
+        res.json({ success: true });
+    });
+    // 列出对当前用户可见的活跃公告（按角色 + 区域过滤）
+    app.get('/api/announcements/active', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const userRoles = safeRoles(user);
+        const userRegion = user.region || 'global';
+        const rows = db.prepare(`
+      SELECT a.id, a.title, a.body, a.severity, a.created_at, a.target_roles, a.target_regions,
+             (SELECT 1 FROM announcement_reads WHERE user_id = ? AND announcement_id = a.id) as is_read
+      FROM announcements a
+      WHERE a.is_active = 1
+        AND (a.starts_at IS NULL OR a.starts_at <= datetime('now'))
+        AND (a.expires_at IS NULL OR a.expires_at >= datetime('now'))
+      ORDER BY a.created_at DESC LIMIT 50
+    `).all(user.id);
+        // JS 端 filter 角色 / 区域（避免 JSON LIKE 在 SQLite 中麻烦）
+        const filtered = rows.filter(a => {
+            if (a.target_roles) {
+                try {
+                    const tr = JSON.parse(a.target_roles);
+                    const matches = tr.some(r => userRoles.includes(r) || user.role === r);
+                    if (!matches)
+                        return false;
+                }
+                catch { }
+            }
+            if (a.target_regions) {
+                try {
+                    const tg = JSON.parse(a.target_regions);
+                    if (!tg.includes(userRegion))
+                        return false;
+                }
+                catch { }
+            }
+            return true;
+        }).map(a => ({ ...a, target_roles: undefined, target_regions: undefined, is_read: !!a.is_read }));
+        res.json({ items: filtered });
+    });
+    app.post('/api/announcements/:id/read', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        try {
+            db.prepare(`INSERT OR IGNORE INTO announcement_reads (user_id, announcement_id) VALUES (?,?)`)
+                .run(user.id, req.params.id);
+        }
+        catch { }
+        res.json({ success: true });
+    });
+}

package/dist/pwa/routes/ap2-mandate.js

@@ -0,0 +1,121 @@
+/**
+ * AP2 Mandate 构造器 — 把 webaz 内部 verify_price / place_order 输出
+ * 映射为 Google AP2 (Agent Payments Protocol) 的三类 Mandate 结构,
+ * 与 webaz 原 schema 并存(不破坏现有客户端),让 AP2-aware 的 agent 可直接消费。
+ *
+ * AP2 三类 Mandate:
+ *   IntentMandate  — 用户/agent "想买什么"(verify_price 锁价时签发)
+ *   CartMandate    — agent 实际组装的购物车(place_order 成功时签发)
+ *   PaymentMandate — 卖家应收金额(place_order 成功时签发,与 Cart 并发)
+ *
+ * 签名方案 = Phase 4 同款 eip191(hot wallet),signature 字段由调用方填充。
+ * canonical 是用于签名的 JSON.stringify 输出(确定序列化、键序固定)。
+ */
+const AP2_VERSION = '1.0';
+const AP2_SPEC = 'https://github.com/google-agentic-commerce/AP2';
+function nowIso() { return new Date().toISOString(); }
+function canonical(obj) {
+    // 简单深排序后 JSON.stringify;够用于签名稳定性,不引入额外依赖。
+    const sort = (v) => {
+        if (v === null || typeof v !== 'object')
+            return v;
+        if (Array.isArray(v))
+            return v.map(sort);
+        return Object.keys(v).sort().reduce((acc, k) => {
+            acc[k] = sort(v[k]);
+            return acc;
+        }, {});
+    };
+    return JSON.stringify(sort(obj));
+}
+function baseProof(input) {
+    return {
+        type: 'EcdsaSecp256k1RecoverySignature2020',
+        scheme: 'eip191',
+        proofPurpose: 'assertionMethod',
+        verificationMethod: `${input.issuerDid}#controller`,
+        blockchainAccountId: `eip155:8453:${input.issuerAddress}`,
+        created: input.issuedAt ?? nowIso(),
+        signature: '', // 调用方填充
+    };
+}
+export function buildIntentMandate(input) {
+    const issuedAt = input.issuedAt ?? nowIso();
+    const mandate = {
+        '@context': ['https://www.w3.org/2018/credentials/v1', AP2_SPEC],
+        type: ['VerifiableCredential', 'IntentMandate'],
+        ap2_version: AP2_VERSION,
+        issuer: input.issuerDid,
+        issuedAt,
+        ...(input.expiresAt ? { expiresAt: input.expiresAt } : {}),
+        principal: input.principal,
+        intent: {
+            action: 'purchase',
+            target: { type: 'product', sku: input.productId, ...(input.productName ? { name: input.productName } : {}) },
+            constraints: {
+                max_unit_price: input.maxUnitPrice,
+                quantity: input.quantity,
+                max_total: input.maxUnitPrice * input.quantity,
+                currency: input.currency,
+            },
+            session_token: input.sessionToken,
+        },
+        proof: baseProof({ ...input, issuedAt }),
+    };
+    // canonical 签名内容 = 除 proof.signature 外的全部字段
+    const forSign = JSON.parse(JSON.stringify(mandate));
+    forSign.proof.signature = '';
+    return { canonical: canonical(forSign), mandate };
+}
+export function buildCartMandate(input) {
+    const issuedAt = input.issuedAt ?? nowIso();
+    const mandate = {
+        '@context': ['https://www.w3.org/2018/credentials/v1', AP2_SPEC],
+        type: ['VerifiableCredential', 'CartMandate'],
+        ap2_version: AP2_VERSION,
+        issuer: input.issuerDid,
+        issuedAt,
+        principal: input.principal,
+        cart: {
+            order_id: input.orderId,
+            items: input.items,
+            subtotal: input.subtotal,
+            ...(input.fees ? { fees: input.fees } : {}),
+            total: input.total,
+            currency: input.currency,
+        },
+        proof: baseProof({ ...input, issuedAt }),
+    };
+    const forSign = JSON.parse(JSON.stringify(mandate));
+    forSign.proof.signature = '';
+    return { canonical: canonical(forSign), mandate };
+}
+export function buildPaymentMandate(input) {
+    const issuedAt = input.issuedAt ?? nowIso();
+    const mandate = {
+        '@context': ['https://www.w3.org/2018/credentials/v1', AP2_SPEC],
+        type: ['VerifiableCredential', 'PaymentMandate'],
+        ap2_version: AP2_VERSION,
+        issuer: input.issuerDid,
+        issuedAt,
+        payer: input.payer,
+        payee: input.payee,
+        payment: {
+            amount: input.amount,
+            currency: input.currency,
+            method: input.paymentMethod,
+            order_id: input.orderId,
+            ...(input.escrowReleaseCondition ? { release_condition: input.escrowReleaseCondition } : {}),
+        },
+        proof: baseProof({ ...input, issuedAt }),
+    };
+    const forSign = JSON.parse(JSON.stringify(mandate));
+    forSign.proof.signature = '';
+    return { canonical: canonical(forSign), mandate };
+}
+/** 把 build*Mandate 输出的 canonical 经 signFn 签名后,塞回 mandate.proof.signature */
+export async function signMandate(out, signFn) {
+    const sig = await signFn(out.canonical);
+    out.mandate.proof.signature = sig;
+    return out.mandate;
+}