flowchart TB
    subgraph PAIN["现状：AI 直连，能力散落"]
        direction LR
        A1["AI / Skill"] -->|"逐个适配"| B1["订单系统"]
        A1 -->|"明文凭证"| B2["用户系统"]
        A1 -->|"裸连数据库"| B3["分析库"]
        B1 & B2 & B3 -.-> X1["越权 · 注入 · 无审计 · 上下文溢出"]
    end

    subgraph GOAL["目标：统一网关，一次接入"]
        direction LR
        A2["AI / Skill"] -->|"一个 MCP 端点<br/>一把 API Key"| G["MCP Gateway"]
        G -->|"按权限转发"| C1["业务接口服务"]
        G -->|"只读 + 部门过滤"| C2["业务数据库"]
        G -.->|"全量留痕"| C3["审计日志"]
    end

    PAIN ==>|"收敛为单一入口"| GOAL

flowchart LR
    subgraph CONSUMER["消费方"]
        AI["AI / Skill / Agent"]
        ADMIN["管理后台<br/>React + Ant Design"]
    end

    subgraph GATEWAY["MCP Gateway"]
        direction TB
        AUTH["① 认证<br/>API Key → 用户身份<br/>（库中仅存 SHA-256 指纹）"]
        DISC["② 能力发现<br/>tools · resources · prompts<br/>只返回权限内清单"]
        PERM["③ 权限判定<br/>allow / deny + 操作级 scopes"]
        PROXY["④-a HTTP 代理<br/>call_service"]
        ENGINE["④-b 数据查询引擎<br/>参数化 · 部门过滤 · 脱敏 · 限流限行"]
        AUDIT["⑤ 审计与可观测<br/>行数/字节/耗时/状态 + 健康探针"]
    end

    subgraph BACKEND["业务后端"]
        SVC["业务接口服务<br/>REST API"]
        DB[("只读数据库<br/>SQLite / MySQL / PG")]
    end

    AI -->|"Bearer mcg_..."| AUTH
    AUTH --> DISC --> PERM
    PERM --> PROXY
    PERM --> ENGINE
    PROXY --> SVC
    ENGINE --> DB
    PROXY --> AUDIT
    ENGINE --> AUDIT
    ADMIN -->|"JWT"| GATEWAY

flowchart TD
    START(["AI 发起 tools/call"]) --> A{"API Key 有效？<br/>用户为 active？"}
    A -->|否| E1["401 / 403 拒绝"]
    A -->|是| B{"对该服务有 allow 授权？<br/>scopes 包含该操作？"}
    B -->|否| E2["拒绝并回传「你可用哪些操作」"]
    B -->|是| C{"服务类型"}

    C -->|"api<br/>HTTP 接口"| D1["校验端点 method + path<br/>拒绝路径穿越"]
    D1 --> D2["转发上游<br/>超时控制 + 响应截断"]

    C -->|"database<br/>数据查询"| Q1["列白名单 + 标识符合法性校验"]
    Q1 --> Q2["强制注入部门过滤<br/>dept_id + 组织子树"]
    Q2 --> Q3["参数化执行<br/>只读连接 · 行数上限 · 超时"]
    Q3 --> Q4["敏感列脱敏 mask / hash"]
    Q4 --> R{"结果规模"}

    R -->|"≤1000 行 且 ≤1MB"| R1["直返 JSON<br/>total · returned · has_more"]
    R -->|"超阈值"| R2["落盘 data/query-results/<br/>返回 file_path"]
    R2 -.-> R3["read_query_result<br/>按审计归属校验后取回"]

    D2 --> AUD["写入审计<br/>用户 · 部门 · 服务 · 行数 · 耗时 · 状态"]
    R1 --> AUD
    R2 --> AUD

# 1) 安装并构建（一键脚本会自动完成：检测 Node → 装依赖 → 构建 → 初始化 → 启动）
./start.sh          # Linux / macOS
.\start.ps1         # Windows PowerShell

# 2) 或手动执行
npm run setup       # 安装前后端依赖 + 构建
npm run db:demo     # 生成演示分析库（只读查询用）
npm run db:seed     # 初始化用户/服务/权限/API Key
npm run dp:demo     #（可选）落地数据中台：建库→采集→建视图→质量→注册查询工具
npm start           # 启动（内置 --experimental-sqlite，含启动前自检）
npm run dev         # 开发模式（源码热重载，无需构建）
npm run check       # 一致性检查（文档链接 / 命令 / 双语配对 / 环境变量）

{
  "mcpServers": {
    "mcp-gateway": {
      "url": "http://localhost:3100/mcp",
      "headers": { "Authorization": "Bearer mcg_你的APIKey" }
    }
  }
}

npm test          # 150 项测试：权限模型 / 注入防护 / 部门过滤 / 分页 / 落盘 / 脱敏 / 限流
npm run doctor    # 环境自检：Node 版本 / 依赖 / 构建 / 数据库 / 端口，并给出修复建议