create-yss-spec 3.4.1 → 3.4.3

package/template/.codex/skills/file-export-download/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: file-export-download
-description: 指导 Vue3 YSS UI 微应用实现文件导出、报表下载、模板下载和附件下载，覆盖 OpenAPI binary 响应、Orval 生成方法检查、responseType blob 兜底、Blob 响应类型、Content-Disposition 文件名、handleBlobResponse、loading 与错误处理；当需求出现导出、下载、Excel、CSV、PDF、ZIP、Blob 或文件流时使用。
+description: "在 Vue3 YSS UI 中实现或修复文件下载与导出，处理 Orval 文件流、Blob、文件名和错误响应。"
 ---
 
 # YSS 文件导出下载 Skill

package/template/.codex/skills/frontend-commit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontend-commit
-description: 分析并提交 Vue、React、TypeScript、JavaScript、Vite、微前端和前端 monorepo 项目的 Git 改动；当用户要求生成 commit message、检查提交规范、拆分原子提交、暂存并执行 git commit，或修复 commitlint 与 commit-msg hook 拒绝时使用。读取仓库实际规则和 diff，选择业务 scope，生成英文 type/scope 与中文标题和正文，并安全验证提交。
+description: "为前端改动生成提交信息、审查原子提交或修复 Git hook；用户明确要求提交时执行 git commit。"
 ---
 
 # 前端规范提交

package/template/.codex/skills/java-backend-commit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: java-backend-commit
-description: 分析并提交 Java、Spring Boot、Maven、Gradle、单体服务和多模块后端项目的 Git 改动；当用户要求生成 commit message、检查提交规范、拆分原子提交、暂存并执行 git commit，或修复 commitlint 与 commit-msg hook 拒绝时使用。读取仓库实际规则、模块结构和 diff，选择服务或业务域 scope，生成英文 type/scope 与中文标题和正文，并安全验证提交。
+description: "为 Java 后端改动生成提交信息、审查原子提交或修复 Git hook；用户明确要求提交时执行 git commit。"
 ---
 
 # Java 后端规范提交

package/template/.codex/skills/llm-wiki/SKILL.md

@@ -1,11 +1,6 @@
 ---
 name: llm-wiki
-description: >
-  Compile and maintain a Karpathy-pattern LLM wiki (raw + wiki + schema) with
-  init, incremental refresh, global rebuild, lint, and narrow ingest. Use when
-  the user wants a local knowledge wiki, incremental wiki refresh, wiki rebuild,
-  compiling a named research note into the wiki, `/llm-wiki`, or an answer from
-  an existing wiki.
+description: "Build or refresh a local LLM wiki; use for wiki init, ingest, rebuild, lint, or source-backed wiki questions."
 ---
 
 # llm-wiki

package/template/.codex/skills/lombok/SKILL.md

@@ -1,22 +1,9 @@
 ---
 name: lombok
-description: |
-  Project Lombok for reducing Java boilerplate. Covers annotations for getters,
-  setters, constructors, builders, logging, and more. Based on production
-  patterns from castellino and gestionale-presenze projects.
-
-  USE WHEN: user mentions "lombok", "@Data", "@Builder", "@Slf4j", asks about
-  "boilerplate reduction", "getters/setters", "@RequiredArgsConstructor", "@Value"
-
-  DO NOT USE FOR: Java language features - use `java` skill instead
-  DO NOT USE FOR: MapStruct integration - use `mapstruct` skill
-  DO NOT USE FOR: Spring annotations - use `backend-spring-boot` skill
-allowed-tools: Read, Grep, Glob, Write, Edit
+description: "配置或排查 Lombok 注解、构造器、Builder 和注解处理器；按对象身份与敏感字段选择生成范围。"
 ---
 # Project Lombok
 
-> **Deep Knowledge**: Use `mcp__documentation__fetch_docs` with technology: `lombok` for comprehensive documentation.
-
 ## YSS 阶段 7 执行结果
 
 - 消费工程 Java 与处理器基线；三个新后端 Profile 为 Java 8。MapStruct binding 进入 annotationProcessorPaths，不作为业务依赖单独引入；示例不授权升级依赖。MVC PO 的身份/敏感字段风险与 DDD 相同，不能默认全量 @Data。
@@ -24,329 +11,16 @@ allowed-tools: Read, Grep, Glob, Write, Edit
 - 受控生成必须记录对象类型、选用/排除注解、实体关系和敏感字段风险、编译/测试实际结果。
 - 按 `yss-implementation-contract-compiler` 的统一 Execution Result 返回 changed files、证据、偏离和新增影响；`@Data` 实体风险、处理器配置缺失或越界路径返回 `violation`。
 
-## Maven Configuration
-
-```xml
-<dependency>
-    <groupId>org.projectlombok</groupId>
-    <artifactId>lombok</artifactId>
-    <version>1.18.34</version>
-    <optional>true</optional>
-</dependency>
-
-<!-- For MapStruct compatibility -->
-<dependency>
-    <groupId>org.projectlombok</groupId>
-    <artifactId>lombok-mapstruct-binding</artifactId>
-    <version>0.2.0</version>
-</dependency>
-```
-
-## Common Annotations
-
-### @Data (All-in-One)
-
-```java
-@Data
-public class User {
-    private Long id;
-    private String name;
-    private String email;
-}
-
-// Generates:
-// - @Getter for all fields
-// - @Setter for all non-final fields
-// - @ToString
-// - @EqualsAndHashCode
-// - @RequiredArgsConstructor
-```
-
-### @Getter / @Setter
-
-```java
-public class User {
-    @Getter @Setter
-    private String name;
-
-    @Getter // Read-only
-    private final String email;
-
-    @Setter(AccessLevel.PROTECTED)
-    private String internalId;
-}
-```
-
-### @NoArgsConstructor / @AllArgsConstructor / @RequiredArgsConstructor
-
-```java
-@NoArgsConstructor
-@AllArgsConstructor
-public class User {
-    private Long id;
-    private String name;
-}
-
-@RequiredArgsConstructor
-public class UserService {
-    private final UserRepository userRepository; // Included in constructor
-    private final UserMapper userMapper;         // Included in constructor
-    private String cacheName;                    // NOT included
-}
-```
-
-### @Builder
-
-```java
-@Data
-@Builder
-public class User {
-    private Long id;
-    private String name;
-    private String email;
-    @Builder.Default
-    private UserStatus status = UserStatus.ACTIVE;
-}
-
-// Usage
-User user = User.builder()
-    .name("John")
-    .email("john@example.com")
-    .build();
-
-// With toBuilder for updates
-User updated = user.toBuilder()
-    .name("Jane")
-    .build();
-```
-
-### @Value (Immutable)
-
-```java
-@Value
-public class UserResponse {
-    Long id;
-    String name;
-    String email;
-    LocalDateTime createdAt;
-}
-
-// Generates:
-// - All fields are private final
-// - @AllArgsConstructor
-// - @Getter (no setters)
-// - @ToString
-// - @EqualsAndHashCode
-```
-
-## Entity Pattern
-
-```java
-@Entity
-@Table(name = "users")
-@Getter
-@Setter
-@NoArgsConstructor(access = AccessLevel.PROTECTED)
-@AllArgsConstructor(access = AccessLevel.PRIVATE)
-@Builder
-@EntityListeners(AuditingEntityListener.class)
-public class User {
-
-    @Id
-    @GeneratedValue(strategy = GenerationType.IDENTITY)
-    private Long id;
-
-    @Column(nullable = false)
-    private String name;
-
-    @Column(unique = true, nullable = false)
-    private String email;
-
-    @Enumerated(EnumType.STRING)
-    @Builder.Default
-    private UserStatus status = UserStatus.ACTIVE;
-
-    @CreatedDate
-    @Column(updatable = false)
-    private LocalDateTime createdAt;
-
-    @LastModifiedDate
-    private LocalDateTime updatedAt;
-
-    @ManyToOne(fetch = FetchType.LAZY)
-    @JoinColumn(name = "department_id")
-    private Department department;
-}
-```
-
-JPA/DDD entities must not default to `@Data`; choose equality and `toString` deliberately from stable identity and exclude lazy, relationship, and sensitive fields.
+## 按需读取
 
-## Service Pattern with Constructor Injection
+先确认当前任务涉及的对象与批准合同，只读取对应参考段落：
 
-```java
-@Service
-@RequiredArgsConstructor
-@Slf4j
-public class UserServiceImpl implements UserService {
-
-    private final UserRepository userRepository;
-    private final UserMapper userMapper;
-    private final PasswordEncoder passwordEncoder;
-
-    @Override
-    public UserResponse create(CreateUserRequest dto) {
-        log.info("Creating user: {}", dto.getEmail());
-        User user = userMapper.toEntity(dto);
-        return userMapper.toResponse(userRepository.save(user));
-    }
-}
-```
-
-## Logging
-
-```java
-@Slf4j  // SLF4J logger
-public class UserService {
-    public void process() {
-        log.info("Processing...");
-        log.debug("Debug info: {}", data);
-        log.error("Error occurred", exception);
-    }
-}
-
-@Log4j2  // Log4j2 logger
-@CommonsLog  // Apache Commons Logging
-@JBossLog  // JBoss Logging
-```
-
-## DTO Pattern
-
-```java
-// Request DTO
-@Data
-public class CreateUserRequest {
-    @NotBlank
-    private String name;
-    @Email
-    private String email;
-    @Size(min = 8)
-    private String password;
-}
-
-// Response DTO (immutable)
-@Value
-@Builder
-public class UserResponse {
-    Long id;
-    String name;
-    String email;
-    UserStatus status;
-    LocalDateTime createdAt;
-}
-```
-
-## @Cleanup
-
-```java
-public void readFile(String path) throws IOException {
-    @Cleanup InputStream in = new FileInputStream(path);
-    // in.close() called automatically
-}
-```
-
-## @SneakyThrows
-
-```java
-@SneakyThrows  // Wraps checked exception
-public String readConfig() {
-    return new String(Files.readAllBytes(Paths.get("config.json")), StandardCharsets.UTF_8);
-}
-```
-
-## @Synchronized
-
-```java
-public class Counter {
-    @Synchronized
-    public void increment() {
-        // Thread-safe
-    }
-}
-```
-
-## @With (Immutable Updates)
-
-```java
-@Value
-@With
-public class Point {
-    int x;
-    int y;
-}
-
-Point p1 = new Point(1, 2);
-Point p2 = p1.withX(5);  // Point(5, 2)
-```
-
-## Key Annotations
-
-| Annotation | Purpose |
-|------------|---------|
-| `@Data` | Getter, Setter, ToString, Equals, Constructor |
-| `@Value` | Immutable class |
-| `@Builder` | Builder pattern |
-| `@RequiredArgsConstructor` | Constructor for final fields |
-| `@Slf4j` | Logger field |
-| `@ToString.Exclude` | Exclude from toString |
-| `@EqualsAndHashCode.Exclude` | Exclude from equals/hashCode |
-
----
-
-## When NOT to Use This Skill
-
-| Scenario | Use Instead |
-|----------|-------------|
-| Java core language | `java` skill |
-| MapStruct mapping | `mapstruct` skill |
-| Spring annotations | `backend-spring-boot` skill |
-| JPA entities complex logic | Manual implementation |
-| Public API design | Explicit methods for clarity |
-
----
-
-## Anti-Patterns
-
-| Anti-Pattern | Why It's Bad | Correct Approach |
-|--------------|--------------|------------------|
-| @Data on JPA entities | toString/equals issues | Use @Getter/@Setter selectively |
-| Not excluding lazy relations | LazyInitializationException | Use @ToString.Exclude |
-| @EqualsAndHashCode on entities | Proxy issues | Use @EqualsAndHashCode(onlyExplicitlyIncluded = true) |
-| @SneakyThrows everywhere | Hides exceptions | Use proper exception handling |
-| @Builder without @Default | Null fields | Add @Builder.Default |
-| @Value with mutable fields | Breaks immutability | Use only immutable types |
-| Mixing @Data and manual methods | Confusing API | Be consistent |
-| Not configuring in lombok.config | Inconsistent behavior | Use lombok.config file |
-
----
-
-## Quick Troubleshooting
-
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| "Cannot find symbol" for getters | IDE not processing | Enable annotation processing |
-| LazyInitializationException | toString on lazy relation | Add @ToString.Exclude |
-| MapStruct not working | Wrong processor order | Lombok before MapStruct |
-| Builder missing fields | No @Builder.Default | Add defaults or check config |
-| StackOverflowError in equals | Circular reference | Exclude relation fields |
-| IDE shows errors but compiles | IDE cache | Invalidate caches/restart |
-| @Slf4j logger not found | SLF4J not in classpath | Add SLF4J dependency |
-| Generated code not visible | delombok needed | Run delombok task |
-
----
+| 任务 | 参考 |
+|---|---|
+| 构造器、Builder、默认值或不可变对象 | [Common Annotations](references/annotation-examples.md#common-annotations) |
+| 实体身份、关联与敏感字段 | [Entity Pattern](references/annotation-examples.md#entity-pattern) |
+| 注解处理器与 MapStruct 集成 | [Maven Configuration](references/annotation-examples.md#maven-configuration)，映射逻辑交给 `mapstruct` |
 
-## Reference Documentation
-- [Lombok Documentation](https://projectlombok.org/features/)
-- [Stable Features](https://projectlombok.org/features/all)
-- [Configuration](https://projectlombok.org/features/configuration)
+选择注解前核查生成的 equals/hashCode/toString 是否符合对象身份与数据边界。敏感字段不能进入生成的 toString 或日志；实体不默认使用全量 `@Data`。依赖和处理器版本复用工程基线，修改生成行为后编译受影响模块，并验证实际生成的访问器、构造器或身份行为。
 
-> **Deep Knowledge**: Use `mcp__documentation__fetch_docs` with technology: `lombok` for comprehensive documentation.
+查第三方行为时使用 `yss-research`，来源为 [Lombok 官方文档](https://projectlombok.org/features/)；不假定某个 MCP 工具已安装。

package/template/.codex/skills/lombok/references/annotation-examples.md

@@ -0,0 +1,307 @@
+# lombok 条件参考
+
+仅在需要具体注解或配置示例时定位对应章节。示例业务名与版本不是工程基线；按批准合同替换，禁止直接复制成业务实现。
+
+## Maven Configuration
+
+复用工程父 POM 中已批准的 Lombok 版本与编译插件配置。Lombok 依赖按工程策略使用 provided 或 optional；使用显式注解处理器路径的项目，将 Lombok 放入 `annotationProcessorPaths`。
+
+与 MapStruct 共用时，在同一处理器配置中核验 Lombok、MapStruct processor 和适用的 lombok-mapstruct-binding；binding 不作为业务依赖单独引入。具体配置参见 [MapStruct 配置示例](../../mapstruct/references/annotation-examples.md#maven-configuration)，示例版本仍由当前工程基线替换。
+
+## Common Annotations
+
+### @Data (All-in-One)
+
+```java
+@Data
+public class User {
+    private Long id;
+    private String name;
+    private String email;
+}
+
+// Generates:
+// - @Getter for all fields
+// - @Setter for all non-final fields
+// - @ToString
+// - @EqualsAndHashCode
+// - @RequiredArgsConstructor
+```
+
+### @Getter / @Setter
+
+```java
+public class User {
+    @Getter @Setter
+    private String name;
+
+    @Getter // Read-only
+    private final String email;
+
+    @Setter(AccessLevel.PROTECTED)
+    private String internalId;
+}
+```
+
+### @NoArgsConstructor / @AllArgsConstructor / @RequiredArgsConstructor
+
+```java
+@NoArgsConstructor
+@AllArgsConstructor
+public class User {
+    private Long id;
+    private String name;
+}
+
+@RequiredArgsConstructor
+public class UserService {
+    private final UserRepository userRepository; // Included in constructor
+    private final UserMapper userMapper;         // Included in constructor
+    private String cacheName;                    // NOT included
+}
+```
+
+### @Builder
+
+```java
+@Data
+@Builder
+public class User {
+    private Long id;
+    private String name;
+    private String email;
+    @Builder.Default
+    private UserStatus status = UserStatus.ACTIVE;
+}
+
+// Usage
+User user = User.builder()
+    .name("John")
+    .email("john@example.com")
+    .build();
+
+// With toBuilder for updates
+User updated = user.toBuilder()
+    .name("Jane")
+    .build();
+```
+
+### @Value (Immutable)
+
+```java
+@Value
+public class UserResponse {
+    Long id;
+    String name;
+    String email;
+    LocalDateTime createdAt;
+}
+
+// Generates:
+// - All fields are private final
+// - @AllArgsConstructor
+// - @Getter (no setters)
+// - @ToString
+// - @EqualsAndHashCode
+```
+
+## Entity Pattern
+
+```java
+@Entity
+@Table(name = "users")
+@Getter
+@Setter
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+@AllArgsConstructor(access = AccessLevel.PRIVATE)
+@Builder
+@EntityListeners(AuditingEntityListener.class)
+public class User {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(nullable = false)
+    private String name;
+
+    @Column(unique = true, nullable = false)
+    private String email;
+
+    @Enumerated(EnumType.STRING)
+    @Builder.Default
+    private UserStatus status = UserStatus.ACTIVE;
+
+    @CreatedDate
+    @Column(updatable = false)
+    private LocalDateTime createdAt;
+
+    @LastModifiedDate
+    private LocalDateTime updatedAt;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "department_id")
+    private Department department;
+}
+```
+
+JPA/DDD entities must not default to `@Data`; choose equality and `toString` deliberately from stable identity and exclude lazy, relationship, and sensitive fields.
+
+## Service Pattern with Constructor Injection
+
+```java
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class UserServiceImpl implements UserService {
+
+    private final UserRepository userRepository;
+    private final UserMapper userMapper;
+    private final PasswordEncoder passwordEncoder;
+
+    @Override
+    public UserResponse create(CreateUserRequest dto) {
+        log.info("Creating user");
+        User user = userMapper.toEntity(dto);
+        return userMapper.toResponse(userRepository.save(user));
+    }
+}
+```
+
+## Logging
+
+```java
+@Slf4j  // SLF4J logger
+public class UserService {
+    public void process() {
+        log.info("Processing...");
+        log.debug("Processing completed");
+        log.error("Error occurred", exception);
+    }
+}
+
+@Log4j2  // Log4j2 logger
+@CommonsLog  // Apache Commons Logging
+@JBossLog  // JBoss Logging
+```
+
+## DTO Pattern
+
+```java
+// Request DTO
+@Getter
+@Setter
+@ToString(onlyExplicitlyIncluded = true)
+public class CreateUserRequest {
+    @NotBlank
+    private String name;
+    @Email
+    private String email;
+    @Size(min = 8)
+    private String password;
+}
+
+// Response DTO (immutable)
+@Value
+@Builder
+public class UserResponse {
+    Long id;
+    String name;
+    String email;
+    UserStatus status;
+    LocalDateTime createdAt;
+}
+```
+
+## @Cleanup
+
+```java
+public void readFile(String path) throws IOException {
+    @Cleanup InputStream in = new FileInputStream(path);
+    // in.close() called automatically
+}
+```
+
+## @SneakyThrows
+
+```java
+@SneakyThrows  // Wraps checked exception
+public String readConfig() {
+    return new String(Files.readAllBytes(Paths.get("config.json")), StandardCharsets.UTF_8);
+}
+```
+
+## @Synchronized
+
+```java
+public class Counter {
+    @Synchronized
+    public void increment() {
+        // Thread-safe
+    }
+}
+```
+
+## @With (Immutable Updates)
+
+```java
+@Value
+@With
+public class Point {
+    int x;
+    int y;
+}
+
+Point p1 = new Point(1, 2);
+Point p2 = p1.withX(5);  // Point(5, 2)
+```
+
+## Key Annotations
+
+| Annotation | Purpose |
+|------------|---------|
+| `@Data` | Getter, Setter, ToString, Equals, Constructor |
+| `@Value` | Immutable class |
+| `@Builder` | Builder pattern |
+| `@RequiredArgsConstructor` | Constructor for final fields |
+| `@Slf4j` | Logger field |
+| `@ToString.Exclude` | Exclude from toString |
+| `@EqualsAndHashCode.Exclude` | Exclude from equals/hashCode |
+
+---
+
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Bad | Correct Approach |
+|--------------|--------------|------------------|
+| @Data on JPA entities | toString/equals issues | Use @Getter/@Setter selectively |
+| Not excluding lazy relations | LazyInitializationException | Use @ToString.Exclude |
+| @EqualsAndHashCode on entities | Proxy issues | Use @EqualsAndHashCode(onlyExplicitlyIncluded = true) |
+| @SneakyThrows everywhere | Hides exceptions | Use proper exception handling |
+| @Builder without @Default | Null fields | Add @Builder.Default |
+| @Value with mutable fields | Breaks immutability | Use only immutable types |
+| Mixing @Data and manual methods | Confusing API | Be consistent |
+| Not configuring in lombok.config | Inconsistent behavior | Use lombok.config file |
+
+---
+
+## Quick Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| "Cannot find symbol" for getters | IDE not processing | Enable annotation processing |
+| LazyInitializationException | toString on lazy relation | Add @ToString.Exclude |
+| MapStruct not working | Wrong processor order | Lombok before MapStruct |
+| Builder missing fields | No @Builder.Default | Add defaults or check config |
+| StackOverflowError in equals | Circular reference | Exclude relation fields |
+| IDE shows errors but compiles | IDE cache | Invalidate caches/restart |
+| @Slf4j logger not found | SLF4J not in classpath | Add SLF4J dependency |
+| Generated code not visible | delombok needed | Run delombok task |
+
+---
+
+## Reference Documentation
+- [Lombok Documentation](https://projectlombok.org/features/)
+- [Stable Features](https://projectlombok.org/features/all)
+- [Configuration](https://projectlombok.org/features/configuration)