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

package/bundled/locales/zh-CN/ai/standards/logging.ai.yaml

@@ -0,0 +1,128 @@
+# 日誌标准 - AI 优化版
+# 来源: core/logging-standards.md
+
+id: logging
+meta:
+  version: "1.1.0"
+  updated: "2026-01-05"
+  source: core/logging-standards.md
+  description: 日誌等级、结构化日誌与最佳实踐
+
+log_levels:
+  ordered:
+    - name: TRACE
+      code: 10
+      use_for: 非常详细的除錯
+      production: false
+    - name: DEBUG
+      code: 20
+      use_for: 診斷信息
+      production: false
+    - name: INFO
+      code: 30
+      use_for: 正常操作
+      production: true
+    - name: WARN
+      code: 40
+      use_for: 潛在問題
+      production: true
+    - name: ERROR
+      code: 50
+      use_for: 需要关注的错误
+      production: true
+    - name: FATAL
+      code: 60
+      use_for: 关鍵故障
+      production: true
+
+structured_logging:
+  required_fields:
+    - timestamp
+    - level
+    - message
+    - service
+    - environment
+  recommended_fields:
+    - trace_id
+    - span_id
+    - request_id
+    - user_id
+    - duration_ms
+  field_naming: snake_case
+  format: 生产環境使用 JSON
+
+sensitive_data:
+  never_log:
+    - 密码
+    - api_keys
+    - 完整令牌
+    - 信用卡
+    - 身分证字号
+  mask_patterns:
+    - "password: '***REDACTED***'"
+    - "token: 'tok_...abc'"
+    - "card: '****4242'"
+
+rules:
+  - id: select-level
+    trigger: 新增日誌語句
+    instruction: |
+      选择適當等级：
+      - DEBUG: 僅診斷用，生产環境关閉
+      - INFO: 正常操作完成
+      - WARN: 意外但可恢復
+      - ERROR: 操作失败
+      - FATAL: 無法繼續
+    priority: required
+
+  - id: structured-format
+    trigger: 写入日誌
+    instruction: 使用包含必要欄位的结构化 JSON 日誌
+    priority: required
+
+  - id: include-context
+    trigger: 记录操作
+    instruction: 包含 request_id 或 trace_id 以便关联
+    priority: required
+
+  - id: no-sensitive-data
+    trigger: 记录数据
+    instruction: 永不记录密码、机密、令牌或 PII
+    priority: required
+
+  - id: error-context
+    trigger: 记录错误
+    instruction: 包含 error_type、error_message、stack 和相关 ID
+    priority: required
+
+  - id: async-logging
+    trigger: 部署到生产環境
+    instruction: 使用非同步/緩衝日誌以提升效能
+    priority: recommended
+
+quick_reference:
+  level_selection:
+    columns: [問題, 等级]
+    rows:
+      - [只是除錯?, DEBUG]
+      - [正常操作?, INFO]
+      - [意外但可接受?, WARN]
+      - [操作失败?, ERROR]
+      - [無法繼續?, FATAL]
+
+  required_fields:
+    columns: [欄位, 格式, 必要]
+    rows:
+      - [timestamp, "ISO 8601", 是]
+      - [level, "INFO/ERROR/等", 是]
+      - [message, 字串, 是]
+      - [service, 字串, 是]
+      - [request_id, UUID, 建议]
+
+  retention:
+    columns: [等级, 保留期间]
+    rows:
+      - [DEBUG, 7 天]
+      - [INFO, 30 天]
+      - [WARN, 90 天]
+      - [ERROR/FATAL, 1 年]

package/bundled/locales/zh-CN/ai/standards/project-structure.ai.yaml

@@ -0,0 +1,134 @@
+# 项目结构标准 - AI 优化版
+# 来源: core/project-structure.md
+
+id: project-structure
+meta:
+  version: "1.1.0"
+  updated: "2025-12-30"
+  source: core/project-structure.md
+  description: 项目目录结构慣例
+  language: zh-CN
+
+options:
+  project_language:
+    description: 选择项目语言/平台
+    choices:
+      - id: dotnet
+        file: options/project-structure/dotnet.ai.yaml
+      - id: nodejs
+        file: options/project-structure/nodejs.ai.yaml
+      - id: python
+        file: options/project-structure/python.ai.yaml
+      - id: java
+        file: options/project-structure/java.ai.yaml
+      - id: go
+        file: options/project-structure/go.ai.yaml
+      - id: rust
+        file: options/project-structure/rust.ai.yaml
+      - id: kotlin
+        file: options/project-structure/kotlin.ai.yaml
+      - id: php
+        file: options/project-structure/php.ai.yaml
+      - id: ruby
+        file: options/project-structure/ruby.ai.yaml
+      - id: swift
+        file: options/project-structure/swift.ai.yaml
+
+structure:
+  common:
+    - dir: src/
+      purpose: 原始码
+      gitignore: false
+
+    - dir: tests/
+      purpose: 测试文件
+      gitignore: false
+
+    - dir: docs/
+      purpose: 文件
+      gitignore: false
+
+    - dir: tools/
+      purpose: 开发/部署脚本
+      gitignore: false
+      subdirs: [deployment/, migration/, scripts/]
+
+    - dir: examples/
+      purpose: 使用範例
+      gitignore: false
+
+  build_output:
+    - dir: dist/
+      purpose: 發布输出
+      gitignore: true
+
+    - dir: build/
+      purpose: 编譯产物
+      gitignore: true
+
+    - dir: out/
+      purpose: 输出目录
+      gitignore: true
+
+    - dir: bin/
+      purpose: 二进位执行檔
+      gitignore: true
+
+  config:
+    - dir: .github/
+      purpose: GitHub 设置
+      gitignore: false
+
+    - dir: .standards/
+      purpose: 开发标准
+      gitignore: false
+
+    - dir: config/
+      purpose: 设置檔
+      gitignore: false
+
+rules:
+  - id: gitignore-build
+    trigger: 建立项目时
+    instruction: 永遠將建置输出目录加入 gitignore (dist/, build/, out/, bin/)
+    priority: required
+
+  - id: src-structure
+    trigger: 組織原始码时
+    instruction: 遵循特定语言的 src/ 结构慣例
+    priority: required
+
+  - id: tests-location
+    trigger: 組織测试时
+    instruction: 將测试放在 tests/ 或原始码旁邊（依语言而定）
+    priority: recommended
+
+  - id: tools-organization
+    trigger: 新增脚本时
+    instruction: 將脚本依用途分組放在 tools/ 的子目录中
+    priority: recommended
+
+quick_reference:
+  directories:
+    columns: [目录, 用途, gitignore]
+    rows:
+      - [src/, 原始码, 否]
+      - [tests/, 测试文件, 否]
+      - [docs/, 文件, 否]
+      - [tools/, 脚本, 否]
+      - [dist/, 建置输出, 是]
+      - [build/, 编譯产物, 是]
+      - [node_modules/, 相依套件, 是]
+      - [.env, 環境变數, 是]
+
+  gitignore_patterns:
+    columns: [模式, 用途]
+    rows:
+      - ["dist/", 建置输出]
+      - ["build/", 编譯产物]
+      - ["*.log", 日誌文件]
+      - [".env*", 環境变數檔]
+      - ["node_modules/", Node 相依套件]
+      - ["__pycache__/", Python 快取]
+      - ["*.pyc", Python 位元码]
+      - [".venv/", Python 虛擬環境]

package/bundled/locales/zh-CN/ai/standards/spec-driven-development.ai.yaml

@@ -0,0 +1,169 @@
+# 規格驅动开发标准 - AI 优化版
+# 来源: core/spec-driven-development.md
+
+id: spec-driven-development
+meta:
+  version: "1.2.0"
+  updated: "2026-01-05"
+  source: core/spec-driven-development.md
+  description: 規格驅动开发 (SDD) 的原則和工作流程
+  language: zh-CN
+
+workflow:
+  stages:
+    - stage: 提案
+      description: 定義要变更什麼及为什麼
+      artifacts: proposal.md
+
+    - stage: 审查
+      description: 利害关系人核准
+      artifacts: 审查意見、核准记录
+
+    - stage: 实作
+      description: 执行已核准的規格
+      artifacts: 程序码、测试、文件
+
+    - stage: 验证
+      description: 确认实作符合規格
+      artifacts: 测试結果、审查
+
+    - stage: 歸檔
+      description: 关閉并歸檔規格
+      artifacts: 已歸檔規格附 commits/PRs 連結
+
+principles:
+  tool_priority:
+    rule: 當 SDD 工具提供命令时，優先使用这些命令而非手动编辑文件
+    rationale:
+      - 一致性（严格的 schema）
+      - 可追溯性（自动记录、ID、連結）
+      - 安全性（內建验证）
+    example: '使用 /openspec proposal "新增登入" 而非手动建立文件'
+
+  methodology_over_tooling:
+    rule: SDD 是一种方法論，不綁定单一工具
+    universal_flow: 提案 -> 审查 -> 实作 -> 验证 -> 歸檔
+
+  spec_first:
+    rule: 没有核准的規格不得进行功能性程序码变更
+    exceptions:
+      - 緊急修復（立即恢復服务，之後補文件）
+      - 瑣碎变更（錯字、註解、格式）
+
+spec_template:
+  sections:
+    - name: 摘要
+      description: 提議变更的簡短描述
+      required: true
+
+    - name: 动机
+      description: 为什麼需要这个变更？解决什麼問題？
+      required: true
+
+    - name: 详细设计
+      description: 技術方法、影響的元件、数据流
+      required: true
+
+    - name: 驗收标准
+      description: 可检查的完成标准
+      required: true
+
+    - name: 相依性
+      description: 对其他規格或外部系统的相依
+      required: false
+
+    - name: 風險
+      description: 潛在風險和緩解策略
+      required: false
+
+integration:
+  commit_messages:
+    instruction: 在 commit 消息中引用規格 ID
+    example: |
+      feat(auth): 实作登入功能
+
+      实作 SPEC-001 登入功能，支援 OAuth2。
+
+      Refs: SPEC-001
+
+  checkin_standards:
+    checklist:
+      - 規格已核准
+      - 实作符合規格
+      - 测试涵蓋驗收标准
+      - PR 中引用規格 ID
+
+  code_review:
+    checklist:
+      - 变更符合核准的規格
+      - 没有超出規格的範圍蔓延
+      - 規格驗收标准已滿足
+
+common_tools:
+  - tool: OpenSpec
+    description: 規格管理
+    commands: ["/openspec proposal", "/openspec approve"]
+
+  - tool: Spec Kit
+    description: 輕量级規格追蹤
+    commands: ["/spec create", "/spec close"]
+
+  - tool: 手动
+    description: 無工具，基于文件
+    commands: ["手动建立 specs/SPEC-XXX.md"]
+
+rules:
+  - id: use-sdd-commands
+    trigger: SDD 工具可用时
+    instruction: 使用工具命令而非手动编辑文件
+    priority: required
+
+  - id: spec-before-code
+    trigger: 開始新功能时
+    instruction: 在编码之前建立并取得規格核准
+    priority: required
+
+  - id: reference-spec-id
+    trigger: 提交实作时
+    instruction: 在 commit 消息和 PR 中包含規格 ID
+    priority: required
+
+  - id: verify-against-spec
+    trigger: 完成实作时
+    instruction: 验证所有驗收标准已滿足
+    priority: required
+
+  - id: archive-completed-specs
+    trigger: 規格实作已验证
+    instruction: 歸檔規格并附上 commits/PRs 連結
+    priority: required
+
+best_practices:
+  do:
+    - 保持規格聚焦和原子性（一个变更一个規格）
+    - 包含清晰的驗收标准
+    - 將規格連結到实作 PRs
+    - 完成後歸檔規格
+
+  do_not:
+    - 在規格核准前開始编码
+    - 实作期间修改範圍而不更新規格
+    - 讓規格处於懸置状态（务必关閉或歸檔）
+    - 跳過验证步骤
+
+quick_reference:
+  workflow:
+    columns: [阶段, 产出物]
+    rows:
+      - [提案, proposal.md]
+      - [审查, 意見/核准]
+      - [实作, 程序码/测试/文件]
+      - [验证, 测试結果]
+      - [歸檔, 已歸檔規格]
+
+  tools:
+    columns: [工具, 命令]
+    rows:
+      - [OpenSpec, "/openspec proposal, /openspec approve"]
+      - [Spec Kit, "/spec create, /spec close"]
+      - [手动, "specs/SPEC-XXX.md"]

package/bundled/locales/zh-CN/ai/standards/test-completeness-dimensions.ai.yaml

@@ -0,0 +1,220 @@
+# 测试完整性維度 - AI 优化版
+# 来源: core/test-completeness-dimensions.md
+
+id: test-completeness-dimensions
+meta:
+  version: "1.0.0"
+  updated: "2025-12-30"
+  source: core/test-completeness-dimensions.md
+  description: 评估测试完整性的 7 个維度框架
+  language: zh-CN
+
+dimensions:
+  - id: 1
+    name: 正常路徑
+    description: 使用有效输入的正常预期行为
+    test_items:
+      - 有效输入产生预期输出
+      - 成功状态码/响应
+      - 数据正确建立/修改
+      - 预期的副作用發生
+
+  - id: 2
+    name: 邊界条件
+    description: 有效範圍邊緣的值
+    test_items:
+      - 最小有效值
+      - 最大有效值
+      - 剛好低於最小值（無效）
+      - 剛好高於最大值（無效）
+      - 空集合 vs 单一项目 vs 多项目
+
+  - id: 3
+    name: 错误处理
+    description: 無效输入和例外情况
+    test_items:
+      - 無效输入格式
+      - 缺少必要欄位
+      - 重複数据衝突
+      - 資源不存在
+      - 外部服务失败
+
+  - id: 4
+    name: 授权
+    description: 每个操作的角色型存取控制
+    test_items:
+      - 每个角色的允許操作
+      - 每个角色的拒絕操作
+      - 未认证存取
+      - 跨租戶/跨使用者数据存取
+    note: 为每个功能建立授权矩陣
+
+  - id: 5
+    name: 状态变更
+    description: 操作前後的系统状态
+    test_items:
+      - 操作前状态
+      - 操作後状态
+      - 状态转换（啟用 → 停用）
+      - 冪等性（重複操作結果相同）
+
+  - id: 6
+    name: 验证邏辑
+    description: 商业規則和格式验证
+    test_items:
+      - 格式验证（email、電話等）
+      - 商业規則验证
+      - 跨欄位验证
+      - 領域特定約束
+
+  - id: 7
+    name: 集成验证
+    description: 实际数据庫查詢和外部集成
+    test_items:
+      - 查詢条件传回正确数据
+      - 实体关联正确载入
+      - 分页正确运作
+      - 排序和篩選正确运作
+    when_required: 如果单元测试使用萬用匹配器（It.IsAny<>、any()、Arg.Any<>）
+
+feature_type_mapping:
+  - type: CRUD API
+    dimensions: [1, 2, 3, 4, 6, 7]
+
+  - type: 查詢/搜尋
+    dimensions: [1, 2, 3, 4, 7]
+
+  - type: 状态机
+    dimensions: [1, 3, 4, 5, 6]
+
+  - type: 验证
+    dimensions: [1, 2, 3, 6]
+
+  - type: 背景作业
+    dimensions: [1, 3, 5]
+
+  - type: 外部集成
+    dimensions: [1, 3, 7]
+
+error_code_coverage:
+  - code: 200
+    meaning: 成功
+    scenario: 正常路徑测试
+
+  - code: 400
+    meaning: 错误请求
+    scenario: 無效格式、缺少欄位
+
+  - code: 401
+    meaning: 未授权
+    scenario: 無效/缺少 token
+
+  - code: 403
+    meaning: 禁止存取
+    scenario: 有效 token 但权限不足
+
+  - code: 404
+    meaning: 找不到
+    scenario: 不存在的資源
+
+  - code: 409
+    meaning: 衝突
+    scenario: 重複数据
+
+  - code: 422
+    meaning: 無法处理
+    scenario: 商业規則違反
+
+  - code: 500
+    meaning: 服务器错误
+    scenario: 例外处理
+
+anti_patterns:
+  - 只测试正常路徑
+  - 多角色系统缺少授权测试
+  - 未验证状态变更
+  - 单元测试使用萬用匹配器但無对应集成测试
+  - 测试数据中 ID 和业务識别码使用相同值
+  - 测试实作細节而非行为
+
+rules:
+  - id: use-checklist
+    trigger: 为功能设计测试时
+    instruction: 使用 7 維度清单确保完整性
+    priority: required
+
+  - id: authorization-matrix
+    trigger: 功能有角色型存取时
+    instruction: 建立授权矩陣，每格都要有测试
+    priority: required
+
+  - id: integration-for-wildcards
+    trigger: 单元测试使用萬用匹配器时
+    instruction: 必須有对应的集成测试
+    priority: required
+
+  - id: cover-error-codes
+    trigger: API 回传错误码时
+    instruction: 每个错误码应有测试場景
+    priority: required
+
+checklist_template: |
+  功能: ___________________
+
+  □ 正常路徑
+    □ 有效输入产生预期成功
+    □ 传回/建立正确数据
+    □ 预期的副作用發生
+
+  □ 邊界条件
+    □ 最小有效值
+    □ 最大有效值
+    □ 空/单一/大量集合
+
+  □ 错误处理
+    □ 無效输入格式
+    □ 缺少必要欄位
+    □ 重複/衝突場景
+    □ 找不到場景
+
+  □ 授权
+    □ 每个允許角色已测试
+    □ 每个拒絕角色已测试
+    □ 未认证存取已测试
+
+  □ 状态变更
+    □ 初始状态已验证
+    □ 最終状态已验证
+    □ 所有有效转换已测试
+
+  □ 验证
+    □ 格式验证
+    □ 商业規則验证
+    □ 跨欄位验证
+
+  □ 集成（如 UT 使用萬用匹配器）
+    □ 查詢条件已验证
+    □ 实体关联已验证
+    □ 分页/排序已验证
+
+quick_reference:
+  dimensions:
+    columns: [ID, 維度, 关鍵焦点]
+    rows:
+      - [1, 正常路徑, 正常预期行为]
+      - [2, 邊界, 最小/最大值和限制]
+      - [3, 错误处理, 無效输入和例外]
+      - [4, 授权, 角色型存取控制]
+      - [5, 状态变更, 前後状态验证]
+      - [6, 验证, 格式和商业規則]
+      - [7, 集成, 实际查詢验证]
+
+  feature_dimensions:
+    columns: [功能类型, 必要維度]
+    rows:
+      - [CRUD API, "1,2,3,4,6,7"]
+      - [查詢/搜尋, "1,2,3,4,7"]
+      - [状态机, "1,3,4,5,6"]
+      - [验证, "1,2,3,6"]
+      - [背景作业, "1,3,5"]
+      - [外部集成, "1,3,7"]