合约与检查

了解由源码管理的合约，以及保障 Lenso 团队与 Agent 安全协作的本地检查。

Lenso 的重要边界都有显式合约和可执行检查，因此团队与 Agent 不必只靠约定推断系统。

如果只是使用 API 而不是修改它，请从 API 参考开始。

已提交的合约

当前已提交的合约面刻意保持精简：

合约	使用方
`contracts/openapi/app-api.v1.yaml`	API 客户端、SDK 生成、Lenso Console API 期望
`contracts/errors/error-response.v1.schema.json`	RFC 9457 Problem Details 消费方（`application/problem+json`）
`contracts/services/lenso-service.v2.schema.json`	Service 与其提供的 Module 拓扑
`contracts/services/support-grpc.v1.proto`	Service 自有 gRPC API 示例

Rust 路由注解和平台 Schema 是事实来源。生成产物会一并提交，让下游使用方可以依赖稳定文件。

ErrorResponse 仍是已提交的 Schema 名称。HTTP 失败响应直接使用其顶层 Problem Details 字段；客户端不应期待嵌套的 error Wrapper。

路由事实来源

HTTP 路由应该将实现和 OpenAPI 元数据放在一起：

use lenso::host::http::{Json, UserActor};
use serde::{Deserialize, Serialize};
use utoipa::ToSchema;

#[derive(Deserialize, ToSchema)]
pub struct CreateTicketRequest {
    pub title: String,
    pub requester_email: String,
}

#[derive(Serialize, ToSchema)]
pub struct TicketResponse {
    pub id: String,
    pub status: String,
}

#[utoipa::path(
    post,
    path = "/v1/support/tickets",
    operation_id = "support_create_ticket",
    tag = "support",
    request_body = CreateTicketRequest,
    responses((status = 200, body = TicketResponse))
)]
pub async fn create_ticket(
    _actor: UserActor,
    Json(request): Json<CreateTicketRequest>,
) -> Json<TicketResponse> {
    Json(TicketResponse {
        id: format!("ticket:{}", request.title),
        status: "open".to_owned(),
    })
}

如果希望运维人员看到路由元数据、Story 标题与 Capability 要求，仍需在 Module Manifest 中声明该路由。

本地门禁

选择足以证明本次变更的最小门禁：

变更	门禁
Rust 代码	`just check`
OpenAPI 或生成的 Schema	`just generated-check`
Module 边界或合约布局	`just arch-check`
候选版本	`just release-check`
Lenso Console Package	在 `lenso-console` 中运行 `pnpm check`
文档网站	在 `lenso-site` 中运行 `pnpm check`

对于公开发布，仅本地检查通过还不够。还应验证用户实际安装的 Crate、npm Package、GitHub Release 或 Workflow Artifact。

架构护栏

just arch-check 用来守住 Module 架构中容易被意外破坏的边界：

缺少提交的 OpenAPI 工件
陈旧的生成合约工件
缺少当前事件的事件有效负载合约
Module 源码内部的跨 Module Import
Module Crate 内出现 api、application、domain 或 infrastructure 等 DDD 目录漂移

目标不是增加流程，而是在架构漂移演变成团队只能靠记忆维护的隐式规则前将其拦截。

Agent 变更清单

Agent 修改 Lenso 时，请按以下形式检查变更与可见状态：

Changed:
- module manifest
- linked route
- business operation

Checks:
- cargo check --bins
- just generated-check

Lenso Console:
- module appears in Modules
- receipt-bound Surface appears under the Module
- generated client calls the declared business operation through Surface Gateway
- story contains the business operation

如果变更应该出现在 Lenso Console 中，仅通过编译检查并不足够。

不要手动编辑生成的文件

生成合约会纳入源码管理，但不应手工编写。请先修改 Rust 路由注解、平台 Schema 或 Proto 源文件，再重新生成：

just generate-contracts
just generated-check

同时提交源文件变更与生成差异。