sql数据流，amdin业务逻辑接入

pages/mall/admin/docs/ops/2026-02-05__admin__user-management-db-integration.md

@@ -0,0 +1,121 @@
+# 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. 页面部署后检查控制台是否有错误信息