next-tjwater-server/docs/README.md

# 供水 Server 文档目录

环境、启动和发布命令见 [仓库 README](../README.md)，开发规则见 [AGENTS.md](../AGENTS.md)。整理日期：2026-11-10。下列文档按职责组织，不将历史迁移或本地验证当作现有服务状态。

## API、认证与数据

| 主题 | 维护入口 |
| --- | --- |
| API 命名、字段和生成契约 | [API 风格](api-style.md) · [OpenAPI](../contracts/server-v1.openapi.json) |
| 身份、项目成员、管理接口与元数据 | [认证与用户管理](../AUTHENTICATION_AND_USER_MANAGEMENT.md) |
| MCP 设计依据、启用与认证配置 | [查询设计](mcp-query-design.md) · [实施与启用](mcp-query-implementation.md) · [Keycloak 配置](mcp-keycloak-setup.md) |
| MCP 分析、项目服务和后台计算 | [分析工具](mcp-analysis-tools.md) · [项目服务](mcp-project-services.md) · [计算队列](calculation-queue.md) |
| 项目地名与空间覆盖 | [地名搜索](project-place-search.md) · [节点覆盖](node-coverage-tool.md) |
| 项目 BizDB 与时序模型 | [数据库架构](../resources/db_v2/DATABASE_ARCHITECTURE.md) · [管网结构](../resources/db_v2/WNDB_STRUCTURE.md) |

工具目录以 `app/mcp/catalog.py` 为准；启用范围、项目权限和会话用途决定实际可用项，不以文档中的历史工具数量推定。

## 任务、调查与工作台

| 主题 | 维护入口 |
| --- | --- |
| 任务类型、调查轮次与协作 | [工况任务契约](operational-tasks.md) |
| Worker、租约、持久消息、外部动作和部署 | [工况工作进程](operational-task-workers.md) |
| 进展、展示事件与人工反馈续调 | [调查进展与展示](investigation-progress-and-presentation.md) |
| 正式报告与稳定引用 | [调查报告契约](investigation-report-contract.md) |
| 爆管工单到处置闭环 | [爆管处置路线](burst-response-workflow.md) |
| 工作台运行态、外围工单与告警存储 | [运行态与存储](workbench-runtime.md) |
| 事件顺序、SSE 与读取去重 | [工作台事件链路](workbench-event-refinement.md) |
| 通知进入、退出与生命周期 | [通知路由](operational-notification-routing.md) |
| 迁移门禁与逐项目验证 | [数据库变更门禁](workbench-database-rollout.md) |
| 外围工单来源、项目路由和主动同步 | [外围服务](peripheral-sample.md) |

[旧动态计划协议](dynamic-investigation-plan.md) 用于兼容历史计划，当前任务和报告规则以上述专门契约为准。[15173 UI Keycloak 客户端](integration-ui-keycloak-client.md) 是特定联调环境说明，不能作为全部部署环境的通用配置。

## SCADA、回放与数据集

| 主题 | 维护入口 |
| --- | --- |
| 回放、时间轴、周期监测与调查边界 | [SCADA 回放设计与实现](scada-peripheral-replay-design.md) |
| 外围测试样本与数据再现 | [合成样本](peripheral-generated-data.md) |
| 凤阳历史爆管模拟 | [凤阳 SCADA 复制记录](fengyang-burst-scada.md) |
| 奉贤独立 Agent benchmark | [tjwater_v2 benchmark](tjwater-v2-burst-benchmark.md) |
| tjwater2 场景选取与观测 | [多距离与弱信号方案](tjwater2-v2-burst-balanced-design.md) |
| tjwater2 水力校准方法 | [爆管模拟校准](tjwater2-v2-burst-simulation-design.md) |
| 监测点算法与资源压力取舍 | [灵敏度优化](sensor-sensitivity-optimization.md) |

这些数据文档分别描述数据准备、算法设计或历史试算，不能互相替代，也不证明目标数据库已经加载或真实 Agent 已完成验收。

## 合并与历史资料

- `workbench-operations-storage.md` 已并入运行态文档的“工单与告警存储”。
- `peripheral-work-order-events.md` 已并入外围服务文档的“工单事件主动同步”，旧固定库限制已按项目路由实现修订。
- [历史命名审查](history/backend-naming-audit.md) 与 [失效接口排查](history/retired-api-investigation.md) 保留原始审查依据，不能作为当前 API 目录。
- `scripts/missing_api_endpoints.md` 是历史能力盘点，新增能力前需重新核对当前契约与调用方。

设计与部署说明保留分工：设计解释选择与边界，运行文档给出可执行配置；不同数据库、不同数据集和不同生命周期的业务对象不为减少文件数而合并。