# Project Context

## 项目背景

### 一、 银行端核心业务背景

银行端作为金融生态的核心资金与风控方，其业务背景建立在与政务、商家、保险及用户的紧密协作之上，通过数字化手段重构核心作业流程。

###### 1. 各端交互与协作生态

银行端通过数据与流程的互联互通，形成完整的金融生态闭环：

*   **与用户端 (农户/C端)**：**服务与被服务**。
    *   **精准获客**: 结合线下走访与线上数据建立多维度画像。
    *   **便捷用信**: 将信贷额度嵌入交易场景，实现“钱找人”的无感支付。
*   **与商家端 (企业/商户)**：**场景与验真**。
    *   **贸易验真**: 交叉验证订单与物流数据，确保信贷资金流向真实贸易。
    *   **受托支付**: 资金封闭运行，直接结算至商户，降低挪用风险。
*   **与保险端 (保险公司)**：**风险共担**。
    *   **履约保证**: 引入保险增信，互通投保状态，构建“无保不贷”机制。
    *   **风险联控**: 逾期信息同步，触发双向预警与理赔协同。
*   **与政务端 (政府监管)**：**合规与引导**。
    *   **穿透监管**: 实时报送业务数据，接受全流程合规审计。
    *   **政策协同**: 自动匹配贴息与补贴政策，实现普惠金融精准滴灌。

###### 2. 核心业务运作模式

银行端业务遵循“贷前调查、贷中审查、贷后管理”的标准化金融规范，并进行了数字化升级：

*   **贷前：网格化营销与建档**
    *   **目标**: 解决信息不对称，还原真实经营状况。
    *   **模式**: 客户经理通过“拜访计划”进行网格化展业，现场采集影像与资产数据，实现数字化建档与初评。
*   **贷中：智能化审批与授信**
    *   **目标**: 提升审批效率，严控准入风险。
    *   **模式**: 系统聚合多方数据进行自动化风控筛查，结合人工专业判断核定额度，一键激活场景化信用额度。
*   **贷后：信息聚合与数据支撑**
    *   **目标**: 为银行提供透明数据，支撑自主贷后管理。
    *   **模式**: 平台作为“信息中介”，实时同步交易数据，聚合还款与经营概况，提供标准化报表辅助银行监测风险。

---

### 二、 商家端核心业务背景

商家端致力于打造“交易+金融”的双轮驱动模式，既是商品交易的履约方，也是普惠金融落地的关键场景方。

###### 1. 数字化经营与供应链管理

*   **目标**: 实现商品与库存的精细化管理，构建可信的交易数据底座。
*   **场景**: 建立标准化的SKU体系，通过数字化进销存沉淀真实的经营流水，将“数据”转化为“资产”。

###### 2. 订单履约与受托支付

*   **目标**: 规范交易流程，确保资金闭环安全。
*   **场景**: 严格执行标准履约流程，作为受托支付对象接收信贷资金，配合验证资金用途。

###### 3. 信用辅助与渠道协同

*   **目标**: 激活供应链上下游信用，降低金融服务门槛。
*   **场景**: 依托核心企业信用推荐优质客户，并在结算环节协助核实交易真实性，完成资金闭环。

---

### 三、 保险端核心业务背景

保险端作为金融生态的“减震器”，通过专业的风险管理能力，为信贷资金提供安全屏障。

###### 1. 产品定制与承保准入

*   **目标**: 精准识别承保标的，提供适配的风险保障。
*   **场景**: 针对不同客群定制差异化保险产品，对接信贷数据进行自动化核保，实现承保前置。

###### 2. 保单管理与风险共担

*   **目标**: 动态评估风险敞口，确保资产安全。
*   **场景**: 全生命周期管理电子保单，与银行端实时交互风险数据，动态调整承保策略。

###### 3. 智能理赔与追偿协同

*   **目标**: 快速响应出险事件，保障权益。
*   **场景**: 接收逾期信号自动触发理赔流程，赔付后与多方协同开展追偿，降低综合损失。

---

### 四、 政务端核心业务背景

政务端在生态中扮演“监管者”与“服务者”的双重角色，引导金融资源合规、高效服务实体经济。

###### 1. 区域金融监测与监管

*   **目标**: 防范系统性风险，掌握宏观态势。
*   **场景**: 通过驾驶舱实时监控辖区信贷指标，设置红线自动预警违规行为。

###### 2. 政策扶持与精准滴灌

*   **目标**: 提高财政资金效益。
*   **场景**: 数字化管理补贴资格白名单，基于真实交易数据自动核算并与信贷发放联动，确保政策红利直达。

###### 3. 信用体系建设与共享

*   **目标**: 打破数据孤岛，构建社会信用。
*   **场景**: 归集政务数据丰富主体画像，输出公共信用评价结果，解决“征信白户”难题。

---

## Purpose

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

1. **用户端**（C端）：提供商品浏览、购物车、订单管理、会员服务、金融服务等功能
2. **商家端**（B端）：提供商品管理、订单处理、财务管理、贷款协助、店铺设置等功能
3. **银行端**（B端）：提供客户管理、贷款审核、交易记录、提现管理、拜访计划等功能
4. **政务端**（B端）：提供银行管理、合规检查、风险预警、报表管理等功能
5. **保险端**（B端）：提供保单管理、理赔处理、合作银行管理等功能

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

**多端架构特点：**
- 每个端独立配置 Tabbar 导航
- 使用分包优化策略，减少首屏加载时间
- 登录后根据角色自动切换到对应端

## 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 - 请求库（推荐，支持 uni-app 适配器）
- **简单封装的 http** - 轻量级请求方案（`src/http/http.ts`）
- **vue-query** - 查询状态管理（用于自动生成接口，`src/http/vue-query.ts`）

**HTTP 配置：**
- 统一的请求拦截器（`src/http/interceptor.ts`）
- 支持登录拦截和自动跳转
- 支持请求/响应错误处理
- 自动注入 Token（如已登录）

### 工具库
- **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

## Development Commands

### 常用开发命令
```bash
# H5 开发（默认）
pnpm dev

# 微信小程序开发
pnpm dev:mp

# App 开发
pnpm dev:app

# 指定环境运行
pnpm dev:test      # 测试环境
pnpm dev:prod      # 生产环境
```

### 打包构建命令
```bash
# H5 打包
pnpm build

# 微信小程序打包
pnpm build:mp

# App 打包
pnpm build:app
```

### 代码检查与类型检查
```bash
# ESLint 检查
pnpm lint

# ESLint 自动修复
pnpm lint:fix

# TypeScript 类型检查
pnpm type-check
```

### API 生成
```bash
# 从 OpenAPI 规范生成 API 接口代码
pnpm openapi
```

### 环境配置
项目支持多环境配置：
- `.env.development` - 开发环境
- `.env.test` - 测试环境
- `.env.production` - 生产环境

## 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 自动导入
- 组件自动导入（支持递归扫描子目录）

#### OpenAPI 集成
- 使用 `openapi-ts-request` 从 OpenAPI 规范自动生成 API 接口代码
- 生成的代码存放在 `src/service/` 目录（不应提交到版本控制）
- 支持自动生成 TypeScript 类型定义和请求函数

### Architecture Patterns

#### 目录结构
```
src/
├── api/               # API 接口定义
├── components/        # 公共组件
├── hooks/            # 组合式函数
├── http/             # HTTP 请求封装
├── layouts/          # 布局组件
├── mock/             # Mock 数据
├── pages/            # 用户端页面（主包）
├── pagesMerchant/    # 商家端页面（分包）
├── pagesBank/        # 银行端页面（分包）
├── pagesGovernment/  # 政务端页面（分包）
├── pagesInsurance/   # 保险端页面（分包）
├── router/           # 路由配置
├── service/          # 自动生成的服务接口
├── static/           # 静态资源
├── store/            # Pinia 状态管理
├── tabbar/           # Tabbar 配置
├── typings/          # 类型定义
└── utils/            # 工具函数
```

#### 路由策略
- **约定式路由**：基于文件系统自动生成路由
- **Layout 布局**：支持多布局系统
- **分包优化**：使用 `@uni-ku/bundle-optimizer` 进行分包优化
- **异步导入**：支持模块和组件的异步跨包引用
- **分包配置**：各端独立分包（pagesMerchant、pagesBank、pagesGovernment、pagesInsurance）
- **预下载规则**：登录后自动预下载所有分包

#### 多端 Tabbar 策略
支持 4 种 Tabbar 策略（`TABBAR_STRATEGY_MAP`）：
- `NO_TABBAR` (0)：无 Tabbar
- `NATIVE_TABBAR` (1)：完全原生 Tabbar
- `CUSTOM_TABBAR_WITH_CACHE` (2)：有缓存自定义 Tabbar（当前配置）
- `CUSTOM_TABBAR_WITHOUT_CACHE` (3)：无缓存自定义 Tabbar

各端独立的 Tabbar 配置：
- `userTabbarList`：用户端（首页、分类、购物车、我的）
- `merchantTabbarList`：商家端（工作台、订单、商品、财务、我的）
- `bankTabbarList`：银行端（工作台、审核、客户、我的）
- `governmentTabbarList`：政务端（工作台、检查、报表、我的）
- `insuranceTabbarList`：保险端（工作台、保单、理赔、我的）

通过 `getTabbarListByClientType()` 根据客户端类型动态切换 Tabbar。

#### 登录策略
支持两种登录策略（通过 `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 进行 Vue 组件测试
- **端到端测试**：使用 Playwright 进行跨平台 E2E 测试
- **小程序测试**：使用 miniprogram-simulate 进行微信小程序单元测试

### 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端）
- **仪表盘**：数据统计
- **客户管理**：客户列表、客户详情、交易记录、提现记录
- **审核管理**：贷款审核列表、审核详情
- **拜访管理**：拜访计划列表、创建拜访、拜访详情
- **报表管理**：报表列表、报表下载

#### 政务端（B端）
- **仪表盘**：区域金融监测
- **银行管理**：银行列表、银行详情
- **合规检查**：检查列表、检查详情
- **风险预警**：风险列表、风险详情

#### 保险端（B端）
- **仪表盘**：业务概览
- **保单管理**：保单列表、保单详情
- **理赔处理**：理赔列表、理赔详情
- **合作银行**：合作银行列表

### 关键概念
- **多端适配**：同一套代码适配 H5、App、小程序
- **五端架构**：用户、商家、银行、政务、保险五个独立端
- **角色权限**：根据登录角色自动切换对应端的 Tabbar 和页面
- **金融服务**：信用额度、贷款申请、结算、核销
- **会员体系**：会员卡、会员权益
- **分包优化**：各端独立分包，登录后预下载
- **Tabbar 策略**：支持原生和自定义 Tabbar，可配置缓存

## Important Constraints

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

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

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

## Deployment Architecture

### 多平台部署流程

**H5 部署：**
1. 运行 `pnpm build` 构建生产版本
2. 生成的文件位于 `dist/build/h5`
3. 部署到 Web 服务器（nginx、Apache 等）
4. 如非根目录部署，需在 `manifest.config.ts` 中配置 `h5.router.base`

**小程序部署：**
1. 运行 `pnpm build:mp` 构建小程序
2. 生成的文件位于 `dist/build/mp-weixin`
3. 使用微信开发者工具导入并上传
4. 在微信公众平台提交审核

**App 部署：**
1. 运行 `pnpm build:app` 构建 App
2. 生成的文件位于 `dist/build/app`
3. 使用 HBuilderX 导入文件夹
4. 选择"发行 - APP云打包"
5. （安卓和鸿蒙可直接用 HBuilderX 运行/发行）

### 分包策略优化
- 用户端（主包）：核心页面和组件
- 商家端、银行端、政务端、保险端：独立分包
- 登录后自动预下载所有分包（`preloadRule`）
- 使用 `@uni-ku/bundle-optimizer` 进行体积优化

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