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

package/bundled/locales/zh-CN/skills/claude-code/git-workflow-guide/git-workflow.md

@@ -0,0 +1,321 @@
+---
+source: ../../../../../skills/claude-code/git-workflow-guide/git-workflow.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2025-12-25
+status: current
+---
+
+# Git 工作流程策略
+
+> **语言**: [English](../../../../../skills/claude-code/git-workflow-guide/git-workflow.md) | 简体中文
+
+**版本**: 1.0.0
+**最後更新**: 2025-12-24
+**適用範圍**: Claude Code Skills
+
+---
+
+## 目的
+
+本文件提供 Git 工作流程策略（GitFlow、GitHub Flow、Trunk-Based）的详细指南。
+
+---
+
+## 策略选择矩陣
+
+| 因素 | GitFlow | GitHub Flow | Trunk-Based |
+|------|---------|-------------|-------------|
+| **發布頻率** | 每月以上 | 每周 | 每天多次 |
+| **团队規模** | 大型 (10+) | 中型 (5-15) | 小到中型 (3-10) |
+| **CI/CD 成熟度** | 基本 | 中等 | 进阶 |
+| **功能旗標** | 可選 | 可選 | 必需 |
+| **複雜度** | 高 | 低 | 中 |
+
+---
+
+## 策略 A: GitFlow
+
+**最適合**: 定期發布、多个正式版本、大型团队
+
+### 分支结构
+
+```
+main          ─●────────●─────────●── (Production: v1.0, v2.0)
+               ╱          ╲         ╲
+develop   ────●────●──────●─────────●── (Development)
+             ╱      ╲      ╲
+feature/*  ─●────────●      ╲  (Features)
+                              ╲
+release/*                      ●───● (Release prep)
+                                   ╱
+hotfix/*                      ────● (Emergency fixes)
+```
+
+### 分支类型
+
+| 分支 | 目的 | 基礎 | 合併至 | 生命周期 |
+|------|------|------|--------|---------|
+| `main` | 正式程序码 | - | - | 永久 |
+| `develop` | 集成 | - | - | 永久 |
+| `feature/*` | 新功能 | `develop` | `develop` | 暫时 |
+| `release/*` | 發布准备 | `develop` | `main` + `develop` | 暫时 |
+| `hotfix/*` | 緊急修復 | `main` | `main` + `develop` | 暫时 |
+
+### 功能开发流程
+
+```bash
+# 從 develop 建立
+git checkout develop
+git pull origin develop
+git checkout -b feature/oauth-login
+
+# 工作并提交
+git add .
+git commit -m "feat(auth): add OAuth2 login"
+git push -u origin feature/oauth-login
+
+# PR 核准後，合併至 develop
+git checkout develop
+git merge --no-ff feature/oauth-login
+git push origin develop
+
+# 刪除功能分支
+git branch -d feature/oauth-login
+git push origin --delete feature/oauth-login
+```
+
+### 發布流程
+
+```bash
+# 建立發布分支
+git checkout develop
+git checkout -b release/v1.2.0
+
+# 准备發布（提升版本、更新变更日誌）
+npm version 1.2.0
+git add package.json CHANGELOG.md
+git commit -m "chore(release): prepare v1.2.0"
+
+# 合併至 main
+git checkout main
+git merge --no-ff release/v1.2.0
+git tag -a v1.2.0 -m "Release v1.2.0"
+git push origin main --tags
+
+# 合併回 develop
+git checkout develop
+git merge --no-ff release/v1.2.0
+git push origin develop
+
+# 刪除發布分支
+git branch -d release/v1.2.0
+```
+
+### 緊急修復流程
+
+```bash
+# 從 main 建立
+git checkout main
+git checkout -b hotfix/critical-fix
+
+# 修復并提交
+git add .
+git commit -m "fix(security): patch vulnerability"
+
+# 合併至 main
+git checkout main
+git merge --no-ff hotfix/critical-fix
+git tag -a v1.2.1 -m "Hotfix v1.2.1"
+git push origin main --tags
+
+# 合併至 develop
+git checkout develop
+git merge --no-ff hotfix/critical-fix
+git push origin develop
+```
+
+---
+
+## 策略 B: GitHub Flow
+
+**最適合**: 持續部署、网页应用程序、小到中型团队
+
+### 分支结构
+
+```
+main      ────●─────────●──────●── (Always deployable)
+               ╲         ╱      ╱
+feature/*       ●───●───●      ╱
+                              ╱
+bugfix/*                 ────●
+```
+
+### 分支类型
+
+| 分支 | 目的 | 基礎 | 合併至 | 生命周期 |
+|------|------|------|--------|---------|
+| `main` | 正式版本 | - | - | 永久 |
+| `feature/*` | 功能 | `main` | `main` | 暫时 |
+| `bugfix/*` | 错误修復 | `main` | `main` | 暫时 |
+
+### 工作流程
+
+```bash
+# 1. 從 main 建立
+git checkout main
+git pull origin main
+git checkout -b feature/user-profile
+
+# 2. 工作并推送
+git add .
+git commit -m "feat(profile): add avatar"
+git push -u origin feature/user-profile
+
+# 3. 透過 GitHub/GitLab UI 開啟 PR 至 main
+
+# 4. 核准且 CI 通過後，合併（建议使用 squash）
+
+# 5. 將 main 部署至正式環境
+
+# 6. 刪除分支（自动或手动）
+```
+
+### 关鍵原則
+
+1. `main` **永遠可部署**
+2. 從 `main` 分支
+3. 透過 PR 合併至 `main`
+4. 合併後立即部署
+
+---
+
+## 策略 C: Trunk-Based Development
+
+**最適合**: 成熟的 CI/CD、高度信任的团队、頻繁集成
+
+### 分支结构
+
+```
+main  ────●─●─●─●─●─●─●──► (Single trunk)
+           ╲│╱ ╲│╱ ╲│╱
+feature/*   ●   ●   ●  (Very short-lived, ≤2 days)
+```
+
+### 分支类型
+
+| 分支 | 目的 | 基礎 | 合併至 | 生命周期 |
+|------|------|------|--------|---------|
+| `main` | 主幹 | - | - | 永久 |
+| `feature/*` | 小变更 | `main` | `main` | ≤2 天 |
+
+### 工作流程
+
+```bash
+# 1. 建立短期分支
+git checkout main
+git pull origin main
+git checkout -b feature/add-validation
+
+# 2. 小型、原子性变更
+git add .
+git commit -m "feat(validation): add email check"
+git push -u origin feature/add-validation
+
+# 3. 快速 PR 并合併（當天完成）
+git checkout main
+git pull origin main
+git rebase main feature/add-validation
+git checkout main
+git merge --ff-only feature/add-validation
+git push origin main
+
+# 4. 立即刪除
+git branch -d feature/add-validation
+```
+
+### 关鍵原則
+
+1. **每天集成多次**
+2. 分支生命周期 **≤2 天**
+3. 使用 **功能旗標** 处理未完成的功能
+4. **一切自动化**
+
+---
+
+## 合併策略比較
+
+### Merge Commit (`--no-ff`)
+
+```bash
+git merge --no-ff feature/user-auth
+```
+
+**優点**: 完整历史、易於还原功能
+**缺点**: 複雜的 git log
+**最適合**: GitFlow、長期功能
+
+### Squash Merge
+
+```bash
+git merge --squash feature/user-auth
+git commit -m "feat(auth): add user authentication"
+```
+
+**優点**: 乾淨历史、每个功能一个 commit
+**缺点**: 失去详细历史
+**最適合**: GitHub Flow、功能 PR
+
+### Rebase + Fast-Forward
+
+```bash
+git rebase main feature/user-auth
+git checkout main
+git merge --ff-only feature/user-auth
+```
+
+**優点**: 线性历史、保留 commit
+**缺点**: 重写历史
+**最適合**: Trunk-Based、短期分支
+
+---
+
+## 受保護分支建议
+
+### 針对 `main`
+
+- ✅ 需要 pull request 审查（1-2 人）
+- ✅ 需要状态检查（CI、测试、lint）
+- ✅ 需要分支保持最新
+- ❌ 不允許強制推送
+- ❌ 不允許刪除
+
+### 針对 `develop` (GitFlow)
+
+- ✅ 需要 pull request 审查（1 人）
+- ✅ 需要状态检查
+- ❌ 不允許強制推送
+
+---
+
+## 相关标准
+
+- [Git Workflow](../../../../../core/git-workflow.md)
+- [分支命名參考](./branch-naming.md)
+- [Commit 消息指南](../../../../../core/commit-message-guide.md)
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 1.0.0 | 2025-12-24 | 新增：标准章节（目的、相关标准、版本历史、授权） |
+
+---
+
+## 授权
+
+本文件以 [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/skills/claude-code/logging-guide/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: logging-guide
+description: |
+  实作结构化日誌，包含正确的日誌层级和敏感数据处理。
+  使用时机：新增日誌、除錯、设置可觀测性。
+  关鍵字：logging, log level, structured logging, observability, 日誌, 记录, 结构化日誌。
+source: ../../../../../skills/claude-code/logging-guide/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-01-08
+status: current
+---
+
+# 日誌指南
+
+> **语言**: [English](../../../../../skills/claude-code/logging-guide/SKILL.md) | 简体中文
+
+**版本**: 1.0.0
+**最後更新**: 2025-12-30
+**適用範圍**: Claude Code Skills
+
+---
+
+## 目的
+
+此技能幫助在所有環境中实作一致、结构化且可操作的应用程序日誌。
+
+## 快速參考
+
+### 日誌层级
+
+| 层级 | 代码 | 使用时机 | 生产環境 |
+|------|------|----------|----------|
+| **TRACE** | 10 | 非常详细的除錯信息 | 关閉 |
+| **DEBUG** | 20 | 详细的除錯信息 | 关閉 |
+| **INFO** | 30 | 正常操作事件 | 開啟 |
+| **WARN** | 40 | 潛在問題，可恢復 | 開啟 |
+| **ERROR** | 50 | 需要注意的错误 | 開啟 |
+| **FATAL** | 60 | 嚴重故障 | 開啟 |
+
+### 层级选择决策樹
+
+```
+只用於除錯？               → DEBUG（生产環境关閉）
+正常操作完成？             → INFO
+意外但没問題的情况？       → WARN
+操作失败？                 → ERROR
+应用程序無法繼續？         → FATAL
+```
+
+### 各层级使用时机
+
+| 层级 | 範例 |
+|------|------|
+| **TRACE** | 函式进入/離開、回圈迭代、变數值 |
+| **DEBUG** | 状态变更、设置值、查詢參數 |
+| **INFO** | 应用啟动/关閉、使用者操作、排程任务 |
+| **WARN** | 已棄用 API、重試嘗試、資源接近上限 |
+| **ERROR** | 失败的操作、捕獲的例外、集成失败 |
+| **FATAL** | 無法恢復的错误、啟动失败、失去关鍵資源 |
+
+## 结构化日誌
+
+### 必要欄位
+
+```json
+{
+  "timestamp": "2025-01-15T10:30:00.123Z",
+  "level": "INFO",
+  "message": "使用者登入成功",
+  "service": "auth-service",
+  "environment": "production"
+}
+```
+
+### 建议欄位
+
+```json
+{
+  "timestamp": "2025-01-15T10:30:00.123Z",
+  "level": "INFO",
+  "message": "使用者登入成功",
+  "service": "auth-service",
+  "environment": "production",
+  "trace_id": "abc123",
+  "span_id": "def456",
+  "user_id": "usr_12345",
+  "request_id": "req_67890",
+  "duration_ms": 150,
+  "http_method": "POST",
+  "http_path": "/api/v1/login",
+  "http_status": 200
+}
+```
+
+### 欄位命名慣例
+
+使用 `snake_case` 并加上領域前綴：
+
+| 領域 | 常用欄位 |
+|------|----------|
+| HTTP | http_method, http_path, http_status, http_duration_ms |
+| 数据庫 | db_query_type, db_table, db_duration_ms, db_rows_affected |
+| 佇列 | queue_name, queue_message_id, queue_delay_ms |
+| 使用者 | user_id, user_role, user_action |
+| 请求 | request_id, trace_id, span_id |
+
+## 详细指南
+
+完整标准請參考：
+- [日誌标准](../../../core/logging-standards.md)
+
+### AI 優化格式（节省 Token）
+
+AI 助手可使用 YAML 格式文件以減少 Token 使用量：
+- 基礎标准：`ai/standards/logging.ai.yaml`
+
+## 敏感数据处理
+
+### 絕对不要记录
+
+- 密码或机密
+- API 金鑰或 Token
+- 信用卡号码
+- 身分证字号
+- 完整的认证 Token
+
+### 遮罩或编修
+
+```javascript
+// 不好
+logger.info('登入嘗試', { password: userPassword });
+
+// 好
+logger.info('登入嘗試', { password: '***已编修***' });
+
+// 好 - 部分遮罩
+logger.info('卡片已处理', { last_four: '4242' });
+```
+
+### PII 处理
+
+- 盡可能记录使用者 ID 而非電子郵件
+- 对敏感查詢使用雜湊識别码
+- 设置数据保留政策
+
+## 错误日誌
+
+### 必要的错误欄位
+
+```json
+{
+  "level": "ERROR",
+  "message": "数据庫連线失败",
+  "error_type": "ConnectionError",
+  "error_message": "連线被拒絕",
+  "error_code": "ECONNREFUSED",
+  "stack": "Error: Connection refused\n    at connect (/app/db.js:45:11)..."
+}
+```
+
+### 错误上下文
+
+务必包含：
+- 嘗試的操作是什麼
+- 相关識别码（user_id, request_id）
+- 输入參數（已清理）
+- 重試次數（如適用）
+
+```javascript
+logger.error('处理订单失败', {
+  error_type: err.name,
+  error_message: err.message,
+  order_id: orderId,
+  user_id: userId,
+  retry_count: 2,
+  stack: err.stack
+});
+```
+
+## 日誌格式
+
+### JSON 格式（生产環境）
+
+```json
+{"timestamp":"2025-01-15T10:30:00.123Z","level":"INFO","message":"请求完成","request_id":"req_123","duration_ms":45}
+```
+
+### 人类可读格式（开发環境）
+
+```
+2025-01-15T10:30:00.123Z [INFO] 请求完成 request_id=req_123 duration_ms=45
+```
+
+## 效能考量
+
+### 各環境的日誌量
+
+| 環境 | 层级 | 策略 |
+|------|------|------|
+| 开发 | DEBUG | 所有日誌 |
+| 测试 | INFO | 大部分日誌 |
+| 生产 | INFO | 高流量端点採样 |
+
+### 高流量端点
+
+- 使用採样（每 100 筆记录 1 筆）
+- 聚合指標而非个别日誌
+- 使用獨立的日誌串流
+
+## 检查清单
+
+### 必要欄位
+
+- [ ] timestamp（ISO 8601）
+- [ ] level
+- [ ] message
+- [ ] service name
+- [ ] request_id 或 trace_id
+
+### 安全性
+
+- [ ] 没有密码或机密
+- [ ] 没有完整 Token
+- [ ] PII 已遮罩或雜湊
+- [ ] 信用卡從不记录
+- [ ] 保留政策已设置
+
+---
+
+## 设置偵测
+
+此技能支援项目特定设置。
+
+### 偵测順序
+
+1. 检查現有的日誌程序庫设置
+2. 检查 `CONTRIBUTING.md` 中的日誌指南
+3. 若無找到，**预设使用结构化 JSON 日誌**
+
+### 首次设置
+
+若未找到日誌标准：
+
+1. 建议：「此项目尚未设置日誌标准。您要设置结构化日誌嗎？」
+2. 建议在 `CONTRIBUTING.md` 中记录：
+
+```markdown
+## 日誌标准
+
+### 日誌层级
+- DEBUG: 僅开发環境，详细診斷信息
+- INFO: 正常操作（啟动、使用者操作、任务）
+- WARN: 意外但可恢復的情况
+- ERROR: 需要調查的失败
+
+### 必要欄位
+所有日誌必須包含：timestamp, level, message, service, request_id
+
+### 敏感数据
+絕不记录：密码、Token、信用卡、身分证字号
+```
+
+---
+
+## 相关标准
+
+- [日誌标准](../../../core/logging-standards.md)
+- [错误码标准](../../../core/error-code-standards.md)
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 1.0.0 | 2025-12-30 | 初始發布 |
+
+---
+
+## 授权
+
+此技能採用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权。
+
+**來源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)