# 活字格工程解析器

**Repository Path**: low-code-dev-lab/huozige-ontology-builder

## Basic Information

- **Project Name**: 活字格工程解析器
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-01
- **Last Updated**: 2026-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# huozige-ontology-builder

一个基于 TypeScript 的命令行工具，用确定性规则扫描活字格工程并输出简化版 Ontology 文件，包含：

- 表结构 `tables`：对应实体与实体间关系
- 页面候选项绑定 `candidatesbindings`：对应候选列绑定信息
- 页面表格绑定 `tablebindings`：对应表格列绑定信息
- 服务端命令 `servercommands`：对应实体动作或函数
- 服务端命令在页面中的使用位置

整个过程不依赖 AI，只依赖文件扫描和 JSON 结构解析。

## 解析范围

- `Tables/**/*.json`
- `ServerCommands/**/*.json`
- `Pages/**/*.json`
- `MasterPages/**/*.json`
- `UserControlPages/**/*.json`

当前对带 HTTP 触发器的服务端命令判定规则是：

- `ServerCommands` 中包含 `PostRequestTrigger`

服务端命令扫描模式由 `--sc_mode` 控制，默认值是 `all`：

- `all`：扫描所有服务端命令
- `whitelist`：仅扫描备注中包含 `[HOB_INCLUDE]` 的服务端命令
- `blacklist`：扫描所有服务端命令，但跳过备注中包含 `[HOB_EXCLUDE]` 的服务端命令

## 安装

```bash
npm install -g huozige-ontology-builder
```

全局安装后，可直接执行：

```bash
huozige-ontology-builder
```

## 使用

```bash
huozige-ontology-builder https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample
```

指定工作目录：

```bash
huozige-ontology-builder https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample --workdir /tmp/hzg-workspace
```

指定服务端命令扫描模式：

```bash
huozige-ontology-builder https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample --sc_mode whitelist
```

指定应用信息：

```bash
huozige-ontology-builder https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample --app_info "这是一个示例应用，没有具体业务"
```

本地开发调试：

```bash
npm install
npm run build
node dist/cli.js https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample --workdir /tmp/hzg-workspace
```

组合使用：

```bash
node dist/cli.js https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample --workdir /tmp/hzg-workspace --sc_mode blacklist
```

如果你只是在当前项目目录执行了 `npm install`，命令不会自动安装到全局 PATH。此时可以改用以下任一方式运行：

```bash
npm run start -- https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample
```

```bash
npx huozige-ontology-builder https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample
```

## 输出目录

CLI 会在工作目录下创建一次运行对应的时间戳目录：

```text
<workspace>/
  <timestamp>/
    src/
      <git-name>/
    result/
      <git-name>/
        ontology.json
        index.md
        entities/
          entity-<EntityName>.md
        servercommands/
          sc-<ServerCommandName>.md
        bindings/
          binding-<PageName>.md
        ...
```

其中：

- clone 路径：`<timestamp>/src/<git-name>/`
- 输出路径：`<timestamp>/result/<git-name>/`

## 输出内容

会同时输出：

- `ontology.json`
- `index.md`
- `entities/entity-{实体名}.md`
- `servercommands/sc-{服务端命令名}.md`
- `bindings/binding-{页面名}.md`

## ontology.json

核心结构如下：

```json
{
  "repo-name": "simple-forguncy-reporting-system",
  "app_info": "示例应用",
  "huozige-version": "11.0.104.0",
  "builder-version": "0.3.0",
  "tables": [
    {
      "table-name": "数据表",
      "table-description": "",
      "columns": [
        {
          "column-name": "id",
          "column-alias": "主键",
          "column-datatype": "Number",
          "column-required": true,
          "column-unique": true
        }
      ],
      "relationships": []
    }
  ],
  "candidatesbindings": [
    {
      "page-name": "页面1",
      "component-type": "ComboBox",
      "column-bindings": [
        {
          "column-type": "ID",
          "TableName": "数据表",
          "ColumnName": "ID",
          "GUID": "a0b4a492-276b-4a0c-a3c2-1d8fe1596f8a"
        },
        {
          "column-type": "text",
          "TableName": "数据表",
          "ColumnName": "文本",
          "GUID": "2bfc7ad4-c23b-460e-877e-b0ed785be45b"
        }
      ]
    }
  ],
  "tablebindings": [
    {
      "page-name": "页面1",
      "view-name": "页面1表格1",
      "list-view-location": "页面1|表格1",
      "table-name": "数据表",
      "columns": [
        {
          "table-name": "数据表",
          "column-name": "文本",
          "guid": "067cc6ea-73f0-4f2f-9dee-9d5d8a178e96"
        }
      ]
    }
  ],
  "servercommands": [
    {
      "servercommand-name": "ExampleCommand",
      "servercommand-description": "PostRequestTrigger",
      "verb": "post",
      "input-arguments": [],
      "output-arguments": [],
      "used-by": []
    }
  ]
}
```

## Table Extraction Rules

- `table-name` 读取自表 JSON 的 `Name`
- `table-description` 固定输出空字符串，不读取表级 `Comment`
- `column-alias` 读取自列 JSON 的 `Alias`，如果缺失则回退到列 `Name`
- `app_info` 读取自命令行参数 `--app_info`
- 校验样例：`https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample/blob/master/Tables/new_table_%E8%A1%A8%E5%88%AB%E5%90%8D_.json`

## Markdown 输出

- `entities/entity-{实体名}.md`：单个实体的字段与关系
- `index.md`：项目总览，包含 `Entities`、`Bindings` 和 `ServerCommands` 摘要
- `servercommands/sc-{服务端命令名}.md`：单个服务端命令详情
- `bindings/binding-{页面名}.md`：单个页面的 `candidatesbindings` 和 `tablebindings` 汇总

`index.md` 中会保留三类摘要信息：

- `Entities`：数量、目录、命名规则、完整实体名列表
- `Bindings`：页面数量、目录、命名规则、完整页面名列表
- `ServerCommands`：数量、目录、命名规则、完整命令名列表

## 规则说明

### 候选项绑定

会扫描页面上的：

- `RadioGroupCellType`
- `CheckBoxGroupCellType`
- `DropDownListCellType`

字段映射规则：

- `ValueColumnBindingInfo` 输出为 `column-type: "ID"`
- `DisplayColumnBindingInfo` 输出为 `column-type: "text"`

### 表格绑定

识别规则：

1. 在 `AttachInfos` 中查找包含 `ListViewInfo` 的单元格，作为表格锚点。
2. 读取 `ListViewInfo.Name`、`TableName`、`RowIndex`、`ColumnIndex`、`RowCount`、`ColumnCount`。
3. 在表格区域内查找带 `BindingInfo` 的单元格。
4. 只收集与当前 `ListViewInfo.TableName` 相同的绑定列。

### 服务端命令扫描模式

- `all`：扫描 `ServerCommands/**/*.json` 下的全部服务端命令
- `whitelist`：仅保留备注中包含 `[HOB_INCLUDE]` 的命令
- `blacklist`：排除备注中包含 `[HOB_EXCLUDE]` 的命令
- 服务端命令备注读取自 `Description`

## 示例文件

- [output-sample/ontology.json](./output-sample/ontology.json)
- [output-sample/entities/entity-answer.md](./output-sample/entities/entity-answer.md)
- [output-sample/index.md](./output-sample/index.md)
- [output-sample/servercommands/sc-CreatPaper.md](./output-sample/servercommands/sc-CreatPaper.md)
- [output-sample/bindings/binding-页面1.md](./output-sample/bindings/binding-页面1.md)

## 校验

```bash
npm run check
npm run build
npm pack --dry-run
```