# 🚀 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
```

**迁移操作**：
```bash
# 直接复制整个 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                 # 教师路由配置
```

**迁移操作**：
```bash
# 复制整个 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/` 下的页面都依赖此文件
- 必须迁移，否则前端代码无法编译

**迁移操作**：
```bash
# 复制类型定义文件
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: 创建新仓库

```bash
# 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: 迁移文档和数据库脚本

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

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

### 步骤 3: 迁移前端代码

```bash
# 复制页面代码
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: 迁移依赖文件（可选）

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

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

### 步骤 5: 更新导入路径

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

#### 5.1 检查类型导入
```bash
# 查找所有 mall-types 的引用
grep -r "from '@/types/mall-types" pages/mall/
```

确保导入路径正确：
```typescript
// 应该是相对路径或配置的别名
import type { ProductType } from '@/types/mall-types.uts'
```

#### 5.2 检查 Supabase 导入
```bash
# 查找 Supabase 引用
grep -r "from '@/components/supadb" pages/mall/
```

#### 5.3 检查工具函数导入
```bash
# 查找工具函数引用
grep -r "from '@/utils" pages/mall/
```

### 步骤 6: 配置数据库

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

#### 6.2 执行数据库脚本
```bash
# 方式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 插入测试数据（可选）
```bash
psql -h localhost -U postgres -d your_database -f doc_mall/database/mock_data_insert.sql
```

### 步骤 7: 配置前端环境

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

**示例：`config/supabase.config.ts`**
```typescript
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: 创建独立的用户表（推荐用于完全独立部署）
```sql
-- 创建独立的用户表（简化版）
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` 等表的外键引用：
```sql
-- 修改外键引用
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 编译测试
```bash
# 尝试编译项目（根据你的构建工具）
npm run build
# 或
uni-app-x build
```

#### 9.2 数据库连接测试
- 测试 Supabase 连接
- 验证 RLS 策略是否生效
- 测试 CRUD 操作

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

---

## 🔧 迁移后需要修改的内容

### 1. 更新导入路径

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

```typescript
// 原项目中的导入
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. 更新数据库表引用

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

```sql
-- 原项目中引用 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/` 下的文档，更新其中的文件路径引用：

```markdown
# 原文档中的路径
- `../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 官方文档](https://supabase.com/docs)
- [uni-app-x 官方文档](https://uniapp.dcloud.net.cn/uni-app-x/)
- [PostgreSQL 官方文档](https://www.postgresql.org/docs/)
- 项目内部文档：
  - `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  
**状态**: ✅ 完整迁移指南