AGENTS.md

项目规则（Yunyu）

本文件用于约束后续 AI 在本仓库中的开发行为。目标是：正确理解需求、尽量少打扰用户、稳定落地代码、避免引入无关改动。

1. 语言与沟通

• 默认使用简体中文回复，除非用户明确要求英文。
• 代码标识符、命令、日志、报错信息保持原始语言，其余解释使用中文。
• 当需求不完整但可以合理推断时，优先基于现有代码结构做合理假设并继续开发，不要频繁停下来追问。
• 当需求存在明显歧义且会影响数据库结构、接口契约、删除逻辑、鉴权逻辑时，先暂停并向用户确认。

2. 项目结构认知

• 本项目是前后端分离仓库：
  • yunyu-server：后端服务，技术栈为 Spring Boot + MyBatis-Plus + Maven。
  • yunyu-web：前端应用，技术栈为 Nuxt 4 + Vue 3。
  • yunyu-native-image-support：Native Image 相关支持模块，非必要不要随意改动。
  • docs：项目文档，涉及设计决策时优先先看现有文档。
• 新功能开发前，先判断改动应落在哪一层，不要把前端逻辑误写到后端，也不要把后端职责塞到前端。

3. 开发总原则

• 优先复用现有模块、类型、工具类、组件、接口封装和数据模型，不要重复造轮子。
• 优先按当前项目已有风格编写代码，不要强行引入新的架构套路。
• 非用户要求，不主动做大规模重构、不顺手修一堆无关问题、不修改无关文件。
• 涉及前后端联动时，必须同时检查以下内容是否一致：
  1. 接口路径与请求方法。
  2. 请求参数结构、字段命名、必填约束。
  3. 返回值结构与前端取值方式。
  4. 枚举值、状态值、布尔语义是否一致。
• 修改功能时，先理解旧逻辑再下手，避免只改表面表现导致隐性回归。

4. 需求处理流程

• 收到“修改功能”或“新增功能”需求时，默认按以下顺序执行：
  1. 先定位相关代码、接口、页面、类型定义。
  2. 理清当前实现、数据流和影响范围。
  3. 只修改与本需求直接相关的文件。
  4. 完成后做必要的静态检查、代码自查和说明。
• 如果仓库中已有相似功能，优先参照已有实现保持一致性。
• 如果用户描述的是业务效果而不是技术方案，AI 需要自行补足实现细节，但不要擅自改变业务语义。

5. 后端开发规则

• 后端开发目录以 yunyu-server 为准，新增或修改接口时要同时关注 Controller、Service、Mapper、实体、DTO/VO、配置等关联层。
• 后端模块目录遵循现有结构：module/<业务域>/controller、service、mapper、entity、dto、vo、convert。
• 新增业务模块时，优先沿用现有 module/<name> 分层方式，不要新造与现有体系平行的目录结构。
• 命名上优先贴合现有习惯：
  • 管理端请求对象优先使用 AdminXXXCreateRequest、AdminXXXUpdateRequest、AdminXXXQueryRequest。
  • 站点端请求对象优先使用 SiteXXXQueryRequest、SiteXXXCreateRequest。
  • 返回对象优先使用 AdminXXXItemResponse、AdminXXXListResponse、SiteXXXDetailResponse、SiteXXXListResponse 等既有风格。
  • 控制器优先区分 AdminXXXController 与 SiteXXXController。
• 能通过 convert 层完成对象转换时，优先保持转换职责集中，不要在 Controller 中堆大量映射代码。
• 涉及数据库字段、查询条件、分页、排序时，优先复用现有 MyBatis-Plus 使用方式与项目中的既有写法。
• 涉及校验时，优先使用已有参数校验机制，不要把应由后端保证的数据合法性完全留给前端。
• 涉及鉴权、登录态、用户身份、角色权限时，要先检查现有安全链路，避免绕过认证或破坏既有权限边界。
• 涉及上传、对象存储、预签名、文件删除等链路时，要特别注意前后端字段、回调参数、资源清理逻辑是否完整。
• 新增接口前，优先先搜索是否已经存在同语义接口或相邻资源接口，避免在不同 Controller 中重复提供近似能力。

6. 前端开发规则

• 前端开发目录以 yunyu-web 为准，优先遵循当前 Nuxt 目录结构与组件组织方式。
• 前端新增功能时，优先按现有职责落位：
  • 页面放在 app/pages。
  • 可复用接口与业务逻辑放在 app/composables。
  • 共享类型放在 app/types。
  • 通用组件放在 app/components 下的对应分类目录。
• 管理端能力优先复用并延续现有 useAdminXXX composable 风格；站点前台能力优先复用 useSiteXXX 或贴合现有语义的 composable。
• 管理端页面优先沿用现有 /admin/... 路由组织方式；同一资源的列表页、创建页、编辑页命名与目录尽量保持一致。
• 页面改动时，要同步检查：
  1. 页面展示逻辑。
  2. 数据请求与接口封装。
  3. 类型定义。
  4. 表单校验与错误提示。
  5. 加载态、空态、异常态。
• 新增字段或接口返回结构变化时，记得同步更新前端类型、渲染逻辑和提交参数。
• 如果新增后端字段已经被前端展示或提交使用，不要只改接口调用而漏掉 app/types 中的类型定义。
• 如果页面只是消费已有 composable，就尽量不要把重复请求逻辑直接写死在页面里。
• 除非用户明确要求，不要擅自重做 UI 风格；应尽量延续现有页面视觉和交互习惯。
• 不要改动 .nuxt、.output、node_modules 等生成目录中的文件。

6.1 前后端联动落地规则

• 新增一个完整业务能力时，优先检查以下链路是否闭环：
  1. 后端 DTO / VO 是否定义完整。
  2. 后端 Controller / Service / Mapper 是否全部接通。
  3. 前端 composable 是否已封装请求。
  4. 前端 types 是否已同步字段。
  5. 页面或组件是否已正确消费返回值。
• 只要接口字段名发生变化，就必须检查前端：
  • 表单提交参数。
  • 列表渲染字段。
  • 详情页取值。
  • 条件筛选与分页参数。
• 对管理端列表页功能，默认检查“查询、分页、创建、更新、状态变更、删除/下线”等相邻操作是否会被当前改动影响。

6.2 搜索与修改策略

• 开发前优先使用搜索定位相似实现，尤其是以下资源：
  • 后端相邻业务模块。
  • 前端同类管理页 composable。
  • 现有 DTO / VO / type 命名。
• 修改代码时优先做“最小闭环改动”：
  • 先完成必要逻辑。
  • 再补类型和注释。
  • 最后检查是否遗漏调用方。
• 如果发现问题根源与用户提到的位置不同，可以修正真正根因，但仍需控制改动范围，并在最终说明中明确指出。

7. 代码注释要求

• 新增代码时必须补充中文注释。
• 每个新类需要在类头添加中文注释，说明功能和作用。
• 每个新方法需要添加中文注释，说明用途、参数与返回值（如有）。
• 对复杂分支、临时兼容逻辑、特殊业务判断，应补充简洁中文注释说明原因，避免只写“做了什么”而不写“为什么这样做”。
• 修改旧代码时，如果相关类或方法缺少明显必要注释，可以顺手补充，但不要为了补注释大面积改动无关代码。

8. 变更边界与安全规则

• 不要随意修改数据库初始化脚本、部署配置、安全配置、Native Image 配置，除非需求明确涉及。
• 不要删除现有逻辑作为“简化实现”，除非可以确认旧逻辑已废弃，或用户明确要求替换。
• 不要修改与当前任务无关的命名、格式、导入顺序或文件结构，避免制造噪音 diff。
• 不要把调试代码、临时日志、占位实现、伪数据长期留在最终代码中。

9. 构建与验证策略（节省 token / 提高效率）

• 默认策略：小改动不主动构建。
• 仅在以下场景自动执行构建、编译或运行验证：
  1. 用户明确要求“构建 / 编译 / 运行验证”。
  2. 改动文件数量较多（>= 8 个文件）时，自动执行一次构建验证。
  3. 改动涉及核心上传链路、数据库映射、公共类型定义且跨前后端时，可自动执行构建验证。
• 如不满足以上条件，则优先做静态检查和代码审阅，不执行构建。
• 若执行验证：
  • 后端优先使用 Maven 项目自身命令。
  • 前端优先使用 package.json 中已有脚本。
  • 不要自创不存在的验证命令。
• 如果因为环境缺失、依赖问题、外部服务不可用而无法验证，需要明确告诉用户未验证原因。

10. 输出与交付要求

• 完成开发后，说明应包含：
  1. 改了什么。
  2. 为什么这么改。
  3. 是否执行了验证；如果没有，说明原因。
• 如果本次改动存在默认假设，也要一并说明，方便用户继续补充。
• 若用户要求“review”或“代码审查”，应以问题清单为主，优先指出风险、缺陷、回归点和测试缺口，而不是只做总结。

11. 指令优先级

• 用户当前轮次的明确要求，优先级高于本文件。
• 如果系统、平台或上层指令与本文件冲突，以上层指令为准。