# 架构说明

系统采用前后端分离加双数据库架构。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` | 保存后台业务数据、用户权限、项目、候选实体、审核记录和任务 |
| `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/acquisition/` | 数据源、批次和冲突工作台 |
| `admin-web/src/panels/review/` | 证据质量、字段审核、专家签核和资产库 |
| `admin-web/src/panels/modeling/` | Schema、词表和健康检查 |
| `admin-web/src/panels/publish/` | 发布与回滚 |
| `admin-web/src/panels/system/` | 用户、权限、区域、通知、Agent 设置和日志 |

## 数据层

PostgreSQL 和 FalkorDB 承担不同职责：

- PostgreSQL：结构化管理数据、审核过程数据、用户权限、任务、来源、候选实体和证据。
- 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` 作为只读挂载提供给数据库容器。