city-life-line/memory/long-term.md

城市生命线长期记忆

项目定位

这是“城市地下管网及设施建设改造智能化系统项目”软件平台中“地下管网管控平台”的 Vue 3 前端，覆盖燃气、排水、供水、管网基础、告警、风险和应急调度等业务域。供水前端与 E:\pipe-ner-server\pipe-network-service 后端共同构成“供水管网安全运行监测系统”。

技术架构

• Vue 3 + Vite
• Element Plus + Pinia
• UnoCSS + SCSS
• Axios 统一请求层，使用 JWT 鉴权
• 百度地图 WebGL 与 Leaflet 并存
• ECharts 用于监测、统计和大屏可视化
• 业务路由由后端菜单和权限动态生成
• 对应后端仓库为 E:\pipe-ner-server；管理后台基于 Spring Boot/RuoYi，网关路由由 Nacos 动态配置。

当前功能成熟度

• 基础台账、排水、应急调度的前端 API 接入相对完整。
• 燃气、井盖、管网页面为真实接口与模拟数据混合。
• 供水 19 个页面已按项目文档 5.3.2 命名完成第一阶段实现；五类设施 CRUD 复用既有页面，设备、运行监测、报警、统计和轻量 GIS 已接后端真实接口，后续按完整供水子系统验收。
• 供水 T3 统计（Issue #7）与 T4 运行监测（Issue #8）已人工验收通过并在 Gogs 关闭（2026-09-05）。

启动约定

• 使用 npm，不依赖 Yarn。
• 开发命令：npm run dev
• 默认前端地址：http://localhost:80
• 备用端口：npm run dev -- --port 5173
• 开发代理：/dev-api → 本机 8300/pipe 后端
• 正常登录和业务菜单需要对应后端服务运行。

记忆库约定

• 每次对话结束后更新当天的 memory/sessions/YYYY-MM-DD.md。
• 稳定决策和长期有效事实同步到本文件。
• 每累计 5 次会话或单日记录超过约 20 KB 时整理长期记忆。
• 不记录密码、Token、API 密钥、地图密钥、内部账号或个人隐私。

用户已确认决策

• 告警表 alarm_data 不再存储设备名称、设备类型、处理时间、处理人和处理备注（2026-09-24）。名称和类型从设备台账查询，处理状态仍使用 alarm_status；操作日志独立保留。

• 采用仓库原生 AGENTS.md + memory/ 方案。

• 直接在当前项目目录维护记忆库，不创建额外 worktree。

• 记忆库只使用 Markdown，不参与前端运行时，不新增 npm 依赖。

• 前后端 Issue 均通过内网 Gogs 网页低频维护，不假定 CLI 或 API 集成。

• Git 提交信息统一使用中文，说明改动目的与范围；一次提交只承载一个主题；用户未明确要求时不推送。

• 工程技能采用默认 triage 标签：needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix。

• 前端领域文档采用单上下文布局；后端 E:\pipe-ner-server 采用按 Maven 模块划分的多上下文布局。

供水前端约定

• 供水动态菜单组件路径统一使用 waterSupply/facility/*、waterSupply/device/*、waterSupply/monitoring/*、waterSupply/monitorAlarm/*。
• 业务菜单仍由 /getRouters 动态下发；前端组件入口存在不等于角色已经获得对应 sys_menu 权限。
• GIS 第一阶段使用后端 GeoJSON 做分类、点线分布与详情联动，后续接入真实底图时保持接口和页面名称不变。
• 供水报警与工单前端统一使用唯一接单责任人；无手机号不阻断派单。
• 供水、排水、燃气、窨井共用统一工单业务流程，系统展示范围由关联设备类型过滤；前端优先复用既有 REST 接口，不因页面入口创建平行工单生命周期。
• 工单系统归属以关联设备类型树稳定业务编码判定；/api/work-order 是跨系统规范 API，旧入口只做兼容适配；统一工单继续采用数据库状态机和统一日志语义。
• 报警管理侧重只读态势与台账；四子系统报警审核共用 src/views/subSystem/alarm/index.vue，sys_menu.path 均为 alarmAudit，菜单 query.rootTypeId 按设备类型树隔离，燃气再限定 warning_code。确认报警创建待派单工单但不改设备状态；工单后续操作仍在统一工单页。此约定取代早期“审核页承载工单全流程/误报解除”的设计。
• 报警继续使用 alarm_level：1～4 为一级～四级报警，一级最严重；audit_status 独立于 alarm_status。本次数据库脚本不迁移历史数据，不引入 source_key；alarm_log.log_id 使用 Kingbase int8 和独立序列 alarm_log_id_seq。
• 报警审核附件只支持 JPG/JPEG/PNG 图片（最多 5 张、单张 10 MB），前后端禁止 PDF；处置记录以缩略图展示，点击查看大图，可切换同条记录的多张图片。
• 报警实际值为空时不展示实际值/阈值行，0 仍正常展示；审核转工单的 work_order.order_desc 保存根据报警信息生成的故障描述，审核意见单独保存在报警日志中。
• 日常巡检和设备保养工单由其他业务系统创建及首次派发；派给当前用户后可以在供水工单总览继续处置。
• 设备报警状态、报警记录状态和工单处置状态必须分别展示，不得互相替代。
• 管理端统一工单生命周期采用数据库与前端一致的 0–7 契约（0 待派单/1 待接单/2 已接单/3 处理中/4 待验收/5 已结案/6 延期中/7 已取消）；终态仅已结案和已取消，延期中是处理旁路。验收驳回是“待验收(4)回退到处理中(3)”的动作而非状态。调用方必须按接口契约解释状态编码并以状态名展示。三仓共识见本仓 docs/domain/work-order-lifecycle.md。
• 相关页面采用蓝白运行指挥台风格；一级至四级报警依次使用红、橙、蓝、绿，供水菜单全部配置图标。
• 详细设计见 docs/design/2026-08-22-water-supply-work-order-ui.md。

产品级决策

• 正式产品定位为“城市地下管网及设施建设改造智能化系统项目”软件平台中的“地下管网管控平台”；供水交付单元为“供水管网安全运行监测系统”，由本前端与 E:\pipe-ner-server\pipe-network-service 后端共同构成。
• KingbaseES 是生产和最终验收唯一数据库真相源；PostgreSQL 仅在无法避免时用于兼容性验证。
• 供水整体开发按业务纵向切片推进，既有接口可复用时优先复用；真实接口失败不得回退到随机模拟数据。
• 前后端保持独立仓库和独立构建，以版本化 REST 契约、真实登录态 E2E 和 KingbaseES 集成验收作为集成门禁。
• 工单处置图片采用 MinIO + KingbaseES 附件元数据；现有工单图片 URL 字段继续兼容，新图片按处理前/处置后阶段展示。