系统架构 (System Architecture)¶

概览¶

graph TB
    subgraph 外部系统
        CIN7[Cin7 ERP<br/>数据源/事实源]
    end

    subgraph 数据管道
        AIRFLOW[Apache Airflow<br/>每晚 ETL]
    end

    subgraph Azure 云平台
        DB[(Azure SQL 数据库<br/>Cin7_PO_Headers<br/>Cin7_PO_Lines)]
        API[Azure Functions<br/>Node.js API]
        SWA[Azure Static Web Apps<br/>React 前端]
    end

    subgraph 身份验证
        AAD[Microsoft Entra ID<br/>Azure AD B2C]
    end

    CIN7 -->|SP-API / 导出| AIRFLOW
    AIRFLOW -->|MERGE 更新插入| DB
    DB --> API
    API --> SWA
    AAD -->|MSAL 认证| SWA
    AAD -->|JWT 验证| API

技术栈¶

层级	技术	用途
前端	React + TypeScript + Tailwind CSS	用户界面
API	Azure Functions (Node.js)	后端 REST API
数据库	Azure SQL Database	数据存储
认证	Microsoft Entra ID (Azure AD B2C) + MSAL	身份验证
托管	Azure Static Web Apps	前端 + API 托管
数据管道	Apache Airflow	每晚 Cin7 → SQL 同步
源码控制	GitHub	代码仓库

数据流¶

每晚同步 (Cin7 → Database)¶

Airflow DAG 在预定时间触发
通过 SP-API 从 Cin7 提取 PO 数据
使用 MERGE 更新插入 (upsert) 转换并加载到 Azure SQL
仅更新来自 Cin7 的列 — 保留应用程序拥有的列（供应商答复、状态等）

用户交互 (浏览器 → API → 数据库)¶

用户通过 MSAL 进行身份验证 → 接收 JWT 令牌 (token)
前端发送 API 请求，并在 X-User-Token 请求头中携带 JWT
API 验证令牌，提取用户角色和供应商代码
API 执行带有基于角色的过滤条件的 SQL 查询
响应返回至前端进行渲染

关键设计决策¶

双列模式 (Dual-Column Pattern)¶

每个可编辑字段都有两列：Cin7 原始值和供应商答复值。例如：xfd (原始) 和 vendor_reply_xfd (供应商编辑)。这在跟踪更改的同时保留了事实源。

状态机引擎 (State Machine Engine)¶

所有状态转换都通过单个 executeTransition() 函数进行，该函数会根据 Ref_PO_Transitions 表进行验证。这确保了不会发生无效的状态更改。

基于角色的访问控制 (RBAC)¶

三个角色（Vendor, Manager, Admin）具有层级结构：Admin > Manager > Vendor。供应商通过 billing_company 过滤条件被限制在其所属公司的 PO 范围内。

AI 聊天架构 (AI Chat Architecture)¶

数据助手严格地在 Azure Functions API 上运行，利用 OpenAI 的模型 (gpt-4o-mini)。它包括全面的 PII 屏蔽机制、智能体 SQL 回退引擎 (Agentic SQL Fallback)，以及观测反馈学习循环机制 (Observability loop)，可不断获取系统性分析数据以进一步指导改善系统。

sequenceDiagram
    participant User as 前端 (用户)
    participant API as Azure Functions (/api/chat)
    participant DB as Azure SQL 数据库
    participant LLM as OpenAI (gpt-4o-mini)

    User->>API: 1. 发送问题
    Note over API: 2. 强制执行 RBAC & PII 屏蔽
    API->>LLM: 3. 第 1 阶段: 请求工具调用
    LLM-->>API: 返回标准函数 或 'run_analysis'

    alt 标准工具 (例如: get_po_count)
        API->>DB: 4a. 执行参数化查询 (受权限限制)
    else 智能体 SQL 回退 (run_analysis)
        Note over API: 4b. 验证 SQL 安全性与执行范围
        API->>DB: 4c. 执行动态生成的 SQL 查询
    end

    DB-->>API: 返回数据记录
    Note over API: 5. 后端规则引擎<br/>生成自定义 ECharts 配置
    API->>LLM: 6a. 第 2 阶段: 发送数据进行总结
    LLM-->>API: 6b. 返回自然语言总结
    Note over API: 7. Zod 输出防护栏 & 取消屏蔽 PII
    API-->>User: 8. 返回响应 (打字机效果文本 + 图表数据)
    Note over API: 9. 遥测日志记入数据库 <br/>附带 auto_score 自动评分验证