实战项目代码规约AGENTS.md分享

# AGENTS.MD

## 1. 目标
本文件用于约束在 `patent-agency-service-source` 仓库内工作的自动化 Agent，确保改动符合当前项目结构与工程约定。

## 2. 仓库结构与职责
- `patent-agency-service-backend`：Java 17 + Spring Boot 3.5.x 多模块后端（Maven 聚合）。
- `patent-agency-service-manager-frontend`：管理端前端，Vue3 + Vite + TS + Element Plus + Pinia。
- `patent-agency-service-company-frontend`：企业端前端，技术栈与管理端一致。
- `.tmp_flowable`：临时/流程相关文件夹，非业务源码主路径。

## 3. 基础约束（所有任务必须遵守）
- 仅在需求相关目录修改文件,原则上只修改本模块的代码，涉及到跨模块的调用时才考虑重构修改其它模块的代码。
- 新增/改动文件统一转成无 BOM UTF-8，不要编码错误导致代码编译失败。
- 对于新增/改动的代码，在对应的类、方法上添加详细的中文注释。
- 严禁回退或覆盖用户已存在的未提交改动。
- 优先最小改动：接口变更必须同时补齐调用方与必要 SQL。
- 项目本地数据库为127.0.0.1:3306,涉及到新增或修改SQL脚本，务必执行SQL落库并做验证。
- 对于执行SQL落库的数据，务必确保字符编码为utf8mb4，排序规则为utf8mb4_unicode_ci，且不要出现中文乱码
- 执行SQL落库后，务必检查菜单正常显示不会出现乱码，功能权限正常。
- 不修改生成物/依赖目录：
- `**/node_modules/**`
  - 前端打包输出目录：
- `patent-agency-service-manager-frontend/patent-agency-service-manager-frontend/**`
    - `patent-agency-service-company-frontend/patent-agency-service-company-frontend/**`
  - `**/*.zip`
  - `**/.codex-dev-server.log`、`**/.codex-dev-server.err`
- 不主动改动环境文件：`**/.env*`、`application-*.yaml`（除非需求明确要求）。

## 4. 后端约束（patent-agency-service-backend）

### 4.1 模块边界
- 聚合工程 `pom.xml` 下核心模块：
- `patent-server`
  - `patent-module-system`
  - `patent-module-infra`
  - `patent-module-company`
  - `patent-module-manager`
  - `patent-module-pay`
  - `patent-module-bpm`
  - `patent-framework`
- 新增业务优先放入对应 `patent-module-xxx`，避免堆到 `patent-server`。

### 4.2 分层落点（保持现有风格）
以 `patent-module-company-server` / `patent-module-manager-server` 为准：
- Controller：`controller/admin/**`
- 请求/响应对象：`controller/admin/**/vo/**`
- Service：`service/**`
- Mapper：`dal/mysql/**`
- DO：`dal/dataobject/**`
- API 常量或跨模块接口：放在对应 `*-api` 模块

### 4.3 后端编码规则
- 遵循现有 `CommonResult`、`PageResult`、`PageParam` 返回模型。
- Mapper 维持 `BaseMapperX` + `LambdaQueryWrapperX` 风格。
- 禁止在 Controller 写复杂业务逻辑，业务下沉到 Service。
- 新增接口时补齐 Swagger 注解（`@Tag`/`@Operation`）与参数校验注解。
- 涉及数据库结构或初始化数据时，必须在 `sql/project/` 增加增量 SQL（文件名使用 `YYYY-MM-DD-功能名.sql`）。

### 4.4 后端验证
- 优先按改动模块最小验证：
- 全量：`mvn -q -DskipTests package`（在 `patent-agency-service-backend`）
- 单模块：`mvn -pl <module-artifact-or-path> -am test`
- 若未执行测试，必须在结果说明中明确“未验证项”。

## 5. 前端约束（双前端）

### 5.1 目录规范
两端结构保持一致，核心目录：
- `src/api`：接口定义与请求封装
- `src/views`：页面
- `src/components`：通用组件
- `src/router`：路由
- `src/store`：状态管理
- `src/types`：类型定义

### 5.2 双端一致性
- 需求同时影响“管理端/企业端”时，必须评估并同步两个前端：
- `patent-agency-service-manager-frontend`
  - `patent-agency-service-company-frontend`
- 任一端不需要同步时，需在说明中写明原因（例如权限域不同、菜单不存在）。

### 5.3 前端编码规则
- API 统一使用 `@/config/axios` 的 `request` 封装。
- 类型优先声明为 `interface`，命名与后端 VO 对齐。
- 页面避免内联大型业务逻辑，提取到 `src/api` 或 `src/hooks`。
- 不直接改编译产物目录（如前端同名打包输出目录中的 `assets` 文件）。

### 5.4 前端验证
在对应前端目录执行：
- 开发启动：`pnpm dev` 或 `pnpm dev-server`
- 类型检查：`pnpm ts:check`
- 必要 lint：`pnpm lint:eslint`
- 打包验证（按环境）：`pnpm build:dev` / `pnpm build:prod`

## 6. 提交与说明规范
- 说明内容至少包括：
- 改了哪些文件
- 为什么这样改
- 是否有未完成项/风险
- 执行了哪些验证命令
- 涉及接口/数据结构变更时，说明前后兼容性。

## 7. 明确禁止事项
- 禁止使用破坏性 Git 命令清理现场（如 `git reset --hard`、`git checkout -- <file>`）。
- 禁止未经确认批量格式化全仓库。
- 禁止修改与当前需求无关模块的业务行为。
- 禁止将密钥、账号、token 写入仓库文件。

## 8. 快速决策规则
- 不确定改动位置时：先查现有同类功能文件，再按同层复制实现。
- 不确定是否双端同步时：默认需要同步，并在无法同步时给出理由。
- 不确定是否需要 SQL 时：只要涉及表结构、字典、菜单、初始化数据，默