@seasonkoh/webaz 0.1.0

package/README.md

@@ -0,0 +1,189 @@
+# WebAZ
+
+让 AI Agent 成为去中心化商业协议的原生参与者。卖家零额外工作量接入新渠道，买家通过 Agent 自动购物，人类与 AI 在同一协议上平等参与。
+
+---
+
+## 核心特性
+
+- **Agent 原生**：通过 MCP 协议让 Claude 直接搜索商品、下单、确认收货
+- **人类 + Agent 双轨**：PWA 供人类操作，MCP 供 Agent 调用，共用同一后端
+- **自动执法**：每笔交易有明确责任方，超时未履行自动判责，无需人工干预
+- **争议系统**：买卖双方举证，仲裁员裁定，败诉方缴纳 1% 仲裁费
+- **声誉体系**：5 级制（新手→传奇），影响质押折扣和搜索排名
+- **Skill 市场**：卖家发布 auto_accept / catalog_sync 等能力插件，Agent 订阅后自动享用
+- **货币单位**：WAZ（Phase 0 为模拟代币，Phase 2 接入链上稳定币）
+
+---
+
+## 快速开始
+
+### 方式一：Claude MCP 接入（Agent 原生体验）
+
+**1. 克隆并安装**
+
+```bash
+git clone <repo-url> webaz
+cd webaz
+npm install
+```
+
+**2. 添加到 Claude Desktop 配置**
+
+编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：
+
+```json
+{
+  "mcpServers": {
+    "webaz": {
+      "command": "npx",
+      "args": ["tsx", "/your/path/to/webaz/src/mcp.ts"]
+    }
+  }
+}
+```
+
+重启 Claude Desktop。
+
+**3. 开始使用**
+
+在 Claude 对话里说：
+
+> "帮我在 WebAZ 注册一个买家账号，然后搜索一下有什么商品"
+
+Claude 会自动调用 `webaz_register` 和 `webaz_search` 完成操作。
+
+---
+
+### 方式二：PWA 浏览器界面
+
+```bash
+cd webaz
+npm run pwa
+# 打开 http://localhost:3000
+# 手机访问：http://<本机IP>:3000
+```
+
+注册账号后即可使用完整功能。
+
+---
+
+## MCP 工具清单
+
+| 工具 | 说明 | 主要参数 |
+|------|------|----------|
+| `webaz_info` | 获取协议概览和实时统计 | — |
+| `webaz_register` | 注册账号，获取 api_key | `name`, `role` |
+| `webaz_search` | 搜索商品（按声誉权重排序） | `query`, `category`, `max_price` |
+| `webaz_list_product` | 卖家上架商品 | `title`, `price`, `stock`, `api_key` |
+| `webaz_place_order` | 买家下单 | `product_id`, `shipping_address`, `api_key` |
+| `webaz_update_order` | 更新订单状态（接单/发货/确认/争议） | `order_id`, `action`, `api_key` |
+| `webaz_get_status` | 查询订单/钱包/争议详情 | `order_id` / `wallet` / `dispute_id`, `api_key` |
+| `webaz_wallet` | 查看钱包余额 | `api_key` |
+| `webaz_notifications` | 查询未读通知 | `api_key` |
+| `webaz_dispute` | 争议操作（查看/举证/裁定） | `action`, `api_key` |
+| `webaz_skill` | Skill 市场（发布/订阅） | `action`, `api_key` |
+
+完整协议规范（状态机/经济模型/争议规则）可通过 MCP Resource 读取：
+
+```
+webaz://protocol/manifest
+```
+
+---
+
+## 角色说明
+
+| 角色 | 可以是人类或 Agent | 职责 |
+|------|-------------------|------|
+| `buyer` 买家 | ✅ 两者均可 | 浏览商品、下单、确认收货或发起争议 |
+| `seller` 卖家 | ✅ 两者均可 | 上架商品、接单、发货，可发布 Skill |
+| `logistics` 物流 | ✅ 两者均可 | 揽收、运输、投递，回传快递单号 |
+| `arbitrator` 仲裁员 | ✅ 两者均可 | 审查争议证据、做出裁定 |
+
+---
+
+## 交易流程
+
+```
+买家下单（paid）
+  → 卖家接单（accepted）      ← 超时 24h：fault_seller
+  → 卖家发货（shipped）       ← 超时 72h：fault_seller（需选择物流公司）
+  → 物流揽收（picked_up）     ← 超时 48h：fault_logistics（回传快递单号）
+  → 运输中（in_transit）
+  → 投递完成（delivered）     ← 超时 48h：fault_logistics
+  → 买家确认（confirmed）     ← 超时 72h：自动确认
+  → 完成结算（completed）
+
+买家在 delivered 阶段可发起争议：
+  → 被告 48h 内举证 → 仲裁员 120h 内裁定
+  → 超时不回应：自动判发起方胜诉
+  → 败诉方缴纳订单金额 1% 仲裁费（最低 1 WAZ）
+  → 裁定结果：全额退款 / 释放给卖家 / 部分退款 / 责任分配
+```
+
+---
+
+## 资金分配
+
+每笔成交按以下比例自动分配：
+
+| 接收方 | 比例 |
+|--------|------|
+| 卖家 | ~93%（扣除各项费用后） |
+| 物流方 | 5% |
+| 协议费 | 2% |
+| 推荐人（如有） | 3% |
+
+卖家上架需质押 15% 作为保证金（声誉越高折扣越大，最低 5%）。
+
+---
+
+## 开发命令
+
+```bash
+npm run pwa          # 启动 WebAZ 服务（含自动执法，端口 3000）
+npm run mcp          # 单独启动 MCP Server（供 Claude Desktop 调用）
+npm run demo         # 跑完整交易演示脚本
+npm run test-dispute # 测试争议系统（三场景）
+npm run test-skill   # 测试 Skill 市场
+npm run test-rep     # 测试声誉系统
+npm run test-manifest# 测试协议 Manifest
+```
+
+---
+
+## 技术栈
+
+| 方向 | 选择 |
+|------|------|
+| 运行时 | Node.js + TypeScript |
+| Agent 接口 | MCP (Model Context Protocol) |
+| 数据库 | SQLite（Phase 0），PostgreSQL（Phase 1+） |
+| 前端 | PWA — 手机浏览器直接访问，无需安装 |
+| 链（Phase 2） | 待定：Base / Optimism |
+
+---
+
+## 当前阶段
+
+**Phase 0 · 概念验证** ✅ 完成
+**Phase 1 · 功能完善** ✅ 完成
+
+Phase 2 将把核心资金和状态上链，实现真正的去中心化。
+
+---
+
+## 路线图
+
+- [x] 状态机 + 责任归因引擎
+- [x] MCP Server（11 个工具）
+- [x] 通知系统（SSE 实时推送）
+- [x] 争议系统（举证 + 超时自动裁定 + 仲裁费）
+- [x] 声誉积分体系
+- [x] Skill 市场
+- [x] Protocol Manifest（机器可读协议规范）
+- [x] PWA 前端（全角色覆盖，人类 + Agent 双轨）
+- [ ] 链上集成（Base/Optimism）
+- [ ] IPFS 证据存储
+- [ ] 治理 DAO

package/dist/cron-enforcement.js

@@ -0,0 +1,83 @@
+/**
+ * DCP 协议自动执法进程
+ *
+ * 每 5 分钟扫描一次：
+ * 1. 订单超时判责（checkTimeouts）
+ * 2. 争议超时自动裁定（checkDisputeTimeouts）
+ *
+ * 运行方式：npm run enforcement
+ * 生产环境建议用 pm2 或 systemd 守护进程保活
+ */
+import { initDatabase } from './layer0-foundation/L0-1-database/schema.js';
+import { initSystemUser, checkTimeouts } from './layer0-foundation/L0-2-state-machine/engine.js';
+import { initDisputeSchema, checkDisputeTimeouts } from './layer3-trust/L3-1-dispute-engine/dispute-engine.js';
+import { initReputationSchema, recordViolationReputation, recordDisputeReputation } from './layer4-economics/L4-3-reputation/reputation-engine.js';
+const INTERVAL_MS = 5 * 60 * 1000; // 5 分钟
+const db = initDatabase();
+initSystemUser(db);
+initDisputeSchema(db);
+initReputationSchema(db);
+function timestamp() {
+    return new Date().toLocaleString('zh-CN', { hour12: false });
+}
+function line() { console.log('─'.repeat(55)); }
+async function enforce() {
+    const start = Date.now();
+    // ── 1. 订单超时判责 ───────────────────────────────────────
+    const orderResult = checkTimeouts(db);
+    // ── 2. 争议超时自动裁定 ───────────────────────────────────
+    const disputeResult = checkDisputeTimeouts(db);
+    const elapsed = Date.now() - start;
+    const totalActions = orderResult.processed + disputeResult.processed;
+    if (totalActions > 0) {
+        line();
+        console.log(`⚡ [${timestamp()}] 执法扫描 完成 (${elapsed}ms)`);
+        if (orderResult.processed > 0) {
+            console.log(`\n   📦 订单超时判责 × ${orderResult.processed}`);
+            orderResult.details.forEach(d => {
+                console.log(`      ${d.orderId}  ${d.action}`);
+                // 判责的终态：fault_seller / fault_logistics / fault_buyer
+                const faultMatch = d.action.match(/→ (fault_\w+)/);
+                if (faultMatch)
+                    recordViolationReputation(db, d.orderId, faultMatch[1]);
+            });
+        }
+        if (disputeResult.processed > 0) {
+            console.log(`\n   ⚖️  争议自动裁定 × ${disputeResult.processed}`);
+            disputeResult.details.forEach(d => {
+                console.log(`      ${d.disputeId}  ${d.action}`);
+                if (d.winnerId && d.loserId && d.orderId) {
+                    recordDisputeReputation(db, d.orderId, d.winnerId, d.loserId);
+                }
+            });
+        }
+        line();
+    }
+    else {
+        // 无动作时只打印一行心跳，保持日志整洁
+        process.stdout.write(`\r⏱  [${timestamp()}] 扫描完成，无超时事件`);
+    }
+}
+// ── 主循环 ────────────────────────────────────────────────────
+console.log('\n🦞 DCP Protocol — 自动执法进程启动');
+console.log(`   扫描间隔：${INTERVAL_MS / 1000}s`);
+console.log(`   职责：订单超时判责 + 争议超时自动裁定`);
+line();
+// 启动时立即执行一次
+enforce().catch(console.error);
+// 定期执行
+const timer = setInterval(() => {
+    enforce().catch(err => {
+        console.error(`\n❌ [${timestamp()}] 执法扫描出错：`, err.message);
+    });
+}, INTERVAL_MS);
+// 优雅退出
+process.on('SIGINT', () => {
+    clearInterval(timer);
+    console.log(`\n\n⏹  执法进程已停止`);
+    process.exit(0);
+});
+process.on('SIGTERM', () => {
+    clearInterval(timer);
+    process.exit(0);
+});

package/dist/demo-agent.js

@@ -0,0 +1,167 @@
+/**
+ * DCP Agent 交互演示
+ * 模拟两个 Agent（卖家Agent + 买家Agent）通过 MCP 工具完成一笔真实交易
+ * 这就是真实 Agent 调用时会发生的事情
+ */
+import { initDatabase, generateId } from './layer0-foundation/L0-1-database/schema.js';
+import { initSystemUser, transition, getOrderStatus } from './layer0-foundation/L0-2-state-machine/engine.js';
+const db = initDatabase();
+initSystemUser(db);
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
+function line() { console.log('─'.repeat(65)); }
+function addHours(date, hours) {
+    return new Date(date.getTime() + hours * 3_600_000).toISOString();
+}
+// 模拟 Agent 说话的感觉
+async function agentSay(role, emoji, msg) {
+    await sleep(120);
+    console.log(`\n${emoji} [${role} Agent]`);
+    console.log(`   ${msg}`);
+}
+async function toolCall(name, result) {
+    await sleep(80);
+    console.log(`   → 调用工具 ${name}`);
+    console.log(`   ← ${JSON.stringify(result, null, 0).slice(0, 120)}...`);
+}
+async function main() {
+    console.clear();
+    console.log('🦞 DCP Protocol — Agent 交互演示');
+    console.log('   两个 Agent 自动完成一笔真实去中心化交易');
+    line();
+    // ── STEP 1: 卖家 Agent 注册 ───────────────────────────────────
+    await agentSay('卖家', '🏪', '我要在 DCP 协议上开店，先注册一个卖家账号');
+    const sellerId = generateId('usr');
+    const sellerKey = generateId('key');
+    db.prepare('INSERT INTO users (id, name, role, api_key) VALUES (?, ?, ?, ?)').run(sellerId, '竹韵手工坊', 'seller', sellerKey);
+    db.prepare('INSERT INTO wallets (user_id, balance) VALUES (?, 500)').run(sellerId);
+    await toolCall('dcp_register', { name: '竹韵手工坊', role: 'seller' });
+    console.log(`   ✅ 注册成功！api_key 已保存`);
+    // ── STEP 2: 卖家 Agent 上架商品 ────────────────────────────────
+    await agentSay('卖家', '🏪', '把我的拳头产品上架，定价 168 DCP，自动质押 15% 保证金');
+    const productId = generateId('prd');
+    const price = 168;
+    const stake = Math.round(price * 0.15 * 100) / 100;
+    db.prepare('INSERT INTO products (id, seller_id, title, description, price, stock, category, stake_amount) VALUES (?,?,?,?,?,?,?,?)')
+        .run(productId, sellerId, '竹编茶叶罐（250g装）', '云南手工竹编，密封保鲜，适合储存普洱、岩茶', price, 10, '茶具', stake);
+    db.prepare('UPDATE wallets SET balance = balance - ?, staked = staked + ? WHERE user_id = ?').run(stake, stake, sellerId);
+    await toolCall('dcp_list_product', { title: '竹编茶叶罐', price: 168, stock: 10 });
+    console.log(`   ✅ 商品已上架！质押 ${stake} DCP，买家现在可以搜索到`);
+    line();
+    // ── STEP 3: 买家 Agent 注册 ────────────────────────────────────
+    await agentSay('买家', '🛒', '帮我注册买家身份，我想买点好茶具');
+    const buyerId = generateId('usr');
+    const buyerKey = generateId('key');
+    db.prepare('INSERT INTO users (id, name, role, api_key) VALUES (?, ?, ?, ?)').run(buyerId, '陈先生', 'buyer', buyerKey);
+    db.prepare('INSERT INTO wallets (user_id, balance) VALUES (?, 1000)').run(buyerId);
+    await toolCall('dcp_register', { name: '陈先生', role: 'buyer' });
+    console.log(`   ✅ 注册成功！初始余额 1000 DCP`);
+    // ── STEP 4: 买家 Agent 搜索 ────────────────────────────────────
+    await agentSay('买家', '🛒', '帮我搜索一下茶具，预算 200 以内');
+    const results = db.prepare(`
+    SELECT p.*, u.name as seller_name FROM products p
+    JOIN users u ON p.seller_id = u.id
+    WHERE p.status = 'active' AND (p.title LIKE '%茶%' OR p.category = '茶具') AND p.price <= 200
+  `).all();
+    await toolCall('dcp_search', { query: '茶具', max_price: 200 });
+    console.log(`   ← 找到 ${results.length} 件商品：`);
+    results.forEach(p => console.log(`      · ${p.title}  ¥${p.price} DCP  卖家：${p.seller_name}`));
+    // ── STEP 5: 买家 Agent 下单 ────────────────────────────────────
+    await agentSay('买家', '🛒', `好！买这个竹编茶叶罐，地址是上海市静安区南京西路×号`);
+    const orderId = generateId('ord');
+    const now = new Date();
+    db.prepare(`
+    INSERT INTO orders (id, product_id, buyer_id, seller_id,
+      quantity, unit_price, total_amount, escrow_amount, status,
+      shipping_address, pay_deadline, accept_deadline, ship_deadline,
+      pickup_deadline, delivery_deadline, confirm_deadline)
+    VALUES (?, ?, ?, ?, 1, ?, ?, ?, 'created', '上海市静安区南京西路×号', ?, ?, ?, ?, ?, ?)
+  `).run(orderId, productId, buyerId, sellerId, price, price, price, addHours(now, 24), addHours(now, 48), addHours(now, 120), addHours(now, 168), addHours(now, 336), addHours(now, 408));
+    db.prepare('UPDATE wallets SET balance = balance - ?, escrowed = escrowed + ? WHERE user_id = ?').run(price, price, buyerId);
+    db.prepare('UPDATE products SET stock = stock - 1 WHERE id = ?').run(productId);
+    transition(db, orderId, 'paid', buyerId, [], '买家付款，资金托管');
+    await toolCall('dcp_place_order', { product_id: productId, shipping_address: '上海市...' });
+    console.log(`   ✅ 订单创建！${price} DCP 已托管`);
+    console.log(`   ℹ️  卖家需在 24h 内接单，否则自动退款`);
+    line();
+    // ── STEP 6: 卖家 Agent 收到通知，接单 ─────────────────────────
+    await agentSay('卖家', '🏪', '收到新订单通知！确认接单，3天内安排发货');
+    transition(db, orderId, 'accepted', sellerId, [], '确认接单，备货中');
+    await toolCall('dcp_update_order', { action: 'accept', order_id: orderId });
+    console.log(`   ✅ 接单成功！协议记录：卖家已承诺履约`);
+    // ── STEP 7: 卖家 Agent 发货 ────────────────────────────────────
+    await agentSay('卖家', '🏪', '商品已打包，交给顺丰，单号 SF1234567890，上传发货凭证');
+    const evtShip = generateId('evt');
+    db.prepare('INSERT INTO evidence (id, order_id, uploader_id, type, description, file_hash) VALUES (?,?,?,?,?,?)')
+        .run(evtShip, orderId, sellerId, 'photo', '包裹照片+快递单SF1234567890', 'sha256_ship_abc');
+    transition(db, orderId, 'shipped', sellerId, [evtShip], '顺丰SF1234567890');
+    await toolCall('dcp_update_order', { action: 'ship', evidence_description: '顺丰单号+包裹照片' });
+    console.log(`   ✅ 发货证明已上链！哈希：sha256_ship_abc`);
+    // ── STEP 8: 物流 Agent 揽收 ────────────────────────────────────
+    const logisticsId = generateId('usr');
+    db.prepare('INSERT INTO users (id, name, role, api_key) VALUES (?,?,?,?)').run(logisticsId, '顺丰小哥李明', 'logistics', generateId('key'));
+    db.prepare('INSERT INTO wallets (user_id, balance) VALUES (?, 0)').run(logisticsId);
+    db.prepare('UPDATE orders SET logistics_id = ? WHERE id = ?').run(logisticsId, orderId);
+    await agentSay('物流', '🚚', '已揽收包裹，上传GPS坐标和扫描记录');
+    const evtPickup = generateId('evt');
+    db.prepare('INSERT INTO evidence (id, order_id, uploader_id, type, description, metadata) VALUES (?,?,?,?,?,?)')
+        .run(evtPickup, orderId, logisticsId, 'gps', '揽收扫描确认', '{"lat":31.22,"lng":121.48,"timestamp":"2026-05-11T10:30:00Z"}');
+    transition(db, orderId, 'picked_up', logisticsId, [evtPickup], '包裹完好，已揽收');
+    transition(db, orderId, 'in_transit', logisticsId, [], '已发往上海转运中心');
+    await toolCall('dcp_update_order', { action: 'pickup', evidence_description: 'GPS+扫描记录' });
+    console.log(`   ✅ 揽收证明已记录，开始运输`);
+    // ── STEP 9: 物流 Agent 投递 ────────────────────────────────────
+    await agentSay('物流', '🚚', '已送达，拍门口照片，收件人已签收');
+    const evtDeliver = generateId('evt');
+    db.prepare('INSERT INTO evidence (id, order_id, uploader_id, type, description, file_hash) VALUES (?,?,?,?,?,?)')
+        .run(evtDeliver, orderId, logisticsId, 'photo', '投递照片（含门牌）+签收记录', 'sha256_deliver_xyz');
+    transition(db, orderId, 'delivered', logisticsId, [evtDeliver], '本人签收，已完成投递');
+    await toolCall('dcp_update_order', { action: 'deliver', evidence_description: '投递照片+签收' });
+    console.log(`   ✅ 投递证明已记录！买家 72h 内确认，否则自动确认`);
+    line();
+    // ── STEP 10: 买家 Agent 确认 ───────────────────────────────────
+    await agentSay('买家', '🛒', '收到了！茶叶罐做工很好，确认收货');
+    transition(db, orderId, 'confirmed', buyerId, [], '商品完好，非常满意！');
+    // 自动结算
+    const sysUser = db.prepare("SELECT id FROM users WHERE id = 'sys_protocol'").get();
+    transition(db, orderId, 'completed', sysUser.id, [], '系统自动结算');
+    const protocolFee = Math.round(price * 0.02 * 100) / 100;
+    const logisticsFee = Math.round(price * 0.05 * 100) / 100;
+    const sellerAmount = price - protocolFee - logisticsFee;
+    db.prepare('UPDATE wallets SET escrowed = escrowed - ? WHERE user_id = ?').run(price, buyerId);
+    db.prepare('UPDATE wallets SET balance = balance + ?, earned = earned + ? WHERE user_id = ?').run(sellerAmount, sellerAmount, sellerId);
+    db.prepare('UPDATE wallets SET balance = balance + ?, earned = earned + ? WHERE user_id = ?').run(logisticsFee, logisticsFee, logisticsId);
+    db.prepare('UPDATE wallets SET staked = staked - ?, balance = balance + ? WHERE user_id = ?').run(stake, stake, sellerId);
+    await toolCall('dcp_update_order', { action: 'confirm' });
+    console.log(`   ✅ 确认收货！资金自动结算中...`);
+    // ── 最终报告 ────────────────────────────────────────────────────
+    line();
+    await agentSay('协议系统', '🦞', '交易完成！以下是完整结算报告');
+    const statusInfo = getOrderStatus(db, orderId);
+    console.log(`\n   📋 订单 ${orderId}`);
+    console.log(`   状态：${statusInfo.order.status}（已完成）\n`);
+    console.log(`   💰 资金分配（总额 ${price} DCP）：`);
+    const sellerW = db.prepare('SELECT * FROM wallets WHERE user_id = ?').get(sellerId);
+    const logW = db.prepare('SELECT * FROM wallets WHERE user_id = ?').get(logisticsId);
+    const buyerW = db.prepare('SELECT * FROM wallets WHERE user_id = ?').get(buyerId);
+    console.log(`      卖家（竹韵手工坊）：+${sellerAmount} DCP (${((sellerAmount / price) * 100).toFixed(0)}%)  总余额：${sellerW.balance.toFixed(2)}`);
+    console.log(`      物流（顺丰小哥）：  +${logisticsFee} DCP (5%)   总余额：${logW.balance.toFixed(2)}`);
+    console.log(`      协议费：           -${protocolFee} DCP (2%)`);
+    console.log(`      买家（陈先生）：   -${price} DCP         总余额：${buyerW.balance.toFixed(2)}`);
+    console.log(`\n   📜 完整状态历史（每步都有链上记录）：`);
+    for (const h of statusInfo.history) {
+        const evtCount = JSON.parse(h.evidence_ids || '[]').length;
+        const evtTag = evtCount > 0 ? ` 📎 ${evtCount}份证据` : '';
+        console.log(`      ${String(h.from_status).padEnd(12)} → ${String(h.to_status).padEnd(12)} ${String(h.actor_name)}${evtTag}`);
+    }
+    line();
+    console.log('\n🎉 这就是 DCP 协议的第一笔真实交易！');
+    console.log();
+    console.log('   用户做了什么：告诉 Agent「买这个」「确认收货」');
+    console.log('   Agent 做了什么：处理所有协议交互、证据上传、状态流转');
+    console.log('   协议做了什么：自动托管资金、验证每步合法性、自动结算分成');
+    console.log();
+    console.log('   如果任何一方违约（超时/货不对版）：');
+    console.log('   协议自动判责 → 自动执行处置 → 不需要任何人工干预');
+    line();
+}
+main().catch(console.error);

package/dist/index.js

@@ -0,0 +1,182 @@
+/**
+ * DCP 启动入口 & 模块测试
+ */
+import { initDatabase, generateId } from './layer0-foundation/L0-1-database/schema.js';
+import { transition, checkTimeouts, getOrderStatus, initSystemUser } from './layer0-foundation/L0-2-state-machine/engine.js';
+console.log('🦞 DCP — Decentralized Commerce Protocol');
+console.log('─'.repeat(50));
+const db = initDatabase();
+const sysUser = initSystemUser(db); // 确保系统用户存在
+// ─── 测试 L0-2：完整交易状态机流转 ───────────────────────────
+console.log('\n📋 测试 L0-2 状态机引擎\n');
+// 1. 创建测试角色
+const buyer = createUser(db, '张三', 'buyer', 500);
+const seller = createUser(db, '李四店铺', 'seller', 200);
+const logistic = createUser(db, '顺丰速运', 'logistics', 300);
+// 2. 上架商品
+const productId = generateId('prd');
+db.prepare(`
+  INSERT INTO products (id, seller_id, title, description, price, stake_amount)
+  VALUES (?, ?, ?, ?, ?, ?)
+`).run(productId, seller.id, '手工皮质钱包', '意大利头层牛皮，手工缝制', 288, 50);
+// 3. 创建订单
+const orderId = generateId('ord');
+const now = new Date();
+db.prepare(`
+  INSERT INTO orders (
+    id, product_id, buyer_id, seller_id,
+    quantity, unit_price, total_amount, escrow_amount,
+    status,
+    pay_deadline, accept_deadline, ship_deadline,
+    pickup_deadline, delivery_deadline, confirm_deadline
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?,  ?, ?, ?, ?, ?, ?)
+`).run(orderId, productId, buyer.id, seller.id, 1, 288, 288, 288, 'created', addHours(now, 24), // 24h 内付款
+addHours(now, 48), // 付款后 24h 内接单
+addHours(now, 120), // 接单后 72h 内发货
+addHours(now, 168), // 发货后 48h 内揽收
+addHours(now, 336), // 揽收后 7天内投递
+addHours(now, 408));
+console.log(`✅ 订单创建：${orderId}`);
+console.log(`   商品：手工皮质钱包 ¥288`);
+console.log(`   买家：${buyer.name}  →  卖家：${seller.name}\n`);
+// ─── 跑一遍完整的正常流程 ──────────────────────────────────────
+const steps = [
+    {
+        desc: '💳 买家付款',
+        fn: () => transition(db, orderId, 'paid', buyer.id, [], '微信支付 ¥288')
+    },
+    {
+        desc: '✅ 卖家接单',
+        fn: () => transition(db, orderId, 'accepted', seller.id, [], '确认接单，3天内发货')
+    },
+    {
+        desc: '📦 卖家发货（需要证据）',
+        fn: () => {
+            // 先创建一条证据记录
+            const evidenceId = generateId('evt');
+            db.prepare(`
+        INSERT INTO evidence (id, order_id, uploader_id, type, description, file_hash)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `).run(evidenceId, orderId, seller.id, 'photo', '包裹外观照片+快递单', 'sha256_mock_abc123');
+            return transition(db, orderId, 'shipped', seller.id, [evidenceId], '顺丰 SF1234567890');
+        }
+    },
+    {
+        desc: '🚚 物流揽收（需要证据）',
+        fn: () => {
+            const evidenceId = generateId('evt');
+            db.prepare(`
+        INSERT INTO evidence (id, order_id, uploader_id, type, description, metadata)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `).run(evidenceId, orderId, logistic.id, 'gps', '揽收GPS坐标', '{"lat":31.23,"lng":121.47}');
+            return transition(db, orderId, 'picked_up', logistic.id, [evidenceId], '已揽收，包裹完好');
+        }
+    },
+    {
+        desc: '🚛 开始运输',
+        fn: () => transition(db, orderId, 'in_transit', logistic.id, [], '已发往上海转运中心')
+    },
+    {
+        desc: '📬 物流投递（需要证据）',
+        fn: () => {
+            const evidenceId = generateId('evt');
+            db.prepare(`
+        INSERT INTO evidence (id, order_id, uploader_id, type, description, file_hash)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `).run(evidenceId, orderId, logistic.id, 'photo', '投递照片（含门牌号）', 'sha256_delivery_xyz789');
+            return transition(db, orderId, 'delivered', logistic.id, [evidenceId], '已放前台，收件人已签收');
+        }
+    },
+    {
+        desc: '✅ 买家确认收货',
+        fn: () => transition(db, orderId, 'confirmed', buyer.id, [], '商品完好，非常满意')
+    },
+    {
+        desc: '💰 系统自动结算',
+        fn: () => transition(db, orderId, 'completed', sysUser.id, [], '交易完成，资金自动分配')
+    },
+];
+let allPassed = true;
+for (const step of steps) {
+    const result = step.fn();
+    if (result.success) {
+        console.log(`  ${step.desc}`);
+        console.log(`     状态 → ${result.newStatus}  [hist: ${result.historyId}]`);
+    }
+    else {
+        console.log(`  ❌ ${step.desc} 失败：${result.error}`);
+        allPassed = false;
+    }
+}
+// ─── 测试「拒绝非法操作」──────────────────────────────────────
+console.log('\n🚫 测试非法操作（应该全部被拒绝）\n');
+const illegalTests = [
+    {
+        desc: '物流方尝试取消买家的订单',
+        fn: () => transition(db, orderId, 'cancelled', logistic.id)
+    },
+    {
+        desc: '买家尝试直接跳到 completed',
+        fn: () => transition(db, orderId, 'completed', buyer.id)
+    },
+    {
+        desc: '卖家尝试把 completed 改回 paid',
+        fn: () => transition(db, orderId, 'paid', seller.id)
+    },
+];
+for (const test of illegalTests) {
+    const result = test.fn();
+    if (!result.success) {
+        console.log(`  ✅ 正确拒绝：${test.desc}`);
+        console.log(`     原因：${result.error}`);
+    }
+    else {
+        console.log(`  ❌ 漏洞！非法操作被允许了：${test.desc}`);
+        allPassed = false;
+    }
+}
+// ─── 查看完整状态历史 ─────────────────────────────────────────
+console.log('\n📜 订单完整状态历史\n');
+const status = getOrderStatus(db, orderId);
+for (const h of status.history) {
+    console.log(`  ${h.from_status.padEnd(12)} → ${h.to_status.padEnd(12)} | ${h.actor_name}（${h.actor_role_name}）`);
+}
+// ─── 测试超时判责 ─────────────────────────────────────────────
+console.log('\n⏰ 测试超时自动判责\n');
+const orderId2 = generateId('ord');
+db.prepare(`
+  INSERT INTO orders (
+    id, product_id, buyer_id, seller_id,
+    quantity, unit_price, total_amount, escrow_amount, status,
+    pay_deadline, accept_deadline, ship_deadline, pickup_deadline, delivery_deadline, confirm_deadline
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+`).run(orderId2, productId, buyer.id, seller.id, 1, 288, 288, 288, 'paid', addHours(now, -48), // 所有截止时间都已过
+addHours(now, -24), // 卖家接单截止时间已过！
+addHours(now, -1), addHours(now, -1), addHours(now, -1), addHours(now, -1));
+console.log(`  模拟场景：卖家超时未接单（截止时间已过 24 小时）`);
+const timeoutResult = checkTimeouts(db);
+console.log(`  处理了 ${timeoutResult.processed} 个超时订单`);
+for (const d of timeoutResult.details) {
+    console.log(`  ✅ ${d.orderId}：${d.action}`);
+}
+// ─── 最终结论 ─────────────────────────────────────────────────
+console.log('\n' + '─'.repeat(50));
+if (allPassed) {
+    console.log('✅ L0-1 数据库：正常');
+    console.log('✅ L0-2 状态机：正常（完整流程 + 非法拦截 + 超时判责）');
+}
+else {
+    console.log('❌ 部分测试未通过，请检查上方输出');
+}
+console.log('─'.repeat(50));
+// ─── 工具函数 ─────────────────────────────────────────────────
+function createUser(db, name, role, balance) {
+    const id = generateId('usr');
+    const apiKey = generateId('key');
+    db.prepare(`INSERT INTO users (id, name, role, api_key) VALUES (?, ?, ?, ?)`).run(id, name, role, apiKey);
+    db.prepare(`INSERT INTO wallets (user_id, balance) VALUES (?, ?)`).run(id, balance);
+    return { id, name, role, apiKey };
+}
+function addHours(date, hours) {
+    return new Date(date.getTime() + hours * 3_600_000).toISOString();
+}