PartsInquiry/doc/项目开发文档.md

配件查询系统 - 项目开发文档

项目名称：配件查询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 环境变量配置

后端必需：

# 数据库
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

前端必需：

# 移动端（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 部署流程

后端部署：

# 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

前端部署：

# 移动端（uni-app）
# HBuilderX: 发行 → 原生App-云打包 / 小程序-微信

# 管理端（Vue3）
cd admin
npm run build
# 将dist目录上传到Nginx/CDN

数据库初始化：

# 首次部署执行
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：初始版本，整合现有需求与开发状态