# 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 入口定位**