106 lines
7.4 KiB
Markdown
106 lines
7.4 KiB
Markdown
# fire-safety-ymd 项目协作与开发规范
|
||
|
||
## 1. 必读入口
|
||
|
||
开始任务前按顺序阅读：
|
||
|
||
1. `AGENTS.md`
|
||
2. `CONTEXT.md`
|
||
3. `PROJECT_STATE.md`
|
||
4. `docs/project/README.md`
|
||
5. 与任务相关的项目文档、Spec、ADR 或 Workflow
|
||
|
||
通用标准位于：
|
||
|
||
- `docs/import/reusable/ai-native-software-engineering-standard.md`
|
||
- `docs/import/reusable/general-development-guidelines.md`
|
||
|
||
项目规则与通用标准冲突时，以用户当前明确要求和 `docs/project/ai-nses-project-overlay.md` 中更具体的项目约束为准。
|
||
|
||
## 2. 项目定位
|
||
|
||
本仓库建设一个 Go 后端，负责连接用户侧应用与既有 SuperAgent 平台，并通过受控 MCP 工具向 Agent 提供森林防火业务数据。PostgreSQL/PostGIS 是空间业务事实的预期权威来源，SuperAgent 负责理解问题、选择工具和组织回答。
|
||
|
||
当前已完成项目骨架、`GET /health`、默认关闭的原生用户对话 API、可选 DashScope 风格兼容对话入口、SuperAgent Open API 出站适配器，以及默认关闭的空间只读 MCP/PostGIS 基线。对话入口只有独立静态联调凭证和单进程内存会话，不是最终用户认证；兼容 SSE 只在严格成功后返回正文。仓库已有多阶段 Docker/Compose 测试部署基线和把 `agent.nianxx.com` 精确反代到本 Go 服务的 Nginx 示例；容器端口只发布到宿主机回环地址，目标服务器和公网链路尚未验证。MCP 具备 7 个固定工具（含地名候选搜索）、独立 Bearer、显式服务端数据范围（数据库全范围或镇街白名单）、readiness 校验和只读参数化查询。数据提供方确认源数据为 EPSG:4326 且无偏移；2026-09-05 已通过受控事务为 4,048 条非空几何补齐 SRID 4326 元数据，严格 readiness 和 7 个工具的本地真实数据库冒烟测试均已通过，但真实消防 Profile 对话、公网部署与 SuperAgent 回调联调尚未完成。地名候选必须由用户确认，不要把查询成功当成资源可用性、路线、实时队伍位置或生产鉴权已经验证。
|
||
|
||
## 3. 默认工作方式
|
||
|
||
- 先确认 checkpoint 的目标、边界、验收标准和允许的写操作。
|
||
- 修改前检查 Git 状态，保留用户已有变更，不回滚、不覆盖、不顺手整理无关文件。
|
||
- 一次只完成一个明确 checkpoint；新需求进入 Spec、Change Request 或下一个 checkpoint。
|
||
- 先读现有接口和项目文档，再新增抽象或依赖。
|
||
- 对未确认的外部接口、数据结构、坐标系、权限规则和部署条件明确标记 `待确认`，不得猜测为事实。
|
||
- 完成后报告变更、验证命令、验证结果、未确认项和建议下一步。
|
||
- 除非用户明确要求，不自动创建提交、推送、迁移生产数据或调用外部系统写接口。
|
||
|
||
## 4. Go 工程规则
|
||
|
||
- 使用 `gofmt` 作为唯一基础格式化标准，变更后至少执行 `go test ./...`。
|
||
- `cmd/server` 只负责进程启动、信号和依赖装配，不放业务规则。
|
||
- `internal/handler` 负责 HTTP/MCP 入站契约、输入校验和响应映射。
|
||
- `internal/service` 编排用例；`internal/domain` 保存稳定领域概念与规则。
|
||
- `internal/repository` 保存持久化适配器和确实稳定的仓储契约，不允许 Handler 直连数据库。
|
||
- `internal/config` 集中读取、默认值处理和配置校验；业务代码不散落读取环境变量。
|
||
- `pkg` 只放确实需要被其他 Go module 导入的稳定 API；没有明确复用方时优先放入 `internal`。
|
||
- 接口应小且由使用方定义；依赖通过构造函数显式注入，避免全局可变状态和隐藏初始化。
|
||
- 错误必须携带上下文并使用 `%w` 保留错误链；正常业务失败不使用 `panic`。
|
||
- 先使用标准库；引入框架或第三方依赖前记录用途、维护状态和替代方案。
|
||
|
||
完整后端规则见 `docs/project/backend-development-guidelines.md`。
|
||
|
||
## 5. 数据、AI 与安全边界
|
||
|
||
- 不允许 Agent 执行任意 SQL；MCP 只暴露固定、参数化、可授权和可审计的领域工具。
|
||
- 用户身份、租户/区域范围和角色来自可信服务端上下文，不接受模型自由填写这些授权参数。
|
||
- 未确认 SRID 前不得上线空间距离或包含关系计算；不得把 WKB 坐标数值猜测直接升级为数据库事实。
|
||
- **原始几何维度不得被静默降维：**用户现场导入已确认 `st_2_xianyoufanghuotongdao.geom` 同时存在二维和带 Z 维度的几何；原导出声明 `geometry(GEOMETRY)` 会以二维 typmod 拒绝 Z 记录（PostgreSQL 错误 `22023`）。该表的原始导入列必须保持为不限定 typmod 的 `geometry`，除非另有经过审查的数据迁移决定。
|
||
- 未经用户或数据所有者明确授权，不得对原始表执行 `ST_Force2D`、重写 WKB 或以其他方式丢弃 Z。若 MCP 算法只接受二维数据，应在只读查询/派生层显式投影并记录语义，不得修改原始事实。几何维度与 SRID 是两件事；成功容纳 Z 不代表坐标系已确认为 EPSG:4326。
|
||
- 实库已发现 35 条无效面几何。当前决策是不自动修复或覆盖原始几何：readiness 明确告警，所有 MCP 查询使用 `ST_IsValid` 排除，工具响应提示结果可能不完整。SRID、坐标范围和几何类型仍是启用 MCP 的硬门禁。
|
||
- 不把资源记录存在等同于设备当前可用；返回值需要能表达来源、更新时间、不确定性和现场确认要求。
|
||
- 联系人、电话、精确位置、访问令牌和数据库凭证按敏感信息处理，不进入普通日志或模型无权限上下文。
|
||
- AI 生成内容是辅助信息，不能虚构现场状态，也不能替代报警、人员撤离和现场指挥。
|
||
|
||
完整边界见 `docs/project/security-access-control-boundary.md`。
|
||
|
||
## 6. 常用命令
|
||
|
||
```bash
|
||
gofmt -w ./cmd ./internal
|
||
go test ./...
|
||
go vet ./...
|
||
go run ./cmd/server
|
||
curl -i http://localhost:8080/health
|
||
# 仅在只读 PostGIS 配置已显式加载时：
|
||
go run ./cmd/postgis-probe
|
||
# 仅使用临时表所有者/迁移凭证，详见项目 operations 文档：
|
||
go run ./cmd/postgis-srid-migrate
|
||
# 仅在项目专属测试凭证已配置时：
|
||
go run ./cmd/superagent-probe
|
||
```
|
||
|
||
默认监听地址为 `:8080`，可通过 `FIRE_SAFETY_HTTP_ADDR` 覆盖。Secret 只允许放在环境变量或未提交的 `.env` 文件中。
|
||
|
||
`docs/import/db-samples/*.sql` 含受限联系人和破坏性导出 DDL，已被 Git 忽略；只能只读分析，不得执行、提交或复制到测试输出。
|
||
|
||
## 7. 文档完成条件
|
||
|
||
每个 Feature 或 checkpoint 完成前检查：
|
||
|
||
- `PROJECT_STATE.md` 是否反映真实状态。
|
||
- Domain、Architecture、Workflow、ADR、Spec 是否需要新增或更新。
|
||
- 接口、安全、权限、审计、外部系统和数据契约是否同步。
|
||
- 验证命令和已知限制是否有可追踪记录。
|
||
|
||
没有文档变化时，交付说明中明确写 `No documentation changes required.`。
|
||
|
||
## 8. 多 Agent 协作
|
||
|
||
使用多 Agent 工作流时：
|
||
|
||
- 主线程拆分任务、分配互不重叠的文件所有权并负责最终整合。
|
||
- 边界明确、可独立完成的任务优先交给 `luna_worker`；需要修改代码且判断要求较高的任务交给 `sol_worker`。
|
||
- 同一个文件同一时间只能由一个写入 Agent 负责，所有 Agent 必须保留他人的现有修改。
|
||
- 实现结束后由 `sol_reviewer` 只读验证，并明确返回 `PASS` 或 `FAIL`。
|
||
- 最多并行启动 6 个子 Agent；运行时上限更低时按实际上限执行。
|
||
- 主线程等待所有子 Agent 返回后再统一总结。
|