543 lines
15 KiB
Markdown
543 lines
15 KiB
Markdown
# 🚀 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
|
||
**状态**: ✅ 完整迁移指南
|