universal-dev-standards 5.16.0 → 6.0.0

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

@@ -0,0 +1,165 @@
+---
+source: options/project-structure/swift.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+# Swift 專案結構
+
+> **語言**: [English](../../../../options/project-structure/swift.md) | 繁體中文
+
+**上層標準**: [專案結構](../../core/project-structure.md)
+
+---
+
+## 概觀
+
+Swift 專案可使用 Swift Package Manager (SPM) 或 Xcode 來管理。iOS/macOS 應用程式通常使用 Xcode 專案，而函式庫與伺服器端 Swift 則使用 SPM。
+
+## 專案類型
+
+### 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
+```
+
+## 設定檔
+
+| 檔案 | 用途 | Required |
+|------|------|----------|
+| `Package.swift` | Swift Package Manager manifest | Yes (SPM) |
+| `*.xcodeproj` | Xcode 專案 | Yes (Xcode) |
+| `*.xcworkspace` | Xcode workspace | No |
+| `.swiftlint.yml` | SwiftLint 設定 | No |
+| `.swift-version` | Swift 版本 | No |
+
+## .gitignore
+
+```
+.build/
+.swiftpm/
+*.xcodeproj/xcuserdata/
+*.xcworkspace/xcuserdata/
+DerivedData/
+.DS_Store
+Pods/
+Carthage/
+```
+
+## 工具
+
+| 類別 | 工具 |
+|------|------|
+| 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 |
+
+## 規則
+
+| 規則 | 描述 | Priority |
+|------|------|----------|
+| Feature folders | 依功能分組，包含 View、ViewModel 與 Models | Recommended |
+| SPM targets | 將 library 與 executable 分拆為不同的 target | Recommended |
+| Protocol-oriented | 使用 protocol 進行抽象與依賴注入 | Recommended |
+| Test naming | 使用 `test_methodName_condition_expectedResult` 格式 | Recommended |
+| Access control | 使用最小存取層級（預設為 internal，API 才用 public） | Required |
+
+## 相關選項
+
+- [Kotlin](./kotlin.md) - Kotlin 專案結構
+- [Rust](./rust.md) - Rust 專案結構
+
+---
+
+## 參考資料
+
+- [Swift Package Manager](https://swift.org/package-manager/)
+- [Apple Developer Documentation](https://developer.apple.com/documentation/)
+- [Vapor](https://vapor.codes/)
+
+---
+
+## 授權
+
+本文件以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權發布。
+
+**來源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-TW/options/testing/contract-testing.md

@@ -0,0 +1,237 @@
+---
+source: options/testing/contract-testing.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# Contract Testing
+
+> **語言**: [English](../../../../options/testing/contract-testing.md) | 繁體中文
+
+**上層標準**: [Testing Completeness](../../core/test-completeness-dimensions.md)
+
+---
+
+## 概觀
+
+Contract testing 透過測試 consumer 與 provider 之間的協議（contract）來驗證服務能否正確通訊。它讓團隊可以獨立開發與部署，同時確保彼此相容。
+
+## 最適用於
+
+- 微服務架構
+- API-first 開發
+- 第三方整合
+- 各自獨立作業的團隊
+- 分散式系統
+
+## Contract 類型
+
+### Consumer-Driven Contracts (CDC)
+
+由 API consumer 定義的 contract。
+
+**流程：**
+1. Consumer 定義預期的互動
+2. 產生 contract（pact 檔案）
+3. Provider 依 contract 進行驗證
+4. 部署前雙方都必須通過
+
+**好處：**
+- 由 consumer 的需求驅動 API 設計
+- 解耦的部署
+- 提早偵測整合問題
+
+### Provider Contracts
+
+由 API provider 定義的 contract。
+
+**使用情境：** 公開 API、OpenAPI-first 設計
+
+**流程：**
+1. Provider 定義 API 規格
+2. Consumer 依規格進行測試
+3. Provider 確保向後相容性
+
+## 工具
+
+| 工具 | 類型 | 語言 |
+|------|------|-----------|
+| **Pact** | Consumer-driven | 多語言 |
+| **Spring Cloud Contract** | 兩者皆可 | JVM |
+| **Dredd** | OpenAPI | 多語言 |
+| **Prism** | Mock | 多語言 |
+
+## Pact 工作流程
+
+### Consumer 端
+
+**1. 定義互動**
+
+```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')
+    }
+  }
+};
+```
+
+**2. 執行 consumer 測試** - 測試針對 mock provider 執行
+
+**3. 發布 contract** - 將 pact 檔案上傳至 broker
+
+### Provider 端
+
+**1. 取得 contract** - 從 broker 下載 contract
+
+**2. 驗證 contract**
+
+```javascript
+verifier.verifyProvider({
+  provider: 'UserService',
+  pactBrokerUrl: 'https://broker.example.com',
+  publishVerificationResult: true
+});
+```
+
+**3. State 設定** - 為每個互動設定 provider state
+
+## Pact Broker
+
+contract 的集中式儲存庫，具備以下功能：
+
+- Contract 儲存
+- 驗證狀態
+- 相依關係圖
+- Can-I-Deploy 檢查
+- 供 CI/CD 使用的 Webhook
+
+### Can-I-Deploy
+
+檢查部署是否安全：
+
+```bash
+pact-broker can-i-deploy \
+  --pacticipant UserService \
+  --version $(git rev-parse HEAD) \
+  --to production
+```
+
+## CI 整合
+
+### Consumer Pipeline
+
+```yaml
+stages:
+  - test:
+      - Run unit tests
+      - Run contract tests (generates pact)
+  - publish:
+      - Publish pact to broker
+  - can-i-deploy:
+      - Check deployment safety
+  - deploy:
+      - Deploy consumer
+```
+
+### Provider Pipeline
+
+```yaml
+stages:
+  - test:
+      - Run unit tests
+      - Verify consumer contracts
+  - publish:
+      - Publish verification results
+  - can-i-deploy:
+      - Check deployment safety
+  - deploy:
+      - Deploy provider
+```
+
+### GitHub Actions 範例
+
+```yaml
+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 }}
+```
+
+## 規則
+
+| 規則 | 說明 | 優先級 |
+|------|-------------|----------|
+| Consumer 優先 | 從 consumer 需求出發，而非 provider 實作 | 建議 |
+| 使用 matcher | 使用型別 matcher（like、eachLike）而非精確值 | 必要 |
+| Provider state | 為每個互動定義清楚的 provider state | 必要 |
+| 為 contract 加版本 | 以 consumer 版本與分支為 contract 加上標籤 | 必要 |
+| Can-I-Deploy | 一律在 CI/CD 中執行 can-i-deploy 檢查 | 必要 |
+| 破壞性變更 | 進行破壞性變更前先與 consumer 團隊協調 | 必要 |
+| 非同步 contract | 為非同步通訊納入 message contract | 建議 |
+
+## 快速參考
+
+### 工作流程
+
+| 步驟 | Consumer | Provider |
+|------|----------|----------|
+| 1. 定義 | 撰寫預期 | 實作 API |
+| 2. 測試 | 針對 mock 執行 | 驗證 contract |
+| 3. 發布 | 上傳 pact | 上傳結果 |
+| 4. 部署 | Can-I-Deploy | Can-I-Deploy |
+
+### 好處
+
+| 好處 | 說明 |
+|---------|-------------|
+| 快速回饋 | 不需要完整的整合環境 |
+| 解耦 | 團隊可以獨立作業 |
+| 安全部署 | Can-I-Deploy 防止破壞性變更 |
+| 活文件 | Contract 記錄了 API 行為 |
+
+## 相關選項
+
+- [Integration Testing](./integration-testing.md) - 元件整合測試
+- [E2E Testing](./e2e-testing.md) - 端對端測試
+
+---
+
+## 參考資料
+
+- [Pact Foundation](https://docs.pact.io/)
+- [Martin Fowler - Contract Test](https://martinfowler.com/bliki/ContractTest.html)
+- [Consumer-Driven Contracts](https://martinfowler.com/articles/consumerDrivenContracts.html)
+
+---
+
+## 授權
+
+本文件以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權釋出。
+
+**來源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-TW/options/testing/industry-pyramid.md

@@ -0,0 +1,200 @@
+---
+source: options/testing/industry-pyramid.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+# 業界測試金字塔
+
+> **語言**: [English](../../../../options/testing/industry-pyramid.md) | 繁體中文
+
+**上層標準**: [測試完整性](../../core/test-completeness-dimensions.md)
+
+---
+
+## 概觀
+
+業界測試金字塔是一套務實的 4 層測試模型，廣為敏捷與 DevOps 團隊採用。它強調透過大量的 unit test 取得快速回饋、適量的 integration test、用於子系統驗證的 system test，以及最少量的端對端測試。
+
+## 最適用於
+
+- 敏捷／Scrum 開發團隊
+- 以 CI/CD 為核心的環境
+- 中小型專案
+- DevOps 實務
+- 快速迭代循環
+
+## 金字塔
+
+```
+    ┌─────────┐
+    │   E2E   │  ←  3% (Slow, expensive)
+    ├─────────┤
+    │   ST    │  ←  7% (Medium speed)
+    ├─────────┤
+    │   IT    │  ← 20% (Fast)
+    ├─────────┤
+    │   UT    │  ← 70% (Very fast, many)
+    └─────────┘
+```
+
+**目標比例：** 70/20/7/3（UT/IT/ST/E2E）
+
+**注意：** 此為 Mike Cohn 的經驗性建議，並非強制標準。
+
+**理由：**
+- 較多 unit test = 更快的回饋
+- 較少 E2E test = 較低的維護成本
+- integration test 能捕捉介面問題
+- system test 在 stub 外部相依的情況下驗證子系統行為
+
+## 測試層級
+
+### 單元測試（UT）- 70%
+
+| 面向 | 細節 |
+|--------|---------|
+| **定義** | 針對個別函式、方法或類別的隔離測試 |
+| **範圍** | 單一函式／方法／類別 |
+| **速度** | 每個測試 < 100ms |
+| **相依** | 全部 mock |
+
+**特性：**
+- 執行快速
+- 結果具決定性
+- 無 I/O 操作
+- 測試單一行為單元
+
+### 整合測試（IT）- 20%
+
+| 面向 | 細節 |
+|--------|---------|
+| **定義** | 針對元件互動與資料流的測試 |
+| **範圍** | 多個元件相互作用 |
+| **速度** | 每個測試 < 1 秒 |
+| **相依** | 真實與 mock 混合 |
+
+**特性：**
+- 測試真實的整合
+- 可能使用容器（Testcontainers）
+- 驗證資料流
+
+### 系統測試（ST）- 7%
+
+| 面向 | 細節 |
+|--------|---------|
+| **定義** | 在 stub 外部相依的情況下測試完整子系統 |
+| **範圍** | 完整子系統驗證 |
+| **速度** | 每個測試 < 10 秒 |
+| **相依** | 真實內部服務、stub 外部 API |
+
+**特性：**
+- 端對端驗證子系統行為
+- stub 外部相依
+- 在 SIT 環境中測試
+
+### 端對端測試（E2E）- 3%
+
+| 面向 | 細節 |
+|--------|---------|
+| **定義** | 跨整個系統測試完整使用者工作流程 |
+| **範圍** | 從使用者視角的完整使用者流程 |
+| **速度** | 每個測試 30 秒至數分鐘 |
+| **相依** | 全部真實 |
+
+**特性：**
+- 模擬真實使用者行為
+- 僅測試關鍵路徑
+- 最高的維護成本
+
+## 覆蓋率目標
+
+| 指標 | 最低 | 建議 |
+|--------|---------|-------------|
+| 行覆蓋率（Line Coverage） | 70% | 85% |
+| 分支覆蓋率（Branch Coverage） | 60% | 80% |
+| 函式覆蓋率（Function Coverage） | 80% | 90% |
+
+## 各層級工具
+
+### 單元測試
+
+| 語言 | 工具 |
+|----------|-------|
+| JavaScript | Jest, Vitest, Mocha |
+| Python | pytest, unittest |
+| Java | JUnit, TestNG |
+| C# | xUnit, NUnit, MSTest |
+| Go | testing package, testify |
+
+### 整合測試
+
+| 語言 | 工具 |
+|----------|-------|
+| JavaScript | Supertest, Testcontainers |
+| Python | pytest, Testcontainers |
+| Java | Spring Boot Test, Testcontainers |
+| C# | WebApplicationFactory, Testcontainers |
+
+### E2E 測試
+
+| 語言 | 工具 |
+|----------|-------|
+| JavaScript | Playwright, Cypress, Puppeteer |
+| Python | Playwright, Selenium |
+| Java | Selenium, Playwright |
+
+## 何時選擇業界金字塔
+
+**選擇時機：**
+- 實踐敏捷／Scrum 方法論
+- CI/CD 管線至關重要
+- 快速回饋為優先
+- 團隊規模小且跨職能
+- 期望最少的文件負擔
+
+**避免時機：**
+- 需要正式 QA 認證
+- 企業合規需求
+- 專責 QA 團隊偏好 ISTQB
+- 需要稽核文件
+
+## 與 ISTQB 的比較
+
+| 業界層級 | ISTQB 對應 | 注意 |
+|----------------|------------------|------|
+| 單元測試（UT） | Component Testing | 概念相同 |
+| 整合測試（IT） | Integration Testing | 概念相同 |
+| 系統測試（ST） | System Testing | 概念相同 |
+| E2E 測試 | Acceptance Testing | 業界 E2E ≈ ISTQB Acceptance |
+
+## 規則
+
+| 規則 | 描述 | 優先級 |
+|------|-------------|----------|
+| 遵循金字塔比例 | UT/IT/ST/E2E 目標 70/20/7/3 比例（經驗性，非強制） | Required |
+| 在最低層級測試 | 在能提供信心的最低層級撰寫測試 | Recommended |
+| 邊界情況避免用 E2E | 邊界情況使用 unit test，而非 E2E | Recommended |
+| 邊界用整合測試 | 使用 integration test 驗證介面合約 | Recommended |
+
+## 相關選項
+
+- [ISTQB 框架](./istqb-framework.md) - 正式的 4 層測試框架
+- [單元測試](./unit-testing.md) - 詳細的單元測試實務
+- [整合測試](./integration-testing.md) - 整合測試實務
+- [E2E 測試](./e2e-testing.md) - 端對端測試實務
+
+---
+
+## 參考資料
+
+- [Martin Fowler's Testing Pyramid](https://martinfowler.com/bliki/TestPyramid.html)
+- [Google Testing Blog](https://testing.googleblog.com)
+
+---
+
+## 授權
+
+本文件以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權釋出。
+
+**來源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)