@jspg-ai/coding-bb 0.0.1

package/cbb/dev-standards/skills/coding-specs/SKILL.md

@@ -0,0 +1,376 @@
+---
+name: coding-specs
+description: "Java 后端编码规范。方案设计、编码实现、Code Review 三个阶段均须参照——涵盖 OpenSpec propose/apply/verify、Superpowers 头脑风暴/writing-plans/executing-plans/requesting-code-review/receiving-code-review、编写技术方案或详细设计、直接编码、直接代码审查。内容包括 API 设计（REST/RPC）、模型分层与转换（DTO/Entity/PO）、异常处理与错误码、日志规范、MySQL 编码与事务、二方三方调用、安全红线，以及并发控制、消息与缓存一致性、幂等设计、ES 查询、定时任务、单元测试等进阶规范。仅限 Java 后端场景，不适用于前端、Python 或纯文档编辑。"
+---
+
+# 编码规范
+
+提供 Java 后端开发的完整规范指南。
+
+核心编码规范（API、模型、代码风格、错误处理、日志、性能、安全红线）在本文件中。各领域的进阶规范按需加载，参见文末路由表。
+
+## 规范内容
+
+### API 设计规范
+
+#### 响应结构
+
+所有 REST API 返回统一响应结构 `Result<T>`：
+
+```java
+Result.success(data)         // 业务成功，HTTP 200
+Result.fail(errorCode, msg)  // 业务失败，HTTP 200
+Result.fail("SYSTEM_ERROR", "系统繁忙")  // 系统异常，HTTP 200
+```
+
+#### 分页
+
+- 使用 `Result<PageView<T>>` 统一分页结构，`PageView` 来自 commons-api
+- page 从 0 开始，页大小变量为 `size`，默认 size=20，最大 100
+
+#### 接口设计
+
+- 1 个 API 接口对应 1 个功能，不出现一对多或多对一
+- 同一组 API 接口命名一致，同一概念不混用不同名称（如 fee 和 amount）
+- 接口命名基于目标，不包含策略与细节：
+
+```java
+// 正例
+Result<T> queryNewestGuaranteePackage(QueryGuaranteePackageRequest request);
+
+// 反例
+Result<T> queryNewestGuaranteePackageContainAllStatus(QueryGuaranteePackageRequest request);
+```
+
+- API 方法名应和具体暴露协议无关：
+
+```java
+// 反例
+getCargoRPC(Long id)
+getCargoRest(Long id)
+```
+
+- REST 和 API 禁止直接抛异常，统一拦截封装成错误码
+
+#### 参数规范
+
+- 参数超过 3 个使用包装类型封装，不允许无业务含义的 Map 作为入参
+- 参数和返回值使用包装类型，不能使用原生类型
+- 必填字段使用 Validation-api 校验：
+
+```java
+public interface UserFacade {
+    Result<String> save(@Valid UserRequest user);
+}
+
+@Data
+public class UserRequest implements Serializable {
+    @NotEmpty(message = "姓名不能为空")
+    private String name;
+
+    @Min(18)
+    private Integer age;
+}
+```
+
+- 常识类属性校验规则：
+
+| 字段类型 | 校验规则 |
+|---------|----------|
+| 金额 | 非负数 |
+| 数量 | 非负数 |
+| 车长 | 非负数，有最大值 |
+| 里程 | 非负数 |
+| 经纬度 | 纬度 -90~90，经度 -180~180 |
+| 邮箱 | 格式校验 |
+| 手机号 | 格式校验 |
+
+#### 返回值
+
+- 禁止返回 null，使用 YmmResult 或 Result 统一包装
+- 返回集合时不返回 null，返回空集合
+
+#### 错误码设计
+
+- 格式：`模块前缀_数字`（如 `ORDER_40001`、`CARGO_50002`）
+- 每个模块维护独立的编号段，避免跨模块冲突
+- 错误码统一在枚举类或常量类中定义，禁止在业务代码中硬编码字符串
+
+```java
+// 正例：枚举类集中管理
+public enum OrderErrorCode {
+    ORDER_NOT_FOUND("ORDER_40001", "订单不存在"),
+    ORDER_STATUS_INVALID("ORDER_40002", "订单状态不允许此操作");
+
+    private final String code;
+    private final String message;
+}
+
+// 反例：硬编码
+Result.fail("ORDER_40001", "订单不存在");
+```
+
+#### 接口管理
+
+- REST 和 API 接口统一接入 FTAPI，支持自动上报、自动更新
+- C 端批量接口单次返回数据量 <= 200
+
+#### 命名规则
+
+方法名使用动词+名词格式：
+
+| 动词 | 含义 |
+|------|------|
+| create | 创建、新建 |
+| update | 修改 |
+| get | 获取单个对象 |
+| query | 获取多个对象 |
+| delete | 删除 |
+
+查询接口入参是单个类型（非主键 ID）时使用 `ByXxx` 后缀。复杂查询使用 `QueryCondition` 封装。
+
+### 错误处理规范
+
+#### 异常处理
+
+- try-catch 范围尽可能小，不嵌套 try-catch
+- 后端内部业务代码不能声明 `Throwable`，避免吞掉虚拟机 Error
+- 尽可能对异常分类处理，稳定代码不放入 try 块
+
+#### 禁止事项
+
+- 不用异常处理代替逻辑校验（异常处理效率远低于条件判断）
+- 事务场景不能吞掉异常，避免事务回滚机制失效
+- finally 块中禁止使用 return（会覆盖 try 块中的 return）
+
+### 模型设计规范
+
+#### 字段命名一致性
+
+相同语义字段在不同表中的命名和类型必须一致（主键与外键可不同）。
+
+#### 金额字段
+
+| 场景 | 类型 | 精度 |
+|------|------|------|
+| 交易业务 | long（分为单位） | 整数分 |
+| 金融类应用 | decimal | 确保小数位不丢失精度 |
+
+#### 模型字段类型
+
+对外交互模型（DTO、Entity、VO、DO、Request、Response）的字段：
+- 不能使用基础类型（boolean、int、long、byte、char、short、float、double）
+- 不能给字段设置默认值
+- 防止 NULL 值被覆盖
+
+#### 枚举
+
+- API 返回值中不允许使用枚举类型，使用 Integer 并添加 `@see` 注释：
+
+```java
+/**
+ * 货源状态:初始化、待上架、已上架、已下架
+ * @see CargoStatusEnum
+ */
+private Integer cargoStatus;
+```
+
+#### 模型设计
+
+- 复杂业务场景建立核心模型 + 扩展模型体系，扩展字段不过度侵入核心模型
+- 非极端高性能场景不建议冗余字段；有数据快照需求时可以冗余
+- 冗余字段选择：不是频繁修改的字段、不是唯一索引的字段、不是 varchar 超长或 text 字段
+- 配置类复杂结构数据建议独立字段存储，无须符合第一范式
+- 模型分层嵌套不超过 3 层，超过 3 层在上层提供简易获取方法
+
+#### 模型分层与转换
+
+各层模型职责：
+
+| 模型 | 所在模块 | 职责 |
+|------|---------|------|
+| Request / Response | xxx-api | RPC/REST 接口入参出参 |
+| DTO | xxx-api | 服务间传输对象 |
+| Entity / DO | xxx-service | 业务领域模型 |
+| PO | xxx-service | 持久化对象（对应数据库表） |
+
+转换规则：
+- 使用 MapStruct 进行对象映射，禁止手写大量 get/set 转换
+- 跨层必须转换，不能将 PO 直接暴露给 API 层，也不能将 Request 直接传到 DAO 层
+- 同层内字段结构相同时可以共用模型，但跨层必须用独立类型
+
+```java
+@Mapper(componentModel = "spring")
+public interface OrderConverter {
+    OrderDTO toDTO(OrderEntity entity);
+    OrderEntity toEntity(CreateOrderRequest request);
+    List<OrderDTO> toDTOList(List<OrderEntity> entities);
+}
+```
+
+### 代码风格规范
+
+#### 命名规范
+
+- 工程内接口和实现命名统一配对：`IxxxService` + `xxxService` 或 `xxxService` + `xxxServiceImpl`
+- 禁止望文不知义的缩写（反例：`AbsClass`）
+
+#### 领域术语
+
+**用户域：**
+
+| 中文 | 英文 |
+|------|------|
+| 账户 | account |
+| 货主 | shipper |
+| 司机 | driver |
+| 手机号 | mobile |
+| 车辆 | vehicle |
+| 车队 | fleet |
+
+**货源域：**
+
+| 中文 | 英文 |
+|------|------|
+| 货源 | cargo |
+| 草稿货源 | draftCargo |
+| 上架/下架 | putOn / putOff |
+| 父货源 | parentCargo |
+| 一口价 | buyout |
+| 车型/车长 | vehicleType / vehicleLength |
+| 备注 | remark |
+
+**订单域：**
+
+| 中文 | 英文 |
+|------|------|
+| 订单/运单 | order / waybill |
+| 装货/卸货 | load / unload |
+| 协议 | contract |
+| 回单 | receipt |
+| 履约凭证 | proof |
+
+**费用支付域：**
+
+| 中文 | 英文 |
+|------|------|
+| 支付/退款 | pay / refund |
+| 结算/代扣 | settle / deduct |
+| 应付/应收 | payable / receivable |
+| 实收/实付 | received / paid |
+| 运费/佣金 | freight / commission |
+| 发票 | invoice |
+
+### 日志规范
+
+#### 框架选择
+
+使用 SLF4J + Log4j2，禁止直接使用 Log4j 或 Logback API。
+
+#### 日志占位符
+
+使用 `{}` 占位符，禁止字符串拼接。
+
+#### 日志级别
+
+- trace/debug 级别日志必须先判断级别
+- 异常日志使用 `logger.error("desc {}", context, e)`，禁止 `e.printStackTrace()`
+
+#### 日志输出时机
+
+- REST/RPC 调用无需自行打印出入参数，微服务已自动打印
+- 读链路非必要不打日志
+- 写链路方法需要打印出入参数
+
+### 性能优化规范
+
+#### 二方、三方调用管理
+
+- 二方、三方调用必须通过防腐层（Repo），面向失败编程，考虑网络抖动、服务劣化等异常
+- 所有二方、三方调用必须明确设置超时时间
+- 三方调用发生错误时，对错误响应编码分类打点，必须打印日志
+
+#### IO 优化
+
+- 禁止在循环内执行非必要 IO 操作
+- 可以批量调用的不循环调用
+- 业务代码中禁止使用 DELETE/TRUNCATE/DROP 操作数据库，统一使用逻辑删除（deleted 字段）
+
+### MySQL 编码规范
+
+#### SQL 编写
+
+- 禁止在循环中执行 SQL
+- 禁止 `SELECT *`，明确列出字段
+- 多表关联时列名加表名/表别名限定
+- 使用 `count(*)` 统计行数
+- `WHERE` 条件避免在索引字段上使用函数和隐式类型转换
+- 分页查询必须有索引覆盖排序字段
+- 大表深度分页（偏移量 > 1000）使用游标分页或子查询优化
+- 单次查询数据量不超过 1000 条
+
+#### 事务控制
+
+- 事务必须在 Service 层控制，禁止在 DAO 层
+- 事务尽可能短小，禁止在事务中调用 RPC 或外部服务；如需调用，先提交事务再调用
+- 默认读从库，延时敏感场景主动设置读主库
+
+#### 删除操作
+
+- 应用程序使用逻辑删除（deleted 字段），禁止在业务代码中使用物理删除
+
+### 安全红线规范
+
+#### SQL 注入防护
+
+- 必须使用 `#{}` 占位符，禁止 `${}` 拼接用户输入（详见 `/mysql-design-specs`）
+- 排序字段、表名等无法使用占位符的场景，必须通过白名单校验
+
+#### 敏感数据处理
+
+- 密码、密钥等凭据禁止明文存储，使用 Thaad 加密
+- 手机号、身份证号等 PII 字段在日志中脱敏打印（如 `138****1234`）
+- 禁止在 URL 参数中传递敏感信息（token、密码等），使用 Header 或 POST body
+- 禁止将敏感信息写入异常消息或返回给前端
+
+## 进阶规范
+
+根据当前任务场景，按需读取对应的进阶规范文件：
+
+| 场景 | 规范文件 |
+|------|---------|
+| 多线程、线程池、锁、ThreadLocal | [references/concurrency.md](references/concurrency.md) |
+| 消息一致性、缓存一致性、事务、幂等 | [references/distributed.md](references/distributed.md) |
+| 输入输出转义、文件上传校验、风控 | [references/security.md](references/security.md) |
+| 编写或审查单元测试 | [references/unit-testing.md](references/unit-testing.md) |
+| Lion 配置读取、注解使用 | [references/config-center.md](references/config-center.md) |
+| 定时任务设计、数据备份、分片 | [references/scheduled-task.md](references/scheduled-task.md) |
+| ES 增删改查、分页、bulk 操作 | [references/es-coding.md](references/es-coding.md) |
+
+## 检查清单
+
+根据当前任务场景，只检查对应分组的项。不需要每次全量检查。
+
+**写接口 / 定义模型时检查：**
+- [ ] API 是否使用统一响应结构（Result<T>）
+- [ ] 分页参数是否合理（page 从 0 开始，size 默认 20 最大 100）
+- [ ] 接口命名是否符合动词+名词格式，与协议无关
+- [ ] 参数是否使用包装类型封装，必填字段是否有 Validation 校验
+- [ ] 错误码是否在枚举类中集中定义，格式是否为 模块前缀_数字
+- [ ] 模型字段是否使用包装类型，金额字段类型是否正确（交易用 long 分，金融用 decimal）
+- [ ] 跨层模型是否使用 MapStruct 转换，PO 是否暴露到 API 层
+- [ ] 领域术语是否使用规范英文（cargo/order/freight 等）
+
+**写业务逻辑时检查：**
+- [ ] 异常处理是否分类处理，try-catch 范围是否最小
+- [ ] 日志是否使用 SLF4J + {} 占位符，写链路是否打印出入参
+- [ ] 二方三方调用是否通过防腐层、是否设置超时
+- [ ] 敏感数据是否脱敏，SQL 是否使用 #{} 占位符
+
+**涉及数据库操作时检查：**
+- [ ] SQL 是否禁止 SELECT * 和循环执行，事务是否在 Service 层控制
+
+**涉及并发/分布式场景时检查：**
+- [ ] 并发控制是否合理（锁策略、线程池参数、ThreadLocal 清理）
+- [ ] 幂等性是否保证（唯一约束、MQ 消费幂等）
+

package/cbb/dev-standards/skills/coding-specs/references/concurrency.md

@@ -0,0 +1,53 @@
+# 并发控制规范
+
+多线程、线程池、锁、ThreadLocal 等并发场景的编码规范。
+
+## 共享资源识别
+
+多线程并发场景关注：单例对象、静态对象、共享内存、计数器、文件/数据库操作、线程池、缓存、网络资源、全局状态。
+
+## 锁策略选择
+
+| 场景 | 策略 |
+|------|------|
+| 高并发写、数据竞争激烈 | 悲观锁 |
+| 读多写少 | 乐观锁 |
+
+## 死锁预防
+
+- 批量加锁严格控制顺序
+- MySQL 事务内批量更新严格控制记录执行顺序
+- 分布式锁必须设置过期时间
+- 悲观锁必须使用可重入锁
+
+## 线程池
+
+创建线程池必须明确指定：核心线程数、最大线程数、等待队列长度、拒绝策略。
+
+线程命名格式：`业务含义-` 前缀
+
+```java
+threadPoolTaskExecutor.setThreadNamePrefix("asyncMetricThread-");
+```
+
+**队列选择：**
+- 稳定流量：同步队列或较大核心线程数
+- 高低峰不均：阻塞队列，长度为线程数 3~5 倍
+- 禁止使用无界队列
+
+## 分布式锁
+
+使用 `ironman-lock`，支持 Redis（CP）和 Zookeeper（AP）实现。
+
+## 原子变量
+
+优先使用 AtomicXxx，避免 volatile（volatile 只保证可见性不保证原子性）。
+
+## 双重检查锁
+
+延迟初始化必须使用 volatile + 临时变量确保对象完整构建后再赋值。
+
+## ThreadLocal
+
+- 能通过参数传递就不要通过 ThreadLocal
+- 必须使用 ThreadLocal 时，使用完毕后在 finally 中 remove

package/cbb/dev-standards/skills/coding-specs/references/config-center.md

@@ -0,0 +1,16 @@
+# 配置中心规范
+
+Lion 配置读取、注解使用等配置中心场景的编码规范。
+
+## 基本规则
+
+- 配置值大小不超过 600KB
+- Lion 配置对象全局唯一且只读，写操作必须先深拷贝
+- Lion 配置的类型必须和代码声明类型一致，避免反序列化问题
+- 固定结构的配置优先使用 JSON，不使用通用 String
+
+## 注解使用
+
+- Lion 注解注入的属性不应该设置为 `static`，不能使用 `final` 修饰
+- `@Value` 注解不感知实时变更，只获取第一次的配置值
+- BeanPostProcessor 之前的阶段，不能使用 Lion 注解，应使用 `ConfigCache.getInstance().getProperty()` 获取（注意此方式也不感知实时变更）

package/cbb/dev-standards/skills/coding-specs/references/distributed.md

@@ -0,0 +1,42 @@
+# 分布式规范
+
+消息一致性、缓存一致性、事务、幂等等分布式场景的编码规范。
+
+## 消息一致性
+
+**最终一致性消息：**
+- Producer 必须有补偿策略，确保消息不丢失
+- 领域事件发送：先持久化事件 → 发送 → 成功后更新状态 → 失败用 Job 补偿
+
+**强一致性消息：**
+- 必须使用 IronMan 的事务消息能力
+
+## 缓存一致性
+
+**读时更新缓存（高并发读场景）：**
+- 写链路使用延迟双删：删除缓存 → 更新数据库 → 延迟删除缓存
+- 延迟时间与读链路 RT 相关
+
+**写时更新缓存：**
+- 使用最新数据写入，避免 ABA 问题
+- 缓存写入失败需要补偿
+
+## 事务
+
+- 同一数据库多张表的写操作必须使用数据库事务
+
+## 幂等
+
+**资源创建幂等：**
+- 必须定义唯一标识字段，相同请求只做一次处理，返回结果一致
+
+**数据库唯一约束：**
+- 使用数据库唯一性约束防止重复插入
+- 逻辑删除场景，唯一索引需添加 `deleted_id` 字段，格式：`(A, B, deleted_id)`
+
+**MQ 消费幂等：**
+- Consumer 必须支持幂等，先检查是否已处理，使用消息 ID 或业务唯一键判断
+
+## 线程安全
+
+线上核心业务流程禁止使用 `Thread.sleep()`。

package/cbb/dev-standards/skills/coding-specs/references/es-coding.md

@@ -0,0 +1,60 @@
+# ES 查询规范
+
+- from/size 分页最大支持 10000 条，超过使用 `search_after`
+- 禁止用 scroll 代替普通查询，scroll 仅用于数据导出
+- 查询必须设置 timeout
+- 精确匹配使用 filter（不计算评分，可利用缓存）
+- 全文搜索使用 query（计算相关性评分）
+
+## Filter vs Query
+
+精确匹配用 filter：
+
+```json
+{
+  "query": {
+    "bool": {
+      "filter": [
+        { "term": { "cargo_status": 1 } },
+        { "range": { "create_time": { "gte": "2026-01-01", "lte": "2026-03-31" } } }
+      ]
+    }
+  },
+  "timeout": "3s"
+}
+```
+
+全文搜索用 query + filter 组合：
+
+```json
+{
+  "query": {
+    "bool": {
+      "must": [
+        { "match": { "company_name": "Acme Logistics" } }
+      ],
+      "filter": [
+        { "term": { "cargo_status": 1 } }
+      ]
+    }
+  },
+  "timeout": "3s"
+}
+```
+
+## Bulk 批量操作
+
+使用 bulk 批量写入，bulk size 在 5~15MB 之间：
+
+```json
+{"index": {"_index": "cargo_info", "_id": "1001"}}
+{"id": 1001, "order_no": "ORD202601001", "cargo_status": 1}
+{"update": {"_index": "cargo_info", "_id": "1002"}}
+{"doc": {"cargo_status": 2}}
+```
+
+批量导入场景可临时调大 `refresh_interval` 提升写入性能。
+
+## 连接管理
+
+应用程序退出时必须调用 `restClient.close()` 关闭连接。

package/cbb/dev-standards/skills/coding-specs/references/scheduled-task.md

@@ -0,0 +1,25 @@
+# 定时任务规范
+
+定时任务设计、数据备份、分片等场景的编码规范。
+
+## 数据安全
+
+- 执行刷数任务前必须记录原始数据，支持出问题时恢复
+- 备份方案可选：备份表、增量数据分层、记录日志
+
+## 任务设计
+
+- 任务进度必须可观察、可持久化
+- 任务中断后重新执行，已处理过的数据可跳过，支持从断点继续
+- 无顺序依赖的任务，单条数据失败不阻塞整个任务，记录失败数据，支持失败部分重新处理
+- 定时任务必须幂等，多次执行不会产生重复数据或操作，使用唯一标识或状态检查控制
+- 多个任务的触发时间应分布在不同时段，平衡系统负载
+
+## 数据量控制
+
+- 任务处理数据量 > 10 万时，必须支持分片，考虑内存限制、CPU/IO 资源、实时性要求、并行处理能力
+- 每批查询数据量 <= 1000，分批方式可选：分页、ID 范围、时间范围、消息队列
+
+## 异常告警
+
+任务处理失败或超时必须监控和告警，及时修复数据。

package/cbb/dev-standards/skills/coding-specs/references/security.md

@@ -0,0 +1,11 @@
+# 安全规范
+
+输入输出安全、文件上传、风控等安全场景的编码规范。
+
+> SQL 注入防护和敏感数据处理属于基础安全红线，已在主规范 SKILL.md 中定义，本文件不再重复。
+
+## 输入输出安全
+
+- 用户输入输出必须进行转义或安全过滤
+- 上传文件必须进行类型校验和大小校验
+- 用户自定义文本内容（名称、备注等）必须接入风控校验

package/cbb/dev-standards/skills/coding-specs/references/unit-testing.md

@@ -0,0 +1,43 @@
+# 单元测试规范
+
+编写和审查单元测试时的编码规范。
+
+## 基本原则
+
+- 每个测试必须独立运行，测试之间不能有依赖关系
+- 测试方法名清晰描述测试目的或行为，示例：`shouldThrowNotFoundException()`
+- 每个测试必须包含断言，只有打印输出无法验证通过
+- 一个单测只测一个功能，尽可能小而快
+
+## 测试结构
+
+遵循 Arrange-Act-Assert 模式：
+
+```java
+@Test
+public void shouldReturnOrderWhenOrderExists() {
+    // Arrange
+    Order order = new Order();
+    order.setId(1L);
+    when(orderMapper.selectById(1L)).thenReturn(order);
+
+    // Act
+    Result<Order> result = orderService.getOrder(1L);
+
+    // Assert
+    assertTrue(result.isSuccess());
+    assertEquals(1L, result.getData().getId());
+}
+```
+
+## Mock 使用
+
+- 使用 JUnit + Mockito，外部资源（RPC、数据库、Redis、MQ）通过 Mock 隔离
+- 只 Mock 外部依赖，不 Mock 被测方法所在类的内部方法
+- Mock 返回值要覆盖正常、异常、边界场景
+
+## 测试范围
+
+- Service 层核心业务逻辑必须有单测覆盖
+- 简单的 CRUD 和纯委托调用不需要单测
+- 重点关注：分支逻辑、异常路径、边界值、幂等逻辑