akmon/doc_mall/database/ROLE_FIELD_SUMMARY.md

角色字段统一方案总结

📋 概述

为了提高代码可读性和语义清晰度，我们将商城系统中的用户角色字段从 user_type (INTEGER) 统一为 role (TEXT)。

🔄 修改内容

1. 字段类型变更

原始设计 (已废弃)

-- ml_user_profiles 表
user_type INTEGER DEFAULT 1 NOT NULL
-- 约束：CHECK (user_type IN (1,2,3,4,5))
-- 1:消费者 2:商家 3:配送员 4:客服 5:管理员

新设计 (当前版本)

-- ml_user_profiles 表 + ak_users 表
role TEXT DEFAULT 'customer' NOT NULL
-- 约束：CHECK (role IN ('customer', 'merchant', 'delivery', 'service', 'admin'))
-- customer:消费者, merchant:商家, delivery:配送员, service:客服, admin:管理员

2. 数据映射关系

旧 user_type (INTEGER)	新 role (TEXT)	中文含义
1	customer	消费者
2	merchant	商家
3	delivery	配送员
4	service	客服
5	admin	管理员

3. 统一后的优势

1. 语义清晰：role 比 user_type 更符合业务语义
2. 代码可读：字符串值比数字更易理解
3. 扩展性好：便于添加新角色类型
4. 国际化友好：角色名称可直接用于多语言映射
5. API友好：前端可直接使用角色字符串

📁 相关文件

核心数据库文件

• ✅ complete_mall_database.sql - 主数据库结构（已更新）
• ✅ mock_data_insert.sql - 测试数据插入（已更新）

迁移脚本

• 🆕 quick_role_migration.sql - 快速迁移脚本（推荐）
• 🆕 role_field_unification.sql - 完整统一方案

其他升级脚本（自动兼容）

• ✅ mall_alter_upgrade.sql - 增量升级脚本
• ✅ mall_fields_only_upgrade.sql - 字段升级脚本
• ✅ mall_migration.sql - 完整迁移脚本
• ✅ mall_seo_security.sql - SEO和安全脚本

文档

• ✅ UPGRADE_GUIDE.md - 升级指南（已更新）

🚀 执行步骤

对于新项目

直接使用最新的 complete_mall_database.sql，已包含 role 字段设计。

对于现有项目

如果您的数据库中存在 user_type 字段，请按以下步骤升级：

步骤 1：数据备份

pg_dump your_database > backup_before_role_migration.sql

步骤 2：执行快速迁移

psql -d your_database -f quick_role_migration.sql

步骤 3：验证迁移结果

-- 检查角色分布
SELECT role, COUNT(*) as count 
FROM ml_user_profiles 
GROUP BY role;

-- 检查数据一致性
SELECT COUNT(*) as inconsistent_records
FROM ak_users u
JOIN ml_user_profiles p ON u.id = p.user_id
WHERE u.role != p.role;

步骤 4：（可选）清理旧字段

迁移成功并确认无误后，可删除旧的 user_type 字段：

ALTER TABLE ml_user_profiles DROP COLUMN user_type;

🔧 技术细节

更新的数据库对象

1. 表结构

   • ml_user_profiles.role - 新增字段
   • ak_users.role - 与之保持同步

2. 约束

   • chk_ml_user_role - 角色值约束
   • 移除：chk_ml_user_type

3. 索引

   • idx_ml_user_profiles_role - 角色字段索引
   • 移除：idx_ml_user_profiles_type

4. 函数

   • is_verified_merchant() - 商家验证函数
   • get_user_role() - 获取用户角色
   • check_user_permission() - 权限检查
   • upgrade_user_role() - 角色升级

5. 视图

   • ml_users_view - 用户信息视图
   • vw_user_info - 用户完整信息视图
   • vw_role_statistics - 角色统计视图

6. RLS策略

   • 所有涉及角色检查的策略已更新

兼容性说明

• ✅ 向前兼容：新脚本可在空数据库上运行
• ✅ 向后兼容：提供完整回滚方案
• ✅ 增量升级：支持现有数据的平滑迁移
• ✅ Supabase兼容：完全支持Supabase环境

🔍 测试验证

测试用例

-- 1. 测试角色约束
INSERT INTO ml_user_profiles (user_id, role) 
VALUES (uuid_generate_v4(), 'invalid_role'); -- 应该失败

-- 2. 测试函数
SELECT get_user_role('user-uuid-here');
SELECT check_user_permission('user-uuid-here', ARRAY['admin', 'merchant']);

-- 3. 测试视图
SELECT * FROM vw_role_statistics;
SELECT * FROM ml_users_view WHERE role = 'merchant';

性能影响

• 角色查询性能：通过 idx_ml_user_profiles_role 索引优化
• 存储开销：TEXT字段比INTEGER稍大，但差异微小
• 查询兼容：所有现有查询逻辑已更新

📞 支持

如果在角色字段迁移过程中遇到问题，请：

1. 检查错误日志
2. 确认数据备份完整
3. 运行 mall_database_check.sql 诊断问题
4. 如需回滚，使用 quick_role_migration.sql 中的回滚脚本

---

总结：角色字段统一方案提供了更清晰、更语义化的用户角色管理，同时保持了完整的向后兼容性和迁移安全性。