6.3 KiB
6.3 KiB
Mycontent-book 项目总览
我是卡若。
做这个项目，逻辑很简单：把书卖出去，把私域做起来，把钱分下去。
这就不是一个普通的博客网站，这是一个内容变现系统。所有的技术架构，都要围绕着“阅读体验”、“流量承接”和“变现转化”来做。
别整那些虚头巴脑的概念，咱们直接看这个盘子怎么搭。
1. 核心逻辑
这个项目的生意逻辑就是三层：
- 流量层（前端）：让用户看着爽，像刷抖音、看公众号一样流畅。必须移动端优先，模拟 iOS 的原生质感。
- 内容层（数据）：
book/目录下的 Markdown 文件就是我们的资产。改个字，推送到 GitHub，网站立马更新。 - 变现层（后端/接口）：谁看了？谁买了？谁推荐的？这些数据要跑通。
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、需求：我们要干啥，成本多少，技术要求；TDD 需求方案。
- 2、架构：整体怎么搭，前后端怎么分。
- 3、原型：原型设计规范。
- 4、前端：前端架构（含 soul-admin、小程序）、模块详解、开发规范；当前小程序开发细则；ui 子目录：项目概述、页面功能、组件清单、API/状态/分销/支付/管理后台/部署说明等。
- 5、接口：前后端怎么说话。
- 6、后端：soul-api（Go + Gin + GORM）架构与业务模块，后端开发规范。
- 7、数据库：数据存哪，怎么存。
- 8、部署：怎么上线、本地运行、宝塔部署、新分销部署、修复与优化记录等。
- 9、手册：怎么写书，怎么维护。
- 10、项目管理：项目推进与提示词。
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 核心原则
- 后端统一走 soul-api：新接口在 soul-api 实现，路径与现网一致，响应字段统一 camelCase。
- 管理端统一走 soul-admin：新管理功能在 soul-admin 开发，请求体与展示字段统一 camelCase。
- 小程序优先：C 端新功能只在小程序开发，请求/响应已按 camelCase 对接。
- 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，便于多端对接与后续扩展。