隐式契约防御

两段代码假设了同一件事，但没有机制保证一致。改了一处，另一处静默腐坏。这就是隐式契约。

适用：前端（任意）+ Rust + SeaORM + 数据库（任意）

架构：隔离仓（外壳）/ 内壳

┌─────────────────────────────────────────────┐
│  隔离仓（外壳）— 所有跨边界交互在此收敛      │
│                                             │
│  ┌─────────────┐  ┌────────┐  ┌──────────┐ │
│  │ contracts   │  │ consts │  │ entity/  │ │
│  │ (API 类型)  │  │ (常量) │  │ (数据表) │ │
│  └─────────────┘  └────────┘  └──────────┘ │
├─────────────────────────────────────────────┤
│  内壳 — 纯 Rust 业务逻辑                     │
│  只引用隔离仓的类型和常量，不碰外部数据       │
└─────────────────────────────────────────────┘

分区一：API 契约（contracts.rs）

后端有且仅有一个文件定义所有与前端交互的请求/响应结构体。

• 所有 #[ts(export)] 只允许出现在此文件
• API 边界用到的枚举也定义在此文件
• 前端类型由 gen_types.sh 自动生成（cargo test → ts-rs 导出 → 合并到前端指定路径），禁止手动修改

// contracts.rs
use serde::{Deserialize, Serialize};
use ts_rs::TS;

#[derive(Serialize, Deserialize, TS)]
#[ts(export)]
pub struct CreateTaskRequest {
    pub title: String,
    pub prompt: String,
    pub agent_type: AgentType,
}

#[derive(Serialize, Deserialize, TS)]
#[ts(export)]
pub struct TaskResponse {
    pub id: String,
    pub status: TaskStatus,
    pub created_at: String,
}

分区二：常量（consts.rs）

有且仅有一个文件集中定义所有业务常量。true/false/0/1 除外，其余字面量都算魔法值。

• 能用 enum 穷举的优先 enum，不用常量
• 路径/文件名用 struct 方法封装，不用字符串常量

// consts.rs
pub const DEFAULT_TIMEOUT_MS: u64 = 5000;
pub const MAX_ROUNDS: usize = 3;
pub const DEFAULT_PAGE_SIZE: usize = 20;

分区三：数据库实体（entity/*.rs）

一个文件完全表达一张表。打开 entity 文件就能知道表的一切，无需连数据库、无需看 DDL。

类型映射

状态枚举带流转检查

有状态流转的枚举必须实现 can_transition_to()，状态变更前必须调用：

#[derive(Clone, Debug, PartialEq, Eq, EnumIter, DeriveActiveEnum, Serialize, Deserialize)]
#[sea_orm(rs_type = "String", db_type = "String(StringLen::N(20))")]
pub enum TaskStatus {
    #[sea_orm(string_value = "pending")]
    Pending,
    #[sea_orm(string_value = "running")]
    Running,
    #[sea_orm(string_value = "success")]
    Success,
    #[sea_orm(string_value = "failed")]
    Failed,
}

impl TaskStatus {
    pub fn can_transition_to(&self, next: &TaskStatus) -> bool {
        matches!((self, next),
            (Self::Pending, Self::Running)
            | (Self::Running, Self::Success)
            | (Self::Running, Self::Failed)
            | (Self::Failed, Self::Pending)
        )
    }
}

Entity 文件要求

• 文件级 //! doc comment（业务规则、状态流转、关联关系）
• 每个字段 /// 注释（业务含义，不是字段名复述）
• 使用 SeaORM Entity First 自动建表，不手写 migration
• 跨表操作用事务（db.transaction）
• 软删除表查询过滤 is_deleted

Entity 示例

//! # tasks 表 — 编码任务
//!
//! ## 业务规则
//! - 一个 task 对应一次容器执行，容器内 agent 自主完成编码
//! - prompt 是用户提交的原始需求，不可修改；执行中的补充指令走 exec_plan
//! - rounds_used 由 entrypoint wrapper 回报，不由业务代码直接写入
//!
//! ## 状态流转
//! Pending → Running → Success/Failed，Failed → Pending（重试）
//! cancel 操作：Running → Cancelled（需 kill 容器）
//!
//! ## 关联
//! - container_id 关联 Docker/Podman 容器（逻辑外键，不建物理外键）
//! - 未来 Phase 2 会关联 projects 表
//!
//! ## 软删除
//! 此表使用软删除（is_deleted），查询活跃记录必须过滤

use sea_orm::entity::prelude::*;
use serde::{Deserialize, Serialize};

#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel, Serialize, Deserialize)]
#[sea_orm(table_name = "tasks")]
pub struct Model {
    /// 主键 UUID，由后端生成
    #[sea_orm(primary_key, auto_increment = false)]
    pub id: String,

    /// 任务标题，用于列表展示
    pub title: String,

    /// 用户提交的原始 prompt，创建后不可修改
    #[sea_orm(column_type = "Text")]
    pub prompt: String,

    /// 任务状态，变更前必须调用 TaskStatus::can_transition_to()
    #[sea_orm(default_value = "pending")]
    pub status: TaskStatus,

    /// agent 实际执行的轮次数，由 entrypoint wrapper 的 report.json 回填
    #[sea_orm(default_value = 0)]
    pub rounds_used: i32,

    /// 软删除标记，false=活跃，true=已删除
    #[sea_orm(default_value = false)]
    pub is_deleted: bool,

    /// 创建时间 UTC
    pub created_at: DateTimeUtc,

    /// 完成时间 UTC，任务结束（成功/失败/取消）时写入
    pub finished_at: Option<DateTimeUtc>,
}

#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
pub enum Relation {}
impl ActiveModelBehavior for ActiveModel {}

内壳规则

隔离仓之外的 Rust 代码：

1. 所有外部数据（用户输入、LLM 输出、API 返回、容器产出）在入口处立即 serde 反序列化到强类型，失败即 Error
2. 引用 consts.rs 的常量或 enum 变体，不内联字面量
3. 通过 SeaORM Entity/ActiveModel 操作数据库，不写裸 SQL

并发

优先消灭共享可变状态：单线程 event loop > Actor 模型（tokio channel）> 不可变数据 + 消息传递。避免在业务代码中用 Mutex/RwLock。

演化

改类型定义 → 编译器报错 → 逐个修复 → 全部通过。改 contracts.rs → 重新 gen_types.sh → 前端编译报错 → 修复。隔离仓的价值：把变更传播交给编译器。

脚本

脚本顶部有 CONFIG 区域，agent 根据项目实际路径修改。

Agent 行动指南

初始化：创建 contracts.rs + consts.rs + entity/ 目录，将两个脚本放入项目并配置路径，Cargo.toml 加 ts-rs 依赖。

开发：新增 API → 先在 contracts.rs 定义类型 → 再写逻辑。新增表 → 先写 entity 文件。新增常量 → 加到 consts.rs。每次改完跑 check_contracts.sh。

先看 entity 文件了解数据表，一个文件 = 一张表的全部信息。