# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

**始终使用简体中文与我对话，并在回答时保持专业、简洁。**

## 项目概述

Flame-Plus 是基于 Vue 3 + Element-Plus 二次开发的组件库（当前版本 1.5.7），用于配合 Sparks 后台快速开发框架，通过 `PageRouter.vue` 等页面动态配置前端界面。核心理念是**配置驱动**——通过 JSON 配置对象控制组件行为，实现动态页面生成。

## 常用命令

```bash
npm run dev        # 启动 Vite 开发服务器
npm run build      # 打包为 ES + UMD 格式，输出到 flameDist/
npm run preview    # 预览打包结果
npm run gen <name> # 生成新的基础组件脚手架（scripts/gc.sh）
```

没有配置测试命令（虽然 gc.sh 会生成 vitest 测试文件骨架，但项目未配置测试运行器）。

## 发布流程

```bash
# 1. 先构建
npm run build

# 2. 更新版本号（默认只升小版本）
#    手动编辑 package.json 中的 "version" 字段，如 "1.5.7" → "1.5.8"

# 3. 发布到 npm
npm publish
```

> **注意**：发布前必须先执行 `npm run build`，确保 `flameDist/` 目录下是最新的构建产物。发布的是 `flameDist/` 中的内容（由 package.json 的 `main`/`module` 字段指向）。

## 架构

### 三层组件体系

```
src/packages/
├── components/
│   ├── base/       → 基础组件：对 Element-Plus 原生组件的封装
│   ├── complex/    → 复合组件：组合多个基础组件的业务组件
│   └── page/       → 页面组件：完整的可配置业务页面
├── types/          → 本地 TypeScript 类型（ControlTypes 枚举、FormConfig 等）
├── utils/          → 工具函数（filterConfig、format）
├── eutils/         → 从 @vueuse/core 引入的工具
├── plugins/        → 插件配置（TinyMCE）
└── index.ts        → 主入口，定义 install() 和所有组件导出
```

### 基础组件模式（base）

每个基础组件是对 Element-Plus 组件的 config 封装。核心模式：

1. 接收单一 `config` prop（类型来自 `flame-types` 包，如 `InputConfig`）
2. 使用 `filterConfig(defaultConfig, props.config)` 合并默认配置与用户配置
3. 使用 TSX render function 渲染对应的 `el-*` 组件
4. 通过 emit 向上传递事件

```vue
<!-- 典型基础组件结构（TSX） -->
<script lang="tsx">
import { InputConfig, inputDefaultConfig } from 'flame-types'
import { filterConfig } from '../../../utils'

const inputConfig = computed(() => filterConfig(inputDefaultConfig, props.config))
return () => <el-input {...inputConfig.value} {...events} />
</script>
```

### 复合组件（complex）

- **flmForm**：配置驱动表单，根据 `ControlTypes` 枚举动态渲染不同控件
- **flmTable**：可编辑表格，支持排序、过滤、自定义列渲染
- **flmSearch**：搜索表单，支持默认字段 + 抽屉式额外字段
- **flmSearchSelect**：搜索页选择，集成 flame-request 发起 API 请求
- **flmModuleForm**：模块化复杂表单，支持表单+表格嵌套、Tab 页签
- **FlmToolbar**：工具栏

### 页面组件（page）

- **flmReportPage**：完整报表页面（搜索 + 表格 + 工具栏 + 对话框 + 分页），是最核心的高层组件
- **flmExportPage**：导出页面

### 组件注册机制

`install()` 函数支持三个可选参数：
```typescript
install(app, plugins?, components?, elementPlusIconsVue?)
```
- `plugins`：Vue 插件数组
- `components`：自定义组件数组，与内置组件合并
- `elementPlusIconsVue`：Element-Plus 图标组件

## 关键依赖

| 包 | 用途 |
|---|---|
| `flame-types` | 所有组件的配置类型定义和默认配置 |
| `flame-request` | HTTP 请求库，在部分组件中直接使用（外部化，不打包） |
| `element-plus` | 基础 UI 库（外部化，不打包） |
| `tinymce` | 富文本编辑器（外部化，不打包） |
| `dayjs` / `numeral` | 日期/数字格式化 |
| `bootstrap 4.6.2` | CSS 基础样式 |

## 构建配置要点

- 入口：`src/packages/index.ts`
- 输出：`flameDist/flame-plus.es.js` 和 `flameDist/flame-plus.umd.js`
- 外部化依赖：vue、element-plus、tinymce、flame-request（不打包进库）
- CSS 不分割（合并到一个文件）
- 路径别名：`@/` → `src/`
- 开发代理：`/spark-auth-service`、`/spark-openapi-service`、`/spark-resource-service` → UAT 环境

## 编码规范

- Prettier：行宽 100、2 空格缩进、单引号、无分号
- 基础组件使用 `<script lang="tsx">` + `defineComponent` + render function
- 复合/页面组件使用 `<script setup lang="ts">`
- 组件命名：基础组件 `flm` 前缀小驼峰（flmInput），复杂独立组件 `Flm` 前缀大驼峰（FlmEditor）

## 与 Sparks 后端的关系

Flame-Plus 组件（特别是 flmReportPage）通过 Sparks 后端的 `flame_table_info` / `flame_table_info_item` 元数据表驱动页面配置。PageRouter.vue 选择应用和菜单后，根据配置的表名加载对应的搜索、表格、表单等 UI 定义，实现无代码/低代码页面生成。
