# 星线 Pay 技术概览

星线 Pay 当前包含公开介绍页面与独立的微信支付 Native 后端。后端可以按服务端商品表创建支付订单、核验通知和主动对账；公开页面中的登录、注册地区引导尚未形成用户支付操作闭环。

## 入口与实现范围

公开入口为 [星线 Pay](https://pay.thestarline.cn/)。公开前端是 HTML、CSS、Canvas 与静态地区数据，展示地球、品牌和地区选择；地区选择后的不可用提示不等于用户注册成功、支付资格校验通过或已连接钱包。

支付服务使用 Go，依赖微信支付 API v3 官方 SDK 和 SQLite 驱动。模块声明 Go 1.27.2、微信支付 SDK v0.2.21、`modernc.org/sqlite` v1.60.1。这里的版本来自源码依赖声明，不代表生产进程已按该版本构建或验收。

| 能力 | 当前实现 |
| --- | --- |
| 商品与金额 | 服务端商品记录控制 SKU、说明、分金额和启用状态 |
| 下单 | 内部系统提交业务订单标识，服务端调用 Native 下单 |
| 查询与主动对账 | 查询本地订单，向微信查询并验证成功结果 |
| 支付通知 | 官方 SDK 验签解密后严格核对订单与金额 |
| 履约 | 未提供通用发货、云资源开通或业务交付实现 |

该后端不提供余额钱包、资金托管、汇兑、跨境清结算或金融交易账户。源码也没有退款 HTTP 路由，不能因为上线检查文档提及退款就宣称已具备退款接口。

## 服务间接口与字段

`/internal/` 路由使用 `X-Internal-Key`，通过摘要与常量时间比较校验。该凭据不能交给浏览器或嵌入公开 JavaScript。公开反向代理需要按业务职责限制可达路径，不能把内部下单接口当作匿名客户端 API。

| 接口 | 方法 | 作用 |
| --- | --- | --- |
| `/healthz` | GET | 返回进程状态与创建支付的配置就绪标志 |
| `/internal/orders` | POST | 为已知服务端 SKU 预留或复用订单并取得支付二维码地址 |
| `/internal/orders/{tradeNo}` | GET | 查询订单的受限公开字段 |
| `/internal/orders/{tradeNo}/reconcile` | POST | 主动查询支付结果并尝试更新本地状态 |
| `/wechat/notify` | POST | 接收微信支付成功通知 |

创建请求只接受 `source`、`source_order_id`、`customer_ref`、`sku`。调用方不传金额；服务器按照启用商品的 `amount_fen` 定价。标识只允许字母数字开头，后续为字母数字、下划线、句点、冒号或连字符；长度上限依次为 32、64、128、64。JSON 限制为 2048 字节，拒绝未知字段和额外 JSON 值。

订单响应包含 `trade_no`、`source_order_id`、`sku`、`description`、`amount_fen`、`status`、`code_url`、`expires_at_unix`。金额为整数分，失效时间为 Unix 秒；`code_url` 是支付流程材料，不应作为普通公开内容长期发布。商户配置与内部身份字段不在这组响应中输出。

## 幂等与状态流转

SQLite 对来源与业务订单号的组合、支付订单号和交易号设置唯一约束。首次下单预留 `created` 记录；取得预支付结果后为 `prepay`；核验成功后为 `paid`；模型还包含 `closed`。

重复请求不能仅因业务订单号相同就任意复用：服务会检查 SKU、客户引用和商户/App 上下文是否一致。已支付订单返回原结果；未过期且已有预支付结果的订单复用原二维码；过期或冲突请求返回明确错误。进程内创建锁用于控制并发调用，数据库唯一约束承担持久层约束。

通知最多接收 65536 字节，先由官方 SDK 验签并解密，再要求事件和交易结果符合成功契约。入账必须同时匹配订单号、商户号、App ID、总金额、人民币币种与非空交易号；不能只凭浏览器“支付完成”或一条未验证回调标记成功。主动对账同样复用成功验证，非成功结果不会直接伪造本地支付成功。

## 开启条件、失败与验收

创建支付需要显式启用开关，并具备商户/App 配置、存储、网关和内部调用凭据。未启用返回 `503 PAYMENTS_DISABLED`；商品不可用或订单不存在为 404；订单过期或业务冲突为 409；上游支付服务异常为 502。健康接口中的就绪布尔值只是本地条件判断，不验证微信权限、证书有效性、外网通知可达或实际扣款。

资料依据 2026-10-23 源码整理。历史“关闭支付”记录不能替代当前环境状态检查，代码具备下单能力也不能替代真实商户验收。接入业务必须另外验证通知重复投递、超时主动对账、金额冲突和支付成功后的幂等履约。

## 源码依据

支付模块的 `payment/go.mod`、`http.go`、`domain.go`、`service.go`、`store.go`、`wechat_gateway.go` 与 `cmd/payment/main.go` 定义上述契约。公开产品关系见 [官网](https://document.thestarline.cn/website/)，相关政策见 [法律中心](https://document.thestarline.cn/legal/)。