aodw-skill 0.7.5 → 0.7.7

package/.aodw/03-standards/stacks/java-springboot/ai-coding-rules-backend.md

@@ -23,9 +23,88 @@
 - **缓存**：Redis
 - **消息中间件**：RabbitMQ
 
+**必须与以下规范配合使用**：
+- `.aodw/03-standards/ai-coding-rules.md`（主文件，包含通用原则）
+- `.aodw/03-standards/ai-coding-rules-common.md`（通用编码规范）
+- `.aodw/05-tooling/ai-tools-init-rules.md`（工具初始化规则，如果通过 AI 方式初始化工具）
+
+**⚠️ 强制要求**：所有后端开发必须严格遵守 `docs/backend-guidelines.md` 中的规范（如果存在）。
+
+---
+
+## 2. 工具初始化检查（必须）
+
+> **⚠️ 重要**：所有后端开发必须使用工具强制执行规范，不能只靠自觉。  
+> 本项目的后端规范通过 **工具自动化质量体系** 实现：
+> - ✅ 编辑器即时提示 → Git 提交前阻断 → CI 自动失败 → AI 自动服从
+
+在开始任何后端开发前，AI 必须检查工具初始化状态：
+
+### 2.1 工具初始化状态检查
+
+**AI 必须检查**：
+- [ ] 是否已运行工具初始化？
+- [ ] `.aodw/tools-status.yaml` 中 `initialized: true` 且后端工具状态为 `configured: true`？
+
+**检查方法**：
+1. 读取 `.aodw/tools-status.yaml` 文件
+2. 检查 `tools_init.initialized` 是否为 `true`
+3. 检查 `tools_init.backend.maven.configured` 是否为 `true`（Maven 依赖管理）
+4. 检查 `tools_init.backend.checkstyle.configured` 是否为 `true`（如果使用 Checkstyle）
+5. 检查 `tools_init.backend.spotless.configured` 是否为 `true`（如果使用 Spotless）
+6. 检查 `tools_init.backend.pre_commit.configured` 和 `hooks_installed` 是否为 `true`
+
+### 2.2 工具要求
+
+**Java 后端开发推荐使用以下工具**：
+- **Maven**：依赖管理（必须）
+- **Checkstyle**：代码风格检查（推荐）
+- **Spotless**：代码格式化（推荐）
+- **pre-commit**：Git 提交前强制检查（推荐）
+- **Maven Wrapper**：确保 Maven 版本一致性（推荐）
+
+**工具作用**：
+- **Maven**：依赖管理，确保依赖版本一致性和可重现性
+- **Checkstyle**：自动检查代码风格，确保符合 Java 编码规范
+- **Spotless**：自动统一代码格式，避免风格争议
+- **pre-commit**：不合格的代码连 commit 都提不上去，实现"提交前阻断"
+
+**工具工作流程**：
+- 每次执行 `git commit` 时，将自动触发：
+  1. Checkstyle 检查：发现代码风格问题 → ❌ 直接中断提交
+  2. Spotless 格式化：格式不统一 → ❌ 强制格式化后重新提交
+  3. 全部通过 → ✅ 才允许提交
+
+### 2.3 工具未初始化时的处理
+
+**如果工具未初始化或未配置**：
+1. **AI 必须立即停止编码**
+2. **AI 必须提示用户运行工具初始化**：
+   - **CLI 方式**：运行 `aodw` 选择"工具初始化"，或运行 `aodw init-tools`
+   - **AI 方式**：说"初始化工具"或"设置开发工具"
+3. **AI 必须说明**：工具初始化会引导用户完成工具的安装和配置
+4. **在工具初始化完成前，不能开始编码**
+
+### 2.4 工具配置参考
+
+**配置模板位置**：`.aodw/templates/tools-config/backend/`
+- Checkstyle 配置模板：`checkstyle.config.template.xml`（如果存在）
+- Spotless 配置模板：`spotless.config.template.xml`（如果存在）
+- pre-commit 配置模板：`pre-commit.config.template.yaml`
+
+**如果工具已初始化**：
+- 配置应已符合 AODW 规范
+- 配置文件应已生成或合并
+- 工具应已正确安装和配置
+- pre-commit hooks 应已安装
+
+**如果需要对配置进行调整**：
+- 可以再次运行工具初始化
+- 或参考配置模板手动调整
+
 ---
 
-## 2. 目录结构规范
+## 3. 目录结构规范
 
 ### 2.1 标准 Maven 结构
 ```
@@ -55,7 +134,7 @@ backend/
 
 ---
 
-## 3. 命名规范
+## 4. 命名规范
 
 - **类名**: PascalCase (如 `ProjectService`)。
 - **接口名**: 无需 `I` 前缀。
@@ -64,7 +143,7 @@ backend/
 
 ---
 
-## 4. Spring Boot 编码规范
+## 5. Spring Boot 编码规范
 
 ### 4.1 注解使用
 - 优先使用构造函数注入 (`@RequiredArgsConstructor`) 代替 `@Autowired`。
@@ -80,7 +159,7 @@ backend/
 
 ---
 
-## 5. 依赖管理 (Maven)
+## 6. 依赖管理 (Maven)
 
 - **pom.xml**：
   - 代码变更涉及新依赖时，必须更新 `pom.xml`。
@@ -89,12 +168,64 @@ backend/
 
 ---
 
-## 6. AI 实现流程约束
+## 7. AI 实现流程约束
 
-### 6.1 生成粒度
+### 7.1 生成粒度
 - 遵循“一个文件一次生成”原则。
 - 复杂功能应先生成 Entity/Repository，再生成 Service，最后生成 Controller。
 
-### 6.2 代码质量
+### 7.2 代码质量
 - 所有的 POJO 类建议使用 `@Data` (Lombok) 以减少冗余。
 - API 接口必须符合 RESTful 设计原则。
+
+---
+
+## 8. Java 代码提交前检查清单
+
+在提交 Java 代码前，必须完成以下检查：
+
+### 8.1 工具初始化检查（参考 `.aodw/03-standards/stacks/java-springboot/ai-coding-rules-backend.md` 第 2 节）
+
+- [ ] **工具是否已初始化**：
+  - [ ] 检查 `.aodw/tools-status.yaml` 中 `initialized: true`
+  - [ ] **Maven** 是否已安装并配置？
+  - [ ] **Checkstyle** 是否已安装并配置？（如果使用）
+  - [ ] **Spotless** 是否已安装并配置？（如果使用）
+  - [ ] **pre-commit** 是否已安装并配置？
+  - [ ] pre-commit hooks 是否已安装？
+
+### 8.2 依赖管理检查
+
+- [ ] **Maven 依赖管理**：
+  - [ ] 是否使用 Maven 管理依赖？
+  - [ ] `pom.xml` 是否已更新？
+  - [ ] 依赖版本是否与 `xg-common-parent` 一致？
+  - [ ] 依赖范围是否准确（compile, provided, test 等）？
+
+### 8.3 代码质量检查（工具自动）
+
+- [ ] **Checkstyle 静态检查**（如果使用）：
+  - [ ] `mvn checkstyle:check` 是否通过？
+  - [ ] 代码风格是否符合规范？
+- [ ] **Spotless 格式化**（如果使用）：
+  - [ ] `mvn spotless:apply` 是否已运行？
+  - [ ] 代码格式是否统一？
+
+### 8.4 目录结构检查
+
+- [ ] **分层架构检查**：
+  - [ ] controller 层是否未直接导入 mapper/dao？
+  - [ ] service 层是否未直接导入 controller？
+  - [ ] 依赖关系是否符合规范？
+
+### 8.5 最终验证
+
+- [ ] **运行完整检查**：
+  ```bash
+  mvn clean compile
+  mvn checkstyle:check  # 如果使用 Checkstyle
+  mvn spotless:apply    # 如果使用 Spotless
+  mvn test
+  pre-commit run --all-files  # 如果使用 pre-commit
+  ```
+- [ ] **所有检查通过后，才能提交代码**

package/.aodw/03-standards/stacks/rust-axum/ai-coding-rules-backend.md

@@ -0,0 +1,134 @@
+# AI Coding Rules - Backend Development (Rust)
+
+> **注意**：本文件是 `.aodw-next/03-standards/ai-coding-rules.md` 的子规范文件。  
+> 请先阅读主文件了解通用编码原则。
+
+**适用场景**：
+- 后端开发（Rust + Axum + SQLx）
+- 命令行工具开发
+- 高性能组件开发
+
+**依赖规范**：
+- [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
+- [Effective Rust](https://www.lurklurk.org/effective-rust/)
+
+## 1. 核心原则 (Core Principals)
+
+### 1.1 稳定性优先 (Stability First)
+- **绝对禁止在业务逻辑中使用 `unwrap()` 或 `expect()`**。
+    - 仅允许在 `tests/`, `examples/`, 或 `bin/` 的初始化阶段（无法恢复的启动错误）使用。
+    - 业务代码必须使用 `match`, `if let`, 或 `?` 传播 `Result`。
+- **避免 Panic**：任何可能 Panic 的操作（如数组索引 `arr[i]`）都应使用安全版本（如 `arr.get(i)`）。
+
+### 1.2 错误处理 (Error Handling)
+- 使用 `thiserror` 定义库/模块级别的错误枚举。
+- 使用 `anyhow` 处理顶层应用（Application）的错误传播。
+- **Axum Handler** 必须返回实现了 `IntoResponse` 的 Result 类型（通常自定义 `AppError`）。
+
+### 1.3 异步规范 (Async)
+- 避免在异步上下文中执行阻塞操作（如标准 `std::fs` 或大量 CPU 计算）。
+- 使用 `tokio::fs` 替代 `std::fs`。
+- 长时间计算任务使用 `tokio::task::spawn_blocking`。
+
+---
+
+## 2. 代码风格与命名 (Style & Naming)
+
+遵循 `rustfmt` 默认配置。
+
+- **Types (Structs, Enums, Traits)**: `PascalCase`
+- **Functions, Methods, Variables, Modules**: `snake_case`
+- **Constants, Statics**: `SCREAMING_SNAKE_CASE`
+- **File Names**: `snake_case.rs`
+
+---
+
+## 3. 目录结构规范 (Directory Structure)
+
+```
+backend/
+  src/
+    bin/              # 独立可执行文件（工具脚本）
+    routes/           # Axum 路由处理函数 (Handlers)
+      mod.rs          # 路由注册
+      users.rs        # 用户模块路由
+    models/           # 数据模型 (Structs) & DB 映射
+    services/         # 业务逻辑层 (可选，复杂逻辑从 routes 剥离)
+    utils/            # 通用工具函数
+    main.rs           # 应用入口，仅包含启动配置
+```
+
+- **Routes**: 负责 HTTP 解析、参数校验、调用 Service/Model、返回响应。
+- **Services/Models**: 负责核心业务逻辑和数据持久化，不应依赖 HTTP 层细节。
+
+---
+
+## 4. 最佳实践 (Best Practices)
+
+### 4.1 SQLx 使用
+- 优先使用 `sqlx::query_as!` 宏进行编译时 SQL 检查。
+- 如果必须使用动态 SQL，确保使用参数化查询 (`bind`) 防止注入。
+- 数据库模型 Struct 字段应与 DB 列名一致，或使用 `#[sqlx(rename = "...")]`。
+
+### 4.2 Axum Handler
+- 保持 Handler 瘦身：如果逻辑超过 50 行，考虑提取到 Service 层或独立函数。
+- 使用 `State` 抽取共享状态（如 DB Pool）。
+
+### 4.3 日志 (Logging)
+- 使用 `tracing` 而非 `println!`。
+- 关键业务路径必须有 `info!` 日志。
+- 错误分支必须有 `error!` 日志，包含上下文信息。
+
+---
+
+## 5. 工具链配置 (Tooling)
+
+所有 Rust 项目必须包含以下配置：
+
+### 5.1 工具初始化（必须）
+
+在开始开发前，必须运行工具初始化：
+- 通过 AI 命令："初始化工具" 或 "设置开发工具"
+- 通过 CLI 命令：`aodw init-tools`
+
+工具初始化会自动：
+- 检测 rustfmt、clippy、cargo 是否已安装
+- 从模板生成 `rustfmt.toml` 和 `clippy.toml` 配置文件
+- 配置 pre-commit hooks（如果使用）
+
+### 5.2 配置文件
+
+**rustfmt.toml**（从模板生成）：
+- 模板位置：`.aodw/templates/tools-config/backend/rustfmt.config.template.toml`
+- 生成位置：项目根目录 `rustfmt.toml`
+- 主要配置：
+  ```toml
+  edition = "2021"
+  max_width = 100
+  use_small_heuristics = "Max"
+  ```
+
+**clippy.toml**（从模板生成）：
+- 模板位置：`.aodw/templates/tools-config/backend/clippy.config.template.toml`
+- 生成位置：项目根目录 `clippy.toml` 或 `Cargo.toml` 的 `[lints.clippy]` 部分
+- 主要配置：
+  - 零警告策略：`warn = "all"`, `deny = ["warnings"]`
+  - 复杂度限制：`cognitive_complexity_threshold = 15`, `cyclomatic_complexity_threshold = 15`
+  - 文件长度限制：`too_many_lines_threshold = 400`
+
+### 5.3 提交前检查（必须）
+
+所有代码提交前必须通过以下检查：
+- `cargo fmt -- --check`（代码格式化检查）
+- `cargo clippy -- -D warnings`（零警告策略）
+- `cargo test`（单元测试）
+
+这些检查应配置在 pre-commit hooks 中，确保提交前自动执行。
+
+---
+
+## 6. 代码质量指标 (Metrics)
+
+- **函数长度**: 软限制 60 行。超过则拆分。
+- **文件长度**: 软限制 400 行。
+- **复杂度**: 单个函数 Cyclomatic Complexity < 15。

package/.aodw/03-standards/stacks/vue2/ai-coding-rules-frontend.md

@@ -8,6 +8,13 @@
 - UI 组件开发
 - 前端工具配置
 
+**必须与以下规范配合使用**：
+- `.aodw/03-standards/ai-coding-rules.md`（主文件，包含通用原则）
+- `.aodw/03-standards/ai-coding-rules-common.md`（通用编码规范）
+- `.aodw/05-tooling/ai-tools-init-rules.md`（工具初始化规则，如果通过 AI 方式初始化工具）
+
+**⚠️ 强制要求**：所有前端开发必须严格遵守 `docs/frontend-guidelines.md` 中的规范（如果存在）。
+
 ---
 
 ## 1. 技术栈确认
@@ -22,12 +29,68 @@
 
 ---
 
-## 2. 工具配置检查
+## 2. 工具初始化检查（必须）
+
+> **⚠️ 重要**：所有前端开发必须使用工具强制执行规范，不能只靠自觉。  
+> 本项目的后端规范通过 **工具自动化质量体系** 实现：
+> - ✅ 编辑器即时提示 → Git 提交前阻断 → CI 自动失败 → AI 自动服从
+
+在开始任何前端开发前，AI 必须检查工具初始化状态：
+
+### 2.1 工具初始化状态检查
+
+**AI 必须检查**：
+- [ ] 是否已运行工具初始化？
+- [ ] `.aodw/tools-status.yaml` 中 `initialized: true` 且前端工具状态为 `configured: true`？
+
+**检查方法**：
+1. 读取 `.aodw/tools-status.yaml` 文件
+2. 检查 `tools_init.initialized` 是否为 `true`
+3. 检查 `tools_init.frontend.eslint.configured` 是否为 `true`
+4. 检查 `tools_init.frontend.prettier.configured` 是否为 `true`
+5. 检查 ESLint 配置是否适用于 Vue 2
+
+### 2.2 工具要求
+
+**Vue 2 前端开发必须使用以下工具**：
+- **ESLint**：代码质量检查（语法错误、未使用变量、Vue 2 特定规则）
+- **Prettier**：代码格式化（统一代码风格）
+- **PostCSS**：CSS 后处理（兼容性配置）
+
+**工具作用**：
+- ESLint：自动拦截代码质量问题，确保符合 Vue 2 编码规范
+- Prettier：自动统一代码格式，避免风格争议
+- PostCSS：处理 CSS 兼容性问题
+
+### 2.3 工具未初始化时的处理
+
+**如果工具未初始化或未配置**：
+1. **AI 必须立即停止编码**
+2. **AI 必须提示用户运行工具初始化**：
+   - **CLI 方式**：运行 `aodw` 选择"工具初始化"，或运行 `aodw init-tools`
+   - **AI 方式**：说"初始化工具"或"设置开发工具"
+3. **AI 必须说明**：工具初始化会引导用户完成工具的安装和配置
+4. **在工具初始化完成前，不能开始编码**
+
+### 2.4 工具配置参考
+
+**配置模板位置**：`.aodw/templates/tools-config/frontend/`
+- ESLint 配置模板：`eslint.config.template.json`（需要适配 Vue 2）
+- Prettier 配置模板：`prettier.config.template.json`
+
+**Vue 2 特定配置要求**：
+- ESLint 必须包含 `eslint-plugin-vue` 插件
+- ESLint 配置必须设置为 Vue 2 模式（`vue/no-v-for-template-key` 等规则）
+- Prettier 配置需要兼容 Vue 2 的单文件组件格式
+
+**如果工具已初始化**：
+- 配置应已符合 AODW 规范
+- 配置文件应已生成或合并
+- 工具应已正确安装和配置
 
-在开始编码前，AI 应检查以下配置：
-- **ESLint**: 检查 `.eslintrc.js` 确保适用于 Vue 2。
-- **Prettier**: 确保配置符合项目风格。
-- **PostCSS**: 检查兼容性配置。
+**如果需要对配置进行调整**：
+- 可以再次运行工具初始化
+- 或参考配置模板手动调整
 
 ---
 
@@ -95,3 +158,63 @@ frontend/
 ### 6.2 代码生成策略
 - 优先生成符合 Vue 2 语法的代码（Option API）。
 - 确保所有的 `import` 路径正确（使用项目中定义的别名，如 `@`）。
+
+---
+
+## 7. Vue 2 代码提交前检查清单
+
+在提交 Vue 2 代码前，必须完成以下检查：
+
+### 7.1 工具初始化检查（参考 `.aodw/03-standards/stacks/vue2/ai-coding-rules-frontend.md` 第 2 节）
+
+- [ ] **工具是否已初始化**：
+  - [ ] 检查 `.aodw/tools-status.yaml` 中 `initialized: true`
+  - [ ] ESLint 是否已安装并配置？（必须支持 Vue 2）
+  - [ ] Prettier 是否已安装并配置？
+  - [ ] PostCSS 是否已配置？
+
+### 7.2 目录结构检查
+
+- [ ] **目录结构是否符合规范**：
+  - [ ] 页面组件是否放在 `src/views/` 下？
+  - [ ] 通用组件是否放在 `src/components/` 下？
+  - [ ] API 请求是否放在 `src/api/` 下？
+  - [ ] 工具函数是否放在 `src/utils/` 下？
+
+### 7.3 文件大小检查
+
+- [ ] **文件大小是否符合规范**：
+  - [ ] 单个 `.vue` 文件是否 ≤ 500 行？
+  - [ ] `template` 部分是否 ≤ 300 行？
+  - [ ] 单个函数是否 ≤ 60 行？
+
+### 7.4 Vue 2 编码规范检查
+
+- [ ] **组件定义**：
+  - [ ] 是否包含 `name` 属性？
+  - [ ] `data` 是否是一个函数？
+  - [ ] `props` 是否定义了类型、默认值或是否必传？
+- [ ] **样式约定**：
+  - [ ] 组件样式是否使用了 `scoped`？
+  - [ ] 是否优先使用项目定义的 SASS 变量？
+
+### 7.5 代码质量检查（工具自动）
+
+- [ ] **ESLint 静态检查**：
+  - [ ] `npm run lint` 或 `npx eslint .` 是否通过？
+  - [ ] 是否有语法错误？
+  - [ ] 是否有未使用的变量？
+  - [ ] Vue 2 特定规则是否通过？
+- [ ] **Prettier 格式化**：
+  - [ ] `npm run format` 或 `npx prettier --write .` 是否已运行？
+  - [ ] 代码格式是否统一？
+
+### 7.6 最终验证
+
+- [ ] **运行完整检查**：
+  ```bash
+  npm run lint      # ESLint 检查
+  npm run format    # Prettier 格式化
+  npm run build     # 构建检查
+  ```
+- [ ] **所有检查通过后，才能提交代码**