添加代码风格文档

2026-03-12 17:46:45 +08:00
parent 7fcefb439b
commit 973524b001
4 changed files with 196 additions and 0 deletions
@@ -0,0 +1,121 @@
+---
+inclusion: always
+---
+
+# 代码开发风格文档
+
+本项目为 Spring Boot + MyBatis-Plus 的 Java 17 多模块后端项目，基础包名 `org.jiayunet`。
+
+## 项目结构
+
+- `common` — 公共模块：配置、拦截器、工具类、统一响应、异常体系
+- `client-api` — C 端接口模块，依赖 manager
+- `manager` — 业务共享模块：实体、Mapper、业务服务，B 端和 C 端共用，依赖 common
+- 各模块内按职责分包：`controller`、`server`、`pojo`（dto/vo/po/param）、`mapper`、`config`、`aop`、`annotation`、`tool`、`constant`、`interceptor`
+
+## 命名约定
+
+### 类命名
+- 服务层以 `Server` 结尾（不用 Service），如 `LoginServer`、`SmsServer`
+- DTO 以 `Dto` 结尾，VO 以 `Vo` 结尾，Param 以 `Param` 结尾，PO 无后缀直接用业务名
+- Controller 以 `Controller` 结尾
+- 工具类以 `Tool` 结尾，如 `RedisServerTool`、`HttpIpTool`
+- 配置类以 `Config` 或 `Conf` 结尾
+- 切面以 `Aspect` 结尾，拦截器以 `Interceptor` 结尾，过滤器以 `Filter` 结尾
+- 能力/抽象类以 `Ability` 结尾，如 `EmailAbility`
+- 枚举以 `Enum` 结尾，枚举接口以 `Operations` 结尾
+
+### 常量
+- Redis key 前缀用 `interface` 定义常量，集中在 `PreRedisKeyName` 中
+- 自定义配置属性统一用 `app.` 前缀分组
+
+## 注解与依赖注入
+
+- Controller 层：`@RestController` + `@RequestMapping`，构造器注入（`@AllArgsConstructor`）
+- Server 层：`@Service`，字段注入（`@Autowired`）
+- 配置值：`@Value("${app.xxx:默认值}")`，始终提供默认值
+- 参数校验：类上 `@Validated`，字段上 `@NotBlank`、`@Pattern` 等
+- 写操作方法加 `@Transactional(rollbackFor = Exception.class)`
+- 所有 POJO 使用 `@Data`，需要日志的类加 `@Slf4j`
+
+## 注释规范
+
+- 类注释 Javadoc 格式，标注 `@author zk`
+- 方法注释 `/** */`，简洁描述功能
+- 字段注释 `/** */` 单行格式
+
+### PO 实体类注释
+- 类注释说明对应的表名和用途
+- 特殊字段（状态码、标志位、枚举值等）在注释中说明每个值的含义，如 `/** 状态 0=正常 1=禁用 */`
+
+### Server 类注释
+- 类注释说明该服务的主要功能
+- 类注释中列出依赖的其他模块/服务，以及使用到的表和使用目的，格式示例：
+  ```java
+  /**
+   * 登录服务
+   * <p>依赖：SmsServer（验证码发送与校验）、UserRegisterServer（自动注册）</p>
+   * <p>使用表：bg_user（查询/创建用户）</p>
+   *
+   * @author zk
+   */
+  ```
+- 每个方法用 `/** */` 简要说明逻辑流程，复杂方法可分步骤描述，格式示例：
+  ```java
+  /**
+   * 短信验证码登录
+   * <p>1. 校验验证码 2. 查询用户，不存在则自动注册 3. 检查用户状态 4. 生成JWT并写入Redis 5. 设置Cookie</p>
+   */
+  ```
+
+## POJO 规范
+
+- DTO：入参对象 + 校验注解，放在 `pojo/dto/{功能模块}/` 下，功能模块一般是对应 Server 类名的简写，如 `pojo/dto/login/SmsLoginDto.java`
+- VO：出参对象，放在 `pojo/vo/{功能模块}/` 下，如 `pojo/vo/login/LoginVo.java`
+- PO：对应数据库表字段，统一放在 `manager` 模块的 `pojo/po/` 下
+- Param：查询参数对象，放在 `pojo/param/{功能模块}/` 下
+
+## 获取当前登录用户
+
+- 通过 `UserSecurityTool.getUserId()` 静态方法获取当前登录用户 ID
+- 底层从 `SecurityContextHolder` 中取值，无需传参，任何层都可直接调用
+
+## 分页规范
+
+- 分页入参继承或组合 `PageParam`（位于 common 模块），包含 `pageNum`（默认1）和 `pageSize`（默认10，最大100）
+- 通过 `pageParam.toPage()` 转换为 MyBatis-Plus 的 `Page<T>` 对象
+- 分页出参统一使用 `PageResult<T>`，通过 `PageResult.from(page)` 从 MyBatis-Plus 分页结果构建
+- 带业务筛选条件的分页查询，Param 对象中包含分页参数和筛选字段，放在 `pojo/param/{功能模块}/` 下
+
+## 接口规范
+
+- Controller 只负责参数接收和调用 Server，不写业务逻辑
+- 无需鉴权的接口放在 `/public` 前缀下
+- POST 用 `@PostMapping`，GET 用 `@GetMapping` ...
+- 复杂参数 `@Validated @RequestBody`，简单参数 `@RequestParam`
+- Controller 方法直接返回业务对象，由 `UnifiedResponseBodyAdvice` 自动包装为 `UnifiedResponse`
+
+## 异常处理
+
+- 业务异常统一使用 `throw new BusinessException(BusinessExpCodeEnum.XXX, "描述")` 抛出
+- 简单断言使用 Spring 的 `Assert.hasText()`、`Assert.notNull()` 等
+- 不要 catch 后吞掉异常，交由 `GlobalExceptionAdvice` 统一处理
+
+## Redis 使用规范
+
+- 统一通过 `RedisServerTool` 操作，不直接使用 `RedisTemplate`
+- key 自动拼接应用名前缀：`{appName}:{业务key}`
+- 值统一 JSON 序列化
+- 设置 TTL 时使用 `TimeUnit` 明确单位
+
+## 数据库设计风格
+
+- 表名以 `bg_` 前缀，下划线命名，如 `bg_user`、`bg_route_menu`
+- 主键 `id`，类型 `Long`，策略 `ASSIGN_ID`（雪花算法）
+- 时间字段使用 `Instant` 类型，包含 `createTime` 和 `updateTime`
+- 逻辑删除字段 `isDelete`，类型 `Long`，0=正常，非0=删除（`@TableLogic(value = "0", delval = "new()")`）
+- 状态字段用 `Integer`，0/1 表示，注释中说明含义
+- PO 类加 `@TableName(value = "bg_xxx")`，主键加 `@TableId(type = IdType.ASSIGN_ID)`
+- 查询使用 `LambdaQueryWrapper` 构建条件，避免硬编码字段名
+- 简单的 CRUD 直接使用 MyBatis-Plus 的 `BaseMapper` 方法和 `LambdaQueryWrapper`，只有复杂查询（多表关联、子查询等）才写 Mapper XML SQL
+- Mapper 接口继承 `BaseMapper<T>`
@@ -0,0 +1,167 @@
+# OfferPie Back‑End 项目结构说明
+@zk
+## 1️⃣ 项目整体层次
+```
+offerpie/back-end
+│
+├─ pom.xml                     # 父 Maven 项目，统一管理依赖、插件、属性
+│
+├─ client‑api/                 # **C 端**（面向用户）API 服务
+│   ├─ pom.xml
+│   └─ src/main/java
+│       └─ org.jiayunet
+│           ├─ ClientApplication.java      # Spring Boot 主入口
+│           ├─ annotation/
+│           │   └─ FuncPermission.java     # 功能权限校验注解（标记在Controller方法上）
+│           ├─ aop/
+│           │   └─ FuncPermissionAspect.java  # 功能权限校验切面（拦截注解，校验+扣减+异常回退）
+│           ├─ controller/
+│           │   ├─ LoginController.java    # 登录相关接口（发送验证码、短信登录）
+│           │   └─ RouteMenuController.java # 路由菜单接口（获取用户有效菜单树）
+│           ├─ server/
+│           │   ├─ LoginServer.java        # 登录业务逻辑（验证码校验、自动注册、JWT生成、Cookie设置）
+│           │   ├─ UserRegisterServer.java # 用户注册服务（注册逻辑、邀请码生成与绑定）
+│           │   ├─ FuncPermissionServer.java  # 功能权限服务（校验、扣减、查询、添加库存、回退）
+│           │   ├─ RouteMenuServer.java    # 路由菜单服务（查询、添加库存、获取用户菜单树）
+│           │   └─ WxPayNotifyMessageAbstractImpl.java  # 微信支付回调实现
+│           └─ pojo/
+│               ├─ dto/
+│               │   └─ SmsLoginDto.java    # 短信登录入参（mobileNumber + code + inviteCode）
+│               └─ vo/
+│                   ├─ LoginVo.java        # 登录返回（userId + nick）
+│                   └─ RouteMenuVo.java    # 路由菜单树形VO（含children子菜单）
+│
+├─ common/                     # **共享层**：被 C 端和 B 端共同使用的代码库
+│   ├─ pom.xml
+│   └─ src/main/java
+│       └─ org.jiayunet
+│           ├─ config/                # OSS、Redis、Security、WxPay、Sms 等统一配置
+│           ├─ tool/                  # Http、IP、Redis、认证、验证码等工具类
+│           ├─ interceptor/           # 全局拦截器（日志、TraceId、黑名单、SQL 统计等）
+│           ├─ aop/                   # AOP 日志切面
+│           ├─ exception/             # 业务异常统一处理
+│           ├─ email/                 # 邮件发送抽象（EmailAbility）
+│           ├─ wxPay/                 # 微信支付相关能力（Js、Native、Transfer 等）
+│           ├─ pojo/                  # 公共 POJO（统一响应、登录/防重放 token 等）
+│           └─ web/                   # Spring MVC 全局响应体 advice
+│
+└─ manager/                    # **B 端 + C 端共享** 的业务实现（尚未搭建完整的 B 端 UI）
+    ├─ pom.xml
+    └─ src/main/java
+        └─ org.jiayunet
+            ├─ constant/             # 常量枚举（OSS路径、短信模板等）
+            ├─ controller/           # 对外 REST 接口（HealthCheck、Oss 等）
+            ├─ mapper/               # MyBatis Mapper
+            │   ├─ UserMapper.java
+            │   ├─ OssFileMapper.java
+            │   ├─ UserInviteMapper.java              # 用户邀请记录Mapper
+            │   ├─ RouteMenuMapper.java              # 路由菜单Mapper
+            │   ├─ FuncPermissionMapper.java          # 功能权限Mapper
+            │   ├─ UserRouteMenuStockMapper.java      # 用户路由菜单库存Mapper
+            │   ├─ UserFuncPermissionStockMapper.java # 用户功能权限库存Mapper
+            │   └─ UserFuncUsageLogMapper.java        # 用户功能使用记录Mapper
+            ├─ pojo/
+            │   ├─ po/               # 持久化实体
+            │   │   ├─ User.java
+            │   │   ├─ OssFile.java
+            │   │   ├─ UserInvite.java                # 用户邀请记录表（bg_user_invite）
+            │   │   ├─ RouteMenu.java                # 路由菜单表（bg_route_menu）
+            │   │   ├─ FuncPermission.java            # 功能权限表（bg_func_permission）
+            │   │   ├─ UserRouteMenuStock.java        # 用户路由菜单库存表（bg_user_route_menu_stock）
+            │   │   ├─ UserFuncPermissionStock.java   # 用户功能权限库存表（bg_user_func_permission_stock）
+            │   │   └─ UserFuncUsageLog.java          # 用户功能使用记录表（bg_user_func_usage_log）
+            │   └─ vo/               # ViewObject（OssUrlVo 等）
+            └─ server/               # 业务 Service（OssServer、SmsServer 等）
+```
+> **设计理念** – 业务实体和 Mapper 位于 `manager`，B 端和 C 端共享；C 端特有的注解、切面、权限服务、路由菜单服务位于 `client-api`，避免 B 端误用；`common` 提供统一的技术支撑。
+
+## 2️⃣ 各层模块职责
+| 层级 | 主要职责 | 关键类/包 |
+|------|----------|-----------|
+| **client-api** | - 面向终端用户的 REST API <br> - 启动 Spring Boot 应用 <br> - 短信验证码登录（含自动注册、邀请码绑定） <br> - **功能权限校验**：注解 + 切面 + 权限服务（校验、扣减、回退） <br> - **路由菜单**：获取用户有效菜单树 | `ClientApplication`、`LoginController`、`RouteMenuController`、`FuncPermission`、`FuncPermissionAspect`、`FuncPermissionServer`、`RouteMenuServer`、`UserRegisterServer`、`RouteMenuVo` |
+| **common** | - **统一配置**：OSS、Redis、Security、WxPay、Sms 等 <br> - **跨层工具**：HTTP、IP、认证、验证码、Redis Server 等 <br> - **全局拦截/切面**：日志、TraceId、黑名单、SQL 打印 <br> - **统一异常/响应**：`GlobalExceptionAdvice`、`UnifiedResponse` <br> - **业务抽象**：邮件发送、微信支付（Native/JS/Transfer） <br> - **公共 POJO**：登录令牌、防重放信息等 | `config/`, `tool/`, `interceptor/`, `aop/`, `exception/`, `email/`, `wxPay/`, `pojo/` |
+| **manager** | - **业务实体**（`User`、`OssFile`、`UserInvite`、`RouteMenu`、`FuncPermission`、`UserRouteMenuStock`、`UserFuncPermissionStock`、`UserFuncUsageLog`） <br> - **MyBatis Mapper**（`UserMapper`、`OssFileMapper`、`UserInviteMapper`、`RouteMenuMapper`、`FuncPermissionMapper`、`UserRouteMenuStockMapper`、`UserFuncPermissionStockMapper`、`UserFuncUsageLogMapper`） <br> - **业务 API**：文件上传/下载、健康检查等 <br> - **业务逻辑**：服务层、工具类等 <br> - **既供 B 端 UI（待实现）使用，也供 C 端业务直接调用** | `controller/`, `mapper/`, `pojo/po/`, `pojo/vo/`, `server/`, `constant/` |
+
+## 3️⃣ 关键业务实体
+| 实体 | 所属模块 | 作用概述 |
+|------|----------|----------|
+| `User` | manager | 记录用户基础信息（手机号、邮箱、密码、昵称、微信绑定、邀请码等），配合 `UserMapper` 完成持久化。 |
+| `OssFile` | manager | 描述 OSS（对象存储）中文件的元数据（路径、大小、标签等），通过 `OssFileMapper` 进行增删改查。 |
+| `UserInvite` | manager | 用户邀请记录表，记录邀请人与被邀请人的关系及邀请时间。 |
+| `RouteMenu` | manager | 路由菜单表（bg_route_menu），支持多级树形结构，通过 rootId/parentId 表达层级关系，openAccess 标识是否公开免费。 |
+| `FuncPermission` | manager | 功能权限表（bg_func_permission），定义功能点编码（func_code，最长12字符，唯一约束），daily_free_count 配置每日免费次数。 |
+| `UserRouteMenuStock` | manager | 用户路由菜单库存表（bg_user_route_menu_stock），记录用户拥有的菜单权限，支持时间维度。 |
+| `UserFuncPermissionStock` | manager | 用户功能权限库存表（bg_user_func_permission_stock），记录用户拥有的功能权限，支持时间/次数/复合维度。 |
+| `UserFuncUsageLog` | manager | 用户功能使用记录表（bg_user_func_usage_log），记录每次功能使用，用于免费次数统计和异常回退。 |
+| `RouteMenuVo` | client-api | 路由菜单树形VO，包含 children 子菜单列表，供前端渲染动态路由。 |
+| `LoginVo` | client-api | 登录成功后返回的用户信息（userId、nick）。 |
+| `SmsLoginDto` | client-api | 短信验证码登录的请求参数（mobileNumber、code、inviteCode）。 |
+
+## 4️⃣ 权限体系设计
+### 整体架构
+- **前端**：路由控制菜单/页面可见性，登录后拉取用户有效菜单树（含公开免费菜单 + 库存授权菜单）
+- **后端**：AOP 切面拦截 `@FuncPermission` 注解，校验权限 + 扣减库存，业务异常自动回退次数
+- **权限来源**：商品模块下单成功后写入库存表，权限框架不关心来源
+
+### 数据库表（5张）
+| 表名 | 说明 |
+|------|------|
+| `bg_route_menu` | 路由菜单定义（树形结构，open_access 标识公开免费菜单） |
+| `bg_user_route_menu_stock` | 用户路由菜单库存（时间维度） |
+| `bg_func_permission` | 功能权限定义（func_code 唯一，daily_free_count 配置每日免费次数） |
+| `bg_user_func_permission_stock` | 用户功能权限库存（时间/次数/复合维度） |
+| `bg_user_func_usage_log` | 用户功能使用记录（每次使用插入，用于免费次数统计和异常回退） |
+
+### 库存维度
+- `time_limit` + `expire_time`：时间维度，0=不限时，1=限时
+- `count_limit` + `remain_count`：次数维度，0=不限次，1=限次
+- 两个维度独立控制，组合形成四种模式：永久不限次、限时不限次、永久限次、限时限次
+- 添加库存时不降级：已经不限时/不限次的不会被覆盖
+
+### 切面校验流程
+1. 拿注解上的 funcCode + 当前登录用户 userId
+2. 查 bg_func_permission（funcCode + status=1），拿到 dailyFreeCount
+3. dailyFreeCount > 0 → COUNT 今日使用记录，未超额 → 插入使用记录，放行
+4. 免费额度用完或无免费额度 → 查付费库存表（userId + funcCode）
+5. 无记录 → 无权限
+6. time_limit=1 且过期 → 已过期
+7. count_limit=0 → 插入使用记录，放行
+8. count_limit=1 → SQL 原子扣减 `remain_count = remain_count - 1`（WHERE remain_count > 0）→ 插入使用记录，放行
+9. 业务方法异常 → 删除使用记录 + 尝试回退库存次数（count_limit=1 时 remain_count + 1）
+
+## 5️⃣ 共享技术栈（位于 `common`）
+| 类别 | 关键实现 | 位置 |
+|------|----------|------|
+| **配置** | `OssConfig`, `RedissonConf`, `SecurityConfig`, `WxPayConfig`, `SmsConfig` | `common/config` |
+| **安全** | JWT 过滤器、登录令牌 (`RedisLoginTokenInfo`)、防重放 (`RedisPreventReplayInfo`) | `common/interceptor`、`common/pojo/interceptor` |
+| **邮件** | `EmailAbility`（封装邮件发送） | `common/email` |
+| **微信支付** | `WxJsPayAbility`, `WxNativePayAbility`, `WxTransferPayAbility`, `WxPayNotifyController` | `common/wxPay` |
+| **全局异常** | `GlobalExceptionAdvice`, `BusinessException`, `BusinessExpCodeEnum` | `common/exception` |
+| **日志 & AOP** | `ControllerLogAspect`, `LoggingOriginalRequestFilter`, `SqlLoggerInterceptor` | `common/aop`, `common/interceptor` |
+| **工具类** | `HttpTool`, `HttpIpTool`, `AuthenticTool`, `ObjectTool`, `VerifyImageCodeUtils` | `common/tool` |
+| **统一返回体** | `UnifiedResponse`, `UnifiedResponseBodyAdvice` | `common/pojo`, `common/web` |
+| **批量/更新** | `UpdateBatchMethod`（批量更新策略） | `common/config` |
+
+## 6️⃣ 构建与运行
+- **父 POM**（`back-end/pom.xml`）统一管理子模块的依赖与插件。
+- 子模块 (`client-api`, `common`, `manager`) 均可单独 `mvn clean install`，生成各自的 jar 包。
+- **启动入口**：运行 `client-api` 中的 `ClientApplication`，Spring Boot 会自动扫描并加载 `common`（配置、拦截、工具）以及 `manager` 中声明的 Mapper 与 Service。
+
+## 7️⃣ 小结
+- 项目采用 **三层结构**：
+  1. **client-api** → C 端 REST 接口 + 功能权限校验（注解/切面/服务） + 路由菜单服务 + 用户注册与邀请。
+  2. **manager** → 业务实体、Mapper 与业务 API，B 端 + C 端共享层。
+  3. **common** → 所有层共同依赖的底层设施（配置、工具、拦截、异常、支付、邮件等）。
+- 权限体系分两层：前端路由控制菜单可见性，后端切面控制功能点权限与库存扣减。
+- 权限和菜单作为商品维度，框架只负责校验和库存管理，不关心权限来源。
+
+## 4.5️⃣ 邀请模块设计
+### 数据库表（1张）
+| 表名 | 说明 |
+|------|------|
+| `bg_user_invite` | 用户邀请记录（记录邀请人与被邀请人的关系及邀请时间） |
+
+### 核心逻辑
+- 用户注册时自动生成10位邀请码（大写字母+数字），存入 `User.invite_code`，碰撞检查最多重试3次
+- 注册时可携带 `inviteCode`，有效则写入邀请记录，无效仅日志警告不阻断注册
+- 注册逻辑由 `UserRegisterServer` 独立承担，`LoginServer` 委托调用