|
|
@@ -326,9 +326,36 @@ haha-sdk（独立模块，不依赖其他内部模块）
|
|
|
## 九、开发规范要点
|
|
|
|
|
|
1. **Long类型序列化**：所有 Long 类型 ID 和外键字段必须添加 `@JsonSerialize(using = ToStringSerializer.class)` 防精度丢失
|
|
|
+ - **原因**：JavaScript 的 Number 类型最大安全整数为 2^53-1，超过则精度丢失。雪花算法生成的ID约19位数字，远超此限制
|
|
|
+ - **影响**：不添加此注解，前端接收到的ID末尾会被截断为0，导致根据ID查询/更新失败
|
|
|
2. **日期格式**：`@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "Asia/Shanghai")`
|
|
|
3. **金额字段**：必须使用 `BigDecimal`，禁止 `double` / `float`
|
|
|
+ - **原因**：浮点数在计算机中无法精确表示十进制小数，如 0.1 + 0.2 != 0.3
|
|
|
+ - **运算**：使用 `setScale(2, RoundingMode.HALF_UP)` 保留2位小数
|
|
|
4. **依赖注入**：构造器注入（`final` + `@RequiredArgsConstructor`），循环依赖时用 `@Autowired @Lazy`
|
|
|
5. **事务**：写操作必须 `@Transactional(rollbackFor = Exception.class)`
|
|
|
+ - **注意**：`rollbackFor = Exception.class` 不能省略，默认只回滚 RuntimeException
|
|
|
6. **分页校验**：`page < 1` 设为 1，`pageSize > 100` 设为 10
|
|
|
7. **业务异常**：使用 `BusinessException` + `ResponseEnum`，禁止 Controller 中抛出未处理异常
|
|
|
+8. **雪花算法ID注意**：手写SQL中的逻辑删除条件不会自动添加，需手动加 `WHERE deleted = 0`
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 十、关键设计决策记录
|
|
|
+
|
|
|
+### 10.1 为什么用雪花算法而非自增ID？
|
|
|
+
|
|
|
+系统需要与哈哈平台（设备端）交互，设备端生成 `activityId` 关联开关门和订单。自增ID依赖数据库生成，在分布式场景和回调场景下不可用。雪花算法在应用层生成ID，不依赖数据库，且全局唯一。
|
|
|
+
|
|
|
+**迁移注意**：项目早期使用自增ID，后改为雪花算法。已有数据需保留原ID，新数据使用雪花算法。`alter_snowflake_id.sql` 处理了迁移逻辑。
|
|
|
+
|
|
|
+### 10.2 为什么 haha-sdk 是独立模块？
|
|
|
+
|
|
|
+`haha-sdk` 封装与哈哈平台的HTTP交互，不依赖任何内部业务模块。这样设计是因为：
|
|
|
+- SDK可独立发布给第三方使用
|
|
|
+- 避免循环依赖（如果SDK依赖service，service又调用SDK）
|
|
|
+- SDK的更新不影响业务模块的编译
|
|
|
+
|
|
|
+### 10.3 MyBatis-Plus 逻辑删除的特殊处理
|
|
|
+
|
|
|
+MyBatis-Plus 的 `@TableLogic` 注解在 MP 自动生成的 SQL 中会自动添加 `WHERE deleted = 0`，但**手写SQL（XML或注解式）不会自动添加**。开发手写SQL时必须手动处理逻辑删除条件，否则会查询到已删除的数据。
|
skyline