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

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 验证

-- 验证 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. 页面部署后检查控制台是否有错误信息