Polish project documentation and runtime config

docs/ARCHITECTURE.md

@@ -0,0 +1,81 @@
+# 架构说明
+
+系统采用前后端分离加双数据库架构。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` 作为只读挂载提供给数据库容器。