adspecs 0.1.19 → 0.1.21

package/skills/adspecs-utest/SKILL.md

@@ -2,10 +2,10 @@
 name: adspecs-utest
 description: "基于后端系统设计文档，生成 Service 层 / Controller 层单元测试代码，并按模板输出单元测试报告"
 argument-hint: "指定功能名或系统设计文档路径，如 M06-01 或 docs/30-system-design/crm/M06-01-销售预测_system-design.md"
-compatibility: "需要 docs/ 目录体系：docs/20-prd（PRD）+ docs/30-system-design（系统设计+tasks）+ CLAUDE.md（ECP 编码宪章）"
+compatibility: "需要 docs/ 目录体系：docs/20-prd（PRD）+ docs/30-system-design（系统设计+tasks）+ CLAUDE.md + docs/40-project_conventions/end-integration/index.md"
 metadata:
   author: "qingwen"
-  source: "基于 adspecs-analyze 通用模板 + ECP 全链路追溯 ID 体系 + CLI 规范 10 条 + TDD 一致性检测改造"
+  source: "基于 adspecs-analyze 通用模板 + 全链路追溯 ID 体系 + TDD 一致性检测改造"
 user-invocable: true
 disable-model-invocation: false
 ---
@@ -22,7 +22,7 @@ disable-model-invocation: false
 
 | 对比项   | 本技能（adspecs-utest）                | /adspecs-tasks     |
 | -------- | -------------------------------------- | ------------------ |
-| 输出     | 测试代码（Java）+ 测试报告（md）       | TDD 任务清单（md） |
+| 输出     | 测试代码 + 测试报告（md）              | TDD 任务清单（md） |
 | 目标读者 | 开发工程师 / 测试工程师                | 开发工程师         |
 | 关注点   | 验证 Service/Controller 业务逻辑正确性 | 拆解编码实现步骤   |
 | 阶段     | 编码完成后                             | 编码之前           |
@@ -31,7 +31,7 @@ disable-model-invocation: false
 
 读取用户指定的后端系统设计文档，生成 **两类输出**：
 
-1. **单元测试代码**（`.java`）— Service 层测试 + Controller 层测试，JUnit 5 + Mockito，遵循项目现有测试模式
+1. **单元测试代码** — Service 层测试 + Controller 层测试，按后端规范的测试框架和 Mock 模式，遵循项目现有测试风格
 2. **单元测试报告**（`.md`）— 按 `.adspecs/templates/07-单元测试报告模板.md` 结构填写
 
 本技能**不修改**业务代码、不生成集成测试、不执行测试运行。
@@ -59,118 +59,113 @@ disable-model-invocation: false
 | ---- | ---------------------------------------------------------------------------------- | -------------------------------------------------------- |
 | 1    | 用户指定的系统设计文件（如 `{DESIGN_DIR}/crm/M01-01-产品主数据_system-design.md`） | 提取 Service 方法、Controller 端点、异常码、§12 测试场景 |
 | 2    | `.adspecs/templates/07-单元测试报告模板.md`                                         | 测试报告的输出模板（6 部分结构）                         |
-| 3    | `CLAUDE.md`                                                                        | 项目模块结构、测试框架约定、包路径规范                   |
+| 3    | `CLAUDE.md`                                                                        | 项目模块结构                                             |
+| 4    | `docs/40-project_conventions/end-integration/index.md`                              | 后端编码规范索引（测试框架、Mock 模式、命名约定等）      |
 
 ### 参考文件（按需读取）
 
-| 序号 | 文件                                         | 用途                                 |
-| ---- | -------------------------------------------- | ------------------------------------ |
-| 4    | 已有的 `*Test.java` 文件（同模块或相邻模块） | 对齐项目现有测试风格和 Mock 模式     |
-| 5    | 对应的 `*_tasks.md` 文件                     | 了解 T0xx 任务编号与 US 的映射关系   |
-| 6    | 实际的 Service / Controller 源码             | 了解方法签名、依赖注入、业务逻辑细节 |
-| 7    | 对应的 i18n `.properties` 文件               | 确认消息码与实际异常描述的对应       |
+| 序号 | 文件                                       | 用途                                 |
+| ---- | ------------------------------------------ | ------------------------------------ |
+| 5    | 已有的测试文件（同模块或相邻模块）         | 对齐项目现有测试风格和 Mock 模式     |
+| 6    | 对应的 `*_tasks.md` 文件                   | 了解 T0xx 任务编号与 US 的映射关系   |
+| 7    | 实际的 Service / Controller 源码           | 了解方法签名、依赖注入、业务逻辑细节 |
+| 8    | 对应的 i18n 语言文件                       | 确认消息码与实际异常描述的对应       |
+
+### 加载后端编码规范（必选）
+
+1. 读取 `docs/40-project_conventions/end-integration/index.md`
+2. 按 `index.md` 中"推荐读取顺序"依次加载所有关联规范文件
+3. 后续所有测试代码中的框架选择、Mock 模式、命名约定、异常类引用等，均以该规范为准
+4. 如该目录不存在或 `index.md` 缺失，中止执行并提示先运行 `/project-init` 选择技术栈
 
 ## 项目测试约定
 
+> **以下约定均从 `docs/40-project_conventions/end-integration/index.md` 运行时加载。本节仅描述通用结构，具体框架、注解、类名以规范为准。**
+
 ### 技术栈
 
-| 项         | 值                                                                       |
-| ---------- | ------------------------------------------------------------------------ |
-| 测试框架   | JUnit 5（`org.junit.jupiter`）                                           |
-| Mock 框架  | Mockito（`@ExtendWith(MockitoExtension.class)`）                         |
-| 断言       | JUnit 5 Assertions（`assertEquals`, `assertNotNull`, `assertThrows` 等） |
-| 显示名称   | `@DisplayName("T0xx [US-xx] 描述")`                                      |
-| 覆盖率目标 | 行覆盖率 100%，分支覆盖率 100%                                           |
+| 项         | 值                                         |
+| ---------- | ------------------------------------------ |
+| 测试框架   | 按后端规范（如 JUnit 5 / pytest 等）       |
+| Mock 框架  | 按后端规范（如 Mockito / unittest.mock 等） |
+| 断言       | 按后端规范的断言库                         |
+| 显示名称   | 按后端规范的测试标注方式                   |
+| 覆盖率目标 | 行覆盖率 100%，分支覆盖率 100%             |
 
 ### 测试类命名与位置
 
-| 被测类                 | 测试类命名                 | 测试类位置                                                                                                 |
-| ---------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `CrmProductService`    | `CrmProductServiceTest`    | `3100-crm-{mod}-application/src/test/java/com/sie/crm/{mod}/model/service/impl/CrmProductServiceTest.java` |
-| `CrmProductController` | `CrmProductControllerTest` | `3100-crm-{mod}-application/src/test/java/com/sie/crm/{mod}/api/controller/CrmProductControllerTest.java`  |
+| 被测类      | 测试类命名            | 测试类位置                         |
+| ----------- | --------------------- | ---------------------------------- |
+| Service 类  | `{ServiceName}Test`   | 按后端规范的测试目录结构           |
+| Controller 类 | `{ControllerName}Test` | 按后端规范的测试目录结构        |
 
-### Service 层测试模式（Mockito + @Spy + @InjectMocks）
+### Service 层测试模式
 
-```java
-@ExtendWith(MockitoExtension.class)
-@DisplayName("{ClassName} 单元测试")
-class {ClassName}Test {
+> 以下为通用模式示意，具体注解和 Mock 方式按后端规范。
 
-    @Mock
-    private {DaoName} {daoField};
+```
+{ServiceUnderTest} 测试类 {
 
-    @Spy
-    @InjectMocks
-    private {ServiceImplName} {serviceField};
+    // Mock 数据访问层依赖（按后端规范）
+
+    // Spy 或 InjectMocks 被测 Service 实例（按后端规范）
 
     // setUp() 中构建 mock 数据
 
-    @Test
-    @DisplayName("T0xx [US-xx] 场景描述 — 预期结果")
-    void methodName_scenario() {
-        // Given
-        doReturn(...).when(...).method(...);
-        // When
-        var result = service.method(args);
-        // Then
-        assertNotNull(result);
-        assertEquals(expected, result.getXxx());
+    // 测试方法
+    methodName_scenario() {
+        // Given — mock 依赖方法
+        // When — 调用被测方法
+        // Then — 断言返回值/异常
     }
 }
 ```
 
 **关键约定**：
 
-- Service 实现类使用 `@Spy + @InjectMocks`，因为需要 mock 继承自 `BaseCommonServer` 的方法（如 `getById`, `save`, `updateById`, `deleteById`）
-- DAO 使用 `@Mock`
+- Service 实现类的测试需要 mock 其基类的数据访问方法（如 getById、save、updateById、deleteById 等，按后端规范）
+- 数据访问层使用 Mock
 - 测试方法命名：`methodName_scenarioDescription`（驼峰式，不用下划线分隔单词）
-- 异常测试用 `assertThrows(ExceptionClass.class, () -> ...)`
-- 无异常测试用 `assertDoesNotThrow(() -> ...)`
+- 异常测试使用后端规范的断言方式
+- 无异常测试使用后端规范的断言方式
+
+### Controller 层测试模式
 
-### Controller 层测试模式（Mockito + @InjectMocks）
+> 以下为通用模式示意，具体注解和请求/响应包装按后端规范。
 
-```java
-@ExtendWith(MockitoExtension.class)
-@DisplayName("{ClassName} 集成测试")
-class {ClassName}Test {
+```
+{ControllerUnderTest} 测试类 {
 
-    @Mock
-    private II{Entity} {serviceField};
+    // Mock Service 依赖（按后端规范）
 
-    @InjectMocks
-    private {ControllerName} controller;
+    // InjectMocks 被测 Controller 实例（按后端规范）
 
     // setUp() 中构建 mockEntity 和 mockRo
 
-    @Test
-    @DisplayName("T0xx [US-xx] HTTP METHOD /path → 预期结果")
-    void endpointName_scenario() {
-        // Given
-        doReturn(...).when(service).method(...);
-        // 构造 RequestData / PaginationRequestData
-        // When
-        ResponseData<...> response = controller.method(requestData);
-        // Then
-        assertNotNull(response);
-        assertNotNull(response.getData());
+    // 测试方法
+    endpointName_scenario() {
+        // Given — mock Service 方法
+        // 构造请求包装对象（按后端规范）
+        // When — 调用 Controller 方法
+        // Then — 断言响应对象的 code / data 结构
     }
 }
 ```
 
 **关键约定**：
 
-- Controller 使用 `@InjectMocks`（非 Spy），因为不测试继承行为
-- Service 使用 `@Mock`
-- 需手动构造 `RequestData<Dto>` 和 `PaginationRequestData<Dto>`
-- 测试 Controller 的 dto 为 null 场景（返回 `ResponseData.fail`）
-- 验证 `ResponseData` 的 code / data 结构
+- Controller 使用 InjectMocks（非 Spy），因为不测试继承行为
+- Service 使用 Mock
+- 需手动构造后端规范定义的请求包装对象
+- 测试 Controller 的入参为 null 场景（返回失败响应）
+- 验证响应对象的 code / data 结构
 
-### @DisplayName 命名规则
+### 测试显示名称命名规则
 
 **Service 测试**：`T0xx [US-xx] 方法名 — 场景描述，预期结果`
 
 - 示例：`T016-1 [US-01] 分页查询 — 无条件分页，返回 1 条记录`
-- 示例：`T028-2 [US-03] 新增 — 编码重复，抛出 GushenRuntimeException`
+- 示例：`T028-2 [US-03] 新增 — 编码重复，抛出业务异常`
 
 **Controller 测试**：`T0xx [US-xx] HTTP方法 /端点 → 预期结果`
 
@@ -200,10 +195,8 @@ class {ClassName}Test {
 
 ### 步骤 2：读取参考文件（对齐风格）
 
-1. 检查同模块下已有的 `*Test.java` 文件，对齐测试风格
-2. 如果没有，读取相邻模块的测试文件作为参考：
-   - `3100-crm-mdm/.../CrmProductServiceTest.java`
-   - `3100-crm-mdm/.../CrmCustomerControllerTest.java`
+1. 检查同模块下已有的测试文件，对齐测试风格
+2. 如果没有，读取相邻模块的测试文件作为参考
 3. 如果存在 `*_tasks.md`，读取 T0xx 编号与 US 的映射
 
 ### 步骤 3：生成 Service 层测试代码
@@ -229,20 +222,20 @@ class {ClassName}Test {
 
 2. **新增方法**（`saveXxx`）：
    - 合法数据保存成功
-   - 唯一性字段重复（抛出 `GushenRuntimeException`）
+   - 唯一性字段重复（抛出后端规范定义的业务异常）
    - 默认值设置（如 isActive=1）
 
 3. **编辑方法**（`updateXxx`）：
    - 合法更新成功，不可修改字段不变
-   - 数据不存在（抛出 `RecordNotExistsException`）
+   - 数据不存在（抛出后端规范定义的数据不存在异常）
 
 4. **删除方法**（`deleteXxx`）：
    - 存在数据逻辑删除成功
-   - 数据不存在（抛出 `RecordNotExistsException`）
+   - 数据不存在（抛出后端规范定义的数据不存在异常）
 
 5. **详情查询方法**（`findById`）：
    - 数据存在，返回完整字段
-   - 数据不存在（抛出 `RecordNotExistsException`）
+   - 数据不存在（抛出后端规范定义的数据不存在异常）
 
 6. **编码查询方法**（`findByCode`）：
    - 上架产品，返回完整信息
@@ -251,7 +244,7 @@ class {ClassName}Test {
 
 **Mock 数据构建规则**：
 
-- 在 `@BeforeEach setUp()` 中构建 1-2 个可复用的 mock 对象
+- 在测试初始化方法（setUp）中构建 1-2 个可复用的 mock 对象
 - mock 对象的业务字段必须使用真实业务数据（如产品编码 "PROD-001"、产品名称 "5052 铝板"），不使用 "test1"、"abc" 等无意义数据
 - 异常场景专用的 mock 对象在测试方法内部构建
 
@@ -261,17 +254,17 @@ class {ClassName}Test {
 
 **每个端点至少覆盖**：
 
-| 场景             | 验证内容                                      |
-| ---------------- | --------------------------------------------- |
-| 正常请求         | ResponseData 非空，data 字段正确              |
-| dto 为 null      | 返回 `ResponseData.fail`（Controller 空校验） |
-| Service 抛出异常 | 异常传播（Controller 不吞异常）               |
+| 场景             | 验证内容                                       |
+| ---------------- | ---------------------------------------------- |
+| 正常请求         | 响应对象非空，data 字段正确                    |
+| dto 为 null      | 返回失败响应（Controller 空校验）              |
+| Service 抛出异常 | 异常传播（Controller 不吞异常）                |
 
 **Controller 测试生成规则**：
 
-- 手动构造 `RequestData<Dto>` 和 `PaginationRequestData<Dto>`
-- 验证 `ResponseData` 的 code 和 data 结构
-- dto 为 null 场景直接传入 null 或构造空 RequestData
+- 手动构造后端规范定义的请求包装对象
+- 验证响应对象的 code 和 data 结构
+- dto 为 null 场景直接传入 null 或构造空请求对象
 
 ### 步骤 5：生成单元测试报告
 
@@ -295,31 +288,29 @@ class {ClassName}Test {
 
 ### 步骤 6：保存文件
 
-| 输出            | 保存位置                                                                                             |
-| --------------- | ---------------------------------------------------------------------------------------------------- |
-| Service 测试    | `{port}-{mod}-application/src/test/java/com/sie/crm/{mod}/model/service/impl/{ServiceName}Test.java` |
-| Controller 测试 | `{port}-{mod}-application/src/test/java/com/sie/crm/{mod}/api/controller/{ControllerName}Test.java`  |
-| 测试报告        | `{TEST_REPORT_DIR}/{模块编号}-{模块名}_单元测试报告.md`                                              |
+| 输出            | 保存位置                                                           |
+| --------------- | ------------------------------------------------------------------ |
+| Service 测试    | `{模块}-application/{测试目录}/{包路径}/service/impl/{ServiceName}Test` |
+| Controller 测试 | `{模块}-application/{测试目录}/{包路径}/controller/{ControllerName}Test` |
+| 测试报告        | `{TEST_REPORT_DIR}/{模块编号}-{模块名}_单元测试报告.md`            |
 
 ## 输出
 
 ### 文件命名
 
-| 文件类型        | 命名规则                              | 示例                                |
-| --------------- | ------------------------------------- | ----------------------------------- |
-| Service 测试    | `{ServiceName}Test.java`              | `CrmProductServiceTest.java`        |
-| Controller 测试 | `{ControllerName}Test.java`           | `CrmProductControllerTest.java`     |
-| 测试报告        | `{模块编号}-{模块名}_单元测试报告.md` | `M01-01-产品主数据_单元测试报告.md` |
+| 文件类型        | 命名规则                                | 示例                                  |
+| --------------- | --------------------------------------- | ------------------------------------- |
+| Service 测试    | `{ServiceName}Test.{ext}`（按后端规范） | `CrmProductServiceTest.java`          |
+| Controller 测试 | `{ControllerName}Test.{ext}`（按后端规范） | `CrmProductControllerTest.java`   |
+| 测试报告        | `{模块编号}-{模块名}_单元测试报告.md`   | `M01-01-产品主数据_单元测试报告.md`   |
 
 ### 输出目录映射
 
-测试代码目录根据系统设计文档的模块元数据确定：
+测试代码目录根据系统设计文档的模块元数据和后端规范确定：
 
-| 系统设计文档中的模块 | 测试代码根路径                                                                     |
-| -------------------- | ---------------------------------------------------------------------------------- |
-| 3100-crm-mdm         | `crm-service/3100-crm-mdm/3100-crm-mdm-application/src/test/java/`                 |
-| 3103-crm-contract    | `crm-service/3103-crm-contract/3103-crm-contract-application/src/test/java/`       |
-| 3104-crm-fulfillment | `crm-service/3104-crm-fulfillment/3104-crm-fulfillment-application/src/test/java/` |
+| 系统设计文档中的模块 | 测试代码根路径                               |
+| -------------------- | -------------------------------------------- |
+| 各业务模块           | `{模块}-application/{后端规范测试目录}/`     |
 
 ## 测试用例编号规则
 
@@ -345,14 +336,14 @@ class {ClassName}Test {
 ### 测试代码质量
 
 - [ ] 每个 Service 方法至少 3 个测试用例（正常+异常+边界）
-- [ ] 每个 Controller 端点至少 2 个测试用例（正常+dto 为 null）
+- [ ] 每个 Controller 端点至少 2 个测试用例（正常+入参为 null）
 - [ ] 测试方法命名规范：`methodName_scenarioDescription`
-- [ ] @DisplayName 包含 T0xx 编号和 [US-xx] 关联
+- [ ] 测试显示名称包含 T0xx 编号和 [US-xx] 关联（按后端规范的标注方式）
 - [ ] Mock 数据使用真实业务数据，不使用无意义字符串
-- [ ] Service 测试使用 `@Spy + @InjectMocks`
-- [ ] Controller 测试使用 `@InjectMocks`
-- [ ] 异常测试使用 `assertThrows` 并验证异常类型
-- [ ] 无 import 未使用的类
+- [ ] Service 测试按后端规范选择 Spy/InjectMocks 策略
+- [ ] Controller 测试按后端规范使用 InjectMocks
+- [ ] 异常测试按后端规范的断言方式验证异常类型
+- [ ] 无未使用的引用/导入
 - [ ] 测试类在正确的包路径下
 
 ### 测试报告质量
@@ -375,11 +366,11 @@ class {ClassName}Test {
 ## 约束
 
 - **仅生成测试代码和测试报告**：不修改业务代码
-- **遵循项目现有测试模式**：参照已有的 `*Test.java` 文件风格
-- **不执行测试**：生成代码后不自动运行 `mvn test`
+- **遵循项目现有测试模式**：参照已有的测试文件风格
+- **不执行测试**：生成代码后不自动运行测试命令
 - **不生成集成测试**：仅 Service 层单元测试 + Controller 层单元测试
-- **禁止 QueryWrapper**：测试中不直接使用 QueryWrapper 构造查询条件
-- **mock 继承方法**：对 `BaseCommonServer` 的 `getById`/`save`/`updateById`/`deleteById` 使用 `doReturn(...).when(spy).method(...)` 模式
+- **禁止绕过数据访问层**：测试中不直接构造数据访问层的查询对象
+- **mock 继承方法**：对基类的数据访问方法（如 getById/save/updateById/deleteById 等，按后端规范）使用 mock 模式
 - **测试独立性**：每个测试方法独立运行，不依赖其他测试方法的执行顺序或结果
 
 ## 触发关键词

package/skills/grill-me/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: grill-me
+description: A relentless interview to sharpen a plan or design.
+disable-model-invocation: true
+---
+
+Run a `/grilling` session.

package/skills/grill-me/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Grill Me"
+  short_description: "Sharpen a plan through interview"
+policy:
+  allow_implicit_invocation: false