feat(admin): 用户体验体系化提升与高危缺陷修复

UX 缺陷修复:
- 校验失败不再卡死弹窗按钮(Users/Roles/Bills)
- 押金收取/批量收取/添加分期防重复提交;切换房型重置勾选
- AI 表单/批量确认不再出现"假成功"
- Dashboard 各数据模块独立加载,单接口失败不再整页清零
- 房间可视化加载失败显示错误态而非永久转圈
- 学生编辑表单回填前重置,避免字段残留污染
- 覆盖式导入增加二次确认;恢复默认考勤时段确认并同步表单
- 金数据匹配关闭前确认,同步中禁止误关

体验提升:
- 新增统一 QueryErrorState/QueryEmpty,20+ 页面加载失败显示错误态与重试
- 全局 ErrorBoundary + RouteKeeper 逐页兜底
- 新增 usePageVisible/useVisibleRefetch,保活页面切回自动刷新数据
- 新增首次登录角色引导 RoleTour 与业务闭环 NextStepHint 引导卡
- 重构 A2UI:useSubmissionState/useXCardSurface 收敛状态与命令生命周期,
  ArtifactErrorBoundary 渲染降级,图表空数据占位
- AI 助手欢迎语与建议话术按角色定制,会话列表空态引导
- 更新 a2ui-contract.md 契约文档说明实现现状

scripts/a2ui-contract.md

@@ -139,3 +139,23 @@ interface AiUiForm {
 
 ## 完成后报告
 改动文件清单、跑过的测试命令与结果、与契约的偏差说明。
+
+## 实现现状补充（2026-08 修订）
+
+> 前端 `apps/admin/src/components/AiChat/**` 的实际实现已演进为「统一 artifact」协议，
+> 本段描述现行事实，供后续开发对齐；上文的 `ui.form`/`AiUiForm`/`uiForms` 为早期单轨方案，
+> 当前仅保留历史兼容读取，新写一律走 artifact。
+
+- **统一类型**：`types.ts` 以 `AiArtifactSchema`（`message.uiArtifacts`）为唯一事实源，
+  `artifact.type` ∈ `form | review | chart | import_wizard`，`payload` 携带各类型 schema。
+- **合并逻辑**：`uiArtifacts.ts` 的 `mergeArtifactIntoMessage` 将新 artifact upsert 进
+  `uiArtifacts`，并**向后兼容**地派发到 legacy 字段（`forms`/`reviews`/`charts`）供老消息渲染。
+- **渲染层**：`AiMessageContent.tsx` 消费 legacy 列表渲染 `DynamicForm`/`DynamicReview`/
+  `DynamicChart`；每个制品用 `ArtifactErrorBoundary` 包裹（单个渲染失败不影响整条气泡）。
+- **A2UI 组件实现**：`DynamicForm`/`DynamicReview`/`DynamicChart` 共享
+  `useSubmissionState`（提交状态：防重复提交 + 失败可重试）与 `useXCardSurface`
+  （XCard commands 增量更新 + createSurface 自动去重）。
+- **SSE 事件 / 提交与确认接口**：与上文契约一致，未变更。
+
+后续若彻底移除 legacy 字段，需保证历史消息（持久化 metadata 中的 `forms`/`reviews`/`charts`）
+仍可渲染——建议先迁移历史数据或保留兼容读取。