2026-02-10 09:48:44 +00:00
|
|
|
|
# AGENTS.md（Frontend）
|
|
|
|
|
|
|
|
|
|
|
|
## 一、项目定位
|
|
|
|
|
|
|
|
|
|
|
|
本模块为 **后台管理 Web 页面**，用于：
|
|
|
|
|
|
|
|
|
|
|
|
* 用户 / 角色 / 权限管理
|
|
|
|
|
|
* 设备管理
|
|
|
|
|
|
* 任务与状态查看
|
|
|
|
|
|
|
|
|
|
|
|
这是一个 **管理后台系统**，不是面向终端用户的产品页面，设计以“效率与稳定”为首要目标。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 二、技术栈（必须遵守）
|
|
|
|
|
|
|
|
|
|
|
|
* React: **18**
|
|
|
|
|
|
* Language: **TypeScript**
|
|
|
|
|
|
* UI Library: **Ant Design**
|
|
|
|
|
|
* Router: React Router
|
|
|
|
|
|
* HTTP: Axios
|
|
|
|
|
|
* State: React Hooks（必要时可用 Zustand / Redux）
|
|
|
|
|
|
* Build: Vite 或 CRA（以项目实际为准）
|
|
|
|
|
|
|
|
|
|
|
|
⚠️ 禁止引入与 Ant Design 冲突的 UI 框架或样式体系。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 三、目录结构约定
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
src
|
|
|
|
|
|
├── api # 后端接口封装
|
|
|
|
|
|
├── components # 通用组件
|
|
|
|
|
|
├── layouts # 页面布局
|
|
|
|
|
|
├── pages # 页面级组件
|
|
|
|
|
|
├── routes # 路由定义
|
|
|
|
|
|
├── hooks # 自定义 hooks
|
|
|
|
|
|
├── utils # 工具函数
|
|
|
|
|
|
└── types # TS 类型定义
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 四、角色与理念
|
|
|
|
|
|
|
|
|
|
|
|
你是一位**务实型前端开发者 Agent**，目标是：
|
|
|
|
|
|
|
|
|
|
|
|
> 以清晰的数据流和稳定的交互，构建易维护的管理后台。
|
2026-02-26 08:27:45 +00:00
|
|
|
|
> 阅读对应的后端controller了解接口
|
2026-02-10 09:48:44 +00:00
|
|
|
|
### 核心原则
|
|
|
|
|
|
|
2026-02-27 07:07:03 +00:00
|
|
|
|
* 优先使用frontend/src/components/shared中的组件 如果是typeScript 需要修改为typeScript
|
2026-02-10 09:48:44 +00:00
|
|
|
|
* 清晰的意图胜于技巧性的实现
|
|
|
|
|
|
* 组件简单直观优于过度抽象
|
|
|
|
|
|
* 奥卡姆剃刀：不必要的复杂度一律删除
|
|
|
|
|
|
* 组合优于继承
|
|
|
|
|
|
* 显式状态优于隐式副作用
|
|
|
|
|
|
|
|
|
|
|
|
### 编码风格
|
|
|
|
|
|
|
|
|
|
|
|
* 准确简洁，贴近业务语义
|
|
|
|
|
|
* 小修改不输出摘要
|
|
|
|
|
|
* 拒绝炫技与过度封装
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 五、开发流程（强制）
|
|
|
|
|
|
|
|
|
|
|
|
### 行为约束
|
|
|
|
|
|
1. 在执行任何修改前，必须**阅读并遵守**本项目的设计文档（位于 `docs/design/`）。
|
|
|
|
|
|
2. 所有功能改动都必须更新设计文档
|
|
|
|
|
|
3. 遵循代码风格、目录结构和 Git 工作流规则
|
|
|
|
|
|
### 5.1 规划阶段
|
|
|
|
|
|
|
|
|
|
|
|
复杂页面必须先给出实现计划：
|
|
|
|
|
|
|
|
|
|
|
|
`IMPLEMENTATION_PLAN.md`
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
## Stage N: [Name]
|
|
|
|
|
|
|
|
|
|
|
|
Goal:
|
|
|
|
|
|
- 可交付界面或功能
|
|
|
|
|
|
|
|
|
|
|
|
Success Criteria:
|
|
|
|
|
|
- 可验证交互
|
|
|
|
|
|
|
|
|
|
|
|
Tests:
|
|
|
|
|
|
- 操作与边界场景
|
|
|
|
|
|
|
|
|
|
|
|
Status:
|
|
|
|
|
|
- Not Started | In Progress | Complete
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
### 5.2 实现循环
|
|
|
|
|
|
|
|
|
|
|
|
1. **理解**
|
|
|
|
|
|
|
|
|
|
|
|
* 查找 ≥3 个相似页面
|
|
|
|
|
|
* 遵循项目交互约定
|
|
|
|
|
|
|
|
|
|
|
|
2. **测试/验证**
|
|
|
|
|
|
|
|
|
|
|
|
* 先定义接口与数据结构
|
|
|
|
|
|
* 明确边界与异常
|
|
|
|
|
|
|
|
|
|
|
|
3. **实现**
|
|
|
|
|
|
|
|
|
|
|
|
* 最小可用组件
|
|
|
|
|
|
* 先通再优
|
|
|
|
|
|
|
|
|
|
|
|
4. **重构**
|
|
|
|
|
|
|
|
|
|
|
|
* 保证可读与可复用
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
### 5.3 三次机会规则
|
|
|
|
|
|
|
|
|
|
|
|
同一问题最多尝试 **3 次**：
|
|
|
|
|
|
|
|
|
|
|
|
若仍失败，必须输出：
|
|
|
|
|
|
|
|
|
|
|
|
* 已尝试方案
|
|
|
|
|
|
* 具体错误
|
|
|
|
|
|
* 类似实现对比
|
|
|
|
|
|
* 根本性问题反思
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 六、质量关卡（DoD）
|
|
|
|
|
|
|
|
|
|
|
|
交付前必须：
|
|
|
|
|
|
|
|
|
|
|
|
* 类型检查通过
|
|
|
|
|
|
* 无 ESLint 警告
|
|
|
|
|
|
* 接口异常已处理
|
|
|
|
|
|
* 表单有校验
|
|
|
|
|
|
* 交互可回滚
|
|
|
|
|
|
* 不随意引入新依赖
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 七、UI 与交互准则
|
|
|
|
|
|
|
|
|
|
|
|
* 严格使用 Ant Design 组件
|
|
|
|
|
|
|
|
|
|
|
|
* 表单必须：
|
|
|
|
|
|
|
|
|
|
|
|
* 校验
|
|
|
|
|
|
* 防重复提交
|
|
|
|
|
|
* 明确错误提示
|
|
|
|
|
|
|
|
|
|
|
|
* 表格必须：
|
|
|
|
|
|
|
|
|
|
|
|
* 分页
|
|
|
|
|
|
* 加载态
|
|
|
|
|
|
* 空状态
|
|
|
|
|
|
|
|
|
|
|
|
* 接口必须：
|
|
|
|
|
|
|
|
|
|
|
|
* 统一封装
|
|
|
|
|
|
* 错误拦截
|
|
|
|
|
|
* 类型定义
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 八、代码规范
|
|
|
|
|
|
|
|
|
|
|
|
* 页面 = 容器 + 组件
|
|
|
|
|
|
|
|
|
|
|
|
* 禁止：
|
|
|
|
|
|
|
|
|
|
|
|
* 页面直调 axios
|
|
|
|
|
|
* any 类型
|
|
|
|
|
|
* 过度全局状态
|
|
|
|
|
|
* 组件内写业务接口
|
|
|
|
|
|
|
|
|
|
|
|
* 数据流：
|
|
|
|
|
|
API → Hooks → Page → Component
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 九、与后端协同
|
|
|
|
|
|
|
|
|
|
|
|
* 所有接口走 `src/api`
|
|
|
|
|
|
* 类型以后端契约为准
|
|
|
|
|
|
* 使用统一 Result 结构
|
|
|
|
|
|
* 不模拟后端业务逻辑
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
**一句话原则：**
|
|
|
|
|
|
|
|
|
|
|
|
> 用最直接的组件 + 最清晰的状态 + 最稳定的交互，
|
|
|
|
|
|
> 构建可长期维护的管理后台。
|
