docs: 统一使用 HeroUI 组件库

AGENTS.md

@@ -21,12 +21,15 @@
   - **常量**：使用全大写下划线 (SNAKE_CASE)。
 - **技术栈偏好**：
   - 优先使用 React Hooks 和函数组件。
-  - 样式处理：**优先使用 Tailwind Plus / Catalyst UI Kit（见 `src/catalyst-ui-kit`）+ Tailwind CSS**。
-  - 交互组件：**优先使用 Headless UI**（已在 Catalyst 组件内封装，除非缺组件才直接用 `@headlessui/react`）。
+  - UI 组件：**全项目统一使用 HeroUI 与 HeroUI Pro**。基础控件直接使用 `@heroui/react`，专业布局和数据展示组件使用 `@heroui-pro/react` 或其已验证子路径。
+  - 样式处理：使用项目现有 HeroUI 主题、设计 Token 与 Tailwind CSS；Tailwind 类主要用于布局、间距、尺寸、对齐、溢出和响应式，不得覆盖 HeroUI 组件的视觉与交互状态。
+  - 交互组件：弹窗、下拉、选择器、日期选择、提示等交互必须优先使用 HeroUI / HeroUI Pro 提供的可访问组件及其 compound API。
   - 组件选择优先级（从高到低）：
-    1. `src/catalyst-ui-kit/javascript/*`（Button/Input/Dialog/Table/Combobox/SidebarLayout/...）
-    2. 基于 Catalyst 样式规范的自定义组件（仅在 Kit 无现成组件时）
-    3. 原生 HTML + 自写样式（尽量避免）
+    1. `@heroui-pro/react` 或其已验证子路径（AppShell/Sidebar/Navbar/DataGrid/ActionBar/EmptyState/KPI/Chart/...）
+    2. `@heroui/react`（Button/Input/Autocomplete/DatePicker/Checkbox/TextArea/Modal/Table/...）
+    3. 项目内基于 HeroUI 当前 API 构建且已经验证的共享组合组件
+    4. 基于 HeroUI 设计 Token 的自定义组件（仅在 HeroUI 与 HeroUI Pro 均无对应能力时）
+    5. 原生语义 HTML + Tailwind 布局样式（仅用于组件库无对应能力的结构性场景）
 
 ## 4. 接口请求规范
 
@@ -39,12 +42,14 @@
 - 如果 `record-api.md` 或 `subjectsDefinition.md` 中的定义不清晰，请务必询问我，不要随意猜测字段名。
 - 每次生成代码后，简要说明你引用了哪个 API 和哪些数据对象。
 
-## 6. UI 规范（Tailwind Plus / Headless UI 强制约束）
+## 6. UI 规范（HeroUI / HeroUI Pro 强制约束）
 
-- **全项目 UI 统一**：默认使用 `src/catalyst-ui-kit` 中的 Catalyst 组件与样式体系，避免引入其它 UI 框架。
-- **Headless UI 优先**：弹窗/下拉/选择器等交互优先用 Headless UI（直接或通过 Catalyst 组件）。
-- **一致性**：表单控件优先用 Catalyst 的 `Input/Select/Checkbox/Textarea/Fieldset`，表格用 `Table`，对话框用 `Dialog`。
-- **可访问性**：移动端侧栏/弹层必须使用 Headless UI 的 Dialog 等可访问性组件（focus trap / esc 关闭等）。
+- **全项目 UI 统一**：新开发与重构代码必须使用 HeroUI / HeroUI Pro，禁止继续使用或新增 Catalyst UI Kit、Headless UI 及其他 UI 框架。
+- **直接使用当前 API**：优先直接导入 `@heroui/react`、`@heroui-pro/react` 或其已验证子路径，使用当前 compound API、value/selection model 与事件模型；禁止为了兼容旧组件而伪造 DOM event、旧 props 或旧 variant。
+- **一致性**：基础表单控件使用 HeroUI 的 `Input`、`Autocomplete`、`DatePicker`、`Checkbox`、`TextArea` 等；复杂数据表格、应用外壳、侧栏、导航、操作栏、空状态、KPI 与图表优先使用 HeroUI Pro。
+- **可访问性**：移动端侧栏、Modal、AlertDialog、Dropdown、Autocomplete、DatePicker、Tooltip 等必须使用 HeroUI / HeroUI Pro 的可访问结构，保留焦点管理、键盘操作、Esc 关闭和必要的可访问名称。
+- **禁止旧库回流**：不得从 `src/catalyst-ui-kit`、`@headlessui/react` 或旧 UI 兼容包装中导入组件；历史目录和迁移记录仅供审计，不作为新代码来源。
+- **设计系统一致性**：实现前必须查阅 `docs/ui-architecture.md` 与 `docs/xinyuan-design-system.md`，遵守项目现有主题、Token、Surface 层级、Portal 主题继承及响应式规范。
 
 # AI 开发执行规范
 
@@ -54,12 +59,12 @@
 
 | 字段类型 (Type) | UI 组件 (Component) | 交互逻辑 / 备注 |
 | :-- | :-- | :-- |
-| **文本 (String)** | Catalyst `Input` | 标准文本输入 |
-| **引用 (Reference)** | `ReferenceSearchSelect`（Headless UI Combobox） | 必须通过 API 获取列表，选中后仅存储 `_id` |
-| **数字 (Number)** | Catalyst `Input`（`type="number"`） | 仅允许输入数字 |
-| **日期 (Date)** | Catalyst `Input`（`type="date"` / `datetime-local`） | 提交时格式化为 `ISO 8601` 字符串 |
-| **布尔 (Boolean)** | Catalyst `Checkbox` | 映射为 true/false |
-| **JSON** | Catalyst `Textarea` | 需要包含 JSON 校验逻辑 |
+| **文本 (String)** | HeroUI `Input` | 标准文本输入 |
+| **引用 (Reference)** | HeroUI `Autocomplete` + `ListBox`（或项目内已验证的 HeroUI-native 引用选择组合） | 必须通过 API 获取列表，选中后仅存储 `_id` |
+| **数字 (Number)** | HeroUI `Input`（`type="number"`） | 仅允许输入数字 |
+| **日期 (Date)** | HeroUI `DatePicker` / `DateField` | 使用 `@internationalized/date` 转换受控值，提交时格式化为 `ISO 8601` 字符串 |
+| **布尔 (Boolean)** | HeroUI `Checkbox` | 映射为 true/false |
+| **JSON** | HeroUI `TextArea` | 需要包含 JSON 校验逻辑 |
 | **子对象 (Subject)** | **动态表单递归** | **核心逻辑：** 必须先调用 `loadSubject(subjectName)` 接口读取该子对象的字段定义，然后递归应用本映射表生成子表单。 |
 
 ---
@@ -81,7 +86,7 @@ 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` 对象的对应路径下。
 
 ---