@specpow/framework 0.8.2 → 0.8.3

package/builtin/schemas/mes-prd-to-code/comment-rules.md

@@ -0,0 +1,75 @@
+# Java 代码注释规范
+
+> 本文件定义 MES 项目 Java 代码的注释规范，在代码生成阶段由 AI 读取并遵循。
+
+## 类级别注释
+
+- 所有类（Entity、Controller、Service、ServiceImpl、Mapper、测试类等）必须使用 JavaDoc 格式注释
+- 必须包含：功能描述、@author、@date
+- 格式：
+  ```java
+  /**
+   * 物料主数据实体类
+   *
+   * @author AI-Generated
+   * @date 2025-01-01
+   */
+  ```
+
+## 方法级别注释
+
+- 公共方法（public）必须使用 JavaDoc 格式，包含功能描述、@param、@return、@throws（如有）
+- 私有方法（private）使用行内 `//` 注释说明意图
+- 接口方法必须写 JavaDoc（作为契约文档）
+- 重写方法（@Override）如果父类已有 JavaDoc，可用 `//` 补充差异说明
+- 格式：
+  ```java
+  /**
+   * 分页查询物料列表
+   *
+   * @param page 分页参数
+   * @param entity 查询条件
+   * @return 分页结果
+   */
+  IPage<MmMaterial> pageSearch(Page<MmMaterial> page, @Param("entity") MmMaterial entity);
+  ```
+
+## 字段级别注释
+
+- Entity 业务字段使用 `//` 行内注释标注业务含义（与 @ExcelProperty 配合）
+- 常量（static final）使用 JavaDoc 格式
+- 集合字段注释说明子表含义
+- 字段注释必须写在字段上方独立一行，禁止写在行尾
+- 格式：
+  ```java
+  // 物料编码，唯一标识
+  @ExcelProperty("物料编码")
+  private String materialCode;
+
+  /** 批次大小，默认 500 */
+  public static final int DEFAULT_BATCH_SIZE = 500;
+  ```
+
+## 行内注释
+
+- 复杂业务逻辑必须添加行内注释说明意图
+- Service 层校验逻辑必须注释说明校验规则
+- 行内注释必须写在代码上方独立一行，禁止写在行尾
+- 禁止无意义注释（如 `// 设置名称` 紧跟 `entity.setName()`）
+- 格式：
+  ```java
+  // 校验物料编码唯一性（按组织维度）
+  LambdaQueryWrapper<MmMaterial> wrapper = new LambdaQueryWrapper<>();
+  wrapper.eq(MmMaterial::getMaterialCode, code);
+
+  // 批量查询后内存处理，避免 N+1
+  List<MmMaterial> existing = this.list(wrapper);
+  ```
+
+## 特殊场景
+
+- Controller 方法：简要 JavaDoc 说明接口用途，参数说明可省略（框架自动解析）
+- Service 事务方法：JavaDoc 说明业务逻辑和异常场景
+- 测试方法：JavaDoc 或 @DisplayName 说明测试场景，无需 @param/@return
+- Mapper XML：`<!-- 注释 -->` 说明 SQL 片段用途
+- 枚举类：每个枚举值使用 `//` 注释说明含义

package/builtin/schemas/mes-prd-to-code/schema.yaml

@@ -195,6 +195,8 @@ artifacts:
     instruction: |
       基于解析报告和确认结果，生成完整的技术设计文档。
 
+      生成代码模板前请先读取本 schema 目录下的 comment-rules.md，遵循其中的 Java 注释规范（类/方法/字段/行内注释格式）。
+
       ## 文档结构
 
       ### 1. 数据库设计
@@ -329,6 +331,8 @@ artifacts:
     instruction: |
       基于技术设计文档，拆分为可执行的实施任务列表。
 
+      生成代码前请先读取本 schema 目录下的 comment-rules.md，遵循其中的 Java 注释规范（类/方法/字段/行内注释格式）。
+
       ## 任务拆分原则
       1. 每个任务足够小（2-5 分钟完成）
       2. 包含精确的文件路径（匹配 MES 项目包结构）
@@ -393,6 +397,7 @@ artifacts:
       基于 tasks.md 中的 ServiceImpl 代码，生成对应的单元测试。
 
       生成前请先读取本 schema 目录下的 references.md，了解可用的公共工具类和方法，测试中 Mock 的依赖方法签名需与 references.md 一致。
+      生成代码前请先读取本 schema 目录下的 comment-rules.md，遵循其中的 Java 注释规范（类/方法/字段/行内注释格式）。
 
       ## 测试规范
       - 测试类名 = 原类名 + MockTest（如 PcCadDataServiceImpl → PcCadDataServiceImplMockTest）
@@ -429,6 +434,7 @@ artifacts:
       按任务清单逐个生成代码文件。
 
       生成前请先读取本 schema 目录下的 references.md，了解可用的公共工具类和方法，优先复用已有方法，避免重复实现。
+      生成代码前请先读取本 schema 目录下的 comment-rules.md，遵循其中的 Java 注释规范（类/方法/字段/行内注释格式）。
 
       ## 执行方式
       1. 按任务依赖顺序执行

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specpow/framework",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Spec-Powered AI Development Framework - 融合 OpenSpec 规范驱动 + Superpowers 执行引擎的企业级 AI 辅助编程框架",
   "type": "module",
   "main": "dist/index.js",