GAC 报文工具 · LightSwift · frontend-intro-v5

1. 页面概览

GAC 报文工具是 LightSwift 的支付发起端（GAC 客户端软件版原型），路由 /swift/gac，对应源码 action/web/src/views/SwiftGACPage.vue（M5.4c）。GAC 客户端 = 报文生成 + 国密签名 + 加密发送：页面填写付款人/收款人账户、金额、币种、附言与可选任务编号，点「发起支付」后由后端生成 pacs.008 → SM3 摘要 + SM2 签名 → SM4-GCM 加密 → 经星地链路发送至 HCC，并返回支付详情（ID、状态、报文 msg_id、签名、链路结果）。

页面下方为在途支付列表，点击行可展开详情（状态流转、原因、链路结果、SM3 哈希、SM2 签名与 pacs JSON）；对处于 SENT 状态的支付可模拟 HCC 回执（ACCP 接受 / RJCT 拒绝）。一句话总结：GAC 报文工具是 LightSwift 端到端支付链路的发起端与状态跟踪台。

2. 访问入口

路由与菜单：/swift/gac（SwiftLayout 子路由），name SwiftGAC，标题「Swift GAC 报文工具」；无 requiresAuth，onMounted 校验 swift_token，未登录自动回 /swift。
认证与权限：使用独立 swift_token；/payments/* 为 JWT-only，/admin/accounts（账户下拉数据源）需 admin 角色。
端口与 API 前缀：Swift 后端 18084，前端前缀 /swift-api（Vite 代理重写为 /api/v1）。

3. 界面布局

+--------------------------------------------------------------+
| 子导航：工作台 | 报文实验室 | GAC 报文工具(激活) | HCC 管控台     |
+--------------------------------------------------------------+
| 页头：GAC 报文工具  GAC 客户端 = 报文生成+国密签名+加密发送  [刷新] |
+--------------------------------------------------------------+
| 发起支付（card）：付款人账户▾/名称  收款人账户▾/名称              |
|   金额（元）/ 币种▾  附言（RmtInf）/ 任务编号（可选）             |
|   [发起支付]                                                    |
+--------------------------------------------------------------+
| 支付详情（card，发起成功后出现）：ID/msg_id/金额/付款人/收款人     |
|   链路结果 / SM3 哈希 / SM2 签名                                 |
|   [模拟回执：接受（ACCP）] [模拟回执：拒绝（RJCT）]（仅 SENT 可用）|
+--------------------------------------------------------------+
| 在途支付列表（card）：ID/状态/msg_id/金额/币种/付款人/收款人/时间  |
|   点击行展开：状态流转 DRAFT→SIGNED→SENT→ACKED/REJECTED + pacs   |
+--------------------------------------------------------------+

各板块职责：发起支付表单收集支付要素并提交到 /payments；支付详情卡展示最近一笔支付的完整要素与国密签名信息，并提供模拟 HCC 回执按钮；在途支付列表展示全部支付并支持行展开查看状态流转与报文结构化内容。

4. 交互元素

控件	位置	含义与作用
付款人 / 收款人账户下拉框	发起支付	数据源 `GET /admin/accounts`，选项显示 `id（owner · 币种 · 余额）`，切换自动回填名称与币种
付款人 / 收款人名称输入	发起支付	选中账户后自动带出 owner，也可手工修改
金额（元）/ 币种下拉框	发起支付	金额以元输入，提交转 `amount_cents` 定点分；币种列表 CNY/EUR/USD/GBP/JPY
附言（RmtInf）/ 任务编号	发起支付	附言进报文 RmtInf；任务编号留空则不挂航天扩展 Aero（`aero` 块）
发起支付按钮	发起支付	调 `POST /payments`，成功后刷新支付列表并在详情卡展示结果
模拟回执：接受（ACCP）/ 拒绝（RJCT）	支付详情	仅 `status === 'SENT'` 可用，调 `POST /payments/{id}/ack` 推进到 ACKED / REJECTED
列表行点击 / 展开	在途支付列表	点击行或「展开」切换详情行（状态流转、原因、链路结果、SM3/SM2、pacs JSON），「收起」折叠

5. 后端关联

API 客户端：swiftClient.js，baseURL /swift-api/v1，timeout 30000；成功 {code:0, data} 自动解包。

端点表：

方法	路径	用途
GET	`/admin/accounts`	结算账户列表（账户下拉数据源，需 admin）
POST	`/payments`	发起支付：`{msg_type, dbtr_name/acct, cdtr_name/acct, amount_cents, ccy, rmt_inf[, aero]}`
GET	`/payments`	在途支付列表
POST	`/payments/:id/ack`	模拟 HCC 结算回执 `{status: ACCP \| RJCT}`

关键机制：

支付状态机：DRAFT → SIGNED → SENT → ACKED / REJECTED；列表状态徽标按 ACKED 绿 / REJECTED 红 / 其余黄（pending）着色，回执按钮仅 SENT 态可用。
GAC 客户端链路：POST /payments 由后端一次完成 Pacs008 生成 → 国密签名 → 星地链路加密发送，返回 {id, status, msg_id, link_result, hash_hex, signature_hex, pacs}。
金额单位换算：表单输入元，yuanToFen 转定点分 int64 字符串；详情与列表用 fenToYuan 转回元（pacs.Amount）。
航天扩展：任务编号 mssn_id 填写时附带 aero: {mssn_id, svc_type: 'LAUNCH', lch_vhcl: 'CZ-7A', trgt_orbt: 'LEO 500km'}；留空则 payload 不带 aero 字段。

6. 权限与安全

认证：所有请求附 swift_token Bearer，401 自动清 token 回 /swift。
角色限制：/payments/* 仅需登录；/admin/accounts 挂 admin 中间件，非 admin 账户下拉加载失败。
写操作防护：回执操作仅限 SENT 状态（按钮置灰），避免对已终态支付重复回执。

7. 常见问题与排错

问题 1：账户列表加载失败

现象：付款人/收款人下拉为空，弹「账户列表加载失败」。

原因：/admin/accounts 走 admin 中间件，当前账号非 admin，或后端未启动。

处理：用 admin/admin1 登录重试；确认 18084 进程存活。

问题 2：发起支付失败

现象：点「发起支付」报错。

原因：付款人账户余额不足、金额非法（非正数）、或收款/付款账户不存在。

处理：检查金额大于 0、账户下拉选择有效账户（seed 中 LS-CN-0001-BJ 初始 100 万 EUR 可正常扣款）。

问题 3：回执按钮置灰无法点击

现象：「模拟回执」两个按钮不可点。

原因：当前支付状态不是 SENT（如已是 ACKED / REJECTED，或刚发起仍处中间态）。

处理：等支付推进到 SENT 后再操作；已终态支付无需回执。

问题 4：未登录访问 `/swift/gac` 被弹回 `/swift`

现象：直接输 URL 进入 GAC 页，闪回工作台登录页。

原因：onMounted 检测不到 swift_token，主动重定向。

处理：先在工作台用 admin/admin1 登录，再进入 GAC 页。

8. 已知缺陷与边界

项	说明
无分页	`/payments` 与 `/admin/accounts` 全量返回，数据量大时列表变长
详情依赖本地 state	支付详情仅展示最近一笔/当前展开行，刷新后需从列表重新展开
账户余额展示单位	账户下拉余额为元字符串（后端 AmountStr），非分
无退款/撤销	支付只支持 ACCP/RJCT 回执，无取消或退款操作