教训：PostgreSQL 事务内错误导致员工 APP 登录失败

记录日期：2026-02-05

Bug PostgreSQL Backend

1. 问题现象

用 curl 直接测试后端 API，返回 500 内部错误：

$ curl -X POST http://localhost:3000/api/auth/employee/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test.superadmin@qqnails.com","password":"test123","tenantId":"qqnails"}'

{
  "success": false,
  "error": {
    "code": "E1003",
    "type": "COMMON_INTERNAL_ERROR",
    "message": "Login failed, please try again later"
  }
}

关键发现：这不是账号密码错误（401），而是服务器内部错误（500），说明问题出在后端逻辑。

2. 定位过程

第一步：确认 APP 请求路径

排查 APP 端代码，确认请求链路：

• API Base URL: http://localhost:3000/api（env_config.dart）
• Login Endpoint: /auth/employee/login（api_endpoints.dart）
• 完整 URL: http://localhost:3000/api/auth/employee/login
• 后端路由挂载: app.use('/api/auth/employee', ...)（server.js:1082）

路径匹配正确，排除了路由问题。

第二步：确认后端服务状态

$ curl http://localhost:3000/api/health
→ 200 OK

后端正在运行，排除了服务未启动的问题。

第三步：检查 iOS ATS 限制

检查了 Info.plist 是否缺少 NSAppTransportSecurity 配置。 但 iOS 模拟器对 localhost 有 ATS 豁免，所以这不是问题。

第四步：直接测试 API 并查看日志

用 curl 测试 API 得到 500 错误后，通过 pm2 logs 查看后端日志，发现了关键线索：

[Login Debug] 密码验证结果: true
[RBAC] 高级角色获取所有店铺: { role: 'super_admin', storeCount: 9 }
📝 令牌签发记录: { userId: 'e2e_test_superadmin', tokenType: 'access' }
📝 令牌签发记录: { userId: 'e2e_test_superadmin', tokenType: 'refresh' }

[error]: 员工登录错误 current transaction is aborted,
         commands ignored until end of transaction block
    → at EmployeeAuthController.login (employee_auth_controller.js:348)

密码验证成功了，token 也生成了，但在第 348 行（UPDATE employees SET last_login_at）崩了。

3. 根本原因

问题出在 employee_auth_controller.js 第 296-307 行：

// 在 BEGIN 事务内部...

// 查询是否已设置 PIN（兼容未部署 time-clock 表结构的环境）
try {
  const pinResult = await client.query(
    'SELECT 1 FROM employee_pins WHERE employee_id = $1 LIMIT 1',
    [employee.id]
  );
  hasPinSetup = pinResult.rows.length > 0;
} catch (pinError) {
  if (pinError?.code !== '42P01') {  // 42P01 = 表不存在
    throw pinError;
  }
  hasPinSetup = false;  // 吞掉错误，继续执行
}

这段代码的意图是好的：如果 employee_pins 表还没创建（time-clock 功能还没部署），就忽略错误，默认 PIN 未设置。

但它犯了一个关键错误：JavaScript 的 try-catch 只能控制 JavaScript 的执行流，无法修复 PostgreSQL 事务的状态。

所以虽然 JavaScript 层面的代码继续执行了，但数据库连接上的事务已经废了，后面的 UPDATE 和 COMMIT 全部会失败。

4. 执行时序分析

5. 三种修复方案

方案一：SAVEPOINT（事务存档点）

原理

SAVEPOINT 是 PostgreSQL 提供的"事务内存档机制"。 你可以在危险操作前设一个存档点，如果操作失败，回滚到存档点而不是回滚整个事务，事务继续保持健康状态。

代码示意

// 在查询 employee_pins 之前设置存档点
await client.query('SAVEPOINT before_pin_check');

try {
  const pinResult = await client.query(
    'SELECT 1 FROM employee_pins WHERE employee_id = $1 LIMIT 1',
    [employee.id]
  );
  hasPinSetup = pinResult.rows.length > 0;
  // 成功则释放存档点（可选）
  await client.query('RELEASE SAVEPOINT before_pin_check');
} catch (pinError) {
  // 失败则回滚到存档点，事务恢复健康
  await client.query('ROLLBACK TO SAVEPOINT before_pin_check');
  hasPinSetup = false;
}

SQL 层面发生了什么

BEGIN;
  ... 前面的操作都正常 ...
  SAVEPOINT before_pin_check;            -- 设存档点
  SELECT 1 FROM employee_pins ...;       -- 如果失败...
  ROLLBACK TO SAVEPOINT before_pin_check;-- 回到存档点，事务恢复
  UPDATE employees SET last_login_at ... -- 可以正常执行！
COMMIT;                                   -- 成功！

优点

• 改动最小：只需在现有代码前后加 3 行
• 精确控制：只撤销出问题的那一步，不影响其他
• PostgreSQL 官方推荐的事务内错误恢复方式

缺点

• 需要了解 SAVEPOINT 概念，后续维护的人可能不熟悉
• 多了 2-3 次数据库往返（性能影响微乎其微）

方案二：先检查表是否存在

原理

在执行可能出错的查询之前，先去 PostgreSQL 的系统目录（information_schema）查一下目标表存不存在。 如果不存在就直接跳过，根本不执行那条会报错的 SQL，事务始终保持健康。

代码示意

// 先检查表是否存在
const tableCheck = await client.query(`
  SELECT EXISTS (
    SELECT 1 FROM information_schema.tables
    WHERE table_schema = $1 AND table_name = 'employee_pins'
  ) AS exists
`, [schemaName]);

if (tableCheck.rows[0].exists) {
  const pinResult = await client.query(
    'SELECT 1 FROM employee_pins WHERE employee_id = $1 LIMIT 1',
    [employee.id]
  );
  hasPinSetup = pinResult.rows.length > 0;
} else {
  hasPinSetup = false;
}

优点

• 最直观：逻辑清楚——"有表就查，没表就跳过"
• 完全避免错误：事务内不会触发任何 SQL 错误
• 好维护：任何开发者一看就懂

缺点

• 每次登录都多一次 information_schema 查询
• 理论上存在微小的时间窗口问题（查完"表存在"到实际查询之间表可能被删，实际中不会发生）
• 如果项目里有多个类似的"可能不存在的表"，代码里会到处都是这种检查

方案三：把 PIN 查询移到事务外面

原理

重新审视事务的范围——哪些操作真正需要原子性保证，哪些不需要。

查询 employee_pins 只是为了给前端返回一个 hasPinSetup 布尔值， 它和"验证密码、更新登录时间"等操作之间没有原子性要求。 把它移到事务 COMMIT 之后单独查询，即使失败也不影响登录。

代码示意

// ---- 事务内 ----
await client.query('BEGIN');
  // ... 查租户、查员工、验密码、查店铺 ...
  // ... 更新 last_login_at ...
await client.query('COMMIT');

// ---- 事务外（COMMIT 之后） ----
let hasPinSetup = false;
try {
  const pinResult = await client.query(
    'SELECT 1 FROM employee_pins WHERE employee_id = $1 LIMIT 1',
    [employee.id]
  );
  hasPinSetup = pinResult.rows.length > 0;
} catch (e) {
  hasPinSetup = false;  // 查不到就算了，不影响登录
}

// 生成 token，返回响应...
res.json({ success: true, data: { ..., has_pin_setup: hasPinSetup } });

优点

• 从根本上消除问题：不在事务内查可能不存在的表，事务永远不会被污染
• 逻辑更清晰：事务只包含必须原子执行的操作，职责分离更好
• 最健壮：即使 PIN 查询出任何异常，登录流程都不受影响

缺点

• 改动相对大一些，需要调整代码结构
• 需要注意 COMMIT 之后 client 的 search_path 是否还是 tenant_qqnails（通常是的，因为 search_path 是 session 级别设置，不受事务回滚影响）

6. 方案对比

7. 知识补充：PostgreSQL 事务机制

7.1 什么是数据库事务

事务（Transaction）是一组数据库操作的"打包"，具有 ACID 四个特性：

7.2 PostgreSQL vs MySQL 的事务错误处理

示例对比：

-- PostgreSQL 行为
BEGIN;
  INSERT INTO orders (id) VALUES (1);    -- OK
  INSERT INTO orders (id) VALUES (1);    -- 主键冲突，报错！
  INSERT INTO orders (id) VALUES (2);    -- 被拒绝！(25P02)
COMMIT;                                   -- 也失败，实际等于 ROLLBACK

-- MySQL 行为
START TRANSACTION;
  INSERT INTO orders (id) VALUES (1);    -- OK
  INSERT INTO orders (id) VALUES (1);    -- 主键冲突，报错
  INSERT INTO orders (id) VALUES (2);    -- 继续执行，成功！
COMMIT;                                   -- 成功（1 和 2 都插入了）

7.3 SAVEPOINT 详解

SAVEPOINT 是 SQL 标准的一部分，用于在事务内创建"存档点"。

BEGIN;
  -- 正常操作
  INSERT INTO users (name) VALUES ('Alice');

  SAVEPOINT my_savepoint;        -- 创建存档点

  -- 可能失败的操作
  INSERT INTO logs (msg) VALUES ('...');  -- 如果这里失败...

  ROLLBACK TO my_savepoint;      -- 回到存档点（只撤销 logs 的插入）
                                  -- users 的插入仍然有效！
                                  -- 事务恢复到 "idle in transaction" 状态

  RELEASE SAVEPOINT my_savepoint; -- 释放存档点（可选）

  -- 可以继续正常操作
  INSERT INTO users (name) VALUES ('Bob');

COMMIT;  -- 成功！Alice 和 Bob 都插入了

7.4 事务状态机

PostgreSQL 事务有以下状态（可以用 SELECT txid_current_if_assigned() 等方式间接观察）：

7.5 search_path 和事务的关系

我们的代码里在事务内执行了 SET search_path TO tenant_qqnails, public。需要知道：

• SET search_path 是 session 级别的设置，不属于事务
• 即使事务 ROLLBACK，search_path 的改变不会被撤销
• 但如果使用 SET LOCAL search_path，则是事务级别的，ROLLBACK 会撤销

7.6 编程语言 try-catch vs 数据库事务

这个 bug 的本质是混淆了两个不同层面的错误处理：

8. 经验总结

1. 用 SAVEPOINT 保护——在可能失败的操作前后加存档点
2. 先检查再操作——确认条件满足后再执行
3. 移到事务外——如果操作不需要原子性保证，就不要放在事务里
4. 绝对不要只用 JavaScript try-catch 包住就以为没事了

涉及文件：

• backend/auth/employee_auth_controller.js 第 296-307 行（PIN 查询）
• backend/auth/employee_auth_controller.js 第 348 行（UPDATE 失败点）
• employee_mobile_app/lib/features/auth/（APP 端认证流程）