签入版本

2026-09-29 10:14:04 +08:00
parent 3e5fc01124
commit d6b552103d
1664 changed files with 298944 additions and 0 deletions
@@ -0,0 +1,93 @@
+# 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. 枚举字段的值是否在字典中存在