Initial commit of akmon project

doc_mall/database/ROLE_FIELD_SUMMARY.md

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