# 可链接自定义表单

**Repository Path**: marsdonne/linkable-custom-forms

## Basic Information

- **Project Name**: 可链接自定义表单
- **Description**: rust demo
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-25
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

***

# Linkable Custom Forms (LCF)

一个基于 Rust 和 GraphQL 的**可链接自定义表单**系统：表单结构可动态定义（9 种字段类型），实例数据按定义校验并提交，支持实例间引用关系。

## 来龙去脉

- **起源（Qwen Studio）**：这是作者学完《Rust 程序设计语言》后的第一个实战项目。整体架构——Cargo Workspace 拆分、JSONB 动态字段存储、DataLoader 批量加载、状态机设计——最初在 **Qwen Studio**（`qwen3.7-plus`）中设计完成，完整会话见 [qwen-chat-export-1783302757959.json](./qwen-chat-export-1783302757959.json)，[会话链接](https://chat.qwen.ai/s/a8e6562b-5730-4592-aa54-4ccc46613a0b?fev=0.2.68)。
- **深化（mattpocock-skills）**：后续迭代借助 **mattpocock-skills** 技能集（`grill-with-docs` / `improve-codebase-architecture` / `ask-matt` 等）驱动——游标分页约定、fields 按需加载、字段类型映射补齐、演示前端。开发过程在仓库内留有完整痕迹：`.scratch/`（本地 issue tracker 与 spec）、`docs/adr/`（决策记录 0001–0003）、各 crate 的 `CONTEXT.md`（领域词汇表）。
- **当前状态**：后端 API + 演示前端均已可用，见下方「运行」。

## 核心功能

1. **可链接实例 (Linkable Instances)**：表单实例间引用关系，通过 GraphQL DataLoader 批量加载，避免 N+1。
2. **游标分页 (Cursor Pagination)**：Relay 风格，Base64 微秒精度游标 + PostgreSQL `MIN/MAX` 边界判断，避免 `COUNT`。
3. **动态过滤 (Dynamic Filtering)**：JSONB `@>` 操作符，客户端可传任意 JSON 作为查询条件。
4. **按需加载 (Fields On-demand)**：`formDefinitions` 返回 interface 节点——公共字段直接取，字段集合（大 JSONB）仅在被请求时经 `look_ahead` 加载（列裁剪，ADR-0002）。
5. **9 种字段类型**：Text / TextArea / Number / Date / DateTime / Boolean / Select / MultiSelect / Reference，含配置校验。

## Workspace & Crates 依赖

```text
.
├── lcf-model/             # 领域模型层：实体、Repository trait、游标分页抽象（无依赖）
├── lcf-store-pgsql/       # 存储适配器：PostgreSQL + sqlx 实现   → 依赖 lcf-model
├── lcf-api-graphql/       # GraphQL 接口层：类型映射 + Resolver → 依赖 lcf-model, lcf-store-pgsql
├── lcf-server/            # 应用启动：Axum + CORS               → 依赖 lcf-api-graphql, lcf-store-pgsql
├── lcf-integration-tests/ # 端到端测试（Testcontainers PG）     → 依赖 lcf-server, lcf-store-pgsql
├── frontend/              # 演示前端：Vue 3 + Vite + Element Plus（纯 CSR）
│                          #   → 通过 GraphQL 访问 lcf-server（CORS 已放行）
├── docs/adr/              # 架构决策记录（0001–0003）
└── .scratch/              # 本地 issue tracker（feature spec + tickets）
```

**依赖流向**：`lcf-model`（无依赖）→ `lcf-store-pgsql` → `lcf-api-graphql` → `lcf-server` ← `frontend`（GraphQL）

## 技术栈

* **后端**：Rust 2024 Edition · async-graphql (Relay Connection) · sqlx + PostgreSQL · Testcontainers
* **前端**：Vue 3 · Vite · TypeScript · Element Plus（客户端渲染，无 SSR）

## 运行

```bash
# 1. 启动 PostgreSQL（示例：Docker，端口 5433）
docker run -d --name lcf-pg -e POSTGRES_PASSWORD=postgres -p 5433:5432 postgres:18.1

# 2. 后端（自动迁移，监听 :3000，GraphQL 端点 /graphql）
$env:DATABASE_URL="postgres://postgres:postgres@localhost:5433/postgres"
cargo run -p lcf-server

# 3. 演示前端（http://localhost:5173，含示例表单一键载入）
cd frontend && npm install && npm run dev
```