JooLun Plus 技术规范

1. 项目定位

本项目是基于 Spring Cloud 的多模块微服务系统，包含后台管理、认证中心、网关、商城业务、微信能力、支付能力、直播能力、公共组件与多端前端应用。

2. 技术栈

• 后端：Java 17、Spring Boot 4.x、Spring Cloud 2025.x、Spring Cloud Alibaba、MyBatis Plus
• 后台前端：Vue 2、Element-UI、Avue
• 移动端：UniApp
• 中间件：MySQL、Redis、Nacos 3.1.1、RocketMQ、Elasticsearch
• 运维：Docker

3. 模块边界

• joolun-gateway：统一网关
• joolun-auth：认证授权中心
• joolun-upms：平台管理、租户、权限、公共配置
• joolun-mall：商城业务
• joolun-weixin：公众号、小程序、微信能力
• joolun-pay：支付相关能力
• joolun-live：直播相关能力
• joolun-codegen：代码生成器
• joolun-monitor：监控中心
• joolun-common：公共基础库

当前 plus 基础框架不包含 open_* 服务。

4. 分层规范

• Controller 只做参数接收、权限控制、返回封装
• Service 承载业务逻辑
• Mapper / SQL 只做数据访问
• VO / DTO 只做数据传输
• 公共能力优先沉淀到 joolun-common

5. 数据规范

• 系统主库固定为 joolun_plus_upms
• 业务分库遵循 基础库名_租户ID
• 默认租户标识为 -1
• 所有租户相关数据必须显式处理 tenant_id

6. 租户与权限

• 租户上下文由 TenantContextHolder 统一维护
• 权限码按模块前缀区分，例如：
  • upms:*
  • mall:*
  • pay:*
  • live:*
• 菜单与角色授权通过 SQL 脚本同步

7. 编码规范

• Java / XML / SQL 使用 UTF-8、LF
• Java 使用 tab 缩进
• 前端 JS / Vue 使用 2 空格
• 类名使用大驼峰，方法名使用小驼峰
• 新增接口必须补中文注释或接口说明

8. 配置规范

• 环境分为 dev、test、pro
• 配置统一走 Nacos
• 不提交真实密钥、证书、生产账号
• 新增模块若依赖数据库连接，必须说明对应配置项
• Spring Boot 4 之后，所有服务都必须保留 spring.config.import 的 Nacos 导入配置

9. SQL 规范

• 升级脚本放在 db/升级脚本
• 一个脚本只处理一个版本增量
• SQL 文件尽量避免写死 USE 库名;
• 涉及菜单权限时，必须同时包含 sys_menu 和 sys_role_menu
• 涉及配置中心变更时，优先同步 joolun_plus_config

10. 前端规范

• 页面路径与后端模块保持一致
• API 路径按模块划分
• 页面标题、提示、空状态统一中文
• 上传 / 批量类页面必须支持重置和重复操作

11. 部署规范

• 本地开发先启动基础中间件，再启动服务
• Nacos 基线统一为 3.1.1
• 每次升级要同步更新数据库脚本和 Nacos 配置
• 升级后要清理缓存并重启相关服务
• 支付服务名称统一使用 joolun-pay-admin

12. 变更要求

• 新增功能必须明确所属模块
• 跨模块调用优先使用 Feign 或公共接口
• 不允许把平台级能力误放进业务模块
• 权限、菜单、路由必须同步变更

13. 验收要求

• 后端核心服务能启动
• 后台前端能正常编译
• 菜单能正常显示
• 权限能正确控制
• 数据库脚本可重复执行
• /v3/api-docs/swagger-config 能正常访问