Merge pull request #27 from TrueNine/dev

🚀 [release] 0.0.23

Author: TrueNine

.augment/rules/global-convention.md

@@ -4,62 +4,56 @@ type: "always_apply"
 
 # 通用标准
 
+在开始实现任何功能之前，请将任务拆解为更小的模块，并逐步编写代码。每写一小部分代码后，务必进行单元测试验证，确保其正确性和稳定性。即使用户给出的需求很复杂，也请始终保持渐进式开发，逐步完成，并通过测试及时发现并解决问题。避免一次性编写大量代码，以便尽早识别潜在的错误和问题。保持代码的高质量和稳定性，逐步积累完成整个任务。
+
 **强制规则**
 
-1.
-在开始实现任何功能之前，请将任务拆解为更小的模块，并逐步编写代码。每写一小部分代码后，务必进行单元测试验证，确保其正确性和稳定性。即使用户给出的需求很复杂，也请始终保持渐进式开发，逐步完成，并通过测试及时发现并解决问题。避免一次性编写大量代码，以便尽早识别潜在的错误和问题。保持代码的高质量和稳定性，逐步积累完成整个任务。
-2. 始终使用**简体中文**回复，即使用户输入大量英文提示，也应返回简体中文
-3. 禁止编写任何供用户使用的示例代码，即使需要临时测试，任务完成后也必须立即删除
-4. 严禁通过简化问题来解决问题
-5. 严禁通过降级依赖版本来解决问题
-6. 严禁通过减少测试断言来解决问题
-7. 严禁忽略异常或任何隐藏异常的行为
+1. 始终使用**简体中文**回复，即使用户输入大量英文提示，也应返回简体中文
+2. 禁止编写任何供用户使用的示例代码，即使需要临时测试，任务完成后也必须立即删除
+3. 严禁通过简化问题来解决问题
+4. 严禁通过降级依赖版本来解决问题
+5. 严禁通过减少测试断言来解决问题
+6. 严禁忽略异常或任何隐藏异常的行为
+7. 严禁在代码中暴露 API 密钥、密码和令牌
 8. 应当积极按照规则来重构修复上下文中出现的代码
 9. 严禁在代码中暴露 API 密钥、密码和令牌
 10. 应积极使用日志完善记录，主动补充缺失的日志
 11. 允许在单元测试调试期间添加日志以协助解决问题
 12. 必须最大化使用 `early return` 技术来减少代码嵌套层级
 13. 严禁在对话或任务完成后生成总结文档文件和其他不必要的操作
 14. 严禁出现 `util`,`utils`,`tool` 等的让我恶心的命名方式以及命名空间
-15. 严禁使用 `@Suppress` 注解压制警告
-
-**输出规则**
-
-- **优先简洁直接的回复** - 避免冗长解释
-- **批量相关工具调用** - 将多个信息请求合并为单次调用
-- **使用高效工具序列** - 最小化冗余调用
+15. 严禁使用 `@Suppress`/`// @ts-ignore` 等注解压制警告
 
 **注释规则**
 
-- 文档注释：英文注释
-- 代码内部注释：英文注释，且解释"为什么"而非"做什么"
+- 文档注释：必须使用英文注释
+- 代码内部注释：必须使用中文注释
+- 严禁使用行尾注释
 
-**TDD 约定**
+**TDD渐进式开发方法论**
 
-1. TDD流程：失败测试→实现代码→重构
-2. 覆盖边界条件和异常情况
-3. 独立运行，无外部依赖
-4. 测试命名清晰表达意图
-5. 测试类与被测试类同名
-6. **嵌套测试组织**：使用合适的分组，避免根级别大量独立测试方法
-7. 严禁出现没有断言的测试方法，发现应该立即补全断言
+- 采用测试驱动开发结合渐进式开发方法
+- **Baby Steps开发**：每次只编写少量代码，立即进行单元测试验证
+- **快速反馈循环**：开发一点测试一点，绝不一次性编写大量代码
+- **逐个验证原则**：为多个代码编写单元测试时，一个个编写一个个验证，避免批量编写后统一验证
+- **风险最小化**：通过频繁的小幅度验证确保代码质量，避免错误累积
+- **嵌套测试组织**：使用合适的分组，避免根级别大量独立测试方法
+- 严禁出现没有断言的测试方法，发现应该立即补全断言
 
 **测试组织最佳实践：**
 
 - 每个被测试类/函数/变量/方法创建主要分组
 - 按场景细分：正常用例、异常用例、边界用例
-- 示例kotlin：`@Nested inner class CreateUser { @Test fun should_create_successfully() {} }`
+  + 示例kotlin：`@Nested inner class CreateUser { @Test fun should_create_successfully() {} }`
 - 测试方法命名使用反引号包围的中文描述：`fun \`测试用户创建成功\`()`
 - 禁止使用 `@DisplayName` 注解
 
 # 特定语言约定
 
 **SQL 标准**
 
-1. 检查现有查询是否使用参数化
-2. 统一使用snake_case命名
-3. 验证无字符串拼接风险
-4. 应尽量使用小写来编写SQL
+- 检查现有查询是否使用参数化
+- 统一使用 snake_case 命名，即使是出现在其他语言中的字符串
 
 **JVM 标准**
 
@@ -82,10 +76,9 @@ type: "always_apply"
 4. 严禁使用 `println` 记录输出
 5. 严禁在单元测试中使用 `mockito`，而是使用 `mockk`
 
-**TypeScript 和 Vue 标准**
+**TypeScript标准**
 
 - TypeScript: 启用strict模式，避免any类型
-- Vue: 积极使用 vue3 新特性
 
 **SCSS 标准**
 

.cursor/rules/ai-integration.mdc

@@ -0,0 +1,55 @@
+---
+globs: **/ai/**/*.kt,**/*AI*.kt,**/*LangChain*.kt
+---
+
+# AI Integration Guidelines
+
+Standards for AI-related modules and LangChain4j integration.
+
+## AI Module Structure
+- **Shared abstractions**: Use [ai/ai-shared/](mdc:ai/ai-shared/) for common interfaces
+- **LangChain4j integration**: Implement via [ai/ai-langchain4j/](mdc:ai/ai-langchain4j/)
+- **Model abstractions**: Support multiple AI providers
+- **Configuration**: Externalize model settings and API keys
+
+## LangChain4j Integration
+- **Version**: Use version from [gradle/libs.versions.toml](mdc:gradle/libs.versions.toml)
+- **Chain building**: Use fluent API for complex workflows
+- **Memory management**: Implement conversation memory appropriately
+- **Tool integration**: Create tools for external system integration
+
+## AI Service Design
+- **Interface-based**: Define clear service interfaces
+- **Async operations**: Use coroutines for long-running AI operations
+- **Error handling**: Graceful degradation for AI service failures
+- **Rate limiting**: Implement to respect API limits
+
+## Model Configuration
+- **Multiple providers**: Support OpenAI, Ollama, local models
+- **Model selection**: Runtime model switching capability
+- **Parameter tuning**: Externalize temperature, max tokens, etc.
+- **Fallback models**: Implement fallback strategies
+
+## Security Considerations
+- **API key management**: Never hardcode API keys
+- **Input sanitization**: Validate and sanitize user inputs
+- **Output filtering**: Filter potentially harmful AI responses
+- **Audit logging**: Log AI interactions for compliance
+
+## Testing AI Components
+- **Mock AI responses**: Use deterministic responses for unit tests
+- **Integration tests**: Test with real AI services in CI/CD
+- **Performance tests**: Measure response times and throughput
+- **Accuracy tests**: Validate AI output quality
+
+## Prompt Engineering
+- **Template management**: Centralize prompt templates
+- **Version control**: Track prompt changes
+- **A/B testing**: Support prompt experimentation
+- **Localization**: Support multiple languages
+
+## Data Handling
+- **Privacy compliance**: Handle PII appropriately
+- **Data retention**: Implement retention policies
+- **Anonymization**: Remove sensitive data from training
+- **Consent management**: Track user consent for AI processing

.cursor/rules/database-patterns.mdc

@@ -0,0 +1,48 @@
+---
+globs: **/rds/**/*.kt,**/*Repository.kt,**/*Entity.kt,**/migration/**/*.sql
+---
+
+# Database & Persistence Patterns
+
+Standards for working with Jimmer ORM, Flyway migrations, and database operations.
+
+## Jimmer ORM Conventions
+- **Base classes**: Extend from [rds/rds-shared/](mdc:rds/rds-shared/) base entities
+- **Entity definitions**: Use Jimmer annotations and Kotlin data classes
+- **Repository patterns**: Follow [rds/rds-crud/](mdc:rds/rds-crud/) CRUD implementations
+- **Query optimization**: Leverage Jimmer's compile-time query generation
+
+## Database Migrations
+- **PostgreSQL**: Use [rds/rds-flyway-migration-postgresql/](mdc:rds/rds-flyway-migration-postgresql/)
+- **MySQL**: Use [rds/rds-flyway-migration-mysql8/](mdc:rds/rds-flyway-migration-mysql8/)
+- **Shared utilities**: Leverage [rds/rds-flyway-migration-shared/](mdc:rds/rds-flyway-migration-shared/)
+
+## SQL Standards
+- **Use lowercase** for SQL keywords and identifiers
+- **snake_case naming** for tables and columns
+- **Parameterized queries only** - no string concatenation
+- **Verify no SQL injection risks** in all queries
+
+## Entity Design
+- **Immutable entities** where possible using `val` properties
+- **Proper relationships** using Jimmer associations
+- **Validation annotations** for data integrity
+- **Audit fields** for tracking changes
+
+## Repository Patterns
+- **Interface-based repositories** for testability
+- **Transaction boundaries** clearly defined
+- **Error handling** with meaningful exceptions
+- **Pagination support** for large datasets
+
+## Testing Database Code
+- **Use TestContainers** for integration tests via [testtoolkit/](mdc:testtoolkit/)
+- **Test migrations** in isolated environments
+- **Verify data integrity** constraints
+- **Test rollback scenarios** for critical operations
+
+## Performance Considerations
+- **Lazy loading** configuration for associations
+- **Query optimization** using Jimmer's features
+- **Connection pooling** via HikariCP
+- **Index strategies** for frequently queried fields

.cursor/rules/development-workflow.mdc

@@ -0,0 +1,57 @@
+---
+description: General development workflow and best practices
+---
+
+# Development Workflow
+
+General development practices and workflow guidelines based on [docs/GLOBAL_CLAUDE.md](mdc:docs/GLOBAL_CLAUDE.md).
+
+## Development Process
+1. **Task breakdown**: Split complex tasks into smaller modules
+2. **Incremental development**: Write small code portions with immediate testing
+3. **TDD approach**: Test-driven development with red-green-refactor cycle
+4. **Code review**: Ensure code quality and adherence to standards
+
+## Code Quality Standards
+- **Early return**: Maximize use to reduce nesting levels
+- **Meaningful names**: Avoid abbreviations, use descriptive names
+- **Single responsibility**: Functions and classes should have one purpose
+- **Immutability**: Prefer immutable data structures and `val` declarations
+
+## Forbidden Practices
+- **No example code**: Never write user-facing example code
+- **No problem simplification**: Don't solve problems by reducing complexity
+- **No dependency downgrades**: Don't solve issues by downgrading versions
+- **No test assertion reduction**: Don't reduce test coverage to fix issues
+- **No exception hiding**: Never ignore or suppress exceptions
+- **No sensitive data exposure**: Never commit API keys, passwords, tokens
+
+## Logging Standards
+- **Comprehensive logging**: Add detailed logging for debugging and monitoring
+- **Structured logging**: Use consistent log formats
+- **No println**: Use proper logging framework, never `println` or `System.out.println`
+- **Debug logs**: Allowed during development, remove after completion
+
+## Documentation Requirements
+- **English comments**: Use English for all code documentation
+- **Explain why**: Comments should explain reasoning, not what code does
+- **KDoc**: Document all public APIs
+- **No auto-generated docs**: Don't create summary documents automatically
+
+## Error Handling
+- **Proper exception handling**: Never ignore exceptions
+- **Meaningful error messages**: Provide context for debugging
+- **Graceful degradation**: Handle failures appropriately
+- **Logging errors**: Log errors with sufficient context
+
+## Performance Considerations
+- **Lazy loading**: Use where appropriate
+- **Resource management**: Proper cleanup of resources
+- **Caching strategies**: Implement appropriate caching
+- **Database optimization**: Efficient queries and indexing
+
+## Security Mindset
+- **Input validation**: Validate all external inputs
+- **Output encoding**: Prevent injection attacks
+- **Secure defaults**: Use secure configurations by default
+- **Regular updates**: Keep dependencies updated for security patches

.cursor/rules/gradle-build-conventions.mdc

@@ -0,0 +1,62 @@
+---
+globs: *.gradle.kts,gradle/**/*,**/build.gradle.kts
+---
+
+# Gradle Build Conventions
+
+Standards for Gradle build scripts and dependency management.
+
+## Build Script Structure
+- **Kotlin DSL**: Use `.gradle.kts` for all build scripts
+- **Version Catalog**: Reference [gradle/libs.versions.toml](mdc:gradle/libs.versions.toml) for all dependencies
+- **Build Logic**: Custom conventions in [build-logic/](mdc:build-logic/) directory
+- **Type-safe accessors**: Leverage `libs.` and `projects.` accessors
+
+## Dependency Management
+- **Version Catalog**: All versions centralized in [gradle/libs.versions.toml](mdc:gradle/libs.versions.toml)
+- **BOM usage**: Import [bom/](mdc:bom/) for internal dependency alignment
+- **No version conflicts**: Use dependency resolution strategies
+- **Security scanning**: OWASP dependency check enabled in root build
+
+## Plugin Application
+- **Plugin DSL**: Use `plugins {}` block with version catalog aliases
+- **Custom plugins**: Apply from [gradle-plugin/](mdc:gradle-plugin/) module
+- **Build conventions**: Apply from [build-logic/](mdc:build-logic/) for consistency
+
+## Module Configuration
+- **Consistent structure**: Follow patterns from existing modules
+- **Shared configurations**: Use build conventions for common setup
+- **Testing setup**: Include [testtoolkit/](mdc:testtoolkit/) for test utilities
+- **Publishing**: Configure for Maven Central via [gradle-plugin/](mdc:gradle-plugin/)
+
+## Build Performance
+- **Gradle daemon**: Configured in [gradle/gradle-daemon-jvm.properties](mdc:gradle/gradle-daemon-jvm.properties)
+- **Parallel builds**: Enable for multi-module project
+- **Build cache**: Use for faster incremental builds
+- **Configuration cache**: Enable where possible
+
+## Quality Gates
+- **Spotless**: Code formatting via build conventions
+- **Detekt**: Static analysis for Kotlin code
+- **Test coverage**: JaCoCo integration
+- **Dependency updates**: Automated via version catalog update plugin
+
+## Publishing Configuration
+- **Maven Central**: Publishing setup in [gradle-plugin/](mdc:gradle-plugin/)
+- **Signing**: GPG signing for releases
+- **Metadata**: Complete POM information
+- **Staging**: Sonatype OSSRH staging process
+
+## Example Module Build Script
+```kotlin
+plugins {
+    id("buildlogic.kotlin-library-conventions")
+    id("buildlogic.publishing-conventions")
+}
+
+dependencies {
+    api(projects.shared)
+    implementation(libs.spring.boot.starter)
+    testImplementation(projects.testtoolkit)
+}
+```

.cursor/rules/kotlin-standards.mdc

@@ -0,0 +1,50 @@
+---
+globs: *.kt,*.kts
+---
+
+# Kotlin Development Standards
+
+Based on [docs/GLOBAL_CLAUDE.md](mdc:docs/GLOBAL_CLAUDE.md), follow these strict Kotlin conventions:
+
+## Variable Declarations
+- **Always prefer `val`** over `var` for immutable variables
+- Use descriptive names, avoid abbreviations
+- **Forbidden**: `util`, `utils`, `tool` in naming
+
+## Null Safety
+- **Avoid `!!` operator** - use `?.` or `let{}` instead
+- Prefer safe calls and Elvis operator
+- Use `let`, `run`, `with`, `apply` scope functions appropriately
+
+## Function Design
+- **Use data classes** instead of functions with many parameters
+- **Maximize `early return`** to reduce nesting levels
+- Keep functions small and focused on single responsibility
+
+## Testing Standards
+- **Use `mockk`** instead of Mockito for mocking
+- **Forbidden**: `@DisplayName` annotations
+- Test method names use backticks with Chinese descriptions: `fun \`测试用户创建成功\`()`
+- **Nested test organization**: Use `@Nested inner class` for grouping
+- **Every test must have assertions** - no assertion-free tests allowed
+
+## Logging
+- **Forbidden**: `println` for output - use proper logging framework
+- Add comprehensive logging for debugging and monitoring
+- Use structured logging with meaningful context
+
+## Code Quality
+- **Forbidden**: `@Suppress` annotations to hide warnings
+- **Forbidden**: Exposing API keys, passwords, tokens in code
+- Handle exceptions properly - never ignore or hide them
+- Use meaningful variable and function names
+
+## Spring Framework
+- **Use `@Resource`** instead of `@Autowired` for dependency injection
+- Follow Spring Boot 3.5.x conventions
+- Leverage Kotlin-specific Spring features
+
+## Build Scripts (*.kts)
+- Use Kotlin DSL for Gradle build scripts
+- Leverage type-safe project accessors
+- Follow version catalog conventions from [gradle/libs.versions.toml](mdc:gradle/libs.versions.toml)