soul-yongping/开发文档/2、架构/前后端架构分离策略.md

前后端分离开发架构

我是卡若。

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

1. 当前架构（已落地）

```mermaid graph LR subgraph "前端" Admin[soul-admin
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 即可。