Safe OS UI - API Gateway 路由转发规则文档

本系统包含多个独立的后端AI服务（规划系统、开发平台、质量门禁等）。为了使前端统一指向单一入口并简化跨域和请求分发配置，建议使用 API Gateway 进行统一路由和负载均衡。

以下是当前前端所有与后端服务交互的接口清单以及转发规则。Gateway 服务需要解析相应的路径前缀（Ingress Prefix），将请求 Rewrite 后转发至对应的内部后端服务。

整体架构与入口规则

统一入口 URL：http://<api-gateway-host>:<port> （前端将所有 API 请求指向此地址）
核心路由匹配策略：基于 URL前缀进行正则匹配或前缀匹配。

业务模块	Ingress Prefix (外部路径)	Forward Target (内部服务地址)	Rewrite Rule (路径重写规则)
Planning System	`/planning-api/*`	`http://localhost:8090`	`/planning-api/(.*)` ➔ `/api/$1`
DevOps System	`/devops-api/*`	`http://localhost:8000`	`/devops-api/(.*)` ➔ `/$1`
Quality Gate System	`/quality-api/*`	`http://localhost:5000`	`/quality-api/(.*)` ➔ `/api/$1`

1. 规划子系统接口 (Planning System)

底层服务: http://localhost:8090 前缀重写规则：请求至统一入口 .../planning-api/X 会被转发至内部的 .../api/X。

方法	外部暴露路径 (Gateway URL)	内部转发路径 (Target URL)	接口描述
`POST`	`/planning-api/chat/stream`	`/api/chat/stream`	铁三角 Agent：发送大系统规划/史诗业务需求内容（SSE流式数据返回）
`POST`	`/planning-api/upload`	`/api/upload`	文档上传：支持用户上传附件作为系统知识或输入来源

2. 研发自动引擎接口 (DevOps System)

底层服务: http://localhost:8000 前缀重写规则：请求至统一入口 .../devops-api/X 会被去掉前缀，转为后端的 .../X。该系统重度依赖SSE (Server-Sent Events) 流式连接，请在Gateway配置中确保不会缓冲或阻断流数据。

方法	外部暴露路径 (Gateway URL)	内部转发路径 (Target URL)	接口描述
`POST`	`/devops-api/session/start`	`/session/start`	新建研发自动化任务会话 (Session)
`POST`	`/devops-api/session/{sessionId}/clarify`	`/session/{sessionId}/clarify`	基于需求说明进行需求澄清和补充
`GET`	`/devops-api/session/{sessionId}/pm/stream`	`/session/{sessionId}/pm/stream`	PM角色执行需求细化分析流程 (SSE流)
`GET`	`/devops-api/session/{sessionId}/pm/refine/stream`	`/session/{sessionId}/pm/refine/stream`	追加PM反馈，继续流式提炼需求 (SSE流)
`GET`	`/devops-api/session/{sessionId}/qa/stream`	`/session/{sessionId}/qa/stream`	QA角色基于需求生成测试用例并执行评估 (SSE流)
`GET`	`/devops-api/session/{sessionId}/qa/refine/stream`	`/session/{sessionId}/qa/refine/stream`	追加QA用例反馈并更新测试集 (SSE流)
`GET`	`/devops-api/session/{sessionId}/dev/stream`	`/session/{sessionId}/dev/stream`	核心编码过程：依据需求、架构与测试生成最终业务/Java等工程代码 (SSE流)
`POST`	`/devops-api/session/{sessionId}/test/run`	`/session/{sessionId}/test/run`	运行集成编译与单元/端到端测试并获取结果
`GET`	`/devops-api/session/{sessionId}/test/fix/stream`	`/session/{sessionId}/test/fix/stream`	针对测试错误进行的AI代码自动修复 (SSE流)

注意： {sessionId} 属于路径层级中的动态参数，具体网关转发时使用泛类型或通配符放行。

3. 代码质量门禁接口 (Quality Gate)

底层服务: http://localhost:5000 前缀重写规则：请求至统一入口 .../quality-api/X 会被转发至后端内部的 .../api/X。

方法	外部暴露路径 (Gateway URL)	内部转发路径 (Target URL)	接口描述
`GET`	`/quality-api/prs`	`/api/prs`	获取 PR 扫描工单列表（支持多种查询参数）
`GET`	`/quality-api/prs/history`	`/api/prs/history`	获取 PR 处理历史，用于趋势看板 (e.g., `?limit=15`)
`GET`	`/quality-api/prs/{prId}`	`/api/prs/{prId}`	获取某一条指定 PR 扫描记录的详细执行状态及摘要
`GET`	`/quality-api/prs/{prId}/files`	`/api/prs/{prId}/files`	拉取这条 PR 的被影响/改动的文件目录结构
`GET`	`/quality-api/prs/{prId}/file`	`/api/prs/{prId}/file`	获取PR里指定文件的 Diff 对象（包含行内审查反馈），附带 `?path=xxx` 查询参数
`POST`	`/quality-api/prs/{prId}/merge`	`/api/prs/{prId}/merge`	在门禁界面确认问题修缮无误后，合并该次 PR
`POST`	`/quality-api/prs/{prId}/close`	`/api/prs/{prId}/close`	门禁审查不通过，拒绝/关闭此条扫描和合并申请

Nginx Gateway 配置示例 (参考)

如果网关选用 Nginx，可快速参考如下配置来完成上述 Rewrite 与 Proxy：

server {
    listen 80;
    server_name api-gateway.safe-os.local;

    # 1. Planning API 转发
    location /planning-api/ {
        # 截取 /planning-api/ 后的内容，拼接到 /api/
        rewrite ^/planning-api/(.*)$ /api/$1 break;
        proxy_pass http://localhost:8090;
        
        # 启用流连接所需的头信息
        proxy_set_header Connection '';
        proxy_http_version 1.1;
        chunked_transfer_encoding off;
        proxy_buffering off;
        proxy_cache off;
    }

    # 2. DevOps API 转发
    location /devops-api/ {
        # 截取 /devops-api/ 后的内容，直接拼接
        rewrite ^/devops-api/(.*)$ /$1 break;
        proxy_pass http://localhost:8000;

        # 支撑 SSE (Server-Sent Events) 的流配置
        proxy_set_header Connection '';
        proxy_http_version 1.1;
        chunked_transfer_encoding off;
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 3600s; # 考虑大模型生成代码时间较长
    }

    # 3. Quality Gate API 转发
    location /quality-api/ {
        # 截取 /quality-api/ 后的内容，拼接到 /api/
        rewrite ^/quality-api/(.*)$ /api/$1 break;
        proxy_pass http://localhost:5000;
    }
}

以上文档即针对前端当前服务现状所整理的 API Gateway 路由规划规范，您可以直接根据此规范开发 API Gateway 或调整 Nginx 等负载均衡器的配置。

6.4 KiB Raw Blame History Unescape Escape