shop-toy/openspec/project.md

Project Context

Purpose

这是一个基于 unibest 模板开发的跨平台电商应用系统，包含三个主要端：

1. 用户端（C端）：提供商品浏览、购物车、订单管理、会员服务、金融服务等功能
2. 商家端（B端）：提供商品管理、订单处理、财务管理、贷款协助、店铺设置等功能
3. 银行端（B端）：提供客户管理、贷款审核、交易记录、提现管理等功能

项目支持多平台部署，包括 H5、iOS、Android 以及多个小程序平台（微信、支付宝、百度、字节、快手、QQ、钉钉、小红书等）。

Tech Stack

核心框架

• uni-app 3.0.0 - 跨平台开发框架
• Vue 3 3.4.21 - 前端框架
• TypeScript 5.8.0 - 类型系统
• Vite 5.2.8 - 构建工具

UI 组件库

• wot-design-uni - UI 组件库
• UnoCSS 66.0.0 - 原子化 CSS 框架
• z-paging 2.8.7 - 分页组件

状态管理与路由

• Pinia 2.0.36 - 状态管理
• pinia-plugin-persistedstate 3.2.1 - 状态持久化
• vue-router 4.5.1 - 路由管理
• vue-i18n 9.1.9 - 国际化

HTTP 请求库（支持多种选择）

• alova 3.3.3 - 请求库（推荐）
• 简单封装的 http - 轻量级请求方案
• vue-query - 查询状态管理（用于自动生成接口）

工具库

• dayjs 1.11.10 - 日期处理
• js-cookie 3.0.5 - Cookie 操作

开发工具

• pnpm 10.10.0 - 包管理器
• ESLint 9.31.0 - 代码检查
• Husky 9.1.7 - Git hooks
• commitlint 19.8.1 - 提交信息规范

Node.js 环境

• Node.js >= 20
• pnpm >= 9

Project Conventions

Code Style

命名约定

• 文件命名：使用 kebab-case（如 cart-item.vue）
• 组件命名：使用 PascalCase（如 CartItem.vue）
• 变量/函数命名：使用 camelCase（如 getCartList）
• 常量命名：使用 UPPER_SNAKE_CASE（如 API_BASE_URL）

代码格式化

• 使用 @uni-helper/eslint-config 作为 ESLint 配置
• 支持 CSS、LESS、SCSS、HTML 的自动格式化
• Vue SFC 块顺序：[script, template] → style

路径别名

• @/* → ./src/*
• @img/* → ./src/static/images/*

自动导入

• Vue 和 uni-app API 自动导入
• src/hooks 目录下的 hooks 自动导入
• 组件自动导入（支持递归扫描子目录）

Architecture Patterns

目录结构

src/
├── api/           # API 接口定义
├── components/    # 公共组件
├── hooks/        # 组合式函数
├── http/         # HTTP 请求封装
├── layouts/      # 布局组件
├── mock/         # Mock 数据
├── pages/        # 用户端页面
├── pagesMerchant/# 商家端页面
├── pagesBank/    # 银行端页面
├── router/       # 路由配置
├── service/      # 自动生成的服务接口
├── static/       # 静态资源
└── typings/      # 类型定义

路由策略

• 约定式路由：基于文件系统自动生成路由
• Layout 布局：支持多布局系统
• 分包优化：使用 @uni-ku/bundle-optimizer 进行分包优化
• 异步导入：支持模块和组件的异步跨包引用

登录策略

支持两种登录策略（通过 DEFAULT_NO_NEED_LOGIN 配置）：

1. 默认无需登录策略（DEFAULT_NO_NEED_LOGIN）

   • 进入任何页面都不需要登录
   • 只有黑名单中的页面需要登录
   • 适用于大部分 2C 应用（如美团、抖音）

2. 默认需要登录策略（DEFAULT_NEED_LOGIN）

   • 进入任何页面都需要登录
   • 只有白名单中的页面不需要登录
   • 适用于 2B 和后台管理类应用

请求拦截

• 统一的请求拦截器（src/http/interceptor.ts）
• 支持登录拦截
• 支持请求/响应错误处理

Testing Strategy

当前项目未配置自动化测试框架。建议：

• 使用 Vitest 进行单元测试
• 使用 @vue/test-utils 进行组件测试
• 使用 Playwright 进行端到端测试

Git Workflow

分支策略

• main / base - 主分支
• base-i18n - 国际化分支
• base-login - 登录功能分支
• base-login-i18n - 登录+国际化分支

提交规范

使用 Conventional Commits 规范：

• feat: - 新功能
• fix: - 修复 bug
• docs: - 文档更新
• style: - 代码格式调整
• refactor: - 重构
• test: - 测试相关
• chore: - 构建/工具相关

Git Hooks

• 使用 Husky 管理 Git hooks
• 使用 lint-staged 在提交前自动修复代码

Domain Context

业务领域

用户端（C端）

• 商品模块：商品列表、详情、分类、搜索
• 购物车模块：添加商品、数量调整、结算
• 订单模块：订单确认、订单列表、订单详情
• 会员模块：会员卡、会员权益
• 金融模块：信用额度、结算、核销、贷款申请

商家端（B端）

• 仪表盘：数据统计、概览
• 商品管理：商品列表、编辑
• 订单管理：订单列表、订单详情
• 财务管理：财务统计、结算、提现
• 贷款协助：协助用户申请贷款
• 店铺设置：店铺信息管理

银行端（B端）

• 仪表盘：数据统计
• 客户管理：客户列表、客户详情、交易记录、提现记录
• 审核管理：贷款审核列表、审核详情

关键概念

• 多端适配：同一套代码适配 H5、App、小程序
• 角色权限：用户、商家、银行三种角色
• 金融服务：信用额度、贷款申请、结算、核销
• 会员体系：会员卡、会员权益

Important Constraints

技术约束

• Node.js 版本：必须 >= 20
• pnpm 版本：必须 >= 9
• 包管理器：强制使用 pnpm（通过 only-allow pnpm）
• TypeScript：必须使用 TypeScript 开发
• 平台限制：不同 UI 框架支持的平台有所不同

业务约束

• 多端兼容性：需要确保在所有目标平台上正常运行
• 性能要求：分包优化、按需加载、减少包体积
• 安全性：登录拦截、请求加密、数据验证

开发约束

• 代码规范：必须通过 ESLint 检查
• 提交规范：必须符合 Conventional Commits 规范
• 文件忽略：自动生成的文件（如 src/service/**）不应提交

External Dependencies

平台依赖

• DCloudio - uni-app 官方框架和工具链
• 微信开发者工具 - 微信小程序开发调试
• HBuilderX - App 平台打包（可选）

第三方服务

• OpenAPI - 用于自动生成 API 接口类型和代码
• Iconify - 图标库（Carbon 图标集）

构建依赖

• @uni-helper - uni-app 辅助工具集
• @uni-ku - uni-app 性能优化工具
• unplugin-auto-import - 自动导入插件

开发依赖

• @dcloudio/types - uni-app 类型定义
• miniprogram-api-typings - 小程序 API 类型定义
• rollup-plugin-visualizer - 打包分析工具