DevFlow/docs/02-架构设计/构想审查/前后端类型对齐-2026-06-12.md

前后端类型对齐

创建: 2026-06-10 | 状态: 初稿

---

实施状态(2026-06-18 核对)

本设计文档已大面积过时，正文枚举表不再反映真实代码。 以下为实际落地形态(以 crates/df-types/src/types.rs 为准)：

类型契约机制 — 未采用 ts-rs 代码生成，仍手写 types.ts：

• ts-rs 依赖：Cargo.lock 0 处、crates/df-types/Cargo.toml 无 ts-rs 依赖、全 crate 无 build.rs、无 #[ts_rs]/#[derive(TS)] 标注。memory「未做/手写 types.ts」属实。
• 前端类型手维护：src/api/types.ts:1 注释「TypeScript 类型定义 — 与 Rust Record 结构体严格对齐」。
• 「ts-rs 代码生成」仍列在 todo：docs/todo.md:122(ARC-260615-07 架构清理项之一)。

Crate 重命名 — df-core 改名 df-types 已完成：

• workspace 下无 crates/df-core 目录(ls 核验 "df-core NOT FOUND")；类型定义现居 crates/df-types/src/{types.rs,events.rs,error.rs,lib.rs}。
• 正文出现的 df-core/src/types.rs 路径全部应读作 crates/df-types/src/types.rs。

枚举对齐 — 正文 PascalCase 表全部过时，实际为 snake_case 序列化 + 枚举值数已变：

• 正文写 #[serde] PascalCase "Created" 字符串值；实际 crates/df-types/src/types.rs:51/89/130/195/233 全部 #[serde(rename_all = "snake_case")]，前端/DB 存小写 snake_case。
• TaskStatus：正文 6 值(Created/BranchCreated/InProgress/ReviewReady/Merged/Abandoned) → 实际 7 值(types.rs:131-146)：todo / in_progress / in_review / testing / done / blocked / cancelled。正文 6 个枚举名已无一存在。前端 7 态对齐见 src/constants/project.ts:55(D-260616-01)。
• IdeaStatus：正文 8 值(Draft/Evaluating/Scored/Hot/Promoted/Parked/Merged/Discarded) → 实际 6 值(types.rs:52-65)：draft / pending_review / approved / rejected / promoted / archived。正文 8 个枚举名已无一存在。
• ProjectStatus：正文 4 值(Active/Paused/Completed/Archived) → 实际 7 值(types.rs:90-105)：planning / in_progress / testing / releasing / completed / paused / cancelled。
• WorkflowStatus(正文误标 "WorkflowRunStatus")：正文 6 值(Pending/Running/Paused/Completed/Failed/Cancelled) → 实际 6 值(types.rs:195-208)：pending / running / paused / completed / failed / cancelled(枚举名同正文，序列化改 snake_case，枚举名 WorkflowStatus 非 WorkflowRunStatus)。
• NodeStatus / BranchStatus / Priority 正文未列，实际见 types.rs:233-248 / 272-281 / 301-312。
• ID 类型：正文「所有 ID = UUID v4」与实际 types.rs:10-28 pub type XId = String + new_id() 一致(未漂移)。

校验能力追加：TaskStatus::is_valid / valid_values(types.rs:165-183)用于落库前拦截拼写错误(R-P1-5 修复)，正文未涉及。

原文以下设计正文保持不变，作为历史设计记录；当前真实枚举/类型契约形态以上方"实施状态"为准，查阅请直接读 crates/df-types/src/types.rs。

---

概述

DevFlow 前端 (TypeScript) 和后端 (Rust) 通过 Tauri IPC 和 JSON 序列化通信。两侧的类型定义必须保持一致。

类型映射

基础类型

Rust	TypeScript	说明
String	string	文本字段
i64	number	时间戳 (Unix timestamp)
Option<String>	string | null	可空字段
Vec<String>	string[]	数组 (JSON 序列化)
bool	boolean	布尔值

ID 类型

实体	Rust	TypeScript	格式
所有 ID	String	string	UUID v4

所有 ID 统一使用 UUID v4 字符串，便于前后端传递。

枚举对齐

IdeaStatus (8 值)

Rust	TypeScript
Draft	"Draft"
Evaluating	"Evaluating"
Scored	"Scored"
Hot	"Hot"
Promoted	"Promoted"
Parked	"Parked"
Merged	"Merged"
Discarded	"Discarded"

TaskStatus (6 值)

Rust	TypeScript
Created	"Created"
BranchCreated	"BranchCreated"
InProgress	"InProgress"
ReviewReady	"ReviewReady"
Merged	"Merged"
Abandoned	"Abandoned"

WorkflowRunStatus (6 值)

Rust	TypeScript
Pending	"Pending"
Running	"Running"
Paused	"Paused"
Completed	"Completed"
Failed	"Failed"
Cancelled	"Cancelled"

ProjectStatus (4 值)

Rust	TypeScript
Active	"Active"
Paused	"Paused"
Completed	"Completed"
Archived	"Archived"

约定

1. 枚举值使用 PascalCase 字符串，前后端保持一致
2. JSON 字段（如 scores、tags）在 Rust 侧用 TEXT 存储 JSON 字符串，前端解析为对象/数组
3. 时间字段统一用 i64 (Unix timestamp)，前端用 new Date(ts * 1000) 转换
4. 新增枚举值时，Rust 和 TypeScript 两侧必须同步更新