# Mycontent-book 项目总览

**我是卡若。**

做这个项目，逻辑很简单：**把书卖出去，把私域做起来，把钱分下去。**

这就不是一个普通的博客网站，这是一个**内容变现系统**。所有的技术架构，都要围绕着“阅读体验”、“流量承接”和“变现转化”来做。

别整那些虚头巴脑的概念，咱们直接看这个盘子怎么搭。

## 1. 核心逻辑

这个项目的生意逻辑就是三层：
1.  **流量层（前端）**：让用户看着爽，像刷抖音、看公众号一样流畅。必须移动端优先，模拟 iOS 的原生质感。
2.  **内容层（数据）**：`book/` 目录下的 Markdown 文件就是我们的资产。改个字，推送到 GitHub，网站立马更新。
3.  **变现层（后端/接口）**：谁看了？谁买了？谁推荐的？这些数据要跑通。

## 2. 为什么这么架构？

我选 Next.js，不是因为流行，是因为它**省事**。
- **SSR（服务端渲染）**：SEO 友好，百度谷歌能搜到，自带流量。
- **API Routes**：不用单独起个 Java 或 Python 服务，省服务器钱。
- **Vercel/宝塔部署**：自动化流水线，我只管写文章，代码自动跑。

## 3. 当前项目结构（前后端已分离）

### 3.1 仓库根目录

| 目录/项目 | 技术栈 | 说明 |
|-----------|--------|------|
| **soul-api/** | Go 1.25 + Gin + GORM + MySQL | 独立后端 API 服务，路径与现网一致 `/api/*` |
| **soul-admin/** | React 18 + Vite 6 + TypeScript + Tailwind 4 + Radix UI | 管理后台 SPA，请求通过 `VITE_API_BASE_URL` 对接 soul-api 或 Next |
| **miniprogram/** | 微信小程序原生 | C 端主阵地，用户阅读、购买、分销、提现等 |
| **next-project/** | Next.js（可选保留） | 原单体：含 `app/view/` C 端、`app/admin/` 管理端、`app/api/`；可作备用或逐步下线 |

### 3.2 接口与前端对应关系

- **API 服务**：由 **soul-api**（Go）提供，端口默认 8080；路径与现网完全一致（如 `/api/user/profile`、`/api/admin/withdrawals`）。
- **管理端**：**soul-admin** 独立部署，环境变量 `VITE_API_BASE_URL` 指向 soul-api 或 Next 的 API 基地址。
- **小程序**：通过 `app.request()` 等封装请求 API，baseUrl 可配置，与 soul-api 对接。
- **API 字段规范**：对外请求/响应**统一使用小写开头驼峰（camelCase）**，如 `userId`、`referralCode`、`createdAt`；数据库列名仍为 snake_case，仅在服务端内部使用。

## 4. 目录导航（别迷路）

- **[1、需求](1、需求/业务需求.md)**：我们要干啥，成本多少，技术要求；[TDD 需求方案](1、需求/TDD_创业派对项目方案_v1.0.md)。
- **[2、架构](2、架构/系统架构.md)**：整体怎么搭，前后端怎么分。
    - [技术选型与全景图](2、架构/技术选型与全景图.md)、[前后端架构分离策略](2、架构/前后端架构分离策略.md)
- **[3、原型](3、原型/原型设计规范.md)**：原型设计规范。
- **[4、前端](4、前端/前端架构.md)**：前端架构（含 **soul-admin**、小程序）、模块详解、开发规范；[当前小程序开发细则](4、前端/当前小程序开发细则.md)；[ui 子目录](4、前端/ui/)：项目概述、页面功能、组件清单、API/状态/分销/支付/管理后台/部署说明等。
- **[5、接口](5、接口/API接口.md)**：前后端怎么说话。
- **[6、后端](6、后端/后端架构.md)**：**soul-api**（Go + Gin + GORM）架构与业务模块，后端开发规范。
- **[7、数据库](7、数据库/数据库设计.md)**：数据存哪，怎么存。
- **[8、部署](8、部署/部署总览.md)**：怎么上线、本地运行、宝塔部署、新分销部署、修复与优化记录等。
- **[9、手册](9、手册/写作与结构维护手册.md)**：怎么写书，怎么维护。
- **[10、项目管理](10、项目管理/项目落地推进表.md)**：项目推进与提示词。

## 5. 开发约束（重要）

> **2026-02-07 更新：前后端已分离，soul-api + soul-admin 为主力**

### 5.1 项目与开发策略

| 项目/端 | 路径/端口 | 开发状态 | 说明 |
|---------|-----------|----------|------|
| **soul-api** | 端口 8080 | ✅ 主力后端 | Go + Gin，提供全部 `/api/*` 接口，MySQL + GORM |
| **soul-admin** | 独立 SPA | ✅ 主力管理端 | React + Vite，通过 `VITE_API_BASE_URL` 对接 soul-api |
| **微信小程序** | `miniprogram/` | ✅ 主力 C 端 | 所有面向用户的新功能在此开发 |
| **Next.js** | `next-project/` 或原 app | 🔒 备用/冻结 | C 端 `app/view/` 冻结；`app/api/` 可作过渡或下线 |

### 5.2 核心原则

1. **后端统一走 soul-api**：新接口在 soul-api 实现，路径与现网一致，响应字段统一 **camelCase**。
2. **管理端统一走 soul-admin**：新管理功能在 soul-admin 开发，请求体与展示字段统一 **camelCase**。
3. **小程序优先**：C 端新功能只在小程序开发，请求/响应已按 camelCase 对接。
4. **API 契约统一**：查询、新增、编辑、删除的请求/响应字段全部小写开头驼峰（如 `userId`、`createdAt`、`referralCode`）。

### 5.3 登录与鉴权

| 端 | 登录方式 | 说明 |
|---|----------|------|
| 小程序 | 微信一键登录 / 手机号快速授权 | 与 soul-api 或 Next 的 `/api/miniprogram/login` 等对接 |
| soul-admin | 手机号 + 密码 | POST `/api/admin` 登录，GET 鉴权，Cookie/Token |
| 账号统一 | 以手机号/用户 ID 为唯一标识 | 多端数据互通 |

### 5.4 为什么前后端分离？

- **独立部署与扩展**：后端 Go 可单独扩容，前端静态资源可 CDN。
- **多端复用 API**：小程序、soul-admin、未来 App 共用同一套 soul-api。
- **开发效率**：前后端并行、接口契约清晰（camelCase 统一）。

## 6. 这里的规矩

- **行动至上**：文档是用来指导干活的，不是写来看的。
- **数据说话**：所有优化要有数据支撑，加载快了多少？转化高了多少？
- **保持简单**：能用现成的库就别自己造轮子。

---
**复盘：**
项目已完成前后端分离：soul-api（Go）负责接口与数据库，soul-admin（React）负责管理后台，miniprogram 负责 C 端。API 与前端字段已统一为 camelCase，便于多端对接与后续扩展。