universal-dev-standards 5.16.0 → 6.0.0

package/bundled/locales/zh-CN/core/mutation-testing.md

@@ -0,0 +1,106 @@
+---
+source: ../../../core/mutation-testing.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: 6a5286d76274
+status: current
+---
+
+# 变异测试标准
+
+> **语言**: [English](../../../core/mutation-testing.md) | [繁體中文](../../zh-TW/core/mutation-testing.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-05-04
+**适用性**: 所有具备单元/集成测试的软件项目
+**范围**: universal
+**行业标准**: ISTQB Foundation Syllabus（测试有效性指标）
+**参考**: "Introduction to Software Testing"（Ammann & Offutt）, Stryker Mutator 文档
+
+---
+
+## 目的
+
+变异测试（mutation testing）通过注入人工 bug 并检查测试是否能检测到它们，来评估测试套件的有效性。它回答了行覆盖率无法回答的问题：**「我的测试真的在验证正确行为吗？」**
+
+---
+
+## 核心概念：Mutation Score
+
+```
+Mutation Score = Killed Mutants / (Killed + Survived) × 100%
+```
+
+- **Killed**：测试套件检测到人工 bug（测试失败）✅
+- **Survived**：测试套件漏掉了 bug（测试仍通过）❌
+
+一个只有 `expect(x).toBeDefined()` 的测试可以达到 100% 行覆盖率，却会让许多变异存活（因为 `x` 是 `null`、`0` 或 `"wrong"` 都满足 `.toBeDefined()`）。
+
+---
+
+## 工具
+
+| 语言 | 工具 | 命令 |
+|------|------|------|
+| TypeScript/JS | Stryker Mutator | `npx stryker run` |
+| Python | mutmut | `mutmut run` |
+| Java | PIT (Pitest) | `mvn pitest:mutationCoverage` |
+
+---
+
+## 阈值
+
+| 模块类型 | 最低分数 | 强制程度 |
+|---------|---------|---------|
+| Auth/License/Payment/Security | 80% | 阻断 release |
+| 标准业务逻辑 | 70% | 警告；下次 release 前解决 |
+| AI 生成的测试 | 50% | 必需；低于即拒绝 |
+| 整体项目 | 60% | 跟踪趋势；回归时告警 |
+
+---
+
+## 何时运行
+
+| 触发条件 | 命令 | 强制程度 |
+|---------|------|---------|
+| Pre-release 门禁 | `npm run test:mutation` | 整体 ≥ 60% |
+| 关键模块变更 | `npx stryker run --mutate 'src/auth/**'` | ≥ 80% |
+| AI 生成测试评审 | `npx stryker run` | ≥ 50% |
+
+**绝不**把变异测试加入 commit hook——它太慢了（10-60 分钟）。
+
+---
+
+## Stryker 快速上手（TypeScript + Vitest）
+
+```bash
+npm install --save-dev @stryker-mutator/core @stryker-mutator/vitest-runner
+```
+
+```json
+// stryker.config.json
+{
+  "testRunner": "vitest",
+  "coverageAnalysis": "perTest",
+  "mutate": ["src/license/**/*.ts", "!src/**/*.test.ts"],
+  "thresholds": { "high": 80, "low": 60, "break": 50 }
+}
+```
+
+---
+
+## 反模式
+
+- 把行覆盖率当作测试有效性的替代指标
+- 在每个 PR 的 CI 中都加入变异测试（太慢）
+- 未经 mutation score 验证就接受 AI 生成的测试
+- 靠加 `toBeDefined()` 断言来杀死变异
+
+---
+
+## 与其他标准的关系
+
+- `test-completeness-dimensions`：维度 8（AI 测试质量）引用 mutation score
+- `mock-boundary`：空心测试会让许多变异存活；mock 边界规则防止空心测试
+- `testing`：变异测试是测试金字塔顶端的质量门禁

package/bundled/locales/zh-CN/core/no-cicd-deployment.md

@@ -0,0 +1,219 @@
+---
+source: ../../../core/no-cicd-deployment.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: dbe8c04bf6a4
+status: current
+---
+
+# No-CI/CD Deployment Strategy
+
+> **Language**: [English](../../../core/no-cicd-deployment.md) | [繁體中文](../../zh-TW/core/no-cicd-deployment.md) | 简体中文
+
+> **补充**: 本文档补充 `deployment-standards.md`，专注于无 CI/CD 平台（GitHub Actions / GitLab CI）环境下的可靠部署设计。
+
+## 核心三层架构
+
+```
+Layer 1: 防止错误部署
+  └─ set -euo pipefail、版本 tag 强制、deploy.lock
+
+Layer 2: 验证部署正确
+  └─ Smoke Test、健康检查、版本号比对、自动 rollback
+
+Layer 3: 快速恢复能力
+  └─ Blue-Green 切换、< 30 秒 rollback
+```
+
+## Layer 1：防止错误部署
+
+### Shell 脚本强制执行
+
+所有部署脚本必须以下列标头开始：
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+```
+
+- `set -e`：任何命令失败立即退出
+- `set -u`：引用未定义变量视为错误
+- `set -o pipefail`：管线中任何命令失败都会传播错误
+
+### 强制部署顺序
+
+```bash
+echo "[1/4] 执行测试..."
+npm test
+
+echo "[2/4] 构建产物..."
+npm run build
+
+echo "[3/4] 推送到服务器..."
+rsync -avz --delete ./dist/ user@server:/app/
+
+echo "[4/4] 验证部署..."
+./verify.sh || { echo "验证失败，执行 rollback..."; ./rollback.sh; exit 1; }
+```
+
+### deploy.lock 防并发
+
+```bash
+LOCK_FILE="/tmp/deploy.lock"
+trap "rm -f $LOCK_FILE" EXIT
+
+if [ -f "$LOCK_FILE" ]; then
+  echo "❌ 部署进行中（PID: $(cat $LOCK_FILE)），请等待完成"
+  exit 1
+fi
+
+echo $$ > "$LOCK_FILE"
+```
+
+### 版本 Tag 强制
+
+```bash
+CURRENT_TAG=$(git describe --exact-match --tags HEAD 2>/dev/null || echo "")
+if [ -z "$CURRENT_TAG" ]; then
+  echo "❌ 当前 commit 没有版本 tag，请先执行："
+  echo "   git tag v$(cat VERSION) && git push --tags"
+  exit 1
+fi
+```
+
+## Layer 2：验证部署正确
+
+### Smoke Test 脚本 (verify.sh)
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+HEALTH_URL="${HEALTH_URL:-https://example.com/health}"
+EXPECTED_VERSION=$(cat VERSION)
+MAX_RETRIES=3
+RETRY_INTERVAL=5
+
+for i in $(seq 1 $MAX_RETRIES); do
+  RESPONSE=$(curl -sf --max-time 10 "$HEALTH_URL" 2>/dev/null) && break
+  echo "健康检查失败 ($i/$MAX_RETRIES)，等待 ${RETRY_INTERVAL}s..."
+  sleep $RETRY_INTERVAL
+done
+
+ACTUAL_VERSION=$(echo "$RESPONSE" | python3 -c "import json,sys; print(json.load(sys.stdin)['version'])")
+
+if [ "$ACTUAL_VERSION" != "$EXPECTED_VERSION" ]; then
+  echo "❌ 版本不符！预期 $EXPECTED_VERSION，实际 $ACTUAL_VERSION"
+  exit 1
+fi
+
+echo "✅ 版本验证通过：$ACTUAL_VERSION"
+```
+
+### 健康检查端点规格
+
+应用程序必须提供 `/health` 端点，响应格式：
+
+```json
+{
+  "status": "ok",
+  "version": "1.2.3",
+  "timestamp": "2026-04-26T10:00:00Z"
+}
+```
+
+## Layer 3：快速恢复能力
+
+### Blue-Green 架构
+
+```
+[Nginx]
+  │
+  ├─── Blue (port 3001) ← 稳定版（当前 active）
+  └─── Green (port 3002) ← 新版（部署目标）
+```
+
+**Nginx 配置**：
+
+```nginx
+upstream app {
+  server 127.0.0.1:3001;  # blue
+  # server 127.0.0.1:3002;  # green（切换时启用此行并停用上一行）
+}
+
+server {
+  listen 80;
+  location / {
+    proxy_pass http://app;
+  }
+}
+```
+
+### Rollback 脚本 (rollback.sh)
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+CURRENT=$(readlink /app/current)
+if [[ "$CURRENT" == *"green"* ]]; then
+  TARGET="/app/blue"
+else
+  TARGET="/app/green"
+fi
+
+ln -sfn "$TARGET" /app/current
+nginx -s reload
+
+echo "✅ 已切回 $TARGET（$(date -u +%Y-%m-%dT%H:%M:%SZ)）"
+
+# 记录 rollback 事件
+echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"event\":\"rollback\",\"from\":\"$CURRENT\",\"to\":\"$TARGET\",\"operator\":\"$(whoami)\"}" >> /var/log/deployments.jsonl
+```
+
+### 完整 Makefile
+
+```makefile
+.PHONY: deploy rollback verify
+
+deploy:
+	@./deploy.sh
+
+rollback:
+	@./rollback.sh
+
+verify:
+	@./verify.sh
+
+status:
+	@echo "Current: $$(readlink /app/current)"
+	@curl -s $${HEALTH_URL:-http://localhost/health} | python3 -m json.tool
+```
+
+## Deployment Log 格式
+
+每次部署（成功或失败）都必须写入 JSON Lines 格式的日志：
+
+```json
+{"timestamp":"2026-04-26T10:00:00Z","version":"1.2.3","git_commit":"abc1234","operator":"albert","result":"success","duration_seconds":45,"slot":"green"}
+{"timestamp":"2026-04-26T11:30:00Z","version":"1.2.4","git_commit":"def5678","operator":"albert","result":"failure","duration_seconds":12,"slot":"green","error":"version_mismatch"}
+```
+
+## 适用场景
+
+| 场景 | 建议 |
+|------|------|
+| 个人 VPS / 小型项目 | Layer 1 + Layer 2（无需 Blue-Green） |
+| 自架服务器（多人团队） | 三层全套 + deploy.lock |
+| Air-gapped 环境 | 三层全套 + 本地 artifact registry |
+| 容器化部署 | 搭配 `docker compose` 执行 |
+
+## 相关标准
+
+- `deployment-standards.ai.yaml` — 有 CI/CD 平台的部署策略（本文档的补充前提）
+- `health-check-standards.ai.yaml` — /health 端点设计规范
+- `circuit-breaker.ai.yaml` — 断路器集成（进阶场景）
+
+
+**Scope**: universal

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

@@ -1,8 +1,9 @@
 ---
 source: ../../../core/packaging-standards.md
-source_version: 1.0.0
-translation_version: 1.0.0
-last_synced: 2026-04-20
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-06-10
+source_hash: aa338edba3b1
 status: current
 ---
 
@@ -10,8 +11,8 @@ status: current
 
 > **语言**: [English](../../../core/packaging-standards.md) | 简体中文
 
-**版本**: 1.0.0
-**最后更新**: 2026-04-15
+**版本**: 1.1.0
+**最后更新**: 2026-05-26
 **适用性**: 使用 UDS-aware 工具链的项目
 **范围**: 通用 (Universal)
 
@@ -202,6 +203,75 @@ targets:
 
 ---
 
+## 归档格式完整性
+
+当打包步骤生成将被部署脚本使用的归档（`.zip`、`.tar.gz`、`.tar.bz2` 等）时，**真实的二进制格式必须与文件扩展名一致**。命名为 `.zip` 的文件必须是真正的 ZIP 归档（PKZip 魔数 `PK\x03\x04`），而不是改名后的 tar 归档。
+
+> **为何必须：** 格式不匹配的归档会触发下游静默失败。PowerShell 的 `Expand-Archive` 和 `[System.IO.Compression.ZipFile]::ExtractToDirectory()` 会**不抛出任何错误地**接受 tar 改名为 `.zip` 的文件——文件被读取，但什么都不会被解压，且没有任何异常。若部署脚本的下一步是破坏性操作（例如"删除当前安装目录"），则运行中的安装将被销毁而无任何内容可替换。
+
+### 发布前验证
+
+每个生成归档的打包步骤**必须**在声明成功前包含格式验证。最低验证要求：
+
+| 格式 | 验证单行命令 |
+|---|---|
+| `.zip` | `python -c "import zipfile; zipfile.ZipFile('out.zip').namelist()"` 必须成功 |
+| `.zip`（Unix） | `file out.zip` 必须报告 `Zip archive data`，**不得**为 `POSIX tar archive` |
+| `.tar.gz` | `tar -tzf out.tar.gz >/dev/null` 必须成功 |
+| 任意格式 | 可选：对预期文件清单进行哈希比对 |
+
+验证失败必须在发布前终止打包流水线。
+
+### 各平台配置示例
+
+**Windows — 应当使用：**
+
+```powershell
+# 选项 A：PowerShell 内置（生成真正的 ZIP）
+Compress-Archive -Path "publish\*" -DestinationPath "dist\patch.zip" -Force
+
+# 选项 B：.NET API（生成真正的 ZIP）
+Add-Type -Assembly System.IO.Compression.FileSystem
+[System.IO.Compression.ZipFile]::CreateFromDirectory(
+    "publish", "dist\patch.zip", "Optimal", $false
+)
+```
+
+**Windows — 不应使用：**
+
+```bash
+# ❌ git-bash / busybox 的 tar -a -cf 在 Windows 上不可靠
+# -a "按扩展名自动选择格式" 标志会生成带 .zip 扩展名的 POSIX tar 归档。
+# `file patch.zip` → "POSIX tar archive (GNU)"（而非 "Zip archive data"）
+cd publish && tar -a -cf "../dist/patch.zip" api/
+```
+
+**类 Unix 系统 — 应当使用：**
+
+```bash
+# 使用 'zip' 生成 ZIP 归档（BSD/Linux）
+zip -r dist/patch.zip publish/
+
+# 使用 'tar -czf'（不加 -a）生成 tar.gz 归档——明确、确定
+tar -czf dist/patch.tar.gz publish/
+
+# 发布前验证
+file dist/patch.zip            # 期望 "Zip archive data"
+python -c "import zipfile; zipfile.ZipFile('dist/patch.zip').namelist()"
+```
+
+### 消费者侧防御
+
+生产者无法保证消费者会进行验证。消费者（部署脚本）**必须**在任何破坏性操作前验证归档完整性。消费者侧要求参见[部署标准 — 防御性部署排序](deployment-standards.md#防御性部署排序)。
+
+### 失败模式参考（真实事故）
+
+某 Windows IIS 生产部署脚本（2026-05-24）在 git-bash 中使用 `tar -a -cf patch.zip api/` 生成发布归档。消费者侧的 PowerShell 部署脚本随后执行了 `Expand-Archive`（对该 tar 改名文件静默无操作），继续对运行中的 `apiDir` 执行 `Remove-Item -Recurse`，然后从根本不存在的源路径执行 `Copy-Item`（因为什么都没有被解压）。运行中的安装被清空，AppPool 停止，生产环境中断了约 3 分钟，直到基于备份的回滚完成。
+
+（a）生产者使用自动扩展名 tar，（b）消费者未验证解压输出——这两个因素共同造成了运行中的安装被销毁，且整个过程无任何错误被报告。
+
+---
+
 ## 相关标准
 
 - [部署标准](deployment-standards.md) — 打包后的部署阶段
@@ -215,6 +285,7 @@ targets:
 
 | 版本 | 日期 | 变更 |
 |------|------|------|
+| 1.1.0 | 2026-05-26 | 新增：归档格式完整性章节——真实格式必须与扩展名一致的规则、验证单行命令、Windows 配置 DO/DON'T 列表、真实事故参考（XSPEC-231 / 关闭 issue #113） |
 | 1.0.0 | 2026-04-15 | 初始发行 — XSPEC-034 Phase 1 |
 
 ---

package/bundled/locales/zh-CN/core/pipeline-security-gates.md

@@ -0,0 +1,126 @@
+---
+source: ../../../core/pipeline-security-gates.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: a2d6e88e26c8
+status: current
+---
+
+# Pipeline Security Gates（CI Pipeline 安全检查点）
+
+> **Language**: [English](../../../core/pipeline-security-gates.md) | [繁體中文](../../zh-TW/core/pipeline-security-gates.md) | 简体中文
+
+---
+
+## 概述
+
+本标准定义嵌入 CI pipeline 各阶段的安全检查点，涵盖 SAST、DAST、SCA（含 SBOM）和密钥扫描，并明确规定各类发现的阻断（Block）、警告（Warn）、记录（Log）行为。
+
+---
+
+## 核心原则
+
+- **密钥扫描在 pre-commit**：所有包含密钥的提交都必须被阻断，不得例外
+- **SAST 在构建后**：Critical 和 High 等级发现阻断 pipeline
+- **SCA + SBOM 在打包阶段**：追踪依赖组件风险并生成物料清单
+- **DAST 在 staging 部署后**：对运行中的应用进行动态扫描
+- **安全闸门失败 = pipeline 失败**：不得视为可忽略的警告
+- **任何绕过都需审计轨迹**：禁止静默跳过安全闸门
+
+---
+
+## 安全闸门位置与配置
+
+### 1. Pre-Commit — 密钥扫描
+
+| 项目 | 说明 |
+|------|------|
+| 扫描范围 | 所有 staged 文件 |
+| 推荐工具 | gitleaks、trufflehog、detect-secrets |
+| 阻断条件 | 任何密钥模式匹配 |
+| 可跳过 | 否（`never_skip: true`） |
+
+**重要**：此闸门必须在代码进入版本控制前执行，一旦密钥进入 git 历史便需要完整的密钥轮换流程。
+
+---
+
+### 2. Post-Build — SAST（静态应用安全测试）
+
+| 项目 | 说明 |
+|------|------|
+| 扫描范围 | 源代码 + 构建产出物 |
+| 推荐工具 | semgrep、codeql、sonarqube |
+| 阻断条件 | Critical、High |
+| 警告条件 | Medium |
+| 仅记录 | Low、Info |
+
+---
+
+### 3. Package Stage — SCA + SBOM
+
+| 项目 | 说明 |
+|------|------|
+| 扫描范围 | 依赖组件 + 容器镜像 |
+| 推荐工具 | trivy、syft、grype、dependabot |
+| 阻断条件 | Critical CVE（有可用修复版本） |
+| 警告条件 | High CVE、过时依赖组件 |
+| SBOM 格式 | SPDX、CycloneDX |
+
+**SBOM 用途**：上传至 dependency-track 或 grype-db 进行持续监控。
+
+---
+
+### 4. Post-Staging Deploy — DAST（动态应用安全测试）
+
+| 项目 | 说明 |
+|------|------|
+| 扫描范围 | 运行中的 staging 应用程序 |
+| 推荐工具 | ZAP、nuclei、BurpSuite Enterprise |
+| 阻断条件 | Critical |
+| 需审核批准 | High |
+| 警告条件 | Medium |
+
+---
+
+## 严重性响应矩阵
+
+| 严重性 | 动作 | 通知对象 | SLA |
+|--------|------|---------|-----|
+| Critical | 阻断 pipeline | 安全团队 | 立即 |
+| High | 阻断 pipeline | 团队负责人 | 当日 |
+| Medium | 警告 + 需审核批准 | 开发者 | 下个 Sprint |
+| Low | 仅记录 | 无 | Backlog |
+
+---
+
+## 绕过策略
+
+**默认禁止绕过**。
+
+若有特殊情况：
+- **例外流程**：需书面安全审核 + 审计日志记录
+- **紧急绕过**：有时效性令牌（time-limited token）+ 强制事后审查
+
+---
+
+## 集成点
+
+| 集成项目 | 说明 |
+|---------|------|
+| 密钥管理 | 集成 HashiCorp Vault 或 AWS Secrets Manager 进行密钥注入 |
+| SBOM 注册表 | 上传 SBOM 至 dependency-track 或 grype-db 持续监控 |
+| 事故响应 | Critical 发现自动创建事故工单 |
+
+---
+
+## 相关标准
+
+- [security-standards.md](../../../core/security-standards.md) — 应用安全基础标准
+- [pipeline-integration-standards.md](../../../core/pipeline-integration-standards.md) — CI 管道集成标准
+- [deployment-standards.md](../../../core/deployment-standards.md) — 部署基础原则
+- AI 格式：[pipeline-security-gates.ai.yaml](../../../ai/standards/pipeline-security-gates.ai.yaml)
+
+---
+
+**Scope**: universal