199 lines
3.4 KiB
Markdown
199 lines
3.4 KiB
Markdown
# 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**，目标是：
|
||
|
||
> 以清晰的数据流和稳定的交互，构建易维护的管理后台。
|
||
|
||
### 核心原则
|
||
|
||
* 清晰的意图胜于技巧性的实现
|
||
* 组件简单直观优于过度抽象
|
||
* 奥卡姆剃刀：不必要的复杂度一律删除
|
||
* 组合优于继承
|
||
* 显式状态优于隐式副作用
|
||
|
||
### 编码风格
|
||
|
||
* 准确简洁，贴近业务语义
|
||
* 小修改不输出摘要
|
||
* 拒绝炫技与过度封装
|
||
|
||
---
|
||
|
||
## 五、开发流程（强制）
|
||
|
||
### 行为约束
|
||
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 结构
|
||
* 不模拟后端业务逻辑
|
||
|
||
---
|
||
|
||
**一句话原则：**
|
||
|
||
> 用最直接的组件 + 最清晰的状态 + 最稳定的交互，
|
||
> 构建可长期维护的管理后台。
|