| | |
|---|
| | | 先从原始需求出发，不默认用户已经完全想清楚目标、约束和实现路径。 |
|---|
| | | 只有当需求存在关键歧义，且不同理解会导致明显不同方案或较高错误成本时，才先停下来澄清； |
|---|
| | | 否则基于最合理解释继续，并明确说明假设。 当需要给出修改或重构方案时，遵循以下原则： |
|---|
| | | - 默认只围绕用户明确提出的目标设计方案，不擅自扩展业务目标，不引入替代业务路径。 |
|---|
| | | - 优先给出满足目标的最小完整方案，而不是补丁式兼容方案；但如果“最短路径”与“非补丁”冲突，应优先选择不会引入结构性错误的最小正确方案。 |
|---|
| | | - 不做与当前需求无关的兜底、降级或额外分支设计；但为保证逻辑闭合，允许加入必要的输入约束、状态检查和边界保护。 |
|---|
| | | - 输出方案前，按输入、处理流程、状态变化、输出、上下游影响进行链路检查； |
|---|
| | | - 对无法验证的部分必须明确标注假设和未验证前提，不得将推测表述为已确认事实。 |
|---|
| | | 先从原始需求出发，不默认用户已经完全想清楚目标、约束和实现路径。 |
|---|
| | | 只有当需求存在关键歧义，且不同理解会导致明显不同方案或较高错误成本时，才先停下来澄清；否则基于最合理解释继续，并明确说明假设。 |
|---|
| | | |
|---|
| | | 当需要在本仓库内给出修改、排查或重构方案时，遵循以下规则。 |
|---|
| | | |
|---|
| | | ## 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. 执行前检查 |
|---|
| | | |
|---|
| | | 开始实现前至少确认以下几点： |
|---|
| | | |
|---|
| | | - 需求属于哪个模块：`asrs`、`core`、`system`、`ai`、`common`、`com/core` |
|---|
| | | - 是否涉及数据库字段、SQL、菜单、配置项 |
|---|
| | | - 是否涉及前后端联动 |
|---|
| | | - 是否涉及线程状态、设备动作、WebSocket 推送 |
|---|
| | | - 是否需要补国际化文案 |
|---|
| | | - 是否需要新增 SQL 迁移脚本 |
|---|
| | | |
|---|
| | | 如果这些问题里有任何一项答案是“是”，实现时必须把相关链路一并纳入。 |
|---|
| | | |
|---|
| | | ## 6. 搜索与排查方式 |
|---|
| | | |
|---|
| | | 优先用快速定位，不做无边界扫读： |
|---|
| | | |
|---|
| | | ```bash |
|---|
| | | 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 消费点 |
|---|
| | | |
|---|
| | | ## 7. 校验与验证 |
|---|
| | | |
|---|
| | | 按成本从低到高执行，无法执行时要明确说明原因。 |
|---|
| | | |
|---|
| | | ### 7.1 编译校验 |
|---|
| | | |
|---|
| | | ```bash |
|---|
| | | mvn -q -DskipTests compile |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | ### 7.2 定向测试 |
|---|
| | | |
|---|
| | | 若改动附近已有测试，优先跑定向测试，例如： |
|---|
| | | |
|---|
| | | ```bash |
|---|
| | | mvn -q -Dtest=NavigateUtilsTest test |
|---|
| | | mvn -q -Dtest=WrkAnalysisServiceImplTest test |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | ### 7.3 整体测试 |
|---|
| | | |
|---|
| | | ```bash |
|---|
| | | mvn test |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | ### 7.4 启动验证 |
|---|
| | | |
|---|
| | | ```bash |
|---|
| | | 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` |
|---|
| | | |
|---|
| | | ## 8. 高风险改动提醒 |
|---|
| | | |
|---|
| | | - 改 Mapper XML 时，重点防字段漏映射、别名不一致、结果集类型错误。 |
|---|
| | | - 改线程/调度逻辑时，重点防竞态、重复下发、状态不回收、死循环、异常丢失。 |
|---|
| | | - 改页面字段时，重点防前后端 JSON 字段名不一致。 |
|---|
| | | - 改上下文路径相关代码时，重点防前端硬编码路径漏加 `/wcs`。 |
|---|
| | | - 改 AI 配置时，重点防把数据库配置链路和 YAML 回退链路混淆。 |
|---|
| | | - 改监控/地图逻辑时，重点防“后端数据正确但前端渲染错位”和“前端显示正常但状态源错误”互相误判。 |
|---|
| | | |
|---|
| | | ## 9. 输出要求 |
|---|
| | | |
|---|
| | | 完成任务后，结果说明应尽量包含： |
|---|
| | | |
|---|
| | | 1. 改了什么，目的是什么。 |
|---|
| | | 2. 影响了哪条链路或哪些模块。 |
|---|
| | | 3. 实际修改了哪些文件。 |
|---|
| | | 4. 跑了哪些验证，结果如何。 |
|---|
| | | 5. 哪些内容是基于假设，哪些部分未验证。 |
|---|
| | | |
|---|
| | | 如果是排查类任务，优先说明根因、证据和修复点；如果尚未完成，明确阻塞位置，不要把推测当结论。 |
|---|
