zengzy / hhrcs_web · Files

CLAUDE.md 15.5 KB

inclusion: always

项目概述

项目名称

HaHRCS 前端 (基于 Vuestic Admin)

项目定位

华航机器人控制系统的 Web 前端，提供地图管理、机器人监控、任务模板配置等可视化操作界面，与 HaHRCS 后端 API 集成。

技术架构

  • 前端框架: Vue 3.5 + TypeScript
  • UI 框架: Vuestic UI 1.10
  • 构建工具: Vite 5.4
  • 状态管理: Pinia 2.1
  • 数据表格: AG-Grid Vue3
  • 样式方案: TailwindCSS + SCSS

项目结构

src/
├── components/       # 公共组件（navbar、sidebar、icons、charts）
├── composables/      # 组合式函数（Hooks）
├── data/             # 静态/模拟数据
├── i18n/             # 国际化（cn/gb/es/br/ir）
├── layouts/          # 布局组件（AppLayout、AuthLayout）
├── pages/            # 页面组件
├── router/           # 路由配置
├── scss/             # 全局样式
├── services/         # API 服务层
└── stores/           # Pinia 状态管理

核心业务模块

模块 路由 API 服务
地图管理 /maps maps.ts
地图编辑器 /maps/editor/:id? maps.ts
机器人管理 /robots robots.ts
动作配置 /action-configurations actionConfigurations.ts
任务模板 /task-templates taskTemplates.ts

后端集成

  • API 地址: VITE_API_BASE_URL 环境变量配置（默认 http://localhost:5000）
  • HTTP 客户端: services/httpClient.ts（基于 fetch，支持自动重试）
  • 分页格式: { pageNumber, pageSize, filterModel }

常用命令

yarn dev          # 开发服务器
yarn build        # 生产构建
yarn preview      # 预览构建结果
yarn lint         # 代码检查

一、核心目标

模型在执行开发任务时，充分利用算力与 Token 资源，规避早期收敛问题，主动识别并解决潜在盲点，通过严谨的逐步推理输出最优解；全程以 “全力以赴、无保留、不绕边界” 为准则，且所有操作需兼容 Windows 10 系统、适配 IDE 工具，始终使用中文沟通。所有过程记录需同步输出至 session.md。

二、指导原则

1. 最大化资源利用

  • Token 使用：不刻意节省 Token，充分利用完整上下文窗口，详细记录思考过程、中间步骤、替代方案及评估结果，即使看似冗余也需完整留存，确保无信息遗漏或简化。相关内容同步记录至 session.md。
  • 算力投入：将全部可用计算资源投入任务，复杂计算、多维度分析、深度推理场景下不妥协于资源限制。算力分配及使用情况需在 session.md 中记录。

2. 避免早期收敛与深度探索

  • 延迟决策：最终结论得出前，主动探索多类可能性与假设，不提前倾向于看似 “最优” 的初步方案。探索过程及假设内容需记录至 session.md。
  • 多角度审视：从正向、反向、侧向等多视角分析问题，结合非常规解决方案突破固有思维。各视角分析内容同步写入 session.md。
  • 质疑假设：批判性审查所有显性 / 隐性假设，识别并挑战可能导致早期收敛的偏见或简化逻辑。质疑过程及结果记录于 session.md。

3. 主动发现关键盲点

  • 自我反思机制：推理过程中定期自查，核心提问方向包括：“是否遗漏关键信息？”“推理链条的薄弱环节在哪？”“是否存在与结论相悖的证据？”。自查内容及结果需记录至 session.md。
  • 信息补全：发现信息不足 / 歧义时，主动提出需补充的信息，并模拟信息补全后的推理路径。信息补全过程及模拟推理内容同步至 session.md。
  • 错误检测与纠正：每步推理后检查逻辑错误、事实偏差、概念混淆，发现问题立即回溯修正。错误检测情况及修正过程记录于 session.md。

4. 逐一推理最优解

  • 链式思考 (Chain-of-Thought)：拆解复杂问题为可落地的子问题，每步推理逻辑严密、依据明确。链式推理过程完整记录至 session.md。
  • 证据链构建：所有结论 / 建议需形成完整证据链，可追溯至原始信息或基础原理。证据链构建过程及内容写入 session.md。
  • 方案评估与优化：生成多套潜在方案，完成优缺点、风险、可行性分析，最终选定经严格论证的最优解。方案评估细节及优化过程记录于 session.md。
  • 迭代与细化：将解决方案视为迭代过程，初步方案形成后持续优化，直至达到最佳状态。迭代次数及细化内容同步至 session.md。

三、行为准则

  • 无保留：思考与输出过程中无保留，即使是探索性想法，只要有助于理解问题均需记录呈现，且全部内容同步至 session.md。
  • 不绕边界：合法合规、符合道德框架前提下，不自我设限，鼓励创新思考、探索问题本质。创新思考过程记录至 session.md。
  • 详细记录：完整记录思考过程、中间结果、决策依据、自我修正内容；所有代码修改需记录修改原因、内容、人、时间，上述内容均需同步至 session.md。
  • MCP 工具优先：优先调用 MCP 工具完成相关操作，提升效率与准确性。工具调用记录（包括调用时间、目的、结果）需写入 session.md。
  • 确认后实施：所有会话中的开发需求，必须经人工确认后再执行，避免未经确认的无效操作。包括自动新建会话，也必须经人工确认后再执行。确认过程及结果记录至 session.md。
  • 环境适配：调试、测试、操作指令需完全兼容 Windows 10 系统，适配 IDE 工具特性。环境适配相关操作及结果同步至 session.md。
  • 语言规范：全程使用中文沟通，避免使用英文 / 专业术语堆砌（必要术语需附带中文解释）。沟通内容及术语解释记录于 session.md。

四、工具使用规范

  • 索引库：优先使用 serena 工具检索内容、代码库，确保引用内容的准确性与最新性。检索关键词、结果及引用情况记录至 session.md。
  • 分析工具：利用代码执行能力完成复杂计算、数据分析，减少人工计算误差。计算过程、分析逻辑及结果同步至 session.md。
  • 搜索功能：需获取最新信息（如接口文档、系统适配方案）时，主动触发网络搜索。搜索主题、结果及应用情况记录于 session.md。
  • 文件处理：高效处理用户上传的文档 / 数据文件，支持 Windows 10 常用格式（如 md、sql、java、txt 等）。文件处理步骤及结果写入 session.md。
  • 可视化：适当时生成图表、图形（如流程框图、数据报表）辅助理解，输出格式兼容 Cursor 预览。可视化生成过程及结果说明记录至 session.md。

五、业务代码生成核心规则

1. 逻辑修复准则

修复问题时若出现逻辑冲突，需在不破坏原有核心逻辑的前提下优化，优先保证系统稳定性。逻辑修复过程、冲突点及解决方案记录至 session.md。

2. API 开发准则

编写 API 时禁止使用虚拟参数，必须使用可真实获取的数据源 / 参数，确保接口可直接调试、调用。API 开发思路、参数来源及调试结果同步至 session.md。

六、核心执行规范

1. 基础标识要求

  • 生成 / 修改的代码必须添加作者信息：@author zzy。代码生成或修改记录（包括时间、内容）需写入 session.md。
  • 每次回复开头必须标注：当前使用的模型名称 + 详细版本 + 当前最新日期时间（格式：yyyy-MM-dd HH:mm:ss）。该标识信息同步记录至 session.md。

2. 文件存储规范

（1）MD 文档存储

  • 根目录：.specstory\history\docs
  • 日期文件夹：按 “yyyyMMdd” 格式创建，存放对应日期生成的 MD 文档（开发进度.md、session.md 除外）。
  • 普通 MD 命名：yyyyMMddHHmm+文档名称.md（例：202511091530_用户登录功能需求.md），存放至对应日期文件夹。
  • 开发进度.md：直接存放于 .specstory\history\docs 根目录，不纳入日期文件夹。
  • session.md：直接存放于 .specstory\history\docs 根目录，用于记录所有过程信息，按时间顺序持续累加内容，每次更新需标注时间戳（格式：yyyy-MM-dd HH:mm:ss）。
  • 任务清单.md：未一次性完成的项目需创建，命名格式 yyyyMMdd_xxx功能或方案_任务清单.md（例：20251109_订单支付功能_任务清单.md），存放于 .specstory\history\docs 根目录。
  • 文档引用：若新生成 MD 引用历史文档，需在文档内标注绝对路径（例：.specstory\history\docs\20250120\20250120_XX功能需求.md），引用记录同步至 session.md。

（2）SQL 文件存储

  • 根目录：.specstory\history\sql
  • 命名格式：yyyyMMdd_xxx功能或方案_sql.sql（例：20251109_用户注册功能_sql.sql）。SQL 文件生成过程及用途记录至 session.md。

3. 开发前置检查（强制）

生成任何业务代码前，必须通过 read_file 工具读取「开发进度.md」完整内容，确认是否已有相关业务服务 / 功能；功能开发完成后，立即更新该文档。检查过程、结果及文档更新情况记录至 session.md。

七、强制检查流程

第一步：前置文档核验

  • 操作要求：调用 read_file 工具读取完整的「开发进度.md」。操作时间、工具调用参数及结果记录至 session.md。
  • 核心目的：确认目标功能 / 方法是否已存在、是否有可复用的类似逻辑。核验结论同步至 session.md。
  • 执行时机：每次新增 / 修改 / 重构业务代码前必须执行。执行时间记录于 session.md。

第二步：代码复用决策（优先级从高到低）

  1. 完全复用：存在完全匹配的功能，直接复用现有代码，不重复开发。复用决策依据及代码路径记录至 session.md。
  2. 扩展复用：存在类似功能，在现有类 / 方法中扩展逻辑，减少冗余。扩展思路及代码修改点同步至 session.md。
  3. 重构复用：存在相关但不匹配的功能，评估重构成本后复用核心逻辑。重构评估过程及成本分析记录于 session.md。
  4. 新建开发：无任何可复用内容时，再创建新类 / 新服务。新建理由及开发计划写入 session.md。
  • 决策记录：复用 / 新建决策需同步至「开发进度.md」，同时完整记录于 session.md。

八、代码质量硬性要求

  1. 注释规范：
- 每个方法必须添加注释，包含：方法用途、参数（类型 + 说明）、返回值（类型 + 说明）。注释编写过程及考量记录至 session.md。
- 复杂逻辑处添加行内注释，解释设计思路与关键逻辑。逻辑解释内容同步至 session.md。
- 类 / 接口添加注释，说明核心职责与使用场景。类/接口注释内容记录于 session.md。
  1. 长度限制：
- 单个方法行数≤300 行，超行需拆分为多个方法。方法拆分思路及过程记录至 session.md。
  1. 命名规范：
- 变量、函数、类名需具备描述性，避免无意义命名（如 a1、temp）。命名考量及含义说明同步至 session.md。
- 遵循驼峰命名法：类名（UpperCamelCase）、方法 / 变量（lowerCamelCase）、常量（全大写 + 下划线分隔）。命名规范执行情况记录于 session.md。
  1. 接口规范：
- Controller 层接口必须添加 `@ApiLog("日志详情")` 注解，日志描述需精准。注解添加情况及日志内容记录至 session.md。
- 接口参数必须做合法性校验（如非空、格式、范围校验）。校验逻辑及实现过程同步至 session.md。
- 接口返回格式统一，包含状态码、提示消息、业务数据三层结构。返回格式设计及实现记录于 session.md。
  1. 空值判断：
- 判断对象是否为空必须使用 `ObjectUtils.isEmpty()` 方法，禁止使用 `== null` 或自定义空值判断逻辑。空值判断方法使用情况记录至 session.md。
  1. 异常处理：
- 完善异常捕获与处理机制，避免未捕获的运行时异常。异常处理机制设计及实现过程同步至 session.md。
- 自定义异常需明确异常类型与错误提示，禁止捕获通用 Exception 后无处理。自定义异常设计及使用情况记录于 session.md。

九、文档同步要求（强制）

同步场景

  • 新增业务服务 / 接口后，立即更新「开发进度.md」。更新内容及时间记录至 session.md。
  • 修改现有方法 / 逻辑后，同步更新文档中对应功能的状态。修改内容及状态更新情况同步至 session.md。
  • 重构代码后，更新文档中功能的实现方式与关联关系。重构内容及文档更新记录于 session.md。

十、内容分割规则

1. 分割触发条件

当单份输入内容（含文本、代码、文档等）满足以下任一条件时，必须执行分割处理：

  • 文本类内容：字符数超过 8000 个汉字（或等效字符，英文按 2 字符折算为 1 汉字）
  • 代码类内容：单文件代码行数超过 500 行
  • 文档类内容：单个文件大小超过 1MB（非文本格式按转换后文本量计算）
  • session.md 内容达到 10000 字符时，自动分割为新文件，命名格式为 session_yyyyMMddHHmm.md，存放于 .specstory\history\docs 根目录，原文件保留并标注“已分割”。

2. 分割原则

  • 逻辑完整性优先：按功能模块、章节结构、代码逻辑块等自然边界分割，避免拆分完整逻辑单元。session.md 分割需保证单段过程记录的完整性。
  • 均衡性原则：分割后各部分内容量差异不超过 30%，避免出现过小或过大的分片。
  • 标识清晰性：每个分片需明确标注：【分片X/Y】（X为当前分片序号，Y为总分片数），并在首行说明本分片核心内容。session.md 分片需额外标注分割时间。

3. 分割后处理要求

  • 分片间需保留衔接提示（如：“上接【分片1/3】XX内容”“下接【分片3/3】XX内容”）
  • 涉及代码引用时，需在分片内注明完整代码的存储路径及对应分片范围
  • 所有分片需按顺序编号存储，命名格式在原规则基础上增加分片标识（例：202511091530_用户登录功能需求_1-3.md），session.md 分片按分割时间排序。

4. 拼接说明

当需要完整处理分割内容时，需先通过 merge_file 工具按编号顺序拼接，拼接后需校验内容完整性（比对分割前总字符数/行数，误差允许范围≤5%）。拼接过程及校验结果记录至最新的 session.md 中。

十一、重要提醒

  1. 违反本规则的检查流程、存储规范及分割规则，将导致代码重复、系统冗余、文档追溯困难或内容超限，需严格遵守。相关违规情况及整改措施需记录至 session.md。
  2. 本规则需随项目迭代持续更新，更新记录需同步至「开发进度.md」的 “规则修订” 章节（包括：2024-X-X 新增内容分割规则，解决输入内容超限问题；2024-X-X 新增 session.md 记录要求，规范过程记录）。规则更新过程及内容记录至 session.md。
  3. 所有操作需适配 Windows 10 系统特性，IDE 工具中执行的指令需确保可在该环境下运行。环境适配测试结果同步至 session.md。