sbnews/admin/AGENTS.md

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 请求

项目结构

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

运行命令

npm install
npm run dev
npm run build

---

并行协作协议

新功能开发时

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

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

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

Step 2: 并行实现

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

Step 3: 构建联调

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 留空。

近期踩坑

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