# af-vue2-client 详细参考

需要更细的约定、目录树或技术栈时查阅本文档。日常以 [SKILL.md](../SKILL.md) 为主。

## 目录

- [代码风格与约定](#代码风格与约定)
  - [工具与实用程序](#工具与实用程序)
- [项目目录结构](#项目目录结构)
- [技术栈版本](#技术栈版本)
- [发布检查清单](#发布检查清单)
- [项目内其他文档](#项目内其他文档)

---

## 代码风格与约定

### 组件
- 优先：Vue 2.7 组合 API + `<script setup>`，声明式。
- 避免：选项 API（除非改既有代码）。
- 方法/计算属性用箭头函数；简单条件可单行 `if (x) return y`。

### 命名
- 目录：kebab-case（如 `user-manage`）。
- 组件文件：PascalCase（如 `UserTable.vue`）。
- 可组合/工具：camelCase（如 `useAuthState.js`、`formatDate.js`）。
- 布尔：`isLoading`、`hasError`、`canEdit`、`shouldShow`。
- 常量：UPPER_SNAKE_CASE。
- 注释与用户可见文案：中文。

### 导入顺序
1. Vue/第三方库 → 2. 组件 → 3. composables → 4. utils → 5. 样式。

### X 组件与配置
- base-client 中 XForm、XTable、XCard、XPageView 等全局注册，用 JSON 配置驱动。
- 系统配置在 `src/config/`，默认配置在 `src/config/default/`，替换器在 `src/config/replacer/`。
- 能用配置的不写硬编码；表单校验等共享逻辑用 mixins；布局用 XFormCol 栅格。

### Less 与主题
- Less 变量在 `src/theme/`，Ant Design 主题可动态替换；组件样式与组件同目录；可选 BEM。

### ESLint / Git
- 提交前必须 `npm run lint` 通过；推荐约定式提交（feat/fix/docs/style/refactor/test/chore）。

### 工具与实用程序

#### 多级日志系统 (`src/utils/logger.js`)

支持 `a.b.c` 格式的多级日志名，从**项目本地配置文件**读取日志开关配置。已注册为 Vue 插件，可在组件和配置脚本中使用。

**配置文件位置**：
- 优先：`src/config/logger.config.js`（推荐，独立配置文件）
- 备选：`src/config/config.js`（如果存在 `logger`、`logLevels` 或 `logEnabled` 字段）

**使用方式**：

1. **在 Vue 组件中**（推荐）：
```javascript
// 在组件方法中使用
this.$logger('a.b.c').log('消息内容')
this.$logger('a.b.c').info('信息')
this.$logger('a.b.c').warn('警告')
this.$logger('a.b.c').error('错误')
this.$logger('a.b.c').debug('调试信息')
```

2. **在配置脚本中**（如 `dataProcessScript`、`customFunction` 等）：
```javascript
// 配置脚本中 this 指向组件实例，可直接使用
this.$logger('report.dataProcess').log('开始处理数据')
this.$logger('report.dataProcess').info('数据:', data)
```

3. **通过 import 导入**（在普通 JS 文件中）：
```javascript
import logger from '@vue2-client/utils/logger'

logger('a.b.c').log('消息内容')
logger('a.b.c').info('信息')
```

4. **全局访问**（不推荐，仅用于特殊场景）：
```javascript
Vue.$logger('a.b.c').log('消息内容')
```

**配置文件格式**（在项目 `src/config/logger.config.js` 中设置）：

1. **数组格式（支持通配符）**（推荐）：
```javascript
// src/config/logger.config.js
module.exports = ['report.setData', 'report.dataProcessScript', 'report.*']
```

2. **对象格式**：
```javascript
// src/config/logger.config.js
module.exports = {
  'report.setData': true,
  'report.dataProcessScript': true,
  'report.configLoad': false
}
```

3. **在 config.js 中使用 logLevels 字段**：
```javascript
// src/config/config.js
module.exports = {
  compatible: 'V4',
  logLevels: ['report.setData', 'report.*']
}
```

**说明**：
- Logger 已注册为 Vue 插件（`LoggerPlugin`），在 `bootstrap.js` 中自动加载
- 配置文件从**项目本地**读取，每个开发者可以设置自己的日志配置，互不影响
- 如果配置文件不存在或没有日志配置，默认**全部启用**（开发友好）
- 支持通配符：`"a.*"` 会匹配 `a.b`、`a.b.c`、`a.x.y` 等所有以 `a.` 开头的日志路径
- 日志输出格式：`log[a.b.c]: 内容`
- 配置会被缓存，避免重复读取
- 在配置脚本（如 `XReport` 的 `dataProcessScript`）中，`this` 指向组件实例，可直接使用 `this.$logger()`

---

## 项目目录结构

```
vue2-client/
├── src/
│   ├── main.js, bootstrap.js, App.vue    # 入口
│   ├── base-client/                      # 基础组件（X 系列，全局注册）
│   │   ├── components/                   # XForm, XTable, XCard, XPageView...
│   │   └── plugins/
│   ├── pages/                            # 页面（按功能分子目录）
│   ├── layouts/                          # 布局
│   ├── router/                           # 路由（index, guards, async/router.map.js）
│   ├── services/                         # apiService, DataModel, api/*
│   ├── store/modules/                    # Vuex 模块
│   ├── config/                           # 配置（default, replacer）
│   ├── utils/                            # 工具
│   ├── theme/                            # 主题
│   ├── expression/, logic/               # 低代码表达式与逻辑
│   ├── components/                       # 通用组件（按需引入）
│   ├── mixins/, plugins/                 # 混入与自定义插件
│   └── assets/                           # 静态资源（经 Webpack）
├── public/                               # 静态资源（不经 Webpack）
├── test/, tests/unit/                    # 测试
├── vue.config.js, package.json, .env*    # 配置
└── .cursor/commands/release.md           # 发布步骤
```

---

## 技术栈版本

| 类别     | 依赖               | 版本/说明        |
|----------|--------------------|------------------|
| 框架     | Vue                | 2.7.14           |
| 路由/状态| Vue Router / Vuex  | 3.6.x            |
| UI       | ant-design-vue     | 1.7.8            |
| 构建     | Vue CLI / Webpack  | 5.x / 5.x        |
| 样式     | Less               | 预处理器         |
| HTTP     | axios              | 0.27.x           |
| 测试     | Jest, @vue/test-utils | 29.x, 1.3.x   |
| 开发端口 | —                  | 8020             |
| 别名     | @, @vue2-client    | → src/           |

- Windows 需 `NODE_OPTIONS=--openssl-legacy-provider`；不支持 IE11。

---

## 发布检查清单

1. 更新 `package.json` 版本号。
2. 运行 `yarn lint` 或 `npm run lint`，无错误通过。
3. 更新 `CHANGELOG.md`：版本号、更新内容、提交人（`git config user.name`）、当前日期；格式参考既有条目。
4. `git status` 确认无遗漏未提交更改。
5. 写约定式 commit，可加 emoji：✨ 新功能、🐛 修复、⚡ 性能、🔧 配置、📝 文档、♻️ 重构、🎨 样式。

提交 message 示例：

```
发布 x.xx.xx

- 新增 xxx 功能
- 修改 xxx 中的 xxx 方法
- 更新 xxx 枚举，增加 xxx 选项
```

---

## 项目内其他文档

- 项目根目录 [CLAUDE.md](../../../../CLAUDE.md)：命令与架构总览。
- `.serena/memories/code_style_conventions.md`：完整代码风格。
- `.serena/memories/project_structure.md`：完整目录与模块说明。
- `.serena/memories/tech_stack.md`：完整技术栈与配置。
- `.cursor/commands/release.md`：发布步骤与 commit 示例。
