Polish project documentation and runtime config

docs/MAINTENANCE.md

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