h-builds/eco-trace

# 🌿 Eco Trace — 企业级验证架构演示    ## 什么是 Eco Trace？ Eco Trace 是一个**协作式的企业级验证架构演示**，它将供应链的可持续发展声明转化为经过加密验证且随时可审计的产品历史记录。 它展示了现代工程团队如何设计跨分布式供应链参与者的、值得信赖且可审计的工作流。这些工作流使用了特定角色的界面、加密验证、边缘原生持久化、确定性的碳足迹逻辑、合规性报告、共享的设计系统以及协作式的多应用架构。 ### Eco Trace 是什么 - 一个达到作品集级别的架构演示。 - 一个双应用生态系统：**Admin Workstation** (React 19) + **Consumer Verification App** (Vue 3.5 Vapor)。 - 一份在前端、边缘计算、密码学、治理和 UX 方面展现工程判断力的证明。 - 一个对招聘人员友好的技术案例研究。 ### Eco Trace 不是什么 - 不是一家生产级的 ESG 合规公司。 - 不是一个区块链项目。 - 不是一个 SaaS 计费产品。 - 不是一个 AI 包装器。 - 不是对真实的 ISO 认证、真实客户或真实企业级部署的声明。 ## 为什么要有两个应用？ Eco Trace 拥有两个独立的应用程序，因为它展示了两种不同的企业级业务面： | 业务面 | 应用 | 技术 | 目的 | |---------|-----|-----------|---------| | 内部审计员 | Admin Workstation | React 19, Server Components, Next.js Edge | 治理、RBAC、参与者/资产控制、完整性违规、合规性导出 | | 外部消费者 | Consumer Verification | Vue 3.5 Vapor, Vite | 基于 QR 的验证、只读透明度、移动优先的信任建立 | | 共享信任层 | Go/Wasm 引擎 | Go 1.22+, WebAssembly | 确定性计算、Ed25519 签名/验证，由两个应用共享 | ## 系统架构 ``` graph TD subgraph Edge Network [Cloudflare Global Network] API[Next.js Edge API Handlers] DB[(Cloudflare D1 SQLite)] end subgraph User Interfaces Admin[React 19 Admin Dashboard] Consumer[Vue 3.5 Consumer App] end subgraph Cryptographic Engine Wasm[Go WebAssembly Wasm binary] end Admin <-->|JSON Payloads| API Consumer <-->|Read-only Audits| API API <-->|SQL Queries| DB Admin -->|In-Browser Verification| Wasm Consumer -->|In-Browser Verification| Wasm ``` ### 确定性验证流程 每个事件在持久化之前都会经过严格的 Ed25519 验证： ``` sequenceDiagram participant User as Auditor (Admin UI) participant Wasm as Go Engine (Wasm) participant API as Edge Route participant D1 as Cloudflare D1 User->>Wasm: Modifies Data (Tamper/Impersonate) Wasm-->>User: Recalculates Hash & Validates Signature alt Signature Matches & Actor is Trusted Wasm-->>User: Status: VALID else Signature Fails Wasm-->>User: Status: INVALID (Integrity Alert) else Signature Matches but Actor Untrusted Wasm-->>User: Status: UNAUTHORIZED (Identity Alert) end User->>API: POST /api/events (Includes Status & Signature) API->>D1: INSERT INTO events D1-->>User: Confirms Persistence ``` ## 已实现的功能 ### 管理后台工作站 (React 19) - 具备 Edge 兼容 session token (Cloudflare Workers KV) 的审计员登录流程。 - RBAC 角色：`ADMIN`、`AUDITOR`、`VIEWER`，通过中间件强制实施路由保护。 - 对所有身份验证事件进行审计日志记录。 - `/dashboard/overview` — 使用 React Server Components、Suspense 流式传输和时间范围过滤器的宏观分析。 - `/dashboard/entities` — 受信任参与者引导、资产注册、搜索和分页。 - `/dashboard/events` — 按 `event_id` 分组的线索式审计追踪、基于 Wasm 的完整性验证、防篡改/防冒充测试。 - `/dashboard/compliance` — 具备日期范围和参与者过滤条件的 PDF 和 CSV 合规性导出，包含不可变的已验证值。 ### Consumer 验证 App (Vue 3.5 Vapor) - Vue 3.5 + Vite，采用面向 Vapor 模式的渲染。 - 只读的 Wasm 桥接：`VerifySignature` + `CalculateCarbonFootprint`。 - 原生 QR 扫描器，具备摄像头权限处理。 - 产品透明度视图：真实性徽章、碳排放公式、审计追踪时间线。 - 使用类型化 API 客户端的 SWR 风格事件注水。 - 工业编辑风格落地页（Precision Blueprint 设计系统）。 - 移动优先的响应式布局。 ### Go/Wasm 引擎 - 确定性碳足迹计算：$CF_{total} = \sum_{i=1}^{n} (E_i \times EF_i)$ - Ed25519 签名和验证。 - 具备未授权参与者检测的受信任参与者注册表。 - 为两个前端应用程序提供 Wasm 桥接。 ### 共享基础设施 - `@eco-trace/ui` 设计 token（颜色、间距、排版、圆角、阴影）。 - 数据字典 (`DATA_DICTIONARY.md`)。 - 包含 10 个黄金测试用例的评估框架。 - 治理规则（Zero-Slop Commenting、UI Dependency First、Mobile-First）。 ## 演示场景：经过验证的产品旅程 所有演示工作都围绕一个具有确定性种子数据的明确场景展开： | 元素 | 值 | |---------|-------| | 资产 ID | `ASSET-COFFEE-2026-001` | | 产品 | 安第斯溯源咖啡批次 001 | | 供应商 | 安第斯有机合作社 | | 加工商 | Veridian 加工节点 | | 物流 | 北极星物流 | 该场景包括有效的供应链事件（ORIGIN → TRANSFORM → TRANSPORT → AUDIT），一个被篡改的事件（`INVALID`），以及一个未授权参与者的事件（`UNAUTHORIZED`）。 ## 当前运行状态 **阶段 8 — 作品集演示卓越版** 所有核心功能（阶段 1–7）均已实现并归档。阶段 8 是附加内容：演示优化、招聘人员浏览旅程、真实性对齐、跨应用契约以及文档编写。 活动的任务文件： | 文件 | 范围 | |------|-------| | `PLAN.md` | 阶段 8 路线图的事实来源 | | `TASKS.md` | 根级别的跨领域交付成果 | | `apps/admin/TASKS.md` | Admin Workstation 演示优化 | | `apps/consumer/TASKS.md` | Consumer Verification 演示优化 | | `apps/admin/archive/TASKS.md` | 阶段 1–4（已归档，全部完成） | | `apps/consumer/archive/TASKS.md` | 阶段 1–6（已归档，全部完成） | 所有任务文件均使用共享的**执行顺序 (1)–(11)**，以便在各个应用之间协调工作。 ## 技术栈 ### 前端 / 客户端层 - **React 19：** 用于 Admin Dashboard 的 Server Components 和 Server Actions。 - **Vue 3.5 (Vapor 模式)：** 超轻量级的 Consumer 应用程序。 - **`@eco-trace/ui`：** 带有共享 token 的内部设计系统。 - **Lucide React/Vue：** 一致的图标体系。 ### 后端 / 边缘层 - **Next.js Route Handlers：** 在 Edge runtime 上运行。 - **Cloudflare D1：** 位于边缘的分布式 Serverless SQL 数据库。 - **Wrangler：** 用于 Cloudflare 资源的本地模拟和部署。 ### 核心密码学 - **Go (Golang) v1.22+：** 编译为 `.wasm`，用于在浏览器中以接近原生的速度执行 Ed25519 加密和确定性验证。 ### 工具与基础设施 - **pnpm：** 感知 Workspace 的 Monorepo 管理。 - **TypeScript 5.x：** 端到端的严格类型安全。 - **Node.js 22.x (LTS)。** ## 本地开发快速入门 ### 1. 前置条件 - **Node.js**：v22.x (LTS) - **Go**：v1.22+（用于 Wasm 编译） - **pnpm**：`npm install -g pnpm` ### 2. 安装 ``` git clone git@github.com:h-builds/eco-trace.git cd eco-trace pnpm install ``` ### 3. 引擎编译 (WebAssembly) ``` cd packages/engine ./build.sh cd ../.. ``` ### 4. 数据库设置 (Cloudflare D1) ``` cd apps/admin # 应用 Schema npx wrangler d1 execute eco-trace-events --local --file=./schema.sql # 生成确定性 Key Pairs 和 Mock Data npx tsx lib/seed.ts # 填充 Database npx wrangler d1 execute eco-trace-events --local --file=./seed.sql ``` ### 5. 运行 Admin 应用 (Edge Server) ``` # 在 apps/admin 中 pnpm run dev:edge ``` 访问 http://localhost:8788/dashboard/overview 打开 Admin Dashboard。 ### 6. 运行 Consumer 应用 ``` # 在 apps/consumer 中 pnpm run dev ``` 在终端中显示的 Vite 开发服务器 URL 处访问 Consumer 应用。 ### 7. 验证命令 ``` pnpm build # Build all workspaces pnpm test # Run all tests pnpm lint # Lint all workspaces ``` 特定引擎的命令： ``` cd packages/engine GOOS=js GOARCH=wasm go build -o main.wasm ``` ## 未来范围 这些项目已规划，但**尚未实现**： - **演示中心：** 将招聘人员引导至两个应用程序的统一入口体验。 - **架构案例研究：** 技术叙事文档 (`docs/case-study.md`)。 - **PWA / 离线模式：** 具备离线优先缓存的 Service Worker。 - **i18n：** 面向全球供应链参与者的多语言支持。 - **AI 异常检测：** 使用 Pinecone 向量嵌入进行统计异常检测。 - **ERP Webhook：** 面向 SAP/Oracle 风格系统的出站事件 schema。 - **供应链地图：** 供应商旅程的交互式地理可视化。 ## 智能化基础设施 (.ai/) 项目治理位于一个结构化的智能层中： - **上下文：** 活动状态和会话记忆 (`CONTEXT.md`)。 - **规则：** Zero-Hallucination、Zero-Slop Commenting、UI Dependency First (`RULES.md`)。 - **知识：** 数据字典、架构、评估框架。 - **库：** 用于关键任务工作流的版本化 prompt 模板。 ## 作品集定位 专为 Edge 打造。为信任而设计。来自南美的管理。

标签：ESG审计, React, Syscalls, Vue, WebAssembly, 供应链管理, 文件系统扫描, 碳足迹核算, 自动化攻击, 边缘计算