MiragenFlow/docs/miragenflow-tdesign-unification-goal.md

MiragenFlow 统一 TDesign 长期目标

目标状态：进行中（active）

目标线程：01a033b1-abd1-7ed0-b6a3-c347551b2f78

本文是本轮“前后台统一组件体系”长任务的执行基线。这里的“统一”只指基础组件、主题语义、图标和交互契约统一；web/ 与 admin/ 仍是两个独立应用，不能合并页面、路由、权限、状态或业务 API。

本轮前后台业务、中文化、真实交互、渠道、日志、图表、响应式和验收要求已汇总到 docs/miragenflow-long-task-goal-prompt.md，长任务优先以该综合目标为入口。

旧版页面蓝本只作为历史背景；当渠道交互与综合目标不一致时，必须采用 OpenAI 单一供应方式、统一弹窗和“基础信息 / 模型列表 / 模型映射”三个可自由切换 Tab。

1. 目标定义

将 MiragenFlow 的用户端 web/ 与管理端 admin/ 统一到同一锁定版本 tdesign-react@1.15.1 的基础组件体系，同时保持两个应用的业务、权限和视觉职责分离。

最终结果必须满足：

• 用户端和管理端的按钮、输入框、下拉、选择器、弹窗、抽屉、提示、表单、表格、分页等基础交互均基于 TDesign。
• 用户端保留现有自定义视觉，包括主题令牌、品牌字体、布局密度、画布极简工具栏、移动端布局和用户侧文案；不能把管理台模板直接套到用户端。
• 管理端现有 TDesign 主题、工作台密度、菜单、权限、认证和业务页面保持视觉与行为稳定。
• 两端都使用本地化 Lineicons 子集，不使用 CDN、WebFont、全量图标目录或未批准的图标库。
• 所有下拉和弹层使用项目自己的样式适配，不渲染浏览器原生 <select>。
• 页面可见文案、表头、状态、动作和错误提示统一使用中文；仅保留必要的专有名词或缩写（如 TDesign、Lineicons、ECharts、MFA、API、ID），禁止直接展示英文 action、内部字段名或原始 JSON。
• 服务端、共享接口契约、用户端和管理端仍按边界独立，不能因为统一组件库而互相导入业务代码。

这是一个“统一组件运行时、保留应用视觉和业务边界”的目标，不是复制管理台页面，也不是合并两个应用。

2. 当前基线

用户端当前已完成基础 TDesign 适配层和本地 Lineicons 接入，保留 React 19、React Router 7、自定义用户控制台组件和 Zustand；Ant Design、ProComponents、Radix 普通控件及 reset 已从当前源码/依赖中清理，画布节点、侧栏、图片创作、资产入口、参数选项、资源提及输入和主题切换等主要可见控件已统一到共享 TDesign 适配层。剩余工作是隐藏文件上传等明确原生 API 例外、完整浏览器回归和最终证据复核。入口和主题主要位于：

• web/src/main.tsx
• web/src/components/layout/app-providers.tsx
• web/src/lib/tdesign-theme.ts
• web/src/user-console/components/primitives/

管理端目前使用 React 18、React Router 6、TDesign、Redux 和 ECharts；入口和管理台业务边界主要位于：

• admin/src/main.tsx
• admin/src/router/index.ts
• admin/src/layouts/components/AppRouter.tsx
• admin/src/pages/Business/index.tsx
• admin/src/services/platform.ts

两端 React、路由和主题令牌版本不同，所以不能用一次性依赖替换完成迁移。TDesign 在用户端 React 19 下的兼容性必须先验证；不能未经验证地强行降级或升级 React。

3. 目标架构

用户端 web/ 页面与业务
        |
        v
用户端 TDesign 适配层 ---- 用户端自定义主题、布局、文案
        |
        v
共享 TDesign 基础 UI + 本地 Lineicons
        ^
        |
管理端 admin/ 现有 TDesign 页面与主题

用户端 web/ -----------------------+
                                   |--> packages/contracts --> server API
管理端 admin/ ---------------------+

建议只增加一个无业务依赖的共享 UI 包（例如 packages/ui），内部提供纯 props 组件、主题语义令牌和图标导出。共享包不能依赖 admin 的 Redux、路由、权限、管理员请求或业务字段。

4. 明确边界

可以共享

• TDesign 基础控件包装：Button、Input、Select、Switch、Tooltip、Tag、Tabs、Modal、Drawer、Dropdown、Form、Table、Pagination、Empty、Loading、Message。
• 键盘、焦点、ESC、遮罩关闭、弹层层级和受控字段行为契约。
• 语义主题令牌：主色、成功/警告/错误、表面、边框、正文、圆角、间距、断点；由各应用分别生成 TDesign 变量。
• 本地 Lineicons 图标子集、尺寸和点击区域规范。
• 无状态的统计卡、日期范围控件和错误页展示壳；路由、权限和动作由调用方注入。

用户端专属

• 用户端页面、画布、资产、任务、账户、认证和 WebDAV 流程。
• .mf-console 自定义主题、品牌字体、首页作品流、画布工具栏和移动端布局。
• 用户端 Zustand、React Query、localforage、Motion、Tailwind、CodeMirror 和画布状态。
• 用户端不得暴露供应商名称、Base URL、API Key、内部模型 ID、渠道顺序或管理配置。

管理端专属

• 管理台菜单、路由元数据、scope/role 权限、PermissionGate、管理员 MFA/CAPTCHA 和登录流程。
• adminRequest 的管理员 Bearer、CSRF、幂等键、401 刷新和错误策略。
• 用户、渠道、渠道组、模型产品、计费、审批、任务、存储、系统设置和审计业务。
• 管理台现有 TDesign 主题、ECharts 主题映射和工作台布局。

5. 迁移阶段

P0：锁定版本与建立适配边界

1. 固定两端使用的 tdesign-react 版本并验证 React 19 兼容性。
2. 建立共享 UI 包或用户端适配层，先实现 Provider、主题桥接和 Lineicons 导出。
3. 记录管理端关键页面截图/交互基线；迁移期间禁止新增 Ant Design import。
4. 保持用户端和管理端入口、路由、状态、认证和 API 完全独立。

P1：迁移普通控件

按 Button、Input、Switch、Tag、Tooltip、Tabs、Card、Empty、Loading、Select 的顺序迁移，优先覆盖账户、任务、设置和认证页面。当前 packages/ui/src/ 已提供按组件子路径导出的 TDesign 控件入口，用户端普通控件通过 @miragenflow/ui/* 使用，保持按需加载。

P2：迁移反馈、弹层和表单

迁移 Message、Notification、Modal、Drawer、Dropdown、Popconfirm、DatePicker、Form、Pagination，并统一验证取消、右上角关闭、遮罩关闭、ESC、焦点回收和异步成功自动关闭。

P3：迁移复杂业务与画布

迁移资产页和画布中的标签多选、搜索下拉、上传、Image 预览、Slider、InputNumber、Popover、复杂受控表单；同步改写所有 .ant-* CSS 和 closest() 事件边界。

P4：清理旧依赖

确认用户端所有调用方和测试通过后，从 web/ 删除 Ant Design、ProComponents、Ant reset 和 Radix 普通控件；管理端本来就以 TDesign 为基线，不为统一目标引入或删除管理端业务依赖。保留仍有业务价值的无框架复合组件和动画组件。

6. 删除与保留清单

迁移完成后删除或改写

• web/package.json 与锁文件中的 antd、@ant-design/pro-components。
• web/src/main.tsx 中的 antd/dist/reset.css。
• web/src/components/layout/app-providers.tsx 中的 Ant ConfigProvider、ProConfigProvider 和 App.useApp() 依赖。
• 用户端旧的 web/src/lib/app-theme.ts Ant 主题文件；主题变量统一维护在 web/src/lib/tdesign-theme.ts。
• 用户端所有 import ... from 'antd' 及依赖 Ant DOM 类名的样式和事件判断。
• 所有普通控件迁移后，删除 radix-ui 和 web/src/components/ui/select.tsx。

必须保留

• web/src/user-console/components/primitives/，但把基础控件内部实现替换为 TDesign 包装；Feedback 等业务复合组件仍可保留。
• animated-theme-toggler.tsx、dia-text-reveal.tsx 等与组件库无关的动画组件。
• Zustand、React Query、localforage、Tailwind、Motion、CodeMirror、画布和资产存储。
• 管理端现有 TDesign、Redux、路由、权限、认证、服务层、Business 页面和 ECharts。
• 两端本地 Lineicons 资源及许可证；必要时再抽成共享本地包。
• packages/contracts、server 和现有 API/持久化逻辑。

7. 取舍说明

统一 TDesign 会移除用户端 Ant Design、ProComponents 和 Radix 的运行时负担，并减少重复控件实现。它不会自动让两个独立 Vite 应用只下载一份 JavaScript；如果未来要求物理层面共享 vendor 文件，需要另行设计统一构建或共享静态资源，不把两个应用强行合并作为本目标的一部分。

React 18/19、Router 6/7、Redux/Zustand 仍可在各自应用内保留。统一组件库不要求统一这些业务运行时，强行合并会扩大回归范围。

8. 验收标准

依赖与边界

• 用户端和管理端基础控件最终均来自 TDesign 或共享 TDesign 包装层。
• 用户端不再有 Ant Design、ProComponents、Radix 普通控件或原生 <select> 引用。
• 用户端和管理端没有互相导入业务页面、Redux store、路由、权限或 API 服务。
• 没有 CDN、WebFont、Lucide 或全量图标目录；Lineicons 仅加载本地实际使用子集。

视觉与交互

• 管理端关键页面视觉与迁移前基线一致。
• 用户端仍保持现有自定义主题、品牌字体、画布扁平工具栏和移动端列表布局。
• 浅色/深色主题、桌面/手机尺寸均无溢出、遮挡、黑色错误容器或白屏。
• 所有弹窗和抽屉支持保存、取消、右上角关闭、遮罩关闭、ESC 关闭；异步成功自动关闭，失败保留表单。
• 所有受控字段在切换 Tab、重开编辑、保存失败和刷新后不会丢失或被空值覆盖。

业务与安全

• 现有用户端画布、资产、任务、账户和认证流程不回归。
• 管理端 22 个可见页面、权限、真实 API、审计、计费和渠道流程不回归。
• 页面不展示原始 JSON、内部供应商凭证、Base URL、API Key、内部模型 ID 或管理专属字段。
• 加载、空态、网络错误、403、409、422、503 和重试路径均有明确中文反馈。
• 按路由、筛选和分页加载的列表必须具备请求代次或取消保护；过期响应不得回写当前页面的行数据、加载态或错误态。

验证命令

npm --prefix server run typecheck
npm --prefix server test
npm --prefix web run typecheck
npm --prefix web run build
npm --prefix admin run typecheck
npm --prefix admin run build
npm --prefix admin run lint
npm run build:all
git diff --check

使用 npm run dev:all 进行同源验证，至少检查 /、/canvas、/assets、/tools/image、/admin/ 和管理台关键页面；使用桌面、390px 手机、浅色和深色主题验证控件、弹层、键盘和滚动。未验证内容只能记录到 pending-test.mdx，不能宣布完成。

9. 长任务执行规则

1. 先读取 AGENTS.md、本目标文档、综合目标提示词、架构图 JSON，以及两端入口、Provider、主题和依赖文件；先形成迁移盘点和删除/保留清单，再开始代码修改。
2. 每次只推进一个迁移阶段；先改适配层，再逐页迁移，禁止一次性删除 Ant 依赖。
3. 修改前记录涉及页面、控件、状态契约和视觉基线；修改后检查用户端和管理端边界。
4. 不回滚已有用户改动，不创建展示用 mock，不把未接入功能伪装成成功。
5. 每完成一个阶段，运行对应类型检查/构建并记录结果；浏览器未验证的项目写入 pending-test.mdx。
6. 只有在用户端 Ant/Radix 引用清零、所有复杂控件回归通过、管理端视觉基线稳定后，才允许删除旧依赖。

9.1 本轮需求转化

必须达成

• web/ 与 admin/ 使用同一锁定版本的 TDesign 作为基础控件运行时；用户端通过适配层接入，不直接复制管理台页面。
• 用户端保留现有自定义主题、品牌字体、首页/登录/创作/画布/资产视觉、画布专属交互和移动端紧凑列表；管理端保持现有工作台密度、菜单、权限、认证、表格和 ECharts 视觉。
• 两端共享的只能是无业务依赖的 TDesign 包装、语义主题令牌、可访问性/键盘行为契约和本地 Lineicons 子集；不得共享管理端 Redux、路由、权限、请求服务或业务字段。
• 所有 Select、Dropdown、Cascader、TreeSelect、弹层和提示均使用 TDesign 或项目自定义样式适配；禁止浏览器原生 <select>、CDN、WebFont、Lucide、全量图标目录和原始 JSON 展示。
• 页面文案、表头、状态、动作和错误提示使用中文；只保留 TDesign、Lineicons、ECharts、MFA、API、ID 等必要专有名词或缩写。

明确不做

• 不把用户端改造成管理台模板，不统一两端的布局、品牌色、信息密度或业务导航。
• 不合并 React、React Router、Redux/Zustand、认证、API、持久化或画布运行时；不为“减少依赖”删除仍被业务使用的动画、画布和存储能力。
• 不通过 mock、静态 JSON、假按钮或隐藏错误来宣称迁移完成；未接入或未验证的能力必须明确记录。

长任务完成门槛

• 每个阶段先迁移适配层，再逐页迁移，保留可回滚边界；不得在 web/ 引用尚未清零前删除用户端 Ant Design、ProComponents、Radix 或 reset 样式。
• 每阶段必须留下类型检查/构建结果；最终还要用同源启动在桌面、390px、浅色和深色下逐页检查首页、登录、创作、画布、资产、任务、账户和管理台关键页面。
• 必须验证加载、空态、错误、403、409、422、503、重试、键盘 Tab/Enter/Escape、焦点回收、弹层关闭、表单回填、Tab 切换和窄屏滚动；未人工验证的项目只能写入 pending-test.mdx。
• 必须用延迟旧请求后快速切换页面的场景验证管理台列表不会发生跨路由数据串线，过期请求不能清除当前页面的加载或错误状态。

10. 可直接设立的目标提示词

本文件不再复制第二份提示词，避免长期执行时出现版本漂移。请直接复制 docs/miragenflow-long-task-goal-prompt.md 第 8 节的完整文本；该文本包含本文件的组件迁移规则、前后台边界、OpenAI 三 Tab 渠道规则、阶段顺序和最终验收命令。