100 lines
8.6 KiB
Markdown
100 lines
8.6 KiB
Markdown
# fire-safety-ymd 项目上下文
|
||
|
||
## 1. 项目目标
|
||
|
||
`fire-safety-ymd` 是一个面向森林防火场景的 Go 后端项目。目标调用链是：用户在业务应用中提问，后端维护会话并调用既有 SuperAgent 平台；SuperAgent 在需要业务事实时调用本项目提供的 MCP 工具；本项目从受控的 PostgreSQL/PostGIS 数据源查询消防资源和风险区域，再将结构化结果返回给 Agent 组织回答或辅助方案。
|
||
|
||
项目不自行训练或实现通用 Agent，也不允许大模型直接访问数据库。
|
||
|
||
## 2. 当前系统组成
|
||
|
||
| 路径或系统 | 当前职责 | 当前状态 |
|
||
| --- | --- | --- |
|
||
| `cmd/server` | Go 服务进程入口 | 已建立 |
|
||
| `internal/app` | 应用装配、readiness 和 HTTP 生命周期 | 已建立；按开关装配原生/兼容 Chat、SuperAgent 和 MCP/PostGIS |
|
||
| `internal/config` | 环境配置入口 | 已包含 HTTP、SuperAgent、Chat 兼容 App ID、MCP 与 PostGIS 配置校验和凭证分离门禁 |
|
||
| `internal/handler` | HTTP/MCP 入站协议层 | `GET /health` 已启用；默认关闭的原生 `/api/chat`、可选 DashScope 风格 `completion` 和 `/mcp` 已实现 |
|
||
| `internal/service` | 业务用例编排 | 已实现单进程聊天会话/并发 Run 控制，以及地名候选、有界空间查询、可信数据库全范围/镇街白名单和结果语义 |
|
||
| `internal/domain` | 森林防火领域模型与规则 | 已包含点位、水源、候选设施、通道、队伍和风险区模型 |
|
||
| `internal/repository` | PostgreSQL/PostGIS 持久化适配 | 已实现 pgxpool、只读固定 SQL 与 schema/SRID readiness；实库 SRID 元数据、严格 readiness 和 7 个工具真实查询已验证 |
|
||
| `cmd/postgis-srid-migrate` | 显式 SRID 元数据迁移 | 已执行；默认只读预检，写入需独立迁移凭证和明确 CRS 确认 |
|
||
| `internal/integration/superagent` | SuperAgent Open API 出站适配 | 已实现并通过模拟 Provider 测试，默认关闭 |
|
||
| `cmd/superagent-probe` | 无业务数据的显式连通性探针 | 已实现；需要项目专属测试配置 |
|
||
| `cmd/postgis-probe` | 不读取业务行的 PostGIS readiness 探针 | 已实现；需要只读数据库配置 |
|
||
| `Dockerfile` / `compose.yaml` | 测试环境容器构建与单实例进程托管 | 已建立；只发布宿主机回环端口，目标服务器尚未验证 |
|
||
| `pkg` | 可被外部 module 复用的稳定 Go API | 当前为空 |
|
||
| `docs/import` | 字段/表映射、通用模板和本地数据库样例 | 样例 SQL 含受限数据并被 Git 忽略，不会执行 |
|
||
| SuperAgent | 对话理解、工具选择和答案组织 | 已按仓库内 2026-07-12 协议基线实现客户端；当前环境待联调 |
|
||
| PostgreSQL/PostGIS | 消防空间业务事实的预期权威来源 | 8 表共 4,055 条记录；4,048 条非空几何已标记 EPSG:4326，严格 readiness 与本地真实工具冒烟均通过；35 条无效几何按当前策略排除并告警 |
|
||
|
||
## 3. 技术栈
|
||
|
||
### 已采用
|
||
|
||
- Go module：`fire-safety-ymd`（临时 module 名）。
|
||
- 本地工具链：Go `1.26.6`。
|
||
- HTTP：Go 标准库 `net/http`。
|
||
- 测试：Go 标准库 `testing`、`httptest`。
|
||
- 配置：环境变量；支持 HTTP、SuperAgent、Chat、MCP 与 PostGIS 配置，并默认关闭 Chat 及两个外部方向。
|
||
- Chat API：标准库 HTTP/SSE；原生 `/api/chat` 使用静态联调 Bearer，可选 `completion` 兼容入口使用同一信任方向的 `xtoken`；两者共享精确 Origin、严格 JSON、总超时、有界单进程会话和同会话并发冲突。兼容入口只在严格成功后发送正文。
|
||
- SuperAgent：标准库 HTTP/SSE 客户端，分离 Session 创建和消息发送，支持严格完成判定与既有 Run 断流恢复。
|
||
- MCP：标准库 HTTP/JSON-RPC，协议基线 `2025-06-18`，同步 JSON 响应，独立 Bearer 和 7 个只读工具；地名工具只搜索现有业务记录并要求用户确认候选。
|
||
- PostgreSQL：`github.com/jackc/pgx/v5 v5.10.0` 原生连接池；连接默认只读并设置 statement timeout。
|
||
- PostGIS：`ST_Covers`、`ST_DWithin`、`ST_Distance` 和 `ST_ClosestPoint`；只在实库确认 EPSG:4326 后启用。
|
||
- 部署：多阶段 Docker 镜像与单实例 Compose；Secret 通过未提交的 `.env` 在运行时注入，应用端口只发布到宿主机 `127.0.0.1:8080`，由宿主机 Nginx 终止 TLS。
|
||
|
||
### 计划但尚未接入或确认
|
||
|
||
- PostgreSQL/PostGIS 的适用索引和生产查询计划验证。
|
||
- SuperAgent 到 `/mcp` 的真实网络、TLS、Header 与 Token 联调。
|
||
- 任意地址/山名的外部地理编码、别名词典和大数据量地名索引。
|
||
- 用户聊天的真实身份认证、动态授权、共享/持久会话、主动取消和限流策略；首版默认关闭的静态 Bearer + 内存会话 API 已实现。
|
||
- 最终用户鉴权、动态角色/区域或租户隔离、持久审计与完整可观测性方案。
|
||
- 正式前端身份接入；现有客户端仅通过受限 DashScope 风格协议适配。
|
||
|
||
## 4. 已知业务数据范围
|
||
|
||
当前资料描述 8 类森林防火空间资源：
|
||
|
||
| 资源 | 预期 PostgreSQL 表 | 预期几何形态 |
|
||
| --- | --- | --- |
|
||
| 蓄水池 | `st_2_xianyouxushuichiguan` | 点 |
|
||
| 防火通道 | `st_2_xianyoufanghuotongdao` | 线；样例为 MultiLineString，原始数据混合二维与 Z 维度 |
|
||
| 水源地 | `st_2_mpslfh_t_slfh_syd` | 点 |
|
||
| 林区工矿企业 | `st_2_linqugongkuangqiye` | 面 |
|
||
| 防火网格 | `st_2_fanghuowangge` | 面 |
|
||
| 防火瞭望哨 | `st_2_fanghuoliaowangshao` | 点 |
|
||
| 防火检查站 | `st_2_fanghuojianchazhan` | 点 |
|
||
| 墓地坟区 | `st_2_mudifenqu_mian` | 面 |
|
||
|
||
仓库中的两份 Excel 是字段与数据表映射资料，不是可查询的业务数据库。`docs/import/db-samples/*.sql` 是含敏感字段的本地参考输入，已被 Git 忽略且不得由开发 Agent 执行。用户在 2026-09-04 的现场导入中确认，防火通道原始数据同时包含二维和带 Z 维度的几何：`geometry(GEOMETRY)` 导入到第 256 条附近时报 `Geometry has Z dimension but column does not`，将该原始列改为不限定 typmod 的 `geometry` 后重导成功。2026-09-05 的初始只读 audit 覆盖 8 表共 4,055 条记录：4,048 条非空几何均标记 SRID 0，7 条为空，35 条面几何无效，仅防火网格表存在 GiST 几何索引；类型和经纬度数值范围符合预期。数据提供方随后确认 8 表源数据均为 EPSG:4326、无坐标偏移，并允许 MCP 二维计算忽略 Z，但原始 Z 仍须保留。项目使用独立 `admin` 迁移凭证在单个事务中补齐了 4,048 条几何的 SRID 4326 元数据：7 张二维表改为 `geometry(Geometry,4326)`，防火通道保持裸 `geometry` 且 2 条 Z 几何未变；迁移前后无 SRID WKB 指纹、行数、类型、有效性和维度一致，随后只读严格 readiness 通过。无效几何仍不自动修复，查询排除并明确告警。
|
||
|
||
## 5. 目标职责边界
|
||
|
||
- 用户侧应用：采集用户输入并展示结果；具体形态待确认。
|
||
- 本 Go 服务：鉴权上下文、会话转发、MCP 工具、数据查询、权限、安全和审计。
|
||
- SuperAgent：理解自然语言、决定是否调用工具、组织自然语言结果。
|
||
- MCP 工具：提供固定的森林防火领域查询，不开放任意 SQL 或跨权限访问。
|
||
- PostgreSQL/PostGIS：保存和计算可信空间事实；资源是否可用仍取决于明确状态和数据时效。
|
||
|
||
## 6. 当前开发方向与非目标
|
||
|
||
当前阶段已有可运行、可测试、文档自解释的 Go 基线、SuperAgent Open API Adapter、默认关闭的原生用户对话 API、可选 DashScope 风格兼容入口，以及空间只读 MCP/PostGIS 实现。对话入口使用独立静态联调凭证和单进程内存会话；仓库已有多阶段 Docker/Compose 基线以及精确路径、无 Secret 的 Nginx HTTPS 反向代理示例，但尚未在目标机验证。MCP 默认关闭，实库严格 readiness 和全部 7 个工具的本地真实查询已通过。下一阶段在测试服务器应用这些部署资产，并使用真实消防 Profile 联调公网对话与 MCP。
|
||
|
||
本阶段不实现：
|
||
|
||
- 面向真实用户的认证、动态权限、持久会话和已验证生产能力；当前对话入口只用于受控联调。
|
||
- PostgreSQL/PostGIS 数据导入或索引 DDL；SRID 元数据迁移是已经显式执行的一次受控运维操作，不是应用运行时行为。
|
||
- 用户登录、权限模型、审计存储和生产部署。
|
||
- 面向真实火情的自动决策或路径规划。
|
||
- 队伍实时定位、集结点管理和资源调度。
|
||
|
||
## 7. 新 Agent 阅读顺序
|
||
|
||
1. `AGENTS.md`
|
||
2. `CONTEXT.md`
|
||
3. `PROJECT_STATE.md`
|
||
4. `docs/project/README.md`
|
||
5. `docs/project/ai-nses-project-overlay.md`
|
||
6. 与任务相关的后端或安全规范
|