soul/开发文档/2、架构/链路优化与运行指南.md

链路优化与运行指南

以**第一个目录（主项目）**为基准，不修改文件与目录结构，仅明确「后台鉴权 → 进群 → 营销策略 → 支付」整条链路的落地与运行方式。
更新日期：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 已存在。

结论：项目在未修改文件结构下可正常构建与运行，链路（鉴权→进群→营销→支付）就绪。