# 交互规范

1、使用中文交互

---

# 项目架构概览

## 技术栈


| 层级      | 技术                         |
| --------- | ---------------------------- |
| 框架      | Vue 3 + TypeScript 5         |
| 构建      | Vite 4                       |
| UI 组件库 | Ant Design Vue 3             |
| 状态管理  | Pinia 2                      |
| 路由      | Vue Router 4                 |
| HTTP      | Axios（自定义封装`defHttp`） |
| 样式      | Less + Windi CSS             |
| 国际化    | Vue I18n 9                   |
| 基础框架  | Vben Admin（深度定制）       |
| 包管理    | pnpm                         |

> 注意：本项目与 Vue 3.4.x 不兼容，请保持 Vue ~3.3.4。

---

## 目录结构

```
src/
├── api/            # HTTP 请求模块，按业务域分组
│   └── <domain>/
│       └── <module>/
│           ├── index.ts      # 请求函数
│           └── model/        # 请求/响应 TS 类型
├── assets/         # 静态资源、全局样式
├── components/     # 可复用组件（BasicTable、BasicForm、Modal 等）
├── design/         # 全局 Less 主题入口
├── hooks/          # 组合式函数（composables）
├── layouts/        # 布局组件（header、sider、tabs）
├── locales/        # i18n 配置
├── router/         # 路由配置、守卫
├── store/          # Pinia 状态模块
│   └── modules/    # app / user / permission / locale / lock / multipleTab
├── utils/          # 工具函数
│   └── http/axios/ # HTTP 封装核心
└── views/          # 业务页面，按业务域分组
    └── <domain>/   # erp / system / workflow / contract / sales ...
```

---

## 路径别名


| 别名      | 指向                              |
| --------- | --------------------------------- |
| `/@/`     | `src/`                            |
| `/#/`     | `types/`                          |
| `/@bpmn/` | `src/views/workflow/design/bpmn/` |

**始终使用别名，禁止使用相对路径 `../../`。**

---

# 代码规范

## 1. Vue 组件

### 新文件优先使用 `<script setup>`

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { useI18n } from '/@/hooks/web/useI18n';

const { t } = useI18n();
const visible = ref(false);
</script>
```

存量代码中存在 `defineComponent` 写法，维护时保持原有风格，新增代码统一用 `<script setup>`。

### 文件命名


| 场景        | 规范        | 示例                                |
| ----------- | ----------- | ----------------------------------- |
| 页面入口    | `index.vue` | `src/views/system/user/index.vue`   |
| 弹窗/子组件 | PascalCase  | `UserModal.vue`、`DetailDrawer.vue` |
| 组合式函数  | camelCase   | `useUserList.ts`                    |

### 事件处理函数命名

统一以 `handle` 开头：`handleEdit`、`handleDelete`、`handleSubmit`。

---

## 2. API 模块

每个业务模块的 API 结构：

```
src/api/<domain>/<module>/
├── index.ts      # 导出请求函数
└── model/
    └── index.ts  # 请求/响应类型定义
```

**示例：**

```ts
// src/api/erp/purchase/apply/index.ts
import { defHttp } from '/@/utils/http/axios';
import type { ApplyListParams, ApplyListResult } from './model';

enum Api {
  List = '/erp/purchase/apply/list',
  Save = '/erp/purchase/apply/save',
}

export const getApplyList = (params: ApplyListParams) =>
  defHttp.get<ApplyListResult>({ url: Api.List, params });

export const saveApply = (data: ApplyListParams) =>
  defHttp.post({ url: Api.Save, data });
```

- 所有 HTTP 请求必须通过 `defHttp`，禁止直接使用 axios。
- 接口路径统一用 `enum Api` 管理。
- 错误提示通过 `errorMessageMode` 控制（`'modal'` | `'message'` | `'none'`）。

---

## 3. 状态管理（Pinia）

```ts
// src/store/modules/xxx.ts
import { defineStore } from 'pinia';
import { store } from '/@/store';

export const useXxxStore = defineStore({
  id: 'app-xxx',
  state: () => ({ ... }),
  getters: { ... },
  actions: { ... },
});

// 在 setup 外使用
export function useXxxStoreWithOut() {
  return useXxxStore(store);
}
```

- Store 命名：`useXxxStore`
- 需要在 setup 外调用时，导出 `useXxxStoreWithOut`

---

## 4. 表格页面（CRUD 标准模式）

```vue
<template>
  <PageWrapper>
    <BasicTable @register="registerTable">
      <template #toolbar>
        <a-button type="primary" @click="handleAdd">新增</a-button>
      </template>
      <template #action="{ record }">
        <TableAction :actions="getActions(record)" />
      </template>
    </BasicTable>
    <XxxModal @register="registerModal" @success="reload" />
  </PageWrapper>
</template>

<script setup lang="ts">
import { useTable } from '/@/components/Table';
import { useModal } from '/@/components/Modal';
import { PageWrapper } from '/@/components/Page';
import { TableAction } from '/@/components/Table';

const [registerTable, { reload }] = useTable({
  api: getXxxList,
  columns,
  useSearchForm: true,
  formConfig: { schemas },
  showTableSetting: true,
  bordered: true,
});

const [registerModal, { openModal }] = useModal();

function handleAdd() {
  openModal(true, { isUpdate: false });
}

function getActions(record) {
  return [
    { label: '编辑', onClick: () => openModal(true, { record, isUpdate: true }) },
    { label: '删除', color: 'error', popConfirm: { title: '确认删除?', confirm: () => handleDelete(record) } },
  ];
}
</script>
```

---

## 5. 样式规范

- 组件内样式：`<style lang="less" scoped>`
- 全局主题变量在 `src/design/` 和 `src/assets/style/theme/` 中定义
- 工具类优先使用 Windi CSS（如 `flex`、`items-center`、`mt-4`）
- 项目自定义主题类前缀：`lng-`
- 禁止在 scoped 样式中直接穿透 AntD 组件，改用 `:deep()`

```less
// 正确
:deep(.ant-table-cell) {
  padding: 8px;
}
```

---

## 6. TypeScript 规范

- 严格模式已开启（`strict: true`），但项目对 `any` 较宽松
- API 请求/响应类型放在对应 `model/` 目录
- 通用类型放在 `types/` 目录，通过 `/#/` 别名引用
- 变量命名：
  - `ref` 变量加 `Ref` 后缀：`visibleRef`、`loadingRef`
  - computed 可加 `ComputedRef` 后缀

---

## 7. 国际化

所有用户可见文本必须通过 i18n：

```ts
import { useI18n } from '/@/hooks/web/useI18n';
const { t } = useI18n();

// 使用
t('common.okText')
```

---

## 8. 权限控制

按钮级权限通过 `v-auth` 指令或 `usePermission` 控制：

```vue
<a-button v-auth="'system:user:add'">新增</a-button>
```

```ts
import { usePermission } from '/@/hooks/web/usePermission';
const { hasPermission } = usePermission();
if (hasPermission('system:user:edit')) { ... }
```

---

## 9. 工作流路由约定

特殊路由格式（在 `src/router/routes/basic.ts` 中定义）：


| 路由                                | 用途         |
| ----------------------------------- | ------------ |
| `/flow/:arg1/:arg2/createFlow`      | 发起流程     |
| `/flow/:arg1/:arg2/approveFlowPage` | 审批流程     |
| `/form/:module/:id/createForm`      | 通用表单新建 |
| `/form/:module/:id/updateForm`      | 通用表单编辑 |
| `/flowList/todo`                    | 待办列表     |

---

## 10. 提交规范

遵循 Conventional Commits：

```
feat: 新增功能
fix: 修复 bug
refactor: 重构
style: 样式调整
docs: 文档更新
chore: 构建/工具变更
```

---

## 新增页面检查清单

- [ ]  在 `src/views/<domain>/` 下创建目录
- [ ]  页面入口为 `index.vue`，弹窗为 `XxxModal.vue`
- [ ]  API 模块放在 `src/api/<domain>/<module>/index.ts`
- [ ]  类型定义放在 `model/index.ts`
- [ ]  使用 `PageWrapper` + `BasicTable` + `useTable` + `useModal` 标准结构
- [ ]  文本通过 `useI18n` 国际化
- [ ]  按钮权限通过 `v-auth` 控制
- [ ]  样式使用 `<style lang="less" scoped>`
- [ ]  路径使用 `/@/` 别名

---

# 代码生成器（generator）规范

## 目录结构

```
src/views/generator/
├── codeTemplate/          # 模板管理列表（草稿增删改查）
├── designer/              # 表单设计器演示/测试页
├── dev/                   # 代码生成器核心入口
│   ├── choose.vue         # 模式选择入口页
│   └── components/
│       ├── DataFirstModal.vue      # 数据优先向导
│       ├── CodeFirstModal.vue      # 界面优先向导
│       ├── SimpleTemplateModal.vue # 简易模板向导
│       ├── PreviewCodeStep.vue     # 代码预览步骤（三种模式共用）
│       └── SelectDatabase.vue     # 选择数据库表弹窗
├── desktop/               # 桌面/首页可视化设计器
├── order/                 # 示例产物（订单模块演示）
└── print/                 # 打印模板设计器
```

步骤子组件统一放在 `/@/components/CreateCodeStep/src/` 下。

---

## 三种生成模式

| 维度 | 数据优先 | 界面优先 | 简易模板 |
|------|---------|---------|---------|
| `designType` | `'data'` | `'code'` | `'template'` |
| `outputConfig.type` | `0` | `1` | `2` |
| 起点 | 选数据库表 | 设计表单 | 设计表单（固定 master 库） |
| 表配置字段 | `tableConfigs` | `tableStructureConfigs` | `tableStructureConfigs` |
| 生成接口 | `dataFirstGeneratorCode` | `codeFirstGeneratorCode` | `codeFirstGeneratorCode` |
| 预览接口 | `dataFirstPreviewCode` | `codeFirstPreviewCode` | `codeFirstPreviewCode` |
| 特殊逻辑 | 无 | 自动推导主表名 | 额外判断字段大小写（Oracle/DM 等） |

简易模板本质是界面优先的变体，复用同一套后端生成接口，仅 `type` 不同。

---

## 核心设计模式

### 1. provide/inject 共享生成状态

父 Modal 通过 `provide` 下发，子步骤通过 `inject` 直接读写，禁止 props 层层传递：

```ts
provide('generatorConfig', generatorConfig)  // 核心配置（reactive）
provide('tableInfo', tableInfo)              // 表结构信息
provide('current', current)                  // 当前步骤索引
provide('designType', 'data')               // 生成模式标识
provide('widgetForm', widgetForm)            // 表单设计器状态
provide('mainTableName', mainTableName)      // 主表名（界面优先/简易模板）
provide('isFieldUpper', isFieldUpper)        // 字段大小写（简易模板）
```

### 2. ref + defineExpose 控制步骤流转

每个步骤子组件必须暴露 `validateStep()`，父组件通过 ref 统一调用：

```ts
// 子组件
defineExpose({ validateStep, initStep?, getFormData?, editFieldsValue? })

// 父组件
const stepValidate = {
  0: () => tableConfigStepRef.value.validateStep(),
  1: () => formDesignStepRef.value.validateStep(),
  // ...
}
```

### 3. 前端本地生成 + 后端补全的混合模式

```
前端本地 buildCode()              后端接口 previewCode()
─────────────────────             ──────────────────────
listCode（列表页）                controllerCode（控制器）
formCode（表单页）                entityCode（实体类）
apiCode（API 模块）
modelCode（TS 类型）
configJsonCode（路由配置）
```

### 4. hiddenComponent 生命周期

```ts
// 编辑模板时：从列表剔除，不在设计器中展示
formJson.list = formJson.list.filter(x => x.type !== 'hiddenComponent')

// 正式生成时：重新塞回，参与代码生成
generatorConfig.formJson.list.push(...generatorConfig.formJson.hiddenComponent)
```

### 5. 两段式下载

```
生成接口 → 返回 uuid → downloadCodes(uuid) → 下载 zip
```

---

## 核心数据结构

```ts
GeneratorConfig {
  databaseId: string | null
  listConfig: {
    isLeftMenu, queryConfigs, leftMenuConfig,
    columnConfigs, buttonConfigs, defaultOrder, isPage
  }
  tableConfigs: TableConfig[]            // 仅数据优先
  tableStructureConfigs: []              // 界面优先/简易模板
  formJson: FormJson                     // 表单设计结果
  menuConfig: MenuConfig
  outputConfig: {
    creator, isMenu,
    type: 0 | 1 | 2                     // 生成模式
  }
  formEventConfig: FormEventColumnConfig
  isDataAuth: boolean
  dataAuthList: []
}
```

类型定义文件：`src/api/system/generator/model/index.ts`

---

## API 接口

所有接口在 `src/api/system/generator/index.ts`：

| 函数 | 方法 | 路径 |
|------|------|------|
| `dataFirstGeneratorCode` | POST | `/system/generator/generator-code/data-first` |
| `codeFirstGeneratorCode` | POST | `/system/generator/generator-code/code-first` |
| `dataFirstPreviewCode` | POST | `/system/generator/preview-code/data-first` |
| `codeFirstPreviewCode` | POST | `/system/generator/preview-code/code-first` |
| `saveDraftGeneratorCode` | POST | `/system/code-schema` |
| `updateDraftGeneratorCode` | PUT | `/system/code-schema` |
| `getCodeTemplateInfo` | GET | `/system/code-schema/info` |
| `getCodeTemplateList` | GET | `/system/code-schema/page` |
| `deleteCodeTemplate` | DELETE | `/system/code-schema` |
| `getMasterInfo` | GET | `/system/databaselink/master-info` |
| `batchGeneratorCode` | POST | `/system/generator/generator-code/batch` |
| `downloadCodes` | GET | `/system/generator/downloadCodes/{uuid}` |

---

## 功能扩展指南

### 新增生成模式

1. 复制 `CodeFirstModal.vue`，修改 `designType` 和 `outputConfig.type`
2. 在 `choose.vue` 加入入口卡片
3. 在 `codeTemplate/index.vue` 的路由名判断中加入新类型
4. 后端新增对应生成/预览接口

### 新增向导步骤

1. 在 `/@/components/CreateCodeStep/src/` 下新建步骤组件，暴露 `validateStep()`
2. 在主 Modal 的 `<a-steps>` 中加入新步骤
3. 在 `stepValidate` 对象中加入对应索引的校验函数
4. 在 `generatorConfig` 中加入新步骤的配置字段，并通过 `provide` 下发

### 扩展代码预览输出类型

1. 在 `FrontCode` 类型中加入新字段
2. 在 `PreviewCodeStep.vue` 的 `<a-tabs>` 中加入新 tab
3. 在 `validateStep()` 中加入非空校验
4. 在 `buildCode()` 或 `previewCode()` 中补充生成逻辑