medical-mall/mall_sql/docs/MIGRATION_GUIDE.md

🚀 doc_mall 项目迁移指南

📋 迁移概述

本指南将帮助你将 doc_mall 商城系统模块从当前项目迁移到一个独立的仓库中，确保所有相关模块和依赖项都能正确复用。

---

📁 需要迁移的文件和目录清单

1. 核心文档和数据库脚本 (doc_mall/)

完整目录结构：

doc_mall/
├── README.md                          # 文档索引
├── TECHNICAL_IMPLEMENTATION.md        # 技术实现拆解
├── MODULE_ANALYSIS.md                 # 模块深度分析
├── FRONTEND_BACKEND_DEBUGGING.md      # 前后端联调指南
├── user_reuse_summary.md              # 用户表复用方案
├── migration_complete_report.md       # 迁移完成报告
├── README_subscription_consumer.md    # 订阅功能说明
├── 裂变红包.md                        # 红包功能文档
├── create_mall_subscription_tables.sql        # 订阅表创建脚本
├── subscription_guard_trigger.sql             # 订阅触发器
├── subscription_rls_policies.sql              # 订阅RLS策略
├── analysis/                          # 分析文档目录
│   └── user_compatibility_analysis.md
├── database/                          # 数据库脚本目录
│   ├── complete_mall_database.sql     # 完整数据库（推荐）
│   ├── database_creation_report.md
│   ├── database_syntax_fix_report.md
│   ├── user_compatibility_implementation.sql
│   ├── product_database.sql
│   ├── mock_data_insert.sql
│   ├── mock_data_documentation.md
│   ├── deployment_guide.md
│   ├── validation_test.sql
│   ├── complete_deployment_guide.md
│   └── [其他SQL和文档文件]
└── reports/                           # 生成报告目录
    ├── system_generation_report.md
    ├── detail_pages_report.md
    └── profile_pages_report.md

迁移操作：

# 直接复制整个 doc_mall 目录
cp -r doc_mall/ /path/to/new-repo/doc_mall/

---

2. 前端页面代码 (pages/mall/)

完整目录结构：

pages/mall/
├── admin/                             # 管理端页面
│   ├── index.uvue
│   ├── profile.uvue
│   ├── user-detail.uvue
│   └── subscription/
│       ├── plan-management.uvue
│       └── user-subscriptions.uvue
├── analytics/                         # 数据分析端页面
│   ├── index.uvue
│   ├── profile.uvue
│   └── report-detail.uvue
├── consumer/                          # 消费者端页面
│   ├── index.uvue
│   ├── product-detail.uvue
│   ├── order-detail.uvue
│   ├── profile.uvue
│   └── subscription/
│       ├── plan-list.uvue
│       ├── plan-detail.uvue
│       ├── subscribe-checkout.uvue
│       ├── my-subscriptions.uvue
│       └── README.md
├── delivery/                          # 配送端页面
│   ├── index.uvue
│   ├── order-detail.uvue
│   └── profile.uvue
├── merchant/                          # 商家端页面
│   ├── index.uvue
│   ├── product-detail.uvue
│   └── profile.uvue
├── service/                           # 客服端页面
│   ├── index.uvue
│   ├── profile.uvue
│   └── ticket-detail.uvue
├── nfc/                               # NFC支付相关（可选）
│   ├── admin/index.uvue
│   ├── librarian/index.uvue
│   ├── merchant/pos-cashier.uvue
│   ├── parent/index.uvue
│   ├── security/index.uvue
│   ├── student/index.uvue
│   ├── teacher/index.uvue
│   └── [其他NFC相关文件]
├── mall.md                            # 业务需求文档
├── nfc.md                             # NFC功能文档
├── nfc-modules-guide.md               # NFC模块指南
├── pages-config.json                  # 页面路由配置（主要）
├── pages-admin.json                   # 管理端路由配置
├── pages-librarian.json               # 图书管理员路由配置
├── pages-merchant.json                # 商家路由配置
├── pages-parent.json                  # 家长路由配置
├── pages-security.json                # 安全员路由配置
├── pages-student.json                 # 学生路由配置
└── pages-teacher.json                 # 教师路由配置

迁移操作：

# 复制整个 pages/mall 目录
cp -r pages/mall/ /path/to/new-repo/pages/mall/

---

3. 类型定义文件 (types/mall-types.uts)

文件路径：

types/mall-types.uts

说明：

• 包含所有商城系统相关的 TypeScript/UTS 类型定义
• 所有 pages/mall/ 下的页面都依赖此文件
• 必须迁移，否则前端代码无法编译

迁移操作：

# 复制类型定义文件
mkdir -p /path/to/new-repo/types
cp types/mall-types.uts /path/to/new-repo/types/

---

🔗 依赖关系分析

3.1 内部依赖（必须迁移）

Supabase 客户端封装

• 依赖文件：components/supadb/aksupainstance.uts
• 使用情况：所有商城页面都通过 Supabase 客户端访问数据库
• 迁移建议：
  • 如果新仓库也需要使用 Supabase，需要迁移此文件
  • 或者创建新的 Supabase 客户端封装

工具函数

• 检查项目：是否需要 utils/ 下的工具函数
• 常见使用：日期格式化、数据验证等
• 迁移建议：
  • 检查商城页面中 @/utils/ 的引用
  • 根据需要迁移相应的工具函数

3.2 外部依赖（需要配置）

数据库依赖

• 依赖表：ak_users (用户主表)
• 说明：商城系统复用现有用户表实现单点登录
• 迁移策略：
  • 方案A：在新仓库中创建独立的用户表
  • 方案B：保持与现有用户表的关联（需要跨数据库访问）
  • 方案C：通过 API 服务访问用户数据

Supabase 配置

• 需要配置：Supabase 项目 URL 和 API Key
• 配置文件：通常保存在环境变量或配置文件中
• 迁移步骤：
  1. 在新仓库创建 Supabase 项目（或使用现有项目）
  2. 执行数据库脚本创建表结构
  3. 配置 RLS 策略和权限
  4. 更新前端配置中的 Supabase 连接信息

---

📝 迁移步骤详解

步骤 1: 创建新仓库

# 1. 创建新仓库目录
mkdir mall-system
cd mall-system

# 2. 初始化 Git 仓库
git init

# 3. 创建基础目录结构
mkdir -p doc_mall/{analysis,database,reports}
mkdir -p pages/mall
mkdir -p types
mkdir -p components/supadb  # 如果需要
mkdir -p utils              # 如果需要

步骤 2: 迁移文档和数据库脚本

# 从原项目复制 doc_mall 目录
cp -r /path/to/akmon/doc_mall/* ./doc_mall/

# 验证文件完整性
ls -la doc_mall/

步骤 3: 迁移前端代码

# 复制页面代码
cp -r /path/to/akmon/pages/mall/* ./pages/mall/

# 复制类型定义
cp /path/to/akmon/types/mall-types.uts ./types/

# 验证关键文件
ls -la pages/mall/
ls -la types/mall-types.uts

步骤 4: 迁移依赖文件（可选）

# 如果需要 Supabase 客户端
cp -r /path/to/akmon/components/supadb/* ./components/supadb/

# 检查并迁移需要的工具函数
# 查看 pages/mall/ 下文件中的 import 语句
grep -r "from '@/utils" pages/mall/

步骤 5: 更新导入路径

在新仓库中，需要检查并更新以下内容：

5.1 检查类型导入

# 查找所有 mall-types 的引用
grep -r "from '@/types/mall-types" pages/mall/

确保导入路径正确：

// 应该是相对路径或配置的别名
import type { ProductType } from '@/types/mall-types.uts'

5.2 检查 Supabase 导入

# 查找 Supabase 引用
grep -r "from '@/components/supadb" pages/mall/

5.3 检查工具函数导入

# 查找工具函数引用
grep -r "from '@/utils" pages/mall/

步骤 6: 配置数据库

6.1 创建 Supabase 项目

1. 访问 Supabase 控制台
2. 创建新项目或使用现有项目
3. 记录项目 URL 和 API Key

6.2 执行数据库脚本

# 方式1: 通过 Supabase Dashboard SQL Editor
# 打开 doc_mall/database/complete_mall_database.sql
# 复制内容到 Supabase SQL Editor 执行

# 方式2: 通过 psql 命令行（如果使用自建 PostgreSQL）
psql -h localhost -U postgres -d your_database -f doc_mall/database/complete_mall_database.sql

6.3 配置 RLS 策略

确保执行以下脚本：

• doc_mall/subscription_rls_policies.sql
• doc_mall/subscription_guard_trigger.sql
• 数据库脚本中已包含的 RLS 策略

6.4 插入测试数据（可选）

psql -h localhost -U postgres -d your_database -f doc_mall/database/mock_data_insert.sql

步骤 7: 配置前端环境

7.1 创建配置文件

在新仓库根目录创建配置文件（根据你的项目结构）：

示例：config/supabase.config.ts

export const supabaseConfig = {
  url: 'https://your-project.supabase.co',
  anonKey: 'your-anon-key',
  // 其他配置
}

7.2 更新 Supabase 客户端初始化

如果迁移了 components/supadb/aksupainstance.uts，确保它使用新的配置。

7.3 配置路由

检查并更新以下路由配置文件：

• pages/mall/pages-config.json （主要路由配置）
• 其他角色端路由配置 JSON 文件

步骤 8: 处理用户表依赖

商城系统依赖 ak_users 表，有几种处理方案：

方案 A: 创建独立的用户表（推荐用于完全独立部署）

-- 创建独立的用户表（简化版）
CREATE TABLE public.mall_users (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    phone VARCHAR(20) UNIQUE NOT NULL,
    email VARCHAR(255),
    nickname VARCHAR(100),
    -- 其他必要字段
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

然后更新所有 ml_user_profiles 等表的外键引用：

-- 修改外键引用
ALTER TABLE public.ml_user_profiles 
DROP CONSTRAINT ml_user_profiles_user_id_fkey;

ALTER TABLE public.ml_user_profiles 
ADD CONSTRAINT ml_user_profiles_user_id_fkey 
FOREIGN KEY (user_id) REFERENCES public.mall_users(id) ON DELETE CASCADE;

方案 B: 通过 API 服务访问用户数据

• 保持数据库结构不变
• 通过 API 服务层访问用户数据
• 前端不直接访问 ak_users 表

方案 C: 跨数据库访问（复杂，不推荐）

• 保持现有的数据库引用
• 配置跨数据库访问权限

步骤 9: 测试和验证

9.1 编译测试

# 尝试编译项目（根据你的构建工具）
npm run build
# 或
uni-app-x build

9.2 数据库连接测试

• 测试 Supabase 连接
• 验证 RLS 策略是否生效
• 测试 CRUD 操作

9.3 功能测试

• 测试各个角色端页面是否能正常加载
• 测试核心业务流程（商品浏览、下单等）
• 测试权限控制

---

🔧 迁移后需要修改的内容

1. 更新导入路径

检查并更新所有文件中的导入路径，确保它们指向正确的位置：

// 原项目中的导入
import type { ProductType } from '@/types/mall-types.uts'
import { supabase } from '@/components/supadb/aksupainstance.uts'

// 新仓库中可能需要调整为
import type { ProductType } from '@/types/mall-types.uts'
import { supabase } from '@/lib/supabase/client.uts'  // 如果路径改变了

2. 更新数据库表引用

如果用户表方案改变，需要更新所有相关的外键和查询：

-- 原项目中引用 ak_users
user_id UUID NOT NULL REFERENCES public.ak_users(id)

-- 如果改为独立用户表
user_id UUID NOT NULL REFERENCES public.mall_users(id)

3. 更新环境变量和配置

• Supabase 项目 URL 和 API Key
• 数据库连接字符串
• 其他环境相关配置

4. 更新文档中的路径引用

检查 doc_mall/ 下的文档，更新其中的文件路径引用：

# 原文档中的路径
- `../types/mall-types.uts`

# 新仓库中应该为
- `types/mall-types.uts`

---

✅ 迁移检查清单

使用以下清单确保迁移完整：

• 文档迁移

  • doc_mall/ 目录完整复制
  • 所有子目录（analysis, database, reports）已迁移
  • 文档中的路径引用已更新

• 前端代码迁移

  • pages/mall/ 所有页面文件已迁移
  • types/mall-types.uts 已迁移
  • 所有路由配置文件（pages-*.json）已迁移
  • 业务需求文档（mall.md）已迁移

• 依赖文件迁移

  • Supabase 客户端封装已迁移或重新创建
  • 必要的工具函数已迁移
  • 组件依赖已处理

• 数据库配置

  • Supabase 项目已创建并配置
  • 数据库脚本已执行
  • RLS 策略已配置
  • 测试数据已插入（可选）
  • 用户表依赖已处理

• 代码适配

  • 所有导入路径已更新
  • 数据库表引用已更新（如需要）
  • 配置文件已更新
  • 环境变量已配置

• 测试验证

  • 项目可以正常编译
  • 数据库连接正常
  • 页面可以正常加载
  • 核心功能测试通过

---

🚨 常见问题和解决方案

问题 1: 编译错误 - 找不到类型定义

错误信息：

Cannot find module '@/types/mall-types.uts'

解决方案：

1. 确认 types/mall-types.uts 文件已迁移
2. 检查 TypeScript/UTS 配置中的路径别名设置
3. 确保 @/types 正确映射到 types/ 目录

问题 2: Supabase 连接失败

错误信息：

Failed to connect to Supabase

解决方案：

1. 检查 Supabase 项目 URL 和 API Key 配置
2. 验证网络连接
3. 检查 Supabase 项目的状态

问题 3: RLS 策略导致权限错误

错误信息：

new row violates row-level security policy

解决方案：

1. 确认已执行所有 RLS 策略脚本
2. 检查用户认证状态
3. 验证 RLS 策略的 SELECT/INSERT/UPDATE 权限设置

问题 4: 外键约束错误

错误信息：

foreign key constraint "ml_user_profiles_user_id_fkey" fails

解决方案：

1. 如果使用独立用户表，需要更新外键引用
2. 确保引用的用户记录存在
3. 检查外键约束的 CASCADE 设置

---

📚 参考资料

• Supabase 官方文档
• uni-app-x 官方文档
• PostgreSQL 官方文档
• 项目内部文档：
  • doc_mall/TECHNICAL_IMPLEMENTATION.md - 技术实现详情
  • doc_mall/FRONTEND_BACKEND_DEBUGGING.md - 调试指南
  • doc_mall/database/complete_deployment_guide.md - 数据库部署指南

---

📞 迁移支持

如果在迁移过程中遇到问题：

1. 查看文档：先查看 doc_mall/ 下的相关文档
2. 检查日志：查看编译日志和运行时日志
3. 数据库验证：使用 doc_mall/database/validation_test.sql 验证数据库状态
4. 联系开发团队：提供详细的错误信息和迁移步骤

---

最后更新: 2025年1月
版本: v1.0
状态: ✅ 完整迁移指南