111 lines
5.0 KiB
Markdown
111 lines
5.0 KiB
Markdown
# 前后端类型对齐
|
||
|
||
> 创建: 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 两侧必须同步更新
|