# 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：

```nginx
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 等负载均衡器的配置。