docs: define Ayatori platform vision

docs/concepts/api-design.md

@@ -0,0 +1,39 @@
+# API 设计原则
+
+## 合理抽象
+
+API 应当比后端简单，但不能剥夺自用场景真正需要的控制力。
+
+- 用户主动做出的资源决策进入产品 API。
+- 平台稳定的运维策略进入 Profile、Class 或 Policy。
+- 能够稳定推导的机械参数由 adapter 生成。
+- 罕见但合理的特殊需求使用受控 override。
+- 解析结果、外部 ID 和后端摘要通过只读 status 展示。
+
+例如 VM 用户可以指定 CPU、内存、磁盘、存储、镜像和逻辑网络；QEMU machine type、
+cloud-init 设备、bridge/VLAN 映射和默认 placement 由平台维护。
+
+## 不做虚假可移植性
+
+允许 API 表达当前真实后端的有用能力，但不接受任意 `rawConfig` 透传。未来出现第二个
+真实实现时，根据已经观察到的共同语义抽象，而不是预先猜测最低公分母。
+
+## 引用与依赖
+
+- 使用 typed reference 表达资源依赖，不复制动态地址和外部 ID。
+- 被引用资源暂时不存在或未 Ready 时，controller 应等待而不是要求 apply 顺序。
+- 长期依赖通过 API 关系推导；Flux `dependsOn` 只用于确实需要的提交顺序。
+
+## 生命周期基线
+
+所有受管资源必须定义：
+
+- `observedGeneration`
+- 结构化 `status.conditions`
+- ownership 与外部资源标识
+- finalizer 与删除策略
+- import/adopt/observe 行为
+- controller 重启后的恢复行为
+- 可重试错误与需要人工介入错误的区别
+
+对数据库、bucket、持久磁盘等资源，默认删除行为必须保守并显式表达。