# 前后端连接指南

## 前端配置方式

### 1. 环境变量配置（推荐）

前端项目使用 `.env` 文件配置后端地址：

```bash
# OpenCodeUI/.env
VITE_API_BASE_URL=http://localhost:8000
```

### 2. 修改位置

前端项目中的 API 地址配置文件：
- **文件路径**: `OpenCodeUI/src/constants/api.ts`
- **配置项**: `API_BASE_URL`

```typescript
export const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || 'http://127.0.0.1:4096'
```

## 添加项目创建接口到前端

### 步骤 1: 创建 API 调用函数

在 `OpenCodeUI/src/api/` 目录下创建 `project.ts`:

```typescript
// OpenCodeUI/src/api/project.ts

import { getApiBaseUrl, getAuthHeader } from './http'

export interface ProjectCreateRequest {
  project_name: string
}

export interface ProjectCreateResponse {
  success: boolean
  message: string
  project_path: string
}

/**
 * 创建新项目
 * POST /fs/project/create
 */
export async function createProject(
  params: ProjectCreateRequest
): Promise<ProjectCreateResponse> {
  const baseUrl = getApiBaseUrl()
  const url = `${baseUrl}/fs/project/create`

  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      ...getAuthHeader(),
    },
    body: JSON.stringify(params),
  })

  if (!response.ok) {
    const error = await response.json().catch(() => ({ detail: '请求失败' }))
    throw new Error(error.detail || response.statusText)
  }

  return response.json()
}
```

### 步骤 2: 在 React 组件中使用

```tsx
// OpenCodeUI/src/components/ProjectCreate.tsx

import React, { useState } from 'react'
import { createProject } from '@/api/project'

export function ProjectCreate() {
  const [projectName, setProjectName] = useState('')
  const [loading, setLoading] = useState(false)
  const [error, setError] = useState('')

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault()
    setLoading(true)
    setError('')

    try {
      const result = await createProject({ project_name: projectName })
      alert(result.message)
      setProjectName('')
    } catch (err) {
      setError(err instanceof Error ? err.message : '创建失败')
    } finally {
      setLoading(false)
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={projectName}
        onChange={(e) => setProjectName(e.target.value)}
        placeholder="输入项目名称"
      />
      <button type="submit" disabled={loading}>
        {loading ? '创建中...' : '创建项目'}
      </button>
      {error && <p style={{ color: 'red' }}>{error}</p>}
    </form>
  )
}
```

## 本地开发联调

### 1. 启动后端服务

```bash
cd OpenCode-backend
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

### 2. 启动前端开发服务器

```bash
cd OpenCodeUI
# 确保 .env 文件中配置了正确的后端地址
echo "VITE_API_BASE_URL=http://localhost:8000" > .env.local
npm install
npm run dev
```

### 3. 跨域配置（如需要）

后端已配置 CORS，允许所有来源访问。如需限制，修改：

```python
# OpenCode-backend/app/core/config.py
class Settings(BaseSettings):
    CORS_ORIGINS: List[str] = ["http://localhost:5173", "http://127.0.0.1:5173"]
```

## API 接口列表

| 接口 | 方法 | 地址 | 描述 |
|------|------|------|------|
| 创建项目 | POST | `/fs/project/create` | 创建新项目目录 |
| 健康检查 | GET | `/` | 服务状态检查 |

## 请求示例

### cURL

```bash
curl -X POST "http://localhost:8000/fs/project/create" \
  -H "Content-Type: application/json" \
  -d '{"project_name": "my_project"}'
```

### 成功响应

```json
{
  "success": true,
  "message": "项目 'my_project' 创建成功",
  "project_path": "/root/workspace/my_project"
}
```

### 错误响应

```json
{
  "detail": "项目名称仅允许包含中英文、数字、下划线、横杠"
}
```

## 安全说明

1. **路径安全**: 后端已锁定所有文件操作在 `/root/workspace` 目录内
2. **输入校验**: 项目名经过正则校验，禁止路径逃逸字符
3. **CORS**: 生产环境建议配置具体的允许来源