57 lines
3.1 KiB
Markdown
57 lines
3.1 KiB
Markdown
# 操作文档：修复 `handle_new_user` 触发器函数
|
||
|
||
- **日期**: 2026-02-04
|
||
- **范围**: 数据库触发器函数 (`public.handle_new_user`)
|
||
- **标题**: 修复 `auth.users` -> `public.ak_users` 的自动用户同步逻辑
|
||
|
||
## 摘要
|
||
|
||
本操作通过更新 `public.handle_new_user()` 触发器函数的定义，解决了新用户在 Supabase Auth 注册后，无法在核心业务表 `public.ak_users` 中自动创建对应记录的根本问题。
|
||
|
||
## 动机
|
||
|
||
经过排查，发现 `on_auth_user_created` 触发器调用的 `handle_new_user()` 函数并未向 `public.ak_users` 表执行任何 `INSERT` 操作，而是错误地将数据写入了 `public.user_roles` 和 `auth.users.raw_user_meta_data`。这导致 `auth.users` 和 `public.ak_users` 之间的数据完全脱节，使得所有依赖 `ak_users.role` 的权限校验（如 RPC 鉴权）全部失败。
|
||
|
||
## 影响范围
|
||
|
||
- **数据库函数**: `public.handle_new_user()`
|
||
- **数据库触发器**: `on_auth_user_created` (在 `auth.users` 表上)
|
||
- **数据库表**: `public.ak_users` (现在可以被自动写入), `public.user_roles` (保持兼容写入)
|
||
- **业务流程**: 新用户注册的数据同步流程。
|
||
|
||
## 变更清单
|
||
|
||
- **新增文件**:
|
||
- `docs/sql/30_rpc/auth/handle_new_user_v2.sql`: 包含了修正后的 `handle_new_user` 函数的权威 SQL 脚本。
|
||
- `docs/ops/2026-02-04__db-trigger__fix-handle-new-user-sync.md`: 本操作文档。
|
||
|
||
- **修改内容**: `public.handle_new_user()` 函数的定义
|
||
- **新增**: 向 `public.ak_users` 表 `INSERT` 新用户记录的逻辑，包含 `auth_id`, `email`, `username`, 和 `role`。
|
||
- **新增**: 使用 `ON CONFLICT` 确保操作的幂等性。
|
||
- **保留**: 保留了向 `public.user_roles` 和 `auth.users.raw_user_meta_data` 的写入，以兼容现有逻辑。
|
||
- **安全**: 函数已遵循 `SECURITY DEFINER` 和 `SET search_path = public` 的安全规范。
|
||
|
||
## 兼容性与风险
|
||
|
||
- **数据兼容性**: 此变更为向前兼容。它修复了新用户的数据同步问题，不会影响现有的 `ak_users` 记录。
|
||
- **风险**: 无明显风险。函数现在会正确地执行其预期的核心任务。
|
||
|
||
## 回滚方案
|
||
|
||
如果需要撤销此变更，可以从版本控制（Git）中找回旧的 `handle_new_user()` 函数定义，或者从数据库备份中恢复，然后重新执行 `CREATE OR REPLACE FUNCTION` 即可。
|
||
|
||
## 验证方式
|
||
|
||
1. **执行变更**: 在数据库中执行 `docs/sql/30_rpc/auth/handle_new_user_v2.sql` 的内容，以更新函数定义。
|
||
2. **注册新用户**: 在 App 中注册一个全新的用户（例如 `final_test@example.com`）。
|
||
3. **验证 `ak_users` 表**: 在 SQL Editor 中查询，确认 `ak_users` 表中已自动创建了与新用户 `auth_id` 对应的记录，并且 `role` 已根据邮箱规则（或默认为 `customer`）被正确设置。
|
||
```sql
|
||
SELECT auth_id, email, username, role FROM public.ak_users WHERE email = 'final_test@example.com';
|
||
```
|
||
4. **验证一致性**: 再次执行一致性检查 SQL，确认新用户的 `consistency_status` 为 `CONSISTENT`。
|
||
|
||
## 关联文档
|
||
|
||
- `docs/AGENT_PROJECT_SPEC.md`
|
||
- `docs/sql/30_rpc/auth/handle_new_user_v2.sql`
|