3.4 KiB

Raw Blame History

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

以清晰的数据流和稳定的交互，构建易维护的管理后台。

核心原则

清晰的意图胜于技巧性的实现
组件简单直观优于过度抽象
奥卡姆剃刀：不必要的复杂度一律删除
组合优于继承
显式状态优于隐式副作用

编码风格

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

五、开发流程（强制）

行为约束

在执行任何修改前，必须阅读并遵守本项目的设计文档（位于 docs/design/）。
所有功能改动都必须更新设计文档
遵循代码风格、目录结构和 Git 工作流规则

5.1 规划阶段

复杂页面必须先给出实现计划：

IMPLEMENTATION_PLAN.md

## Stage N: [Name]

Goal:
- 可交付界面或功能

Success Criteria:
- 可验证交互

Tests:
- 操作与边界场景

Status:
- Not Started | In Progress | Complete

5.2 实现循环

理解
- 查找 ≥3 个相似页面
- 遵循项目交互约定
测试/验证
- 先定义接口与数据结构
- 明确边界与异常
实现
- 最小可用组件
- 先通再优
重构
- 保证可读与可复用

5.3 三次机会规则

同一问题最多尝试 3 次：

若仍失败，必须输出：

已尝试方案
具体错误
类似实现对比
根本性问题反思

六、质量关卡（DoD）

交付前必须：

类型检查通过
无 ESLint 警告
接口异常已处理
表单有校验
交互可回滚
不随意引入新依赖

七、UI 与交互准则

严格使用 Ant Design 组件
表单必须：
- 校验
- 防重复提交
- 明确错误提示
表格必须：
- 分页
- 加载态
- 空状态
接口必须：
- 统一封装
- 错误拦截
- 类型定义

八、代码规范

页面 = 容器 + 组件
禁止：
- 页面直调 axios
- any 类型
- 过度全局状态
- 组件内写业务接口
数据流： API → Hooks → Page → Component

九、与后端协同

所有接口走 src/api
类型以后端契约为准
使用统一 Result 结构
不模拟后端业务逻辑

一句话原则：

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

3.4 KiB Raw Blame History Unescape Escape