# MetaPlugin 使用文档

## 1. 插件简介

MetaPlugin 是一个 IntelliJ IDEA 插件，用于把 XSD 结构转换为可配置的 XOM 映射 XML，并按配置生成对应的 Java 实体类。

当前项目中的插件信息：
- 插件名：`MetaPlugin`
- 插件 ID：`com.dmiki.metaplugin`
- 当前版本：`1.0.0`
- IDE 兼容下限：`sinceBuild = 193`（IntelliJ IDEA 2019.3+）

## 2. 核心能力

- 解析 XSD 并以树表格方式展示节点结构。
- 可视化配置每个节点的：
  - 配置策略
  - Java 属性名
  - Java 类型
  - 自定义属性（可按节点启用）
  - 预处理属性（可按节点启用）
- 预览最终 XOM 内容。
- 生成完整 XOM 文件。
- 可按“选中节点”局部预览/局部生成 XOM。
- 打开已有 `.xml` / `.xom` 映射文件后，反向回显到配置界面继续编辑。

## 3. 安装与启动

### 3.1 开发调试（推荐）

在项目根目录执行：

```bash
./gradlew.bat runIde
```

会启动一个带插件的沙箱 IDE。

### 3.2 打包安装

在项目根目录执行：

```bash
./gradlew.bat buildPlugin
```

打包产物位于：

- `build/distributions/MetaPlugin-1.0.0.zip`

在 IDEA 中通过 `Settings -> Plugins -> Install Plugin from Disk...` 选择该 ZIP 安装。

## 4. 入口与触发条件

插件动作名称为：`XOM生成`。

显示位置：
- Project View 右键菜单
- Editor 右键菜单

显示条件：仅在右键目标是以下文件时可见：
- `.xsd`
- `.xml`
- `.xom`

说明：
- 右键 `.xsd`：进入 XSD 解析与配置流程。
- 右键 `.xml` / `.xom`：按 XOM 回显流程加载已有映射。
- `.xml` 入口对任意 XML 文件可见，但只有包含 `message/schema/resultMap` 结构的映射 XML 才能正确回显。

## 5. 快速使用流程

### 5.1 从 XSD 开始生成

1. 在项目中右键一个 `.xsd` 文件，点击 `XOM生成`。
2. 插件自动解析 XSD 并展示树表格。
3. 按需修改顶部参数与节点配置。
4. 点击 `预览XOM` 检查输出。
5. 点击 `生成XOM文件` 生成映射文件与 Java 实体。

### 5.2 从已存在映射文件继续编辑（回显）

1. 右键一个 `.xml` 或 `.xom` 映射文件，点击 `XOM生成`。
2. 插件根据 `<schema xsdPath="...">` 找到对应 XSD。
3. 自动恢复节点策略、属性映射、自定义属性、预处理属性等配置。
4. 调整后可再次预览或生成。

## 6. 界面参数说明

### 6.1 顶部基础参数

- 报文类型（`schemaId`）：默认取 XSD 文件名（去扩展名）。
- 包名：默认 `com.example.message`。
  - 注意这里填写的是“包名”，最终 `resultMap.type` 会自动拼接为：`包名 + 报文类型大写格式`。
  - 例如 `hvps.101.001.01` 会转为 `HVPS_101_001_01`。
- 输出目录：支持绝对路径或相对项目根目录路径。
- 自定义属性：全局默认值，默认 `sign`。
- 预处理属性：全局默认值，默认空。

### 6.2 表格列说明

- XML节点：节点名称与标记（必填、Choice、List、属性节点等）。
- 配置策略：控制该节点是否保留层级/属性/子项。
- JAVA属性名：生成 `property` 与 Java 字段名的来源。
- JAVA类型：生成 Java 实体字段类型（可编辑）。
- 自定义属性：勾选后为该节点输出 `attribute="..."`。
- 预处理属性：勾选后为该节点输出 `pre-processor="..."`。

说明：
- 自定义属性、预处理属性为“每行可启用 + 文本值”的组合输入。
- 若行内启用但文本为空，会回退使用顶部全局默认值。

## 7. 配置策略语义

### 7.1 非叶子节点可选策略

- `保留层级保留属性`
  - 输出该节点 `<result>`，同时输出 `property`。
- `保留层级不保留属性`
  - 输出该节点 `<result>`，不输出 `property`。
- `不保留层级`
  - 不输出当前层 `<result>`，子节点上提到父层；标签会写成 `父:子`。
- `不保留层级且不保留子项`
  - 当前节点及其子树都不输出。

### 7.2 叶子节点可选策略

- `保留`：输出该节点 `<result>`。
- `不保留`：忽略该节点。

## 8. 输出规则

### 8.1 XOM XML 结构

输出结构固定为：

- `<message>`
- `<schema id="..." xsdPath="..."/>`
- `<resultMap id="..." type="..."> ... </resultMap>`

### 8.2 标签属性命名

- 普通节点使用 `lable="..."`（历史拼写，插件当前仍按该键输出）。
- 属性节点使用 `lable-attribute="..."`。

说明：回显逻辑同时兼容 `label/lable` 与 `label-attribute/lable-attribute` 两套写法。

### 8.3 输出目录与文件名

- 默认输出目录：`src/main/resources` 下第一个不存在的目录：
  - `msgmapper`
  - `msgmapper1`
  - `msgmapper2`
  - ... 依次类推
- 默认输出文件名：`报文类型.xml`。
- 右键“生成选中节点XOM文件”时，默认文件名：`报文类型_节点名.xml`。

### 8.4 Java 实体输出规则

- 仅当 `resultMap.type` 含包名（存在 `.`）时才会生成 Java 文件。
- Java 文件输出目录固定为：`XOM 文件所在目录/java`。
- 如果包名为空（或未形成完整限定名），仅生成 XOM，不生成 Java。

## 9. 右键节点快捷能力

在树表格中右键某节点可用：

- `预览选中节点XOM`
- `生成选中节点XOM文件`

用途：
- 仅验证或导出某个子树配置，减少大文件全量生成的调试成本。

## 10. 常见错误与排查

- `XOM-001`：XSD 路径为空，或文件不存在/不可读。
- `XOM-002`：生成参数为空，或 `schemaId` 为空。
- `XOM-003`：
  - 未解析到可渲染节点，或
  - 严格模式下出现同级重复 label。
- `XOM-004`：
  - 严格模式启用但 `resultMap.type` 为空，或
  - 启用未知类型校验时节点 Java 类型缺失。
- `XOM-005`：最大层级不合法，或节点深度超限。
- `XOM-006`：输出文件/目录写入失败、目录创建失败等 IO 问题。

排查建议：
- 优先确认 `schema.xsdPath` 指向的文件实际存在。
- 确认输出目录有写权限。
- 先用 `预览XOM` 验证结构，再执行生成。
- 如果回显失败，优先检查映射文件是否存在 `resultMap` 节点及 `schema.xsdPath`。

## 11. 常用 Gradle 命令

```bash
# 运行单元测试
./gradlew.bat test

# 启动带插件的沙箱 IDEA
./gradlew.bat runIde

# 打包插件 ZIP
./gradlew.bat buildPlugin
```

## 12. 当前版本已知行为

- 动作仅在右键 `.xsd/.xml/.xom` 文件时出现。
- 默认根类型会偏向以 XSD 中名为 `Document` 的全局元素作为根；若不存在则取第一个全局元素。
- 输出 XOM 使用 `lable` 字段名属于历史兼容行为。