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

package/bundled/locales/zh-TW/ai/standards/logging.ai.yaml

@@ -0,0 +1,128 @@
+# 日誌標準 - AI 優化版
+# 來源: core/logging-standards.md
+
+id: logging
+meta:
+  version: "1.1.0"
+  updated: "2026-01-05"
+  source: core/logging-standards.md
+  description: 日誌等級、結構化日誌與最佳實踐
+
+log_levels:
+  ordered:
+    - name: TRACE
+      code: 10
+      use_for: 非常詳細的除錯
+      production: false
+    - name: DEBUG
+      code: 20
+      use_for: 診斷資訊
+      production: false
+    - name: INFO
+      code: 30
+      use_for: 正常操作
+      production: true
+    - name: WARN
+      code: 40
+      use_for: 潛在問題
+      production: true
+    - name: ERROR
+      code: 50
+      use_for: 需要關注的錯誤
+      production: true
+    - name: FATAL
+      code: 60
+      use_for: 關鍵故障
+      production: true
+
+structured_logging:
+  required_fields:
+    - timestamp
+    - level
+    - message
+    - service
+    - environment
+  recommended_fields:
+    - trace_id
+    - span_id
+    - request_id
+    - user_id
+    - duration_ms
+  field_naming: snake_case
+  format: 生產環境使用 JSON
+
+sensitive_data:
+  never_log:
+    - 密碼
+    - api_keys
+    - 完整令牌
+    - 信用卡
+    - 身分證字號
+  mask_patterns:
+    - "password: '***REDACTED***'"
+    - "token: 'tok_...abc'"
+    - "card: '****4242'"
+
+rules:
+  - id: select-level
+    trigger: 新增日誌語句
+    instruction: |
+      選擇適當等級：
+      - DEBUG: 僅診斷用，生產環境關閉
+      - INFO: 正常操作完成
+      - WARN: 意外但可恢復
+      - ERROR: 操作失敗
+      - FATAL: 無法繼續
+    priority: required
+
+  - id: structured-format
+    trigger: 寫入日誌
+    instruction: 使用包含必要欄位的結構化 JSON 日誌
+    priority: required
+
+  - id: include-context
+    trigger: 記錄操作
+    instruction: 包含 request_id 或 trace_id 以便關聯
+    priority: required
+
+  - id: no-sensitive-data
+    trigger: 記錄資料
+    instruction: 永不記錄密碼、機密、令牌或 PII
+    priority: required
+
+  - id: error-context
+    trigger: 記錄錯誤
+    instruction: 包含 error_type、error_message、stack 和相關 ID
+    priority: required
+
+  - id: async-logging
+    trigger: 部署到生產環境
+    instruction: 使用非同步/緩衝日誌以提升效能
+    priority: recommended
+
+quick_reference:
+  level_selection:
+    columns: [問題, 等級]
+    rows:
+      - [只是除錯?, DEBUG]
+      - [正常操作?, INFO]
+      - [意外但可接受?, WARN]
+      - [操作失敗?, ERROR]
+      - [無法繼續?, FATAL]
+
+  required_fields:
+    columns: [欄位, 格式, 必要]
+    rows:
+      - [timestamp, "ISO 8601", 是]
+      - [level, "INFO/ERROR/等", 是]
+      - [message, 字串, 是]
+      - [service, 字串, 是]
+      - [request_id, UUID, 建議]
+
+  retention:
+    columns: [等級, 保留期間]
+    rows:
+      - [DEBUG, 7 天]
+      - [INFO, 30 天]
+      - [WARN, 90 天]
+      - [ERROR/FATAL, 1 年]

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

@@ -0,0 +1,134 @@
+# 專案結構標準 - AI 優化版
+# 來源: core/project-structure.md
+
+id: project-structure
+meta:
+  version: "1.1.0"
+  updated: "2025-12-30"
+  source: core/project-structure.md
+  description: 專案目錄結構慣例
+  language: zh-TW
+
+options:
+  project_language:
+    description: 選擇專案語言/平台
+    choices:
+      - id: dotnet
+        file: options/project-structure/dotnet.ai.yaml
+      - id: nodejs
+        file: options/project-structure/nodejs.ai.yaml
+      - id: python
+        file: options/project-structure/python.ai.yaml
+      - id: java
+        file: options/project-structure/java.ai.yaml
+      - id: go
+        file: options/project-structure/go.ai.yaml
+      - id: rust
+        file: options/project-structure/rust.ai.yaml
+      - id: kotlin
+        file: options/project-structure/kotlin.ai.yaml
+      - id: php
+        file: options/project-structure/php.ai.yaml
+      - id: ruby
+        file: options/project-structure/ruby.ai.yaml
+      - id: swift
+        file: options/project-structure/swift.ai.yaml
+
+structure:
+  common:
+    - dir: src/
+      purpose: 原始碼
+      gitignore: false
+
+    - dir: tests/
+      purpose: 測試檔案
+      gitignore: false
+
+    - dir: docs/
+      purpose: 文件
+      gitignore: false
+
+    - dir: tools/
+      purpose: 開發/部署腳本
+      gitignore: false
+      subdirs: [deployment/, migration/, scripts/]
+
+    - dir: examples/
+      purpose: 使用範例
+      gitignore: false
+
+  build_output:
+    - dir: dist/
+      purpose: 發布輸出
+      gitignore: true
+
+    - dir: build/
+      purpose: 編譯產物
+      gitignore: true
+
+    - dir: out/
+      purpose: 輸出目錄
+      gitignore: true
+
+    - dir: bin/
+      purpose: 二進位執行檔
+      gitignore: true
+
+  config:
+    - dir: .github/
+      purpose: GitHub 設定
+      gitignore: false
+
+    - dir: .standards/
+      purpose: 開發標準
+      gitignore: false
+
+    - dir: config/
+      purpose: 設定檔
+      gitignore: false
+
+rules:
+  - id: gitignore-build
+    trigger: 建立專案時
+    instruction: 永遠將建置輸出目錄加入 gitignore (dist/, build/, out/, bin/)
+    priority: required
+
+  - id: src-structure
+    trigger: 組織原始碼時
+    instruction: 遵循特定語言的 src/ 結構慣例
+    priority: required
+
+  - id: tests-location
+    trigger: 組織測試時
+    instruction: 將測試放在 tests/ 或原始碼旁邊（依語言而定）
+    priority: recommended
+
+  - id: tools-organization
+    trigger: 新增腳本時
+    instruction: 將腳本依用途分組放在 tools/ 的子目錄中
+    priority: recommended
+
+quick_reference:
+  directories:
+    columns: [目錄, 用途, gitignore]
+    rows:
+      - [src/, 原始碼, 否]
+      - [tests/, 測試檔案, 否]
+      - [docs/, 文件, 否]
+      - [tools/, 腳本, 否]
+      - [dist/, 建置輸出, 是]
+      - [build/, 編譯產物, 是]
+      - [node_modules/, 相依套件, 是]
+      - [.env, 環境變數, 是]
+
+  gitignore_patterns:
+    columns: [模式, 用途]
+    rows:
+      - ["dist/", 建置輸出]
+      - ["build/", 編譯產物]
+      - ["*.log", 日誌檔案]
+      - [".env*", 環境變數檔]
+      - ["node_modules/", Node 相依套件]
+      - ["__pycache__/", Python 快取]
+      - ["*.pyc", Python 位元碼]
+      - [".venv/", Python 虛擬環境]

package/bundled/locales/zh-TW/ai/standards/spec-driven-development.ai.yaml

@@ -0,0 +1,169 @@
+# 規格驅動開發標準 - AI 優化版
+# 來源: core/spec-driven-development.md
+
+id: spec-driven-development
+meta:
+  version: "1.2.0"
+  updated: "2026-01-05"
+  source: core/spec-driven-development.md
+  description: 規格驅動開發 (SDD) 的原則和工作流程
+  language: zh-TW
+
+workflow:
+  stages:
+    - stage: 提案
+      description: 定義要變更什麼及為什麼
+      artifacts: proposal.md
+
+    - stage: 審查
+      description: 利害關係人核准
+      artifacts: 審查意見、核准記錄
+
+    - stage: 實作
+      description: 執行已核准的規格
+      artifacts: 程式碼、測試、文件
+
+    - stage: 驗證
+      description: 確認實作符合規格
+      artifacts: 測試結果、審查
+
+    - stage: 歸檔
+      description: 關閉並歸檔規格
+      artifacts: 已歸檔規格附 commits/PRs 連結
+
+principles:
+  tool_priority:
+    rule: 當 SDD 工具提供命令時，優先使用這些命令而非手動編輯檔案
+    rationale:
+      - 一致性（嚴格的 schema）
+      - 可追溯性（自動記錄、ID、連結）
+      - 安全性（內建驗證）
+    example: '使用 /openspec proposal "新增登入" 而非手動建立檔案'
+
+  methodology_over_tooling:
+    rule: SDD 是一種方法論，不綁定單一工具
+    universal_flow: 提案 -> 審查 -> 實作 -> 驗證 -> 歸檔
+
+  spec_first:
+    rule: 沒有核准的規格不得進行功能性程式碼變更
+    exceptions:
+      - 緊急修復（立即恢復服務，之後補文件）
+      - 瑣碎變更（錯字、註解、格式）
+
+spec_template:
+  sections:
+    - name: 摘要
+      description: 提議變更的簡短描述
+      required: true
+
+    - name: 動機
+      description: 為什麼需要這個變更？解決什麼問題？
+      required: true
+
+    - name: 詳細設計
+      description: 技術方法、影響的元件、資料流
+      required: true
+
+    - name: 驗收標準
+      description: 可檢查的完成標準
+      required: true
+
+    - name: 相依性
+      description: 對其他規格或外部系統的相依
+      required: false
+
+    - name: 風險
+      description: 潛在風險和緩解策略
+      required: false
+
+integration:
+  commit_messages:
+    instruction: 在 commit 訊息中引用規格 ID
+    example: |
+      feat(auth): 實作登入功能
+
+      實作 SPEC-001 登入功能，支援 OAuth2。
+
+      Refs: SPEC-001
+
+  checkin_standards:
+    checklist:
+      - 規格已核准
+      - 實作符合規格
+      - 測試涵蓋驗收標準
+      - PR 中引用規格 ID
+
+  code_review:
+    checklist:
+      - 變更符合核准的規格
+      - 沒有超出規格的範圍蔓延
+      - 規格驗收標準已滿足
+
+common_tools:
+  - tool: OpenSpec
+    description: 規格管理
+    commands: ["/openspec proposal", "/openspec approve"]
+
+  - tool: Spec Kit
+    description: 輕量級規格追蹤
+    commands: ["/spec create", "/spec close"]
+
+  - tool: 手動
+    description: 無工具，基於檔案
+    commands: ["手動建立 specs/SPEC-XXX.md"]
+
+rules:
+  - id: use-sdd-commands
+    trigger: SDD 工具可用時
+    instruction: 使用工具命令而非手動編輯檔案
+    priority: required
+
+  - id: spec-before-code
+    trigger: 開始新功能時
+    instruction: 在編碼之前建立並取得規格核准
+    priority: required
+
+  - id: reference-spec-id
+    trigger: 提交實作時
+    instruction: 在 commit 訊息和 PR 中包含規格 ID
+    priority: required
+
+  - id: verify-against-spec
+    trigger: 完成實作時
+    instruction: 驗證所有驗收標準已滿足
+    priority: required
+
+  - id: archive-completed-specs
+    trigger: 規格實作已驗證
+    instruction: 歸檔規格並附上 commits/PRs 連結
+    priority: required
+
+best_practices:
+  do:
+    - 保持規格聚焦和原子性（一個變更一個規格）
+    - 包含清晰的驗收標準
+    - 將規格連結到實作 PRs
+    - 完成後歸檔規格
+
+  do_not:
+    - 在規格核准前開始編碼
+    - 實作期間修改範圍而不更新規格
+    - 讓規格處於懸置狀態（務必關閉或歸檔）
+    - 跳過驗證步驟
+
+quick_reference:
+  workflow:
+    columns: [階段, 產出物]
+    rows:
+      - [提案, proposal.md]
+      - [審查, 意見/核准]
+      - [實作, 程式碼/測試/文件]
+      - [驗證, 測試結果]
+      - [歸檔, 已歸檔規格]
+
+  tools:
+    columns: [工具, 命令]
+    rows:
+      - [OpenSpec, "/openspec proposal, /openspec approve"]
+      - [Spec Kit, "/spec create, /spec close"]
+      - [手動, "specs/SPEC-XXX.md"]

package/bundled/locales/zh-TW/ai/standards/test-completeness-dimensions.ai.yaml

@@ -0,0 +1,220 @@
+# 測試完整性維度 - AI 優化版
+# 來源: core/test-completeness-dimensions.md
+
+id: test-completeness-dimensions
+meta:
+  version: "1.0.0"
+  updated: "2025-12-30"
+  source: core/test-completeness-dimensions.md
+  description: 評估測試完整性的 7 個維度框架
+  language: zh-TW
+
+dimensions:
+  - id: 1
+    name: 正常路徑
+    description: 使用有效輸入的正常預期行為
+    test_items:
+      - 有效輸入產生預期輸出
+      - 成功狀態碼/回應
+      - 資料正確建立/修改
+      - 預期的副作用發生
+
+  - id: 2
+    name: 邊界條件
+    description: 有效範圍邊緣的值
+    test_items:
+      - 最小有效值
+      - 最大有效值
+      - 剛好低於最小值（無效）
+      - 剛好高於最大值（無效）
+      - 空集合 vs 單一項目 vs 多項目
+
+  - id: 3
+    name: 錯誤處理
+    description: 無效輸入和例外情況
+    test_items:
+      - 無效輸入格式
+      - 缺少必要欄位
+      - 重複資料衝突
+      - 資源不存在
+      - 外部服務失敗
+
+  - id: 4
+    name: 授權
+    description: 每個操作的角色型存取控制
+    test_items:
+      - 每個角色的允許操作
+      - 每個角色的拒絕操作
+      - 未認證存取
+      - 跨租戶/跨使用者資料存取
+    note: 為每個功能建立授權矩陣
+
+  - id: 5
+    name: 狀態變更
+    description: 操作前後的系統狀態
+    test_items:
+      - 操作前狀態
+      - 操作後狀態
+      - 狀態轉換（啟用 → 停用）
+      - 冪等性（重複操作結果相同）
+
+  - id: 6
+    name: 驗證邏輯
+    description: 商業規則和格式驗證
+    test_items:
+      - 格式驗證（email、電話等）
+      - 商業規則驗證
+      - 跨欄位驗證
+      - 領域特定約束
+
+  - id: 7
+    name: 整合驗證
+    description: 實際資料庫查詢和外部整合
+    test_items:
+      - 查詢條件傳回正確資料
+      - 實體關聯正確載入
+      - 分頁正確運作
+      - 排序和篩選正確運作
+    when_required: 如果單元測試使用萬用匹配器（It.IsAny<>、any()、Arg.Any<>）
+
+feature_type_mapping:
+  - type: CRUD API
+    dimensions: [1, 2, 3, 4, 6, 7]
+
+  - type: 查詢/搜尋
+    dimensions: [1, 2, 3, 4, 7]
+
+  - type: 狀態機
+    dimensions: [1, 3, 4, 5, 6]
+
+  - type: 驗證
+    dimensions: [1, 2, 3, 6]
+
+  - type: 背景作業
+    dimensions: [1, 3, 5]
+
+  - type: 外部整合
+    dimensions: [1, 3, 7]
+
+error_code_coverage:
+  - code: 200
+    meaning: 成功
+    scenario: 正常路徑測試
+
+  - code: 400
+    meaning: 錯誤請求
+    scenario: 無效格式、缺少欄位
+
+  - code: 401
+    meaning: 未授權
+    scenario: 無效/缺少 token
+
+  - code: 403
+    meaning: 禁止存取
+    scenario: 有效 token 但權限不足
+
+  - code: 404
+    meaning: 找不到
+    scenario: 不存在的資源
+
+  - code: 409
+    meaning: 衝突
+    scenario: 重複資料
+
+  - code: 422
+    meaning: 無法處理
+    scenario: 商業規則違反
+
+  - code: 500
+    meaning: 伺服器錯誤
+    scenario: 例外處理
+
+anti_patterns:
+  - 只測試正常路徑
+  - 多角色系統缺少授權測試
+  - 未驗證狀態變更
+  - 單元測試使用萬用匹配器但無對應整合測試
+  - 測試資料中 ID 和業務識別碼使用相同值
+  - 測試實作細節而非行為
+
+rules:
+  - id: use-checklist
+    trigger: 為功能設計測試時
+    instruction: 使用 7 維度清單確保完整性
+    priority: required
+
+  - id: authorization-matrix
+    trigger: 功能有角色型存取時
+    instruction: 建立授權矩陣，每格都要有測試
+    priority: required
+
+  - id: integration-for-wildcards
+    trigger: 單元測試使用萬用匹配器時
+    instruction: 必須有對應的整合測試
+    priority: required
+
+  - id: cover-error-codes
+    trigger: API 回傳錯誤碼時
+    instruction: 每個錯誤碼應有測試場景
+    priority: required
+
+checklist_template: |
+  功能: ___________________
+
+  □ 正常路徑
+    □ 有效輸入產生預期成功
+    □ 傳回/建立正確資料
+    □ 預期的副作用發生
+
+  □ 邊界條件
+    □ 最小有效值
+    □ 最大有效值
+    □ 空/單一/大量集合
+
+  □ 錯誤處理
+    □ 無效輸入格式
+    □ 缺少必要欄位
+    □ 重複/衝突場景
+    □ 找不到場景
+
+  □ 授權
+    □ 每個允許角色已測試
+    □ 每個拒絕角色已測試
+    □ 未認證存取已測試
+
+  □ 狀態變更
+    □ 初始狀態已驗證
+    □ 最終狀態已驗證
+    □ 所有有效轉換已測試
+
+  □ 驗證
+    □ 格式驗證
+    □ 商業規則驗證
+    □ 跨欄位驗證
+
+  □ 整合（如 UT 使用萬用匹配器）
+    □ 查詢條件已驗證
+    □ 實體關聯已驗證
+    □ 分頁/排序已驗證
+
+quick_reference:
+  dimensions:
+    columns: [ID, 維度, 關鍵焦點]
+    rows:
+      - [1, 正常路徑, 正常預期行為]
+      - [2, 邊界, 最小/最大值和限制]
+      - [3, 錯誤處理, 無效輸入和例外]
+      - [4, 授權, 角色型存取控制]
+      - [5, 狀態變更, 前後狀態驗證]
+      - [6, 驗證, 格式和商業規則]
+      - [7, 整合, 實際查詢驗證]
+
+  feature_dimensions:
+    columns: [功能類型, 必要維度]
+    rows:
+      - [CRUD API, "1,2,3,4,6,7"]
+      - [查詢/搜尋, "1,2,3,4,7"]
+      - [狀態機, "1,3,4,5,6"]
+      - [驗證, "1,2,3,6"]
+      - [背景作業, "1,3,5"]
+      - [外部整合, "1,3,7"]