huangzhenbao/medical-mall
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

项目从akmon迁入到mall

Browse Source
This commit is contained in:
comlibmb
2026-01-21 12:12:22 +08:00
parent cf8236e175
commit d7f95f7fa5
165 changed files with 69160 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

542
doc_mall/MIGRATION_GUIDE.md Normal file
View File

@@ -0,0 +1,542 @@
# 🚀 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
**状态**: ✅ 完整迁移指南