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

package/bundled/locales/zh-TW/options/git-workflow/squash-merge.md

@@ -0,0 +1,117 @@
+---
+source: ../../../../options/git-workflow/squash-merge.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2025-12-30
+status: current
+---
+
+# Squash Merge 合併策略
+
+> **語言**: [English](../../../../options/git-workflow/squash-merge.md) | 繁體中文
+
+**上層標準**: [Git 工作流程](../../core/git-workflow.md)
+
+---
+
+## 概述
+
+Squash merge 在合併時將功能分支的所有 commit 壓縮成單一 commit。這在主分支上建立乾淨、線性的歷史，每個合併代表一個完整的功能或變更。
+
+## 適用情境
+
+- 重視主分支歷史整潔的團隊
+- 開發過程中有許多小型 commit 的專案
+- 程式碼審查流程中最終結果比過程重要
+- 接受外部貢獻的開源專案
+
+## 運作方式
+
+```
+功能分支：              合併後的 main 分支：
+A---B---C---D            X---Y---Z（單一壓縮 commit）
+    \                        |
+     E---F---G---H    →      S（包含 E+F+G+H）
+    （功能 commits）
+```
+
+## 工作流程
+
+### 透過 CLI 進行 Squash Merge
+
+```bash
+# 切到 main 分支
+git checkout main
+git pull origin main
+
+# Squash merge
+git merge --squash feature/user-profile
+
+# 建立有意義的單一 commit
+git commit -m "feat(users): add user profile with avatar upload
+
+- Add profile page component
+- Implement avatar upload functionality
+- Add comprehensive test coverage
+
+Closes #123"
+
+# 推送並清理
+git push origin main
+git branch -d feature/user-profile
+git push origin --delete feature/user-profile
+```
+
+### 透過 GitHub 進行
+
+1. 開啟 Pull Request
+2. 點擊「Squash and merge」按鈕
+3. 編輯 commit 訊息使其有意義
+4. 確認合併
+5. 刪除功能分支
+
+## Commit 訊息最佳實踐
+
+進行 squash merge 時，撰寫完整的 commit 訊息：
+
+```
+feat(scope): 簡潔描述
+
+- 主要變更 1
+- 主要變更 2
+- 主要變更 3
+
+Closes #issue-number
+Co-authored-by: Name <email@example.com>
+```
+
+## 優點
+
+| 優點 | 說明 |
+|------|------|
+| 乾淨的歷史 | 主分支每個功能一個 commit |
+| 容易還原 | 單一 commit 還原整個功能 |
+| 簡化 bisect | 較少 commit 需要搜尋 |
+| 自由提交 | 開發者可頻繁提交不會雜亂 |
+
+## 缺點
+
+| 缺點 | 說明 |
+|------|------|
+| 失去細節 | 個別 commit 歷史遺失 |
+| 難以追蹤 | 無法追溯特定行到原始 commit |
+| 大型 diff | 單一 commit 可能有大量變更 |
+| 失去脈絡 | 開發過程不被保留 |
+
+## 相關選項
+
+- [Merge Commit](./merge-commit.md) - 保留所有 commit 歷史
+- [Rebase and Fast-Forward](./rebase-ff.md) - 線性歷史保留所有 commit
+
+---
+
+## 授權條款
+
+本文件採用 [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/git-workflow/trunk-based.md

@@ -0,0 +1,125 @@
+---
+source: ../../../../options/git-workflow/trunk-based.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2025-12-30
+status: current
+---
+
+# Trunk-Based 開發
+
+> **語言**: [English](../../../../options/git-workflow/trunk-based.md) | 繁體中文
+
+**上層標準**: [Git 工作流程](../../core/git-workflow.md)
+
+---
+
+## 概述
+
+Trunk-Based 開發是一種版本控制管理實踐，所有開發者在單一分支（稱為「trunk」或「main」）上進行小型、頻繁的更新。它最大化持續整合，減少合併問題。
+
+## 適用情境
+
+- 經驗豐富的團隊
+- 強大的 CI/CD 基礎設施
+- 需要快速發布週期
+- 高度自動化測試環境
+
+## 核心原則
+
+| 原則 | 說明 |
+|------|------|
+| 單一主分支 | 所有開發在 main/trunk 進行 |
+| 小型提交 | 頻繁提交小變更 |
+| 功能標誌 | 使用 feature flags 控制功能 |
+| 持續整合 | 頻繁合併到主分支 |
+
+## 工作流程
+
+### 直接在 trunk 工作
+
+```bash
+# 更新本地 main
+git checkout main
+git pull origin main
+
+# 進行小型變更
+git add .
+git commit -m "feat: add user avatar display"
+git push origin main
+```
+
+### 短期功能分支（可選）
+
+```bash
+# 建立短期分支（最長 1-2 天）
+git checkout -b feat/quick-change
+# 進行變更
+git checkout main
+git merge feat/quick-change
+git push origin main
+git branch -d feat/quick-change
+```
+
+## 功能標誌
+
+使用功能標誌在生產環境控制未完成功能：
+
+```javascript
+// 功能標誌範例
+if (featureFlags.isEnabled('new-checkout-flow')) {
+  return <NewCheckoutFlow />;
+} else {
+  return <LegacyCheckoutFlow />;
+}
+```
+
+### 功能標誌類型
+
+| 類型 | 用途 | 生命週期 |
+|------|------|----------|
+| 發布標誌 | 隱藏未完成功能 | 短期 |
+| 實驗標誌 | A/B 測試 | 中期 |
+| 權限標誌 | 功能存取控制 | 長期 |
+| 營運標誌 | 系統行為控制 | 長期 |
+
+## 前提條件
+
+使用 Trunk-Based 開發需要：
+
+1. **全面的自動化測試**
+2. **快速的 CI/CD 管線**
+3. **程式碼審查文化**
+4. **功能標誌系統**
+5. **即時監控能力**
+
+## 優點
+
+| 優點 | 說明 |
+|------|------|
+| 最少合併衝突 | 頻繁整合減少衝突 |
+| 持續整合 | 真正的 CI 實踐 |
+| 快速反饋 | 問題快速浮現 |
+| 簡化分支管理 | 無複雜分支策略 |
+
+## 缺點
+
+| 缺點 | 說明 |
+|------|------|
+| 需要高度紀律 | 團隊必須遵守規則 |
+| 需要強大的 CI | 測試和建置必須快速 |
+| 功能標誌複雜性 | 需要管理標誌生命週期 |
+| 不適合新手團隊 | 需要經驗和信任 |
+
+## 相關選項
+
+- [GitHub Flow](./github-flow.md) - 帶有 PR 的簡化流程
+- [GitFlow](./gitflow.md) - 適合有排程發布的專案
+
+---
+
+## 授權條款
+
+本文件採用 [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/project-structure/dotnet.md

@@ -0,0 +1,183 @@
+---
+source: ../../../../options/project-structure/dotnet.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2025-12-30
+status: current
+---
+
+# .NET 專案結構
+
+> **語言**: [English](../../../../options/project-structure/dotnet.md) | 繁體中文
+
+**上層標準**: [專案結構](../../core/project-structure.md)
+
+---
+
+## 概述
+
+本文件定義遵循 Clean Architecture 原則的 .NET/C# 專案標準目錄結構。它促進關注點分離，相依性指向核心領域。
+
+## 適用情境
+
+- ASP.NET Core Web API
+- 企業級應用程式
+- 微服務
+- 領域驅動設計專案
+- 大型應用程式
+
+## 目錄結構
+
+```
+SolutionName/
+├── src/
+│   ├── SolutionName.Api/           # Web API 專案
+│   │   ├── Controllers/
+│   │   ├── Middleware/
+│   │   ├── Filters/
+│   │   ├── Program.cs
+│   │   └── appsettings.json
+│   ├── SolutionName.Core/          # 核心業務邏輯
+│   │   ├── Entities/
+│   │   ├── Interfaces/
+│   │   ├── Services/
+│   │   └── Exceptions/
+│   ├── SolutionName.Infrastructure/ # 外部服務實作
+│   │   ├── Data/
+│   │   │   ├── ApplicationDbContext.cs
+│   │   │   └── Migrations/
+│   │   ├── Repositories/
+│   │   └── ExternalServices/
+│   └── SolutionName.Shared/        # 共用程式碼
+│       ├── DTOs/
+│       ├── Extensions/
+│       └── Utils/
+├── tests/
+│   ├── SolutionName.UnitTests/
+│   ├── SolutionName.IntegrationTests/
+│   └── SolutionName.FunctionalTests/
+├── docs/
+├── SolutionName.sln
+└── README.md
+```
+
+## Clean Architecture 層次
+
+```
+┌─────────────────────────────────────────┐
+│              API 層                      │
+│  Controllers, Middleware, Filters        │
+├─────────────────────────────────────────┤
+│         Infrastructure 層                │
+│  DbContext, Repositories, External APIs  │
+├─────────────────────────────────────────┤
+│             Core 層                      │
+│  Entities, Services, Interfaces          │
+└─────────────────────────────────────────┘
+        相依性指向內部 ↓
+```
+
+## 命名慣例
+
+| 類型 | 慣例 | 範例 |
+|------|------|------|
+| 檔案 | PascalCase.cs | `UserService.cs` |
+| 目錄 | PascalCase | `Controllers/` |
+| 類別 | PascalCase | `UserService` |
+| 介面 | IPascalCase | `IUserService` |
+| 方法 | PascalCase | `CreateUser()` |
+| 私有欄位 | _camelCase | `_userRepository` |
+
+## 層次結構
+
+### Core 層（領域）
+
+```csharp
+// src/SolutionName.Core/Entities/User.cs
+namespace SolutionName.Core.Entities;
+
+public class User
+{
+    public Guid Id { get; private set; }
+    public string Email { get; private set; } = string.Empty;
+    public string Name { get; private set; } = string.Empty;
+
+    public static User Create(string email, string name)
+    {
+        return new User
+        {
+            Id = Guid.NewGuid(),
+            Email = email,
+            Name = name
+        };
+    }
+}
+```
+
+```csharp
+// src/SolutionName.Core/Interfaces/IUserRepository.cs
+public interface IUserRepository
+{
+    Task<User?> GetByIdAsync(Guid id, CancellationToken ct = default);
+    Task<User> AddAsync(User user, CancellationToken ct = default);
+}
+```
+
+### API 層
+
+```csharp
+// src/SolutionName.Api/Controllers/UsersController.cs
+[ApiController]
+[Route("api/[controller]")]
+public class UsersController : ControllerBase
+{
+    private readonly IUserService _userService;
+
+    public UsersController(IUserService userService)
+    {
+        _userService = userService;
+    }
+
+    [HttpPost]
+    [ProducesResponseType(typeof(UserDto), StatusCodes.Status201Created)]
+    public async Task<IActionResult> CreateUser(
+        [FromBody] CreateUserRequest request,
+        CancellationToken ct)
+    {
+        var user = await _userService.CreateUserAsync(request, ct);
+        return CreatedAtAction(nameof(GetUser), new { id = user.Id }, user.ToDto());
+    }
+}
+```
+
+## 專案參考
+
+| 專案 | 可參考 |
+|------|--------|
+| Api | Infrastructure, Core, Shared |
+| Infrastructure | Core, Shared |
+| Core | 僅 Shared（無外部相依）|
+| Shared | 無 |
+
+## 最佳實踐
+
+1. **相依性指向內部** - Core 無外部相依
+2. **使用介面** - 在 Core 定義，在 Infrastructure 實作
+3. **建構子注入** - 永遠使用 DI
+4. **可為空參考類型** - 啟用並強制執行
+5. **全程非同步** - 使用 CancellationToken
+
+## 相關選項
+
+- [Node.js](./nodejs.md) - Node.js 專案結構
+- [Python](./python.md) - Python 專案結構
+- [Java](./java.md) - Java/Spring 專案結構
+- [Go](./go.md) - Go 專案結構
+
+---
+
+## 授權條款
+
+本文件採用 [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/project-structure/go.md

@@ -0,0 +1,226 @@
+---
+source: ../../../../options/project-structure/go.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2025-12-30
+status: current
+---
+
+# Go 專案結構
+
+> **語言**: [English](../../../../options/project-structure/go.md) | 繁體中文
+
+**上層標準**: [專案結構](../../core/project-structure.md)
+
+---
+
+## 概述
+
+本文件定義遵循社群最佳實踐的 Go 專案標準目錄結構。它在簡單性和可擴展性之間取得平衡，適用於小型服務和大型應用程式。
+
+## 適用情境
+
+- HTTP 服務和 API
+- CLI 應用程式
+- 微服務
+- 系統工具
+- 函式庫和套件
+
+## 目錄結構
+
+```
+project-root/
+├── cmd/                      # 應用程式進入點
+│   ├── api/
+│   │   └── main.go
+│   └── cli/
+│       └── main.go
+├── internal/                 # 私有應用程式碼
+│   ├── config/
+│   │   └── config.go
+│   ├── domain/               # 業務邏輯
+│   │   ├── user/
+│   │   │   ├── user.go
+│   │   │   ├── service.go
+│   │   │   ├── repository.go
+│   │   │   └── service_test.go
+│   │   └── product/
+│   ├── handler/              # HTTP 處理器
+│   │   ├── user_handler.go
+│   │   └── middleware/
+│   ├── repository/           # 資料存取實作
+│   │   ├── postgres/
+│   │   └── redis/
+│   └── server/
+│       └── server.go
+├── pkg/                      # 公開可重用套件
+│   └── validator/
+│       └── validator.go
+├── api/                      # API 規格
+│   └── openapi.yaml
+├── scripts/                  # 建置/部署腳本
+├── docs/                     # 文件
+├── go.mod
+├── go.sum
+├── Makefile
+└── README.md
+```
+
+## 命名慣例
+
+| 類型 | 慣例 | 範例 |
+|------|------|------|
+| 檔案 | snake_case.go | `user_service.go` |
+| 套件 | lowercase | `user`, `httphandler` |
+| 匯出 | PascalCase | `UserService`, `CreateUser` |
+| 未匯出 | camelCase | `userRepository`, `validateEmail` |
+| 常數 | PascalCase 或 ALL_CAPS | `MaxRetries`, `DB_TIMEOUT` |
+| 介面 | PascalCase + "er" 後綴 | `Reader`, `UserRepository` |
+
+## 關鍵目錄
+
+### cmd/
+
+應用程式進入點。每個子目錄是一個獨立的二進位檔案：
+
+```go
+// cmd/api/main.go
+package main
+
+import (
+    "log"
+    "myproject/internal/config"
+    "myproject/internal/server"
+)
+
+func main() {
+    cfg, err := config.Load()
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    srv := server.New(cfg)
+    if err := srv.Run(); err != nil {
+        log.Fatal(err)
+    }
+}
+```
+
+### internal/
+
+無法被其他專案匯入的私有程式碼。
+
+### pkg/
+
+可被其他專案匯入的公開套件。
+
+## 領域層
+
+### 實體
+
+```go
+// internal/domain/user/user.go
+package user
+
+import (
+    "errors"
+    "time"
+)
+
+var (
+    ErrInvalidEmail = errors.New("invalid email format")
+    ErrUserNotFound = errors.New("user not found")
+    ErrEmailExists  = errors.New("email already exists")
+)
+
+type User struct {
+    ID        string
+    Email     string
+    Name      string
+    CreatedAt time.Time
+}
+
+func NewUser(email, name string) (*User, error) {
+    if !isValidEmail(email) {
+        return nil, ErrInvalidEmail
+    }
+    return &User{
+        Email:     email,
+        Name:      name,
+        CreatedAt: time.Now(),
+    }, nil
+}
+```
+
+### Repository 介面
+
+```go
+// internal/domain/user/repository.go
+package user
+
+import "context"
+
+type Repository interface {
+    Create(ctx context.Context, user *User) error
+    GetByID(ctx context.Context, id string) (*User, error)
+    GetByEmail(ctx context.Context, email string) (*User, error)
+}
+```
+
+### 服務
+
+```go
+// internal/domain/user/service.go
+package user
+
+import "context"
+
+type Service struct {
+    repo Repository
+}
+
+func NewService(repo Repository) *Service {
+    return &Service{repo: repo}
+}
+
+func (s *Service) CreateUser(ctx context.Context, input CreateUserInput) (*User, error) {
+    existing, _ := s.repo.GetByEmail(ctx, input.Email)
+    if existing != nil {
+        return nil, ErrEmailExists
+    }
+
+    user, err := NewUser(input.Email, input.Name)
+    if err != nil {
+        return nil, err
+    }
+
+    if err := s.repo.Create(ctx, user); err != nil {
+        return nil, err
+    }
+    return user, nil
+}
+```
+
+## 最佳實踐
+
+1. **接受介面，回傳結構**
+2. **保持 `main.go` 最小化** - 連接相依性，呼叫 `Run()`
+3. **使用 `internal/` 存放私有程式碼**
+4. **在使用處定義介面** - 而非實作處
+5. **錯誤包裝** - 使用 `fmt.Errorf("context: %w", err)`
+6. **Context 傳播** - 所有層都傳遞 context
+
+## 相關選項
+
+- [Node.js](./nodejs.md) - Node.js 專案結構
+- [Python](./python.md) - Python 專案結構
+- [.NET](./dotnet.md) - .NET/C# 專案結構
+- [Java](./java.md) - Java/Spring 專案結構
+
+---
+
+## 授權條款
+
+本文件採用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權條款。
+
+**來源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)