# 角色字段统一方案总结

## 📋 概述

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

## 🔄 修改内容

### 1. 字段类型变更

#### 原始设计 (已废弃)
```sql
-- ml_user_profiles 表
user_type INTEGER DEFAULT 1 NOT NULL
-- 约束：CHECK (user_type IN (1,2,3,4,5))
-- 1:消费者 2:商家 3:配送员 4:客服 5:管理员
```

#### 新设计 (当前版本)
```sql
-- 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：数据备份
```bash
pg_dump your_database > backup_before_role_migration.sql
```

#### 步骤 2：执行快速迁移
```bash
psql -d your_database -f quick_role_migration.sql
```

#### 步骤 3：验证迁移结果
```sql
-- 检查角色分布
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` 字段：
```sql
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环境

## 🔍 测试验证

### 测试用例
```sql
-- 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` 中的回滚脚本

---

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