签入版本

DjangoAdmin_Tornado_NaiveVue/zh/volume2/faq.md

@@ -0,0 +1,169 @@
+# 常见问题与排错
+
+本章汇总模块开发过程中的常见问题和解决方案。
+
+## 后端问题
+
+### Q1: 启动报错 `Table 'xxx.tornado_position' doesn't exist`
+
+**原因**：模型定义后未执行建表。
+
+**解决**：
+
+```bash
+# 方式一：脚本自动建表
+python scripts/init_db.py
+
+# 方式二：Alembic 迁移
+alembic revision --autogenerate -m "add position table"
+alembic upgrade head
+
+# 方式三：手动建表（参考 model.md 中的 DDL）
+```
+
+### Q2: 接口返回 `{"code": 1, "msg": "权限不足"}`
+
+**原因**：权限节点未配置或未分配给当前用户角色。
+
+**排查步骤**：
+1. 确认菜单管理中已添加权限节点，权限标识与代码中 `@permission_required` 完全一致
+2. 确认权限节点已分配给当前用户的角色
+3. 使用 admin 账号（ID=1）测试，admin 自动跳过权限校验
+
+### Q3: 唯一性校验不生效
+
+**原因**：`unique_fields` 配置错误。
+
+**排查步骤**：
+1. 确认 key 是模型字段名（如 `name`），不是中文名
+2. 确认 Service 类中声明了 `unique_fields`
+3. 确认调用的是 `service.add()` 或 `service.update()`，而非直接操作 repo
+
+### Q4: 分页查询返回空数据
+
+**原因**：分页参数名不匹配或字段配置错误。
+
+**排查步骤**：
+1. 前端传参名应为 `pageNo` 和 `pageSize`（驼峰）
+2. 确认 `page_like_fields` 和 `page_eq_fields` 中的字段名与模型一致
+3. 检查数据库中是否有数据（`is_delete=0` 的记录）
+
+### Q5: 删除时报错 "存在引用"
+
+**原因**：`_before_delete` 钩子检测到关联数据。
+
+**解决**：先调整引用该记录的其他数据，再执行删除。如岗位被用户引用时，需先修改用户的岗位字段。
+
+### Q6: `batch_delete` 端点报 500 错误
+
+**原因**：Handler 方法未正确继承 `BaseHandler`。
+
+**解决**：批量删除 Handler 必须继承 `BaseHandler` 并使用 `async def`：
+
+```python
+class PositionBatchDeleteHandler(BaseHandler):
+    @permission_required("sys:position:delete")
+    @check_demo
+    async def post(self):
+        return await position_service.batch_delete(self)
+```
+
+## 前端问题
+
+### Q7: 页面白屏，控制台报 `Failed to fetch dynamically imported module`
+
+**原因**：路由组件路径配置错误。
+
+**排查步骤**：
+1. 确认路由中的 `component` 路径与实际文件路径一致
+2. 确认后端菜单的 `component` 字段值正确（如 `system/position/index`）
+3. 检查文件名大小写是否匹配
+
+### Q8: 搜索功能不生效
+
+**原因**：搜索表单的 `submit` 事件未正确绑定。
+
+**排查步骤**：
+1. 确认 `BasicForm` 绑定了 `@submit="handleSearch"` 事件
+2. 确认 `handleSearch` 中调用了 `reload({ searchInfo: values })`
+3. 确认后端 `page_like_fields` 和 `page_eq_fields` 配置了对应字段
+
+### Q9: 编辑弹窗不回填数据
+
+**原因**：`openModal` 未传入记录数据。
+
+**解决**：
+
+```javascript
+// 正确：第一个参数 true 表示编辑模式，第二个参数是记录数据
+openModal(true, record);
+```
+
+### Q10: 操作按钮不显示
+
+**原因**：`v-perm` 权限标识与后端不一致。
+
+**排查步骤**：
+1. 确认 `v-perm` 中的权限字符串与后端 `@permission_required` 完全一致
+2. 确认当前用户拥有对应权限
+3. 检查 `TableAction` 中的 `auth` 字段是否正确
+
+## 通用问题
+
+### Q11: 接口返回 401 Unauthorized
+
+**原因**：JWT Token 过期或未携带。
+
+**解决**：
+1. 确认请求头包含 `Authorization: Bearer <token>`
+2. Token 过期后需调用刷新接口或重新登录
+3. 前端 `defHttp` 自动处理 Token 注入，检查是否正确引入
+
+### Q12: 接口返回 403 Forbidden（演示模式）
+
+**原因**：演示模式下写操作被拦截。
+
+**解决**：将 `.env` 中的 `TORNADO_DEMO` 设为 `False`，或移除端点上的 `@check_demo` 装饰器（仅开发阶段）。
+
+### Q13: 数据库字段中文乱码
+
+**原因**：数据库或表的字符集不是 UTF-8。
+
+**解决**：
+- MySQL：确保数据库和表使用 `utf8mb4` 字符集
+- PostgreSQL：建库时指定 `ENCODING 'UTF8'`
+
+## 开发调试技巧
+
+### 查看 SQL 日志
+
+在 `.env` 中开启 SQL 调试：
+
+```bash
+DB_DEBUG=True
+```
+
+重启后所有 SQL 查询都会输出到控制台。
+
+### 使用 curl 调试
+
+使用 curl 或 Postman 等工具直接测试接口：
+
+```bash
+# 登录获取 Token
+curl -X POST http://127.0.0.1:8041/api/v1/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"123456","code":"xxxx","key":"xxxx"}'
+
+# 携带 Token 调用业务接口
+curl http://127.0.0.1:8041/api/v1/position/page \
+  -H "Authorization: Bearer <token>"
+```
+
+### 检查权限配置
+
+如果不确定权限是否配置正确，可以用 admin 账号测试。admin（ID=1）自动跳过所有权限校验。
+
+## 总结
+
+模块开发常见问题主要集中在：字段类型不匹配、唯一性校验遗漏、软删除过滤缺失、分页参数命名不一致、权限节点未配置等。遇到问题时优先检查后端日志，确认接口入参和返回值是否符合预期。