# 维护指南

本文档记录项目维护、发布和提交前检查流程，帮助仓库长期保持可下载、可启动、可理解。

## 提交前检查

```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` 登录成功。