# 常见问题与排错

本章汇总模块开发过程中的常见问题和解决方案。

## 后端问题

### Q1: 启动报错 `Table 'xxx.flask_position' doesn't exist`

**原因**：模型定义后未执行建表。

**解决**：

```bash
# 方式一：脚本自动建表
python scripts/setup_db.py

# 方式二：Flask-Migrate 迁移
flask db migrate -m "add position table"
flask db upgrade

# 方式三：手动建表（参考 model.md 中的 DDL）
```

### Q2: 接口返回 `{"code": 1, "msg": "权限不足"}`

**原因**：权限节点未配置或未分配给当前用户角色。

**排查步骤**：
1. 确认菜单管理中已添加权限节点，权限标识与代码中 `@check_permission` 完全一致
2. 确认权限节点已分配给当前用户的角色
3. 使用 admin 账号（ID=1）测试，admin 自动跳过权限校验

### Q3: 唯一性校验不生效

**原因**：Schema 中 `validate_` 方法的 `exists_by` 调用错误。

**排查步骤**：
1. 确认 Schema 类中定义了 `validate_{field_name}` 方法
2. 确认 `exists_by({'field': value}, exclude_id=current_id)` 参数正确
3. 确认调用的是 `service.add()` 或 `service.update()`，而非直接操作 repo

### Q4: 分页查询返回空数据

**原因**：分页参数名不匹配或字段配置错误。

**排查步骤**：
1. 前端传参名应为 `pageNo` 和 `pageSize`（驼峰）
2. 确认 Repository 的 `page()` 方法中 `filters` / `like_filters` 字段名与模型一致
3. 检查数据库中是否有数据（`is_delete=0` 的记录）

### Q5: 删除时报错 "存在引用"

**原因**：`before_delete` 钩子检测到关联数据。

**解决**：先调整引用该记录的其他数据，再执行删除。如岗位被用户引用时，需先修改用户的岗位字段。

### Q6: 批量删除报 500 错误

**原因**：`parse_id_list` 函数未正确导入或使用。

**解决**：确保正确导入并使用：

```python
from src.common.utils.request import parse_batch_ids

@position_blue.route('/batchDelete', methods=["DELETE"])
@check_permission("sys:position:batchDelete")
@check_demo
def batch_delete():
    id_str, err = parse_batch_ids()
    if err:
        return err
    count = position.delete_positions(id_str)
    return R.ok(msg=f"本次共删除{count}条数据")
```

## 前端问题

### 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. 确认 Repository 的 `page()` 方法中 `filters` / `like_filters` 配置了对应字段

### Q9: 编辑弹窗不回填数据

**原因**：`openModal` 未传入记录数据。

**解决**：

```javascript
// 正确：第一个参数 true 表示编辑模式，第二个参数是记录数据
openModal(true, record);
```

### Q10: 操作按钮不显示

**原因**：`v-perm` 权限标识与后端不一致。

**排查步骤**：
1. 确认 `v-perm` 中的权限字符串与后端 `@check_permission` 完全一致
2. 确认当前用户拥有对应权限
3. 检查 `TableAction` 中的 `auth` 字段是否正确

## 通用问题

### Q11: 接口返回 401 Unauthorized

**原因**：JWT Token 过期或未携带。

**解决**：
1. 确认请求头包含 `Authorization: Bearer <token>`
2. Token 过期后需调用刷新接口或重新登录
3. 前端 `VAxios` 自动处理 Token 注入，检查是否正确引入

### Q12: 接口返回 403 Forbidden（演示模式）

**原因**：演示模式下写操作被拦截。

**解决**：将 `.env` 中的 `FLASK_DEMO` 设为 `False`，或移除端点上的 `@check_demo` 装饰器（仅开发阶段）。

### Q13: 数据库字段中文乱码

**原因**：数据库或表的字符集不是 UTF-8。

**解决**：
- MySQL：确保数据库和表使用 `utf8mb4` 字符集
- PostgreSQL：建库时指定 `ENCODING 'UTF8'`

## 开发调试技巧

### 查看 SQL 日志

在 `.env` 中开启 SQL 调试：

```bash
DB_DEBUG=True
```

重启后所有 SQL 查询都会输出到控制台。

### 使用 Postman 调试

使用 Postman 或 curl 调试接口：
1. 先调用登录接口获取 Token
2. 在请求头中添加 `Authorization: Bearer <token>`
3. 调用业务接口

### 检查权限配置

如果不确定权限是否配置正确，可以用 admin 账号测试。admin（ID=1）自动跳过所有权限校验。

## 总结

模块开发常见问题主要集中在：字段类型不匹配、唯一性校验遗漏、软删除过滤缺失、分页参数命名不一致、权限节点未配置等。遇到问题时优先检查后端日志和接口返回值，确认接口入参和返回值是否符合预期。