universal-dev-standards 5.17.0 → 6.0.0

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

@@ -1,8 +1,9 @@
 ---
 source: ../../../core/deployment-standards.md
-source_version: 1.0.0
-translation_version: 1.0.0
-last_synced: 2026-03-24
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-06-10
+source_hash: ede6223c8aba
 status: current
 ---
 
@@ -10,8 +11,8 @@ status: current
 
 # 部署标准
 
-**版本**: 1.0.0
-**最后更新**: 2026-02-09
+**版本**: 1.1.0
+**最后更新**: 2026-05-26
 **适用范围**: 所有具有部署流水线的软件项目
 **范围**: universal
 **行业标准**: Twelve-Factor App, Google SRE — Release Engineering, DORA State of DevOps
@@ -65,6 +66,13 @@ status: current
           └── 否 → 滚动更新
 ```
 
+### 策略组合
+
+各策略并不互斥，常见组合如下：
+- **金丝雀 + 功能标志**：以禁用状态的标志部署金丝雀版本，先为金丝雀组开启标志
+- **蓝绿 + 功能标志**：切换流量至绿环境后，再渐进启用标志
+- **滚动 + 功能标志**：滚动发布代码，然后独立控制功能暴露
+
 ---
 
 ## 部署验证
@@ -107,18 +115,329 @@ Smoke Test 失败必须阻断部署并触发 rollback。
 
 ---
 
+## 功能标志生命周期
+
+### 标志类型
+
+| 类型 | 用途 | 生命周期 | 示例 |
+|------|------|----------|------|
+| **Release（发布）** | 控制功能上线 | 数天至数周 | `enable_new_checkout` |
+| **Experiment（实验）** | A/B 测试 | 数周至数月 | `experiment_pricing_v2` |
+| **Ops（运营）** | 运营控制（紧急开关） | 永久 | `enable_cache_layer` |
+| **Permission（权限）** | 用户权益 | 永久 | `feature_premium_export` |
+
+### 生命周期阶段
+
+| 阶段 | 操作 | 目标时长 |
+|------|------|----------|
+| **1. 创建** | 定义标志、设置默认值（关闭）、记录用途与负责人 | 第 0 天 |
+| **2. 启用** | 渐进上线：1% → 10% → 50% → 100% | 数天至数周 |
+| **3. 监控** | 跟踪指标、错误率、用户反馈 | 100% 后 1-2 周 |
+| **4. 清理** | 从代码移除标志、删除配置、更新测试 | 全量上线后 1 个 sprint 内 |
+
+### 技术债规则
+
+| 规则 | 执行方式 |
+|------|----------|
+| Release 标志必须在全量上线后 **30 天**内移除 | 自动提醒 / 工单 |
+| Experiment 标志必须在 **90 天**内移除 | 季度审计 |
+| 每个标志必须有**负责人**和**到期日** | 标志创建检查清单 |
+| 每个服务的标志数量不应超过 **20** 个 | 仪表板告警 |
+
+---
+
+## 回滚策略
+
+### 自动触发条件
+
+| 指标 | 告警阈值 | 自动回滚阈值 | 观测窗口 |
+|------|---------|-------------|----------|
+| **错误率** | > 1% | > 5% | 5 分钟 |
+| **p95 延迟** | > 2× 基线 | > 3× 基线 | 5 分钟 |
+| **Health Check** | 1 次失败 | 连续 3 次失败 | 立即 |
+| **CPU 使用率** | > 80% | > 95% | 10 分钟 |
+| **内存使用率** | > 85% | > 95% | 10 分钟 |
+
+### 手动触发场景
+
+- 客户报告影响核心功能的严重缺陷
+- 部署后发现安全漏洞
+- 检测到数据损坏或不一致
+- 发现违反法规合规的问题
+
+### 严重性决策矩阵
+
+| 严重性 | 影响 | 操作 | 时限 |
+|--------|------|------|------|
+| **P1 严重** | 服务中断、数据丢失 | 立即回滚，全员响应 | < 5 分钟 |
+| **P2 高** | 主要功能故障、显著用户影响 | 在窗口内回滚 | < 15 分钟 |
+| **P3 中** | 次要功能故障、存在变通方案 | 决定：回滚或热修复 | < 1 小时 |
+| **P4 低** | 外观问题、边缘情况 | 在下次版本中前向修复 | 下次部署 |
+
+### 回滚方法
+
+| 方法 | 适用时机 | 速度 |
+|------|---------|------|
+| **回退部署** | 应用代码问题，无数据库变更 | < 5 分钟 |
+| **功能标志切换** | 标志控制的功能出现问题 | 即时 |
+| **数据库回滚** | 数据库迁移失败（如可逆） | 5-30 分钟 |
+
+---
+
+## 环境一致性
+
+### 三大差距（Twelve-Factor App）
+
+| 差距 | 反模式 | 最佳实践 |
+|------|--------|----------|
+| **时间差距** | 开发与部署之间间隔数周 | 开发后数小时即部署 |
+| **人员差距** | 开发者编写，运维人员部署 | 编写代码的开发者参与部署 |
+| **工具差距** | 不同环境使用不同技术栈 | 各处使用相同的后端服务 |
+
+### 环境一致性检查清单
+
+#### 基础设施
+- [ ] 各环境使用相同的操作系统系列与版本
+- [ ] 相同的容器运行时与编排器版本
+- [ ] 相同的网络拓扑（负载均衡器、服务网格）
+- [ ] 相同的资源分配比例（预发布 = 生产 × 缩放因子）
+
+#### 应用程序
+- [ ] 各环境部署相同的应用程序版本
+- [ ] 相同的依赖版本（已提交锁文件）
+- [ ] 相同的运行时版本（Node.js、Python、JVM 等）
+- [ ] 相同的构建产物（一次构建，多处部署）
+
+#### 数据
+- [ ] 相同的数据库引擎与版本
+- [ ] 相同的数据库迁移工具
+- [ ] 预发布环境有真实的数据量（脱敏后的生产数据）
+- [ ] 相同的消息队列与缓存实现
+
+#### 配置
+- [ ] 环境特定值通过环境变量管理
+- [ ] 无环境特定代码路径（无 `if (env === 'production')`）
+- [ ] 各环境使用相同的密钥管理工具
+- [ ] 配置差异已记录并最小化
+
+---
+
+## 部署前检查清单
+
+### 1. 代码质量
+- [ ] 所有测试通过（单元、集成、E2E）
+- [ ] 代码审查已批准
+- [ ] 无关键静态分析警告
+- [ ] 测试覆盖率未下降
+
+### 2. 安全性
+- [ ] 依赖漏洞扫描通过
+- [ ] 代码或配置文件中无密钥
+- [ ] 已配置安全响应头
+- [ ] 认证/授权变更已审查
+
+### 3. 性能
+- [ ] 受影响端点的负载测试已完成
+- [ ] 未检测到性能回退
+- [ ] 数据库查询性能已验证
+- [ ] 缓存失效策略已确认
+
+### 4. 数据库
+- [ ] 迁移脚本已在预发布环境测试
+- [ ] 回滚迁移已可用并测试
+- [ ] 无不兼容的 schema 变更（无向后兼容性）
+- [ ] 已用接近生产量的数据验证数据迁移
+
+### 5. 配置与依赖
+- [ ] 环境变量已记录并设置
+- [ ] 功能标志已配置正确默认值
+- [ ] 第三方服务依赖已验证
+- [ ] API 版本兼容性已确认
+
+### 6. 部署就绪
+- [ ] 部署 runbook 已更新
+- [ ] 回滚流程已记录并测试
+- [ ] 监控仪表板已准备
+- [ ] 告警阈值已配置
+
+### 7. 沟通
+- [ ] 利益相关者已收到部署窗口通知
+- [ ] 值班工程师已确认并就位
+- [ ] 客户支持已了解变更内容
+- [ ] 状态页已准备（如对外公开）
+
+---
+
+## 防御性部署排序
+
+当部署脚本替换正在运行的安装（Windows IIS、SystemD 托管服务或任何「停止 → 替换 → 启动」工作流常见的破坏性更新模式）时，破坏性步骤与验证的顺序不容有误。
+
+### 禁止的排序
+
+```
+1. 停止服务
+2. 解压新包         ← 格式不匹配时可能静默无操作
+3. 删除旧安装       ← 无条件执行——会销毁运行中的安装
+4. 复制新安装       ← 抛出错误（源不存在）
+5. 启动服务         ← 无法启动（二进制文件已消失）
+```
+
+若步骤 2 静默失败（归档损坏、格式错误、磁盘满、权限问题），步骤 3 仍会执行并**销毁运行中的安装**，只能依靠备份恢复——但备份仅能完整回滚，**无法防止服务中断**，因为服务已经停止了。
+
+### 必须遵循的排序——先解压和验证，再删除
+
+破坏性部署排序**必须**为：
+
+```
+1. 停止服务
+2. 将新包解压到暂存区      （不直接覆盖运行中的安装）
+3. ✅ 验证暂存区包含预期产物
+   ↑ 验证失败则终止，不得触碰运行中的安装
+4. 备份运行中的安装         （或提前完成——两者都做更好）
+5. 删除旧安装（保留日志/运行时数据）
+6. 从暂存区复制新安装
+7. 还原保留的配置
+8. 启动服务
+9. 完整性检查（HTTP 探针 / 健康检查端点）
+```
+
+**步骤 3 验证不可妥协。** 最低验证要求是确认新包中至少一个已知文件存在于暂存区。如果有可用的文件清单，则优先选择哈希比对。
+
+### 验证代码片段
+
+**PowerShell**（Windows IIS 部署）：
+
+```powershell
+$staging = "C:\deploy\staging-$(Get-Date -Format yyyyMMddHHmmss)"
+Expand-Archive -Path $zipPath -DestinationPath $staging -Force
+
+# 不可妥协：在触碰运行中安装前验证暂存区
+if (-not (Test-Path "$staging\api\MyApp.dll")) {
+    throw "Expected $staging\api\MyApp.dll not found — archive may be corrupt or wrong format. Aborting deploy. Live install untouched."
+}
+
+# 只有此时才可触碰运行中的安装
+Copy-Item "$apiDir" "$backupDir" -Recurse -Force
+Get-ChildItem $apiDir -Exclude logs | Remove-Item -Recurse -Force
+Copy-Item "$staging\api\*" $apiDir -Recurse
+```
+
+**bash**（Linux SystemD 托管服务）：
+
+```bash
+set -euo pipefail
+
+STAGING="/srv/deploy/staging-$(date +%Y%m%d%H%M%S)"
+mkdir -p "$STAGING"
+tar -xzf "$ARCHIVE" -C "$STAGING"
+
+# 不可妥协：在触碰运行中安装前验证暂存区
+if [ ! -f "$STAGING/bin/myapp" ]; then
+  echo "ERROR: Expected $STAGING/bin/myapp not found. Aborting deploy. Live install untouched." >&2
+  exit 1
+fi
+
+# 只有此时才可触碰运行中的安装
+systemctl stop myapp
+cp -a "$LIVE_DIR" "$BACKUP_DIR"
+find "$LIVE_DIR" -mindepth 1 -not -path "$LIVE_DIR/logs*" -delete
+cp -a "$STAGING"/* "$LIVE_DIR/"
+systemctl start myapp
+```
+
+### 失败模式分析
+
+| 失败模式 | 防护措施 |
+|----------|---------|
+| 归档格式错误（如 tar 改名为 `.zip`） | 步骤 3 验证失败——运行中的安装未受影响 |
+| 解压不完整（磁盘在解压中途已满） | 步骤 3 验证失败——运行中的安装未受影响 |
+| 归档根目录结构变更（多余的包装目录、缺少关键文件） | 步骤 3 验证失败——运行中的安装未受影响 |
+| 权限问题（解压步骤有读权限但无写权限） | 步骤 3 验证失败——运行中的安装未受影响 |
+| 备份脚本本身失败 | 步骤 4 后可选进行二次检查 |
+
+### 上游预防
+
+在消费者侧验证是最后一道防线。**上游**预防——从一开始就拒绝生产格式错误的归档——由[打包标准 — 归档格式完整性](packaging-standards.md#归档格式完整性)涵盖。两层共同形成纵深防御组合；单独任何一层都不足够。
+
+### 失败模式参考（真实事故）
+
+某 Windows IIS 生产部署脚本（2026-05-24）对一个 tar 改名为 `.zip` 的归档运行了 `Expand-Archive`（静默无操作），然后对运行中的 `apiDir` 执行了 `Remove-Item -Recurse`，再从根本不存在的源路径执行 `Copy-Item`（因为什么都没有被解压）。运行中的安装被清空，AppPool 停止，生产环境中断了约 3 分钟，直到基于备份的回滚完成。在暂存阶段增加步骤 3 验证（`Test-Path "$staging/api/MyApp.dll"`）本可在运行中的安装完全未受影响的情况下终止部署。
+
+---
+
+## 部署后检查清单
+
+### 立即（< 5 分钟）
+
+- [ ] 健康检查端点返回 200
+- [ ] 应用程序日志无错误
+- [ ] 核心业务指标未变化（订单、注册等）
+- [ ] 监控仪表板显示正常模式
+
+### 短期（< 1 小时）
+
+- [ ] 错误率在可接受阈值内（< 0.1%）
+- [ ] 响应时间符合 SLA（p95 < 目标）
+- [ ] 客户支持工单无增加
+- [ ] 数据库性能稳定
+
+### 中期（< 24 小时）
+
+- [ ] 批处理任务成功完成
+- [ ] 数据一致性已验证
+- [ ] 无内存泄漏或资源降级
+- [ ] 功能标志渐进上线按计划推进
+
+### 长期（< 1 周）
+
+- [ ] 功能标志清理已安排
+- [ ] 部署回顾已完成
+- [ ] 监控阈值已按需调整
+- [ ] 文档已更新，记录经验教训
+
+---
+
+## DORA 指标
+
+| 指标 | 精英 | 高 | 中 | 低 |
+|------|------|----|----|-----|
+| **部署频率** | 按需（每天多次） | 每周至每月 | 每月至每半年 | 每半年至每年 |
+| **变更前置时间** | < 1 小时 | 1 天至 1 周 | 1 周至 1 月 | 1 至 6 个月 |
+| **变更失败率** | < 5% | 5-10% | 10-15% | > 15% |
+| **平均恢复时间 (MTTR)** | < 1 小时 | < 1 天 | < 1 周 | > 1 周 |
+
+### 追踪建议
+
+| 指标 | 数据来源 | 工具示例 |
+|------|---------|----------|
+| **部署频率** | CI/CD 流水线事件 | GitHub Actions、GitLab CI、Jenkins |
+| **前置时间** | 首次提交 → 生产部署 | Git log + 部署时间戳 |
+| **变更失败率** | 回滚次数 / 总部署次数 | 事故跟踪 + 部署日志 |
+| **MTTR** | 事故开始 → 解决 | PagerDuty、Opsgenie、事故日志 |
+
+---
+
 ## 相关标准
 
-- [安全标准](security-standards.md)
-- [性能标准](performance-standards.md)
-- [测试标准](testing-standards.md)
-- [签入标准](checkin-standards.md) - 部署前质量关卡
+- [代码签入标准](checkin-standards.md) - 部署前质量关卡
+- [测试标准](testing-standards.md) - 部署就绪的测试要求
+- [安全标准](security-standards.md) - 部署安全检查清单
+- [性能标准](performance-standards.md) - 部署前性能验证
 - [Changelog 标准](changelog-standards.md) - 记录已部署变更
 - [Git 工作流标准](git-workflow.md) - 分支策略与发布流程
 - [版本标准](versioning.md) - 发布版本号码
 
 ---
 
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 1.1.0 | 2026-05-26 | 新增：防御性部署排序章节——必须先解压验证再删除的序列、PowerShell + bash 验证代码片段、失败模式映射、交叉引用打包标准归档格式完整性（XSPEC-231 / 关闭 issue #110） |
+| 1.0.0 | 2026-02-09 | 初始发行 |
+
+---
+
 ## 许可证
 
 本标准采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 发布。

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

@@ -3,7 +3,7 @@ source: ../../../core/deprecation-standards.md
 source_version: 1.0.0
 translation_version: 1.0.0
 last_synced: 2026-04-10
-status: current
+status: stale
 ---
 
 # 弃用与日落标准

package/bundled/locales/zh-CN/core/developer-memory.md

@@ -3,7 +3,7 @@ source: ../../../core/developer-memory.md
 source_version: 1.0.0
 translation_version: 1.0.0
 last_synced: 2026-02-07
-status: current
+status: stale
 ---
 
 # 开发者持久记忆标准
@@ -528,7 +528,7 @@ by_category:
 
 | 模式 | 特性 | 示例 | 需要 Skill？ |
 |------|------|------|------------|
-| **用户触发** | 用户明确调用、多步骤引导式工作流 | `/commit`、`/review`、`/sdd` | 是 |
+| **用户触发** | 用户明确调用、多步骤引导式工作流 | `/commit`、`/code-review`、`/sdd` | 是 |
 | **Always-On Protocol** | AI 加载 ai.yaml 后持续遵循规则 | 反幻觉、开发者记忆 | 否 |
 
 ### 理由：不需要 CLI / Skill / 斜杠命令

package/bundled/locales/zh-CN/core/disaster-recovery-drill.md

@@ -0,0 +1,87 @@
+---
+source: ../../../core/disaster-recovery-drill.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: c97a5f4a554b
+status: current
+---
+
+# 灾难恢复演练标准
+
+> **Language**: [English](../../../core/disaster-recovery-drill.md) | [繁體中文](../../zh-TW/core/disaster-recovery-drill.md) | 简体中文
+
+## 概述
+
+未经测试的 DR 计划只是虚假的安全感。从未在压力下实际执行过恢复 runbook 的团队，会在最糟糕的时间点才发现缺口。DR 演练能安全地暴露这些缺口。
+
+## RTO/RPO 目标
+
+在撰写 runbook 之前先定义这些指标：
+
+| 指标 | 定义 | 商用等级目标 |
+|--------|-----------|--------------------------|
+| RTO (Recovery Time Objective) | 可接受的最大停机时间 | < 1 小时 |
+| RPO (Recovery Point Objective) | 可接受的最大数据丢失量 | < 24 小时（每日备份） |
+
+## 备份还原脚本
+
+```bash
+#!/usr/bin/env bash
+# scripts/backup-restore.sh — DR drill backup restore verification
+set -euo pipefail
+
+BACKUP_DIR="${BACKUP_DIR:-/var/backups/app}"
+RESTORE_DIR="${RESTORE_DIR:-/tmp/dr-restore}"
+DB_FILE="${DB_FILE:-app.db}"
+
+echo "=== DR Drill: Backup Restore Verification ==="
+echo "Source: ${BACKUP_DIR}/${DB_FILE}.backup"
+echo "Target: ${RESTORE_DIR}/${DB_FILE}"
+
+mkdir -p "$RESTORE_DIR"
+
+# Find latest backup
+LATEST=$(ls -t "${BACKUP_DIR}"/*.backup 2>/dev/null | head -1)
+if [[ -z "$LATEST" ]]; then
+  echo "FAIL: No backup found in ${BACKUP_DIR}"
+  exit 1
+fi
+
+# Restore
+cp "$LATEST" "${RESTORE_DIR}/${DB_FILE}"
+
+# Verify integrity (SQLite)
+if command -v sqlite3 >/dev/null 2>&1; then
+  sqlite3 "${RESTORE_DIR}/${DB_FILE}" "PRAGMA integrity_check;" | grep -q "ok" && \
+    echo "OK: Database integrity check passed" || \
+    { echo "FAIL: Integrity check failed"; exit 1; }
+fi
+
+BACKUP_AGE=$(( ($(date +%s) - $(stat -c %Y "$LATEST" 2>/dev/null || stat -f %m "$LATEST")) / 3600 ))
+echo "OK: Backup age: ${BACKUP_AGE} hours (RPO target: 24h)"
+
+echo "=== PASS: Restore complete ==="
+```
+
+## Game Day 协议
+
+1. **公告（Announce）**：提前一周通知团队，定义演练范围
+2. **基准（Baseline）**：记录当前系统状态
+3. **注入（Inject）**：模拟故障（重命名/删除 DB、kill process 等）
+4. **执行（Execute）**：团队从头遵循 runbook 操作——不准抄捷径
+5. **量测（Measure）**：记录 RTO、RPO 与遇到的问题
+6. **回顾（Retrospective）**：哪里不够清晰？哪里有遗漏？
+
+## Runbook 模板
+
+完整 runbook 模板请见 `docs/DR-RUNBOOK.md`。
+
+## 相关标准
+
+- [Deployment Standards](deployment-standards.md) — 部署管线
+- [Chaos Engineering Standards](chaos-engineering-standards.md) — 故障注入
+- [Verification Evidence Standards](verification-evidence.md) — 演练记录
+
+
+**Scope**: universal

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

@@ -291,7 +291,7 @@ graduated-to: path/to/formal-doc.md  # 若已毕业
 
 ## 相关标准
 
-- [API 文档标准](api-documentation-standards.md)
+- [API 文档标准](api-design-standards.md)
 - [变更日志标准](changelog-standards.md)
 - [规格驱动开发](spec-driven-development.md)
 

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

@@ -612,7 +612,7 @@ channels:
 | 需求 | 描述 | 示例 |
 |------|------|------|
 | **浅显语言** | 使用清晰、简单的语言；目标为 8 年级阅读程度 | 避免：「utilize」→ 使用：「use」 |
-| **图片替代文字** | 为所有非装饰性图片提供描述性替代文字 | `![显示三层架构的架构图](arch.png)` |
+| **图片替代文字** | 为所有非装饰性图片提供描述性替代文字 | `![显示三层架构的架构图](path/to/arch.png)` |
 | **标题层级** | 使用正确的标题层级（h1→h2→h3），不跳级 | 不要从 `#` 直接跳到 `###` |
 | **链接文字** | 使用描述性链接文字，而非「点此」 | 避免：[点此] → 使用：[安装指南] |
 | **代码区块** | 使用带语言标示的围栏式代码区块 | ` ```javascript ` 而非 ` ``` ` |

package/bundled/locales/zh-CN/core/error-code-standards.md

@@ -3,7 +3,7 @@ source: ../../../core/error-code-standards.md
 source_version: 1.2.0
 translation_version: 1.1.0
 last_synced: 2026-01-08
-status: outdated
+status: stale
 ---
 
 > **语言**: [English](../../../core/error-code-standards.md) | [简体中文](../../zh-TW/core/error-code-standards.md) | 简体中文
@@ -171,7 +171,7 @@ AUTH_VAL_001
 ## 相关标准
 
 - [日志标准](logging-standards.md) - 错误日志实践
-- [API 文档标准](api-documentation-standards.md) - 错误响应文档
+- [API 文档标准](api-design-standards.md) - 错误响应文档
 
 ---