# Admin Agent — Sport Era 管理后台

Vue 3 + Vite + Element Plus 管理后台 SPA。**消费 `server/app/adminapi/controller/` 的接口。**

## 技术栈

- **Vue** 3 + **TypeScript**
- **Vite**
- **Element Plus**
- **Pinia** 状态管理
- **Vue Router** 路由
- **Axios** HTTP 请求

## 项目结构

```text
src/
├── main.ts                # 应用入口
├── App.vue                # 根组件
├── permission.ts          # 路由权限守卫
├── api/                   # 接口请求模块（→ 后端 /adminapi/*）
├── views/                 # 页面组件
├── layout/                # 布局组件
├── components/            # 公共组件
├── stores/                # Pinia Store
├── router/                # 路由配置
├── hooks/                 # 组合式函数
├── utils/                 # 工具函数
├── enums/                 # 枚举常量
├── config/                # 应用配置
├── styles/                # 全局样式
└── assets/                # 静态资源
```

## 运行命令

```bash
npm install
npm run dev
npm run build
```

---

## 并行协作协议

### 新功能开发时

#### Step 1: 等待或查阅后端 API 契约

查看 `server/app/adminapi/controller/` 下对应 controller，并结合 validate、logic、model 获取：

- 接口路径和方法
- 请求参数类型和必填项
- 响应数据结构
- 字段、状态、字典或配置来源

#### Step 2: 并行实现

```text
1. src/api/ 下新增或复用接口请求模块
2. src/views/ 下新增页面组件
3. 按现有路由/菜单机制配置页面入口
4. 如需菜单，配合后端菜单和权限节点
```

#### Step 3: 构建联调

```bash
npm run build
```

## 从后端 Agent 获取信息的方式

| 需要了解           | 查看位置                                          |
| ------------------ | ------------------------------------------------- |
| 接口路径/参数/响应 | `server/app/adminapi/controller/` 对应 controller |
| 参数校验           | `server/app/adminapi/validate/` 对应 validate     |
| 业务字段           | `server/app/common/model/` 对应 model             |
| 枚举/字典          | `server/app/common/enum/`、字典表、配置表         |
| Token 机制         | `server/app/common/cache/AdminTokenCache.php`     |

## 代码约定

- API 请求统一通过 `src/api/` 模块，沿用现有请求封装。
- 列表页复用现有搜索表单、表格、分页和批量操作风格。
- 表单页复用 `el-form`、`el-dialog`、上传组件等现有封装。
- 状态管理用 Pinia，Store 放在 `src/stores/`。
- 新增视图先参考同业务目录的已有页面风格。
- **禁止前端硬编码业务枚举**：优先从字典接口、配置接口或后端返回字段读取。
- 顶级菜单需配 icon，二级及以下菜单 icon 留空。

## 近期踩坑

- 后台表单新增字段时，不能只改页面输入项；要同时核对后端接口字段白名单、数据库列和保存逻辑，否则会出现“能填但存不进去”的假象。