# 2026-02-05__admin__user-management-db-integration.md

## 摘要

为管理后台用户管理模块（`pages/mall/admin/user/user-management/index.uvue`）接入数据库，实现用户列表分页查询、筛选、用户详情展示，并支持会员信息（是否会员 + 方案名 + 到期时间）与余额（固定 0）的展示。

## 动机

- 原 admin 用户管理页面为占位页，无真实数据接入
- 需要按照项目规范（`AGENT_PROJECT_SPEC.md`）通过 `services/` 层访问数据，admin 全局数据走 RPC
- 用户管理需展示会员信息（基于 `ml_user_subscriptions`）与余额（暂固定 0）

## 影响范围

- **数据库层**：新增 RPC（暂存于 `test/`，待验证后入库到 `docs/sql/30_rpc/admin/`）
- **服务层**：新增 `services/admin/AdminUserService.uts`
- **页面层**：`pages/mall/admin/user/user-management/index.uvue` 从占位页升级为完整功能页
- **工具层**：`utils/supabaseService.uts` 新增 `export { supa }` 供 services 统一使用

## 变更清单

### 新增文件
- `pages/mall/admin/user/test/rpc_admin_user_list_v1.sql` - 用户列表 RPC（分页+筛选）
- `pages/mall/admin/user/test/rpc_admin_user_detail_v1.sql` - 用户详情 RPC
- `services/admin/AdminUserService.uts` - Admin 用户管理服务封装
- `pages/mall/admin/docs/ops/2026-02-05__admin__user-management-db-integration.md` - 本操作文档

### 修改文件
- `pages/mall/admin/user/user-management/index.uvue` - 从占位页升级为完整功能页
- `utils/supabaseService.uts` - 新增 `export { supa }` 供 services 层统一使用

### 删除文件
- 无

## 兼容性与风险

### 兼容性
- RPC 依赖现有表结构：`ak_users`、`ml_user_profiles`、`ml_user_subscriptions`、`ml_subscription_plans`、`ml_user_addresses`
- 会员关联口径：`ml_user_subscriptions.user_id = ak_users.auth_id`（即 `auth.users.id`）
- 余额字段固定返回 0，不影响现有业务

### 风险
- RPC 暂存于 `test/` 目录，未入库到 `docs/sql/`，需验证后再迁移
- 新增 `export { supa }` 可能影响其他模块的导入行为（但为统一出口，风险较低）
- 页面功能较复杂，需充分测试分页、筛选、弹窗等交互

## 回滚方案

1. **回滚页面**：恢复 `pages/mall/admin/user/user-management/index.uvue` 为原占位页内容
2. **回滚服务**：删除 `services/admin/AdminUserService.uts`
3. **回滚工具**：移除 `utils/supabaseService.uts` 中的 `export { supa }`
4. **回滚 RPC**：删除 `pages/mall/admin/user/test/` 下的两个 RPC 文件

## 验证方式

### 功能验证
1. 访问管理后台 → 用户管理 → 用户列表
2. 验证列表数据加载正常，显示用户基本信息、会员信息、余额
3. 测试筛选功能：搜索、角色、状态、会员筛选
4. 测试分页功能：上一页/下一页
5. 点击"查看"按钮，验证用户详情弹窗正常显示
6. 验证详情页中的会员信息（方案名、到期时间）和地址信息

### 技术验证
1. 检查 RPC 调用是否正常返回数据
2. 检查服务层数据转换是否正确
3. 检查页面渲染是否正常，无报错
4. 检查网络请求是否通过 services 层，未直接访问 supabase client

### SQL 验证
```sql
-- 验证 RPC 是否创建成功
SELECT proname, prosrc FROM pg_proc WHERE proname LIKE 'rpc_admin_user_%';

-- 测试用户列表 RPC
SELECT * FROM rpc_admin_user_list(1, 20, NULL, NULL, NULL, NULL);

-- 测试用户详情 RPC（替换为真实用户ID）
SELECT * FROM rpc_admin_user_detail('your-user-id-here');
```

## 关联文档

- `docs/project_spec/AGENT_PROJECT_SPEC.md` - 项目规范文档
- `docs/sql/30_rpc/auth/get_current_user_role_v1.sql` - RPC 鉴权入口
- `mall_sql/schemas/complete_mall_database.sql` - 数据库表结构
- `doc_mall/create_mall_subscription_tables.sql` - 订阅表结构
- `pages/mall/admin/user/docs/USER_STATISTICS_DB.md` - 用户统计相关文档

## 技术实现要点

### RPC 设计
- 使用 `SECURITY DEFINER` + `SET search_path = public`
- 入口鉴权：`get_current_user_role() IN ('admin', 'analytics')`
- 支持分页、搜索、多维度筛选
- 会员信息通过 `LATERAL JOIN` 获取最新有效订阅

### 服务层设计
- 封装 RPC 调用，提供类型安全的接口
- 统一错误处理和日志记录
- 数据转换：UTSJSONObject → TypeScript 类型

### 页面设计
- 响应式布局，支持移动端
- 完整的筛选和分页功能
- 用户详情弹窗展示完整信息
- 会员信息按方案 C 展示：是否会员 + 方案名 + 到期时间

## 后续计划

1. **RPC 入库**：验证通过后，将 RPC 迁移到 `docs/sql/30_rpc/admin/`
2. **功能扩展**：根据业务需求，可能需要添加用户编辑、状态变更等功能
3. **性能优化**：考虑添加缓存、索引优化等
4. **余额功能**：当钱包/余额表实现后，接入真实余额数据

## 部署注意事项

1. 确保数据库表结构已部署（`ml_user_profiles`、`ml_user_subscriptions` 等）
2. 确保 `get_current_user_role()` RPC 已部署
3. 部署前建议在测试环境验证 RPC 功能正常
4. 页面部署后检查控制台是否有错误信息