universal-dev-standards 4.2.0 → 5.0.0-beta.10

package/bundled/locales/zh-CN/core/documentation-writing-standards.md

@@ -1,8 +1,8 @@
 ---
 source: ../../../core/documentation-writing-standards.md
-source_version: 1.0.1
-translation_version: 1.0.1
-last_synced: 2025-12-30
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-01-24
 status: current
 ---
 
@@ -469,11 +469,142 @@ project-root/
 |---------|-------|
 | Markdown 编辑 | VS Code + Markdown Preview Enhanced |
 | 图表绘制 | Mermaid / draw.io / PlantUML |
-| API 文件 | OpenAPI (Swagger) / Redoc |
+| API 文档 | OpenAPI (Swagger) / Redoc |
 | ER 图 | dbdiagram.io / DBeaver |
 
 ---
 
+## AI 协作文档
+
+### Token 感知设计
+
+为 AI 助手优化文档结构：
+
+**原则**:
+
+| 原则 | 说明 |
+|------|------|
+| **前置重要信息** | 关键信息放在文档开头 |
+| **结构化数据** | 使用表格、列表、代码块 |
+| **明确标记** | 使用清晰的章节标题 |
+| **避免冗余** | 减少重复内容 |
+
+**AI 友好文档模式**:
+
+```markdown
+---
+# YAML 前置元数据（AI 可解析）
+title: API 端点文档
+version: 2.0.0
+last_updated: 2026-01-24
+ai_summary: 用户认证 API，支持 OAuth2
+---
+
+<!-- AI-SECTION-START: quick-reference -->
+## 快速参考
+[最常用的信息放这里]
+<!-- AI-SECTION-END: quick-reference -->
+
+<!-- AI-SECTION-START: details -->
+## 详细说明
+[完整详情放这里]
+<!-- AI-SECTION-END: details -->
+```
+
+### 为 AI 代码生成撰写
+
+撰写 AI 可用于生成代码的文档：
+
+**范例 - 好的 AI 提示友好文档**:
+
+```markdown
+## 创建用户 API
+
+### 约束条件
+- 用户名：3-20 字符，仅字母数字
+- 邮箱：必须唯一
+- 密码：最少 8 字符，需含数字
+
+### 成功响应
+返回 HTTP 201 和用户对象（不含密码）
+
+### 错误情况
+- 409: 邮箱已存在
+- 400: 验证失败
+```
+
+**AI 提示友好特点**:
+
+| 特点 | 好处 |
+|------|------|
+| 明确约束条件 | AI 可生成验证代码 |
+| 列出错误情况 | AI 可生成错误处理 |
+| 结构化格式 | AI 易于解析 |
+
+---
+
+## API 文档标准
+
+### OpenAPI 3.1 规范
+
+```yaml
+openapi: 3.1.0
+info:
+  title: 示例 API
+  version: 1.0.0
+  description: |
+    ## 概述
+    此 API 提供用户管理功能。
+
+    ## 认证
+    使用 Bearer Token 认证。
+
+paths:
+  /users:
+    post:
+      summary: 创建用户
+      operationId: createUser
+      tags: [Users]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateUserRequest'
+      responses:
+        '201':
+          description: 用户创建成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+```
+
+### AsyncAPI 2.6 规范（异步 API）
+
+```yaml
+asyncapi: 2.6.0
+info:
+  title: 事件 API
+  version: 1.0.0
+
+channels:
+  user/created:
+    publish:
+      summary: 用户创建事件
+      message:
+        payload:
+          type: object
+          properties:
+            userId:
+              type: string
+            createdAt:
+              type: string
+              format: date-time
+```
+
+---
+
 ## 相关标准
 
 - [Documentation Structure Standard](documentation-structure.md) - 文件结构标准
@@ -485,8 +616,18 @@ project-root/
 
 | 版本 | 日期 | 变更内容 |
 |---------|------|---------|
+| 1.1.0 | 2026-01-24 | 新增：AI 协作文档章节、API 文档标准（OpenAPI 3.1、AsyncAPI 2.6） |
 | 1.0.1 | 2025-12-24 | 新增：相关标准章节 |
-| 1.0.0 | 2025-12-10 | 初版文件撰写标准 |
+| 1.0.0 | 2025-12-10 | 初版文档撰写标准 |
+
+---
+
+## 参考资料
+
+- [OpenAPI 3.1 规范](https://spec.openapis.org/oas/v3.1.0) - RESTful API 描述标准
+- [AsyncAPI 2.6 规范](https://www.asyncapi.com/docs/reference/specification/v2.6.0) - 异步 API 描述标准
+- [JSON Schema](https://json-schema.org/) - 数据验证标准
+- [Diátaxis 文档框架](https://diataxis.fr/) - 技术文档组织方法
 
 ---
 

package/bundled/locales/zh-CN/core/git-workflow.md

@@ -1,8 +1,8 @@
 ---
 source: ../../../core/git-workflow.md
-source_version: 1.2.1
-translation_version: 1.2.1
-last_synced: 2026-01-08
+source_version: 1.4.0
+translation_version: 1.4.0
+last_synced: 2026-02-10
 status: current
 ---
 
@@ -109,6 +109,160 @@ branches
 
 ---
 
+## Trunk-Based Development + Feature Flags
+
+### 功能开关整合
+
+Trunk-Based Development 依赖功能开关安全地集成未完成功能：
+
+```javascript
+// 功能开关示例
+if (featureFlags.isEnabled('new-checkout-flow', user)) {
+  return newCheckoutFlow(cart);
+} else {
+  return legacyCheckout(cart);
+}
+```
+
+### 功能开关生命周期
+
+| 阶段 | 状态 | 动作 |
+|------|------|------|
+| 开发中 | 关闭 | 仅开发环境启用 |
+| 测试中 | 部分启用 | 内部测试者启用 |
+| 灰度发布 | 百分比推出 | 5% → 25% → 50% → 100% |
+| 全量发布 | 完全启用 | 移除开关代码 |
+
+### 最佳实践
+
+- 开关不超过 2 周
+- 追踪开关的创建日期和负责人
+- 定期清理过期开关
+
+---
+
+## Ship/Show/Ask 决策模型
+
+### 模型说明
+
+决定代码变更如何合并到主分支：
+
+| 模式 | 动作 | 适用场景 |
+|------|------|---------|
+| **Ship** | 直接合并 | 微小修复、文档、配置 |
+| **Show** | 合并后审查 | 非关键功能、重构 |
+| **Ask** | 审查后合并 | 核心功能、API 变更、安全相关 |
+
+### 决策流程图
+
+```
+开始
+  │
+  ▼
+是否涉及核心逻辑/安全？ ──是──► ASK（审查后合并）
+  │
+  否
+  ▼
+是否需要知识共享？ ──────是──► SHOW（合并后审查）
+  │
+  否
+  ▼
+SHIP（直接合并）
+```
+
+---
+
+## Stacked PRs 工作流程
+
+### 概念
+
+将大型变更拆分为可独立审查的小型连续 PR：
+
+```
+main ────●───────────────────●─────
+          \                 /
+PR #1      ●──────●        /    (数据模型)
+                   \      /
+PR #2               ●────●      (API 端点)
+                          \
+PR #3                      ●    (前端整合)
+```
+
+### 建立步骤
+
+```bash
+# 1. 第一个 PR
+git checkout main
+git checkout -b feature/data-model
+# ... 开发数据模型 ...
+git push -u origin feature/data-model
+# 创建 PR #1: main ← feature/data-model
+
+# 2. 第二个 PR（基于第一个）
+git checkout -b feature/api-endpoints
+# ... 开发 API ...
+git push -u origin feature/api-endpoints
+# 创建 PR #2: feature/data-model ← feature/api-endpoints
+
+# 3. 第三个 PR（基于第二个）
+git checkout -b feature/frontend
+# ... 开发前端 ...
+git push -u origin feature/frontend
+# 创建 PR #3: feature/api-endpoints ← feature/frontend
+```
+
+### 合并顺序
+
+1. PR #1 合并后，更新 PR #2 的 base 到 main
+2. PR #2 合并后，更新 PR #3 的 base 到 main
+3. 依此类推
+
+---
+
+## Conventional PR 标题
+
+### 格式
+
+```
+<type>(<scope>): <description>
+
+Examples:
+feat(auth): add OAuth2 login support
+fix(api): resolve rate limiting issue
+docs(readme): update installation guide
+```
+
+### 类型参考
+
+| 类型 | 说明 |
+|------|------|
+| feat | 新功能 |
+| fix | 错误修复 |
+| docs | 文档变更 |
+| style | 格式变更 |
+| refactor | 重构 |
+| test | 测试相关 |
+| chore | 维护任务 |
+
+### GitHub Actions 验证
+
+```yaml
+name: PR Title Check
+on:
+  pull_request:
+    types: [opened, edited, synchronize]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+---
+
 ## 分支命名规范
 
 ### 格式
@@ -184,7 +338,28 @@ Closes #123
 ## 相关标准
 
 - [提交消息指南](commit-message-guide.md)
-- [代码审查指南](code-review-guide.md)
+- [代码审查清单](code-review-checklist.md)
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 1.3.0 | 2026-01-24 | 新增：Trunk-Based + Feature Flags、Ship/Show/Ask、Stacked PRs、Conventional PR 标题 |
+| 1.2.1 | 2026-01-08 | 修复：翻译同步 |
+| 1.2.0 | 2026-01-05 | 新增：工作流程选择决策矩阵 |
+| 1.0.0 | 2025-12-30 | 初始 Git 工作流程标准 |
+
+---
+
+## 参考资料
+
+- [Ship/Show/Ask](https://martinfowler.com/articles/ship-show-ask.html) - Martin Fowler 文章
+- [Feature Flags Best Practices](https://launchdarkly.com/blog/best-practices-for-feature-flags/) - LaunchDarkly
+- [Stacked Diffs](https://newsletter.pragmaticengineer.com/p/stacked-diffs) - The Pragmatic Engineer
+- [Conventional Commits](https://www.conventionalcommits.org/) - 提交消息规范
+- [Trunk-Based Development](https://trunkbaseddevelopment.com/) - 官方指南
 
 ---
 

package/bundled/locales/zh-CN/core/logging-standards.md

@@ -1,8 +1,8 @@
 ---
 source: ../../../core/logging-standards.md
-source_version: 1.1.0
-translation_version: 1.1.0
-last_synced: 2026-01-08
+source_version: 1.2.0
+translation_version: 1.2.0
+last_synced: 2026-01-24
 status: current
 ---
 
@@ -142,6 +142,157 @@ logger.info('卡片处理', { last_four: '4242' });
 
 ---
 
+## OpenTelemetry 整合
+
+### 语义规范
+
+OpenTelemetry 定义标准化的属性名称，确保跨工具的互操作性。
+
+**资源属性**（服务身份）:
+
+| 属性 | 说明 | 范例 |
+|------|------|------|
+| `service.name` | 逻辑服务名称 | `payment-service` |
+| `service.version` | 服务版本 | `2.3.1` |
+| `service.instance.id` | 唯一实例标识符 | `pod-abc123` |
+| `deployment.environment` | 环境名称 | `production` |
+
+**HTTP 属性**:
+
+| 属性 | 说明 | 范例 |
+|------|------|------|
+| `http.request.method` | HTTP 方法 | `POST` |
+| `http.route` | 路由模式 | `/api/v1/users/{id}` |
+| `http.response.status_code` | 响应状态 | `200` |
+
+**数据库属性**:
+
+| 属性 | 说明 | 范例 |
+|------|------|------|
+| `db.system` | 数据库类型 | `postgresql` |
+| `db.name` | 数据库名称 | `orders_db` |
+| `db.operation` | 操作类型 | `SELECT` |
+
+### 日志严重性对照
+
+| 传统级别 | OTel 严重性 | OTel 数值 |
+|---------|------------|----------|
+| TRACE | TRACE | 1-4 |
+| DEBUG | DEBUG | 5-8 |
+| INFO | INFO | 9-12 |
+| WARN | WARN | 13-16 |
+| ERROR | ERROR | 17-20 |
+| FATAL | FATAL | 21-24 |
+
+---
+
+## 可观测性三支柱整合
+
+### 日志、指标、追踪关联
+
+现代可观测性需要通过共享标识符关联三大支柱。
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      可观测性三支柱                               │
+├─────────────────────────────────────────────────────────────────┤
+│   ┌──────────┐    trace_id    ┌──────────┐    trace_id    ┌──────────┐
+│   │   LOGS   │◄──────────────►│  TRACES  │◄──────────────►│ METRICS  │
+│   │  (事件)   │                │  (Spans) │                │ (计数器)  │
+│   └──────────┘                └──────────┘                └──────────┘
+│                    关联键: trace_id, span_id, service.name              │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 关联最佳实践
+
+| 实践 | 好处 |
+|------|------|
+| 日志中始终包含 `trace_id` | 从日志跳转到完整追踪 |
+| 在指标中加入 `trace_id` 作为 exemplar | 调查指标异常 |
+| 使用一致的 `service.name` | 跨所有支柱筛选 |
+
+---
+
+## 基于日志的告警
+
+### 告警设计原则
+
+**1. 避免告警风暴**
+
+```yaml
+# 不好：每个错误都告警
+- alert: ErrorOccurred
+  expr: log_errors_total > 0  # ❌ 太吵杂
+
+# 好：基于错误率告警
+- alert: ErrorRateHigh
+  expr: rate(log_errors_total[5m]) > 0.01  # ✅ 基于比率
+  for: 5m
+```
+
+**2. 分组相关告警**
+
+```yaml
+group_by: ['service', 'error_type']
+group_wait: 30s
+group_interval: 5m
+```
+
+### 告警严重性指南
+
+| 严重性 | 响应时间 | 条件范例 |
+|--------|---------|---------|
+| Critical | 立即（呼叫） | 服务宕机、数据丢失风险 |
+| Warning | 数小时内 | 错误率升高、资源 80% |
+| Info | 下个工作日 | 弃用警告、轻微异常 |
+
+---
+
+## 进阶关联模式
+
+### 跨服务关联 ID
+
+跨服务边界传播关联上下文：
+
+**W3C Trace Context 头**:
+
+```http
+traceparent: 00-abc123def456-span789-01
+tracestate: vendor=value
+```
+
+**消息队列传播**:
+
+```json
+{
+  "headers": {
+    "traceparent": "00-abc123-def456-01"
+  },
+  "body": {
+    "order_id": "ORD-123"
+  }
+}
+```
+
+### 业务事务关联
+
+对于多步骤业务流程：
+
+```json
+{
+  "trace_id": "abc123",
+  "business_correlation": {
+    "transaction_id": "TXN-789",
+    "order_id": "ORD-456",
+    "flow_step": "3/5",
+    "flow_name": "order_fulfillment"
+  }
+}
+```
+
+---
+
 ## 快速参考卡
 
 ### 必要字段检查清单
@@ -165,7 +316,29 @@ logger.info('卡片处理', { last_four: '4242' });
 ## 相关标准
 
 - [测试标准](testing-standards.md) - 测试日志输出（或使用 `/testing-guide` 技能）
-- [代码审查指南](code-review-guide.md) - 审查日志实践
+- [代码审查清单](code-review-checklist.md) - 审查日志实践
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|-----|------|------|
+| 1.2.0 | 2026-01-24 | 新增：OpenTelemetry 语义规范、可观测性三支柱整合、基于日志的告警、进阶关联模式 |
+| 1.1.0 | 2026-01-05 | 新增：参考标准章节，包含 OWASP、RFC 5424、OpenTelemetry 和 12 Factor App |
+| 1.0.0 | 2025-12-30 | 初始日志标准 |
+
+---
+
+## 参考标准
+
+- [OWASP 日志备忘单](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html) - 安全日志最佳实践
+- [RFC 5424 - Syslog 协议](https://datatracker.ietf.org/doc/html/rfc5424) - 标准日志消息格式
+- [OpenTelemetry 日志](https://opentelemetry.io/docs/specs/otel/logs/) - 现代可观测性标准
+- [OpenTelemetry 语义规范](https://opentelemetry.io/docs/specs/semconv/) - 标准化属性命名
+- [W3C Trace Context](https://www.w3.org/TR/trace-context/) - 分布式追踪上下文传播
+- [12 Factor App - 日志](https://12factor.net/logs) - 云原生日志原则
+- [Google SRE - 基于 SLO 告警](https://sre.google/workbook/alerting-on-slos/) - 告警设计最佳实践
 
 ---
 

package/bundled/locales/zh-CN/core/project-structure.md

@@ -1,8 +1,8 @@
 ---
 source: ../../../core/project-structure.md
-source_version: 1.0.1
-translation_version: 1.0.1
-last_synced: 2026-01-08
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-01-24
 status: current
 ---
 
@@ -172,10 +172,122 @@ Thumbs.db
 
 ---
 
+## Monorepo vs Polyrepo 决策指南
+
+### 决策矩阵
+
+| 因素 | Monorepo 适合 | Polyrepo 适合 |
+|------|-------------|--------------||
+| **代码共享** | 高（共用库、组件） | 低（独立服务） |
+| **团队结构** | 单一团队或紧密协作 | 自治团队 |
+| **发布节奏** | 协调发布 | 独立发布 |
+| **CI/CD 复杂度** | 可接受统一管道 | 需要隔离管道 |
+| **仓库大小** | < 5GB，< 100万文件 | 大型资产、长历史 |
+
+### 快速选择指南
+
+**选择 Monorepo 当**:
+- 多个项目共享大量代码或依赖
+- 团队愿意投资于工具
+
+**选择 Polyrepo 当**:
+- 团队需要发布独立性
+- 各项目完全独立
+
+---
+
+## Monorepo 工具比较
+
+| 功能 | Turborepo | Nx | Lerna | Rush |
+|------|-----------|----|----|------|
+| **主要用途** | 任务执行 | 完整框架 | 发布 | 企业级 |
+| **学习曲线** | 低 | 中高 | 低 | 高 |
+| **构建速度** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ |
+| **远程缓存** | ✅ 内置 | ✅ Nx Cloud | ❌ 手动 | ✅ 内置 |
+| **代码生成** | ❌ | ✅ 丰富 | ❌ | ❌ |
+| **最适合** | 小中型团队 | 大型团队、企业 | 简单发布 | 企业规模 |
+
+---
+
+## Workspace 配置
+
+### pnpm Workspaces
+
+```yaml
+# pnpm-workspace.yaml
+packages:
+  - 'apps/*'
+  - 'packages/*'
+  - 'tools/*'
+```
+
+### Yarn Workspaces
+
+```json
+{
+  "workspaces": ["apps/*", "packages/*"]
+}
+```
+
+---
+
+## 基于包的架构
+
+### 概念
+
+基于包的架构按**功能边界**而非技术层次组织代码。每个包是独立的单元，有清晰的接口。
+
+```
+传统（分层）                    基于包（按功能）
+─────────────                  ────────────────
+src/                           packages/
+├── controllers/               ├── authentication/
+├── services/                  │   ├── api/
+├── models/                    │   ├── domain/
+└── repositories/              │   └── infrastructure/
+                               ├── orders/
+                               └── shared/
+```
+
+### 好处
+
+| 好处 | 说明 |
+|------|------|
+| **清晰边界** | 每个包有明确的公开 API |
+| **独立测试** | 可隔离测试包 |
+| **并行开发** | 团队可在不同包上工作 |
+| **选择性部署** | 只部署变更的包 |
+
+---
+
 ## 相关标准
 
-- [文档结构](documentation-structure.md)
-- [Git 工作流程](git-workflow.md)
+- [文档结构标准](documentation-structure.md) - 文档结构标准
+- [代码签入标准](checkin-standards.md) - 代码签入标准
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 1.1.0 | 2026-01-24 | 新增：Monorepo vs Polyrepo 决策指南、Monorepo 工具比较、Workspace 配置、基于包的架构 |
+| 1.0.1 | 2025-12-24 | 新增：相关标准章节 |
+| 1.0.0 | 2025-12-11 | 初始项目结构标准 |
+
+---
+
+## 参考资料
+
+- [.NET Project Structure](https://docs.microsoft.com/en-us/dotnet/core/porting/project-structure)
+- [Node.js Project Structure Best Practices](https://github.com/goldbergyoni/nodebestpractices)
+- [Python Packaging User Guide](https://packaging.python.org/en/latest/)
+- [Standard Go Project Layout](https://github.com/golang-standards/project-layout)
+- [Maven Standard Directory Layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html)
+- [Turborepo 文档](https://turbo.build/repo/docs) - 现代 JavaScript/TypeScript monorepo 构建系统
+- [Nx 文档](https://nx.dev/getting-started/intro) - 智能 monorepo 工具
+- [pnpm Workspaces](https://pnpm.io/workspaces) - 快速、高效的包管理器 workspaces
+- [Monorepo Explained](https://monorepo.tools/) - Monorepo 工具全面指南
 
 ---