# terra_graph

**Repository Path**: waidais/terra_graph

## Basic Information

- **Project Name**: terra_graph
- **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-27
- **Last Updated**: 2026-04-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Pipeline World Map Workbench 1.0 (MVP)

> 本工程为纯 AI 实现的 MVP 原型。README 默认使用中文维护。

Pipeline World Map Workbench 是一个本地优先的分层世界地图工作台，用于生成、查看、查询、补丁编辑和持久化地图。Rust 后端负责地图模型、Pipeline 执行、存储和 HTTP API；Vite/React 前端提供浏览器交互界面。

## 目录结构

- `crates/worldgen-profile`：共享地图 profile/schema 类型。
- `crates/worldgen-core`：地图模型、Pipeline pass、生成器预设、查询/补丁逻辑和存储格式。
- `crates/worldgen-scripting`：基于 Rhai 的脚本型 Pipeline pass 支持。
- `crates/worldgen-server`：Axum HTTP 服务和进程内应用状态。
- `worldgen-web`：Vite + React 前端。
- `profiles/default`：默认 profile 和 pipeline 示例配置。
- `maps_test_it`：集成测试使用的小型目录格式地图 fixture。

## 环境要求

- 支持 Rust edition 2024 的 Rust 工具链。
- 用于前端开发的 Node.js 和 npm。

## 运行

1. 启动后端：
   - `cargo run -p worldgen-server`
2. 启动前端：
   - `cd worldgen-web`
   - `npm install`
   - `npm run dev`
3. 打开终端中 Vite 输出的开发服务器地址。

前端当前默认访问 `http://127.0.0.1:3000`。

## 构建与测试

- Rust 工作区测试：`cargo test`
- 仅测试后端：`cargo test -p worldgen-server`
- 前端生产构建：
  - `cd worldgen-web`
  - `npm run build`

目前还没有前端测试脚本。

## 最小演示流程

1. 在 Web UI 中创建一个地图 ID，例如 `demo-map`。
2. 点击 `运行 Pipeline` 执行当前 Pipeline。
3. 在图层列表中切换图层。
4. 在查询面板运行 `AreaSummary` 查询。
5. 在补丁编辑器中应用 patch。
6. 在底部面板查看 pass reports。
7. 通过 IO 控件保存或加载地图。

## 存储格式

地图可以保存为目录项目，也可以导出为 `.tg` 归档。目录格式会分别保存项目元数据、profile、pipeline 配置、source fields 和 derived cache。

典型目录文件包括：

- `project.json`
- `profile.json`
- `pipeline.json`
- `fields/`
- `derived_cache/`

Runtime overlay 默认不会持久化，除非保存或导出请求明确要求包含 overlay。

## API 说明

常用接口包括：

- `POST /api/maps/create`
- `GET /api/maps/:id/summary`
- `POST /api/maps/:id/pipeline/run`
- `POST /api/maps/:id/query`
- `POST /api/maps/:id/patch/apply`
- `POST /api/maps/:id/save`
- `POST /api/maps/:id/open`

当前 MVP 中，服务端把地图记录保存在进程内存中。重启服务会清空未保存状态，因此关闭服务前需要先保存地图。

## 当前 MVP 边界

- 应用状态是进程本地状态，并由单个 mutex 保护。
- Web API 基址目前硬编码在前端中。
- CORS 使用适合本地开发的宽松配置。
- CI 和前端测试尚未配置。