173 lines
5.0 KiB
Markdown
173 lines
5.0 KiB
Markdown
# 角色字段统一方案总结
|
||
|
||
## 📋 概述
|
||
|
||
为了提高代码可读性和语义清晰度，我们将商城系统中的用户角色字段从 `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` 中的回滚脚本
|
||
|
||
---
|
||
|
||
**总结**：角色字段统一方案提供了更清晰、更语义化的用户角色管理，同时保持了完整的向后兼容性和迁移安全性。
|