universal-dev-standards 3.5.1-beta.1 → 3.5.1-beta.11

package/bundled/locales/zh-TW/ai/options/project-structure/ruby.ai.yaml

@@ -0,0 +1,140 @@
+# Ruby 專案結構 - AI 優化選項
+# 父層: project-structure
+
+id: ruby
+meta:
+  parent: project-structure
+  version: "1.0.0"
+  description: Ruby 專案慣例
+
+structure:
+  gem: |
+    project-root/
+    ├── lib/
+    │   ├── gem_name.rb       # 主要進入點
+    │   └── gem_name/
+    │       ├── version.rb
+    │       ├── client.rb
+    │       └── errors.rb
+    ├── spec/                 # RSpec 測試
+    │   ├── spec_helper.rb
+    │   └── gem_name/
+    │       └── client_spec.rb
+    ├── bin/                  # 可執行檔
+    │   └── gem_name
+    ├── sig/                  # RBS 類型簽名
+    ├── Gemfile
+    ├── Gemfile.lock
+    ├── gem_name.gemspec
+    ├── Rakefile
+    └── README.md
+
+  rails: |
+    project-root/
+    ├── app/
+    │   ├── controllers/
+    │   ├── models/
+    │   ├── views/
+    │   ├── helpers/
+    │   ├── mailers/
+    │   ├── jobs/
+    │   └── services/         # 自訂新增
+    ├── config/
+    │   ├── routes.rb
+    │   ├── database.yml
+    │   └── environments/
+    ├── db/
+    │   ├── migrate/
+    │   ├── schema.rb
+    │   └── seeds.rb
+    ├── lib/
+    │   └── tasks/
+    ├── public/
+    ├── spec/                 # 或 test/
+    │   ├── models/
+    │   ├── controllers/
+    │   ├── requests/
+    │   └── factories/
+    ├── Gemfile
+    └── config.ru
+
+  sinatra: |
+    project-root/
+    ├── app.rb                # 主應用程式
+    ├── config.ru
+    ├── lib/
+    │   └── helpers/
+    ├── views/
+    ├── public/
+    ├── spec/
+    ├── Gemfile
+    └── Gemfile.lock
+
+config_files:
+  - file: Gemfile
+    purpose: 相依性宣告
+    required: true
+
+  - file: Gemfile.lock
+    purpose: 相依性鎖定檔
+    required: true
+
+  - file: "*.gemspec"
+    purpose: Gem 規格
+    required: 僅限 gem
+
+  - file: Rakefile
+    purpose: Rake 任務
+    required: false
+
+  - file: ".rubocop.yml"
+    purpose: RuboCop 設定
+    required: false
+
+  - file: ".rspec"
+    purpose: RSpec 設定
+    required: false
+
+gitignore:
+  - ".bundle/"
+  - log/
+  - tmp/
+  - "*.gem"
+  - ".env"
+  - coverage/
+  - node_modules/
+  - ".byebug_history"
+
+rules:
+  - id: lib-structure
+    trigger: 組織 gem 程式碼
+    instruction: "將主要程式碼放在 lib/<gem_name>/"
+    priority: required
+
+  - id: spec-location
+    trigger: 放置測試
+    instruction: 在 spec/ 目錄中映射 lib/ 結構
+    priority: recommended
+
+  - id: service-objects
+    trigger: 組織 Rails 業務邏輯
+    instruction: 在 app/services/ 使用服務物件處理複雜操作
+    priority: recommended
+
+  - id: factory-bot
+    trigger: 設定測試資料
+    instruction: 使用 FactoryBot，工廠放在 spec/factories/
+    priority: recommended
+
+  - id: rubocop-config
+    trigger: 設定檢查工具
+    instruction: 使用專案特定規則設定 RuboCop
+    priority: recommended
+
+tools:
+  build: [Rake, Bundler]
+  test_runner: [RSpec, Minitest]
+  linter: [RuboCop, Standard]
+  formatter: [RuboCop --auto-correct, Standard]
+  package_manager: [Bundler, RubyGems]
+  documentation: [YARD, RDoc]

package/bundled/locales/zh-TW/ai/options/project-structure/rust.ai.yaml

@@ -0,0 +1,117 @@
+# Rust 專案結構 - AI 優化選項
+# 父層: project-structure
+
+id: rust
+meta:
+  parent: project-structure
+  version: "1.0.0"
+  description: Rust 專案慣例
+
+structure:
+  binary: |
+    project-root/
+    ├── src/
+    │   ├── main.rs           # 進入點
+    │   ├── lib.rs            # 程式庫根目錄（可選）
+    │   ├── config.rs
+    │   ├── error.rs
+    │   └── modules/
+    │       ├── mod.rs
+    │       ├── handler.rs
+    │       └── service.rs
+    ├── tests/                # 整合測試
+    │   └── integration_test.rs
+    ├── benches/              # 效能測試
+    │   └── benchmark.rs
+    ├── examples/             # 範例程式碼
+    │   └── example.rs
+    ├── Cargo.toml
+    ├── Cargo.lock
+    └── README.md
+
+  library: |
+    project-root/
+    ├── src/
+    │   ├── lib.rs            # 程式庫進入點
+    │   ├── error.rs
+    │   └── modules/
+    │       └── mod.rs
+    ├── tests/
+    ├── examples/
+    ├── Cargo.toml
+    └── README.md
+
+  workspace: |
+    project-root/
+    ├── crates/
+    │   ├── core/
+    │   │   ├── src/
+    │   │   └── Cargo.toml
+    │   ├── api/
+    │   │   ├── src/
+    │   │   └── Cargo.toml
+    │   └── cli/
+    │       ├── src/
+    │       └── Cargo.toml
+    ├── Cargo.toml            # 工作區根目錄
+    └── Cargo.lock
+
+config_files:
+  - file: Cargo.toml
+    purpose: 套件設定檔
+    required: true
+
+  - file: Cargo.lock
+    purpose: 相依性鎖定檔
+    required: true
+    note: 二進位檔提交，程式庫忽略
+
+  - file: rust-toolchain.toml
+    purpose: 工具鏈版本
+    required: false
+
+  - file: .cargo/config.toml
+    purpose: Cargo 設定
+    required: false
+
+gitignore:
+  - target/
+  - "*.pdb"
+  - ".env"
+  - "Cargo.lock"  # 僅限程式庫
+
+rules:
+  - id: module-organization
+    trigger: 組織模組
+    instruction: 一致使用 mod.rs 或 module_name.rs 模式
+    priority: required
+
+  - id: tests-location
+    trigger: 放置測試
+    instruction: |
+      單元測試：在同一檔案中使用 #[cfg(test)] mod tests
+      整合測試：放在 tests/ 目錄
+    priority: required
+
+  - id: error-handling
+    trigger: 定義錯誤
+    instruction: 在 error.rs 或 errors.rs 中定義自訂錯誤類型
+    priority: recommended
+
+  - id: workspace-for-large
+    trigger: 組織大型專案
+    instruction: 多 crate 專案使用 Cargo 工作區
+    priority: recommended
+
+  - id: doc-comments
+    trigger: 記錄公開 API
+    instruction: 公開項目使用 ///，模組級別文件使用 //!
+    priority: recommended
+
+tools:
+  build: [cargo build, cargo build --release]
+  test_runner: [cargo test, cargo nextest]
+  linter: [clippy]
+  formatter: [rustfmt, cargo fmt]
+  package_manager: [cargo, crates.io]
+  documentation: [cargo doc, rustdoc]

package/bundled/locales/zh-TW/ai/options/project-structure/swift.ai.yaml

@@ -0,0 +1,143 @@
+# Swift 專案結構 - AI 優化選項
+# 父層: project-structure
+
+id: swift
+meta:
+  parent: project-structure
+  version: "1.0.0"
+  description: Swift 專案慣例
+
+structure:
+  spm_library: |
+    project-root/
+    ├── Sources/
+    │   └── PackageName/
+    │       ├── PackageName.swift
+    │       ├── Models/
+    │       ├── Services/
+    │       └── Utilities/
+    ├── Tests/
+    │   └── PackageNameTests/
+    │       └── PackageNameTests.swift
+    ├── Package.swift
+    └── README.md
+
+  spm_executable: |
+    project-root/
+    ├── Sources/
+    │   ├── AppName/
+    │   │   └── main.swift
+    │   └── AppNameCore/
+    │       └── Core.swift
+    ├── Tests/
+    │   └── AppNameTests/
+    ├── Package.swift
+    └── README.md
+
+  ios_app: |
+    project-root/
+    ├── AppName/
+    │   ├── App/
+    │   │   ├── AppNameApp.swift
+    │   │   └── ContentView.swift
+    │   ├── Features/
+    │   │   ├── Home/
+    │   │   │   ├── HomeView.swift
+    │   │   │   └── HomeViewModel.swift
+    │   │   └── Settings/
+    │   ├── Core/
+    │   │   ├── Models/
+    │   │   ├── Services/
+    │   │   └── Utilities/
+    │   ├── Resources/
+    │   │   ├── Assets.xcassets
+    │   │   └── Localizable.strings
+    │   └── Info.plist
+    ├── AppNameTests/
+    ├── AppNameUITests/
+    ├── AppName.xcodeproj
+    └── README.md
+
+  vapor: |
+    project-root/
+    ├── Sources/
+    │   ├── App/
+    │   │   ├── configure.swift
+    │   │   ├── routes.swift
+    │   │   ├── Controllers/
+    │   │   ├── Models/
+    │   │   └── Migrations/
+    │   └── Run/
+    │       └── main.swift
+    ├── Tests/
+    │   └── AppTests/
+    ├── Resources/
+    │   └── Views/
+    ├── Public/
+    ├── Package.swift
+    └── docker-compose.yml
+
+config_files:
+  - file: Package.swift
+    purpose: Swift Package Manager 設定檔
+    required: true（SPM 專案）
+
+  - file: "*.xcodeproj"
+    purpose: Xcode 專案
+    required: true（Xcode 專案）
+
+  - file: "*.xcworkspace"
+    purpose: Xcode 工作區
+    required: false
+
+  - file: ".swiftlint.yml"
+    purpose: SwiftLint 設定
+    required: false
+
+  - file: ".swift-version"
+    purpose: Swift 版本
+    required: false
+
+gitignore:
+  - ".build/"
+  - ".swiftpm/"
+  - "*.xcodeproj/xcuserdata/"
+  - "*.xcworkspace/xcuserdata/"
+  - DerivedData/
+  - ".DS_Store"
+  - Pods/
+  - Carthage/
+
+rules:
+  - id: feature-folders
+    trigger: 組織 iOS 功能
+    instruction: 按功能分組，每個包含 View、ViewModel 和 Models
+    priority: recommended
+
+  - id: spm-targets
+    trigger: 組織 SPM 套件
+    instruction: 將程式庫和可執行檔分開到不同的目標
+    priority: recommended
+
+  - id: protocol-oriented
+    trigger: 設計 API
+    instruction: 使用協定進行抽象和相依性注入
+    priority: recommended
+
+  - id: test-naming
+    trigger: 命名測試
+    instruction: "使用 test_methodName_condition_expectedResult 格式"
+    priority: recommended
+
+  - id: access-control
+    trigger: 定義可見性
+    instruction: 使用最小存取等級（預設 internal，API 使用 public）
+    priority: required
+
+tools:
+  build: [Swift Package Manager, Xcode, xcodebuild]
+  test_runner: [XCTest, Quick/Nimble]
+  linter: [SwiftLint, SwiftFormat]
+  formatter: [SwiftFormat, swift-format]
+  package_manager: [Swift Package Manager, CocoaPods, Carthage]
+  documentation: [DocC, Jazzy]

package/bundled/locales/zh-TW/ai/options/testing/contract-testing.ai.yaml

@@ -0,0 +1,254 @@
+# 契約測試 - AI 優化選項
+# 父層: testing
+
+id: contract-testing
+meta:
+  parent: testing
+  version: "1.0.0"
+  description: API 與服務整合的契約測試標準
+  references:
+    - "Pact Foundation"
+    - "Consumer-Driven Contracts"
+    - "Martin Fowler - Contract Test"
+
+best_for:
+  - 微服務架構
+  - API 優先開發
+  - 第三方整合
+  - 獨立工作的團隊
+  - 分散式系統
+
+concepts:
+  consumer_driven_contracts:
+    abbreviation: CDC
+    name: 消費者驅動契約
+    description: 由 API 消費者定義的契約
+    flow:
+      1: 消費者定義預期的互動
+      2: 產生契約（pact 檔案）
+      3: 提供者驗證契約
+      4: 雙方都必須通過才能部署
+    benefits:
+      - 消費者需求驅動 API 設計
+      - 解耦部署
+      - 及早發現整合問題
+
+  provider_contracts:
+    name: 提供者契約
+    description: 由 API 提供者定義的契約
+    use_case: 公開 API、OpenAPI 優先設計
+    flow:
+      1: 提供者定義 API 規格
+      2: 消費者針對規格測試
+      3: 提供者確保向後相容
+
+contract_types:
+  http_api:
+    description: REST/HTTP API 契約
+    tools:
+      - name: Pact
+        languages: 多語言
+        type: 消費者驅動
+      - name: Spring Cloud Contract
+        languages: Java/JVM
+        type: 兩者皆可
+      - name: Dredd
+        languages: 多語言
+        type: 提供者（OpenAPI）
+
+  message_queue:
+    description: 非同步訊息契約
+    tools:
+      - name: Pact（非同步）
+        support: 基於訊息的互動
+      - name: Spring Cloud Contract
+        support: 訊息通道
+
+  graphql:
+    description: GraphQL API 契約
+    tools:
+      - name: Pact
+        support: GraphQL 查詢
+      - name: Apollo Contract Testing
+        support: Schema 驗證
+
+pact_workflow:
+  consumer_side:
+    name: 消費者端
+    step_1:
+      name: 定義互動
+      code: |
+        // JavaScript 範例
+        const interaction = {
+          state: 'user exists',
+          uponReceiving: 'a request for user by id',
+          withRequest: {
+            method: 'GET',
+            path: '/users/1',
+            headers: { Accept: 'application/json' }
+          },
+          willRespondWith: {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+            body: {
+              id: like(1),
+              name: like('John'),
+              email: like('john@example.com')
+            }
+          }
+        };
+
+    step_2:
+      name: 執行消費者測試
+      description: 測試對模擬提供者執行
+
+    step_3:
+      name: 發布契約
+      description: 上傳 pact 檔案到 broker
+
+  provider_side:
+    name: 提供者端
+    step_1:
+      name: 取得契約
+      description: 從 broker 下載契約
+
+    step_2:
+      name: 驗證契約
+      code: |
+        // 提供者驗證
+        verifier.verifyProvider({
+          provider: 'UserService',
+          pactBrokerUrl: 'https://broker.example.com',
+          publishVerificationResult: true
+        });
+
+    step_3:
+      name: 狀態設定
+      description: 為每個互動設定提供者狀態
+
+pact_broker:
+  description: 契約的中央儲存庫
+  features:
+    - 契約儲存
+    - 驗證狀態
+    - 相依性圖表
+    - Can-I-Deploy 檢查
+    - CI/CD 的 Webhooks
+
+  can_i_deploy:
+    description: 檢查部署是否安全
+    command: |
+      pact-broker can-i-deploy \
+        --pacticipant UserService \
+        --version $(git rev-parse HEAD) \
+        --to production
+
+rules:
+  - id: consumer-first
+    trigger: 設計 API 契約
+    instruction: 從消費者需求開始，而非提供者實作
+    priority: recommended
+
+  - id: use-matchers
+    trigger: 定義契約主體
+    instruction: 使用類型匹配器（like、eachLike），而非精確值
+    priority: required
+
+  - id: provider-states
+    trigger: 設定測試情境
+    instruction: 為每個互動定義清晰的提供者狀態
+    priority: required
+
+  - id: version-contracts
+    trigger: 發布契約
+    instruction: 以消費者版本和分支標記契約
+    priority: required
+
+  - id: can-i-deploy
+    trigger: 部署前
+    instruction: 在 CI/CD 中始終執行 can-i-deploy 檢查
+    priority: required
+
+  - id: breaking-changes
+    trigger: 修改 API
+    instruction: |
+      破壞性變更需要：
+      1. 驗證沒有消費者依賴變更的行為
+      2. 與消費者團隊協調
+      3. 如需要使用棄用期間
+    priority: required
+
+  - id: async-contracts
+    trigger: 測試基於訊息的系統
+    instruction: 為非同步通訊包含訊息契約
+    priority: recommended
+
+ci_integration:
+  consumer_pipeline: |
+    # 消費者 CI
+    stages:
+      - test:
+          - 執行單元測試
+          - 執行契約測試（產生 pact）
+      - publish:
+          - 發布 pact 到 broker
+      - can-i-deploy:
+          - 檢查部署安全性
+      - deploy:
+          - 部署消費者
+
+  provider_pipeline: |
+    # 提供者 CI
+    stages:
+      - test:
+          - 執行單元測試
+          - 驗證消費者契約
+      - publish:
+          - 發布驗證結果
+      - can-i-deploy:
+          - 檢查部署安全性
+      - deploy:
+          - 部署提供者
+
+  github_actions_consumer: |
+    name: Consumer Contract Tests
+    on: [push, pull_request]
+    jobs:
+      contract-test:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v4
+          - name: Run contract tests
+            run: npm run test:contract
+          - name: Publish pact
+            run: npm run pact:publish
+          - name: Can I deploy?
+            run: |
+              pact-broker can-i-deploy \
+                --pacticipant MyConsumer \
+                --version ${{ github.sha }}
+
+quick_reference:
+  workflow:
+    columns: [步驟, 消費者, 提供者]
+    rows:
+      - ["1. 定義", "撰寫預期", "實作 API"]
+      - ["2. 測試", "對模擬執行", "驗證契約"]
+      - ["3. 發布", "上傳 pact", "上傳結果"]
+      - ["4. 部署", "Can-I-Deploy", "Can-I-Deploy"]
+
+  tools:
+    columns: [工具, 類型, 語言]
+    rows:
+      - [Pact, CDC, 多語言]
+      - [Spring Cloud Contract, 兩者, JVM]
+      - [Dredd, OpenAPI, 多語言]
+      - [Prism, Mock, 多語言]
+
+  benefits:
+    columns: [效益, 描述]
+    rows:
+      - [快速回饋, 不需要完整整合環境]
+      - [解耦, 團隊可獨立工作]
+      - [安全部署, Can-I-Deploy 防止破壞性變更]
+      - [活文件, 契約記錄 API 行為]