@seasonkoh/webaz 0.1.0

package/dist/layer0-foundation/L0-1-database/schema.js

@@ -0,0 +1,179 @@
+/**
+ * L0-1 · 数据库 Schema
+ * 所有表结构定义。协议里每个角色、每笔交易、每个状态都存在这里。
+ */
+import Database from 'better-sqlite3';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DB_PATH = path.join(__dirname, '../../../webaz.db');
+export function initDatabase() {
+    const db = new Database(DB_PATH);
+    db.pragma('journal_mode = WAL'); // 更好的并发性能
+    db.pragma('foreign_keys = ON'); // 强制外键约束
+    db.exec(`
+
+    /* ──────────────────────────────────────────
+       用户表 · 每个参与协议的人
+    ────────────────────────────────────────── */
+    CREATE TABLE IF NOT EXISTS users (
+      id          TEXT PRIMARY KEY,          -- 唯一ID，格式：usr_xxxx
+      name        TEXT NOT NULL,
+      role        TEXT NOT NULL,             -- seller / buyer / logistics / reviewer / arbitrator / promoter
+      api_key     TEXT UNIQUE NOT NULL,      -- Agent 调用时用这个验证身份
+      stake       REAL DEFAULT 0,            -- 当前质押金额（模拟货币）
+      reputation  REAL DEFAULT 100,          -- 声誉分（满分100）
+      created_at  TEXT DEFAULT (datetime('now')),
+      updated_at  TEXT DEFAULT (datetime('now'))
+    );
+
+    /* ──────────────────────────────────────────
+       商品表 · 卖家上架的商品
+    ────────────────────────────────────────── */
+    CREATE TABLE IF NOT EXISTS products (
+      id            TEXT PRIMARY KEY,         -- 格式：prd_xxxx
+      seller_id     TEXT NOT NULL REFERENCES users(id),
+      title         TEXT NOT NULL,
+      description   TEXT NOT NULL,
+      price         REAL NOT NULL,
+      currency      TEXT DEFAULT 'DCP',       -- 协议内部模拟货币
+      stock         INTEGER DEFAULT 1,
+      category      TEXT,
+      images        TEXT DEFAULT '[]',        -- JSON 数组，存图片路径
+      stake_amount  REAL DEFAULT 0,           -- 卖家为这个商品质押的金额
+      status        TEXT DEFAULT 'active',    -- active / paused / delisted
+      created_at    TEXT DEFAULT (datetime('now')),
+      updated_at    TEXT DEFAULT (datetime('now'))
+    );
+
+    /* ──────────────────────────────────────────
+       订单表 · 一笔完整的交易
+    ────────────────────────────────────────── */
+    CREATE TABLE IF NOT EXISTS orders (
+      id              TEXT PRIMARY KEY,       -- 格式：ord_xxxx
+      product_id      TEXT NOT NULL REFERENCES products(id),
+      buyer_id        TEXT NOT NULL REFERENCES users(id),
+      seller_id       TEXT NOT NULL REFERENCES users(id),
+      logistics_id    TEXT REFERENCES users(id),   -- 接单的物流方
+      promoter_id     TEXT REFERENCES users(id),   -- 带来流量的推荐人（可为空）
+
+      quantity        INTEGER DEFAULT 1,
+      unit_price      REAL NOT NULL,
+      total_amount    REAL NOT NULL,          -- 买家支付总额
+      escrow_amount   REAL NOT NULL,          -- 托管中的金额
+
+      -- 当前状态（L0-2 状态机管理这个字段）
+      status          TEXT NOT NULL DEFAULT 'created',
+      -- 状态枚举：
+      -- created       买家下单，资金待托管
+      -- paid          资金已托管
+      -- accepted      卖家确认接单
+      -- shipped       卖家已交物流
+      -- picked_up     物流已揽收
+      -- in_transit    运输中
+      -- delivered     物流已投递
+      -- confirmed     买家确认收货 → 触发结算
+      -- disputed      争议中
+      -- completed     交易完成，资金已分配
+      -- cancelled     取消
+
+      -- 各节点截止时间（超时自动判责）
+      pay_deadline      TEXT,   -- 下单后 24h 内必须完成支付
+      accept_deadline   TEXT,   -- 支付后 24h 内卖家必须接单
+      ship_deadline     TEXT,   -- 接单后按承诺时间发货
+      pickup_deadline   TEXT,   -- 发货后 48h 内物流必须揽收
+      delivery_deadline TEXT,   -- 揽收后 X 天内必须投递
+      confirm_deadline  TEXT,   -- 投递后 72h 内买家确认（否则自动确认）
+
+      shipping_address  TEXT,   -- 收货地址（JSON）
+      notes             TEXT,   -- 买家备注
+
+      created_at  TEXT DEFAULT (datetime('now')),
+      updated_at  TEXT DEFAULT (datetime('now'))
+    );
+
+    /* ──────────────────────────────────────────
+       状态历史表 · 订单每次状态变更的完整记录
+       这是「自举证」系统的核心，任何状态变更都留档
+    ────────────────────────────────────────── */
+    CREATE TABLE IF NOT EXISTS order_state_history (
+      id           TEXT PRIMARY KEY,
+      order_id     TEXT NOT NULL REFERENCES orders(id),
+      from_status  TEXT NOT NULL,
+      to_status    TEXT NOT NULL,
+      actor_id     TEXT NOT NULL REFERENCES users(id),  -- 谁触发了这次状态变更
+      actor_role   TEXT NOT NULL,                        -- 触发者的角色
+      evidence_ids TEXT DEFAULT '[]',                    -- 本次附上的证据（JSON数组）
+      notes        TEXT,                                 -- 说明
+      created_at   TEXT DEFAULT (datetime('now'))
+    );
+
+    /* ──────────────────────────────────────────
+       证据表 · 每一份上传的证明材料
+    ────────────────────────────────────────── */
+    CREATE TABLE IF NOT EXISTS evidence (
+      id           TEXT PRIMARY KEY,           -- 格式：evt_xxxx
+      order_id     TEXT NOT NULL REFERENCES orders(id),
+      uploader_id  TEXT NOT NULL REFERENCES users(id),
+      type         TEXT NOT NULL,              -- photo / video / document / gps / signature
+      description  TEXT NOT NULL,              -- 这份证据证明什么
+      file_path    TEXT,                       -- 本地存储路径（Phase 0）
+      file_hash    TEXT,                       -- 文件内容的哈希（防篡改）
+      metadata     TEXT DEFAULT '{}',          -- 额外信息，如GPS坐标（JSON）
+      created_at   TEXT DEFAULT (datetime('now'))
+    );
+
+    /* ──────────────────────────────────────────
+       争议表 · 出现纠纷时的记录
+    ────────────────────────────────────────── */
+    CREATE TABLE IF NOT EXISTS disputes (
+      id              TEXT PRIMARY KEY,         -- 格式：dsp_xxxx
+      order_id        TEXT NOT NULL REFERENCES orders(id),
+      initiator_id    TEXT NOT NULL REFERENCES users(id),   -- 谁发起的争议
+      reason          TEXT NOT NULL,            -- 争议原因
+      stake_deposit   REAL DEFAULT 0,           -- 发起方质押的保证金（防恶意争议）
+
+      status          TEXT DEFAULT 'open',      -- open / in_review / resolved / dismissed
+      assigned_arbitrators TEXT DEFAULT '[]',   -- 分配到的仲裁员（JSON数组）
+      verdict         TEXT,                     -- 裁定结果（JSON）
+      verdict_reason  TEXT,                     -- 裁定理由
+
+      created_at      TEXT DEFAULT (datetime('now')),
+      resolved_at     TEXT
+    );
+
+    /* ──────────────────────────────────────────
+       钱包表 · 协议内的模拟资金
+    ────────────────────────────────────────── */
+    CREATE TABLE IF NOT EXISTS wallets (
+      user_id   TEXT PRIMARY KEY REFERENCES users(id),
+      balance   REAL DEFAULT 0,        -- 可用余额
+      staked    REAL DEFAULT 0,        -- 质押中（锁定不可用）
+      escrowed  REAL DEFAULT 0,        -- 托管中（交易进行时锁定）
+      earned    REAL DEFAULT 0,        -- 累计收益（统计用）
+      updated_at TEXT DEFAULT (datetime('now'))
+    );
+
+    /* ──────────────────────────────────────────
+       收益分配记录
+    ────────────────────────────────────────── */
+    CREATE TABLE IF NOT EXISTS payouts (
+      id           TEXT PRIMARY KEY,
+      order_id     TEXT NOT NULL REFERENCES orders(id),
+      recipient_id TEXT NOT NULL REFERENCES users(id),
+      role         TEXT NOT NULL,       -- 以什么角色获得这笔收益
+      amount       REAL NOT NULL,
+      reason       TEXT NOT NULL,       -- seller_share / promoter_fee / logistics_fee / etc.
+      created_at   TEXT DEFAULT (datetime('now'))
+    );
+
+  `);
+    console.log('✅ L0-1 数据库初始化完成：', DB_PATH);
+    return db;
+}
+// 生成唯一 ID 的工具函数
+export function generateId(prefix) {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).slice(2, 6);
+    return `${prefix}_${timestamp}${random}`;
+}

package/dist/layer0-foundation/L0-2-state-machine/engine.js

@@ -0,0 +1,183 @@
+/**
+ * L0-2 · 状态机引擎
+ *
+ * 三个核心职责：
+ * 1. transition()     — 执行状态转移（验证权限 + 记录历史）
+ * 2. checkTimeouts()  — 扫描超时订单，自动判责
+ * 3. getStatus()      — 查询订单当前状态和责任方
+ */
+import { generateId } from '../L0-1-database/schema.js';
+import { VALID_TRANSITIONS, CURRENT_RESPONSIBLE } from './transitions.js';
+// ─── 核心函数 ────────────────────────────────────────────────
+/**
+ * 执行状态转移
+ * @param db        数据库连接
+ * @param orderId   订单ID
+ * @param toStatus  目标状态
+ * @param actorId   操作者用户ID
+ * @param evidenceIds 附上的证据ID列表
+ * @param notes     备注说明
+ */
+export function transition(db, orderId, toStatus, actorId, evidenceIds = [], notes = '') {
+    // 1. 读取订单和操作者
+    const order = db.prepare('SELECT * FROM orders WHERE id = ?').get(orderId);
+    if (!order)
+        return { success: false, error: `订单不存在：${orderId}` };
+    const actor = db.prepare('SELECT * FROM users WHERE id = ?').get(actorId);
+    if (!actor)
+        return { success: false, error: `用户不存在：${actorId}` };
+    const fromStatus = order.status;
+    // 2. 查找合法转移规则
+    const transitionKey = `${fromStatus}→${toStatus}`;
+    const rule = VALID_TRANSITIONS[transitionKey];
+    if (!rule) {
+        return {
+            success: false,
+            error: `非法状态转移：${fromStatus} → ${toStatus}（协议不允许此操作）`
+        };
+    }
+    // 3. 验证角色权限
+    if (!rule.allowedRoles.includes(actor.role)) {
+        return {
+            success: false,
+            error: `权限不足：${actor.role} 无法执行 ${fromStatus} → ${toStatus}。` +
+                `允许的角色：${rule.allowedRoles.join(', ')}`
+        };
+    }
+    // 4. 验证证据要求
+    if (rule.requiresEvidence && evidenceIds.length === 0) {
+        return {
+            success: false,
+            error: `此操作需要上传证据。提示：${rule.evidenceHint ?? '请上传相关证明文件'}`
+        };
+    }
+    // 5. 执行转移（数据库事务，保证原子性）
+    const historyId = generateId('hist');
+    const execute = db.transaction(() => {
+        // 更新订单状态
+        db.prepare(`
+      UPDATE orders
+      SET status = ?, updated_at = datetime('now')
+      WHERE id = ?
+    `).run(toStatus, orderId);
+        // 记录状态历史（自举证的核心）
+        db.prepare(`
+      INSERT INTO order_state_history
+        (id, order_id, from_status, to_status, actor_id, actor_role, evidence_ids, notes)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(historyId, orderId, fromStatus, toStatus, actorId, actor.role, JSON.stringify(evidenceIds), notes);
+    });
+    execute();
+    return { success: true, newStatus: toStatus, historyId };
+}
+/**
+ * 扫描所有超时订单，自动判责
+ * 这个函数应该定期运行（如每分钟），是「协议自动执法」的实现
+ */
+export function checkTimeouts(db) {
+    const now = new Date().toISOString();
+    const details = [];
+    // 找出所有进行中的订单
+    const activeOrders = db.prepare(`
+    SELECT * FROM orders
+    WHERE status NOT IN ('completed', 'cancelled', 'fault_buyer', 'fault_seller', 'fault_logistics')
+  `).all();
+    for (const order of activeOrders) {
+        const transitionKey = findActiveDeadlineTransition(order, now);
+        if (!transitionKey)
+            continue;
+        const [, autoFaultState] = transitionKey;
+        const systemUser = getSystemUser(db);
+        // 系统自动触发判责状态
+        const result = transition(db, order.id, autoFaultState, systemUser.id, [], `系统自动判责：超过截止时间 ${new Date(now).toLocaleString()}`);
+        if (result.success) {
+            details.push({
+                orderId: order.id,
+                action: `${order.status} → ${autoFaultState}（超时自动判责）`
+            });
+            // 如果判责状态可以自动完成，继续执行
+            const completionKey = `${autoFaultState}→completed`;
+            if (VALID_TRANSITIONS[completionKey]) {
+                transition(db, order.id, 'completed', systemUser.id, [], '系统自动执行处置');
+            }
+        }
+    }
+    return { processed: details.length, details };
+}
+/**
+ * 查询订单的完整状态（含当前责任方、距截止时间）
+ */
+export function getOrderStatus(db, orderId) {
+    const order = db.prepare('SELECT * FROM orders WHERE id = ?').get(orderId);
+    if (!order)
+        return null;
+    const history = db.prepare(`
+    SELECT h.*, u.name as actor_name, u.role as actor_role_name
+    FROM order_state_history h
+    JOIN users u ON h.actor_id = u.id
+    WHERE h.order_id = ?
+    ORDER BY h.created_at ASC
+  `).all(orderId);
+    const currentResponsible = CURRENT_RESPONSIBLE[order.status] ?? null;
+    const activeDeadline = getActiveDeadline(order);
+    return {
+        order,
+        history,
+        currentResponsible,
+        activeDeadline,
+        isOverdue: activeDeadline ? new Date() > new Date(activeDeadline.deadline) : false
+    };
+}
+// ─── 内部工具函数 ─────────────────────────────────────────────
+/** 找出当前订单超时的转移（如果有） */
+function findActiveDeadlineTransition(order, now) {
+    // 按当前状态找对应的截止时间规则
+    const relevantRules = Object.entries(VALID_TRANSITIONS).filter(([key, rule]) => key.startsWith(`${order.status}→`) &&
+        rule.deadlineField &&
+        rule.autoFaultState);
+    for (const [, rule] of relevantRules) {
+        const deadlineField = rule.deadlineField;
+        const deadline = order[deadlineField];
+        if (deadline && now > deadline && rule.autoFaultState) {
+            return [deadlineField, rule.autoFaultState];
+        }
+    }
+    return null;
+}
+/** 获取当前有效的截止时间 */
+function getActiveDeadline(order) {
+    const deadlineMap = {
+        created: 'pay_deadline',
+        paid: 'accept_deadline',
+        accepted: 'ship_deadline',
+        shipped: 'pickup_deadline',
+        in_transit: 'delivery_deadline',
+        delivered: 'confirm_deadline',
+    };
+    const field = deadlineMap[order.status];
+    if (!field)
+        return null;
+    const deadline = order[field];
+    if (!deadline)
+        return null;
+    return { field, deadline };
+}
+/** 获取或创建系统用户（用于自动触发），启动时调用一次 */
+export function initSystemUser(db) {
+    return getSystemUser(db);
+}
+function getSystemUser(db) {
+    let sys = db.prepare("SELECT * FROM users WHERE id = 'sys_protocol'").get();
+    if (!sys) {
+        db.prepare(`
+      INSERT OR IGNORE INTO users (id, name, role, api_key)
+      VALUES ('sys_protocol', '协议系统', 'system', 'sys_internal_key')
+    `).run();
+        db.prepare(`
+      INSERT OR IGNORE INTO wallets (user_id, balance)
+      VALUES ('sys_protocol', 0)
+    `).run();
+        sys = db.prepare("SELECT * FROM users WHERE id = 'sys_protocol'").get();
+    }
+    return sys;
+}

package/dist/layer0-foundation/L0-2-state-machine/transitions.js

@@ -0,0 +1,197 @@
+/**
+ * L0-2 · 状态机：合法转移表
+ *
+ * 每一行定义：从哪个状态 → 到哪个状态，谁有权触发，需要什么证据，用哪个截止时间。
+ * 不在这张表里的转移，一律拒绝——这是「无歧义」设计的核心。
+ */
+// key 格式：'from_status→to_status'
+export const VALID_TRANSITIONS = {
+    // ── 买家付款 ──────────────────────────────────────────────
+    'created→paid': {
+        allowedRoles: ['buyer'],
+        deadlineField: 'pay_deadline',
+        requiresEvidence: false,
+        autoFaultState: 'cancelled',
+        faultParty: 'buyer',
+        description: '买家完成付款，资金进入托管'
+    },
+    'created→cancelled': {
+        allowedRoles: ['buyer', 'seller', 'system'],
+        requiresEvidence: false,
+        description: '下单后付款前取消订单'
+    },
+    // ── 卖家接单 ──────────────────────────────────────────────
+    'paid→accepted': {
+        allowedRoles: ['seller'],
+        deadlineField: 'accept_deadline',
+        requiresEvidence: false,
+        autoFaultState: 'fault_seller',
+        faultParty: 'seller',
+        description: '卖家确认接单，承诺按时发货'
+    },
+    'paid→cancelled': {
+        allowedRoles: ['buyer'],
+        requiresEvidence: false,
+        description: '卖家接单前买家可取消（全额退款）'
+    },
+    // ── 卖家发货 ──────────────────────────────────────────────
+    'accepted→shipped': {
+        allowedRoles: ['seller'],
+        deadlineField: 'ship_deadline',
+        requiresEvidence: true,
+        evidenceHint: '上传：物流单号截图 + 包裹称重/外观照片',
+        autoFaultState: 'fault_seller',
+        faultParty: 'seller',
+        description: '卖家将包裹交给物流，提交发货证明'
+    },
+    // ── 物流揽收 ──────────────────────────────────────────────
+    'shipped→picked_up': {
+        allowedRoles: ['logistics'],
+        deadlineField: 'pickup_deadline',
+        requiresEvidence: true,
+        evidenceHint: '上传：揽收扫描记录 + 当前GPS位置',
+        autoFaultState: 'fault_logistics',
+        faultParty: 'logistics',
+        description: '物流方确认已揽收，包裹完整'
+    },
+    // ── 运输中更新 ─────────────────────────────────────────────
+    'picked_up→in_transit': {
+        allowedRoles: ['logistics', 'system'],
+        requiresEvidence: false,
+        description: '包裹开始运输（可自动触发）'
+    },
+    // ── 物流投递 ──────────────────────────────────────────────
+    'in_transit→delivered': {
+        allowedRoles: ['logistics'],
+        deadlineField: 'delivery_deadline',
+        requiresEvidence: true,
+        evidenceHint: '上传：投递照片（含门牌号）+ 收件人签收/GPS坐标',
+        autoFaultState: 'fault_logistics',
+        faultParty: 'logistics',
+        description: '物流确认投递完成，提交投递证明'
+    },
+    // ── 买家确认 ──────────────────────────────────────────────
+    'delivered→confirmed': {
+        allowedRoles: ['buyer', 'system'], // system = 超时自动确认
+        deadlineField: 'confirm_deadline',
+        requiresEvidence: false,
+        autoFaultState: 'confirmed', // 超时不是判责，而是自动确认
+        faultParty: 'system',
+        description: '买家确认收货，触发资金结算'
+    },
+    // ── 发起争议（任何阶段都可触发）──────────────────────────────
+    'paid→disputed': {
+        allowedRoles: ['buyer', 'seller'],
+        requiresEvidence: true,
+        evidenceHint: '描述问题并上传相关证据',
+        description: '资金托管后发现问题，发起争议'
+    },
+    'accepted→disputed': {
+        allowedRoles: ['buyer', 'seller'],
+        requiresEvidence: true,
+        evidenceHint: '描述问题并上传相关证据',
+        description: '卖家接单后发现问题'
+    },
+    'shipped→disputed': {
+        allowedRoles: ['buyer', 'seller', 'logistics'],
+        requiresEvidence: true,
+        evidenceHint: '描述问题并上传相关证据',
+        description: '发货后出现问题'
+    },
+    'picked_up→disputed': {
+        allowedRoles: ['buyer', 'seller', 'logistics'],
+        requiresEvidence: true,
+        evidenceHint: '描述问题并上传相关证据',
+        description: '揽收后出现问题（如包裹损毁）'
+    },
+    'in_transit→disputed': {
+        allowedRoles: ['buyer', 'seller', 'logistics'],
+        requiresEvidence: true,
+        evidenceHint: '描述问题并上传相关证据',
+        description: '运输中出现问题'
+    },
+    'delivered→disputed': {
+        allowedRoles: ['buyer'],
+        requiresEvidence: true,
+        evidenceHint: '上传：收到货物的照片 + 问题描述',
+        description: '买家收货后发现货不对版或货损'
+    },
+    // ── 仲裁结束 ──────────────────────────────────────────────
+    'disputed→completed': {
+        allowedRoles: ['arbitrator', 'system'], // system = 超时自动裁定
+        requiresEvidence: false,
+        evidenceHint: '上传仲裁裁定书',
+        description: '仲裁员完成裁定，释放资金给卖家'
+    },
+    'disputed→cancelled': {
+        allowedRoles: ['arbitrator', 'system'], // system = 超时自动裁定
+        requiresEvidence: false,
+        evidenceHint: '上传仲裁裁定书',
+        description: '仲裁裁定取消交易，全额退款给买家'
+    },
+    // ── 正常完成 ──────────────────────────────────────────────
+    'confirmed→completed': {
+        allowedRoles: ['system'],
+        requiresEvidence: false,
+        description: '买家确认后系统自动结算，交易完成'
+    },
+    // ── 超时自动判责转移（system 触发）────────────────────────────
+    // 这些转移不在正常操作流程里，只由 checkTimeouts 自动触发
+    'created→fault_buyer': {
+        allowedRoles: ['system'],
+        requiresEvidence: false,
+        description: '买家超时未付款，自动取消并标记违约'
+    },
+    'paid→fault_seller': {
+        allowedRoles: ['system'],
+        requiresEvidence: false,
+        description: '卖家超时未接单，自动退款并标记违约'
+    },
+    'accepted→fault_seller': {
+        allowedRoles: ['system'],
+        requiresEvidence: false,
+        description: '卖家超时未发货，自动退款并标记违约'
+    },
+    'shipped→fault_logistics': {
+        allowedRoles: ['system'],
+        requiresEvidence: false,
+        description: '物流超时未揽收，标记物流违约'
+    },
+    'picked_up→fault_logistics': {
+        allowedRoles: ['system'],
+        requiresEvidence: false,
+        description: '物流超时未投递，标记物流违约'
+    },
+    'in_transit→fault_logistics': {
+        allowedRoles: ['system'],
+        requiresEvidence: false,
+        description: '物流超时未投递，标记物流违约'
+    },
+    // ── 判责后的处置结算 ─────────────────────────────────────────
+    'fault_seller→completed': {
+        allowedRoles: ['system'],
+        requiresEvidence: false,
+        description: '卖家违约：退款买家，扣除卖家质押'
+    },
+    'fault_logistics→completed': {
+        allowedRoles: ['system'],
+        requiresEvidence: false,
+        description: '物流违约：从物流质押池赔付'
+    },
+    'fault_buyer→completed': {
+        allowedRoles: ['system'],
+        requiresEvidence: false,
+        description: '买家违约：资金转给卖家，扣除买家质押'
+    },
+};
+/** 给定当前状态，返回「当前应该由谁来操作」 */
+export const CURRENT_RESPONSIBLE = {
+    created: 'buyer', // 等买家付款
+    paid: 'seller', // 等卖家接单
+    accepted: 'seller', // 等卖家发货
+    shipped: 'logistics', // 等物流揽收
+    picked_up: 'logistics', // 等物流投递
+    in_transit: 'logistics', // 等物流投递
+    delivered: 'buyer', // 等买家确认
+    disputed: 'arbitrator', // 等仲裁处理
+};