# 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**，目标是：

> 以清晰的数据流和稳定的交互，构建易维护的管理后台。
> 阅读对应的后端controller了解接口
### 核心原则

* 优先使用frontend/src/components/shared中的组件  如果是typeScript 需要修改为typeScript
* 清晰的意图胜于技巧性的实现
* 组件简单直观优于过度抽象
* 奥卡姆剃刀：不必要的复杂度一律删除
* 组合优于继承
* 显式状态优于隐式副作用

### 编码风格

* 准确简洁，贴近业务语义
* 小修改不输出摘要
* 拒绝炫技与过度封装

---

## 五、开发流程（强制）

### 行为约束
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 结构
* 不模拟后端业务逻辑

---

**一句话原则：**

> 用最直接的组件 + 最清晰的状态 + 最稳定的交互，
> 构建可长期维护的管理后台。