Polish project documentation and runtime config
This commit is contained in:
91
docs/API_REFERENCE.md
Normal file
91
docs/API_REFERENCE.md
Normal file
@@ -0,0 +1,91 @@
|
||||
# API 说明
|
||||
|
||||
FastAPI 会自动生成交互式 API 文档。启动服务后访问：
|
||||
|
||||
```text
|
||||
http://localhost:8102/docs
|
||||
```
|
||||
|
||||
所有后台接口统一挂载在：
|
||||
|
||||
```text
|
||||
/v1/admin
|
||||
```
|
||||
|
||||
## 常用接口
|
||||
|
||||
| 接口 | 方法 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `/v1/admin/health` | `GET` | 健康检查 |
|
||||
| `/v1/admin/auth/login` | `POST` | 管理员登录 |
|
||||
| `/v1/admin/auth/me` | `GET` | 当前登录用户 |
|
||||
| `/v1/admin/projects` | `GET/POST` | 项目管理 |
|
||||
| `/v1/admin/ontology-schemas/current` | `GET` | 当前 schema |
|
||||
| `/v1/admin/source-profiles` | `GET/POST/PATCH` | 数据源管理 |
|
||||
| `/v1/admin/batches` | `GET` | 批次管理 |
|
||||
| `/v1/admin/entities` | `GET` | 候选实体列表 |
|
||||
| `/v1/admin/conflicts` | `GET` | 冲突列表 |
|
||||
| `/v1/admin/publish-jobs` | `GET/POST` | 发布任务 |
|
||||
| `/v1/admin/graph/overview` | `GET` | 图谱概览 |
|
||||
| `/v1/admin/graph/query` | `POST` | 图谱查询 |
|
||||
| `/v1/admin/plaza/overview` | `GET` | 图谱广场概览 |
|
||||
| `/v1/admin/manual-ingest/extract` | `POST` | 手动抽取 |
|
||||
| `/v1/admin/travel/assistant-query` | `POST` | 旅行客服问答 |
|
||||
| `/v1/admin/super-agent/run` | `POST` | Super Agent 任务 |
|
||||
| `/v1/admin/roles` | `GET/POST` | 角色管理 |
|
||||
| `/v1/admin/users` | `GET/POST` | 用户管理 |
|
||||
| `/v1/admin/areas/tree` | `GET` | 区域树 |
|
||||
| `/v1/admin/notifications` | `GET` | 通知列表 |
|
||||
|
||||
## 登录示例
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:8102/v1/admin/auth/login \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"username":"admin@example.com","password":"change-me"}'
|
||||
```
|
||||
|
||||
返回中包含 `access_token`，后续接口可使用：
|
||||
|
||||
```bash
|
||||
TOKEN="上一步返回的 access_token"
|
||||
curl http://localhost:8102/v1/admin/auth/me \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
## 图谱查询示例
|
||||
|
||||
```bash
|
||||
curl http://localhost:8102/v1/admin/graph/overview
|
||||
```
|
||||
|
||||
```bash
|
||||
curl http://localhost:8102/v1/admin/graph/query \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"query":"MATCH (n) RETURN n LIMIT 10"}'
|
||||
```
|
||||
|
||||
## 旅行客服问答示例
|
||||
|
||||
```bash
|
||||
curl http://localhost:8102/v1/admin/travel/assistant-query \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"question":"黄小西三日游多少钱？"}'
|
||||
```
|
||||
|
||||
## 前端调用
|
||||
|
||||
React 管理后台通过 `admin-web/src/api.ts` 访问同源 API。Docker 部署时前端和 API 同在 `http://localhost:8102`，因此无需额外配置跨域代理。
|
||||
|
||||
## 外部服务
|
||||
|
||||
LLM 和高德地图相关能力默认关闭或留空。启用前需要在 `.env` 或 Docker Compose 环境变量中配置：
|
||||
|
||||
- `LLM_API_BASE`
|
||||
- `LLM_API_KEY`
|
||||
- `LLM_MODEL`
|
||||
- `LLM_EXTRACTION_ENABLED=true`
|
||||
- `AMAP_WEB_KEY`
|
||||
- `AMAP_JS_KEY`
|
||||
- `AMAP_SECURITY_JSCODE`
|
||||
- `GAODE_CRAWLER_PATH`
|
||||
81
docs/ARCHITECTURE.md
Normal file
81
docs/ARCHITECTURE.md
Normal file
@@ -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` 作为只读挂载提供给数据库容器。
|
||||
103
docs/DATA_SNAPSHOTS.md
Normal file
103
docs/DATA_SNAPSHOTS.md
Normal file
@@ -0,0 +1,103 @@
|
||||
# 数据快照说明
|
||||
|
||||
仓库内置数据库快照，目的是让用户 clone 后可以直接恢复 `new2` 图谱系统，而不需要重新采集、抽取和发布数据。
|
||||
|
||||
## 快照文件
|
||||
|
||||
| 文件 | 类型 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| `snapshots/postgres/kg_admin_new2.dump` | PostgreSQL custom dump | 恢复后台业务库、账号、项目、候选实体、审核数据等 |
|
||||
| `snapshots/falkordb/dump.rdb` | FalkorDB RDB | 恢复图数据库中的业务图和空间图 |
|
||||
|
||||
默认数据：
|
||||
|
||||
| 项 | 值 |
|
||||
| --- | --- |
|
||||
| PostgreSQL database | `kg_admin` |
|
||||
| PostgreSQL schema | `kg_admin_new2` |
|
||||
| FalkorDB 业务图 | `guiyang_new2` |
|
||||
| FalkorDB 空间图 | `guiyang_spatial_v1` |
|
||||
| 空间 POI | 约 `80609` 条 |
|
||||
| 候选实体 | 约 `37457` 条 |
|
||||
|
||||
## 恢复流程
|
||||
|
||||
Docker Compose 首次启动时会自动恢复：
|
||||
|
||||
1. `postgres` 容器创建数据卷。
|
||||
2. `docker/postgres-init/01-restore-snapshot.sh` 使用 `pg_restore` 恢复 PostgreSQL 快照。
|
||||
3. 脚本把演示管理员密码重置为 `change-me`。
|
||||
4. `falkordb-seed` 容器把 `dump.rdb` 复制到 FalkorDB 数据卷。
|
||||
5. `falkordb` 容器读取 RDB 并加载图数据。
|
||||
|
||||
如果数据卷已存在，初始化不会重复执行。需要重置时运行：
|
||||
|
||||
```bash
|
||||
docker compose down -v
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
## 校验数据
|
||||
|
||||
PostgreSQL：
|
||||
|
||||
```bash
|
||||
docker compose exec postgres psql -U admin -d kg_admin \
|
||||
-c "SELECT COUNT(*) FROM kg_admin_new2.amap_spatial_pois;"
|
||||
```
|
||||
|
||||
候选实体：
|
||||
|
||||
```bash
|
||||
docker compose exec postgres psql -U admin -d kg_admin \
|
||||
-c "SELECT COUNT(*) FROM kg_admin_new2.candidate_entities;"
|
||||
```
|
||||
|
||||
FalkorDB 图列表：
|
||||
|
||||
```bash
|
||||
docker compose exec falkordb redis-cli -p 6379 GRAPH.LIST
|
||||
```
|
||||
|
||||
快照文件哈希：
|
||||
|
||||
```bash
|
||||
shasum -a 256 snapshots/postgres/kg_admin_new2.dump snapshots/falkordb/dump.rdb
|
||||
```
|
||||
|
||||
当前发布快照的参考哈希：
|
||||
|
||||
```text
|
||||
c70a3fe2730cd40a96e729097cef1eb39c66498371b88b2e36e985c923043e75 snapshots/postgres/kg_admin_new2.dump
|
||||
dde96ac99bff58d18bb00e84939772d8a4efc4893aeeae02329aa893ae51f247 snapshots/falkordb/dump.rdb
|
||||
```
|
||||
|
||||
## 重新导出快照
|
||||
|
||||
如果本机仍保留 `new2` 原始容器，可以运行：
|
||||
|
||||
```bash
|
||||
bash scripts/export_snapshots.sh
|
||||
```
|
||||
|
||||
脚本默认从以下容器导出：
|
||||
|
||||
| 容器 | 用途 |
|
||||
| --- | --- |
|
||||
| `zn-kg-new2-postgres` | 导出 `kg_admin_new2` schema |
|
||||
| `zn-kg-new2-falkordb` | 触发 `BGSAVE` 并复制 `dump.rdb` |
|
||||
|
||||
导出后请验证：
|
||||
|
||||
```bash
|
||||
ls -lh snapshots/postgres/kg_admin_new2.dump snapshots/falkordb/dump.rdb
|
||||
shasum -a 256 snapshots/postgres/kg_admin_new2.dump snapshots/falkordb/dump.rdb
|
||||
```
|
||||
|
||||
## 仓库边界
|
||||
|
||||
`data/`、浏览器 profile、日志、缓存和本地 Docker 数据卷不进入 Git。它们是运行过程或采集过程中的临时产物，不适合作为 GitHub 项目内容。系统可复现所需的数据已经收敛到 `snapshots/`、`schema搭建/`、`docs/` 和源码目录中。
|
||||
|
||||
## GitHub 文件大小提醒
|
||||
|
||||
GitHub 单文件硬限制为 100 MB。当前两个快照均低于该限制。后续如果快照继续增大，建议改用 Git LFS、Release Asset 或对象存储，并在 README 中保留下载和恢复说明。
|
||||
169
docs/DEPLOYMENT.md
Normal file
169
docs/DEPLOYMENT.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# 部署指南
|
||||
|
||||
本文档说明如何用 Docker 启动、重置、配置和排查旅行知识图谱管理系统。
|
||||
|
||||
## 环境要求
|
||||
|
||||
- Docker Desktop 或 Docker Engine
|
||||
- Docker Compose v2
|
||||
- 至少 4 GB 可用内存
|
||||
- 至少 3 GB 可用磁盘空间
|
||||
|
||||
## 一键启动
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
启动后访问：
|
||||
|
||||
```text
|
||||
http://localhost:8102/admin
|
||||
```
|
||||
|
||||
默认账号：
|
||||
|
||||
```text
|
||||
admin@example.com / change-me
|
||||
```
|
||||
|
||||
## 首次启动会发生什么
|
||||
|
||||
1. 构建 API 镜像，并打包 React 管理后台。
|
||||
2. 创建 PostgreSQL 数据卷。
|
||||
3. PostgreSQL 初始化脚本恢复 `snapshots/postgres/kg_admin_new2.dump`。
|
||||
4. `falkordb-seed` 把 `snapshots/falkordb/dump.rdb` 写入 FalkorDB 数据卷。
|
||||
5. FastAPI 服务等待 PostgreSQL 和 FalkorDB 健康后启动。
|
||||
|
||||
## 常用命令
|
||||
|
||||
查看服务状态：
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
查看 API 日志：
|
||||
|
||||
```bash
|
||||
docker compose logs -f api
|
||||
```
|
||||
|
||||
停止服务：
|
||||
|
||||
```bash
|
||||
docker compose down
|
||||
```
|
||||
|
||||
停止并删除数据卷，下一次启动将重新恢复快照：
|
||||
|
||||
```bash
|
||||
docker compose down -v
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
## 端口配置
|
||||
|
||||
可以在启动时覆盖端口：
|
||||
|
||||
```bash
|
||||
API_PORT=18102 \
|
||||
POSTGRES_PORT=15433 \
|
||||
FALKORDB_PORT=16380 \
|
||||
FALKORDB_BROWSER_PORT=13002 \
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
默认端口：
|
||||
|
||||
| 变量 | 默认值 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `API_PORT` | `8102` | FastAPI 与管理后台 |
|
||||
| `POSTGRES_PORT` | `5433` | PostgreSQL 映射端口 |
|
||||
| `FALKORDB_PORT` | `6380` | FalkorDB Redis 协议端口 |
|
||||
| `FALKORDB_BROWSER_PORT` | `3002` | FalkorDB Browser |
|
||||
|
||||
## 环境变量
|
||||
|
||||
Docker Compose 已提供可运行默认值。生产部署时建议改成 `.env` 文件或部署平台的环境变量。
|
||||
|
||||
| 变量 | 说明 |
|
||||
| --- | --- |
|
||||
| `DATABASE_URL` | 后端连接 PostgreSQL 的 URL |
|
||||
| `DB_SCHEMA` | 默认 `kg_admin_new2` |
|
||||
| `DB_MIGRATIONS_ENABLED` | 快照部署默认 `false` |
|
||||
| `FALKORDB_HOST` | Docker 内默认 `falkordb` |
|
||||
| `FALKORDB_GRAPH` | 默认业务图 `guiyang_new2` |
|
||||
| `AUTH_SECRET` | JWT 签名密钥，生产必须替换 |
|
||||
| `AUTH_DEFAULT_USERNAME` | 默认管理员用户名 |
|
||||
| `AUTH_DEFAULT_PASSWORD` | 默认管理员密码 |
|
||||
| `LLM_API_BASE` | OpenAI 兼容模型服务地址，可选 |
|
||||
| `LLM_API_KEY` | LLM 密钥，可选 |
|
||||
| `LLM_EXTRACTION_ENABLED` | 是否启用 LLM 抽取 |
|
||||
| `AMAP_WEB_KEY`、`AMAP_JS_KEY` | 高德地图密钥，可选 |
|
||||
| `GAODE_CRAWLER_PATH` | 外部高德采集脚本路径，可选 |
|
||||
| `TRAVEL_AGENCY_SOURCE_ROOT` | 旅行社原始资料目录，仅运行采集/构图脚本时需要 |
|
||||
| `TRAVEL_DELIVERY_ROOT` | POI 交付 CSV 目录，仅运行采集/增强脚本时需要 |
|
||||
| `TRAVEL_KG_EXPORT_ROOT` | 采集/构图脚本导出目录 |
|
||||
|
||||
## 健康检查
|
||||
|
||||
API：
|
||||
|
||||
```bash
|
||||
curl http://localhost:8102/v1/admin/health
|
||||
```
|
||||
|
||||
PostgreSQL：
|
||||
|
||||
```bash
|
||||
docker compose exec postgres pg_isready -U admin -d kg_admin
|
||||
```
|
||||
|
||||
FalkorDB：
|
||||
|
||||
```bash
|
||||
docker compose exec falkordb redis-cli -p 6379 PING
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 管理后台 404
|
||||
|
||||
确认镜像已重新构建：
|
||||
|
||||
```bash
|
||||
docker compose up -d --build api
|
||||
```
|
||||
|
||||
前端静态资源由 FastAPI 挂载在 `/admin`，直接访问根路径不会进入后台。
|
||||
|
||||
### 数据没有恢复
|
||||
|
||||
PostgreSQL 初始化脚本只在数据卷首次创建时运行。如果已经创建过数据卷，需要先删除卷：
|
||||
|
||||
```bash
|
||||
docker compose down -v
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
### 端口被占用
|
||||
|
||||
使用端口变量覆盖默认端口，例如：
|
||||
|
||||
```bash
|
||||
API_PORT=18102 docker compose up -d
|
||||
```
|
||||
|
||||
### 登录失败
|
||||
|
||||
初始化脚本会把 `admin@example.com` 的演示密码设置为 `change-me`。如果仍失败，先确认 PostgreSQL 已重新恢复快照，再查看 API 日志。
|
||||
|
||||
## 生产加固建议
|
||||
|
||||
- 修改 `AUTH_SECRET`、数据库密码和默认管理员密码。
|
||||
- 不要把真实 `.env`、LLM key、高德 key 提交到仓库。
|
||||
- 用反向代理提供 HTTPS。
|
||||
- 给 PostgreSQL 和 FalkorDB 配置持久化备份。
|
||||
- 如果面向公网，限制数据库端口暴露，只暴露 API/前端。
|
||||
- 开启日志采集和容器监控。
|
||||
101
docs/MAINTENANCE.md
Normal file
101
docs/MAINTENANCE.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# 维护指南
|
||||
|
||||
本文档记录项目维护、发布和提交前检查流程，帮助仓库长期保持可下载、可启动、可理解。
|
||||
|
||||
## 提交前检查
|
||||
|
||||
```bash
|
||||
git status --short
|
||||
python -m compileall app
|
||||
cd admin-web && npm run build
|
||||
cd ..
|
||||
docker compose config
|
||||
```
|
||||
|
||||
如果修改 Docker 或数据库快照，建议再做一次完整启动验证：
|
||||
|
||||
```bash
|
||||
API_PORT=18102 \
|
||||
POSTGRES_PORT=15433 \
|
||||
FALKORDB_PORT=16380 \
|
||||
FALKORDB_BROWSER_PORT=13002 \
|
||||
docker compose up -d --build
|
||||
|
||||
curl http://localhost:18102/v1/admin/health
|
||||
|
||||
docker compose down -v
|
||||
```
|
||||
|
||||
## 更新系统代码
|
||||
|
||||
- 后端 API 放在 `app/api/`。
|
||||
- Agent 和抽取流程放在 `app/agents/`。
|
||||
- 图谱核心能力放在 `app/kg_core/`。
|
||||
- 前端页面和面板放在 `admin-web/src/`。
|
||||
- 配置项统一从 `app/config.py` 和环境变量读取。
|
||||
|
||||
历史采集/构图脚本的本地资料路径统一在 `scripts/common_paths.py` 中配置，默认指向仓库内 `data/source` 和 `data/exports`。需要接入自己的原始资料时，可通过 `TRAVEL_AGENCY_SOURCE_ROOT`、`TRAVEL_DELIVERY_ROOT`、`TRAVEL_KG_EXPORT_ROOT`、`GAODE_CRAWLER_PATH` 覆盖。
|
||||
|
||||
新增功能时请同步更新：
|
||||
|
||||
- README 的功能说明或项目结构。
|
||||
- `docs/API_REFERENCE.md` 中的接口列表。
|
||||
- 需要运行环境变量时更新 `.env.example` 和 `docs/DEPLOYMENT.md`。
|
||||
|
||||
## 更新图谱 schema
|
||||
|
||||
图谱 schema 和 DSL 资料主要放在 `schema搭建/`。如果 schema 已经发布到数据库或 FalkorDB，建议同时更新：
|
||||
|
||||
- schema 文件
|
||||
- 发布脚本
|
||||
- `docs/reports/new2_current_kg_schema_snapshot.md`
|
||||
- 数据快照
|
||||
|
||||
## 更新数据快照
|
||||
|
||||
从本地 `new2` 容器导出：
|
||||
|
||||
```bash
|
||||
bash scripts/export_snapshots.sh
|
||||
```
|
||||
|
||||
导出后检查：
|
||||
|
||||
```bash
|
||||
ls -lh snapshots/postgres/kg_admin_new2.dump snapshots/falkordb/dump.rdb
|
||||
shasum -a 256 snapshots/postgres/kg_admin_new2.dump snapshots/falkordb/dump.rdb
|
||||
```
|
||||
|
||||
快照更新后必须执行 Docker 恢复验证，确保新用户 clone 仓库后可以直接使用。
|
||||
|
||||
## 仓库不应包含
|
||||
|
||||
- `.env` 和真实密钥
|
||||
- `node_modules/`
|
||||
- Python 虚拟环境
|
||||
- Playwright/浏览器 profile
|
||||
- Docker 数据卷
|
||||
- 临时日志、截图和缓存
|
||||
- 超过 GitHub 限制的大文件
|
||||
|
||||
## 发布建议
|
||||
|
||||
成熟发布建议包含：
|
||||
|
||||
1. 代码和文档已提交。
|
||||
2. Docker 可以从零构建。
|
||||
3. PostgreSQL 和 FalkorDB 快照可以恢复。
|
||||
4. 默认账号可以登录。
|
||||
5. README 中的启动命令与端口正确。
|
||||
6. GitHub 仓库首页可以看到系统定位、架构、数据和部署方式。
|
||||
|
||||
## 当前验证记录
|
||||
|
||||
本地已用非默认端口完成 Docker 验证：
|
||||
|
||||
- API 健康检查返回 `{"status":"ok"}`。
|
||||
- 管理后台 `/admin/` 返回 `200`。
|
||||
- PostgreSQL 恢复后 `kg_admin_new2.amap_spatial_pois` 为 `80609` 条。
|
||||
- PostgreSQL 恢复后 `kg_admin_new2.candidate_entities` 为 `37457` 条。
|
||||
- FalkorDB 可列出 `guiyang_new2`、`guiyang_spatial_v1` 等图。
|
||||
- `admin@example.com / change-me` 登录成功。
|
||||
58
docs/PROJECT_OVERVIEW.md
Normal file
58
docs/PROJECT_OVERVIEW.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# 系统介绍
|
||||
|
||||
旅行知识图谱管理系统是 `new2` 版本的城市与旅行领域知识图谱平台，面向景区、旅行社、文旅运营和智能客服场景。系统把采集资料、百科文本、POI 空间数据、线路产品、酒店/餐饮/车辆等资源沉淀为可审核、可发布、可查询的图谱资产。
|
||||
|
||||
## 目标用户
|
||||
|
||||
- 文旅运营人员：查看图谱覆盖、数据质量、缺口和发布状态。
|
||||
- 数据标注与审核人员：处理实体字段、证据来源、冲突合并和专家签核。
|
||||
- 产品和线路人员：维护固定线路、景点组合、报价说明和资源约束。
|
||||
- 智能客服研发人员：基于图谱接口构建线路问答、周边资源推荐和报价查询。
|
||||
- 工程维护人员：通过 Docker、快照和脚本复现系统与数据。
|
||||
|
||||
## 核心能力
|
||||
|
||||
| 能力 | 说明 |
|
||||
| --- | --- |
|
||||
| 数据源与批次管理 | 管理来源、采集批次、原始记录和质量摘要 |
|
||||
| 实体审核 | 查看候选实体、字段决策、证据链、审查历史和合并 |
|
||||
| 图谱广场 | 汇总图谱规模、使用情况、健康告警和用户查询 |
|
||||
| Schema 管理 | 管理 ontology schema、DSL、版本和发布记录 |
|
||||
| 证据质量 | 聚合 POI 证据、资源质量和字段可信度 |
|
||||
| 发布与回滚 | 创建发布任务、查看 diff、回滚图谱版本 |
|
||||
| 城市空间图谱 | 使用高德 POI 与空间网格支持周边检索 |
|
||||
| 旅行客服 Agent | 支持线路清单、线路匹配、线路报价、酒店资源、车辆和附近资源查询 |
|
||||
| 权限与组织 | 内置角色、能力矩阵、用户和区域责任管理 |
|
||||
|
||||
## 典型业务流程
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["采集/导入资料"] --> B["抽取候选实体"]
|
||||
B --> C["字段证据与质量检查"]
|
||||
C --> D["人工审核/冲突合并"]
|
||||
D --> E["发布到 FalkorDB 图谱"]
|
||||
E --> F["图谱查询/客服问答/运营分析"]
|
||||
```
|
||||
|
||||
## 随仓库发布的内容
|
||||
|
||||
- 后端源码：`app/`
|
||||
- 前端源码：`admin-web/`
|
||||
- Docker 运行环境：`Dockerfile`、`docker-compose.yml`、`docker/`
|
||||
- 图谱数据快照：`snapshots/postgres/`、`snapshots/falkordb/`
|
||||
- 图谱 schema 与样例资料：`schema搭建/`
|
||||
- 采集、构建、发布和快照脚本：`scripts/`
|
||||
- 项目文档：`README.md`、`docs/`
|
||||
|
||||
## 默认演示数据
|
||||
|
||||
快照以 `new2` 本地系统为来源，包含贵阳/贵州旅行场景相关数据：
|
||||
|
||||
- PostgreSQL schema：`kg_admin_new2`
|
||||
- FalkorDB 主要图：`guiyang_new2`
|
||||
- FalkorDB 空间图：`guiyang_spatial_v1`
|
||||
- 空间 POI：约 `80609` 条
|
||||
- 候选实体：约 `37457` 条
|
||||
|
||||
这些数据随仓库一起发布，下载后通过 Docker 初始化脚本自动恢复。
|
||||
@@ -198,6 +198,6 @@ NEARBY_ATTRACTION -> 青岩古镇: 已对齐到 amap:B035300ESE
|
||||
对应脚本：
|
||||
|
||||
```text
|
||||
/Users/xuexue/new2/scripts/align_huaxi_kg_with_existing_graph.py
|
||||
scripts/align_huaxi_kg_with_existing_graph.py
|
||||
```
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
已完成：
|
||||
|
||||
- 从 `/Users/xuexue/new` 复制到 `/Users/xuexue/new2`。
|
||||
- 从 `原 new 目录` 复制到 `项目根目录`。
|
||||
- 排除 `node_modules`、`.env`、`data`、`__pycache__`、运行产物。
|
||||
- 将空间汇报材料和基准测试材料纳入 `docs/reports`。
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## 文件复刻
|
||||
|
||||
`/Users/xuexue/new2` 已从 `/Users/xuexue/new` 完整补齐：
|
||||
`项目根目录` 已从 `原 new 目录` 完整补齐：
|
||||
|
||||
- `.env`
|
||||
- `admin-web/node_modules`
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# new2 当前知识图谱 Schema 快照
|
||||
|
||||
生成时间：2026-05-28
|
||||
项目目录：`/Users/xuexue/new2`
|
||||
项目目录：`项目根目录`
|
||||
|
||||
## 1. 当前配置
|
||||
|
||||
|
||||
@@ -28,8 +28,8 @@
|
||||
|
||||
代码位置：
|
||||
|
||||
- `/Users/xuexue/new2/app/api/travel_assistant.py:1944`
|
||||
- `/Users/xuexue/new2/app/api/travel_assistant.py:3082`
|
||||
- `app/api/travel_assistant.py:1944`
|
||||
- `app/api/travel_assistant.py:3082`
|
||||
|
||||
### 方法二：线路清单使用轻量图谱查询
|
||||
|
||||
@@ -47,8 +47,8 @@ TourProduct -> ProductDay -> RouteStop -> ScenicAttraction/SubAttraction
|
||||
|
||||
代码位置：
|
||||
|
||||
- `/Users/xuexue/new2/app/api/travel_assistant.py:1679`
|
||||
- `/Users/xuexue/new2/app/api/travel_assistant.py:2975`
|
||||
- `app/api/travel_assistant.py:1679`
|
||||
- `app/api/travel_assistant.py:2975`
|
||||
|
||||
### 方法三：景区附近资源使用 NEARBY 关系直查
|
||||
|
||||
@@ -63,7 +63,7 @@ ScenicAttraction -> ATTRACTION_NEARBY_RESOURCE -> Restaurant
|
||||
|
||||
代码位置：
|
||||
|
||||
- `/Users/xuexue/new2/app/api/travel_assistant.py:2013`
|
||||
- `app/api/travel_assistant.py:2013`
|
||||
|
||||
### 方法四：费用资源兼容两条查询路径
|
||||
|
||||
@@ -86,7 +86,7 @@ ScenicAttraction -> ATTRACTION_HAS_ITEM -> TravelItem
|
||||
|
||||
代码位置：
|
||||
|
||||
- `/Users/xuexue/new2/app/api/travel_assistant.py:2196`
|
||||
- `app/api/travel_assistant.py:2196`
|
||||
|
||||
### 方法五：推荐问题才走完整图谱排序
|
||||
|
||||
@@ -114,8 +114,8 @@ NEARBY
|
||||
|
||||
代码位置：
|
||||
|
||||
- `/Users/xuexue/new2/app/api/travel_assistant.py:1536`
|
||||
- `/Users/xuexue/new2/app/api/travel_assistant.py:3082`
|
||||
- `app/api/travel_assistant.py:1536`
|
||||
- `app/api/travel_assistant.py:3082`
|
||||
|
||||
## 3. 当前已经验证的效果
|
||||
|
||||
@@ -146,10 +146,10 @@ NEARBY
|
||||
|
||||
代码位置：
|
||||
|
||||
- `/Users/xuexue/new2/admin-web/src/panels/plaza/TravelAgencyAssistantPanel.tsx:131`
|
||||
- `/Users/xuexue/new2/admin-web/src/panels/plaza/TravelAgencyAssistantPanel.tsx:156`
|
||||
- `/Users/xuexue/new2/admin-web/src/panels/plaza/TravelAgencyAssistantPanel.tsx:182`
|
||||
- `/Users/xuexue/new2/admin-web/src/panels/plaza/TravelAgencyAssistantPanel.tsx:218`
|
||||
- `admin-web/src/panels/plaza/TravelAgencyAssistantPanel.tsx:131`
|
||||
- `admin-web/src/panels/plaza/TravelAgencyAssistantPanel.tsx:156`
|
||||
- `admin-web/src/panels/plaza/TravelAgencyAssistantPanel.tsx:182`
|
||||
- `admin-web/src/panels/plaza/TravelAgencyAssistantPanel.tsx:218`
|
||||
|
||||
## 5. 是否满足当前原型需求
|
||||
|
||||
|
||||
Reference in New Issue
Block a user