Design model contract

1. 源真相

JSON design 是唯一源真相。浏览器画布、分数、Mermaid 和 Markdown 都是可重建派生物。

当前 schemaVersion 为 1。导入器对未知版本 fail closed，不静默猜测迁移。

2. 顶层结构

{
  "schemaVersion": 1,
  "title": "短链接服务",
  "scenarioId": "url-shortener",
  "nodes": [],
  "edges": [],
  "tradeoffs": [],
  "checklist": {}
}

字段	语义	限制
`title`	方案名称	最长 120 字符
`scenarioId`	内置或嵌入场景 ID	必须能解析，且与 `scenario.id` 一致
`scenario`	可选的便携自定义场景	严格校验数值、单位、组件类型和问题列表
`nodes`	组件与假设	最多 200 个，ID 唯一
`edges`	有向数据流	最多 500 条，引用必须存在，不允许自环
`tradeoffs`	选择、备选、理由	最多 100 条，三项都必填
`checklist`	面试/评审阶段证据	仅接受已知布尔字段

3. 节点

{
  "id": "api",
  "type": "service",
  "label": "短链 API",
  "x": 430,
  "y": 250,
  "capacityRps": 5000,
  "latencyMs": 25,
  "replicas": 3,
  "availability": 0.995,
  "hourlyCost": 16,
  "critical": true,
  "notes": "无状态服务"
}

capacityRps 是单副本的学习假设，不是 benchmark。
latencyMs 是无排队压力下的基础延迟。
replicas 至少为 1；分析器按线性容量扩展近似。
availability 在 0–1 之间，表示单副本可用概率假设。
hourlyCost 是抽象成本单位，不对应特定云厂商币种。
critical=false 的节点仍被分析，但不成为 SLO 端点；关键节点即使只有可选输出，也仍可结束核心路径。
x、y 只影响画布展示，不参与评分。

组件类型 allowlist：client、cdn、load_balancer、api_gateway、service、cache、database、queue、worker、object_storage、ai_model、observability。

4. 连线

{
  "id": "edge-api-cache",
  "source": "api",
  "target": "cache",
  "trafficPercent": 90,
  "required": true,
  "label": "90% read"
}

trafficPercent 的解释是“上游流量中有多少比例经过这条边”：

两条边各 50%，表示流量拆分。
两条边各 100%，表示每个请求同时触发两个下游。
总和低于 100%，表示过滤、缓存命中后短路或只建模部分流量。
总和高于 100%，表示扇出、重试或一个请求产生多个工作单元。

这使分支语义显式化，但不会自动判断业务语义是否合理。

required=false 表示这条连线不进入目标节点的关键延迟/可靠性路径；流量仍会传播，局部容量和成本仍会计算。它适合异步旁路、可降级阅读视图或非阻断观测，不适合隐藏真实同步依赖。

5. 自定义场景

便携设计可以嵌入 scenario：

{
  "id": "content-evidence-pipeline",
  "title": "内容证据流水线",
  "summary": "从源工件生成经过验证的阅读视图。",
  "inputRps": 0.2,
  "trafficUnit": "内容变更/s",
  "targetLatencyMs": 5000,
  "targetAvailability": 0.95,
  "maxHourlyCost": 30,
  "costUnit": "维护点/周期",
  "requiredTypes": ["service", "database", "worker", "observability"],
  "requirements": ["失败不能产生成功收据"],
  "questions": ["如何证明派生视图没有漂移？"]
}

自定义场景与设计一起导入、保存和导出，不需要修改内置 catalog。ID 必须与顶层 scenarioId 一致，组件类型只能来自 allowlist，列表和文本长度有上限。

6. 权衡记录

{
  "id": "tradeoff-cache",
  "decision": "缓存热点结果",
  "alternative": "每次读取主数据库",
  "rationale": "降低延迟，但接受短时间陈旧并处理击穿。"
}

只写“用了 Redis”不算权衡；必须同时写被放弃的备选和当前约束下的理由。

7. Checklist

字段对应一条完整设计控制流：

requirements：功能与非功能需求。
estimates：流量、存储、带宽和增长估算。
apiData：API、数据模型与一致性。
highLevel：端到端高层数据流。
deepDive：一个瓶颈的深入设计。
failureReview：故障、降级、恢复与观测。

勾选只表示学习者声称完成该阶段；导出的报告仍需承载实际证据。

8. 兼容性策略

v1 导入会规范数值边界、文本长度和 ID 字符，并去除未知字段。
同一版本内可增加向后兼容的可选字段；缺少 scenario、critical 或 required 的旧文件继续按内置场景和关键路径默认值读取。
改变分析语义或必填字段时，应升级 schemaVersion 并提供显式迁移函数。
CLI、浏览器和测试必须共享同一校验器，禁止出现三套略有差异的 schema。

FilesExpand file tree

model-contract.md

Latest commit

History