From cd2b7d36f3610417c268d062454b7ec43e9ca937 Mon Sep 17 00:00:00 2001
From: wsj <593216709@qq.com>
Date: Wed, 28 Oct 2026 22:51:24 +0800
Subject: [PATCH] feat: 日志页面
---
CLAUDE.md | 83 +++++++++++++++++++++++++++++++++++++++--
1 files changed, 78 insertions(+), 5 deletions(-)
diff --git a/CLAUDE.md b/CLAUDE.md
index 17347af..d2ca45b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -41,7 +41,7 @@
│ ├── business/orders/
│ ├── customers/list/
│ └── error/NotFound.tsx
-│ # 页面目录：index.tsx、columns.tsx、types.ts、server.ts、同名 .scss（按需）
+│ # 页面目录：index.tsx、columns.tsx、types.ts、server.ts、components/（按需）、同名 .scss（按需）
├── router/
│ ├── routeConfig.tsx # 路由 + 菜单唯一数据源（含页面组件）
│ ├── menu.tsx # 菜单过滤与 antd Menu 结构生成
@@ -119,11 +119,58 @@
- 登录校验：`src/router/index.tsx` 中的 `RequireAuth`
- 全局提示 / 确认框：使用 `<App>` 提供的 `AntdApp.useApp()` 中的 `message`、`modal`，**不要**直接使用 `message.success()` / `Modal.confirm()` 静态方法。
3. **表格优先使用 ProTable**：新增列表页时优先使用 `@ant-design/pro-components` 提供的 `ProTable`，其搜索、分页、工具栏等能力开箱即用，不要手写筛选表单 + Table 的组合。
-4. **不要手写**弹窗、Toast、下拉菜单、分页、表格、表单校验等基础交互。
-5. 不引入新的 UI 组件库；确需新组件时，先检查是否已有可复用实现，再考虑在 `src/components/` 下新增。
-6. 使用 Ant Design 5 的 API，不使用已废弃属性。例如 Card 使用 `variant="borderless"`，不要使用 `bordered={false}`。
+4. **表单内的选择控件优先使用 ProForm 组件**：`Form` 内的 Select、TreeSelect、Cascader 等选择控件，只要选项来自接口（包括父组件传入的接口数据，如组织树、角色列表），必须使用 `@ant-design/pro-components` 提供的 `ProFormSelect`、`ProFormTreeSelect`、`ProFormCascader` 等，不要用 antd 原生控件包在 `Form.Item` 中；静态枚举选项不受此限制。远程搜索使用 `request`（配合 `debounceTime`），已有选项数据通过 `options` 或 `fieldProps` 传入，校验规则直接写在组件的 `rules` 上。
+ ```tsx
+ // ✅ 选项来自接口
+ <ProFormSelect
+ name="leaderId"
+ label="负责人"
+ showSearch
+ debounceTime={300}
+ request={async ({ keyWords }) => getLeaderOptions({ keyword: keyWords })}
+ />
-### 3. Table columns 必须单独提取
+ // ✅ 选项由父组件传入
+ <ProFormTreeSelect
+ name="parentId"
+ label="上级组织"
+ fieldProps={{ treeData: orgTree, showSearch: true }}
+ />
+
+ // ❌ 不要这样写
+ <Form.Item name="leaderId" label="负责人">
+ <Select options={leaderOptions} />
+ </Form.Item>
+ ```
+5. **不要手写**弹窗、Toast、下拉菜单、分页、表格、表单校验等基础交互。
+6. 不引入新的 UI 组件库；确需新组件时，先检查是否已有可复用实现，再考虑在 `src/components/` 下新增。
+7. 使用 Ant Design 5 的 API，不使用已废弃属性。例如 Card 使用 `variant="borderless"`，不要使用 `bordered={false}`。
+
+### 3. 独立组件必须放到 `components/`，超长页面拆分
+
+单独封装的组件不写在页面目录根部，统一放到页面目录下的 `components/` 子目录。
+
+- Drawer、Modal 等弹层组件，以及详情卡片、表单、局部业务块等可独立成文件的组件，放到 `src/pages/<业务域>/<页面>/components/` 下。
+- 组件文件使用大驼峰命名，如 `UserFormDrawer.tsx`、`CustomerDetailDrawer.tsx`；组件私有的 `.scss` 与组件同目录，由组件自身引入。
+- 组件只接收 `props`，接口调用仍放在页面目录的 `server.ts`，由页面或组件按需调用；不要跨页面直接引用其他页面目录下的组件。
+- 单个页面文件（含 `index.tsx`）超过 300 行时必须拆分：按功能块抽取到 `components/`，`columns.tsx`、`types.ts`、`server.ts`、`utils.ts` 等继续单独维护。
+- 大于 300 行的复杂组件同样按功能拆分，不要在同一个文件里堆叠多个组件。
+
+```text
+src/pages/system/users/
+├── index.tsx # 页面组件（尽量精简）
+├── columns.tsx # 表格列定义
+├── types.ts
+├── server.ts
+├── utils.ts # 按需
+├── Users.scss
+└── components/
+ ├── UserFormDrawer.tsx
+ ├── UserDetailDrawer.tsx
+ └── UserImportModal.tsx
+```
+
+### 4. Table columns 必须单独提取
所有表格的 `columns` 不得内联在 `<Table />` 的 JSX 中，也不写在页面组件内部。统一提取到页面目录单独维护。
@@ -231,6 +278,32 @@
- 页面级接口调用统一放在页面目录下的 `server.ts`，页面组件通过它调用接口，不要在组件内直接写请求实现。
- 跨页面复用的接口可放在 `src/api/` 下，按业务域拆分文件。
- 网络请求统一使用 `src/api/request.ts` 的 `request`（基于 axios），不要在页面或 `server.ts` 中直接使用 axios。
+- **接口调用使用 `.then` 链式处理，不要使用 `await` + `try/catch`**：成功逻辑写在 `.then`，失败逻辑写在 `.catch`（错误已由 `request` 统一提示时可只保留空 `catch`），收尾逻辑写在 `.finally`。禁止写成 `try { const data = await xxx() } catch {}`。（存量代码在后续迭代中逐步迁移。）
+
+```ts
+// ✅ 使用 .then 链式处理
+getOrgList({ page: 1, size: 20 })
+ .then((data) => {
+ setDataSource(data.records);
+ })
+ .catch(() => {
+ // 错误已由 request 统一提示
+ })
+ .finally(() => {
+ setLoading(false);
+ });
+
+// ❌ 不要使用 await + try/catch
+try {
+ const data = await getOrgList({ page: 1, size: 20 });
+ setDataSource(data.records);
+} catch {
+ // ...
+} finally {
+ setLoading(false);
+}
+```
+
- 开发环境通过 Vite 代理 `/proxy-api` 转发到 `VITE_API_PROXY_TARGET`（未配置时取 `VITE_API_BASE_URL`），因此浏览器端不会产生跨域请求；生产环境需后端配置 CORS，或使用同域反向代理。
- 泛型：`request<TReq, TRes>(config, options)`，分别表示请求参数/请求体与响应 `data` 的类型。
- 默认只返回响应 `data`；传 `parse: false` 时返回完整 `AxiosResponse`。
--
Gitblit v1.9.3