social-app/docs/superpowers/plans/2026-03-19-ui-schema-file-split.md

UI Schema File Split Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 将 apps/lib/core/schemas/ui_schema.dart 从超大单文件拆分为同库的多个 part 文件，在不改变协议行为的前提下提升可维护性。

Architecture: 保留 ui_schema.dart 作为唯一对外入口和 single source of truth；通过 part 把 enums、common types、actions、nodes、document、builder 按职责拆分到 core/schemas/ui_schema/ 子目录。所有类型名、JSON 字段、默认值与工厂方法逻辑保持完全一致，避免协议漂移。

Tech Stack: Dart library/part、Flutter analyze、Flutter test

---

Task 1: 建立拆分骨架并保留外部接口

Files:

• Modify: apps/lib/core/schemas/ui_schema.dart

• Create: apps/lib/core/schemas/ui_schema/enums.dart

• Create: apps/lib/core/schemas/ui_schema/common_types.dart

• Create: apps/lib/core/schemas/ui_schema/actions.dart

• Create: apps/lib/core/schemas/ui_schema/nodes.dart

• Create: apps/lib/core/schemas/ui_schema/document.dart

• Create: apps/lib/core/schemas/ui_schema/builders.dart

• Step 1: 在主文件添加 part 声明并保留文件头注释

• Step 1.1: 所有子文件统一使用 part of '../ui_schema.dart';，避免子目录相对路径错误

• Step 2: 将 enum 定义迁移到 enums.dart，语义不变

• Step 3: 将基础 DTO 迁移到 common_types.dart，语义不变

• Step 4: 将 Action 协议与解析逻辑迁移到 actions.dart，语义不变

• Step 5: 将 UiNode 与各 node 实现迁移到 nodes.dart，语义不变

• Step 6: 将文档配置/文档模型迁移到 document.dart，语义不变

• Step 7: 将 buildSuccessDocument/buildErrorDocument 迁移到 builders.dart

Task 2: 进行协议稳定性验证

Files:

• Create: apps/test/core/schemas/ui_schema_test.dart

• Test: apps/test/features/chat/ui_schema_renderer_test.dart

• Test: apps/test/features/chat/ui_schema_navigation_test.dart

• Test: apps/test/features/chat/ag_ui_event_test.dart

• Step 1: 新增 ui_schema.dart 直连回归测试

  • 覆盖 enum fallback、actionSpecFromJson 分支、UiNode.fromJson 分支、Document/builder 默认值、round-trip 稳定性。

• Step 2: 在 apps/ 目录运行 analyze，确认 part 结构无编译错误

  • Run (apps/): flutter analyze

• Step 3: 在 apps/ 目录运行 UI Schema 渲染与导航相关测试

  • Run: flutter test test/features/chat/ui_schema_renderer_test.dart
  • Run: flutter test test/features/chat/ui_schema_navigation_test.dart

• Step 4: 在 apps/ 目录运行 AG-UI 事件模型回归测试

  • Run: flutter test test/features/chat/ag_ui_event_test.dart

• Step 5: 在 apps/ 目录运行新增 schema 回归测试

  • Run: flutter test test/core/schemas/ui_schema_test.dart

Task 3: 完成收尾与风险核对

Files:

• Modify: apps/lib/core/schemas/ui_schema.dart

• Modify: apps/lib/core/schemas/ui_schema/*.dart

• Step 1: 检查 public API 未变化（类型名/函数名不变）

• Step 2: 检查 JSON 键、默认值、fallback 分支未变化

• Step 3: 确认 ui_schema.dart 行数显著下降并保留 single source 入口定位