# 架构说明

系统采用前后端分离加双数据库架构。Docker Compose 会启动 PostgreSQL、FalkorDB 和 FastAPI API 服务；React 管理后台在镜像构建时被打包为静态文件，由 FastAPI 挂载到 `/admin`。

## 容器拓扑

```mermaid
flowchart TB
    subgraph compose["Docker Compose"]
        API["api\nFastAPI + 静态后台"]
        PG["postgres\nPostgreSQL 16"]
        Seed["falkordb-seed\n复制 dump.rdb"]
        FK["falkordb\nFalkorDB"]
    end
    Browser["浏览器"] --> API
    API --> PG
    API --> FK
    Seed --> FK
```

## 服务职责

| 服务 | 职责 |
| --- | --- |
| `api` | 提供 `/v1/admin/*` API，挂载 `/admin` 前端页面，连接 PostgreSQL 与 FalkorDB |
| `postgres` | 保存项目、Schema、结构化业务数据、用户权限和后台流程支撑数据 |
| `falkordb-seed` | 首次启动时把仓库内的 `snapshots/falkordb/dump.rdb` 写入数据卷 |
| `falkordb` | 保存图数据库，支持 Cypher/Redis 协议访问和 FalkorDB Browser |

## 后端模块

| 路径 | 说明 |
| --- | --- |
| `app/main.py` | FastAPI 入口、CORS、路由挂载和前端静态资源挂载 |
| `app/config.py` | 环境变量配置 |
| `app/db.py` | PostgreSQL 连接池 |
| `app/api/` | 管理后台 API 路由 |
| `app/agents/` | 采集、抽取、对齐和外部站点 Agent |
| `app/kg_core/` | 空间图谱与核心图谱辅助逻辑 |
| `app/schemas/` | 抽取 schema |
| `app/security.py`、`app/auth.py` | 登录、令牌和权限相关逻辑 |

## 前端模块

| 路径 | 说明 |
| --- | --- |
| `admin-web/src/App.tsx` | 管理后台主应用与路由 |
| `admin-web/src/api.ts` | API 客户端 |
| `admin-web/src/panels/plaza/` | 数据大屏、业务问答、图谱浏览和 Super Agent |
| `admin-web/src/panels/data-platform/` | 项目数据库、表、记录、CSV 与 SQL 工作区 |
| `admin-web/src/panels/modeling/` | 当前项目 Schema 的只读展示 |
| `admin-web/src/panels/system/` | 简化用户管理（数据管理/数据查看）和接口中心 |

## 数据层

PostgreSQL 和 FalkorDB 承担不同职责：

- PostgreSQL：项目、Schema、结构化业务数据、用户权限，以及 Agent 所需的内部流程数据。
- FalkorDB：图谱实体、关系、路线、资源、POI、空间索引和面向查询的图结构。

默认配置：

| 配置项 | 默认值 |
| --- | --- |
| PostgreSQL database | `kg_admin` |
| PostgreSQL schema | `kg_admin_new2` |
| FalkorDB 业务图 | `guiyang_new2` |
| FalkorDB 空间图 | `guiyang_spatial_v1` |

## 构建过程

`Dockerfile` 使用多阶段构建：

1. Node.js 阶段进入 `admin-web/`，执行 `npm ci` 和 `npm run build`。
2. Python 阶段安装 `requirements.txt`。
3. 复制 `app/`、`schema搭建/` 和前端构建产物到镜像。
4. 容器启动 `uvicorn app.main:app --host 0.0.0.0 --port 8000`。

快照文件不会进入 API 镜像，它们由 `docker-compose.yml` 作为只读挂载提供给数据库容器。