# 四方聚合支付系统 · 项目计划书

| 项目 | 内容 |
| --- | --- |
| 项目名称 | 四方聚合支付系统(暂定代号:JiaMeng Pay,佳梦支付) |
| 建设单位 | 四川佳梦云网络科技有限公司 |
| 文档版本 | V1.3 |
| 编制日期 | 2026-09-14 |
| 文档状态 | 已按评审意见修订,待批准 |

### 变更记录

| 版本 | 日期 | 变更内容 |
| --- | --- | --- |
| V1.0 | 2026-09-14 | 初稿 |
| V1.1 | 2026-09-14 | 按评审意见落定:通道范围(微信原生/支付宝原生/汇付天下/富友)、品牌 Logo 与主色、阿里云短信、仅 Web+H5、自有聚合收银台、腾讯云轻量服务器+宝塔部署、全站中英文双语;调整部署架构(一期以 Redis Stream 替代 RabbitMQ)与性能指标 |
| V1.2 | 2026-09-14 | 新增**投诉中心**子系统:微信/支付宝投诉 API 同步 + 消费者站内投诉 + 处理流程与 SLA + 商户端/服务商端近 7 天投诉率统计 + 阈值预警与风控联动;通道插件契约新增可选投诉能力位;P2 周期 6 周调整为 7 周,上线目标顺延至 2027 年 2 月下旬 |
| V1.3 | 2026-09-14 | 细化消费者站内投诉动线:升级为**消费者服务页**(订单查询 + 投诉提交 + 进度跟踪,免注册、中英双语);投诉入口四类预留(收银台支付成功页 / 消费者订单查询页 / 带商户标识的投诉二维码物料 / 商户系统 API 短链);消费者短信回执(可选)与"确认解决/仍有异议"处理闭环 |

---

## 1. 项目概述

### 1.1 项目背景与定位

本项目为"四方支付平台":即聚合支付技术服务平台。平台向上承接商户(及商户的服务商)的收款、退款、代付、进件等业务需求,向下对接持牌第三方支付公司与微信支付、支付宝原生官方通道,统一封装成标准化的 API、自有品牌聚合收银台与管理后台对外输出。

平台定位为**纯技术服务与信息聚合平台**,自身不触碰、不清算、不截留任何交易资金(详见第 2.4 节合规模型),以规避"二清"等无证经营支付业务的法律风险。

### 1.2 建设目标

1. 聚合微信支付、支付宝、QQ钱包等多种支付方式,支持扫码(主扫/被扫)、H5、JSAPI、小程序等主流支付场景,对外提供平台**自有品牌的聚合收银台**。
2. 首发通道四条:**微信支付原生直连、支付宝原生直连、汇付天下(聚合)、富友支付(聚合)**;QQ钱包、云闪付等经汇付/富友聚合通道承载。
3. 支持标准化的 **API 代付/转账**能力(以汇付、富友的代付/付款能力为主)。
4. 支持**商户进件**(商户入驻申请),覆盖汇付/富友入网 API;平台具备微信服务商/支付宝 ISV 资质后可叠加原生进件(见 5.6 节)。
5. 完整的**服务商(代理)体系**:服务商仅能由平台后台开通,不可自助注册;可发展、管理下属商户并参与分润。
6. 商户支持自助注册,但须满足以下条件之一:平台后台开放自助注册权限(全局开关,可配审核策略),或通过服务商邀请(邀请码/专属链接)注册并绑定该服务商。
7. 平台、服务商、商户三端权限**细粒度 RBAC 管理**,支持自定义角色、子账号、数据范围隔离。
8. 核心功能(支付通道、通知、快捷登录、风控扩展等)**全部插件化**,并提供带完整注释的 **Demo 插件 + 插件开发脚手架 + 开发文档**,使公司内外部开发者可按规范自行开发适配插件。
9. 支持**快捷登录**(阿里云短信验证码、运营商一键登录、微信扫码)。
10. 支持**微信公众号模板消息通知**与**邮件通知**,通知事件、模板、接收人均可视化配置。
11. **投诉中心**:经 API 同步微信/支付宝侧商户投诉;支持消费者在平台站内直接对订单投诉(不依赖微信/支付宝内入口);商户端与服务商端均可见**近 7 天投诉率**,支持阈值预警与风控联动。
12. 全站界面**不使用任何 Emoji 表情**,图标统一采用 SVG 方案;三端后台与收银台支持**中英文双语切换**;整体安全性达到资金级标准。

### 1.3 建设范围

| 端 | 说明 |
| --- | --- |
| 平台管理后台(Web) | 面向平台运营方:商户/服务商/通道/插件/订单/投诉/分润/风控/对账/通知/系统管理,中英双语 |
| 服务商后台(Web) | 面向服务商:名下商户管理、交易统计、分润报表、协助进件、投诉查看、权限管理,中英双语 |
| 商户后台(Web) | 面向商户:应用与密钥、订单、退款、代付、投诉处理、对账、员工子账号,中英双语 |
| 开放 API | 面向商户系统:统一下单、查询、退款、代付、投诉查询(可选)、回调通知、进件(可选) |
| 聚合收银台(H5) | **平台自有品牌**收银页,中英双语,自动识别环境拉起对应支付方式 |
| 消费者服务页(H5) | 无需注册:订单支付状态查询、站内投诉提交(凭平台订单号)、投诉进度跟踪(凭投诉单号),中英双语,含凭证上传 |
| API 文档站 | 在线接口文档、错误码、SDK 与示例下载 |
| 插件运行时与插件包 | 通道/通知/登录/扩展四类插件,含 Demo 插件与开发规范 |

本期**仅建设 Web 与 H5,不含任何原生 APP**(商户请求中的 APP 支付方式作为 API 能力保留,由商户自己的 APP 调用)。

### 1.4 名词定义

| 名词 | 定义 |
| --- | --- |
| 四方平台 | 本系统,聚合技术服务平台,不触碰资金 |
| 三方 | 持牌第三方支付公司,本期为汇付天下、富友支付 |
| 原生 | 微信支付、支付宝官方接口直连 |
| 服务商 | 由平台开通的代理机构,可发展商户并按约定比例分润 |
| 商户 | 使用平台收付款能力的企业或个体经营者 |
| 进件 | 向通道提交商户入驻申请并开通收款权限的流程 |
| 代付 | 商户通过 API 发起的转账/付款(至银行卡等,以通道能力为准) |
| 分润 | 服务商按约定比例从交易手续费中获得的服务报酬 |
| 渠道投诉 | 消费者在微信支付/支付宝侧发起的商户投诉 |
| 站内投诉 | 消费者直接在平台投诉页对订单发起的投诉(不在微信/支付宝内) |

---

## 2. 业务模型与角色设计

### 2.1 业务拓扑

```mermaid
graph TD
    M[商户系统 / 收银台] -->|统一下单 API| P[四方平台 JiaMeng Pay]
    SP[服务商] -->|邀请注册 / 协助进件| M
    C[消费者] -->|消费者服务页: 站内投诉/订单查询/进度跟踪| P
    P -->|插件: 原生直连| WX[微信支付 V2/V3]
    P -->|插件: 原生直连| ALI[支付宝 OpenAPI]
    P -->|插件: 聚合通道| HF[汇付天下]
    P -->|插件: 聚合通道| FY[富友支付]
    WX -.->|投诉API同步| P
    ALI -.->|投诉API同步| P
    P -->|支付结果回调验签| M
    P -->|模板消息 / 邮件| N1[平台 / 服务商 / 商户管理员]
```

QQ钱包与云闪付等支付方式由汇付/富友聚合通道在上图通道内透出,平台不单独直连。

### 2.2 角色与开通规则(硬性约束)

| 角色 | 开通方式 | 说明 |
| --- | --- | --- |
| 平台账号 | 仅超级管理员后台创建 | 平台后台强制双因素登录(2FA),可配置后台访问 IP 白名单 |
| 服务商 | **仅平台后台开通**,系统不提供任何服务商自助注册入口(前端无页面、后端无注册接口) | 开通时录入企业资料、管理员账号、分润比例、可用通道与费率模板;支持邀请码方式由平台预生成后线下交付 |
| 商户 | 方式一:平台后台直接开通;方式二:全局"商户自助注册"开关开启后自助注册(注册后需审核,策略可配:人工审核/自动通过);方式三:通过服务商邀请码或专属注册链接注册,注册即绑定该服务商 | 三种方式互斥共存,由后台配置决定;绑定服务商的商户继承服务商的费率模板与通道权限,可被平台单独覆写 |

### 2.3 权限体系(细粒度 RBAC)

权限模型:用户 - 角色 - 权限节点 - 数据范围 四层。

- **权限节点**:`模块:资源:操作`,例如 `order:query:list`、`transfer:apply:submit`、`complaint:reply:submit`,平台内置约 200+ 节点,后台可勾选组合。
- **数据范围**:全部数据 / 本服务商及名下商户 / 本商户 / 仅本人创建(收银员仅能看自己班次订单等场景)。
- **三端内置角色**(均支持自定义新增与节点微调):

| 端 | 内置角色 | 权限要点 |
| --- | --- | --- |
| 平台 | 超级管理员 / 运营 / 财务 / 风控 / 客服 | 超管全量;运营管商户服务商通道;财务管对账结算代付复核;风控管规则黑白名单与投诉处置;客服只读+订单备注+投诉回复 |
| 服务商 | 服务商管理员 / 商务 / 财务 / 普通员工 | 管理员管名下商户与子账号;商务仅名下商户发展与协助进件;财务仅分润与报表;投诉默认只读+协助(可配) |
| 商户 | 商户管理员 / 收银员 / 财务 / 开发者 | 管理员全量(不含删除商户);收银员仅订单查询与退款申请(可关);财务仅对账与代付发起;开发者仅应用密钥与 API 文档;投诉处理可分配给管理员或客服子账号 |

- 服务商可创建子账号并分配上述服务商角色;商户同理。所有敏感操作(修改密钥、修改结算信息、代付复核)写审计日志。

### 2.4 资金与合规模型(红线设计)

1. 交易资金一律由持牌机构(微信/支付宝/汇付/富友)直接清算至商户或服务商指定的合规账户,平台账户**不出现任何形式的资金沉淀、截留、代收代付**。
2. 分润不通过平台转账实现,而通过:(a) 持牌机构的分账/分润产品(汇付、富友均提供),或 (b) 平台与服务商签署技术服务协议后按账期开票结算技术服务费。系统内仅做分润**记账、对账与报表**,不产生资金指令。
3. 商户进件执行实名 KYC(营业执照、法人身份证、结算卡三要素/四要素校验),拒绝为无证、冒名、异常商户进件。
4. 风控内置可疑交易监测与投诉率监测(见第 10.7 节),对明确违法场景(赌博、诈骗等黑产特征)自动拦截、留痕并支持导出配合调查。
5. 数据合规:遵循《数据安全法》《个人信息保护法》,敏感字段加密存储、展示脱敏、留存期限可配、导出审批。

---

## 3. 总体架构

### 3.1 架构图

```mermaid
flowchart TB
    subgraph Client[接入层]
        CA[商户系统] --> GW[Nginx / WAF / 限流 宝塔托管]
        CB[聚合收银台 H5] --> GW
        CB2[消费者服务页 H5: 订单查询/投诉/进度跟踪] --> GW
        CC[平台/服务商/商户后台] --> GW
    end
    GW --> APP[JiaMeng Pay 应用 模块化单体 Spring Boot 集群]
    subgraph Core[核心模块]
        ACC[账户与权限中心 RBAC]
        ORD[订单中心 状态机/幂等]
        CMP[投诉中心 同步/站内/投诉率]
        ROUTE[渠道路由引擎]
        TRANS[代付中心]
        ONB[进件中心]
        PS[分润记账]
        RISK[风控引擎]
        EVT[事件总线]
        NOTI[通知中心]
        OPEN[开放API 签名/防重放]
    end
    APP --> Core
    APP --> PR[插件运行时 PF4J: 通道/通知/登录/扩展]
    APP --> RD[(Redis 7 缓存/锁/限流/幂等/Stream队列)]
    APP --> DB[(MySQL 8)]
    APP --> FS[对象存储 腾讯云COS 进件与投诉影像等]
    PR --> CH[微信/支付宝原生 + 汇付/富友]
    NOTI --> MP[微信公众号模板消息]
    NOTI --> MAIL[SMTP 邮件]
    MON[Prometheus + Grafana 单机] -.-> APP
```

说明:一期以 **Redis Stream** 承担异步队列职责(商户回调通知、通知发送、对账与投诉同步任务),降低轻量服务器资源占用;代码层抽象消息队列接口,数据量增长后可平滑切换 RabbitMQ/RocketMQ,无需改动业务代码。

### 3.2 关键流程

**支付主流程(时序):**

```mermaid
sequenceDiagram
    participant M as 商户系统
    participant P as 平台
    participant C as 通道插件
    participant U as 用户
    M->>P: 统一下单(签名: HMAC-SHA256/RSA2 + 时间戳 + 随机数)
    P->>P: 验签/防重放/风控/幂等检查(out_trade_no 唯一)
    P->>P: 路由引擎选通道(费率/成功率/限额/权重/熔断)
    P->>C: 通道下单
    C-->>P: 支付参数(二维码/跳转链接/JSAPI参数/收银台URL)
    P-->>M: 返回支付参数(含签名)
    U->>C: 完成支付
    C->>P: 异步回调(平台回调网关,统一入口)
    P->>P: 验签/金额比对/订单状态机流转(仅待支付->已支付,幂等)
    P->>M: 商户异步通知(带签名, 阶梯重试最多 12 次)
    P->>P: 事件总线 -> 通知插件(模板消息/邮件)、分润记账、统计
```

**投诉处理流程:** 渠道投诉经插件定时拉取与回调通知同步入库(幂等去重) / 消费者经站内投诉页提交 -> 分派商户处理人 -> 商户回复(渠道内投诉经插件回传微信/支付宝侧) -> 消费者补充或确认 -> 已解决/已关闭;超 SLA 自动升级通知服务商与平台;投诉率命中阈值触发预警与风控动作(见 5.8)。

**代付流程:** 商户发起代付申请(经汇付/富友付款通道) -> 风控规则校验(金额阈值/频次/黑白名单) -> 可配置的二级人工复核 -> 调用通道代付接口 -> 状态轮询 + 回调双确认 -> 通知商户与相关人员。

**进件流程:** 商户/服务商填写资料并上传影像件 -> 平台初审 -> 提交汇付/富友入网 API -> 轮询 + 回调同步状态 -> 审核结果通知(模板消息/邮件) -> 通过后自动生成通道配置并开通收款。

### 3.3 技术选型

| 层 | 选型 | 理由 | 备选 |
| --- | --- | --- | --- |
| 后端 | Java 17 + Spring Boot 3.2(模块化单体) | 资金级生态成熟、类型安全、审计友好;单进程部署契合轻量服务器 | Go / PHP 8.3(开发快但插件隔离与安全基建弱) |
| 插件框架 | PF4J + Spring 集成 | 成熟的动态插件加载(安装/卸载/升级)、扩展点机制 | 自研 ClassLoader 隔离(成本高,不建议) |
| ORM | MyBatis-Plus | SQL 可控、便于审计与性能优化 | JPA |
| 数据库 | MySQL 8.0(宝塔托管,数据盘独立) | 事务可靠 | PostgreSQL |
| 缓存/队列/限流 | Redis 7(缓存 + 分布式锁 + 令牌桶限流 + Stream 队列) | 一组件多能,降低单机内存占用;队列接口抽象,可平滑换 RabbitMQ | RabbitMQ(数据量上来后引入) |
| 前端 | Vue 3 + TypeScript + Vite + Element Plus + Pinia + vue-i18n | 三端后台单工程多入口,生态成熟,i18n 开箱即用 | React + Ant Design |
| 图标 | 自建 SVG Sprite(vite-svg-icons)+ 离线 Iconify SVG 包 | 全站无 Emoji,图标矢量化、可主题染色 | — |
| 网关 | Nginx(宝塔托管,含 WAF 规则与限流) | HTTPS 终结、静态、负载 | APISIX(远期) |
| 对象存储 | 腾讯云 COS | 进件/投诉影像、对账单文件,与轻量同账号同地域 | MinIO 自建 |
| 部署 | 腾讯云轻量服务器 + 宝塔面板 | 见 3.4 节部署架构 | K8s(远期多节点) |
| 监控 | Prometheus + Grafana(单机容器)+ 宝塔监控 | 指标+日志+告警闭环,告警接入通知中心 | ELK(远期) |
| CI/CD | GitLab CI / GitHub Actions 产出 Jar 与前端产物,宝塔部署 | 与宝塔工作流契合 | Jenkins |

> 插件对外契约(配置结构、回调事件、API 语义)与语言无关;若未来需要非 Java 插件,可通过 sidecar HTTP 插件桥接,本期不实现。

### 3.4 部署架构(腾讯云轻量服务器 + 宝塔面板)

**拓扑(一期单机):**

```
腾讯云轻量服务器(建议 4核8G 起,系统盘+数据盘,Ubuntu 22.04 / CentOS Stream 9)
└── 宝塔面板
    ├── Nginx            : 443/80, HTTPS证书(腾讯云免费证书/Let's Encrypt), 反代+静态
    ├── Java项目管理器    : jiameng-pay.jar(Spring Boot 单进程, 建议分配 3~4G 内存)
    ├── MySQL 8          : 仅监听 127.0.0.1, 数据盘独立目录
    ├── Redis 7          : 密码+仅本机, 持久化 AOF
    └── Docker(可选)     : Prometheus/Grafana 监控栈
对象存储: 腾讯云 COS(私有桶, 进件影像/投诉凭证/对账单/数据库备份)
DNS/CDN: 腾讯云 DNSPod; 收银台与后台静态资源可挂 CDN
```

**服务器规划:**

| 项目 | 一期(起步) | 成长期(升级路径) |
| --- | --- | --- |
| 机型 | 1 台 4C8G 轻量(应用+数据同机,数据盘独立) | 应用与数据库分机:2C4G 应用 xN + 4C8G 数据库主从 |
| MySQL | 单机,每日全量备份 + Binlog 增量至 COS | 主从复制,读写分离 |
| 应用 | 单进程,JVM 参数按内存裁剪 | 多实例负载(Nginx upstream),会话外置 Redis |
| 队列 | Redis Stream | RabbitMQ 集群(切换成本接近零,接口已抽象) |
| 高可用 | 单机(99.5% 目标,快照+COS 快速重建) | 多机集群 + K8s(远期) |

**宝塔侧安全基线**(与应用层安全并列执行):面板修改默认端口与安全入口并开启 2FA;SSH 改端口+密钥登录+禁 root 密码;轻量防火墙仅放行 80/443/SSH/面板;MySQL/Redis 仅监听本机;宝塔与组件保持更新;面板绑定域名+HTTPS;开启宝塔 SSH 防爆破与日志告警。

**备份策略:** 宝塔计划任务每日凌晨全量备份数据库与站点至本地数据盘,同步推送腾讯云 COS(异地);开启轻量服务器每周系统快照;保留策略 7 天日备 + 4 周周备;备份有效性每季度演练恢复一次。

---

## 4. 插件体系设计(核心)

### 4.1 插件分类与清单

| 类型 | 扩展点接口 | 首发插件 |
| --- | --- | --- |
| 支付通道 channel | `PaymentChannelPlugin` | `channel-wxpay-native`(微信原生 V2/V3,含投诉同步)、`channel-alipay-native`(支付宝原生,含投诉同步)、`channel-huifu`(汇付天下:聚合扫码/进件/代付/分账)、`channel-fuiou`(富友:聚合支付/入网/代付/分账)、`channel-tp-demo`(三方对接通用模板,后续新增三方时复制改造)、`channel-demopay`(纯模拟 Demo,含模拟投诉) |
| 通知 notifier | `NotifierPlugin` | `notifier-wechat-tmpl`(微信公众号模板消息)、`notifier-email`(SMTP 邮件);预留钉钉/飞书/短信扩展 |
| 快捷登录 auth | `AuthPlugin` | `auth-sms`(阿里云短信验证码)、`auth-oneclick`(运营商一键登录,可选)、`auth-wechat-oauth`(微信扫码) |
| 扩展 ext | `HookPlugin` | `ext-risk-rule-demo`(自定义风控规则示例)、`ext-report-export-demo`(自定义报表导出示例) |

### 4.2 通道插件接口契约(摘要)

```java
public interface PaymentChannelPlugin extends PluginPoint {

    ChannelMeta meta();
    // 声明:插件ID、名称、支持的产品(WECHAT_NATIVE/ALIPAY_H5/QQ_QR/UNIONPAY/...)
    // 能力位:是否支持退款/代付/进件/部分退款/撤销/投诉(COMPLAINT)

    PayResponse pay(PayOrder order, ChannelConfig cfg);
    // 统一下单:入参为平台标准化订单,出参标准化支付要素
    // (二维码串 / 跳转URL / JSAPI参数 / 收银台URL)

    OrderQueryResponse queryOrder(PayOrder order, ChannelConfig cfg);
    RefundResponse refund(RefundOrder refund, ChannelConfig cfg);
    RefundQueryResponse queryRefund(RefundOrder refund, ChannelConfig cfg);
    TransferResponse transfer(TransferOrder t, ChannelConfig cfg);       // 代付(汇付/富友)
    TransferQueryResponse queryTransfer(TransferOrder t, ChannelConfig cfg);

    CallbackResult parseCallback(RawRequest raw, ChannelConfig cfg);
    // 验签 + 解密 + 金额/商户号/订单号一致性校验,返回标准化回调结果

    OnboardingResponse submitOnboarding(OnboardingRequest r, ChannelConfig cfg);
    OnboardingStatus queryOnboarding(String bizApplyNo, ChannelConfig cfg);

    BillDownloadResponse downloadBill(BillQuery q, ChannelConfig cfg);   // 对账单

    // 以下为可选能力位 COMPLAINT(投诉):不支持投诉能力的通道可不实现
    ComplaintPage fetchComplaints(ComplaintQuery q, ChannelConfig cfg);          // 投诉增量拉取
    ComplaintDetail fetchComplaintDetail(String complaintId, ChannelConfig cfg); // 投诉详情(含协商历史)
    ComplaintReplyResult replyComplaint(ComplaintReply r, ChannelConfig cfg);    // 回复同步回渠道侧
}
```

所有插件配置通过 `plugin.json` 声明 `configSchema`(后台自动渲染配置表单,密钥类字段写入时加密存储、读取时脱敏展示)。

`plugin.json` 示例:

```json
{
  "id": "channel-huifu",
  "name": "汇付天下(聚合通道)",
  "type": "payment-channel",
  "version": "1.0.0",
  "coreVersion": ">=1.0.0",
  "entry": "com.jiameng.pay.plugin.huifu.HuifuPlugin",
  "author": "四川佳梦云网络科技有限公司",
  "capabilities": ["PAY", "REFUND", "TRANSFER", "ONBOARDING", "PROFIT_SHARING", "BILL", "COMPLAINT"],
  "configSchema": [
    { "key": "sysId",    "type": "string", "label": "系统号", "required": true },
    { "key": "md5Key",   "type": "secret", "label": "MD5密钥", "required": true },
    { "key": "rsaPriv",  "type": "secret", "label": "RSA私钥", "required": true }
  ]
}
```

### 4.3 插件生命周期与安全

1. 生命周期:上传(仅平台超管) -> 签名与完整性校验(内置证书校验包体哈希) -> 版本兼容校验 -> 安装(配置默认项) -> 启用/停用 -> 升级(配置迁移钩子) -> 卸载(强制校验:存在关联通道配置时禁止卸载)。
2. 隔离:插件运行于受控 ClassLoader,仅暴露平台 SPI 白名单类;插件异常熔断不影响主流程(下单失败自动切换备用通道并告警)。
3. 审计:插件安装/升级/启停/配置变更全部记录审计日志,配置变更保留历史版本可回滚。
4. 插件中心:插件列表、启停、配置、版本管理全部在平台后台"插件中心"完成。

### 4.4 事件总线(插件可订阅事件)

| 事件 | 触发时机 | 典型订阅方 |
| --- | --- | --- |
| order.created / order.paid / order.closed | 订单生命周期 | 通知插件、分润记账、风控 |
| refund.succeeded / refund.failed | 退款结果 | 通知 |
| transfer.submitted / transfer.succeeded / transfer.failed | 代付状态 | 通知、风控 |
| complaint.created / complaint.replied / complaint.overdue / complaint.rate.warned | 投诉新增/回复/超时/投诉率预警 | 通知、风控 |
| merchant.registered / merchant.audited | 商户注册与审核 | 通知 |
| onboarding.submitted / onboarding.auditing / onboarding.approved / onboarding.rejected | 进件状态 | 通知 |
| channel.callback.failed / reconcile.diff.found | 渠道回调异常、对账差错 | 通知、风控 |
| security.login.anomaly | 异地/异常登录 | 通知 |

### 4.5 Demo 插件与开发者支持(交付重点)

1. `channel-demopay`:完整实现下单/查询/退款/代付/回调/进件/**投诉**全接口,内置模拟银行、模拟投诉与模拟回调按钮(用于联调测试),代码逐行中文注释,标注每个扩展点的必做/选做逻辑、验签示例、幂等要求。
2. 插件脚手架:`plugin-scaffold` 命令行/模板工程,一键生成标准目录、`plugin.json`、单测骨架。
3. 《插件开发规范》文档(随文档站发布,中英双语):接口契约、配置 Schema 规范、密钥安全要求(禁止明文、禁止打印日志)、回调验签规范、金额单位统一为"分"、超时与重试规范、单测覆盖率要求(核心路径不低于 80%)、提审清单与平台审核流程。
4. 三方接入示例:`channel-tp-demo` 通用模板演示 MD5/RSA 验签、表单跳转类通道与纯 API 通道两类对接方式;本期 `channel-huifu`、`channel-fuiou` 即按此模板由公司实施,后续新增三方照此复制。

---

## 5. 支付能力设计

### 5.1 支付方式矩阵(首发)

| 通道 | 扫码(主扫) | 付款码(被扫) | H5/WAP | JSAPI/公众号/小程序 | QQ钱包/云闪付 |
| --- | --- | --- | --- | --- | --- |
| 微信原生 V3 | Native | 付款码 | H5 | JSAPI/小程序 | - |
| 支付宝原生 | 当面付(precreate) | 付款码 | WAP | JSAPI/小程序 | - |
| 汇付天下 | 聚合扫码 | 聚合付款码 | 聚合 H5 | 聚合 JS/小程序 | 经聚合通道支持 |
| 富友支付 | 聚合扫码 | 聚合付款码 | 聚合 H5 | 聚合 JS/小程序 | 经聚合通道支持(QQ钱包/银联) |

说明:三方通道的产品能力在插件 `meta()` 中声明,后台自动渲染可用支付方式,不硬编码;APP 支付作为 API 能力保留(供商户自有 APP 调用),平台自身不提供 APP。

### 5.2 自有聚合收银台(H5,重点)

平台提供**完全自有品牌**的聚合收银台,域名、Logo、名称、主题色、底部版权均在平台后台配置:

1. **下单接入**:商户 API 以 `cashier_mode` 下单即返回收银台 URL;商户亦可在商户后台生成固定收款链接(金额可固定/可输入,备注可配)供日常扫码收款。
2. **环境自动识别**:微信内打开自动走 JSAPI;支付宝内打开自动走支付宝 H5;PC 打开展示各支付方式二维码;手机浏览器打开走 H5/拉起对应 APP。
3. **支付方式渲染**:按订单实际可用通道动态展示(微信、支付宝、QQ钱包、云闪付等),无可用通道时给出明确提示。
4. **状态交互**:轮询 + SSE 实时确认支付结果,订单超时倒计时,支付成功页支持商户自定义回跳地址(白名单校验);**支付成功页固定预留"对本次订单投诉"按钮**(跳转消费者服务页,见 5.8)。
5. **双语**:中英文自动检测(浏览器语言)+ 手动切换,文案、错误提示、成功页全量覆盖。
6. **安全**:收银台订单绑定一次性 token 防重放;CSP/防 XSS;不暴露商户与平台敏感信息;页面资源全部 HTTPS + CDN。
7. **视觉**:遵循第 13 章规范,品牌蓝主题,图标全 SVG,零 Emoji。

### 5.3 渠道路由与容灾

- 路由因子:商户/服务商可用通道白名单、费率成本、近实时成功率(滑动窗口统计)、单笔/日累计限额、商户号状态、权重(支持轮询)。
- 容灾:通道下单失败或超时自动按优先级切换备用通道(如微信原生失败自动切汇付/富友的微信通道);连续失败熔断并告警;支持人工置维护。
- 同一商户同一支付方式可绑定多个通道实例,策略(优先级/轮询/按金额分层)商户级可配。

### 5.4 订单与幂等

- 订单状态机:待支付 -> 支付成功/已关闭;(退款:已支付 -> 退款中 -> 部分退款/全额退款)。
- 幂等:商户订单号(`out_trade_no`)商户维度唯一索引;回调处理以"平台订单号+状态机"双重幂等,重复回调直接返回成功。
- 金额一致性:回调金额、查询金额与订单金额三方比对,不一致即冻结订单并触发告警事件。

### 5.5 代付/转账子系统

| 能力 | 说明 |
| --- | --- |
| 承载通道 | 汇付天下、富友(均具备付款/代付能力,转银行卡为主,具体到账渠道以通道开通为准) |
| 发起方式 | 商户后台人工发起 / 商户 API 发起(独立权限节点+独立密钥作用域) |
| 安全控制 | 独立风控规则(单笔/日累计阈值、收款方黑白名单、频次)、可配置二级人工复核、大额强制复核 |
| 状态确认 | 回调 + 主动轮询双确认,以查询结果为最终态 |
| 手续费 | 按通道配置单笔固定/百分比,独立记账 |

### 5.6 进件子系统

- **三方入网(首发主路径)**:汇付天下、富友商户入网 API,由 `channel-huifu`/`channel-fuiou` 插件实现;资料清单由插件 Schema 动态生成表单。
- **原生进件(资质就绪后叠加)**:微信支付特约商户进件(Applyment4Sub V3)需平台持有微信支付**服务商**商户号;支付宝进件需平台具备 **ISV** 资质并签约。平台暂不具备该资质时,原生通道用于"商户自备商户号"模式(商户上传自己的微信/支付宝商户号与密钥直连),新商户进件一律走汇付/富友。
- 资料:营业执照、法人/经办人身份证正反面、结算卡、门头照/场景照等按通道要求动态生成。
- 影像:仅接受 JPG/PNG,大小限制,病毒查杀,存储于腾讯云 COS 私有桶,链接带签名与有效期。
- 状态机:草稿 -> 待平台初审 -> 渠道审核中 -> 通过/驳回(驳回原因逐项展示,支持修改重提)。
- 全程事件通知(模板消息/邮件);通过后自动建立"商户-通道-子商户号"映射并下发收款参数。

### 5.7 分润与结算(记账层面)

- 配置:服务商分润比例(全局默认 + 商户级覆写),支持固定金额或百分比。
- 记账:订单支付成功即生成分润流水(只在系统记账,不产生资金指令,见 2.4);资金侧分润通过汇付/富友分账产品或技术服务费协议落地。
- 报表:服务商维度日/月分润报表,可导出对账文件供财务开票结算。

### 5.8 投诉中心(投诉子系统)

#### 5.8.1 投诉来源与同步

**A. 渠道投诉(API 同步)**:消费者在微信/支付宝内发起的商户投诉,由通道插件同步至平台,统一收敛到投诉中心:

| 渠道 | 同步方式 | 插件实现 |
| --- | --- | --- |
| 微信支付 | 商户投诉 2.0 系列接口(投诉列表、详情、协商历史、回复)与投诉通知回调;定时增量拉取 + 回调双通道,按渠道投诉号幂等去重 | `channel-wxpay-native`(能力位 COMPLAINT) |
| 支付宝 | 开放平台消费者投诉相关接口(以支付宝最新文档为准),定时增量拉取,按投诉单号幂等去重 | `channel-alipay-native`(能力位 COMPLAINT) |
| 汇付/富友 | 如其提供投诉查询/通知能力则由对应插件同步;否则支持平台后台手动登记投诉,保持统一视图与统一统计 | `channel-huifu` / `channel-fuiou`(能力位视通道实际支持) |

**B. 站内投诉(平台自有,消费者直达)**:消费者**不经过微信/支付宝**,直接在平台对订单发起投诉;平台为消费者预留**全程无需注册**的消费者服务页(H5,中英双语):

1. **入口预留(四处)**:
   - 收银台支付成功页固定"对本次订单投诉"按钮;
   - 消费者订单查询页(独立 H5,凭平台订单号 + 手机号后四位查询支付状态)内嵌投诉按钮;
   - 独立投诉直达页(固定短链,扫码即达):平台统一生成**带商户标识的投诉入口二维码**,预置在商户收款码海报、电子小票与门店物料模板中,商户后台可直接下载;
   - 商户系统嵌入:商户可经开放 API 生成**带签名与时效的投诉页跳转链接**,放置在商户自己的订单详情页,点击即进入本平台投诉页并自动带入订单。
2. **提交流程**:定位订单(扫码/带参链接自动带入订单信息,或手动输入平台订单号/商户订单号)-> 身份校验(支付/预留手机号后四位;校验不通过时降级为图形验证码 + 转人工审核,防撞单防枚举)-> 填写投诉类型与描述 -> 上传凭证 -> 提交生成平台投诉单号(页面展示,可选短信回执),并即时经事件总线通知商户处理人。
3. **进度跟踪**:消费者凭投诉单号 + 手机号在投诉页随时查看处理进度,查看商户/平台回复,补充留言与新凭证,并对处理结果进行**"确认解决 / 仍有异议"**操作;确认解决后投诉单自动关闭,选择异议则升级平台仲裁。
4. **触达(可选)**:受理、商户回复、解决确认等关键节点经阿里云短信通知消费者(模板提前报备);未启用短信时以页面进度为准。
5. **防刷与滥用防护**:IP/设备维度限流,图形验证码前置,同订单同类型投诉 24 小时内限 1 次;命中风控黑名单直接拦截留痕。
6. **内容规范**:投诉类型(未收到货/退款纠纷/商品或服务与描述不符/涉嫌欺诈/其他)+ 文字描述(长度限制,敏感词过滤)+ 图片凭证(JPG/PNG,数量与大小限制,病毒查杀,存 COS 私有桶,带有效期签名链接)。

#### 5.8.2 处理流程与 SLA

- 状态机:待受理 -> 处理中 -> 已回复 -> 已解决 / 已关闭(无效投诉);消费者可在解决前补充留言与凭证。
- 责任分派:商户为第一处理人(可分配给管理员或客服子账号);服务商可查看并可协助回复(权限可配);"涉嫌欺诈"类投诉**强制平台介入仲裁**。
- 渠道回传:渠道内投诉的回复经插件 API 同步回微信/支付宝侧(用户可在微信/支付宝内看到);站内投诉通过投诉页进度 + 可选短信触达消费者。
- SLA 可配(默认 24 小时首次响应、72 小时办结);超时自动升级:通知商户管理员 -> 服务商管理员 -> 平台运营,并计入商户投诉处理考核。
- 全流程操作留痕(受理/回复/仲裁/关闭均写审计日志),回复内容与凭证留存可回溯。

#### 5.8.3 近 7 天投诉率(商户与服务商均可见)

- **口径**:投诉率(万分比)= 近 7 天投诉单数 / 近 7 天支付成功订单数 × 10000;同时提供三个口径并行展示:**全渠道合计(含站内)/ 渠道内(微信、支付宝分列)/ 站内**,其中渠道内口径与微信官方商户投诉率对齐,便于对标其处罚线。
- **商户端**:商户后台工作台展示"近 7 天投诉率"卡片(当前值 + 近 7 天趋势折线 + 待处理投诉数 + 距预警线余量),投诉列表支持按来源(渠道/站内)、类型、状态筛选。
- **服务商端**:服务商后台工作台展示名下商户**汇总投诉率**与**商户投诉率排行榜**(可下钻到具体商户与投诉单),支持导出;分页明细均带数据范围隔离(仅名下商户)。
- **平台端**:全量投诉率总览、按通道/类型分布、同步任务监控(拉取失败/积压告警)。
- **统计实现**:小时级预聚合定时任务 + 事件驱动增量更新,明细留存可回溯,统计口径与数据生成时间对用户可见,避免口径争议。

#### 5.8.4 预警与风控联动

- 阈值可配(默认参考微信处罚线设置安全余量):达到**预警线**(如 3‱)发送模板消息/邮件给商户与服务商管理员,事件 `complaint.rate.warned`;达到**高危线**(如 6‱)自动生成风控事件,可配置动作:限制商户新订单 / 暂停指定通道收款 / 要求平台人工审核进件,处置留痕可申诉。
- 投诉类型为"涉嫌欺诈"的投诉单独立标记,累计达到阈值自动冻结商户待平台人工核查。
- 投诉率与投诉处理时效(首响/办结)纳入商户经营看板,供服务商辅导商户使用。

#### 5.8.5 权限与可见性

| 端 | 可见与操作 |
| --- | --- |
| 平台 | 全量投诉查看/仲裁/关闭、手动登记、同步任务管理、阈值与 SLA 配置、投诉率总览 |
| 服务商 | 名下商户投诉查看(默认只读,协助回复可配)、名下投诉率报表与排行 |
| 商户 | 本商户投诉全处理权限(受理/回复/解决申请),可分配给子账号 |

权限节点示例:`complaint:list:view`、`complaint:detail:view`、`complaint:reply:submit`、`complaint:close:submit`、`complaint:arbitrate:execute`、`complaint:config:manage`。

---

## 6. 三端后台功能清单

### 6.1 平台后台

| 模块 | 功能点 |
| --- | --- |
| 工作台 | 今日交易概览、成功率、通道健康度、待办(审核/复核/差错/**投诉超时**),中英切换 |
| 商户管理 | 列表/详情/编辑、审核、冻结/解冻、密码重置、通道与费率配置、自助注册开关 |
| 服务商管理 | **仅此处开通服务商**(企业资料、管理员、分润比例、名下商户树)、冻结、费率模板 |
| 通道管理 | 通道实例(插件+配置)、上游商户号池(汇付/富友/微信/支付宝)、限额、启停、维护、健康监控 |
| 插件中心 | 上传/安装/升级/启停/卸载、配置表单、版本与审计 |
| 订单管理 | 全局订单查询、详情、手动补单(需双人复核)、异常单处理 |
| **投诉管理** | 全量投诉收件箱(渠道+站内)、详情/仲裁/关闭、手动登记、渠道同步任务监控、投诉率总览、SLA 与阈值配置 |
| 退款/代付 | 退款查询与人工处理、代付审核队列、复核记录 |
| 进件管理 | 进件队列、初审、驳回处理、状态同步监控 |
| 分润 | 分润流水、服务商报表、导出 |
| 风控 | 规则配置、黑白名单、投诉率阈值动作、实时拦截记录、风险订单处置 |
| 对账 | 渠道账单下载、自动核对、差错处理(长款/短款/状态不一致)、对账报告 |
| 通知中心 | 事件管理(含投诉事件)、模板管理(公众号模板ID/邮件模板,中英)、接收人规则、发送记录与失败重发 |
| 系统管理 | 平台角色权限、管理员账号、操作/登录审计日志、参数配置、敏感配置(主密钥)、公告、**收银台品牌配置** |
| 安全 | 2FA 强制、IP 白名单、会话策略、密码策略、登录异常记录 |

### 6.2 服务商后台

工作台(名下商户交易概览 + **近 7 天投诉率汇总与商户排行**)、商户管理(邀请链接/邀请码生成、协助注册资料预填、协助进件)、交易查询(限名下商户)、**投诉中心(名下商户投诉查看与协助回复,可配)**、分润报表与流水、子账号与角色管理、消息通知设置。中英双语。

### 6.3 商户后台

工作台(**近 7 天投诉率卡片与趋势、待处理投诉数**)、应用管理(AppID、API 密钥生成/重置、IP 白名单、允许接口权限)、订单查询、退款管理、代付管理、**投诉中心(投诉列表、详情、回复、解决,渠道内回复自动同步微信/支付宝)**、对账单下载、**收款链接管理**(固定码/收款码海报生成,海报模板预置平台投诉入口二维码)、员工子账号、开发者文档入口、通知设置(绑定接收模板消息的 OpenID)。中英双语。

---

## 7. 开放 API(商户对接)

### 7.1 接口列表(V1)

| 接口 | 说明 |
| --- | --- |
| POST /api/v1/pay/unifiedorder | 统一下单(指定 payWay 或 cashier_mode 返回收银台 URL) |
| GET /api/v1/pay/query | 订单查询 |
| POST /api/v1/pay/close | 关闭订单 |
| POST /api/v1/pay/refund | 申请退款 |
| GET /api/v1/pay/refund/query | 退款查询 |
| GET /api/v1/pay/refund (内部分页) | 退款记录 |
| POST /api/v1/transfer/apply | 代付申请(独立权限,经汇付/富友) |
| GET /api/v1/transfer/query | 代付查询 |
| GET /api/v1/complaint/list | 投诉列表查询(本商户,含渠道与站内,可选开通) |
| GET /api/v1/complaint/detail | 投诉详情(含协商历史,可选开通) |
| GET /api/v1/complaint/rate | 本商户近 7 天投诉率(可选开通) |
| GET /api/v1/account/balance | 账户/额度查询(通道侧,视能力) |
| /api/v1/notify/{merchantAppId} | 平台 -> 商户异步通知(签名) |

### 7.2 安全规范

- 签名:RSA2(推荐)或 HMAC-SHA256;所有请求含 `timestamp`(±5 分钟)+ `nonce`(Redis 去重防重放)+ `sign`;响应与回调同样签名。
- 金额单位统一为分(整数),杜绝浮点误差。
- 每应用独立密钥 + 可配置 IP 白名单 + 接口级限流(令牌桶)。
- 商户回调地址支持按应用配置,失败阶梯重试(15s/30s/1m/5m/10m/30m/1h...,最多 12 次),通知记录可查、可手动重发。

### 7.3 配套

- API 文档站(在线调试、错误码表、变更日志,中文为主,英文版随词条库产出)。
- 官方 SDK 与示例:PHP / Java / Python / Node.js 各一份最小可运行 Demo(调用统一下单 + 接收回调验签示例)。
- 沙箱环境:基于 `channel-demopay` 插件提供全流程联调沙箱(含模拟投诉)。

---

## 8. 账号与登录体系

### 8.1 登录方式

| 方式 | 适用端 | 说明 |
| --- | --- | --- |
| 账号密码 + 图形验证码 | 三端 | 密码策略可配(长度/复杂度/历史);连续失败锁定(阈值可配);Argon2id 哈希 |
| 双因素 2FA(TOTP) | 平台后台强制,服务商/商户可选 | 绑定与恢复流程 |
| 手机验证码快捷登录 | 商户端、服务商端 | `auth-sms` 插件,**阿里云短信服务**(签名与模板需提前报备);验证码 5 分钟有效、60 秒发送间隔、图形验证码前置防刷,发送与验证全量风控 |
| 运营商一键登录 | 商户端(可选) | `auth-oneclick` 插件,本机号码认证,视商务需要后置 |
| 微信扫码登录 | 商户端 | `auth-wechat-oauth` 插件;PC 扫码需**微信开放平台"网站应用"**审核通过(企业主体),若暂未取得资质则先行上线验证码/一键登录,扫码登录随资质落地启用;**服务商端不开放任何自助注册类登录,扫码仅用于已存在账号绑定** |

### 8.2 注册与开通流程

- 服务商:平台后台"开通服务商"表单(企业信息、管理员手机号/邮箱、初始密码线下交付或首次登录强制改密)。
- 商户自助注册:全局开关开启时,注册页开放;提交企业资料 -> 审核(人工/自动) -> 通过后开通应用与密钥。
- 服务商邀请注册:邀请码/专属链接 -> 注册表单预绑定服务商 -> 审核策略可配(服务商初审+平台终审 或 仅平台审核)。

### 8.3 账号安全

异地登录检测与提醒(邮件+模板消息)、常用设备管理、会话超时与单点互踢策略、敏感操作二次验证(密码/短信)、全部登录与敏感操作审计留痕。

---

## 9. 消息通知体系

### 9.1 通道

| 通道 | 插件 | 说明 |
| --- | --- | --- |
| 微信公众号模板消息 | `notifier-wechat-tmpl` | 平台注册**微信公众号**(服务号,需企业认证),接收人关注公众号并绑定 OpenID;模板 ID 在后台按事件配置;受微信限制模板内容为中文 |
| 邮件 | `notifier-email` | SMTP 可配(腾讯云企业邮/阿里云邮件推送等),HTML 模板化,**中英双语模板**,支持变量占位符 |

### 9.2 事件与订阅(默认表,可增删)

| 事件 | 默认接收人 |
| --- | --- |
| 订单支付成功(大额/全部,可配) | 商户管理员、(全部时)平台运营 |
| 退款结果 | 商户管理员、平台财务 |
| 代付状态变更 | 商户管理员、发起人 |
| 新投诉(complaint.created) | 商户管理员(处理人)、平台运营 |
| 投诉有新回复(complaint.replied) | 商户管理员、(站内投诉时)消费者可选短信 |
| 投诉超时未处理(complaint.overdue) | 商户管理员、服务商管理员、平台运营 |
| 投诉率预警(complaint.rate.warned) | 商户管理员、服务商管理员、平台风控 |
| 商户注册待审核 / 审核结果 | 平台运营、商户 |
| 进件状态变更 | 商户管理员、服务商管理员、平台运营 |
| 渠道回调异常 / 对账差错 | 平台运营、风控 |
| 登录异常 | 账号本人 |

### 9.3 能力

模板中心(变量占位符、预览、测试发送)、接收人规则(按角色/按人/按事件)、发送记录、失败自动重试与手动重发、频控(防轰炸)、退订/停用。

---

## 10. 安全设计(资金级)

### 10.1 传输与边界

全站强制 HTTPS(TLS1.2+,建议 1.3)+ HSTS;生产环境后台与 API/收银台域名分离,后台可配 IP 白名单;Nginx 层 WAF 规则与全入口限流;轻量防火墙仅放行必要端口(见 3.4 宝塔安全基线)。

### 10.2 密钥与敏感数据

- 渠道密钥(汇付 MD5/RSA、富友证书、微信 APIv3、支付宝应用私钥等):AES-256-GCM 加密落库,主密钥来自独立配置文件(仅运维可读,权限 600)与环境变量组合;界面只显示尾四位。
- 密码 Argon2id;身份证/银行卡/手机号等敏感字段加密存储 + 展示脱敏;投诉中消费者手机号同样脱敏展示;日志全链路敏感字段打码(统一脱敏组件强制)。
- 密钥轮换机制:商户密钥支持"双密钥并行期"平滑轮换。

### 10.3 接口安全

签名(HMAC-SHA256/RSA2)+ 时间戳 + nonce 防重放;幂等键;接口级权限节点校验(拒绝越权,默认拒绝);参数严格校验(Bean Validation + 白名单);返回报文最小化;**站内投诉页等匿名公开接口独立限流与验证码策略,防止撞单、枚举订单号与垃圾提交**。

### 10.4 应用安全

OWASP Top 10 全覆盖:预编译 SQL、CSP、XSS 过滤、CSRF Token(后台表单)、SameSite Cookie、上传文件类型/魔数双校验 + COS 私有桶存储(进件影像与投诉凭证同一安全基线)、依赖漏洞扫描(CI 集成 Trivy/OWASP DC)、越权测试用例纳入回归。

### 10.5 资金安全

回调验签 + 金额三方比对 + 状态机幂等;手动补单/退款/代付等资金敏感操作双人复核;代付独立权限与独立密钥;对账差错自动冻结待人工处置。

### 10.6 审计与追溯

操作日志、登录日志、API 调用日志、回调日志、投诉处理日志全量留存(默认 2 年,可配);审计日志哈希链防篡改 + 定期归档;支持按商户/操作人/时间追溯导出。

### 10.7 风控引擎

规则可配置:单笔/日累计限额、频次异常、时间窗异常、收款金额谐数/整数特征、黑名单(商户/设备/IP/收款方)、进件资料风险标签、**投诉率与欺诈类投诉累计阈值**;命中动作:放行/人工审核/拒绝/冻结;全量命中记录可查;风控规则亦以插件形式可扩展(`ext-risk-rule-demo` 示例)。

### 10.8 安全验证

上线前:第三方渗透测试 + 代码安全审计(或内部双人审计);SDL:需求安全检查点、CI 静态扫描、密钥扫描(gitleaks)、镜像扫描。

---

## 11. 性能与容量(按轻量服务器单机规划)

| 指标 | 一期目标(4C8G 单机) | 成长期目标(拆分后) |
| --- | --- | --- |
| 统一下单 API | P99 < 300ms(不含上游通道耗时),全链路 P99 < 1.5s | 不变 |
| 回调处理 | 入队 < 100ms,处理 < 1s | 不变 |
| 并发 | 100~200 TPS(单机,JVM 3~4G) | 500+ TPS(多实例) |
| 可用性 | 99.5%(单机,快照+COS 快速重建,RTO < 60 分钟,RPO < 10 分钟) | 99.9%(应用与数据库分离+主从) |
| 消息可靠性 | Redis Stream 持久化 + 消费确认 + 死信重试,回调零丢失 | 切换 RabbitMQ 后同等保证 |

降级策略:通知类失败不阻塞主链路;通道熔断自动切换;统计异步化(含投诉率预聚合)。上线前完成单机容量压测并输出扩容阈值(建议 CPU 持续 70% 或连接数打满即触发拆分)。

---

## 12. UI/UX 规范

### 12.1 品牌与视觉

1. **Logo**:采用公司提供的徽标(已存入 `assets/brand/logo.png`,深色底版)。因当前图为深色矩形底,Web 端需要**透明底或白底的方形 PNG/SVG 源文件**(见附录 C 待确认事项);收银台与后台默认浅色场景使用透明底版本。
2. **品牌色**(自 Logo 取样):主色蓝 `#2F6FE4`,渐变区间 `#275CE0 -> #4CA5F6`,深色底 `#33373B` 用于页脚/深色模式;成功色、警示色、错误色沿用组件库语义色并统一调整。
3. **全站禁用 Emoji**:前端建立独立 SVG 图标体系(vite-svg-icons 构建雪碧图 + Iconify 离线 SVG 包),组件库图标全部替换为 SVG;CI 增加 Emoji 检查脚本(扫描源码与文案,命中即构建失败),文案评审规则同步约束。
4. 布局:后台采用左侧导航 + 顶部工作台的经典三端布局,统一栅格与间距规范;表格类页面统一操作列规范;收银台与投诉页移动优先。

### 12.2 中英文双语(i18n)

1. 范围:平台/服务商/商户三端后台、聚合收银台与**消费者服务页(订单查询/投诉提交/进度跟踪)**的**全量界面文案中英双语**;后端返回消息与错误码按 `Accept-Language` 输出中英;邮件模板双语可配;微信模板消息受微信限制仅中文。
2. 实现:vue-i18n,词条文件 `zh-CN`/`en-US` 分模块维护;语言切换入口位于顶栏,选择持久化(localStorage),首次访问按浏览器语言自动检测。
3. 规范:禁止文案硬编码,所有用户可见文本走词条库(CI 用脚本扫描拦截);词条 Key 命名规范随前端规范文档发布。
4. 本地化:金额统一"分"存储、展示按语言格式化;日期时区默认 `Asia/Shanghai`,后台可显示 UTC;中英文排版字体栈分别定义。

### 12.3 交互与性能

关键操作二次确认、危险操作红色隔离、表单实时校验;商户端提供新手引导与接入自检(密钥配置检测);后台桌面优先、收银台与投诉页移动优先;首屏 < 2s(DNSPod + CDN + 路由懒加载 + brotli)。

---

## 13. 开发计划与里程碑

### 13.1 阶段划分(自 2026-09-14 起,总计约 20 周)

| 阶段 | 周期 | 交付内容 |
| --- | --- | --- |
| P0 需求与设计 | 1 周(09-14 ~ 09-18) | 原型图(含中英词条框架,覆盖三端后台/收银台/投诉页)、数据库设计、接口契约评审、UI 规范与品牌色定稿、阿里云短信/公众号/汇付/富友资料启动申请 |
| P1 一期 MVP | 7 周(09-21 ~ 11-06) | 核心框架与插件运行时、RBAC、商户/服务商开通与审核、**微信原生+支付宝原生通道插件**、统一下单/查询/关闭/回调、**自有聚合收银台(中英)**、三端后台基础版(中英框架)、审计日志、宝塔部署流水线 |
| P2 二期 | 7 周(11-09 ~ 12-25) | **汇付天下+富友插件(含进件/代付)**、进件中心、代付中心、**投诉中心(微信/支付宝投诉 API 同步 + 消费者服务页:订单查询/投诉提交/进度跟踪 + 处理流程与 SLA + 近 7 天投诉率统计与预警联动)**、分润记账、通知中心(公众号模板消息+阿里云短信驱动+邮件)、快捷登录插件、插件中心(上传/启停/配置)、Demo 插件+脚手架+开发文档、API 文档站与 SDK |
| P3 三期 | 4 周(12-28 ~ 2027-01-22) | 智能路由与容灾完善、风控引擎(含投诉率阈值动作)、自动对账、性能压测与安全加固(渗透测试)、监控告警完备、上线演练 |
| 试运行与验收 | 2 周(01-25 ~ 02-05) | 灰度试运行、问题修复、培训与文档移交、正式验收 |
| 正式上线 | 目标 2027 年 2 月下旬(避开春节周) | — |

注:P1 期间即可并行推进汇付/富户的商务签约与商户入网资料准备(通常需 1~2 周以上),避免 P2 联调被资质阻塞;微信投诉 2.0 接口权限、支付宝投诉接口权限随各自商户号资质一并申请;阿里云短信签名/模板、微信公众号认证、微信开放平台网站应用申请同样在 P0 启动。P2 因新增投诉中心由 6 周调整为 7 周。

### 13.2 人力配置(建议)

| 岗位 | 人数 | 职责 |
| --- | --- | --- |
| 项目经理/架构师 | 1 | 计划、架构、核心评审 |
| 后端工程师 | 3 | 核心 + 插件(汇付/富友/微信/支付宝) + 开放 API + 投诉中心 |
| 前端工程师 | 2 | 三端后台 + 收银台 + 投诉页 + 文档站(含中英词条) |
| 测试工程师 | 1.5 | 功能/接口/安全/性能 |
| UI 设计 | 0.5 | 视觉规范与 SVG 图标库(基于已定 Logo 与品牌色) |
| 运维(兼) | 0.5 | 腾讯云/宝塔环境与 CI/CD |

### 13.3 交付物清单

源代码(含插件与 Demo)、数据库设计文档、接口文档站(中英)、插件开发规范与示例(中英)、部署手册(腾讯云轻量+宝塔专项)、运维手册(备份/监控/告警/应急)、测试报告(功能/安全/性能)、用户手册(三端,中英)。

---

## 14. 测试与质量保障

- 单元测试核心模块覆盖率 >= 80%,插件核心路径 >= 80%(强制卡点)。
- 接口自动化:开放 API 全量用例自动化回归;回调验签/幂等/金额比对专项用例。
- 通道联调:微信/支付宝官方沙箱;汇付/富友测试环境联测(入网-收款-退款-代付全链);未开通前用 `channel-demopay` 与 Mock Server 不阻塞主线。
- 投诉链路专项:渠道投诉同步幂等(重复通知不重复建单)、投诉详情/协商历史完整性、回复回传渠道侧、站内投诉页防刷(限流/验证码/同单去重)、消费者进度跟踪与"确认解决/仍有异议"闭环、四类投诉入口(成功页/订单查询页/二维码物料/API 短链)鉴权与带参正确性、投诉率统计口径正确性(三口径交叉验证)、投诉率预警与风控动作触发。
- 混沌用例:回调乱序、重复回调、金额不一致、通道超时、Redis 宕机恢复(Stream 消息不丢)。
- 性能压测(JMeter/Locust):按第 11 章单机指标验收,输出扩容阈值。
- 安全测试:内部越权/注入/重放专项 + 第三方渗透测试,高危漏洞清零后方可上线。
- i18n 专项:切词完整性检查(缺失词条扫描)、中英文混排溢出测试(含投诉页与收银台)。

---

## 15. 风险分析与应对

| 风险 | 影响 | 应对 |
| --- | --- | --- |
| 合规风险(二清/无证经营) | 法律 | 坚持 2.4 红线设计;上线前法务复审;仅对接持牌机构(汇付/富友)与官方通道 |
| **投诉率超标导致微信/支付宝侧限权或处罚** | 商户经营/平台声誉 | 三口径投诉率监测与预警线提前干预;高危自动限权与平台介入;服务商辅导商户处理流程;投诉处理时效考核 | 
| 汇付/富友签约与入网周期不可控 | 进度 | P0 即启动商务申请;P1 用原生通道+Demo 插件先行;插件按 tp-demo 模板预开发,拿到密钥即可联调 |
| 平台暂无微信服务商/支付宝 ISV 资质 | 功能 | 原生进件后置,新商户进件走汇付/富友;原生通道先以"自备商户号"模式服务存量商户 |
| 微信开放平台"网站应用"未过审 | 功能 | 扫码登录后置,验证码+一键登录先行,架构预留 |
| 单机部署故障(轻量服务器) | 可用性 | COS 异地备份+快照快速重建;监控告警;预留拆分升级路径(3.4 节) |
| 通道政策/接口变更(含微信投诉接口调整) | 中 | 插件隔离变更面;版本兼容校验;通道健康监控告警;投诉同步失败降级为手动登记 |
| 安全攻击(重放/越权/拖库) | 资金/数据 | 第 10 章全量措施 + 宝塔安全基线 + 渗透测试 + 应急预案演练 |
| 进度延误 | 上线 | 里程碑双周评审;一期范围刚性,MVP 先行;投诉中心若进度紧张可将"投诉查询 API(可选)"后置 |
| 人员流动 | 维护 | 文档/规范/注释强制标准,插件契约清晰降低耦合 |

---

## 16. 验收标准(摘要)

1. 三端后台功能与第 6 章清单一致,权限节点与数据范围验证通过(含横向越权测试)。
2. 微信/支付宝官方沙箱全支付方式走通;汇付/富友测试环境入网-收款-退款-代付全链路联测通过;Demo 通道全流程(含代付/进件/投诉/回调模拟)走通。
3. **投诉中心**:微信投诉接口测试数据同步入库(重复通知不重复建单);站内投诉全流程(四类入口进入-提交-身份校验-受理-回复-消费者进度跟踪与"确认解决/仍有异议"闭环)演示通过;商户端与服务商端"近 7 天投诉率"展示且三口径一致、数据范围隔离正确;投诉率预警与风控动作演示通过。
4. 服务商无任何自助注册入口(前端+接口双重验证);商户三种开通方式行为符合 2.2。
5. 自有聚合收银台:品牌可配置、环境自动识别、状态实时确认、中英切换,验收演示通过。
6. 新开发者仅凭《插件开发规范》+ Demo 插件 + 脚手架,可在 1 个工作日内完成一个可安装运行的自定义通道插件(验收演示项)。
7. 快捷登录(阿里云短信验证码/一键登录/微信扫码,按资质就绪情况)可用;微信公众号模板消息与邮件通知按事件配置可达、可查、可重发。
8. 全站源码与页面零 Emoji(CI 检查通过),图标全部 SVG;中英文切换覆盖三端后台、收银台与投诉页,缺失词条扫描为零。
9. 渗透测试高危漏洞清零;性能达第 11 章指标;对账连续 7 个自然日零差错。

---

## 附录 A:核心数据表概要

| 分组 | 表 |
| --- | --- |
| 账号权限 | users, roles, permissions, role_permissions, user_roles, user_security(2FA/设备), login_logs |
| 商户/服务商 | service_providers, merchants, merchant_service_relations, merchant_audit_logs, merchant_apps(应用/密钥), app_ip_whitelists |
| 通道 | channels, channel_accounts(上游商户号池), channel_merchant_maps(进件映射), channel_health_stats |
| 插件 | plugins, plugin_configs, plugin_config_versions |
| 交易 | pay_orders, order_channels(路由尝试记录), refunds, transfers, transfer_reviews, callbacks_in(上游回调), notify_out(商户通知) |
| **投诉** | complaints(投诉单:来源渠道/类型/状态/SLA), complaint_replies(回复与协商记录), complaint_materials(凭证影像), complaint_sync_logs(渠道同步日志), complaint_rate_stats(投诉率小时级预聚合) |
| 进件 | onboardings, onboarding_materials |
| 分润 | profit_sharing_rules, profit_sharing_flows |
| 对账 | bill_files, reconcile_results, reconcile_diffs |
| 通知 | notify_events, notify_templates, notify_receivers, notify_records |
| 风控 | risk_rules, risk_blacklists, risk_hits |
| 系统 | sys_configs, sys_i18n_messages(词条/双语), audit_logs(哈希链), operation_logs, announcements, cashier_branding(收银台品牌) |

## 附录 B:项目目录结构(规划)

```
jiameng-pay/
├── jiameng-pay-core/              # 核心框架:订单/账户/RBAC/路由/投诉/事件总线/幂等
├── jiameng-pay-openapi/           # 开放API(签名/防重放/限流)
├── jiameng-pay-admin-api/         # 三端后台API
├── jiameng-pay-cashier/           # 自有聚合收银台(H5,中英)
├── jiameng-pay-complaint-h5/      # 消费者服务页(H5):订单查询/站内投诉/进度跟踪(中英,可并入cashier工程)
├── jiameng-pay-web/               # 三端后台前端(单工程多入口, Vue3+TS+i18n)
├── jiameng-pay-doc/               # API文档站 + 插件开发规范(中英)
├── plugins/
│   ├── channel-wxpay-native/      # 微信原生(含投诉同步)
│   ├── channel-alipay-native/     # 支付宝原生(含投诉同步)
│   ├── channel-huifu/             # 汇付天下(聚合/进件/代付/分账)
│   ├── channel-fuiou/             # 富友(聚合/入网/代付/分账)
│   ├── channel-tp-demo/           # 三方通道通用模板
│   ├── channel-demopay/           # Demo插件(全注释,含模拟投诉)
│   ├── notifier-email/
│   ├── notifier-wechat-tmpl/
│   ├── auth-sms/                  # 阿里云短信驱动
│   ├── auth-oneclick/  auth-wechat-oauth/
│   └── ext-risk-rule-demo/
├── plugin-scaffold/               # 插件脚手架
├── sdks/                          # PHP/Java/Python/Node 商户SDK与示例
├── assets/brand/logo.png          # 品牌Logo(已存入)
└── deploy/                        # 宝塔部署脚本/Nginx配置/监控栈/备份脚本
```

## 附录 C:待确认事项(V1.2 更新)

1. **Logo 源文件**:当前提供的是深色底 PNG,需要透明底或白底版本(方形 PNG/SVG/AI 源件),用于后台浅色界面与收银台。
2. **汇付/富友商务资料**:两家公司的合作协议、商户号/系统号与密钥、接口文档版本(决定插件联调排期,P0 启动申请)。
3. **平台资质**:是否具备或计划申请微信支付服务商商户号、支付宝 ISV 资质(决定原生进件上线时间,不阻塞首发);微信投诉 2.0 接口、支付宝投诉接口的开通权限随商户号资质确认。
4. **腾讯云资源**:轻量服务器具体规格(建议 4C8G 起,数据盘独立)、域名与 ICP 备案进度、HTTPS 证书、COS 桶规划。
5. **微信侧账号**:公众号(服务号,认证)AppID、微信开放平台"网站应用"(扫码登录)申请进度、模板消息库模板报备(含投诉类模板)。
6. **阿里云短信**:签名与模板报备(注册/登录验证码、进件与代付通知类;若站内投诉需触达消费者,投诉进度通知类模板一并报备),AccessKey 专用子账号开通。
7. **英文版范围确认**:三端后台+收银台+投诉页全量双语已列入本期;API 文档站英文版与邮件英文模板是否本期必须(当前按"文档站中文为主、邮件双语"规划)。
8. **投诉相关商务口径**:站内投诉是否需要向消费者展示处理结果公示页;平台介入仲裁的服务商协议条款(建议法务随主协议一并起草)。

---

编制:四川佳梦云网络科技有限公司 · 技术部