有色再生资源交易平台 - 后端项目架构设计文档 项目代号：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