二、项目与工程全景

备注

🏪 上一章告诉你”要做什么、不做什么”。这一章回答另一个问题：这套系统长什么样、各部分怎么协作、为什么必须这样组装。读完它，你不会立刻能动手部署，但你脑子里会有一张可以”按图索骥”的工程地图，后面每一步都能在地图上找到位置。

本教程后半段会用 saas-starter 作为默认业务 SaaS 示例：它不是替代 web-pay，而是扮演“真实业务系统”的角色，用来验证从 SaaS 下单到统一收银台、再到支付回调和会员订阅更新的完整闭环。

2.1 用一笔付款看清整套系统怎么协作

先不要去想”前端、后端、数据库、CI/CD”这些词。先想一笔最普通的付款，注意看每一步背后是哪个组件在干活：

步骤 用户感知 背后干活的组件
1 在小程序里看到商品或服务 小程序 / SaaS 业务前端
2 点击「购买」 小程序前端 → 支付网关后端
3 系统生成一张订单 支付网关后端 + 数据库
4 跳转到收款页面 统一收银台前端(pay.example.com)
5 选择微信 / 支付宝付款 收银台前端 → 支付网关后端 → 微信 / 支付宝
6 微信 / 支付宝告诉系统"付成功了" 支付平台 → 支付网关后端(回调)
7 订单状态变成"已支付" 支付网关后端 → 数据库
8 你打开后台能查到这笔订单 运营平台前端 + 运营平台后端 + 数据库

重要

✨ 这份教程的主线，就是把上面这 8 步全部串起来跑通。后面每一章其实都在解决其中一两步的真实配置。

新增概念图：一笔付款背后的组件协作

用一笔付款看清整套系统怎么协作

2.2 用「开一家线上小店」类比技术组件

如果上面那张表里”支付网关后端、运营平台、数据库”这些词仍然让你犯怵，可以先放下技术名词，用一个生活化的类比建立直觉：

小店里的角色 技术里对应什么 它负责什么
店面和菜单 小程序 / SaaS 业务前端 让用户看到商品、服务和购买入口
收银台 统一收银台前端 展示金额，让用户选择微信或支付宝付款
收银员和收银机 支付网关后端 生成订单、发起支付、接收支付结果
账本 数据库 保存订单、配置、支付状态
店长后台 运营平台前端 让你查订单、看应用、管配置
后台办事员 运营平台后端 给运营平台提供订单和配置数据
店铺地址 域名 让别人通过网址找到你的页面和接口
长期开机的电脑 云服务器 让后端程序一直在线运行
文件仓库 OBS / 对象存储 放前端页面文件和静态资源
加速配送网络 CDN 让用户更快打开前端页面
自动打包发货线 CodeArts / CI/CD 自动构建、上传和发布

小技巧

💡 后面所有章节里出现的技术词，几乎都能在这张表里找到对应的”小店角色”。一旦你忘记某个词的作用，就回到这张表上找它的店铺职责。

新增概念图：线上小店与技术组件对照

用开一家线上小店类比技术组件

2.3 整体架构图与主路径

下面这张图把”小店里的角色”换成真实的服务和地址。第一次看不懂没关系，等你完成几章配置后再回来，会变得越来越熟：

        flowchart LR
  MiniProgram["小程序 / SaaS 业务前端"] --> Cashier["统一收银台前端<br/>pay.example.com"]
  Cashier --> PayAPI["支付网关后端<br/>pay-api.example.com"]
  ManagerUI["运营平台前端<br/>paymanager.example.com"] --> ManagerAPI["运营平台后端<br/>paymanager-api.example.com"]
  ManagerAPI --> DB["PostgreSQL 数据库"]
  PayAPI --> DB
  ManagerAPI --> Redis["Redis"]
  PayAPI --> Redis
  ManagerAPI --> MQ["ActiveMQ"]
  PayAPI --> MQ
  PayAPI --> Channel["微信支付 / 支付宝"]
  Channel --> PayAPI

主路径(也就是真正发生一笔付款时数据怎么流):🔗

  1. 用户从小程序或业务前端发起支付。

  2. 系统把用户带到统一收银台(pay.example.com)。

  3. 收银台请求支付网关后端(pay-api.example.com)。

  4. 支付网关后端和微信 / 支付宝交互。

  5. 用户付款成功，支付平台回调到 pay-api.example.com。

  6. 支付网关后端把订单状态写入 PostgreSQL。

  7. 你打开运营平台(paymanager.example.com)从数据库读取订单。

警告

⚠️ 整张图里最容易出错的一条线是第 5 步:支付平台回调地址必须填到支付网关后端 API 域名(pay-api.example.com)，不能填到任何前端域名。这条规则会在后面的章节里反复出现。

新增概念图：支付主路径与回调写库

整体架构图与主路径

2.4 系统的两个面孔:收银台 vs 运营平台

整套系统有两个完全不同用途的前端，分别给不同的人看：

新增概念图：付款用户与老板看到的两个前端

统一收银台 🧾 — 给付款用户看。用户付款时看到金额、订单信息和微信 / 支付宝等支付方式：

统一收银台：选择支付方式

统一收银台：微信扫码支付

统一收银台：支付宝扫码支付

运营平台 📊 — 给你自己看。你可以查看应用、订单、支付流水和回调状态：

运营平台：数据看板与应用筛选

运营平台：支付订单与回调状态

重要

💡 部署提醒：这两个前端虽然都通过浏览器访问，但 部署位置完全不同——它们各自上传到独立的 OBS 桶，对应不同的 CDN 域名（收银台 pay.example.com、运营平台 paymanager.example.com）。后面「线上部署」那一章会反复区分这两套；业务上可以管理无限多个 SaaS，工程上收银台和运营平台各只需部署一份。

系统的两个面孔收银台与运营平台

2.5 为什么 OPC 需要「统一收银台 + 运营平台」

上面两个前端看起来只是「一个给用户付款、一个给你查单」。但对 一人公司（OPC）同时运营多个 SaaS 产品 来说，它们合起来构成的是一套 多 SaaS 支付管理平台——这才是本项目的核心卖点。

新增概念图：一商户多应用共用支付底座

2.5.1 没有统一平台时，你会遇到什么

假设你做了 3 个小产品：流浪猫档案小程序、在线课程网站、工具类 APP。如果 每个产品各自去接入微信 / 支付宝：

痛点 具体表现
重复申请与配置 每个产品单独填商户资料、配密钥、维护回调地址
收款分散 微信 / 支付宝后台只能按商户号看流水，无法按产品拆分
统计困难 月底算总营收要分别登录多个后台、手工加总
报税麻烦 收入分散在多处，按日期 / 按产品汇总都要自己拼 Excel
运维成本高 每上新一个 SaaS，支付链路从头搭一遍

对 OPC 来说，这等于 每做一个新产品，就多养一套支付系统——一个人根本忙不过来。

2.5.2 本项目的解法：一套平台，接入任意 SaaS

web-pay 采用的是经典的 「一商户 + 多应用」 模型：

你的一人公司（商户 mch_no）
├── 应用 A：喵呜档案小程序      → app_id_1
├── 应用 B：在线课程网站        → app_id_2
└── 应用 C：工具类 APP          → app_id_3
         │
         ▼
  共用一套支付网关 + 一套微信/支付宝商户资质
  共用统一收银台（pay.example.com）
  共用运营平台（paymanager.example.com）

任何小程序 / APP / 网站，只要在你名下创建一个「应用」，带上自己的 appId 调用统一下单接口，就能接入这套平台——不需要再单独去微信 / 支付宝开一套商户。

代码里的对应关系很清晰：

概念 数据库 / 代码 含义
收款主体 t_mch_info.mch_no OPC 通常只有 一个商户号，代表你的公司
每个 SaaS 产品 t_mch_app.app_id + app_name 每上线一个 SaaS，在运营平台新建一个应用
支付订单 t_pay_order.app_id 每笔付款都绑定来源应用，天然可按 SaaS 拆分
统一下单 POST /api/pay/unifiedOrder 各 SaaS 后端携带 mchNo + appId 发起支付
统一收银台 QR_CASHIER → pay.example.com/#/hub/{token} 所有 SaaS 的用户最终跳到 同一个收银台 选微信 / 支付宝

各 SaaS 业务前端只负责「发起购买」；真正对接微信 / 支付宝、处理回调、写订单的，始终是 同一套支付网关后端。微信 / 支付宝的商户密钥也只需在运营平台配置一次，新建应用时还可以 从模板复制支付配置，避免重复录入。

运营平台：多应用列表

2.5.3 运营平台：一人公司的「财务驾驶舱」

统一收银台解决的是 用户侧体验一致；运营平台解决的是 你作为老板怎么管钱。

在运营平台里，你可以：

  • 按应用筛选：只看「喵呜档案」或「在线课程」的收入，也可以不筛选看 全平台总计。

  • 按日期快速统计：近 7 日金额曲线、本周 / 本月汇总、每日成功 / 失败趋势——不用再去微信 / 支付宝后台分别导出。

  • 应用收入排行：后台直接按 app_id 聚合（selectAppRanking），一眼看出哪个 SaaS 最赚钱。

  • 订单与回调可查：每笔订单的支付状态、回调是否成功，在一个列表里按 appId 过滤即可排查。

  • 报税 / 营收核算更省事：选定日期范围 + 选定应用（或全选），导出就是该周期的收入明细；总收入和各 SaaS 分项都在同一张 t_pay_order 表里，不用再手工拼多个支付后台的数据。

对 OPC 而言，这意味着：产品可以一个个加，支付和管理始终只有一套。你专注做业务，营收统计、对账、报税所需的数据结构已经由平台帮你分好层。

重要

🎯 一句话总结卖点：把任意小程序 / APP / 网站的支付都接入此平台统一管理，可以 单独统计每个 SaaS 的收入，也可以 一眼看到总收入——而不是每个 SaaS 各自对接微信 / 支付宝、各自维护、各自算账。

运营平台：数据看板与应用筛选

2.6 跑通后能看到的工程画面

光有图和组件还不够，你需要知道主流程跑通的样子长什么样。完成主流程后，你应该能看到这些可验证的工程画面：

  • 浏览器能通过 HTTPS 打开统一收银台和运营平台。

  • 收银台能正确展示订单金额和支付方式。

  • 支付成功后，订单状态从”待支付”自动变成”已支付”。

  • 运营平台能看到应用、订单和支付流水。

  • 你关掉自己的电脑后，线上页面和后端服务依然能访问。

  • 服务器上 9216 / 9217 两个 Java 进程一直在线。

  • 后续改代码时，可以通过 CodeArts 流水线减少手工上传。

重要

✨ 这就是”工程闭环”的真正含义：不是只有一个页面能打开，而是从用户操作 → 支付平台 → 服务器后端 → 数据库 → 你的运营后台，每个环节都连得上、关得住、查得到。

新增概念图：主流程跑通后的可验证闭环

跑通后能看到的工程画面

2.7 为什么必须要这么多组件

新手常常会问：为什么不能只写一个小程序页面就上线？看完前面几节你应该已经有答案了。这里再正式回答一次。

一个真正能收款的小程序不是”一个页面”那么简单，它至少需要：🧩

  • 一个让用户付款的页面(收银台前端)。

  • 一个生成订单、对接支付平台的程序(支付网关后端)。

  • 一个保存订单的数据库(PostgreSQL)。

  • 一个长期开机帮你跑后端程序的服务器(云服务器)。

  • 一个让用户用网址找到你的入口(域名 + DNS + HTTPS)。

  • 一个让支付平台能回调过来的公网地址(还是后端 API 域名)。

  • 一个查订单的后台(运营平台前后端)。

  • 一个能让你以后更新部署的流程(手工脚本 / CI/CD)。

新增概念图：一人公司承担软件公司上线流程

2.7.1 这其实是一家软件公司的完整开发流程

换个角度看，上面这张清单不是故意把事情搞复杂——它恰恰是一家正规软件公司从 0 到 1 上线一个 SaaS 产品时，本来就要走通的全部环节。区别只在于：公司里这些活通常分给不同的人做，而你作为 OPC，一个人把这些角色都扛了起来。

软件公司里的角色 在本教程里对应什么 你实际在做什么
产品经理 第 1 章「要做什么、不做什么」+ 多 SaaS 规划 定方向：做什么 SaaS、接哪些支付、怎么管多个产品
UI 设计 收银台 / 运营平台前端页面 用户看到的付款页、你自己的数据看板（可借助 AI 生成与调整）
前端开发 zhcpay-ui-cashier + zhcpay-ui-manager + 你的 SaaS 小程序/网站 把页面做出来，并和后端 API 联调
后端开发 zhcpay-payment + zhcpay-manager 两个 Java 服务 统一下单、支付回调、订单入库、运营接口
测试 本地联调 + 沙箱支付 + 第 9 章支付验收清单 走通一笔真实付款，确认订单状态和回调都对
运维 / 部署 云服务器、宝塔、RDS、OBS/CDN、CodeArts 让服务 7×24 在线，域名和证书配好，改代码能自动发布
运营 运营平台查单、按应用看收入、管多个 SaaS 上线后日常看数据、对账、上新应用

在一家公司里，这往往是 7～10 人的协作链路；流程图、评审会、排期、交接文档一套接一套。而 OPC 的模式是：同一条链路还在，但中间不再有人帮你「翻译」和「填缝」——产品想清楚了要自己写进配置，页面改完要自己部署，支付回调地址填错要自己排查。

听起来负担很重？但时代已经变了：

  • AI 能帮你写页面、改接口、解释报错，大幅压缩「前端 / 后端 / 测试」的纯编码时间。

  • 本教程 把「产品经理该定的边界」和「运维该配的清单」都写成了可照着做的步骤，你不需要先读三年计算机再去碰服务器。

  • 统一支付平台（第 2.5 节的收银台 + 运营平台）让你不必每做一个 SaaS 就重搭一套支付——产品可以一个个加，底座只维护一份。

所以，跟着这份文档从零跑通，你完成的不是「学几个工具」，而是 第一次以一人公司的方式，走完一家软件公司上线 SaaS 的全流程。组件看起来多，是因为真实世界本来就需要这些环节；以前是一个团队分工，现在是 你 + AI + 这份操作手册 把分工合并成一个人的工作流。

小技巧

🚀 给 OPC 的一句实话：你不需要先变成「全栈工程师」才敢开一人公司。你需要的是 敢对一个真实产品负责到底——从「用户能不能付钱」到「我能不能在后台看到钱进来」，中间缺哪一环，就按章节补哪一环。跑通第一次之后，第二个、第三个 SaaS 会快很多；难的是从 0 到 1，不是从 1 到 N。

备注

🤖 AI 可以帮你写其中的页面或代码片段，但这些组件之间的连接、域名、证书、回调、配置一致性仍然需要你按顺序配置。这正是后面各章要带你做的事情——不是为难新手，而是替你把软件公司那套流程，压缩成 OPC 一个人也能执行的版本。

为什么必须要这么多组件

2.8 可信案例:喵呜档案

这套工程链路不是教程作者凭空写出来的。「喵呜档案」 是第一个按本教程同一套架构真实跑通、并持续在线运营的 SaaS 案例——支付、部署、数据库、后端服务、OBS / CDN、CI/CD 等环节都已验证可用。

2.8.1 先亲自体验一下

打开微信，在小程序搜索框输入 「喵呜档案」（同名即可），建议你先以普通用户身份逛一圈：

  • 图鉴：按喵星 / 区域浏览流浪猫档案，点进单猫看照片、健康、故事。

  • 打卡：志愿者选猫、选操作（喂养、换水、喂药、TNR 等），带图提交形成可追溯时间线。

  • 阳光账本：收支附凭证、可筛选、可公示——善款「从哪来、花到哪」对齐事实。

  • 云守护 / 主理人订阅：远程支持者低门槛参与；主理人按档位订阅管理工具权益。

目前已和多家高校动保社团合作，百余只流浪猫在线建档。你看到的不是 Demo，而是 OPC 一人把产品从 0 做到 1、并长期运维的真实结果。

喵呜档案

2.8.2 它解决的是什么问题

救助场景里，微信群 + 备忘录 + Excel 是常态——信息一多就乱：今天谁去喂了？这猫换过药没？上月捐款和支出对得上吗？

喵呜档案把 结构化档案、协作时间线、可审计账本、分层权限 收进一个产品里，面向高校社团、小区群、小团队。技术栈也很典型：

层级 技术 说明
前端 uni-app（Vue 3 + TypeScript） 微信小程序 / H5 / App 共用一套代码
业务后端 Java 17 + Spring Boot 3 独立 SaaS 服务，端口如 9219
数据 PostgreSQL 业务数据与支付订单分开存储
支付 本教程的 web-pay 统一支付平台 不直连微信 / 支付宝，走统一网关 + 收银台

对读这份文档的你来说，喵呜档案最重要的意义是：它就是一个「接入统一支付平台的 SaaS 应用」的活样本——不是理论图，而是你可以搜到、用到、并对照源码学习的真实产品。

2.8.3 它和 web-pay 是怎么连起来的

喵呜档案在 web-pay 运营平台里注册为 一个应用（app_id）；用户付款时，业务后端调用支付网关的统一下单接口，用户被带到 统一收银台 完成微信 / 支付宝付款，订单写入 t_pay_order 并带上 app_id，你在运营平台就能按「喵呜档案」单独查收入。

代码里的链路（源码见下方仓库）大致如下：

喵呜小程序 → 喵呜 Spring Boot 后端 → ZhcpayClient.unifiedOrder()
           → web-pay 支付网关 (zhcpay-payment)
           → 统一收银台 (pay.example.com) → 微信 / 支付宝
           → 回调 → 订单入库 → 运营平台可查

业务侧有两条典型付费场景，都走同一套支付底座：

  • 云守护：用户远程支持某只喵星，后端 createGuardianPayApi → 统一下单。

  • 主理人订阅：队长购买 TRIAL / STANDARD / PREMIUM 档位，后端 createSubscriptionPayApi → 统一下单。

小程序里支持 WX_LITE（微信内直接拉起支付）和 QR_CASHIER（跳转统一收银台）等方式——和你在第 2.5 节看到的「多 SaaS 共用一套收银台」是同一套机制。

新增概念图：喵呜档案接入 web-pay 支付底座

备注

📌 边界说明：喵呜档案在本文档里 只作为可信依据与参考实现——证明这条 OPC + 统一支付 + 云部署的链路工程上真实可跑通。主线仍然是教你 复现自己的 SaaS 小程序支付和部署闭环，而不是让你做一个流浪猫项目。你的行业可以是课程、工具、社群、任何 SaaS；底座和流程与喵呜档案相同，业务代码换成你的即可。

可信案例喵呜档案

到这里，你应该已经对整套系统有了一张完整的工程地图。下一章开始会进入真正动手的部分，从账号、成本与资料准备开始，逐项把图里的每个方框变成你自己的真实配置。