# modelBase

**Repository Path**: pei6/model-base

## Basic Information

- **Project Name**: modelBase
- **Description**: No description available
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-13
- **Last Updated**: 2026-03-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KCL 元模型工具

从 KCL 文件中提取元模型（Schema）、管理项目空间，并对基于元模型的实例数据做类 Git 的变更管理（commit / log / revert）。

## 项目总结

| 项目 | 说明 |
|------|------|
| **技术栈** | Java 21、Maven、Picocli、Jackson（JSON/YAML） |
| **已实现** | ① 从 KCL 提取元模型 ② 项目空间（init、kcl-project.yaml） ③ 实例数据变更管理（commit/log/revert） ④ 后端 HTTP 服务 ⑤ **前端 webClient**（Vue3+TS：空间管理、KCL 树、元模型展示、模型数据编辑与提交） |
| **交付物** | `mvn package` 生成 `target/kcl-meta.jar`（含依赖，可直接 `java -jar` 运行） |
| **文档** | 设计：`doc/design/kcl-meta-model-tool.md`；实现：`doc/implementation/kcl-meta-model-tool.md` |

## 要求

- JDK 21
- Maven 3.6+
- （可选）Git：用于管理本仓库代码；使用前在项目根目录执行 `git init`
- （可选）**KCL**：提交前 check 与 API `/api/check` 会调用 `kcl vet`。若 kcl 不在 PATH 中，可设置环境变量 **`KCL_HOME`** 指向 kcl 所在目录（如 `c:\tools`），程序会使用 `%KCL_HOME%\kcl.exe`（Windows）或 `$KCL_HOME/kcl`（Linux/macOS）

## 构建与运行

```bash
# 编译
mvn compile

# 测试
mvn test

# 打包（含依赖，生成 target/kcl-meta.jar）
mvn package

# 运行（需已配置 JAVA_HOME 与 PATH 或使用完整路径）
java -jar target/kcl-meta.jar <子命令> [选项]
```

**Windows 示例**（若 Maven/JDK 未在 PATH 中）：

```powershell
$env:JAVA_HOME = "C:\jdk-21.0.1"
$env:PATH = "C:\apache-maven-3.9.14\bin;C:\jdk-21.0.1\bin;$env:PATH"
cd c:\code
mvn -q package -DskipTests
java -jar target/kcl-meta.jar --help
```

## 使用说明

### 1. 提取元模型

从指定 KCL 文件提取所有 schema，输出为 YAML/JSON：

```bash
# 指定文件
java -jar target/kcl-meta.jar extract -f path/to/a.k -f path/to/b.k -o meta.yaml

# 从项目空间配置的 KCL 列表提取
java -jar target/kcl-meta.jar extract -p . -o meta.yaml
```

### 2. 项目空间

```bash
# 创建项目空间（当前目录）
java -jar target/kcl-meta.jar init .

# 指定路径与初始 KCL 文件
java -jar target/kcl-meta.jar init my-project -n my-app -f src/a.k -f src/b.k
```

项目空间内会生成 `kcl-project.yaml`，可编辑其中的 `kclFiles` 配置 KCL 文件列表。

### 3. 变更管理（实例数据）

在项目空间目录下执行：

```bash
# 提交当前实例数据（.kcl-model/current.yaml）为一次快照
java -jar target/kcl-meta.jar commit -m "描述"

# 查看提交历史
java -jar target/kcl-meta.jar log

# 回滚到指定提交
java -jar target/kcl-meta.jar revert <commit-id>
```

实例数据存放在项目空间下的 `.kcl-model/current.yaml`，可直接编辑该文件或通过其他工具按元模型结构写入；提交后会在 `.kcl-model/history/` 中保留每次快照。

### 4. 后端服务

以 HTTP 服务方式提供与 CLI 等价的 API，便于前端或其它服务调用：

```bash
# 启动服务（默认端口 8080）
java -jar target/kcl-meta.jar server

# 指定端口
java -jar target/kcl-meta.jar server -p 9090
```

| 接口 | 方法 | 说明 |
|------|------|------|
| `/health` | GET | 健康检查，返回 `{"status":"UP"}` |
| `/api/extract` | POST | 提取元模型；body: `{"projectPath":"."}` 全量，或 `{"projectPath":".","relativePaths":["a.k"]}` 指定文件，或 `{"files":["path/a.k"]}`；返回 `{"metaModels":[...]}` |
| `/api/project/init` | POST | 创建项目空间；body: `{"path":".","name":"x","kclFiles":[]}` |
| `/api/project` | GET | 获取项目配置；query: `path=...` |
| `/api/project/file` | GET | 读取项目内文件；query: `projectPath=...`、`relativePath=...`（如 `kcl-files.json`），返回 `{"content":"..."}` |
| `/api/commit` | POST | 提交；body: `{"projectPath":".","message":"说明"}`，返回 `{"commitId":"..."}` |
| `/api/log` | GET | 提交历史；query: `projectPath=...`，返回 `{"commits":[...]}` |
| `/api/revert` | POST | 回滚；body: `{"projectPath":".","commitId":"..."}` |
| `/api/current` | GET | 读取当前实例数据；query: `projectPath=...` |
| `/api/current` | PUT | 写入当前实例数据；body: `{"projectPath":".","data":{...}}` |

请求/响应均为 JSON；服务启用 CORS（`Access-Control-Allow-Origin: *`），便于浏览器前端调用。

### 5. 前端 webClient

在 `webClient/` 目录下为 Vue 3 + TypeScript 项目，提供：

- **项目空间管理**：创建、从列表移除、列表（持久化在 localStorage）；打开指定空间后进入工作区。
- **KCL 文件树**：从项目内 `kcl-files.json` 加载树形配置并展示；点击某 .k 文件后在右侧展示该文件提取出的元模型。
- **模型数据**：浏览/编辑当前实例数据（JSON）、保存到工作区、提交（commit）、历史（log）、回滚（revert）。

```bash
cd webClient && npm install && npm run dev
```

前端默认 http://localhost:5173，并代理 `/api` 到后端（需先启动 `java -jar target/kcl-meta.jar server`）。详见 `webClient/README.md`。

## 示例

- **sample/**：单文件示例 `User.k` 与 `kcl-files.json`，用于 CLI 或提取测试。
- **my-proj/A**：完整示例项目空间，含 5 个 KCL 文件（user/app/config/resource/network）及多种元模型、`kcl-files.json` 树形配置，可用于前端或后端联调。

## 文档

- 设计文档：`doc/design/kcl-meta-model-tool.md`
- 实现文档：`doc/implementation/kcl-meta-model-tool.md`
- 元模型与 KCL 概念：`doc/kcl-model.md`、`doc/meta-model.md`

## 代码管理

- 使用 Git 管理代码时，请在项目根目录执行 `git init`；若需忽略实例数据历史，可将 `.kcl-model/` 加入 `.gitignore`（当前未默认忽略，便于按需提交）。