ai-engineering-init 1.4.3 → 1.5.0

package/src/skills/architecture-design/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: architecture-design
+description: |
+  系统架构设计、模块划分、代码重构、技术栈选型。核心内容：三层架构规范、业务模块划分、表设计规范、技术栈优先级决策。
+
+  触发场景：
+  - 系统整体架构设计
+  - 新业务模块的模块划分与结构规划
+  - 代码分层与重构策略
+  - 依赖关系梳理与解耦
+  - 架构演进路径建议
+  - 领域边界划分与包结构设计
+  - 技术栈选型与方案决策
+
+  触发词：架构设计、模块划分、三层架构、分层、领域划分、重构、解耦、依赖管理、系统设计、代码组织、技术栈、架构演进
+
+  注意：
+  1. 具体技术对比（Redis vs 本地缓存）-> 使用 tech-decision
+  2. 开发具体 CRUD 模块 -> 使用 crud-development
+  3. 数据库建表与字典配置 -> 使用 database-ops
+  4. 本项目是纯后端项目（无前端代码）
+---
+
+# 架构设计指南
+
+## 核心技术栈
+
+| 层级 | 技术栈 | 版本 |
+|------|--------|------|
+| 后端框架 | Spring Boot | 3.5.9 |
+| 开发语言 | Java | 17 |
+| ORM | MyBatis-Plus | 3.5.16 |
+| 安全 | Sa-Token | 1.44.0 |
+| 数据库 | MySQL | 8.0+ |
+| 缓存 | Redis + Redisson | 3.52.0 |
+| 文档 | SpringDoc | 2.8.15 |
+| 工具库 | Hutool | 5.8.43 |
+| 对象转换 | Mapstruct-Plus | 1.5.0 |
+
+## 已集成技术栈（按优先级）
+
+### 高优先级（优先选择）
+
+| 技术 | 使用场景 |
+|------|---------|
+| Redis + Redisson | 缓存、分布式锁、延迟队列、布隆过滤器 |
+| WebSocket | 实时推送、在线聊天、消息通知 |
+| Sa-Token | 权限控制、登录认证、单点登录 |
+| Lock4j | 分布式锁（基于 Redisson） |
+| SnailJob | 分布式定时任务、复杂调度 |
+
+### 中优先级（按需使用）
+
+| 技术 | 使用场景 |
+|------|---------|
+| SSE | 服务端单向推送 |
+| FastExcel | Excel 导入导出 |
+| SMS4j | 多平台短信发送 |
+| JustAuth | 第三方 OAuth 登录（30+ 平台） |
+| AWS S3 | 对象存储（兼容 MinIO） |
+| MailSender | 邮件发送 |
+| Redis Streams | 轻量级消息队列 |
+
+### 已集成扩展能力
+
+数据加密、数据脱敏、防重复提交、国际化翻译、审计日志、接口限流
+
+### 需自行扩展
+
+| 技术 | 使用场景 |
+|------|---------|
+| RocketMQ | 高吞吐消息队列、分布式事务 |
+| MQTT | 物联网设备通信 |
+| LangChain4j | AI 大模型集成 |
+
+### 技术选型决策树
+
+```
+需要实时通信？
++-- 是 -> WebSocket（首选）
++-- 否 -> 需要消息队列？
+         +-- 是 -> Redis Streams（优先） / RocketMQ（高吞吐，自行引入）
+         +-- 否 -> 需要定时任务？
+                +-- 是 -> SnailJob（分布式） / @Scheduled（简单场景）
+                +-- 否 -> 需要缓存？
+                       +-- 是 -> Redis + Redisson
+```
+
+---
+
+## 三层架构（Controller -> Service -> Mapper）
+
+**没有独立的 DAO 层。** Service 直接调用 Mapper，`buildQueryWrapper()` 在 Service 实现类中。
+
+```
+Controller 层：接收 HTTP 请求、参数校验、返回 R<T>
+    |
+Service 层：业务逻辑、事务管理、buildQueryWrapper()、直接注入 Mapper
+    |
+Mapper 层：extends BaseMapperPlus<Entity, Vo>，ORM 映射
+```
+
+---
+
+## 模块划分与表前缀
+
+**包名必须是 `org.dromara.*`**
+
+### 标准模块
+
+| 模块 | 目录 | 包路径 | 表前缀 |
+|------|------|--------|--------|
+| 系统管理 | `ruoyi-modules/ruoyi-system/` | `org.dromara.system` | `sys_` |
+| 演示模块 | `ruoyi-modules/ruoyi-demo/` | `org.dromara.demo` | `test_` |
+| 工作流 | `ruoyi-modules/ruoyi-workflow/` | `org.dromara.workflow` | `flow_` |
+
+### 扩展模块命名
+
+```
+ruoyi-modules/ruoyi-{业务}/  ->  org.dromara.{业务}  ->  {前缀}_
+例：ruoyi-mall/  ->  org.dromara.mall  ->  m_
+```
+
+### 关键规则
+
+```java
+// 1. 表前缀与模块一一对应
+// OK: sys_user -> ruoyi-system    NG: sys_user -> ruoyi-demo
+
+// 2. 所有业务表继承 TenantEntity
+public class Order extends TenantEntity {
+    @TableId(value = "id")       // 雪花ID，依赖全局配置，不指定 type
+    private Long id;
+
+    @TableLogic
+    private Long delFlag;        // 逻辑删除
+}
+
+// 3. 主键使用雪花 ID（全局配置 idType: ASSIGN_ID）
+@TableId(value = "id")           // OK
+@TableId(value = "id", type = IdType.ASSIGN_ID)  // NG: 冗余
+// SQL 中禁止 AUTO_INCREMENT
+```
+
+---
+
+## 模块内部结构（以 TestDemo 为例）
+
+```
+ruoyi-modules/ruoyi-demo/src/main/java/org/dromara/demo/
++-- controller/
+|   +-- TestDemoController.java      # @RestController
++-- service/
+|   +-- ITestDemoService.java        # 接口
+|   +-- impl/
+|       +-- TestDemoServiceImpl.java  # 实现（含 buildQueryWrapper）
++-- mapper/
+|   +-- TestDemoMapper.java          # extends BaseMapperPlus<TestDemo, TestDemoVo>
++-- domain/
+    +-- TestDemo.java                # extends TenantEntity
+    +-- bo/
+    |   +-- TestDemoBo.java          # @AutoMapper
+    +-- vo/
+        +-- TestDemoVo.java
+```
+
+### Service 实现核心模式
+
+```java
+@Service
+public class TestDemoServiceImpl implements ITestDemoService {
+    private final TestDemoMapper baseMapper;  // 直接注入 Mapper
+
+    private LambdaQueryWrapper<TestDemo> buildQueryWrapper(TestDemoBo bo) {
+        Map<String, Object> params = bo.getParams();
+        LambdaQueryWrapper<TestDemo> lqw = Wrappers.lambdaQuery();
+        lqw.eq(bo.getDeptId() != null, TestDemo::getDeptId, bo.getDeptId());
+        lqw.like(StringUtils.isNotBlank(bo.getTestKey()), TestDemo::getTestKey, bo.getTestKey());
+        lqw.between(params.get("beginCreateTime") != null && params.get("endCreateTime") != null,
+            TestDemo::getCreateTime, params.get("beginCreateTime"), params.get("endCreateTime"));
+        return lqw;
+    }
+
+    @Override
+    public TableDataInfo<TestDemoVo> queryPageList(TestDemoBo bo, PageQuery pageQuery) {
+        LambdaQueryWrapper<TestDemo> lqw = buildQueryWrapper(bo);
+        Page<TestDemoVo> result = baseMapper.selectVoPage(pageQuery.build(), lqw);
+        return TableDataInfo.build(result);
+    }
+}
+```
+
+---
+
+## 建表模板（MySQL）
+
+```sql
+CREATE TABLE xxx_table (
+    id              BIGINT(20)    NOT NULL COMMENT '主键ID',
+    tenant_id       VARCHAR(20)   DEFAULT '000000' COMMENT '租户ID',
+    -- 业务字段
+    xxx_name        VARCHAR(100)  NOT NULL COMMENT '名称',
+    status          CHAR(1)       DEFAULT '0' COMMENT '状态',
+    remark          VARCHAR(500)  DEFAULT NULL COMMENT '备注',
+    -- 审计字段（TenantEntity 提供）
+    create_dept     BIGINT(20)    DEFAULT NULL COMMENT '创建部门',
+    create_by       BIGINT(20)    DEFAULT NULL COMMENT '创建人',
+    create_time     DATETIME      DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+    update_by       BIGINT(20)    DEFAULT NULL COMMENT '更新人',
+    update_time     DATETIME      DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+    del_flag        CHAR(1)       DEFAULT '0' COMMENT '删除标志(0正常 1已删除)',
+    PRIMARY KEY (id),
+    INDEX idx_tenant_id (tenant_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='xxx表';
+```
+
+**建表必须**：tenant_id、审计字段、del_flag、雪花ID（无 AUTO_INCREMENT）、表前缀对应模块。
+
+多数据库 SQL 位置：`script/sql/` 下的 `ry_vue_5.X.sql`（MySQL）、`oracle/`、`postgres/`、`sqlserver/`
+
+---
+
+## 技术选型决策速查
+
+| 场景 | 推荐方案 |
+|------|---------|
+| 简单异步通知 | 同步调用即可 |
+| 解耦场景消息队列 | Redis Streams |
+| 高并发削峰 | RocketMQ（自行引入） |
+| 单机定时任务 | `@Scheduled` |
+| 分布式定时任务 | SnailJob |
+| 实时双向通信 | WebSocket |
+| 服务端单向推送 | SSE |
+| IoT 设备通信 | MQTT（自行集成） |
+
+---
+
+## 新模块设计检查清单
+
+- [ ] 包路径：`org.dromara.{模块名}`
+- [ ] 表前缀与模块对应
+- [ ] 主键雪花ID、含 tenant_id、审计字段、del_flag
+- [ ] 三层完整：Controller / Service（含 buildQueryWrapper） / Mapper（extends BaseMapperPlus）
+- [ ] 对象转换：`MapstructUtils.convert()`
+- [ ] 异常处理：`ServiceException`
+- [ ] 权限注解：`@SaCheckPermission("{模块}:{实体}:{操作}")`
+- [ ] 缓存优先 Redis、实时通信优先 WebSocket、导出用 FastExcel
+
+---
+
+## 多项目适配对照
+
+| 特征 | RuoYi-Vue-Plus | leniu-tengyun-core |
+|------|----------------|-------------------|
+| 包名前缀 | `org.dromara.*` | `net.xnzn.core.*` |
+| JDK | 17 | 21 |
+| 请求封装 | 直接 BO | `LeRequest<T>` |
+| 响应封装 | `R<T>`, `TableDataInfo<T>` | `Page<T>`, `void` |
+| 异常类 | `ServiceException` | `LeException` |
+| 国际化 | `MessageUtils.message()` | `I18n.getMessage()` |
+| 权限注解 | `@SaCheckPermission` | `@RequiresAuthentication` |
+| 分页 | `PageQuery`, `TableDataInfo` | `PageDTO`, `Page<VO>` |

package/src/skills/backend-annotations/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: backend-annotations
+description: |
+  后端高级注解使用指南。包含 @RateLimiter、@RepeatSubmit、@Sensitive、@EncryptField、@ApiEncrypt、@DataPermission 等注解的用法。
+
+  触发场景：
+  - 配置接口限流（@RateLimiter）
+  - 配置防重复提交（@RepeatSubmit）
+  - 配置数据脱敏（@Sensitive）
+  - 配置字段加密（@EncryptField）
+  - 配置接口加密（@ApiEncrypt）
+  - 配置数据权限注解（@DataPermission）
+
+  触发词：注解、@RateLimiter、@RepeatSubmit、@Sensitive、@EncryptField、@ApiEncrypt、@DataPermission、@DataColumn、限流、防重复、脱敏、加密、数据权限注解
+---
+
+# 后端高级注解指南
+
+> RuoYi-Vue-Plus 三层架构，包名 `org.dromara.*`
+
+## 注解总览
+
+| 注解 | 机制 | 作用层 | 依赖 |
+|------|------|--------|------|
+| `@RateLimiter` | AOP | Controller 方法 | Redis |
+| `@RepeatSubmit` | AOP | Controller 方法 | Redis + Token |
+| `@Sensitive` | Jackson 序列化器 | VO 字段 | 无 |
+| `@EncryptField` | MyBatis 拦截器 | Entity 字段 | 无 |
+| `@ApiEncrypt` | 拦截器 | Controller 方法 | 无 |
+| `@DataPermission` | AOP | Mapper 接口 | MyBatis |
+
+---
+
+## 1. @RateLimiter - 接口限流
+
+**导入**：`org.dromara.common.ratelimiter.annotation.RateLimiter`
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `key` | String | "" | 限流key，支持SpEL |
+| `time` | int | 60 | 时间窗口（秒） |
+| `count` | int | 100 | 最大请求次数 |
+| `limitType` | LimitType | DEFAULT | DEFAULT/IP/CLUSTER |
+| `message` | String | 国际化key | 错误提示 |
+
+```java
+// 全局限流：60秒100次
+@RateLimiter(time = 60, count = 100)
+@GetMapping("/list")
+public R<List<XxxVo>> list() { }
+
+// IP限流：每个IP每分钟10次（登录、验证码）
+@RateLimiter(time = 60, count = 10, limitType = LimitType.IP)
+@PostMapping("/login")
+public R<String> login() { }
+
+// 动态key：基于用户ID限流
+@RateLimiter(key = "#userId", time = 60, count = 5)
+@PostMapping("/submit")
+public R<Void> submit(Long userId) { }
+```
+
+---
+
+## 2. @RepeatSubmit - 防重复提交
+
+**导入**：`org.dromara.common.idempotent.annotation.RepeatSubmit`
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `interval` | int | 5000 | 间隔时间（毫秒） |
+| `timeUnit` | TimeUnit | MILLISECONDS | 时间单位 |
+| `message` | String | 国际化key | 错误提示 |
+
+```java
+// 默认5秒
+@RepeatSubmit()
+@PostMapping()
+public R<Long> add(@RequestBody OrderBo bo) { }
+
+// 10秒间隔 + 自定义提示
+@RepeatSubmit(interval = 10, timeUnit = TimeUnit.SECONDS, message = "请勿重复提交")
+@PostMapping("/pay")
+public R<Void> pay(@RequestBody PayBo bo) { }
+```
+
+**原理**：`MD5(token + ":" + 序列化参数)` -> Redis 设置/检查 -> 成功保留key防重复 -> 异常删除key允许重试。
+
+---
+
+## 3. @Sensitive - 数据脱敏
+
+**导入**：`org.dromara.common.sensitive.annotation.Sensitive`
+
+### 脱敏策略
+
+| 策略 | 效果 | 策略 | 效果 |
+|------|------|------|------|
+| `ID_CARD` | 110\*\*\*5431 | `PHONE` | 176\*\*\*\*5371 |
+| `EMAIL` | t\*\*@example.com | `BANK_CARD` | 6222\*\*\*2853 |
+| `CHINESE_NAME` | 张\* | `ADDRESS` | 北京市朝阳区\*\*\*\* |
+| `PASSWORD` | \*\*\*\*\*\* | `IPV4` | 192.\*.\*.\* |
+| `FIRST_MASK` | a\*\*\*\*\* | `CLEAR` | "" |
+
+```java
+public class UserVo {
+    // 所有人看脱敏数据
+    @Sensitive(strategy = SensitiveStrategy.PHONE)
+    private String phone;
+
+    // admin 角色可查看原数据
+    @Sensitive(strategy = SensitiveStrategy.ID_CARD, roleKey = {"admin"})
+    private String idCard;
+
+    // 需要权限才能看原数据
+    @Sensitive(strategy = SensitiveStrategy.EMAIL, perms = {"system:user:detail"})
+    private String email;
+}
+```
+
+**权限逻辑**：roleKey 和 perms 都为空 = 全部脱敏；满足任一 roleKey **或** 任一 perms = 可查看原数据（OR 关系）。
+
+---
+
+## 4. @EncryptField - 字段加密
+
+**导入**：`org.dromara.common.encrypt.annotation.EncryptField`
+
+| 算法 | 说明 | 算法 | 说明 |
+|------|------|------|------|
+| `BASE64` | 编码（低安全） | `AES` | 对称加密（推荐） |
+| `RSA` | 非对称（高安全） | `SM2` | 国密非对称 |
+| `SM4` | 国密对称 | | |
+
+```java
+@Data
+@TableName("test_demo")
+public class TestDemo extends BaseEntity {
+    // AES 加密（使用 yml 全局秘钥）
+    @EncryptField(algorithm = AlgorithmType.AES)
+    private String phone;
+
+    // RSA 加密（指定公私钥）
+    @EncryptField(algorithm = AlgorithmType.RSA,
+                 privateKey = "MIICdQ...", publicKey = "MFkwEw...")
+    private String idCard;
+
+    // 使用 yml 默认配置
+    @EncryptField
+    private String secretField;
+}
+```
+
+**配置**：
+
+```yaml
+mybatis-encryptor:
+  enable: false
+  algorithm: BASE64          # 默认算法
+  encode: BASE64             # 编码方式：BASE64 | HEX
+  password: your-secret-16   # AES/SM4 秘钥（16字符）
+  publicKey: MFwwDQ...       # RSA/SM2 公钥
+  privateKey: MIIBVAIBADANBg... # RSA/SM2 私钥
+```
+
+---
+
+## 5. @ApiEncrypt - 接口加密
+
+**导入**：`org.dromara.common.encrypt.annotation.ApiEncrypt`
+
+```java
+// 加密响应数据
+@ApiEncrypt(response = true)
+@GetMapping("/{id}")
+public R<UserVo> getUser(@PathVariable Long id) { }
+```
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `response` | boolean | false | 是否加密响应 |
+
+**配置**：
+
+```yaml
+api-decrypt:
+  enabled: true
+  headerFlag: encrypt-key
+  publicKey: MFwwDQ...       # 响应加密公钥
+  privateKey: MIIBVAIBADANBg... # 请求解密私钥
+```
+
+---
+
+## 6. @DataPermission - 数据权限
+
+**导入**：`org.dromara.common.mybatis.annotation.DataPermission`、`@DataColumn`
+
+```java
+public interface OrderMapper extends BaseMapperPlus<Order, OrderVo> {
+
+    // 按部门+创建人隔离
+    @DataPermission({
+        @DataColumn(key = "deptName", value = "dept_id"),
+        @DataColumn(key = "userName", value = "create_by")
+    })
+    default Page<OrderVo> selectPageOrderList(Page<Order> page, Wrapper<Order> wrapper) {
+        return this.selectVoPage(page, wrapper);
+    }
+
+    // 使用表别名
+    @DataPermission({
+        @DataColumn(key = "deptName", value = "d.dept_id"),
+        @DataColumn(key = "userName", value = "u.create_by")
+    })
+    List<OrderVo> selectWithJoin(@Param(Constants.WRAPPER) Wrapper<Order> wrapper);
+}
+```
+
+**@DataColumn 参数**：
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `key` | "deptName" | 占位符关键字 |
+| `value` | "dept_id" | 替换的字段名 |
+| `permission` | "" | 拥有此权限则不过滤 |
+
+**权限范围**：全部数据 / 本部门 / 本部门及以下 / 仅本人 / 自定义。
+
+---
+
+## 七、组合使用
+
+```java
+// 接口防护：限流 + 防重复 + 日志
+@RateLimiter(time = 60, count = 10, limitType = LimitType.IP)
+@RepeatSubmit(interval = 10, timeUnit = TimeUnit.SECONDS)
+@Log(title = "订单", businessType = BusinessType.INSERT)
+@PostMapping()
+public R<Long> addOrder(@Validated @RequestBody OrderBo bo) { }
+```
+
+```java
+// 数据保护分层：Entity 加密存储 + VO 脱敏展示
+@TableName("sys_user")
+public class SysUser extends TenantEntity {
+    @EncryptField(algorithm = AlgorithmType.AES)
+    private String phone;          // 存储时加密
+}
+
+public class UserVo {
+    @Sensitive(strategy = SensitiveStrategy.PHONE)
+    private String phone;          // 序列化时脱敏
+}
+```
+
+---
+
+## 八、常见错误
+
+```java
+// ❌ @RateLimiter 用在 Service 方法上（无效，只能 Controller）
+@Service
+public class XxxService {
+    @RateLimiter(...)  // 无效！
+    public void doSomething() { }
+}
+
+// ❌ @DataPermission 未配置 @DataColumn
+@DataPermission  // 空注解无效！
+public interface UserMapper { }
+
+// ❌ @Sensitive 用在 Entity 上（应在 VO 上）
+// ❌ @EncryptField 用在 VO 上（应在 Entity 上）
+
+// ✅ @DataPermission 支持类级别 + 方法级别（方法覆盖类）
+@DataPermission({ @DataColumn(key = "deptName", value = "dept_id") })
+public interface UserMapper {
+    @DataPermission({ /* 方法级覆盖 */ })
+    List<UserVo> selectList();
+}
+```
+
+---
+
+## 九、参考实现
+
+| 类型 | 位置 |
+|------|------|
+| 限流示例 | `org.dromara.demo.controller.RedisRateLimiterController` |
+| 脱敏示例 | `org.dromara.demo.controller.TestSensitiveController` |
+| 加密示例 | `org.dromara.demo.domain.TestDemo` |
+| 数据权限 | `org.dromara.system.mapper.SysUserMapper` |
+
+**配置位置**：
+
+```
+application.yml:
+  mybatis-encryptor.*  → @EncryptField 全局配置
+  api-decrypt.*        → @ApiEncrypt 全局配置
+  spring.data.redis.*  → @RateLimiter/@RepeatSubmit 依赖
+```

package/src/skills/banana-image/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-12-22
+
+### Added
+
+- Initial release of Banana Image skill
+- **Dual model support**: Flash (fast) and Pro (4K high-quality)
+- **Image generation** with customizable parameters:
+  - Aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4, 4:5, 5:4, 2:3, 3:2, 21:9
+  - Resolutions: 1K, 2K, 4K (Pro model only for 4K)
+  - Negative prompts for content exclusion
+  - Batch generation (1-4 images)
+- **Image editing mode** - modify existing images with text prompts
+- **Proxy support** via undici for corporate network environments
+- **Google Search grounding** for Pro model
+- **Template system** with predefined configurations:
+  - Product photography
+  - Social media posts
+  - Posters
+  - Thumbnails
+- CLI interface with comprehensive options
+- JSON output format for easy integration
+- Claude Code skill integration
+
+### Technical Details
+
+- Models:
+  - Flash: `gemini-2.5-flash-image`
+  - Pro: `gemini-3-pro-image-preview`
+- Default output: `./images` directory
+- Supported input formats: PNG, JPG, JPEG, GIF, WebP