TONASPACE/PartsInquiry

Fork 0

Files

Wdp-ab 0e14a5fa1c 准备上传

2025-10-08 19:15:20 +08:00

23 KiB

Raw Permalink Blame History

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

项目名称：配件查询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 数据库设计

核心设计原则：

多租户隔离：所有业务表包含shop_id
软删除：使用deleted_at标记，查询时过滤
审计追踪：记录创建人、修改人、时间戳
外键约束：合理使用，避免过度影响性能
索引优化：高频查询字段建立复合索引

表分类：

核心业务表（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：仅一方实现或未完全联调

核心接口组：

认证：/api/auth/*
用户端：/api/user/*、/api/products/*、/api/orders/*、/api/vip/*
平台管理端：/api/admin/*
普通管理端：/api/normal-admin/*
公共：/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 严重问题

数据库脚本不一致：
- backend/db/db.sql缺少：admins、vip_users、vip_price、vip_recharges、sms_codes、email_codes、normal_admin_audits、consults、consult_replies、notices等表
- 新环境部署时无法初始化
- 建议：立即同步db.sql与线上数据库结构
密码默认值泄露：
- application.properties第14行硬编码数据库密码默认值
- 建议：移除默认值，强制要求环境变量
unitId字段不一致：
- Product实体无unitId字段（已移除）
- ProductDtos仍保留unitId
- OpenAPI文档中ProductDetail包含unitId
- 建议：统一移除所有unitId引用

4.3.2 中等问题

身份验证混乱：
- 后端支持JWT和X-Admin-Id两种方式
- 前端仍使用X-Admin-Id
- 建议：统一迁移到JWT Bearer Token
OpenAPI状态不准确：
- 多个已实现接口仍标记为"Partially Implemented"
- 建议：逐一验证并更新状态
配置硬编码：
- 前端存在多处硬编码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 数据库变更流程

本地测试：在开发环境验证DDL
更新文档：同步修改doc/数据库设计文档-*.md
更新脚本：同步修改backend/db/db.sql
执行变更：通过MysqlMCP执行线上变更
验证结果：查询information_schema确认结构
更新代码：修改Entity、DTO、Service
更新接口：修改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月）

完成普通管理员审批流程
前端统一迁移到JWT认证
同步数据库脚本（db.sql）
补充缺失的前端功能（公告编辑、VIP管理等）
完善单元测试覆盖率

8.2 中期（3-6月）

微信登录集成
数据导入导出功能
高级报表（利润分析、库龄分析）
消息通知系统（审核结果、VIP到期提醒）
多语言支持（国际化）

8.3 长期（6月+）

移动端原生性能优化
大数据量优化（分库分表）
多角色权限体系（RBAC）
第三方支付集成（微信支付、支付宝）
数据分析与BI看板
API开放平台（OAuth2.0）

九、联系方式

技术支持：

项目地址：C:\Users\21826\Desktop\wj\PartsInquiry
数据库：mysql.tonaspace.com:3306
文档路径：doc/

文档维护：

数据库变更后必须更新数据库设计文档
接口变更后必须更新openapi.yaml
新功能上线后必须更新本开发文档

文档修订历史：

2025-10-01：初始版本，整合现有需求与开发状态

23 KiB Raw Permalink Blame History Unescape Escape