ylhp-ai-project-manager/docs/frontend-sse-integration.md

SSE 前端对接文档

概述

本文档描述前端如何与后端 SSE (Server-Sent Events) 服务进行对接，实现异步任务的实时进度推送。

核心特性

• 用户绑定：SSE 通道通过 userId 绑定，一个用户只需建立一个连接
• 多业务复用：同一连接可接收多种业务类型的消息（项目初始化、系统通知等）
• 类型区分：通过消息中的 type 字段区分不同业务

---

消息格式

所有 SSE 消息采用统一格式：

{
  "type": "project-init",      // 业务类型
  "event": "progress",         // 事件名称
  "userId": "user_123",        // 用户ID
  "data": { ... },             // 业务数据
  "timestamp": "2024-01-01T10:00:00"
}

业务类型 (type)

类型	说明
project-init	项目初始化任务进度
system-notification	系统通知
task-notification	任务通知
system	系统事件（连接成功等）

事件名称 (event)

项目初始化 (type=project-init)

事件	说明	数据结构
submitted	任务已提交	{ taskId, message }
progress	进度更新	ProjectInitTaskVO
complete	任务完成	ProjectInitTaskVO
error	执行错误	{ error }

系统事件 (type=system)

事件	说明
connected	SSE 连接成功

---

对接步骤

1. 建立 SSE 连接

// 使用用户ID建立连接
const userId = 'user_123'; // 当前登录用户ID
const eventSource = new EventSource(`/api/v1/sse/connect/${userId}`);

// 监听连接成功事件
eventSource.addEventListener('connected', (e) => {
    const message = JSON.parse(e.data);
    console.log('SSE连接成功:', message);
    // { type: "system", event: "connected", userId: "user_123", data: {...} }
});

2. 监听业务消息

// 监听项目初始化进度
eventSource.addEventListener('progress', (e) => {
    const message = JSON.parse(e.data);
    
    // 根据 type 字段处理不同业务
    switch(message.type) {
        case 'project-init':
            handleProjectInitProgress(message.data);
            break;
        case 'system-notification':
            handleSystemNotification(message.data);
            break;
        case 'task-notification':
            handleTaskNotification(message.data);
            break;
    }
});

// 监听任务完成
eventSource.addEventListener('complete', (e) => {
    const message = JSON.parse(e.data);
    if (message.type === 'project-init') {
        console.log('项目初始化完成:', message.data);
        // data 包含完整的 ProjectInitTaskVO，包括 result 字段
    }
});

// 监听错误
eventSource.addEventListener('error', (e) => {
    const message = JSON.parse(e.data);
    console.error('任务执行错误:', message.data.error);
});

3. 提交项目初始化任务

async function submitProjectInitTask(file) {
    const formData = new FormData();
    formData.append('userId', userId);  // 必须与 SSE 连接时的 userId 一致
    formData.append('file', file);

    const response = await fetch('/api/v1/project-init/sse/submit-task', {
        method: 'POST',
        body: formData
    });

    const result = await response.json();
    
    if (result.code === 200) {
        console.log('任务提交成功:', result.data.taskId);
        // 进度将通过已建立的 SSE 连接推送
    } else {
        console.error('提交失败:', result.message);
    }
}

4. 关闭连接

// 页面卸载时关闭连接
window.addEventListener('beforeunload', () => {
    // 可选：调用后端关闭接口
    fetch(`/api/v1/sse/close/${userId}`, { method: 'POST' });
    eventSource.close();
});

---

完整示例

class SseClient {
    constructor(userId) {
        this.userId = userId;
        this.eventSource = null;
        this.listeners = new Map();
    }

    // 建立连接
    connect() {
        this.eventSource = new EventSource(`/api/v1/sse/connect/${this.userId}`);

        // 系统事件
        this.eventSource.addEventListener('connected', (e) => {
            console.log('SSE连接成功');
            this.emit('connected', JSON.parse(e.data));
        });

        // 项目初始化事件
        this.eventSource.addEventListener('submitted', (e) => {
            const msg = JSON.parse(e.data);
            if (msg.type === 'project-init') {
                this.emit('project-init-submitted', msg.data);
            }
        });

        this.eventSource.addEventListener('progress', (e) => {
            const msg = JSON.parse(e.data);
            if (msg.type === 'project-init') {
                this.emit('project-init-progress', msg.data);
            }
        });

        this.eventSource.addEventListener('complete', (e) => {
            const msg = JSON.parse(e.data);
            if (msg.type === 'project-init') {
                this.emit('project-init-complete', msg.data);
            }
        });

        this.eventSource.addEventListener('error', (e) => {
            const msg = JSON.parse(e.data);
            this.emit('error', msg.data);
        });
    }

    // 提交项目初始化任务
    async submitProjectInitTask(file) {
        const formData = new FormData();
        formData.append('userId', this.userId);
        formData.append('file', file);

        const response = await fetch('/api/v1/project-init/sse/submit-task', {
            method: 'POST',
            body: formData
        });

        return response.json();
    }

    // 事件监听
    on(event, callback) {
        if (!this.listeners.has(event)) {
            this.listeners.set(event, []);
        }
        this.listeners.get(event).push(callback);
    }

    emit(event, data) {
        const callbacks = this.listeners.get(event);
        if (callbacks) {
            callbacks.forEach(cb => cb(data));
        }
    }

    // 关闭连接
    close() {
        if (this.eventSource) {
            this.eventSource.close();
        }
    }
}

// 使用示例
const sseClient = new SseClient('user_123');

// 监听进度
sseClient.on('project-init-progress', (data) => {
    console.log(`进度: ${data.progress}%, ${data.progressMessage}`);
    // 更新进度条
});

sseClient.on('project-init-complete', (data) => {
    console.log('完成:', data.result);
    // 显示结果
});

// 建立连接
sseClient.connect();

// 提交任务
document.getElementById('uploadBtn').addEventListener('click', async () => {
    const file = document.getElementById('fileInput').files[0];
    const result = await sseClient.submitProjectInitTask(file);
    console.log('提交结果:', result);
});

---

数据结构

ProjectInitTaskVO

interface ProjectInitTaskVO {
    taskId: string;              // 任务ID
    status: string;              // 状态: pending/processing/completed/failed
    statusDesc: string;          // 状态描述
    progress: number;            // 进度百分比 (0-100)
    progressMessage: string;     // 进度描述
    originalFilename: string;    // 原始文件名
    createTime: string;          // 创建时间
    startTime: string;           // 开始时间
    completeTime: string;        // 完成时间
    result?: ProjectInitResult;  // 结果数据（完成时）
    errorMessage?: string;       // 错误信息（失败时）
}

进度阶段说明

进度	阶段	说明
0%	pending	任务已提交，等待处理
10%	processing	开始处理，正在上传文件
30%	processing	文件上传完成，读取内容
50%	processing	文件读取完成，AI分析中
60%	processing	AI解析项目结构
100%	completed	项目预览数据生成成功

---

错误处理

连接错误

eventSource.onerror = (error) => {
    console.error('SSE连接错误:', error);
    // 可尝试重连
};

提交任务错误

// HTTP 响应错误
if (response.code !== 200) {
    console.error('提交失败:', response.message);
    // 可能的错误：
    // - "上传文件不能为空"
    // - "用户未建立SSE连接，请先调用 /api/v1/sse/connect/{userId}"
}

// 任务执行错误（通过 SSE 推送）
eventSource.addEventListener('error', (e) => {
    const msg = JSON.parse(e.data);
    console.error('任务执行错误:', msg.data.error);
});

---

注意事项

1. 用户ID一致性：SSE 连接和提交任务时必须使用相同的 userId

2. 连接超时：默认 30 分钟超时，超时后需要重新建立连接

3. 单用户单连接：一个 userId 同时只能有一个 SSE 连接，新建连接会自动关闭旧连接

4. 文件大小限制：建议前端先做文件大小校验，避免上传过大文件

5. 重连机制：建议实现自动重连机制，当连接断开时自动重新建立连接

// 简单重连示例
function connectWithRetry(userId, maxRetries = 3) {
    let retries = 0;
    
    const connect = () => {
        const es = new EventSource(`/api/v1/sse/connect/${userId}`);
        
        es.onerror = (e) => {
            es.close();
            retries++;
            if (retries < maxRetries) {
                setTimeout(connect, 3000); // 3秒后重试
            }
        };
        
        return es;
    };
    
    return connect();
}