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

package/bundled/locales/zh-CN/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-CN/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-CN/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-CN/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)