# 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** - 打包分析工具