星线 Pay 技术概览
星线 Pay 当前包含公开介绍页面与独立的微信支付 Native 后端。后端可以按服务端商品表创建支付订单、核验通知和主动对账；公开页面中的登录、注册地区引导尚未形成用户支付操作闭环。
入口与实现范围
公开入口为 星线 Pay。公开前端是 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 定义上述契约。公开产品关系见 官网，相关政策见 法律中心。