先从原始需求出发，不默认用户已经完全想清楚目标、约束和实现路径。
只有当需求存在关键歧义，且不同理解会导致明显不同方案或较高错误成本时，才先停下来澄清；否则基于最合理解释继续，并明确说明假设。

当需要在本仓库内给出修改、排查或重构方案时，遵循以下规则。

1. 目标边界

• 默认只围绕用户明确提出的目标设计方案，不擅自扩展业务目标，不引入替代业务路径。
• 优先给出满足目标的最小完整方案，而不是补丁式兼容方案；但如果“最短路径”和“最小正确方案”冲突，优先不引入结构性错误。
• 不做与当前需求无关的兜底、降级或额外分支设计；但为保证逻辑闭合，允许加入必要的输入约束、状态检查和边界保护。
• 输出方案前，按“输入 -> 处理流程 -> 状态变化 -> 输出 -> 上下游影响”完成链路检查。
• 对无法验证的部分，必须明确标注假设和未验证前提，不得将推测表述为已确认事实。

2. 仓库结构总览

这是一个 Spring Boot 3.5 + Java 17 + MyBatis-Plus + WAR 的 WCS 项目，前端不是独立 Node 工程，而是 src/main/webapp 下的页面与静态脚本直出。

2.1 启动与构建

• 启动入口：src/main/java/com/zy/Boot.java
• Maven 坐标：com.zy:wcs:1.0.0
• 打包方式：war
• 最终产物名：wcs
• 默认端口：9090
• 默认上下文路径：/wcs（由 server.servlet.context-path: /@pom.build.finalName@ 解析而来）

2.2 Java 包结构

• src/main/java/com/zy/asrs
• 业务域主模块。
• 常见分层：controller、service、mapper、entity、domain、task、planner、ws。
• 与任务、出入库、站点、地图、路径策略相关的需求，优先从这里定位。

• src/main/java/com/zy/core

• 设备运行时与调度核心。
• 关注 dispatch、network、thread、task、move、plugin、trace、properties。
• 设备动作编排、线程执行、主流程插件、网络通讯问题优先看这里。

• src/main/java/com/zy/system

• 系统管理与基础配置。
• 包含用户、角色、权限、资源、日志、License许可证、系统配置、定时任务等。

• src/main/java/com/zy/ai

• AI 相关功能模块。
• 包含提示词模板、LLM 路由、调用日志、诊断、MCP 挂载、定时任务、初始化逻辑。
• 涉及 /ai/** 页面或接口、Spring AI、MCP Server 时优先看这里。

• src/main/java/com/zy/common

• 通用能力。
• 包含认证、Web、工具、国际化、通用模型与公共服务。

• src/main/java/com/core

• 旧公共基础能力和代码生成相关内容。
• 常见内容包括注解、异常、基础工具、生成器模板支撑。
• 不要默认这里是当前主业务入口，但改动生成器、基础返回结构或底层工具时需要关注。

2.3 资源与前端结构

• 页面：src/main/webapp/views/**
• 页面脚本：src/main/webapp/static/js/**
• 公共组件：src/main/webapp/components/**
• 样式：src/main/webapp/static/css/**
• Mapper XML：src/main/resources/mapper/*.xml
• SQL 迁移脚本：src/main/resources/sql/*.sql
• 国际化：src/main/resources/i18n/**
• 代码生成模板：src/main/resources/templates/**
• 地图/示例文件：src/main/resources/map/**

前端结构以“页面目录”和“同名脚本目录”配对为主，例如：

• views/basStation/** 对应 static/js/basStation/**
• views/watch/** 对应 static/js/watch/**
• views/ai/** 对应 AI 相关页面

但监控与可视化页面还会额外依赖：

• src/main/webapp/components/MapCanvas.js
• src/main/webapp/components/WatchCrnCard.js
• src/main/webapp/components/WatchDualCrnCard.js
• src/main/webapp/components/WatchRgvCard.js

3. 按需求类型定位代码

3.1 后端接口或业务逻辑

优先按这条链路检查：

Controller -> Service -> ServiceImpl -> Mapper.java -> mapper/*.xml -> 实体/DTO/Param

注意：

• 本项目大量查询和更新依赖 XML SQL，不能只改 Java Mapper 接口不改 XML。
• 改字段时必须同步检查实体、参数对象、返回对象、SQL 别名和前端字段名。
• 如果是列表页或保存页，通常还要继续联动到 views/** 与 static/js/**。

3.2 数据库结构或菜单/配置新增

优先检查：

• src/main/resources/sql/*.sql
• src/main/java/com/zy/system/**
• src/main/java/com/zy/asrs/**
• src/main/java/com/zy/ai/**

规则：

• 表结构、初始化数据、菜单、配置项新增，默认补 SQL 脚本，而不是只改运行时代码。
• 若需求涉及历史迁移，按现有命名风格新增增量 SQL，避免直接覆盖旧脚本。

3.3 设备线程、调度、主流程、网络通讯

优先检查：

• src/main/java/com/zy/core/thread/**
• src/main/java/com/zy/core/dispatch/**
• src/main/java/com/zy/core/task/**
• src/main/java/com/zy/core/network/**
• src/main/java/com/zy/asrs/task/**
• src/main/java/com/zy/core/plugin/**

规则：

• 不要只在单个线程类中做局部修补而忽略状态来源、任务下发条件和回写路径。
• 必须检查共享状态、阻塞点、异常吞噬、重试条件、线程退出条件。
• 涉及主流程切换时，注意 mainProcessPlugin 配置及相关插件实现。

3.4 监控大屏、地图、WebSocket、PixiJS

优先检查：

• src/main/webapp/views/watch/**
• src/main/webapp/views/locMap/locMap.html
• src/main/webapp/components/MapCanvas.js
• src/main/java/com/zy/asrs/ws/**

规则：

• WebSocket 地址要带上下文路径 /wcs。
• 监控页改动通常不止一个 HTML，可能同时影响 console.html、console_pixijs.html、locMap.html 和组件文件。
• 地图点位、设备状态、颜色、轨迹、性能问题，优先判断是前端渲染问题还是后端推送数据问题，不要混在一起改。

3.5 AI、诊断、LLM 路由、MCP

优先检查：

• src/main/java/com/zy/ai/controller/**
• src/main/java/com/zy/ai/service/**
• src/main/java/com/zy/ai/config/**
• src/main/java/com/zy/ai/mcp/**
• src/main/webapp/views/ai/**
• src/main/resources/sql/*ai*.sql

规则：

• 路由、模板、挂载信息很多已经迁移到数据库，不要只盯 application.yml。
• 如果需求涉及模型、密钥、路由切换，先区分“数据库主配置”和“YAML 回退配置”。

4. 修改原则

4.1 默认最小闭环，不做半链路改动

• 只改用户目标直接相关文件。
• 但只要当前链路天然依赖上下游文件，就必须一次改完整，不能留下明显断链。

4.2 保持现有工程风格

• 后端保持当前包结构和分层命名方式。
• 前端保持当前 Vue 2 风格脚本直写 的方式，不额外引入前端构建体系。
• 非必要不把现有 HTML/JS 页面改造成全新框架写法。

4.3 避免结构性错误

• 不随意把业务逻辑塞进 Controller。
• 不新增与现有体系并行但职责重复的 Service、Util、线程或页面。
• 不绕过 Mapper XML 直接拼接杂散 SQL。

5. 代码可读性要求

Agent 生成的代码必须易于人类阅读和维护，禁止以下写法：

5.1 命名

• 禁止单字母变量名（循环计数器 i/j 除外）、无意义缩写（mgr、hdl、proc 除非是项目既有约定）。
• 变量名和方法名必须能表达意图，读名字就知道"这是什么"或"做什么"。
• 中文业务术语可直接用拼音或英文全称，不要发明缩写。

5.2 控制流

• 禁止超过 3 层的嵌套 if/for。遇到深层嵌套，提取为独立方法或用 early-return 扁平化。
• 禁止超长方法（超过 80 行应考虑拆分）。
• 禁止在一个表达式里链式调用超过 3 个操作（如 a.getB().getC().getD().do()），应拆成中间变量并命名。
• 三元运算符只用于简单赋值，禁止嵌套三元。

5.3 注释与意图

• 不写"翻译式注释"（如 // 获取用户名称 放在 getUserName() 上方）。
• 注释只解释"为什么这样做"，不重复"做了什么"。
• 复杂业务逻辑、非显而易见的边界处理、绕过的坑，必须加注释说明原因。

5.4 结构

• 不把多步逻辑压缩成一行以"减少行数"。一行只做一件事。
• 不为了"通用"而提前抽象。三次以上重复才考虑提取。
• 异常处理必须有实际意义，禁止空 catch、e.printStackTrace() 或吞掉异常后继续跑。

6. 执行前检查

开始实现前至少确认以下几点：

• 需求属于哪个模块：asrs、core、system、ai、common、com/core
• 是否涉及数据库字段、SQL、菜单、配置项
• 是否涉及前后端联动
• 是否涉及线程状态、设备动作、WebSocket 推送
• 是否需要补国际化文案
• 是否需要新增 SQL 迁移脚本

如果这些问题里有任何一项答案是“是”，实现时必须把相关链路一并纳入。

7. 搜索与排查方式

优先用快速定位，不做无边界扫读：

rg -n "关键字" src/main/java src/main/resources src/main/webapp
rg --files src/main/java/com/zy | rg "Controller|Service|Mapper|Task|Thread"
rg -n "接口路径|字段名|配置项名" src/main/java src/main/webapp src/main/resources

排查问题时优先找：

1. 入口 Controller 或页面按钮事件
2. 对应 Service 主流程
3. Mapper XML / SQL
4. 状态回写点
5. 页面渲染或 WebSocket 消费点

8. 校验与验证

按成本从低到高执行，无法执行时要明确说明原因。

7.1 编译校验

mvn -q -DskipTests compile

7.2 定向测试

若改动附近已有测试，优先跑定向测试，例如：

mvn -q -Dtest=NavigateUtilsTest test
mvn -q -Dtest=WrkAnalysisServiceImplTest test

7.3 整体测试

mvn test

7.4 启动验证

mvn -q -DskipTests spring-boot:run

重点确认：

• 服务端口 9090
• 实际访问前缀 /wcs
• MySQL、Redis 依赖是否可连接

7.5 页面验证

如果改了页面、脚本或 WebSocket，至少说明验证了哪些页面，例如：

• /wcs/views/index.html
• /wcs/views/watch/console.html
• /wcs/views/locMap/locMap.html
• /wcs/views/ai/*.html

9. 高风险改动提醒

• 改 Mapper XML 时，重点防字段漏映射、别名不一致、结果集类型错误。
• 改线程/调度逻辑时，重点防竞态、重复下发、状态不回收、死循环、异常丢失。
• 改页面字段时，重点防前后端 JSON 字段名不一致。
• 改上下文路径相关代码时，重点防前端硬编码路径漏加 /wcs。
• 改 AI 配置时，重点防把数据库配置链路和 YAML 回退链路混淆。
• 改监控/地图逻辑时，重点防“后端数据正确但前端渲染错位”和“前端显示正常但状态源错误”互相误判。

10. 输出要求

完成任务后，结果说明应尽量包含：

1. 改了什么，目的是什么。
2. 影响了哪条链路或哪些模块。
3. 实际修改了哪些文件。
4. 跑了哪些验证，结果如何。
5. 哪些内容是基于假设，哪些部分未验证。

如果是排查类任务，优先说明根因、证据和修复点；如果尚未完成，明确阻塞位置，不要把推测当结论。