报文实验室

1. 页面概览

报文实验室是 LightSwift 的报文构造与解析工具页，路由 /swift/messages，对应源码 action/web/src/views/SwiftMessagePage.vue（M5.4c）。核心能力分四块：报文生成（按类型表单生成 pacs.008 / pacs.002 / mt103 / aero.pacs.001 报文，结果支持 XML 原文 / JSON 结构化 / MT 文本三种视图）；报文解析（粘贴报文原文显示结构化 JSON）；报文校验（返回 {valid, errors[]} 红绿提示）；国密签名 / 验签（SM3 摘要 + SM2 签名，展示签名 hex 与哈希）。

生成与签名结果会记录到本地历史表，可回查报文全文或载入解析区。一句话总结：报文实验室是 LightSwift 全报文类型的生成、解析、校验与国密签名验签一体化工作台。

2. 访问入口

• 路由与菜单：/swift/messages（SwiftLayout 子路由），name SwiftMessages，标题「Swift 报文实验室」；无 requiresAuth，但 onMounted 会校验 swift_token，未登录自动 router.replace('/swift') 回登录页。
• 认证与权限：使用独立 swift_token，请求经 swiftClient.js 附 Bearer；/messages/* 为 JWT-only（无需 admin 角色）。
• 端口与 API 前缀：Swift 后端 18084，前端前缀 /swift-api（Vite 代理重写为 /api/v1）。

3. 界面布局

+--------------------------------------------------------------+
| 子导航：工作台 | 报文实验室(激活) | GAC 报文工具 | HCC 管控台     |
+--------------------------------------------------------------+
| 页头：报文实验室  报文类型 n 种  [刷新类型]                      |
+--------------------------------------------------------------+
| 报文生成（card）：报文类型▾ 币种▾ 金额（元）                     |
|   按类型切换业务字段（pacs/aero/mt103/pacs.002 各自表单块）      |
|   [生成报文]                                                    |
+--------------------------------------------------------------+
| 生成结果（card，生成后出现）：XML 原文 | JSON 结构化 | MT 文本     |
|   SM3 摘要 + [解析为 JSON][校验][签名]                          |
+--------------------------------------------------------------+
| 报文解析 / 校验（card）：textarea + [解析][校验] + 结果区        |
+--------------------------------------------------------------+
| 国密签名 / 验签（card）：报文原文 + SM2 私钥/公钥 hex + 签名 hex  |
|   [签名][验签] + 签名/哈希/记录ID 与验签结果                    |
+--------------------------------------------------------------+
| 最近生成 / 签名报文（card）：本地历史表（回查 / 载入解析）        |
+--------------------------------------------------------------+

各板块职责：子导航与页头提供页面切换与类型刷新；生成表单按所选报文类型动态切换字段；生成结果卡用三个 tab 展示不同格式并附带 SM3 摘要；解析/校验卡用于对任意报文原文做结构化与合法性检查；签名/验签卡完成国密 SM3+SM2 操作；历史表本地记录最近生成/签名项，可回查全文。

4. 交互元素

5. 后端关联

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

端点表：

关键机制：

• 金额单位换算：表单输入「元」，前端 yuanToFen 转为定点分字符串（Math.round(n*100)），非法/非正数返回 "0"。
• 格式驱动的 tab：生成结果按 format === 'mt' 默认切到「MT 文本」，其余默认「XML 原文」；JSON 结构化数据需手动点「解析为 JSON」调 parse 接口生成。
• 签名链路：/messages/sign 只传 content 与可选私钥 hex，返回签名、SM3 哈希与记录 ID；验签必须提供公钥 hex 与签名 hex，成功提示「验签通过：签名与报文一致」。
• 本地历史：history 为内存数组（生成/签名成功后 unshift），仅本次会话有效，回查/载入解析走 GET /messages/:id。

6. 权限与安全

• 认证：/messages/* 仅需 swift_token Bearer（JWT-only），未登录页面直接重定向回 /swift。
• 写操作防护：签名私钥 hex 由用户手工输入，页面不做持久化；校验失败以 errors 列表展示不落库。
• 数据范围：历史记录仅存浏览器内存，刷新即清空，无服务端个人数据存储。

7. 常见问题与排错

问题 1：报文类型加载失败 / 类型数为 0

现象：页头显示「报文类型 0 种」或弹「报文类型加载失败」。

原因：GET /messages/types 失败，后端 18084 未启动或 token 失效。

处理：确认后端进程存活、重新登录后再进页面；Network 面板查看 401/404。

问题 2：生成失败提示金额相关错误

现象：点「生成报文」报错。

原因：金额非正数或格式非法，yuanToFen 返回 "0" 后端拒绝。

处理：金额输入需大于 0 的数字（默认 50000000），重新生成。

问题 3：验签一直失败

现象：「验签」结果始终为「验签失败：签名与报文不匹配」。

原因：公钥 hex / 签名 hex 与报文原文不匹配，或签名 hex 为空、私钥留空导致签名未生成。

处理：先用「签名」生成一组 {signature, hash}，再原样回填签名 hex 与对应 HCC 证书公钥验签。

问题 4：刷新页面后历史记录消失

现象：历史表为空，之前生成的报文找不到。

原因：历史为前端内存记录，刷新即丢。

处理：生成前先记下 msg_id，刷新后可点「回查」用 GET /messages/{id} 找回，或在 GAC 页发起支付让报文落到后端。

8. 已知缺陷与边界