docs: record payment integration readiness
This commit is contained in:
@@ -2732,3 +2732,45 @@
|
||||
### 阻塞项
|
||||
- 本轮无 required 阻塞项。
|
||||
- 仍保留旧的非 required 项：外部告警 Webhook 未配置。
|
||||
|
||||
## 2026-05-18 商业化 Phase2 远程部署、0026 迁移与真实支付接入准备
|
||||
### 本轮完成项
|
||||
- 已从干净临时 worktree 部署当前已提交版本，避免把主工作区旧的未提交前端改动一起发布到开发测试服务器。
|
||||
- 后端 Docker 部署：
|
||||
- 结果：`PHASE7_BACKEND_DOCKER_DEPLOY_PASS`
|
||||
- 产物：`project-docs/qa-artifacts/phase7-backend-docker-deploy/2026-05-18T23-57-47`
|
||||
- 前端 Docker 部署：
|
||||
- 结果：`PHASE7_FRONTEND_DOCKER_DEPLOY_PASS`
|
||||
- 产物：`project-docs/qa-artifacts/phase7-frontend-docker-deploy/2026-05-19T00-01-02`
|
||||
- 远程 PostgreSQL 迁移确认：
|
||||
- `alembic current`：`20260518_0026 (head)`
|
||||
- `alembic_version.version_num`：`20260518_0026`
|
||||
- 已存在业务表：`commercial_orders`、`commercial_invoices`
|
||||
- 远程运行验证：
|
||||
- `GET http://192.168.3.90:8001/health`：HTTP 200，`status=ok`
|
||||
- `GET http://192.168.3.90:3003/billing`：HTTP 200
|
||||
- 正式巡检：`PHASE5_PRODUCTION_HEALTH_PASS`
|
||||
- 巡检产物：`project-docs/qa-artifacts/phase5-production-health/2026-05-19T00-05-50`
|
||||
- 已新增真实在线支付接入资料清单：
|
||||
- `project-docs/AI合同起草与审查助手-真实在线支付接入资料清单-2026-05-18.md`
|
||||
- 说明微信支付、支付宝分别需要哪些资料，哪些可以告诉 Codex，哪些必须只放服务器环境变量或安全目录。
|
||||
|
||||
### 当前状态
|
||||
- 商业化 Phase2 的“套餐、额度、试用到期、超额拦截、支付前订单、管理员确认收款、发票台账”已经部署到开发测试服务器并通过远程数据库验证。
|
||||
- 真实在线支付进入资料准备阶段；代码层下一刀应接入一个支付通道的创建支付单、回调验签、订单自动生效和前端支付入口。
|
||||
|
||||
### 未完成项
|
||||
- 微信支付 / 支付宝真实在线支付尚未接入，原因是缺少真实商户配置、证书/密钥和公网 HTTPS 回调地址。
|
||||
- 当前 `192.168.3.90` 是内网开发测试服务器，正式支付平台通常无法直接回调内网 IP，需要公网域名、反向代理或内网穿透。
|
||||
- 支付成功后的自动生效逻辑可复用现有 `commercial_orders` 激活链路，但仍需补支付平台验签、金额校验、重复回调幂等和订单超时处理。
|
||||
|
||||
### 需要用户配合
|
||||
- 先确定第一刀接入微信支付还是支付宝。
|
||||
- 准备公网 HTTPS 回调域名，或确认先使用内网穿透做联调。
|
||||
- 准备商户号、AppID、证书序列号等非密钥编号。
|
||||
- 将 API v3 密钥、商户私钥、支付宝应用私钥等敏感资料只配置到服务器环境变量或安全目录，不要发到聊天、不要写入文档、不要提交 Git。
|
||||
- 告诉 Codex 证书文件在服务器上的路径、回调域名、是否使用沙箱和订单超时时间。
|
||||
|
||||
### 阻塞项
|
||||
- 无部署和数据库 required 阻塞项。
|
||||
- 真实在线支付的 required 阻塞项是外部资料：商户通道、密钥证书、公网 HTTPS 回调地址。
|
||||
|
||||
@@ -0,0 +1,199 @@
|
||||
# AI合同起草与审查助手-真实在线支付接入资料清单
|
||||
|
||||
日期：2026-05-18
|
||||
|
||||
## 1. 当前结论
|
||||
|
||||
平台已经完成商业化闭环的前半段：
|
||||
|
||||
1. 套餐与收费边界已经有页面入口。
|
||||
2. 租户已经有试用、套餐、额度、到期和超额控制。
|
||||
3. 已经有支付前订单。
|
||||
4. 已经有管理员确认收款后自动生效。
|
||||
5. 已经有发票资料登记和开票台账。
|
||||
6. 开发测试服务器已经部署到远程 Docker，并确认远程 PostgreSQL 迁移到 `20260518_0026`。
|
||||
|
||||
当前真正还不能由 Codex 凭空完成的是“微信支付 / 支付宝真实在线收款”，因为这必须依赖真实商户资料、证书、密钥和平台可访问的回调地址。
|
||||
|
||||
## 2. 先接哪一种支付方式
|
||||
|
||||
建议第一刀只选一种先打通，不要微信和支付宝同时开工。
|
||||
|
||||
优先建议：
|
||||
|
||||
| 优先级 | 支付方式 | 适合场景 | 原因 |
|
||||
|---|---|---|---|
|
||||
| 1 | 微信支付 Native 二维码 | PC Web 页面扫码付款 | 对当前后台账单页最自然，用户生成订单后扫码付款 |
|
||||
| 2 | 支付宝电脑网站支付 | PC Web 页面跳转或扫码付款 | 对企业客户也常见，回调验签相对清晰 |
|
||||
| 3 | 微信 JSAPI / 小程序支付 | 公众号、小程序内支付 | 需要公众号或小程序入口，不适合当前第一刀 |
|
||||
| 4 | H5 支付 | 手机浏览器支付 | 需要移动端访问链路稳定后再做 |
|
||||
|
||||
建议当前选择：微信支付 Native 二维码，或者支付宝电脑网站支付。二选一先闭环。
|
||||
|
||||
## 3. 你需要配合准备什么
|
||||
|
||||
### 3.1 共同必须准备
|
||||
|
||||
| 资料 | 是否可以发给 Codex | 说明 |
|
||||
|---|---|---|
|
||||
| 支付方式选择 | 可以 | 先选微信支付或支付宝 |
|
||||
| 商户主体名称 | 可以 | 用于确认收款主体和发票主体 |
|
||||
| 正式收费价格 | 可以 | 当前套餐价格是否沿用方案中的建议价 |
|
||||
| 订单超时时间 | 可以 | 例如 30 分钟未支付自动失效 |
|
||||
| 是否先用沙箱 | 可以 | 有沙箱就先沙箱，没有再直接正式通道 |
|
||||
| 公网 HTTPS 域名 | 可以 | 支付平台回调通常不能使用 `192.168.3.90` 内网地址 |
|
||||
| 回调地址备案方式 | 可以 | 域名、反向代理、内网穿透或正式服务器 |
|
||||
| 退款规则 | 可以 | 是否允许后台发起退款，第一版可先不做自动退款 |
|
||||
|
||||
最关键的是公网 HTTPS 回调地址。当前开发测试服务器是内网 `192.168.3.90`，微信支付和支付宝的正式回调通常无法直接访问这个内网地址。
|
||||
|
||||
### 3.2 微信支付需要准备
|
||||
|
||||
| 资料 | 是否可以发给 Codex | 建议保存方式 |
|
||||
|---|---|---|
|
||||
| 微信支付商户号 | 可以 | 环境变量 `WECHAT_PAY_MCH_ID` |
|
||||
| 绑定的 AppID | 可以 | 环境变量 `WECHAT_PAY_APP_ID` |
|
||||
| 商户 API 证书序列号 | 可以 | 环境变量 `WECHAT_PAY_MCH_SERIAL_NO` |
|
||||
| API v3 密钥 | 不要发聊天，不要写 Git | 只放服务器环境变量 `WECHAT_PAY_API_V3_KEY` |
|
||||
| 商户私钥文件 | 不要发聊天，不要写 Git | 上传到服务器安全目录，只告诉文件路径 |
|
||||
| 平台证书或平台证书下载配置 | 不要发聊天，不要写 Git | 只放服务器安全目录 |
|
||||
| 回调通知地址 | 可以 | 例如 `https://你的域名/api/v1/payments/wechat/notify` |
|
||||
| 支付产品权限 | 可以说明是否已开通 | Native 支付、JSAPI 支付、H5 支付等 |
|
||||
|
||||
微信支付第一版建议需要的服务器环境变量：
|
||||
|
||||
```text
|
||||
WECHAT_PAY_ENABLED=true
|
||||
WECHAT_PAY_MCH_ID=你的商户号
|
||||
WECHAT_PAY_APP_ID=你的AppID
|
||||
WECHAT_PAY_MCH_SERIAL_NO=你的证书序列号
|
||||
WECHAT_PAY_API_V3_KEY=只放服务器环境变量
|
||||
WECHAT_PAY_PRIVATE_KEY_PATH=/opt/ai-contract-platform/secrets/wechat/apiclient_key.pem
|
||||
WECHAT_PAY_NOTIFY_URL=https://你的域名/api/v1/payments/wechat/notify
|
||||
```
|
||||
|
||||
### 3.3 支付宝需要准备
|
||||
|
||||
| 资料 | 是否可以发给 Codex | 建议保存方式 |
|
||||
|---|---|---|
|
||||
| 支付宝应用 AppID | 可以 | 环境变量 `ALIPAY_APP_ID` |
|
||||
| 支付宝网关 | 可以 | 正式环境或沙箱环境 |
|
||||
| 应用私钥 | 不要发聊天，不要写 Git | 上传到服务器安全目录，只告诉文件路径 |
|
||||
| 支付宝公钥或证书 | 不要发聊天，不要写 Git | 上传到服务器安全目录，只告诉文件路径 |
|
||||
| 回调通知地址 | 可以 | 例如 `https://你的域名/api/v1/payments/alipay/notify` |
|
||||
| 支付后返回地址 | 可以 | 例如 `https://你的域名/billing` |
|
||||
| 电脑网站支付权限 | 可以说明是否已开通 | 需要在支付宝开放平台确认 |
|
||||
|
||||
支付宝第一版建议需要的服务器环境变量：
|
||||
|
||||
```text
|
||||
ALIPAY_ENABLED=true
|
||||
ALIPAY_APP_ID=你的支付宝应用AppID
|
||||
ALIPAY_GATEWAY_URL=https://openapi.alipay.com/gateway.do
|
||||
ALIPAY_APP_PRIVATE_KEY_PATH=/opt/ai-contract-platform/secrets/alipay/app_private_key.pem
|
||||
ALIPAY_PUBLIC_KEY_PATH=/opt/ai-contract-platform/secrets/alipay/alipay_public_key.pem
|
||||
ALIPAY_NOTIFY_URL=https://你的域名/api/v1/payments/alipay/notify
|
||||
ALIPAY_RETURN_URL=https://你的域名/billing
|
||||
```
|
||||
|
||||
## 4. 哪些资料可以给我，哪些不能给
|
||||
|
||||
可以直接告诉我的：
|
||||
|
||||
1. 先接微信还是支付宝。
|
||||
2. 商户号、AppID、证书序列号这类非密钥编号。
|
||||
3. 是否有公网域名和 HTTPS。
|
||||
4. 回调地址准备用哪个域名。
|
||||
5. 套餐价格、订单超时时间、是否支持退款。
|
||||
6. 证书文件在服务器上的保存路径。
|
||||
|
||||
不要发到聊天、不要写进文档、不要提交 Git 的：
|
||||
|
||||
1. 微信支付 API v3 密钥。
|
||||
2. 微信支付商户私钥。
|
||||
3. 支付宝应用私钥。
|
||||
4. 支付宝公钥证书私密材料。
|
||||
5. 任何 `.pem`、`.key`、`.p12`、`.pfx` 文件内容。
|
||||
6. 支付平台后台账号密码、短信验证码、扫码登录二维码。
|
||||
|
||||
正确做法是：你把密钥和证书上传到服务器安全目录，我只使用“路径”和“环境变量名”接入程序，不在代码和文档里保存密钥内容。
|
||||
|
||||
## 5. 服务器建议目录
|
||||
|
||||
开发测试服务器可以先使用以下目录：
|
||||
|
||||
```text
|
||||
/opt/ai-contract-platform/secrets/wechat/
|
||||
/opt/ai-contract-platform/secrets/alipay/
|
||||
```
|
||||
|
||||
建议权限：
|
||||
|
||||
```text
|
||||
目录权限：700
|
||||
私钥文件权限：600
|
||||
所属用户：运行后端容器或 Docker 管理用户可读
|
||||
```
|
||||
|
||||
## 6. 回调地址为什么重要
|
||||
|
||||
真实支付不是“用户点了付款，前端自己判断成功”。
|
||||
|
||||
正确流程是：
|
||||
|
||||
1. 平台创建商业订单。
|
||||
2. 平台向微信或支付宝发起支付请求。
|
||||
3. 用户扫码或跳转付款。
|
||||
4. 微信或支付宝主动请求平台回调地址。
|
||||
5. 平台验签通过后，把订单标记为已支付。
|
||||
6. 平台自动升级租户套餐和额度。
|
||||
7. 前端账单页显示订单已生效。
|
||||
|
||||
如果支付平台访问不到我们的回调地址，系统就无法自动确认真实收款。当前 `192.168.3.90` 是内网地址，所以正式支付回调需要公网 HTTPS 域名、反向代理或内网穿透方案。
|
||||
|
||||
## 7. 第一版真实支付开发闭环
|
||||
|
||||
拿到资料后，建议按下面顺序实施：
|
||||
|
||||
1. 只启用一个支付通道。
|
||||
2. 后端补支付配置读取和启动前检查。
|
||||
3. 后端补创建支付单接口。
|
||||
4. 后端补支付平台回调接口。
|
||||
5. 后端补验签、金额校验、订单状态幂等处理。
|
||||
6. 支付成功后复用现有订单生效逻辑，自动升级套餐和额度。
|
||||
7. 前端账单页从“管理员确认收款”升级为“生成支付二维码 / 去支付 / 查询支付状态”。
|
||||
8. 回调成功后前端显示“已支付并生效”。
|
||||
9. 补测试：未配置密钥、金额不一致、重复回调、伪造回调、订单超时。
|
||||
10. 部署到开发测试服务器，跑一次真实沙箱或小额正式支付。
|
||||
|
||||
## 8. 当前已经完成的部署验证
|
||||
|
||||
本轮已完成开发测试服务器部署验证：
|
||||
|
||||
1. 后端 Docker 部署通过：`PHASE7_BACKEND_DOCKER_DEPLOY_PASS`
|
||||
2. 前端 Docker 部署通过：`PHASE7_FRONTEND_DOCKER_DEPLOY_PASS`
|
||||
3. 远程 Alembic 版本：`20260518_0026`
|
||||
4. 远程 PostgreSQL 已存在：
|
||||
- `commercial_orders`
|
||||
- `commercial_invoices`
|
||||
5. 后端健康检查：`http://192.168.3.90:8001/health` 返回 200
|
||||
6. 前端账单页：`http://192.168.3.90:3003/billing` 返回 200
|
||||
7. 正式巡检脚本通过：`PHASE5_PRODUCTION_HEALTH_PASS`
|
||||
|
||||
## 9. 你现在最需要做的三件事
|
||||
|
||||
第一，先决定第一刀接微信支付还是支付宝。
|
||||
|
||||
第二，确认有没有公网 HTTPS 域名。如果没有，需要先决定：
|
||||
|
||||
1. 临时内网穿透测试；
|
||||
2. 先上正式域名和反向代理；
|
||||
3. 先只做支付接口代码，等域名准备好再做真实回调联调。
|
||||
|
||||
第三，把对应商户资料准备好。密钥和证书不要发给我，只上传到服务器安全目录，然后告诉我：
|
||||
|
||||
1. 使用哪个支付通道；
|
||||
2. 非密钥编号；
|
||||
3. 证书文件路径；
|
||||
4. 回调域名；
|
||||
5. 是否使用沙箱。
|
||||
Reference in New Issue
Block a user