# 二、项目与工程全景
```{note}
🏪 上一章告诉你"要做什么、不做什么"。这一章回答另一个问题：**这套系统长什么样、各部分怎么协作、为什么必须这样组装**。读完它，你不会立刻能动手部署，但你脑子里会有一张可以"按图索骥"的工程地图，后面每一步都能在地图上找到位置。
```
本教程后半段会用 `saas-starter` 作为默认业务 SaaS 示例：它不是替代 web-pay，而是扮演“真实业务系统”的角色，用来验证从 SaaS 下单到统一收银台、再到支付回调和会员订阅更新的完整闭环。
## 2.1 用一笔付款看清整套系统怎么协作
先不要去想"前端、后端、数据库、CI/CD"这些词。先想一笔最普通的付款，**注意看每一步背后是哪个组件在干活**：
| 步骤 | 用户感知 | 背后干活的组件 |
| --- | --- | --- |
| 1 | 在小程序里看到商品或服务 | 小程序 / SaaS 业务前端 |
| 2 | 点击「购买」 | 小程序前端 → 支付网关后端 |
| 3 | 系统生成一张订单 | 支付网关后端 + 数据库 |
| 4 | 跳转到收款页面 | 统一收银台前端(`pay.example.com`) |
| 5 | 选择微信 / 支付宝付款 | 收银台前端 → 支付网关后端 → 微信 / 支付宝 |
| 6 | 微信 / 支付宝告诉系统"付成功了" | 支付平台 → 支付网关后端(回调) |
| 7 | 订单状态变成"已支付" | 支付网关后端 → 数据库 |
| 8 | 你打开后台能查到这笔订单 | 运营平台前端 + 运营平台后端 + 数据库 |
```{important}
✨ 这份教程的主线，就是把上面这 8 步**全部串起来跑通**。后面每一章其实都在解决其中一两步的真实配置。
```
## 2.2 用「开一家线上小店」类比技术组件
如果上面那张表里"支付网关后端、运营平台、数据库"这些词仍然让你犯怵，可以先放下技术名词，用一个生活化的类比建立直觉：
| 小店里的角色 | 技术里对应什么 | 它负责什么 |
| --- | --- | --- |
| 店面和菜单 | 小程序 / SaaS 业务前端 | 让用户看到商品、服务和购买入口 |
| 收银台 | 统一收银台前端 | 展示金额，让用户选择微信或支付宝付款 |
| 收银员和收银机 | 支付网关后端 | 生成订单、发起支付、接收支付结果 |
| 账本 | 数据库 | 保存订单、配置、支付状态 |
| 店长后台 | 运营平台前端 | 让你查订单、看应用、管配置 |
| 后台办事员 | 运营平台后端 | 给运营平台提供订单和配置数据 |
| 店铺地址 | 域名 | 让别人通过网址找到你的页面和接口 |
| 长期开机的电脑 | 云服务器 | 让后端程序一直在线运行 |
| 文件仓库 | OBS / 对象存储 | 放前端页面文件和静态资源 |
| 加速配送网络 | CDN | 让用户更快打开前端页面 |
| 自动打包发货线 | CodeArts / CI/CD | 自动构建、上传和发布 |
```{tip}
💡 后面所有章节里出现的技术词，几乎都能在这张表里找到对应的"小店角色"。一旦你忘记某个词的作用，就回到这张表上找它的店铺职责。
```
## 2.3 整体架构图与主路径
下面这张图把"小店里的角色"换成真实的服务和地址。第一次看不懂没关系，等你完成几章配置后再回来，会变得越来越熟：
```mermaid
flowchart LR
MiniProgram["小程序 / SaaS 业务前端"] --> Cashier["统一收银台前端
pay.example.com"]
Cashier --> PayAPI["支付网关后端
pay-api.example.com"]
ManagerUI["运营平台前端
paymanager.example.com"] --> ManagerAPI["运营平台后端
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`)从数据库读取订单。
```{warning}
⚠️ **整张图里最容易出错的一条线**是第 5 步:支付平台回调地址必须填到支付网关后端 API 域名(`pay-api.example.com`)，不能填到任何前端域名。这条规则会在后面的章节里反复出现。
```
## 2.4 系统的两个面孔:收银台 vs 运营平台
整套系统有两个完全不同用途的前端，**分别给不同的人看**：
**统一收银台** 🧾 — 给付款用户看。用户付款时看到金额、订单信息和微信 / 支付宝等支付方式：
**运营平台** 📊 — 给你自己看。你可以查看应用、订单、支付流水和回调状态：
```{important}
💡 **部署提醒**：这两个前端虽然都通过浏览器访问，但 **部署位置完全不同**——它们各自上传到独立的 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 采用的是经典的 **「一商户 + 多应用」** 模型：
```text
你的一人公司（商户 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 而言，这意味着：**产品可以一个个加，支付和管理始终只有一套**。你专注做业务，营收统计、对账、报税所需的数据结构已经由平台帮你分好层。
```{important}
🎯 **一句话总结卖点**：把任意小程序 / APP / 网站的支付都接入此平台统一管理，可以 **单独统计每个 SaaS 的收入**，也可以 **一眼看到总收入**——而不是每个 SaaS 各自对接微信 / 支付宝、各自维护、各自算账。
```
## 2.6 跑通后能看到的工程画面
光有图和组件还不够，你需要知道**主流程跑通的样子**长什么样。完成主流程后，你应该能看到这些**可验证的工程画面**：
- 浏览器能通过 HTTPS 打开统一收银台和运营平台。
- 收银台能正确展示订单金额和支付方式。
- 支付成功后，订单状态从"待支付"自动变成"已支付"。
- 运营平台能看到应用、订单和支付流水。
- 你关掉自己的电脑后，线上页面和后端服务依然能访问。
- 服务器上 `9216` / `9217` 两个 Java 进程一直在线。
- 后续改代码时，可以通过 CodeArts 流水线减少手工上传。
```{important}
✨ 这就是"工程闭环"的真正含义：**不是只有一个页面能打开**，而是从用户操作 → 支付平台 → 服务器后端 → 数据库 → 你的运营后台，每个环节都连得上、关得住、查得到。
```
## 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 + 这份操作手册** 把分工合并成一个人的工作流。
```{tip}
🚀 **给 OPC 的一句实话**：你不需要先变成「全栈工程师」才敢开一人公司。你需要的是 **敢对一个真实产品负责到底**——从「用户能不能付钱」到「我能不能在后台看到钱进来」，中间缺哪一环，就按章节补哪一环。跑通第一次之后，第二个、第三个 SaaS 会快很多；**难的是从 0 到 1，不是从 1 到 N**。
```
```{note}
🤖 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`，你在运营平台就能按「喵呜档案」单独查收入。
代码里的链路（源码见下方仓库）大致如下：
```text
喵呜小程序 → 喵呜 Spring Boot 后端 → ZhcpayClient.unifiedOrder()
→ web-pay 支付网关 (zhcpay-payment)
→ 统一收银台 (pay.example.com) → 微信 / 支付宝
→ 回调 → 订单入库 → 运营平台可查
```
业务侧有两条典型付费场景，都走同一套支付底座：
- **云守护**：用户远程支持某只喵星，后端 `createGuardianPayApi` → 统一下单。
- **主理人订阅**：队长购买 TRIAL / STANDARD / PREMIUM 档位，后端 `createSubscriptionPayApi` → 统一下单。
小程序里支持 `WX_LITE`（微信内直接拉起支付）和 `QR_CASHIER`（跳转统一收银台）等方式——和你在第 2.5 节看到的「多 SaaS 共用一套收银台」是同一套机制。
```{note}
📌 **边界说明**：喵呜档案在本文档里 **只作为可信依据与参考实现**——证明这条 OPC + 统一支付 + 云部署的链路工程上真实可跑通。主线仍然是教你 **复现自己的 SaaS 小程序支付和部署闭环**，而不是让你做一个流浪猫项目。你的行业可以是课程、工具、社群、任何 SaaS；**底座和流程与喵呜档案相同，业务代码换成你的即可**。
```
---
到这里，你应该已经对整套系统有了一张完整的工程地图。下一章开始会进入真正动手的部分，从**账号、成本与资料准备**开始，逐项把图里的每个方框变成你自己的真实配置。