# 交付物模板：non-functional-design.md + non-functional-design.html

> 7 维度详解见 `nfr-dimensions.md`。

## frontmatter

```yaml
---
verdict: pass
upstream: issues.md
downstream: code-architecture.md
backfed_from:   # 被哪些下游阶段反哺过（如 [⑤]），初始为空
---
```

## 章节结构

```markdown
# 非功能性设计 — {主题}

## 分析矩阵

| Issue | 方案 | 安全 | 数据 | 性能 | 并发 | 稳定性 | 兼容性 | 可观测 |
|-------|------|------|------|------|------|--------|--------|--------|
| #1 | 方案A | ⚠️ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ⚠️ |
| #3 | 方案B | ✅ | ⚠️ | ✅ | ⚠️ | ⚠️ | ✅ | ✅ |

（✅ 无风险 / ⚠️ 有风险已缓解 / ❌ 不可接受需回退 / — 不适用+理由）

## 详细分析

> **写量规则（反膨胀，N issue × 7 维度 = 7N 子节的最大瘦身杠杆）：**
> 矩阵标 ✅ 的维度**只写一行理由**（为何不适用 / 无风险）；
> 只有 ⚠️ 维度才按 `nfr-dimensions.md` 的 4 字段模板展开（风险/影响范围/缓解/残余）。

### Issue #1: {标题} — 方案 A

#### ⚠️ 维度：按 4 字段模板展开
#### ✅ 维度：一行理由即可（不套模板）

## 缓解项回灌登记（Mitigation Rollback）— [MANDATORY]

> 每条缓解方案不能只留在本文档——必须落地为下游可执行项。
> 未回灌的缓解 = 设计期发现风险却不修 = NFR 分析白做。
>
> **「验收方式」列（关键，防风险裸奔）：** 每条缓解标一个验收方式，决定它是否进⑤test-matrix
> 成为实现验收的一部分。安全/性能/可观测/兼容类风险常常不是时序图异常分支，
> 若不标「代码测试」，会在⑤被遗漏、最终无人测试。

| 缓解项 | 来源 Issue# | 维度 | 回灌去向 | 落地为 | **验收方式** | 状态 |
|--------|------------|------|---------|--------|------------|------|
| 幂等键 | #1 | 并发 | ⑤契约 | API 签名加 idempotency-key 字段 | 骨架约束 | 待落 |
| 审计日志 | #3 | 可观测 | ③issue | 新 issue #7 [P1] | 代码测试 | 待落 |
| 事务边界 | #1 | 数据 | ⑤时序图 | §4.1 时序图标事务边界 | 骨架约束 | 待落 |
| 输入参数化防注入 | #1 | 安全 | ⑤test-matrix | 验证恶意输入被拦截 | 代码测试 | 待落 |
| 告警阈值 | #3 | 可观测 | 运维项 | Prometheus 规则 | 运维项 | 待落 |

**回灌去向规则：**
- 契约/签名/时序图层面 → ⑤code-arch（标注到具体章节）
- 需独立开发工作 → ③issues（新建 issue，标 P 级 + blocked_by）
- 纯监控/告警配置 → 本表记录即可（运维项，不进开发 issue）

**验收方式取值（四选一，反膨胀阀）：**

| 验收方式 | 含义 | 下游落点 | 例子 |
|---------|------|---------|------|
| **代码测试** | 风险可在代码层断言 → 生成 NFR-AC 进⑤test-matrix | ⑤test-matrix「NFR 风险→用例映射表」 | 注入被拦截 / 越权被拒 / 降级返回兜底值 / 日志含 traceId |
| **骨架约束** | 风险体现为签名/字段/锁的**存在性**，由⑤骨架 tsc 验证 | ⑤骨架（已有机制，不重复进测试） | 幂等键字段 / 锁字段 / 事务边界标注 |
| **性能混沌** | 可量化 SLA 目标（吞吐/延迟/可用性/故障恢复），需压测/混沌环境+脚本，**非单次代码可断言** | ⑥独立 perf/chaos Wave 或 pre-prod gate（**不进⑤**——⑤来源B 是单测/集成测，压不住这类） | P99<100ms@1000QPS / 单实例宕机仍可用 / 限流触发后雪崩被阻断 |
| **运维项** | 纯部署/配置/监控，与代码实现无关 | 本表记录，不进开发 issue | 告警阈值 / 灰度配比 / 连接池大小 |

**「代码测试」判定标准（防止 agent 把所有风险都塞进测试）：**
只有同时满足以下才标「代码测试」——
1. **实现层不确定性**：缓解逻辑是代码行为（校验/拦截/降级/补偿），不是配置
2. **可断言**：能写明确的通过/失败断言（"输入 X 返回 403" / "日志含 traceId"），不是主观感受

纯运维项（告警阈值、监控配置、连接池大小）走「运维项」列，不进测试。
体现为签名/字段存在性的走「骨架约束」，由⑤骨架 tsc gate 兜住，不重复进测试。

**回灌指针可验证性（即时承诺 vs 延期承诺）：**

回灌去向分两类，④ 执行时只能验证前者——

| 回灌去向 | 性质 | ④ 执行时可查？ | 谁闭合 |
|---------|------|---------------|--------|
| **③ 新 issue #N** | **即时承诺**（③已产出）| ✅ Step2 回灌重建器从 issues.md 反向核对 #N 是否真实存在 | ④ Step2 |
| **⑤ 章节/字段/test-matrix** | **延期承诺**（⑤尚未产出）| ❌ ⑤还没写，查不了 | ⑤ code-arch §6「来源 B：NFR 风险→用例映射表」反向核对每条 `验收方式=代码测试` 的缓解项有 ≥1 对应用例 |
| **⑥ perf/chaos Wave** | **延期承诺**（⑥尚未编排）| ❌ ⑥还没编排，查不了 | ⑥ execution-plan：`验收方式=性能混沌` 的缓解项有对应 Wave 条目（**不进⑤**，因⑤来源B 是单测/集成测） |

> ④ 不重复查 ⑤ 指针——⑤ 自己的 Step2 已接住这条闭环（来源 B 双向映射）。④ 只对**现在能查的 ③ 指针**负责：说「去 ③ 新 issue #7」就必须 #7 真在 issues.md 里。

## 残余风险登记

| 风险 | 影响 | 接受理由 | 监控方式 |
|------|------|---------|---------|

## 需⑤骨架验证的副作用（标记登记）
（标记为需⑤骨架验证的高不确定性副作用：验证什么、预期结论方向。stub 方法进⑤骨架，结论回写本节）
```