medical-mall/docs/ops/2026-02-05__auth__fix-login-registration-sync.md

操作文档：修复登录注册与数据同步全链路问题

• 日期: 2026-02-05
• 范围: 用户认证、注册、数据库同步及页面守卫
• 标题: 修复因“写入协调”失败导致的 Admin 功能权限问题

摘要

本操作彻底解决了新用户注册后，因数据库写入协调失败，导致业务用户表 (public.ak_users) 记录缺失，进而使得所有需要 admin/analytics 角色的 RPC 调用和页面访问全部失败的问题。修复遵循 @docs/AGENT_PROJECT_SPEC.md 规范，涉及数据库 DDL、触发器函数、前端服务和页面守卫的全链路调整。

动机

• 直接问题: Admin 后台的统计图表始终显示为 0，即使在数据库中有数据。
• 根本原因: 前端 RPC 调用因权限不足被拒绝。
• 深层原因: 权限检查依赖的 get_current_user_role() 函数因在 ak_users 表中找不到当前用户的 auth_id 而返回 NULL。
• 最终根源: 新用户在 auth.users 表注册后，自动同步到 ak_users 表的数据库触发器 handle_new_user() 函数逻辑错误（未向 ak_users 写入），导致数据不一致。

影响范围

• 数据库: public.ak_users 表结构, public.handle_new_user() 函数, auth.users 表上的 on_auth_user_created 触发器。
• 前端服务: utils/sapi.uts (ensureUserProfile), utils/store.uts (getCurrentUser), services/analytics/authGuard.uts.
• 前端页面: pages/user/login.uvue, pages/user/register.uvue, layouts/admin/AdminLayout.uvue.

变更清单

数据库侧 (权威 SQL)

1. 修复 ak_users 表结构约束:

   • 文件: docs/sql/10_schema/user/ak_users_constraints_fix_v1.sql
   • 内容: 移除了 username 和 email 的 NOT NULL 约束，以确保自动同步不会因缺少值而失败。

2. 修复 handle_new_user 触发器函数:

   • 文件: docs/sql/30_rpc/auth/handle_new_user_v3.sql
   • 内容: 将函数逻辑修正为正确地向 public.ak_users 表 INSERT 新用户记录，并兼容写入 public.user_roles。

3. 创建 get_current_user_role 函数:

   • 文件: docs/sql/30_rpc/auth/get_current_user_role_v1.sql
   • 内容: 创建了用于 RPC 鉴权的权威函数，通过 auth_id 查询 ak_users 表获取角色。

前端侧

1. 修复 ensureUserProfile 写入逻辑:

   • 文件: utils/sapi.uts
   • 内容: 修正了 INSERT 逻辑，确保写入的是 auth_id 而不是业务主键 id，并设置了默认角色。

2. 修复登录逻辑:

   • 文件: pages/user/login.uvue
   • 内容: 移除了生产环境下的 admin/admin 本地绕过登录，强制所有登录走 Supabase Auth 以获取有效 Token。并在登录成功后调用 ensureUserProfile。

3. 实现统一页面守卫:

   • 文件: layouts/admin/AdminLayout.uvue
   • 内容: 在布局的 onMounted 钩子中加入了统一的权限守卫，覆盖所有使用该布局的 Admin 页面。

最终解决方案与验证流程

1. 数据库部署: 按顺序执行以下权威 SQL 文件：

   • docs/sql/10_schema/user/ak_users_constraints_fix_v1.sql
   • docs/sql/30_rpc/auth/get_current_user_role_v1.sql
   • docs/sql/30_rpc/auth/handle_new_user_v3.sql
   • ALTER TABLE auth.users ENABLE TRIGGER on_auth_user_created; (确保触发器是启用的)

2. 新用户注册: 在 App 中注册一个全新的用户。

3. 验证数据同步: 在 SQL Editor 中执行“三表一致性”查询，确认新用户的 status 为 OK 或至少 ak_users 不再 MISSING。

4. 提升权限: 手动将新用户在 public.ak_users 表中的 role 字段更新为 'admin'。

5. 登录并访问: 使用新注册并已提权的账号登录 App，访问 Admin 后台的统计页面，确认数据能正常加载。

关联文档

• docs/AGENT_PROJECT_SPEC.md
• docs/sql/11_roles_and_permissions_strategy.md