fix: 将 admin 改为普通目录

2026-07-31 16:39:16 +08:00
parent e7f9328611
commit fdf8022662
592 changed files with 41318 additions and 1 deletions
@@ -0,0 +1,95 @@
+# 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 留空。
+
+## 近期踩坑
+
+- 后台表单新增字段时，不能只改页面输入项；要同时核对后端接口字段白名单、数据库列和保存逻辑，否则会出现“能填但存不进去”的假象。