Donaldo-Crish/supply-chain-verification-agent

# [NEXUS TRACE](https://nexus-trace.streamlit.app/) | ***供应链取证平台*** [](https://nexus-trace.streamlit.app/)       # 📌 **概述** 现代供应链饱受数据管道碎片化、运输日志不透明以及假冒伪劣产品注入风险日益增加的困扰。传统的审计系统是被动的——它们只能在损害发生后才察觉问题。 **NEXUS TRACE** 是一个 AI 驱动的供应链记录审计和取证分析平台。进入账本的每一条记录都通过 SHA-256 进行加密指纹化，通过模糊匹配的语义映射器进行规范化，并交由具备推理能力的 LLM 处理，该模型会重建模拟的监管链，识别异常情况，并解释为什么某条记录需要进一步调查。 本项目使用带有 SHA-256 完整性验证的 SQLite 支持的账本。虽然它不是区块链实现，但它展示了如何将加密指纹、审计追踪和验证工作流程应用于供应链记录。 架构有意采用了模块化设计，以便日后可以将存储层替换为分布式账本（如 Hyperledger Fabric），而无需重新设计推理层。 ## 🎯 项目范围 本项目侧重于对历史供应链记录进行审计和验证，而非实时运输追踪。 产品记录被摄取到 SQLite 支持的账本中，通过模糊语义映射进行规范化，使用 SHA-256 进行加密指纹化，并由 AI 取证调查员进行分析。 目前的实现展示了供应链审计、异常调查、制造商风险分析、对话式产品分析以及合规性报告。 未来版本可集成 RFID 系统、IoT 传感器、ERP 平台、区块链网络或物流 API，以进行实时事件追踪。 ## 🏗️ 系统架构  ### 工作原理 1. **数据摄取** — 通过表单逐一添加产品，或通过 CSV 批量上传。语义映射器 (`thefuzz`) 根据同义词表对每个传入的列进行评分，并建议带有置信度百分比的目标字段；您未映射的任何列都将作为 JSON blob (`extra_data`) 保留，而不是被丢弃。 2. **状态规范化** — 将任意状态字符串（`pass`、`cleared`、`fail`、`hold` 等）规范化为以下三种账本状态之一：`VERIFIED`、`FLAGGED` 或 `PENDING`。 3. **加密指纹化** — 每条记录基于其产品 ID、制造商、批次 ID、位置和状态进行 SHA-256 哈希处理，生成一个唯一的指纹，与该行数据一同存储。 4. **账本存储** — 记录存入已建立索引的 SQLite 表（`product_id`、`status`、`manufacturer`），以便在大规模下进行快速过滤。 5. **取证推理** — 验证产品时会通过 Groq 向 Llama 3.3 70B 发送 prompt。模型接收该记录、模拟的监管链（制造商 → 质量控制 → 运输 → 分销），以及与原始 `products.csv` 导入记录交叉引用的历史事件计数——然后返回一个状态、具体原因、风险等级和一条建议。 6. **制造商模式检测** — SQL 聚合分析可揭示被标记产品计数最高的制造商；同一推理引擎会编写一份关于系统性风险的简短高管摘要。 7. **对话式跟进** — 聊天界面基于特定产品的账本记录、模拟旅程和历史计数，回答关于该产品的自由提问。 8. **审计导出** — 由 ReportLab 生成的 PDF 会捕获产品详情、SHA-256 指纹、监管链表格以及 AI 的发现，以供合规记录保存。 ## 🛠️ 技术栈 | 层级 | 技术 | |---|---| | 后端与逻辑 | Python 3.10+ | | 前端 UI | Streamlit ≥ 1.58 | | 数据库 | SQLite + Pandas ≥ 3.0.3 | | AI / LLM | Groq API — `llama-3.3-70b-versatile` | | 完整性 | SHA-256 (`hashlib`) | | 语义映射 | thefuzz ≥ 0.22.1 (模糊同义词匹配) | | 数据可视化 | Plotly Express ≥ 6.8.0 | | PDF 导出 | ReportLab ≥ 4.5.1 | | 配置 | python-dotenv ≥ 1.2.2 | ## ⚡ 快速开始 ### 1. 克隆仓库 ``` git clone https://github.com/Donaldo-Crish/supply-chain-verification-agent.git cd supply-chain-verification-agent ``` ### 2. 创建并激活虚拟环境 ``` python -m venv venv # Windows venv\Scripts\activate # Mac/Linux source venv/bin/activate ``` ### 3. 安装依赖 ``` pip install -r requirements.txt ``` ### 4. 配置环境变量 在根目录下创建一个 `.env` 文件： ``` GROQ_API_KEY=your_groq_api_key_here ``` 在 [console.groq.com](https://console.groq.com) 获取免费的 API 密钥。如果没有它，应用仍然可以运行并且账本依然有效——AI 分析只会返回一条“未配置”通知，而不是取证报告。 ### 5. 确保 `products.csv` 存在 历史事件查询（同时用于 AI 取证调查员和代理的推理 prompt 中）直接从项目根目录下的 `products.csv` 读取，与实时的 SQLite 账本分开。即使您已经将产品清单摄取到数据库中，也请在项目中保留一份副本。 ### 6. 运行应用 ``` streamlit run app.py ``` ## 📸 截图 ##       ## 🔑 核心功能 - **🔒 SHA-256 记录指纹化** — 每一条账本记录都会被哈希化（产品 ID + 制造商 + 批次 + 位置 + 状态），并且指纹会同时显示在 UI 和导出的 PDF 中。 - **🧠 取证 AI 推理** — 解释产品*为什么*被标记、挂起或验证，分配 LOW / MEDIUM / HIGH 风险等级，并给出一条可操作的建议。 - **🏭 制造商风险模式检测** — 一键扫描聚合每个制造商的标记率，并让 AI 撰写一份关于最高风险来源的高管摘要。 - **🔍 多产品取证搜索** — 不区分标点符号的逗号分隔搜索（`PRD-9272`、`9272`、`Component-9272` 均可匹配）返回带有实时状态和 SHA-256 验证徽章的匹配产品卡片。 - **💬 针对产品的上下文聊天** — 基于产品的账本记录、模拟监管链和历史事件计数提出后续问题。 - **📄 PDF 审计导出** — 一份由 ReportLab 生成的报告，包含带有颜色编码的状态徽章、加密指纹框、监管链表格以及 AI 的发现。 - **📊 分析仪表板** — 实时指标、异常可视化、制造商风险分析、基于位置的异常追踪、制造时间轴和风险热力图。 - **🔄 语义批量摄取** — 上传任何 CSV 结构；模糊匹配会建议带有置信度分数的列映射，并在您提交前允许对每一列进行手动覆盖。 - **📇 账本浏览器与记录探索器** — 按状态、制造商或位置进行过滤，并带有颜色编码的行。 - **➕ 实时账本管理** — 通过表单添加记录，通过 CSV 批量摄取，或者通过设有确认机制的“危险区”清除账本（必须输入 `DELETE`）。 ## 📁 项目结构 ``` supply-chain-verification-agent/ ├── app.py # Streamlit frontend — all 4 views, sidebar, styling ├── agent.py # Groq reasoning engine, chat, journey simulation, risk patterns ├── database.py # SQLite ledger, SHA-256 hashing, semantic mapper ├── pdf_export.py # ReportLab audit PDF generation ├── architecture-diagram.svg # System architecture diagram (this README) ├── products.csv # Source manifest — also used for historical lookups ├── requirements.txt ├── .env # GROQ_API_KEY (gitignored) ├── .gitignore # Excludes .env, venv, __pycache__, *.db └── README.md # You are here ``` ## 🗺️ 路线图 - [ ] **区块链集成** — 从 SQLite 迁移到实时的去中心化节点（Ethereum / Hyperledger Fabric / Corda Enterprise），以实现密码学上的不可篡改性 - [ ] **多代理推理** — 并行 AI 代理同时处理不同的供应链环节 - [ ] **RFID / IoT 集成** — 实时检查点扫描，直接馈送至验证 pipeline - [ ] **电子邮件 / Webhook 警报** — 检测到高风险产品时的自动通知 - [ ] **基于角色的访问控制** — 为审计员、供应商和管理员提供独立的视图 ## 👤 作者 **Pravin S** 机电一体化工程与自动化 | AI Agent 架构师 *使用通过 Groq API 的 Llama 3.3 70B 构建。* ## 🤝 致谢 本项目的开发得益于 AI 辅助工具的使用，包括 ChatGPT、Claude、Gemini 和 Perplexity 在头脑风暴、调试、文档编写和设计迭代方面的帮助。

标签：DLL 劫持, Kubernetes, SHA-256校验, SQLite, Streamlit, Sysdig, 代码示例, 供应链管理, 大语言模型, 审计追踪, 数据分析, 访问控制, 逆向工具