Spec 协议健壮性提升与元数据一致性：多维度严��校验、必填字段、Zod-First、CI 守护等方案清单

[hotlong]

问题背景

通过对 objectui（及所有 example）项目应用的实战梳理发现，当前 spec 项目存在如下不足，导致规范约束性弱、静态校验缺失、下游实现不一致：

• defineStack 入口几乎无 runtime 校验机制，默认能"吞掉"不规范数据
• DashboardWidget、View、Page 等类型定义大量字段可选且类型泛滥（z.unknown/z.any）
• interface 和 Zod schema 同名却常常不同步，易漂移
• 多种协议字段（如 filter 格式）业界无统一方案，当前 implementation 存在多种格式并存
• 自动化测试主要覆盖正向（happy path），未设置逆向与快照守护

优化目标

• 使 Spec schema 能最大化提前捕获元数据规范错误，为 IDE/开发/CLI/CI 等提供一致、可靠的安全边界
• 下游用户和低代码 IDE 能获得一致强校验支持

---

方案要点（优先级已排定）

1. defineStack() 接口默认严格校验

• 默认 { strict: true }，无特殊理由禁止关闭
• 校验顶层结构&子项 required/类型
• 导航、引用、seed data 等全部交叉验证
• 校验失败应抛异常，阻止加载/编译

2. 所有 Zod schema 必须按SSOT（单一真相）原则，类型和校验同步维护

• interface 一律用 z.infer 自动推导，禁止 interface/zod 漂移
• 删除冗余/过时 interface，禁止重复定义

3. DashboardWidget/Report/View/Page 等 schema 必填字段与 discriminated union 风格

• type, id, object[Name], field, layout 等协议主字段全部标记 required
• DashboardWidget/Report 建议用 discriminatedUnion 按 type 区分 subtype（chart、metric、table等必填字段不同）
• 替换所有 z.unknown/z.any，为具体的 composite schema

4. Filter 格式统一 & 全局复用 types

• filter 必须全局设定标准结构，如[['field','op','value']]，禁止扁平或对象式混用
• 一处改 schema，所有协议统一同步

5. 测试体系加强（正向/逆向/快照覆盖）

• 逆向测试（各类缺字段、类型非法、enum 越界等）必须报错
• example/kitchen-sink/crm/todo 等所有 defineStack 均需 strict 校验且能通过
• seed 数据与字段可用选项交叉快照，必测

6. CI/Lint/pre-commit 守护

• 新增/更新 spec schema 时，所�� example 元数据自动严格校验
• 拒绝 z.unknown/z.any，或报警给审批
• pre-commit 校验所有 type/interface/zod 只在一个地方维护

---

落地建议

• 首先针对 DashboardWidget/View/Page/Seed/Navigation 全面升级 required 字段及 discriminated union
• 补全所有文档注释，IDE 能提示每个字段含义/必填性
• 编写脚本自动迁移/校对历史 example 数据
• 逐步移除 z.any/z.unknown
• 形成使用模板/脚手架/校验工具链
• 完成后完善Roadmap、规范文档，并补充逆向用例

---

如需详细升级规划和接口代码示例，可分步骤提交子 issue。