230 lines
12 KiB
Markdown
230 lines
12 KiB
Markdown
有色再生资源交易平台 - 后端项目架构设计文档
|
||
项目代号：METALLOOP / metalloop
|
||
文档版本：v1.0
|
||
创建时间：2026-09-09
|
||
技术基座：Spring Boot 3.x + Sa-Token + MyBatis-Plus + MySQL 8.0 + Redis 6.0
|
||
|
||
1. 项目概述
|
||
本后端服务于“有色再生资源交易平台”，提供用户认证、权限管理、企业认证、产品目录管理、供应/求购信息发布与审核、即时聊天集成等核心业务 API。系统采用 RBAC（基于角色的访问控制） 权限模型，通过 Sa-Token 实现认证与鉴权，具备高扩展性和可维护性。
|
||
|
||
1.1 核心业务目标
|
||
支持企业注册、认证（营业执照 + 法人信息）、入驻平台；
|
||
|
||
支持企业发布供应信息与求购信息；
|
||
|
||
支持管理员审核交易信息与企业认证资料；
|
||
|
||
支持基于 RBAC 的后台管理权限体系；
|
||
|
||
支持与 OpenIM 集成，实现买卖双方在线即时沟通；
|
||
|
||
支持多环境部署（开发、测试、生产）。
|
||
|
||
2. 技术栈选型
|
||
组件 选型 版本 说明
|
||
JDK Oracle OpenJDK 17 LTS 长期支持版本，兼容 Spring Boot 3.x
|
||
开发框架 Spring Boot 3.2.x 核心基础框架
|
||
安全认证 Sa-Token 1.37.x 轻量级权限认证框架，支持 RBAC、分布式会话
|
||
ORM 框架 MyBatis-Plus 3.5.x 增强 MyBatis，提供代码生成、分页、逻辑删除等
|
||
数据库 MySQL 8.0+ 关系型数据库，支持事务、窗口函数等
|
||
缓存 / 会话存储 Redis 6.0+ 用于 Sa-Token 分布式会话、接口防刷、热点数据缓存
|
||
API 文档 Knife4j / Swagger 4.x 在线接口调试与文档生成
|
||
工具库 Hutool 5.8.x 常用工具类集合（日期、加密、Bean 拷贝等）
|
||
JSON 处理 Jackson (Spring Boot 内置) 序列化/反序列化
|
||
日志 SLF4J + Logback (Spring Boot 内置) 日志门面 + 实现
|
||
连接池 HikariCP (Spring Boot 内置) 高性能数据库连接池
|
||
构建工具 Maven 3.6+ 项目构建与依赖管理
|
||
3. 系统模块划分（Maven 多模块）
|
||
项目采用 Maven 多模块结构，便于后续拆分微服务或模块独立部署。
|
||
|
||
text
|
||
metalloop-backend/
|
||
├── pom.xml # 父 POM，统一版本管理
|
||
├── metalloop-common/ # 公共模块（无业务依赖）
|
||
│ ├── src/main/java/
|
||
│ │ └── com.metalloop.common/
|
||
│ │ ├── annotation/ # 自定义注解
|
||
│ │ ├── constant/ # 常量、枚举类
|
||
│ │ ├── exception/ # 自定义异常
|
||
│ │ ├── model/ # 统一返回模型（Result、PageResult）
|
||
│ │ └── utils/ # 工具类（MD5、JWT、DateUtil 等）
|
||
│ └── pom.xml
|
||
│
|
||
├── metalloop-framework/ # 框架配置模块
|
||
│ ├── src/main/java/
|
||
│ │ └── com.metalloop.framework/
|
||
│ │ ├── config/ # 通用配置（Jackson、线程池、CORS）
|
||
│ │ ├── satoken/ # Sa-Token 配置、权限拦截器
|
||
│ │ ├── mybatis/ # MyBatis-Plus 配置（分页、填充、逻辑删除）
|
||
│ │ └── swagger/ # Knife4j 配置
|
||
│ └── pom.xml
|
||
│
|
||
├── metalloop-dao/ # 数据访问层
|
||
│ ├── src/main/java/
|
||
│ │ └── com.metalloop.dao/
|
||
│ │ ├── entity/ # 数据库实体类（对应每张表）
|
||
│ │ ├── mapper/ # MyBatis-Plus Mapper 接口
|
||
│ │ ├── dto/ # 数据传输对象（业务层入参/出参）
|
||
│ │ └── vo/ # 视图对象（Controller 返回专用）
|
||
│ └── pom.xml
|
||
│
|
||
├── metalloop-service/ # 业务逻辑层
|
||
│ ├── src/main/java/
|
||
│ │ └── com.metalloop.service/
|
||
│ │ ├── auth/ # 认证服务
|
||
│ │ ├── user/ # 用户服务
|
||
│ │ ├── enterprise/ # 企业服务（含认证审核）
|
||
│ │ ├── product/ # 产品、品种、材质服务
|
||
│ │ ├── trade/ # 供应/求购信息服务
|
||
│ │ ├── permission/ # 权限与角色服务
|
||
│ │ ├── im/ # OpenIM 集成服务
|
||
│ │ └── impl/ # 各服务实现类（按模块分包）
|
||
│ └── pom.xml
|
||
│
|
||
├── metalloop-api/ # API 接口定义（可选，用于 Feign 或微服务）
|
||
│ ├── src/main/java/
|
||
│ │ └── com.metalloop.api/ # 对外暴露的 API 接口
|
||
│ └── pom.xml
|
||
│
|
||
└── metalloop-web/ # Web 启动模块
|
||
├── src/main/java/
|
||
│ └── com.metalloop.web/
|
||
│ ├── controller/ # REST Controller（按模块分包）
|
||
│ ├── interceptor/ # 全局拦截器
|
||
│ ├── filter/ # 过滤器
|
||
│ └── advice/ # 全局异常处理器
|
||
├── src/main/resources/
|
||
│ ├── application.yml # 主配置文件
|
||
│ ├── application-dev.yml # 开发环境配置
|
||
│ ├── application-prod.yml # 生产环境配置
|
||
│ ├── logback-spring.xml # 日志配置
|
||
│ └── mapper/ # MyBatis XML 映射文件（可选）
|
||
└── pom.xml
|
||
|
||
4. 包结构设计（单模块方案）
|
||
若采用单模块结构，推荐按业务模块分包，清晰隔离各领域：
|
||
|
||
text
|
||
com.metalloop
|
||
│
|
||
├── common # 公共组件（可独立为 common 模块）
|
||
│ ├── annotation # 自定义注解
|
||
│ │ ├── @RequirePermission # 权限校验注解（可选，Sa-Token 自带 @SaCheckPermission）
|
||
│ │ └── @LogOperation # 操作日志注解
|
||
│ ├── constant # 常量与枚举
|
||
│ │ ├── ApiCode.java # API 响应码枚举
|
||
│ │ ├── AuditStatusEnum.java # 审核状态枚举
|
||
│ │ └── UserStatusEnum.java # 用户状态枚举
|
||
│ ├── exception # 异常处理
|
||
│ │ ├── BusinessException.java # 业务异常
|
||
│ │ └── GlobalExceptionHandler.java # 全局异常拦截
|
||
│ ├── model # 统一响应模型
|
||
│ │ ├── Result.java # 统一返回结构
|
||
│ │ └── PageResult.java # 分页返回结构
|
||
│ └── utils # 工具类
|
||
│ ├── RedisUtil.java # Redis 工具封装
|
||
│ ├── SecurityUtil.java # 加密工具（BCrypt、MD5）
|
||
│ └── BeanCopyUtil.java # 对象拷贝工具
|
||
│
|
||
├── framework # 框架集成（可独立为 framework 模块）
|
||
│ ├── satoken
|
||
│ │ ├── SaTokenConfig.java # Sa-Token 配置类
|
||
│ │ ├── StpInterfaceImpl.java # 权限/角色数据源实现
|
||
│ │ └── SaTokenInterceptor.java # 全局鉴权拦截器（可选）
|
||
│ ├── mybatis
|
||
│ │ ├── MybatisPlusConfig.java # 分页、乐观锁配置
|
||
│ │ ├── MetaObjectHandler.java # 自动填充（createTime、updateTime）
|
||
│ │ └── LogicDeleteConfig.java # 逻辑删除配置（若使用）
|
||
│ ├── redis
|
||
│ │ └── RedisConfig.java # Redis 序列化配置（Jackson2Json）
|
||
│ └── swagger
|
||
│ └── Knife4jConfig.java # API 文档配置
|
||
│
|
||
├── modules # 业务模块
|
||
│ │
|
||
│ ├── auth # 认证模块
|
||
│ │ ├── controller
|
||
│ │ │ └── AuthController.java # 登录、登出、刷新 Token
|
||
│ │ ├── service
|
||
│ │ │ ├── AuthService.java
|
||
│ │ │ └── impl
|
||
│ │ │ └── AuthServiceImpl.java
|
||
│ │ ├── model
|
||
│ │ │ ├── LoginDTO.java # 登录请求参数
|
||
│ │ │ └── LoginVO.java # 登录响应（含 Token）
|
||
│ │ └── mapper # （复用 dao 层 Mapper）
|
||
│ │
|
||
│ ├── user # 用户管理模块
|
||
│ │ ├── controller
|
||
│ │ │ └── UserController.java # 用户 CRUD、禁用/启用
|
||
│ │ ├── service
|
||
│ │ └── model
|
||
│ │
|
||
│ ├── enterprise # 企业管理模块
|
||
│ │ ├── controller
|
||
│ │ │ └── EnterpriseController.java # 企业认证、审核、查询
|
||
│ │ ├── service
|
||
│ │ ├── model
|
||
│ │ │ ├── EnterpriseSubmitDTO.java # 提交认证资料
|
||
│ │ │ └── EnterpriseAuditDTO.java # 审核操作
|
||
│ │ └── mapper
|
||
│ │
|
||
│ ├── product # 产品目录模块
|
||
│ │ ├── controller
|
||
│ │ │ ├── ProductController.java
|
||
│ │ │ ├── VarietyController.java
|
||
│ │ │ └── MaterialController.java
|
||
│ │ ├── service
|
||
│ │ └── model
|
||
│ │
|
||
│ ├── trade # 交易信息模块
|
||
│ │ ├── controller
|
||
│ │ │ ├── SupplyController.java # 供应信息
|
||
│ │ │ └── PurchaseController.java # 求购信息
|
||
│ │ ├── service
|
||
│ │ └── model
|
||
│ │
|
||
│ ├── permission # 权限管理模块（后台）
|
||
│ │ ├── controller
|
||
│ │ │ ├── RoleController.java # 角色 CRUD
|
||
│ │ │ └── PermissionController.java # 权限/菜单管理
|
||
│ │ ├── service
|
||
│ │ └── model
|
||
│ │
|
||
│ └── im # 即时聊天模块（OpenIM 集成）
|
||
│ ├── controller
|
||
│ │ └── IMController.java # 获取 IM Token、Webhook 接收
|
||
│ ├── service
|
||
│ │ ├── IMService.java # OpenIM API 调用封装
|
||
│ │ └── WebhookService.java # 处理 OpenIM 回调事件
|
||
│ └── model
|
||
│
|
||
└── web # Web 层公共配置
|
||
├── config
|
||
│ └── WebMvcConfig.java # 跨域、静态资源、拦截器注册
|
||
├── filter
|
||
│ └── RequestLogFilter.java # 请求日志过滤器
|
||
└── MainApplication.java # Spring Boot 启动类
|
||
5. 数据库表清单
|
||
5.1 系统权限模块（sys_*）
|
||
表名 说明 关键字段
|
||
sys_user 用户表 id, username, password, phone, enterprise_id, auth_status, user_status
|
||
sys_role 角色表 id, role_name, status, is_system, sort
|
||
sys_permission 权限表（菜单 + 按钮） id, name, code, type, parent_id, api_path, route_path
|
||
sys_user_role 用户-角色关联表 user_id, role_id
|
||
sys_role_permission 角色-权限关联表 role_id, permission_id
|
||
5.2 企业模块（sys_enterprise 系列）
|
||
注：根据现有数据库，企业表实际前缀为 sys_，与系统模块共用，逻辑上可按业务域区分。
|
||
|
||
表名 说明 关键字段
|
||
sys_enterprise 企业信息主表 id, enterprise_name, legal_person, unified_social_credit_code, audit_status, credit_limit
|
||
sys_enterprise_image 企业图片附件表 id, enterprise_id, image_type, image_url
|
||
5.3 业务交易模块（biz_*）
|
||
表名 说明 关键字段
|
||
biz_product 产品基础表 id, product_name, product_code, unit, status
|
||
biz_variety 品种表（支持层级） id, variety_name, parent_id, variety_grade
|
||
biz_material 材质基础表 id, material_name
|
||
biz_enterprise_product 企业经营产品表 id, enterprise_id, variety_id, material_id, unit_price, weight
|
||
biz_purchase_request 求购信息表 id, create_user_id, title, quantity, unit_price, audit_status, expire_time
|
||
biz_supply_info 发布信息表（供应） id, create_user_id, title, quantity, unit_price, audit_status, expire_time
|
||
biz_product_element_detail 产品材质详情表 id, product_id, element_name, element_content |