准备上传

doc/项目开发文档.md

@@ -0,0 +1,793 @@
+# 配件查询系统 - 项目开发文档
+
+**项目名称**：配件查询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：初始版本，整合现有需求与开发状态
+