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

前后端分离开发架构图

我是卡若。

为了让你（开发人员）能闭着眼睛把活干了，我把前后端分离的流程画得清清楚楚。

我们采用接口契约驱动开发 (Contract-First Development)。

1. 分离开发流程

```mermaid sequenceDiagram participant PM as 卡若 (PM) participant Doc as API 文档 participant FE as 前端开发 participant BE as 后端开发

PM->>Doc: 1. 定义需求与接口 (API接口.md)
Note over Doc: 确定 URL, Params, Response

par 并行开发
    FE->>Doc: 2. 查阅接口定义
    FE->>FE: 3. Mock 数据 (假数据)
    FE->>FE: 4. 开发 UI 与交互
    
    BE->>Doc: 2. 查阅接口定义
    BE->>BE: 3. 实现业务逻辑
    BE->>BE: 4. 单元测试 (Postman)
end

FE->>BE: 5. 联调 (对接真实接口)
BE-->>FE: 返回真实数据

FE->>PM: 6. 验收与上线

```

2. 架构交互图 (Data Flow)

```mermaid graph LR subgraph "前端域 (Browser)" UI[页面组件] --> API_Client[API 请求封装层] API_Client -- JSON 请求 --> API_Route end

subgraph "后端域 (Server/Next.js)"
    API_Route[API 路由入口] --> Controller[业务控制器]
    Controller --> Service[逻辑服务层]
    
    Service --> Content[内容解析器]
    Service --> Config[配置加载器]
    
    Content -- 读取 --> FS[文件系统 book/]
    Config -- 读取 --> DB[(MongoDB/JSON)]
end

Service -- JSON 响应 --> Controller
Controller -- HTTP 响应 --> API_Client
API_Client -- 数据 --> UI

```

3. 落地执行规范

1. 接口先行: 没定义好接口文档，不许写代码。
2. Mock 优先: 前端别等后端，自己造个 JSON 数据先跑起来。
3. 统一封装: 前端所有请求必须走 lib/api.ts，禁止在组件里直接写 fetch('/api/...')。

---

卡若说： 按这个流程走，前后端吵架的概率降低 90%。效率就是这么抠出来的。