lizi/shop-toy
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
725aa1819a9378d3c593d76bf8bb3627ab5330c1
shop-toy/openspec/project.md
xiayebo 725aa1819a 修改项目信息
2026-01-12 11:41:56 +08:00

16 KiB
Raw Blame History

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

常用开发命令

# H5 开发（默认）
pnpm dev

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

# App 开发
pnpm dev:app

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

打包构建命令

# H5 打包
pnpm build

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

# App 打包
pnpm build:app

代码检查与类型检查

# ESLint 检查
pnpm lint

# ESLint 自动修复
pnpm lint:fix

# TypeScript 类型检查
pnpm type-check

API 生成

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