soul/开发文档/永平版优化对比与合并说明.md

永平版 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 建议支持（可选）：

# 数据库（不设则用代码内默认值）
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，需自行执行迁移，例如：

   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() 已包含上述结构。

---

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