# 非功能性设计 7 维度

> 评估 Step 3 每个 issue 解决方案对系统的副作用，并给出缓解方案。
> 不是「检查清单填空」——每个维度要回答「这个改动带来什么风险 + 如何缓解」。

> **各维度模板仅 ⚠️ 必填（反膨胀，全局规则）：** 分析矩阵标 ✅ 的维度**只写一行理由**（为何不适用/无风险），不套下面 4 字段模板铺开；只有 ⚠️ 维度才按对应模板展开。CW gate 的机器检查（check-nfr）不查详细分析字段数，但写量在此。

## 维度 1: 系统安全（Security）

### 关注点

- **认证与授权**：新增功能是否需要新的权限模型？现有权限边界是否被打破？
- **注入风险**：用户输入是否直接进入查询/命令/模板？是否有参数化防护？
- **越权访问**：横向越权（A 用户访问 B 用户数据）、纵向越权（普通用户访问管理员功能）
- **敏感数据暴露**：日志/错误信息/响应体是否泄漏敏感字段？

### 模板

```markdown
### 安全影响

**风险**: {issue 解决方案引入的安全风险}
**影响范围**: {哪些接口/数据/角色受影响}
**缓解方案**: {认证加固/输入校验/权限检查/数据脱敏}
**残余风险**: {缓解后仍存在的，标注接受理由}
```

---

## 维度 2: 业务数据安全（Data Integrity）

### 关注点

- **数据一致性**：跨表/跨系统更新是否事务保护？部分失败如何补偿？
- **并发控制**：多用户同时操作同一数据——乐观锁/悲观锁/幂等？
- **数据迁移**：schema 变更对存量数据的影响？默认值？回滚策略？
- **数据丢失**：哪些操作不可逆？是否有软删除/回收站/审计日志？

### 模板

```markdown
### 数据一致性影响

**事务边界**: {哪些操作必须在同一事务}
**并发场景**: {最可能的并发冲突 + 控制策略}
**迁移方案**: {存量数据如何处理}
**回滚策略**: {出错时如何恢复}
```

---

## 维度 3: 性能（Performance）

### 关注点

- **吞吐量**：预期 QPS/并发量？瓶颈在哪？（CPU/IO/DB/网络）
- **延迟**：关键路径的 P99 延迟目标？是否有 N+1 查询？
- **数据量增长**：表数据量从 1K→100K→10M 时性能如何衰减？
- **资源消耗**：内存/连接池/文件句柄是否泄漏？

### 模板

```markdown
### 性能影响

**预期负载**: {QPS/并发数/数据量}
**关键路径延迟**: {P99 目标 + 瓶颈分析}
**扩展性瓶颈**: {数据量增长时的衰减点}
**优化方案**: {索引/缓存/批量/异步}
```

---

## 维度 4: 并发控制（Concurrency）

### 关注点

- **竞态条件**：check-then-act 模式是否有时间窗口漏洞？
- **幂等性**：重复请求（网络重试/用户双击）是否产生副作用？
- **锁粒度**：悲观锁的粒度是否过粗（影响吞吐）？乐观锁的冲突率？
- **分布式锁**：多实例部署时是否需要分布式锁？锁的超时与续期？

### 模板

```markdown
### 并发控制

**竞态场景**: {具体的 check-then-act 漏洞}
**幂等策略**: {请求 ID/状态机守卫/数据库唯一约束}
**锁策略**: {乐观/悲观/无锁 + 粒度}
**分布式考虑**: {多实例下的并发控制}
```

---

## 维度 5: 稳定性·高可用（Reliability & HA）

### 关注点

- **降级**：依赖的外部服务不可用时，系统是报错还是降级运行？
- **熔断**：下游服务持续超时/失败时，是否熔断防止雪崩？
- **限流**：突发流量是否有限流保护？
- **容错**：单点故障（某实例/某依赖挂了）是否影响整体可用性？
- **重试**：失败重试策略（次数/退避/幂等保证）？

### 模板

```markdown
### 稳定性影响

**故障场景**: {依赖不可用时的系统行为}
**降级方案**: {报错 vs 降级 + 降级后的体验}
**熔断/限流**: {阈值 + 触发后行为}
**重试策略**: {次数/退避算法/幂等保证}
**SLA 影响**: {改动对可用性目标的影响}
```

---

## 维度 6: 兼容性（Compatibility）

### 关注点

- **前后端兼容**：API 变更（新增/删除/修改字段）对现有前端的影响？版本化策略？
- **数据兼容**：数据格式变更对存量数据和下游消费者的影响？
- **协议兼容**：通信协议变更（REST→gRPC）的迁移方案？
- **版本兼容**：灰度发布/回滚时新旧版本能否共存？
- **向后兼容**：新功能是否破坏旧客户端的使用？

### 模板

```markdown
### 兼容性影响

**API 变更**: {breaking/non-breaking + 版本策略}
**数据兼容**: {格式变更 + 迁移方案}
**客户端影响**: {旧客户端是否仍可用}
**灰度/回滚**: {新旧版本共存的兼容性}
```

---

## 维度 7: 可观测性（Observability）

### 关注点

- **日志**：关键操作是否有结构化日志？日志级别是否合理？是否含 trace ID？
- **指标**：是否有业务指标（成功率/延迟/吞吐）和系统指标（资源使用）？
- **追踪**：跨服务调用链是否可追踪？是否有 distributed tracing？
- **告警**：哪些异常需要告警？告警阈值和通知方式？
- **审计**：敏感操作是否有审计日志（谁/何时/做了什么）？

### 模板

```markdown
### 可观测性

**日志**: {关键操作的结构化日志 + trace ID}
**指标**: {业务/系统指标 + 采集方式}
**追踪**: {跨服务调用链追踪}
**告警**: {告警条件 + 阈值 + 通知方式}
**审计**: {敏感操作的审计日志}
```

---

## Prototype 验证（标记后交⑤骨架验证）

对**不确定性高的副作用**（如「这个并发方案会不会死锁」「这个缓存策略命中率如何」），
不要纯脑力推演——**标记为需⑤骨架验证，其 stub 方法直接进⑤骨架代码**。

### 何时标记需骨架验证

- 并发控制方案的理论分析有分歧
- 性能优化的效果不确定（缓存/索引/批量）
- 数据一致性的补偿逻辑复杂

### 标记原则（④只标记，不产出独立 prototype 代码）

- **登记而不实现** — ④NFR 标记「此副作用需⑤骨架验证」，记录要验证什么、预期结论方向
- **stub 进⑤骨架** — 相关 stub 方法（锁字段、idempotency-key、缓存 key）在⑤骨架代码里落地，⑤验证编译+调用链时一并验证存在性
- **结论回写** — ⑤骨架验证的结论回写到④NFR 文档（验证了什么、结论是什么）

> 历史上④会产「一次性 prototype 代码用完即删」，现已改为合并进⑤骨架——省一次重复设计，
> 且并发/幂等相关 stub 留在骨架里成为⑥Wave 的天然起点。详见 code-arch skill 的
> `references/skeleton-spike.md`「与 ④NFR prototype 的合并」一节。