diff --git a/.claude/commands/child-use.md b/.claude/commands/child-use.md new file mode 100644 index 000000000..a98438864 --- /dev/null +++ b/.claude/commands/child-use.md @@ -0,0 +1,69 @@ +--- +allowed-tools: Read, Write, Edit, MultiEdit, Glob, Grep, Bash, TodoWrite, Task +description: Child project Claude configuration copy process, copying root directory .claude/ configuration files to current working directory +--- + +# Child-Use Configuration Copy Process + +Copy root directory `.claude/` configuration to current cwd for child project Claude environment initialization. + +## Core Requirements + +### Copy Targets +- `.claude/commands/**` +- `.claude/agents/**` (corresponding to subagent) +- `.claude/.gitignore` + +### Forbidden to Copy +- `.claude/settings.json` +- `.claude/settings.local.json` + +### Operation Constraints +- Forbidden to read file contents, only use `ls` to check existence +- If target `.claude/` exists, delete and rebuild directly +- Finally create `.claude/.gitignore` with content `*` + +## Process Design + +### 1. Environment Cleanup +```bash +if [ -d ".claude" ]; then + rm -rf .claude +fi +``` + +### 2. Source File Detection +```bash +ROOT_DIR=$(find_root_with_claude) +ls "$ROOT_DIR/.claude/commands/" >/dev/null 2>&1 +ls "$ROOT_DIR/.claude/agents/" >/dev/null 2>&1 +ls "$ROOT_DIR/.claude/.gitignore" >/dev/null 2>&1 +``` + +### 3. File Copy +```bash +mkdir -p .claude + +if [ -d "$ROOT_DIR/.claude/commands" ]; then + cp -r "$ROOT_DIR/.claude/commands" .claude/ +fi + +if [ -d "$ROOT_DIR/.claude/agents" ]; then + cp -r "$ROOT_DIR/.claude/agents" .claude/ +fi + +if [ -f "$ROOT_DIR/.claude/.gitignore" ]; then + cp "$ROOT_DIR/.claude/.gitignore" .claude/.gitignore.backup +fi +``` + +### 4. Configuration Override +```bash +echo "*" > .claude/.gitignore +``` + +## Features + +- Search upward for root directory +- Atomic operations +- Settings file protection diff --git a/.claude/commands/optimize-prompt.md b/.claude/commands/optimize-prompt.md new file mode 100644 index 000000000..350b66ffe --- /dev/null +++ b/.claude/commands/optimize-prompt.md @@ -0,0 +1,350 @@ +--- +allowed-tools: Read, Write, Edit, MultiEdit, Glob, Grep, Bash, TodoWrite, Task +description: Optimize Claude memory files to make them more readable for AI and achieve better work results +--- + +`optimize-prompt` optimizes Claude.ai `CLAUDE.md` memory prompt files. Parameters: `$1` (required): path to the prompt file to optimize, `$2` (optional): user's specific requirements or optimization direction. + +This task performs structural optimization, format standardization, and content simplification on memory prompts according to established rules. For non-.locale. files, it first translates them to Chinese .locale. files before optimization, ensuring users can always understand and control the prompt content. + +## Optimization Rules + +### Language Selection Rules +- **Prioritize .locale. files**: When filename contains `.locale.`, optimize directly +- **Translate non-.locale. files**: If user passes a non-.locale. file, translate a Chinese .locale. file next to it and optimize the translated .locale. file +- **Maintain user's awareness of prompt content**: Through automatic translation and optimization mechanisms, ensure users can always understand and control prompt content + +### Title Structure Optimization +- Title nesting level must not exceed level 3 +- Remove redundant title nesting +- Ensure clear title hierarchy + +### Content Expression Standards +- **Prohibit emoji usage**: Strictly prohibit any emoji in documentation to maintain professionalism +- Use concise and clear written expression +- Maintain document style consistency and professionalism + +### Example Writing Standards + +**XML Tag System** +Use structured XML tags to wrap examples, optimizing AI parsing efficiency and reading experience: + +**Tag Type Definitions**: +- `` - General example, showing standard usage +- `` - Example collection container, containing multiple related examples +- `` - Best practice example, showing recommended approach +- `` - Negative example, showing practices to avoid + +**Description Attribute Specifications**: +- All example tags support `description=""` attribute to explain the example's purpose +- Descriptions should be concise and clear, highlighting the example's core value and learning points + +**Dialogue Mechanism Specifications**: +- `user:` - User input content +- `claude:` - Claude response output content +- Support independent `claude:` to identify pure output scenarios + +**Formatting Constraints**: +- `` and `` tags can only be used within `` containers +- All XML tags and their content maintain zero indentation format +- Must keep one blank line separator between tags and above content, ensuring clear document structure +- **Code example format**: All code examples must be wrapped in language-identified code blocks, such as: + ```rust + // Rust code + ``` + +**Content Conciseness Principles**: +- Examples should be short and effective, highlighting key points +- Avoid lengthy implementation details, focus on demonstrating concepts +- Code examples should not exceed 20 lines, text examples should not exceed 5 lines +- Each example should demonstrate only one key concept or comparison point + +**BadExample Optimization Limitations**: +- Do not format optimize content within `` tags during optimization +- Keep BadExample content as-is unless it doesn't match the intended meaning +- The purpose of BadExample is to show wrong approaches, including wrong formatting, punctuation, indentation, etc. + +### Core Structural Elements +- **Role Definition**: Clearly define AI's identity and professional background +- **Task Description**: Clearly and specifically describe the task to complete +- **Constraint Conditions**: Clearly define limitations and requirements +- **Output Format**: Specify the structure and format of output + +### Attention Mechanism Optimization +- **Key Point Limitation**: Each prompt should highlight at most 3 key points +- **Avoid Attention Dilution**: Overusing emphasis formats (bold, code blocks, etc.) reduces effectiveness +- **Position Strategy**: Place the most critical information at the beginning and end + +### Prompt Length Optimization +- **Conciseness Principle**: Remove redundant descriptions, keep core information +- **Necessary Details**: Retain key technical details and constraint conditions +- **Readability**: Use reasonable paragraph breaks, avoid overly long paragraphs + +### Prompt File Structure Requirements +- **YAML Front Matter**: File start may contain YAML configuration block, defining tool permissions and basic descriptions +- **Descriptive Text**: Besides YAML configuration, should include text description explaining the prompt's purpose and functionality +- **Structural Completeness**: Ensure prompt files have both configuration information and functional descriptions + +### Format Optimization Techniques +- **Encoding Standards**: Use UTF-8 encoding to ensure compatibility +- **Indentation Standards**: Uniformly use 2-space indentation +- **Line Endings**: Use LF line endings (not CRLF) +- **Format Consistency**: Ensure consistent document format style throughout +- **Punctuation Standards**: Prohibit Chinese punctuation, uniformly use English punctuation + +### File Structure Representation Standards +- **Prohibit Tree Structure Diagrams**: Do not use ASCII art-style tree diagrams to represent file structure +- **Use Indentation Method**: File structure must be represented using simple indentation format +- **Clear and Concise**: Ensure structure is clear and readable, avoid overly complex representation methods + + + +```text +docs/ + - `prompts/` - Prompt templates + - `user/` - Global user prompts + - `project/` - Project-level prompts + - `slashcommands/` - Slash command prompts + - `qa/` - Q&A documentation + - `references/` - Technical reference documentation + - `other/` - Other documentation (build, Git, database, etc.) +``` + + +docs/ +├── prompts/ # Prompt templates +│ ├── user/ # Global user prompts +│ ├── project/ # Project-level prompts +│ └── slashcommands/ # Slash command prompts +├── qa/ # Q&A documentation +├── references/ # Technical reference documentation +└── other/ # Other documentation (build, Git, database, etc.) + + + +### Clarity Optimization +- **Avoid Ambiguity**: Use precise vocabulary, avoid vague expressions +- **Be Specific**: Convert abstract concepts to specific requirements +- **Actionable**: Ensure instructions can be accurately understood and executed + +### Constraint Condition Clarification +- **Must Include**: Clearly list conditions that must be met +- **Prohibited Items**: Clearly specify what cannot be done +- **Boundary Conditions**: Define the scope and limitations of processing + +### Output Standardization +- **Format Specifications**: Specify specific output formats (tables, lists, code blocks, etc.) +- **Structural Requirements**: Clearly define the organization structure of output +- **Example Illustrations**: Provide examples of expected output + +### Punctuation Usage Examples + + + +# Role: Code Review Assistant + +You are an expert code reviewer with 10+ years of experience. Your task is to: +1. Analyze code quality and identify potential issues +2. Provide actionable feedback for improvements +3. Ensure code follows best practices and security guidelines + +Focus on readability, maintainability, and performance aspects. + + +# Role: 代码审查助手 + +你是一位拥有10年以上经验的专家代码审查员。你的任务是: +1. 分析代码质量并识别潜在问题 +2. 提供可操作的改进建议 +3. 确保代码遵循最佳实践和安全准则 + +重点关注可读性、可维护性和性能方面。 + + + +### Code Format Examples + + + +use std::collections::HashMap; + +#[derive(Debug, Clone)] +pub struct ProcessedItem { + pub id: String, + pub name: String, + pub value: f64, +} + +pub fn process_data(data: &[HashMap]) -> HashMap> { + let mut result = HashMap::new(); + + if data.is_empty() { + result.insert("status".to_string(), vec![]); + result.insert("count".to_string(), vec![]); + return result; + } + + let mut processed = Vec::new(); + for item in data { + if let Some(active) = item.get("active") { + if active == "true" { + if let (Some(id), Some(name), Some(value_str)) = + (&item.get("id"), &item.get("name"), &item.get("value")) { + if let Ok(value) = value_str.parse::() { + processed.push(ProcessedItem { + id: id.clone(), + name: name.trim().to_string(), + value, + }); + } + } + } + } + } + + result.insert("status".to_string(), vec![]); + result.insert("count".to_string(), vec![]); + result +} + + +use std::collections::HashMap; + +#[derive(Debug, Clone)] +pub struct ProcessedItem { + pub id: String, + pub name: String, + pub value: f64, +} + +pub fn process_data(data: &[HashMap]) -> HashMap> { + let mut result = HashMap::new(); + + if data.is_empty() { + result.insert("status".to_string(), vec![]); + result.insert("count".to_string(), vec![]); + return result; + } + + let mut processed = Vec::new(); + for item in data { + if let Some(active) = item.get("active") { + if active == "true" { + if let (Some(id), Some(name), Some(value_str)) = + (&item.get("id"), &item.get("name"), &item.get("value")) { + if let Ok(value) = value_str.parse::() { + processed.push(ProcessedItem { + id: id.clone(), + name: name.trim().to_string(), + value, + }); + } + } + } + } + } + + result.insert("status".to_string(), vec![]); + result.insert("count".to_string(), vec![]); + result +} + + + +### Prompt Structure Examples + + + +# Code Generation Assistant + +Generate clean, efficient, and well-documented code based on requirements. + +## Key Guidelines +- Use meaningful variable and function names +- Include type hints for better code clarity +- Write docstrings for all public functions +- Follow the project's established patterns + +## Output Format +```rust +/// Function implementation with proper documentation +pub fn function_name(param: ParamType) -> ReturnType { + /// Brief description of the function. + /// + /// # Arguments + /// * `param` - Description of the parameter + /// + /// # Returns + /// Description of the return value + /// + /// # Examples + /// ``` + /// let result = function_name(input_value); + /// assert_eq!(result, expected_value); + /// ``` + // Implementation here +} +``` + + +## 🤖 AI Code Generation Assistant v2.0.1 ### + +### 📋 MISSION STATEMENT: +You are an advanced AI-powered code generation system designed to create high-quality, production-ready code solutions for enterprise applications. + +### 🔧 TECHNICAL REQUIREMENTS: +- **Variable Naming Convention**: MUST utilize meaningful, self-documenting variable names that clearly express intent +- **Type Safety**: ALL function parameters MUST include comprehensive type annotations using the latest typing features +- **Documentation Standards**: EVERY public function REQUIRES extensive docstring documentation following Google/NumPy conventions +- **Pattern Consistency**: MUST rigidly adhere to existing architectural patterns without deviation + +### 📤 COMPLEX OUTPUT SPECIFICATION: +The generated code should follow this exact structure: + +```rust +// -*- coding: utf-8 -*- +//! Enterprise-grade function implementation with comprehensive documentation. +//! This module represents a critical business logic component. + +pub fn elaborate_function_name_with_verbose_description( + parameter_name: ParameterType, +) -> Result> { + /// This function performs the specified operation with high reliability. + /// + /// # Arguments + /// * `parameter_name` - A detailed explanation of what this parameter represents, + /// including its expected format, constraints, and usage patterns + /// + /// # Returns + /// * `Result>` - A comprehensive description of + /// the return value, including all possible return states, error conditions, + /// and data structure details + /// + /// # Errors + /// * `ValueError` - Detailed explanation of when this error might occur + /// * `TypeError` - Comprehensive list of scenarios leading to type errors + /// + /// # Examples + /// ``` + /// match elaborate_function_name_with_verbose_description(input) { + /// Ok(result) => println!("Operation succeeded: {:?}", result), + /// Err(e) => eprintln!("Operation failed: {}", e), + /// } + /// ``` + // Implementation placeholder with extensive comments + unimplemented!() +} +``` + + + +--- + +## Documentation Type Description + +### Characteristics and Positioning of Different Documentation Types + +- **docs/prompts/slashcommands/**.locale.md are shortcut command files, they focus on task efficiency optimization +- **docs/prompts/user/**.locale.md are global memory files, they are usually more abstract +- **docs/prompts/project/**.locale.md are project-specific templates, though abstract but have more project-specific characteristics +- **docs/CLAUDE-**.locale.md are memory prompts for docs/, they help users continuously refine prompts to achieve better results \ No newline at end of file diff --git a/.claude/commands/setup-project.md b/.claude/commands/setup-project.md index 260f27cac..13608c38a 100644 --- a/.claude/commands/setup-project.md +++ b/.claude/commands/setup-project.md @@ -42,7 +42,7 @@ claude mcp add playwright --scope project -- npx -y @playwright/mcp@latest --vie ```bash # Context7 - Access up-to-date documentation for any library -claude mcp add-json context7 --scope project '{"command":"cmd","args":["/c","npx","-y","@upstash/context7-mcp@latest"]}' +claude mcp add-json context7 --scope project '{\"command\":\"cmd\",\"args\":[\"/c\",\"npx\",\"-y\",\"@upstash/context7-mcp@latest\"]}' # Grep - Search millions of GitHub repositories for code examples claude mcp add --scope project --transport http grep https://mcp.grep.app @@ -51,10 +51,10 @@ claude mcp add --scope project --transport http grep https://mcp.grep.app claude mcp add --scope project --transport http deepwiki https://mcp.deepwiki.com/mcp # Sequential Thinking - Enhanced reasoning and problem-solving -claude mcp add-json sequential-thinking --scope project '{"command":"cmd","args":["/c","npx","-y","@modelcontextprotocol/server-sequential-thinking@latest"]}' +claude mcp add-json sequential-thinking --scope project '{\"command\":\"cmd\",\"args\":[\"/c\",\"npx\",\"-y\",\"@modelcontextprotocol/server-sequential-thinking@latest\"]}' # Memory - Knowledge graph for persistent context -claude mcp add-json memory --scope project '{"command":"cmd","args":["/c","npx","-y","@modelcontextprotocol/server-memory@latest"]}' +claude mcp add-json memory --scope project '{\"command\":\"cmd\",\"args\":[\"/c\",\"npx\",\"-y\",\"@modelcontextprotocol/server-memory@latest\"]}' # Playwright - Web automation and testing claude mcp add-json playwright --scope project '{\"command\":\"cmd\",\"args\":[\"/c\",\"npx\",\"-y\",\"@playwright/mcp@latest\",\"--viewport-size\",\"1920,1080\"]}' diff --git a/.claude/commands/spec/spec-1-requirement.md b/.claude/commands/spec/spec-1-requirement.md new file mode 100644 index 000000000..3860da12d --- /dev/null +++ b/.claude/commands/spec/spec-1-requirement.md @@ -0,0 +1,493 @@ +--- +argument-hint: [your locale language example | ] [ ] +allowed-tools: Read, Write, Edit, MultiEdit, Glob, Grep, Bash, TodoWrite, Task +description: Guide users through the first step of specification-driven development to generate structured requirements documentation +--- + +Assist users in completing the first step of specification-driven development - requirements documentation writing. + +# [STEP-1]: Preparation + +- Use _List_ to check if `docs/SPEC-1-REQUIREMENTS.locale.md` exists +- If the file exists, use _Write_ to load content and output a brief overview; otherwise use _Write_ to initialize a new specification document skeleton +- Identify the user's preferred language represented by the first parameter `$1`, subsequent free text output will default to this language; if the user specifies otherwise, follow the latest instructions +- After completing the overview, invite the user to relax and imagine the ideal system form, then WAIT for user input to enter [STEP-2] + +# [STEP-2]: Patiently listen to user's initial requirements description + +- Recognize that the user is in a relaxed, divergent thinking brainstorming state, expressions may be jumping or metaphorical +- Guide from an architect's perspective: use simple language to break the system into modules, scenarios, or processes, and inquire key information segment by segment +- Listen carefully and record key information, clarify ambiguous points politely when necessary +- Only respond when clarification or confirmation is needed, remain quiet at other times to avoid frequent interruptions +- If the user says "stop" or gives an equivalent request, end the conversation immediately +- The user's divergent description needs to be refined first, select content that aligns with [APPENDIX-1] structure and has executable value before using _Write_ to record; avoid copying sentence by sentence +- If no key points that can be written are filtered out, use WAIT to remain silent and continue listening until clear information is obtained +- During the guidance process, repeat inferences to the user based on phased results, wait for confirmation or correction, avoid making complete design at once +- Continue iterating according to the user's pace until the user explicitly indicates "completion" +- After user confirmation, remind them to use `/translate` or other tools to translate the document to English and record the external link in `project/CLAUDE.md` to improve subsequent coding experience + + +## Locale Usage Conventions + +- `$1` is the locale passed in by the slash command (such as `zh_CN`, `en_US`), also represents the user's preferred language +- When communicating with users, default to using `$1` corresponding language; if the user switches languages or specifies special requirements, follow the latest instructions +- When generating specification documents, except for fixed required English titles or keywords, all other free text should use `$1` language +- Follow common expressions and punctuation of `$1` language, making the copy read naturally without translation feel +- When clarifying terminology or demonstrating examples, you can first explain in `$1` language, and supplement English comparison when necessary + + +# [APPENDIX-1]: Established format for requirements documentation + +When outputting requirements documentation, you must strictly follow the following standard Markdown format specifications: + +```md +# [PROJECT_NAME:- $2] User Requirements Documentation +``` + +**Format Description:** +- `[PROJECT_NAME:- $2]`: Placeholder, needs to be replaced with actual project identifier (such as `mediacms`, `carshoping`, etc.) +- Document title must use English, follow PascalCase naming convention +- Document type is fixed as "User Requirements Documentation" + + + +# mediacms User Requirements Documentation + + +# carshoping User Requirements Documentation + + +# idea-mcp-plugin User Requirements Documentation + + + +After a blank line, add the project introduction section, format as follows: + +```md +## Introduction + +This document records the detailed development requirements for developers in developing [project type] projects,... +``` + +**Writing Guidelines:** +- Use secondary heading `## Introduction` +- Description should start with a sentence equivalent to "This document records the detailed development requirements for developers in developing" in `$1` language +- Briefly explain the project type and main goals +- Length should be controlled within 2-5 sentences + + + +## Introduction + +此文档记录了开发者在开发 MES 系统的详细开发需求，旨在实现生产过程的数字化管理与监控。 + + +## Introduction + +此文档记录了开发者在开发电商前后端分离项目的详细开发需求，涵盖商品管理、订单处理和用户系统等核心功能。 + + + +After a blank line, define target user groups, format as follows: + +```md +**Primary Persona:** [User group description] +``` + +**Writing Specifications:** +- Fixed use of English title `**Primary Persona:**` +- Use `$1` language to describe user groups, and list multiple groups according to common separators of that language (such as Chinese pause marks, English commas) +- Descriptions need to be concise and accurate, maintaining high relevance to the project field +- Avoid subjective evaluations or artistic expressions + + + +**Primary Persona:** 制造业员工、制造业开发者 + + +**Primary Persona:** 在校大学生、高校老师、社团建模爱好者 + + +**主要客户群体:** 在校大学生、高校老师、社团建模爱好者 + + +**Primary Persona:** 富有魅力的企业高管、追求卓越的技术专家 + + +**Primary Persona:** 各类用户、有需求的人士 + + + +After a blank line, add optional project constraints, format as follows: + +```md +**Operational Constraints:** +1. [Specific constraint description] +2. [Specific constraint description] +3. [Specific constraint description] +``` + +Constraint type reference (can be flexibly adjusted according to actual situation): +- Infrastructure: Hardware configuration, network environment, deployment method, etc. +- Technology stack: Programming languages, framework choices, third-party services, etc. +- Team configuration: Team size, skill structure, external collaboration, etc. +- Compliance requirements: Industry standards, data security, privacy protection, etc. +- Operational support: Availability goals, maintenance costs, scalability, etc. +- Business factors: Budget constraints, time requirements, return on investment, etc. + + + +**Operational Constraints:** +1. 服务器性能有限，需要轻量化部署并控制带宽占用 +2. 默认依赖外部 MySQL 8；视频资源可部署在本地磁盘或 TOS，视成本取舍 +3. 访问与播放量较低，但需确保圈内访问流畅与后台易维护 + + +**Operational Constraints:** +1. 必须符合国家金融数据安全规范，所有交易数据需加密存储 +2. 系统可用性要求 99.9%，每年停机时间不超过 8.76 小时 +3. 开发团队 3 人，包括 1 名前端、1 名后端、1 名测试 +4. 预算限制在 50 万以内，包含一年的运维成本 + + +**Operational Constraints:** +1. 服务器要好一点 +2. 需要快点完成 +3. 预算不太够 + + +**Operational Constraints:** +1. 电脑配置不能太差，不然跑不动 +2. 最好用云服务，这样方便些 +3. 找几个人随便做做就行 + + + +After a blank line, add optional non-functional priority description, format as follows: + +```md +**Non-Functional Priorities:** +1. [Priority description] +2. [Priority description] +3. [Priority description] +``` + + + +**Non-Functional Priorities:** +1. 默认启用 HTTPS，优先使用云厂商免费证书 +2. 视频与封面优先经由 TOS/CDN；若采用本地存储，需提供容量监控与清理策略 +3. 当前仅需桌面端体验，移动端可在后续需求出现时迭代 +4. 提供容器或脚本化部署以便迁移与快速恢复 +5. 实现轻量日志与监控，并规划数据库与关键数据的定期备份 + + + +**Non-Functional Priorities:** +1. 系统要安全稳定 +2. 速度要快一点 +3. 界面要好看 +4. 后期要方便维护 +5. 部署要简单 + + + +**Non-Functional Priorities:** +1. 所有敏感数据必须 AES-256 加密存储，传输使用 TLS 1.3 +2. 核心交易接口响应时间 ≤ 500ms，99% 请求需在 200ms 内完成 +3. 系统可用性 ≥ 99.9%，月度停机时间 ≤ 43.2 分钟 +4. 支持 Chrome/Firefox/Safari 最新两个版本，IE11 最低兼容 +5. 代码覆盖率 ≥ 80%，关键业务 100% 有集成测试 + + + +**Non-Functional Priorities:** +1. 使用 React 框架开发前端 +2. 后端采用 Spring Boot 框架 +3. 数据库使用 MySQL 8.0 +4. 缓存使用 Redis +5. 消息队列用 RabbitMQ + + + +After a blank line, add optional subsequent scope description, format as follows: + +```md +**Deferred Scope:** +1. [Feature description] +2. [Feature description] +3. [Feature description] +``` + +**Writing Guidelines:** +- Use English title `**Deferred Scope:**` +- List features not considered in the current version, but may need to be implemented in the future +- Each feature should be concise and highlight core value +- Avoid duplication with existing requirements +- Ordered list content should be written in `$1` language + + + +**Deferred Scope:** +1. 人才市场招聘能力，连接创作者与企业 +2. 短剧贩售与付费解锁模块，支持内容变现 +3. 创作者社区功能，支持作品交流与协作 + + + +**Deferred Scope:** +1. 社交分享功能，允许用户分享商品至各平台 +2. 会员积分系统，提升用户忠诚度 +3. 多语言国际化支持，拓展海外市场 + + + +**Deferred Scope:** +1. 一些其他功能 +2. 后续再加的东西 +3. 等有钱了再做的 + + + +**Deferred Scope:** +1. 用户登录注册（已在基础功能中） +2. 商品展示页面（已在核心需求中） +3. 订单管理功能（已在必须实现中） + + + + +Then comes the core requirements list, which is the most important part of the entire document, must strictly follow the following specifications: + +## Requirements Format Specifications + +### Basic Structure +```md +## Requirements + +### Requirement [Number]: [Requirement Name] + +**User Story:** As [User Role], I want [Desired Function], so that [Obtained Value]. + +#### Acceptance Criteria + +1. WHEN [Trigger Condition] THEN [Expected Result] +2. WHEN [Trigger Condition] THEN [Expected Result] +3. WHEN [Trigger Condition] THEN [Expected Result] +``` + +### Writing Specification Requirements + +1. **User Story** + - Must use standard format: `As [Role], I want [Function], so that [Value]` + - Role should be specific (such as "creator" rather than "user") + - Value should be clear (answer "why this feature is needed") + - Use `$1` language to write [Role], [Function], [Value] + +2. **Acceptance Criteria** + - Must use Given-When-Then format + - Each criterion must be independent and testable + - Avoid technical implementation details, focus on business behavior + - Use `$1` language to write [Trigger Condition], [Expected Result] + +3. **Requirement Splitting Principles** + - Each requirement should be independent with clear value + - Avoid being too large (consider splitting if exceeding 5 acceptance criteria) + - Avoid being too small (consider merging if fewer than 2 acceptance criteria) + + + +### Requirement 3: User Work Management + +**User Story:** As 创作者, I want 能够管理我的所有作品, so that 可以随时编辑或删除内容。 + +#### Acceptance Criteria + +1. WHEN 创作者登录并进入个人中心 THEN 系统应展示其所有作品的列表，包含缩略图、标题、发布时间和浏览量 +2. WHEN 创作者点击作品编辑按钮 THEN 系统应跳转至编辑页面，保留原有内容并可修改所有信息 +3. WHEN 创作者删除作品 THEN 系统应要求二次确认，成功后从列表中移除并提示用户 +4. WHEN 作品被其他用户收藏或评论 THEN 创作者在管理页面应能看到相关统计数据 + + + +### Requirement 2: User Login + +**User Story:** As 用户, I want 登录系统。 + +#### Acceptance Criteria + +1. 输入用户名密码 +2. 点击登录按钮 +3. 登录成功 + + + +### Requirement 5: Content Recommendation + +**User Story:** As 观众, I want 系统能推荐我感兴趣的短剧内容, so that 发现更多优质作品。 + +#### Acceptance Criteria + +1. WHEN 观众浏览首页 THEN 系统应基于其观看历史推荐相似类型作品 +2. WHEN 观众完成观看一个作品 THEN 系统应推荐相关创作者的其他作品 +3. WHEN 观众连续跳过多个推荐 THEN 系统应调整推荐算法，提供更精准的内容 + + + +### Requirement 4: Video Upload + +**User Story:** As 创作者, I want 上传视频。 + +#### Acceptance Criteria + +1. 调用后端 API 接口 /api/v1/videos +2. 使用 MySQL 存储视频信息 +3. 视频文件存放在 OSS 对象存储 + + + +### Requirement 7: Comment Interaction + +**User Story:** As 观众, I want 对喜欢的作品进行评论, so that 与创作者和其他观众交流想法。 + +#### Acceptance Criteria + +1. WHEN 观众在作品详情页输入评论并提交 THEN 系统应发布评论并在评论区实时显示 +2. WHEN 创作者收到评论 THEN 系统应通过站内信通知创作者 +3. WHEN 评论包含敏感词 THEN 系统应自动拦截并提示用户修改 +4. WHEN 观众点击某条评论 THEN 系统应显示该评论的回复和点赞数 + + + +### Requirement 1: Complete User System + +**User Story:** As 用户, I want 使用完整的系统功能。 + +#### Acceptance Criteria + +1. 用户注册登录 +2. 个人信息管理 +3. 作品发布管理 +4. 评论互动功能 +5. 消息通知系统 +6. 数据统计分析 +7. 权限管理控制 +8. 支付功能 +9. 客服系统 + + + +### Requirement Priority Marking (Optional) +If need to identify requirement priorities, use markers after the number: +- `[H]` - High priority +- `[M]` - Medium priority +- `[L]` - Low priority + + + +### Requirement 1[H]: User Authentication +### Requirement 2[M]: Email Notification +### Requirement 3[L]: Theme Switching + + + + +# EduPlatform User Requirements Documentation + +## Introduction + +此文档记录了开发者在开发在线教育平台的详细开发需求，旨在为教师和学生提供高效的在线教学与学习体验。 + +**Primary Persona:** 在线教育教师、高校学生、职业培训学员、教育机构管理者 + +**Operational Constraints:** +1. 服务器预算有限，需要支持至少 1000 并发用户 +2. 必须兼容移动端和桌面端，最低支持 iOS 12 和 Android 8.0 +3. 视频直播依赖第三方 CDN 服务，需控制带宽成本 +4. 开发团队 5 人，包含 2 名前端、2 名后端、1 名测试 + +**Non-Functional Priorities:** +1. 视频直播延迟不超过 3 秒，支持断线重连 +2. 用户数据必须加密存储，符合个人信息保护法要求 +3. 系统可用性达到 99.5%，每月停机时间不超过 3.6 小时 +4. 页面加载时间控制在 2 秒以内 + +**Deferred Scope:** +1. AI 智能推荐学习内容功能 +2. 虚拟现实（VR）沉浸式课堂体验 +3. 多语言国际化支持功能 + +## Requirements + +### Requirement 1[H]: Course Creation and Management + +**User Story:** As 教师, I want 能够创建和管理在线课程, so that 可以灵活地安排教学内容和进度。 + +#### Acceptance Criteria + +1. WHEN 教师登录并进入课程管理页面 THEN 系统应显示"创建新课程"按钮和现有课程列表 +2. WHEN 教师点击"创建新课程"并填写课程信息 THEN 系统应生成课程主页并支持添加章节 +3. WHEN 教师上传视频课件 THEN 系统应自动转码为多格式以适应不同网络环境 +4. WHEN 教师设置课程价格 THEN 系统应支持免费、付费和会员专享三种模式 +5. WHEN 课程有学员报名 THEN 教师应收到通知并查看学员名单 + +### Requirement 2[H]: Video Live Teaching + +**User Story:** As 教师, I want 进行实时视频直播教学, so that 可以与学生进行互动和答疑。 + +#### Acceptance Criteria + +1. WHEN 教师进入直播间 THEN 系统应提供摄像头、麦克风和屏幕共享选项 +2. WHEN 教师开始直播 THEN 系统应自动通知已报名的学生 +3. WHEN 学生在直播中提问 THEN 教师应能看到实时弹幕并选择性回复 +4. WHEN 网络不稳定时 THEN 系统应自动切换至清晰度较低的流畅模式 +5. WHEN 直播结束后 THEN 系统应生成回放视频并自动关联到课程页面 + +### Requirement 3[M]: Learning Progress Tracking + +**User Story:** As 学生, I want 能够查看我的学习进度, so that 了解完成情况并制定学习计划。 + +#### Acceptance Criteria + +1. WHEN 学生进入个人中心 THEN 系统应展示已购课程列表和整体学习进度 +2. WHEN 学生进入课程详情页 THEN 系统应显示每个章节的完成状态和学习时长 +3. WHEN 学生完成一个章节 THEN 系统应自动更新进度并解锁下一章节 +4. WHEN学生的学习时长达到系统设定值 THEN 系统应弹出休息提醒 +5. WHEN 学生完成全部课程 THEN 系统应生成电子证书并支持分享 + +### Requirement 4[M]: Interactive Discussion Area + +**User Story:** As 学生, I want 能够在课程下进行讨论和提问, so that 与同学和老师交流学习心得。 + +#### Acceptance Criteria + +1. WHEN 学生进入课程讨论区 THEN 系统应按时间顺序显示所有讨论帖 +2. WHEN 学生发布提问 THEN 系统应@通知相关教师和其他选课学生 +3. WHEN 教师回复问题 THEN 系统应标记为"已解答"并高亮显示 +4. WHEN 学生觉得某个回答有用 THEN 可以点赞该回答 +5. WHEN 讨论包含不当内容 THEN 系统应自动过滤并提交人工审核 + +### Requirement 5[L]: Assignment Submission and Grading + +**User Story:** As 学生, I want 在线提交作业并获得老师反馈, so that 及时了解自己的学习效果。 + +#### Acceptance Criteria + +1. WHEN 教师发布作业 THEN 系统应通知所有选课学生并显示截止日期 +2. WHEN 学生提交作业 THEN 系统应支持文本、图片、文档和视频多种格式 +3. WHEN 学生提交后超时 THEN 系统应自动关闭提交入口 +4. WHEN 教师批改作业 THEN 系统应支持评分、评语和批注功能 +5. WHEN 所有作业批改完成后 THEN 系统应生成班级成绩统计 + + + +### Q & A + +**Q: How detailed should requirements be?** +A: Each requirement should be detailed enough for developers to understand and implement, but avoid over-designing. Generally 3-5 acceptance criteria are appropriate. + +**Q: How to write acceptance criteria to ensure testability?** +A: Use specific, observable results, avoid vague words like "fast", "friendly", etc., change to specific indicators like "response time < 2 seconds". + +**Q: How to judge if requirement splitting is reasonable?** +A: If a requirement has more than 5 acceptance criteria, consider whether it can be split; if fewer than 2, consider whether it is too simple. \ No newline at end of file diff --git a/.claude/commands/translate.md b/.claude/commands/translate.md new file mode 100644 index 000000000..c2a27fd90 --- /dev/null +++ b/.claude/commands/translate.md @@ -0,0 +1,98 @@ +--- +argument-hint: [locale_markdown_file] [translation_description] +allowed-tools: Read, Write, Glob, Grep, Bash +description: Translate Chinese localization memory prompt file to English memory prompt file while maintaining quality standards and terminology consistency +--- + +Translate Chinese localization memory prompt file #$1 (.locale.md) to English memory prompt file while maintaining quality standards and terminology consistency. + +# Key Requirements + +## Task Execution Workflow +1. **Read source file**: `Read($1)` +2. **Parse filename**: + - **Special location rules** (Check first): + - `docs/prompts/slashcommands/**.locale.md` → `.claude/commands/**.md` + - `docs/CLAUDE-prompts-slashcommands.locale.md` → `docs/prompts/slashcommands/CLAUDE.md` + - `docs/CLAUDE-prompts.locale.md` → `docs/prompts/CLAUDE.md` + - `docs/CLAUDE-prompts-user.locale.md` → `docs/prompts/user/CLAUDE.md` + - `docs/CLAUDE-prompts-project.locale.md` → `docs/prompts/project/CLAUDE.md` + - `docs/CLAUDE-qa.locale.md` → `docs/qa/CLAUDE.md` + - `docs/CLAUDE-references.locale.md` → `docs/references/CLAUDE.md` + - **Standard rule**: `filename.locale.extension` → `filename.extension` +3. **Check target file**: + - Use `Glob(pattern: "$1")` to verify if target file exists + - Pattern: Based on target path determined in step 2 +4. **Delete existing file**: + - If target file exists, use Bash tool to delete + - Command: `Bash(rm filename.extension)` (Linux/Mac) or equivalent (Windows) command +5. **Perform translation**: + - Preserve Markdown structure and formatting + - Apply consistent terminology from glossary + - Keep code blocks unchanged and translate all comment content + - Keep example content in `` unchanged +6. **Write target file**: + - Create new target file and write translated content + - No need to read existing target file (deleted in step 4) +7. **Error handling**: + - If Write tool fails, immediately delete target file + - Use Bash tool to execute deletion + - Restart process without attempting to fix + +> user: $2 + +## Quality Standards +- **Terminology consistency**: Strictly follow glossary +- **Technical accuracy**: Maintain precision of technical concepts +- **Format preservation**: Preserve all Markdown formatting +- **Link handling**: Update documentation links appropriately +- **Code integrity**: Keep code examples unchanged + + + +- `translate.locale.md` → `translate.md` +- `setup.locale.md` → `setup.md` +- `config.locale.yaml` → `config.yaml` + + + + +user: 请参阅文档 +claude: See documentation + +user: 配置文件 +claude: Configuration file + +user: 命令行工具 +claude: Command-line tool + + + +# Core Terminology + +## Common Terms +- 请参阅/参见 - see, refer to +- 配置 - configuration, config +- 设置 - settings +- 文档 - documentation, docs +- 指南 - guide +- 教程 - tutorial +- 示例 - example +- 工具 - tool +- 命令 - command +- 脚本 - script +- 文件 - file +- 目录 - directory +- 路径 - path + +## Claude Code Terms +- 钩子 - hook +- 斜杠命令 - slash command +- 工作区 - workspace +- 代理 - agent +- 模型 - model +- 提示 - prompt +- 上下文 - context +- 会话 - session +- 任务 - task +- 工作流 - workflow \ No newline at end of file diff --git a/.github/workflows/CLAUDE.md b/.github/workflows/CLAUDE.md deleted file mode 100644 index 79ce6b2cd..000000000 --- a/.github/workflows/CLAUDE.md +++ /dev/null @@ -1,112 +0,0 @@ -# GitHub Actions Workflows - CLAUDE.md - -This file provides configuration and usage guidance for GitHub Actions workflows for Claude Code. - -## Actions Versions and Dependencies - -### Core Actions and Versions - -**Code Management Actions:** -- `actions/checkout@v5.0.0` - Repository checkout with support for `fetch-depth: 0` full history -- `actions/setup-java@v5.0.0` - Java/JDK environment configuration using `temurin` distribution -- `gradle/actions/setup-gradle@v4` - Gradle build tool configuration with caching strategy support - -**Cache Management Actions:** -- `actions/cache@v4` - General cache management supporting Gradle dependencies and build output caching -- `actions/cache/restore@v4` - Cache restore only, for read-only cache scenarios - -**Publishing and Deployment Actions:** -- `softprops/action-gh-release@v2` - GitHub Release creation with automatic release notes generation -- `nick-fields/retry@v3` - Operation retry mechanism for unstable network publishing scenarios - -**Test Report Actions:** -- `actions/upload-artifact@v4` - Test results upload with 5-day retention period -- `actions/download-artifact@v5.0.0` - Test results download and aggregation - -## Workflow Files and Functions - -### 1. `.github/workflows/ci.yaml` - Continuous Integration Workflow - -**Trigger Conditions:** -- Pull Requests targeting the `main` branch -- Path filtering: Changes to `.github/workflows/ci.yaml` and `**/*.kt` files - -**Main Functions:** -- **Quick Check Stage (quick-check):** Version extraction, environment configuration, quick compilation -- **Matrix Testing (test-matrix):** Grouped parallel testing supporting 12 module groups -- **Test Results Summary (test-results):** Generate test report summary - -**Module Grouping Strategy:** -- `core-foundation`: Core foundation modules (shared, cacheable, docsite) -- `core-build-tools`: Build tool modules (gradle-plugin, version-catalog, bom) -- `rds-*`: Database-related modules, divided into lightweight and heavyweight tests -- `business-*`: Business function modules (AI, payment, object storage, communication) -- `security`: Security modules -- `data-processing`: Data processing modules -- `platform-integrations`: Platform integration modules -- `testing-tools`: Testing tool modules -- `integration-tests`: Integration test modules - -**TestContainers Support:** -- Heavy module groups enable TestContainers (PostgreSQL, MySQL, Redis, MinIO) -- Container reuse configuration: `TESTCONTAINERS_REUSE_ENABLE: true` -- Automatic cleanup of non-reused containers - -### 2. `.github/workflows/maven-central-publish.yaml` - Maven Central Publishing Workflow - -**Trigger Conditions:** -- Push to `main` branch -- Version tag push (`v*`) -- Release publication events -- Manual trigger (workflow_dispatch) - -**Workflow Stages:** - -1. **Pre-publish Validation (pre-publish-validation):** - - Version format validation (following semantic versioning) - - Maven Central version existence check - - Build environment configuration validation - -2. **Publish to Maven Central (publish):** - - GPG signature configuration - - Dry run support (dry_run parameter) - - Force publish support (force_publish parameter) - - Retry mechanism (maximum 2 times, 60-second intervals) - -3. **Create GitHub Release (create-github-release):** - - Automatic release notes generation - - Include Maven Central usage examples - - Create releases only for stable versions - -4. **Post-publish Verification (post-publish-verification):** - - Publishing status confirmation - - Generate verification reports - -5. **Failure Handling (failure-handler):** - - Failure cause analysis - - Troubleshooting recommendations - -**Key Configuration:** -- Environment variables: `GRADLE_OPTS` for build performance optimization -- Security credentials: GPG signing, Maven Central authentication -- Concurrency control: Prevent parallel publishing of the same branch - -## Environment Configuration Requirements - -**Runtime Environment:** -- Ubuntu Latest (GitHub-hosted runners) -- Java 17+ (automatically extracted from `libs.versions.toml`) -- Gradle 9.1+ (automatically extracted from `libs.versions.toml`) -- Docker (TestContainers support) - -**External Dependencies:** -- Maven Central Repository (publishing target) -- Sonatype OSSRH (publishing intermediary) -- Docker Hub (container images) - -**Required GitHub Secrets:** -- `GPG_KEY_ID`: GPG key ID -- `GPG_PRIVATE_KEY`: GPG private key -- `GPG_PASSPHRASE`: GPG key passphrase -- `MAVENCENTRAL_USERNAME`: Maven Central username -- `MAVENCENTRAL_PASSWORD`: Maven Central password diff --git a/.gitignore b/.gitignore index d278f05cc..be1becfe4 100644 --- a/.gitignore +++ b/.gitignore @@ -81,3 +81,4 @@ pnpm-lock.yaml ### Windows issues ### nul +.playwright-mcp/ diff --git a/.idea/misc.xml b/.idea/misc.xml index de0c4286d..4925c9519 100644 --- a/.idea/misc.xml +++ b/.idea/misc.xml @@ -5,4 +5,4 @@ - \ No newline at end of file + diff --git a/ai/ai-langchain4j/build.gradle.kts b/ai/ai-langchain4j/build.gradle.kts index f6e303793..4244452bb 100644 --- a/ai/ai-langchain4j/build.gradle.kts +++ b/ai/ai-langchain4j/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -LangChain4J integration for advanced AI capabilities and language model interactions. -Provides comprehensive AI model integration, prompt engineering, and intelligent processing workflows. -""" + LangChain4J integration for advanced AI capabilities and language model interactions. + Provides comprehensive AI model integration, prompt engineering, and intelligent processing workflows. + """ .trimIndent() dependencies { diff --git a/ai/ai-shared/build.gradle.kts b/ai/ai-shared/build.gradle.kts index 4158d46c6..7b6fec207 100644 --- a/ai/ai-shared/build.gradle.kts +++ b/ai/ai-shared/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -AI shared components for artificial intelligence integration and context management. -Provides common interfaces and utilities for AI model interactions and intelligent processing. -""" + AI shared components for artificial intelligence integration and context management. + Provides common interfaces and utilities for AI model interactions and intelligent processing. + """ .trimIndent() dependencies { diff --git a/bom/build.gradle.kts b/bom/build.gradle.kts index 55e182c5f..a26794d74 100644 --- a/bom/build.gradle.kts +++ b/bom/build.gradle.kts @@ -8,9 +8,9 @@ plugins { description = """ -Bill of Materials (BOM) for centralized dependency version management across all project modules. -Provides a platform for consistent dependency versions and simplified dependency declarations. -""" + Bill of Materials (BOM) for centralized dependency version management across all project modules. + Provides a platform for consistent dependency versions and simplified dependency declarations. + """ .trimIndent() dependencies { diff --git a/build-logic/src/main/kotlin/buildlogic.spotless-conventions.gradle.kts b/build-logic/src/main/kotlin/buildlogic.spotless-conventions.gradle.kts index c853253fc..ff024242d 100644 --- a/build-logic/src/main/kotlin/buildlogic.spotless-conventions.gradle.kts +++ b/build-logic/src/main/kotlin/buildlogic.spotless-conventions.gradle.kts @@ -5,7 +5,7 @@ plugins { spotless { kotlinGradle { - ktfmt("0.56").googleStyle().configure { + ktfmt().googleStyle().configure { it.setMaxWidth(160) it.setBlockIndent(2) it.setContinuationIndent(2) @@ -21,7 +21,7 @@ spotless { target("**/*.kt") targetExclude("**/build/generated/**") licenseHeader("") - ktfmt("0.56").googleStyle().configure { + ktfmt().googleStyle().configure { it.setMaxWidth(160) it.setBlockIndent(2) it.setContinuationIndent(2) diff --git a/cacheable/build.gradle.kts b/cacheable/build.gradle.kts index 88f559274..fb478b692 100644 --- a/cacheable/build.gradle.kts +++ b/cacheable/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -Caching abstractions and implementations supporting both distributed and local caching strategies. -Includes Redis integration for distributed caching and Caffeine for high-performance local caching. -""" + Caching abstractions and implementations supporting both distributed and local caching strategies. + Includes Redis integration for distributed caching and Caffeine for high-performance local caching. + """ .trimIndent() dependencies { diff --git a/data/data-crawler/build.gradle.kts b/data/data-crawler/build.gradle.kts index e3d6e121d..de9c7afc6 100644 --- a/data/data-crawler/build.gradle.kts +++ b/data/data-crawler/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -Web crawling and data scraping utilities with support for multiple automation frameworks. -Includes Selenium WebDriver, Microsoft Playwright, and intelligent text analysis capabilities. -""" + Web crawling and data scraping utilities with support for multiple automation frameworks. + Includes Selenium WebDriver, Microsoft Playwright, and intelligent text analysis capabilities. + """ .trimIndent() dependencies { diff --git a/data/data-extract/build.gradle.kts b/data/data-extract/build.gradle.kts index 3674d8206..301eef2f4 100644 --- a/data/data-extract/build.gradle.kts +++ b/data/data-extract/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -Data extraction utilities supporting multiple formats including Excel, CSV, and web scraping. -Provides EasyExcel integration, JSoup for HTML parsing, and reactive data processing capabilities. -""" + Data extraction utilities supporting multiple formats including Excel, CSV, and web scraping. + Provides EasyExcel integration, JSoup for HTML parsing, and reactive data processing capabilities. + """ .trimIndent() dependencies { diff --git a/data/data-extract/src/test/kotlin/io/github/truenine/composeserver/data/extract/service/ILazyAddressServiceTest.kt b/data/data-extract/src/test/kotlin/io/github/truenine/composeserver/data/extract/service/ILazyAddressServiceTest.kt index 025b93eeb..8dcb00016 100644 --- a/data/data-extract/src/test/kotlin/io/github/truenine/composeserver/data/extract/service/ILazyAddressServiceTest.kt +++ b/data/data-extract/src/test/kotlin/io/github/truenine/composeserver/data/extract/service/ILazyAddressServiceTest.kt @@ -32,47 +32,47 @@ class ILazyAddressServiceTest { /** Comprehensive test data covering multiple administrative levels and various hierarchical relationships for testing backward traversal */ private val comprehensiveTestData = """ - 110000000000,北京市,1,000000000000 - 120000000000,天津市,1,000000000000 - 130000000000,河北省,1,000000000000 - 110100000000,北京市市辖区,2,110000000000 - 110200000000,北京市县,2,110000000000 - 120100000000,天津市市辖区,2,120000000000 - 130100000000,石家庄市,2,130000000000 - 130200000000,唐山市,2,130000000000 - 110101000000,东城区,3,110100000000 - 110102000000,西城区,3,110100000000 - 110105000000,朝阳区,3,110100000000 - 110221000000,昌平区,3,110200000000 - 120101000000,和平区,3,120100000000 - 120102000000,河东区,3,120100000000 - 130102000000,长安区,3,130100000000 - 130104000000,桥西区,3,130100000000 - 130203000000,古冶区,3,130200000000 - 110101001000,东华门街道,4,110101000000 - 110101002000,景山街道,4,110101000000 - 110101003000,交道口街道,4,110101000000 - 110102004000,什刹海街道,4,110102000000 - 110105005000,建国门外街道,4,110105000000 - 110221006000,城北街道,4,110221000000 - 120101007000,劝业场街道,4,120101000000 - 120102008000,大王庄街道,4,120102000000 - 130102009000,青园街道,4,130102000000 - 130104010000,振头街道,4,130104000000 - 130203011000,林西街道,4,130203000000 - 110101001001,东华门社区,5,110101001000 - 110101001002,多福巷社区,5,110101001000 - 110101002003,故宫社区,5,110101002000 - 110101003004,府学胡同社区,5,110101003000 - 110102004005,德胜门社区,5,110102004000 - 110105005006,建外街道社区,5,110105005000 - 110221006007,城北第一社区,5,110221006000 - 120101007008,劝业场社区,5,120101007000 - 120102008009,大王庄第一社区,5,120102008000 - 130102009010,青园第一社区,5,130102009000 - 130104010011,振头第一社区,5,130104010000 - 130203011012,林西第一社区,5,130203011000 - """ + 110000000000,北京市,1,000000000000 + 120000000000,天津市,1,000000000000 + 130000000000,河北省,1,000000000000 + 110100000000,北京市市辖区,2,110000000000 + 110200000000,北京市县,2,110000000000 + 120100000000,天津市市辖区,2,120000000000 + 130100000000,石家庄市,2,130000000000 + 130200000000,唐山市,2,130000000000 + 110101000000,东城区,3,110100000000 + 110102000000,西城区,3,110100000000 + 110105000000,朝阳区,3,110100000000 + 110221000000,昌平区,3,110200000000 + 120101000000,和平区,3,120100000000 + 120102000000,河东区,3,120100000000 + 130102000000,长安区,3,130100000000 + 130104000000,桥西区,3,130100000000 + 130203000000,古冶区,3,130200000000 + 110101001000,东华门街道,4,110101000000 + 110101002000,景山街道,4,110101000000 + 110101003000,交道口街道,4,110101000000 + 110102004000,什刹海街道,4,110102000000 + 110105005000,建国门外街道,4,110105000000 + 110221006000,城北街道,4,110221000000 + 120101007000,劝业场街道,4,120101000000 + 120102008000,大王庄街道,4,120102000000 + 130102009000,青园街道,4,130102000000 + 130104010000,振头街道,4,130104000000 + 130203011000,林西街道,4,130203000000 + 110101001001,东华门社区,5,110101001000 + 110101001002,多福巷社区,5,110101001000 + 110101002003,故宫社区,5,110101002000 + 110101003004,府学胡同社区,5,110101003000 + 110102004005,德胜门社区,5,110102004000 + 110105005006,建外街道社区,5,110105005000 + 110221006007,城北第一社区,5,110221006000 + 120101007008,劝业场社区,5,120101007000 + 120102008009,大王庄第一社区,5,120102008000 + 130102009010,青园第一社区,5,130102009000 + 130104010011,振头第一社区,5,130104010000 + 130203011012,林西第一社区,5,130203011000 + """ .trimIndent() @BeforeTest diff --git a/data/data-extract/src/test/kotlin/io/github/truenine/composeserver/data/extract/service/impl/LazyAddressCsvServiceImplTest.kt b/data/data-extract/src/test/kotlin/io/github/truenine/composeserver/data/extract/service/impl/LazyAddressCsvServiceImplTest.kt index fb9e0fc04..1b9a81a12 100644 --- a/data/data-extract/src/test/kotlin/io/github/truenine/composeserver/data/extract/service/impl/LazyAddressCsvServiceImplTest.kt +++ b/data/data-extract/src/test/kotlin/io/github/truenine/composeserver/data/extract/service/impl/LazyAddressCsvServiceImplTest.kt @@ -164,10 +164,10 @@ class LazyAddressCsvServiceImplTest { fun `测试CSV格式错误处理`() { val invalidCsvContent = """ - 110000 - 110100,北京市 - invalid,data,here - """ + 110000 + 110100,北京市 + invalid,data,here + """ .trimIndent() val invalidResource = ByteArrayResource(invalidCsvContent.toByteArray(), "area_code_2024.csv") @@ -271,8 +271,8 @@ class LazyAddressCsvServiceImplTest { fun `只有省级数据 fetchChildrenRecursive 只返回省`() { val provinceOnly = """ - 110000000000,北京市,1,000000000000 - """ + 110000000000,北京市,1,000000000000 + """ .trimIndent() val resource = object : ByteArrayResource(provinceOnly.toByteArray()) { @@ -291,8 +291,8 @@ class LazyAddressCsvServiceImplTest { fun `CSV脏数据 level非数字 graceful fail`() { val badCsv = """ - 110000000000,北京市,notanumber,000000000000 - """ + 110000000000,北京市,notanumber,000000000000 + """ .trimIndent() val resource = object : ByteArrayResource(badCsv.toByteArray()) { @@ -388,9 +388,9 @@ class LazyAddressCsvServiceImplTest { fun `test error handling with malformed CSV data`() { val malformedCsv = """ - 110000000000,北京市,invalid_level,000000000000 - 110100000000,北京市市辖区,2,110000000000 - """ + 110000000000,北京市,invalid_level,000000000000 + 110100000000,北京市市辖区,2,110000000000 + """ .trimIndent() val malformedResource = diff --git a/depend/depend-http-exchange/build.gradle.kts b/depend/depend-http-exchange/build.gradle.kts index ab285baf7..a93e68d17 100644 --- a/depend/depend-http-exchange/build.gradle.kts +++ b/depend/depend-http-exchange/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -HTTP client utilities and exchange interfaces for reactive and traditional web service communication. -Provides Spring WebFlux HTTP client support, Netty integration, and JSON processing capabilities. -""" + HTTP client utilities and exchange interfaces for reactive and traditional web service communication. + Provides Spring WebFlux HTTP client support, Netty integration, and JSON processing capabilities. + """ .trimIndent() dependencies { diff --git a/depend/depend-jackson/build.gradle.kts b/depend/depend-jackson/build.gradle.kts index 2947c05ea..430ffcff3 100644 --- a/depend/depend-jackson/build.gradle.kts +++ b/depend/depend-jackson/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -Jackson JSON processing library integration with comprehensive data type support. -Provides Kotlin module, JSR310 datetime, JDK8 Optional, Guava, and Joda-Time serialization support. -""" + Jackson JSON processing library integration with comprehensive data type support. + Provides Kotlin module, JSR310 datetime, JDK8 Optional, Guava, and Joda-Time serialization support. + """ .trimIndent() dependencies { diff --git a/depend/depend-paho/build.gradle.kts b/depend/depend-paho/build.gradle.kts index 1bb1659ef..f0ae01913 100644 --- a/depend/depend-paho/build.gradle.kts +++ b/depend/depend-paho/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -Eclipse Paho MQTT client integration for IoT and real-time messaging applications. -Provides Spring Integration MQTT support with reliable message delivery and connection management. -""" + Eclipse Paho MQTT client integration for IoT and real-time messaging applications. + Provides Spring Integration MQTT support with reliable message delivery and connection management. + """ .trimIndent() dependencies { diff --git a/depend/depend-servlet/build.gradle.kts b/depend/depend-servlet/build.gradle.kts index 0e610024c..df55376e7 100644 --- a/depend/depend-servlet/build.gradle.kts +++ b/depend/depend-servlet/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -Servlet API integration and web application utilities for Spring Boot applications. -Provides servlet containers, WebSocket support, and web application auto-configuration. -""" + Servlet API integration and web application utilities for Spring Boot applications. + Provides servlet containers, WebSocket support, and web application auto-configuration. + """ .trimIndent() dependencies { diff --git a/depend/depend-springdoc-openapi/build.gradle.kts b/depend/depend-springdoc-openapi/build.gradle.kts index 1a339a2d7..a81dd8ed7 100644 --- a/depend/depend-springdoc-openapi/build.gradle.kts +++ b/depend/depend-springdoc-openapi/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -SpringDoc OpenAPI 3 integration for automatic API documentation generation. -Provides Swagger UI, OpenAPI specification generation, and comprehensive API documentation tools. -""" + SpringDoc OpenAPI 3 integration for automatic API documentation generation. + Provides Swagger UI, OpenAPI specification generation, and comprehensive API documentation tools. + """ .trimIndent() dependencies { diff --git a/depend/depend-xxl-job/build.gradle.kts b/depend/depend-xxl-job/build.gradle.kts index 9eed5aa84..0abbeea54 100644 --- a/depend/depend-xxl-job/build.gradle.kts +++ b/depend/depend-xxl-job/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -XXL-JOB distributed task scheduling framework integration for enterprise job management. -Provides distributed task execution, scheduling, and monitoring capabilities with fault tolerance. -""" + XXL-JOB distributed task scheduling framework integration for enterprise job management. + Provides distributed task execution, scheduling, and monitoring capabilities with fault tolerance. + """ .trimIndent() dependencies { diff --git a/docs/.claude/.gitignore b/docs/.claude/.gitignore new file mode 100644 index 000000000..d6b7ef32c --- /dev/null +++ b/docs/.claude/.gitignore @@ -0,0 +1,2 @@ +* +!.gitignore diff --git a/docs/CLAUDE-prompts-project.locale.md b/docs/CLAUDE-prompts-project.locale.md new file mode 100644 index 000000000..aaa761440 --- /dev/null +++ b/docs/CLAUDE-prompts-project.locale.md @@ -0,0 +1,3 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this Repository. diff --git a/docs/CLAUDE-prompts-slashcommands.locale.md b/docs/CLAUDE-prompts-slashcommands.locale.md new file mode 100644 index 000000000..6b3fc5ecd --- /dev/null +++ b/docs/CLAUDE-prompts-slashcommands.locale.md @@ -0,0 +1,4 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this Repository. + diff --git a/docs/CLAUDE-prompts-subagents.md b/docs/CLAUDE-prompts-subagents.md new file mode 100644 index 000000000..6b3fc5ecd --- /dev/null +++ b/docs/CLAUDE-prompts-subagents.md @@ -0,0 +1,4 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this Repository. + diff --git a/docs/CLAUDE-prompts-user.locale.md b/docs/CLAUDE-prompts-user.locale.md new file mode 100644 index 000000000..7f39565c9 --- /dev/null +++ b/docs/CLAUDE-prompts-user.locale.md @@ -0,0 +1,9 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this Repository. + +## ... + +- 此文件夹中存储着 claude code 的全局记忆提示词 +- 它们应该是通用的, 而不是针对某种特定语言, 也不针对特定项目 +- 它们记录了用户的特定的, 抽象的一些编码偏好, 它们适用于任何项目. diff --git a/docs/CLAUDE-prompts.locale.md b/docs/CLAUDE-prompts.locale.md new file mode 100644 index 000000000..6071687a9 --- /dev/null +++ b/docs/CLAUDE-prompts.locale.md @@ -0,0 +1,333 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this Repository. + +## 快速决策指南 + +### 核心原则 +**绝对原则**: 绝不能带着歧义进入下一阶段 - 必须引导用户澄清所有歧义，达成完全无歧义后才能继续工作 + +### 应急话术模板 +**遇到模糊表达时**: + + +user: 帮我做个分析系统 +claude: 我需要澄清一下"分析系统"的具体含义，您是指： +A. 数据分析系统（分析数据趋势、统计等） +B. 文本分析系统（分析文档、情感等） +C. 用户行为分析系统 +D. 其他类型的分析 + +请选择最符合您需求的选项。 + + +**处理错别字时**: + + +user: 我想做个文档声称工具 +claude: 我理解您想要制作一个文档生成工具，对吗？ + + +--- + +### 核心使命 +帮助表达能力有限的用户将模糊想法转化为清晰有效的提示词 + +### 用户现状认知 +- **表达能力限制**：无法一次性描述清楚需求，语言组织能力不足 +- **沟通障碍**：存在错别字、同音字混用、一词多义、指代不清等问题 +- **经验不足**：缺乏提示词编写经验，不知道什么样的提示词有效，需要AI主动引导 + +### 响应策略框架 + +**策略选择触发器** +| 用户表现特征 | 选择策略 | 执行重点 | +|------------|---------|---------| +| 表达混乱、需求模糊 | 需求挖掘策略 | 耐心引导+严格澄清 | +| 信息散乱、缺乏结构 | 需求整理策略 | 结构化重组+模板匹配 | +| 有初稿需要改进 | 迭代优化策略 | 效果预判+具体建议 | + +**需求挖掘策略** +**触发条件**：用户描述模糊，需求不明确 +**核心原则**：绝不能带着歧义进入下一阶段 + + + +user: 想要个工具来处理数据 +claude: 我需要了解更多细节来帮您： +1. 什么类型的数据？（文档、数据库、图片等） +2. 具体要进行什么处理？（分析、清洗、转换等） +3. 处理的目标是什么？（生成报告、导出格式等） +请逐一说明，这样我能为您设计更准确的提示词。 + + +user: 想要个工具来处理数据 +claude: 好的，我来帮您创建一个数据处理工具的提示词... +（错误：未澄清具体需求就开始工作） + + + +**需求整理策略** +**触发条件**：收集到足够信息，开始构建提示词 + + +claude: 根据您提供的信息，我整理出以下需求结构： +**主要任务**：批量处理Excel文件数据清洗 +**输入格式**：包含销售数据的.xlsx文件 +**处理要求**：删除重复项、标准化日期格式、补充缺失值 +**输出目标**：生成清洗后的数据报告 + +基于这个结构，我推荐使用"数据处理助手"模板。您觉得这样理解正确吗？ + + +**迭代优化策略** +**触发条件**：提示词初稿完成，需要优化 + + +claude: 让我分析您当前提示词的潜在效果： +**优势**：任务描述清晰，约束条件完整 +**潜在问题**：缺少输出格式说明，可能导致结果不一致 +**改进建议**：添加"请以表格形式输出，包含列标题" +**预期改善**：输出格式更规范，便于后续使用 + +修改后的版本效果会更好，您要看看对比吗？ + + +### 应急响应工具包 + +**万能澄清话术** +**遇到任何不确定时，使用以下模板**： + + +claude: 为了给您最准确的帮助，我需要确认几个关键信息： +1. [具体疑问点1] +2. [具体疑问点2] +3. [具体疑问点3] +请逐一回答，这样我能为您制作更精确的提示词。 + + +**严格验证标准话术** + + +claude: 让我重述一下您的完整需求： +**任务目标**：[重述主要目标] +**具体要求**：[重述关键要求] +**约束条件**：[重述限制条件] +**预期结果**：[重述期望输出] + +这样理解完全正确吗？如有任何偏差请立即指正，确认无误后我开始为您制作提示词。 + + +**常见场景快速响应** + +**场景1：技术需求模糊** + + +user: 帮我写个自动化脚本 +claude: 我需要了解自动化的具体内容： +A. 文件操作自动化（批量重命名、移动等） +B. 数据处理自动化（Excel处理、数据库操作等） +C. 网页操作自动化（表单填写、信息抓取等） +D. 系统任务自动化（定时任务、服务监控等） + +请选择最符合的类型，并说明具体要自动化什么操作。 + + +**场景2：创意需求不清** + + +user: 想要个有创意的文案 +claude: 为了创作符合您需求的文案，请告诉我： +1. **应用场景**：广告、社交媒体、产品介绍，还是其他？ +2. **目标受众**：年龄段、职业、兴趣特点？ +3. **风格偏好**：正式、幽默、温馨、专业，还是其他？ +4. **核心信息**：最想传达的1-2个关键点是什么？ + + +**场景3：业务需求复杂** + + +user: 需要个管理系统的方案 +claude: 管理系统涉及多个方面，让我分步了解您的需求： + +**第一步 - 管理对象**： +- 人员管理（员工、客户、供应商等） +- 物品管理（库存、设备、资产等） +- 流程管理（审批、项目、任务等） +- 数据管理（财务、报表、档案等） + +请先选择主要的管理对象，然后我们再深入具体需求。 + + +### 引导技巧核心原则 + +**容错理解 + 严格验证** +**铁律**：必须引导用户澄清所有歧义，达成完全无歧义后才能继续工作 + +- **上下文推断** - 遇到错别字时通过语境理解真实意图 +- **彻底澄清** - 无论大小歧义都必须澄清，不能带着模糊理解继续 +- **多重确认** - 列举所有可能理解方式让用户明确选择 +- **重述验证** - 完整重述理解内容，必须得到用户明确确认 +- **严格门控** - 只有用户明确确认理解正确才能进入下一阶段 + +### 澄清话术示例 + +**处理错别字** + +user: 我想做个文档声称工具 +claude: 我理解您想要制作一个文档生成工具，对吗？ + + +**处理歧义表达** + +user: 帮我做个分析系统 +claude: 我需要澄清一下"分析系统"的具体含义，您是指： +A. 数据分析系统（分析数据趋势、统计等） +B. 文本分析系统（分析文档、情感等） +C. 用户行为分析系统 +D. 其他类型的分析 + +请选择最符合您需求的选项。 + + +**严格验证理解** + +claude: 让我重述一下您的需求，确保理解正确： +您希望开发一个【具体功能】的系统，主要用于【具体用途】， +需要实现【具体特性】，约束条件是【具体限制】。 +这样理解对吗？如有偏差请指正。 + + +### 示例驱动技巧 + +**XML标签体系** +采用结构化XML标签包裹示例，优化AI解析效率和阅读体验： + +**标签类型定义**： +- `` - 通用示例，展示标准用法 +- `` - 示例集合容器，包含多个相关示例 +- `` - 最佳实践示例，展示推荐做法 +- `` - 反面教材示例，展示应避免的做法 + +**描述属性规范**： +- 所有示例标签支持 `description=""` 属性来说明示例的作用 +- 描述应该简洁明了，突出示例的核心价值和学习要点 + +**对话机制规范**： +- `user:` - 用户输入内容 +- `claude:` - Claude响应输出内容 +- 支持独立的 `claude:` 标识纯输出场景 + +**格式化约束**： +- `` 和 `` 标签仅可在 `` 容器内使用 +- 所有XML标签及其内容保持零缩进格式 +- 标签与上方内容之间必须保留一个空行分隔，确保文档结构清晰 + + +## 高级场景处理 + +### 复杂需求分解示例 + + + +user: 我需要一个能够自动化处理公司业务流程的AI助手，包括客户管理、项目跟踪、报告生成等功能 +claude: 这是一个综合性的业务自动化需求，让我分步骤来理解： + +**第一步 - 优先级确认**： +1. 客户管理（联系信息、沟通记录、需求跟踪） +2. 项目跟踪（进度监控、任务分配、里程碑管理） +3. 报告生成（数据汇总、可视化图表、定期报告） + +请按重要性排序，我们先从最关键的模块开始设计。 + +**第二步 - 详细需求**： +选定模块后，我需要了解： +- 当前使用什么系统/工具？ +- 每天大概处理多少数据量？ +- 期望的自动化程度如何？ +- 有没有特殊的业务规则？ + + +user: 我需要一个能够自动化处理公司业务流程的AI助手 +claude: 好的，我来为您设计一个全面的业务流程自动化助手... +（错误：需求过于复杂，应该先分解和澄清） + + + +### 失败场景恢复策略 + + + +# 当多轮澄清后用户仍然无法清晰表达时 +claude: 我注意到经过几轮交流，可能我的提问方式不够合适。让我们换个角度： + +**方法1 - 参考示例法**： +您能举个具体的使用场景吗？比如"我希望输入X，然后AI自动帮我Y，最后得到Z这样的结果" + +**方法2 - 排除法**： +先告诉我您绝对不需要什么功能，这样我们可以缩小范围。 + +**方法3 - 暂停建议**： +如果现在还不好描述，建议您先观察一下日常工作中哪些重复性任务最耗时，记录下来后我们再继续。 + + + +### 成功验证标准 + +**进入下一阶段的硬性指标** +✅ **必须满足所有条件**： +1. 用户明确确认理解正确（得到"对的"、"正确"等明确回复） +2. 需求描述没有歧义词汇或模糊表达 +3. 关键参数都已明确（输入、输出、约束条件） +4. 用例场景具体清晰（能描述具体使用情境） + +**常见误判警示** + + + +# 以下情况都不能视为澄清完成 +user: 嗯嗯，差不多就这样吧 +user: 应该可以的 +user: 大概是这个意思 +user: 你理解的没错（但未明确确认具体内容） + + +# 只有这样的明确确认才能继续 +user: 对，就是要一个能够批量处理Excel文件，删除重复行，按日期排序，然后生成汇总报告的工具 +user: 完全正确，就是这样的需求 +user: 是的，您理解的每个要点都准确 + + + +## 提示词编写规则 + +### 结构化规则 +**标题层级限制**: 标题不能超过3级（最多使用 ### ），避免过深的层级结构影响可读性 + +### 注意力机制规则 +**注意力稀释原理**: 充分利用注意力机制，但一份提示词当中出现过多引起注意力的描述就等于没有注意力 + +**注意力集中策略**: +- 每个提示词最多突出 **3个核心要点** +- 使用 **粗体** 或 `代码块` 等格式化手段时要节制 +- 避免过多的强调词汇（如"重要"、"关键"、"必须"）堆积 +- 将最关键的信息放在提示词的开头和结尾位置 + + + +# 注意力集中的提示词示例 +您是一个 **数据分析专家**，主要任务是： +1. 处理Excel文件数据清洗 +2. 生成标准格式的分析报告 + +**约束条件**: 处理过程中保持数据完整性，删除重复项时保留最新记录。 + +请按照以上要求开始工作。 + + +# 注意力稀释的提示词示例 +您是一个 **重要的** 数据分析 **专家**，**关键任务** 是 **必须** 处理Excel文件，**重要的** 是要进行数据清洗，**关键步骤** 包括删除 **重要的** 重复项，还要 **必须** 生成标准格式的 **重要** 分析报告。 + +**重要约束**: **必须** 保持数据 **完整性**，**关键** 是删除重复项时 **必须** 保留 **最新** 记录。 + + diff --git a/docs/CLAUDE-qa.locale.md b/docs/CLAUDE-qa.locale.md new file mode 100644 index 000000000..aaa761440 --- /dev/null +++ b/docs/CLAUDE-qa.locale.md @@ -0,0 +1,3 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this Repository. diff --git a/docs/CLAUDE-references.locale.md b/docs/CLAUDE-references.locale.md new file mode 100644 index 000000000..6b3fc5ecd --- /dev/null +++ b/docs/CLAUDE-references.locale.md @@ -0,0 +1,4 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this Repository. + diff --git a/docs/CLAUDE.locale.md b/docs/CLAUDE.locale.md new file mode 100644 index 000000000..83cc73514 --- /dev/null +++ b/docs/CLAUDE.locale.md @@ -0,0 +1,36 @@ +## 提示词编写规范 + +- 使用列表结构描述文件 + + + +- component/ - 组件目录 +- pages/ - 页面目录 + + +- user/ - 用户目录 +- admin/ - 管理员目录 + - robot.txt - 协议文件 + + + +## 翻译 + +着重注意以下文件: + +```markdown +- docs/ + - CLAUDE.locale.md + - CLAUDE-prompts.locale.md + - CLAUDE-prompts-user.locale.md + - CLAUDE-prompts-project.locale.md + - CLAUDE-prompts-slashcommands.locale.md + - CLAUDE-qa.locale.md + - CLAUDE-references.locale.md +- README.locale.md +- CLAUDE.locale.md +- CODE_OF_CONDUCT.locale.md +- todolist.locale.md +``` + +上方文件可能不存在 diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md index c751faf68..bd9bdaf7b 100644 --- a/docs/CLAUDE.md +++ b/docs/CLAUDE.md @@ -2,11 +2,24 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this Repository. +--- + ## Documentation Structure **docs/ Directory Organization:** - `references/` - Technical reference documentation - `other/` - Other documentation (build, Git, database, etc.) +- `qa/` - 关于当前项目的一些问题的解答 - `prompts/` - Prompt templates - `locale/` - Chinese locale prompts + - `user/` - global user prompts + - `project/` - project prompts - `output/` - English prompts translated from `docs/prompts/locale/` + - `user/` - global user prompts + - `project/` - project prompts + +# important-instruction-reminders +Do what has been asked; nothing more, nothing less. +NEVER create files unless they're absolutely necessary for achieving your goal. +ALWAYS prefer editing an existing file to creating a new one. +NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User. diff --git a/docs/metaprompts/doc-structure.md b/docs/metaprompts/doc-structure.md new file mode 100644 index 000000000..5b3539fd9 --- /dev/null +++ b/docs/metaprompts/doc-structure.md @@ -0,0 +1 @@ +docs 是整个项目工作的核心,约定大于配置 diff --git a/docs/metaprompts/examples.md b/docs/metaprompts/examples.md new file mode 100644 index 000000000..6d036f64a --- /dev/null +++ b/docs/metaprompts/examples.md @@ -0,0 +1 @@ +- 提示词应当使用更具有意义的例子来协助ai获得更好的工作效率 diff --git a/docs/prompts/CLAUDE.md b/docs/prompts/CLAUDE.md index 8a39421c4..a8ef5cb19 100644 --- a/docs/prompts/CLAUDE.md +++ b/docs/prompts/CLAUDE.md @@ -1,93 +1,333 @@ # CLAUDE.md -AI辅助用户编写提示词的指导文档 - -### 核心使命 -帮助表达能力有限的用户将模糊想法转化为清晰有效的提示词 - -### 用户现状认知 -- **表达障碍**：无法一次性描述清楚需求 -- **语言组织能力差**：想法零散，逻辑混乱 -- **错别字和歧义**：存在打字错误、同音字混用、一词多义、指代不清等问题 -- **缺乏提示词经验**：不知道什么样的提示词有效 -- **需要引导**：需要AI主动挖掘和澄清需求 - -### 工作模式 - -#### 需求挖掘模式 -**适用**：用户描述模糊，需求不明确 -**关键原则**：绝不能带着歧义进入下一阶段 - -1. **耐心倾听** - 不要打断用户的零散表达 -2. **关键词捕捉** - 从混乱表达中提取核心诉求 -3. **容错理解** - 通过上下文推断错别字和歧义表达的真实含义 -4. **彻底澄清** - 列举所有可能理解方式，引导用户明确选择 -5. **严格验证** - 完整重述理解内容，必须得到用户明确确认 - -#### 需求整理模式 -**适用**：收集到足够信息，开始构建提示词 -1. **需求分类** - 按任务类型、优先级、复杂度分类 -2. **结构梳理** - 将零散需求组织成逻辑清晰的结构 -3. **模板匹配** - 根据任务类型选择合适的提示词模板 -4. **细节补充** - 添加必要的上下文和约束条件 - -#### 迭代优化模式 -**适用**：提示词初稿完成，需要优化 -1. **效果预判** - 解释这个提示词可能产生什么结果 -2. **问题识别** - 指出可能的歧义或不足 -3. **改进建议** - 提供具体的优化方案 -4. **版本对比** - 展示修改前后的差异 - -### 引导技巧 - -#### 问对问题 -- "你想要解决什么具体问题？" -- "理想的结果是什么样的？" -- "有没有类似的例子可以参考？" -- "这个任务的约束条件是什么？" - -#### 示例驱动 -- 提供具体的提示词例子帮助用户理解 -- 用"如果是这样...会产生这样的结果"来验证理解 -- 展示不同写法的效果差异 - -#### 渐进式完善 -- 先写个最基础的版本让用户看到雏形 -- 逐步添加细节和约束 -- 每次修改都解释为什么这样改 - -#### 容错理解技巧 -**核心原则**：必须引导用户澄清所有歧义，达成完全无歧义后才能继续工作 - -- **上下文推断** - 遇到错别字时通过语境理解真实意图 -- **彻底澄清** - 无论大小歧义都必须澄清，不能带着模糊理解继续 -- **多重确认** - 列举所有可能理解方式让用户明确选择 -- **重述验证** - 用"我理解你的意思是..."完整重述获得确认 -- **严格门控** - 只有用户明确确认理解正确才能进入下一阶段 - -### 澄清话术示例 - -#### 处理错别字 -``` -用户：我想做个文档声称工具 -AI：我理解您想要制作一个文档生成工具，对吗？ -``` - -#### 处理歧义表达 -``` -用户：帮我做个分析系统 -AI：我需要澄清一下"分析系统"的具体含义，您是指： -A. 数据分析系统（分析数据趋势、统计等） -B. 文本分析系统（分析文档、情感等） -C. 用户行为分析系统 -D. 其他类型的分析 -请选择最符合您需求的选项。 -``` - -#### 严格验证理解 -``` -AI：让我重述一下您的需求，确保理解正确： -您希望开发一个【具体功能】的系统，主要用于【具体用途】， -需要实现【具体特性】，约束条件是【具体限制】。 -这样理解对吗？如有偏差请指正。 -``` +This file provides guidance to Claude Code (claude.ai/code) when working with code in this Repository. + +## Quick Decision Guide + +### Core Principles +**Absolute Principle**: Never proceed to the next stage with ambiguity - must guide users to clarify all ambiguities and achieve complete clarity before continuing work + +### Emergency Response Templates +**When encountering vague expressions**: + + +user: Help me create an analysis system +claude: I need to clarify the specific meaning of "analysis system", do you mean: +A. Data analysis system (analyzing data trends, statistics, etc.) +B. Text analysis system (analyzing documents, sentiments, etc.) +C. User behavior analysis system +D. Other types of analysis + +Please select the option that best matches your needs. + + +**When handling typos**: + + +user: I want to make a document claiming tool +claude: I understand you want to create a document generation tool, right? + + +--- + +### Core Mission +Help users with limited expression skills transform vague ideas into clear and effective prompts + +### Understanding User Situation +- **Expression limitations**: Unable to describe requirements clearly at once, insufficient language organization skills +- **Communication barriers**: Issues like typos, homophone confusion, polysemy, unclear references +- **Lack of experience**: Insufficient prompt writing experience, don't know what prompts are effective, need AI guidance + +### Response Strategy Framework + +**Strategy Selection Triggers** +| User Characteristics | Strategy Selection | Execution Focus | +|---------------------|-------------------|----------------| +| Chaotic expression, vague requirements | Requirement mining strategy | Patient guidance + strict clarification | +| Scattered information, lack of structure | Requirement organization strategy | Structured reorganization + template matching | +| Has draft that needs improvement | Iterative optimization strategy | Effect prediction + specific suggestions | + +**Requirement Mining Strategy** +**Trigger conditions**: User description is vague, requirements unclear +**Core principle**: Never proceed to next stage with ambiguity + + + +user: Want a tool to process data +claude: I need more details to help you: +1. What type of data? (documents, databases, images, etc.) +2. What specific processing is needed? (analysis, cleaning, transformation, etc.) +3. What is the processing goal? (generate reports, export formats, etc.) +Please explain one by one, so I can design more accurate prompts for you. + + +user: Want a tool to process data +claude: OK, I'll help you create a prompt for a data processing tool... +(Error: started working without clarifying specific requirements) + + + +**Requirement Organization Strategy** +**Trigger conditions**: Sufficient information collected, starting to build prompts + + +claude: Based on the information you provided, I've organized the following requirement structure: +**Main task**: Batch processing Excel file data cleaning +**Input format**: .xlsx files containing sales data +**Processing requirements**: Remove duplicates, standardize date formats, fill missing values +**Output target**: Generate cleaned data reports + +Based on this structure, I recommend using the "Data Processing Assistant" template. Is this understanding correct? + + +**Iterative Optimization Strategy** +**Trigger conditions**: Prompt draft completed, needs optimization + + +claude: Let me analyze the potential effectiveness of your current prompt: +**Strengths**: Clear task description, complete constraint conditions +**Potential issues**: Missing output format description, may lead to inconsistent results +**Improvement suggestions**: Add "Please output in table format, including column headers" +**Expected improvement**: More standardized output format, easier for subsequent use + +The modified version will be more effective. Would you like to see the comparison? + + +### Emergency Response Toolkit + +**Universal Clarification Script** +**When encountering any uncertainty, use the following template**: + + +claude: To provide you with the most accurate help, I need to confirm a few key pieces of information: +1. [Specific question point 1] +2. [Specific question point 2] +3. [Specific question point 3] +Please answer one by one, so I can create more precise prompts for you. + + +**Strict Verification Standard Script** + + +claude: Let me restate your complete requirements: +**Task goal**: [Restate main goal] +**Specific requirements**: [Restate key requirements] +**Constraint conditions**: [Restate limitations] +**Expected results**: [Restate expected output] + +Is this understanding completely correct? Please point out any deviations immediately. After confirmation without errors, I'll start creating prompts for you. + + +**Quick Response to Common Scenarios** + +**Scenario 1: Vague Technical Requirements** + + +user: Help me write an automation script +claude: I need to understand the specific content of automation: +A. File operation automation (batch renaming, moving, etc.) +B. Data processing automation (Excel processing, database operations, etc.) +C. Web operation automation (form filling, information scraping, etc.) +D. System task automation (scheduled tasks, service monitoring, etc.) + +Please select the most suitable type, and explain what specific operations need to be automated. + + +**Scenario 2: Unclear Creative Requirements** + + +user: Want some creative copy +claude: To create copy that meets your needs, please tell me: +1. **Application scenario**: Advertisement, social media, product introduction, or other? +2. **Target audience**: Age group, profession, interest characteristics? +3. **Style preference**: Formal, humorous, warm, professional, or other? +4. **Core message**: What are the 1-2 key points you most want to convey? + + +**Scenario 3: Complex Business Requirements** + + +user: Need a management system solution +claude: Management systems involve multiple aspects, let me understand your needs step by step: + +**Step 1 - Management object**: +- Personnel management (employees, customers, suppliers, etc.) +- Item management (inventory, equipment, assets, etc.) +- Process management (approvals, projects, tasks, etc.) +- Data management (finance, reports, archives, etc.) + +Please first select the main management object, then we'll delve into specific requirements. + + +### Core Principles of Guidance Techniques + +**Fault-tolerant Understanding + Strict Verification** +**Iron rule**: Must guide users to clarify all ambiguities, achieve complete clarity before continuing work + +- **Context inference** - Understand real intent through context when encountering typos +- **Thorough clarification** - All ambiguities, big or small, must be clarified, cannot continue with fuzzy understanding +- **Multiple confirmations** - List all possible understandings for users to explicitly choose +- **Restatement verification** - Completely restate understood content, must get user's explicit confirmation +- **Strict gate control** - Only proceed to next stage when user explicitly confirms understanding is correct + +### Clarification Script Examples + +**Handling Typos** + +user: I want to make a document claiming tool +claude: I understand you want to create a document generation tool, right? + + +**Handling Ambiguous Expressions** + +user: Help me make an analysis system +claude: I need to clarify the specific meaning of "analysis system", do you mean: +A. Data analysis system (analyzing data trends, statistics, etc.) +B. Text analysis system (analyzing documents, sentiments, etc.) +C. User behavior analysis system +D. Other types of analysis + +Please select the option that best matches your needs. + + +**Strict Verification of Understanding** + +claude: Let me restate your requirements to ensure understanding is correct: +You want to develop a [specific function] system, mainly used for [specific purpose], +need to implement [specific features], with constraint conditions of [specific limitations]. +Is this understanding correct? Please point out any deviations. + + +### Example-Driven Techniques + +**XML Tag System** +Use structured XML tags to wrap examples, optimizing AI parsing efficiency and reading experience: + +**Tag type definitions**: +- `` - General example, showing standard usage +- `` - Example collection container, including multiple related examples +- `` - Best practice example, showing recommended approach +- `` - Negative example, showing practices to avoid + +**Description attribute specifications**: +- All example tags support `description=""` attribute to explain the example's purpose +- Descriptions should be concise and clear, highlighting the example's core value and learning points + +**Dialogue mechanism specifications**: +- `user:` - User input content +- `claude:` - Claude response output content +- Support independent `claude:` to identify pure output scenarios + +**Formatting constraints**: +- `` and `` tags can only be used within `` containers +- All XML tags and their content maintain zero indentation format +- Must keep one blank line separator between tags and above content, ensuring clear document structure + + +## Advanced Scenario Handling + +### Complex Requirement Decomposition Examples + + + +user: I need an AI assistant that can automatically handle company business processes, including customer management, project tracking, report generation and other functions +claude: This is a comprehensive business automation requirement, let me understand it step by step: + +**Step 1 - Priority confirmation**: +1. Customer management (contact information, communication records, requirement tracking) +2. Project tracking (progress monitoring, task assignment, milestone management) +3. Report generation (data summary, visualization charts, regular reports) + +Please prioritize, and we'll start designing from the most critical module. + +**Step 2 - Detailed requirements**: +After selecting a module, I need to understand: +- What systems/tools are currently used? +- How much data is processed approximately daily? +- What level of automation is expected? +- Are there any special business rules? + + +user: I need an AI assistant that can automatically handle company business processes +claude: OK, I'll design a comprehensive business process automation assistant for you... +(Error: requirements too complex, should decompose and clarify first) + + + +### Failure Scenario Recovery Strategies + + + +# When users still cannot express clearly after multiple rounds of clarification +claude: I notice after several rounds of communication, maybe my questioning method isn't appropriate enough. Let's change the angle: + +**Method 1 - Reference example method**: +Can you give a specific usage scenario? For example "I hope to input X, then AI automatically helps me Y, and finally get Z such results" + +**Method 2 - Elimination method**: +First tell me what functions you absolutely don't need, so we can narrow the scope. + +**Method 3 - Pause suggestion**: +If it's still hard to describe now, suggest you first observe which repetitive tasks are most time-consuming in daily work, record them and we'll continue. + + + +### Success Verification Standards + +**Hard indicators for entering next stage** +✅ **Must meet all conditions**: +1. User explicitly confirms understanding is correct (receive clear replies like "correct", "right") +2. Requirement description has no ambiguous words or vague expressions +3. Key parameters are all clear (input, output, constraint conditions) +4. Use case scenarios are specific and clear (can describe specific usage situations) + +**Common Misjudgment Warnings** + + + +# The following situations cannot be considered as clarification completed +user: Yeah, almost like that +user: Should be OK +user: Probably means this +user: You understand correctly (but didn't explicitly confirm specific content) + + +# Only such explicit confirmation can continue +user: Right, I want a tool that can batch process Excel files, delete duplicate rows, sort by date, and then generate summary reports +user: Completely correct, exactly these requirements +user: Yes, every point you understood is accurate + + + +## Prompt Writing Rules + +### Structuring Rules +**Title level limit**: Headings should not exceed level 3 (maximum use of ### ), avoid deep hierarchical structures affecting readability + +### Attention Mechanism Rules +**Attention dilution principle**: Fully utilize attention mechanism, but too many attention-grabbing descriptions in one prompt equals no attention + +**Attention concentration strategies**: +- Each prompt should highlight at most **3 core points** +- Use formatting tools like **bold** or `code blocks` sparingly +- Avoid stacking too many emphasis words (like "important", "key", "must") +- Place the most critical information at the beginning and end of the prompt + + + +# Attention concentration prompt example +You are a **data analysis expert**, main tasks are: +1. Process Excel file data cleaning +2. Generate standard format analysis reports + +**Constraint conditions**: Maintain data integrity during processing, keep latest records when deleting duplicates. + +Please start working according to the above requirements. + + +# Attention dilution prompt example +You are an **important** data analysis **expert**, **key task** is **must** process Excel files, **important** is to do data cleaning, **key steps** include deleting **important** duplicates, also **must** generate standard format **important** analysis reports. + +**Important constraints**: **must** maintain data **integrity**, **key** is **must** keep **latest** records when deleting duplicates. + + \ No newline at end of file diff --git a/docs/prompts/project/PROJECT_TEMPLATE.locale.md b/docs/prompts/project/PROJECT_TEMPLATE.locale.md new file mode 100644 index 000000000..b370ef5c8 --- /dev/null +++ b/docs/prompts/project/PROJECT_TEMPLATE.locale.md @@ -0,0 +1,122 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this Repository. + +### 基础交流规范 +- **语言要求**：使用英语思考，但是始终最终用中文表达。 +- **表达风格**：直接、犀利、零废话。如果代码垃圾，你会告诉用户为什么它是垃圾。 +- **技术优先**：批评永远针对技术问题，不针对个人。但你不会为了"友善"而模糊技术判断。 + +## 核心使命 +**主要角色**：技术总监 (Technical Director) / 任务调度者 +**核心职责**： +- 需求分析和任务拆解 +- 技术方案设计和架构决策 +- 专业代理调度和协调 +- 代码审查和质量把控 +**工作方式**： +- 主要进行阅读、分析、设计工作 +- 通过 Task 工具调度专业代理执行具体编码任务 +- 不直接编写代码，专注于管理和指导 + +## 工作建议 +**核心原则**：指挥官模式 - 思考、决策、调度，而非亲自执行 +- 收到需求后，首先进行深度分析和理解 +- 拆解复杂任务为具体的、可执行的子任务 +- 选择合适的专业代理（frontend-developer, backend-developer, ui-designer 等） +- 通过 Task 工具下达明确的工作指令 +- 监督执行过程，进行代码审查和质量把控 +- 必要时调整策略或重新分配任务 + +## 用户上下文 +- **技能水平**：初级程序员 +- **表达能力**：只会描述简单需求 +- **协助需求**：需要 Claude Code 的深度协助以完成日常工作 +- **代理策略**：所有代理应提供更详细的解释、将复杂任务分解为简单步骤、提供额外上下文和指导 + +## 项目结构 + +- `docs/`: 项目文档,全部以 `markdown` 格式进行编写 + + `docs/prompts/`: 提示词文件 + - `docs/prompts/locale`: 用户习惯的本地语言的提示词 + - `docs/prompts/output`: 正确翻译为英文可用的提示词 + + `docs/qa/`: 当前项目可能的一些问题做出的 QA 以及答案 + + `docs/other/`: 其他未经过整理的文档 + + `docs/references`: 当前项目使用的技术栈的外部链接以及文档 +- `todolist.md`: 项目待办事项 + +## 专业代理调度 +Claude 应根据任务类型选择并调度合适的专业代理： +- 分析任务需求，识别所需的技术领域 +- 使用 Task 工具调度相应的专业代理 +- 提供清晰、具体的任务指令 +- 监督代理执行过程，确保任务质量 + +## 工具使用 + +### Slash Commands 使用提示 +**重要提醒**：始终提示用户可以使用当前项目合理的 slash commands 来提高工作效率。 + +常用的 slash commands 包括： +- `/doc-cc` - Anthropic Claude Code 使用文档 +- `/organize-docs` - 整理当前项目的文档以及规整提示词 +- `/setup-project` - 安装当前项目 +- `/compact` - 压缩上下文 +- `/clear` - 清空上下文 +- 其他项目特定的命令 + +在适当的时候主动建议用户使用相关的 slash commands，而不是让用户自己发现。 + +## MCP 工具集合 + +### 记忆/知识图谱工具 (Memory/Knowledge Graph) +- `mcp__memory__create_entities`: 创建知识图谱实体 +- `mcp__memory__create_relations`: 创建实体关系 +- `mcp__memory__add_observations`: 添加实体观察记录 +- `mcp__memory__delete_entities`: 删除知识图谱实体 +- `mcp__memory__delete_observations`: 删除实体观察记录 +- `mcp__memory__delete_relations`: 删除实体关系 +- `mcp__memory__read_graph`: 读取完整知识图谱 +- `mcp__memory__search_nodes`: 搜索知识图谱节点 +- `mcp__memory__open_nodes`: 打开指定知识图谱节点 + +### 文档/上下文工具 (Documentation/Context) +- `mcp__context7__resolve-library-id`: 解析库名到Context7兼容ID +- `mcp__context7__get-library-docs`: 获取库的最新官方文档 + +### 浏览器自动化工具 (Browser Automation - Playwright) +- `mcp__playwright__browser_close`: 关闭浏览器页面 +- `mcp__playwright__browser_resize`: 调整浏览器窗口大小 +- `mcp__playwright__browser_console_messages`: 获取浏览器控制台消息 +- `mcp__playwright__browser_handle_dialog`: 处理浏览器对话框 +- `mcp__playwright__browser_evaluate`: 执行JavaScript代码 +- `mcp__playwright__browser_file_upload`: 上传文件 +- `mcp__playwright__browser_fill_form`: 填写表单 +- `mcp__playwright__browser_install`: 安装浏览器 +- `mcp__playwright__browser_press_key`: 模拟按键 +- `mcp__playwright__browser_type`: 输入文本 +- `mcp__playwright__browser_navigate`: 导航到URL +- `mcp__playwright__browser_navigate_back`: 返回上一页 +- `mcp__playwright__browser_network_requests`: 获取网络请求 +- `mcp__playwright__browser_take_screenshot`: 截图 +- `mcp__playwright__browser_snapshot`: 获取页面快照 +- `mcp__playwright__browser_click`: 点击元素 +- `mcp__playwright__browser_drag`: 拖拽元素 +- `mcp__playwright__browser_hover`: 悬停元素 +- `mcp__playwright__browser_select_option`: 选择下拉选项 +- `mcp__playwright__browser_tabs`: 管理浏览器标签页 +- `mcp__playwright__browser_wait_for`: 等待元素或时间 + +### 代码搜索工具 (Code Search) +- `mcp__grep__searchGitHub`: 搜索GitHub公开仓库代码示例 + +### Wiki/文档工具 (Wiki/Documentation) +- `mcp__deepwiki__read_wiki_structure`: 读取GitHub仓库文档结构 +- `mcp__deepwiki__read_wiki_contents`: 读取GitHub仓库文档内容 +- `mcp__deepwiki__ask_question`: 询问GitHub仓库相关问题 + +### IDE工具 (IDE Tools) +- `mcp__ide__getDiagnostics`: 获取IDE诊断信息 + +### 思考工具 (Thinking Tools) +- `mcp__sequential-thinking__sequentialthinking`: 序列化思考和问题解决工具 diff --git a/docs/prompts/project/obsidian_personal.md b/docs/prompts/project/obsidian_personal.md new file mode 100644 index 000000000..6b3fc5ecd --- /dev/null +++ b/docs/prompts/project/obsidian_personal.md @@ -0,0 +1,4 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this Repository. + diff --git a/docs/prompts/slashcommands/cache-clean.locale.md b/docs/prompts/slashcommands/cache-clean.locale.md new file mode 100644 index 000000000..77868d3bf --- /dev/null +++ b/docs/prompts/slashcommands/cache-clean.locale.md @@ -0,0 +1,23 @@ +--- +allowed-tools: Read, Write, Edit, MultiEdit, Glob, Grep, Bash, TodoWrite, Task +description: Complete Claude Code project setup with MCP tools and configuration +--- + + +## Claude Code Directory Structure + +Understanding the Claude Code file organization: + +```md +# Global Configuration +~/.claude/ # Global Claude Code directory +~/.claude.json # Global settings +~/.claude.json.backup # Backup of global settings + +# Project-Specific Configuration +project/.claude/ # Project Claude Code directory +project/.claude/settings.json # Project settings +project/.claude/settings.local.json # Local project settings (gitignored) +project/.claude/.mcp.json # MCP configuration +project/.claude/.mcp.local.json # Local MCP configuration (gitignored) +``` diff --git a/docs/prompts/slashcommands/child-use.locale.md b/docs/prompts/slashcommands/child-use.locale.md new file mode 100644 index 000000000..f683c1655 --- /dev/null +++ b/docs/prompts/slashcommands/child-use.locale.md @@ -0,0 +1,70 @@ +--- +allowed-tools: Read, Write, Edit, MultiEdit, Glob, Grep, Bash, TodoWrite, Task +description: 子项目 Claude 配置复制流程，将根目录 .claude/ 配置文件复制到当前工作目录 +--- + +# Child-Use 配置复制流程 + +将根目录 `.claude/` 配置复制到当前 cwd，用于子项目 Claude 环境初始化。 + +## 核心要求 + +### 复制目标 +- `.claude/commands/**` +- `.claude/agents/**` (对应 subagent) +- `.claude/.gitignore` + +### 禁止复制 +- `.claude/settings.json` +- `.claude/settings.local.json` + +### 操作约束 +- 禁止读取文件内容，仅使用 `ls` 检查存在性 +- 目标 `.claude/` 存在则直接删除重建 +- 最终创建 `.claude/.gitignore`，内容为 `*` + +## 流程设计 + +### 1. 环境清理 +```bash +if [ -d ".claude" ]; then + rm -rf .claude +fi +``` + +### 2. 源文件检测 +```bash +ROOT_DIR=$(find_root_with_claude) +ls "$ROOT_DIR/.claude/commands/" >/dev/null 2>&1 +ls "$ROOT_DIR/.claude/agents/" >/dev/null 2>&1 +ls "$ROOT_DIR/.claude/.gitignore" >/dev/null 2>&1 +``` + +### 3. 文件复制 +```bash +mkdir -p .claude + +if [ -d "$ROOT_DIR/.claude/commands" ]; then + cp -r "$ROOT_DIR/.claude/commands" .claude/ +fi + +if [ -d "$ROOT_DIR/.claude/agents" ]; then + cp -r "$ROOT_DIR/.claude/agents" .claude/ +fi + +if [ -f "$ROOT_DIR/.claude/.gitignore" ]; then + cp "$ROOT_DIR/.claude/.gitignore" .claude/.gitignore.backup +fi +``` + +### 4. 配置覆写 +```bash +echo "*\n!.gitignore" > .claude/.gitignore +``` + +## 特点 + +- 向上查找根目录 +- 原子性操作 +- 设置文件保护 +- 备份原 .gitignore diff --git a/docs/prompts/slashcommands/optimize-prompt.locale.md b/docs/prompts/slashcommands/optimize-prompt.locale.md new file mode 100644 index 000000000..fcea6ca6f --- /dev/null +++ b/docs/prompts/slashcommands/optimize-prompt.locale.md @@ -0,0 +1,357 @@ +--- +argument-hint: [locale_file_at_path] +allowed-tools: Read, Write, Edit, Glob, Grep, Bash +description: 优化 "Claude Code" 记忆提示词文件, 使得其记忆提示词文件让 "Claude Code" 更具可读性,达到更好的工作效果 +--- + +`optimize-prompt` 优化 Claude.ai `$1` 记忆提示词文件的任务. 参数: `$1` (必需): 需要优化的提示词文件路径, `$2` (可选): 用户的具体需求或优化方向. + +该任务会根据既定规则对 记忆提示词 进行结构优化、格式规范和内容精简. 对于非 `**.locale.*` 文件,会先翻译成中文 `**.locale.*` 文件再进行优化, 确保用户始终能够理解和控制提示词内容. + +## 优化规则 + +### 语言选择规则 +- **优先处理 `**.locale.*` 文件**: 当文件名包含 `**.locale.*` 时,直接执行流程 +- **翻译非 .locale. 文件**: 如果用户传入的不是 `**.locale.*` 文件,则在其旁边翻译一份中文的 `**.locale.*` 文件,并对翻译后的 `**.locale.*` 文件进行优化 +- **始终保持用户对提示词的感知能力**: 通过自动翻译和优化机制,确保用户始终能够理解和控制提示词内容 + +### 文档开头的简要描述 +- 记忆提示词文件第一段应当包含一段 2-5 句的对整个文档内容的描述 +- 简明扼要不艺术和表达 + +### 标题结构优化 +- 标题嵌套级别不得大于3级 +- 去除冗杂的标题嵌套 +- 确保标题层次清晰 + +### 内容表达规范 +- **禁止使用表情符号**:文档中严格禁止使用任何表情符号(emoji)保持专业性 +- 使用简洁明了的书面语表达 +- 保持文档风格一致性和专业性 + +### 示例编写规范 + +**XML标签体系** +采用结构化XML标签包裹示例, 优化AI解析效率和阅读体验: + +**标签类型定义**: +- `` - 通用示例,展示标准用法 +- `` - 示例集合容器,包含多个相关示例 +- `` - 最佳实践示例,展示推荐做法 +- `` - 反面教材示例,展示应避免的做法 + +**描述属性规范**: +- 所有示例标签支持 `description=""` 属性来说明示例的作用 +- 描述应该简洁明了,突出示例的核心价值和学习要点 + +**对话机制规范**: +- `user:` - 用户输入内容 +- `claude:` - Claude响应输出内容 +- 支持独立的 `claude:` 标识纯输出场景 + +**格式化约束**: +- `` 和 `` 标签仅可在 `` 容器内使用 +- 所有XML标签及其内容保持零缩进格式 +- 标签与上方内容之间必须保留一个空行分隔,确保文档结构清晰 +- **代码示例格式**:所有代码示例必须使用语言标识的代码块包裹,如: + ```rust + // Rust 代码 + ``` + +**内容精简原则**: +- 示例应当简短有效,突出核心要点 +- 避免冗长的实现细节,专注展示概念 +- 代码示例不超过20行,文本示例不超过5行 +- 每个示例只展示一个关键概念或对比点 + +**BadExample 优化限制**: +- 优化时不对 `` 标签内的内容进行格式优化 +- 除非 `` 中的内容不符合真正要表达的意义,否则保持原样 +- `` 的目的是展示错误做法,包括错误的格式、标点、缩进等 + +### 核心结构要素 +- **角色定义**:明确AI的身份和专业背景 +- **任务描述**:清晰具体地说明要完成的任务 +- **约束条件**:明确限制和要求 +- **输出格式**:指定输出的结构和格式 + +### 注意力机制优化 +- **核心要点限制**:每个提示词最多突出3个核心要点 +- **避免注意力稀释**:过度使用强调格式(粗体、代码块等)会降低效果 +- **位置策略**:将最关键信息放在开头和结尾 + +### 提示词长度优化 +- **精简原则**:去除冗余描述,保留核心信息 +- **必要细节**:保留关键的技术细节和约束条件 +- **可读性**:合理分段,避免过长的段落 + +### 提示词文件结构要求 +- **YAML 前置配置**: 文件开头可能包含 YAML 配置块,定义工具权限和基本描述 +- **描述性文本**: 除了 YAML 配置外,还应包含一段文字描述,说明记忆提示词的用途和功能,大约 2-5 句 +- **结构完整**: 确保提示词文件既有配置信息,又有功能说明 +- ****: + +### 格式优化技巧 +- **编码规范**:使用 UTF-8 编码确保兼容性 +- **缩进规范**:统一使用 2 空格缩进 +- **行结束符**:使用 LF 行结束符(非 CRLF) +- **格式一致性**:确保整个文档格式风格统一 +- **标点符号规范**:禁止使用中文标点符号,统一使用英文标点符号 + +### 文件结构表示规范 +- **禁止使用树形结构图**:不使用 ASCII 艺术风格的树形图来表示文件结构 +- **使用缩进方式**:文件结构必须使用简单的缩进格式表示 +- **清晰简洁**:确保结构清晰易读,避免过度复杂的表示方法 + + + +```text +docs/ + - `prompts/` - 提示词模板 + - `user/` - 全局用户提示词 + - `project/` - 项目级提示词 + - `slashcommands/` - 斜杠命令提示词 + - `qa/` - 问答文档 + - `references/` - 技术参考文档 + - `other/` - 其他文档(构建、Git、数据库等) +``` + + +docs/ +├── prompts/ # 提示词模板 +│ ├── user/ # 全局用户提示词 +│ ├── project/ # 项目级提示词 +│ └── slashcommands/ # 斜杠命令提示词 +├── qa/ # 问答文档 +├── references/ # 技术参考文档 +└── other/ # 其他文档(构建、Git、数据库等) + + + +### 明确性优化 +- **避免歧义**:使用精确的词汇,避免模糊表达 +- **具体化**:将抽象概念转化为具体要求 +- **可执行性**:确保指令可以被准确理解和执行 + +### 约束条件明确化 +- **必须包含**:明确列出必须满足的条件 +- **禁止事项**:清晰说明不能做什么 +- **边界条件**:定义处理的范围和限制 + +### 输出标准化 +- **格式规范**:指定具体的输出格式(表格、列表、代码块等) +- **结构要求**:明确输出的组织结构 +- **示例说明**:提供期望输出的示例 + +### 标点符号使用示例 + + + +# Role: Code Review Assistant + +You are an expert code reviewer with 10+ years of experience. Your task is to: +1. Analyze code quality and identify potential issues +2. Provide actionable feedback for improvements +3. Ensure code follows best practices and security guidelines + +Focus on readability, maintainability, and performance aspects. + + +# Role: 代码审查助手 + +你是一位拥有10年以上经验的专家代码审查员。你的任务是: +1. 分析代码质量并识别潜在问题 +2. 提供可操作的改进建议 +3. 确保代码遵循最佳实践和安全准则 + +重点关注可读性、可维护性和性能方面。 + + + +### 代码格式示例 + + + +use std::collections::HashMap; + +#[derive(Debug, Clone)] +pub struct ProcessedItem { + pub id: String, + pub name: String, + pub value: f64, +} + +pub fn process_data(data: &[HashMap]) -> HashMap> { + let mut result = HashMap::new(); + + if data.is_empty() { + result.insert("status".to_string(), vec![]); + result.insert("count".to_string(), vec![]); + return result; + } + + let mut processed = Vec::new(); + for item in data { + if let Some(active) = item.get("active") { + if active == "true" { + if let (Some(id), Some(name), Some(value_str)) = + (&item.get("id"), &item.get("name"), &item.get("value")) { + if let Ok(value) = value_str.parse::() { + processed.push(ProcessedItem { + id: id.clone(), + name: name.trim().to_string(), + value, + }); + } + } + } + } + } + + result.insert("status".to_string(), vec![]); + result.insert("count".to_string(), vec![]); + result +} + + +use std::collections::HashMap; + +#[derive(Debug, Clone)] +pub struct ProcessedItem { + pub id: String, + pub name: String, + pub value: f64, +} + +pub fn process_data(data: &[HashMap]) -> HashMap> { + let mut result = HashMap::new(); + + if data.is_empty() { + result.insert("status".to_string(), vec![]); + result.insert("count".to_string(), vec![]); + return result; + } + + let mut processed = Vec::new(); + for item in data { + if let Some(active) = item.get("active") { + if active == "true" { + if let (Some(id), Some(name), Some(value_str)) = + (&item.get("id"), &item.get("name"), &item.get("value")) { + if let Ok(value) = value_str.parse::() { + processed.push(ProcessedItem { + id: id.clone(), + name: name.trim().to_string(), + value, + }); + } + } + } + } + } + + result.insert("status".to_string(), vec![]); + result.insert("count".to_string(), vec![]); + result +} + + + +### 提示词结构示例 + + + +# Code Generation Assistant + +Generate clean, efficient, and well-documented code based on requirements. + +## Key Guidelines +- Use meaningful variable and function names +- Include type hints for better code clarity +- Write docstrings for all public functions +- Follow the project's established patterns + +## Output Format +```rust +/// Function implementation with proper documentation +pub fn function_name(param: ParamType) -> ReturnType { + /// Brief description of the function. + /// + /// # Arguments + /// * `param` - Description of the parameter + /// + /// # Returns + /// Description of the return value + /// + /// # Examples + /// ``` + /// let result = function_name(input_value); + /// assert_eq!(result, expected_value); + /// ``` + // Implementation here +} +``` + + +## 🤖 AI Code Generation Assistant v2.0.1 ### + +### 📋 MISSION STATEMENT: +You are an advanced AI-powered code generation system designed to create high-quality, production-ready code solutions for enterprise applications. + +### 🔧 TECHNICAL REQUIREMENTS: +- **Variable Naming Convention**: MUST utilize meaningful, self-documenting variable names that clearly express intent +- **Type Safety**: ALL function parameters MUST include comprehensive type annotations using the latest typing features +- **Documentation Standards**: EVERY public function REQUIRES extensive docstring documentation following Google/NumPy conventions +- **Pattern Consistency**: MUST rigidly adhere to existing architectural patterns without deviation + +### 📤 COMPLEX OUTPUT SPECIFICATION: +The generated code should follow this exact structure: + +```rust +// -*- coding: utf-8 -*- +//! Enterprise-grade function implementation with comprehensive documentation. +//! This module represents a critical business logic component. + +pub fn elaborate_function_name_with_verbose_description( + parameter_name: ParameterType, +) -> Result> { + /// This function performs the specified operation with high reliability. + /// + /// # Arguments + /// * `parameter_name` - A detailed explanation of what this parameter represents, + /// including its expected format, constraints, and usage patterns + /// + /// # Returns + /// * `Result>` - A comprehensive description of + /// the return value, including all possible return states, error conditions, + /// and data structure details + /// + /// # Errors + /// * `ValueError` - Detailed explanation of when this error might occur + /// * `TypeError` - Comprehensive list of scenarios leading to type errors + /// + /// # Examples + /// ``` + /// match elaborate_function_name_with_verbose_description(input) { + /// Ok(result) => println!("Operation succeeded: {:?}", result), + /// Err(e) => eprintln!("Operation failed: {}", e), + /// } + /// ``` + // Implementation placeholder with extensive comments + unimplemented!() +} +``` + + + +--- + +## 文档类型说明 + +### 不同类型文档的特点和定位 + +- `docs/prompts/slashcommands/**.locale.md` - 是快捷命令文件, 它们注重任务效率优化 +- `docs/prompts/user/**.locale.md` - 是全局记忆文件, 它们通常更抽象 +- `docs/prompts/project/**.locale.md` - 是针对项目的模板, 虽抽象但更具有各项目的特色 +- `docs/prompts/subagents/**.locale.md` - 是 "Clauee Code 子代理", 它们很专业且单有领域 +- `docs/CLAUDE-**.locale.md` - 是针对 docs/ 的记忆提示词, 它们来帮助用户不断精进提示词以获得更好的效果 diff --git a/docs/prompts/slashcommands/setup-project.locale.md b/docs/prompts/slashcommands/setup-project.locale.md new file mode 100644 index 000000000..f13fb1459 --- /dev/null +++ b/docs/prompts/slashcommands/setup-project.locale.md @@ -0,0 +1,99 @@ +--- +allowed-tools: Read, Write, Edit, MultiEdit, Glob, Grep, Bash, TodoWrite, Task +description: Complete Claude Code project setup with MCP tools and configuration +--- + +# Claude Code Project Setup Assistant + +This command provides comprehensive setup instructions for Claude Code projects, including MCP (Model Context Protocol) tools installation and configuration management. + +## MCP Tools Installation + +Execute the following commands in your project root directory to install essential MCP tools. + +### Linux/macOS Commands + +```bash +# Context7 - Access up-to-date documentation for any library +claude mcp add context7 --scope project -- npx -y @upstash/context7-mcp@latest + +# Grep - Search millions of GitHub repositories for code examples +# Reference: https://vercel.com/blog/grep-a-million-github-repositories-via-mcp +claude mcp add --scope project --transport http grep https://mcp.grep.app + +# DeepWiki - GitHub repository documentation assistant +# Reference: https://docs.devin.ai/work-with-devin/deepwiki-mcp +claude mcp add --scope project --transport http deepwiki https://mcp.deepwiki.com/mcp + +# Sequential Thinking - Enhanced reasoning and problem-solving +claude mcp add sequential-thinking --scope project -- npx -y @modelcontextprotocol/server-sequential-thinking + +# Playwright - Web automation and testing +# Reference: https://github.com/microsoft/playwright-mcp +claude mcp add playwright --scope project -- npx -y @playwright/mcp@latest --viewport-size 1920,1080 + +``` + +### Windows Commands + +```bash +# Context7 - Access up-to-date documentation for any library +claude mcp add-json context7 --scope project '{\"command\":\"cmd\",\"args\":[\"/c\",\"npx\",\"-y\",\"@upstash/context7-mcp@latest\"]}' + +# Grep - Search millions of GitHub repositories for code examples +claude mcp add --scope project --transport http grep https://mcp.grep.app + +# DeepWiki - GitHub repository documentation assistant +claude mcp add --scope project --transport http deepwiki https://mcp.deepwiki.com/mcp + +# Sequential Thinking - Enhanced reasoning and problem-solving +claude mcp add-json sequential-thinking --scope project '{\"command\":\"cmd\",\"args\":[\"/c\",\"npx\",\"-y\",\"@modelcontextprotocol/server-sequential-thinking@latest\"]}' + +# Playwright - Web automation and testing +claude mcp add-json playwright --scope project '{\"command\":\"cmd\",\"args\":[\"/c\",\"npx\",\"-y\",\"@playwright/mcp@latest\",\"--viewport-size\",\"1920,1080\"]}' + +``` + +## Troubleshooting + +### Clear Caches and Reset + +If experiencing issues, remove these cache directories and files: + +```text +# Global Caches +~/.claude/tools/ # Cached tools +~/.claude/projects/ # Project caches +~/.claude/settings.local.json # Local settings +~/.claude.json # Global config +~/.claude.json.backup # Config backup + +# Project Caches +project/.claude/settings.local.json # Local project settings +project/.mcp.json # MCP config +project/.mcp.local.json # Local MCP config +``` + +### Fix Onboarding Issues + +If Claude Code fails to start, manually set the onboarding flag in `~/.claude.json`: + +```json +{ + "hasCompletedOnboarding": true +} +``` + +## Post-Setup Verification + +After installation, verify your setup by: +1. Checking MCP tools are properly installed: `claude mcp list` +2. Testing agent functionality with sub-agents +3. Running a simple command to ensure all tools work correctly + +## Usage Tips + +- Use `--scope project` to install tools project-wide +- Local configuration files are automatically gitignored +- MCP tools extend Claude's capabilities significantly +- Each tool serves specific purposes - refer to their documentation for advanced usage diff --git a/docs/prompts/slashcommands/spec/spec-1-requirement.locale.md b/docs/prompts/slashcommands/spec/spec-1-requirement.locale.md new file mode 100644 index 000000000..72e86b2a7 --- /dev/null +++ b/docs/prompts/slashcommands/spec/spec-1-requirement.locale.md @@ -0,0 +1,518 @@ +--- +argument-hint: [your locale language example | ] [ ] +allowed-tools: Read, Write, Edit, MultiEdit, Glob, Grep, Bash, TodoWrite, Task +description: 渐进式引导用户以指定语言完成规范驱动开发第一步，生成结构化需求文档 +--- + +协助用户渐进式完成规范驱动开发（**Specification-Driven Development**）流程第一步，需求文档编写。 + +# [STEP-1]: 准备工作 + +- 使用 `Search(pattern="docs/spec/SPEC-1-REQUIREMENT.locale.md")` 检查 `docs/spec/SPEC-1-REQUIREMENTS.locale.md` 是否存在 +- 如果文件存在则使用 `Read` 载入内容并输出简明概述；否则使用 `Write` 初始化一个空文件 +- 识别第一个参数 `$1` 所代表的用户首选语言，后续自由文本输出默认使用该语言；若用户另有指定，以最新指示为准 +- 在完成概述后，邀请用户保持放松、发挥想象，描绘理想的系统完成形态，然后等待用户输入第一次想法以进入 [STEP-2] + +# [STEP-2]: 耐心倾听用户首次描述需求 + +- 认可用户正处于放松、发散思维的头脑风暴状态，表达可能跳跃或带有隐喻 +- 以架构师视角进行循序引导：使用浅显语言，将系统拆分为模块、场景或流程，逐段探询关键信息 +- 细致倾听并记录关键信息，必要时以礼貌提问澄清模糊点 +- 仅在需要澄清或确认时响应，其他时间保持安静倾听，避免频繁插话 +- 如果用户说“停止”或给出等价请求，则立即结束对话 +- 用户的发散描述需先进行提炼，选择其中与 [APPENDIX-1] 结构对齐、具备可执行价值的内容再使用 _Write_ 记录；避免逐句照抄 +- 若暂未筛选出可写入的要点，则使用 WAIT 保持沉默，继续倾听直到获得明确信息 +- 在引导过程中按阶段性成果向用户复述推断，等待确认或纠正，避免一次性做出完整设计 +- 按照用户节奏持续迭代，直到用户明确表示“完成”为止 +- 用户确认完成后，提醒其使用 `/translate` 或其他工具将文档翻译为英文，并把译文外链记录在 `project/CLAUDE.md` 以提升后续编码体验 + + + +user: 我想做一个帮助远程团队协作的系统，但暂时只想到要让大家沟通更顺畅。 +claude: `Update("docs/spec/SPEC-1-REQUIREMENT.locale.md", "- 让远程团队沟通更顺畅")` +claude: 很棒的初衷！记录好了。可以先想象一下这个系统完美运行时的场景，例如团队成员在一天里会怎样协作？随意分享任何浮现的片段，我们再一起把它们补充成结构化要点。 + + +user: 我想做一个帮助远程团队协作的系统，但暂时只想到要让大家沟通更顺畅。 +claude: 你描述得太模糊了，这样没法写需求，想清楚再来吧。 + + +user: 就想做点酷的，可能是个帮朋友们玩游戏的东西？我还没想明白呢。 +claude: `Update("docs/spec/SPEC-1-REQUIREMENT.locale.md", "- 帮朋友们更顺利地一起玩游戏")` +claude: 听起来很有趣！已经先记下这个目标。暂时不用急着定具体功能，可以先从你们玩游戏时遇到的小烦恼入手，比如语音沟通、组队流程或活动安排。随便说几个真实场景，我来帮你梳理哪些值得记录。 + + +user: 嗯……想做个跟 AI 有关的东西，但我还没想好具体做什么。 +claude: 这个方向很有潜力！眼下信息还比较抽象，我先不写入文档。可以先聊聊你想解决的痛点、谁会使用，或者你期待看到的理想画面。分享得越具体，我就越容易帮你提炼出可记录的要点。 + + +user: 就想做点酷的，可能是个帮朋友们玩游戏的东西？我还没想明白呢。 +claude: 你必须先确定具体功能，否则没法继续，等你想好了再回来。 + + + + +## Locale 使用约定 + +- `$1` 为 slash 命令传入的 locale（如 `zh_CN`、`en_US`），亦代表用户首选语言 +- 与用户交流时默认使用 `$1` 对应语言；若用户切换语言或指定特殊需求，以最新指示为准 +- 在生成规范文档时，除固定要求的英文标题或关键字外，其余自由文本均采用 `$1` 语言 +- 遵循 `$1` 语言的常用表述与标点，让文案读起来自然且无翻译腔 +- 当需要澄清术语或演示示例时，可先用 `$1` 语言解释，必要时再补充英文对照 + + +# [APPENDIX-1]: 需求文档的既定格式 + +在输出需求文档时，必须严格遵循以下标准 Markdown 格式规范： + +```md +# [PROJECT_NAME:- $2] User Requirements Documentation +``` + +**格式说明：** +- `[PROJECT_NAME:- $2]`：占位符，需替换为实际的项目标识符（如 `mediacms`、`carshoping` 等） +- 文档标题必须使用英文，遵循 PascalCase 命名规范 +- 文档类型固定为 "User Requirements Documentation" + + + +# mediacms User Requirements Documentation + + +# carshoping User Requirements Documentation + + +# idea-mcp-plugin User Requirements Documentation + + + +空一行后，添加项目简介部分，格式如下： + +```md +## Introduction + +此文档记录了开发者在开发 [项目类型] 项目的详细开发需求，... +``` + +**编写指南：** +- 使用二级标题 `## Introduction` +- 描述应以 `$1` 语言中等价于“此文档记录了开发者在开发”的句式开头 +- 简明扼要地说明项目类型和主要目标 +- 长度控制在 2-5 句话内 + + + +## Introduction + +此文档记录了开发者在开发 MES 系统的详细开发需求，旨在实现生产过程的数字化管理与监控。 + + +## Introduction + +此文档记录了开发者在开发电商前后端分离项目的详细开发需求，涵盖商品管理、订单处理和用户系统等核心功能。 + + + +空一行后，定义目标用户群体，格式如下： + +```md +**Primary Persona:** [用户群体描述] +``` + +**编写规范：** +- 固定使用英文标题 `**Primary Persona:**` +- 使用 `$1` 语言描述用户群体，并依照该语言的常用分隔符（如中文顿号、英文逗号）列出多个群体 +- 描述需简洁、准确，保持与项目领域的高相关性 +- 避免主观评价或艺术化表达 + + + +**Primary Persona:** 制造业员工、制造业开发者 + + +**Primary Persona:** 在校大学生、高校老师、社团建模爱好者 + + +**主要客户群体:** 在校大学生、高校老师、社团建模爱好者 + + +**Primary Persona:** 富有魅力的企业高管、追求卓越的技术专家 + + +**Primary Persona:** 各类用户、有需求的人士 + + + +空一行后，添加可选的项目约束条件，格式如下： + +```md +**Operational Constraints:** +1. [具体的约束条件描述] +2. [具体的约束条件描述] +3. [具体的约束条件描述] +``` + +约束条件类型参考（可根据实际情况灵活调整）： +- 基础设施：硬件配置、网络环境、部署方式等 +- 技术栈：编程语言、框架选择、第三方服务等 +- 团队配置：人员规模、技能结构、外部协作等 +- 合规要求：行业标准、数据安全、隐私保护等 +- 运营保障：可用性目标、维护成本、扩展性等 +- 商业因素：预算限制、时间要求、投资回报等 + + + +**Operational Constraints:** +1. 服务器性能有限，需要轻量化部署并控制带宽占用 +2. 默认依赖外部 MySQL 8；视频资源可部署在本地磁盘或 TOS，视成本取舍 +3. 访问与播放量较低，但需确保圈内访问流畅与后台易维护 + + +**Operational Constraints:** +1. 必须符合国家金融数据安全规范，所有交易数据需加密存储 +2. 系统可用性要求 99.9%，每年停机时间不超过 8.76 小时 +3. 开发团队 3 人，包括 1 名前端、1 名后端、1 名测试 +4. 预算限制在 50 万以内，包含一年的运维成本 + + +**Operational Constraints:** +1. 服务器要好一点 +2. 需要快点完成 +3. 预算不太够 + + +**Operational Constraints:** +1. 电脑配置不能太差，不然跑不动 +2. 最好用云服务，这样方便些 +3. 找几个人随便做做就行 + + + +空一行后，添加可选的非功能性优先级说明，格式如下： + +```md +**Non-Functional Priorities:** +1. [优先级描述] +2. [优先级描述] +3. [优先级描述] +``` + + + +**Non-Functional Priorities:** +1. 默认启用 HTTPS，优先使用云厂商免费证书 +2. 视频与封面优先经由 TOS/CDN；若采用本地存储，需提供容量监控与清理策略 +3. 当前仅需桌面端体验，移动端可在后续需求出现时迭代 +4. 提供容器或脚本化部署以便迁移与快速恢复 +5. 实现轻量日志与监控，并规划数据库与关键数据的定期备份 + + + +**Non-Functional Priorities:** +1. 系统要安全稳定 +2. 速度要快一点 +3. 界面要好看 +4. 后期要方便维护 +5. 部署要简单 + + + +**Non-Functional Priorities:** +1. 所有敏感数据必须 AES-256 加密存储，传输使用 TLS 1.3 +2. 核心交易接口响应时间 ≤ 500ms，99% 请求需在 200ms 内完成 +3. 系统可用性 ≥ 99.9%，月度停机时间 ≤ 43.2 分钟 +4. 支持 Chrome/Firefox/Safari 最新两个版本，IE11 最低兼容 +5. 代码覆盖率 ≥ 80%，关键业务 100% 有集成测试 + + + +**Non-Functional Priorities:** +1. 使用 React 框架开发前端 +2. 后端采用 Spring Boot 框架 +3. 数据库使用 MySQL 8.0 +4. 缓存使用 Redis +5. 消息队列用 RabbitMQ + + + +空一行后，添加可选的后续功能范围说明，格式如下： + +```md +**Deferred Scope:** +1. [功能描述] +2. [功能描述] +3. [功能描述] +``` + +**编写指南：** +- 使用英文标题 `**Deferred Scope:**` +- 列出当前版本不考虑，但未来可能需要实现的功能 +- 每项功能应简明扼要，突出核心价值 +- 避免与已有需求重复 +- 有序列表内容使用 `$1` 语言进行书写 + + + +**Deferred Scope:** +1. 人才市场招聘能力，连接创作者与企业 +2. 短剧贩售与付费解锁模块，支持内容变现 +3. 创作者社区功能，支持作品交流与协作 + + + +**Deferred Scope:** +1. 社交分享功能，允许用户分享商品至各平台 +2. 会员积分系统，提升用户忠诚度 +3. 多语言国际化支持，拓展海外市场 + + + +**Deferred Scope:** +1. 一些其他功能 +2. 后续再加的东西 +3. 等有钱了再做的 + + + +**Deferred Scope:** +1. 用户登录注册（已在基础功能中） +2. 商品展示页面（已在核心需求中） +3. 订单管理功能（已在必须实现中） + + + + +随后是核心需求列表，这是整个文档最重要的部分，必须严格遵循以下规范： + +## Requirements 格式规范 + +### 基本结构 +```md +## Requirements + +### Requirement [编号]: [需求名称] + +**User Story:** As [用户角色], I want [想要完成的功能], so that [获得的价值]. + +#### Acceptance Criteria + +1. WHEN [触发条件] THEN [期望结果] +2. WHEN [触发条件] THEN [期望结果] +3. WHEN [触发条件] THEN [期望结果] +``` + +### 编写规范要求 + +1. **用户故事（User Story）** + - 必须使用标准格式：`As [角色], I want [功能], so that [价值]` + - 角色要具体（如"创作者"而非"用户"） + - 价值要明确（回答"为什么要这个功能"） + - 使用 `$1` 语言书写 [角色]、[功能]、[价值] + +2. **验收标准（Acceptance Criteria）** + - 必须使用 Given-When-Then 格式 + - 每条标准必须独立、可测试 + - 避免技术实现细节，关注业务行为 + - 使用 `$1` 语言书写 [触发条件]、[期望结果] + +3. **需求拆分原则** + - 每个需求应独立且有明确价值 + - 避免过大（超过 5 条验收标准需考虑拆分） + - 避免过小（少于 2 条验收标准需考虑合并） + + + +### Requirement 3: 用户作品管理 + +**User Story:** As 创作者, I want 能够管理我的所有作品, so that 可以随时编辑或删除内容。 + +#### Acceptance Criteria + +1. WHEN 创作者登录并进入个人中心 THEN 系统应展示其所有作品的列表，包含缩略图、标题、发布时间和浏览量 +2. WHEN 创作者点击作品编辑按钮 THEN 系统应跳转至编辑页面，保留原有内容并可修改所有信息 +3. WHEN 创作者删除作品 THEN 系统应要求二次确认，成功后从列表中移除并提示用户 +4. WHEN 作品被其他用户收藏或评论 THEN 创作者在管理页面应能看到相关统计数据 + + + +### Requirement 2: 用户登录 + +**User Story:** As 用户, I want 登录系统。 + +#### Acceptance Criteria + +1. 输入用户名密码 +2. 点击登录按钮 +3. 登录成功 + + + +### Requirement 5: 内容推荐 + +**User Story:** As 观众, I want 系统能推荐我感兴趣的短剧内容, so that 发现更多优质作品。 + +#### Acceptance Criteria + +1. WHEN 观众浏览首页 THEN 系统应基于其观看历史推荐相似类型作品 +2. WHEN 观众完成观看一个作品 THEN 系统应推荐相关创作者的其他作品 +3. WHEN 观众连续跳过多个推荐 THEN 系统应调整推荐算法，提供更精准的内容 + + + +### Requirement 4: 视频上传 + +**User Story:** As 创作者, I want 上传视频。 + +#### Acceptance Criteria + +1. 调用后端 API 接口 /api/v1/videos +2. 使用 MySQL 存储视频信息 +3. 视频文件存放在 OSS 对象存储 + + + +### Requirement 7: 评论互动 + +**User Story:** As 观众, I want 对喜欢的作品进行评论, so that 与创作者和其他观众交流想法。 + +#### Acceptance Criteria + +1. WHEN 观众在作品详情页输入评论并提交 THEN 系统应发布评论并在评论区实时显示 +2. WHEN 创作者收到评论 THEN 系统应通过站内信通知创作者 +3. WHEN 评论包含敏感词 THEN 系统应自动拦截并提示用户修改 +4. WHEN 观众点击某条评论 THEN 系统应显示该评论的回复和点赞数 + + + +### Requirement 1: 完整的用户系统 + +**User Story:** As 用户, I want 使用完整的系统功能。 + +#### Acceptance Criteria + +1. 用户注册登录 +2. 个人信息管理 +3. 作品发布管理 +4. 评论互动功能 +5. 消息通知系统 +6. 数据统计分析 +7. 权限管理控制 +8. 支付功能 +9. 客服系统 + + + +### 需求优先级标记（可选） +如需标识需求优先级，可在编号后使用标记： +- `[H]` - High priority（高优先级） +- `[M]` - Medium priority（中优先级） +- `[L]` - Low priority（低优先级） + + + +### Requirement 1[H]: 用户认证 +### Requirement 2[M]: 邮件通知 +### Requirement 3[L]: 主题切换 + + + + +# EduPlatform User Requirements Documentation + +## Introduction + +此文档记录了开发者在开发在线教育平台的详细开发需求，旨在为教师和学生提供高效的在线教学与学习体验。 + +**Primary Persona:** 在线教育教师、高校学生、职业培训学员、教育机构管理者 + +**Operational Constraints:** +1. 服务器预算有限，需要支持至少 1000 并发用户 +2. 必须兼容移动端和桌面端，最低支持 iOS 12 和 Android 8.0 +3. 视频直播依赖第三方 CDN 服务，需控制带宽成本 +4. 开发团队 5 人，包含 2 名前端、2 名后端、1 名测试 + +**Non-Functional Priorities:** +1. 视频直播延迟不超过 3 秒，支持断线重连 +2. 用户数据必须加密存储，符合个人信息保护法要求 +3. 系统可用性达到 99.5%，每月停机时间不超过 3.6 小时 +4. 页面加载时间控制在 2 秒以内 + +**Deferred Scope:** +1. AI 智能推荐学习内容功能 +2. 虚拟现实（VR）沉浸式课堂体验 +3. 多语言国际化支持功能 + +## Requirements + +### Requirement 1[H]: 课程创建与管理 + +**User Story:** As 教师, I want 能够创建和管理在线课程, so that 可以灵活地安排教学内容和进度。 + +#### Acceptance Criteria + +1. WHEN 教师登录并进入课程管理页面 THEN 系统应显示"创建新课程"按钮和现有课程列表 +2. WHEN 教师点击"创建新课程"并填写课程信息 THEN 系统应生成课程主页并支持添加章节 +3. WHEN 教师上传视频课件 THEN 系统应自动转码为多格式以适应不同网络环境 +4. WHEN 教师设置课程价格 THEN 系统应支持免费、付费和会员专享三种模式 +5. WHEN 课程有学员报名 THEN 教师应收到通知并查看学员名单 + +### Requirement 2[H]: 视频直播教学 + +**User Story:** As 教师, I want 进行实时视频直播教学, so that 可以与学生进行互动和答疑。 + +#### Acceptance Criteria + +1. WHEN 教师进入直播间 THEN 系统应提供摄像头、麦克风和屏幕共享选项 +2. WHEN 教师开始直播 THEN 系统应自动通知已报名的学生 +3. WHEN 学生在直播中提问 THEN 教师应能看到实时弹幕并选择性回复 +4. WHEN 网络不稳定时 THEN 系统应自动切换至清晰度较低的流畅模式 +5. WHEN 直播结束后 THEN 系统应生成回放视频并自动关联到课程页面 + +### Requirement 3[M]: 学习进度跟踪 + +**User Story:** As 学生, I want 能够查看我的学习进度, so that 了解完成情况并制定学习计划。 + +#### Acceptance Criteria + +1. WHEN 学生进入个人中心 THEN 系统应展示已购课程列表和整体学习进度 +2. WHEN 学生进入课程详情页 THEN 系统应显示每个章节的完成状态和学习时长 +3. WHEN 学生完成一个章节 THEN 系统应自动更新进度并解锁下一章节 +4. WHEN学生的学习时长达到系统设定值 THEN 系统应弹出休息提醒 +5. WHEN 学生完成全部课程 THEN 系统应生成电子证书并支持分享 + +### Requirement 4[M]: 互动讨论区 + +**User Story:** As 学生, I want 能够在课程下进行讨论和提问, so that 与同学和老师交流学习心得。 + +#### Acceptance Criteria + +1. WHEN 学生进入课程讨论区 THEN 系统应按时间顺序显示所有讨论帖 +2. WHEN 学生发布提问 THEN 系统应@通知相关教师和其他选课学生 +3. WHEN 教师回复问题 THEN 系统应标记为"已解答"并高亮显示 +4. WHEN 学生觉得某个回答有用 THEN 可以点赞该回答 +5. WHEN 讨论包含不当内容 THEN 系统应自动过滤并提交人工审核 + +### Requirement 5[L]: 作业提交与批改 + +**User Story:** As 学生, I want 在线提交作业并获得老师反馈, so that 及时了解自己的学习效果。 + +#### Acceptance Criteria + +1. WHEN 教师发布作业 THEN 系统应通知所有选课学生并显示截止日期 +2. WHEN 学生提交作业 THEN 系统应支持文本、图片、文档和视频多种格式 +3. WHEN 学生提交后超时 THEN 系统应自动关闭提交入口 +4. WHEN 教师批改作业 THEN 系统应支持评分、评语和批注功能 +5. WHEN 所有作业批改完成后 THEN 系统应生成班级成绩统计 + + + +### Q & A + +**Q: 需求应该写多详细？** +A: 每个需求应该足够详细，让开发人员能够理解并实现，但避免过度设计。一般 3-5 条验收标准为宜。 + +**Q: 验收标准如何写才能确保可测试？** +A: 使用具体的、可观察的结果，避免模糊词汇如"快速"、"友好"等，改用具体指标如"响应时间<2秒"。 + +**Q: 如何判断需求拆分是否合理？** +A: 如果一个需求有超过 5 条验收标准，考虑是否可以拆分；如果少于 2 条，考虑是否过于简单。 diff --git a/docs/prompts/slashcommands/spec/spec-4-preview-result.locale.md b/docs/prompts/slashcommands/spec/spec-4-preview-result.locale.md new file mode 100644 index 000000000..3cf4a0431 --- /dev/null +++ b/docs/prompts/slashcommands/spec/spec-4-preview-result.locale.md @@ -0,0 +1,41 @@ +--- +argument-hint: no_parameters +allowed-tools: Read, Write, Edit, Glob, Grep, Bash +description: 规范驱动开发步骤1, 按照严格文档格式，协助用户完成序文文档编写 +--- + +立即对任务[$ARGUMENTS]进行质量评分： + +```md +## 📊 需求质量评估报告 + +### 评分维度（100分制） + +- **明确性**（0-25分）：任务目标是否清晰明确 +- **范围性**（0-25分）：任务范围是否界定清楚 +- **可行性**（0-25分）：技术实现路径是否可行 +- **标准性**（0-25分）：成功标准是否明确定义 + +### 当前得分：[X]/100分 + +### 需求理解 + +[对任务的初步理解描述] + +### 需求改进建议 + +[仅当分数<90时显示] +❓ 需要澄清的问题： + +1. [具体问题1] +2. [具体问题2] +3. [具体问题3] + +请回答以上问题，以便我更准确地理解您的需求。 +``` + +**步骤2：迭代澄清循环** + +- 持续与用户交互直到需求质量分≥90分 +- 每轮澄清后更新需求理解和评分 +- 记录澄清过程供后续参考 diff --git a/docs/prompts/slashcommands/translate.locale.md b/docs/prompts/slashcommands/translate.locale.md new file mode 100644 index 000000000..e1564a286 --- /dev/null +++ b/docs/prompts/slashcommands/translate.locale.md @@ -0,0 +1,98 @@ +--- +argument-hint: [locale_markdown_file] [translation_description] +allowed-tools: Read, Write, Glob, Grep, Bash +description: 将中文本地化记忆提示词文件翻译为英文记忆提示词文件，遵循一致的术语和质量标准 +--- + +将中文本地化记忆提示词文件 #$1 (.locale.md) 翻译为英文记忆提示词文件，同时保持质量标准和术语一致性。 + +# 关键要求 + +## 任务执行流程 +1. **读取源文件**: `Read($1)` +2. **解析文件名**: + - **特殊位置规则** (优先检查): + - `docs/prompts/slashcommands/**.locale.md` → `.claude/commands/**.md` + - `docs/CLAUDE-prompts-slashcommands.locale.md` → `docs/prompts/slashcommands/CLAUDE.md` + - `docs/CLAUDE-prompts.locale.md` → `docs/prompts/CLAUDE.md` + - `docs/CLAUDE-prompts-user.locale.md` → `docs/prompts/user/CLAUDE.md` + - `docs/CLAUDE-prompts-project.locale.md` → `docs/prompts/project/CLAUDE.md` + - `docs/CLAUDE-qa.locale.md` → `docs/qa/CLAUDE.md` + - `docs/CLAUDE-references.locale.md` → `docs/references/CLAUDE.md` + - **标准规则**: `filename.locale.extension` → `filename.extension` +3. **检查目标文件**: + - 使用 `Search(pattern: "$1")` 验证目标文件是否存在 + - 模式: 基于步骤 2 确定的目标路径 +4. **删除现有文件**: + - 如果目标文件存在，使用 Bash 工具删除 + - 命令: `Bash(rm filename.extension)` (Linux/Mac) 或 等价 (Windows) 命令 +5. **执行翻译**: + - 保留 Markdown 结构和格式 + - 应用词汇表中的一致术语 + - 保持代码块不变, 且翻译所有注释内容 + - 保持 `` 中的例子内容不变 +6. **写入目标文件**: + - 创建新的目标文件并写入翻译内容 + - 无需读取现有目标文件 (已在步骤 4 中删除) +7. **错误处理**: + - 如果 `Write` 工具失败，立即删除目标文件 + - 使用 `Bash` 工具执行删除 + - 重新开始流程，不尝试修复 + +> user: $2 + +## 质量标准 +- **术语一致性**: 严格遵循词汇表 +- **技术准确性**: 保持技术概念的精确性 +- **格式保持**: 保留所有 Markdown 格式 +- **链接处理**: 适当更新文档链接 +- **代码完整性**: 保持代码示例不变 + + + +- `translate.locale.md` → `translate.md` +- `setup.locale.md` → `setup.md` +- `config.locale.yaml` → `config.yaml` + + + + +user: 请参阅文档 +claude: See documentation + +user: 配置文件 +claude: Configuration file + +user: 命令行工具 +claude: Command-line tool + + + +# 核心术语 + +## 常用术语 +- 请参阅/参见 - see, refer to +- 配置 - configuration, config +- 设置 - settings +- 文档 - documentation, docs +- 指南 - guide +- 教程 - tutorial +- 示例 - example +- 工具 - tool +- 命令 - command +- 脚本 - script +- 文件 - file +- 目录 - directory +- 路径 - path + +## Claude Code 术语 +- 钩子 - hook +- 斜杠命令 - slash command +- 工作区 - workspace +- 代理 - agent +- 模型 - model +- 提示 - prompt +- 上下文 - context +- 会话 - session +- 任务 - task +- 工作流 - workflow diff --git a/docs/prompts/subagents/spec/spec-1-requirement.locale.md b/docs/prompts/subagents/spec/spec-1-requirement.locale.md new file mode 100644 index 000000000..c9d39750a --- /dev/null +++ b/docs/prompts/subagents/spec/spec-1-requirement.locale.md @@ -0,0 +1,517 @@ +--- +argument-hint: [your locale language example | ] [ ] +allowed-tools: Read, Write, Edit, MultiEdit, Glob, Grep, Bash, TodoWrite, Task +description: 渐进式引导用户以指定语言完成规范驱动开发第一步，生成结构化需求文档 +--- + +协助用户渐进式完成规范驱动开发（**Specification-Driven Development**）流程第一步，需求文档编写。 + +# [STEP-1]: 准备工作 + +- 使用 `Search(pattern="docs/spec/SPEC-1-REQUIREMENT.locale.md")` 检查 `docs/spec/SPEC-1-REQUIREMENTS.locale.md` 是否存在 +- 如果文件存在则使用 `Read` 载入内容并输出简明概述；否则使用 `Write` 初始化一个空文件 +- 识别第一个参数 `$1` 所代表的用户首选语言，后续自由文本输出默认使用该语言；若用户另有指定，以最新指示为准 +- 在完成概述后，邀请用户保持放松、发挥想象，描绘理想的系统完成形态，然后等待用户输入第一次想法以进入 [STEP-2] + +# [STEP-2]: 耐心倾听用户首次描述需求 + +- 认可用户正处于放松、发散思维的头脑风暴状态，表达可能跳跃或带有隐喻 +- 以架构师视角进行循序引导：使用浅显语言，将系统拆分为模块、场景或流程，逐段探询关键信息 +- 细致倾听并记录关键信息，必要时以礼貌提问澄清模糊点 +- 仅在需要澄清或确认时响应，其他时间保持安静倾听，避免频繁插话 +- 如果用户说“停止”或给出等价请求，则立即结束对话 +- 用户的发散描述需先进行提炼，选择其中与 [APPENDIX-1] 结构对齐、具备可执行价值的内容再使用 _Write_ 记录；避免逐句照抄 +- 若暂未筛选出可写入的要点，则保持沉默，继续倾听直到获得明确信息 +- 按照用户节奏持续迭代，直到用户明确表示“完成”为止 +- 用户确认完成后，提醒其使用 `/translate` 或其他工具将文档翻译为英文，并把译文外链记录在 `project/CLAUDE.md` 以提升后续编码体验 + + + +user: 我想做一个帮助远程团队协作的系统，但暂时只想到要让大家沟通更顺畅。 +claude: `Update("docs/spec/SPEC-1-REQUIREMENT.locale.md", "- 让远程团队沟通更顺畅")` +claude: 很棒的初衷！记录好了。可以先想象一下这个系统完美运行时的场景，例如团队成员在一天里会怎样协作？随意分享任何浮现的片段，我们再一起把它们补充成结构化要点。 + + +user: 我想做一个帮助远程团队协作的系统，但暂时只想到要让大家沟通更顺畅。 +claude: 你描述得太模糊了，这样没法写需求，想清楚再来吧。 + + +user: 就想做点酷的，可能是个帮朋友们玩游戏的东西？我还没想明白呢。 +claude: `Update("docs/spec/SPEC-1-REQUIREMENT.locale.md", "- 帮朋友们更顺利地一起玩游戏")` +claude: 听起来很有趣！已经先记下这个目标。暂时不用急着定具体功能，可以先从你们玩游戏时遇到的小烦恼入手，比如语音沟通、组队流程或活动安排。随便说几个真实场景，我来帮你梳理哪些值得记录。 + + +user: 嗯……想做个跟 AI 有关的东西，但我还没想好具体做什么。 +claude: 这个方向很有潜力！眼下信息还比较抽象，我先不写入文档。可以先聊聊你想解决的痛点、谁会使用，或者你期待看到的理想画面。分享得越具体，我就越容易帮你提炼出可记录的要点。 + + +user: 就想做点酷的，可能是个帮朋友们玩游戏的东西？我还没想明白呢。 +claude: 你必须先确定具体功能，否则没法继续，等你想好了再回来。 + + + + +## Locale 使用约定 + +- `$1` 为 slash 命令传入的 locale（如 `zh_CN`、`en_US`），亦代表用户首选语言 +- 与用户交流时默认使用 `$1` 对应语言；若用户切换语言或指定特殊需求，以最新指示为准 +- 在生成规范文档时，除固定要求的英文标题或关键字外，其余自由文本均采用 `$1` 语言 +- 遵循 `$1` 语言的常用表述与标点，让文案读起来自然且无翻译腔 +- 当需要澄清术语或演示示例时，可先用 `$1` 语言解释，必要时再补充英文对照 + + +# [APPENDIX-1]: 需求文档的既定格式 + +在输出需求文档时，必须严格遵循以下标准 Markdown 格式规范： + +```md +# [PROJECT_NAME:- $2] User Requirements Documentation +``` + +**格式说明：** +- `[PROJECT_NAME:- $2]`：占位符，需替换为实际的项目标识符（如 `mediacms`、`carshoping` 等） +- 文档标题必须使用英文，遵循 PascalCase 命名规范 +- 文档类型固定为 "User Requirements Documentation" + + + +# mediacms User Requirements Documentation + + +# carshoping User Requirements Documentation + + +# idea-mcp-plugin User Requirements Documentation + + + +空一行后，添加项目简介部分，格式如下： + +```md +## Introduction + +此文档记录了开发者在开发 [项目类型] 项目的详细开发需求，... +``` + +**编写指南：** +- 使用二级标题 `## Introduction` +- 描述应以 `$1` 语言中等价于“此文档记录了开发者在开发”的句式开头 +- 简明扼要地说明项目类型和主要目标 +- 长度控制在 2-5 句话内 + + + +## Introduction + +此文档记录了开发者在开发 MES 系统的详细开发需求，旨在实现生产过程的数字化管理与监控。 + + +## Introduction + +此文档记录了开发者在开发电商前后端分离项目的详细开发需求，涵盖商品管理、订单处理和用户系统等核心功能。 + + + +空一行后，定义目标用户群体，格式如下： + +```md +**Primary Persona:** [用户群体描述] +``` + +**编写规范：** +- 固定使用英文标题 `**Primary Persona:**` +- 使用 `$1` 语言描述用户群体，并依照该语言的常用分隔符（如中文顿号、英文逗号）列出多个群体 +- 描述需简洁、准确，保持与项目领域的高相关性 +- 避免主观评价或艺术化表达 + + + +**Primary Persona:** 制造业员工、制造业开发者 + + +**Primary Persona:** 在校大学生、高校老师、社团建模爱好者 + + +**主要客户群体:** 在校大学生、高校老师、社团建模爱好者 + + +**Primary Persona:** 富有魅力的企业高管、追求卓越的技术专家 + + +**Primary Persona:** 各类用户、有需求的人士 + + + +空一行后，添加可选的项目约束条件，格式如下： + +```md +**Operational Constraints:** +1. [具体的约束条件描述] +2. [具体的约束条件描述] +3. [具体的约束条件描述] +``` + +约束条件类型参考（可根据实际情况灵活调整）： +- 基础设施：硬件配置、网络环境、部署方式等 +- 技术栈：编程语言、框架选择、第三方服务等 +- 团队配置：人员规模、技能结构、外部协作等 +- 合规要求：行业标准、数据安全、隐私保护等 +- 运营保障：可用性目标、维护成本、扩展性等 +- 商业因素：预算限制、时间要求、投资回报等 + + + +**Operational Constraints:** +1. 服务器性能有限，需要轻量化部署并控制带宽占用 +2. 默认依赖外部 MySQL 8；视频资源可部署在本地磁盘或 TOS，视成本取舍 +3. 访问与播放量较低，但需确保圈内访问流畅与后台易维护 + + +**Operational Constraints:** +1. 必须符合国家金融数据安全规范，所有交易数据需加密存储 +2. 系统可用性要求 99.9%，每年停机时间不超过 8.76 小时 +3. 开发团队 3 人，包括 1 名前端、1 名后端、1 名测试 +4. 预算限制在 50 万以内，包含一年的运维成本 + + +**Operational Constraints:** +1. 服务器要好一点 +2. 需要快点完成 +3. 预算不太够 + + +**Operational Constraints:** +1. 电脑配置不能太差，不然跑不动 +2. 最好用云服务，这样方便些 +3. 找几个人随便做做就行 + + + +空一行后，添加可选的非功能性优先级说明，格式如下： + +```md +**Non-Functional Priorities:** +1. [优先级描述] +2. [优先级描述] +3. [优先级描述] +``` + + + +**Non-Functional Priorities:** +1. 默认启用 HTTPS，优先使用云厂商免费证书 +2. 视频与封面优先经由 TOS/CDN；若采用本地存储，需提供容量监控与清理策略 +3. 当前仅需桌面端体验，移动端可在后续需求出现时迭代 +4. 提供容器或脚本化部署以便迁移与快速恢复 +5. 实现轻量日志与监控，并规划数据库与关键数据的定期备份 + + + +**Non-Functional Priorities:** +1. 系统要安全稳定 +2. 速度要快一点 +3. 界面要好看 +4. 后期要方便维护 +5. 部署要简单 + + + +**Non-Functional Priorities:** +1. 所有敏感数据必须 AES-256 加密存储，传输使用 TLS 1.3 +2. 核心交易接口响应时间 ≤ 500ms，99% 请求需在 200ms 内完成 +3. 系统可用性 ≥ 99.9%，月度停机时间 ≤ 43.2 分钟 +4. 支持 Chrome/Firefox/Safari 最新两个版本，IE11 最低兼容 +5. 代码覆盖率 ≥ 80%，关键业务 100% 有集成测试 + + + +**Non-Functional Priorities:** +1. 使用 React 框架开发前端 +2. 后端采用 Spring Boot 框架 +3. 数据库使用 MySQL 8.0 +4. 缓存使用 Redis +5. 消息队列用 RabbitMQ + + + +空一行后，添加可选的后续功能范围说明，格式如下： + +```md +**Deferred Scope:** +1. [功能描述] +2. [功能描述] +3. [功能描述] +``` + +**编写指南：** +- 使用英文标题 `**Deferred Scope:**` +- 列出当前版本不考虑，但未来可能需要实现的功能 +- 每项功能应简明扼要，突出核心价值 +- 避免与已有需求重复 +- 有序列表内容使用 `$1` 语言进行书写 + + + +**Deferred Scope:** +1. 人才市场招聘能力，连接创作者与企业 +2. 短剧贩售与付费解锁模块，支持内容变现 +3. 创作者社区功能，支持作品交流与协作 + + + +**Deferred Scope:** +1. 社交分享功能，允许用户分享商品至各平台 +2. 会员积分系统，提升用户忠诚度 +3. 多语言国际化支持，拓展海外市场 + + + +**Deferred Scope:** +1. 一些其他功能 +2. 后续再加的东西 +3. 等有钱了再做的 + + + +**Deferred Scope:** +1. 用户登录注册（已在基础功能中） +2. 商品展示页面（已在核心需求中） +3. 订单管理功能（已在必须实现中） + + + + +随后是核心需求列表，这是整个文档最重要的部分，必须严格遵循以下规范： + +## Requirements 格式规范 + +### 基本结构 +```md +## Requirements + +### Requirement [编号]: [需求名称] + +**User Story:** As [用户角色], I want [想要完成的功能], so that [获得的价值]. + +#### Acceptance Criteria + +1. WHEN [触发条件] THEN [期望结果] +2. WHEN [触发条件] THEN [期望结果] +3. WHEN [触发条件] THEN [期望结果] +``` + +### 编写规范要求 + +1. **用户故事（User Story）** + - 必须使用标准格式：`As [角色], I want [功能], so that [价值]` + - 角色要具体（如"创作者"而非"用户"） + - 价值要明确（回答"为什么要这个功能"） + - 使用 `$1` 语言书写 [角色]、[功能]、[价值] + +2. **验收标准（Acceptance Criteria）** + - 必须使用 Given-When-Then 格式 + - 每条标准必须独立、可测试 + - 避免技术实现细节，关注业务行为 + - 使用 `$1` 语言书写 [触发条件]、[期望结果] + +3. **需求拆分原则** + - 每个需求应独立且有明确价值 + - 避免过大（超过 5 条验收标准需考虑拆分） + - 避免过小（少于 2 条验收标准需考虑合并） + + + +### Requirement 3: 用户作品管理 + +**User Story:** As 创作者, I want 能够管理我的所有作品, so that 可以随时编辑或删除内容。 + +#### Acceptance Criteria + +1. WHEN 创作者登录并进入个人中心 THEN 系统应展示其所有作品的列表，包含缩略图、标题、发布时间和浏览量 +2. WHEN 创作者点击作品编辑按钮 THEN 系统应跳转至编辑页面，保留原有内容并可修改所有信息 +3. WHEN 创作者删除作品 THEN 系统应要求二次确认，成功后从列表中移除并提示用户 +4. WHEN 作品被其他用户收藏或评论 THEN 创作者在管理页面应能看到相关统计数据 + + + +### Requirement 2: 用户登录 + +**User Story:** As 用户, I want 登录系统。 + +#### Acceptance Criteria + +1. 输入用户名密码 +2. 点击登录按钮 +3. 登录成功 + + + +### Requirement 5: 内容推荐 + +**User Story:** As 观众, I want 系统能推荐我感兴趣的短剧内容, so that 发现更多优质作品。 + +#### Acceptance Criteria + +1. WHEN 观众浏览首页 THEN 系统应基于其观看历史推荐相似类型作品 +2. WHEN 观众完成观看一个作品 THEN 系统应推荐相关创作者的其他作品 +3. WHEN 观众连续跳过多个推荐 THEN 系统应调整推荐算法，提供更精准的内容 + + + +### Requirement 4: 视频上传 + +**User Story:** As 创作者, I want 上传视频。 + +#### Acceptance Criteria + +1. 调用后端 API 接口 /api/v1/videos +2. 使用 MySQL 存储视频信息 +3. 视频文件存放在 OSS 对象存储 + + + +### Requirement 7: 评论互动 + +**User Story:** As 观众, I want 对喜欢的作品进行评论, so that 与创作者和其他观众交流想法。 + +#### Acceptance Criteria + +1. WHEN 观众在作品详情页输入评论并提交 THEN 系统应发布评论并在评论区实时显示 +2. WHEN 创作者收到评论 THEN 系统应通过站内信通知创作者 +3. WHEN 评论包含敏感词 THEN 系统应自动拦截并提示用户修改 +4. WHEN 观众点击某条评论 THEN 系统应显示该评论的回复和点赞数 + + + +### Requirement 1: 完整的用户系统 + +**User Story:** As 用户, I want 使用完整的系统功能。 + +#### Acceptance Criteria + +1. 用户注册登录 +2. 个人信息管理 +3. 作品发布管理 +4. 评论互动功能 +5. 消息通知系统 +6. 数据统计分析 +7. 权限管理控制 +8. 支付功能 +9. 客服系统 + + + +### 需求优先级标记（可选） +如需标识需求优先级，可在编号后使用标记： +- `[H]` - High priority（高优先级） +- `[M]` - Medium priority（中优先级） +- `[L]` - Low priority（低优先级） + + + +### Requirement 1[H]: 用户认证 +### Requirement 2[M]: 邮件通知 +### Requirement 3[L]: 主题切换 + + + + +# EduPlatform User Requirements Documentation + +## Introduction + +此文档记录了开发者在开发在线教育平台的详细开发需求，旨在为教师和学生提供高效的在线教学与学习体验。 + +**Primary Persona:** 在线教育教师、高校学生、职业培训学员、教育机构管理者 + +**Operational Constraints:** +1. 服务器预算有限，需要支持至少 1000 并发用户 +2. 必须兼容移动端和桌面端，最低支持 iOS 12 和 Android 8.0 +3. 视频直播依赖第三方 CDN 服务，需控制带宽成本 +4. 开发团队 5 人，包含 2 名前端、2 名后端、1 名测试 + +**Non-Functional Priorities:** +1. 视频直播延迟不超过 3 秒，支持断线重连 +2. 用户数据必须加密存储，符合个人信息保护法要求 +3. 系统可用性达到 99.5%，每月停机时间不超过 3.6 小时 +4. 页面加载时间控制在 2 秒以内 + +**Deferred Scope:** +1. AI 智能推荐学习内容功能 +2. 虚拟现实（VR）沉浸式课堂体验 +3. 多语言国际化支持功能 + +## Requirements + +### Requirement 1[H]: 课程创建与管理 + +**User Story:** As 教师, I want 能够创建和管理在线课程, so that 可以灵活地安排教学内容和进度。 + +#### Acceptance Criteria + +1. WHEN 教师登录并进入课程管理页面 THEN 系统应显示"创建新课程"按钮和现有课程列表 +2. WHEN 教师点击"创建新课程"并填写课程信息 THEN 系统应生成课程主页并支持添加章节 +3. WHEN 教师上传视频课件 THEN 系统应自动转码为多格式以适应不同网络环境 +4. WHEN 教师设置课程价格 THEN 系统应支持免费、付费和会员专享三种模式 +5. WHEN 课程有学员报名 THEN 教师应收到通知并查看学员名单 + +### Requirement 2[H]: 视频直播教学 + +**User Story:** As 教师, I want 进行实时视频直播教学, so that 可以与学生进行互动和答疑。 + +#### Acceptance Criteria + +1. WHEN 教师进入直播间 THEN 系统应提供摄像头、麦克风和屏幕共享选项 +2. WHEN 教师开始直播 THEN 系统应自动通知已报名的学生 +3. WHEN 学生在直播中提问 THEN 教师应能看到实时弹幕并选择性回复 +4. WHEN 网络不稳定时 THEN 系统应自动切换至清晰度较低的流畅模式 +5. WHEN 直播结束后 THEN 系统应生成回放视频并自动关联到课程页面 + +### Requirement 3[M]: 学习进度跟踪 + +**User Story:** As 学生, I want 能够查看我的学习进度, so that 了解完成情况并制定学习计划。 + +#### Acceptance Criteria + +1. WHEN 学生进入个人中心 THEN 系统应展示已购课程列表和整体学习进度 +2. WHEN 学生进入课程详情页 THEN 系统应显示每个章节的完成状态和学习时长 +3. WHEN 学生完成一个章节 THEN 系统应自动更新进度并解锁下一章节 +4. WHEN学生的学习时长达到系统设定值 THEN 系统应弹出休息提醒 +5. WHEN 学生完成全部课程 THEN 系统应生成电子证书并支持分享 + +### Requirement 4[M]: 互动讨论区 + +**User Story:** As 学生, I want 能够在课程下进行讨论和提问, so that 与同学和老师交流学习心得。 + +#### Acceptance Criteria + +1. WHEN 学生进入课程讨论区 THEN 系统应按时间顺序显示所有讨论帖 +2. WHEN 学生发布提问 THEN 系统应@通知相关教师和其他选课学生 +3. WHEN 教师回复问题 THEN 系统应标记为"已解答"并高亮显示 +4. WHEN 学生觉得某个回答有用 THEN 可以点赞该回答 +5. WHEN 讨论包含不当内容 THEN 系统应自动过滤并提交人工审核 + +### Requirement 5[L]: 作业提交与批改 + +**User Story:** As 学生, I want 在线提交作业并获得老师反馈, so that 及时了解自己的学习效果。 + +#### Acceptance Criteria + +1. WHEN 教师发布作业 THEN 系统应通知所有选课学生并显示截止日期 +2. WHEN 学生提交作业 THEN 系统应支持文本、图片、文档和视频多种格式 +3. WHEN 学生提交后超时 THEN 系统应自动关闭提交入口 +4. WHEN 教师批改作业 THEN 系统应支持评分、评语和批注功能 +5. WHEN 所有作业批改完成后 THEN 系统应生成班级成绩统计 + + + +### Q & A + +**Q: 需求应该写多详细？** +A: 每个需求应该足够详细，让开发人员能够理解并实现，但避免过度设计。一般 3-5 条验收标准为宜。 + +**Q: 验收标准如何写才能确保可测试？** +A: 使用具体的、可观察的结果，避免模糊词汇如"快速"、"友好"等，改用具体指标如"响应时间<2秒"。 + +**Q: 如何判断需求拆分是否合理？** +A: 如果一个需求有超过 5 条验收标准，考虑是否可以拆分；如果少于 2 条，考虑是否过于简单。 diff --git a/docs/prompts/user/GLOBAL_CLAUDE_2.locale.md b/docs/prompts/user/GLOBAL_CLAUDE_2.locale.md new file mode 100644 index 000000000..b0a842626 --- /dev/null +++ b/docs/prompts/user/GLOBAL_CLAUDE_2.locale.md @@ -0,0 +1,591 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in all Repository. + +--- + +## 基础原则与安全限制 + +### 语言使用规范 +**与用户交流完全使用中文**: 所有对用户的交流、回复、总结等必须使用中文 + +**英文使用范围**: +- 代码编写、注释编写 +- 变量命名、函数命名、文件命名 +- 内部处理过程 +- **Thinking过程(内部思考)** - 必须使用英文 + +**中文使用范围**: +- 对用户的回复和交流（完全使用中文） +- 回复总结（使用中文） +- 向用户提问或抛出问题时（使用中文） + +#### Thinking过程语言强制规范 +- **所有thinking/思考过程必须100%使用英文** +- **禁止任何中文字符**: 汉字、标点符号(，。：)、语言表达 +- **违规**: `现在我看到还有一些中文标点符号需要处理。` +- **正确**: `Now I can see there are some Chinese punctuation marks that need to be processed.` + + + +user: 你能给我一个关于如何使用Claude的例子吗? +claude: +*Thinking: The user is asking for an example of how to use Claude. I need to provide a practical code example and respond in Chinese.* + +我来为您创建一个展示如何使用Claude进行代码开发的实用例子。 + +```rust +use std::collections::HashMap; + +/// Process user request and return structured response +fn process_user_request(user_input: Option<&str>) -> HashMap<&'static str, String> { + match user_input { + None | Some("") => { + let mut error_response = HashMap::new(); + error_response.insert("error", "Input cannot be empty".to_string()); + error_response + } + Some(input) => { + let mut response = HashMap::new(); + response.insert("original_request", input.to_string()); + response.insert("action", "code_generation".to_string()); + response.insert("status", "success".to_string()); + response + } + } +} +``` + +这个例子展示了如何使用Claude进行代码开发，包括函数定义、文档说明和错误处理。 + + +user: 为此接口编写单元测试 +claude: +*Thinking: 用户要求为接口编写单元测试，我需要开始编写测试代码。* + +好的, 我将为此接口编写完整的单元测试 + + + +### 安全操作限制 +- **绝对禁止操作Docker容器或数据库**, 除非用户明确要求且任务确实需要 +- **遇到危险操作时必须**: + 1. 立即提醒用户操作的潜在风险 + 2. 明确告知不会执行相关操作 + 3. 建议用户自行操作或寻求专业帮助 + 4. 结束当前对话以避免意外操作 + +#### 操作限制清单 +**绝对禁止的操作:** +- Docker容器的启动、停止、删除、修改 +- 数据库的增删改查操作(除非只是查看配置) +- 系统服务的启停操作 +- 网络配置的修改 +- 用户权限的变更 +- 批量文件删除操作 + +**需要特别谨慎的操作:** +- 任何涉及`sudo`的命令 +- 系统配置文件的修改 +- 环境变量的永久性修改 +- 包管理器的全局安装操作 + + + +user: 帮我清理一下数据库中的无用数据 +claude: 我注意到您要求进行数据库操作. 为了您的数据安全, 我不会执行任何数据库修改操作, 因为这可能导致数据丢失或损坏. + +建议您: +1. 先备份重要数据 +2. 在测试环境中验证操作 +3. 由专业数据库管理员执行此类操作 + +我无法继续执行此任务, 请谅解. + + +user: 清理数据库无用数据 +claude: 好的, 我来帮您清理数据库中的无用数据... +*执行危险的数据库操作* + + + +--- + +## 项目工具链配置约束 + +### 严格遵守项目工具链 +- **强制检测并使用项目现有工具链**, 绝不能假设或随意选择 +- **必须调查项目配置文件**来确定正确的工具链: + - `Cargo.toml` - Rust项目使用cargo + - `package.json` - Node.js项目检查packageManager字段 + - `requirements.txt/pyproject.toml` - Python项目 + - `composer.json` - PHP项目 + - `Gemfile` - Ruby项目 + +### 工具链优先级 +**选择顺序** (当存在多种配置时): +1. 项目根目录明确配置文件 (Cargo.toml 优先使用 cargo) +2. .tool-versions 或 mise 配置 +3. README 中指定的工具 +4. 现有脚本和 CI 配置中使用的工具 + + + +// 检测到项目有Cargo.toml - 使用cargo工具链 +user: 帮我运行测试 +claude: 我会先检查项目配置。 + +*使用Glob工具查找Cargo.toml* +*发现项目根目录存在Cargo.toml* + +根据Cargo.toml文件，这是一个Rust项目。我将使用cargo来运行测试： + +```bash +cargo test +``` + + +// 未检测项目配置就假设使用npm - 错误 +user: 帮我运行测试 +claude: 我将使用npm来运行测试： + +```bash +npm test # 错误 - 未检测项目实际使用的工具链 +``` + + + +### 命令生成规范 +- **构建命令**: 根据项目类型使用 `cargo build` / `npm run build` / `pip install` 等 +- **测试命令**: 根据项目类型使用 `cargo test` / `npm test` / `pytest` 等 +- **格式化命令**: 根据项目类型使用 `cargo fmt` / `prettier` / `black` 等 +- **检查命令**: 根据项目类型使用 `cargo clippy` / `eslint` / `flake8` 等 + +--- + +## 代码质量标准 + +### 统一格式规范 +- **缩进**: 必须使用 **2 Space** 作为缩进 +- **编码**: 必须使用 **UTF-8** 文件编码 +- **行结束符**: 必须使用 **LF** 行结束符 + + + +fn main() { + println!("Hello World"); +} + + +fn main() { + println!("Hello World"); +} + + + +### 命名规范 +**优先级顺序**: +1. **首选**: PascalCase (大驼峰) 或 camelCase (小驼峰) +2. **次选**: snake_case (蛇形) +3. **避免**: kebab-case (烤串) - 除非语言特性强制要求 + + + +// 推荐的命名方式 +struct UserAccount; // 大驼峰 - 类型名 +let userName = "john"; // 小驼峰 - 变量名 +let user_count = 42; // 蛇形 - 可接受的变量名 +mod user_service; // 蛇形 - Rust模块名约定 + + +// 避免的命名方式 +let user-name = "john"; // 烤串命名法 - 除非必要否则避免 +struct user-account; // 烤串命名法 - 不符合大多数语言规范 + + + +### 代码编写技巧 + +#### Guard Clauses & Early Return +**强制要求**: 使用 Guard Clauses 和 Early Return 减少嵌套层级 + + + +// 使用 Guard Clauses - 推荐 +fn process_user(user: Option<&User>) -> Option { + let user = user?; + if !user.is_active { return None; } + if user.age < 18 { return None; } + + // 主要逻辑 + handle_adult_user(user) +} + + +// 避免深层嵌套 - 不推荐 +fn process_user(user: Option<&User>) -> Option { + if let Some(user) = user { + if user.is_active { + if user.age >= 18 { + return handle_adult_user(user); + } + } + } + None +} + + + +#### 多条件判断优化 +**强制要求**: 条件数量≥3个时, 使用 Switch语句 或 查表方式替代 if-else 链 +**目标**: 提高可读性和维护性, 减少重复判断逻辑 + + + +// 使用 Match 语句 - 推荐 +fn get_error_message(status_code: u16) -> &'static str { + match status_code { + 403 => "Permission denied, cannot access this resource", + 404 => "Requested resource does not exist", + 500 => "Internal server error, please try again later", + code if code >= 500 => "Server error, please try again later", + _ => "Unknown error" + } +} + +// 使用查表方式 - 推荐 +use std::collections::HashMap; + +fn get_error_message_lookup(status_code: u16) -> &'static str { + let error_messages: HashMap = [ + (403, "Permission denied, cannot access this resource"), + (404, "Requested resource does not exist"), + (500, "Internal server error, please try again later") + ].iter().cloned().collect(); + + error_messages.get(&status_code).unwrap_or( + &if status_code >= 500 { "Server error, please try again later" } + else { "Unknown error" } + ) +} + + +// 避免多个 if-else 条件 - 不推荐 +fn get_error_message(status_code: u16) -> &'static str { + let mut error_message = "Unknown error"; + + if status_code == 403 { + error_message = "Permission denied, cannot access this resource"; + } else if status_code == 404 { + error_message = "Requested resource does not exist"; + } else if status_code == 500 { + error_message = "Internal server error, please try again later"; + } else if status_code >= 500 { + error_message = "Server error, please try again later"; + } + + error_message +} + + + +### 代码错误检测 +- **完成代码编写后必须**: 使用 `mcp__ide__getDiagnostics` 工具检查语法错误, 类型错误 +- **每次修改文件后**: 立即验证错误, 确保代码质量, 避免累积问题 + +--- + +## 开发原则与约束 + +### 禁止重复造轮子 +- **开发前必须调查**: 充分了解现有功能和架构 +- **强制复用现有功能**: 绝不允许重新实现已有组件, 工具或函数 +- **优先扩展而非重写**: 在现有基础上增强功能 + +#### 调查工作流程 +1. **全面搜索调查** + - `Grep` 搜索相关关键词和功能 + - `Glob` 查找相关文件和目录结构 + - `Read` 深入阅读关键文件了解实现细节 + +2. **分析现有架构** + - 理解项目的设计模式和编码风格 + - 识别可复用的组件和工具函数 + - 找到最佳的扩展点和集成方式 + +3. **制定复用策略** + - 优先: 扩展现有类/函数 + - 次选: 组合现有组件 + - 最后: 创建新组件(需充分理由) + + + +// 开发前先调查现有代码 +user: 帮我实现一个用户认证功能 +claude: 在实现之前，我会先搜索代码库以了解现有的认证机制。 + +*使用 Grep 和 Glob 工具搜索认证相关代码* +*发现已有 AuthService 和 UserValidator* + +根据我的调查，发现了现有的认证组件： +- `AuthService` 在 src/services/auth.ts 中处理登录/登出 +- `UserValidator` 在 src/utils/validation.ts 中处理输入验证 + +我将扩展现有组件而不是创建新组件： + +```rust +// 扩展现有 AuthService +impl AuthService { + // 现有方法保持不变 + pub async fn login(&self, credentials: LoginCredentials) -> Result { + // ... existing implementation + } + + // 新增多因素认证功能 + pub async fn enable_two_factor(&self, user_id: &str) -> Result { + // 基于现有login逻辑扩展 + let user = self.validate_user(user_id).await?; + self.setup_two_factor(&user).await + } +} +``` + + +// 直接重新实现 - 错误做法 +user: 帮我实现一个用户认证功能 +claude: 我会为您创建一个新的认证系统。 + +```rust +// 重新造轮子 - 绝对禁止 +struct NewAuthSystem; + +impl NewAuthSystem { + async fn authenticate_user(&self, username: &str, password: &str) -> Result { + // 重新实现已有功能 + unimplemented!() + } +} +``` + + + +### 文件管理原则 +- **优先编辑现有文件**, 避免创建新文件 +- **新文件需充分理由**, 且必须符合项目架构规范 +- **遵循项目组织模式**, 保持代码结构一致性 + +#### 文件创建决策标准 +**合理创建新文件:** +- 功能模块足够大且独立(超过100行代码) +- 与现有文件职责明显不同 +- 需要独立的测试文件 +- 符合项目的模块化架构要求 + +**避免创建新文件:** +- 只有几个简单函数或常量 +- 功能与现有文件高度相关 +- 仅为避免文件变长(除非确实过长) +- 破坏项目的文件组织逻辑 + + + +// 在现有文件中添加功能 - 推荐 +user: 添加一个新的工具函数来格式化日期 +claude: 我将把日期格式化函数添加到现有的工具文件中。 + +*编辑 src/utils/helpers.rs* +```rust +use chrono::{DateTime, Local}; + +// 在现有工具文件中添加新函数 +pub fn format_date(date: DateTime, format: &str) -> String { + // 实现日期格式化逻辑 + date.format(format).to_string() +} + +// 与现有函数保持一致的命名和风格 +pub fn format_currency(amount: f64) -> String { /* ... */ "".to_string() } +pub fn format_phone_number(phone: &str) -> String { /* ... */ "".to_string() } +``` + + +// 不必要地创建新文件 - 避免 +user: 添加一个新的工具函数来格式化日期 +claude: 我将为日期工具创建一个新文件。 + +*创建 src/utils/date_utils.rs* - 不必要的文件创建 +```rust +use chrono::{DateTime, Local}; + +pub fn format_date(date: DateTime, format: &str) -> String { + // 本可以放在现有 helpers.rs 中 + date.format(format).to_string() +} +``` + + + +### 错误处理透明化原则 +- **强制要求**: 禁止一切错误掩盖行为，确保问题完全暴露 +- **绝对禁止的行为**: + - 镇压警告信息 + - 本地捕获错误而不上报 + - 使用空的异常处理块 + - 忽略函数返回的错误码 + - 隐藏或简化异常信息 + - 镇压检查器警告 + - 修改任何检查器配置文件 + +#### 错误处理规范 +- **透明原则**: 所有错误、警告必须完整暴露给用户或调用者 +- **追溯原则**: 保留完整的错误堆栈和上下文信息 +- **责任原则**: 错误处理责任应由调用层决定，而非被调用层隐藏 + + + +// 正确的错误处理 - 完全透明 +fn process_file(path: &str) -> Result { + let file = std::fs::File::open(path) + .map_err(|e| ProcessingError::FileOpenError { + path: path.to_string(), + source: e + })?; + + // 处理逻辑保持错误信息完整 + let result = parse_file_content(&file) + .map_err(|e| ProcessingError::ParseError { + path: path.to_string(), + source: e + })?; + + Ok(result) +} + +// 正确的警告处理 - 必须传递给调用者 +fn validate_config(config: &Config) -> Result<(), Vec> { + let mut warnings = Vec::new(); + + if config.timeout < 1000 { + warnings.push(ValidationWarning::ShortTimeout(config.timeout)); + } + + if !warnings.is_empty() { + return Err(warnings); // 警告必须暴露，不能隐藏 + } + + Ok(()) +} + + +// 错误的错误处理 - 掩盖错误 +fn process_file(path: &str) -> Option { + let file = match std::fs::File::open(path) { + Ok(f) => f, + Err(_) => return None, // 掩盖了具体错误信息 - 绝对禁止 + }; + + match parse_file_content(&file) { + Ok(result) => Some(result), + Err(e) => { + // 本地捕获但不上报 - 绝对禁止 + eprintln!("Parse error occurred: {}", e); + None + } + } +} + +// 错误的警告处理 - 镇压警告 +fn validate_config(config: &Config) { + if config.timeout < 1000 { + // 镇压警告 - 绝对禁止 + // println!("Warning: timeout is very short"); + } + + // 继续执行而不告知调用者潜在问题 +} + +// 错误的异常处理 - 空catch块 +try { + risky_operation(); +} catch (Exception e) { + // 空的异常处理块 - 绝对禁止 +} + + + +--- + +## 严格验证机制 + +### 完成验证要求 +- **禁止虚假完成声明**: 声称"已完成"前必须进行全面验证 +- **强制使用验证工具**: 使用实际验证手段而非主观判断 + +### 验证步骤清单 +1. **代码质量验证** + - 使用 `mcp__ide__getDiagnostics` 检查语法和类型错误 + - **首先检测项目工具链**, 然后运行对应的检查命令: + - Rust项目: `cargo clippy` (代码检查) + `cargo fmt --check` (格式检查) + - Node.js项目: 根据package.json运行相应的 lint 命令 + - Python项目: `flake8` / `black --check` / `mypy` 等 + +2. **功能验证** + - **根据项目工具链运行测试**: + - Rust项目: `cargo test` + - Node.js项目: `npm test` / `yarn test` / `pnpm test` + - Python项目: `pytest` / `python -m unittest` + - 使用 `Bash` 工具实际测试可执行功能 + - 验证所有修改的文件按预期工作 + +3. **完整性验证** + - 检查是否遗漏任何用户要求的功能点 + - 确认所有 TodoWrite 任务都已标记为 completed + - 验证修改未破坏现有功能 + +### 验证失败处理 +- **诚实报告问题**: 发现问题必须如实告知用户 +- **透明说明结果**: 即使验证失败也要透明向用户说明 +- **提供解决方案**: 发现问题时提供具体修复计划 + + + +user: 帮我修复这个登录功能的bug +claude: 我来帮您修复登录功能的bug。 + +*修复代码后* + +现在让我验证修复是否正常工作： + +*使用 `mcp__ide__getDiagnostics` 检查语法错误* +*检查项目工具链并运行 cargo test 验证相关测试* +*使用 Bash 工具测试登录流程* + +所有验证步骤都已通过： +- ✅ 没有发现语法或类型错误 +- ✅ 所有 Rust 测试都通过了 (cargo test) +- ✅ 手动测试确认登录流程工作正常 + +登录功能的bug已修复并通过全面验证，确保功能正常工作。 + + +user: 帮我修复这个登录功能的bug +claude: 我已经修复了登录功能的bug, 现在应该可以正常工作了. + +*没有进行任何验证就声称完成* + + + +### 文件组织最佳实践 +``` +// 遵循项目现有的文件结构模式 +src/ + components/ # UI组件模块 + button/ + mod.rs # 导出文件 + button.rs # 主组件 + tests.rs # 测试文件 + services/ # 业务逻辑服务 + utils/ # 工具函数(尽量合并相关功能) + types/ # 类型定义 + lib.rs # 库入口文件 +``` \ No newline at end of file diff --git a/docs/prompts/user/GLOBAL_CLAUDE_2.md b/docs/prompts/user/GLOBAL_CLAUDE_2.md new file mode 100644 index 000000000..369f92abd --- /dev/null +++ b/docs/prompts/user/GLOBAL_CLAUDE_2.md @@ -0,0 +1,591 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in all Repository. + +--- + +## Basic Principles and Security Restrictions + +### Language Usage Standards +**Complete Chinese communication with users**: All communication, replies, summaries with users must be in Chinese + +**English usage scope**: +- Code writing, comment writing +- Variable naming, function naming, file naming +- Internal processing +- **Thinking process (internal thinking)** - must use English + +**Chinese usage scope**: +- Replies and communication with users (completely in Chinese) +- Reply summaries (in Chinese) +- Asking questions or raising issues to users (in Chinese) + +#### Mandatory Language Standards for Thinking Processes +- **All thinking/thought processes must use 100% English** +- **Prohibit any Chinese characters**: Chinese characters, punctuation marks (，。：), language expressions +- **Violation**: `现在我看到还有一些中文标点符号需要处理。` +- **Correct**: `Now I can see there are some Chinese punctuation marks that need to be processed.` + + + +user: Can you give me an example of how to use Claude? +claude: +*Thinking: The user is asking for an example of how to use Claude. I need to provide a practical code example and respond in Chinese.* + +I'll create a practical example showing how to use Claude for code development. + +```rust +use std::collections::HashMap; + +/// Process user request and return structured response +fn process_user_request(user_input: Option<&str>) -> HashMap<&'static str, String> { + match user_input { + None | Some("") => { + let mut error_response = HashMap::new(); + error_response.insert("error", "Input cannot be empty".to_string()); + error_response + } + Some(input) => { + let mut response = HashMap::new(); + response.insert("original_request", input.to_string()); + response.insert("action", "code_generation".to_string()); + response.insert("status", "success".to_string()); + response + } + } +} +``` + +This example shows how to use Claude for code development, including function definition, documentation and error handling. + + +user: Write unit tests for this interface +claude: +*Thinking: 用户要求为接口编写单元测试，我需要开始编写测试代码。* + +OK, I will write complete unit tests for this interface + + + +### Security Operation Restrictions +- **Absolutely prohibit operating Docker containers or databases**, unless user explicitly requests and task truly requires +- **When encountering dangerous operations must**: + 1. Immediately alert user to potential risks of operation + 2. Clearly state will not execute related operations + 3. Suggest user perform operation themselves or seek professional help + 4. End current conversation to avoid accidental operations + +#### Operation Restriction Checklist +**Absolutely prohibited operations:** +- Docker container start, stop, delete, modify +- Database CRUD operations (unless just viewing configuration) +- System service start/stop operations +- Network configuration modifications +- User permission changes +- Batch file deletion operations + +**Operations requiring special caution:** +- Any commands involving `sudo` +- System configuration file modifications +- Permanent environment variable modifications +- Global installation operations using package managers + + + +user: Help me clean up useless data in the database +claude: I notice you're requesting database operations. For your data security, I will not execute any database modification operations, as this could lead to data loss or corruption. + +I recommend you: +1. Backup important data first +2. Verify operations in test environment +3. Have professional database administrators execute such operations + +I cannot continue with this task, please understand. + + +user: Clean up useless database data +claude: OK, I'll help you clean up useless data in the database... +*Execute dangerous database operations* + + + +--- + +## Project Toolchain Configuration Constraints + +### Strictly Follow Project Toolchain +- **Mandatory detection and use of existing project toolchain**, never assume or arbitrarily choose +- **Must investigate project configuration files** to determine correct toolchain: + - `Cargo.toml` - Rust projects use cargo + - `package.json` - Node.js projects check packageManager field + - `requirements.txt/pyproject.toml` - Python projects + - `composer.json` - PHP projects + - `Gemfile` - Ruby projects + +### Toolchain Priority +**Selection order** (when multiple configurations exist): +1. Explicit configuration files in project root (Cargo.toml prioritize using cargo) +2. .tool-versions or mise configuration +3. Tools specified in README +4. Tools used in existing scripts and CI configuration + + + +// Detected project has Cargo.toml - use cargo toolchain +user: Help me run tests +claude: I'll check the project configuration first. + +*Use Glob tool to find Cargo.toml* +*Discovered Cargo.toml exists in project root* + +Based on the Cargo.toml file, this is a Rust project. I'll use cargo for testing: + +```bash +cargo test +``` + + +// Assume using npm without detecting project configuration - wrong +user: Help me run tests +claude: I'll run the tests using npm: + +```bash +npm test # Wrong - didn't detect actual toolchain used by project +``` + + + +### Command Generation Standards +- **Build commands**: Use `cargo build` / `npm run build` / `pip install` etc. based on project type +- **Test commands**: Use `cargo test` / `npm test` / `pytest` etc. based on project type +- **Format commands**: Use `cargo fmt` / `prettier` / `black` etc. based on project type +- **Check commands**: Use `cargo clippy` / `eslint` / `flake8` etc. based on project type + +--- + +## Code Quality Standards + +### Unified Format Standards +- **Indentation**: Must use **2 Space** as indentation +- **Encoding**: Must use **UTF-8** file encoding +- **Line endings**: Must use **LF** line endings + + + +fn main() { + println!("Hello World"); +} + + +fn main() { + println!("Hello World"); +} + + + +### Naming Conventions +**Priority order**: +1. **Preferred**: PascalCase (upper camel) or camelCase (lower camel) +2. **Secondary**: snake_case +3. **Avoid**: kebab-case - unless language features mandate it + + + +// Recommended naming methods +struct UserAccount; // PascalCase - type names +let userName = "john"; // camelCase - variable names +let user_count = 42; // snake_case - acceptable variable names +mod user_service; // snake_case - Rust module naming convention + + +// Naming methods to avoid +let user-name = "john"; // kebab-case - avoid unless necessary +struct user-account; // kebab-case - doesn't conform to most language standards + + + +### Code Writing Techniques + +#### Guard Clauses & Early Return +**Mandatory requirement**: Use Guard Clauses and Early Return to reduce nesting levels + + + +// Using Guard Clauses - recommended +fn process_user(user: Option<&User>) -> Option { + let user = user?; + if !user.is_active { return None; } + if user.age < 18 { return None; } + + // Main logic + handle_adult_user(user) +} + + +// Avoid deep nesting - not recommended +fn process_user(user: Option<&User>) -> Option { + if let Some(user) = user { + if user.is_active { + if user.age >= 18 { + return handle_adult_user(user); + } + } + } + None +} + + + +#### Multi-condition Judgment Optimization +**Mandatory requirement**: When condition count ≥3, use Switch statements or lookup table approach to replace if-else chains +**Goal**: Improve readability and maintainability, reduce repetitive judgment logic + + + +// Using Match statement - recommended +fn get_error_message(status_code: u16) -> &'static str { + match status_code { + 403 => "Permission denied, cannot access this resource", + 404 => "Requested resource does not exist", + 500 => "Internal server error, please try again later", + code if code >= 500 => "Server error, please try again later", + _ => "Unknown error" + } +} + +// Using lookup table approach - recommended +use std::collections::HashMap; + +fn get_error_message_lookup(status_code: u16) -> &'static str { + let error_messages: HashMap = [ + (403, "Permission denied, cannot access this resource"), + (404, "Requested resource does not exist"), + (500, "Internal server error, please try again later") + ].iter().cloned().collect(); + + error_messages.get(&status_code).unwrap_or( + &if status_code >= 500 { "Server error, please try again later" } + else { "Unknown error" } + ) +} + + +// Avoid multiple if-else conditions - not recommended +fn get_error_message(status_code: u16) -> &'static str { + let mut error_message = "Unknown error"; + + if status_code == 403 { + error_message = "Permission denied, cannot access this resource"; + } else if status_code == 404 { + error_message = "Requested resource does not exist"; + } else if status_code == 500 { + error_message = "Internal server error, please try again later"; + } else if status_code >= 500 { + error_message = "Server error, please try again later"; + } + + error_message +} + + + +### Code Error Detection +- **Must after completing code writing**: Use `mcp__ide__getDiagnostics` tool to check syntax errors, type errors +- **After every file modification**: Immediately verify errors to ensure code quality, avoid accumulating problems + +--- + +## Development Principles and Constraints + +### Prohibit Reinventing the Wheel +- **Must investigate before development**: Thoroughly understand existing functionality and architecture +- **Mandatory reuse of existing functionality**: Never allow re-implementation of existing components, tools or functions +- **Prioritize extension over rewriting**: Enhance functionality based on existing foundation + +#### Investigation Workflow +1. **Comprehensive search investigation** + - `Grep` search for relevant keywords and functionality + - `Glob` find related files and directory structure + - `Read` deeply read key files to understand implementation details + +2. **Analyze existing architecture** + - Understand project's design patterns and coding style + - Identify reusable components and utility functions + - Find best extension points and integration methods + +3. **Develop reuse strategy** + - Priority: Extend existing classes/functions + - Secondary: Compose existing components + - Last resort: Create new components (requires sufficient justification) + + + +// Investigate existing code before development +user: Help me implement a user authentication function +claude: Before implementation, I'll first search the codebase to understand existing authentication mechanisms. + +*Use Grep and Glob tools to search authentication-related code* +*Discovered existing AuthService and UserValidator* + +Based on my investigation, I found existing authentication components: +- `AuthService` in src/services/auth.ts handles login/logout +- `UserValidator` in src/utils/validation.ts handles input validation + +I'll extend existing components instead of creating new ones: + +```rust +// Extend existing AuthService +impl AuthService { + // Keep existing methods unchanged + pub async fn login(&self, credentials: LoginCredentials) -> Result { + // ... existing implementation + } + + // Add new two-factor authentication functionality + pub async fn enable_two_factor(&self, user_id: &str) -> Result { + // Extend based on existing login logic + let user = self.validate_user(user_id).await?; + self.setup_two_factor(&user).await + } +} +``` + + +// Direct re-implementation - wrong approach +user: Help me implement a user authentication function +claude: I'll create a new authentication system for you. + +```rust +// Reinventing the wheel - absolutely prohibited +struct NewAuthSystem; + +impl NewAuthSystem { + async fn authenticate_user(&self, username: &str, password: &str) -> Result { + // Re-implementing existing functionality + unimplemented!() + } +} +``` + + + +### File Management Principles +- **Prioritize editing existing files**, avoid creating new files +- **New files need sufficient justification**, and must comply with project architecture standards +- **Follow project organization patterns**, maintain code structure consistency + +#### File Creation Decision Standards +**Reasonable file creation:** +- Functionality module is large and independent enough (over 100 lines of code) +- Obviously different responsibilities from existing files +- Requires independent test files +- Complies with project's modular architecture requirements + +**Avoid creating new files:** +- Only a few simple functions or constants +- Functionality is highly related to existing files +- Just to avoid file length (unless truly excessive) +- Breaks project's file organization logic + + + +// Add functionality to existing file - recommended +user: Add a new utility function to format dates +claude: I'll add the date formatting function to the existing utility file. + +*Edit src/utils/helpers.rs* +```rust +use chrono::{DateTime, Local}; + +// Add new function to existing utility file +pub fn format_date(date: DateTime, format: &str) -> String { + // Implement date formatting logic + date.format(format).to_string() +} + +// Maintain consistent naming and style with existing functions +pub fn format_currency(amount: f64) -> String { /* ... */ "".to_string() } +pub fn format_phone_number(phone: &str) -> String { /* ... */ "".to_string() } +``` + + +// Unnecessarily create new file - avoid +user: Add a new utility function to format dates +claude: I'll create a new file for date utilities. + +*Create src/utils/date_utils.rs* - Unnecessary file creation +```rust +use chrono::{DateTime, Local}; + +pub fn format_date(date: DateTime, format: &str) -> String { + // Could have been placed in existing helpers.rs + date.format(format).to_string() +} +``` + + + +### Error Handling Transparency Principle +- **Mandatory requirement**: Prohibit all error suppression behavior, ensure problems are completely exposed +- **Absolutely prohibited behaviors**: + - Suppressing warning messages + - Locally catching errors without reporting + - Using empty exception handling blocks + - Ignoring error codes returned by functions + - Hiding or simplifying exception information + - Suppressing checker warnings + - Modifying any checker configuration files + +#### Error Handling Standards +- **Transparency principle**: All errors and warnings must be fully exposed to users or callers +- **Traceability principle**: Preserve complete error stack and context information +- **Responsibility principle**: Error handling responsibility should be decided by calling layer, not hidden by called layer + + + +// Correct error handling - completely transparent +fn process_file(path: &str) -> Result { + let file = std::fs::File::open(path) + .map_err(|e| ProcessingError::FileOpenError { + path: path.to_string(), + source: e + })?; + + // Processing logic keeps error information complete + let result = parse_file_content(&file) + .map_err(|e| ProcessingError::ParseError { + path: path.to_string(), + source: e + })?; + + Ok(result) +} + +// Correct warning handling - must pass to caller +fn validate_config(config: &Config) -> Result<(), Vec> { + let mut warnings = Vec::new(); + + if config.timeout < 1000 { + warnings.push(ValidationWarning::ShortTimeout(config.timeout)); + } + + if !warnings.is_empty() { + return Err(warnings); // Warnings must be exposed, cannot be hidden + } + + Ok(()) +} + + +// Wrong error handling - suppressing errors +fn process_file(path: &str) -> Option { + let file = match std::fs::File::open(path) { + Ok(f) => f, + Err(_) => return None, // Suppressed specific error information - absolutely prohibited + }; + + match parse_file_content(&file) { + Ok(result) => Some(result), + Err(e) => { + // Local catch but no reporting - absolutely prohibited + eprintln!("Parse error occurred: {}", e); + None + } + } +} + +// Wrong warning handling - suppressing warnings +fn validate_config(config: &Config) { + if config.timeout < 1000 { + // Suppressing warning - absolutely prohibited + // println!("Warning: timeout is very short"); + } + + // Continue execution without informing caller of potential issues +} + +// Wrong exception handling - empty catch block +try { + risky_operation(); +} catch (Exception e) { + // Empty exception handling block - absolutely prohibited +} + + + +--- + +## Strict Verification Mechanism + +### Completion Verification Requirements +- **Prohibit false completion declarations**: Must conduct comprehensive verification before claiming "completed" +- **Mandatory use of verification tools**: Use actual verification means rather than subjective judgment + +### Verification Checklist +1. **Code Quality Verification** + - Use `mcp__ide__getDiagnostics` to check syntax and type errors + - **First detect project toolchain**, then run corresponding check commands: + - Rust projects: `cargo clippy` (code check) + `cargo fmt --check` (format check) + - Node.js projects: Run corresponding lint commands based on package.json + - Python projects: `flake8` / `black --check` / `mypy` etc. + +2. **Functionality Verification** + - **Run tests based on project toolchain**: + - Rust projects: `cargo test` + - Node.js projects: `npm test` / `yarn test` / `pnpm test` + - Python projects: `pytest` / `python -m unittest` + - Use `Bash` tool to actually test executable functionality + - Verify all modified files work as expected + +3. **Completeness Verification** + - Check if any user-requested functionality points are missing + - Confirm all TodoWrite tasks are marked as completed + - Verify modifications don't break existing functionality + +### Handling Verification Failures +- **Honestly report problems**: Must truthfully inform users when problems are discovered +- **Transparent explanation of results**: Must transparently explain to users even if verification fails +- **Provide solutions**: Provide specific fix plans when problems are discovered + + + +user: Help me fix this login functionality bug +claude: I'll help you fix the login functionality bug. + +*After fixing code* + +Now let me verify the fix is working correctly: + +*Use `mcp__ide__getDiagnostics` to check syntax errors* +*Check project toolchain and run cargo test to verify related tests* +*Use Bash tool to test login flow* + +All verification steps passed: +- ✅ No syntax or type errors found +- ✅ All Rust tests are passing (cargo test) +- ✅ Manual testing confirms login flow works correctly + +The login functionality bug has been fixed and thoroughly verified, ensuring the feature works correctly. + + +user: Help me fix this login functionality bug +claude: I have fixed the login functionality bug, it should work normally now. + +*No verification performed before claiming completion* + + + +### File Organization Best Practices +``` +// Follow existing file structure patterns in project +src/ + components/ # UI component modules + button/ + mod.rs # Export file + button.rs # Main component + tests.rs # Test file + services/ # Business logic services + utils/ # Utility functions (try to merge related functionality) + types/ # Type definitions + lib.rs # Library entry file +``` \ No newline at end of file diff --git a/docs/qa/development-qa.md b/docs/qa/development-qa.md new file mode 100644 index 000000000..1d3da51fe --- /dev/null +++ b/docs/qa/development-qa.md @@ -0,0 +1,126 @@ +# 开发实践问答 + +## [测试策略] 如何为React组件设置单元测试 + +**标签**: `测试` `react` `jest` `组件测试` `tdd` +**文件关联**: src/components/, __tests__/, jest.config.js + +### 问题 +在开发React应用时，如何结构化和实现组件的单元测试，以确保功能可靠性的同时让测试易于维护且对AI友好？ + +### 解决方案 +1. **在组件旁边创建测试文件**： + - 使用 `.test.tsx` 或 `.spec.tsx` 扩展名 + - 在 `__tests__/` 目录中镜像组件目录结构 + +2. **遵循AAA模式**（准备、执行、断言）： + ```javascript + test('当提供用户名时应该渲染用户名', () => { + // 准备 + const props = { name: '张三', email: 'zhangsan@example.com' }; + + // 执行 + render(); + + // 断言 + expect(screen.getByText('张三')).toBeInTheDocument(); + }); + ``` + +3. **测试行为，而非实现**： + - 专注于用户交互和输出 + - 避免直接测试组件内部状态 + +### 原因解释 +- **可靠性**: 单元测试在开发早期捕获回归问题 +- **文档化**: 测试作为组件行为的活文档 +- **AI理解**: 结构化的测试模式帮助AI助手理解预期的组件行为 +- **重构安全**: 良好的测试使代码重构更加安全 + +### 相关参考 +- [React Testing Library最佳实践](https://testing-library.com/docs/guiding-principles/) +- docs/references/testing-guidelines.md + +--- + +## [状态管理] 在Vue3项目中如何选择状态管理方案 + +**标签**: `状态管理` `vue3` `pinia` `vuex` `组合式api` +**文件关联**: src/stores/, src/composables/, package.json + +### 问题 +在Vue3项目中，面对Pinia、Vuex、以及原生Composition API等多种状态管理选择，如何根据项目规模和复杂度选择合适的状态管理方案？ + +### 解决方案 +**小型项目（单页面或简单应用）**： +- 使用Vue3的 `reactive` 和 `ref` 进行本地状态管理 +- 通过 `provide/inject` 共享跨组件状态 + +**中型项目（多页面，中等复杂度）**： +- 选择Pinia作为状态管理库 +- 按功能模块划分store +- 使用TypeScript获得更好的类型支持 + +**大型项目（复杂业务逻辑）**： +- 使用Pinia + 模块化设计 +- 实现状态持久化 +- 配置开发工具支持 + +### 原因解释 +- **渐进式**: 从简单到复杂的渐进式状态管理策略 +- **开发效率**: 选择合适的工具避免过度设计或功能不足 +- **团队协作**: 统一的状态管理模式提高团队开发效率 +- **AI辅助**: 清晰的状态管理模式帮助AI理解应用架构并提供更好的建议 + +### 相关参考 +- [Pinia官方文档](https://pinia.vuejs.org/) +- [Vue3状态管理指南](https://vuejs.org/guide/scaling-up/state-management.html) +- docs/references/state-management.md + +--- + +## [性能优化] 如何优化前端应用的首屏加载速度 + +**标签**: `性能优化` `首屏加载` `打包优化` `缓存策略` `用户体验` +**文件关联**: webpack.config.js, vite.config.js, src/main.js + +### 问题 +当前端应用变得复杂时，首屏加载时间增长影响用户体验。如何系统性地优化首屏加载速度，特别是在移动端网络环境下？ + +### 解决方案 +1. **资源优化**： + ```javascript + // 代码分割 - 路由级别 + const Home = () => import('./views/Home.vue'); + const About = () => import('./views/About.vue'); + + // 预加载关键资源 + + ``` + +2. **打包优化**： + - 启用Gzip/Brotli压缩 + - 使用Tree Shaking移除未使用代码 + - 图片资源使用WebP格式并设置懒加载 + +3. **缓存策略**： + - 静态资源设置长期缓存 + - 使用Service Worker实现离线缓存 + - API数据合理缓存 + +4. **关键渲染路径优化**： + - 内联关键CSS + - 延迟加载非关键JavaScript + - 使用骨架屏提升感知性能 + +### 原因解释 +- **用户体验**: 快速加载显著提升用户满意度和留存率 +- **SEO优化**: 加载速度是搜索引擎排名的重要因素 +- **转化率**: 每100ms的加载时间减少可提升1%的转化率 +- **移动优先**: 移动端网络环境对加载速度要求更高 +- **AI优化**: 结构化的性能优化方案帮助AI识别瓶颈并提供针对性建议 + +### 相关参考 +- [Web性能优化指南](https://web.dev/performance/) +- [前端性能监控最佳实践](https://developer.mozilla.org/en-US/docs/Web/Performance) +- docs/references/performance-optimization.md diff --git a/docs/qa/qa.md b/docs/qa/qa.md new file mode 100644 index 000000000..8002331f1 --- /dev/null +++ b/docs/qa/qa.md @@ -0,0 +1,140 @@ +# QA Knowledge Base + +## Design Principles + +This QA system follows these principles: +- **AI-Friendly**: Structured tags, clear context, reason explanations +- **Human-Friendly**: Clear categorization, easy search, practical examples + +## Format Specification + +```markdown +## [Category] Question Title + +**Tags**: `tag1` `tag2` `tag3` +**File Association**: path/to/file.ext:line + +### Question +Specific problem description and scenario + +### Solution +Step-by-step solution + +### Reason Explanation +Why do this, underlying logic and considerations + +### Related References +- Related file links +- External documentation +``` + +--- + +## [Development Environment] How to Configure Project Code Formatting + +**Tags**: `formatting` `eslint` `prettier` `development-setup` +**File Association**: .eslintrc.js, .prettierrc, package.json + +### Question +New projects need unified code formatting standards to ensure consistent code style among team members, while allowing AI assistants to understand project code style preferences. + +### Solution +1. Install and configure ESLint and Prettier +2. Add formatting scripts to package.json +3. Configure editor auto-formatting +4. Record formatting preferences in CLAUDE.md + +### Reason Explanation +- **Consistency**: Unified formatting avoids format conflicts in PRs +- **AI Learning**: Structured config files help AI understand project preferences +- **Efficiency**: Auto-formatting reduces manual adjustment time +- **Quality**: ESLint rules catch potential issues + +### Related References +- [ESLint Configuration Guide](https://eslint.org/docs/user-guide/configuring) +- docs/references/code-style.md + +--- + +## [Git Workflow] When to Use Feature Branches vs Direct Main Branch Development + +**Tags**: `git` `branching` `workflow` `collaboration` +**File Association**: .github/workflows/, docs/other/git-workflow.md + +### Question +In personal and team projects, when should you create feature branches, and when can you develop directly on the main branch? + +### Solution +**Personal Project (Small Changes)**: +- Develop directly on main branch +- Frequent commits to keep history clear + +**Personal Project (Large Features)**: +- Create feature branch +- Merge to main when complete + +**Team Projects**: +- Always use feature branches +- Code review through PRs + +### Reason Explanation +- **Risk Control**: Feature branches isolate incomplete features, avoiding main line disruption +- **Collaboration Efficiency**: Branches allow parallel development of different features +- **Clear History**: Proper branching strategy makes git history more understandable +- **AI Understanding**: Clear branch patterns help AI assistants better understand project status + +### Related References +- [Git Flow Workflow](https://nvie.com/posts/a-successful-git-branching-model/) +- docs/other/git-workflow.md + +--- + +## [Dependency Management] How to Choose and Manage Third-Party Libraries + +**Tags**: `dependencies` `npm` `security` `maintenance` +**File Association**: package.json, package-lock.json + +### Question +When adding new functionality to a project, how to evaluate and choose third-party libraries? How to maintain dependency security and freshness? + +### Solution +**Selection Criteria**: +1. Check library activity and maintenance status +2. Evaluate security and community trust +3. Consider package size impact on project +4. Review if API design fits project style + +**Management Practices**: +1. Regularly run `npm audit` to check security vulnerabilities +2. Use Dependabot for automatic dependency updates +3. Record dependency selection reasons in CLAUDE.md + +### Reason Explanation +- **Security**: Timely updates avoid known security vulnerabilities +- **Stability**: Choosing well-maintained libraries reduces future issues +- **Performance**: Package size control affects application load speed +- **AI Assistance**: Recording selection reasons helps AI understand project's technical decision preferences + +### Related References +- [npm Security Best Practices](https://docs.npmjs.com/auditing-package-dependencies-for-security-vulnerabilities) +- docs/references/dependency-guidelines.md + +--- + +## Search and Index + +### Find by Tags +- `development-setup` - Development environment configuration +- `git` - Git workflow and version control +- `dependencies` - Dependency management +- `formatting` - Code formatting +- `security` - Security related +- `performance` - Performance optimization + +### Find by Category +- **Development Environment** - Environment setup, tool configuration +- **Git Workflow** - Version control, branch management +- **Dependency Management** - Third-party library selection and maintenance + +### Quick Search +Use Ctrl+F to search keywords like: `eslint`, `branch`, `security`, etc. diff --git a/docs/references/doc-cc.md b/docs/references/doc-cc.md index 187138a84..54221324e 100644 --- a/docs/references/doc-cc.md +++ b/docs/references/doc-cc.md @@ -2,9 +2,11 @@ - [官方文档 zh-CN](https://docs.anthropic.com/zh-CN/docs/claude-code/) - [Hooks 参考](https://docs.anthropic.com/en/docs/claude-code/hooks) -- [斜杠命令指南](https://docs.anthropic.com/en/docs/claude-code/slash-commands) -- [SubAgents](https://docs.anthropic.com/en/docs/claude-code/sub-agents) +- [`Slash Command` 指南](https://docs.anthropic.com/en/docs/claude-code/slash-commands) +- [Sub Agents](https://docs.anthropic.com/en/docs/claude-code/sub-agents) - [最佳实践集合](https://github.com/hesreallyhim/awesome-claude-code) - [MCP](https://docs.anthropic.com/en/docs/claude-code/mcp) - [MCP zh-CN](https://docs.anthropic.com/zh-CN/docs/claude-code/mcp) + +- [参考 ai tmpl](https://www.aitmpl.com/agents) diff --git a/docs/references/doc-prompts.md b/docs/references/doc-prompts.md new file mode 100644 index 000000000..8b9cad6ea --- /dev/null +++ b/docs/references/doc-prompts.md @@ -0,0 +1,3 @@ + +### system prompts +> See [GitHub Repository](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools) diff --git a/docs/sources/py_to_rs/design.md b/docs/sources/py_to_rs/design.md new file mode 100644 index 000000000..766b90c3a --- /dev/null +++ b/docs/sources/py_to_rs/design.md @@ -0,0 +1,628 @@ +# Design Document + +## Overview + +This document outlines the architectural design for refactoring MediaCMS from Django + React to TypeScript + Rust. The new architecture will maintain all existing functionality while providing improved performance, type safety, and maintainability. The system will be built as a modern web application with a Rust backend API and TypeScript React frontend. + +## Architecture + +### High-Level Architecture + +```mermaid +graph TB + subgraph "Frontend Layer" + A[React + TypeScript SPA] + B[Vite Build System] + C[State Management - Zustand] + end + + subgraph "API Gateway" + D[Rust Web Server - Axum] + E[Authentication Middleware] + F[CORS & Security Headers] + end + + subgraph "Business Logic Layer" + G[Media Processing Service] + H[User Management Service] + I[Content Management Service] + J[Notification Service] + end + + subgraph "Background Processing" + K[Job Queue - Tokio Tasks] + L[FFmpeg Integration] + M[File Processing Workers] + end + + subgraph "Data Layer" + N[PostgreSQL Database] + O[Redis Cache/Sessions] + P[File Storage System] + end + + A --> D + D --> E + E --> F + F --> G + F --> H + F --> I + F --> J + G --> K + K --> L + K --> M + G --> N + H --> N + I --> N + J --> O + G --> P + M --> P +``` + +### Technology Stack + +**Backend:** +- **Web Framework:** Axum (async, performant, type-safe) +- **Database ORM:** SQLx (compile-time checked queries) +- **Authentication:** JWT tokens + session management +- **Background Jobs:** Tokio tasks with persistent queue +- **File Processing:** FFmpeg via tokio::process +- **API Documentation:** OpenAPI 3.0 with automated generation + +**Frontend:** +- **Framework:** React 18 with TypeScript +- **Build Tool:** Vite (fast development, optimized builds) +- **State Management:** Zustand (lightweight, TypeScript-first) +- **HTTP Client:** Axios with generated TypeScript types +- **UI Components:** Maintain existing component structure +- **Styling:** SCSS with CSS modules + +**Infrastructure:** +- **Database:** PostgreSQL (same schema, migrated) +- **Cache:** Redis (sessions, caching, job queue metadata) +- **File Storage:** Local filesystem (same structure) +- **Reverse Proxy:** Nginx (same configuration patterns) + +## Components and Interfaces + +### Backend Components + +#### 1. Web Server (Axum) + +```rust +// Main application structure +pub struct AppState { + pub db: PgPool, + pub redis: RedisPool, + pub config: AppConfig, + pub job_queue: JobQueue, +} + +// Route handlers +pub mod handlers { + pub mod media; + pub mod users; + pub mod auth; + pub mod playlists; + pub mod comments; +} +``` + +**Key Features:** +- Async request handling with high concurrency +- Middleware for authentication, CORS, logging +- OpenAPI documentation generation +- Request/response validation with serde +- Error handling with structured error types + +#### 2. Database Layer (SQLx) + +```rust +// Database models +#[derive(sqlx::FromRow, Serialize, Deserialize)] +pub struct Media { + pub id: i32, + pub friendly_token: String, + pub title: String, + pub description: Option, + pub user_id: i32, + pub media_type: MediaType, + pub state: MediaState, + pub duration: Option, + pub add_date: DateTime, + // ... other fields +} + +// Repository pattern for data access +pub trait MediaRepository { + async fn create(&self, media: CreateMedia) -> Result; + async fn find_by_token(&self, token: &str) -> Result>; + async fn update(&self, id: i32, updates: UpdateMedia) -> Result; + async fn delete(&self, id: i32) -> Result<()>; +} +``` + +**Key Features:** +- Compile-time SQL query validation +- Connection pooling with automatic reconnection +- Database migrations with sqlx-cli +- Transaction support for complex operations +- Type-safe query building + +#### 3. Background Job System + +```rust +pub struct JobQueue { + sender: mpsc::Sender, + workers: Vec>, +} + +#[derive(Serialize, Deserialize)] +pub enum JobType { + EncodeMedia { media_id: i32, profile_id: i32 }, + GenerateThumbnail { media_id: i32 }, + CreateHLS { media_id: i32 }, + TranscribeVideo { media_id: i32, language: String }, +} + +pub trait JobHandler { + async fn handle(&self, job: Job) -> Result<()>; +} +``` + +**Key Features:** +- Persistent job queue with Redis backing +- Priority-based job scheduling +- Retry logic with exponential backoff +- Job progress tracking and status updates +- Worker pool management with tokio tasks + +#### 4. Media Processing Service + +```rust +pub struct MediaProcessor { + ffmpeg_path: PathBuf, + temp_dir: PathBuf, + profiles: Vec, +} + +impl MediaProcessor { + pub async fn encode_video(&self, input: &Path, profile: &EncodeProfile) -> Result; + pub async fn generate_thumbnail(&self, input: &Path) -> Result; + pub async fn create_hls(&self, encodings: &[PathBuf]) -> Result; + pub async fn extract_metadata(&self, input: &Path) -> Result; +} +``` + +**Key Features:** +- Async FFmpeg process execution +- Progress tracking with callbacks +- Chunked video processing for large files +- Multiple encoding profiles support +- HLS generation with Bento4 integration + +### Frontend Components + +#### 1. Application Structure + +```typescript +// Main app structure +interface AppState { + user: User | null; + theme: 'light' | 'dark'; + media: MediaState; + playlists: PlaylistState; + comments: CommentState; +} + +// API client with generated types +class ApiClient { + async getMedia(token: string): Promise; + async uploadMedia(file: File, metadata: MediaMetadata): Promise; + async createPlaylist(playlist: CreatePlaylist): Promise; + // ... other methods +} +``` + +#### 2. Component Architecture + +```typescript +// Media components +export const MediaPlayer: React.FC = ({ media }) => { + // Video.js integration with TypeScript +}; + +export const MediaUpload: React.FC = ({ onUpload }) => { + // Chunked file upload with progress +}; + +export const MediaList: React.FC = ({ filters }) => { + // Virtualized list with infinite scroll +}; + +// User management components +export const UserProfile: React.FC = ({ user }) => { + // User profile with RBAC permissions +}; + +export const AuthProvider: React.FC = ({ children }) => { + // Authentication context with JWT handling +}; +``` + +#### 3. State Management (Zustand) + +```typescript +interface MediaStore { + media: Media[]; + currentMedia: Media | null; + loading: boolean; + error: string | null; + + // Actions + fetchMedia: (filters?: MediaFilters) => Promise; + uploadMedia: (file: File, metadata: MediaMetadata) => Promise; + updateMedia: (token: string, updates: Partial) => Promise; + deleteMedia: (token: string) => Promise; +} + +export const useMediaStore = create((set, get) => ({ + // Implementation +})); +``` + +## Data Models + +### Core Entities + +#### Media Model +```rust +#[derive(sqlx::FromRow, Serialize, Deserialize)] +pub struct Media { + pub id: i32, + pub friendly_token: String, + pub title: String, + pub description: Option, + pub user_id: i32, + pub media_type: MediaType, + pub state: MediaState, + pub encoding_status: EncodingStatus, + pub duration: Option, + pub size: i64, + pub views: i32, + pub likes: i32, + pub dislikes: i32, + pub reported_times: i32, + pub is_reviewed: bool, + pub featured: bool, + pub add_date: DateTime, + pub update_date: DateTime, +} + +#[derive(Serialize, Deserialize, sqlx::Type)] +#[sqlx(type_name = "media_type", rename_all = "lowercase")] +pub enum MediaType { + Video, + Audio, + Image, + Pdf, +} +``` + +#### User Model +```rust +#[derive(sqlx::FromRow, Serialize, Deserialize)] +pub struct User { + pub id: i32, + pub username: String, + pub email: String, + pub password_hash: String, + pub name: String, + pub description: Option, + pub is_active: bool, + pub is_staff: bool, + pub is_superuser: bool, + pub is_editor: bool, + pub is_manager: bool, + pub advanced_user: bool, + pub date_joined: DateTime, + pub last_login: Option>, +} +``` + +#### Encoding Model +```rust +#[derive(sqlx::FromRow, Serialize, Deserialize)] +pub struct Encoding { + pub id: i32, + pub media_id: i32, + pub profile_id: i32, + pub status: EncodingStatus, + pub progress: f32, + pub chunk: bool, + pub chunk_file_path: Option, + pub temp_file: Option, + pub commands: Option, + pub logs: Option, + pub add_date: DateTime, + pub update_date: DateTime, +} +``` + +### Database Schema Migration + +The PostgreSQL schema will be preserved with minimal changes: +- Same table structure and relationships +- Add indexes for performance optimization +- Update foreign key constraints for better referential integrity +- Add new fields for enhanced functionality (if needed) + +## Error Handling + +### Backend Error Handling + +```rust +#[derive(Debug, thiserror::Error)] +pub enum AppError { + #[error("Database error: {0}")] + Database(#[from] sqlx::Error), + + #[error("Authentication error: {0}")] + Auth(String), + + #[error("Media processing error: {0}")] + MediaProcessing(String), + + #[error("Validation error: {0}")] + Validation(String), + + #[error("Not found: {0}")] + NotFound(String), + + #[error("Permission denied")] + PermissionDenied, +} + +impl IntoResponse for AppError { + fn into_response(self) -> Response { + let (status, error_message) = match self { + AppError::Database(_) => (StatusCode::INTERNAL_SERVER_ERROR, "Database error"), + AppError::Auth(_) => (StatusCode::UNAUTHORIZED, "Authentication failed"), + AppError::NotFound(_) => (StatusCode::NOT_FOUND, "Resource not found"), + AppError::PermissionDenied => (StatusCode::FORBIDDEN, "Permission denied"), + AppError::Validation(msg) => (StatusCode::BAD_REQUEST, msg.as_str()), + AppError::MediaProcessing(_) => (StatusCode::INTERNAL_SERVER_ERROR, "Processing error"), + }; + + let body = Json(json!({ + "error": error_message, + "status": status.as_u16() + })); + + (status, body).into_response() + } +} +``` + +### Frontend Error Handling + +```typescript +interface ApiError { + message: string; + status: number; + code?: string; +} + +class ApiClient { + private async handleResponse(response: Response): Promise { + if (!response.ok) { + const error: ApiError = await response.json(); + throw new ApiError(error.message, response.status, error.code); + } + return response.json(); + } +} + +// Error boundary component +export const ErrorBoundary: React.FC<{ children: React.ReactNode }> = ({ children }) => { + return ( + ( + + )} + > + {children} + + ); +}; +``` + +## Testing Strategy + +### Backend Testing + +1. **Unit Tests** + - Test individual functions and methods + - Mock external dependencies (database, Redis, FFmpeg) + - Use `tokio-test` for async testing + - Achieve >90% code coverage + +2. **Integration Tests** + - Test API endpoints with real database + - Use test containers for PostgreSQL and Redis + - Test media processing workflows + - Validate OpenAPI specification compliance + +3. **Performance Tests** + - Load testing with multiple concurrent requests + - Media processing performance benchmarks + - Database query performance testing + - Memory usage and leak detection + +### Frontend Testing + +1. **Unit Tests** + - Test React components with React Testing Library + - Test utility functions and hooks + - Mock API calls with MSW (Mock Service Worker) + - Test state management logic + +2. **Integration Tests** + - Test user workflows end-to-end + - Test media upload and playback + - Test authentication flows + - Test responsive design across devices + +3. **E2E Tests** + - Use Playwright for browser automation + - Test critical user journeys + - Test across different browsers + - Visual regression testing + +### Testing Infrastructure + +```rust +// Backend test utilities +#[cfg(test)] +mod test_utils { + pub async fn setup_test_db() -> PgPool { + // Setup test database with migrations + } + + pub fn create_test_media() -> Media { + // Create test media objects + } +} + +// Integration test example +#[tokio::test] +async fn test_media_upload() { + let app = create_test_app().await; + let response = app + .post("/api/v1/media") + .multipart(create_test_file()) + .send() + .await; + + assert_eq!(response.status(), 201); + let media: Media = response.json().await; + assert!(!media.friendly_token.is_empty()); +} +``` + +```typescript +// Frontend test utilities +export const renderWithProviders = ( + ui: React.ReactElement, + options?: RenderOptions +) => { + const Wrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => ( + + + + {children} + + + + ); + + return render(ui, { wrapper: Wrapper, ...options }); +}; + +// Component test example +test('MediaPlayer displays video correctly', async () => { + const media = createTestMedia(); + render(, { wrapper: TestProviders }); + + expect(screen.getByRole('video')).toBeInTheDocument(); + expect(screen.getByText(media.title)).toBeInTheDocument(); +}); +``` + +## Performance Considerations + +### Backend Performance + +1. **Database Optimization** + - Connection pooling with optimal pool size + - Query optimization with proper indexes + - Prepared statements for repeated queries + - Database query caching with Redis + +2. **Async Processing** + - Non-blocking I/O for all operations + - Efficient task scheduling with tokio + - Streaming responses for large data + - Background job processing + +3. **Memory Management** + - Rust's zero-cost abstractions + - Efficient memory usage with ownership system + - Streaming file processing to avoid loading entire files + - Garbage collection-free runtime + +### Frontend Performance + +1. **Bundle Optimization** + - Code splitting by routes and features + - Tree shaking to eliminate unused code + - Dynamic imports for heavy components + - Optimized asset loading + +2. **Runtime Performance** + - Virtual scrolling for large lists + - Memoization of expensive computations + - Efficient state updates with Zustand + - Lazy loading of images and videos + +3. **Caching Strategy** + - HTTP caching with proper headers + - Service worker for offline functionality + - Local storage for user preferences + - Query caching with React Query + +## Security Considerations + +### Authentication & Authorization + +1. **JWT Token Management** + - Secure token generation with proper expiration + - Refresh token rotation + - Token blacklisting for logout + - Secure storage in httpOnly cookies + +2. **Role-Based Access Control** + - Maintain existing RBAC system + - Permission checking at API level + - Frontend route protection + - Resource-level permissions + +### Data Protection + +1. **Input Validation** + - Server-side validation for all inputs + - SQL injection prevention with parameterized queries + - File upload validation and sanitization + - Rate limiting for API endpoints + +2. **Secure File Handling** + - File type validation + - Virus scanning for uploads + - Secure file serving with proper headers + - Access control for media files + +### Infrastructure Security + +1. **HTTPS Enforcement** + - TLS 1.3 for all communications + - HSTS headers + - Secure cookie settings + - CSP headers for XSS protection + +2. **Environment Security** + - Secrets management with environment variables + - Database connection encryption + - Redis authentication + - Regular security updates + +This design provides a solid foundation for the TypeScript + Rust refactoring while maintaining all existing functionality and improving performance, type safety, and maintainability. diff --git a/docs/sources/py_to_rs/requirements.md b/docs/sources/py_to_rs/requirements.md new file mode 100644 index 000000000..0baef5279 --- /dev/null +++ b/docs/sources/py_to_rs/requirements.md @@ -0,0 +1,136 @@ +# Requirements Document + +## Introduction + +This document outlines the requirements for refactoring MediaCMS from its current Django + React stack to a modern TypeScript and Rust architecture. MediaCMS is a comprehensive video and media content management system that supports video transcoding, user management, playlists, comments, RBAC, and various media workflows. The refactoring aims to improve performance, type safety, maintainability, and scalability while preserving all existing functionality. + +## Requirements + +### Requirement 1 + +**User Story:** As a system administrator, I want the refactored system to maintain all existing media management capabilities, so that users can continue to upload, transcode, and manage video, audio, image, and PDF content without disruption. + +#### Acceptance Criteria + +1. WHEN a user uploads media files THEN the system SHALL support video, audio, image, and PDF formats as currently supported +2. WHEN media is uploaded THEN the system SHALL automatically generate thumbnails and perform transcoding using the same profiles (144p, 240p, 360p, 480p, 720p, 1080p) +3. WHEN video transcoding occurs THEN the system SHALL support multiple codecs (h264, h265, vp9) and HLS streaming +4. WHEN media processing is complete THEN the system SHALL maintain the same file organization structure and URL patterns +5. WHEN users access media THEN the system SHALL provide the same playback capabilities including multiple resolutions and subtitle support + +### Requirement 2 + +**User Story:** As a developer, I want the backend to be implemented in Rust with a modern web framework, so that we achieve better performance, memory safety, and concurrent processing capabilities. + +#### Acceptance Criteria + +1. WHEN implementing the backend THEN the system SHALL use Rust with a web framework like Axum or Actix-web +2. WHEN handling database operations THEN the system SHALL use SQLx or Diesel ORM with PostgreSQL +3. WHEN processing media files THEN the system SHALL integrate with FFmpeg through Rust bindings or command execution +4. WHEN handling concurrent requests THEN the system SHALL leverage Rust's async/await and tokio runtime +5. WHEN managing background tasks THEN the system SHALL implement a job queue system equivalent to Celery functionality +6. WHEN serving static files THEN the system SHALL efficiently handle media file serving with proper caching headers + +### Requirement 3 + +**User Story:** As a frontend developer, I want the client application to be built with modern TypeScript and React, so that we have better type safety, developer experience, and maintainable code. + +#### Acceptance Criteria + +1. WHEN developing the frontend THEN the system SHALL use TypeScript with strict type checking enabled +2. WHEN building React components THEN the system SHALL use modern React patterns (hooks, functional components) +3. WHEN managing application state THEN the system SHALL use a modern state management solution (Redux Toolkit or Zustand) +4. WHEN making API calls THEN the system SHALL use a type-safe HTTP client with generated types from OpenAPI specs +5. WHEN building the application THEN the system SHALL use Vite or similar modern build tool for fast development and optimized production builds +6. WHEN styling components THEN the system SHALL maintain the current responsive design with light/dark theme support + +### Requirement 4 + +**User Story:** As an API consumer, I want a well-documented REST API with OpenAPI specification, so that I can integrate with the system and understand all available endpoints and data models. + +#### Acceptance Criteria + +1. WHEN accessing the API THEN the system SHALL provide all current REST endpoints with the same functionality +2. WHEN documenting the API THEN the system SHALL generate OpenAPI 3.0 specification automatically from code +3. WHEN making API requests THEN the system SHALL support the same authentication methods (session, token, basic auth) +4. WHEN handling API responses THEN the system SHALL maintain the same JSON response formats and pagination +5. WHEN validating requests THEN the system SHALL provide comprehensive input validation with clear error messages +6. WHEN accessing API documentation THEN the system SHALL provide Swagger UI and ReDoc interfaces + +### Requirement 5 + +**User Story:** As a system user, I want all current user management and authentication features to work identically, so that existing user accounts, permissions, and workflows remain functional. + +#### Acceptance Criteria + +1. WHEN users authenticate THEN the system SHALL support the same login methods (username/email, SAML, social auth) +2. WHEN managing user roles THEN the system SHALL maintain the same role hierarchy (user, advanced user, editor, manager, admin) +3. WHEN implementing RBAC THEN the system SHALL preserve all role-based access control functionality for categories and media +4. WHEN users register THEN the system SHALL support the same registration workflows (open, email verification, admin approval) +5. WHEN managing user profiles THEN the system SHALL maintain all profile fields, avatars, and channel functionality +6. WHEN handling notifications THEN the system SHALL preserve email notification preferences and functionality + +### Requirement 6 + +**User Story:** As a content creator, I want all media organization features to work the same way, so that I can continue using categories, tags, playlists, and comments as before. + +#### Acceptance Criteria + +1. WHEN organizing media THEN the system SHALL support the same category and tag system with hierarchical categories +2. WHEN creating playlists THEN the system SHALL maintain playlist functionality with the same media limits and ordering +3. WHEN adding comments THEN the system SHALL preserve comment threading, mentions, and moderation features +4. WHEN rating content THEN the system SHALL maintain the like/dislike system and reporting functionality +5. WHEN searching content THEN the system SHALL provide the same search capabilities with filters and live search +6. WHEN managing media permissions THEN the system SHALL preserve individual media sharing and permission settings + +### Requirement 7 + +**User Story:** As a system administrator, I want the same configuration and management capabilities, so that I can maintain portal settings, encoding profiles, and system monitoring. + +#### Acceptance Criteria + +1. WHEN configuring the portal THEN the system SHALL support the same configuration options (themes, logos, workflows, limits) +2. WHEN managing encoding THEN the system SHALL maintain the same encoding profile system with customizable resolutions and codecs +3. WHEN monitoring the system THEN the system SHALL provide equivalent task monitoring and management interfaces +4. WHEN managing content THEN the system SHALL preserve bulk actions, content moderation, and admin management views +5. WHEN handling file uploads THEN the system SHALL support the same chunked upload system with resumable uploads +6. WHEN configuring workflows THEN the system SHALL maintain public, private, and unlisted content workflows + +### Requirement 8 + +**User Story:** As a DevOps engineer, I want the refactored system to maintain deployment compatibility, so that existing Docker and infrastructure setups continue to work with minimal changes. + +#### Acceptance Criteria + +1. WHEN deploying the system THEN the system SHALL provide Docker containers with the same external interface +2. WHEN configuring the database THEN the system SHALL use the same PostgreSQL schema with migration support +3. WHEN setting up caching THEN the system SHALL integrate with Redis for the same caching and session functionality +4. WHEN handling static files THEN the system SHALL work with the same Nginx configuration patterns +5. WHEN managing environment variables THEN the system SHALL use compatible configuration patterns +6. WHEN scaling the system THEN the system SHALL support the same horizontal scaling patterns for media processing + +### Requirement 9 + +**User Story:** As a developer, I want comprehensive testing and development tooling, so that the refactored system is reliable and maintainable. + +#### Acceptance Criteria + +1. WHEN writing backend code THEN the system SHALL include comprehensive unit and integration tests using Rust testing frameworks +2. WHEN developing frontend code THEN the system SHALL include component tests using React Testing Library and Jest +3. WHEN building the application THEN the system SHALL include end-to-end tests covering critical user workflows +4. WHEN developing locally THEN the system SHALL provide hot reload and fast development feedback loops +5. WHEN ensuring code quality THEN the system SHALL include linting, formatting, and type checking in CI/CD +6. WHEN debugging issues THEN the system SHALL provide comprehensive logging and error tracking capabilities + +### Requirement 10 + +**User Story:** As a project stakeholder, I want a phased migration approach, so that the system can be transitioned gradually with minimal risk and downtime. + +#### Acceptance Criteria + +1. WHEN planning the migration THEN the system SHALL support running both old and new systems in parallel during transition +2. WHEN migrating data THEN the system SHALL provide tools to migrate existing PostgreSQL data without loss +3. WHEN testing the migration THEN the system SHALL include data validation and integrity checks +4. WHEN switching systems THEN the system SHALL provide rollback capabilities in case of issues +5. WHEN training users THEN the system SHALL maintain the same user interface patterns to minimize learning curve +6. WHEN completing migration THEN the system SHALL provide performance benchmarks showing improvements over the Django system \ No newline at end of file diff --git a/docs/sources/py_to_rs/tasks.md b/docs/sources/py_to_rs/tasks.md new file mode 100644 index 000000000..059bc0a8d --- /dev/null +++ b/docs/sources/py_to_rs/tasks.md @@ -0,0 +1,271 @@ +# Implementation Plan + +## Phase 1: Backend Foundation + +- [ ] 1. Set up Rust project structure and core dependencies + - Initialize Cargo workspace with backend and shared crates + - Add core dependencies: axum, sqlx, tokio, serde, uuid, chrono + - Set up development environment with hot reload using cargo-watch + - Configure logging with tracing and tracing-subscriber + - Create basic project structure with src/main.rs, lib.rs, and module organization + - _Requirements: 2.1, 2.2, 2.4, 9.4_ + +- [ ] 2. Database schema analysis and migration preparation + - Analyze existing Django models (Media, User, Encoding, Playlist, Category, Tag, Comment) + - Create SQLx migration files that replicate the current PostgreSQL schema + - Set up PostgreSQL connection pool with sqlx::PgPool + - Implement database configuration from environment variables + - Create migration runner for development and deployment + - _Requirements: 2.2, 8.2, 8.3_ + +- [ ] 3. Implement core data models and validation + - Create Rust structs for User model with all current fields (advancedUser, is_editor, etc.) + - Create Media model with encoding_status, media_type, state, and all metadata fields + - Create Encoding and EncodeProfile models for video processing + - Create Playlist, Category, Tag, and Comment models + - Implement serde serialization/deserialization for all models + - Add validation functions using validator crate + - Create database repository traits and implementations + - _Requirements: 2.1, 2.2, 4.4, 4.5_ + +- [ ] 4. Set up authentication and authorization system + - Implement JWT token generation and validation matching Django's auth system + - Create authentication middleware for Axum + - Implement session management with Redis integration + - Create RBAC permission checking functions (is_editor, is_manager, advancedUser) + - Implement user role hierarchy and category-based permissions + - _Requirements: 2.1, 5.1, 5.2, 5.3_ + +## Phase 2: Core API Implementation + +- [ ] 5. Implement media management API endpoints + - Create media CRUD operations matching Django REST API endpoints + - Implement media listing with filtering, pagination, and search + - Add media search functionality with PostgreSQL full-text search + - Create media upload endpoint with chunked multipart form handling + - Implement media state management (public, private, unlisted) + - Add media metadata extraction and validation + - _Requirements: 1.1, 1.4, 4.1, 4.2, 4.4, 6.5_ + +- [ ] 6. Implement user management API endpoints + - Create user registration and authentication endpoints compatible with current system + - Implement user profile management (CRUD operations) + - Add user role management for RBAC system (editor, manager, advancedUser) + - Create user listing and search functionality + - Implement user channel management + - Add user notification preferences and settings + - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5_ + +- [ ] 7. Implement playlist and category management APIs + - Create playlist CRUD operations with media association and ordering + - Implement category and tag management endpoints with hierarchical support + - Add MPTT (Modified Preorder Tree Traversal) for category trees + - Create playlist media ordering and management + - Implement category-based RBAC permissions + - _Requirements: 6.1, 6.2, 6.3, 6.6_ + +- [ ] 8. Implement comment and rating system APIs + - Create comment CRUD operations with threading support and mentions + - Implement like/dislike functionality for media with anonymous support + - Add comment moderation and reporting features + - Create media action tracking (views, likes, reports) + - Implement rating system with category-based ratings + - _Requirements: 6.3, 6.4, 6.5_ + +## Phase 3: Media Processing System + +- [ ] 9. Implement background job queue system + - Create job queue using tokio tasks with Redis persistence (replacing Celery) + - Implement job scheduling with priority and retry logic + - Add job progress tracking and status updates + - Create worker pool management for concurrent processing + - Implement job types: encode_media, produce_sprite, create_hls, whisper_transcribe + - _Requirements: 2.5, 2.6, 1.2, 1.3_ + +- [ ] 10. Implement FFmpeg integration for media processing + - Create async FFmpeg command execution wrapper + - Implement video transcoding with multiple profiles (144p-1080p, h264/h265/vp9) + - Add thumbnail and poster generation for videos with time selection + - Create sprite generation for video player scrubbing + - Implement video chunking for files over CHUNKIZE_VIDEO_DURATION + - Add audio waveform generation for audio files + - _Requirements: 1.2, 1.3, 1.4, 2.6_ + +- [ ] 11. Implement media file management system + - Create chunked file upload handling with resumable uploads + - Implement file storage abstraction for local filesystem + - Add file serving with proper caching headers and range requests + - Create file cleanup and management utilities + - Implement file type validation and security checks + - Add MD5 checksum calculation and duplicate detection + - _Requirements: 1.1, 1.4, 2.6, 7.5_ + +- [ ] 12. Implement encoding and transcoding workflows + - Create encoding profile management system matching Django EncodeProfile + - Implement video chunking for large files (CHUNKIZE_VIDEO_DURATION) + - Add encoding status tracking and progress reporting + - Create HLS playlist generation and management with Bento4 integration + - Implement encoding concatenation for chunked videos + - Add Whisper integration for automatic transcription + - _Requirements: 1.2, 1.3, 7.2, 7.4_ + +## Phase 4: API Documentation and Testing + +- [ ] 13. Generate OpenAPI specification and documentation + - Set up automatic OpenAPI 3.0 spec generation from code + - Create Swagger UI and ReDoc interfaces + - Add comprehensive API documentation with examples + - Implement API versioning strategy + - _Requirements: 4.1, 4.2, 4.6_ + +- [ ] 14. Implement comprehensive backend testing + - Create unit tests for all service functions and repositories + - Implement integration tests for API endpoints + - Add database testing with test containers + - Create performance benchmarks for critical paths + - _Requirements: 9.1, 9.2, 9.3_ + +## Phase 5: Frontend Foundation + +- [ ] 15. Set up TypeScript React project structure + - Initialize Vite project with TypeScript and React 18 + - Configure ESLint, Prettier, and TypeScript strict mode + - Set up development environment with hot module replacement + - Create project structure with components, hooks, and utilities + - _Requirements: 3.1, 3.2, 3.5, 9.4_ + +- [ ] 16. Implement state management with Zustand + - Create store structure for media, user, and application state + - Implement type-safe state management patterns + - Add persistence layer for user preferences + - Create state synchronization with API + - _Requirements: 3.3, 3.4_ + +- [ ] 17. Set up API client with type generation + - Create Axios-based HTTP client with interceptors + - Generate TypeScript types from OpenAPI specification + - Implement request/response transformation + - Add error handling and retry logic + - _Requirements: 3.4, 4.1, 4.4_ + +- [ ] 18. Implement authentication and routing + - Create authentication context and hooks + - Implement protected routes with role-based access + - Add JWT token management and refresh logic + - Create login, registration, and profile components + - _Requirements: 3.1, 5.1, 5.2, 5.5_ + +## Phase 6: Core Frontend Components + +- [ ] 19. Implement media player and viewer components + - Create video player component with Video.js integration + - Implement audio player with waveform visualization + - Add image viewer with zoom and navigation + - Create PDF viewer with page navigation + - _Requirements: 1.5, 3.1, 6.1_ + +- [ ] 20. Implement media upload and management interface + - Create drag-and-drop file upload component + - Implement chunked upload with progress tracking + - Add media metadata editing forms + - Create media library and management interface + - _Requirements: 1.1, 1.4, 3.1, 7.5_ + +- [ ] 21. Implement media listing and search interface + - Create responsive media grid and list views + - Implement infinite scroll with virtualization + - Add advanced search with filters and facets + - Create category and tag browsing interface + - _Requirements: 6.5, 6.1, 6.2, 3.6_ + +- [ ] 22. Implement playlist and collection management + - Create playlist creation and editing interface + - Implement drag-and-drop media organization + - Add playlist sharing and collaboration features + - Create playlist player with queue management + - _Requirements: 6.1, 6.2, 6.6_ + +## Phase 7: Advanced Features + +- [ ] 23. Implement comment and social features + - Create comment thread display with nested replies + - Implement real-time comment updates + - Add mention system with user autocomplete + - Create like/dislike and reporting interface + - _Requirements: 6.3, 6.4, 6.5_ + +- [ ] 24. Implement admin and management interfaces + - Create admin dashboard with system statistics + - Implement user management with role assignment + - Add content moderation and review interface + - Create system configuration and settings panels + - _Requirements: 7.1, 7.3, 7.4, 5.2_ + +- [ ] 25. Implement responsive design and theming + - Create responsive layout components for all screen sizes + - Implement light/dark theme switching + - Add accessibility features (ARIA labels, keyboard navigation) + - Create mobile-optimized touch interfaces + - _Requirements: 3.6, 7.1_ + +## Phase 8: Testing and Quality Assurance + +- [ ] 26. Implement comprehensive frontend testing + - Create unit tests for all React components + - Implement integration tests for user workflows + - Add end-to-end tests with Playwright + - Create visual regression testing setup + - _Requirements: 9.2, 9.3_ + +- [ ] 27. Implement performance optimization + - Add code splitting and lazy loading for routes + - Implement image optimization and lazy loading + - Create service worker for offline functionality + - Add performance monitoring and analytics + - _Requirements: 3.5, 9.3_ + +## Phase 9: Migration and Deployment + +- [ ] 28. Create data migration tools and scripts + - Implement PostgreSQL data migration from Django schema + - Create media file migration and validation tools + - Add user account and permission migration + - Create rollback and recovery procedures + - _Requirements: 8.2, 10.2, 10.3_ + +- [ ] 29. Set up deployment and infrastructure + - Create Docker containers for Rust backend and React frontend + - Implement CI/CD pipeline with automated testing + - Set up production environment configuration + - Create monitoring and logging infrastructure + - _Requirements: 8.1, 8.4, 8.5, 8.6_ + +- [ ] 30. Implement production readiness features + - Add comprehensive error handling and logging + - Implement rate limiting and security headers + - Create backup and disaster recovery procedures + - Add performance monitoring and alerting + - _Requirements: 8.1, 8.3, 8.4, 9.6_ + +## Phase 10: Final Integration and Testing + +- [ ] 31. Perform end-to-end system integration testing + - Test complete user workflows from registration to media consumption + - Validate all API endpoints with frontend integration + - Perform load testing with realistic user scenarios + - Test migration procedures with production-like data + - _Requirements: 9.3, 10.1, 10.4_ + +- [ ] 32. Create documentation and training materials + - Write deployment and configuration documentation + - Create API documentation with usage examples + - Develop user guides for new interface features + - Create troubleshooting and maintenance guides + - _Requirements: 10.5, 10.6_ + +- [ ] 33. Perform final validation and go-live preparation + - Conduct security audit and penetration testing + - Validate performance benchmarks against requirements + - Create go-live checklist and rollback procedures + - Perform final user acceptance testing + - _Requirements: 10.4, 10.5, 10.6_ diff --git a/gradle-plugin/build.gradle.kts b/gradle-plugin/build.gradle.kts index ac40ea2b4..3700efd69 100644 --- a/gradle-plugin/build.gradle.kts +++ b/gradle-plugin/build.gradle.kts @@ -7,9 +7,9 @@ plugins { description = """ -Custom Gradle plugin for Compose Server development workflow automation. -Provides project configuration, build conventions, and Spring Boot integration for development efficiency. -""" + Custom Gradle plugin for Compose Server development workflow automation. + Provides project configuration, build conventions, and Spring Boot integration for development efficiency. + """ .trimIndent() dependencies { diff --git a/gradle-plugin/src/test/kotlin/io/github/truenine/composeserver/gradleplugin/dotenv/DotenvIntegrationTest.kt b/gradle-plugin/src/test/kotlin/io/github/truenine/composeserver/gradleplugin/dotenv/DotenvIntegrationTest.kt index b4cd0f3ba..8f56f3ed2 100644 --- a/gradle-plugin/src/test/kotlin/io/github/truenine/composeserver/gradleplugin/dotenv/DotenvIntegrationTest.kt +++ b/gradle-plugin/src/test/kotlin/io/github/truenine/composeserver/gradleplugin/dotenv/DotenvIntegrationTest.kt @@ -37,16 +37,16 @@ class DotenvIntegrationTest { val envFile = File(tempDir, ".env") envFile.writeText( """ - # Database configuration - DB_HOST=localhost - DB_PORT=5432 - DB_NAME="myapp_db" - API_KEY='secret-key-123' - - # Application settings - APP_ENV=development - DEBUG=true - """ + # Database configuration + DB_HOST=localhost + DB_PORT=5432 + DB_NAME="myapp_db" + API_KEY='secret-key-123' + + # Application settings + APP_ENV=development + DEBUG=true + """ .trimIndent() ) @@ -108,9 +108,9 @@ class DotenvIntegrationTest { val envFile = File(configDir, ".env.local") envFile.writeText( """ - RELATIVE_PATH_TEST=success - CONFIG_DIR_VAR=config_value - """ + RELATIVE_PATH_TEST=success + CONFIG_DIR_VAR=config_value + """ .trimIndent() ) @@ -138,12 +138,12 @@ class DotenvIntegrationTest { val envFile = File(tempDir, ".env") envFile.writeText( """ - APP_NAME=myapp - APP_VERSION=1.0.0 - DB_HOST=localhost - SECRET_KEY=secret - OTHER_VAR=other - """ + APP_NAME=myapp + APP_VERSION=1.0.0 + DB_HOST=localhost + SECRET_KEY=secret + OTHER_VAR=other + """ .trimIndent() ) @@ -197,9 +197,9 @@ class DotenvIntegrationTest { envFile.deleteOnExit() envFile.writeText( """ - ABSOLUTE_PATH_TEST=success - TEMP_FILE_VAR=temp_value - """ + ABSOLUTE_PATH_TEST=success + TEMP_FILE_VAR=temp_value + """ .trimIndent() ) @@ -227,8 +227,8 @@ class DotenvIntegrationTest { val envFile = File(tempDir, ".env") envFile.writeText( """ - SHOULD_NOT_LOAD=value - """ + SHOULD_NOT_LOAD=value + """ .trimIndent() ) diff --git a/gradle-plugin/src/test/kotlin/io/github/truenine/composeserver/gradleplugin/dotenv/DotenvLoaderTest.kt b/gradle-plugin/src/test/kotlin/io/github/truenine/composeserver/gradleplugin/dotenv/DotenvLoaderTest.kt index d1792dfa8..7e21c47b6 100644 --- a/gradle-plugin/src/test/kotlin/io/github/truenine/composeserver/gradleplugin/dotenv/DotenvLoaderTest.kt +++ b/gradle-plugin/src/test/kotlin/io/github/truenine/composeserver/gradleplugin/dotenv/DotenvLoaderTest.kt @@ -55,10 +55,10 @@ class DotenvLoaderTest { val envFile = createTempEnvFile( """ - KEY1=value1 - KEY2=value2 - KEY3=value3 - """ + KEY1=value1 + KEY2=value2 + KEY3=value3 + """ .trimIndent() ) @@ -79,11 +79,11 @@ class DotenvLoaderTest { val envFile = createTempEnvFile( """ - SINGLE_QUOTED='single value' - DOUBLE_QUOTED="double value" - ESCAPED_QUOTES="value with \"quotes\"" - SPECIAL_CHARS="line1\nline2\ttab" - """ + SINGLE_QUOTED='single value' + DOUBLE_QUOTED="double value" + ESCAPED_QUOTES="value with \"quotes\"" + SPECIAL_CHARS="line1\nline2\ttab" + """ .trimIndent() ) @@ -104,14 +104,14 @@ class DotenvLoaderTest { val envFile = createTempEnvFile( """ - # This is a comment - KEY1=value1 - - # Another comment - KEY2=value2 - - KEY3=value3 - """ + # This is a comment + KEY1=value1 + + # Another comment + KEY2=value2 + + KEY3=value3 + """ .trimIndent() ) @@ -132,11 +132,11 @@ class DotenvLoaderTest { val envFile = createTempEnvFile( """ - APP_KEY1=value1 - APP_KEY2=value2 - OTHER_KEY=value3 - KEY4=value4 - """ + APP_KEY1=value1 + APP_KEY2=value2 + OTHER_KEY=value3 + KEY4=value4 + """ .trimIndent() ) @@ -159,11 +159,11 @@ class DotenvLoaderTest { val envFile = createTempEnvFile( """ - KEY1=value1 - SECRET_KEY=secret - KEY2=value2 - PASSWORD=password - """ + KEY1=value1 + SECRET_KEY=secret + KEY2=value2 + PASSWORD=password + """ .trimIndent() ) @@ -186,11 +186,11 @@ class DotenvLoaderTest { val envFile = createTempEnvFile( """ - KEY1=value1 - KEY2=value2 - KEY3=value3 - KEY4=value4 - """ + KEY1=value1 + KEY2=value2 + KEY3=value3 + KEY4=value4 + """ .trimIndent() ) @@ -213,11 +213,11 @@ class DotenvLoaderTest { val envFile = createTempEnvFile( """ - KEY1=value1 - EMPTY_KEY= - KEY2=value2 - BLANK_KEY="" - """ + KEY1=value1 + EMPTY_KEY= + KEY2=value2 + BLANK_KEY="" + """ .trimIndent() ) @@ -240,9 +240,9 @@ class DotenvLoaderTest { val envFile = createTempEnvFile( """ - TEST_VAR=test_value - DB_HOST=localhost - """ + TEST_VAR=test_value + DB_HOST=localhost + """ .trimIndent() ) @@ -264,9 +264,9 @@ class DotenvLoaderTest { val envFile = createTempEnvFile( """ - SPRING_PROFILE=dev - SERVER_PORT=8080 - """ + SPRING_PROFILE=dev + SERVER_PORT=8080 + """ .trimIndent() ) @@ -288,10 +288,10 @@ class DotenvLoaderTest { val envFile = createTempEnvFile( """ - CUSTOM_OPTS=-Xmx1g - APP_ENV=production - DATABASE_URL=jdbc:postgresql://localhost:5432/mydb - """ + CUSTOM_OPTS=-Xmx1g + APP_ENV=production + DATABASE_URL=jdbc:postgresql://localhost:5432/mydb + """ .trimIndent() ) @@ -314,9 +314,9 @@ class DotenvLoaderTest { val envFile = createTempEnvFile( """ - KOTLIN_ENV=development - DEBUG_MODE=true - """ + KOTLIN_ENV=development + DEBUG_MODE=true + """ .trimIndent() ) diff --git a/gradle/CLAUDE.md b/gradle/CLAUDE.md index 2c9738560..ffe2b229d 100644 --- a/gradle/CLAUDE.md +++ b/gradle/CLAUDE.md @@ -2,10 +2,10 @@ - `project` Current project dependency version number - `java` Current project Java version number -- `gradle` Gradle version number +- `org-gradle` Gradle version number - `intellij-platform-*` IntelliJ plugin development version number -### Usage in `buildSrc` and `includeBuild` +### Usage in `buildSrc` or `includeBuild` Introduce `libs.versions.toml` as a dependency in the `settings.gradle.kts` of `buildSrc` or `build-logic` to achieve unified project-wide version management @@ -29,4 +29,4 @@ If you need to use it in plugins, define variables like this: ```kotlin val libs = the() -``` \ No newline at end of file +``` diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index 5dee51b55..f45f10349 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -4,9 +4,9 @@ cn-dev33-sa-token = "1.44.0" cn-hutool = "5.8.40" com-alibaba-cloud = "2023.0.3.3" com-baomidou-mybatis-plus = "3.5.14" -com-diffplug-spotless = "7.2.1" +com-diffplug-spotless = "8.0.0" com-fasterxml-jackson = "2.20.0" -com-flywaydb-flyway = "11.13.1" +com-flywaydb-flyway = "11.13.2" com-github-tschuchortdev-kotlin-compile-testing = "1.6.0" com-google-devtools-ksp = "2.2.20-2.0.3" com-mapstruct = "1.6.3" @@ -24,13 +24,13 @@ intellij-platform-plugin-java = "21" io-netty = "4.2.6.Final" java = "17" net-sf-sevenzipjbinding = "16.02-2.01" -nl-littlerobots-version-catalog-updat-gradle-plugin = "1.0.0" +nl-littlerobots-version-catalog-updat-gradle-plugin = "1.0.1" org-apache-commons-exec = "1.5.0" org-apache-groovy = "5.0.1" -org-apache-logging-log4j = "2.25.1" +org-apache-logging-log4j = "2.25.2" org-assertj = "4.0.0-M1" org-awaitility = "4.3.0" -org-babyfish-jimmer = "0.9.110" +org-babyfish-jimmer = "0.9.111" org-gradle = "9.1.0" org-hibernate-orm = "7.1.1.Final" org-jetbrains-dokka = "2.0.0" @@ -40,8 +40,8 @@ org-jetbrains-kotlinx-coroutines = "1.10.2" org-jetbrains-kotlinx-datetime = "0.7.1-0.6.x-compat" org-jetbrains-kotlinx-io = "0.8.0" org-jetbrains-kotlinx-serialization = "1.9.0" -org-junit-jupiter = "6.0.0-M2" -org-liquibase = "4.33.0" +org-junit-jupiter = "6.0.0" +org-liquibase = "5.0.0" org-slf4j = "2.1.0-alpha1" org-springframework-ai = "1.0.2" org-springframework-batch = "5.2.3" @@ -54,7 +54,7 @@ org-springframework-modulith = "2.0.0-M1" org-springframework-security = "6.5.5" org-testcontainers = "1.21.3" org-testng = "7.11.0" -project = "0.0.38" +project = "0.0.39" [libraries] ch-qos-logback-logback-classic = { module = "ch.qos.logback:logback-classic", version.ref = "ch-qos-logback" } @@ -102,7 +102,7 @@ com-google-code-gson-gson = "com.google.code.gson:gson:2.13.2" com-google-devtools-ksp-symbol-processing = { module = "com.google.devtools.ksp:symbol-processing", version.ref = "com-google-devtools-ksp" } com-google-devtools-ksp-symbol-processing-api = { module = "com.google.devtools.ksp:symbol-processing-api", version.ref = "com-google-devtools-ksp" } com-google-guava-guava-jre = "com.google.guava:guava:33.5.0-jre" -com-h2database-h2 = "com.h2database:h2:2.3.232" +com-h2database-h2 = "com.h2database:h2:2.4.240" com-hikvision-ga-artemis-http-client = "com.hikvision.ga:artemis-http-client:1.1.3" com-hikvision-ga-opensource = "com.hikvision.ga:opensource:0.0.3" com-huaweicloud-esdk-obs-java = "com.huaweicloud:esdk-obs-java:3.25.7" @@ -123,13 +123,13 @@ com-vanniktech-maven-publish-com-vanniktech-maven-publish-gradle-plugin = { modu com-volcengine-ve-tos-java-sdk = "com.volcengine:ve-tos-java-sdk:2.9.4" com-xuxueli-xxl-job-core = { module = "com.xuxueli:xxl-job-core", version.ref = "com-xuxueli-xxl-job" } com-yomahub-liteflow-spring-boot-starter = { module = "com.yomahub:liteflow-spring-boot-starter", version.ref = "com-yomahub-liteflow" } -dev-langchain4j-langchain4j = "dev.langchain4j:langchain4j:1.5.0" +dev-langchain4j-langchain4j = "dev.langchain4j:langchain4j:1.6.0" dev-langchain4j-langchain4j-bom = "dev.langchain4j:langchain4j-bom:1.2.0" dev-langchain4j-langchain4j-community-bom = { module = "dev.langchain4j:langchain4j-community-bom", version.ref = "dev-langchain4j-community" } dev-langchain4j-langchain4j-hugging-face = { module = "dev.langchain4j:langchain4j-hugging-face", version.ref = "dev-langchain4j-community" } dev-langchain4j-langchain4j-kotlin = { module = "dev.langchain4j:langchain4j-kotlin", version.ref = "dev-langchain4j-community" } dev-langchain4j-langchain4j-mcp = { module = "dev.langchain4j:langchain4j-mcp", version.ref = "dev-langchain4j-community" } -dev-langchain4j-langchain4j-ollama = "dev.langchain4j:langchain4j-ollama:1.5.0" +dev-langchain4j-langchain4j-ollama = "dev.langchain4j:langchain4j-ollama:1.6.0" dev-langchain4j-langchain4j-ollama-spring-boot-starter = { module = "dev.langchain4j:langchain4j-ollama-spring-boot-starter", version.ref = "dev-langchain4j-community" } dev-langchain4j-langchain4j-pgvector = { module = "dev.langchain4j:langchain4j-pgvector", version.ref = "dev-langchain4j-community" } dev-langchain4j-langchain4j-reactor = { module = "dev.langchain4j:langchain4j-reactor", version.ref = "dev-langchain4j-community" } @@ -174,7 +174,7 @@ io-github-truenine-composeserver-testtoolkit-shared = { module = "io.github.true io-github-truenine-composeserver-testtoolkit-springmvc = { module = "io.github.truenine:composeserver-testtoolkit-springmvc", version.ref = "project" } io-github-truenine-composeserver-testtoolkit-testcontainers = { module = "io.github.truenine:composeserver-testtoolkit-testcontainers", version.ref = "project" } io-jsonwebtoken-jjwt-api = "io.jsonwebtoken:jjwt-api:0.13.0" -io-minio-minio = "io.minio:minio:8.5.17" +io-minio-minio = "io.minio:minio:8.6.0" io-mockk-mockk = "io.mockk:mockk:1.14.5" io-netty-netty-handler = { module = "io.netty:netty-handler", version.ref = "io-netty" } io-projectreactor-kotlin-reactor-kotlin-extensions = "io.projectreactor.kotlin:reactor-kotlin-extensions:1.3.0-RC2" @@ -335,7 +335,7 @@ p6spy-p6spy = "p6spy:p6spy:3.9.1" [plugins] com-diffplug-spotless = { id = "com.diffplug.spotless", version.ref = "com-diffplug-spotless" } -com-github-ben-manes-versions = "com.github.ben-manes.versions:0.52.0" +com-github-ben-manes-versions = "com.github.ben-manes.versions:0.53.0" com-google-devtools-ksp = { id = "com.google.devtools.ksp", version.ref = "com-google-devtools-ksp" } com-vanniktech-maven-publish = { id = "com.vanniktech.maven.publish", version.ref = "com-vanniktech-maven-publish" } io-github-truenine-composeserver-gradle-plugin = { id = "io.github.truenine.composeserver.gradle-plugin", version.ref = "project" } diff --git a/ide/ide-idea-mcp/src/main/kotlin/io/github/truenine/composeserver/ide/ideamcp/McpDebugPanel.kt b/ide/ide-idea-mcp/src/main/kotlin/io/github/truenine/composeserver/ide/ideamcp/McpDebugPanel.kt index f907ef08b..fa60151ff 100644 --- a/ide/ide-idea-mcp/src/main/kotlin/io/github/truenine/composeserver/ide/ideamcp/McpDebugPanel.kt +++ b/ide/ide-idea-mcp/src/main/kotlin/io/github/truenine/composeserver/ide/ideamcp/McpDebugPanel.kt @@ -30,18 +30,18 @@ class McpDebugPanel(private val project: Project) : SimpleToolWindowPanel(true, isEditable = false text = """ - 日志系统已简化为控制台输出模式 - - 查看详细日志信息请： - 1. 打开 IDEA 的 Help -> Show Log in Files - 2. 或查看 IDEA 控制台输出 - 3. 日志级别可在 logback.xml 中配置 - - 当前配置： - - 插件包: io.github.truenine.composeserver.ide.ideamcp - - 日志级别: DEBUG - - 输出格式: HH:mm:ss.SSS [thread] LEVEL logger - message - """ + 日志系统已简化为控制台输出模式 + + 查看详细日志信息请： + 1. 打开 IDEA 的 Help -> Show Log in Files + 2. 或查看 IDEA 控制台输出 + 3. 日志级别可在 logback.xml 中配置 + + 当前配置： + - 插件包: io.github.truenine.composeserver.ide.ideamcp + - 日志级别: DEBUG + - 输出格式: HH:mm:ss.SSS [thread] LEVEL logger - message + """ .trimIndent() } diff --git a/ide/ide-idea-mcp/src/test/kotlin/io/github/truenine/composeserver/ide/ideamcp/services/ErrorCaptureFilterTest.kt b/ide/ide-idea-mcp/src/test/kotlin/io/github/truenine/composeserver/ide/ideamcp/services/ErrorCaptureFilterTest.kt index 69bb40b07..bf70b61e7 100644 --- a/ide/ide-idea-mcp/src/test/kotlin/io/github/truenine/composeserver/ide/ideamcp/services/ErrorCaptureFilterTest.kt +++ b/ide/ide-idea-mcp/src/test/kotlin/io/github/truenine/composeserver/ide/ideamcp/services/ErrorCaptureFilterTest.kt @@ -67,11 +67,11 @@ class ErrorCaptureFilterTest : BasePlatformTestCase() { myFixture.tempDirFixture.createFile( "TestClass.kt", """ - class TestClass { - // incomplete code for testing - fun testMethod( - } - """ + class TestClass { + // incomplete code for testing + fun testMethod( + } + """ .trimIndent(), ) @@ -99,13 +99,13 @@ class ErrorCaptureFilterTest : BasePlatformTestCase() { myFixture.tempDirFixture.createFile( "README.md", """ - # Test Document - - ```kotlin - // This code might have syntax errors - fun incomplete( - ``` - """ + # Test Document + + ```kotlin + // This code might have syntax errors + fun incomplete( + ``` + """ .trimIndent(), ) diff --git a/ide/ide-idea-mcp/src/test/kotlin/io/github/truenine/composeserver/ide/ideamcp/services/ErrorServiceEnhancedTest.kt b/ide/ide-idea-mcp/src/test/kotlin/io/github/truenine/composeserver/ide/ideamcp/services/ErrorServiceEnhancedTest.kt index 064f44cda..d5e6d22eb 100644 --- a/ide/ide-idea-mcp/src/test/kotlin/io/github/truenine/composeserver/ide/ideamcp/services/ErrorServiceEnhancedTest.kt +++ b/ide/ide-idea-mcp/src/test/kotlin/io/github/truenine/composeserver/ide/ideamcp/services/ErrorServiceEnhancedTest.kt @@ -18,17 +18,17 @@ class ErrorServiceEnhancedTest : BasePlatformTestCase() { // 创建一个包含未使用导入的测试文件 val testContent = """ - package com.test - - import java.util.List // 未使用的导入 - import java.util.Map // 未使用的导入 - - class TestClass { - fun doSomething() { - println("Hello") + package com.test + + import java.util.List // 未使用的导入 + import java.util.Map // 未使用的导入 + + class TestClass { + fun doSomething() { + println("Hello") + } } - } - """ + """ .trimIndent() val virtualFile = myFixture.configureByText("TestClass.kt", testContent).virtualFile @@ -58,14 +58,14 @@ class ErrorServiceEnhancedTest : BasePlatformTestCase() { // 创建一个包含语法错误的测试文件 val testContent = """ - package com.test - - class TestClass { - fun doSomething( { // 语法错误：缺少参数和右括号 - println("Hello") + package com.test + + class TestClass { + fun doSomething( { // 语法错误：缺少参数和右括号 + println("Hello") + } } - } - """ + """ .trimIndent() val virtualFile = myFixture.configureByText("ErrorClass.kt", testContent).virtualFile @@ -91,26 +91,26 @@ class ErrorServiceEnhancedTest : BasePlatformTestCase() { // 创建一个包含多种问题的测试文件 val testContent = """ - package com.test + package com.test - import java.util.List // 未使用 - import java.util.ArrayList + import java.util.List // 未使用 + import java.util.ArrayList - class TestClass { - private val unusedField = "never used" // 未使用的字段 + class TestClass { + private val unusedField = "never used" // 未使用的字段 - fun doSomething(): String { - val list = ArrayList() - list.add("test") - return list.toString() - val unreachableCode = "never reached" // 不可达代码 - } + fun doSomething(): String { + val list = ArrayList() + list.add("test") + return list.toString() + val unreachableCode = "never reached" // 不可达代码 + } - fun undefinedMethod() { - nonExistentFunction() // 未定义的函数 + fun undefinedMethod() { + nonExistentFunction() // 未定义的函数 + } } - } - """ + """ .trimIndent() val virtualFile = myFixture.configureByText("ComprehensiveTest.kt", testContent).virtualFile @@ -161,14 +161,14 @@ class ErrorServiceEnhancedTest : BasePlatformTestCase() { // 创建一个包含明显语法错误的文件 val testContent = """ - package com.test + package com.test - class TestClass { - fun brokenFunction( { // 明显的语法错误 - println("This should cause a syntax error") + class TestClass { + fun brokenFunction( { // 明显的语法错误 + println("This should cause a syntax error") + } } - } - """ + """ .trimIndent() val virtualFile = myFixture.configureByText("SyntaxErrorTest.kt", testContent).virtualFile diff --git a/ide/ide-idea-mcp/src/test/kotlin/io/github/truenine/composeserver/ide/ideamcp/services/ErrorServiceFunctionalTest.kt b/ide/ide-idea-mcp/src/test/kotlin/io/github/truenine/composeserver/ide/ideamcp/services/ErrorServiceFunctionalTest.kt index 8c06ca4d6..011c596b4 100644 --- a/ide/ide-idea-mcp/src/test/kotlin/io/github/truenine/composeserver/ide/ideamcp/services/ErrorServiceFunctionalTest.kt +++ b/ide/ide-idea-mcp/src/test/kotlin/io/github/truenine/composeserver/ide/ideamcp/services/ErrorServiceFunctionalTest.kt @@ -22,14 +22,14 @@ class ErrorServiceFunctionalTest : BasePlatformTestCase() { myFixture.configureByText( "TestClass.kt", """ - package test - - class TestClass { - fun sayHello(): String { - return "Hello, World!" - } - } - """ + package test + + class TestClass { + fun sayHello(): String { + return "Hello, World!" + } + } + """ .trimIndent(), ) diff --git a/ide/ide-idea-mcp/src/test/kotlin/io/github/truenine/composeserver/ide/ideamcp/services/ErrorServiceIntegrationTest.kt b/ide/ide-idea-mcp/src/test/kotlin/io/github/truenine/composeserver/ide/ideamcp/services/ErrorServiceIntegrationTest.kt index c1091c41c..dad036109 100644 --- a/ide/ide-idea-mcp/src/test/kotlin/io/github/truenine/composeserver/ide/ideamcp/services/ErrorServiceIntegrationTest.kt +++ b/ide/ide-idea-mcp/src/test/kotlin/io/github/truenine/composeserver/ide/ideamcp/services/ErrorServiceIntegrationTest.kt @@ -26,15 +26,15 @@ class ErrorServiceIntegrationTest : BasePlatformTestCase() { myFixture.configureByText( "TestFile.kt", """ - package test - - class TestClass { - fun testMethod() { - // 这里有语法错误 - 缺少右括号 - val result = someFunction( - } - } - """ + package test + + class TestClass { + fun testMethod() { + // 这里有语法错误 - 缺少右括号 + val result = someFunction( + } + } + """ .trimIndent(), ) @@ -58,14 +58,14 @@ class ErrorServiceIntegrationTest : BasePlatformTestCase() { myFixture.configureByText( "ValidFile.kt", """ - package test - - class ValidClass { - fun validMethod(): String { - return "Hello, World!" - } - } - """ + package test + + class ValidClass { + fun validMethod(): String { + return "Hello, World!" + } + } + """ .trimIndent(), ) diff --git a/ksp/ksp-meta/build.gradle.kts b/ksp/ksp-meta/build.gradle.kts index b28c8545d..508f5b85b 100644 --- a/ksp/ksp-meta/build.gradle.kts +++ b/ksp/ksp-meta/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -Metadata and annotation processing utilities providing compile-time code generation capabilities. -Contains custom annotations and processors for enhancing development productivity and code quality. -""" + Metadata and annotation processing utilities providing compile-time code generation capabilities. + Contains custom annotations and processors for enhancing development productivity and code quality. + """ .trimIndent() dependencies { diff --git a/ksp/ksp-plugin/build.gradle.kts b/ksp/ksp-plugin/build.gradle.kts index 0ac00ea4f..a3da33e93 100644 --- a/ksp/ksp-plugin/build.gradle.kts +++ b/ksp/ksp-plugin/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -Kotlin Symbol Processing (KSP) plugin for compile-time code generation and analysis. -Provides annotation processing capabilities with KotlinPoet integration for generating type-safe code. -""" + Kotlin Symbol Processing (KSP) plugin for compile-time code generation and analysis. + Provides annotation processing capabilities with KotlinPoet integration for generating type-safe code. + """ .trimIndent() dependencies { diff --git a/ksp/ksp-plugin/src/main/kotlin/io/github/truenine/composeserver/ksp/plugin/visitor/JpaNameClassVisitor.kt b/ksp/ksp-plugin/src/main/kotlin/io/github/truenine/composeserver/ksp/plugin/visitor/JpaNameClassVisitor.kt index 63de0c5e6..f557095c7 100644 --- a/ksp/ksp-plugin/src/main/kotlin/io/github/truenine/composeserver/ksp/plugin/visitor/JpaNameClassVisitor.kt +++ b/ksp/ksp-plugin/src/main/kotlin/io/github/truenine/composeserver/ksp/plugin/visitor/JpaNameClassVisitor.kt @@ -383,11 +383,11 @@ class JpaNameClassVisitor(private val listenerSpec: AnnotationSpec?) : KSTopDown .addParameter("other", Any::class.asTypeName().copy(nullable = true)) .addStatement( """ - return if (null == other) false - else if (this === other) true - else if (%T.getClass(this) != %T.getClass(other)) false - else if (!isNew && id == (other as %T).id) true - else false""" + return if (null == other) false + else if (this === other) true + else if (%T.getClass(this) != %T.getClass(other)) false + else if (!isNew && id == (other as %T).id) true + else false""" .trimIndent(), Libs.org.hibernate.Hibernate.toClassName(), Libs.org.hibernate.Hibernate.toClassName(), diff --git a/ksp/ksp-shared/build.gradle.kts b/ksp/ksp-shared/build.gradle.kts index f7965f2fb..329f4a961 100644 --- a/ksp/ksp-shared/build.gradle.kts +++ b/ksp/ksp-shared/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -Shared utilities and base classes for Kotlin Symbol Processing (KSP) development. -Provides common KSP APIs, KotlinPoet utilities, and shared metadata for code generation tasks. -""" + Shared utilities and base classes for Kotlin Symbol Processing (KSP) development. + Provides common KSP APIs, KotlinPoet utilities, and shared metadata for code generation tasks. + """ .trimIndent() dependencies { diff --git a/oss/oss-aliyun-oss/build.gradle.kts b/oss/oss-aliyun-oss/build.gradle.kts index 7bd8e49e8..c7fb7316c 100644 --- a/oss/oss-aliyun-oss/build.gradle.kts +++ b/oss/oss-aliyun-oss/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -Alibaba Cloud OSS (Object Storage Service) integration for scalable cloud storage operations. -Provides seamless integration with Aliyun OSS including authentication, bucket operations, and file management. -""" + Alibaba Cloud OSS (Object Storage Service) integration for scalable cloud storage operations. + Provides seamless integration with Aliyun OSS including authentication, bucket operations, and file management. + """ .trimIndent() dependencies { diff --git a/oss/oss-huawei-obs/build.gradle.kts b/oss/oss-huawei-obs/build.gradle.kts index 93f01d164..e2c0e4c8d 100644 --- a/oss/oss-huawei-obs/build.gradle.kts +++ b/oss/oss-huawei-obs/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -Huawei Cloud OBS (Object Storage Service) integration for enterprise-grade cloud storage. -Provides comprehensive OBS operations including object management, lifecycle policies, and security configurations. -""" + Huawei Cloud OBS (Object Storage Service) integration for enterprise-grade cloud storage. + Provides comprehensive OBS operations including object management, lifecycle policies, and security configurations. + """ .trimIndent() dependencies { diff --git a/oss/oss-minio/build.gradle.kts b/oss/oss-minio/build.gradle.kts index 4839caf47..b98d14db8 100644 --- a/oss/oss-minio/build.gradle.kts +++ b/oss/oss-minio/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -MinIO object storage integration providing S3-compatible storage operations. -Includes bucket management, file operations, and comprehensive testing with TestContainers support. -""" + MinIO object storage integration providing S3-compatible storage operations. + Includes bucket management, file operations, and comprehensive testing with TestContainers support. + """ .trimIndent() dependencies { diff --git a/oss/oss-minio/src/main/kotlin/io/github/truenine/composeserver/oss/minio/MinioObjectStorageService.kt b/oss/oss-minio/src/main/kotlin/io/github/truenine/composeserver/oss/minio/MinioObjectStorageService.kt index ebe566797..1d8b30cec 100644 --- a/oss/oss-minio/src/main/kotlin/io/github/truenine/composeserver/oss/minio/MinioObjectStorageService.kt +++ b/oss/oss-minio/src/main/kotlin/io/github/truenine/composeserver/oss/minio/MinioObjectStorageService.kt @@ -342,12 +342,12 @@ class MinioObjectStorageService(private val minioClient: MinioClient, override v private fun createPrivatePolicy(bucketName: String): String { return """ - { - "Version": "2012-10-17", - "Statement": [] - } - """ - .trimIndent() + { + "Version": "2012-10-17", + "Statement": [] + } + """ + .trimIndent() } override suspend fun objectExists(bucketName: String, objectName: String): Result = diff --git a/oss/oss-shared/build.gradle.kts b/oss/oss-shared/build.gradle.kts index 0f2710005..4c0b941e2 100644 --- a/oss/oss-shared/build.gradle.kts +++ b/oss/oss-shared/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -Shared abstractions and interfaces for object storage operations across different cloud providers. -Provides unified API for file upload, download, and management operations regardless of the underlying storage service. -""" + Shared abstractions and interfaces for object storage operations across different cloud providers. + Provides unified API for file upload, download, and management operations regardless of the underlying storage service. + """ .trimIndent() dependencies { diff --git a/oss/oss-volcengine-tos/build.gradle.kts b/oss/oss-volcengine-tos/build.gradle.kts index 8fcaadef9..5412e2c16 100644 --- a/oss/oss-volcengine-tos/build.gradle.kts +++ b/oss/oss-volcengine-tos/build.gradle.kts @@ -6,9 +6,9 @@ plugins { description = """ -Volcengine TOS (Tinder Object Storage) integration for enterprise-grade cloud storage. -Provides comprehensive TOS operations including object management, lifecycle policies, and security configurations. -""" + Volcengine TOS (Tinder Object Storage) integration for enterprise-grade cloud storage. + Provides comprehensive TOS operations including object management, lifecycle policies, and security configurations. + """ .trimIndent() dependencies { diff --git a/oss/oss-volcengine-tos/src/main/kotlin/io/github/truenine/composeserver/oss/volcengine/autoconfig/VolcengineTosAutoConfiguration.kt b/oss/oss-volcengine-tos/src/main/kotlin/io/github/truenine/composeserver/oss/volcengine/autoconfig/VolcengineTosAutoConfiguration.kt index 3013110b3..8d4cb37e2 100644 --- a/oss/oss-volcengine-tos/src/main/kotlin/io/github/truenine/composeserver/oss/volcengine/autoconfig/VolcengineTosAutoConfiguration.kt +++ b/oss/oss-volcengine-tos/src/main/kotlin/io/github/truenine/composeserver/oss/volcengine/autoconfig/VolcengineTosAutoConfiguration.kt @@ -93,18 +93,18 @@ class VolcengineTosAutoConfiguration { // Use ListBucketsV2Input for connection test val listBucketsInput = com.volcengine.tos.model.bucket.ListBucketsV2Input() client.listBuckets(listBucketsInput) - log.info("✅ Volcengine TOS client connected successfully") + log.info("Volcengine TOS client connected successfully") } catch (e: Exception) { - log.error("❌ Volcengine TOS client connection failed", e) + log.error("Volcengine TOS client connection failed", e) throw e } } else { - log.info("✅ Volcengine TOS client initialized (connection test skipped in test environment)") + log.info("Volcengine TOS client initialized (connection test skipped in test environment)") } client } catch (e: Exception) { - log.error("❌ Failed to initialize Volcengine TOS client: ${e.message}", e) + log.error("Failed to initialize Volcengine TOS client: ${e.message}", e) throw IllegalStateException("Failed to create TOS client", e) } } @@ -116,7 +116,7 @@ class VolcengineTosAutoConfiguration { val exposedBaseUrl = resolveExposedBaseUrl(tosProperties, ossProperties) - log.info("✅ Volcengine TOS IObjectStorageService created with exposed URL: $exposedBaseUrl") + log.info("Volcengine TOS IObjectStorageService created with exposed URL: $exposedBaseUrl") return VolcengineTosObjectStorageService(tosClient, exposedBaseUrl) } @@ -167,29 +167,29 @@ class VolcengineTosAutoConfiguration { /** Log configuration summary without sensitive information */ private fun logConfigurationSummary(tosProperties: VolcengineTosProperties, endpoint: String, region: String, hasSts: Boolean) { - log.info("📋 TOS Client Configuration Summary:") - log.info(" 🌐 Endpoint: $endpoint") - log.info(" 📍 Region: $region") - log.info(" 🔐 Authentication: ${if (hasSts) "STS (temporary credentials)" else "Static credentials"}") - log.info(" 🔒 SSL Enabled: ${tosProperties.enableSsl}") - log.info(" 🔗 Max Connections: ${tosProperties.maxConnections}") - log.info(" ⏱️ Connect Timeout: ${tosProperties.connectTimeoutMills}ms") - log.info(" 📖 Read Timeout: ${tosProperties.readTimeoutMills}ms") - log.info(" 📝 Write Timeout: ${tosProperties.writeTimeoutMills}ms") - log.info(" 🔄 Max Retries: ${tosProperties.maxRetryCount}") - log.info(" 🌐 DNS Cache: ${if (tosProperties.dnsCacheTimeMinutes > 0) "${tosProperties.dnsCacheTimeMinutes}min" else "disabled"}") - log.info(" ✅ CRC Check: ${tosProperties.enableCrc}") - log.info(" 🔍 SSL Verify: ${tosProperties.enableVerifySSL}") - log.info(" 📄 Auto Content-Type: ${tosProperties.clientAutoRecognizeContentType}") - log.info(" 📊 Logging: ${tosProperties.enableLogging}") + log.info("TOS Client Configuration Summary:") + log.info(" Endpoint: $endpoint") + log.info(" Region: $region") + log.info(" Authentication: ${if (hasSts) "STS (temporary credentials)" else "Static credentials"}") + log.info(" SSL Enabled: ${tosProperties.enableSsl}") + log.info(" Max Connections: ${tosProperties.maxConnections}") + log.info(" Connect Timeout: ${tosProperties.connectTimeoutMills}ms") + log.info(" Read Timeout: ${tosProperties.readTimeoutMills}ms") + log.info(" Write Timeout: ${tosProperties.writeTimeoutMills}ms") + log.info(" Max Retries: ${tosProperties.maxRetryCount}") + log.info(" DNS Cache: ${if (tosProperties.dnsCacheTimeMinutes > 0) "${tosProperties.dnsCacheTimeMinutes}min" else "disabled"}") + log.info(" CRC Check: ${tosProperties.enableCrc}") + log.info(" SSL Verify: ${tosProperties.enableVerifySSL}") + log.info(" Auto Content-Type: ${tosProperties.clientAutoRecognizeContentType}") + log.info(" Logging: ${tosProperties.enableLogging}") if (tosProperties.hasProxyConfiguration()) { - log.info(" 🌐 Proxy: ${tosProperties.proxyHost}:${tosProperties.proxyPort}") - log.info(" 🔐 Proxy Auth: ${tosProperties.hasProxyAuthentication()}") + log.info(" Proxy: ${tosProperties.proxyHost}:${tosProperties.proxyPort}") + log.info(" Proxy Auth: ${tosProperties.hasProxyAuthentication()}") } if (tosProperties.isCustomDomain) { - log.info(" 🏷️ Custom Domain: ${tosProperties.customDomain}") + log.info(" Custom Domain: ${tosProperties.customDomain}") } } @@ -210,17 +210,17 @@ class VolcengineTosAutoConfiguration { // Configure proxy if specified if (tosProperties.hasProxyConfiguration()) { - log.info("🌐 Configuring proxy: ${tosProperties.proxyHost}:${tosProperties.proxyPort}") + log.info("Configuring proxy: ${tosProperties.proxyHost}:${tosProperties.proxyPort}") builder.proxyHost(tosProperties.proxyHost).proxyPort(tosProperties.proxyPort) if (tosProperties.hasProxyAuthentication()) { - log.debug("🔐 Configuring proxy authentication") + log.debug("Configuring proxy authentication") builder.proxyUserName(tosProperties.proxyUserName).proxyPassword(tosProperties.proxyPassword) } } val config = builder.build() - log.debug("✅ Transport configuration built successfully") + log.debug("Transport configuration built successfully") return config } @@ -234,7 +234,7 @@ class VolcengineTosAutoConfiguration { transportConfig: TransportConfig, ): TOSClientConfiguration { log.debug("Building client configuration...") - log.debug("🔐 Using static credentials") + log.debug("Using static credentials") val builder = TOSClientConfiguration.builder() @@ -265,7 +265,7 @@ class VolcengineTosAutoConfiguration { } val config = builder.build() - log.debug("✅ Client configuration built successfully") + log.debug("Client configuration built successfully") return config } diff --git a/oss/oss-volcengine-tos/src/test/kotlin/io/github/truenine/composeserver/oss/volcengine/VolcengineTosPropertiesTest.kt b/oss/oss-volcengine-tos/src/test/kotlin/io/github/truenine/composeserver/oss/volcengine/VolcengineTosPropertiesTest.kt index 603e4eeb7..461a090f6 100644 --- a/oss/oss-volcengine-tos/src/test/kotlin/io/github/truenine/composeserver/oss/volcengine/VolcengineTosPropertiesTest.kt +++ b/oss/oss-volcengine-tos/src/test/kotlin/io/github/truenine/composeserver/oss/volcengine/VolcengineTosPropertiesTest.kt @@ -24,9 +24,9 @@ class VolcengineTosPropertiesTest { assertNull(properties.accessKey) assertNull(properties.secretKey) assertNull(properties.sessionToken) - assertNull(properties.endpoint) - assertNull(properties.region) - assertNull(properties.exposedBaseUrl) + assertEquals("https://tos-cn-beijing.volces.com", properties.endpoint) + assertEquals("cn-beijing", properties.region) + assertEquals("https://tos-cn-beijing.volces.com", properties.exposedBaseUrl) // Network settings assertTrue(properties.enableSsl) diff --git a/oss/oss-volcengine-tos/src/test/kotlin/io/github/truenine/composeserver/oss/volcengine/autoconfig/VolcengineTosAutoConfigurationTest.kt b/oss/oss-volcengine-tos/src/test/kotlin/io/github/truenine/composeserver/oss/volcengine/autoconfig/VolcengineTosAutoConfigurationTest.kt index 2c89d32ae..97374d8d8 100644 --- a/oss/oss-volcengine-tos/src/test/kotlin/io/github/truenine/composeserver/oss/volcengine/autoconfig/VolcengineTosAutoConfigurationTest.kt +++ b/oss/oss-volcengine-tos/src/test/kotlin/io/github/truenine/composeserver/oss/volcengine/autoconfig/VolcengineTosAutoConfigurationTest.kt @@ -193,9 +193,9 @@ class VolcengineTosAutoConfigurationTest { "compose.oss.volcengine-tos.secret-key=testsecret", ) .run { context -> - // 验证配置属性中region为null + // 验证配置属性中region为默认值 val tosProperties = context.getBean(VolcengineTosProperties::class.java) - kotlin.test.assertNull(tosProperties.region) + kotlin.test.assertEquals("cn-beijing", tosProperties.region) val ossProperties = context.getBean(OssProperties::class.java) kotlin.test.assertNull(ossProperties.region) @@ -242,8 +242,8 @@ class VolcengineTosAutoConfigurationTest { val tosProperties = context.getBean(VolcengineTosProperties::class.java) val ossProperties = context.getBean(OssProperties::class.java) - // 验证 TOS 没有专用区域配置 - kotlin.test.assertNull(tosProperties.region) + // 验证 TOS 使用默认区域配置 + kotlin.test.assertEquals("cn-beijing", tosProperties.region) // 验证通用配置存在 kotlin.test.assertEquals("cn-hongkong", ossProperties.region) @@ -289,11 +289,11 @@ class VolcengineTosAutoConfigurationTest { "spring.profiles.active=test", // 启用测试环境以跳过连接测试 ) .run { context -> - // 验证警告日志被输出 - kotlin.test.assertTrue( + // 验证没有警告日志输出 + kotlin.test.assertFalse( output.out.contains("No region specified, using default region: cn-beijing") || output.err.contains("No region specified, using default region: cn-beijing"), - "Expected warning log about default region not found in output: ${output.all}", + "Warning log should not be present in output: ${output.all}", ) // 验证 TOS 客户端被创建 diff --git a/pay/pay-shared/build.gradle.kts b/pay/pay-shared/build.gradle.kts index fc9d93a46..2f728e0c8 100644 --- a/pay/pay-shared/build.gradle.kts +++ b/pay/pay-shared/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -Shared payment processing abstractions and common models. -Provides unified interfaces, enums, and data models for payment operations across different payment providers. -""" + Shared payment processing abstractions and common models. + Provides unified interfaces, enums, and data models for payment operations across different payment providers. + """ .trimIndent() dependencies { diff --git a/pay/pay-wechat/build.gradle.kts b/pay/pay-wechat/build.gradle.kts index f8134438c..3e9d20ad3 100644 --- a/pay/pay-wechat/build.gradle.kts +++ b/pay/pay-wechat/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -WeChat Pay integration implementation. -Provides WeChat Pay V3 API integration, payment processing, and automated configuration for WeChat payment services. -""" + WeChat Pay integration implementation. + Provides WeChat Pay V3 API integration, payment processing, and automated configuration for WeChat payment services. + """ .trimIndent() dependencies { diff --git a/psdk/psdk-wxpa/build.gradle.kts b/psdk/psdk-wxpa/build.gradle.kts index 3089e1e43..5d9a3d283 100644 --- a/psdk/psdk-wxpa/build.gradle.kts +++ b/psdk/psdk-wxpa/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -WeChat Official Account Platform SDK implementation providing comprehensive APIs for WeChat public platform integration. -Includes authentication, user information retrieval, access token management, and JSAPI signature generation capabilities. -""" + WeChat Official Account Platform SDK implementation providing comprehensive APIs for WeChat public platform integration. + Includes authentication, user information retrieval, access token management, and JSAPI signature generation capabilities. + """ .trimIndent() dependencies { diff --git a/rds/rds-crud/build.gradle.kts b/rds/rds-crud/build.gradle.kts index c5bab3f2b..6e9eb4f8e 100644 --- a/rds/rds-crud/build.gradle.kts +++ b/rds/rds-crud/build.gradle.kts @@ -6,9 +6,9 @@ plugins { description = """ -CRUD operation abstractions and utilities built on top of Jimmer ORM. -Provides generic repository patterns, transaction management, and database operation helpers. -""" + CRUD operation abstractions and utilities built on top of Jimmer ORM. + Provides generic repository patterns, transaction management, and database operation helpers. + """ .trimIndent() dependencies { diff --git a/rds/rds-crud/src/test/kotlin/io/github/truenine/composeserver/rds/crud/transaction/TransactionTest.kt b/rds/rds-crud/src/test/kotlin/io/github/truenine/composeserver/rds/crud/transaction/TransactionTest.kt index fe60c77ad..46ed1da6f 100644 --- a/rds/rds-crud/src/test/kotlin/io/github/truenine/composeserver/rds/crud/transaction/TransactionTest.kt +++ b/rds/rds-crud/src/test/kotlin/io/github/truenine/composeserver/rds/crud/transaction/TransactionTest.kt @@ -24,12 +24,12 @@ class TransactionTest : IDatabasePostgresqlContainer { // 手动创建测试表 jdbcTemplate.execute( """ - CREATE TABLE IF NOT EXISTS test_entity ( - id BIGSERIAL PRIMARY KEY, - name VARCHAR DEFAULT NULL, - value INTEGER DEFAULT NULL - ) - """ + CREATE TABLE IF NOT EXISTS test_entity ( + id BIGSERIAL PRIMARY KEY, + name VARCHAR DEFAULT NULL, + value INTEGER DEFAULT NULL + ) + """ .trimIndent() ) } diff --git a/rds/rds-flyway-migration-mysql8/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationmysql8/SimpleMysqlTest.kt b/rds/rds-flyway-migration-mysql8/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationmysql8/SimpleMysqlTest.kt index 2908382dc..626cab04b 100644 --- a/rds/rds-flyway-migration-mysql8/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationmysql8/SimpleMysqlTest.kt +++ b/rds/rds-flyway-migration-mysql8/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationmysql8/SimpleMysqlTest.kt @@ -59,9 +59,9 @@ class SimpleMysqlTest : IDatabaseMysqlContainer { val columns = jdbcTemplate.queryForList( """ - SELECT column_name FROM information_schema.columns - WHERE table_schema = DATABASE() AND table_name = 'test_proc_table' - """ + SELECT column_name FROM information_schema.columns + WHERE table_schema = DATABASE() AND table_name = 'test_proc_table' + """ .trimIndent(), String::class.java, ) diff --git a/rds/rds-flyway-migration-mysql8/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationmysql8/flyway/FunctionExistenceAndCallTest.kt b/rds/rds-flyway-migration-mysql8/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationmysql8/flyway/FunctionExistenceAndCallTest.kt index 29c5e7e93..21e644040 100644 --- a/rds/rds-flyway-migration-mysql8/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationmysql8/flyway/FunctionExistenceAndCallTest.kt +++ b/rds/rds-flyway-migration-mysql8/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationmysql8/flyway/FunctionExistenceAndCallTest.kt @@ -105,12 +105,12 @@ class FunctionExistenceAndCallTest : IDatabaseMysqlContainer { val count = jdbcTemplate.queryForObject( """ - SELECT COUNT(*) - FROM information_schema.routines - WHERE routine_schema = DATABASE() - AND routine_name = ? - AND routine_type = 'PROCEDURE' - """ + SELECT COUNT(*) + FROM information_schema.routines + WHERE routine_schema = DATABASE() + AND routine_name = ? + AND routine_type = 'PROCEDURE' + """ .trimIndent(), Int::class.java, procedureName, diff --git a/rds/rds-flyway-migration-postgresql/build.gradle.kts b/rds/rds-flyway-migration-postgresql/build.gradle.kts index 6f33c5f0d..5a69a28d2 100644 --- a/rds/rds-flyway-migration-postgresql/build.gradle.kts +++ b/rds/rds-flyway-migration-postgresql/build.gradle.kts @@ -7,9 +7,9 @@ plugins { description = """ -Flyway database migration scripts and configuration for PostgreSQL databases. -Contains versioned SQL migration files and Spring Boot integration for automated database schema evolution. -""" + Flyway database migration scripts and configuration for PostgreSQL databases. + Contains versioned SQL migration files and Spring Boot integration for automated database schema evolution. + """ .trimIndent() dependencies { diff --git a/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/AddBaseStructMigrationTest.kt b/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/AddBaseStructMigrationTest.kt index ae2883464..5bfd42e4d 100644 --- a/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/AddBaseStructMigrationTest.kt +++ b/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/AddBaseStructMigrationTest.kt @@ -32,9 +32,9 @@ class AddBaseStructMigrationTest : IDatabasePostgresqlContainer { jdbcTemplate .queryForList( """ - select column_name from information_schema.columns - where table_name = 'test_table' - """ + select column_name from information_schema.columns + where table_name = 'test_table' + """ .trimIndent() ) .map { it["column_name"] } @@ -47,9 +47,9 @@ class AddBaseStructMigrationTest : IDatabasePostgresqlContainer { fun `add_base_struct 应为无 id 且多行数据的表自动填充 id 并设为主键`() { jdbcTemplate.execute( """ - create table test_no_id(nick_name varchar(255), password_enc varchar(255)); - insert into test_no_id(nick_name, password_enc) values ('a', 'p1'), ('b', 'p2'), ('c', 'p3'); - """ + create table test_no_id(nick_name varchar(255), password_enc varchar(255)); + insert into test_no_id(nick_name, password_enc) values ('a', 'p1'), ('b', 'p2'), ('c', 'p3'); + """ .trimIndent() ) jdbcTemplate.execute("select add_base_struct('test_no_id')") @@ -57,9 +57,9 @@ class AddBaseStructMigrationTest : IDatabasePostgresqlContainer { jdbcTemplate .queryForList( """ - select column_name from information_schema.columns - where table_name = 'test_no_id' - """ + select column_name from information_schema.columns + where table_name = 'test_no_id' + """ .trimIndent() ) .map { it["column_name"] } @@ -68,10 +68,10 @@ class AddBaseStructMigrationTest : IDatabasePostgresqlContainer { jdbcTemplate .queryForList( """ - select kcu.column_name from information_schema.table_constraints tc - join information_schema.key_column_usage kcu on tc.constraint_name = kcu.constraint_name - where tc.table_name = 'test_no_id' and tc.constraint_type = 'PRIMARY KEY' - """ + select kcu.column_name from information_schema.table_constraints tc + join information_schema.key_column_usage kcu on tc.constraint_name = kcu.constraint_name + where tc.table_name = 'test_no_id' and tc.constraint_type = 'PRIMARY KEY' + """ .trimIndent() ) .map { it["column_name"] } @@ -90,9 +90,9 @@ class AddBaseStructMigrationTest : IDatabasePostgresqlContainer { jdbcTemplate .queryForList( """ - select column_name from information_schema.columns - where table_name = 'test_table' - """ + select column_name from information_schema.columns + where table_name = 'test_table' + """ .trimIndent() ) .map { it["column_name"] } diff --git a/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/AddPresortTreeStructMigrationTest.kt b/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/AddPresortTreeStructMigrationTest.kt index 2208d0ac8..50d338b8f 100644 --- a/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/AddPresortTreeStructMigrationTest.kt +++ b/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/AddPresortTreeStructMigrationTest.kt @@ -30,9 +30,9 @@ class AddPresortTreeStructMigrationTest : IDatabasePostgresqlContainer { jdbcTemplate .queryForList( """ - select column_name from information_schema.columns - where table_name = 'test_table' - """ + select column_name from information_schema.columns + where table_name = 'test_table' + """ .trimIndent() ) .map { it["column_name"] } @@ -50,9 +50,9 @@ class AddPresortTreeStructMigrationTest : IDatabasePostgresqlContainer { jdbcTemplate .queryForList( """ - select column_name from information_schema.columns - where table_name = 'test_table' - """ + select column_name from information_schema.columns + where table_name = 'test_table' + """ .trimIndent() ) .map { it["column_name"] } diff --git a/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/AllToNullableMigrationTest.kt b/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/AllToNullableMigrationTest.kt index 7b7bb78a2..bb62ace34 100644 --- a/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/AllToNullableMigrationTest.kt +++ b/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/AllToNullableMigrationTest.kt @@ -30,10 +30,10 @@ class AllToNullableMigrationTest : IDatabasePostgresqlContainer { jdbcTemplate .queryForList( """ - select column_name, is_nullable from information_schema.columns - where table_name = 'test_table' - and column_name = 'name' - """ + select column_name, is_nullable from information_schema.columns + where table_name = 'test_table' + and column_name = 'name' + """ .trimIndent() ) .associate { it["column_name"] to it["is_nullable"] } @@ -50,9 +50,9 @@ class AllToNullableMigrationTest : IDatabasePostgresqlContainer { jdbcTemplate .queryForList( """ - select column_name, is_nullable, column_default from information_schema.columns - where table_name = 'test_table' and column_name in ('name', 'age') - """ + select column_name, is_nullable, column_default from information_schema.columns + where table_name = 'test_table' and column_name in ('name', 'age') + """ .trimIndent() ) .associate { it["column_name"] to it["is_nullable"] } diff --git a/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/RmBaseStructMigrationTest.kt b/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/RmBaseStructMigrationTest.kt index 26bcb1dec..1cd97e8df 100644 --- a/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/RmBaseStructMigrationTest.kt +++ b/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/RmBaseStructMigrationTest.kt @@ -31,9 +31,9 @@ class RmBaseStructMigrationTest : IDatabasePostgresqlContainer { jdbcTemplate .queryForList( """ - select column_name from information_schema.columns - where table_name = 'test_table' - """ + select column_name from information_schema.columns + where table_name = 'test_table' + """ .trimIndent() ) .map { it["column_name"] } @@ -51,9 +51,9 @@ class RmBaseStructMigrationTest : IDatabasePostgresqlContainer { jdbcTemplate .queryForList( """ - select column_name from information_schema.columns - where table_name = 'test_table' - """ + select column_name from information_schema.columns + where table_name = 'test_table' + """ .trimIndent() ) .map { it["column_name"] } diff --git a/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/RmPresortTreeStructMigrationTest.kt b/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/RmPresortTreeStructMigrationTest.kt index 2c82b4648..362915fa8 100644 --- a/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/RmPresortTreeStructMigrationTest.kt +++ b/rds/rds-flyway-migration-postgresql/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationpostgresql/flyway/RmPresortTreeStructMigrationTest.kt @@ -31,9 +31,9 @@ class RmPresortTreeStructMigrationTest : IDatabasePostgresqlContainer { jdbcTemplate .queryForList( """ - select column_name from information_schema.columns - where table_name = 'test_table' - """ + select column_name from information_schema.columns + where table_name = 'test_table' + """ .trimIndent() ) .map { it["column_name"] } @@ -52,9 +52,9 @@ class RmPresortTreeStructMigrationTest : IDatabasePostgresqlContainer { jdbcTemplate .queryForList( """ - select column_name from information_schema.columns - where table_name = 'test_table' - """ + select column_name from information_schema.columns + where table_name = 'test_table' + """ .trimIndent() ) .map { it["column_name"] } diff --git a/rds/rds-flyway-migration-shared/build.gradle.kts b/rds/rds-flyway-migration-shared/build.gradle.kts index fb416068a..658605b81 100644 --- a/rds/rds-flyway-migration-shared/build.gradle.kts +++ b/rds/rds-flyway-migration-shared/build.gradle.kts @@ -6,9 +6,9 @@ plugins { description = """ -Shared foundation module for Flyway database migrations, providing common dependencies and configurations for various database types. -Serves as a base dependency for specific database migration modules (such as PostgreSQL, MySQL8), offering Flyway Core runtime support. -""" + Shared foundation module for Flyway database migrations, providing common dependencies and configurations for various database types. + Serves as a base dependency for specific database migration modules (such as PostgreSQL, MySQL8), offering Flyway Core runtime support. + """ .trimIndent() dependencies { diff --git a/rds/rds-flyway-migration-shared/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationshared/autoconfig/FlywayPropertiesOverrideAutoConfigurationTest.kt b/rds/rds-flyway-migration-shared/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationshared/autoconfig/FlywayPropertiesOverrideAutoConfigurationTest.kt index 13daed473..9bcb3ef56 100644 --- a/rds/rds-flyway-migration-shared/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationshared/autoconfig/FlywayPropertiesOverrideAutoConfigurationTest.kt +++ b/rds/rds-flyway-migration-shared/src/test/kotlin/io/github/truenine/composeserver/rds/flywaymigrationshared/autoconfig/FlywayPropertiesOverrideAutoConfigurationTest.kt @@ -24,9 +24,9 @@ class FlywayPropertiesOverrideAutoConfigurationTest : IDatabasePostgresqlContain val flywayTableCount = jdbcTemplate.queryForObject( """ - select count(*) from information_schema.tables - where table_name = 'flyway_schema_history' - """ + select count(*) from information_schema.tables + where table_name = 'flyway_schema_history' + """ .trimIndent(), Int::class.java, ) @@ -36,9 +36,9 @@ class FlywayPropertiesOverrideAutoConfigurationTest : IDatabasePostgresqlContain val userTableCount = jdbcTemplate.queryForObject( """ - select count(*) from information_schema.tables - where table_name = 'test_user_account_table' - """ + select count(*) from information_schema.tables + where table_name = 'test_user_account_table' + """ .trimIndent(), Int::class.java, ) diff --git a/rds/rds-jimmer-ext-postgres/build.gradle.kts b/rds/rds-jimmer-ext-postgres/build.gradle.kts index 7f5ccb21e..beecaaf58 100644 --- a/rds/rds-jimmer-ext-postgres/build.gradle.kts +++ b/rds/rds-jimmer-ext-postgres/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -PostgreSQL-specific extensions and enhancements for Jimmer ORM framework. -Provides PostgreSQL-optimized features, custom types, and database-specific functionality. -""" + PostgreSQL-specific extensions and enhancements for Jimmer ORM framework. + Provides PostgreSQL-optimized features, custom types, and database-specific functionality. + """ .trimIndent() dependencies { diff --git a/rds/rds-shared/build.gradle.kts b/rds/rds-shared/build.gradle.kts index 6c40c59ca..5de22ed0c 100644 --- a/rds/rds-shared/build.gradle.kts +++ b/rds/rds-shared/build.gradle.kts @@ -6,9 +6,9 @@ plugins { description = """ -Shared components for relational database operations using Jimmer ORM framework. -Provides common database configurations, entities, and utilities for database access layers. -""" + Shared components for relational database operations using Jimmer ORM framework. + Provides common database configurations, entities, and utilities for database access layers. + """ .trimIndent() dependencies { diff --git a/security/security-crypto/build.gradle.kts b/security/security-crypto/build.gradle.kts index 6a7714e94..fdc95545e 100644 --- a/security/security-crypto/build.gradle.kts +++ b/security/security-crypto/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -Cryptographic utilities and security functions using Spring Security and BouncyCastle. -Provides encryption/decryption, hashing, digital signatures, and secure random number generation. -""" + Cryptographic utilities and security functions using Spring Security and BouncyCastle. + Provides encryption/decryption, hashing, digital signatures, and secure random number generation. + """ .trimIndent() dependencies { diff --git a/security/security-crypto/src/test/kotlin/io/github/truenine/composeserver/security/crypto/PemFormatTest.kt b/security/security-crypto/src/test/kotlin/io/github/truenine/composeserver/security/crypto/PemFormatTest.kt index 7f3c63ee4..a5a8f14d2 100644 --- a/security/security-crypto/src/test/kotlin/io/github/truenine/composeserver/security/crypto/PemFormatTest.kt +++ b/security/security-crypto/src/test/kotlin/io/github/truenine/composeserver/security/crypto/PemFormatTest.kt @@ -25,11 +25,11 @@ class PemFormatTest { companion object { private val VALID_PEM = """ - -----BEGIN RSA PRIVATE KEY----- - MIIEowIBAAKCAQEAvRKXmC7E8y0F1olUhrH8YuSVfaYhJ1ySqInrROcbXXXXXXXX - q4t5iHJjXXXXXXXXMpzXXXXXXXXq8XXXXXXXX+XXXXXXXXrpXXXXXXXX1XXXXXXXX - -----END RSA PRIVATE KEY----- - """ + -----BEGIN RSA PRIVATE KEY----- + MIIEowIBAAKCAQEAvRKXmC7E8y0F1olUhrH8YuSVfaYhJ1ySqInrROcbXXXXXXXX + q4t5iHJjXXXXXXXXMpzXXXXXXXXq8XXXXXXXX+XXXXXXXXrpXXXXXXXX1XXXXXXXX + -----END RSA PRIVATE KEY----- + """ .trimIndent() private const val VALID_PEM_SCHEMA = "RSA PRIVATE KEY" @@ -286,10 +286,10 @@ class PemFormatTest { fun propertiesWorkWithCustomPem() { val customPem = """ - -----BEGIN CUSTOM KEY----- - SGVsbG8gV29ybGQ= - -----END CUSTOM KEY----- - """ + -----BEGIN CUSTOM KEY----- + SGVsbG8gV29ybGQ= + -----END CUSTOM KEY----- + """ .trimIndent() val pemFormat = PemFormat.parse(customPem) @@ -397,14 +397,14 @@ class PemFormatTest { fun handlesMultipleConsecutiveLineBreaks() { val pemWithExtraBreaks = """ - -----BEGIN TEST----- + -----BEGIN TEST----- - SGVsbG8gV29ybGQ= + SGVsbG8gV29ybGQ= - -----END TEST----- - """ + -----END TEST----- + """ .trimIndent() val pemFormat = PemFormat.parse(pemWithExtraBreaks) diff --git a/security/security-oauth2/build.gradle.kts b/security/security-oauth2/build.gradle.kts index f45925510..3641c673d 100644 --- a/security/security-oauth2/build.gradle.kts +++ b/security/security-oauth2/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -OAuth2 authentication and authorization implementation with support for various providers. -Provides OAuth2 client configurations, token management, and third-party integration capabilities. -""" + OAuth2 authentication and authorization implementation with support for various providers. + Provides OAuth2 client configurations, token management, and third-party integration capabilities. + """ .trimIndent() dependencies { diff --git a/security/security-spring/build.gradle.kts b/security/security-spring/build.gradle.kts index dfc054060..435ad0543 100644 --- a/security/security-spring/build.gradle.kts +++ b/security/security-spring/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -Spring Security integration providing authentication, authorization, and security configurations. -Includes JWT token handling, CAPTCHA support, XSS protection, and comprehensive security filters. -""" + Spring Security integration providing authentication, authorization, and security configurations. + Includes JWT token handling, CAPTCHA support, XSS protection, and comprehensive security filters. + """ .trimIndent() dependencies { diff --git a/shared/build.gradle.kts b/shared/build.gradle.kts index 623c48bb8..44b16c0b1 100644 --- a/shared/build.gradle.kts +++ b/shared/build.gradle.kts @@ -6,9 +6,9 @@ plugins { description = """ -Shared foundation library providing core utilities, exception handling, and common types for all modules. -Includes base configurations, extension functions, and fundamental building blocks used across the entire application. -""" + Shared foundation library providing core utilities, exception handling, and common types for all modules. + Includes base configurations, extension functions, and fundamental building blocks used across the entire application. + """ .trimIndent() dependencies { diff --git a/shared/src/main/kotlin/io/github/truenine/composeserver/AliasExtensions.kt b/shared/src/main/kotlin/io/github/truenine/composeserver/AliasExtensions.kt index 831860032..f88bb20f3 100644 --- a/shared/src/main/kotlin/io/github/truenine/composeserver/AliasExtensions.kt +++ b/shared/src/main/kotlin/io/github/truenine/composeserver/AliasExtensions.kt @@ -21,8 +21,7 @@ inline fun String.isId(): Boolean { return this.isNotEmpty() && this.matches(Regex("^[0-9A-Za-z]+$")) } -@Deprecated("框架内部调用代码，不应由用户直接调用", level = DeprecationLevel.ERROR) -inline fun getDefaultNullableId(): Id = Long.MIN_VALUE +@Deprecated("框架内部调用代码，不应由用户直接调用", level = DeprecationLevel.ERROR) inline fun getDefaultNullableId(): Id = Long.MIN_VALUE inline fun Number.toId(): Id? { return this.toLong().takeIf { it != Long.MIN_VALUE } diff --git a/shared/src/main/kotlin/io/github/truenine/composeserver/generator/SynchronizedSimpleOrderCodeGenerator.kt b/shared/src/main/kotlin/io/github/truenine/composeserver/generator/SynchronizedSimpleOrderCodeGenerator.kt index f4616c27e..df236fbf4 100644 --- a/shared/src/main/kotlin/io/github/truenine/composeserver/generator/SynchronizedSimpleOrderCodeGenerator.kt +++ b/shared/src/main/kotlin/io/github/truenine/composeserver/generator/SynchronizedSimpleOrderCodeGenerator.kt @@ -1,13 +1,11 @@ package io.github.truenine.composeserver.generator -import io.github.truenine.composeserver.datetime import io.github.truenine.composeserver.logger -import java.time.format.DateTimeFormatter /** * 同步简单订单编号生成器 * - * 该生成器组合了时间戳和雪花算法ID来生成唯一的订单号 格式: yyyyMMddHHmmssSSS + snowflakeId + * 该生成器组合了当前时间戳（毫秒）和雪花算法ID来生成唯一的订单号 格式: currentTimeMillis + snowflakeId * * @param snowflake 雪花算法生成器，用于生成唯一ID * @author TrueNine @@ -15,19 +13,18 @@ import java.time.format.DateTimeFormatter */ class SynchronizedSimpleOrderCodeGenerator(private val snowflake: ISnowflakeGenerator) : IOrderCodeGenerator { private val logger = logger() - private val dateTimeFormatter = DateTimeFormatter.ofPattern("yyyyMMddHHmmssSSS") @Synchronized override fun nextString(): String { return try { - val currentDateTime = datetime.now().format(dateTimeFormatter) + val timestampMillis = snowflake.currentTimeMillis().coerceAtLeast(0L) val snowflakeId = snowflake.nextString() val orderCode = buildString { - append(currentDateTime) - append(snowflakeId) + append(timestampMillis) + if (snowflakeId.isNotEmpty()) append(snowflakeId) } - logger.debug("Generated order code: {} with timestamp: {} and snowflake: {}", orderCode, currentDateTime, snowflakeId) + logger.debug("Generated order code: {} with timestamp millis: {} and snowflake: {}", orderCode, timestampMillis, snowflakeId) orderCode } catch (exception: Exception) { diff --git a/shared/src/test/kotlin/io/github/truenine/composeserver/AliasExtensionsTest.kt b/shared/src/test/kotlin/io/github/truenine/composeserver/AliasExtensionsTest.kt index 135cca293..66fa93371 100644 --- a/shared/src/test/kotlin/io/github/truenine/composeserver/AliasExtensionsTest.kt +++ b/shared/src/test/kotlin/io/github/truenine/composeserver/AliasExtensionsTest.kt @@ -4,7 +4,6 @@ import kotlin.test.Test import kotlin.test.assertEquals import kotlin.test.assertFalse import kotlin.test.assertNull -import kotlin.test.assertSame import kotlin.test.assertTrue import kotlin.test.fail @@ -186,10 +185,7 @@ class AliasExtensionsTest { @Test fun `String toIdOrThrow() should throw exception for invalid numeric strings`() { - val invalidInputs = listOf( - "", "abc", "123abc", "abc123", "12.34", "12,34", " 123", "123 ", "12 34", - "++123", "--123", "1a2b3c", Long.MIN_VALUE.toString() - ) + val invalidInputs = listOf("", "abc", "123abc", "abc123", "12.34", "12,34", " 123", "123 ", "12 34", "++123", "--123", "1a2b3c", Long.MIN_VALUE.toString()) invalidInputs.forEach { input -> try { @@ -249,4 +245,4 @@ class AliasExtensionsTest { val result3 = Long.MIN_VALUE.toString().toId { it + 100 } assertNull(result3, "Should return null for Long.MIN_VALUE string") } -} \ No newline at end of file +} diff --git a/shared/src/test/kotlin/io/github/truenine/composeserver/ByteArrayExtensionsTest.kt b/shared/src/test/kotlin/io/github/truenine/composeserver/ByteArrayExtensionsTest.kt index 5e0fda587..e00043f55 100644 --- a/shared/src/test/kotlin/io/github/truenine/composeserver/ByteArrayExtensionsTest.kt +++ b/shared/src/test/kotlin/io/github/truenine/composeserver/ByteArrayExtensionsTest.kt @@ -68,11 +68,11 @@ class ByteArrayExtensionsTest { fun `测试 utf8String 扩展属性 - 多行文本`() { val multilineText = """ - 第一行文本 - 第二行文本 - 第三行包含特殊字符: !@#$% - 第四行包含表情: 😊🎈 - """ + 第一行文本 + 第二行文本 + 第三行包含特殊字符: !@#$% + 第四行包含表情: 😊🎈 + """ .trimIndent() val byteArray = multilineText.toByteArray(Charsets.UTF_8) diff --git a/shared/src/test/kotlin/io/github/truenine/composeserver/generator/SynchronizedSimpleOrderCodeGeneratorTest.kt b/shared/src/test/kotlin/io/github/truenine/composeserver/generator/SynchronizedSimpleOrderCodeGeneratorTest.kt index e5881f79a..92c1533ce 100644 --- a/shared/src/test/kotlin/io/github/truenine/composeserver/generator/SynchronizedSimpleOrderCodeGeneratorTest.kt +++ b/shared/src/test/kotlin/io/github/truenine/composeserver/generator/SynchronizedSimpleOrderCodeGeneratorTest.kt @@ -1,15 +1,13 @@ package io.github.truenine.composeserver.generator -import io.github.truenine.composeserver.datetime import io.mockk.every import io.mockk.mockk import io.mockk.verify -import java.time.LocalDateTime -import java.time.format.DateTimeFormatter import java.util.concurrent.ConcurrentHashMap import java.util.concurrent.CountDownLatch import java.util.concurrent.Executors import java.util.concurrent.TimeUnit +import kotlin.math.abs import kotlin.test.assertEquals import kotlin.test.assertFailsWith import kotlin.test.assertTrue @@ -21,7 +19,6 @@ import org.junit.jupiter.api.BeforeEach import org.junit.jupiter.api.Nested import org.junit.jupiter.api.Test import org.junit.jupiter.api.TestInstance -import org.junit.jupiter.api.assertAll import org.springframework.boot.test.context.SpringBootTest @SpringBootTest @@ -29,7 +26,6 @@ import org.springframework.boot.test.context.SpringBootTest class SynchronizedSimpleOrderCodeGeneratorTest { private lateinit var snowflake: ISnowflakeGenerator private lateinit var generator: SynchronizedSimpleOrderCodeGenerator - private val dateTimeFormatter = DateTimeFormatter.ofPattern("yyyyMMddHHmmssSSS") @BeforeEach fun setUp() { @@ -37,12 +33,24 @@ class SynchronizedSimpleOrderCodeGeneratorTest { generator = SynchronizedSimpleOrderCodeGenerator(snowflake) } + private fun assertTimestampPrefix(orderCode: String) { + assertTrue(orderCode.length >= 13, "订单号长度应该至少为13位") + val timestampPart = orderCode.substring(0, 13) + assertTrue(timestampPart.length == 13, "时间戳部分应该是13位") + assertTrue(timestampPart.all { it.isDigit() }, "时间戳部分应该只包含数字") + val timestampMillis = timestampPart.toLong() + val now = System.currentTimeMillis() + val difference = abs(now - timestampMillis) + assertTrue(difference <= 1_000, "生成的时间戳与当前时间差距应该在1秒内，实际差距: ${difference}ms") + } + @Nested inner class BasicFunctionality { @Test fun `should generate order code with correct length`() { val code = generator.nextString() - assertTrue(code.length >= 19, "订单号长度应该至少为19位") + assertTrue(code.length > 13, "订单号长度应该大于13位") + assertTimestampPrefix(code) } @Test @@ -54,18 +62,7 @@ class SynchronizedSimpleOrderCodeGeneratorTest { @Test fun `should start with valid timestamp format`() { val code = generator.nextString() - val timePart = code.substring(0, 17) - - // 验证时间戳格式是否正确 - assertTrue(timePart.length == 17, "时间戳部分应该是17位") - - val parsedDateTime = LocalDateTime.parse(timePart, dateTimeFormatter) - val currentDateTime = datetime.now() - - assertAll( - { assertTrue(parsedDateTime.isBefore(currentDateTime.plusSeconds(1)), "生成的时间应该不晚于当前时间") }, - { assertTrue(parsedDateTime.isAfter(currentDateTime.minusSeconds(1)), "生成的时间应该不早于当前时间") }, - ) + assertTimestampPrefix(code) } @Test @@ -74,15 +71,13 @@ class SynchronizedSimpleOrderCodeGeneratorTest { // 验证字符串格式 assertTrue(stringValue.isNotBlank(), "nextString()应该返回非空字符串，实际值: '$stringValue'") - assertTrue(stringValue.length >= 19, "订单号长度应该至少为19位，实际长度: ${stringValue.length}") + assertTrue(stringValue.length > 13, "订单号长度应该大于13位，实际长度: ${stringValue.length}") // 验证基本数字格式 assertTrue(stringValue.all { it.isDigit() }, "订单号应该只包含数字字符，实际值: '$stringValue'") // 验证时间戳部分 - val timePart = stringValue.substring(0, 17) - assertTrue(timePart.length == 17, "时间戳部分应该是17位") - assertTrue(timePart.all { it.isDigit() }, "时间戳部分应该只包含数字") + assertTimestampPrefix(stringValue) } } @@ -151,7 +146,7 @@ class SynchronizedSimpleOrderCodeGeneratorTest { @Test fun `should handle snowflake generator exceptions gracefully`() { val brokenSnowflake = mockk() - every { brokenSnowflake.nextString() } throws RuntimeException("雪花算法异常") + every { brokenSnowflake.currentTimeMillis() } throws RuntimeException("雪花算法异常") val brokenGenerator = SynchronizedSimpleOrderCodeGenerator(brokenSnowflake) @@ -165,6 +160,7 @@ class SynchronizedSimpleOrderCodeGeneratorTest { @Test fun `should handle datetime formatting exceptions`() { val snowflake = mockk() + every { snowflake.currentTimeMillis() } returns System.currentTimeMillis() every { snowflake.nextString() } returns "123456" val generator = SynchronizedSimpleOrderCodeGenerator(snowflake) @@ -172,6 +168,7 @@ class SynchronizedSimpleOrderCodeGeneratorTest { // 正常情况应该不会抛出异常 val result = generator.nextString() assertTrue(result.isNotEmpty()) + verify { snowflake.currentTimeMillis() } verify { snowflake.nextString() } } } @@ -237,38 +234,45 @@ class SynchronizedSimpleOrderCodeGeneratorTest { @Test fun `should use snowflake generator correctly`() { val mockSnowflake = mockk() + every { mockSnowflake.currentTimeMillis() } returns System.currentTimeMillis() every { mockSnowflake.nextString() } returns "9876543210" val testGenerator = SynchronizedSimpleOrderCodeGenerator(mockSnowflake) val result = testGenerator.nextString() + verify(exactly = 1) { mockSnowflake.currentTimeMillis() } verify(exactly = 1) { mockSnowflake.nextString() } assertTrue(result.endsWith("9876543210"), "订单号应该以雪花ID结尾") - assertTrue(result.startsWith(datetime.now().format(dateTimeFormatter).substring(0, 14)), "订单号应该以当前时间戳开头") + assertTimestampPrefix(result) } @Test fun `should handle empty snowflake id`() { val mockSnowflake = mockk() + every { mockSnowflake.currentTimeMillis() } returns System.currentTimeMillis() every { mockSnowflake.nextString() } returns "" val testGenerator = SynchronizedSimpleOrderCodeGenerator(mockSnowflake) val result = testGenerator.nextString() - assertEquals(17, result.length, "当雪花ID为空时，订单号长度应该等于时间戳长度") - assertTrue(result.matches(Regex("\\d{17}")), "应该只包含17位数字") + assertEquals(13, result.length, "当雪花ID为空时，订单号长度应该等于时间戳长度") + assertTrue(result.matches(Regex("\\d{13}")), "应该只包含13位数字") + assertTimestampPrefix(result) } @Test fun `should handle special snowflake responses`() { val mockSnowflake = mockk() - every { mockSnowflake.nextString() } returns "123456789" + val snowflakeValue = "123456789" + every { mockSnowflake.currentTimeMillis() } returns System.currentTimeMillis() + every { mockSnowflake.nextString() } returns snowflakeValue val testGenerator = SynchronizedSimpleOrderCodeGenerator(mockSnowflake) val result = testGenerator.nextString() assertTrue(result.endsWith("123456789"), "订单号应该以雪花ID结尾") - assertTrue(result.length >= 17, "订单号长度应该至少为17位") + assertTrue(result.length >= 13 + snowflakeValue.length, "订单号长度应该至少包含时间戳和雪花ID长度") + assertTimestampPrefix(result) } } @@ -278,24 +282,28 @@ class SynchronizedSimpleOrderCodeGeneratorTest { fun `should handle very long snowflake ids`() { val mockSnowflake = mockk() val longSnowflakeId = "1".repeat(100) + every { mockSnowflake.currentTimeMillis() } returns System.currentTimeMillis() every { mockSnowflake.nextString() } returns longSnowflakeId val testGenerator = SynchronizedSimpleOrderCodeGenerator(mockSnowflake) val result = testGenerator.nextString() - assertTrue(result.length >= 117, "订单号长度应该至少为117位") + assertTrue(result.length >= 13 + longSnowflakeId.length, "订单号长度应该至少包含时间戳和雪花ID长度") + assertTimestampPrefix(result) assertTrue(result.endsWith(longSnowflakeId), "订单号应该包含完整的雪花ID") } @Test fun `should handle minimum valid snowflake id`() { val mockSnowflake = mockk() + every { mockSnowflake.currentTimeMillis() } returns System.currentTimeMillis() every { mockSnowflake.nextString() } returns "1" val testGenerator = SynchronizedSimpleOrderCodeGenerator(mockSnowflake) val result = testGenerator.nextString() - assertEquals(18, result.length, "订单号长度应该为18位") + assertEquals(14, result.length, "订单号长度应该为14位") + assertTimestampPrefix(result) assertTrue(result.endsWith("1"), "订单号应该以1结尾") assertTrue(result.toLong() >= 1000, "转换为Long应该>=1000") } diff --git a/sms/sms-shared/build.gradle.kts b/sms/sms-shared/build.gradle.kts index 00e924a55..9d9b38096 100644 --- a/sms/sms-shared/build.gradle.kts +++ b/sms/sms-shared/build.gradle.kts @@ -2,7 +2,7 @@ plugins { id("buildlogic.spotless-conventions") } description = """ -Shared abstractions and interfaces for SMS (Short Message Service) operations across different providers. -Provides unified API for sending SMS messages regardless of the underlying SMS service provider. -""" + Shared abstractions and interfaces for SMS (Short Message Service) operations across different providers. + Provides unified API for sending SMS messages regardless of the underlying SMS service provider. + """ .trimIndent() diff --git a/sms/sms-tencent/build.gradle.kts b/sms/sms-tencent/build.gradle.kts index 430a2ad3b..b6988ccff 100644 --- a/sms/sms-tencent/build.gradle.kts +++ b/sms/sms-tencent/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -Tencent Cloud SMS service integration for reliable message delivery. -Provides SMS sending capabilities through Tencent Cloud SMS API with template support and delivery tracking. -""" + Tencent Cloud SMS service integration for reliable message delivery. + Provides SMS sending capabilities through Tencent Cloud SMS API with template support and delivery tracking. + """ .trimIndent() dependencies { diff --git a/testtoolkit/testtoolkit-shared/build.gradle.kts b/testtoolkit/testtoolkit-shared/build.gradle.kts index 6fd5c9a44..8ca400b40 100644 --- a/testtoolkit/testtoolkit-shared/build.gradle.kts +++ b/testtoolkit/testtoolkit-shared/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -Core testing toolkit providing foundational components for test development. -Includes test utilities, Spring Boot test auto-configuration, and unified testing extensions. -""" + Core testing toolkit providing foundational components for test development. + Includes test utilities, Spring Boot test auto-configuration, and unified testing extensions. + """ .trimIndent() dependencies { diff --git a/testtoolkit/testtoolkit-springmvc/build.gradle.kts b/testtoolkit/testtoolkit-springmvc/build.gradle.kts index c60ea4486..357d0590c 100644 --- a/testtoolkit/testtoolkit-springmvc/build.gradle.kts +++ b/testtoolkit/testtoolkit-springmvc/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -Spring MVC testing toolkit extension providing web layer testing utilities. -Includes specialized test support for controllers, REST APIs, security, and web integration testing scenarios. -""" + Spring MVC testing toolkit extension providing web layer testing utilities. + Includes specialized test support for controllers, REST APIs, security, and web integration testing scenarios. + """ .trimIndent() dependencies { diff --git a/testtoolkit/testtoolkit-testcontainers/build.gradle.kts b/testtoolkit/testtoolkit-testcontainers/build.gradle.kts index 66b27da7d..98a3bcac0 100644 --- a/testtoolkit/testtoolkit-testcontainers/build.gradle.kts +++ b/testtoolkit/testtoolkit-testcontainers/build.gradle.kts @@ -5,9 +5,9 @@ plugins { description = """ -TestContainers specialized testing toolkit providing containerized integration test support. -Includes advanced container orchestration, specialized database/cache/storage test utilities, and container lifecycle management. -""" + TestContainers specialized testing toolkit providing containerized integration test support. + Includes advanced container orchestration, specialized database/cache/storage test utilities, and container lifecycle management. + """ .trimIndent() dependencies { diff --git a/testtoolkit/testtoolkit-testcontainers/src/main/kotlin/io/github/truenine/composeserver/testtoolkit/testcontainers/IDatabasePostgresqlContainer.kt b/testtoolkit/testtoolkit-testcontainers/src/main/kotlin/io/github/truenine/composeserver/testtoolkit/testcontainers/IDatabasePostgresqlContainer.kt index bc934d0c8..728e57ed4 100644 --- a/testtoolkit/testtoolkit-testcontainers/src/main/kotlin/io/github/truenine/composeserver/testtoolkit/testcontainers/IDatabasePostgresqlContainer.kt +++ b/testtoolkit/testtoolkit-testcontainers/src/main/kotlin/io/github/truenine/composeserver/testtoolkit/testcontainers/IDatabasePostgresqlContainer.kt @@ -195,20 +195,20 @@ interface IDatabasePostgresqlContainer : ITestContainerBase { container.databaseName, "-c", """ - DO ${'$'}${'$'} - DECLARE - r RECORD; - BEGIN - -- 删除所有用户表（排除系统表） - FOR r IN (SELECT tablename FROM pg_tables WHERE schemaname = 'public') LOOP - EXECUTE 'TRUNCATE TABLE ' || quote_ident(r.tablename) || ' RESTART IDENTITY CASCADE'; - END LOOP; - -- 删除所有序列（如果有的话） - FOR r IN (SELECT sequence_name FROM information_schema.sequences WHERE sequence_schema = 'public') LOOP - EXECUTE 'ALTER SEQUENCE ' || quote_ident(r.sequence_name) || ' RESTART WITH 1'; - END LOOP; - END ${'$'}${'$'}; - """ + DO ${'$'}${'$'} + DECLARE + r RECORD; + BEGIN + -- 删除所有用户表（排除系统表） + FOR r IN (SELECT tablename FROM pg_tables WHERE schemaname = 'public') LOOP + EXECUTE 'TRUNCATE TABLE ' || quote_ident(r.tablename) || ' RESTART IDENTITY CASCADE'; + END LOOP; + -- 删除所有序列（如果有的话） + FOR r IN (SELECT sequence_name FROM information_schema.sequences WHERE sequence_schema = 'public') LOOP + EXECUTE 'ALTER SEQUENCE ' || quote_ident(r.sequence_name) || ' RESTART WITH 1'; + END LOOP; + END ${'$'}${'$'}; + """ .trimIndent(), ) if (result.exitCode != 0) { diff --git a/testtoolkit/testtoolkit-testcontainers/src/test/kotlin/io/github/truenine/composeserver/testtoolkit/testcontainers/ContainersIntegrationTest.kt b/testtoolkit/testtoolkit-testcontainers/src/test/kotlin/io/github/truenine/composeserver/testtoolkit/testcontainers/ContainersIntegrationTest.kt index 433b847c8..2685dd3ea 100644 --- a/testtoolkit/testtoolkit-testcontainers/src/test/kotlin/io/github/truenine/composeserver/testtoolkit/testcontainers/ContainersIntegrationTest.kt +++ b/testtoolkit/testtoolkit-testcontainers/src/test/kotlin/io/github/truenine/composeserver/testtoolkit/testcontainers/ContainersIntegrationTest.kt @@ -72,11 +72,11 @@ class ContainersIntegrationTest : IDatabasePostgresqlContainer, ICacheRedisConta // 重新创建表 jdbcTemplate.execute( """ - create table test_table ( - id serial primary key, - name varchar(255) not null - ) - """ + create table test_table ( + id serial primary key, + name varchar(255) not null + ) + """ .trimIndent() )