DevLog #004: SAF 架构看护体系 — 需求-特性-测试三角闭环

日期: 2026-04-13 状态: 已建立 Tags: architecture, quality-assurance, requirements, testing

背景

随着 SAF 平台规模扩大，如何确保架构完整性不被侵蚀成为重要问题。我们建立了"架构看护体系"，通过三个核心文档形成闭环。

三大核心文档

文档用途格式
FEATURE_TREE.mdSAF 完整特性树特性 → 子特性 → 孙子特性
SYSTEM_REQUIREMENTS.md系统需求规格REQ-ID 格式
TEST_DESIGN.md系统级测试设计基于需求规格

闭环流程

┌──────────────────────────────────────────────────────────────┐
│                                                              │
│   需求规格 (SYSTEM_REQUIREMENTS.md)                          │
│       │                                                     │
│       ▼                                                     │
│   特性树 (FEATURE_TREE.md)                                   │
│       │                                                     │
│       ▼                                                     │
│   测试用例 (TEST_DESIGN.md)                                  │
│       │                                                     │
│       ▼                                                     │
│   ┌─────────────────┐                                      │
│   │  通过 = 功能正确  │                                      │
│   └─────────────────┘                                      │
│                                                              │
└──────────────────────────────────────────────────────────────┘

看护机制

CI/CD Pipeline:
  ├── pytest (单元测试)
  ├── pytest --cov (覆盖率检查)
  └── 全部通过 → 部署

验证命令

# 运行 SAF 所有测试
cd SAF && pytest tests/ -v --cov=saf --cov-report=term-missing

# 测试通过 = 系统功能良好

看护目标

通过以上机制，确保：

  1. 需求可追溯 — 每个测试对应一个需求ID
  2. 特性全覆盖 — 特性树中的每个节点都有测试
  3. 架构被看护 — 测试失败 = 架构退化 = 必须修复

文档模板

Feature Tree 模板

# {子系统名} 特性树

## 整体定位
{subsystem description}

## 顶层业务流程
{业务流图}

## 特性树
{root}
├── 1. {Category}
│   ├── 1.1 {Feature}
│   │   └── {Sub-feature}
...

System Requirements 模板

# {子系统} 系统需求规格

## 系统定位
{定位描述}

## 功能需求
| 需求ID | 需求描述 | 验收标准 |
|--------|----------|----------|
| REQ-{MOD}-{###} | ... | ... |

Test Design 模板

# {子系统} 系统级测试设计

## 测试分层
- Unit Tests
- Integration Tests
- E2E Tests

## 测试用例
### {Category}

#### UT-{MOD}-###: {Test Name}
def test_xxx():
    """REQ-XXX: {需求描述}"""
    ...

子系统交付状态

子系统负责人交付物状态
SAFClaudeFEATURE_TREE + REQ + TEST✅ 完成
strategy_factory(待输出)同上格式⏳
tss(待输出)同上格式⏳

架构看护的价值

★ Insight ───────────────────────────────────── 架构退化往往发生在"不经意的小改动"中。 当没有系统性看护时，开发者可能为了快速解决问题而绕过架构约束， 久而久之，架构就变成了"技术债务的废墟"。

架构看护体系的核心价值不是"限制自由度"，而是"让架构退化成为可量化的指标"。 当测试失败时，架构退化不再是模糊的"感觉"，而是具体的数字。 ──────────────────────────────────────────────────

Generated from: SAF/docs/ARCHITECTURE_GUARDIAN.md