> ## Documentation Index
> Fetch the complete documentation index at: https://gisagent.mapgis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 用户用例

# 用户用例

> 三个真实用户的完整氛围编程案例，时间线全部来自原始对话记录（数据与项目名已泛化，token 已脱敏）
> 看别人怎么一步步走弯路的，比自己总结十条方法论有用

## 用例一：一张专题图的完整两天

**需求**：管网资产健康专题图——融合管龄、材质、土质、接口形式，逐段计算健康指数（HI）与剩余寿命（RUL），按风险分级着色出图。

### 阶段 A：首轮 24 分钟出图（14:28 → 14:52）

| 步 | 发生了什么 | 结果 |
| :- | :- | :- |
| 1 | 盘点数据库：42 个 schema 里定位到 `pipeline` schema 的管段表 | 14,882 条管段、27 个字段 |
| 2 | 首版 SQL 用 `regexp_matches` 从"埋设日期"提取年份算管龄 | 执行失败，正则嵌套写法不通 |
| 3 | 改用 `LEFT("埋设日期",4)::integer` + 缺省 30 年兜底 | 跑通，HI = 管龄×0.4 + 管材×0.3 + 土质×0.2 + 接口×0.1 |
| 4 | 导出 GeoJSON 时才发现工具输出是 `{data:{features}}` 嵌套结构，前端拿不到 | Python 脚本扁平化为标准 GeoJSON |
| 5 | 8.5 MB 数据首屏太慢 | 坐标 10 位小数截到 5 位 + JSON 压缩 → 7.1 MB（-11.7%） |
| 6 | 交付 MapLibre 交互页 + README + 技术报告 | **从对话到可打开的专题图：24 分钟** |

### 阶段 B：11 项交互大重构（14:52 一轮指令）

用户对界面提出 11 项要求（顶栏 KPI、悬停浮窗、Shift 框选、六因子雷达图、HI 仪表盘、风险矩阵、情景模拟器、甘特图、双管段对比、时间轴播放……），AI 整批实现，同时给每条管段补了 2018–2030 共 13 年的 HI/RUL 时序。

中间插曲：属性压缩时试过 base64+定点编码，压缩收益不高反而牺牲可读性，**回退**为"短字段名 + 保留明文时序"的方案。

### 阶段 C：预览排障三连（15:35 → 15:37，两分钟三错）

| 用户反馈 | 根因 | 修复 |
| :- | :- | :- |
| 15:35 "加载失败: echarts is not defined" | ① ECharts 只挂了 1 个 CDN，单点失败；② 修复时把 app.js 动态注入，注入完成时 `DOMContentLoaded` 早已触发，`loadData()` 永远不执行 | 4 个 CDN 依次降级 + 启动逻辑判断 `document.readyState` 自适应 |
| 15:37 "Cannot read properties of undefined (reading 'slice')" | `renderScatterChart` 里 `data` 已经是 features 数组，代码又写 `data.features.slice()` | 全文件扫了 6 处 `.slice()` 逐一核对，修正取值链 |

**注意：第二个错误是修第一个错误时引入的**——大改启动时序时带出的回归，靠用户贴报错原文一轮定位。

### 阶段 D：界面与底图六连改（16:02 → 18:39）

| 时间 | 用户指令 | 结果 |
| :- | :- | :- |
| 16:02 | 去掉右侧详情面板、地图填白、裁剪对应地区底图 | CSS 网格 3 列改 2 列，详情改居中弹窗 |
| 16:06 | "把界面里面的常州字段去掉" | 标题/水印/注释全清，grep 复核 0 残留 |
| 16:42 | 底图加天地图 | 加了 DataServer 简式 URL + 测试 token → 加载失败 |
| 16:50\~18:05 | 去天地图→百度、再回天地图→又失败→切高德 | **四种底图轮换了三轮**，每次切换都要同步改瓦片 URL、坐标转换和降级链 |
| 18:11 | "预览页面还是显示天地图加载测试" | 用户打开的是排查时留下的 `test_tianditu.html`，不是 `index.html`——删测试文件，交付目录只留主入口 |
| 18:12 | 直接贴一条**完整可用的 WMTS 地址**（真实 x/y/z + tk） | 一次即通。AI 复盘：之前一直按"文档常见格式"试错，**用户手里有能用的 URL 时应该第一时间要** |
| 18:21 | 报错 `Cannot read properties of null (reading 'appendChild')` | head 里执行 `document.body.appendChild`，body 尚不存在 → 改挂 `document.head` |
| 18:39 | "管网和底图有偏移，管网是常州的" | 为百度底图写的 WGS84→BD09 转换在换天地图后残留在数据加载/中心点/fitBounds/flyTo 多处 → 全部移除，WGS84 直叠（详见[空间参考系](https://gisagent.mapgis.com/docs/spatial-crs.md)） |

### 复盘

* 顺利的部分都符合一个模式：**需求具体 → 一轮完成**（阶段 A、B）；卡住的部分也符合一个模式：**底图/坐标系这类"环境约束"没在首轮说清，后面用 10 轮偿还**。
* 阶段 C 三个报错全部靠 F12 原文在 1\~2 轮内解决，没有一个是"描述现象"能定位的。

## 用例二：十个页面的漏损管控后台

**需求**：基于上传的"管网数据1016.rar"（5 个 shp 图层）做漏损管控系统，第二轮升级为 10 页面后台（驾驶舱/DMA/监测/定位/预测/压优/告警/工单/智能体/配置）。

### 阶段 A：数据落地（14:52 起，前 6 步全在解压）

| 步 | 尝试 | 结果 |
| :- | :- | :- |
| 1 | `unrar` 命令 | 容器内无此命令，apt 安装失败 |
| 2 | python `rarfile` 读文件列表 | ✓ 成功（能列表） |
| 3 | `rarfile.extractall` | ✗ 解压仍失败（缺后端工具） |
| 4 | `bsdtar -xf` | ✓ 解压成功 |
| 5 | `geopandas` 解析 shp | ✗ 环境缺依赖 |
| 6 | 纯 python `shapefile`(pyshp) | ✓ 5 图层解析：管段 14,882 / 节点 8,829 / 接水点 2,823 / 水表 580 / 消防栓 504 |
| 7 | 转 GeoJSON 首版 | ✗ 日期字段不可序列化 → 补 `isoformat` 处理后 ✓ |
| 8 | 坐标范围体检 | 值落在经度区间内，判定已是地理坐标，免投影转换 |
| 9 | K-means+凸包生成 DMA | ✗ 环境无 sklearn → **降级为 3×3 网格法**；首跑又因属性含 None 崩溃，`or 0` 兜底后 ✓ 生成 9 个分区 |

### 阶段 B：报错驱动的三轮修复（15:08 / 15:59 / 16:09）

| 用户反馈（均为 F12 原文或精确位置） | 根因 | 修复 |
| :- | :- | :- |
| `GET https://t{0-7}.tianditu.gov.cn/... net::ERR_NAME_NOT_RESOLVED` | 提示词里的 `{0-7}` 域名模板被 AI 原样照抄进代码，浏览器真去解析这个域名 | 改为 t0/t1/t2 具体域名列表，MapLibre 自动负载均衡 |
| "驾驶舱的实时态势、趋势监控、实时告警下方内容都是空的" | `height: calc(100vh - 320px)` 把容器算没了；缺加载态与空数据兜底 | min-height 系列 + 地图 10s 超时提示 + 图表延迟渲染 + 告警空检查 |
| `App.initMap is not a function at pages-dashboard.js:147`（含完整调用栈） | `initMap` 在 app.js 里定义了，但模块 `return` 清单漏导出 | 补导出，并 `grep "App\."` 全量扫描页面模块引用，一次对齐 7 个方法 |
| "实时监测的实时曲线是空的" | 1 小时窗口恰好 0 个数据点（边界问题）+ canvas 未就绪 | 延迟渲染 + 空数据自动生成 + 超 100 点抽样 |

第二条反馈值得注意：用户说"内容是空的"其实没给报错，但因为**精确指到了页面和区块名**，AI 读代码一轮定位——"位置精确"是"报错原文"之外的第二种有效反馈。

### 阶段 C：迭代与反复（16:14 → 16:43）

| 时间 | 指令 | 结果 |
| :- | :- | :- |
| 16:14 | "管网数据用本对话上传文件中的数据" | 16MB 真实管段接入，`coalesce` 兼容中英文字段名，模拟数据留作 fallback |
| 16:21 | "DMA 分区不要画成正方形，按管网分布画" | K-means+凸包（这次环境备好了）→ 12 个 12\~20 边界点的不规则分区 |
| 16:26 | "删除不在 DMA 范围内的流量点、告警点" | 射线法 point-in-polygon + 过滤函数，测试脚本验证后 ✓ |
| 16:32 | "**撤销**刚才的过滤操作" | 三个函数整体移除 |
| 16:34 | "管网范围坐标是多少" | AI 遍历 30,704 个坐标点报出 bbox：119.949~~119.987 / 31.763~~31.799 |
| 16:37 | "删除不在**这个 bbox** 内的点位" | 换边界框条件重做过滤 |
| 16:40 | "**取消**刚才的 bbox 过滤" | 再次整体移除 |
| 16:43 | "把所有的'千m³'改成'Km³'" | 2 文件 3 处，grep 复核 0 残留 |

16:26→16:40 这 14 分钟里同一个"过滤点位"需求做了—撤—再做—再撤，**四轮往返零净进展**。若 16:26 那轮先问一句"过滤会动哪些数据、影响哪些页面，先给我看清单再执行"，至少能省两轮。

### 复盘

* 全程约 10 轮指令，产出 6,125 行、10 页面、含 AI 算法模拟的完整后台——**每轮指令都短、具体、可验收**是速度来源。
* AI 的交付自述要抽查：本轮汇报"DMA-01 管线总长 17,385 km"，而全区管网实际约 167 km——单位差了量级，属于 AI 汇总统计时的换算错误，**看到大数先对量级**。

## 用例三：支持群实录——"改了 5 遍没修好"

需求方工程师与平台支持的真实对话（管网应用加载失败）：

| # | 用户侧 | 支持侧 | 点评 |
| :- | :- | :- | :- |
| 1 | "新建的管网应用为什么一直加载失败" | "F12 报什么错误？发给 AI 了吗" | 支持第一句就要日志，方向正确 |
| 2 | "发了，但还是没改好"（未附日志内容） | 后台看到应用在**请求国外底图**，内网环境加载不上 | 关键线索：失败的不是代码是网络环境 |
| 3 | "算了，我把对话删了重新发起" | "**不需要删除对话，AI 可以自修复**" | — |
| 4 | 贴出 `Uncaught SyntaxError: Identifier 'APP_DATA' has already been declared (at index.html:3646:9)`，"错误没有解决" | "删了对话我看不见你的记录了，也不好定位" | 报错给了，但现场已删，双方都瞎 |
| 5 | "改了 5 遍是有的""一直没修改" | "F12 的错误要提供给 AI；只说'看不见图'这类自然语言，AI 无法精准定位；给错误日志，AI 都能一把过" | 分水岭判词 |
| 6 | "我就是复制的报错日志，但管网就是加载不出来" | 指向提示词工程 + 分享一个用 DeepSeek 生成提示词的对话链接 | 日志之外，需求陈述也是短板 |
| 7 | 支持："把需求先发给 DeepSeek 生成提示词，再复制给 AI；反复临摹几次就摸清 AI 的性格了" | 用户："我上午已经试过完整提示词，但做的很乱、地图出不来" | 提示词≠一次到位，还要配渐进式 |
| 8 | 用户按"先让地图和管网出来，再来调"分步重试 | 支持："渐进式、结果驱动，一步步来" | 开始收敛 |
| 9 | 用户换 DeepSeek 生成提示词后重试："明显不一样了" | 支持："你已经从自然语言预研到软件工程的进化阶段了，这是 vibe code 的重要分水岭" | 质变时刻 |
| 10 | 用户："整体看起来可以了，但细节好多问题，需要调" | — | **这就是过线后的常态**：从"完全不行"进入"能调"的循环 |

### 复盘

* 失败根因有两个且互相叠加：**环境约束没说**（内网访问不了国外底图，对应[空间参考系](https://gisagent.mapgis.com/docs/spatial-crs.md)和底图选择问题）+ **现场被删**（删对话后 AI 与技术支持同时失明）。
* 用户自认"贴了日志"，但支持方判断其日志没有配合正确的对话现场与需求陈述——**日志、现场、需求三者齐了，"一把过"才成立**。
* 从"删对话重来"到"明显不一样了"，用户实际只做了两件事：换 DeepSeek 打磨提示词、把需求拆成"先地图管网再细节"。方法论就这两条，案例里全看到了。

## 三个用例的公约数

| 用例 | 最大收益动作 | 最大损耗动作 | 对应方法 |
| :- | :- | :- | :- |
| 一 | 首轮需求五件套说全，24 分钟出图 | 底图/坐标系约束后补，六轮底图轮换偿还 | [氛围编程](https://gisagent.mapgis.com/docs/vibe-code.md) §需求模板 |
| 二 | 每轮指令短、具体、可验收，10 轮搭起 10 页后台 | 过滤-撤销-重做四轮往返；自报大数没核量级 | 反馈纪律 2 + 结果验收 |
| 三 | 贴 F12 原文 + 拆阶梯后"明显不一样" | 删对话丢现场，5 轮白改 | 反馈纪律 1 |

***

**使用提示：** 三个用例里所有"弯路"都有解法且都在[氛围编程](https://gisagent.mapgis.com/docs/vibe-code.md)里——开工前照着本文时间线自查一遍：环境约束说了吗、报错原文带了吗、这一步的验收标准是什么。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.