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

- **日期**: 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`