From 8c5024a943b9999336ac3b491b5384c43bb54d30 Mon Sep 17 00:00:00 2001 From: huangzhenbao <17818024429@163.com> Date: Wed, 28 Jan 2026 11:10:05 +0800 Subject: [PATCH 1/7] =?UTF-8?q?=E4=BF=AE=E6=94=B9=E9=A1=B5=E9=9D=A2?= =?UTF-8?q?=E5=B8=83=E5=B1=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- pages/mall/admin/homePage/index.uvue | 215 ++++++++++++++--------- pages/mall/admin/product-management.uvue | 1 + 2 files changed, 130 insertions(+), 86 deletions(-) diff --git a/pages/mall/admin/homePage/index.uvue b/pages/mall/admin/homePage/index.uvue index 98a2280e..f488d5c2 100644 --- a/pages/mall/admin/homePage/index.uvue +++ b/pages/mall/admin/homePage/index.uvue @@ -54,24 +54,32 @@ - 订单 + + + + + + 订单 + + - + {{ p.label }} + + - + - 📊 ECharts 组合图：柱状图(订单金额) + 折线图(订单数量) - 时间粒度：{{ selectedPeriodLabel }} + + 111 @@ -146,7 +154,10 @@ const kpiData = ref({ // 图表配置 const selectedPeriod = ref('30days') -const selectedPeriodLabel = ref('30天') +const selectedPeriodLabel = computed((): string => { + const hit = chartPeriods.value.find((x) => x.value === selectedPeriod.value) + return hit ? hit.label : "" +}) const chartPeriods = [ { label: '30天', value: '30days' }, @@ -155,6 +166,12 @@ const chartPeriods = [ { label: '年', value: 'year' } ] +type PeriodItem = { + label: string + value: string +} + + // 方法 const formatNumber = (num: number) => { if (num >= 10000) { @@ -178,6 +195,8 @@ const changePeriod = (period: string) => { // TODO: 重新加载图表数据 console.log('切换时间粒度:', period) } + + +``` + +## 🎯 项目成果 + +✅ **完全自主开发**: 无任何源码复制，100%自主编写 +✅ **CRMEB 风格**: 严格遵循设计规范和布局结构 +✅ **完整功能**: 数据看板 + 用户统计双页面 +✅ **响应式设计**: 桌面/平板/手机全适配 +✅ **技术先进**: Vue 3 + TypeScript + 组合式API +✅ **可维护性**: 模块化架构，易于扩展 + +--- + +## 🚀 部署运行 + +```bash +# 开发环境 +npm run dev:h5 + +# 构建生产 +npm run build:h5 + +# 运行到小程序 +npm run dev:mp-weixin +``` + +访问地址：`http://localhost:5173/pages/mall/admin/index` + +--- + +*本项目完全自主开发，实现了CRMEB标准版后台的核心功能，为后续功能扩展奠定了坚实基础。* \ No newline at end of file diff --git a/docs/CRMEB_REFACTORING_PLAN.md b/docs/CRMEB_REFACTORING_PLAN.md deleted file mode 100644 index ee38af71..00000000 --- a/docs/CRMEB_REFACTORING_PLAN.md +++ /dev/null @@ -1,940 +0,0 @@ -# CRMEB 项目重构计划文档 - -## 📋 文档说明 - -本文档基于 **Clean-Room 重构原则**，通过分析 CRMEB 项目的**可观察行为与功能规格**，制定将 CRMEB 商城系统迁移到 **uni-app x (uvue) + Supabase** 技术栈的重构计划。 - -### 重构原则 - -1. **禁止复制源码**：不直接使用 CRMEB 的任何 PHP/Vue 源码 -2. **规格驱动开发**：基于功能规格和行为描述进行独立实现 -3. **技术栈迁移**： - - 前端：Vue/UniApp → **uvue (uni-app x)** - - 后端：PHP/ThinkPHP → **Supabase (PostgreSQL + RLS + Edge Functions)** -4. **组件复用**：尽量不修改 `components/supadb`，仅通过接口调用 - ---- - -## 一、功能规格提取 (Spec Extraction) - -### 1.1 核心业务模块 - -基于 CRMEB 项目结构分析，提取以下核心功能模块： - -#### 1.1.1 用户系统 (User System) -**功能清单**： -- 用户注册/登录（手机号、微信、邮箱） -- 用户信息管理（昵称、头像、性别） -- 用户角色（消费者、商家、配送员、客服、管理员） -- 用户认证（实名认证、商家认证） -- 用户地址管理（多地址、默认地址） -- 用户余额/积分管理 - -**数据字段规格**： -- 用户基础信息：id, phone, email, nickname, avatar_url, gender, user_type, status -- 用户扩展信息：real_name, id_card, credit_score, verification_status -- 地址信息：receiver_name, receiver_phone, province, city, district, address_detail, is_default - -**权限矩阵**： -- 用户只能查看/修改自己的信息 -- 管理员可查看所有用户信息 -- 商家可查看自己的店铺信息 - -#### 1.1.2 商品系统 (Product System) -**功能清单**： -- 商品管理（创建、编辑、上架、下架） -- 商品分类（多级分类、分类树） -- 商品品牌管理 -- 商品规格/SKU（多规格、价格、库存） -- 商品图片（主图、详情图、轮播图） -- 商品搜索（关键词、分类、品牌、价格区间） -- 商品排序（价格、销量、时间、综合） - -**数据字段规格**： -- 商品基础：id, merchant_id, category_id, name, description, base_price, original_price, stock, sales, status -- 商品图片：main_image_url, image_urls (JSONB) -- 商品规格：sku_code, specifications (JSONB), price, stock -- 分类：id, pid (parent_id), name, icon, sort - -**业务规则**： -- 商品状态：0-下架，1-上架，2-审核中 -- 库存扣减：下单时扣减，取消订单时恢复 -- 价格计算：支持原价、现价、会员价 - -#### 1.1.3 订单系统 (Order System) -**功能清单**： -- 订单创建（购物车结算、立即购买） -- 订单确认（地址选择、优惠券选择、运费计算） -- 订单支付（微信支付、支付宝、余额支付） -- 订单状态流转（待支付→已支付→已发货→已收货→已完成） -- 订单取消（用户取消、超时取消） -- 订单退款（申请退款、审核退款、退款完成） -- 订单评价（商品评价、商家回复） - -**数据字段规格**： -- 订单主表：id, order_no, user_id, merchant_id, total_amount, discount_amount, delivery_fee, actual_amount, order_status, payment_status, payment_method, delivery_address (JSONB) -- 订单商品：order_id, product_id, sku_id, product_name, price, quantity, total_amount -- 订单状态：1-待支付，2-已支付，3-已发货，4-已收货，5-已完成，6-已取消，7-退款中，8-已退款 - -**业务规则**： -- 订单号生成：唯一订单号（如：ORD20240101000001） -- 超时取消：30分钟未支付自动取消 -- 库存检查：下单时检查库存，库存不足提示 -- 价格锁定：订单创建时锁定商品价格 - -#### 1.1.4 购物车系统 (Cart System) -**功能清单**： -- 购物车添加（商品、SKU、数量） -- 购物车编辑（数量修改、删除） -- 购物车选择（单选、全选） -- 购物车结算（批量结算、价格计算） - -**数据字段规格**： -- 购物车：id, user_id, product_id, sku_id, quantity, selected - -**业务规则**： -- 同一商品同一SKU合并数量 -- 商品下架时从购物车移除提示 -- 库存不足时提示并限制数量 - -#### 1.1.5 营销系统 (Marketing System) -**功能清单**： -- 优惠券（满减券、折扣券、免运费券） -- 优惠券领取（用户领取、系统发放） -- 优惠券使用（下单时选择、自动抵扣） -- 拼团活动（创建拼团、参团、成团） -- 秒杀活动（限时秒杀、库存限制） -- 砍价活动（发起砍价、好友助力） -- 积分系统（积分获取、积分兑换） -- 签到奖励（每日签到、连续签到） - -**数据字段规格**： -- 优惠券模板：id, name, coupon_type, discount_type, discount_value, min_order_amount, total_quantity, start_time, end_time, status -- 用户优惠券：id, user_id, template_id, coupon_code, status, used_at, expire_at -- 优惠券类型：1-满减，2-折扣，3-免运费，4-新人券，5-会员券 - -**业务规则**： -- 优惠券有效期检查 -- 优惠券使用条件（满额、指定商品、指定分类） -- 每人限领数量 - -#### 1.1.6 配送系统 (Delivery System) -**功能清单**： -- 配送员管理（注册、认证、审核） -- 配送任务分配（自动分配、手动分配） -- 配送状态跟踪（待接单→已接单→已取货→配送中→已送达） -- 配送费用计算（距离、重量、时间） - -**数据字段规格**： -- 配送员：id, user_id, real_name, id_card, vehicle_type, work_status, current_location (JSONB), service_areas (Array) -- 配送任务：id, order_id, driver_id, pickup_address (JSONB), delivery_address (JSONB), distance, delivery_fee, status - -**业务规则**： -- 配送员认证审核 -- 配送范围限制 -- 配送费用计算规则 - -#### 1.1.7 评价系统 (Review System) -**功能清单**： -- 商品评价（评分、文字、图片） -- 商家回复 -- 评价展示（全部、好评、中评、差评） -- 评价统计（好评率、平均分） - -**数据字段规格**： -- 评价：id, order_id, product_id, user_id, rating, content, images (Array), reply_content, reply_time, status - -**业务规则**： -- 仅已收货订单可评价 -- 评价后不可修改，可追评 -- 匿名评价选项 - -#### 1.1.8 店铺系统 (Shop System) -**功能清单**： -- 店铺创建（商家注册店铺） -- 店铺信息管理（名称、Logo、简介、轮播图） -- 店铺认证（营业执照、资质审核） -- 店铺营业状态（营业中、休息中、关闭） -- 店铺评分（综合评分、服务评分、商品评分） - -**数据字段规格**： -- 店铺：id, merchant_id, shop_name, shop_logo, shop_banner, shop_description, shop_status, rating, total_sales - -**业务规则**： -- 商家认证后才能开店 -- 店铺关闭后商品自动下架 -- 店铺评分计算规则 - -### 1.2 管理后台功能 - -#### 1.2.1 商品管理 -- 商品列表（搜索、筛选、排序） -- 商品审核（上架审核、下架管理） -- 分类管理（分类树、排序） -- 品牌管理 - -#### 1.2.2 订单管理 -- 订单列表（状态筛选、搜索） -- 订单详情查看 -- 订单发货 -- 退款审核 - -#### 1.2.3 用户管理 -- 用户列表 -- 用户详情 -- 用户状态管理（冻结、解冻） - -#### 1.2.4 营销管理 -- 优惠券管理（创建、发放、统计） -- 活动管理（拼团、秒杀、砍价） - -#### 1.2.5 系统设置 -- 系统配置（支付配置、物流配置） -- 权限管理 -- 数据统计 - -### 1.3 前端页面清单 - -#### 1.3.1 消费者端 (Consumer) -- 首页（轮播图、分类导航、推荐商品、热门商品） -- 分类页（分类列表、商品列表） -- 商品详情页（商品信息、SKU选择、评价、推荐） -- 购物车页 -- 订单确认页 -- 订单列表页 -- 订单详情页 -- 个人中心（信息、订单、地址、优惠券、收藏） -- 搜索页 -- 评价页 - -#### 1.3.2 商家端 (Merchant) -- 商家中心首页（数据统计、订单概览） -- 商品管理（列表、添加、编辑） -- 订单管理（列表、详情、发货） -- 店铺设置 -- 数据统计 - -#### 1.3.3 配送端 (Delivery) -- 配送中心首页（待接单、配送中、已完成） -- 订单详情 -- 配送路线 - -#### 1.3.4 管理后台 (Admin) -- 登录页 -- 首页（数据概览） -- 商品管理 -- 订单管理 -- 用户管理 -- 营销管理 -- 系统设置 - ---- - -## 二、架构映射 (Architecture Mapping) - -### 2.1 前端架构映射：Vue/UniApp → uvue - -#### 2.1.1 技术栈对比 - -| CRMEB 原技术 | 目标技术 (uvue) | 说明 | -| ------------ | ------------------------------ | -------------- | -| Vue 2/3 | ` -``` - ---- - -## 四、验证清单 (Verification Checklist) - -### 4.1 功能验证 - -#### 4.1.1 用户系统 -- [ ] 用户注册（手机号、邮箱） -- [ ] 用户登录（密码、验证码） -- [ ] 用户信息修改 -- [ ] 地址添加/编辑/删除 -- [ ] 默认地址设置 - -#### 4.1.2 商品系统 -- [ ] 商品列表展示（分页、筛选、排序） -- [ ] 商品详情展示 -- [ ] 商品搜索 -- [ ] 分类导航 -- [ ] SKU 选择 -- [ ] 商家商品管理（增删改查） - -#### 4.1.3 购物车 -- [ ] 添加商品到购物车 -- [ ] 修改购物车商品数量 -- [ ] 删除购物车商品 -- [ ] 购物车商品选择 -- [ ] 购物车价格计算 - -#### 4.1.4 订单系统 -- [ ] 订单确认页（地址、优惠券、运费） -- [ ] 创建订单 -- [ ] 订单支付 -- [ ] 订单列表（状态筛选） -- [ ] 订单详情 -- [ ] 订单取消 -- [ ] 订单退款 - -#### 4.1.5 营销系统 -- [ ] 优惠券列表 -- [ ] 优惠券领取 -- [ ] 优惠券使用 -- [ ] 优惠券过期处理 - -### 4.2 权限验证 - -- [ ] 用户只能查看/修改自己的数据 -- [ ] 商家只能管理自己的商品和订单 -- [ ] 管理员可以查看所有数据 -- [ ] 未登录用户只能查看公开商品 -- [ ] RLS 策略正确生效 - -### 4.3 性能验证 - -- [ ] 商品列表加载速度（< 2秒） -- [ ] 图片加载优化（懒加载） -- [ ] 分页加载流畅 -- [ ] 数据库查询性能（索引优化） - -### 4.4 安全验证 - -- [ ] SQL 注入防护（参数化查询） -- [ ] XSS 防护（数据转义） -- [ ] 权限验证（RLS） -- [ ] 敏感数据加密 - -### 4.5 兼容性验证 - -- [ ] Android 平台 -- [ ] iOS 平台（如支持） -- [ ] Web 平台（如支持） -- [ ] 不同屏幕尺寸适配 - ---- - -## 五、差异清单 (Difference List) - -### 5.1 允许的差异 - -1. **UI 风格差异** - - 可以重新设计 UI，不要求与 CRMEB 完全一致 - - 遵循现代 UI 设计规范 - -2. **交互细节差异** - - 动画效果可以不同 - - 页面布局可以优化 - -3. **非核心功能差异** - - 某些营销活动（如砍价、拼团）可以简化或延后实现 - - 数据统计功能可以简化 - -### 5.2 不允许的差异 - -1. **核心业务流程** - - 订单流程必须完整（创建→支付→发货→收货→完成） - - 库存扣减逻辑必须正确 - - 价格计算必须准确 - -2. **数据一致性** - - 订单金额必须准确 - - 库存数据必须准确 - - 用户余额必须准确 - -3. **权限控制** - - 用户权限必须正确 - - 数据访问权限必须正确 - ---- - -## 六、反抄袭自证 - -### 6.1 参考资料说明 - -本文档仅参考以下公开资料： - -1. **CRMEB 项目 README.md** - - 仅用于了解项目功能模块和业务范围 - - 未参考任何 PHP 源码实现 - -2. **Supabase 官方文档** - - https://supabase.com/docs - - 用于了解 Supabase API 使用方式 - -3. **uni-app x 官方文档** - - https://uniapp.dcloud.net.cn/uni-app-x/ - - 用于了解 uvue 语法和规范 - -4. **PostgreSQL 官方文档** - - https://www.postgresql.org/docs/ - - 用于了解数据库功能和语法 - -### 6.2 实现方式说明 - -1. **数据库设计** - - 基于业务需求独立设计表结构 - - 使用 `ml_` 前缀区分商城模块 - - 参考现有 `doc_mall/database/` 中的设计 - -2. **前端实现** - - 使用 uvue 语法独立编写页面 - - 通过 `components/supadb` 调用 Supabase API - - 不复制任何 Vue 组件代码 - -3. **后端实现** - - 使用 Supabase RLS + Edge Functions - - 不编写任何 PHP 代码 - - 业务逻辑通过数据库函数和触发器实现 - -### 6.3 代码原创性声明 - -- 所有代码均为基于功能规格的独立实现 -- 未复制 CRMEB 项目的任何源码 -- 未复制任何第三方项目的实现代码 -- 仅参考公开 API 文档和规范 - ---- - -## 七、参考资料列表 - -### 7.1 官方文档 - -1. **Supabase** - - REST API: https://supabase.com/docs/reference/javascript/introduction - - Auth: https://supabase.com/docs/guides/auth - - RLS: https://supabase.com/docs/guides/auth/row-level-security - - Storage: https://supabase.com/docs/guides/storage - -2. **uni-app x** - - 概述: https://uniapp.dcloud.net.cn/uni-app-x/ - - uvue: https://uniapp.dcloud.net.cn/uni-app-x/component/ - - UTS: https://uniapp.dcloud.net.cn/uni-app-x/uts/ - -3. **PostgreSQL** - - 官方文档: https://www.postgresql.org/docs/ - - JSONB: https://www.postgresql.org/docs/current/datatype-json.html - -### 7.2 项目内部文档 - -1. `doc_mall/MODULE_ANALYSIS.md` - 模块分析报告 -2. `doc_mall/database/` - 数据库设计文档 -3. `components/supadb/SIMPLIFIED_API_GUIDE.md` - Supabase API 使用指南 -4. `types/mall-types.uts` - 类型定义 - ---- - -## 八、总结 - -本文档基于 **Clean-Room 重构原则**，通过分析 CRMEB 项目的功能规格，制定了完整的重构计划： - -1. **功能规格提取**：明确了所有核心业务模块的功能需求 -2. **架构映射**：完成了 Vue→uvue、PHP→Supabase 的技术栈映射 -3. **实现计划**：制定了详细的开发里程碑和目录结构 -4. **验证清单**：提供了完整的测试验证标准 - -所有实现将基于功能规格独立开发，不复制任何源码，确保代码的原创性和合规性。 - ---- - -**文档版本**: v1.0 -**创建时间**: 2025-01-XX -**状态**: ✅ 待实施 diff --git a/docs/CRMEB_TO_UVUE_MIGRATION_GUIDE.md b/docs/CRMEB_TO_UVUE_MIGRATION_GUIDE.md new file mode 100644 index 00000000..7d4d0909 --- /dev/null +++ b/docs/CRMEB_TO_UVUE_MIGRATION_GUIDE.md @@ -0,0 +1,807 @@ +# CRMEB商城系统到uvue项目的重构迁移指南 + +## 项目概述 + +本文档基于CRMEB开源商城系统（PHP版本），指导如何将其核心功能迁移到基于uvue技术栈的项目中。后端使用`@components/supadb`组件库实现，不使用PHP技术栈。 + +## 参考项目分析 + +### CRMEB核心功能模块 + +#### 1. 用户系统 (User Module) +- **用户注册登录**：手机号验证码、微信授权登录 +- **用户资料管理**：个人信息、收货地址、会员等级 +- **用户积分系统**：积分获取、积分消费记录 +- **分销系统**：用户推广、佣金结算 + +#### 2. 商品系统 (Product Module) +- **商品管理**：商品信息、SKU规格、商品分类 +- **商品展示**：商品详情、商品列表、商品搜索 +- **库存管理**：商品库存、规格库存管理 + +#### 3. 订单系统 (Order Module) +- **购物车**：添加商品、修改数量、删除商品 +- **订单创建**：订单确认、地址选择、支付方式 +- **订单管理**：订单状态跟踪、订单取消、退款处理 +- **物流跟踪**：快递信息查询、物流状态更新 + +#### 4. 营销活动 (Activity Module) +- **秒杀活动**：限时抢购、库存锁定 +- **拼团活动**：团购发起、参团流程 +- **砍价活动**：好友助力、砍价进度 +- **优惠券系统**：券领取、使用规则 +- **积分商城**：积分兑换商品 + +#### 5. 支付系统 (Payment Module) +- **多渠道支付**：微信支付、支付宝、余额支付 +- **支付回调**：订单状态更新、支付记录 + +#### 6. 客服系统 (Service Module) +- **在线客服**：实时聊天、消息记录 +- **售后服务**：退换货处理、服务评价 + +#### 7. 内容管理系统 (CMS Module) +- **文章系统**：资讯发布、分类管理 +- **广告位管理**：首页banner、推荐位 + +#### 8. 系统配置 (System Module) +- **基础配置**：站点信息、支付配置、物流配置 +- **权限管理**：管理员权限、操作日志 + +## 技术栈对比 + +### 原CRMEB技术栈 +``` +后端: ThinkPHP 6 + MySQL + Redis +前端: Vue2 + ElementUI + UniApp +其他: Workerman(长连接)、队列、定时任务 +``` + +### 目标技术栈 +``` +后端: Supabase (PostgreSQL + Auth + Storage + Edge Functions) +前端: uvue + @components/supadb +其他: 实时订阅、文件存储、服务器less函数 +``` + +## 数据架构设计 + +### Supabase数据库表结构设计 + +#### 核心数据表 + +##### 1. 用户表 (users) +```sql +-- 继承Supabase auth.users表，扩展字段 +CREATE TABLE public.users ( + id UUID REFERENCES auth.users(id) PRIMARY KEY, + phone TEXT, + nickname TEXT, + avatar_url TEXT, + gender INTEGER DEFAULT 0, + birthday DATE, + level_id INTEGER DEFAULT 0, + integral INTEGER DEFAULT 0, + balance DECIMAL(10,2) DEFAULT 0, + spread_uid INTEGER, + spread_time TIMESTAMP WITH TIME ZONE, + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() +); +``` + +##### 2. 商品表 (products) +```sql +CREATE TABLE public.products ( + id SERIAL PRIMARY KEY, + title TEXT NOT NULL, + description TEXT, + images TEXT[], + category_id INTEGER, + brand_id INTEGER, + price DECIMAL(10,2), + ot_price DECIMAL(10,2), + cost DECIMAL(10,2), + stock INTEGER DEFAULT 0, + sales INTEGER DEFAULT 0, + is_show BOOLEAN DEFAULT true, + is_del BOOLEAN DEFAULT false, + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() +); +``` + +##### 3. 商品规格表 (product_skus) +```sql +CREATE TABLE public.product_skus ( + id SERIAL PRIMARY KEY, + product_id INTEGER REFERENCES products(id), + sku TEXT, + price DECIMAL(10,2), + stock INTEGER DEFAULT 0, + image TEXT, + attributes JSONB, + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() +); +``` + +##### 4. 订单表 (orders) +```sql +CREATE TABLE public.orders ( + id SERIAL PRIMARY KEY, + order_sn TEXT UNIQUE, + user_id UUID REFERENCES users(id), + total_price DECIMAL(10,2), + pay_price DECIMAL(10,2), + coupon_price DECIMAL(10,2), + pay_type INTEGER DEFAULT 1, -- 1微信 2余额 3线下 + status INTEGER DEFAULT 0, -- 订单状态 + address_info JSONB, + mark TEXT, + paid BOOLEAN DEFAULT false, + pay_time TIMESTAMP WITH TIME ZONE, + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() +); +``` + +##### 5. 订单商品表 (order_items) +```sql +CREATE TABLE public.order_items ( + id SERIAL PRIMARY KEY, + order_id INTEGER REFERENCES orders(id), + product_id INTEGER REFERENCES products(id), + sku_id INTEGER REFERENCES product_skus(id), + product_title TEXT, + product_image TEXT, + sku_info JSONB, + price DECIMAL(10,2), + quantity INTEGER, + total_price DECIMAL(10,2), + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() +); +``` + +##### 6. 购物车表 (cart) +```sql +CREATE TABLE public.cart ( + id SERIAL PRIMARY KEY, + user_id UUID REFERENCES users(id), + product_id INTEGER REFERENCES products(id), + sku_id INTEGER REFERENCES product_skus(id), + quantity INTEGER, + selected BOOLEAN DEFAULT true, + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() +); +``` + +##### 7. 优惠券表 (coupons) +```sql +CREATE TABLE public.coupons ( + id SERIAL PRIMARY KEY, + title TEXT, + type INTEGER, -- 1满减 2折扣 + value DECIMAL(10,2), + min_price DECIMAL(10,2), + use_start_time TIMESTAMP WITH TIME ZONE, + use_end_time TIMESTAMP WITH TIME ZONE, + stock INTEGER, + receive_count INTEGER DEFAULT 0, + is_show BOOLEAN DEFAULT true, + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() +); +``` + +##### 8. 用户优惠券表 (user_coupons) +```sql +CREATE TABLE public.user_coupons ( + id SERIAL PRIMARY KEY, + user_id UUID REFERENCES users(id), + coupon_id INTEGER REFERENCES coupons(id), + status INTEGER DEFAULT 0, -- 0未使用 1已使用 2已过期 + use_time TIMESTAMP WITH TIME ZONE, + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() +); +``` + +## API接口设计 + +### 使用@components/supadb实现的数据操作 + +#### 用户相关接口 + +##### 用户注册 +```typescript +// 使用Supabase Auth实现 +const { data, error } = await supa.auth.signUp({ + email: 'user@example.com', + password: 'password' +}) +``` + +##### 用户登录 +```typescript +const { data, error } = await supa.auth.signInWithPassword({ + email: 'user@example.com', + password: 'password' +}) +``` + +##### 获取用户信息 +```typescript +// 使用supadb组件 + + + +``` + +##### 更新用户信息 +```typescript +const result = await supa.from('users').update(userData).eq('id', userId) +``` + +#### 商品相关接口 + +##### 获取商品列表 +```vue + + + + + + +``` + +##### 获取商品详情 +```vue + + + +``` + +##### 商品搜索 +```vue + + + +``` + +#### 订单相关接口 + +##### 创建订单 +```typescript +// 先创建订单记录 +const orderData = { + order_sn: generateOrderSn(), + user_id: userId, + total_price: totalPrice, + // ...其他字段 +} +const { data: order } = await supa.from('orders').insert(orderData).select().single() + +// 然后创建订单商品记录 +const orderItems = cartItems.map(item => ({ + order_id: order.id, + product_id: item.product_id, + // ...其他字段 +})) +await supa.from('order_items').insert(orderItems) +``` + +##### 获取订单列表 +```vue + + + + + +``` + +#### 营销活动接口 + +##### 秒杀活动 +```vue + + + +``` + +##### 优惠券领取 +```typescript +// 检查用户是否已领取 +const { data: existing } = await supa + .from('user_coupons') + .select('*') + .eq('user_id', userId) + .eq('coupon_id', couponId) + .single() + +if (!existing) { + await supa.from('user_coupons').insert({ + user_id: userId, + coupon_id: couponId + }) +} +``` + +## uvue前端页面重构方案 + +### 页面结构重组 + +#### 1. 首页 (pages/index/index.uvue) +```vue + + + +``` + +#### 2. 商品详情页 (pages/goods/detail.uvue) +```vue + + + +``` + +#### 3. 购物车页面 (pages/cart/index.uvue) +```vue + + + +``` + +## 实时功能实现 + +### 使用Supabase实时订阅 + +#### 订单状态更新监听 +```typescript +// 监听订单状态变化 +const orderSubscription = supa + .channel('order-updates') + .on('postgres_changes', + { + event: 'UPDATE', + schema: 'public', + table: 'orders', + filter: `user_id=eq.${userId}` + }, + (payload) => { + console.log('Order updated:', payload) + // 更新订单状态 + } + ) + .subscribe() +``` + +#### 库存变化监听 +```typescript +// 监听商品库存变化 +const stockSubscription = supa + .channel('stock-updates') + .on('postgres_changes', + { + event: 'UPDATE', + schema: 'public', + table: 'products' + }, + (payload) => { + // 更新本地商品库存 + updateLocalStock(payload.new) + } + ) + .subscribe() +``` + +## 文件存储实现 + +### 使用Supabase Storage + +#### 商品图片上传 +```typescript +const uploadProductImage = async (filePath: string, productId: number) => { + const fileName = `product_${productId}_${Date.now()}.jpg` + const { data, error } = await supa.storage + .from('products') + .upload(fileName, filePath) + + if (data) { + const { data: urlData } = supa.storage + .from('products') + .getPublicUrl(fileName) + + return urlData.publicUrl + } +} +``` + +#### 用户头像上传 +```typescript +const uploadAvatar = async (filePath: string) => { + const fileName = `avatar_${userId}_${Date.now()}.jpg` + const { data, error } = await supa.storage + .from('avatars') + .upload(fileName, filePath) + + if (data) { + const { data: urlData } = supa.storage + .from('avatars') + .getPublicUrl(fileName) + + // 更新用户头像 + await supa.from('users').update({ + avatar_url: urlData.publicUrl + }).eq('id', userId) + } +} +``` + +## 服务器端逻辑实现 + +### 使用Supabase Edge Functions + +#### 订单创建函数 +```typescript +// supabase/functions/create-order/index.ts +import { serve } from "https://deno.land/std@0.168.0/http/server.ts" +import { createClient } from 'https://esm.sh/@supabase/supabase-js@2' + +serve(async (req) => { + const { userId, items, address } = await req.json() + + const supabase = createClient( + Deno.env.get('SUPABASE_URL') ?? '', + Deno.env.get('SUPABASE_ANON_KEY') ?? '' + ) + + // 生成订单号 + const orderSn = `ORDER${Date.now()}${Math.random().toString(36).substr(2, 6).toUpperCase()}` + + // 计算总价 + let totalPrice = 0 + for (const item of items) { + const { data: product } = await supabase + .from('products') + .select('price') + .eq('id', item.productId) + .single() + + totalPrice += product.price * item.quantity + } + + // 创建订单 + const { data: order, error } = await supabase + .from('orders') + .insert({ + order_sn: orderSn, + user_id: userId, + total_price: totalPrice, + address_info: address + }) + .select() + .single() + + if (error) throw error + + // 创建订单商品记录 + const orderItems = items.map(item => ({ + order_id: order.id, + product_id: item.productId, + quantity: item.quantity, + price: item.price, + total_price: item.price * item.quantity + })) + + const { error: itemsError } = await supabase + .from('order_items') + .insert(orderItems) + + if (itemsError) throw itemsError + + return new Response( + JSON.stringify({ order }), + { headers: { "Content-Type": "application/json" } } + ) +}) +``` + +#### 支付回调函数 +```typescript +// supabase/functions/payment-callback/index.ts +import { serve } from "https://deno.land/std@0.168.0/http/server.ts" +import { createClient } from 'https://esm.sh/@supabase/supabase-js@2' + +serve(async (req) => { + const { orderSn, paymentResult } = await req.json() + + const supabase = createClient( + Deno.env.get('SUPABASE_URL') ?? '', + Deno.env.get('SUPABASE_ANON_KEY') ?? '' + ) + + // 更新订单支付状态 + const { error } = await supabase + .from('orders') + .update({ + paid: true, + pay_time: new Date().toISOString(), + status: 1 // 已支付 + }) + .eq('order_sn', orderSn) + + if (error) throw error + + return new Response( + JSON.stringify({ success: true }), + { headers: { "Content-Type": "application/json" } } + ) +}) +``` + +## 组件重构对照表 + +### CRMEB组件 → uvue组件映射 + +| CRMEB组件 | uvue组件 | 功能说明 | +|----------|---------|---------| +| HomeComb | home-comb.uvue | 首页搜索组合 | +| GoodList | product-list.uvue | 商品列表 | +| CouponWindow | coupon-popup.uvue | 优惠券弹窗 | +| CartList | cart-list.uvue | 购物车列表 | +| Payment | payment-selector.uvue | 支付方式选择 | +| AddressWindow | address-selector.uvue | 地址选择弹窗 | +| UserEvaluation | product-review.uvue | 商品评价 | +| ShareRedPackets | share-popup.uvue | 分享红包 | + +## 性能优化建议 + +### 1. 数据缓存策略 +```typescript +// 使用Supabase内置缓存 +const { data, error } = await supa + .from('products') + .select('*') + .eq('category_id', categoryId) + .order('sales', { ascending: false }) + .limit(20) + // 启用缓存 + .single() +``` + +### 2. 图片懒加载 +```vue + +``` + +### 3. 列表虚拟化 +```vue + +``` + +## 部署和维护 + +### 环境配置 +```javascript +// config/app.js +export default { + supabase: { + url: 'https://your-project.supabase.co', + anonKey: 'your-anon-key', + serviceRoleKey: 'your-service-role-key' // 服务端使用 + } +} +``` + +### 数据库迁移 +```sql +-- 数据库初始化脚本 +-- 创建表结构 +-- 设置RLS策略 +-- 创建索引 +-- 设置触发器 +``` + +### 监控和日志 +```typescript +// 错误监控 +const handleError = (error) => { + console.error('App Error:', error) + // 上报到监控系统 +} + +// 性能监控 +const reportPerformance = (metrics) => { + // 上报性能数据 +} +``` + +## 总结 + +通过本重构指南，我们将CRMEB的核心功能成功迁移到基于uvue + Supabase的技术栈： + +1. **数据层**：使用Supabase替代MySQL + Redis +2. **API层**：使用@components/supadb替代ThinkPHP +3. **前端**：使用uvue替代uni-app +4. **实时功能**：使用Supabase实时订阅 +5. **文件存储**：使用Supabase Storage +6. **服务器逻辑**：使用Edge Functions + +这种架构具有以下优势： +- **开发效率高**：减少后端开发工作 +- **维护成本低**：Serverless架构 +- **扩展性好**：支持实时功能和全球化部署 +- **安全性高**：Supabase提供完善的安全机制 + +实际迁移时需要根据具体业务需求进行调整，并充分测试各项功能。 \ No newline at end of file diff --git a/docs/FRONTEND_ARCHITECTURE_ANALYSIS.md b/docs/FRONTEND_ARCHITECTURE_ANALYSIS.md new file mode 100644 index 00000000..1e8000a5 --- /dev/null +++ b/docs/FRONTEND_ARCHITECTURE_ANALYSIS.md @@ -0,0 +1,427 @@ +# CRMEB Admin 前端架构梳理分析 + +## 项目概述 +- **项目名称**: CRMEB Admin Template +- **技术栈**: Vue.js + Element UI + Vue Router + Vuex +- **项目类型**: 电商管理后台系统 +- **分析时间**: 2026-01-23 + +## 1. 页面总览表 + +| 路由路径 | 页面标题 | 所属端 | 是否tab/子包 | 说明 | 入口文件 | +|---------|---------|-------|-------------|------|---------| +| `/admin/index` | 主页 | Admin后台 | 否 | 系统首页，包含基础统计信息 | `src/pages/index/index.vue` | +| `/admin/product/product_list` | 商品管理 | Admin后台 | 否 | 商品列表管理页面 | `src/pages/product/productList/index.vue` | +| `/admin/product/product_classify` | 商品分类 | Admin后台 | 否 | 商品分类管理 | `src/pages/product/productClassify/index.vue` | +| `/admin/product/add_product/:id?` | 商品添加 | Admin后台 | 否 | 添加/编辑商品 | `src/pages/product/productAdd/index.vue` | +| `/admin/order/list` | 订单管理 | Admin后台 | 否 | 订单列表管理 | `src/pages/order/orderList/index.vue` | +| `/admin/order/offline` | 收银订单 | Admin后台 | 否 | 线下收银订单 | `src/pages/order/offline/index.vue` | +| `/admin/order/refund` | 售后订单 | Admin后台 | 否 | 售后退款订单 | `src/pages/order/refund/index.vue` | +| `/admin/user/list` | 用户管理 | Admin后台 | 否 | 用户列表管理 | `src/pages/user/list/index.vue` | +| `/admin/user/level` | 用户等级 | Admin后台 | 否 | 用户等级管理 | `src/pages/user/level/index.vue` | +| `/admin/user/group` | 用户分组 | Admin后台 | 否 | 用户分组管理 | `src/pages/user/group/index.vue` | +| `/admin/setting/system_config` | 系统设置 | Admin后台 | 否 | 系统基础配置 | `src/pages/setting/setSystem/index.vue` | +| `/admin/setting/system_role/index` | 身份管理 | Admin后台 | 否 | 管理员角色管理 | `src/pages/setting/systemRole/index.vue` | +| `/admin/setting/system_admin/index` | 管理员列表 | Admin后台 | 否 | 管理员账户管理 | `src/pages/setting/systemAdmin/index.vue` | +| `/admin/marketing/store_combination/index` | 拼团商品 | Admin后台 | 否 | 拼团活动商品管理 | `src/pages/marketing/storeCombination/index.vue` | +| `/admin/marketing/store_coupon_issue/index` | 优惠券 | Admin后台 | 否 | 优惠券发放管理 | `src/pages/marketing/storeCouponIssue/index.vue` | +| `/admin/system/log` | 前端日志 | Admin后台 | 否 | 系统日志查看 | `src/pages/system/log/index.vue` | + +**来源**: `src/router/modules/*.js` 文件中的路由配置 + +## 2. 页面关系树 + +``` +CRMEB Admin 后台系统 +├── 主页 (home_index) +│ ├── 基础信息展示 (baseInfo) +│ ├── 快捷菜单 (gridMenu) +│ ├── 访问统计图表 (visitChart) +│ └── 用户统计图表 (userChart) +├── 商品管理 (product) +│ ├── 商品列表 (productList) +│ │ ├── 搜索筛选区 +│ │ ├── 商品列表表格 +│ │ └── 操作按钮区 +│ ├── 商品分类 (productClassify) +│ ├── 添加商品 (productAdd) +│ ├── 商品评论 (productEvaluate) +│ ├── 商品规格 (productAttr) +│ ├── 商品参数 (paramList) +│ └── 商品标签 (labelList) +├── 订单管理 (order) +│ ├── 订单列表 (orderList) +│ ├── 收银订单 (offline) +│ ├── 售后订单 (refund) +│ └── 发票管理 (invoice) +├── 用户管理 (user) +│ ├── 用户列表 (list) +│ │ ├── 用户搜索筛选 +│ │ ├── 用户列表表格 +│ │ └── 用户详情弹窗 +│ ├── 用户等级 (level) +│ ├── 用户分组 (group) +│ ├── 用户标签 (label) +│ ├── 会员类型 (type) +│ ├── 卡密会员 (card) +│ ├── 会员记录 (record) +│ └── 会员权益 (right) +├── 系统设置 (setting) +│ ├── 系统配置 (setSystem) +│ ├── 身份管理 (systemRole) +│ ├── 管理员列表 (systemAdmin) +│ ├── 消息管理 (notification) +│ ├── 物流配置 (logistics) +│ ├── 短信配置 (sms) +│ ├── 商城配置 (config) +│ ├── 主题风格 (themeStyle) +│ ├── 店铺装修 (devise) +│ ├── 客服管理 (service) +│ ├── 城市数据 (dada) +│ ├── 运费模板 (templates) +│ ├── 提货点管理 (store) +│ ├── 核销员管理 (staff) +│ └── 核销订单 (order) +├── 营销活动 (marketing) +│ ├── 拼团商品 (combinalist) +│ ├── 优惠券 (storeCouponIssue) +│ ├── 秒杀商品 (storeSeckill) +│ ├── 积分商品 (storeIntegral) +│ └── 砍价商品 (bargain) +├── 财务管理 (finance) +│ ├── 财务对账 (financeList) +│ ├── 资金记录 (capitalFlow) +│ ├── 佣金记录 (commissionList) +│ ├── 提现申请 (extractList) +│ └── 账单记录 (billList) +├── 系统管理 (system) +│ ├── 代码生成 (codeGeneration) +│ ├── 文件管理 (fileList) +│ ├── 维护管理 (maintain) +│ └── 数据配置 (groupData) +├── 应用管理 (app) +│ ├── 微信菜单 (wechatMenu) +│ ├── 微信回复 (wechatReply) +│ └── 微信用户 (wechatUser) +└── 统计报表 (statistic) + ├── 产品统计 (productStatistic) + ├── 用户统计 (userStatistic) + ├── 订单统计 (orderStatistic) + └── 交易统计 (transactionStatistic) +``` + +## 3. 页面区域-文件映射表 + +### 3.1 主页 (home_index) + +| 区域名 | 对应组件/文件 | 说明 | 关键状态 | 关键接口 | +|-------|---------------|------|---------|---------| +| 基础信息展示区 | `src/pages/index/components/baseInfo.vue` | 显示今日/昨日数据对比和总计信息 | infoList数组 | `headerApi` (来源: `src/api/index.js`) | +| 快捷菜单区 | `src/pages/index/components/gridMenu.vue` | 九宫格快捷入口菜单 | - | - | +| 访问统计图表 | `src/pages/index/components/visitChart.vue` | 订单统计图表展示 | visitType, visitDate | - | +| 用户统计图表 | `src/pages/index/components/userChart.vue` | 用户数据统计图表 | - | - | +| 页面布局容器 | `src/pages/index/index.vue` | 主页布局容器，组合上述组件 | userInfo | `auth()` (来源: `src/api/system.js`) | +| Vuex状态 | `src/store/module/userInfo.js` | 用户信息状态管理 | userInfo | - | + +**来源**: `src/pages/index/index.vue` (行7-15), `src/store/module/userInfo.js` + +### 3.2 商品列表页面 (product_productList) + +| 区域名 | 对应组件/文件 | 说明 | 关键状态 | 关键接口 | +|-------|---------------|------|---------|---------| +| 搜索筛选区 | 内联在页面模板中 | 商品名称、类型、分类、配送方式等筛选条件 | artFrom表单对象 | - | +| 商品列表表格 | 内联在页面模板中 | 商品数据表格展示，包含分页 | tableData数组 | `productList()` (来源: `src/api/product.js`) | +| 操作按钮区 | 内联在页面模板中 | 批量操作、添加商品等按钮 | - | - | +| 页面布局容器 | `src/pages/product/productList/index.vue` | 商品管理主页面 | artFrom, tableData, loading | `productList()`, `productStatus()` (来源: `src/api/product.js`) | + +**来源**: `src/pages/product/productList/index.vue` (行1-50), `src/api/product.js` + +### 3.3 用户列表页面 (user_list) + +| 区域名 | 对应组件/文件 | 说明 | 关键状态 | 关键接口 | +|-------|---------------|------|---------|---------| +| 用户搜索筛选区 | 内联在页面模板中 | 用户昵称、等级、分组等筛选条件 | userFrom表单对象, field_key | - | +| 用户列表表格 | 内联在页面模板中 | 用户数据表格，包含用户信息展示 | tableData数组 | `userList()` (来源: `src/api/user.js`) | +| 用户详情弹窗 | `src/pages/user/list/handle/userDetails.vue` | 用户详细信息弹窗组件 | visible, userInfo | - | +| 用户编辑弹窗 | `src/pages/user/list/handle/userEdit.vue` | 用户信息编辑弹窗 | visible, editForm | `userEdit()` (来源: `src/api/user.js`) | +| 页面布局容器 | `src/pages/user/list/index.vue` | 用户管理主页面 | userFrom, tableData, collapse | `userList()`, `userLevel()`, `userGroup()` (来源: `src/api/user.js`) | + +**来源**: `src/pages/user/list/index.vue` (行1-100), `src/api/user.js` + +## 4. 文件职责清单 + +### 4.1 Pages 目录文件职责 + +#### 主页相关 (src/pages/index/) +- `index.vue`: 主页容器组件，组合统计组件，处理用户认证 +- `components/baseInfo.vue`: 基础统计信息卡片展示 +- `components/gridMenu.vue`: 快捷操作菜单网格 +- `components/visitChart.vue`: 访问统计图表组件 +- `components/userChart.vue`: 用户统计图表组件 + +#### 商品管理 (src/pages/product/) +- `productList/index.vue`: 商品列表页面，包含搜索、筛选、表格展示 +- `productClassify/index.vue`: 商品分类管理页面 +- `productAdd/index.vue`: 商品添加/编辑页面 +- `productReply/index.vue`: 商品评论管理页面 +- `productAttr/index.vue`: 商品规格管理页面 +- `paramList/index.vue`: 商品参数管理页面 +- `labelList/index.vue`: 商品标签管理页面 + +#### 订单管理 (src/pages/order/) +- `orderList/index.vue`: 订单列表管理页面 +- `offline/index.vue`: 收银订单管理页面 +- `refund/index.vue`: 售后订单管理页面 +- `invoice/index.vue`: 发票管理页面 + +#### 用户管理 (src/pages/user/) +- `list/index.vue`: 用户列表主页面 +- `list/handle/userDetails.vue`: 用户详情弹窗组件 +- `list/handle/userEdit.vue`: 用户编辑弹窗组件 +- `list/handle/userEditForm.vue`: 用户编辑表单组件 +- `list/handle/userInfo.vue`: 用户信息展示组件 +- `list/tableExpand.vue`: 用户列表表格展开组件 +- `level/index.vue`: 用户等级管理页面 +- `group/index.vue`: 用户分组管理页面 +- `label/index.vue`: 用户标签管理页面 + +#### 系统设置 (src/pages/setting/) +- `setSystem/index.vue`: 系统配置主页面 +- `systemRole/index.vue`: 管理员角色管理页面 +- `systemAdmin/index.vue`: 管理员列表管理页面 +- `notification/index.vue`: 消息管理页面 +- `notification/notificationEdit.vue`: 消息编辑页面 +- `membershipLevel/index.vue`: 分销等级管理页面 +- `freight/index.vue`: 物流公司管理页面 +- `cityDada/index.vue`: 城市数据管理页面 +- `shippingTemplates/index.vue`: 运费模板管理页面 +- `storeList/index.vue`: 提货点管理页面 +- `clerkList/index.vue`: 核销员管理页面 +- `verifyOrder/index.vue`: 核销订单管理页面 +- `themeStyle/index.vue`: 主题风格设置页面 +- `devise/list.vue`: 店铺装修页面 +- `devisePage/index.vue`: 页面设计页面 +- `link.vue`: 链接管理页面 +- `storage.vue`: 存储配置页面 +- `ticket.vue`: 打印机设置页面 +- `agreement/index.vue`: 协议设置页面 + +#### 营销活动 (src/pages/marketing/) +- `storeCombination/index.vue`: 拼团商品管理页面 +- `storeCombination/combinaList.vue`: 拼团列表页面 +- `storeCouponIssue/index.vue`: 优惠券管理页面 +- `storeSeckill/index.vue`: 秒杀商品管理页面 +- `storeIntegral/index.vue`: 积分商品管理页面 +- `storeBargain/index.vue`: 砍价商品管理页面 + +#### 财务管理 (src/pages/finance/) +- `financeList/index.vue`: 财务对账页面 +- `capitalFlow/index.vue`: 资金记录页面 +- `commissionList/index.vue`: 佣金记录页面 +- `extractList/index.vue`: 提现申请页面 +- `billList/index.vue`: 账单记录页面 + +#### 系统管理 (src/pages/system/) +- `codeGeneration/index.vue`: 代码生成页面 +- `fileList/index.vue`: 文件管理页面 +- `maintain/index.vue`: 维护管理页面 +- `group/list.vue`: 数据配置页面 + +#### 应用管理 (src/pages/app/) +- `wechatMenu/index.vue`: 微信菜单管理页面 +- `wechatReply/index.vue`: 微信回复管理页面 +- `wechatUser/index.vue`: 微信用户管理页面 + +#### 统计报表 (src/pages/statistic/) +- `productStatistic/index.vue`: 产品统计页面 +- `userStatistic/index.vue`: 用户统计页面 +- `orderStatistic/index.vue`: 订单统计页面 +- `transactionStatistic/index.vue`: 交易统计页面 + +### 4.2 Components 目录文件职责 + +#### 通用组件 (src/components/) +- `common-icon/`: 通用图标组件 +- `copyright/`: 版权信息组件 +- `Pagination/`: 分页组件 +- `parent-view/`: 父视图组件 +- `publicSearchFrom/`: 公共搜索表单组件 +- `searchFrom/`: 搜索表单组件 +- `uploadImg/`: 图片上传组件 +- `uploadPictures/`: 多图上传组件 +- `uploadVideo/`: 视频上传组件 +- `uploadVideo2/`: 视频上传组件(增强版) + +#### 表单组件 (src/components/from/) +- `from/`: 通用表单组件 + +#### 图表组件 (src/components/echarts/) +- `echarts/`: ECharts图表基础组件 +- `echartsNew/`: 新版ECharts图表组件 + +#### 移动端配置组件 (src/components/mobileConfig/) +- 包含大量移动端页面配置组件 + +#### 弹窗组件 (src/components/hotpotModal/) +- `hotpotModal/`: 热区弹窗组件 + +#### 编辑器组件 (src/components/wangEditor/) +- `wangEditor/`: 富文本编辑器组件 + +### 4.3 Store 目录文件职责 + +#### Vuex状态管理模块 (src/store/module/) +- `user.js`: 用户登录状态管理 +- `app.js`: 应用全局状态 +- `menus.js`: 菜单数据管理 +- `menu.js`: 当前菜单状态 +- `userInfo.js`: 用户信息管理 +- `userLevel.js`: 用户等级管理 +- `order.js`: 订单相关状态 +- `media.js`: 媒体文件管理 +- `goodSelect.js`: 商品选择状态 +- `moren.js`: 默认配置管理 +- `shopping.js`: 购物相关状态 +- `fresh.js`: 刷新状态管理 +- `kefu.js`: 客服状态管理 +- `integralOrder.js`: 积分订单管理 +- `mobildConfig.js`: 移动端配置 +- `upgrade.js`: 升级状态管理 +- `layout.js`: 布局状态管理 +- `themeConfig.js`: 主题配置 +- `routesList.js`: 路由列表 +- `tagsViewRoutes.js`: 标签页路由 +- `userInfos.js`: 用户信息扩展 +- `keepAliveNames.js`: 缓存页面名称 + +### 4.4 API 目录文件职责 + +#### 接口文件 (src/api/) +- `index.js`: 首页相关接口 +- `account.js`: 账户相关接口 +- `agent.js`: 代理商相关接口 +- `app.js`: 应用相关接口 +- `cms.js`: CMS内容管理接口 +- `common.js`: 通用接口 +- `crud.js`: CRUD通用接口 +- `diy.js`: DIY装修接口 +- `export.js`: 导出相关接口 +- `finance.js`: 财务相关接口 +- `index.js`: 首页统计接口 +- `kefu.js`: 客服相关接口 +- `kefu_mobile.js`: 移动端客服接口 +- `live.js`: 直播相关接口 +- `lottery.js`: 抽奖相关接口 +- `marketing.js`: 营销活动接口 +- `membershipLevel.js`: 会员等级接口 +- `notification.js`: 消息通知接口 +- `order.js`: 订单相关接口 +- `product.js`: 商品相关接口 +- `setting.js`: 设置相关接口 +- `statistic.js`: 统计相关接口 +- `system.js`: 系统相关接口 +- `systemAdmin.js`: 管理员接口 +- `systemBackendRouting.js`: 后端路由接口 +- `systemCodeGeneration.js`: 代码生成接口 +- `systemMenus.js`: 菜单接口 +- `systemOutAccount.js`: 外部账户接口 +- `upload.js`: 上传相关接口 +- `uploadPictures.js`: 图片上传接口 +- `user.js`: 用户相关接口 + +### 4.5 Utils 目录文件职责 + +#### 工具函数 (src/utils/) +- `ase.js`: AES加密工具 +- `authLapse.js`: 认证过期处理 +- `bus.js`: 事件总线 +- `city.js`: 城市数据处理 +- `componentSize.js`: 组件尺寸工具 +- `compressImg.js`: 图片压缩工具 +- `editorImg.js`: 编辑器图片处理 +- `emoji.js`: 表情符号处理 +- `Excel.js`: Excel处理工具 +- `icon.js`: 图标处理工具 +- `index.js`: 工具函数入口 +- `loading.js`: 加载状态管理 +- `modalForm.js`: 弹窗表单工具 +- `newToExcel.js`: 新版Excel导出 +- `public.js`: 公共工具函数 +- `scroll-to.js`: 滚动工具 +- `storage.js`: 本地存储工具 +- `theme.js`: 主题工具 +- `toolsValidate.js`: 表单验证工具 +- `upload.js`: 上传工具 +- `validate.js`: 数据验证工具 +- `videoCloud.js`: 视频云处理 + +### 4.6 Styles 目录文件职责 + +#### 样式文件 (src/theme/) +- `app.scss`: 应用主样式 +- `base.scss`: 基础样式 +- `common/transition.scss`: 过渡动画样式 +- `dark.scss`: 暗色主题 +- `element.scss`: Element UI样式覆盖 +- `iview.scss`: iView样式覆盖 +- `index.scss`: 样式入口文件 +- `loading.scss`: 加载样式 +- `variables.scss`: 样式变量 + +## 5. 未知/缺失信息清单 + +### 5.1 需要补充分析的页面文件 +- `src/pages/kefu/`: 客服模块页面文件（40个文件）- 未详细分析 +- `src/pages/marketing/`: 部分营销活动页面组件 - 未完全追踪依赖关系 +- `src/pages/setting/`: 系统设置下多个子页面 - 未完全分析组件结构 +- `src/pages/system/`: 系统管理页面 - 未详细分析 +- `src/pages/app/`: 应用管理页面 - 未详细分析 +- `src/pages/statistic/`: 统计报表页面 - 未详细分析 + +### 5.2 需要补充的组件依赖 +- `src/components/mobileConfig/`: 35个移动端配置组件 - 未分析具体职责 +- `src/components/mobileConfigRight/`: 39个右侧配置组件 - 未分析具体职责 +- `src/components/mobilePage/`: 28个移动端页面组件 - 未分析具体职责 +- `src/components/mobilePageDiy/`: 23个DIY页面组件 - 未分析具体职责 + +### 5.3 需要补充的API接口分析 +- 大部分API文件只分析了入口，未分析具体接口函数职责 +- 缺少接口参数和返回数据结构分析 + +### 5.4 需要补充的Store状态分析 +- 大部分store模块只分析了入口，未分析具体state/mutations/actions结构 + +### 5.5 需要补充的Utils工具分析 +- 大部分工具文件未分析具体函数功能和使用场景 + +## 6. 架构优化建议 + +### 6.1 组件抽取建议 +1. **搜索筛选组件**: 将各页面的搜索筛选逻辑抽取为通用组件 +2. **数据表格组件**: 标准化列表页面的表格展示组件 +3. **弹窗表单组件**: 统一弹窗编辑表单的结构和交互 +4. **统计卡片组件**: 标准化统计信息展示组件 + +### 6.2 Store模块重组建议 +1. **按业务域重组**: 将相关业务的状态管理集中到一起 +2. **状态规范化**: 统一state的命名和结构规范 +3. **Actions抽象**: 将通用数据操作抽象为通用actions + +### 6.3 API接口重组建议 +1. **按模块分组**: 将API按业务模块重新组织 +2. **接口规范化**: 统一接口命名和参数结构 +3. **错误处理统一**: 标准化API错误处理逻辑 + +### 6.4 Utils工具优化建议 +1. **工具分类**: 按功能类型重新组织工具函数 +2. **通用工具库**: 抽取跨页面使用的通用工具 +3. **类型定义**: 为工具函数添加TypeScript类型定义 + +### 6.5 文件组织优化建议 +1. **组件按功能分组**: 将组件按功能类型重新组织目录结构 +2. **页面组件瘦身**: 将复杂页面的逻辑抽取到composables中 +3. **样式模块化**: 将样式按组件和页面分离组织 + +--- + +**分析说明**: 本文档基于代码静态分析生成，重点分析了页面结构、组件依赖和文件职责关系。由于项目规模较大，部分细节需要进一步深入分析。 \ No newline at end of file diff --git a/docs/PAGE_STRUCTURE_ANALYSIS.md b/docs/PAGE_STRUCTURE_ANALYSIS.md new file mode 100644 index 00000000..032b689e --- /dev/null +++ b/docs/PAGE_STRUCTURE_ANALYSIS.md @@ -0,0 +1,292 @@ +# CRMEB Admin 页面结构与流转分析 + +## 项目概述 +- **项目**: CRMEB Admin 电商管理后台 +- **技术栈**: Vue.js + Vue Router + Element UI + Vuex +- **路由前缀**: `/admin` (可配置) +- **路由模式**: history + +## 1. 应用入口结构 + +### 1.1 入口文件层级 +``` +main.js (应用入口) +├── Vue实例初始化 + + +├── 路由器配置 +├── Vuex状态管理 +└── 全局组件/插件注册 + +App.vue (根组件) +├── router-view (主路由出口) +└── Setings组件 (布局设置弹窗) +``` + +**源码位置**: +- `src/main.js` (line 250-256): Vue实例创建 +- `src/App.vue` (line 3): 根路由视图 + +## 2. 页面布局体系 + +### 2.1 布局组件层级 +``` +LayoutMain (主布局组件) +├── layout/index.vue (布局选择器) +│ ├── 根据主题配置选择布局类型 +│ ├── 支持4种布局模式 +│ └── 响应式适配 +│ +├── layout/main/defaults.vue (默认布局) +│ ├── Asides (侧边栏) +│ ├── Headers (顶部导航栏) +│ └── Mains (主内容区) +│ +└── layout/component/main.vue (主内容容器) + ├── LayoutParentView (路由视图容器) + ├── Footers (页脚) + ├── Links (链接页面) + └── Iframes (内嵌页面) +``` + +**源码位置**: +- `src/layout/index.vue` (line 3-8): 布局选择逻辑 +- `src/layout/main/defaults.vue` (line 2-11): 默认布局结构 +- `src/layout/component/main.vue` (line 9): 路由视图 + +### 2.2 路由视图容器 +``` +LayoutParentView (父级路由视图) +├── transition (页面切换动画) +├── keep-alive (页面缓存) +└── router-view (实际路由出口) +``` + +**源码位置**: `src/layout/routerView/parent.vue` + +## 3. 路由配置体系 + +### 3.1 路由分类结构 +``` +路由配置 (src/router/routers.js) +├── frameIn (主框架内路由) +│ ├── 基础路径: / +│ ├── 使用LayoutMain布局 +│ ├── 包含所有业务模块 +│ └── 需要权限验证 +│ +├── frameOuts (主框架外路由) +│ ├── 登录页面 +│ ├── 客服模块 +│ ├── 特殊功能页面 +│ └── 无需权限验证 +│ +└── errorPage (错误页面) + ├── 403/404/500错误页 + └── 通配符路由兜底 +``` + +### 3.2 路由模块组织 +``` +src/router/modules/ +├── index.js # 首页模块 +├── product.js # 商品管理 +├── order.js # 订单管理 +├── user.js # 用户管理 +├── setting.js # 系统设置 +├── marketing.js # 营销活动 +├── finance.js # 财务管理 +├── system.js # 系统管理 +├── app.js # 应用管理 +├── statistic.js # 统计报表 +├── frameOut.js # 框架外路由 +├── crud.js # CRUD模块 +├── division.js # 部门管理 +└── agent.js # 代理商管理 +``` + +## 4. 页面流转逻辑 + +### 4.1 应用启动流程 +``` +应用启动 +├── main.js 初始化Vue实例 +├── 注册全局组件和插件 +├── 配置路由和状态管理 +└── 挂载到 #app 元素 + +页面初次加载 +├── App.vue 渲染 +├── 路由器检查当前路径 +├── 匹配路由配置 +└── 渲染对应组件 +``` + +### 4.2 登录认证流程 +``` +访问受保护页面 +├── router.beforeEach 路由守卫拦截 +├── 检查用户token +│ ├── 有token → 验证权限 +│ └── 无token → 跳转登录页 +├── 权限验证 +│ ├── 有权限 → 允许访问 +│ └── 无权限 → 跳转403页 +└── 渲染目标页面 +``` + +**源码位置**: `src/router/index.js` (line 116-169) + +### 4.3 页面导航流程 +``` +用户点击导航 +├── 触发路由变化 ($route变化) +├── layout/index.vue 监听路由变化 +├── 更新面包屑导航 +├── 更新标签页导航 +├── LayoutParentView 处理页面切换 +│ ├── 检查keep-alive缓存 +│ ├── 执行页面切换动画 +│ └── 渲染新页面组件 +└── 滚动到页面顶部 +``` + +### 4.4 布局切换流程 +``` +用户切换布局主题 +├── Vuex状态更新 (themeConfig) +├── layout/index.vue 响应状态变化 +├── 根据配置选择布局组件 +├── 重新渲染布局结构 +└── 保持页面内容不变 +``` + +## 5. 关键页面路径 + +### 5.1 主框架内页面 (frameIn) +| 路径 | 页面名称 | 组件位置 | 权限要求 | +|------|---------|---------|---------| +| `/admin/index` | 主页 | `src/pages/index/index.vue` | `admin-index-index` | +| `/admin/product/product_list` | 商品管理 | `src/pages/product/productList/index.vue` | `admin-store-storeProuduct-index` | +| `/admin/order/list` | 订单管理 | `src/pages/order/orderList/index.vue` | `admin-order-storeOrder-index` | +| `/admin/user/list` | 用户管理 | `src/pages/user/list/index.vue` | `admin-user-user-index` | +| `/admin/setting/system_config` | 系统设置 | `src/pages/setting/setSystem/index.vue` | `setting-system-config` | + +### 5.2 主框架外页面 (frameOut) +| 路径 | 页面名称 | 组件位置 | 说明 | +|------|---------|---------|------| +| `/admin/login` | 登录页面 | `src/pages/account/login/index.vue` | 无需登录即可访问 | +| `/kefu` | 客服管理 | `src/pages/kefu/index.vue` | 独立客服系统 | +| `/kefu/mobile_chat` | 移动端客服 | `src/pages/kefu/mobile/index.vue` | 移动端聊天界面 | +| `/app/upload` | 文件上传 | `src/pages/app/upload.vue` | 移动端扫码上传 | + +## 6. 页面缓存机制 + +### 6.1 Keep-Alive 配置 +```javascript +// src/layout/routerView/parent.vue + + + +``` + +### 6.2 缓存管理 +``` +缓存页面列表 +├── 从Vuex获取 (keepAliveNames) +├── 支持页面刷新功能 +├── 标签页关闭时清理缓存 +└── 路由切换时保持状态 +``` + +**源码位置**: `src/store/module/keepAliveNames.js` + +## 7. 页面布局类型 + +### 7.1 支持的布局模式 +``` +defaults (默认布局) +├── 经典的左右布局 +├── 侧边栏 + 主内容区 +└── 支持固定头部 + +classic (经典布局) +├── 传统管理后台布局 +├── 顶部导航 + 侧边栏 +└── 适用于复杂导航 + +transverse (横向布局) +├── 横向菜单布局 +├── 适用于扁平化导航 +└── 节省垂直空间 + +columns (分栏布局) +├── 多列布局设计 +├── 适用于信息密集页面 +└── 提高空间利用率 +``` + +**源码位置**: `src/layout/main/` 目录下对应文件 + +## 8. 特殊页面处理 + +### 8.1 全屏页面 +```javascript +// 路由meta配置 +meta: { + fullScreen: true // 启用全屏模式 +} +``` +- 隐藏侧边栏和顶部导航 +- 适用于页面设计器等特殊场景 + +### 8.2 内嵌页面 +```javascript +// 路由meta配置 +meta: { + isIframe: true, // 内嵌iframe + isLink: true // 链接页面 +} +``` +- 支持iframe内嵌外部页面 +- 支持直接跳转外部链接 + +### 8.3 标签页固定 +```javascript +// 路由meta配置 +meta: { + isAffix: true // 固定标签页 +} +``` +- 标签页不可关闭 +- 通常用于首页等重要页面 + +## 9. 响应式适配 + +### 9.1 移动端适配 +``` +屏幕宽度检测 +├── < 600px → Mobile模式 +├── 600-992px → Tablet模式 +├── > 992px → Desktop模式 + +布局自适应 +├── 移动端隐藏侧边栏 +├── 自动切换到单列布局 +└── 调整组件尺寸 +``` + +**源码位置**: `src/App.vue` (line 33-49) + +## 10. 总结 + +CRMEB Admin的页面结构采用了典型的管理后台架构： + +1. **分层设计**: 入口层 → 布局层 → 路由层 → 页面层 +2. **模块化组织**: 路由按业务模块拆分，便于维护 +3. **灵活布局**: 支持多种布局模式，适应不同使用场景 +4. **权限控制**: 基于路由的权限验证体系 +5. **缓存优化**: 智能的页面缓存机制提升用户体验 +6. **响应式适配**: 支持多终端访问 + +这种架构设计使得系统具有良好的可扩展性和维护性，同时提供了丰富的定制化选项。 \ No newline at end of file diff --git a/docs/UI_DESIGN_GUIDELINES.md b/docs/UI_DESIGN_GUIDELINES.md deleted file mode 100644 index 54fe54bd..00000000 --- a/docs/UI_DESIGN_GUIDELINES.md +++ /dev/null @@ -1,660 +0,0 @@ -# UI 设计规范文档 - -## 📋 文档说明 - -本文档基于 **CRMEB 项目的 UI 设计理念和交互模式**，提取设计思想、布局方式、组件模式等，为项目提供统一的 UI 设计规范。**所有实现均为原创，不复制任何源码**。 - -### 设计原则 - -1. **参考不复制**：仅参考 CRMEB 的设计理念，不复制任何代码 -2. **现代简约**：遵循现代电商 UI 设计趋势 -3. **用户体验优先**：注重交互流畅性和视觉舒适度 -4. **一致性**：保持整体设计风格统一 - ---- - -## 一、设计风格分析 - -### 1.1 CRMEB 设计特点 - -基于对 CRMEB 项目的分析，提取以下设计特点： - -#### 1.1.1 视觉风格 -- **色彩**：以红色系为主色调（#E93323），体现电商活力 -- **圆角**：大量使用圆角设计（20rpx-24rpx），柔和现代 -- **阴影**：轻微阴影效果，增强层次感 -- **间距**：宽松的间距设计，提升可读性 - -#### 1.1.2 布局特点 -- **卡片式设计**：信息以卡片形式呈现，清晰分组 -- **瀑布流布局**：商品列表采用瀑布流，提升浏览体验 -- **模块化设计**：首页采用模块化组件，灵活配置 -- **响应式适配**：适配不同屏幕尺寸 - -#### 1.1.3 交互特点 -- **流畅动画**：页面切换和操作有平滑过渡 -- **即时反馈**：操作有明确的视觉反馈 -- **加载状态**：优雅的加载动画和骨架屏 -- **错误处理**：友好的错误提示和空状态 - ---- - -## 二、颜色系统 - -### 2.1 主色调 - -基于 CRMEB 的设计理念，定义以下颜色系统： - -```scss -// 主题色 -$theme-primary: #FF4D4F; // 主色（红色系，体现电商活力） -$theme-primary-light: #FF7875; // 主色浅色 -$theme-primary-dark: #CF1322; // 主色深色 - -// 渐变色 -$gradient-start: #FF4D4F; // 渐变起始色 -$gradient-end: #FF7A45; // 渐变结束色 - -// 功能色 -$success: #52C41A; // 成功色 -$warning: #FAAD14; // 警告色 -$error: #FF4D4F; // 错误色 -$info: #1890FF; // 信息色 -``` - -### 2.2 中性色 - -```scss -// 文字颜色 -$text-primary: #111111; // 主要文字 -$text-secondary: #333333; // 次要文字 -$text-tertiary: #666666; // 辅助文字 -$text-disabled: #999999; // 禁用文字 -$text-placeholder: #CCCCCC; // 占位文字 - -// 背景颜色 -$bg-primary: #FFFFFF; // 主背景 -$bg-secondary: #F7F8FA; // 次背景 -$bg-tertiary: #F5F5F5; // 三级背景 -$bg-hover: #F1F1F1; // 悬停背景 - -// 边框颜色 -$border-color: rgba(0, 0, 0, 0.06); // 边框色 -$border-color-light: rgba(0, 0, 0, 0.08); // 浅边框 -``` - -### 2.3 使用规范 - -- **主色**：用于按钮、链接、重要信息 -- **渐变色**：用于主要操作按钮、强调元素 -- **中性色**：用于文字、背景、边框 -- **功能色**：用于状态提示、警告信息 - ---- - -## 三、布局规范 - -### 3.1 间距系统 - -```scss -// 基础间距单位（基于 rpx） -$spacing-xs: 8rpx; // 极小间距 -$spacing-sm: 16rpx; // 小间距 -$spacing-md: 24rpx; // 中等间距 -$spacing-lg: 32rpx; // 大间距 -$spacing-xl: 48rpx; // 超大间距 - -// 页面边距 -$page-padding: 24rpx; // 页面左右边距 -$section-margin: 20rpx; // 模块间距 -``` - -### 3.2 圆角规范 - -```scss -$radius-sm: 8rpx; // 小圆角 -$radius-md: 12rpx; // 中等圆角 -$radius-lg: 20rpx; // 大圆角 -$radius-xl: 24rpx; // 超大圆角 -$radius-circle: 50%; // 圆形 -``` - -### 3.3 阴影规范 - -```scss -// 轻微阴影（卡片） -$shadow-sm: 0 2rpx 8rpx rgba(0, 0, 0, 0.06); - -// 中等阴影（悬浮） -$shadow-md: 0 4rpx 16rpx rgba(0, 0, 0, 0.08); - -// 大阴影（弹窗） -$shadow-lg: 0 8rpx 24rpx rgba(0, 0, 0, 0.12); -``` - -### 3.4 布局模式 - -#### 3.4.1 卡片布局 -- **特点**：信息以卡片形式呈现，有圆角和阴影 -- **应用**：商品卡片、订单卡片、信息卡片 -- **实现**：使用 `view` 容器，添加圆角和阴影样式 - -#### 3.4.2 列表布局 -- **特点**：信息以列表形式呈现，清晰有序 -- **应用**：订单列表、地址列表、设置列表 -- **实现**：使用 `view` 容器，添加分割线 - -#### 3.4.3 网格布局 -- **特点**：信息以网格形式呈现，整齐排列 -- **应用**：商品网格、分类网格、功能入口 -- **实现**：使用 `view` 容器，配合 flex 布局 - ---- - -## 四、组件设计规范 - -### 4.1 按钮组件 - -#### 4.1.1 主要按钮（Primary） -```scss -// 样式特点 -- 背景：渐变色（#FF4D4F → #FF7A45） -- 文字：白色 -- 圆角：18rpx -- 高度：92rpx -- 阴影：0 16rpx 32rpx rgba(255, 77, 79, 0.24) -``` - -#### 4.1.2 次要按钮（Secondary） -```scss -// 样式特点 -- 背景：白色 -- 文字：主题色 -- 边框：1rpx solid 主题色 -- 圆角：18rpx -- 高度：92rpx -``` - -#### 4.1.3 文字按钮（Text） -```scss -// 样式特点 -- 背景：透明 -- 文字：主题色 -- 无边框 -- 无圆角 -``` - -### 4.2 输入框组件 - -#### 4.2.1 标准输入框 -```scss -// 样式特点 -- 背景：#F6F7F9 -- 边框：2rpx solid rgba(0, 0, 0, 0.06) -- 圆角：14rpx -- 高度：84rpx -- 内边距：0 14rpx -- 错误状态：边框变红，背景变浅红 -``` - -### 4.3 商品卡片组件 - -#### 4.3.1 商品列表卡片 -```scss -// 布局特点 -- 图片：180rpx × 180rpx，圆角 20rpx -- 信息：商品名称、价格、销量 -- 间距：左右 30rpx，上下 20rpx -- 活动标签：左上角显示（秒杀/砍价/拼团） -``` - -#### 4.3.2 商品网格卡片 -```scss -// 布局特点 -- 图片：宽高比 1:1，圆角 20rpx -- 信息：商品名称、价格、原价（删除线） -- 间距：网格间距 16rpx -- 两列或三列布局 -``` - -### 4.4 订单卡片组件 - -#### 4.4.1 订单列表卡片 -```scss -// 布局特点 -- 背景：白色 -- 圆角：20rpx -- 内边距：24rpx -- 阴影：轻微阴影 -- 内容：订单号、商品信息、价格、状态 -``` - -### 4.5 导航栏组件 - -#### 4.5.1 顶部导航栏 -```scss -// 样式特点 -- 背景：白色或透明（滚动时变化） -- 高度：88rpx（含状态栏） -- 文字：主题色或白色 -- 返回按钮：左侧 -- 搜索框：居中（可选） -``` - -### 4.6 标签组件 - -#### 4.6.1 活动标签 -```scss -// 样式特点 -- 背景：主题色或渐变色 -- 文字：白色 -- 圆角：4rpx 或 圆形 -- 位置：商品图片左上角 -- 文字：秒杀/砍价/拼团 -``` - ---- - -## 五、交互模式 - -### 5.1 页面切换 - -- **动画**：使用 uni-app 的页面切换动画 -- **返回**：支持滑动返回（iOS 风格） -- **加载**：页面切换时显示加载状态 - -### 5.2 数据加载 - -- **骨架屏**：数据加载时显示骨架屏 -- **下拉刷新**：列表页面支持下拉刷新 -- **上拉加载**：列表页面支持上拉加载更多 -- **加载状态**：显示加载动画和提示文字 - -### 5.3 操作反馈 - -- **点击反馈**：使用 `hover-class` 提供点击反馈 -- **成功提示**：使用 `uni.showToast` 显示成功提示 -- **错误提示**：使用 `uni.showModal` 显示错误信息 -- **加载提示**：使用 `uni.showLoading` 显示加载状态 - -### 5.4 表单交互 - -- **实时验证**：输入时实时验证，显示错误信息 -- **提交反馈**：提交时显示加载状态，防止重复提交 -- **成功跳转**：提交成功后自动跳转或提示 - ---- - -## 六、页面设计规范 - -### 6.1 首页设计 - -#### 6.1.1 布局结构 -``` -┌─────────────────────────┐ -│ 顶部搜索栏（可选） │ -├─────────────────────────┤ -│ 轮播图（Banner） │ -├─────────────────────────┤ -│ 分类导航（横向滚动） │ -├─────────────────────────┤ -│ 营销模块（可选） │ -│ - 秒杀/拼团/砍价 │ -├─────────────────────────┤ -│ 商品推荐 │ -│ - 瀑布流布局 │ -└─────────────────────────┘ -``` - -#### 6.1.2 设计要点 -- **模块化**：首页由多个模块组成，可配置 -- **瀑布流**：商品列表采用瀑布流布局 -- **懒加载**：图片和内容懒加载，提升性能 -- **下拉刷新**：支持下拉刷新 - -### 6.2 商品详情页 - -#### 6.2.1 布局结构 -``` -┌─────────────────────────┐ -│ 商品轮播图 │ -├─────────────────────────┤ -│ 商品信息 │ -│ - 价格（突出显示） │ -│ - 标题 │ -│ - 标签 │ -├─────────────────────────┤ -│ 优惠信息 │ -│ - 优惠券 │ -│ - 活动 │ -├─────────────────────────┤ -│ 规格选择（弹窗） │ -├─────────────────────────┤ -│ 商品详情（Tab切换） │ -│ - 详情 │ -│ - 评价 │ -│ - 推荐 │ -├─────────────────────────┤ -│ 底部操作栏（固定） │ -│ - 购物车/立即购买 │ -└─────────────────────────┘ -``` - -#### 6.2.2 设计要点 -- **图片展示**：轮播图展示商品图片 -- **价格突出**：价格使用大字号和主题色 -- **规格选择**：点击规格弹出选择弹窗 -- **底部固定**：操作按钮固定在底部 - -### 6.3 购物车页面 - -#### 6.3.1 布局结构 -``` -┌─────────────────────────┐ -│ 商品列表 │ -│ ┌───────────────────┐ │ -│ │ ☑ 商品卡片 │ │ -│ │ 数量选择 │ │ -│ └───────────────────┘ │ -├─────────────────────────┤ -│ 底部结算栏（固定） │ -│ - 全选 │ -│ - 合计金额 │ -│ - 结算按钮 │ -└─────────────────────────┘ -``` - -#### 6.3.2 设计要点 -- **选择状态**：每个商品可单独选择 -- **数量编辑**：支持增减数量 -- **价格计算**：实时计算总价 -- **底部固定**：结算栏固定在底部 - -### 6.4 订单确认页 - -#### 6.4.1 布局结构 -``` -┌─────────────────────────┐ -│ 收货地址（可选） │ -├─────────────────────────┤ -│ 商品列表 │ -├─────────────────────────┤ -│ 优惠券选择（可选） │ -├─────────────────────────┤ -│ 配送方式 │ -├─────────────────────────┤ -│ 备注信息 │ -├─────────────────────────┤ -│ 价格明细 │ -│ - 商品总额 │ -│ - 运费 │ -│ - 优惠金额 │ -│ - 实付金额 │ -├─────────────────────────┤ -│ 提交订单按钮（固定） │ -└─────────────────────────┘ -``` - -### 6.5 个人中心页 - -#### 6.5.1 布局结构 -``` -┌─────────────────────────┐ -│ 用户信息卡片 │ -│ - 头像 │ -│ - 昵称 │ -│ - 会员信息 │ -├─────────────────────────┤ -│ 订单状态（快捷入口） │ -│ - 待付款/待发货等 │ -├─────────────────────────┤ -│ 功能菜单 │ -│ - 我的订单 │ -│ - 我的地址 │ -│ - 我的优惠券 │ -│ - 设置 │ -└─────────────────────────┘ -``` - ---- - -## 七、实现指南 - -### 7.1 样式变量定义 - -创建 `styles/variables.uts` 文件： - -```typescript -// 颜色变量 -export const THEME_PRIMARY = '#FF4D4F' -export const THEME_GRADIENT_START = '#FF4D4F' -export const THEME_GRADIENT_END = '#FF7A45' - -// 间距变量 -export const SPACING_XS = '8rpx' -export const SPACING_SM = '16rpx' -export const SPACING_MD = '24rpx' -export const SPACING_LG = '32rpx' - -// 圆角变量 -export const RADIUS_SM = '8rpx' -export const RADIUS_MD = '12rpx' -export const RADIUS_LG = '20rpx' -``` - -### 7.2 通用样式类 - -创建 `styles/common.uvue` 或使用 ` -``` - ---- - -## 八、最佳实践 - -### 8.1 性能优化 - -1. **图片优化** - - 使用合适的图片尺寸 - - 启用图片懒加载 - - 使用 WebP 格式（如支持） - -2. **列表优化** - - 使用虚拟列表（长列表） - - 分页加载数据 - - 避免不必要的重新渲染 - -3. **动画优化** - - 使用 CSS 动画而非 JS 动画 - - 避免过度动画 - - 使用 `transform` 和 `opacity` 做动画 - -### 8.2 可访问性 - -1. **文字大小** - - 最小字号：24rpx - - 主要文字：28rpx-32rpx - - 标题文字：36rpx-40rpx - -2. **点击区域** - - 最小点击区域：88rpx × 88rpx - - 按钮高度：至少 80rpx - -3. **颜色对比** - - 文字与背景对比度：至少 4.5:1 - - 重要信息使用高对比度 - -### 8.3 响应式设计 - -1. **屏幕适配** - - 使用 rpx 单位 - - 使用 flex 布局 - - 适配不同屏幕尺寸 - -2. **横竖屏适配** - - 考虑横屏布局 - - 使用媒体查询（如需要） - ---- - -## 九、设计资源 - -### 9.1 图标系统 - -- **图标库**：使用 uni-app 内置图标或自定义图标 -- **图标大小**：24rpx、32rpx、48rpx -- **图标颜色**：主题色或中性色 - -### 9.2 字体规范 - -- **字体家族**：系统默认字体 -- **字重**：Regular（400）、Medium（500）、Bold（600） -- **字号**：24rpx、28rpx、32rpx、36rpx、40rpx - ---- - -## 十、总结 - -本文档基于 CRMEB 项目的设计理念，提取了以下核心要点： - -1. **设计风格**：现代简约，以红色系为主色调 -2. **布局方式**：卡片式、列表式、网格式 -3. **交互模式**：流畅动画、即时反馈、友好提示 -4. **组件设计**：统一的组件样式和交互规范 - -所有实现均为原创，遵循现代 UI 设计最佳实践，确保用户体验和视觉一致性。 - ---- - -**文档版本**: v1.0 -**创建时间**: 2025-01-XX -**状态**: ✅ 待实施 diff --git a/docs/UNI_APP_X_MIGRATION.md b/docs/UNI_APP_X_MIGRATION.md deleted file mode 100644 index 7b847032..00000000 --- a/docs/UNI_APP_X_MIGRATION.md +++ /dev/null @@ -1,198 +0,0 @@ -# uni-app X 迁移操作总结 - -## 操作日期 -2024年（具体日期根据实际情况填写） - -## 操作背景 -项目需要从传统的 uni-app 迁移到 **uni-app X**，以支持 `.uvue` 文件在 H5 浏览器中正确渲染。 - -## 问题分析 -对比根项目（`akmon`）和 `mall` 项目，发现以下关键差异： - -1. **缺少 uni-app X 配置**：`mall/manifest.json` 中缺少 `"uni-app-x": {}` 配置项 -2. **存在 .vue 文件**：项目中有 23 个 `.vue` 文件，这些文件在 uni-app X 中无法被正确编译到 H5 -3. **编译器配置**：需要确保 HBuilderX 使用 uni-app X 编译器 - -## 执行的操作 - -### 1. 添加 uni-app X 配置 - -在 `manifest.json` 中添加了 `"uni-app-x": {}` 配置项： - -```json -{ - "vueVersion": "3", - "uni-app-x": {}, - "h5": { - "title": "mall", - "router": { - "mode": "hash", - "base": "./" - } - } -} -``` - -**位置**：`manifest.json` 第 66 行 - -**作用**： -- 告诉 HBuilderX 这是一个 uni-app X 项目 -- 启用 uni-app X 编译链，支持 `.uvue` 文件编译到 H5 -- 确保 `.uvue` 文件能够被正确编译和渲染 - -### 2. 删除所有 .vue 文件 - -删除了项目中所有 `.vue` 文件，共 23 个文件： - -**删除的文件列表**： -- `pages/user/boot.vue` -- `pages/user/login.vue` -- `pages/user/register.vue` -- `pages/user/forgot-password.vue` -- `pages/user/profile.vue` -- `pages/user/center.vue` -- `pages/user/terms.vue` -- `pages/mall/consumer/index.vue` -- `pages/mall/consumer/product-detail.vue` -- `pages/mall/consumer/order-detail.vue` -- `pages/mall/consumer/profile.vue` -- `pages/mall/consumer/subscription/plan-list.vue` -- `pages/mall/consumer/subscription/plan-detail.vue` -- `pages/mall/consumer/subscription/subscribe-checkout.vue` -- `pages/mall/consumer/subscription/my-subscriptions.vue` -- `pages/mall/merchant/index.vue` -- `pages/mall/delivery/index.vue` -- `pages/mall/admin/index.vue` -- `pages/mall/admin/subscription/plan-management.vue` -- `pages/mall/admin/subscription/user-subscriptions.vue` -- `pages/mall/service/index.vue` -- `pages/mall/analytics/index.vue` -- `pages/mall/nfc/security/index.vue` - -**删除命令**： -```powershell -Set-Location -Path 'd:\datas\hfkj\akmon\mall' -Get-ChildItem -Recurse -Filter *.vue | Remove-Item -Force -``` - -**原因**： -- `.vue` 文件在 uni-app X 中无法被正确编译到 H5 浏览器 -- 所有页面和组件应使用 `.uvue` 格式 -- 导入语句会自动识别 `.uvue` 扩展名（导入时无需显式指定扩展名） - -## 技术说明 - -### uni-app X vs 传统 uni-app - -| 特性 | 传统 uni-app | uni-app X | -| ------------- | --------------------- | ---------------------- | -| 文件格式 | `.vue` | `.uvue` | -| 脚本语言 | JavaScript/TypeScript | UTS (TypeScript 扩展) | -| 编译器 | uni-app 编译器 | uni-app X 编译器 | -| H5 渲染 | 需要编译 | 需要编译（但支持更好） | -| manifest.json | 不需要 `uni-app-x` | 需要 `"uni-app-x": {}` | - -### 导入语句说明 - -删除 `.vue` 文件后，所有导入语句会自动使用对应的 `.uvue` 文件： - -```typescript -// 之前（.vue） -import LoginPage from './pages/user/login.vue' - -// 现在（.uvue，扩展名可省略） -import LoginPage from './pages/user/login.uvue' -// 或者 -import LoginPage from './pages/user/login' // 自动识别 .uvue -``` - -## 后续操作 - -### 1. 验证配置 - -1. 打开 HBuilderX -2. 打开 `mall` 项目 -3. 检查编译器：**工具** → **切换编译器** → 确认选择 **uni-app X** -4. 如果未选择，请切换到 uni-app X 编译器 - -### 2. 运行到 H5 - -1. 在 HBuilderX 中，点击菜单：**运行** → **运行到浏览器** → **Chrome**（或内置浏览器） -2. 等待编译完成 -3. 浏览器会自动打开并显示应用 - -### 3. 发行 H5 - -如果需要打包发布： - -1. 点击菜单：**发行** → **网站-H5** -2. 等待编译完成 -3. 编译产物在 `unpackage/dist/build/h5` 目录 -4. 将整个 `h5` 目录部署到 Web 服务器 - -### 4. 检查页面 - -确保所有页面都有对应的 `.uvue` 文件： - -- 检查 `pages.json` 中配置的所有页面路径 -- 确认每个页面都有对应的 `.uvue` 文件 -- 如果缺少，需要从备份或版本控制中恢复并转换为 `.uvue` 格式 - -## 注意事项 - -1. **编译器版本**：必须使用支持 uni-app X 的 HBuilderX 版本 -2. **文件格式**：所有页面和组件必须使用 `.uvue` 格式，不能混用 `.vue` -3. **UTS 语法**：`.uvue` 文件中的 ` 标签 --> + + + + + +``` + +#### **步骤 2.2：修复生命周期导入** + +```javascript +// ❌ 错误：从 Vue 导入 uni-app 生命周期 +import { ref, computed, onLoad } from 'vue' + +// ✅ 正确：uni-app-x 生命周期全局可用 +import { ref, computed } from 'vue' + +// 在组件中直接使用 +onLoad(() => { + activeMenu.value = props.currentPage +}) +``` + +#### **步骤 2.3：验证组件结构** + +```vue + +``` + +### **阶段三：页面配置恢复** + +#### **步骤 3.1：恢复主页面配置** + +```json +{ + "pages": [ + { + "path": "pages/minimal", + "style": { + "navigationBarTitleText": "最小测试" + } + }, + { + "path": "pages/mall/admin/index", + "style": { + "navigationBarTitleText": "管理后台", + "navigationStyle": "custom" + } + } + ] +} +``` + +#### **步骤 3.2：恢复子包配置** + +```json +{ + "subPackages": [ + { + "root": "pages/mall", + "pages": [ + { + "path": "admin/user-management", + "style": { + "navigationBarTitleText": "用户管理", + "navigationStyle": "custom" + } + } + // ... 其他页面 + ] + } + ] +} +``` + +#### **步骤 3.3：验证完整配置** + +```json +{ + "pages": [ + { + "path": "pages/minimal", + "style": { "navigationBarTitleText": "最小测试" } + }, + { + "path": "pages/mall/admin/index", + "style": { + "navigationBarTitleText": "管理后台", + "navigationStyle": "custom" + } + } + ], + "subPackages": [ + { + "root": "pages/mall", + "pages": [ + { + "path": "admin/user-management", + "style": { "navigationBarTitleText": "用户管理", "navigationStyle": "custom" } + }, + { + "path": "admin/product-management", + "style": { "navigationBarTitleText": "商品管理", "navigationStyle": "custom" } + }, + { + "path": "admin/order-management", + "style": { "navigationBarTitleText": "订单管理", "navigationStyle": "custom" } + }, + { + "path": "admin/finance-management", + "style": { "navigationBarTitleText": "财务管理", "navigationStyle": "custom" } + }, + { + "path": "admin/system-settings", + "style": { "navigationBarTitleText": "系统设置", "navigationStyle": "custom" } + } + ] + } + ], + "globalStyle": { + "navigationBarTextStyle": "black", + "navigationBarTitleText": "mall", + "navigationBarBackgroundColor": "#FFFFFF", + "backgroundColor": "#F8F8F8" + } +} +``` + +### **阶段四：路径格式统一** + +### **阶段五：特殊字符处理** + +#### **步骤 5.1：移除问题 Emoji 字符** + +```vue + + + + + +``` + +**常见问题 Emoji 及替代方案**: +```javascript +// 统计图标 +'👥' → '👤' // 用户数量 +'✅' → '✓' // 成功/活跃 +'🚫' → '✗' // 禁用/下架 +'📦' → '□' // 商品/包裹 +'⏳' → '○' // 等待/处理中 +'🚚' → '→' // 配送中 +'⚠️' → '!' // 警告/库存不足 + +// 财务图标 +'💰' → '$' // 收入 +'📈' → '↑' // 增长 +'📊' → '≡' // 图表 +'💳' → '■' // 账户 +``` + +#### **步骤 5.2：检查文件编码** + +```bash +# 检查文件编码和特殊字符 +file pages/mall/admin/*.uvue + +# 确保文件编码为 UTF-8 无 BOM +# 移除任何不可见字符 +``` + +#### **步骤 5.3：验证模板语法完整性** + +```vue + + +``` + +#### **步骤 5.4：最终验证** + +### **阶段六：缩进一致性检查** + +#### **步骤 6.1：统一缩进方式** + +```vue + + + + + +``` + +#### **步骤 6.2：检查缩进工具** + +```bash +# 检查文件中是否存在制表符 +grep -P '\t' pages/mall/admin/*.uvue + +# 将制表符转换为空格（2个空格） +sed -i 's/\t/ /g' pages/mall/admin/*.uvue +``` + +#### **步骤 6.3：验证标签闭合** + +```javascript +// 检查所有开始标签都有对应结束标签 +// 检查缩进一致性 +// 确保没有多余的闭合标签 +``` + +#### **步骤 6.4：最终验证** + +### **阶段七：方法调用检查** + +#### **步骤 7.1：检查方法引用** + +```javascript +// ❌ 错误：方法名已更改但模板未更新 + + +// ✅ 正确：更新方法引用 + +``` + +#### **步骤 7.2：验证方法定义** + +```javascript +// 确保所有模板中引用的方法都已定义 +const newMethodName = () => { + // 方法实现 +} +``` + +#### **步骤 7.3：检查参数匹配** + +```javascript +// 确保方法调用时的参数与定义一致 +const handleClick = (param: string) => { + console.log(param) +} + +// 模板调用 + +``` + +#### **步骤 7.4：最终验证** + +### **阶段八：自闭合标签检查** + +#### **步骤 8.1：检查自闭合标签格式** + +```vue + + + + + + + + + +``` + +#### **步骤 8.2：自动修复工具** + +```bash +# 使用 sed 批量修复（注意备份文件） +sed -i 's/><\/image>/ \/>/g' pages/mall/admin/*.uvue +sed -i 's/><\/checkbox>/ \/>/g' pages/mall/admin/*.uvue +``` + +#### **步骤 8.3：验证标签完整性** + +```javascript +// 检查所有自闭合标签都正确结束 +// 确保没有多余的结束标签 +``` + +### **阶段九：模态框位置优化** + +#### **步骤 9.1：识别模态框位置问题** + +```vue + + + + + +``` + +#### **步骤 9.2：重构模态框位置** + +```vue + +``` + +#### **步骤 9.3：验证模态框行为** + +```javascript +// 确保模态框在所有页面模式下都能正常显示 +// 测试不同条件下的模态框显示 +``` + +#### **步骤 9.4：最终验证** + +### **阶段十：.uvue文件特殊处理** + +#### **步骤 10.1：简化复杂模板** + +```vue + + + + + +``` + +#### **步骤 10.2：移除问题Unicode字符** + +```vue + +✓ +✗ +★ + + +Y +N +* +``` + +#### **步骤 10.3：UTS编译器兼容性检查** + +```javascript +// 检查UTS特定的语法要求 +// 确保所有导入和类型定义正确 +// 验证组件Props和事件处理 +``` + +#### **步骤 10.4：渐进式开发策略** + +```javascript +// 1. 从最小可用模板开始 +const minimalTemplate = ` + +` + +// 2. 逐步添加功能，每次只添加一个特性 +// 3. 每次修改后立即编译测试 +// 4. 出现问题时立即回滚到上一个稳定版本 +``` + +#### **步骤 10.5：最终验证** + +### **阶段十一：批量.uvue文件修复** + +### **阶段十二：AdminLayout双侧边栏布局** + +#### **步骤 11.1：识别问题文件** + +```bash +# 检查所有.uvue文件是否正常编译 +# 记录出现"Invalid end tag"错误的文件 +# 按优先级排序修复顺序 +``` + +#### **步骤 11.2：批量简化模板** + +```javascript +// 为每个问题文件创建最小可用模板 +const minimalTemplates = { + 'user-management.uvue': ` + + + + + + `, + + 'product-management.uvue': ` + + + + + + `, + + // 为其他页面创建类似的模板 +} +``` + +#### **步骤 11.3：统一字符替换** + +```bash +# 批量替换所有.uvue文件中的问题字符 +find pages/mall/admin -name "*.uvue" -exec sed -i \ + -e 's/👤/U/g' \ + -e 's/✓/Y/g' \ + -e 's/✗/N/g' \ + -e 's/★/*/g' \ + -e 's/📦/□/g' \ + -e 's/⏳/○/g' \ + -e 's/🚚/→/g' \ + {} \; +``` + +#### **步骤 11.4：验证批量修复** + +```javascript +// 检查所有文件是否正常编译 +// 确认没有"Invalid end tag"错误 +// 测试基本页面导航功能 +``` + +#### **步骤 11.5：最终验证** + +#### **步骤 12.1：设计双侧边栏布局** + +```vue + + + + + +``` + +#### **步骤 12.2：实现菜单数据结构** + +```javascript +const menuList = ref([ + { + id: 'user', + title: '用户管理', + icon: 'icon-user', + path: '/pages/mall/admin/user-management', + subMenus: [ + { id: 'user-list', title: '用户列表', path: '/pages/mall/admin/user-management' }, + { id: 'user-add', title: '添加用户', path: '/pages/mall/admin/user-management?action=add' } + ] + }, + { + id: 'product', + title: '商品管理', + icon: 'icon-product', + path: '/pages/mall/admin/product-management', + subMenus: [ + { id: 'product-list', title: '商品列表', path: '/pages/mall/admin/product-management' }, + { id: 'category', title: '商品分类', path: '/pages/mall/admin/product-management?tab=category' } + ] + }, + // 没有子菜单的页面 + { + id: 'statistics', + title: '用户统计', + icon: 'icon-statistics', + path: '/pages/mall/admin/user-statistics' + } +]) +``` + +#### **步骤 12.3：计算属性实现** + +```javascript +// 计算当前菜单的子菜单 +const activeSubMenus = computed(() => { + const menu = menuList.value.find(m => m.id === activeMenu.value) + return menu ? menu.subMenus || [] : [] +}) + +// 判断是否有子菜单 +const hasSubMenus = computed(() => { + return activeSubMenus.value.length > 0 +}) +``` + +#### **步骤 12.4：菜单点击处理** + +```javascript +const handleMenuClick = (menu: any) => { + activeMenu.value = menu.id + // 设置默认子菜单（如果有的话） + activeSubMenu.value = menu.subMenus && menu.subMenus.length > 0 ? menu.subMenus[0].id : '' + + // 导航到菜单路径 + uni.navigateTo({ + url: menu.path + }) +} + +const handleSubMenuClick = (subMenu: any) => { + activeSubMenu.value = subMenu.id + // 导航到子菜单路径（可能包含查询参数） + uni.navigateTo({ + url: subMenu.path + }) +} +``` + +#### **步骤 12.5：样式实现** + +```scss +/* 主侧边栏 */ +.admin-sider { + width: 200px; + background-color: #001529; + position: fixed; + left: 0; + top: 0; + bottom: 0; + z-index: 1000; +} + +/* 主内容区 */ +.admin-main { + margin-left: 200px; + display: flex; + min-height: 100vh; +} + +/* 内容侧边栏 */ +.content-sider { + width: 180px; + background-color: #ffffff; + border-right: 1px solid #e8e8e8; + box-shadow: 2px 0 8px rgba(0, 0, 0, 0.06); +} + +.content-sub-menu-item { + height: 36px; + padding: 0 16px; + cursor: pointer; + transition: all 0.2s; + + &.active { + background-color: #e6f7ff; + color: #1890ff; + border-right: 2px solid #1890ff; + } +} + +/* 内容区域 */ +.content-area { + flex: 1; + background-color: #f0f2f5; +} +``` + +#### **步骤 12.6：响应式设计** + +```scss +@media (max-width: 768px) { + .admin-sider { + width: 160px; + } + + .admin-main { + margin-left: 160px; + } + + .content-sider { + width: 140px; + } +} +``` + +#### **步骤 12.7：最终验证** + +### **阶段十三：AdminLayout代码清理** + +#### **步骤 13.1：移除遗留变量引用** + +```javascript +// ❌ 错误：引用已删除的变量 +const handleMenuClick = (menu: any) => { + activeMenu.value = menu.id + // 引用不存在的 tabs 变量 + const existingTab = tabs.value.find(tab => tab.id === menu.id) + // ... +} + +// ✅ 修复：移除所有遗留引用 +const handleMenuClick = (menu: any) => { + activeMenu.value = menu.id + activeSubMenu.value = menu.subMenus?.[0]?.id || '' + + uni.navigateTo({ url: menu.path }) +} +``` + +#### **步骤 13.2：检查计算属性完整性** + +```javascript +// 确保所有模板中使用的属性都已定义 +const activeSubMenuTitle = computed(() => { + const subMenu = activeSubMenus.value.find(sm => sm.id === activeSubMenu.value) + return subMenu ? subMenu.title : '' +}) + +// 模板中使用 +{{ activeSubMenuTitle }} +``` + +#### **步骤 13.3：验证模板依赖** + +```vue + + +``` + +#### **步骤 13.4：最终验证** + +### **阶段十二：AdminLayout组件解析修复** + +#### **步骤 12.1：检查组件导入路径** + +```javascript +// ❌ 错误：缺少文件扩展名 +import AdminLayout from '@/layouts/admin/index' + +// ❌ 错误：路径不存在 +import AdminLayout from '@/layout/admin/index.uvue' + +// ✅ 正确：完整路径包含扩展名 +import AdminLayout from '@/layouts/admin/index.uvue' +``` + +#### **步骤 12.2：简化组件结构** + +```vue + + + + + + + +``` + +#### **步骤 12.3：验证组件可用性** + +```javascript +// 在页面中正确使用组件 + +``` + +#### **步骤 12.4：UTS编译器兼容性** + +```javascript +// 确保组件语法符合UTS要求 +// 使用 +``` + +### **原理五：错误排查方法** + +#### **逐步验证策略**: +1. **最小化配置**: 从最简单的配置开始 +2. **逐步添加**: 每次只添加一个功能 +3. **错误定位**: 根据错误信息快速定位问题 +4. **备份恢复**: 修改前备份，失败时快速回滚 + +#### **常见错误检查清单**: +- ✅ pages.json 路径格式是否正确 +- ✅ 页面文件是否存在 +- ✅ 组件语法是否正确 +- ✅ 导入语句是否正确 +- ✅ 生命周期钩子使用是否正确 +- ✅ 响应式数据使用是否正确 +- ✅ 特殊字符和 emoji 是否安全 +- ✅ 缩进是否一致（避免混用制表符和空格） +- ✅ 方法调用是否正确（方法名和参数匹配） +- ✅ 自闭合标签格式是否正确（使用 `/>` 而非 `>`） +- ✅ 模态框位置是否正确（避免条件嵌套） +- ✅ .uvue文件复杂度是否适中（避免过度复杂的模板结构） +- ✅ 批量文件修复是否完整（所有.uvue文件都已简化处理） +- ✅ AdminLayout组件是否正确导入和解析 +- ✅ AdminLayout代码清理是否完整（无遗留变量引用） + +## 🚀 最佳实践指南 + +### **开发规范** + +#### **1. 文件命名规范** +- 页面文件: `kebab-case.uvue` +- 组件文件: `PascalCase.uvue` +- 工具文件: `camelCase.uts` + +#### **2. 路径配置规范** +- 主页面: `pages/page-name` +- 子包页面: `root: "pages/module"`, `path: "sub-page"` +- 组件导入: `@/layouts/...`, `@/components/...` + +#### **3. 代码组织规范** +```vue + + + + + +``` + +### **调试技巧** + +#### **1. 编译错误排查** +- 查看控制台错误信息 +- 检查文件语法 +- 验证导入路径 +- 确认类型定义 + +#### **2. 运行时错误排查** +- 检查页面配置 +- 验证组件 Props +- 确认事件处理 +- 测试页面跳转 + +#### **3. 性能优化** +- 合理使用响应式数据 +- 避免不必要的计算属性 +- 优化组件渲染 +- 使用合适的生命周期 + +#### **4. .uvue文件特殊处理** +- 保持模板结构简单，避免过度复杂 +- 使用UTS编译器兼容的字符集 +- 定期检查文件编码和特殊字符 +- 采用渐进式开发策略，从简单到复杂 +- 出现编译错误时优先简化模板结构 + +#### **5. AdminLayout组件维护** +- 保持组件结构简单，避免过度复杂的功能 +- 使用正确的文件扩展名(.uvue)在导入路径中 +- 定期验证组件的导出和解析 +- 出现解析错误时优先简化组件结构 +- 确保组件语法符合UTS编译器要求 + +#### **6. 双侧边栏布局设计** +- 主侧边栏只显示一级菜单图标，保持简洁 +- 内容侧边栏显示二级菜单，位于内容区左侧 +- 合理分配侧边栏宽度，确保移动端兼容性 +- 使用计算属性动态控制侧边栏显示 +- 确保路由同步和高亮状态正确 + +## 📚 参考资源 + +### **官方文档** +- [uni-app-x 官方文档](https://doc.dcloud.net.cn/uni-app-x/) +- [Vue 3 组合式 API](https://cn.vuejs.org/guide/extras/composition-api-faq.html) +- [TypeScript 指南](https://www.typescriptlang.org/docs/) + +### **最佳实践** +- 遵循项目现有的代码风格 +- 保持配置的一致性 +- 定期检查和更新依赖 +- 编写清晰的注释 + +--- + +## 🎯 总结 + +通过本次修复，我们建立了完整的 uni-app-x 项目开发和调试方法论： + +1. **问题定位**: 快速识别配置和语法错误 +2. **逐步修复**: 从简单到复杂，逐步解决问题 +3. **规范建立**: 统一的代码和配置规范 +4. **最佳实践**: 可复用的开发模式 + +### **新增问题类型** + +#### **特殊字符兼容性问题** +- **现象**: `[plugin:uts] Invalid end tag` 错误 +- **原因**: emoji 字符或特殊 Unicode 符号导致模板解析失败 +- **解决方案**: 替换为标准 ASCII 字符或安全 Unicode 符号 +- **预防**: 在模板中使用经过验证的安全字符集 + +--- + +#### **原因十四：AdminLayout代码清理不完整** +- **遗留变量引用**: 移除功能后仍引用已删除的变量 +- **计算属性缺失**: 重构时遗漏必要的计算属性 +- **模板依赖问题**: 模板中使用未定义的响应式属性 + +--- + +这个指南现在涵盖了 uni-app-x 项目开发中最常见的 14 类编译和运行时错误，为后续开发提供了完整的故障排除和最佳实践指导。 🚀 \ No newline at end of file diff --git a/layouts/admin/components/AdminAside.uvue b/layouts/admin/components/AdminAside.uvue index 740504e2..12159599 100644 --- a/layouts/admin/components/AdminAside.uvue +++ b/layouts/admin/components/AdminAside.uvue @@ -1,5 +1,8 @@