# 3.11 常见问题与排错

## 后端问题

### Q: 新增接口返回 401

A: 检查以下几点：
1. 请求头是否携带 `Authorization: Bearer <token>`
2. Token 是否过期（默认 2 小时）
3. 路由是否在 `route/app.php` 的需认证组中

### Q: 新增接口返回 403

A: 权限不足，检查：
1. 是否在 Controller 方法上添加了 `#[Permission]` 注解
2. 权限码是否在菜单管理中配置
3. 用户角色是否包含该权限节点

### Q: 枚举显示名（typeText/statusText）为空

A: 检查：
1. 字典表中是否存在对应的字典编码（如 `example_type`）
2. 字典项的 value 值是否与数据中的值匹配
3. Logic 中 `serializeMaps` 配置是否正确

```php
// ExampleLogic 中的配置

/**
 * 枚举显示名映射
 *
 * @var array
 */
protected array $serializeMaps = [
    'type'   => 'example_type',
    'status' => 'example_status',
];
```

### Q: 文件上传后 avatar 路径为空

A: 检查：
1. `.env` 中 `FILE.UPLOAD_DIR` 是否配置
2. 上传目录是否存在且有写入权限
3. Logic 中是否配置了 `fileFields`

```php
// ExampleLogic 中的配置
protected array $fileFields = ['avatar'];
protected string $fileSaveDir = 'example';
```

### Q: 排序不生效

A: 检查 Logic 中 `pageOrderBy` 配置：

```php
// ExampleLogic 中的配置
protected array $pageOrderBy = ['field' => 'sort', 'type' => 'asc'];
```

前端可通过 `orderField` 和 `orderType` 参数覆盖默认排序。

## 前端问题

### Q: 菜单不显示

A: 检查：
1. 后端菜单管理中是否添加了对应菜单
2. 菜单的组件路径是否正确（如 `tool/example/index`）
3. 前端 `views` 目录下是否有对应的 `.vue` 文件
4. 用户角色是否包含该菜单权限

### Q: API 请求 404

A: 检查：
1. `route/app.php` 中是否注册了对应路由
2. 路由路径是否与前端 API 模块中的 `url` 一致
3. HTTP 方法是否正确（GET/POST/PUT/DELETE）

### Q: 表格数据不显示

A: 检查：
1. API 返回的数据结构是否正确（应包含 `records` 和 `total`）
2. 前端是否正确绑定了 `tableData`
3. 浏览器控制台是否有报错

### Q: 导入失败

A: 检查：
1. 文件格式是否为 `.xls` 或 `.xlsx`
2. 表头是否与 `headerMap` 中定义的中文名一致
3. 枚举字段的值是否在字典中存在