adspecs 0.1.12

package/references/ant6-front-standard/01-/345/237/272/347/241/200/350/247/204/350/214/203.md

@@ -0,0 +1,181 @@
+# 基础规范
+
+> 适用范围: React 19 + TypeScript 6 + Ant Design 6 + ProComponents
+> 版本: v3.3
+
+---
+
+## 1、技术栈基线
+
+| 维度   | 选型                                            | 备注                                                              |
+| ------ | ----------------------------------------------- | ----------------------------------------------------------------- |
+| 框架   | React 19.2 + TypeScript 6                       | strict 模式                                                       |
+| UI     | `antd` ^6.3 + `@ant-design/pro-components` ^3.1 | 列表统一用 `ProTable`                                             |
+| 图标   | `@ant-design/icons`                             | 按需引入；后端图标名通过 `<Icon icon="ep:xxx">` 走 `iconMap` 转换 |
+| 路由   | `react-router` ^7                               | `createBrowserRouter` + 动态路由 patch                            |
+| 状态   | `zustand` ^5                                    | `useAuthStore` / `useAppStore` / `useDictStore`                   |
+| 网络   | `axios` ^1.15                                   | 统一实例 `@/utils/request`                                        |
+| Mock   | `msw` ^2.13                                     | 仅 dev，受 `VITE_MOCK_ENABLED` 控制                               |
+| 国际化 | `react-i18next` ^17                             | 默认中文                                                          |
+| 构建   | Vite 8                                          | `npm run build` 必须通过 `tsc -b && vite build`                   |
+| 风格   | Prettier 单引号 / 分号 / 100 列宽 / 2 空格      | ESLint flat config + `react-hooks`                                |
+
+> **禁用**：Tailwind、CSS-in-JS 库、TanStack Query、Redux、Class 组件、`element-plus` 残留代码。
+
+---
+
+## 2、目录结构规范
+
+```
+src/
+├── api/                # axios 接口模块（按域拆分）
+│   ├── ai/             # /ai/* 接口
+│   ├── infra/
+│   ├── system/
+│   └── auth.ts
+├── components/         # 通用组件（首字母大写文件夹 + index.tsx 默认导出）
+│   ├── Access/         # 权限包裹
+│   ├── DictTag/        # 字典标签
+│   ├── Footer/         # 页脚
+│   ├── Icon/           # iconify → AntD 图标
+│   ├── Message/        # Header 铃铛 + 未读列表
+│   ├── UploadFile/     # UploadFile / UploadImg / UploadImgs
+│   ├── UserSelectForm/
+│   └── DeptSelectForm/
+├── hooks/              # 自定义 hook，use 前缀
+├── layouts/            # 仅一个 AdminLayout
+├── pages/              # 路由对应的页面
+│   ├── ai/             # 与后端菜单 path 完全对齐
+│   ├── infra/
+│   ├── system/
+│   ├── profile/
+│   └── login/
+├── mocks/              # MSW
+│   ├── data/index.ts   # 所有 mock 数据 + 字典 + 菜单
+│   └── handlers/       # 按模块拆 ai.ts / infra.ts / notify.ts ...
+├── router/             # createBrowserRouter + dynamicRoutes
+├── stores/             # zustand store
+├── types/              # 跨模块共享类型
+└── utils/              # request / formatTime / token / menuConverter ...
+```
+
+**关键约定**：
+
+1. **页面路径必须等于后端菜单 `component` 字段**。例如后端返回 `ai/chat/index/index` → 文件必须落在 `src/pages/ai/chat/index/index.tsx`，否则 `dynamicRoutes` 会报 `Component not found` 警告并显示 404。
+2. 子组件统一放在该页面同级 `components/` 下：`pages/<feature>/components/XxxModal.tsx`。
+3. 通用业务组件命名遵循 `components/<PascalCase>/index.tsx`。
+
+---
+
+## 3、命名规范
+
+| 对象          | 规则                            | 示例                                    |
+| ------------- | ------------------------------- | --------------------------------------- |
+| 组件文件      | PascalCase                      | `DeptModal.tsx` / `index.tsx`           |
+| 页面目录      | kebab-case 或保留后端 path      | `chat-role/`、`data-source-config/`     |
+| Hook          | `useXxx.ts`                     | `useAccess.ts`                          |
+| 工具/常量文件 | camelCase                       | `formatTime.ts`、`token.ts`             |
+| 类型          | `XxxVO`/`XxxParams`/`SystemXxx` | `ChatMessageVO`                         |
+| 常量          | UPPER_SNAKE                     | `MAX_AVATAR_MB`                         |
+| API 函数      | 动词 + 资源                     | `getDeptList`、`updateDataSourceConfig` |
+| 普通变量      | camelCase                       | `userName`                              |
+| 布尔变量      | is/has/can/should 开头          | `isValid`, `hasPermission`              |
+
+---
+
+## 4、编码风格规范
+
+### 4.1 代码格式化
+
+- 使用 2 个空格缩进
+- 优先使用单引号，如 `'string'`
+- JSX 属性使用双引号，如 `<div className="container">`
+- 模板字符串使用反引号
+- 使用分号
+- 函数调用和对象字面量末尾使用尾随逗号
+- 每行最多 100 个字符
+
+### 4.2 注释规范
+
+```typescript
+/**
+ * 获取用户列表
+ * @param params - 查询参数
+ * @param params.pageNum - 页码
+ * @param params.pageSize - 每页数量
+ */
+async function getUserList(params: UserPageParams): Promise<User[]> {
+  // 关键业务逻辑必须添加注释
+}
+```
+
+- 关键业务逻辑必须添加注释
+- 复杂算法必须添加说明
+- 临时解决方案需要标记 `// TODO: 说明`
+
+---
+
+
+---
+
+## 5、TypeScript 规范
+
+### 5.1 类型定义
+
+```typescript
+// 优先使用 interface（可扩展），联合类型 / 工具类型使用 type
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  active: boolean;
+}
+
+// 联合类型
+type Status = 'success' | 'warning' | 'danger';
+
+// API 响应类型（来自 @/types/api，不要重写）
+interface ApiResponse<T> {
+  code: number;
+  message: string;
+  data: T;
+}
+
+interface PageResult<T> {
+  total: number;
+  rows: T[];
+}
+```
+
+### 5.2 类型规则
+
+- **禁用 `any`**；必须时单行 `// eslint-disable-next-line @typescript-eslint/no-explicit-any`
+- API 入参 / 出参 / store 必须显式类型
+- Hook 暴露的 ref 类型用 `forwardRef<Handle, Props>` + `useImperativeHandle`
+- 不要写 `as any`；要么写正确类型，要么 `as unknown as Xxx`
+- 类型文件放在 `src/types/`，按领域组织
+
+---
+
+## 6、样式规范
+
+### 6.1 CSS 文件
+
+- 使用独立的 `.css` 文件，搭配功能名前缀类名（如 `.user-list`）
+- 类名使用 kebab-case
+- 避免使用缩写，如 `.btn` → `.button`
+
+### 6.2 Ant Design 样式定制
+
+- 优先使用 Ant Design 组件的内置属性（`size`, `type`, `variant`）
+- 全局主题定制通过 `ConfigProvider` 的 `theme` 属性
+- 局部覆盖样式使用 CSS 类 + 选择器，避免 `!important`
+- **自定义 SCSS 变量覆盖 → 改用 `ConfigProvider` + `theme.token`**
+
+### 6.3 响应式设计
+
+- 使用 Ant Design 的 `Grid` 组件（`Row` / `Col`）进行响应式布局
+- 断点参考 Ant Design 预设：`xs < 576 < sm < 768 < md < 992 < lg < 1200 < xl`
+- **左右分栏用原生 `display: flex`**，不要用 `Row/Col`（`Row` 默认 `flex-wrap: wrap` 会被换行）
+
+---

package/references/ant6-front-standard/02-/347/273/204/344/273/266/350/247/204/350/214/203.md

@@ -0,0 +1,189 @@
+# 组件规范
+
+> 适用范围: React 19 + TypeScript 6 + Ant Design 6 + ProComponents
+> 版本: v3.3
+
+---
+
+## 1、React 组件规范
+
+### 1.1 函数组件结构
+
+```tsx
+// 1. 导入语句（按类型分组：React -> 第三方库 -> 本地模块 -> 样式）
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { Form, Table, Button, Modal, Space } from 'antd';
+import { PlusOutlined } from '@ant-design/icons';
+import { ProTable, type ProColumns, type ActionType } from '@ant-design/pro-components';
+import { getUserList, deleteUser } from '@/api/system/user';
+import type { User } from '@/types/system/user';
+import Access from '@/components/Access';
+
+// 2. 类型定义（复杂类型建议放在 src/types/ 下）
+interface UserListProps {
+  departmentId?: number;
+}
+
+// 3. 组件定义（使用 function 声明）
+export default function UserList({ departmentId }: UserListProps) {
+  // 4. Hooks 调用（按顺序：ref/state -> custom hooks -> effects）
+  const { message, modal } = App.useApp();
+  const actionRef = useRef<ActionType>(undefined);
+  const [loading, setLoading] = useState(false);
+  const [selectedRowKeys, setSelectedRowKeys] = useState<React.Key[]>([]);
+
+  // 5. 事件处理函数
+  const handleDelete = useCallback(async (record: User) => {
+    modal.confirm({
+      title: '确认删除？',
+      okType: 'danger',
+      content: `确认删除「${record.name}」吗？`,
+      onOk: async () => {
+        await deleteUser(record.id!);
+        message.success('删除成功');
+        actionRef.current?.reload();
+      },
+    });
+  }, [message, modal]);
+
+  // 6. 列定义
+  const columns: ProColumns<User>[] = [
+    { title: '名称', dataIndex: 'name', width: 200 },
+    { title: '操作', key: 'action', search: false, render: (_, record) => (
+      <Space>
+        <Access code="system:user:update">
+          <a onClick={() => handleEdit(record)}>编辑</a>
+        </Access>
+        <Access code="system:user:delete">
+          <a style={{ color: '#ff4d4f' }} onClick={() => handleDelete(record)}>删除</a>
+        </Access>
+      </Space>
+    )},
+  ];
+
+  // 7. 渲染
+  return (
+    <ProTable<User>
+      columns={columns}
+      actionRef={actionRef}
+      rowKey="id"
+      request={async (params) => {
+        const { current, pageSize, ...rest } = params;
+        const { data } = await getUserList({ pageNo: current, pageSize, ...rest });
+        return { data: data.list, total: data.total, success: true };
+      }}
+      toolBarRender={() => [
+        <Access code="system:user:create" key="add">
+          <Button type="primary" icon={<PlusOutlined />} onClick={handleAdd}>新增</Button>
+        </Access>,
+      ]}
+    />
+  );
+}
+```
+
+### 1.2 Props 定义
+
+```typescript
+// 使用 interface 定义 props
+interface UserCardProps {
+  user: User;                        // 必填
+  showActions?: boolean;             // 可选
+  size?: 'small' | 'medium' | 'large'; // 带默认值
+  onDelete: (id: number) => void;    // 回调
+  children?: React.ReactNode;        // 子组件
+}
+
+// 使用 destructuring + 默认值
+export default function UserCard({
+  user,
+  showActions = false,
+  size = 'medium',
+  onDelete,
+  children,
+}: UserCardProps) {
+  return <div>{/* ... */}</div>;
+}
+```
+
+### 1.3 组件拆分原则
+
+- 单个组件不超过 300 行，超出按职责拆分
+- 页面内的子组件（Modal、Drawer 等）放在 `src/pages/<feature>/components/` 目录
+- 全局复用组件放在 `src/components/`
+- 避免在组件内部定义类型，应放在 `src/types/` 目录
+
+### 1.4 自定义 Hook 规范
+
+```typescript
+// hooks/useAccess.ts — 以 use 开头
+import { useAuthStore } from '@/stores/useAuthStore';
+
+export function useAccess(code: string): boolean {
+  const hasPermission = useAuthStore((s) => s.hasPermission);
+  return hasPermission(code);
+}
+```
+
+---
+
+
+---
+
+## 2、上传组件规范
+
+### 2.1 标准用法
+
+```tsx
+import { Upload } from 'antd';
+import { getAccessToken } from '@/utils/token';
+import { useAuthStore } from '@/stores/useAuthStore';
+
+<Upload
+  name="file"
+  action="/admin-api/infra/file/upload"
+  headers={{
+    Authorization: `Bearer ${getAccessToken() ?? ''}`,
+    'tenant-id': String(useAuthStore.getState().tenantId ?? ''),
+  }}
+  beforeUpload={...}
+  onChange={({ file }) => {
+    if (file.status === 'done') {
+      const resp = file.response as { code?: number; data?: string };
+      if (resp?.code === 0 && resp.data) {
+        form.setFieldsValue({ avatar: resp.data });
+      }
+    }
+  }}
+/>
+```
+
+或直接使用项目封装：`import { UploadFile, UploadImg, UploadImgs } from '@/components/UploadFile'`。
+
+### 2.2 Upload 在 Form 中的正确使用
+
+> AntD `Upload` 不识别 `value` 属性。`<Form.Item name="logo">` 默认会注入 `value` → Upload 报警告。
+
+**正确做法**：外层 `Form.Item` 仅做标签（不带 `name`），里面套一个 `<Form.Item name="logo" noStyle hidden><Input /></Form.Item>` 持有值，Upload 通过 `form.setFieldsValue({ logo: url })` 写入。
+
+---
+
+## 3、时间格式化规范
+
+**统一使用 `dateFormatter`**，禁止页面内手写 `dayjs().format(...)` 或字符串拼接：
+
+```tsx
+import { dateFormatter } from '@/utils/formatTime';
+
+// ProTable 列
+render: (_, record) => dateFormatter(record.createTime) || '-',
+
+// Descriptions
+<Descriptions.Item label="创建时间">{dateFormatter(data.createTime) || '-'}</Descriptions.Item>
+```
+
+`dateFormatter` 接受 `string | number | Date | null`，统一返回 `YYYY-MM-DD HH:mm:ss`，空值返回空串。
+
+> **注意**：如果后端 `createTime` 可能是 number/Date，统一用 `new Date(value).getTime()` 包装再比较。
+
+---

package/references/ant6-front-standard/03-/345/210/227/350/241/250/350/247/204/350/214/203.md

@@ -0,0 +1,147 @@
+# 列表规范
+
+> 适用范围: React 19 + TypeScript 6 + Ant Design 6 + ProComponents
+> 版本: v3.3
+
+---
+
+## 1、列表页标准模式（ProTable）
+
+> 所有「带筛选 + 分页」的列表都**必须**使用 `ProTable`，**不要再用** `Card + Form + Table`。
+> 树形列表（dept/menu）例外，用本地 `dataSource` + `pagination={false}` + `expandable`。
+
+### 1.1 标准模板
+
+```tsx
+import { useRef, useState } from 'react';
+import { App, Button, Space } from 'antd';
+import { PlusOutlined, DeleteOutlined } from '@ant-design/icons';
+import { ProTable, type ProColumns, type ActionType } from '@ant-design/pro-components';
+import { getXxxPage, deleteXxx, deleteXxxList, type XxxVO } from '@/api/xxx';
+import Access from '@/components/Access';
+import DictTag from '@/components/DictTag';
+import { dateFormatter } from '@/utils/formatTime';
+import { useDictStore } from '@/stores/useDictStore';
+import XxxModal from './components/XxxModal';
+
+const XxxPage: React.FC = () => {
+  const { message, modal } = App.useApp();
+  const actionRef = useRef<ActionType>(undefined);
+  const [selectedRowKeys, setSelectedRowKeys] = useState<React.Key[]>([]);
+  const [modalOpen, setModalOpen] = useState(false);
+  const [editId, setEditId] = useState<number | null>(null);
+  const getDictOptions = useDictStore((s) => s.getDictOptions);
+
+  const reload = () => actionRef.current?.reload();
+
+  const handleDelete = (record: XxxVO) => {
+    modal.confirm({
+      title: '确认删除？', okType: 'danger',
+      content: `确认删除「${record.name}」吗？`,
+      onOk: async () => {
+        await deleteXxx(record.id!);
+        message.success('删除成功'); reload();
+      },
+    });
+  };
+
+  const handleDeleteBatch = () => {
+    modal.confirm({
+      title: '确认批量删除？', okType: 'danger',
+      content: `确认删除选中的 ${selectedRowKeys.length} 项？`,
+      onOk: async () => {
+        await deleteXxxList(selectedRowKeys.map(Number));
+        message.success('删除成功');
+        setSelectedRowKeys([]);
+        reload();
+      },
+    });
+  };
+
+  const columns: ProColumns<XxxVO>[] = [
+    { title: '名称', dataIndex: 'name', width: 200 },
+    {
+      title: '状态', dataIndex: 'status', width: 100,
+      valueType: 'select',
+      valueEnum: Object.fromEntries(
+        getDictOptions('common_status').map((d) => [d.value, { text: d.label }]),
+      ),
+      render: (_, r) => <DictTag type="common_status" value={r.status} />,
+    },
+    {
+      title: '创建时间', dataIndex: 'createTime', width: 180,
+      valueType: 'dateRange',
+      search: {
+        transform: (value) => {
+          if (!Array.isArray(value)) return {};
+          return { createTimeStart: value[0], createTimeEnd: value[1] };
+        },
+      },
+      render: (_, r) => dateFormatter(r.createTime) || '-',
+    },
+    {
+      title: '操作', key: 'action', width: 140, fixed: 'right', search: false,
+      render: (_, record) => (
+        <Space>
+          <Access code="xxx:update">
+            <a onClick={() => { setEditId(record.id!); setModalOpen(true); }}>编辑</a>
+          </Access>
+          <Access code="xxx:delete">
+            <a style={{ color: '#ff4d4f' }} onClick={() => handleDelete(record)}>删除</a>
+          </Access>
+        </Space>
+      ),
+    },
+  ];
+
+  return (
+    <>
+      <ProTable<XxxVO>
+        columns={columns}
+        actionRef={actionRef}
+        rowKey="id"
+        scroll={{ x: 1200 }}
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        request={async (params: any) => {
+          const { current, pageSize, ...rest } = params;
+          const { data } = await getXxxPage({ pageNo: current ?? 1, pageSize: pageSize ?? 10, ...rest });
+          return { data: data.list, total: data.total, success: true };
+        }}
+        pagination={{ defaultPageSize: 10, showSizeChanger: true }}
+        rowSelection={{ selectedRowKeys, onChange: setSelectedRowKeys }}
+        toolBarRender={() => [
+          <Access code="xxx:create" key="add">
+            <Button type="primary" icon={<PlusOutlined />}
+              onClick={() => { setEditId(null); setModalOpen(true); }}>新增</Button>
+          </Access>,
+          <Access code="xxx:delete" key="batch">
+            <Button danger icon={<DeleteOutlined />}
+              disabled={selectedRowKeys.length === 0}
+              onClick={handleDeleteBatch}>批量删除</Button>
+          </Access>,
+        ]}
+      />
+      <XxxModal open={modalOpen} id={editId}
+        onSuccess={() => { setModalOpen(false); reload(); }}
+        onCancel={() => setModalOpen(false)} />
+    </>
+  );
+};
+
+export default XxxPage;
+```
+
+### 1.2 ProTable 列定义关键规则
+
+| 场景          | 写法                                                                                       |
+| ------------- | ------------------------------------------------------------------------------------------ |
+| 隐藏搜索      | `search: false`（**不是** `hideInSearch`）                                                 |
+| 下拉搜索      | `valueType: 'select'` + `valueEnum: Object.fromEntries(getDictOptions(...).map(...))`      |
+| 日期区间      | `valueType: 'dateRange'` + `search.transform` 拆 `xxxStart/xxxEnd`                         |
+| 日期区间渲染  | **必须用 `render`，不要用 `renderText`**                                                   |
+| 长 label 搜索 | `search={{ labelWidth: 'auto' }}`（在 ProTable 上）                                        |
+| request 参数  | 固定加 `// eslint-disable-next-line @typescript-eslint/no-explicit-any` 允许 `params: any` |
+| 树形表        | 去掉 `request`，改用 `dataSource={tree}` + `pagination={false}` + `expandable`             |
+
+---
+