名称：添加端点描述：向 Catalyst-Relay 服务器添加新的 HTTP 端点。在创建路由、API 端点或 HTTP 处理器时使用。

添加 HTTP 端点

何时使用

创建新的 HTTP 路由
添加 API 端点
将新的处理器连接到 Hono 应用

路由文件模式

每个端点都有其独立的文件，其中包含共置的模式、类型和处理器。

位置： src/server/routes/{类别}/{端点}.ts

// src/server/routes/auth/login.ts

import { z } from 'zod';
import type { Context } from 'hono';
import type { ISessionManager } from '../types';

// 1. 请求模式（共置）
export const loginRequestSchema = z.object({
    url: z.string().url(),
    client: z.string().min(1).max(3),
    auth: authConfigSchema
});

// 2. 响应类型（共置）
export interface LoginResponse {
    sessionId: string;
    username: string;
    expiresAt: number;
}

// 3. 单个处理器导出（工厂模式）
export function loginHandler(sessionManager: ISessionManager) {
    return async (c: Context) => {
        const body = await c.req.json();
        const validation = loginRequestSchema.safeParse(body);

        if (!validation.success) {
            return c.json({
                success: false as const,
                error: '无效请求',
                code: 'VALIDATION_ERROR'
            }, 400);
        }

        // ... 实现 ...

        return c.json({ success: true as const, data: response });
    };
}

连接路由

在 src/server/routes/index.ts 中注册路由：

import { loginHandler } from './auth/login';

export function registerRoutes(app: Hono, sessionManager: ISessionManager) {
    // 认证路由
    app.post('/login', loginHandler(sessionManager));

    // 在此添加您的新路由
}

响应格式

所有端点都使用一致的封装格式：

// 成功
return c.json({ success: true as const, data: result });

// 错误
return c.json({
    success: false as const,
    error: '人类可读的消息',
    code: '机器代码'
}, statusCode);

对判别联合中的字面量类型使用 as const。

库模式映射

如果端点封装了核心功能，请向 ADTClient 添加一个方法：

HTTP 端点	库方法
`POST /login`	`client.login()`
`GET /packages`	`client.getPackages()`
`POST /objects/read`	`client.read(objects)`

文档要求

在 docs/endpoints/{类别}.md 中创建端点文档。

必需的结构：

标题和描述
## 章节 带锚链接的目录
每个端点：
- 描述段落
- 请求表（方法、路径、是否需要认证）
- 请求体表（字段、类型、是否必需、描述）
- 响应表（字段、类型、描述）
- 示例请求/响应 JSON
- 错误代码表
- 用例列表
- 库使用部分

完整示例请参见 docs/endpoints/auth.md。

检查清单

- [ ] 在 src/server/routes/{类别}/ 中创建路由文件
- [ ] 为请求验证添加 Zod 模式
- [ ] 添加响应类型接口
- [ ] 导出处理器函数（工厂模式）
- [ ] 在 src/server/routes/index.ts 中连接路由
- [ ] 如果适用，向 ADTClient 添加库方法
- [ ] 在 docs/endpoints/{类别}.md 中记录
- [ ] 运行类型检查：bun run typecheck

名称：添加端点 描述：向 Catalyst-Relay 服务器添加新的 HTTP 端点。在创建路由、API 端点或 HTTP 处理器时使用。