794 lines
23 KiB
Markdown
794 lines
23 KiB
Markdown
# 配件查询系统 - 项目开发文档
|
||
|
||
**项目名称**：配件查询App
|
||
**版本**：v1.0
|
||
**更新时间**：2025-10-01
|
||
**技术栈**：Spring Boot 3 + MySQL 8.0 + Vue 3 + uni-app
|
||
|
||
---
|
||
|
||
## 一、项目概述
|
||
|
||
### 1.1 项目定位
|
||
|
||
面向小微商户的移动端进销存管理应用，核心功能包括：
|
||
- 商品管理（库存、价格、类别）
|
||
- 进销存业务（销售开单、进货开单、退货处理）
|
||
- 客户与供应商管理
|
||
- 财务管理（账户、收支、报表）
|
||
- **配件查询**：支持配件参数化查询、用户提交、审核上架
|
||
|
||
### 1.2 系统架构
|
||
|
||
```
|
||
前端层：
|
||
├── 移动端（uni-app）: 用户端App + 微信小程序
|
||
├── 管理端（Vue3 + Element Plus）: 平台管理后台
|
||
└── 普通管理端（Vue3 + Element Plus）: 精简审核后台
|
||
|
||
后端层：
|
||
├── Spring Boot 3.x：RESTful API服务
|
||
├── MySQL 8.0：数据持久化
|
||
├── JWT：用户认证
|
||
└── Python FastAPI（可选）：条码识别服务
|
||
|
||
部署层：
|
||
├── 数据库：mysql.tonaspace.com:3306
|
||
├── 后端：Java应用服务器
|
||
└── 前端：静态资源 + CDN
|
||
```
|
||
|
||
### 1.3 多租户模型
|
||
|
||
- **租户隔离**：所有业务数据必须关联shop_id，严格按租户隔离
|
||
- **全局字典**：类别、单位使用shop_id=0作为平台共享字典
|
||
- **权限体系**：
|
||
- 平台管理员（admins表）：跨租户管理
|
||
- 店主（users.is_owner=1）：店铺所有权限
|
||
- 员工（users.role=staff）：基础操作权限
|
||
- 普通管理员（users.role=normal_admin）：配件审核权限
|
||
|
||
---
|
||
|
||
## 二、核心功能需求
|
||
|
||
### 2.1 用户端功能（移动App + 小程序）
|
||
|
||
#### 2.1.1 首页Dashboard
|
||
- ✅ **数据概览**：今日/本月销售额、本月利润、库存数量
|
||
- ✅ **快捷入口**：客户管理、销售开单、账户管理、供应商管理、进货开单、其他支出、VIP会员、报表统计
|
||
- ⚠️ **在线客服**：咨询入口已实现，悬浮按钮待添加
|
||
|
||
#### 2.1.2 货品管理
|
||
**列表功能**：
|
||
- ✅ 按类别筛选、关键字搜索（名称/条码/别名）
|
||
- ✅ 显示库存数量、零库存提示
|
||
- ✅ 总货品种类统计
|
||
|
||
**新增/编辑**：
|
||
- ✅ 商品图片上传（多图、排序、预览）
|
||
- ✅ 扫描条形码（App支持，小程序不支持）
|
||
- ✅ 必填项：商品名称
|
||
- ✅ 可选项：类别、品牌、型号、规格、产地、条码、描述
|
||
- ✅ 价格：进货价、零售价、批发价、大客户价（四列）
|
||
- ✅ 库存：当前库存、安全库存上下限
|
||
- ✅ 支持模板化参数录入
|
||
|
||
**货品设置**：
|
||
- ✅ 类别管理（读取全局字典）
|
||
- ✅ 单位管理（读取全局字典）
|
||
- ⚠️ 隐藏零库存商品、隐藏进货价：前端功能待实现
|
||
|
||
#### 2.1.3 配件查询与提交
|
||
- ✅ **配件搜索**：多参数组合查询、模糊匹配、分页展示
|
||
- ✅ **配件提交**：
|
||
- 型号唯一校验
|
||
- 多图上传（最多9张）
|
||
- 参数JSON录入
|
||
- 备注、安全库存
|
||
- 提交后进入待审核状态
|
||
- ✅ **提交记录**：查看pending/approved/rejected状态
|
||
- ✅ **提交详情**：查看审核结果、驳回原因
|
||
|
||
#### 2.1.4 开单模块
|
||
**销售单**：
|
||
- ✅ 出货单：选择客户、添加商品、计算合计、收款
|
||
- ✅ 退货单：客户退货处理
|
||
- ✅ 收款单：后续收款记录
|
||
|
||
**进货单**：
|
||
- ✅ 进货开单：选择供应商、添加商品、付款
|
||
- ✅ 进货退货：向供应商退货
|
||
|
||
**其他收支**：
|
||
- ✅ 其他收入：分类、往来单位、结算账户、备注
|
||
- ✅ 其他支出：分类、往来单位、结算账户、备注
|
||
- ✅ 财务分类动态配置
|
||
|
||
#### 2.1.5 明细查询
|
||
- ✅ 时间维度筛选：自定义、本周、今日、本月、本年
|
||
- ✅ 业务类型筛选：销售、进货、收银、资金、盘点
|
||
- ✅ 关键字搜索：单据号、客户/供应商名、品名、备注
|
||
- ✅ 总金额统计
|
||
- ✅ 快速新建单据
|
||
|
||
#### 2.1.6 报表统计
|
||
**资金报表**：
|
||
- ✅ 利润统计：按时间分析收入/支出/利润
|
||
- ✅ 销售报表：按客户或按货品维度聚合
|
||
- ⚠️ 营业员统计：待实现
|
||
- ⚠️ 导入导出：待实现
|
||
|
||
**进销存报表**：
|
||
- ✅ 销售统计：按商品/客户/时间维度
|
||
- ✅ 进货统计：按商品/供应商/时间维度
|
||
- ✅ 库存统计：当前库存、成本、分布
|
||
- ⚠️ 应收应付对账单：待实现
|
||
|
||
#### 2.1.7 我的（用户中心）
|
||
**个人信息**：
|
||
- ✅ 查看头像、姓名、手机号、邮箱
|
||
- ✅ 修改头像、姓名
|
||
- ✅ 修改密码
|
||
|
||
**VIP会员**：
|
||
- ✅ VIP状态查询（is_vip、expire_at、status）
|
||
- ✅ 一键开通VIP（点击即开通，临时方案）
|
||
- ✅ 充值记录查询
|
||
- ✅ 数据可见性：
|
||
- VIP用户：查看全部历史数据
|
||
- 普通用户：仅显示最近60天数据（可配置）
|
||
|
||
**基础管理**：
|
||
- ✅ 客户管理：新增、编辑、查询、默认价格等级
|
||
- ✅ 供应商管理：新增、编辑、查询、欠款管理
|
||
|
||
**登录与注册**：
|
||
- ✅ 手机号注册/登录
|
||
- ✅ 邮箱+密码登录
|
||
- ✅ 邮箱验证码注册
|
||
- ✅ 忘记密码（邮箱验证码重置）
|
||
- ⚠️ 短信验证码登录：后端已实现，前端待接入
|
||
- ⚠️ 微信登录：预留接口，待接入
|
||
|
||
**账号与安全**：
|
||
- ✅ 修改个人信息
|
||
- ✅ 修改登录密码
|
||
- ⚠️ 账号注销、退出登录：待实现
|
||
|
||
---
|
||
|
||
### 2.2 管理端功能（平台管理后台）
|
||
|
||
#### 2.2.1 用户管理
|
||
- ✅ 用户列表：按shop_id/关键字/分页查询
|
||
- ✅ 编辑用户：姓名、手机、角色、状态
|
||
- ✅ 拉黑/解除拉黑：置用户status=0/1
|
||
|
||
#### 2.2.2 用户配件管理
|
||
- ✅ 配件列表：按shop_id/关键字查询，显示模板信息
|
||
- ✅ 编辑配件：品牌、型号、规格、图片
|
||
- ✅ 配件恢复：取消软删除
|
||
|
||
#### 2.2.3 配件审核
|
||
- ✅ 提交列表：按状态/关键字/时间/店铺筛选
|
||
- ✅ 审核详情：查看完整信息、图片预览
|
||
- ✅ 编辑提交：修改名称、参数、图片、备注
|
||
- ✅ 审核通过：生成products记录、关联图片、记录审核人
|
||
- ✅ 审核驳回：记录驳回原因、审核人、审核时间
|
||
- ✅ Excel导出：按筛选条件导出（限2000条）
|
||
|
||
#### 2.2.4 配件模板管理
|
||
- ✅ 模板列表：查看所有模板
|
||
- ✅ 模板详情：查看参数定义
|
||
- ⚠️ 创建模板：后端接口已实现，前端待接入
|
||
- ⚠️ 更新模板：后端接口已实现，前端待接入
|
||
- ✅ 删除模板：软删除（status=0）或强制删除
|
||
|
||
#### 2.2.5 VIP管理
|
||
- ✅ 会员列表：按手机号/分页查询
|
||
- ✅ 价格设置：读取/修改vip_price表
|
||
- ✅ 价格配置接口：`GET/PUT /api/admin/vip/price`
|
||
- ⚠️ 新增会员：后端接口已实现，前端待接入
|
||
- ⚠️ 更新会员：后端接口已实现，前端待接入
|
||
|
||
#### 2.2.6 公告管理
|
||
- ✅ 公告列表：按状态/关键字查询
|
||
- ✅ 创建公告：标题、内容、标签、有效期、状态
|
||
- ⚠️ 编辑公告：后端接口已实现，前端待接入
|
||
- ⚠️ 发布/下线：后端接口已实现，前端待接入
|
||
|
||
#### 2.2.7 咨询回复
|
||
- ✅ 咨询列表：按shop_id/状态/关键字查询
|
||
- ✅ 回复咨询：单次回复并自动标记已解决
|
||
- ✅ 查看历史：查看用户历史咨询与回复
|
||
|
||
#### 2.2.8 主数据字典
|
||
- ✅ 主单位维护：新增、编辑、删除（shop_id=0）
|
||
- ✅ 主类别维护：新增、编辑、删除（shop_id=0）
|
||
|
||
#### 2.2.9 普通管理员审批
|
||
- ⚠️ 申请列表：查看待审核申请
|
||
- ⚠️ 审批通过：赋予normal_admin权限
|
||
- ⚠️ 审批驳回：记录驳回原因
|
||
- ⚠️ 撤销权限：移除normal_admin权限
|
||
|
||
#### 2.2.10 管理员登录
|
||
- ⚠️ 登录接口：后端已实现JWT签发，前端待接入
|
||
- 当前方案：本地存储写入ADMIN_ID临时方案
|
||
|
||
---
|
||
|
||
### 2.3 普通管理端功能（Admin-Lite）
|
||
|
||
#### 2.3.1 定位
|
||
- 面向VIP用户申请成为普通管理员后使用
|
||
- 仅包含"配件审核"与"我的"两个功能
|
||
- 使用用户端账号（邮箱+密码）登录
|
||
|
||
#### 2.3.2 配件审核（复用平台管理端逻辑）
|
||
- ⚠️ 提交列表：限定为本店数据
|
||
- ⚠️ 审核详情：查看、编辑、图片管理
|
||
- ⚠️ 通过/驳回：操作权限限定本店
|
||
- ⚠️ 导出（可选）：按配置开放
|
||
|
||
#### 2.3.3 我的
|
||
- ⚠️ 账户信息：展示VIP状态、普通管理员状态
|
||
- ⚠️ 申请入口：未获批VIP显示"申请成为普通管理员"按钮
|
||
- ⚠️ 退出登录
|
||
|
||
#### 2.3.4 权限规则
|
||
- 申请资格：必须为VIP用户（可配置是否要求有效期内）
|
||
- 审批策略：
|
||
- 方案A（当前采用）：平台审核
|
||
- 方案B：自动通过（通过配置normalAdmin.autoApprove控制）
|
||
- 有效性约束：普通管理员权限与VIP状态绑定（可配置）
|
||
- 范围隔离：仅可访问所属shop_id的数据
|
||
|
||
---
|
||
|
||
## 三、技术实现
|
||
|
||
### 3.1 后端技术栈
|
||
|
||
**框架与依赖**：
|
||
- Spring Boot 3.x
|
||
- Spring Data JPA
|
||
- Spring Security（JWT）
|
||
- MySQL Connector
|
||
- Apache POI（Excel导出）
|
||
- Java Mail（邮件验证码）
|
||
|
||
**项目结构**：
|
||
```
|
||
src/main/java/com/example/demo/
|
||
├── account/ # 账户管理
|
||
├── admin/ # 管理端控制器
|
||
├── attachment/ # 附件服务
|
||
├── auth/ # 认证服务（JWT、邮箱、短信、密码）
|
||
├── barcode/ # 条码识别代理
|
||
├── common/ # 公共组件（拦截器、异常处理、配置）
|
||
├── consult/ # 咨询管理
|
||
├── customer/ # 客户管理
|
||
├── dashboard/ # 首页概览
|
||
├── notice/ # 公告管理
|
||
├── order/ # 订单管理
|
||
├── product/ # 商品管理（含配件提交、模板）
|
||
├── report/ # 报表服务
|
||
├── supplier/ # 供应商管理
|
||
├── user/ # 用户管理
|
||
└── vip/ # VIP管理
|
||
```
|
||
|
||
**配置管理**（application.properties）：
|
||
- 数据库连接：通过环境变量`DB_URL/DB_USER/DB_PASSWORD`注入
|
||
- JWT配置：`jwt.secret`、`jwt.expiresIn`
|
||
- 邮件SMTP：`spring.mail.*`
|
||
- 附件存储：`attachments.upload.storage-dir`
|
||
- VIP配置：`vip.dataRetentionDaysForNonVip`（默认60天）
|
||
- 普通管理员：`normalAdmin.autoApprove`（默认false）
|
||
- ⚠️ 禁止硬编码：所有配置值必须通过环境变量或配置文件注入
|
||
|
||
**认证与鉴权**：
|
||
- JWT Token：用户登录后签发，包含userId、shopId、role
|
||
- AdminAuthInterceptor：平台管理端鉴权，支持Bearer Token和X-Admin-Id头
|
||
- NormalAdminAuthInterceptor：普通管理端鉴权，校验role=normal_admin且VIP有效
|
||
|
||
---
|
||
|
||
### 3.2 前端技术栈
|
||
|
||
#### 3.2.1 移动端（uni-app）
|
||
**技术选型**：
|
||
- HBuilderX
|
||
- Vue 2
|
||
- uni-ui组件库
|
||
|
||
**目录结构**：
|
||
```
|
||
frontend/
|
||
├── pages/ # 页面
|
||
│ ├── auth/ # 登录注册
|
||
│ ├── index/ # 首页
|
||
│ ├── product/ # 货品管理（含配件提交）
|
||
│ ├── order/ # 开单
|
||
│ ├── detail/ # 明细
|
||
│ ├── my/ # 我的
|
||
│ ├── customer/ # 客户
|
||
│ ├── supplier/ # 供应商
|
||
│ ├── account/ # 账户
|
||
│ └── report/ # 报表
|
||
├── components/ # 组件
|
||
│ ├── tabs/ # Tab组件
|
||
│ ├── layout/ # 布局组件
|
||
│ └── ImageUploader/ # 图片上传
|
||
└── common/ # 公共文件
|
||
├── config.js # 配置（API_BASE_URL、VIP_PRICE等）
|
||
├── http.js # HTTP封装
|
||
├── constants.js # 常量
|
||
└── navigation.js # 导航
|
||
```
|
||
|
||
**配置管理**（common/config.js）：
|
||
- API_BASE_URL：优先级：环境变量 > 本地存储 > 默认值
|
||
- SHOP_ID：店铺ID配置
|
||
- ENABLE_DEFAULT_USER：开发模式开关
|
||
- VIP_PRICE_PER_MONTH：VIP价格（默认15元）
|
||
- ⚠️ 所有配置禁止硬编码，必须支持环境变量覆盖
|
||
|
||
#### 3.2.2 管理端（Vue 3 + Element Plus）
|
||
**技术选型**：
|
||
- Vue 3 + Vite
|
||
- Element Plus
|
||
- Axios
|
||
|
||
**目录结构**：
|
||
```
|
||
admin/
|
||
├── src/
|
||
│ ├── views/ # 页面
|
||
│ │ ├── admin/ # 用户管理
|
||
│ │ ├── card/ # 卡片
|
||
│ │ ├── consult/ # 咨询
|
||
│ │ ├── dict/ # 字典
|
||
│ │ ├── normal-admin/ # 普通管理员审批
|
||
│ │ ├── notice/ # 公告
|
||
│ │ ├── parts/ # 配件管理（含审核Submissions.vue）
|
||
│ │ ├── supplier/ # 供应商
|
||
│ │ ├── users/ # 用户
|
||
│ │ └── vip/ # VIP管理
|
||
│ ├── api/ # API封装
|
||
│ ├── router/ # 路由
|
||
│ └── styles/ # 样式
|
||
└── vite.config.ts # Vite配置
|
||
```
|
||
|
||
**HTTP配置**（src/api/http.ts）：
|
||
- 自动注入X-Shop-Id、X-Admin-Id、X-User-Id头
|
||
- 优先级：localStorage > 环境变量 > 默认值
|
||
|
||
#### 3.2.3 普通管理端（Vue 3 + Element Plus）
|
||
**项目位置**：`normal-admin/`
|
||
|
||
**功能**：
|
||
- 复制admin项目结构，精简为配件审核+我的两个模块
|
||
- 登录沿用用户端认证接口
|
||
- 鉴权要求：role=normal_admin且VIP有效
|
||
|
||
⚠️ **当前状态**：项目框架已建立，核心功能待实现
|
||
|
||
---
|
||
|
||
### 3.3 数据库设计
|
||
|
||
**核心设计原则**：
|
||
1. 多租户隔离：所有业务表包含shop_id
|
||
2. 软删除：使用deleted_at标记，查询时过滤
|
||
3. 审计追踪：记录创建人、修改人、时间戳
|
||
4. 外键约束：合理使用，避免过度影响性能
|
||
5. 索引优化：高频查询字段建立复合索引
|
||
|
||
**表分类**：
|
||
- 核心业务表（30个）：见《数据库设计文档-核心业务表.md》
|
||
- 辅助配置表（16个）：见《数据库设计文档-辅助配置表.md》
|
||
|
||
**重要约束**：
|
||
- products.barcode：(shop_id, barcode)唯一
|
||
- part_submissions.model_unique：全局唯一
|
||
- users.phone/email：全局唯一
|
||
- accounts.name：(shop_id, name)唯一
|
||
- orders.order_no：(shop_id, order_no)唯一
|
||
|
||
---
|
||
|
||
### 3.4 接口设计
|
||
|
||
**接口文档**：`doc/openapi.yaml`
|
||
|
||
**实现状态标注**：
|
||
- ✅ Fully Implemented：前后端均已实现并联调通过
|
||
- ❌ Partially Implemented：仅一方实现或未完全联调
|
||
|
||
**核心接口组**：
|
||
1. 认证：`/api/auth/*`
|
||
2. 用户端：`/api/user/*`、`/api/products/*`、`/api/orders/*`、`/api/vip/*`
|
||
3. 平台管理端：`/api/admin/*`
|
||
4. 普通管理端：`/api/normal-admin/*`
|
||
5. 公共：`/api/notices`、`/api/attachments`、`/api/finance/categories`
|
||
|
||
**Header约定**：
|
||
- X-Shop-Id：店铺ID（默认1）
|
||
- X-User-Id：用户ID（用户端接口必传）
|
||
- X-Admin-Id：管理员ID（管理端接口必传）
|
||
- Authorization：Bearer Token（JWT方案，逐步迁移）
|
||
|
||
---
|
||
|
||
## 四、开发状态
|
||
|
||
### 4.1 已完成功能
|
||
|
||
**后端**：
|
||
- ✅ 用户认证体系（邮箱、密码、JWT）
|
||
- ✅ 商品管理（CRUD、价格、库存、图片）
|
||
- ✅ 配件提交与审核（用户提交、管理员审核、导出）
|
||
- ✅ 配件模板管理（CRUD、参数定义）
|
||
- ✅ 客户与供应商管理
|
||
- ✅ 订单管理（销售、进货、退货、付款）
|
||
- ✅ 财务管理（账户、其他收支、分类配置）
|
||
- ✅ 库存流水记录
|
||
- ✅ VIP状态查询与一键开通
|
||
- ✅ VIP充值记录查询
|
||
- ✅ 公告管理（CRUD、发布、下线）
|
||
- ✅ 咨询与回复
|
||
- ✅ 主数据字典维护
|
||
- ✅ 附件上传与校验
|
||
- ✅ 首页概览统计
|
||
- ✅ 销售报表（按客户/货品维度）
|
||
- ✅ 条码识别代理
|
||
|
||
**移动端（uni-app）**：
|
||
- ✅ 登录注册（邮箱密码、邮箱验证码）
|
||
- ✅ 首页概览
|
||
- ✅ 商品列表、详情、新增、编辑
|
||
- ✅ 配件提交、列表、详情
|
||
- ✅ 开单（销售、进货、退货、其他收支）
|
||
- ✅ 客户与供应商管理
|
||
- ✅ VIP状态查询与开通
|
||
- ✅ 用户信息查看与修改
|
||
|
||
**管理端（Vue3）**：
|
||
- ✅ 用户管理（列表、编辑、拉黑）
|
||
- ✅ 用户配件管理（列表、编辑、恢复）
|
||
- ✅ 配件审核（列表、详情、通过、驳回、导出）
|
||
- ✅ 模板列表、详情、删除
|
||
- ✅ VIP列表、价格设置
|
||
- ✅ 公告列表、创建
|
||
- ✅ 咨询列表、回复、历史
|
||
- ✅ 主数据字典维护
|
||
|
||
---
|
||
|
||
### 4.2 待完成功能
|
||
|
||
**高优先级**：
|
||
- ⚠️ 管理员登录页（前端）
|
||
- ⚠️ 普通管理员审批流程（前后端）
|
||
- ⚠️ 普通管理端核心功能（前端）
|
||
- ⚠️ 短信验证码登录（前端接入）
|
||
- ⚠️ 数据库脚本同步（backend/db/db.sql缺少多个表）
|
||
|
||
**中优先级**：
|
||
- ⚠️ 公告编辑、发布、下线（前端）
|
||
- ⚠️ VIP新增、更新（前端）
|
||
- ⚠️ 配件模板创建、更新（前端）
|
||
- ⚠️ 账号注销、退出登录
|
||
- ⚠️ 货品设置（隐藏零库存、隐藏进货价）
|
||
- ⚠️ 悬浮客服入口
|
||
- ⚠️ 应收应付对账单
|
||
- ⚠️ 营业员统计
|
||
|
||
**低优先级**：
|
||
- ⚠️ 微信登录（第三方认证）
|
||
- ⚠️ 数据导入导出
|
||
- ⚠️ 多语言支持
|
||
- ⚠️ 公告富文本编辑
|
||
- ⚠️ 操作日志可视化
|
||
|
||
---
|
||
|
||
### 4.3 已知问题
|
||
|
||
#### 4.3.1 严重问题
|
||
1. **数据库脚本不一致**：
|
||
- backend/db/db.sql缺少：admins、vip_users、vip_price、vip_recharges、sms_codes、email_codes、normal_admin_audits、consults、consult_replies、notices等表
|
||
- 新环境部署时无法初始化
|
||
- **建议**：立即同步db.sql与线上数据库结构
|
||
|
||
2. **密码默认值泄露**：
|
||
- application.properties第14行硬编码数据库密码默认值
|
||
- **建议**：移除默认值，强制要求环境变量
|
||
|
||
3. **unitId字段不一致**：
|
||
- Product实体无unitId字段（已移除）
|
||
- ProductDtos仍保留unitId
|
||
- OpenAPI文档中ProductDetail包含unitId
|
||
- **建议**：统一移除所有unitId引用
|
||
|
||
#### 4.3.2 中等问题
|
||
1. **身份验证混乱**：
|
||
- 后端支持JWT和X-Admin-Id两种方式
|
||
- 前端仍使用X-Admin-Id
|
||
- **建议**：统一迁移到JWT Bearer Token
|
||
|
||
2. **OpenAPI状态不准确**：
|
||
- 多个已实现接口仍标记为"Partially Implemented"
|
||
- **建议**：逐一验证并更新状态
|
||
|
||
3. **配置硬编码**：
|
||
- 前端存在多处硬编码fallback值（http://127.0.0.1:8080）
|
||
- **建议**：通过配置文件统一管理
|
||
|
||
---
|
||
|
||
## 五、部署与运维
|
||
|
||
### 5.1 环境要求
|
||
|
||
**生产环境**：
|
||
- JDK 17+
|
||
- MySQL 8.0+
|
||
- Node.js 16+（前端构建）
|
||
- Python 3.8+（可选，条码识别服务）
|
||
|
||
**开发环境**：
|
||
- IntelliJ IDEA / VS Code
|
||
- HBuilderX（uni-app开发）
|
||
- Maven 3.8+
|
||
- Git
|
||
|
||
---
|
||
|
||
### 5.2 环境变量配置
|
||
|
||
**后端必需**：
|
||
```bash
|
||
# 数据库
|
||
DB_URL=jdbc:mysql://mysql.tonaspace.com:3306/partsinquiry
|
||
DB_USER=root
|
||
DB_PASSWORD=<实际密码>
|
||
|
||
# JWT
|
||
JWT_SECRET=<随机生成的密钥>
|
||
JWT_EXPIRES_IN=86400
|
||
|
||
# 邮件（如需邮箱验证码）
|
||
MAIL_HOST=smtp.qq.com
|
||
MAIL_PORT=465
|
||
MAIL_USERNAME=<邮箱>
|
||
MAIL_PASSWORD=<授权码>
|
||
MAIL_FROM=<发件邮箱>
|
||
|
||
# 附件存储
|
||
ATTACHMENTS_DIR=./data/attachments
|
||
ATTACHMENTS_PLACEHOLDER_IMAGE=<占位图路径>
|
||
|
||
# VIP配置
|
||
VIP_NONVIP_RETENTION_DAYS=60
|
||
```
|
||
|
||
**前端必需**：
|
||
```bash
|
||
# 移动端（uni-app）
|
||
VITE_APP_API_BASE_URL=https://api.example.com
|
||
VITE_APP_SHOP_ID=1
|
||
VITE_APP_VIP_PRICE=15
|
||
|
||
# 管理端（Vue3）
|
||
VITE_APP_API_BASE_URL=https://api.example.com
|
||
VITE_APP_TITLE=配件查询管理端
|
||
```
|
||
|
||
---
|
||
|
||
### 5.3 部署流程
|
||
|
||
**后端部署**：
|
||
```bash
|
||
# 1. 打包
|
||
mvn clean package -DskipTests
|
||
|
||
# 2. 上传jar包
|
||
scp target/demo-0.0.1-SNAPSHOT.jar user@server:/app/
|
||
|
||
# 3. 启动服务
|
||
java -jar demo-0.0.1-SNAPSHOT.jar \
|
||
--spring.profiles.active=prod \
|
||
--server.port=8080
|
||
```
|
||
|
||
**前端部署**：
|
||
```bash
|
||
# 移动端（uni-app）
|
||
# HBuilderX: 发行 → 原生App-云打包 / 小程序-微信
|
||
|
||
# 管理端（Vue3）
|
||
cd admin
|
||
npm run build
|
||
# 将dist目录上传到Nginx/CDN
|
||
```
|
||
|
||
**数据库初始化**：
|
||
```bash
|
||
# 首次部署执行
|
||
mysql -h mysql.tonaspace.com -u root -p partsinquiry < backend/db/db.sql
|
||
|
||
# ⚠️ 注意：当前db.sql不完整，需先同步结构
|
||
```
|
||
|
||
---
|
||
|
||
### 5.4 监控与日志
|
||
|
||
**日志配置**：
|
||
- 路径：`./logs/application.log`
|
||
- 级别：生产环境INFO，开发环境DEBUG
|
||
- 轮转：按日期分割，保留30天
|
||
|
||
**监控指标**：
|
||
- 应用健康检查：`/actuator/health`
|
||
- JVM内存：通过Spring Boot Actuator暴露
|
||
- 数据库连接池：Hikari监控
|
||
- 接口响应时间：Logback日志记录
|
||
|
||
**告警规则**：
|
||
- 数据库连接失败
|
||
- 磁盘空间<10%
|
||
- 内存使用>90%
|
||
- 接口5xx错误率>1%
|
||
|
||
---
|
||
|
||
## 六、开发规范
|
||
|
||
### 6.1 代码规范
|
||
|
||
**后端（Java）**：
|
||
- 遵循阿里巴巴Java开发手册
|
||
- 统一使用Lombok简化代码
|
||
- 异常处理：GlobalExceptionHandler统一捕获
|
||
- 日志：使用SLF4J + Logback
|
||
- 事务：@Transactional注解，只读操作标记readOnly=true
|
||
|
||
**前端（JavaScript/TypeScript）**：
|
||
- ESLint规则：推荐配置
|
||
- 组件命名：PascalCase
|
||
- 变量命名：camelCase
|
||
- 常量命名：UPPER_SNAKE_CASE
|
||
|
||
---
|
||
|
||
### 6.2 Git工作流
|
||
|
||
**分支策略**：
|
||
- main：生产环境
|
||
- develop：开发环境
|
||
- feature/*：功能分支
|
||
- hotfix/*：紧急修复
|
||
|
||
**提交规范**：
|
||
```
|
||
feat: 新功能
|
||
fix: 修复bug
|
||
docs: 文档更新
|
||
style: 代码格式调整
|
||
refactor: 重构
|
||
test: 测试相关
|
||
chore: 构建/工具配置
|
||
```
|
||
|
||
**禁止操作**：
|
||
- ❌ 直接push到main分支
|
||
- ❌ 提交时跳过hooks（--no-verify）
|
||
- ❌ force push到main/master
|
||
- ❌ 提交大文件（>10MB）
|
||
- ❌ 提交敏感信息（密码、密钥）
|
||
|
||
---
|
||
|
||
### 6.3 数据库变更流程
|
||
|
||
1. **本地测试**：在开发环境验证DDL
|
||
2. **更新文档**：同步修改`doc/数据库设计文档-*.md`
|
||
3. **更新脚本**：同步修改`backend/db/db.sql`
|
||
4. **执行变更**：通过MysqlMCP执行线上变更
|
||
5. **验证结果**：查询information_schema确认结构
|
||
6. **更新代码**：修改Entity、DTO、Service
|
||
7. **更新接口**：修改`doc/openapi.yaml`
|
||
|
||
⚠️ **禁止直接在生产环境手动执行DDL**
|
||
|
||
---
|
||
|
||
## 七、测试策略
|
||
|
||
### 7.1 单元测试
|
||
|
||
**覆盖率要求**：
|
||
- Service层：>80%
|
||
- Controller层：>60%
|
||
- Util工具类：>90%
|
||
|
||
**测试框架**：
|
||
- JUnit 5
|
||
- Mockito
|
||
- Spring Boot Test
|
||
|
||
### 7.2 集成测试
|
||
|
||
**关键场景**：
|
||
- 配件提交 → 审核 → 生成商品
|
||
- 销售开单 → 库存扣减 → 收款
|
||
- VIP开通 → 数据可见性变化
|
||
- 普通管理员申请 → 审批 → 权限生效
|
||
|
||
### 7.3 性能测试
|
||
|
||
**压测指标**：
|
||
- 商品列表查询：<200ms（1000并发）
|
||
- 订单创建：<500ms（100并发）
|
||
- 配件搜索：<300ms（支持全文检索）
|
||
|
||
**工具**：
|
||
- JMeter
|
||
- Apache Bench
|
||
|
||
---
|
||
|
||
## 八、后续规划
|
||
|
||
### 8.1 短期（1-2月）
|
||
|
||
1. 完成普通管理员审批流程
|
||
2. 前端统一迁移到JWT认证
|
||
3. 同步数据库脚本（db.sql）
|
||
4. 补充缺失的前端功能（公告编辑、VIP管理等）
|
||
5. 完善单元测试覆盖率
|
||
|
||
### 8.2 中期（3-6月）
|
||
|
||
1. 微信登录集成
|
||
2. 数据导入导出功能
|
||
3. 高级报表（利润分析、库龄分析）
|
||
4. 消息通知系统（审核结果、VIP到期提醒）
|
||
5. 多语言支持（国际化）
|
||
|
||
### 8.3 长期（6月+）
|
||
|
||
1. 移动端原生性能优化
|
||
2. 大数据量优化（分库分表）
|
||
3. 多角色权限体系（RBAC）
|
||
4. 第三方支付集成（微信支付、支付宝）
|
||
5. 数据分析与BI看板
|
||
6. API开放平台（OAuth2.0）
|
||
|
||
---
|
||
|
||
## 九、联系方式
|
||
|
||
**技术支持**：
|
||
- 项目地址：C:\Users\21826\Desktop\wj\PartsInquiry
|
||
- 数据库：mysql.tonaspace.com:3306
|
||
- 文档路径：doc/
|
||
|
||
**文档维护**：
|
||
- 数据库变更后必须更新数据库设计文档
|
||
- 接口变更后必须更新openapi.yaml
|
||
- 新功能上线后必须更新本开发文档
|
||
|
||
---
|
||
|
||
**文档修订历史**：
|
||
- 2025-10-01：初始版本，整合现有需求与开发状态
|
||
|