@seasonkoh/webaz 0.1.28 → 0.1.30

package/dist/runtime/webaz-schema-helpers.js

@@ -784,6 +784,17 @@ export function initArbitratorReviewSchema(db) {
     stake_amount    INTEGER DEFAULT 0
   )
 `);
+    // PR-B 生产仲裁员生命周期字段(ADD COLUMN 必在 CREATE 后 —— schema 铁律)。legacy 行 status NULL 视为 active。
+    for (const alter of [
+        `ALTER TABLE arbitrator_whitelist ADD COLUMN status TEXT DEFAULT 'active'`, // active | suspended | revoked
+        `ALTER TABLE arbitrator_whitelist ADD COLUMN suspended_at TEXT`,
+        `ALTER TABLE arbitrator_whitelist ADD COLUMN revoked_at TEXT`,
+    ]) {
+        try {
+            db.exec(alter);
+        }
+        catch { /* 列已存在 */ }
+    }
     try {
         db.exec('CREATE INDEX IF NOT EXISTS idx_arb_apps_status ON arbitrator_applications(status)');
     }
@@ -1220,7 +1231,7 @@ export function initReturnRequestsSchema(db) {
     reason               TEXT NOT NULL,          -- 'quality' | 'wrong_item' | 'damaged' | 'no_longer_needed' | 'other'
     reason_text          TEXT,
     refund_amount        DECIMAL(18,2),          -- 默认 = order.total_amount
-    status               TEXT NOT NULL DEFAULT 'pending', -- pending | accepted | rejected | refunded | escalated | cancelled
+    status               TEXT NOT NULL DEFAULT 'pending', -- pending | accepted | rejected | refunded | escalated | cancelled | (direct_p2p) await_refund | refund_marked
     seller_response      TEXT,
     escalated_dispute_id TEXT,
     created_at           TEXT DEFAULT (datetime('now')),
@@ -1239,6 +1250,15 @@ export function initReturnRequestsSchema(db) {
         db.exec('CREATE INDEX IF NOT EXISTS idx_returns_order ON return_requests(order_id)');
     }
     catch { }
+    // 直付(direct_p2p)送达后退货·场外退款握手(src/direct-pay-returns.ts)。ALTER 必须在 CREATE 之后(fresh DB silent-fail 铁律)。
+    try {
+        db.exec('ALTER TABLE return_requests ADD COLUMN refund_reference TEXT');
+    }
+    catch { /* 已存在 */ }
+    try {
+        db.exec('ALTER TABLE return_requests ADD COLUMN await_refund_since TEXT');
+    }
+    catch { /* 已存在 */ }
 }
 // ─── W2 售后协商时间线（flagged/flag_reasons ALTER 刻意留 server.ts 原位）──
 export function initReturnMessagesSchema(db) {
@@ -1784,13 +1804,47 @@ export function initAgentDelegationGrantsSchema(db) {
       created_at      TEXT NOT NULL DEFAULT (datetime('now')),
       expires_at      TEXT NOT NULL,                    -- short-lived (clamped, RFC-020 bearer-first)
       revoked_at      TEXT,
-      revoked_reason  TEXT
+      revoked_reason  TEXT,
+      permission_bundle TEXT                            -- named bundle key if issued/expanded via a bundle (e.g. 'catalog_agent'); NULL = ad-hoc scopes
     )
   `);
+    try {
+        db.exec(`ALTER TABLE agent_delegation_grants ADD COLUMN permission_bundle TEXT`);
+    }
+    catch { /* existing DB: column already added */ }
     db.exec(`CREATE INDEX IF NOT EXISTS idx_adg_human  ON agent_delegation_grants(human_id, status)`);
     db.exec(`CREATE INDEX IF NOT EXISTS idx_adg_token  ON agent_delegation_grants(token_hash)`);
     db.exec(`CREATE INDEX IF NOT EXISTS idx_adg_expiry ON agent_delegation_grants(status, expires_at)`);
 }
+/**
+ * RFC-020 — Agent Permission Requests (JIT + bundle authorization). An already-connected agent (holds a
+ * grant) that hits a missing scope, or wants a job bundle, lodges a REQUEST here; the human sees it in
+ * #agent-approvals and approves/rejects. Approval expands the agent's existing grant (safe scopes only,
+ * duration-capped). Bound to (human_id, grant_id). NO money/order/status columns; a request grants nothing
+ * until a human approves it.
+ */
+export function initAgentPermissionRequestsSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS agent_permission_requests (
+      id               TEXT PRIMARY KEY,                 -- apr_xxx
+      human_id         TEXT NOT NULL,                    -- resolved from the requesting agent's grant
+      grant_id         TEXT NOT NULL,                    -- the agent's existing grant that approval expands
+      agent_label      TEXT,
+      requested_scopes TEXT NOT NULL DEFAULT '[]',       -- JSON string[] — resolved (bundle expanded) safe scopes
+      permission_bundle TEXT,                            -- bundle key if requested as a bundle; NULL = ad-hoc
+      reason           TEXT,                             -- agent free-text (display only, unverified)
+      task_context     TEXT,                             -- agent free-text about the task (display only)
+      risk_level       TEXT NOT NULL DEFAULT 'low',      -- low | medium | high (derived, not agent-supplied)
+      duration         TEXT NOT NULL DEFAULT '7d',       -- once | 1h | 24h | 7d | 30d (capped by risk tier)
+      status           TEXT NOT NULL DEFAULT 'pending',  -- pending | approved | rejected | expired | revoked
+      created_at       TEXT NOT NULL DEFAULT (datetime('now')),
+      expires_at       TEXT NOT NULL,                    -- request TTL (auto-expire if unanswered)
+      approved_at      TEXT
+    )
+  `);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_apr_human  ON agent_permission_requests(human_id, status)`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_apr_status ON agent_permission_requests(status, expires_at)`);
+}
 /**
  * RFC-020 PR-C1 — agent pairing sessions (OAuth device-flow + PKCE shape).
  *
@@ -1812,7 +1866,7 @@ export function initAgentPairingSchema(db) {
       agent_pubkey    TEXT,                             -- RESERVED (PoP); stored if sent, NOT verified in C1
       reason          TEXT,                             -- agent free-text reason (shown in consent)
       capabilities    TEXT NOT NULL DEFAULT '[]',       -- requested SAFE scopes (validated safe-only at start)
-      status          TEXT NOT NULL DEFAULT 'pending',  -- pending | approved | consumed | expired | revoked
+      status          TEXT NOT NULL DEFAULT 'pending',  -- pending | approved | consumed | expired | revoked | rejected(human declined)
       human_id        TEXT,                             -- set on approve
       grant_id        TEXT,                             -- set on approve (issued grant; token_hash filled at retrieve)
       created_at      TEXT NOT NULL DEFAULT (datetime('now')),
@@ -1846,3 +1900,107 @@ export function initAgentGrantAuthLogSchema(db) {
     db.exec(`CREATE INDEX IF NOT EXISTS idx_agal_grant ON agent_grant_auth_log(grant_id, ts)`);
     db.exec(`CREATE INDEX IF NOT EXISTS idx_agal_ts ON agent_grant_auth_log(ts)`);
 }
+/**
+ * pending_commission_escrow — opt-out promoter activation queue (§3.5b) + RFC-018 clearing ledger.
+ *
+ * Relocated VERBATIM from src/pwa/server.ts (RFC-018 PR1) so the table's whole schema is built once,
+ * in the early helper batch — never half-here / half-inline (the fresh-DB silent-fail铁律 bites a
+ * half-migration the hardest). RFC-018 adds two things, SCHEMA-ONLY (no settle / escrow read-write
+ * logic touched):
+ *   - `matures_at` column — the accrue-then-mature clock (= completed_at + return_days +
+ *     settlement.clearing_buffer_days); NULL until the PR2 clearing model writes it.
+ *   - `reversed` status value — a return inside the clearing window flips pending→reversed; it is a
+ *     TEXT value, so it needs no schema change (documented in the column comment).
+ * order_id stays NULLable for pv_pair rows (PR-1c-b).
+ *
+ * Migration, two independent cases (both idempotent, both skip when already current):
+ *   (a) order_id NOT NULL (pre-1c-b) → full rebuild — SQLite ADD COLUMN cannot relax a NOT NULL
+ *       constraint. Explicit-column INSERT maps the old rows; FK OFF/ON restores L0's global ON. The
+ *       rebuilt table already carries matures_at, so (b) then no-ops.
+ *   (b) missing matures_at (pre-RFC-018) → a cheap, NON-destructive `ALTER TABLE ADD COLUMN`. No
+ *       DROP, rows + indexes preserved. This is the common existing-DB path (every pre-RFC-018 DB,
+ *       incl. prod). We deliberately do NOT rebuild for an additive column — a money-path table on a
+ *       persistent prod volume should take the smallest safe migration. (Allowed here because the
+ *       complexity ratchet counts DDL in server.ts only, not this helper.)
+ */
+export function initPendingCommissionEscrowSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS pending_commission_escrow (
+      id                       INTEGER PRIMARY KEY AUTOINCREMENT,
+      recipient_user_id        TEXT NOT NULL,
+      order_id                 TEXT,                                 -- NULL for pv_pair (PR-1c-b)
+      amount                   REAL NOT NULL,    -- WAZ amount
+      attribution_path         TEXT NOT NULL,    -- 'L1' | 'L2' | 'L3' | 'pv_pair' | etc.
+      status                   TEXT NOT NULL DEFAULT 'pending',  -- 'pending' | 'settled' | 'expired' | 'reversed' (RFC-018)
+      created_at               INTEGER NOT NULL,
+      expires_at               INTEGER NOT NULL,
+      settled_at               INTEGER,
+      expired_to_charity_at    INTEGER,
+      matures_at               INTEGER,          -- RFC-018: completed_at + return_days + clearing_buffer_days; NULL until the clearing model writes it
+      FOREIGN KEY (recipient_user_id) REFERENCES users(id),
+      FOREIGN KEY (order_id) REFERENCES orders(id)
+    )
+  `);
+    (function migrateEscrowSchema() {
+        const cols = db.prepare("PRAGMA table_info(pending_commission_escrow)").all();
+        if (cols.length === 0)
+            return; // table absent (shouldn't happen — CREATE above just ran)
+        const orderIdCol = cols.find(c => c.name === 'order_id');
+        const orderIdNotNull = !!orderIdCol && orderIdCol.notnull === 1;
+        // (a) STRUCTURAL (pre-1c-b): order_id NOT NULL → nullable. Unavoidable full rebuild (ADD COLUMN
+        // cannot relax NOT NULL). The rebuilt table already includes matures_at, so (b) below no-ops.
+        if (orderIdNotNull) {
+            console.log('[pc-escrow-migrate] order_id NOT NULL — rebuilding table to allow NULL for pv_pair');
+            db.exec('PRAGMA foreign_keys = OFF');
+            db.transaction(() => {
+                db.exec(`
+          CREATE TABLE pending_commission_escrow_new (
+            id                       INTEGER PRIMARY KEY AUTOINCREMENT,
+            recipient_user_id        TEXT NOT NULL,
+            order_id                 TEXT,
+            amount                   REAL NOT NULL,
+            attribution_path         TEXT NOT NULL,
+            status                   TEXT NOT NULL DEFAULT 'pending',
+            created_at               INTEGER NOT NULL,
+            expires_at               INTEGER NOT NULL,
+            settled_at               INTEGER,
+            expired_to_charity_at    INTEGER,
+            matures_at               INTEGER,
+            FOREIGN KEY (recipient_user_id) REFERENCES users(id),
+            FOREIGN KEY (order_id) REFERENCES orders(id)
+          )
+        `);
+                // explicit columns: an older DB lacks matures_at → it defaults to NULL in _new (never SELECT *)
+                db.exec(`INSERT INTO pending_commission_escrow_new
+          (id, recipient_user_id, order_id, amount, attribution_path, status, created_at, expires_at, settled_at, expired_to_charity_at)
+          SELECT id, recipient_user_id, order_id, amount, attribution_path, status, created_at, expires_at, settled_at, expired_to_charity_at
+          FROM pending_commission_escrow`);
+                db.exec('DROP TABLE pending_commission_escrow');
+                db.exec('ALTER TABLE pending_commission_escrow_new RENAME TO pending_commission_escrow');
+            })();
+            db.exec('PRAGMA foreign_keys = ON');
+        }
+        // (b) ADDITIVE (pre-RFC-018): matures_at missing → cheap, non-destructive column add (no DROP;
+        // rows + indexes preserved). Idempotent: throws "duplicate column" once present (fresh DB, or
+        // just-rebuilt in (a)) → swallowed. This is the path every existing prod DB takes.
+        try {
+            db.exec('ALTER TABLE pending_commission_escrow ADD COLUMN matures_at INTEGER');
+        }
+        catch { /* column already exists */ }
+    })();
+    try {
+        db.exec('CREATE INDEX IF NOT EXISTS idx_escrow_recipient ON pending_commission_escrow(recipient_user_id, status, expires_at)');
+    }
+    catch { }
+    try {
+        db.exec('CREATE INDEX IF NOT EXISTS idx_escrow_expiry ON pending_commission_escrow(status, expires_at)');
+    }
+    catch { }
+    // PR-1c-a: UNIQUE (recipient, order, path) defends against double-insert if settleCommission ever retries
+    // Note: NULL order_id (PR-1c-b pv_pair) is distinct in SQLite UNIQUE — idempotency for pv_pair relies
+    // on binary_score_records.settled_at instead (source-side dedup).
+    try {
+        db.exec('CREATE UNIQUE INDEX IF NOT EXISTS uniq_escrow_recipient_order_path ON pending_commission_escrow(recipient_user_id, order_id, attribution_path)');
+    }
+    catch { }
+}

package/dist/sale-regions.js

@@ -0,0 +1,116 @@
+const REGION_RE = /^[A-Z0-9-]{2,8}$/;
+/** parse-don't-validate:坏 JSON/坏形状 → null(= 不限,fail-open 到原行为;写入侧另有严校验)。 */
+export function parseSaleRegionsRule(raw) {
+    if (typeof raw !== 'string' || !raw)
+        return null;
+    try {
+        const r = JSON.parse(raw);
+        if (!r || (r.mode !== 'all' && r.mode !== 'list'))
+            return null;
+        const norm = (a) => Array.isArray(a) ? a.map(x => String(x).toUpperCase()).filter(x => REGION_RE.test(x)) : undefined;
+        return { mode: r.mode, include: norm(r.include), exclude: norm(r.exclude) };
+    }
+    catch {
+        return null;
+    }
+}
+/** 写入侧严校验:返回规范化 JSON 串,或 {error}。null/空 = 清除(继承上层)。 */
+export function validateSaleRegionsInput(raw) {
+    if (raw === null || raw === undefined || raw === '')
+        return { json: null };
+    const r = raw;
+    if (typeof r !== 'object' || (r.mode !== 'all' && r.mode !== 'list'))
+        return { error: "sale_regions.mode 必须是 'all' 或 'list'" };
+    const norm = (a, name) => {
+        if (a === undefined || a === null)
+            return undefined;
+        if (!Array.isArray(a) || a.length > 64)
+            return { error: `sale_regions.${name} 须为 ≤64 项数组` };
+        const out = [];
+        for (const x of a) {
+            const code = String(x).trim().toUpperCase();
+            if (!REGION_RE.test(code))
+                return { error: `sale_regions.${name} 含非法地区码:${String(x).slice(0, 12)}(2-8 位大写字母/数字/-)` };
+            out.push(code);
+        }
+        return [...new Set(out)];
+    };
+    const inc = norm(r.include, 'include');
+    if (inc && 'error' in inc)
+        return inc;
+    const exc = norm(r.exclude, 'exclude');
+    if (exc && 'error' in exc)
+        return exc;
+    if (r.mode === 'list' && (!inc || inc.length === 0))
+        return { error: "mode='list' 时 include 不能为空(否则等于全不可卖 —— 想全不可卖请直接下架)" };
+    return { json: JSON.stringify({ mode: r.mode, ...(inc ? { include: inc } : {}), ...(exc ? { exclude: exc } : {}) }) };
+}
+/** 生效规则:商品 ?? 店铺(与 accept_mode/运费模板同层级约定)。 */
+export function effectiveSaleRegionsRule(db, product, sellerId) {
+    const own = parseSaleRegionsRule(product.sale_regions);
+    if (own)
+        return own;
+    try {
+        const row = db.prepare('SELECT store_sale_regions FROM users WHERE id = ?').get(sellerId);
+        return parseSaleRegionsRule(row?.store_sale_regions);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 平台合规名单解析(单一真相源:建单门 gateSaleRegionForCreate + S5 预检 shipping-options 共用)。
+ *   坏配置(非 JSON / 非数组)→ { ok:false },由调用方 fail-closed(建单 503;预检 sellable=platform_policy_invalid)。
+ *   缺省 '[]' → { ok:true, list:[] }。区码统一大写。
+ */
+export function parsePlatformBlocklist(raw) {
+    try {
+        const p = JSON.parse(String(raw ?? '[]'));
+        if (!Array.isArray(p))
+            return { ok: false };
+        return { ok: true, list: p.map(x => String(x).toUpperCase()) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+export function regionAllowedByRule(rule, region) {
+    const r = region.toUpperCase();
+    if (rule.exclude?.includes(r))
+        return false;
+    if (rule.mode === 'list')
+        return !!rule.include?.includes(r);
+    return true;
+}
+/**
+ * 建单可售门(orders-create 单行调用,两轨共用,运费 gate 之前、任何写之前)。
+ * 返回 false = 已写错误响应。平台 overlay 先裁(商家规则不可放宽合规);规则存在但买家没给地区 → fail-closed 要求补选。
+ */
+export function gateSaleRegionForCreate(db, res, product, sellerId, rawRegion, getProtocolParam) {
+    const region = (typeof rawRegion === 'string' && rawRegion.trim()) ? rawRegion.trim().toUpperCase() : null;
+    // ① 平台合规 overlay(protocol param,DEFAULT_PARAMS 已 seed '[]';admin PATCH 有 JSON+区码校验)。
+    //   坏配置【fail-closed】:合规名单读不懂时放行 = 静默解除平台禁售(审计 P2) —— 宁可挡单也不裸奔;
+    //   admin 写入侧已强校验,坏值只可能来自手改 DB,错误信息直接指路。
+    const parsedBlock = parsePlatformBlocklist(getProtocolParam('trade.platform_region_blocklist', '[]'));
+    if (!parsedBlock.ok) {
+        res.status(503).json({ error: '平台合规配置异常,暂无法下单(运营侧需修复 trade.platform_region_blocklist 参数)', error_code: 'PLATFORM_REGION_POLICY_INVALID' });
+        return false;
+    }
+    const platformBlock = parsedBlock.list;
+    const rule = effectiveSaleRegionsRule(db, product, sellerId);
+    if (platformBlock.length === 0 && !rule)
+        return true; // 无任何限制 = 原行为(地区可选)
+    if (!region) {
+        res.status(400).json({ error: '该商品设有可售地区限制,请选择收货国家/地区', error_code: 'SHIP_REGION_REQUIRED' });
+        return false;
+    }
+    if (platformBlock.includes(region)) {
+        res.status(409).json({ error: '平台合规限制:该商品暂不支持销售到该地区', error_code: 'PRODUCT_RESTRICTED', region });
+        return false;
+    }
+    if (rule && !regionAllowedByRule(rule, region)) {
+        res.status(409).json({ error: '卖家未将该地区设为可售范围(与运费无关,不适用询价)', error_code: 'REGION_NOT_FOR_SALE', region });
+        return false;
+    }
+    return true;
+}

package/dist/shipping-templates.js

@@ -0,0 +1,119 @@
+import { toUnits } from './money.js';
+import { freeShippingWaives } from './free-shipping.js'; // 营销域:满额免邮(S2 返工 —— 促销语义不进成本模板)
+const MAX_ENTRIES = 50;
+const MAX_REGION_LEN = 16;
+const MAX_EST_LEN = 20;
+const MAX_FEE = 1_000_000;
+/** 规范化地区 code:trim + 大写。空/非串 → null。 */
+export function normalizeRegion(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const r = raw.trim().toUpperCase();
+    if (!r || r.length > MAX_REGION_LEN)
+        return null;
+    return r;
+}
+/** 校验并规范化模板。null/undefined = 清除模板(合法)。返回 {ok, entries} 或 {ok:false, error}。 */
+export function parseShippingTemplate(raw) {
+    if (raw == null)
+        return { ok: true, entries: null };
+    if (!Array.isArray(raw))
+        return { ok: false, error: '模板必须是数组' };
+    if (raw.length === 0)
+        return { ok: true, entries: null }; // 空数组视同清除
+    if (raw.length > MAX_ENTRIES)
+        return { ok: false, error: `模板最多 ${MAX_ENTRIES} 条` };
+    const out = [];
+    const seen = new Set();
+    for (const e of raw) {
+        const region = e && e.region === '*' ? '*' : normalizeRegion(e?.region);
+        if (!region)
+            return { ok: false, error: '每条须有合法 region(≤16 字大写 code 或 *)' };
+        if (seen.has(region))
+            return { ok: false, error: `region 重复:${region}` };
+        seen.add(region);
+        const fee = Number(e?.fee);
+        if (!Number.isFinite(fee) || fee < 0 || fee > MAX_FEE)
+            return { ok: false, error: `运费必须是 0~${MAX_FEE} 的数字(${region})` };
+        const est = e?.est_days == null ? undefined : String(e.est_days).trim().slice(0, MAX_EST_LEN);
+        out.push({ region, fee: Math.round(fee * 100) / 100, ...(est ? { est_days: est } : {}) });
+    }
+    return { ok: true, entries: out };
+}
+/** 解析已存 JSON(容错:坏 JSON/坏结构 → null=无模板,不阻断读路径)。 */
+export function loadTemplateJson(json) {
+    if (!json)
+        return null;
+    try {
+        const p = parseShippingTemplate(JSON.parse(json));
+        return p.ok ? p.entries : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 生效模板:单品覆盖 ?? 店铺默认 ?? null。product 传订单路径已取到的行(含 shipping_template 列)。 */
+export function effectiveShippingTemplate(db, product, sellerId) {
+    const own = loadTemplateJson(product.shipping_template);
+    if (own)
+        return own;
+    try {
+        const row = db.prepare('SELECT store_shipping_template FROM users WHERE id = ?').get(sellerId);
+        return loadTemplateJson(row?.store_shipping_template);
+    }
+    catch {
+        return null;
+    }
+}
+/** 按买家地区解析运费:精确 → '*' → 未覆盖。(纯成本结构;营销免邮在 gate 层应用) */
+export function resolveShipping(entries, region) {
+    const hit = entries.find(e => e.region === region) ?? entries.find(e => e.region === '*');
+    if (!hit)
+        return { covered: false, fee: 0, est_days: null, matched: null };
+    return { covered: true, fee: hit.fee, est_days: hit.est_days ?? null, matched: hit.region === region ? 'exact' : 'wildcard' };
+}
+/** 询价 opt-in(PR-3):单品 shipping_quote_ok ?? 店铺 store_shipping_quote_ok ?? 关。 */
+export function quoteOutsideTemplateOk(db, product, sellerId) {
+    if (product.shipping_quote_ok != null)
+        return Number(product.shipping_quote_ok) === 1;
+    try {
+        const row = db.prepare('SELECT store_shipping_quote_ok FROM users WHERE id = ?').get(sellerId);
+        return Number(row?.store_shipping_quote_ok) === 1;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 建单运费守门(orders-create 单行调用,两轨共用,任何 DB write 之前):
+ *  - 无模板:不要求地区(给了就规范化快照),运费 0 —— 原行为。
+ *  - 有模板:必须给合法 ship_to_region(否则 400 SHIP_REGION_REQUIRED);命中 → 返回运费(调用方并入总额)。
+ *  - 未命中(含无 '*'):卖家开了询价(quoteOutsideTemplateOk)且直付轨 → quoteRequired=true(建单落
+ *    pending_accept,卖家先报运费/时效、买家确认新总额才进付款窗 —— PR-3);否则(未开询价 / escrow 轨,
+ *    escrow 询价需付款后置钱路手术,PR-5)→ 409 SHIP_REGION_NOT_COVERED。
+ * 返回 null = 已写错误响应,调用方直接 return。
+ */
+export function gateShippingForCreate(db, res, product, sellerId, rawRegion, rail = 'escrow', goodsSubtotalU) {
+    const region = normalizeRegion(rawRegion);
+    const tpl = effectiveShippingTemplate(db, product, sellerId);
+    if (!tpl)
+        return { feeU: 0, fee: 0, region, estDays: null, quoteRequired: false };
+    if (!region) {
+        res.status(400).json({ error: '该商品按地区计运费,请选择收货国家/地区', error_code: 'SHIP_REGION_REQUIRED' });
+        return null;
+    }
+    const r = resolveShipping(tpl, region);
+    if (r.covered) {
+        // 营销域满额免邮(S2 返工:规则在 free-shipping.ts,不在模板)—— 模板费为正 + 券后货款达标 → 免为 0。
+        //   人工询价路径不经此分支(quoteRequired 在下方),天然豁免。
+        if (r.fee > 0 && goodsSubtotalU !== undefined && freeShippingWaives(db, product, sellerId, goodsSubtotalU)) {
+            return { feeU: 0, fee: 0, region, estDays: r.est_days, quoteRequired: false, freeThresholdApplied: true };
+        }
+        return { feeU: toUnits(r.fee), fee: r.fee, region, estDays: r.est_days, quoteRequired: false };
+    }
+    if (rail === 'direct_p2p' && quoteOutsideTemplateOk(db, product, sellerId)) {
+        return { feeU: 0, fee: 0, region, estDays: null, quoteRequired: true }; // 运费待卖家报价,先不入总额
+    }
+    res.status(409).json({ error: rail === 'direct_p2p' ? '卖家暂不配送到该地区' : '卖家暂不配送到该地区(该商品支持直付询价的话,可改用直付下单)', error_code: 'SHIP_REGION_NOT_COVERED', region });
+    return null;
+}

package/dist/store-verification.js

@@ -0,0 +1,77 @@
+export const MAX_URL_LEN = 2048;
+export const MAX_PLATFORM_LEN = 60;
+export const MAX_NOTES_LEN = 500;
+const ACTIVE = "('issued','submitted','verified')";
+const getActive = (db, userId) => db.prepare(`SELECT * FROM store_verifications WHERE user_id = ? AND status IN ${ACTIVE} ORDER BY created_at DESC, rowid DESC LIMIT 1`).get(userId);
+function isStorableHttpUrl(url) {
+    if (typeof url !== 'string' || url.length === 0 || url.length > MAX_URL_LEN)
+        return false;
+    return /^https?:\/\/[^\s]+$/i.test(url.trim());
+}
+/** 卖家申请店铺认证 → issued(签发 code)。单一活跃 per seller。 */
+export function requestStoreVerification(db, args) {
+    const { id, userId, code } = args;
+    if (!id || !userId || !code)
+        return { ok: false, reason: 'missing id/userId/code' };
+    const platform = args.platform ? String(args.platform).trim().slice(0, MAX_PLATFORM_LEN) : null;
+    if (getActive(db, userId))
+        return { ok: false, reason: '已有进行中的店铺认证' };
+    db.prepare(`INSERT INTO store_verifications (id, user_id, code, platform, status, created_at, updated_at)
+    VALUES (?,?,?,?, 'issued', datetime('now'), datetime('now'))`).run(id, userId, code, platform);
+    return { ok: true, status: 'issued', code };
+}
+/** 卖家提交店铺外链 → submitted。要求有 issued 记录;链接仅存储(不抓取)。 */
+export function submitStoreVerificationLink(db, args) {
+    const url = String(args.externalUrl || '').trim();
+    if (!isStorableHttpUrl(url))
+        return { ok: false, reason: '请提交有效的 http(s) 店铺链接' };
+    const active = getActive(db, args.userId);
+    if (!active)
+        return { ok: false, reason: '请先申请店铺认证获取验证码' };
+    if (active.status === 'verified')
+        return { ok: false, reason: '店铺认证已通过,无需重复提交' };
+    const platform = args.platform != null ? String(args.platform).trim().slice(0, MAX_PLATFORM_LEN) : active.platform;
+    db.prepare(`UPDATE store_verifications SET external_url = ?, platform = ?, status = 'submitted', updated_at = datetime('now') WHERE id = ?`).run(url, platform, active.id);
+    return { ok: true, status: 'submitted' };
+}
+/** 真人 admin 核对结论 → verified | rejected。verified 时按 perProductExempt 置豁免位(默认 false)。仅从 submitted 流转。 */
+export function reviewStoreVerification(db, args) {
+    const { id, reviewerId, decision } = args;
+    if (!reviewerId)
+        return { ok: false, reason: 'reviewStoreVerification requires a human reviewerId' };
+    if (decision !== 'verified' && decision !== 'rejected')
+        return { ok: false, reason: 'decision must be verified|rejected' };
+    const row = db.prepare('SELECT * FROM store_verifications WHERE id = ?').get(id);
+    if (!row)
+        return { ok: false, reason: 'store verification not found' };
+    if (row.status === decision)
+        return { ok: true, status: decision, perProductExempt: row.per_product_exempt === 1, already: true };
+    if (row.status !== 'submitted')
+        return { ok: false, reason: `cannot review from status '${row.status}' (need submitted)` };
+    const exempt = decision === 'verified' && args.perProductExempt === true ? 1 : 0; // 仅 verified 才可置豁免;reject 一律 0
+    const notes = args.notes != null ? String(args.notes).slice(0, MAX_NOTES_LEN) : null;
+    db.prepare(`UPDATE store_verifications SET status = ?, per_product_exempt = ?, reviewed_by = ?, reviewed_at = datetime('now'), notes = ?, updated_at = datetime('now') WHERE id = ?`)
+        .run(decision, exempt, reviewerId, notes, id);
+    return { ok: true, status: decision, perProductExempt: exempt === 1 };
+}
+/** 卖家本人最新一条店铺认证(任意状态)。无 → null。 */
+export function getStoreVerification(db, userId) {
+    return db.prepare('SELECT * FROM store_verifications WHERE user_id = ? ORDER BY created_at DESC, rowid DESC LIMIT 1').get(userId) ?? null;
+}
+/** admin 队列:按 status 过滤(默认全部),最新在前。纯读。 */
+export function listStoreVerifications(db, opts = {}) {
+    if (opts.status)
+        return db.prepare(`SELECT * FROM store_verifications WHERE status = ? ORDER BY created_at DESC, rowid DESC`).all(opts.status);
+    return db.prepare(`SELECT * FROM store_verifications ORDER BY created_at DESC, rowid DESC`).all();
+}
+/** 硬门豁免读取:该卖家是否【已被豁免逐品验证】(店铺 verified 且 per_product_exempt=1)。供 direct-pay gate combiner。 */
+export function sellerExemptFromPerProduct(db, userId) {
+    return !!db.prepare("SELECT 1 FROM store_verifications WHERE user_id = ? AND status = 'verified' AND per_product_exempt = 1 LIMIT 1").get(userId);
+}
+export function toSellerStoreVerificationView(row) {
+    return {
+        id: row.id, code: row.code, platform: row.platform, external_url: row.external_url,
+        status: row.status, per_product_exempt: row.per_product_exempt === 1,
+        reviewed_at: row.reviewed_at, created_at: row.created_at, updated_at: row.updated_at,
+    }; // 故意省略 reviewed_by + notes
+}

package/dist/trade-tax.js

@@ -0,0 +1,99 @@
+/**
+ * 跨境税费/进口责任【声明+披露】层(S3)—— 卖家 seller-of-record 自我声明,平台【绝不计算/代收/代缴】。
+ *
+ * 定位纪律(调研结论,2026-07):非托管≠必然免平台义务。EU Art.14a "deemed supplier" 的免责是三肢连接测试
+ *   (不设条款 且 不授权收款 且 不涉订单/配送),WebAZ 设条款+涉订单 → 极可能被认定;US CA/WA 型 "any-activity"
+ *   测试里"传递要约/承诺+接单+上架"各自独立触发,与是否碰钱无关。故本层【只声明只披露】,不碰税款:
+ *     - import_duty_terms(DDP/DDU):卖家声明谁承担进口关税/税(DDP=卖家已含于价;DDU=买家到境自付)。
+ *     - tax_lines(仅 'included' 类):卖家声明"价内已含 X 税"(如 SG GST 9%)—— 纯信息披露,不改总额、不入钱路。
+ *   刻意【不做】(不上假开关):'added' 类税进总额(钱路,单独 PR 门控真实需求)、自动税率、代收代缴(Rail 3+律师)。
+ *   合规义务(即便非 deemed):EU 10 年 / UK 6 年交易留痕由 orders.trade_terms_snapshot 满足(S0 已冻结卖家/货/值/时地/单号)。
+ *   跨境进高执法辖区(EU/UK 及 CA/WA 型州)的 deemed-supplier 姿态 → 由 S1 的 trade.platform_region_blocklist 治理门
+ *   + 律师确认逐区放行(本层不自动放开)。详 docs/COMPLIANCE-CROSS-BORDER-TAX.INTERNAL.md。
+ *
+ * 层级:products.{import_duty_terms,tax_lines} ?? users.store_{import_duty_terms,tax_lines}(与接单/运费/可售同约定)。
+ * 快照:S0 的 trade-terms declarations.{import_duty_terms,tax_lines} 已从这些列自动填充 —— 本模块只管写入校验+生效解析+披露。
+ */
+const REGION_RE = /^[A-Z0-9-]{2,8}$/;
+/** DDP/DDU 写入校验:null/空=清除(继承上层);'ddu'|'ddp' 合法。 */
+export function validateImportDutyTerms(raw) {
+    if (raw === null || raw === undefined || raw === '')
+        return { value: null };
+    if (raw === 'ddu' || raw === 'ddp')
+        return { value: raw };
+    return { error: "import_duty_terms 必须是 'ddu'(买家到境自付)或 'ddp'(卖家已含)或 null" };
+}
+/** 税费科目写入校验:S3 只收 'included'(价内已含,纯披露)。'added'(进总额)明确拒 —— 钱路未开,不上假开关。 */
+export function validateTaxLines(raw) {
+    if (raw === null || raw === undefined || raw === '')
+        return { value: null };
+    if (!Array.isArray(raw))
+        return { error: 'tax_lines 必须是数组或 null' };
+    if (raw.length > 32)
+        return { error: 'tax_lines 最多 32 条' };
+    const out = [];
+    const seen = new Set();
+    for (const e of raw) {
+        if (!e || typeof e !== 'object')
+            return { error: 'tax_lines 每条须是对象' };
+        const r = e;
+        if (r.kind !== undefined && r.kind !== 'included') { // 省略 kind = 'included'(S3 唯一允许值);未来开 'added' 钱路时须显式,勿继承此静默默认
+            return { error: r.kind === 'added' ? "'added' 税费(进总额)暂不支持 —— 平台不代收税;仅支持 'included'(价内已含,披露)" : "tax_lines.kind 仅支持 'included'" };
+        }
+        const region = r.region === '*' ? '*' : (typeof r.region === 'string' ? r.region.trim().toUpperCase() : '');
+        if (region !== '*' && !REGION_RE.test(region))
+            return { error: `tax_lines 含非法 region:${String(r.region).slice(0, 12)}(2-8 位大写码或 *)` };
+        if (seen.has(region))
+            return { error: `tax_lines region 重复:${region}` };
+        seen.add(region);
+        const label = typeof r.label === 'string' ? r.label.trim().slice(0, 40) : '';
+        if (!label)
+            return { error: `tax_lines 每条须有 label(≤40 字,如 GST / VAT)(${region})` };
+        let rate_pct;
+        if (r.rate_pct !== undefined && r.rate_pct !== null) {
+            if (typeof r.rate_pct !== 'number' && typeof r.rate_pct !== 'string')
+                return { error: `tax_lines.rate_pct 必须是数字(${region})` }; // 审计:拒 Number(true)=1 类强转
+            const n = Number(r.rate_pct);
+            if (!Number.isFinite(n) || n < 0 || n > 100)
+                return { error: `tax_lines.rate_pct 必须是 0~100(${region})` };
+            rate_pct = Math.round(n * 100) / 100;
+        }
+        const note = typeof r.note === 'string' && r.note.trim() ? r.note.trim().slice(0, 80) : undefined;
+        out.push({ region, label, ...(rate_pct !== undefined ? { rate_pct } : {}), ...(note ? { note } : {}), kind: 'included' });
+    }
+    return { value: JSON.stringify(out) };
+}
+/** parse-don't-validate 读:坏 JSON/坏形状 → null。 */
+export function parseTaxLines(raw) {
+    if (typeof raw !== 'string' || !raw)
+        return null;
+    try {
+        const a = JSON.parse(raw);
+        if (!Array.isArray(a))
+            return null;
+        return a.filter((e) => !!e && typeof e === 'object' && typeof e.region === 'string' && typeof e.label === 'string');
+    }
+    catch {
+        return null;
+    }
+}
+/** 生效 DDP/DDU:商品 ?? 店铺 ?? null(纯函数;product/store 值由调用方各自的 DB seam 取好传入 —— 消费方是 async seam 路由,不持 sync db)。 */
+export function effectiveImportDutyTerms(productVal, storeVal) {
+    const norm = (x) => (x === 'ddu' || x === 'ddp') ? x : null;
+    return norm(productVal) ?? norm(storeVal);
+}
+/** 生效税费科目:商品 ?? 店铺 ?? null。 */
+export function effectiveTaxLines(productVal, storeVal) {
+    const own = parseTaxLines(productVal);
+    if (own && own.length)
+        return own;
+    const st = parseTaxLines(storeVal);
+    return (st && st.length) ? st : null;
+}
+/** 按目的区筛生效税费(精确 region → '*' 兜底,合并;披露用)。 */
+export function taxLinesForRegion(lines, region) {
+    if (!lines)
+        return [];
+    const r = (region || '').toUpperCase();
+    return lines.filter(l => l.region === '*' || (r && l.region === r));
+}