chore: 初始化项目与后端基础工程

cursor-rules/ui-components-standard.md

@@ -0,0 +1,71 @@
+# UI/UX 与公共组件规范
+
+本规则用于指导 UI/UX 设计、公共组件抽取和组件登记管理。
+
+## UI/UX 设计原则
+
+- 禁止使用 emoji 作为 UI 图标。
+- 首选专业图标库：Lucide Icons，其次 Feather Icons；Ant Design 项目可使用 Ant Design Icons。
+- 禁止使用中文拼音缩写表达业务含义；优先使用英文、中文全称或清晰的领域命名。
+- UI 实现应关注一致性、可访问性、响应式布局和错误状态。
+- 页面设计应先确定信息架构，再确定视觉样式：导航、页面标题、主操作区、筛选区、内容区、分页区、反馈区。
+- 表单必须明确必填、校验、错误提示、提交中、提交成功、提交失败和取消路径。
+- 列表和表格必须明确加载、空数据、错误、筛选无结果、分页、排序和批量操作状态。
+- 时间、金额、状态、权限、危险操作等高频模式必须统一呈现，不允许每个页面各自发挥。
+
+## 公共组件抽取原则
+
+- 同一交互或视觉模式在两个及以上页面出现，优先抽取公共组件。
+- 即使只出现一次，但包含复杂状态、权限、时间段、分页、筛选、表格联动等逻辑，也应优先抽取为领域组件或组合组件。
+- 公共组件 API 应表达业务语义，不暴露页面内部状态细节。
+- 公共组件应保持稳定输入输出：`value`、`onChange`、`loading`、`disabled`、`error`、`empty`、`pagination` 等状态显式建模。
+- 不把页面特有文案、接口请求、路由跳转硬塞进基础公共组件；这些应留在页面层或领域组合层。
+
+## 优先沉淀的组件类型
+
+- 页面布局：`PageLayout`、`PageHeader`、`ContentCard`、`ActionBar`。
+- 查询筛选：`FilterBar`、`SearchInput`、`TimeRangePicker`、`DateRangePreset`。
+- 数据展示：`DataTable`、`Pagination`、`EmptyState`、`LoadingState`、`ErrorState`。
+- 表单交互：`FormField`、`FormSection`、`SubmitBar`、`ConfirmDialog`。
+- 反馈与状态：`StatusBadge`、`PermissionGate`、`Toast`、`ResultPanel`。
+- 业务高频组件：根据项目领域沉淀，不提前抽象不存在的业务概念。
+
+## 页面实现顺序
+
+- 先定义页面布局和数据流，再实现页面。
+- 先抽取公共组件，再堆页面细节。
+- 先覆盖加载、空态、错误、分页和权限状态，再补视觉细节。
+- 当组件参数开始膨胀时，优先评估是否应拆成基础组件、领域组件和页面容器三层。
+
+## UI 公共组件登记表
+
+- 一旦项目出现可复用 UI 组件，必须创建或更新 `pmdocs/ui-components.md`。
+- `pmdocs/ui-components.md` 用于记录组件沉淀情况，避免重复造分页、时间段、筛选栏、表格、表单等组件。
+- 组件登记表至少包含：组件名、组件类型、适用场景、输入状态、输出事件、使用页面、维护状态。
+- 推荐格式：
+
+| 组件 | 类型 | 适用场景 | 输入状态 | 输出事件 | 使用页面 | 状态 |
+|---|---|---|---|---|---|---|
+| `Pagination` | 基础组件 | 列表/表格分页 | `page` / `pageSize` / `total` | `onChange` | 用户列表、订单列表 | 稳定 |
+| `TimeRangePicker` | 组合组件 | 时间范围筛选 | `start` / `end` / `preset` | `onChange` | 数据看板、订单筛选 | 稳定 |
+| `FilterBar` | 组合组件 | 列表筛选栏 | `filters` / `onFilterChange` | `onChange` / `onReset` | 用户列表、订单列表 | 稳定 |
+| `DataTable` | 基础组件 | 数据表格 | `columns` / `data` / `loading` / `pagination` | `onPageChange` / `onSort` | 用户列表、订单列表 | 稳定 |
+
+- 公共组件新增、重命名、废弃或职责变化时，必须同步更新组件登记表。
+- 组件登记表只记录复用组件，不记录一次性页面局部元素。
+
+## 组件参数膨胀应对策略
+
+当组件参数超过 10 个，或出现以下情况时，应重新评估组件边界：
+
+- 参数包含页面特定文案、路由、接口请求
+- 参数包含复杂业务规则或权限判断
+- 参数存在互斥或复杂依赖关系
+- 不同使用场景需要不同参数子集
+
+应对策略：
+
+1. 拆成基础组件 + 领域组件 + 页面容器三层
+2. 使用组合模式而不是配置模式
+3. 使用 Render Props 或 Slots 传递复杂逻辑
+4. 使用 Context 或状态管理隔离跨层状态