Files
soul-yongping/开发文档/10、项目管理/项目落地推进表.md
卡若 22bb29f433 feat: 内容管理深度优化 (03-07~03-09)
- 排名算法权重可配置,排行榜显示点击量/付款数/热度
- 富文本编辑器升级(TipTap),支持@提及/#链接标签/图片/表格
- 「主人公」Tab → 「链接AI」Tab,AI列表+链接标签管理
- 链接标签新增存客宝(ckb)类型,存客宝绑定配置面板
- 人物ID改为可选,名称必填
- 排行榜操作改为「编辑文章」,付款记录移入编辑弹窗
- 章节ID修改支持(originalId/newId机制)
- 付款记录用户ID/订单ID可点击跳转
- 项目推进表补充14-15节(03-07~09改动记录+存客宝技术方案)

Made-with: Cursor
2026-03-09 05:49:03 +08:00

24 KiB
Raw Blame History

项目落地推进表


一、项目总览

  • 项目名称:一场 SOUL 的创业实验场
  • 核心目标
    构建一个集内容阅读、私域引流、知识变现于一体的 H5 应用,验证「内容 + 私域 + 分销」的商业闭环
  • 当前阶段6.2 真实支付系统对接
  • 负责人:卡若 & 智能助手
  • 启动时间2025-12-28

二、关键阶段与里程碑

第一阶段:基础设施搭建(已完成 100%

  • 1.1 开发环境配置Next.js 16 + Tailwind v4
  • 1.2 核心 UI 框架搭建Shadcn/ui + 苹果毛玻璃风格)
  • 1.3 Markdown 解析引擎实现
  • 1.4 路由与导航系统
  • 1.5 移动端底部导航栏(首页/目录/我的)

第二阶段:核心阅读体验(已完成 100%

  • 2.1 首页 / 书籍封面展示
  • 2.2 沉浸式阅读器开发(章节内容渲染)
  • 2.3 目录与章节导航(折叠式章节树)
  • 2.4 内容数据结构设计(动态文件系统读取)
  • 2.5 书籍内容完整导入5篇47章

第三阶段:私域引流体系(已完成 100%

  • 3.1 派对群引流弹窗(支付后自动展示)
  • 3.2「我的」个人中心(个人信息/购买记录/分销中心)
  • 3.3 钩子内容设置(章节解锁逻辑)
  • 3.4 微信群二维码动态配置(活码系统)
  • 3.5 二维码管理后台(支持多链接随机分配)

第四阶段:商业变现闭环(已完成 100%

4.1 基础能力(已完成)

  • 4.1.1 支付弹窗组件PaymentModal
  • 4.1.2 多支付方式支持(微信/支付宝/USDT
  • 4.1.3 购买逻辑(单章节/整本书)
  • 4.1.4 用户权限管理admin账号免购买

4.2 管理后台(已完成)

  • 4.2.1 后台登录页admin / key123456
  • 4.2.2 仪表盘(数据概览)
  • 4.2.3 内容管理(章节价格配置)
  • 4.2.4 支付配置页面(微信/支付宝参数)
  • 4.2.5 用户管理(用户列表/权限管理)
  • 4.2.6 二维码管理(活码配置)
  • 4.2.7 提现审核(提现申请处理)
  • 4.2.8 系统设置(分销比例/价格配置)

4.3 真实支付对接(已完成 100%

  • 4.3.1 支付宝配置集成
    • PID: 2088511801157159
    • Key: lz6ey1h3kl9zqkgtjz3avb5gk37wzbrp
    • 手机网站支付接口
  • 4.3.2 微信支付配置集成
    • 网站AppID: wx432c93e275548671
    • 网站AppSecret: 25b7e7fdb7998e5107e242ebb6ddabd0
    • 服务号AppID: wx7c0dbf34ddba300d
    • 服务号AppSecret: f865ef18c43dfea6cbe3b1f1aebdb82e
    • 商户号: 1318592501
    • API密钥: wx3e31b068be59ddc131b068be59ddc2
  • 4.3.3 支付API路由开发
    • /api/payment/create-order创建订单
    • /api/payment/verify验证支付
    • /api/payment/callback支付回调
    • /api/payment/alipay/notify支付宝回调
    • /api/payment/wechat/notify微信回调
  • 4.3.4 订单管理系统
    • /api/orders订单查询
    • localStorage订单存储
  • 4.3.5 支付SDK服务层开发
    • AlipayService类签名生成/验证)
    • WechatPayService类签名生成/验证)
  • 4.3.6 环境变量配置
    • .env.local模板文件
    • vercel.json生产配置
  • 4.3.7 部署文档编写
    • DEPLOYMENT.md完整部署指南

第五阶段:分销与裂变(已完成 100%

  • 5.1 邀请码生成与绑定
  • 5.2 分销收益计算系统90%给分销者)
  • 5.3 提现申请功能(用户端)
  • 5.4 提现审核功能(管理端)
  • 5.5 裂变海报生成器
  • 5.6 分销数据统计

第六阶段:生产环境优化(已完成 100%

6.1 技术优化(已完成)

  • 6.1.1 移除Mongoose依赖
  • 6.1.2 升级Next.js至16.0.10
  • 6.1.3 修复文件系统路径错误
  • 6.1.4 添加错误调试日志
  • 6.1.5 后台深色主题统一

6.2 支付系统优化(已完成)

  • 6.2.1 支付配置字段统一
  • 6.2.2 跳转链接支持weixin://、alipays://
  • 6.2.3 二维码扫码跳转
  • 6.2.4 支付宝SDK服务类AlipayService
  • 6.2.5 微信支付SDK服务类WechatPayService
  • 6.2.6 支付回调路由(支持签名验证)
  • 6.2.7 订单创建接口(集成真实参数)

6.3 生产环境准备(已完成)

  • 6.3.1 环境变量模板(.env.local
  • 6.3.2 Vercel部署配置vercel.json
  • 6.3.3 部署文档编写DEPLOYMENT.md
  • 6.3.4 区域配置(香港/新加坡节点)
  • 6.3.5 CORS和安全头配置

第七阶段:文档与交付(已完成 100%

  • 7.1 部署指南文档DEPLOYMENT.md
  • 7.2 环境变量配置说明
  • 7.3 支付回调配置指引
  • 7.4 测试流程清单
  • 7.5 监控和日志方案

三、项目完成报告2025-12-29 最终版)

已完成工作(完整清单)

模块名称:知识付费系统完整开发
当前状态:全部功能已完成,可直接部署
完成百分比:整体项目 100%

最终完成内容汇总:

  1. 真实支付SDK集成

    • 支付宝服务类AlipayService订单创建、MD5签名、签名验证
    • 微信支付服务类WechatPayService订单创建、XML解析、签名验证
    • 支付回调路由:/api/payment/alipay/notify 和 /api/payment/wechat/notify
    • 订单创建接口:集成真实支付宝和微信参数
    • 支付方式支持微信、支付宝、USDT、PayPal四种方式
  2. 环境配置完善

    • .env.local包含所有支付参数的模板文件
    • vercel.json生产环境配置区域、环境变量、CORS
    • DEPLOYMENT.md完整的部署指南文档
  3. 分销系统完整实现

    • 推广海报生成器
    • 提现申请和审核
    • 收益自动计算90%分销+10%平台)
    • 邀请链接和绑定机制
  4. 二维码管理系统

    • 动态活码管理
    • 微信群跳转weixin://协议)
    • 后台可视化配置
  5. 后台管理系统

    • 8个完整页面仪表盘、内容、支付、用户、二维码、提现、设置、登录
    • 深色主题统一(#0a1628
    • 数据可视化和统计
  6. 内容管理系统

    • 47章完整内容
    • 动态文件系统
    • 章节价格配置
    • 权限控制
  7. 用户体验优化

    • 苹果毛玻璃风格
    • 移动端完美适配
    • 底部导航栏
    • 流畅的支付流程

四、项目完成度评估(最终版)

模块 完成度 说明
前端UI 100% 所有页面完成,移动端完美适配
后台管理 100% 8个管理页面 + 深色主题
内容系统 100% 动态Markdown文件系统
用户系统 100% 登录注册、邀请码、权限管理
支付配置 100% 微信/支付宝/USDT/PayPal参数配置
支付SDK 100% AlipayService + WechatPayService
支付回调 100% 签名验证 + 订单状态更新
分销系统 100% 邀请、佣金、提现、海报
二维码系统 100% 活码、跳转链接
环境配置 100% .env.local + vercel.json
部署文档 100% DEPLOYMENT.md完整指南
整体进度 100% 可直接部署到生产环境

五、生产部署清单

立即可部署

前置条件:

  1. 拥有Vercel账号
  2. 拥有支付宝和微信支付商户资质
  3. 准备好域名可选Vercel提供免费域名

部署步骤:

```bash

1. 安装Vercel CLI

npm install -g vercel

2. 登录Vercel

vercel login

3. 部署到生产环境

vercel --prod ```

环境变量配置在Vercel Dashboard

  • ALIPAY_PARTNER_ID=2088511801157159
  • ALIPAY_KEY=lz6ey1h3kl9zqkgtjz3avb5gk37wzbrp
  • WECHAT_APP_ID=wx432c93e275548671
  • WECHAT_APP_SECRET=25b7e7fdb7998e5107e242ebb6ddabd0
  • WECHAT_MCH_ID=1318592501
  • WECHAT_API_KEY=wx3e31b068be59ddc131b068be59ddc2
  • NEXT_PUBLIC_BASE_URL=https://your-domain.com

支付回调配置:

  1. 支付宝开放平台配置异步通知URL
  2. 微信商户平台配置支付回调URL

详细步骤请参考 DEPLOYMENT.md


六、系统完整功能清单

用户端功能

用户注册登录
书籍封面展示
目录浏览47章节
试读免费章节
购买单章节¥1/节)
购买整本书¥9.9
四种支付方式
支付后自动跳转微信群
分享专属邀请链接
生成推广海报
查看收益明细
申请提现
个人中心

管理端功能

管理员登录admin/key123456
数据仪表盘(订单/用户/收益统计)
内容管理(章节价格配置)
支付配置(微信/支付宝/USDT/PayPal
用户管理(列表/搜索/删除)
二维码管理(活码配置)
提现审核(批量处理)
系统设置(分销比例/价格)


七、技术栈总结

前端框架:

  • Next.js 16.0.10App Router
  • React 19
  • TypeScript 5.9.3
  • Tailwind CSS v4

UI组件

  • Radix UI无头组件库
  • Lucide React图标
  • Zustand状态管理

支付集成:

  • 支付宝手机网站支付MD5签名
  • 微信Native支付XML格式
  • 自研支付SDK服务类

开发工具:

  • Gray MatterMarkdown解析
  • Crypto签名加密

部署平台:

  • Vercel推荐香港/新加坡节点)

八、项目亮点

🎨 设计优秀

  • 苹果毛玻璃风格统一
  • 移动端完美适配
  • 深色主题护眼

💰 商业闭环完整

  • 内容付费
  • 私域引流
  • 分销裂变

🔐 安全可靠

  • 支付签名验证
  • 环境变量隔离
  • 权限控制完善

📱 用户体验流畅

  • 一键支付跳转
  • 自动解锁内容
  • 无缝跳转微信群

🚀 可扩展性强

  • 模块化代码结构
  • 支持多种支付方式
  • 易于添加新章节

项目状态 已完成100%,可直接部署到生产环境

建议下一步:按需接入永平版可选能力(定时任务、提现记录、地址管理、推广设置页等),见 开发文档/永平版优化对比与合并说明.md

最后更新时间2026-02-27
最后更新人:橙子 (智能助手)
项目交付状态 完整交付

近期更新:见 运营与变更.md 第七部分(开发进度同步)。


九、永平版优化合并迭代2026-02-20

9.1 对比范围

  • 主项目一场soul的创业实验(单 Next 仓,根目录 app/lib/book/miniprogram
  • 永平版一场soul的创业实验-永平多仓soul-api Go、soul-admin Vue、soul Next 在 soul/dist

9.2 已合并优化项

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

9.3 可选后续合并(见永平版优化对比与合并说明)

定时任务(订单同步/过期解绑)、提现待确认与记录 API、用户购买状态/阅读进度/地址 API、分销概览与推广设置页、忘记密码页与我的地址页、standalone 构建脚本、Prisma 等;主项目保持现有 CORS 与扁平 app 路由。


十、链路优化与 yongpxu-soul 对照2026-02-20

10.1 链路优化(不改文件结构)

  • 文档:已新增 开发文档/链路优化与运行指南.md,明确四条链路及落地方式:
    • 后台鉴权admin / key123456store + admin-auth 一致),登出可调 POST /api/admin/logout
    • 进群:支付成功后由前端根据 groupQrCode / 活码展示或跳转;配置来自 /api/config 与后台「二维码管理」(当前存前端 store刷新以接口为准
    • 营销策略:推广、海报、分销比例等以 api/referral/*api/db/config 及 store 配置为准;内容以 book/lib/book-data.ts 为准。
    • 支付create-order → 微信/支付宝 notify → 校验 → 进群/解锁内容;保持现有 app/api/payment/*lib/payment* 不变。
  • 协同:鉴权、进群、营销、支付可多角色并行优化,所有改动限于现有目录与文件,不新增一级目录。
  • 运行:以第一目录为基准,pnpm dev / 生产 build+standalone端口 3006详见 开发文档/本机运行文档.md 与链路指南内运行检查清单。

10.2 yongpxu-soul 分支变更要点(已对照)

  • 相对 soul-contentyongpxu-soul 主要增加部署与文档,业务代码与主项目一致。
    • 新增:scripts/deploy_baota.py开发文档/8、部署/宝塔配置检查说明.md开发文档/8、部署/当前项目部署到线上.md、小程序相关miniprogram 上传脚本、开发文档/小程序管理、开发文档/服务器管理)、开发文档/提现功能完整技术文档.mdlib/wechat-transfer.ts 等。
    • 删除/合并:大量历史部署报告与重复文档(如多份「部署完成」「升级完成」等),功能迭代记录合并精简。
  • 结论:业务链路(鉴权→进群→营销→支付)以第一目录现有实现为准yongpxu-soul 的修改用于部署方式、小程序发布、文档与运维,不改变主项目文件结构与上述四条链路的代码归属。
  • 可运行性:按《链路优化与运行指南》第七节检查清单自检后,项目可在不修改文件结构的前提下完成落地与运行。

10.3 运行检查已执行2026-02-20

  • 已执行:pnpm installpnpm run buildpnpm dev 下验证 GET /GET /api/config 返回 200。
  • 执行记录详见 开发文档/链路优化与运行指南.md 第八节。
  • 结论:构建与开发环境运行正常,链路就绪。

十一、下一步行动计划2026-02-20

优先级 行动项 负责模块 说明
P0 生产部署与回调配置 支付/部署 将当前分支部署至宝塔(或现有环境),配置微信/支付宝回调 URL 指向 /api/payment/wechat/notify/api/payment/alipay/notify,并验证支付→到账→进群展示。
P1 进群配置持久化(可选) 进群/配置 若需多环境或刷新不丢失:让 /api/config 或单独接口读取/写入 api/db/configpayment_config.wechatGroupUrl、活码链接;或后台「二维码管理」保存时调用 db 配置 API。
P1 后台「退出登录」对接 鉴权 app/admin/layout.tsx 将「返回前台」旁增加「退出登录」按钮,点击请求 POST /api/admin/logout 后跳转 /admin/login(若后续改为服务端 Cookie 鉴权即可生效)。
P2 Admin 密码环境变量统一(可选) 鉴权 lib/store.tsadminLogin 中从 process.env.NEXT_PUBLIC_ADMIN_USERNAME / NEXT_PUBLIC_ADMIN_PASSWORD 读取(或通过小 API 校验),与 lib/admin-auth.ts 一致。
P2 营销与内容迭代 营销/内容 在现有结构内更新:book/ 下 Markdown、lib/book-data.ts 章节与免费列表、api/referral/*api/db/config 分销/推广配置;后台「系统设置」「内容管理」按需调整。
P2 文档与分支同步 文档 定期将 yongpxu-soul 的部署/小程序/运维文档变更合并到主分支或文档目录,保持《链路优化与运行指南》《本机运行文档》与线上一致。

以上按 P0 → P1 → P2 顺序推进P0 完成即可上线跑通整条链路P1/P2 为体验与可维护性增强。


十二、永平落地2026-02 依据 cursor_1_14

任务 状态 说明
内容管理仅保留「API 接口」按钮 已完成 soul-admin ContentPage 源码改造,移除 5 按钮,新增 API 接口按钮
侧栏与推广中心页「交易中心」→「推广中心」 已完成 AdminLayout、DistributionPage 文案统一
分销:海报带用户 ID、复制文案去掉邀请码展示 已完成 referral.js scene 用 userId海报去掉邀请码文案
我的页:待领收益→我的收益 已完成 my.wxml 未登录卡片文案统一
后台与前台参数一致(绑定有效期、自动提现、免费章节) 已检查 推广设置、系统设置与 API 对齐
需求与文档整理 已完成 需求汇总需求清单、运营与变更第五部分、本推进表十二节
会员分润差异化(会员 20%/非会员 10% 已完成 computeOrderCommission推广设置页 vipOrderShareVip、vipOrderShareNonVip
VIP 角色管理、SetVipModal、VIP 排序 已完成 vip_roles 表、VipMembers 页、vip_activated_at/vip_sort
开发进度同步会议 已完成 2026-02-27 橙子同步至运营与变更第七部分

十三、找伙伴功能完善2026-03-08

任务 状态 说明
后台「找伙伴」统一入口页5 Tab 已完成 数据统计→找伙伴→资源对接→导师预约→团队招募
找伙伴统计 Tab 已完成 6 统计卡片 + 类型分布 + CKB 7 端点真实测试
匹配池选择VIP/完善/全部) 已完成 3 来源池 + 4 项完善度开关;显示各池人数
用户管理 ?pool= 参数筛选 已完成 支持 ?pool=vip/complete/all 跳转筛选
CKBJoin 写入 match_records 已完成 团队招募/资源对接 ckb/join 成功后同步写入
小程序「超级个体」改名「找伙伴」 已完成 match.js partner label 更新
当天已匹配不重复 已完成 MatchUsers 排除当天已匹配 matched_user_id
存客宝协作需求文档 已完成 4 条需求写入存客宝协作需求.md
CKB 测试"已存在"判定修正 已完成 前端:已存在/已加入也标为成功
匹配记录加载失败修复 已完成 后端 DBMatchRecordsList 对空用户做安全读取,避免 nil panic
存客宝右上角工作台 已完成 从独立 Tab 改为右上角入口;支持接口测试、配置保存、文档摘要
存客宝场景配置列表化 已完成 每个入口独立 apiUrl/apiKey/source/tags/siteTags/notes可保存到 ckb_config.routes
CKB 明细接口 已完成 新增 /api/db/ckb-leads支持已提交线索 / 有联系方式明细查看
存客宝入口位置调整 已完成 从主 Tab 改回右上角按钮入口,点击打开存客宝工作台
存客宝工作台子页化 已完成 概览 / 已提交线索 / 有联系方式 / 场景配置 / 接口测试 / API 文档 六块独立
AI 获客数据首页重构 已完成 数据统计页拆为「找伙伴数据 / AI 获客数据」,已提交线索和有联系方式可点开
本地测试数据插入能力 已完成 新增 /api/db/match-records/test资源对接/团队招募页可一键插入测试记录
Dashboard 增加匹配概览 已完成 首页数据概览新增「匹配次数」「匹配收益」

十四、内容管理深度优化2026-03-07 ~ 2026-03-09

14.1 排名算法可配置化03-07

任务 状态 说明
排名算法权重可编辑 已完成 阅读/新度/付款三权重可在后台直接修改,权重存 system_config
数据填充(点击量/付款数) 已完成 reading_progress + orders 表关联,排行榜显示点击量、付款数、热度
批量移动修复 已完成 修复「移动失败缺少ID」问题SectionIds 正确传递
2026每日派对干货板块一致性 已完成 新建/删除/编辑功能与其他板块保持一致
后台整体优化 已完成 界面美化、交互优化、暗色主题深度定制

14.2 内容管理五项修改03-08 第一批)

任务 状态 说明
删除「钩子设置」Tab → 新增「内容排行榜」Tab 已完成 排行榜按热度排序分页10节/页,显示点击数据
拖拽排序与后端同步修复 已完成 章节树拖拽排序结果正确写入数据库
未付费预览比例可配置 已完成 system_config 存 unpaid_preview_percent后台可修改
排名权重可编辑 + 精选推荐/首页置顶 已完成 置顶用 Star 图标标识pinned_section_ids 存配置
合并预览/编辑按钮 + 章节ID可编辑 已完成 单按钮打开编辑弹窗ID 字段可直接修改

14.3 内容管理五项修改03-08 第二批)

任务 状态 说明
Tab 顺序调整 已完成 章节管理 → 内容排行榜 → 内容搜索
置顶状态全局显示Star图标 已完成 章节树、排行榜、搜索结果均显示 Star
排名积分逻辑细化 已完成 最近更新30分递减/阅读量20分递减/付款数20分递减 + 手动覆盖
富文本编辑器升级 已完成 TipTap 编辑器,支持格式化/图片/表格/@提及/#链接标签
人物列表 + 链接标签管理 已完成 persons/link_tags 表 CRUD后台管理界面

14.4 内容管理三项修改03-09 第三批)

任务 状态 说明
排行榜操作改为「编辑文章」 已完成 原「付款记录」按钮移入编辑弹窗底部
章节ID修改确保保存成功 已完成 前端 originalId 机制 + 后端 newId 字段支持
付款记录用户ID/订单ID可点击跳转 已完成 用户名截短显示,点击跳转用户详情/订单详情

14.5 链接AI Tab03-09 第四批)

任务 状态 说明
「主人公」Tab → 「链接AI」Tab 已完成 链接人与事AI列表 + 链接标签管理
人物ID改为可选 已完成 名称必填ID自动生成后端兼容
链接标签新增「存客宝」类型 已完成 支持 url/miniprogram/ckb 三种类型
存客宝绑定配置面板 已完成 显示API地址和绑定计划跳转存客宝工作台
预填充数据 已完成 卡若/南风/远志/老墨/荷总/永平 + 神仙团队/Soul派对房/飞书中台/超级个体

十五、存客宝集成技术方案

15.1 概述

存客宝CKB是第三方获客工具通过 API 上报线索到微信生态中实现自动加好友/拉群。本项目在以下场景集成:

  1. 找伙伴功能:匹配成功 → 上报存客宝场景 → 自动加好友
  2. 内容管理「链接AI」:文章内 @人物 / #标签 → 点击跳转存客宝链接 → 进入流量池

15.2 核心 API

接口 方法 地址 说明
场景获客 POST https://ckbapi.quwanzhi.com/v1/api/scenarios 上报线索(手机号/微信号等)
线索查询 GET /v1/api/lead/query 按手机号/微信号查询状态(待开发)
批量统计 GET /v1/api/lead/stats 时间段内线索统计(待确认)
自动加好友 POST /v1/api/lead/add-friend 匹配后自动发起好友申请(待确认)

15.3 后台配置

  • 存客宝场景配置找伙伴 → 存客宝工作台 中管理 apiUrl/apiKey/source/tags 等
  • 内容链接绑定内容管理 → 链接AI → 存客宝绑定 面板配置计划绑定
  • 链接标签类型 = ckblink_tags 表 type 支持 url/miniprogram/ckb

15.4 数据库表

  • personsAI人物列表person_id, name, label
  • link_tags链接标签tag_id, label, url, type[url/miniprogram/ckb], app_id, page_path
  • system_config存客宝相关配置ckb_config.routes, ckb_api_key 等)

详细协作需求见 存客宝协作需求.md