Initial commit of akmon project

2026-01-20 08:04:15 +08:00
commit 77a2bab985
1309 changed files with 343305 additions and 0 deletions
--- a/doc_mall/database/ROLE_FIELD_FIX_REPORT.md
+++ b/doc_mall/database/ROLE_FIELD_FIX_REPORT.md
@@ -0,0 +1,151 @@
+# 角色字段统一修复完成报告
+
+## 🔧 问题修复
+
+### 问题1：重复的角色字段
+**原问题**：`ml_user_profiles` 表中存在重复的 `role` 字段，与 `ak_users.role` 重复。
+**解决方案**：删除 `ml_user_profiles.role` 字段，统一使用 `ak_users.role`。
+
+### 问题2：变量类型错误
+**原问题**：订单生成代码中 `merchant_rec` 变量类型错误，导致数据类型不匹配。
+**解决方案**：将 `merchant_rec RECORD` 改为 `merchant_id UUID`。
+
+## ✅ 已修复的文件
+
+### 1. complete_mall_database.sql
+- ❌ 删除：`ml_user_profiles.role` 字段定义
+- ❌ 删除：相关约束 `chk_ml_user_role`
+- ❌ 删除：相关索引 `idx_ml_user_profiles_role`
+- ❌ 删除：相关注释
+- ✅ 更新：`is_verified_merchant()` 函数，从 `ak_users` 表获取角色
+- ✅ 更新：`ml_users_view` 视图，使用 `u.role` 替代 `p.role`
+- ✅ 更新：插入语句，移除 `role` 字段
+
+### 2. mock_data_insert.sql
+- ✅ 更新：用户档案插入语句，移除 `role` 字段
+- ✅ 更新：冲突处理语句，移除 `role` 字段
+- ✅ 修复：订单生成代码中的变量类型错误
+
+### 3. role_field_cleanup.sql (新增)
+- ✅ 创建：专门的角色字段清理脚本
+- ✅ 功能：检查并清理重复的角色字段
+- ✅ 功能：数据迁移和一致性检查
+- ✅ 功能：更新相关函数和视图
+
+## 📊 当前角色字段设计
+
+### 唯一的角色存储位置
+```sql
+-- ak_users 表 - 唯一的角色字段存储位置
+CREATE TABLE public.ak_users (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    role TEXT DEFAULT 'customer' NOT NULL,
+    -- 其他字段...
+    
+    CONSTRAINT chk_ak_users_role 
+    CHECK (role IN ('customer', 'merchant', 'delivery', 'service', 'admin'))
+);
+```
+
+### 相关表关联
+```sql
+-- ml_user_profiles 表 - 不再包含 role 字段
+CREATE TABLE public.ml_user_profiles (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    user_id UUID UNIQUE NOT NULL REFERENCES public.ak_users(id),
+    status INTEGER DEFAULT 1 NOT NULL,
+    -- 其他扩展信息字段...
+);
+```
+
+### 获取用户角色
+```sql
+-- 通过关联查询获取角色信息
+SELECT u.role, p.real_name, p.credit_score
+FROM ak_users u
+LEFT JOIN ml_user_profiles p ON u.id = p.user_id
+WHERE u.id = 'user-uuid';
+```
+
+## 🔍 验证步骤
+
+### 1. 字段检查
+```sql
+-- 检查是否还有重复的 role 字段
+SELECT 
+    table_name,
+    column_name,
+    data_type
+FROM information_schema.columns 
+WHERE column_name = 'role'
+AND table_name IN ('ak_users', 'ml_user_profiles');
+
+-- 预期结果：只有 ak_users.role
+```
+
+### 2. 约束检查
+```sql
+-- 检查角色约束
+SELECT constraint_name, table_name
+FROM information_schema.check_constraints
+WHERE constraint_name LIKE '%role%';
+
+-- 预期结果：只有 chk_ak_users_role
+```
+
+### 3. 功能检查
+```sql
+-- 测试角色相关函数
+SELECT get_user_role('test-user-id');
+SELECT check_user_permission('test-user-id', ARRAY['admin']);
+SELECT * FROM vw_role_statistics;
+```
+
+## 🎯 优势总结
+
+### 1. 数据一致性
+- ✅ 单一数据源：角色信息只存储在一个地方
+- ✅ 避免同步问题：不会出现两个表角色不一致的情况
+- ✅ 数据完整性：通过外键约束保证关联关系
+
+### 2. 代码简洁性
+- ✅ 查询简化：直接从 `ak_users` 获取角色信息
+- ✅ 维护容易：只需要维护一个角色字段
+- ✅ 扩展性好：新增角色类型只需要修改一个约束
+
+### 3. 性能优化
+- ✅ 减少JOIN：在只需要角色信息时无需关联 `ml_user_profiles`
+- ✅ 索引优化：`ak_users.role` 上的索引直接支持角色查询
+- ✅ 存储节约：减少了重复数据的存储
+
+## 📋 迁移指南
+
+### 对于新项目
+直接使用修复后的 `complete_mall_database.sql` 脚本。
+
+### 对于现有项目
+1. 执行 `role_field_cleanup.sql` 脚本
+2. 验证数据迁移结果
+3. 测试相关功能是否正常
+
+### 脚本执行顺序
+```bash
+# 1. 主数据库结构
+psql -f complete_mall_database.sql
+
+# 2. 角色字段清理（如果是从旧版本升级）
+psql -f role_field_cleanup.sql
+
+# 3. 插入测试数据
+psql -f mock_data_insert.sql
+```
+
+## ✨ 结论
+
+角色字段统一修复已经完成，系统现在具有：
+- 🎯 **清晰的数据结构**：角色信息统一存储在 `ak_users.role`
+- 🔒 **数据一致性保证**：消除了数据重复和不一致的风险
+- 🚀 **更好的性能**：简化了查询逻辑，提高了查询效率
+- 🛠️ **易于维护**：减少了代码复杂度，便于后续维护和扩展
+
+所有相关文件已更新完毕，可以安全使用！