docs: standardize on HeroUI component libraries

AGENTS.md

@@ -21,8 +21,9 @@
   - **常量**：使用全大写下划线 (SNAKE_CASE)。
 - **技术栈要求**：
   - 使用 React Hooks 和函数组件。
-  - 页面和共享 UI 组件必须直接使用 `@heroui/react` 与 `@heroui-pro/react`。
-  - 禁止新增或扩展 `src/catalyst-ui-kit`、`@headlessui/react`、旧 UI 适配器和可见原生表单控件。
+  - HeroUI 与 HeroUI Pro 是项目唯一 UI 组件体系。页面和共享 UI 组件必须直接使用 `@heroui/react` 与 `@heroui-pro/react`。
+  - `src/catalyst-ui-kit` 已废弃，仅作为待清理的历史源码保留。禁止在新功能、存量维护、重构、示例和测试中引用、复制或扩展其中的组件。
+  - 禁止新增 `@headlessui/react`、旧 UI 适配器或其他替代组件库，禁止以包装层兼容 Catalyst props，禁止使用可见原生表单控件替代 HeroUI。
   - HeroUI 复合组件遵守官方 compound component 与 `slot` 结构，交互使用 `onPress`。
   - DataGrid 使用 HeroUI Pro 原生选择、排序、分页、固定列和 ActionBar，不手写选择列。
 
@@ -40,7 +41,7 @@
 ## 6. UI 规范（鑫元 HeroUI 强制约束）
 
 - **全项目 UI 统一**：遵循 `xinyuan-design-system` 与 `docs/xinyuan-design-system.md`。
-- **直接引用**：页面不得通过 Catalyst、Headless UI 或兼容包装层间接使用 HeroUI。
+- **直接引用**：页面与共享组件必须从 `@heroui/react`、`@heroui-pro/react` 的官方导出直接组合；不得通过 Catalyst、Headless UI、旧适配器或兼容包装层间接使用。
 - **一致性**：表单使用 HeroUI，复杂表格和 Shell 使用 HeroUI Pro，弹窗使用 HeroUI Modal/AlertDialog。
 - **默认外观**：除 `src/design-system/theme.css` 的主题变量和批准的 Login/AppShell 布局外，组件尺寸、圆角、边框、阴影、Hover、选中态均使用 HeroUI/HeroUI Pro 默认实现；禁止页面 CSS 重画组件。
 - **主题唯一性**：`src/design-system/theme.css` 是组件主题唯一权威；`tokens.css` 只允许提供 Shell/Login 别名，不得覆盖 DataGrid、Tabs、Card、Modal、Checkbox、Pagination 或图表样式。
@@ -82,13 +83,14 @@ AI 在编写 API 调用或数据转换逻辑时，必须遵守：
 
 1. **Step 1**: 查找 `subjectsDefinition.md` 获取该 Subject 的基础字段。
 2. **Step 2**: 检查字段类型。如果遇到 `Subject` 类型，**自动生成**一段调用 `loadSubject` 的代码以获取深层结构。
-3. **Step 3**: 参照上表（第 1 节）选择 tailwind (或你指定的 UI 库) 的组件。
+3. **Step 3**: 参照上表（第 1 节）选择 HeroUI/HeroUI Pro 官方组件；Tailwind 仅用于页面布局，不得用于自制或重画交互组件。
 4. **Step 4**: 自动生成 `onChange` 处理函数，确保数据实时同步到 `metadata` 对象的对应路径下。
 
 ---
 
 ## 4. 强制约束 (Hard Constraints)
 
+- **组件库唯一性**：任何需求都不得重新引入 Catalyst、Headless UI 或其它 UI 组件库；HeroUI/HeroUI Pro 暂无对应组件时，应先按官方 compound API 组合，并遵循 `docs/xinyuan-design-system.md`，不得回退到 `src/catalyst-ui-kit`。
 - **禁止硬编码**：Select 类型的选项必须从 `settings.options` 读取，严禁在代码里写死。
 - **主键保护**：如果字段定义中 `isPrimaryKey: true`，在编辑模式下该组件必须设为 `disabled`。
 - **必填校验**：根据 `isRequired` 自动在 UI 上添加红星标记，并生成相应的 Form Validation 规则。

docs/ui-architecture.md

@@ -2,10 +2,11 @@
 
 ## 组件边界
 
-- 页面直接使用 `@heroui/react` 和 `@heroui-pro/react`。
-- 禁止在 `catalyst-ui-kit`、Headless UI 或旧适配器内部嵌入 HeroUI。
-- 禁止继续扩展 `catalyst-ui-kit`；新功能不得引用旧 UI 组件。
+- HeroUI 与 HeroUI Pro 是全项目唯一 UI 组件体系；页面、共享组件、示例和测试直接使用 `@heroui/react` 和 `@heroui-pro/react`。
+- `src/catalyst-ui-kit` 已停止使用，仅作为待清理的历史源码隔离保留，不属于可用组件目录；新功能、存量维护和重构都不得引用、复制或扩展其中的实现。
+- 禁止引入 Headless UI、其它替代组件库或旧适配器，禁止在兼容包装层内嵌入 HeroUI 并继续暴露 Catalyst props。
 - 允许的共享组件只组合 HeroUI/HeroUI Pro 官方复合结构，不复刻旧 props，不重画组件外观。
+- HeroUI/HeroUI Pro 暂无直接对应组件时，优先组合官方 compound API；确需补充基础能力时先更新架构与设计系统评审结论，不得回退到 Catalyst 或可见原生控件。
 - 业务数据、接口参数、权限、校验、保存回调和状态流转继续由页面与 service 层拥有。
 
 ## 标准实现

docs/ui-migration-checklist.md

 # 鑫元 UI 迁移清单
 
+> 当前规范：HeroUI 与 HeroUI Pro 已成为项目唯一 UI 组件体系。下表“当前来源”列仅记录迁移前状态，不代表仍可使用；新功能、存量维护、重构、示例和测试均不得引用或复制 `src/catalyst-ui-kit`，也不得重新引入 Headless UI 或旧适配器。
+
 状态：`待迁移`、`迁移中`、`待浏览器验收`、`完成`。
 
 | 页面/模块 | 路由 | 当前来源 | 目标组件 | 必须保留的业务边界 | 状态 | 浏览器验收 |
@@ -17,7 +19,7 @@
 
 ## 验收门槛
 
-- 已迁移范围的 Catalyst、Headless UI、旧适配器和可见原生控件引用为零。
+- 全部运行代码、示例和测试中的 Catalyst、Headless UI、旧适配器和可见原生控件引用为零；历史隔离目录不得进入构建或依赖图。
 - Checkbox 单选、取消、全选、半选和禁用状态无 Context/slot 错误。
 - Autocomplete、SearchField、ListBox、Modal、Tooltip、ActionBar 在深浅主题和移动端正确继承 Portal 主题。
 - DataGrid 横向滚动、固定列、分页、排序、选择和批量操作保持原业务结果。
@@ -30,7 +32,7 @@
 - 驾驶舱和整改分析已移除 ECharts、私有 option、主题监听和 HTML Tooltip，改用 HeroUI Pro KPI、PieChart、BarChart、ComposedChart 与默认 ChartTooltip。
 - 整改处理、整改流程、问题清单、详情与引用的页面私有旧色类已清零，状态、提示、空状态、卡片与 KPI 已切换到 HeroUI/HeroUI Pro 和鑫元语义 Token。
 - 未启用的 `ResourceManagementUi.jsx`、`ModuleEmptyState.jsx` 已同步迁移，避免后续功能重新引用旧式表面。
-- 业务页面与共享组件中的 Catalyst/Headless/Heroicons 引用、可见原生控件和旧调色板类扫描均为零；隔离保留的 `src/catalyst-ui-kit` 不属于运行引用范围。
+- 业务页面、共享组件、示例和测试中的 Catalyst/Headless/Heroicons 引用、可见原生控件和旧调色板类扫描均为零；隔离保留的 `src/catalyst-ui-kit` 仅属待清理历史源码，不属于可用组件目录、构建范围或运行依赖。
 - HeroUI Pro CSS 与六个要求的组件子路径可解析/导入，HeroUI/React Aria 依赖树为单套兼容版本。
 - `npm run build` 与 `git diff --check` 已通过。
 - 当前桌面会话没有可用浏览器连接，因此表格勾选、Portal、暗色切换和响应式仍保持“待浏览器验收”，不以构建结果替代。

docs/xinyuan-design-system.md

@@ -4,12 +4,14 @@
 
 ## 1. 唯一技术基线
 
-- 页面和共享组件直接使用 `@heroui/react`、`@heroui-pro/react`。
+- HeroUI 与 HeroUI Pro 是项目唯一 UI 组件体系；页面、共享组件、示例和测试直接使用 `@heroui/react`、`@heroui-pro/react`。
 - HeroUI Pro 精确固定为 `1.0.0-beta.8`，通过官方 `hpsetup` 授权流程获取完整制品；禁止仓库内 `vendor` 镜像、跨项目 `file:` 路径和符号链接。
 - 项目以 npm 和 `package-lock.json` 为唯一包管理基线。本地使用 `HEROUI_KEY=<team-secret> npx -y hpsetup@latest --auto`；CI 将 `HEROUI_KEY` 设为受保护、已遮罩的环境变量。授权密钥不得写入仓库或文档。
 - 图标统一从 `src/components/AppIcons.jsx` 引用 Ant Design Icons；业务页面不得引入 Heroicons、Lucide、Iconify 或自绘功能图标。
-- 禁止引用或扩展 `src/catalyst-ui-kit`，禁止旧组件适配器，禁止在旧组件内部嵌套 HeroUI。
+- `src/catalyst-ui-kit` 已废弃并退出运行时，只能作为待清理的历史源码隔离保留；禁止在新功能、存量维护、重构、示例或测试中引用、复制、扩展或恢复其依赖。
+- 禁止引入 `@headlessui/react`、其它替代组件库或旧组件适配器，禁止在旧组件内部嵌套 HeroUI，禁止包装 HeroUI 来兼容 Catalyst props。
 - 共享组件只能组合 HeroUI/HeroUI Pro 的官方 compound API，不得复刻旧组件 props。
+- 官方组件暂不覆盖的场景应优先组合 HeroUI/HeroUI Pro compound API，并在本设计系统中补充经过评审的约定；不得以 Catalyst 或可见原生控件作为降级方案。
 
 ## 2. 主题权威
 
@@ -152,7 +154,7 @@ Surface 用于表达页面内的包含关系，Overlay 用于表达浮动关系
 
 ## 9. 验收
 
-- 扫描活动页面和共享组件，Catalyst、Headless UI、旧适配器、其他图标库、可见原生控件和私有组件 CSS 必须为零。
+- 扫描全部运行代码、示例和测试，Catalyst、Headless UI、旧适配器、其他图标库、可见原生控件和私有组件 CSS 引用必须为零；`src/catalyst-ui-kit` 历史隔离目录不得进入构建或依赖图。
 - 检查 `npm ls @heroui-pro/react @heroui/react @heroui/styles react-aria-components @react-aria/utils`，运行时只能有一套兼容实例。
 - 验证登录/退出、路由、Tabs、Autocomplete 搜索/单选/多选/清空、筛选、Checkbox 全选/取消、排序、分页、固定列、ActionBar、所有弹窗、图表 Tooltip、深浅主题和响应式。
 - 最终执行 `npm run build`、`git diff --check`、HeroUI Pro 子路径解析和旧引用扫描。

docs/xinyuan-ui-audit.md

 # 问题整改系统 UI/UX 全局审计
 
+> 当前组件库结论：HeroUI 与 HeroUI Pro 是项目唯一 UI 组件体系。文中 Catalyst/Headless UI 只描述迁移前问题和历史整改记录，不构成可用技术选项。
+
 > 2026-08-19 复核：Modal 根面统一保持 HeroUI `overlay`；应用切换项、附件编辑器、流程详情摘要等需要独立边界的弹窗内对象统一使用 HeroUI `secondary`。普通详情查看态以一个 `Surface secondary` 承载整组无框标签/值，编辑态则由 `secondary` 控件直接位于 Overlay。已清理上述范围内的 L1-on-L1 默认 Card，不改变弹窗数据、回调或状态流转；深浅模式实际层级仍待浏览器验收。
 
 审计日期：2026-08-17
@@ -83,7 +85,7 @@
 - 整改处理、整改流程、问题清单和详情/引用四个活动区域残留的页面私有 `white/zinc/slate/sky/rose/red/amber/emerald` 视觉类已归零；状态、提示、加载、空状态、信息 Card 和 KPI 已改为直接使用 HeroUI/HeroUI Pro 与鑫元语义 Token。
 - 暂未被路由引用的 `ResourceManagementUi.jsx` 与 `ModuleEmptyState.jsx` 也已完成同一边界迁移；前者同时移除了已不存在的旧共享样式依赖，避免未来重新启用时形成隐性构建故障。
 - 登录验证码暗色表面与暗色填充态已改为 `theme.css`/`tokens.css` 语义变量和 `color-mix()` 派生值，不再形成硬编码白色孤岛。
-- `src/catalyst-ui-kit` 作为未引用历史源码隔离保留，本次没有进入或修改该目录；新功能禁止引用。
+- `src/catalyst-ui-kit` 作为待清理的未引用历史源码隔离保留，不属于可用组件目录；新功能、存量维护、重构、示例和测试均禁止引用、复制或扩展，且不得进入构建或依赖图。
 - `RecordWorkbench`、问题清单、归档、驾驶舱明细、整改处理和整改流程均已改用 HeroUI Pro DataGrid；选择、分页和 ActionBar 由原生能力承载。
 - 驾驶舱和整改分析已删除 ECharts 与私有图表主题，直接使用 HeroUI Pro KPI、PieChart、BarChart、ComposedChart 和 ChartTooltip；统计数据、筛选状态与重点问题点击回调保持原样。
 - 应用切换、详情、创建、推送、延期、复制、删除和重点问题详情均已改用 HeroUI Modal compound API。

src/catalyst-ui-kit/COMPONENTS.md

 # Catalyst UI Kit 组件文档
 
-本文档详细说明了 Catalyst UI Kit 中所有可用组件的使用方法、Props 接口、样式特点和使用示例。
+> **历史文档，禁止作为开发依据。** Catalyst UI Kit 已退出本项目，HeroUI 与 HeroUI Pro 是唯一 UI 组件体系。禁止引用、复制、扩展下列组件或恢复 `@headlessui/react` 依赖；请改用 [`docs/xinyuan-design-system.md`](../../docs/xinyuan-design-system.md) 和 [`docs/ui-architecture.md`](../../docs/ui-architecture.md) 中规定的 HeroUI/HeroUI Pro 组件。
+
+本文档仅保留 Catalyst 历史组件的 Props、样式和示例，用于迁移追溯。
 
 ---
 

src/catalyst-ui-kit/README.md

 # Catalyst UI Kit
 
+> **已废弃：禁止在本项目中使用。** 项目 UI 已统一为 `@heroui/react` 与 `@heroui-pro/react`。本目录仅保留历史源码，等待后续清理；不得从中导入、复制或扩展组件，不得安装其 Headless UI 依赖，也不得把本目录加入构建。当前开发规范见 [`docs/xinyuan-design-system.md`](../../docs/xinyuan-design-system.md) 和 [`docs/ui-architecture.md`](../../docs/ui-architecture.md)。以下内容仅供追溯原始来源。
+
 Catalyst is a modern application UI kit built with [Tailwind CSS](https://tailwindcss.com) and [React](https://react.dev/), designed and built by the Tailwind CSS team and included as part of [Tailwind Plus](https://tailwindcss.com/plus).
 
 ## Getting started

src/catalyst-ui-kit/demo/javascript/README.md

 # Catalyst Demo
 
+> **已废弃：请勿运行或复用。** 本项目 UI 已统一为 `@heroui/react` 与 `@heroui-pro/react`；该 Demo 仅为历史源码，不得安装依赖、复制组件或加入构建。
+
 To run the Catalyst demo, first install the npm dependencies:
 
 ```bash

src/catalyst-ui-kit/demo/typescript/README.md

 # Catalyst Demo
 
+> **已废弃：请勿运行或复用。** 本项目 UI 已统一为 `@heroui/react` 与 `@heroui-pro/react`；该 Demo 仅为历史源码，不得安装依赖、复制组件或加入构建。
+
 To run the Catalyst demo, first install the npm dependencies:
 
 ```bash