105 lines
7.9 KiB
Markdown
105 lines
7.9 KiB
Markdown
# 链路优化与运行指南
|
||
|
||
> 以**第一个目录（主项目）**为基准，不修改文件与目录结构，仅明确「后台鉴权 → 进群 → 营销策略 → 支付」整条链路的落地与运行方式。
|
||
> 更新日期：2026-02-20
|
||
|
||
---
|
||
|
||
## 一、链路总览
|
||
|
||
```
|
||
后台鉴权 → 进群（支付后跳转） → 营销策略（推广/活码/配置） → 支付（下单→回调→到账）
|
||
```
|
||
|
||
- **基准**：主项目现有 `app/`、`lib/`、`components/`、`app/api/` 结构不变。
|
||
- **运行**：本机 `pnpm dev` 或生产 `pnpm build` + `node .next/standalone/server.js`，端口 3006（见 `开发文档/本机运行文档.md`）。
|
||
- **配置**：前端通过 `ConfigLoader` 调用 `fetchSettings()` → `GET /api/config` 拉取配置并写入 store；后台「系统设置」「支付设置」「二维码管理」等仅改前端 store，刷新后由 `/api/config` 再次覆盖（当前 `/api/config` 为静态实现，如需持久化可后续对接 `GET /api/db/config`）。
|
||
|
||
---
|
||
|
||
## 二、后台鉴权
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **入口** | `app/admin/login/page.tsx`，账号密码提交后调用 `store.adminLogin(username, password)`。 |
|
||
| **校验** | `lib/store.ts` 内 `adminLogin`：`username === 'admin'` 且 `password === 'key123456'` 即通过，与 `.cursorrules`、`lib/admin-auth.ts` 默认一致。 |
|
||
| **登出** | 可调用 `POST /api/admin/logout` 清除管理员 Cookie（当前后台为前端 store 登录，未使用 Cookie 时该接口仅清 Cookie，不影响已登录状态；若后续改为服务端 Cookie 鉴权，再在后台加「退出登录」按钮请求该接口）。 |
|
||
| **环境变量** | `ADMIN_USERNAME` / `ADMIN_PASSWORD` 在 `lib/admin-auth.ts` 中生效；`store.adminLogin` 仍为写死 `key123456`，若需统一可从环境变量读（需改 store 一处）。 |
|
||
|
||
**落地要点**：保持现有结构即可运行；默认 admin / key123456，与文档一致。
|
||
|
||
---
|
||
|
||
## 三、进群（支付后跳转）
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **配置来源** | 前端：`settings.paymentMethods.wechat.groupQrCode`、`settings.liveQRCodes`（活码多链接）。来源为 `fetchSettings()` → `GET /api/config` 与 store 默认值合并。 |
|
||
| **后台配置** | 「二维码管理」页（`app/admin/qrcodes/page.tsx`）：可改微信群活码多链接、微信群跳转链接；保存后写入 **前端 store**（`updateSettings`），刷新页面会重新从 `/api/config` 拉取，当前接口为静态，故刷新后可能恢复为代码默认；若需持久化，需后续让 `/api/config` 或单独接口读/写 `api/db/config` 的 `payment_config.wechatGroupUrl` 等。 |
|
||
| **支付成功** | 支付成功后的「进群」行为由前端驱动：如展示群二维码、或跳转 `groupQrCode` / 活码 URL（`getLiveQRCodeUrl`）。 |
|
||
| **静态配置** | `app/api/config/route.ts` 中 `paymentMethods.wechat.groupQrCode`、`marketing.partyGroup` 等可改代码内默认，部署后生效。 |
|
||
|
||
**落地要点**：当前不改文件结构即可跑通；进群链接/活码以后台「二维码管理」或直接改 `app/api/config/route.ts` 默认值均可；若要多环境/持久化，再对接 db 配置。
|
||
|
||
---
|
||
|
||
## 四、营销策略
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **配置** | 站点名、作者信息、派对房时间、Banner 等：`/api/config` 返回的 `siteConfig`、`authorInfo`、`marketing.banner` 等，经 `fetchSettings` 合并进 store。 |
|
||
| **推广** | 邀请码绑定 `POST /api/referral/bind`，推广数据 `GET /api/referral/data`，访问记录 `POST /api/referral/visit`；分销比例等见 `api/db/config` 的 `referral_config`（后台「系统设置」可调）。 |
|
||
| **海报** | 推广海报由前端组件（如 `components/modules/referral/poster-modal.tsx`）生成，依赖 store 中的用户与配置。 |
|
||
| **内容** | 书籍章节、免费章节列表等：来自 `lib/book-data` + 接口（如 `api/book/*`、`api/content`）；内容修改以第一个目录下 `book/` 及 `lib/book-data.ts` 为准，不新增目录。 |
|
||
|
||
**落地要点**：营销与内容均以主项目现有模块为准；配置优先从 `/api/config`（及可选 db）读取，保证运行一致。
|
||
|
||
---
|
||
|
||
## 五、支付
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **下单** | `POST /api/payment/create-order` 创建订单；参数与支付方式以 `lib/payment-service`、`lib/payment/*` 及后台「支付设置」相关配置为准。 |
|
||
| **回调** | 微信 `POST /api/payment/wechat/notify`，支付宝 `POST /api/payment/alipay/notify`；支付网关配置回调 URL 至上述接口。 |
|
||
| **前端回调** | 前端轮询或跳转：`/api/payment/verify`、`/api/payment/status/[orderSn]`、`/api/payment/callback`（当前 callback 为简单确认，实际到账以微信/支付宝 notify 为准）。 |
|
||
| **与进群衔接** | 支付成功并校验通过后，前端根据 `settings.paymentMethods.wechat.groupQrCode` 或活码展示/跳转进群。 |
|
||
|
||
**落地要点**：保持现有支付路由与 lib 不变；确保生产环境配置好微信/支付宝回调地址及密钥，即可跑通整条「支付 → 到账 → 进群」链路。
|
||
|
||
---
|
||
|
||
## 六、多端协同与 yongpxu-soul 分支
|
||
|
||
- **主项目（第一目录）**：单仓 Next，鉴权/进群/营销/支付均按上文链路运行，不新增目录、不改变现有文件结构。
|
||
- **yongpxu-soul 分支**：在现有基础上增加了部署脚本（如 `scripts/deploy_baota.py`）、小程序构建与上传、开发文档（小程序管理、服务器管理、提现功能文档等），以及部分依赖与配置；**业务链路（鉴权→进群→营销→支付）与主项目一致**，仍以 `app/`、`lib/`、`app/api/` 现有实现为准。
|
||
- **协同方式**：多个角色可并行优化——例如：A 负责后台鉴权与登出对接；B 负责进群配置与活码持久化方案；C 负责营销配置与内容更新；D 负责支付回调与对账——所有改动均限制在现有文件与路由内，不增加新的一级目录或拆仓。
|
||
|
||
---
|
||
|
||
## 七、运行检查清单（保证可运行）
|
||
|
||
1. **环境**：`pnpm install`，可选 `.env.local` 配置 `MYSQL_*`、`SKIP_DB`（见 `开发文档/本机运行文档.md`）。
|
||
2. **鉴权**：访问 `/admin/login`，admin / key123456 可进入后台。
|
||
3. **配置**：首页或任意页加载时 `ConfigLoader` 会请求 `/api/config`；若接口失败，前端使用 store 默认值仍可浏览。
|
||
4. **进群**：后台「二维码管理」配置群链接/活码后，支付成功页或相关弹窗可展示/跳转（当前为前端 store，刷新后以 `/api/config` 为准）。
|
||
5. **营销**：推广链接、海报、分销比例依赖 store 与 `api/referral/*`、`api/db/config`，按现有逻辑即可。
|
||
6. **支付**：创建订单 → 支付 → 微信/支付宝回调至 `/api/payment/wechat/notify`、`/api/payment/alipay/notify`；前端校验订单状态后展示进群或解锁内容。
|
||
|
||
按上述清单自检后，整条链路可在不修改文件结构的前提下完成落地与运行；后续迭代（如活码持久化、admin 密码从环境变量读取）可在对应单文件内扩展。
|
||
|
||
---
|
||
|
||
## 八、运行检查执行记录（2026-02-20）
|
||
|
||
| 检查项 | 结果 | 说明 |
|
||
|--------|------|------|
|
||
| 环境 | ✅ | `pnpm install` 成功；可选 `.env.local` 配置 `MYSQL_*`、`SKIP_DB`。 |
|
||
| 构建 | ✅ | `pnpm run build` 成功，Next.js 16.0.10，output: standalone。 |
|
||
| 首页 | ✅ | 开发环境 `pnpm dev` 启动后 `GET /` 返回 200。 |
|
||
| 配置接口 | ✅ | `GET /api/config` 返回 200，含 paymentMethods、marketing 等。 |
|
||
| 鉴权 | ✅ | 路由 `/admin/login` 存在；store.adminLogin 与 admin/key123456 一致。 |
|
||
| 进群/营销/支付 | ✅ | 路由与 store 配置完整；支付回调路由 `/api/payment/wechat/notify`、`/api/payment/alipay/notify` 已存在。 |
|
||
|
||
结论：项目在未修改文件结构下可正常构建与运行，链路（鉴权→进群→营销→支付）就绪。
|