# 前端开发文档

本文档定义了项目的开发规范、组件复用指南和代码风格要求，确保团队开发风格统一。

---

## 一、开发规范

### 1.1 组件开发规范

#### 组件命名

```typescript
// ✅ 正确：组件文件使用 PascalCase
UserList.vue;
DictTag.vue;
TableAction.vue;

// ❌ 错误：使用 kebab-case 或其他命名
user - list.vue;
dict_tag.vue;
```

#### 组件定义

```vue
<script lang="ts" setup>
// ✅ 正确：统一使用 <script setup lang="ts">
defineOptions({ name: "UserList" });

// Props 定义
interface Props {
  userId: number;
  userName?: string;
}

const props = withDefaults(defineProps<Props>(), {
  userName: "",
});

// Emits 定义
interface Emits {
  (e: "update", value: string): void;
  (e: "delete", id: number): void;
}

const emit = defineEmits<Emits>();
</script>
```

#### TypeScript 规范

```typescript
// ✅ 正确：禁止使用 any，使用具体类型
interface UserInfo {
  id: number;
  name: string;
  email?: string;
}

function getUser(id: number): Promise<UserInfo> {
  return request.get(`/user/${id}`);
}

// ❌ 错误：使用 any
function getUser(id: any): any {
  return request.get(`/user/${id}`);
}

// ✅ 正确：使用 import type 导入类型
import type { UserInfo } from "#/api/system/user";

// ❌ 错误：普通导入类型
import { UserInfo } from "#/api/system/user";
```

### 1.2 目录结构规范

```
src/
├── api/              # API 接口定义，按模块划分
│   ├── system/       # 系统模块
│   │   ├── user/
│   │   │   └── index.ts
│   │   └── dept/
│   │       └── index.ts
│   └── ...
├── components/       # 公共组件（全局注册）
├── views/            # 页面组件，按业务模块划分
│   └── system/
│       └── user/
│           ├── index.vue        # 列表页
│           ├── data.ts          # 数据定义
│           └── modules/         # 子组件/弹窗
│               └── form.vue
├── locales/          # 国际化
├── router/           # 路由配置
├── stores/           # Pinia 状态管理
├── utils/            # 工具函数
└── adapter/          # 适配器配置
```

### 1.3 API 接口规范

```typescript
// src/api/system/user/index.ts

import { request } from "#/utils/request";

export namespace SystemUserApi {
  /** 用户信息 */
  export interface User {
    id: number;
    username: string;
    nickname: string;
    email?: string;
    status: number;
    deptId?: number;
    createTime: string;
  }

  /** 用户分页查询参数 */
  export interface PageParams {
    pageNo: number;
    pageSize: number;
    username?: string;
    status?: number;
    deptId?: number;
  }

  /** 分页结果 */
  export interface PageResult {
    list: User[];
    total: number;
  }
}

/** 获取用户分页列表 */
export function getUserPage(params: SystemUserApi.PageParams) {
  return request.get<SystemUserApi.PageResult>("/system/user/page", { params });
}

/** 获取用户详情 */
export function getUser(id: number) {
  return request.get<SystemUserApi.User>(`/system/user/get?id=${id}`);
}

/** 创建用户 */
export function createUser(data: SystemUserApi.User) {
  return request.post("/system/user/create", data);
}

/** 更新用户 */
export function updateUser(data: SystemUserApi.User) {
  return request.put("/system/user/update", data);
}

/** 删除用户 */
export function deleteUser(id: number) {
  return request.delete(`/system/user/delete?id=${id}`);
}
```

### 1.4 样式规范

```vue
<template>
  <div class="user-list">
    <!-- 优先使用 Tailwind CSS 类 -->
    <div class="flex items-center justify-between p-4 mb-2 bg-white rounded-lg">
      <span class="text-base font-medium text-gray-900">标题</span>
    </div>
  </div>
</template>

<style lang="scss" scoped>
/* 组件样式使用 scoped */
.user-list {
  /* 颜色使用 CSS 变量 */
  background-color: var(--component-background);

  /* 必要时覆盖组件库样式 */
  :deep(.ant-table) {
    border-radius: 8px;
  }
}
</style>
```

---

## 二、核心组件复用指南

### 2.1 表格组件 (useVbenVxeGrid)

项目使用 VxeTable 封装的 `useVbenVxeGrid` 作为核心表格组件。

#### 基础用法

```vue
<script lang="ts" setup>
import type { VxeTableGridOptions } from "#/adapter/vxe-table";
import type { SystemUserApi } from "#/api/system/user";

import { useVbenVxeGrid, TableAction, ACTION_ICON } from "#/adapter/vxe-table";
import { getUserPage } from "#/api/system/user";

// 表格列配置
const columns: VxeTableGridOptions["columns"] = [
  { type: "checkbox", width: 50 },
  { field: "username", title: "用户名", width: 120 },
  { field: "nickname", title: "昵称", width: 120 },
  {
    field: "status",
    title: "状态",
    width: 100,
    cellRender: {
      name: "CellDict",
      props: { type: "common_status" },
    },
  },
  { field: "createTime", title: "创建时间", width: 180 },
  { field: "action", title: "操作", width: 200, slots: { default: "actions" } },
];

// 表格实例
const [Grid, gridApi] = useVbenVxeGrid({
  formOptions: {
    schema: [
      {
        fieldName: "username",
        label: "用户名",
        component: "Input",
      },
      {
        fieldName: "status",
        label: "状态",
        component: "Select",
        componentProps: {
          options: getDictOptions("common_status"),
        },
      },
    ],
  },
  gridOptions: {
    columns,
    height: "auto",
    keepSource: true,
    proxyConfig: {
      ajax: {
        query: async ({ page }, formValues) => {
          return await getUserPage({
            pageNo: page.currentPage,
            pageSize: page.pageSize,
            ...formValues,
          });
        },
      },
    },
    rowConfig: {
      keyField: "id",
      isHover: true,
    },
  } as VxeTableGridOptions<SystemUserApi.User>,
});

// 刷新表格
function handleRefresh() {
  gridApi.query();
}
</script>

<template>
  <Grid table-title="用户列表">
    <template #actions="{ row }">
      <TableAction
        :actions="[
          {
            label: '编辑',
            type: 'link',
            icon: ACTION_ICON.EDIT,
            auth: ['system:user:update'],
            onClick: handleEdit.bind(null, row),
          },
          {
            label: '删除',
            type: 'link',
            danger: true,
            icon: ACTION_ICON.DELETE,
            auth: ['system:user:delete'],
            popConfirm: {
              title: `确认删除【${row.username}】吗？`,
              confirm: handleDelete.bind(null, row),
            },
          },
        ]"
      />
    </template>
  </Grid>
</template>
```

#### 表格列渲染器

| 渲染器          | 用途     | 示例                                                                 |
| --------------- | -------- | -------------------------------------------------------------------- |
| `CellImage`     | 单图展示 | `cellRender: { name: 'CellImage' }`                                  |
| `CellImages`    | 多图展示 | `cellRender: { name: 'CellImages' }`                                 |
| `CellLink`      | 链接按钮 | `cellRender: { name: 'CellLink', props: { text: '查看' } }`          |
| `CellTag`       | 标签展示 | `cellRender: { name: 'CellTag', props: { color: 'blue' } }`          |
| `CellDict`      | 字典标签 | `cellRender: { name: 'CellDict', props: { type: 'common_status' } }` |
| `CellSwitch`    | 开关切换 | `cellRender: { name: 'CellSwitch', attrs: { beforeChange } }`        |
| `CellOperation` | 操作按钮 | `cellRender: { name: 'CellOperation', options: ['edit', 'delete'] }` |

### 2.2 表单弹窗 (useVbenModal)

```vue
<script lang="ts" setup>
import { useVbenModal } from "#/packages/effects/common-ui/src";
import Form from "./modules/form.vue";

// 弹窗实例
const [FormModal, formModalApi] = useVbenModal({
  connectedComponent: Form,
  destroyOnClose: true,
});

// 打开新增弹窗
function handleCreate() {
  formModalApi.setData(null).open();
}

// 打开编辑弹窗
function handleEdit(row: any) {
  formModalApi.setData(row).open();
}
</script>

<template>
  <FormModal @success="handleRefresh" />
</template>
```

表单组件示例：

```vue
<!-- modules/form.vue -->
<script lang="ts" setup>
import type { SystemUserApi } from "#/api/system/user";

import { computed, ref } from "vue";
import { useVbenModal } from "#/packages/effects/common-ui/src";
import { useVbenForm } from "#/adapter/form";
import { createUser, updateUser } from "#/api/system/user";

const emit = defineEmits(["success"]);

const [Modal, modalApi] = useVbenModal({
  async onConfirm() {
    const values = await formApi.getValues();
    if (formData.value?.id) {
      await updateUser({ ...values, id: formData.value.id });
    } else {
      await createUser(values);
    }
    emit("success");
    modalApi.close();
  },
});

const formData = ref<SystemUserApi.User>();

const [Form, formApi] = useVbenForm({
  schema: [
    {
      fieldName: "username",
      label: "用户名",
      rules: "required",
      component: "Input",
    },
    {
      fieldName: "nickname",
      label: "昵称",
      rules: "required",
      component: "Input",
    },
    {
      fieldName: "email",
      label: "邮箱",
      rules: "email",
      component: "Input",
    },
    {
      fieldName: "deptId",
      label: "部门",
      component: "TreeSelect",
    },
  ],
});

// 监听弹窗打开
modalApi.onOpen((data) => {
  formData.value = data;
  if (data) {
    formApi.setValues(data);
  }
});
</script>

<template>
  <Modal title="用户信息">
    <Form />
  </Modal>
</template>
```

### 2.3 字典组件

#### DictTag - 字典标签

用于展示数据字典值的标签形式。

```vue
<script lang="ts" setup>
import DictTag from "#/components/dict-tag/dict-tag.vue";
</script>

<template>
  <DictTag type="common_status" :value="1" />
</template>
```

#### DictSelect - 字典选择器

用于表单中从字典选择值。

```vue
<script lang="ts" setup>
import DictSelect from "#/components/form-create/components/dict-select.vue";
</script>

<template>
  <!-- 下拉选择 -->
  <DictSelect v-model="form.status" dict-type="common_status" />

  <!-- 单选按钮 -->
  <DictSelect
    v-model="form.status"
    dict-type="common_status"
    select-type="radio"
  />

  <!-- 复选框 -->
  <DictSelect
    v-model="form.types"
    dict-type="common_status"
    select-type="checkbox"
  />
</template>
```

#### 字典工具函数

```typescript
import {
  getDictOptions,
  getDictLabel,
  getDictObj,
} from "#/packages/effects/hooks/src";

// 获取字典选项列表（用于 Select/Radio 等组件）
const options = getDictOptions("common_status", "number");

// 获取字典标签文本
const label = getDictLabel("common_status", 1); // "开启"

// 获取字典完整对象
const dictObj = getDictObj("common_status", 1);
// { label: '开启', value: 1, colorType: 'success', cssClass: '' }
```

### 2.4 表格操作组件 (TableAction)

用于表格中的操作按钮，支持权限控制和二次确认。

```vue
<script lang="ts" setup>
import { TableAction, ACTION_ICON } from "#/adapter/vxe-table";
</script>

<template>
  <TableAction
    :actions="[
      {
        label: '编辑',
        type: 'link',
        icon: ACTION_ICON.EDIT,
        auth: ['system:user:update'],
        onClick: handleEdit,
      },
      {
        label: '删除',
        type: 'link',
        danger: true,
        icon: ACTION_ICON.DELETE,
        auth: ['system:user:delete'],
        popConfirm: {
          title: '确认删除吗？',
          confirm: handleDelete,
        },
      },
    ]"
    :drop-down-actions="[
      {
        label: '分配角色',
        auth: ['system:permission:assign-user-role'],
        onClick: handleAssignRole,
      },
    ]"
  />
</template>
```

### 2.5 文件上传组件

#### ImageUpload - 图片上传

```vue
<script lang="ts" setup>
import ImageUpload from "#/components/upload/image-upload.vue";

const imageUrl = ref("");
const imageList = ref<string[]>([]);
</script>

<template>
  <!-- 单图上传 -->
  <ImageUpload v-model="imageUrl" :max-number="1" />

  <!-- 多图上传 -->
  <ImageUpload v-model="imageList" :max-number="5" />

  <!-- 限制大小和格式 -->
  <ImageUpload
    v-model="imageUrl"
    :max-size="5"
    :accept="['.jpg', '.jpeg', '.png']"
  />
</template>
```

#### FileUpload - 文件上传

```vue
<script lang="ts" setup>
import FileUpload from "#/components/upload/file-upload.vue";

const fileList = ref<string[]>([]);
</script>

<template>
  <FileUpload
    v-model="fileList"
    :max-number="3"
    :max-size="10"
    :accept="['.pdf', '.doc', '.docx']"
  />
</template>
```

### 2.6 描述列表组件 (Description)

用于详情页展示数据。

```vue
<script lang="ts" setup>
import Description from "#/components/description/description.vue";

const data = {
  username: "admin",
  nickname: "管理员",
  email: "admin@example.com",
  status: 0,
  createTime: "2024-01-01 12:00:00",
};

const schema = [
  { field: "username", label: "用户名" },
  { field: "nickname", label: "昵称" },
  { field: "email", label: "邮箱" },
  {
    field: "status",
    label: "状态",
    render: (value) => h(DictTag, { type: "common_status", value }),
  },
  { field: "createTime", label: "创建时间" },
];
</script>

<template>
  <Description title="基本信息" :data="data" :schema="schema" />
</template>
```

---

## 三、状态管理

### 3.1 使用 Pinia Store

项目使用 Pinia 进行状态管理，Store 定义在 `src/packages/stores/src` 中。

#### 常用 Store

| Store            | 用途       | 导入路径                |
| ---------------- | ---------- | ----------------------- |
| `useUserStore`   | 用户信息   | `#/packages/stores/src` |
| `useAccessStore` | 权限/Token | `#/packages/stores/src` |
| `useDictStore`   | 数据字典   | `#/packages/stores/src` |

#### 示例

```typescript
import { useUserStore, useAccessStore } from "#/packages/stores/src";

const userStore = useUserStore();
const accessStore = useAccessStore();

// 获取用户信息
const userInfo = userStore.userInfo;

// 检查权限
const { hasAccessByCodes } = useAccess();
const canEdit = hasAccessByCodes(["system:user:update"]);
```

---

## 四、权限控制

### 4.1 按钮权限

```vue
<script lang="ts" setup>
import { useAccess } from "#/packages/effects/access/src";

const { hasAccessByCodes } = useAccess();
</script>

<template>
  <!-- 方式一：通过 TableAction 的 auth 属性 -->
  <TableAction
    :actions="[
      {
        label: '编辑',
        auth: ['system:user:update'],
        onClick: handleEdit,
      },
    ]"
  />

  <!-- 方式二：通过 v-if 手动判断 -->
  <Button v-if="hasAccessByCodes(['system:user:create'])" type="primary">
    新增
  </Button>
</template>
```

### 4.2 路由权限

在路由配置中通过 `meta.authorities` 设置权限：

```typescript
{
  path: 'user',
  name: 'SystemUser',
  component: () => import('#/views/system/user/index.vue'),
  meta: {
    title: '用户管理',
    authorities: ['system:user:visit'],
  },
}
```

---

## 五、国际化

### 5.1 使用方式

```vue
<script lang="ts" setup>
import { $t } from "#/locales";
</script>

<template>
  <Button>{{ $t("common.save") }}</Button>
  <span>{{ $t("ui.actionMessage.deleteSuccess", ["用户"]) }}</span>
</template>
```

### 5.2 添加国际化文本

在 `src/locales` 目录下的语言文件中添加：

```json
// src/locales/zh-CN.json
{
  "common": {
    "save": "保存",
    "cancel": "取消"
  },
  "ui": {
    "actionMessage": {
      "deleteSuccess": "删除【{0}】成功"
    }
  }
}
```

---

## 六、常用 Hooks

### 6.1 usePagination - 分页

```typescript
import { usePagination } from "#/packages/effects/hooks/src";

const { page, pageSize, total, setPage, setTotal } = usePagination();
```

### 6.2 useTabs - 标签页操作

```typescript
import { useTabs } from "#/packages/effects/hooks/src";

const { closeOtherTabs, closeTab, refreshTab } = useTabs();

// 关闭其他标签页
await closeOtherTabs();

// 刷新当前页
await refreshTab();
```

### 6.3 useWatermark - 水印

```typescript
import { useWatermark } from "#/packages/effects/hooks/src";

const { updateWatermark, destroyWatermark } = useWatermark();

// 设置水印
await updateWatermark({
  content: "用户名",
});

// 销毁水印
destroyWatermark();
```

---

## 七、工具函数

### 7.1 常用工具

```typescript
import {
  formatDateTime, // 日期格式化
  formatDate, // 日期格式化（不含时间）
  downloadFileFromBlobPart, // 文件下载
  isEmpty, // 判空
  isFunction, // 判断函数
  isString, // 判断字符串
} from "#/packages/utils/src";

// 日期格式化
formatDateTime("2024-01-01T12:00:00"); // "2024-01-01 12:00:00"

// 文件下载
downloadFileFromBlobPart({
  fileName: "用户列表.xlsx",
  source: blobData,
});

// 判空
isEmpty([]); // true
isEmpty({}); // true
isEmpty(null); // true
```

### 7.2 数字格式化

```typescript
import {
  erpNumberFormatter, // 数字格式化
  fenToYuan, // 分转元
  formatFileSize, // 文件大小格式化
} from "#/packages/utils/src";

// 保留两位小数
erpNumberFormatter(1234.567, 2); // "1,234.57"

// 分转元
fenToYuan(12345); // 123.45

// 文件大小
formatFileSize(1024 * 1024); // "1.00 MB"
```

---

## 八、代码示例：标准 CRUD 页面

```vue
<script lang="ts" setup>
import type { VxeTableGridOptions } from "#/adapter/vxe-table";
import type { SystemUserApi } from "#/api/system/user";

import { ref } from "vue";

import { confirm, Page, useVbenModal } from "#/packages/effects/common-ui/src";
import { getDictOptions } from "#/packages/effects/hooks/src";
import { downloadFileFromBlobPart, isEmpty } from "#/packages/utils/src";

import { message } from "ant-design-vue";

import { useVbenVxeGrid, TableAction, ACTION_ICON } from "#/adapter/vxe-table";
import {
  getUserPage,
  deleteUser,
  createUser,
  updateUser,
  exportUser,
} from "#/api/system/user";
import { $t } from "#/locales";

import Form from "./modules/form.vue";

// ========== 弹窗定义 ==========
const [FormModal, formModalApi] = useVbenModal({
  connectedComponent: Form,
  destroyOnClose: true,
});

// ========== 表格定义 ==========
const checkedIds = ref<number[]>([]);

const [Grid, gridApi] = useVbenVxeGrid({
  formOptions: {
    schema: [
      {
        fieldName: "username",
        label: "用户名",
        component: "Input",
        componentProps: { placeholder: "请输入用户名" },
      },
      {
        fieldName: "status",
        label: "状态",
        component: "Select",
        componentProps: {
          options: getDictOptions("common_status", "number"),
          placeholder: "请选择状态",
        },
      },
    ],
  },
  gridOptions: {
    columns: [
      { type: "checkbox", width: 50 },
      { field: "username", title: "用户名", width: 120 },
      { field: "nickname", title: "昵称", width: 120 },
      {
        field: "status",
        title: "状态",
        width: 100,
        cellRender: { name: "CellDict", props: { type: "common_status" } },
      },
      { field: "createTime", title: "创建时间", width: 180 },
      {
        field: "action",
        title: "操作",
        width: 180,
        slots: { default: "actions" },
      },
    ],
    height: "auto",
    keepSource: true,
    proxyConfig: {
      ajax: {
        query: async ({ page }, formValues) => {
          return await getUserPage({
            pageNo: page.currentPage,
            pageSize: page.pageSize,
            ...formValues,
          });
        },
      },
    },
    rowConfig: { keyField: "id", isHover: true },
    toolbarConfig: { refresh: true, search: true },
  } as VxeTableGridOptions<SystemUserApi.User>,
  gridEvents: {
    checkboxAll: ({ records }) => {
      checkedIds.value = records.map((item) => item.id!);
    },
    checkboxChange: ({ records }) => {
      checkedIds.value = records.map((item) => item.id!);
    },
  },
});

// ========== 操作方法 ==========
function handleRefresh() {
  gridApi.query();
}

async function handleExport() {
  const data = await exportUser(await gridApi.formApi.getValues());
  downloadFileFromBlobPart({ fileName: "用户.xls", source: data });
}

function handleCreate() {
  formModalApi.setData(null).open();
}

function handleEdit(row: SystemUserApi.User) {
  formModalApi.setData(row).open();
}

async function handleDelete(row: SystemUserApi.User) {
  await deleteUser(row.id!);
  message.success($t("ui.actionMessage.deleteSuccess", [row.username]));
  handleRefresh();
}

async function handleDeleteBatch() {
  await confirm($t("ui.actionMessage.deleteBatchConfirm"));
  // ... 批量删除逻辑
}
</script>

<template>
  <Page auto-content-height>
    <FormModal @success="handleRefresh" />

    <Grid table-title="用户列表">
      <template #toolbar-tools>
        <TableAction
          :actions="[
            {
              label: $t('ui.actionTitle.create', ['用户']),
              type: 'primary',
              icon: ACTION_ICON.ADD,
              auth: ['system:user:create'],
              onClick: handleCreate,
            },
            {
              label: $t('ui.actionTitle.export'),
              type: 'primary',
              icon: ACTION_ICON.DOWNLOAD,
              auth: ['system:user:export'],
              onClick: handleExport,
            },
            {
              label: $t('ui.actionTitle.deleteBatch'),
              type: 'primary',
              danger: true,
              icon: ACTION_ICON.DELETE,
              disabled: isEmpty(checkedIds),
              auth: ['system:user:delete'],
              onClick: handleDeleteBatch,
            },
          ]"
        />
      </template>

      <template #actions="{ row }">
        <TableAction
          :actions="[
            {
              label: $t('common.edit'),
              type: 'link',
              icon: ACTION_ICON.EDIT,
              auth: ['system:user:update'],
              onClick: handleEdit.bind(null, row),
            },
            {
              label: $t('common.delete'),
              type: 'link',
              danger: true,
              icon: ACTION_ICON.DELETE,
              auth: ['system:user:delete'],
              popConfirm: {
                title: $t('ui.actionMessage.deleteConfirm', [row.username]),
                confirm: handleDelete.bind(null, row),
              },
            },
          ]"
        />
      </template>
    </Grid>
  </Page>
</template>
```

---

## 九、注意事项

1. **路径别名**：`#/*` 指向 `./src/*`，导入时使用 `#/components/xxx` 而非相对路径
2. **表单验证**：使用 VeeValidate + Zod，在 schema 中通过 `rules` 属性定义
3. **HTML 安全**：用户输入的 HTML 使用 `v-dompurify-html` 处理
4. **敏感数据**：使用 `secure-ls` 加密存储
5. **代码注释**：只在 WHY 不明显时添加注释，避免无意义的注释
6. **组件命名**：必须使用 `defineOptions({ name: 'ComponentName' })` 定义组件名

---

## 十、相关资源

- [Vue 3 文档](https://vuejs.org/)
- [Ant Design Vue 文档](https://antdv.com/)
- [VxeTable 文档](https://vxetable.cn/)
- [Tailwind CSS 文档](https://tailwindcss.com/)
- [项目 CLAUDE.md](./CLAUDE.md)