From ea5071dc37f16322658b560e4b57ee8f816d13b9 Mon Sep 17 00:00:00 2001
From: Apcallover <1503963513@qq.com>
Date: Tue, 28 Jul 2026 11:00:28 +0800
Subject: [PATCH] =?UTF-8?q?flat:=E5=90=88=E5=B9=B6=E4=BB=A3=E7=A0=81?=
 =?UTF-8?q?=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .codex/agents/AGENTS.md |  50 --------------
 AGENTS.md               |  95 ++++++++++++++++++++++++++
 frontend/AGENTS.md      | 143 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 238 insertions(+), 50 deletions(-)
 delete mode 100644 .codex/agents/AGENTS.md
 create mode 100644 AGENTS.md
 create mode 100644 frontend/AGENTS.md

diff --git a/.codex/agents/AGENTS.md b/.codex/agents/AGENTS.md
deleted file mode 100644
index 1d2b249..0000000
--- a/.codex/agents/AGENTS.md
+++ /dev/null
@@ -1,50 +0,0 @@
-
-# 项目背景
-一个培训项目
-
-## 技术栈
-前后端分离
-- 前端：react 版本 18，typescript，vite
-- 后端：springboot 3.4.5，java 21，mybatis-plus
-- 数据库：mysql 8
-- 缓存：redis
-
-## 工作规则
-### 整体规则
-- 所有文件使用 uft-8 格式，避免中文乱码。
-- 修改代码前，必须先阅读项目结构。
-- 修改前必须说明会影响哪些文件。
-- 修改后必须给出启动命令和测试步骤。
-- 不允许把所有功能堆在一个页面或一个文件里。
-- 建表或修改表是要完整的加上相应的注释，注释使用中文。
-- 涉及删除文件、删除结果、清空数据库时，必须有二次确认、操作日志和回滚说明。
-- 测试过程中生成的临时文件无需留存。
-
-## 环境
-- 使用 .env.example 做为环境的配置
-
-### 前端规则
-
-### 后端规则
-- 所有类型为大驼峰格式，变量名为小驼峰格式
-- 代码采用四层结构完成，包括 controller，service，mapper，domain。
-- controller层为接口申明，为前端提供接口。
-- service层为业务逻辑的接口，其中子文件impl，为业务逻辑接口的实现层，专门写业务逻辑。
-- mapper层包括mapper接口和mapper的xml文件，用户操作数据库。
-- domain层包括各个pojo类。
-- 所有的方法参数不允许使用map，需创建对应的dto类。
-- 使用@RequiredArgsConstructor完成依赖注入
-
-## 数据库规则
-- 表名为小写，多个单词之间用下划线"_"连接。
-- 数据库建表或修改表结构后，将最终的建表语句保存在sql/xxx.sql中，xxx为对应数据库表名。
-
-## 输出规范
-- 采用标准的代码格式。
-
-## 完成标准
-- 修改了哪些文件。
-- 每个文件修改了什么。
-- 如何验证功能。
-- 是否涉及数据库 SQL。
-- 是否存在风险和回滚方式。
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..071e412
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,95 @@
+# 项目规则
+
+## 项目背景
+
+这是一个前后端分离的培训项目。
+
+## 技术栈
+
+- 前端：React 18、TypeScript、Vite
+- 后端：Spring Boot 3.4.5、Java 21、MyBatis-Plus
+- 数据库：MySQL 8
+- 缓存：Redis
+
+## 工作规则
+
+- 所有文件使用 UTF-8 编码，避免中文乱码。
+- 修改代码前，先阅读项目结构和相关文件。
+- 修改前说明将影响哪些文件。
+- 修改后给出启动命令和测试步骤。
+- 不要把所有功能堆在一个页面或一个文件中。
+- 建表或修改表结构时，补充完整的中文注释。
+- 涉及删除文件、删除数据或清空数据库时，必须先二次确认，并提供操作日志和回滚说明。
+
+## 环境
+
+- 使用 `.env.example` 作为环境配置参考。
+- 不要将密码、令牌或其他敏感信息写入代码、日志或提交内容。
+
+## 前端规则
+
+- 遵循现有组件、路由、状态管理和样式规范。
+- 保持组件职责清晰，避免创建过大的组件。
+- 修改用户界面时验证桌面端和移动端布局。
+
+## 后端规则
+
+- 类型名使用大驼峰，变量名和方法名使用小驼峰。
+- 采用四层结构：`controller`、`service`、`mapper`、`domain`。
+- `controller` 层声明接口，为前端提供 API。
+- `service` 层声明业务接口，`impl` 子目录负责实现业务逻辑。
+- `mapper` 层包含 Mapper 接口和 XML 文件，负责数据库操作。
+- `domain` 层包含 POJO、DTO 等领域对象。
+- 方法参数不要使用 `Map`；需要结构化参数时创建对应的 DTO 类。
+- 使用 Lombok 的 `@RequiredArgsConstructor` 完成依赖注入。
+
+## API 规范
+
+- 接口路径使用版本前缀，例如 `/api/v1/`、`/api/v2/`；新增不兼容变更时升级主版本。
+- 接口命名使用“动词 + 名词”表达操作和资源，例如 `POST /api/v1/users`。
+- 接口成功响应统一使用以下结构：
+
+    ```json
+    {
+        "code": 200,
+        "message": "success",
+        "data": {}
+    }
+    ```
+
+- 错误码集中定义并保持全局唯一；不要在业务代码中散落硬编码错误码和错误信息。
+- 分页接口统一使用 `page`、`pageSize` 请求参数，并在响应中提供 `total` 总条数；分页数据放在 `data` 中。
+- 需要认证的接口通过 `Authorization: Bearer <token>` 传递凭证。
+- JSON 请求和响应使用 `Content-Type: application/json`，并根据实际内容设置 `Accept` 请求头。
+- 新增接口时同步明确 HTTP 方法、路径、请求头、请求参数、响应结构、错误码和版本归属。
+
+## 数据库规则
+
+- 表名使用大写，多个单词之间使用下划线连接，例如 `USER_PROFILE`。
+- 新建或修改表结构后，将最终建表语句保存到 `sql/<表名>.sql`。
+- SQL 中为表和字段补充清晰的中文注释。
+- 数据库写操作前先确认目标、范围、影响行数和回滚方式。
+
+## 输出规范
+
+- 使用标准代码格式。
+- 完成时说明：修改了哪些文件、每个文件的变化、验证方法、是否涉及 SQL，以及风险和回滚方式。
+
+## 通用约束
+
+### 语言规范（不可变）
+
+- 文档和代码注释必须使用中文。
+- 变量名、函数名、类名和其他代码标识符仍使用英文，并遵循对应语言的命名规范。
+
+### 可观测性与兜底
+
+- 任务必须具备完整链路：任务 ID、关联引用和关键日志。
+- 失败时必须提供明确的兜底提示，并支持合理的重试机制。
+- 日志不得记录密码、令牌或其他敏感信息。
+
+### 占位元素
+
+- 图标或图片资源尚未确定时，使用占位 `div` 并添加 `TODO` 注释。
+- 禁止使用临时 SVG、临时占位图服务或未授权的外部图片作为占位元素。
+- 占位元素必须明确标记最终资源的替换位置。
diff --git a/frontend/AGENTS.md b/frontend/AGENTS.md
new file mode 100644
index 0000000..2246ca8
--- /dev/null
+++ b/frontend/AGENTS.md
@@ -0,0 +1,143 @@
+# 前端开发规则
+
+## 技术栈
+
+- 使用 React 18、TypeScript 和 Vite。
+- UI 组件库使用 shadcn/ui。
+- 样式使用 Tailwind CSS；新增样式优先使用 Tailwind 工具类和主题变量。
+- 图标使用 Lucide React，禁止手写重复的图标 SVG。
+- 优先使用项目现有依赖；引入新依赖前说明必要性和影响。
+
+## 项目结构（不可变）
+
+前端源码必须遵循以下目录结构：
+
+```text
+src/
+├── assets/        # 静态资源
+├── components/    # 可复用 UI 组件
+├── constants/     # 业务常量、枚举
+├── hooks/         # 自定义 Hook
+├── http/          # 请求封装
+├── interfaces/    # 类型声明（model、api）
+├── routes/        # 路由页面
+├── stores/        # 全局状态，按业务拆分
+├── utils/         # 工具函数
+└── 根级入口文件
+```
+
+结构约束：
+
+- 常量必须放在 `constants/`，状态必须放在 `stores/`，接口类型必须放在 `interfaces/`。
+- `interfaces/` 下按业务模块组织类型；每个模块至少包含 `model.ts` 和 `api.ts`。
+- 可复用组件放在 `components/`；仅供单个路由使用的组件放在 `routes/<name>/components/`。
+- 路由页面必须放在 `routes/` 下；每个路由模块包含 `Page`、`Loader` 和 `index.module.scss`。
+- 新增文件前先确认其职责与目录匹配，不得为了方便将业务代码放入根级入口文件。
+
+## 组件规范
+
+### 组件结构
+
+- 组件必须放在 `src/components/` 或对应路由的 `components/` 目录下，每个组件使用独立目录。
+- 组件目录至少包含 `index.tsx` 和 `index.module.scss`。
+- 组件样式必须使用 SCSS Modules，禁止新增全局样式。
+- Props 必须定义明确的 TypeScript 接口，禁止使用隐式或无类型 Props。
+- 使用 `classnames` 管理动态 class；不要通过字符串拼接维护复杂 class 列表。
+
+### 组件层级
+
+- 页面级组件：仅单页使用时，放在 `routes/<page>/components/`。
+- 通用组件：跨页面复用时，放在 `src/components/`。
+- 单个文件建议不超过 400 行；超过后应根据职责拆分为更小的组件或工具模块。
+
+## 编码规范
+
+### TypeScript
+
+- 所有前端源码必须使用 TypeScript，禁止新增 JavaScript 文件。
+- 禁止使用 `any`；确有必要时必须说明理由并添加代码注释。
+- 接口和类型使用 PascalCase 命名；组件 Props 必须定义清晰、完整的接口。
+
+### 命名
+
+| 类型         | 规则       | 示例                   |
+| ------------ | ---------- | ---------------------- |
+| 文件夹、路由 | kebab-case | `user-profile`         |
+| 变量、函数   | camelCase  | `userList`、`onSubmit` |
+| 常量         | UPPER_CASE | `API_TIMEOUT`          |
+| 接口、类     | PascalCase | `UserInfo`             |
+| React 组件   | PascalCase | `UserProfile`          |
+| 自定义 Hook  | `use` 开头 | `useUserStore`         |
+
+### 业务函数
+
+- 事件处理函数使用 `onXxx` 命名，例如 `onSubmit`。
+- 组件或业务内部处理函数使用 `handleXxx` 命名，例如 `handleDelete`。
+
+## 文档规范
+
+### 注释规范
+
+- 必要注释统一使用 JSDoc（`/** ... */`）格式。
+- 注释重点解释设计原因、业务约束和非显而易见的取舍，不要重复代码本身表达的内容。
+- 文件头、函数或方法、复杂逻辑块和类型定义应根据需要补充说明。
+- 注释必须使用中文；代码标识符仍使用英文命名。
+
+## 路由规范（不可变）
+
+### 路由结构
+
+- 路由目录必须位于 `src/routes/` 下，每个页面使用独立目录，目录名使用 kebab-case。
+- 每个页面目录必须包含 `Page.tsx`、`Loader.tsx` 和 `index.module.scss`。
+- `Loader.tsx` 只负责懒加载对应的 `Page.tsx`，不得嵌套 `Routes` 或 `Route`。
+
+### 路由与菜单
+
+- 路由配置必须全局集中管理，禁止在多个文件中重复维护同一套路由。
+- 同一个页面只能在一处使用 `lazy` 引入；菜单、面包屑等导航数据引用统一的路由配置。
+
+## 状态管理规范（不可变）
+
+### 基础规范
+
+- 必须使用项目约定的状态库（例如 Zustand）管理全局状态。
+- 所有 store 必须放在 `src/stores/` 下，禁止在 `src/` 的其他目录中存放 store。
+
+### Store 组织
+
+- 按业务模块划分 store，每个业务模块使用独立文件。
+- 每个 store 对外暴露对应的 `useXxxStore` Hook。
+- Store 只负责数据和业务行为，不得耦合 UI 组件、页面结构或展示逻辑。
+- 需要持久化时使用 `persist` 等状态库中间件，并明确持久化字段范围。
+
+## 代码组织
+
+- 组件使用 PascalCase 命名，变量、函数和文件中的普通标识使用 camelCase。
+- 保持组件职责单一；页面、可复用组件、请求服务和类型定义分开组织。
+- 避免在 `App.tsx` 或单个组件中堆积所有业务逻辑。
+- 为组件 props、接口请求和响应定义明确的 TypeScript 类型，避免使用 `any`。
+- 复用逻辑优先提取为自定义 Hook 或独立工具函数。
+
+## API 调用
+
+- API 路径遵循根目录 `AGENTS.md` 中的版本和响应规范。
+- 请求地址、认证信息和环境差异通过 `.env.example` 中定义的 Vite 环境变量配置。
+- 不在源码中硬编码密码、令牌或生产环境地址。
+- 统一处理加载、成功、空数据和错误状态。
+
+## 样式与交互
+
+- 优先复用现有样式和设计约定，避免为单个页面重复定义相同样式。
+- 样式必须使用 SCSS Modules，组件样式文件命名为 `index.module.scss`；动态 class 使用 `classnames` 管理。
+- 自定义样式中的主色、文本、背景、边框等颜色必须使用主题 CSS 变量，禁止硬编码颜色值。
+- 优先使用 `var(--ant-color-xxx)`；项目已有自定义主题变量时使用 `var(--xxx)`。
+- 新增颜色变量时同步考虑浅色和暗色主题的取值，确保主题切换后的对比度和视觉一致性。
+- 保证桌面端和移动端布局可用，避免固定宽度导致内容溢出。
+- 表单和按钮提供清晰的禁用、提交中和错误状态。
+- 交互文案、错误提示和空状态使用清晰、面向用户的中文描述。
+
+## 验证
+
+- 修改后至少运行 `npm run build`。
+- 涉及页面或交互修改时，使用 `npm run dev` 手动验证主要流程和响应式布局。
+- 提交前检查浏览器控制台无新增错误或警告。