本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：7月5日复制的资料/SQL一致性迁移计划.md。

SQL 一致性迁移计划

现状

Controller 中散落约 100+ 处 直接 SQL 调用（$db->query() / $db->fetchAll() / $db->fetchOne()），Helper 中也有少量。目标是：所有 SQL 统一封装在 Helpers 中，Controller 只调用 Helpers 方法，不出现 $db->。

原则

1. 不改功能，只搬家 — 每条 SQL 原样搬进 Helper，不改逻辑
2. 不改 Helper 原有方法签名 — 已在外被调用的方法保持兼容
3. 每次只动一个 Controller — 改完测完再改下一个
4. 插件不受影响 — Helper 公开方法不变

第一阶段：已有的 Helper 补充收尾（1-2 天）

当前 Helpers 已覆盖大部分业务，只需要把 Controller 里散落的同类 SQL 收进来。

第二阶段：Admin Controllers 专项（3-5 天）

后台 Controller 是 SQL 重灾区，按顺序处理：

第三阶段：前端 Controller 收尾（2-3 天）

迁移示例

以一个典型迁移为例：

// 改前 — ThreadController.php
$categories = $db->fetchAll('SELECT * FROM categories ORDER BY sort_order ASC');

// 改后 — ThreadController.php
$categories = (new \app\Models\Category())->allOrdered();

// 改前 — Admin/UserController.php
$adminCount = $db->fetchOne("SELECT COUNT(*) as cnt FROM users WHERE role = 'admin'");

// 改后 — Auth.php 加一个方法
public static function getAdminCount(): int
{
    $db = \app\Core\Database::getInstance();
    $r = $db->fetchOne("SELECT COUNT(*) as cnt FROM users WHERE role = 'admin'");
    return (int)($r['cnt'] ?? 0);
}

// Controller 调用
$adminCount = \app\Helpers\Auth::getAdminCount();

检验标准

每个 Controller 迁移完成后：

1. 全文搜索该 Controller，确认 零处 $db->query( / $db->fetchAll( / $db->fetchOne( / $db->exec(
2. 手动跑一遍对应页面的所有操作（列表、新增、编辑、删除）
3. 检查是否有 Undefined method 错误

全部完成后搜一次：

grep -r "\$db->query\|->fetchAll\|->fetchOne" app/Controllers/

结果应该为空。

总工作量估计

每天改 2-3 个 Controller，两周内可全部完成。不着急的话，一天改一个，一个月收工。