# 永平版 vs 主项目：优化对比与合并说明

> 对比目录：主项目（一场soul的创业实验） vs 永平版（一场soul的创业实验-永平）  
> 更新日期：2026-02-20

---

## 一、两套目录结构概览

| 项目 | 根目录特点 | Next 源码位置 |
|------|------------|----------------|
| **主项目** | 单仓：Next + book + miniprogram + 开发文档 | 根下 `app/`、`lib/`、`components/` |
| **永平版** | 多仓：soul-api(Go)、soul-admin(Vue)、soul(Next) | `soul/dist/`（源码与构建同目录） |

永平版还包含：`本机运行文档.md`、Go API(8080)、Vue 管理后台(静态)、开发 API(8081)。主项目为纯 Next 站 + 宝塔 3006 部署。

---

## 二、已合并到主项目的优化（本次迭代）

| 模块 | 优化内容 | 主项目路径 |
|------|----------|------------|
| **数据库** | 环境变量 `MYSQL_*`、`SKIP_DB`、连接超时与单次连接错误日志 | `lib/db.ts` |
| **数据库** | 订单表 status 增加 `created`/`expired`，字段 `referrer_id`/`referral_code`；用户表 ALTER 兼容 MySQL 5.7 | 同上 |
| **认证** | 密码哈希/校验（scrypt，兼容旧明文） | `lib/password.ts`（新增） |
| **认证** | Web 端手机号+密码登录 | `app/api/auth/login/route.ts`（新增） |
| **认证** | 重置密码 | `app/api/auth/reset-password/route.ts`（新增） |
| **后台** | 管理员登出（清除 Cookie） | `app/api/admin/logout/route.ts`（新增） |
| **前端** | 仅生产环境加载 Vercel Analytics | `app/layout.tsx` |
| **文档** | 本机/服务器运行说明（端口、目录、Nginx） | `开发文档/本机运行文档.md`（新增） |

---

## 三、永平有、主项目未合并的（可选后续）

| 模块 | 说明 | 永平路径 | 合并建议 |
|------|------|----------|----------|
| 定时任务 | 订单状态同步、过期解绑 | `app/api/cron/sync-orders`、`cron/unbind-expired` | 若需定时同步/解绑再迁入；需配置 CRON_SECRET |
| 提现扩展 | 待确认列表、提现记录 API | `withdraw/pending-confirm`、`withdraw/records` | 若后台要做提现工作流与记录查询可迁入 |
| 用户 API | 购买状态、阅读进度、收货地址 CRUD | `user/check-purchased`、`user/reading-progress`、`user/addresses` | 按产品需要选择性迁入 |
| 后台 | 分销概览 API、推广设置页 | `admin/distribution/overview`、`admin/referral-settings/page.tsx` | 若有分销看板/推广配置页可迁入 |
| 前台 | 忘记密码页、我的地址列表/编辑/新增 | `app/view/login/forgot`、`app/view/my/addresses/*` | 主项目路由为 `app/login/`、`app/my/`，可对应新增 |
| 构建 | standalone 复制 static/public、clean、write-warning | `scripts/prepare-standalone.js` 等 | 若主项目用 standalone 部署可迁入 |
| 数据层 | Prisma 模型与迁移 | `prisma/schema.prisma`、迁移脚本 | 主项目当前为 mysql2；若统一用 Prisma 再迁 |
| 路由结构 | 前台统一在 `app/view/` | 整棵 `app/view/` | 主项目保持扁平 `app/`，非必须 |

---

## 四、主项目保留、与永平不同的部分

- **CORS**：主项目在 `middleware.ts` + `next.config.mjs` 的 headers 中配置 API CORS；永平可能用 Nginx/Go，未在 Next 层做。
- **路由**：主项目前台为 `app/page.tsx`、`app/my/`、`app/read/` 等，无 `view` 前缀。
- **book**：主项目根下保留 `book/` Markdown 与现有内容体系；永平书内容可能来自 API/DB。

---

## 五、环境变量说明（合并后）

主项目 `.env.local` 建议支持（可选）：

```bash
# 数据库（不设则用代码内默认值）
MYSQL_HOST=
MYSQL_PORT=
MYSQL_USER=
MYSQL_PASSWORD=
MYSQL_DATABASE=

# 本地无数据库时跳过连接（接口会报错，适合纯前端联调）
SKIP_DB=0
```

---

## 六、合并与实施注意

1. **路径**：永平 Next 源码在 `soul/dist/`，合并到主项目时对应到根下 `app/`、`lib/`、`开发文档/`。
2. **CORS**：保留主项目现有 `middleware.ts` 与 `next.config.mjs` 的 CORS 配置。
3. **数据库**：主项目继续使用 mysql2，未引入 Prisma；`lib/db.ts` 已支持环境变量与 `SKIP_DB`。
4. **admin 登出**：后台可增加「退出登录」按钮，请求 `POST /api/admin/logout` 后跳转登录页。

5. **已有数据库**：若主项目此前已建过 `orders` 表且无 `referrer_id`/`referral_code` 或 status 无 `created`/`expired`，需自行执行迁移，例如：
   ```sql
   ALTER TABLE orders MODIFY COLUMN status ENUM('created','pending','paid','cancelled','refunded','expired') DEFAULT 'created';
   ALTER TABLE orders ADD COLUMN referrer_id VARCHAR(50) NULL COMMENT '推荐人用户ID', ADD COLUMN referral_code VARCHAR(20) NULL COMMENT '下单时使用的邀请码';
   ```
   若表为新建，`initDatabase()` 已包含上述结构。

---

**文档状态**：已合并项已落地；未合并项见第三节，按需迭代。