# 前后端分离开发架构

**我是卡若。**

当前项目已完成**前后端物理分离**：后端 soul-api（Go），管理端 soul-admin（React），C 端小程序。开发流程仍采用**接口契约驱动**。

## 1. 当前架构（已落地）

\`\`\`mermaid
graph LR
    subgraph "前端"
        Admin[soul-admin<br/>React+Vite]
        Mini[微信小程序]
    end
    
    subgraph "后端 soul-api (Go)"
        Gin[Gin Router /api/*]
        Handler[Handler 层]
        GORM[GORM]
        Gin --> Handler --> GORM
    end
    
    MySQL[(MySQL)]
    GORM --> MySQL
    
    Admin -->|VITE_API_BASE_URL + path| Gin
    Mini -->|baseUrl + path| Gin
\`\`\`

## 2. 分离开发流程

\`\`\`mermaid
sequenceDiagram
    participant Doc as API 文档
    participant FE as 前端 (soul-admin / 小程序)
    participant BE as 后端 (soul-api)
    
    Doc->>FE: 1. 接口定义 (URL、camelCase 字段)
    Doc->>BE: 1. 同上
    
    par 并行开发
        FE->>FE: 2. Mock 或对接已有 API
        FE->>FE: 3. UI 与交互，字段用 camelCase
        BE->>BE: 2. Handler + Model，json 标签 camelCase
        BE->>BE: 3. 单元测试 / 联调
    end
    
    FE->>BE: 4. 联调（path 一致，body/response camelCase）
    BE-->>FE: 返回 camelCase JSON
\`\`\`

## 3. 数据流与规范

- **请求**：前端只发 camelCase（如 `userId`、`referralCode`）。soul-api 的 Go 结构体用 `json:"userId"` 等接收。
- **响应**：soul-api 通过 GORM 模型 `json:"userId"` 等输出 camelCase；前端 TypeScript 类型与接口字段一致（camelCase）。
- **数据库**：表名列名保持 snake_case（如 `user_id`、`created_at`），仅在 soul-api 内部使用，不暴露给前端。

## 4. 落地执行规范

1. **接口先行**：新增/修改接口先在文档约定 URL、方法、请求/响应体（字段 camelCase）。
2. **统一封装**：soul-admin 所有请求走 `src/api/client.ts`（get/post/put/del），path 与现网一致；小程序走 `app.request()`，不写死域名。
3. **字段统一**：禁止在 API 响应或前端类型中使用 snake_case 对外字段；表单提交、列表展示一律 camelCase。

---
**卡若说：**
按这个流程走，前后端对接清晰。路径一致、字段 camelCase 统一，多端复用同一套 soul-api 即可。