leniu-dev 2.0.0

package/.codex/skills/auto-test/references/api-conventions.md

@@ -0,0 +1,260 @@
+# 系统接口请求响应规范（详细参考）
+
+> 本文件定义了 leniu 系统的标准接口契约。生成测试用例时**必须严格匹配**这些模式。
+> 安装框架后可直接使用，无需额外学习。
+
+## 统一请求格式
+
+所有 POST 接口使用 `LeRequest<T>` 封装，业务参数放在 `content` 字段内：
+
+```json
+{
+  "content": { /* 业务参数 */ }
+}
+```
+
+## 统一响应格式
+
+```json
+{
+  "code": 10000,       // 业务码：10000=成功，其他=失败
+  "msg": "操作成功",    // 提示信息
+  "data": ...          // 业务数据（类型取决于接口）
+}
+```
+
+## 接口类型与响应模式速查
+
+根据 Controller 方法返回值类型，确定 data 的结构和对应断言：
+
+| Controller 返回类型 | data 类型 | 示例 | Hurl 断言模板 |
+|---------------------|----------|------|--------------|
+| `Long` | 雪花 ID | `$.data` = 1234567890 | `jsonpath "$.data" isInteger` |
+| `void` | null | `$.data` = null | `jsonpath "$.code" == 10000` |
+| `XxxVO` | 对象 | `$.data.id`, `$.data.name` | `jsonpath "$.data.id" exists` |
+| `PageVO<XxxVO>` | 分页对象 | `$.data.records[0]` | 见「标准分页」 |
+| `ReportBaseTotalVO<XxxVO>` | 分页+合计 | `$.data.resultPage` + `$.data.totalLine` | 见「报表分页」 |
+
+## 标准分页响应（PageVO）
+
+**适用于**：设置类 CRUD 分页查询（如凭证类型、凭证字）
+
+```json
+{
+  "code": 10000,
+  "data": {
+    "records": [ { "id": 1, "name": "..." }, ... ],
+    "current": 1,
+    "size": 10,
+    "total": 25
+  }
+}
+```
+
+**Hurl 断言模板**：
+
+```hurl
+HTTP 200
+[Asserts]
+jsonpath "$.code" == 10000
+jsonpath "$.data.records" isCollection
+jsonpath "$.data.current" exists
+jsonpath "$.data.size" exists
+jsonpath "$.data.total" exists
+# VO 字段逐一验证
+jsonpath "$.data.records[0].id" exists
+jsonpath "$.data.records[0].typeName" isString
+```
+
+## 报表分页响应（ReportBaseTotalVO）
+
+**适用于**：报表类分页查询（凭证列表、科目明细、科目汇总），响应包含 `resultPage`（分页数据）+ `totalLine`（合计行）
+
+```json
+{
+  "code": 10000,
+  "data": {
+    "resultPage": {
+      "records": [ { ... }, ... ],
+      "current": 1,
+      "size": 10,
+      "total": 25
+    },
+    "totalLine": {
+      "debitAmount": 1285100,
+      "creditAmount": 1285000
+    }
+  }
+}
+```
+
+**Hurl 断言模板**：
+
+```hurl
+HTTP 200
+[Asserts]
+jsonpath "$.code" == 10000
+# 分页结构
+jsonpath "$.data.resultPage" exists
+jsonpath "$.data.resultPage.records" isCollection
+jsonpath "$.data.resultPage.current" exists
+jsonpath "$.data.resultPage.size" exists
+jsonpath "$.data.resultPage.total" exists
+# VO 字段逐一验证（首条记录）
+jsonpath "$.data.resultPage.records[0].voucherDate" isString
+jsonpath "$.data.resultPage.records[0].areaName" isString
+jsonpath "$.data.resultPage.records[0].costTypeName" isString  # 关联字段不能为 null
+# 合计行（只有数值字段和方向字段，其余为 null 占位）
+jsonpath "$.data.totalLine" exists
+jsonpath "$.data.totalLine.debitAmount" exists
+jsonpath "$.data.totalLine.creditAmount" exists
+```
+
+## 各操作类型的请求与响应模式
+
+### 1. 新增（save）→ 返回 Long ID
+
+```hurl
+# Controller: Long save(LeRequest<XxxSaveParam>)
+POST {{base_url}}/report/finance/voucher/save
+Content-Type: application/json
+X-Token: {{x_token}}
+merchant-id: {{merchant_id}}
+Merchant-Id: {{merchant_id_auth}}
+{
+  "content": {
+    "areaId": {{area_id}},
+    "name": "auto-test数据，可删除",
+    "entries": [ ... ]
+  }
+}
+
+HTTP 200
+[Asserts]
+jsonpath "$.code" == 10000
+[Captures]
+created_id: jsonpath "$.data"    # 捕获返回的 ID 供后续使用
+```
+
+### 2. 编辑（save 带 id / update）→ 返回 void
+
+```hurl
+# 方式一：save 带 id（delete-insert 模式，常用于主子表）
+POST {{base_url}}/report/finance/voucher/save
+{ "content": { "id": {{created_id}}, "name": "修改后", ... } }
+
+# 方式二：独立 update 接口
+POST {{base_url}}/report/finance/setting/voucher-type/update
+{ "content": { "id": {{type_id}}, "typeName": "修改后" } }
+
+HTTP 200
+[Asserts]
+jsonpath "$.code" == 10000
+```
+
+### 3. 查详情（detail）→ 返回 XxxVO 对象
+
+```hurl
+# Controller: XxxDetailVO detail(LeRequest<Long>)
+# 注意：content 直接传 ID 值（Long），不需要包装对象
+POST {{base_url}}/report/finance/voucher/detail
+{ "content": {{created_id}} }
+
+HTTP 200
+[Asserts]
+jsonpath "$.code" == 10000
+jsonpath "$.data.id" exists
+jsonpath "$.data.areaName" isString
+jsonpath "$.data.entries" isCollection      # 子表数据
+jsonpath "$.data.entries" count == 2
+jsonpath "$.data.entries[0].id" exists
+```
+
+### 4. 删除（delete）→ 返回 void
+
+```hurl
+# Controller: void delete(LeRequest<Long>)
+# 注意：content 直接传 ID 值（Long）
+POST {{base_url}}/report/finance/voucher/delete
+{ "content": {{created_id}} }
+
+HTTP 200
+[Asserts]
+jsonpath "$.code" == 10000
+```
+
+### 5. 提交/审批等状态变更 → 返回 void
+
+```hurl
+# Controller: void submit(LeRequest<Long>)
+POST {{base_url}}/report/finance/voucher/submit
+{ "content": {{created_id}} }
+
+HTTP 200
+[Asserts]
+jsonpath "$.code" == 10000
+```
+
+### 6. 分页查询（page）→ 返回 PageVO 或 ReportBaseTotalVO
+
+```hurl
+# 标准分页（设置类）
+POST {{base_url}}/report/finance/setting/voucher-type/page
+{
+  "content": {
+    "page": { "current": 1, "size": 10 }
+  }
+}
+
+# 报表分页（含合计行）
+POST {{base_url}}/report/finance/voucher/page
+{
+  "content": {
+    "page": { "current": 1, "size": 10 },
+    "startDate": "2026-03-01",
+    "endDate": "2026-03-31"
+  }
+}
+```
+
+### 7. 导出（export）→ 返回 void（异步）
+
+```hurl
+# Controller: void export(LeRequest<XxxPageParam>)
+# 异步导出，仅验证接口不报错
+POST {{base_url}}/report/finance/voucher/export
+{
+  "content": {
+    "page": { "current": 1, "size": 10 },
+    "startDate": "2026-03-01",
+    "endDate": "2026-03-31"
+  }
+}
+
+HTTP 200
+[Asserts]
+jsonpath "$.code" == 10000
+```
+
+### 8. 未授权测试 → 预期 HTTP 401
+
+```hurl
+# 去掉 X-Token 请求头
+POST {{base_url}}/report/finance/voucher/page
+Content-Type: application/json
+merchant-id: {{merchant_id}}
+Merchant-Id: {{merchant_id_auth}}
+{ "content": { "page": { "current": 1, "size": 10 } } }
+
+HTTP 401
+```
+
+## content 传值类型总结
+
+| 场景 | content 类型 | 示例 |
+|------|-------------|------|
+| 分页查询 | 对象（含 page + 查询条件） | `{"page":{"current":1,"size":10},"keyword":"xxx"}` |
+| 新增/编辑 | 对象（业务字段） | `{"name":"xxx","entries":[...]}` |
+| 查详情/删除/提交 | **裸 Long** | `{{id}}` （不是 `{"id": {{id}}}`） |
+
+> **关键区别**：detail/delete/submit 的 content 是**直接传 ID 值**，不需要包装成对象。这是最常见的错误。

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

@@ -0,0 +1,248 @@
+---
+name: backend-annotations
+description: |
+  通用后端高级注解指南。包含限流、防重复提交、数据脱敏、字段加密、接口加密等横切关注点的 AOP 实现模式。
+  触发场景：
+  - 配置接口限流
+  - 配置防重复提交
+  - 配置数据脱敏
+  - 配置字段加密 / 接口加密
+  触发词：注解、限流、防重复提交、脱敏、加密、RateLimiter、Idempotent、Sensitive、Encrypt、AOP
+  注意：如果项目有专属技能（如 `leniu-backend-annotations`），优先使用专属版本。
+---
+
+# 后端高级注解开发指南
+
+> 通用模板。如果项目有专属技能（如 `leniu-backend-annotations`），优先使用。
+
+## 设计原则
+
+1. **横切关注点用 AOP**：限流、防重复、脱敏、加密属于非功能性需求，应通过注解 + AOP/拦截器实现，不侵入业务代码。
+2. **分层职责清晰**：限流/防重复作用于 Controller 层；脱敏作用于 VO 序列化层；加密作用于持久化层。
+3. **声明式优于编程式**：用注解声明意图，框架自动执行，减少样板代码。
+4. **配置外置**：密钥、阈值等参数放在配置文件或配置中心，不硬编码。
+
+---
+
+## 实现模式
+
+### 1. 接口限流
+
+**概念**：通过 AOP 拦截请求，基于 Redis/内存计数器控制单位时间内的请求次数。
+
+```java
+// 自定义注解
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface RateLimiter {
+    String key() default "";          // 限流key，支持 SpEL
+    int time() default 60;            // 时间窗口（秒）
+    int count() default 100;          // 最大请求次数
+    LimitType limitType() default LimitType.DEFAULT; // DEFAULT / IP / CLUSTER
+    String message() default "请求过于频繁";
+}
+
+// AOP 切面
+@Aspect
+@Component
+public class RateLimiterAspect {
+
+    @Autowired
+    private StringRedisTemplate redisTemplate;
+
+    @Around("@annotation([你的包名].annotation.RateLimiter)")
+    public Object around(ProceedingJoinPoint point) throws Throwable {
+        RateLimiter limiter = /* 获取注解 */;
+        String key = buildKey(limiter, point);
+        // 使用 Redis Lua 脚本做原子计数
+        Long count = redisTemplate.execute(rateLimiterScript, List.of(key),
+            String.valueOf(limiter.count()), String.valueOf(limiter.time()));
+        if (count != null && count > limiter.count()) {
+            throw new [你的异常类](limiter.message());
+        }
+        return point.proceed();
+    }
+}
+```
+
+**推荐阈值参考**：
+
+| 场景 | 时间窗口 | 次数 | 限流类型 |
+|------|---------|------|---------|
+| 登录接口 | 60s | 5-10 | IP |
+| 验证码 | 60s | 3 | IP |
+| 查询接口 | 60s | 100-1000 | DEFAULT |
+| 写入接口 | 60s | 10-50 | DEFAULT |
+| 敏感操作 | 60s | 1-5 | IP |
+
+---
+
+### 2. 防重复提交
+
+**概念**：在指定时间窗口内，相同用户的相同请求（基于 Token + 参数哈希）只允许提交一次。
+
+```java
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface RepeatSubmit {
+    int interval() default 5000;       // 间隔时间（毫秒）
+    TimeUnit timeUnit() default TimeUnit.MILLISECONDS;
+    String message() default "请勿重复提交";
+}
+
+// AOP 切面核心逻辑
+// 1. 从请求中提取 Token + 请求参数
+// 2. 计算 MD5(token + ":" + serialize(params))
+// 3. Redis SETNX，设置过期时间 = interval
+// 4. 设置成功 -> 允许请求；设置失败 -> 拒绝
+// 5. 请求异常时删除 key，允许重试
+```
+
+| 场景 | 推荐间隔 |
+|------|---------|
+| 普通表单 | 3-5 秒 |
+| 订单创建 | 10 秒 |
+| 支付操作 | 30 秒 |
+| 文件上传 | 10 秒 |
+
+---
+
+### 3. 数据脱敏
+
+**概念**：在 JSON 序列化阶段，对 VO 中的敏感字段进行掩码处理。通过自定义 Jackson 序列化器实现。
+
+```java
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+@JacksonAnnotationsInside
+@JsonSerialize(using = SensitiveSerializer.class)
+public @interface Sensitive {
+    SensitiveStrategy strategy();
+    String[] roleKey() default {};    // 拥有这些角色可查看原文
+    String[] perms() default {};       // 拥有这些权限可查看原文
+}
+
+public enum SensitiveStrategy {
+    ID_CARD(s -> s.substring(0, 3) + "***" + s.substring(s.length() - 4)),
+    PHONE(s -> s.substring(0, 3) + "****" + s.substring(s.length() - 4)),
+    EMAIL(s -> s.charAt(0) + "**@" + s.substring(s.indexOf('@') + 1)),
+    CHINESE_NAME(s -> s.charAt(0) + "*".repeat(s.length() - 1)),
+    BANK_CARD(s -> s.substring(0, 4) + "****" + s.substring(s.length() - 4)),
+    PASSWORD(s -> "******");
+
+    private final Function<String, String> desensitizer;
+    // constructor, getter...
+}
+
+// 使用
+public class UserVo {
+    @Sensitive(strategy = SensitiveStrategy.PHONE)
+    private String phone;
+
+    @Sensitive(strategy = SensitiveStrategy.ID_CARD, roleKey = {"admin"})
+    private String idCard;
+}
+```
+
+**权限逻辑**：roleKey 和 perms 都为空 = 全部脱敏；满足任一条件 = 可查看原文（OR 关系）。
+
+---
+
+### 4. 字段加密（持久层）
+
+**概念**：通过 MyBatis 拦截器/TypeHandler，在数据写入数据库时自动加密，读取时自动解密。对业务代码透明。
+
+```java
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface EncryptField {
+    AlgorithmType algorithm() default AlgorithmType.DEFAULT; // 使用全局配置
+    String password() default "";    // AES/SM4 密钥
+    String publicKey() default "";   // RSA/SM2 公钥
+    String privateKey() default "";  // RSA/SM2 私钥
+}
+
+public enum AlgorithmType {
+    DEFAULT, BASE64, AES, RSA, SM2, SM4
+}
+```
+
+**配置示例**：
+
+```yaml
+# [你的加密配置前缀]:
+encrypt:
+  enable: true
+  algorithm: AES
+  password: your-secret-key-16ch   # AES/SM4 密钥（16字符）
+  public-key: MFkwEw...            # RSA/SM2 公钥
+  private-key: MIIBVAIBADANBg...   # RSA/SM2 私钥
+```
+
+---
+
+### 5. 接口加密（传输层）
+
+**概念**：通过 Filter/Interceptor，对 HTTP 请求体自动解密、响应体自动加密。适用于前后端通信加密。
+
+```java
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface ApiEncrypt {
+    boolean response() default false; // 是否加密响应
+}
+
+// 在 RequestBodyAdvice / ResponseBodyAdvice 中拦截处理
+// 或通过 Filter + HttpServletRequestWrapper 实现
+```
+
+---
+
+## 选型建议
+
+| 关注点 | 实现方式 | 作用层 | 依赖 |
+|--------|---------|--------|------|
+| 限流 | AOP + Redis Lua 脚本 | Controller | Redis |
+| 防重复 | AOP + Redis SETNX | Controller | Redis + Token |
+| 脱敏 | Jackson 自定义序列化器 | VO 字段 | 无 |
+| 字段加密 | MyBatis 拦截器 / TypeHandler | Entity 字段 | 加密库 |
+| 接口加密 | Filter / RequestBodyAdvice | Controller 方法 | 加密库 |
+
+| 加密算法 | 类型 | 密钥要求 | 适用场景 |
+|---------|------|---------|---------|
+| BASE64 | 编码（非加密） | 无 | 简单混淆 |
+| AES | 对称加密 | 16/24/32 字节 | 通用加密（推荐） |
+| RSA | 非对称加密 | 公钥/私钥对 | 高安全场景 |
+| SM4 | 国密对称 | 16 字节 | 国密合规 |
+| SM2 | 国密非对称 | 公钥/私钥对 | 国密合规 |
+
+---
+
+## 常见错误
+
+```java
+// 1. 限流/防重复注解放在 Service 方法上（无效，应在 Controller）
+@Service
+public class XxxService {
+    @RateLimiter(...)  // 无效！AOP 通常只拦截 Controller
+    public void doSomething() { }
+}
+
+// 2. @Sensitive 用在 Entity 上（应在 VO 上，序列化时生效）
+// 3. @EncryptField 用在 VO 上（应在 Entity 上，持久化时生效）
+
+// 4. 加密密钥硬编码在注解中
+@EncryptField(password = "my-secret-key")  // 不安全
+// 应使用全局配置或环境变量
+
+// 5. 限流 key 设计不合理
+@RateLimiter(key = "")  // 所有用户共享限流
+// 应根据场景选择：用户维度 key="#userId"，IP 维度 limitType=IP
+
+// 6. 组合注解顺序不当
+// 推荐顺序：限流 -> 防重复 -> 权限 -> 日志
+@RateLimiter(time = 60, count = 10)
+@RepeatSubmit(interval = 5000)
+@PostMapping()
+public Result<?> add(@RequestBody XxxDTO dto) { }
+```

package/.codex/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

package/.codex/skills/banana-image/README.md

@@ -0,0 +1,146 @@
+<p align="center">
+  <img src="assets/logo.png" alt="Banana Image Logo" width="280">
+</p>
+
+<h1 align="center">Banana Image</h1>
+
+<p align="center">
+  <strong>AI-Powered Image Generation Tool for Claude Code</strong>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#usage">Usage</a> •
+  <a href="#models">Models</a> •
+  <a href="#examples">Examples</a>
+</p>
+
+---
+
+## Features
+
+- **Dual Model Support** - Flash (fast) and Pro (high-quality 4K)
+- **Flexible Aspect Ratios** - 1:1, 16:9, 9:16, 4:3, 2:3, 21:9, and more
+- **Image Editing** - Modify existing images with text prompts
+- **Batch Generation** - Generate up to 4 variants at once
+- **Proxy Support** - Works behind corporate firewalls
+- **Claude Code Integration** - Seamless skill integration
+
+## Installation
+
+### 1. Set API Key
+
+```bash
+export GEMINI_API_KEY="your-api-key"
+```
+
+### 2. Install Dependencies
+
+```bash
+cd ~/.claude/skills/banana-image/scripts
+npm install
+```
+
+## Usage
+
+### Quick Start
+
+```bash
+# Fast generation (Flash model)
+npx tsx ~/.claude/skills/banana-image/scripts/banana_image_exec.ts \
+  -p "A cute shiba inu in the park" -m flash
+
+# 4K high-quality (Pro model)
+npx tsx ~/.claude/skills/banana-image/scripts/banana_image_exec.ts \
+  -p "Professional product photo: iPhone case" -m pro -r 4K -a 4:5
+```
+
+### CLI Options
+
+| Option               | Description                     | Default          |
+| -------------------- | ------------------------------- | ---------------- |
+| `-p, --prompt`       | Image description (required)    | -                |
+| `-m, --model`        | Model: `flash` or `pro`         | `pro`            |
+| `-a, --aspect-ratio` | Ratio: 1:1, 16:9, 9:16, etc.    | `1:1`            |
+| `-r, --resolution`   | Resolution: 1K, 2K, 4K          | Pro=4K, Flash=1K |
+| `-o, --output`       | Output directory                | `./images`       |
+| `-n, --negative`     | Negative prompt                 | -                |
+| `-i, --input`        | Input image (edit mode)         | -                |
+| `-c, --count`        | Number of images (1-4)          | `1`              |
+| `-g, --grounding`    | Enable Google Search (Pro only) | `false`          |
+
+## Models
+
+| Model     | Speed  | Max Resolution | Best For                                |
+| --------- | ------ | -------------- | --------------------------------------- |
+| **Flash** | 2-5s   | 1024px         | Drafts, iterations, prototypes          |
+| **Pro**   | 10-40s | 4K             | Final delivery, marketing, professional |
+
+## Examples
+
+### Image Generation
+
+```bash
+# 16:9 landscape poster
+npx tsx banana_image_exec.ts -p "Sunset over mountains" -m pro -r 4K -a 16:9
+
+# Portrait for social media
+npx tsx banana_image_exec.ts -p "Product showcase" -m pro -a 9:16
+```
+
+### Image Editing
+
+```bash
+# Edit existing image
+npx tsx banana_image_exec.ts -p "Change background to beach sunset" -i ./photo.png
+```
+
+### Batch Generation
+
+```bash
+# Generate 4 variants
+npx tsx banana_image_exec.ts -p "Logo design concept" -m pro -c 4
+```
+
+## Output
+
+```json
+{
+  "success": true,
+  "images": [
+    {
+      "path": "./images/banana_pro_2025-01-01T12-00-00_abc123.png",
+      "model": "gemini-3-pro-image-preview",
+      "prompt": "Your prompt"
+    }
+  ],
+  "metadata": {
+    "model": "gemini-3-pro-image-preview",
+    "aspectRatio": "16:9",
+    "resolution": "4K",
+    "duration": 15234
+  }
+}
+```
+
+## Aspect Ratio Guide
+
+| Use Case            | Ratio | Keywords                   |
+| ------------------- | ----- | -------------------------- |
+| Social media square | 1:1   | Instagram, profile         |
+| Landscape banner    | 16:9  | YouTube, desktop wallpaper |
+| Portrait story      | 9:16  | Stories, mobile wallpaper  |
+| Product photo       | 4:5   | E-commerce, catalog        |
+| Movie poster        | 2:3   | Poster, print              |
+| Ultra-wide          | 21:9  | Banner, header             |
+
+## Requirements
+
+- Node.js 18+
+- Gemini API Key
+- Network access (proxy supported)
+
+## License
+
+MIT