# 系统架构

**我是卡若。**

架构不是为了画图好看，是为了**省事**和**赚钱**。

我们的架构设计，核心围绕两个字：**分离**。
- 内容和代码分离。
- 前端和后端分离（已落地：soul-api + soul-admin + 小程序）。
- 静态和动态分离。

## 1. 架构全景图（当前）

\`\`\`mermaid
graph TD
    subgraph "内容生产 (Content)"
        Typora[本地写作] --> Git[Git 仓库]
        Git --> AutoSync[自动同步]
    end

    subgraph "后端 (soul-api - Go)"
        API[Gin API /api/*]
        API --> GORM[GORM]
        GORM --> MySQL[(MySQL)]
        AutoSync --> FileSys[文件/配置]
        FileSys --> API
    end

    subgraph "前端"
        Admin[soul-admin React+Vite]
        Mini[微信小程序]
        Admin --> API
        Mini --> API
    end

    subgraph "用户触达"
        Mini --> Wechat[微信]
        Admin --> Browser[浏览器]
    end
\`\`\`

## 2. 当前项目分工

| 层级 | 项目 | 技术 | 说明 |
|------|------|------|------|
| **后端** | soul-api | Go 1.25 + Gin + GORM + MySQL | 提供全部 `/api/*`，路径与现网一致，响应 camelCase |
| **管理端** | soul-admin | React 18 + Vite 6 + TS + Tailwind + Radix UI | SPA，`VITE_API_BASE_URL` 指向 soul-api |
| **C 端** | miniprogram | 微信小程序原生 | 阅读、购买、分销、提现，请求/响应 camelCase |
| **备用** | next-project | Next.js | 原单体，可保留 app/api 过渡或逐步下线 |

## 3. 核心设计理念

### 3.1 “内容即产品”
核心资产是内容（书籍章节、配置）。文章用 Markdown/数据库存，Git 或脚本同步，安全可控。

### 3.2 前后端已分离
- **后端**：soul-api（Go）独立部署，可单独扩容、多端复用。
- **管理端**：soul-admin 纯静态 SPA，部署到任意静态托管或 CDN。
- **接口契约**：路径不变，请求/响应字段统一 **camelCase**，详见 [前后端架构分离策略](前后端架构分离策略.md)。

### 3.3 极简部署
- 后端：Go 二进制 + 环境变量，或 Docker 单容器。
- 管理端：`npm run build` 后部署到 Nginx/Vercel/OSS。
- 小程序：微信后台发布。宝塔/Webhook 可按需做自动拉代码。

## 4. 关键约束

1. **API 字段统一**：对外一律 camelCase（如 `userId`、`createdAt`）；数据库列名保持 snake_case 仅在服务端使用。
2. **本地优先**：写作与开发在本地，通过 soul-api 连接数据库。
3. **单向流动**：数据流向 `内容/配置 -> API -> 前端`；订单、用户等由 API 写库。

## 5. 详细技术栈

详见：**[技术选型与全景图](技术选型与全景图.md)**、**[前后端架构分离策略](前后端架构分离策略.md)**。

---
**总结：**
当前已实现前后端分离：soul-api 负责接口与数据，soul-admin 负责管理后台，小程序负责 C 端。保持接口路径与字段规范统一，便于多端对接与扩展。