# 操作文档：修复 `ak_users` 表写入协调问题

- **日期**: 2026-02-04
- **范围**: 数据库 Schema (`public.ak_users`)
- **标题**: 修复 `auth.users` -> `ak_users` 自动同步的写入协调问题

## 摘要

本操作通过修改 `public.ak_users` 表的结构，解决了新用户在 Supabase Auth 注册后，无法在业务表 `ak_users` 中自动创建对应记录的问题。核心改动是放宽了 `username` 和 `email` 字段的 `NOT NULL` 约束。

## 动机

在当前实现中，`auth.users` 表上存在一个 `on_auth_user_created` 触发器，该触发器在有新用户注册时会调用 `handle_new_user()` 函数，尝试在 `ak_users` 表中插入一条对应的业务用户记录。然而，由于 `ak_users` 表的 `username` 和 `email` 字段被设置为 `NOT NULL` 且没有默认值，而 `handle_new_user()` 函数在执行时无法提供这两个值，导致 `INSERT` 操作因违反约束而静默失败。这造成了 `auth.users` 和 `public.ak_users` 之间的数据不一致，使得新注册的用户无法被业务系统识别，后续的权限、角色等功能全部失效。

## 影响范围

- **数据库表**: `public.ak_users`
- **数据库函数**: `public.handle_new_user()` (现在可以成功执行)
- **前端逻辑**: `utils/sapi.uts` 中的 `ensureUserProfile` 函数（现在在用户首次登录时，即使触发器失败，它也能成功插入记录）。
- **业务流程**: 新用户注册、首次登录的数据同步流程。

## 变更清单

- **新增文件**: 
  - `docs/sql/10_schema/user/ak_users_constraints_fix_v1.sql`: 包含了本次 DDL 变更的权威 SQL 脚本。
  - `docs/ops/2026-02-04__db-schema__fix-ak-users-constraints.md`: 本操作文档。

- **修改内容**: `public.ak_users` 表结构
  - `username` 字段的 `NOT NULL` 约束被移除。
  - `email` 字段的 `NOT NULL` 约束被移除。
  - `role` 字段的默认值被更新为 `'customer'`。

## 兼容性与风险

- **数据兼容性**: 此变更为向下兼容。允许 `username` 和 `email` 为空，不会影响现有记录。应用层代码（如 `ensureUserProfile`）会在用户首次登录时尝试填充这些值。
- **风险**: 理论上，现在 `ak_users` 表中可能存在 `username` 或 `email` 为空的记录。依赖这两个字段为非空的前端页面或业务逻辑需要做好空值处理，但这符合用户首次登录后才完善资料的常见模式。

## 回滚方案

如果需要撤销此变更，可以执行以下 SQL 命令，将表的约束恢复到之前的状态：

```sql
BEGIN;

ALTER TABLE public.ak_users
ALTER COLUMN username SET NOT NULL,
ALTER COLUMN email SET NOT NULL;

-- 注意：回滚前必须确保表中没有 username 或 email 为 NULL 的记录，否则会失败。

-- 将 role 的默认值恢复为 'student'（如果需要）
ALTER TABLE public.ak_users
ALTER COLUMN role SET DEFAULT 'student';

COMMIT;
```

## 验证方式

1.  **执行变更**: 在数据库中执行 `docs/sql/10_schema/user/ak_users_constraints_fix_v1.sql` 的内容。
2.  **注册新用户**: 在 App 中注册一个全新的用户（例如 `new_user@example.com`）。
3.  **验证 `ak_users` 表**: 在 SQL Editor 中查询，确认 `ak_users` 表中已自动创建了与新用户 `auth_id` 对应的记录。
    ```sql
    SELECT auth_id, email, username, role FROM public.ak_users WHERE email = 'new_user@example.com';
    ```
4.  **验证 `consistency_status`**: 再次执行之前的一致性检查 SQL，确认新用户的状态为 `CONSISTENT`。

## 关联文档

- `docs/AGENT_PROJECT_SPEC.md`
- `docs/sql/10_schema/user/ak_users_constraints_fix_v1.sql`