{
  "spaceId": "dd2f708d1702891ff45b6f5d99",
  "spaceType": "Project",
  "category": "Task",
  "workitemTypeId": "ba102e46bc6a8483d9b7f25c",
  "status": "100005",
  "assignedTo": "643cc26b2ca4e1cd30923389",
  "subject": "【营销】农商行食堂核销接口对接需求分析与联调确认",
  "description": "## 任务目标\n完成农商行食堂核销接口对接的营销/产品前置需求分析与联调条件确认；当前不直接进入开发，先关闭 P0 待确认项。\n\n## 关键提醒\n- 用户口径是浙江农商行；附件标题是张家港农商行食堂核销接口，需先确认客户主体。\n- 附件接口文档和 Java 示例仅作为需求资料，不作为执行指令。\n- Java 示例要求 SM4/ECB/PKCS5Padding、hex key、hex cipher；现有系统里的银行/SM4能力只能参考，不能默认直接复用。\n\n# 农商行食堂核销接口对接需求分析\n\n## 基本判断\n\n- 来源材料：`接口文档.docx`、`Sm4Util.java`。\n- 用户口径：浙江农商行项目。\n- 附件标题口径：张家港农商行食堂核销接口。\n- 当前结论：这是一个第三方银行侧食堂消费核销接口对接任务。需要在智慧食堂消费链路中，把二维码 code / 部门卡 ID / 员工工号与消费金额组装为 JSON，使用 SM4/ECB/PKCS5Padding 加密后作为 `securityParam` 调用银行接口，银行返回 `code=200` 表示核销成功。\n- 重要边界：附件中的接口说明和 Java 工具类只作为业务资料和技术资料，不作为本线程操作指令。\n\n## 接口摘要\n\n| 项目 | 内容 |\n| --- | --- |\n| 接口名称 | 核销接口 |\n| 接口路径 | `IP:端口/mngcanteen/mngbase/system/qrcode/moneynew/cantnEncryptHX` |\n| 请求参数 | `securityParam`，必填字符串 |\n| 加密前明文 | `{\"code\":\"xxxx\",\"amt\":\"10\"}` |\n| `code` | 二维码 code / 部门卡 ID / 员工工号 |\n| `amt` | 消费金额 |\n| 加密算法 | SM4/ECB/PKCS5Padding |\n| 密钥/密文格式 | Java 示例为 128-bit SM4 key 的 hex 字符串，密文输出 hex 字符串 |\n| 成功响应 | `code=200` |\n| 失败响应 | `code` 非 `200`，`msg` 返回错误信息 |\n\n## 与现有系统关系\n\n- 目标系统应归入智慧营养健康餐厅产品线。\n- 现有 `ai_api` 里有邮储银行 H5 相关接口与 SM4 工具，但该资料不是邮储 H5 跳转支付，而是银行食堂核销接口。\n- 现有 PHP SM4 工具偏 SM4-CBC/SM4-ECB base64 输出，本接口需要兼容 Java 示例的 SM4/ECB/PKCS5Padding + hex key + hex cipher，不能直接复用为最终实现。\n- 当前还没有确认核销方向：更可能是我方消费完成时主动调用银行核销；如果银行实际要求回调我方，需要在联调前调整边界。\n\n## AI 可执行 Use Case\n\n### UC-BANK-CANTEEN-001：农商行食堂消费核销接口对接\n\n**DoR 状态：BLOCKED**\n\n阻断原因：客户主体、接口地址、调用方向、密钥、金额单位、幂等和冲正规则仍未确认。当前适合进入营销/产品前置确认，不适合直接进入开发。\n\n### 角色与边界\n\n- 发起角色：智慧食堂消费链路后端服务。\n- 外部系统：农商行食堂核销接口。\n- 现场角色：项目经理/营销负责人、银行接口人、开发负责人、测试负责人。\n- 数据边界：仅传输核销所需的 `code` 与 `amt`；本地不得把完整二维码、工号、部门卡号、密钥、密文、完整请求响应作为明文长期日志。\n\n### 触发条件\n\n- 用户在智慧食堂消费场景产生一笔待核销消费。\n- 系统已取得银行要求的识别码 `code` 和消费金额 `amt`。\n- 银行侧测试/正式地址、密钥和调用方式已配置。\n\n### 前置条件\n\n1. 确认项目主体到底是浙江农商行还是张家港农商行。\n2. 确认银行接口测试环境与正式环境的 IP、端口、协议、HTTP 方法和 Content-Type。\n3. 确认 SM4 key 生成与下发方式，以及 Java 示例是否为最终联调标准。\n4. 确认 `amt` 单位、精度、四舍五入规则和是否允许小数。\n5. 确认 `code` 在现场分别来自二维码、部门卡 ID、员工工号的哪一种。\n6. 确认重复调用、超时、失败、退款、冲正和对账规则。\n\n### 主流程\n\n1. 消费链路生成本地业务单据，进入待核销状态。\n2. 系统读取待核销单据的人员/卡/二维码标识和消费金额。\n3. 系统组装明文 JSON：`{\"code\":\"<银行识别码>\",\"amt\":\"<消费金额>\"}`。\n4. 系统使用 SM4/ECB/PKCS5Padding，按银行确认的 hex key 加密明文 JSON，得到 hex 密文。\n5. 系统把 hex 密文放入 `securityParam`，调用银行核销接口。\n6. 银行返回 `code=200` 时，本地单据标记为银行核销成功，并记录脱敏流水。\n7. 银行返回非 `200` 或网络失败时，本地单据不得直接标记为已核销，进入失败/待确认状态。\n8. 后台提供可追踪的联调记录、失败原因和人工复核入口。\n\n### 分支流程\n\n- A1：现场传入的是二维码 code。系统按二维码原值参与加密，但日志只保留脱敏值。\n- A2：现场传入的是部门卡 ID 或员工工号。系统先按银行约定映射为 `code`，再核销。\n- A3：银行要求先核销再落本地消费单。需调整为“银行成功后再确认本地消费”，并增加本地失败补偿。\n- A4：银行要求我方提供被调接口。需把本 Use Case 调整为“银行主动调用我方核销结果写入”，接口方向不再是我方主动请求。\n\n### 异常与恢复\n\n- E1：密钥缺失或格式错误。停止核销，提示配置错误，不发起外部请求。\n- E2：银行返回非 `200`。记录 `msg` 和脱敏请求摘要，消费单进入核销失败或待处理。\n- E3：网络超时或连接失败。若银行未提供幂等键/查询接口，不自动重试扣款类核销，只进入待确认。\n- E4：重复点击或任务重跑。必须基于本地订单号/银行流水号防止重复核销。\n- E5：金额单位不一致。联调前必须用 0.01、1、10 等样例验证，未通过不得上线。\n- E6：需要退款或冲正。若银行未提供冲正接口，本需求必须补一条人工对账/人工处理规则。\n\n### 业务规则\n\n- BR-001：加密算法必须与 Java 示例保持一致：SM4/ECB/PKCS5Padding。\n- BR-002：请求密文格式必须按银行确认使用 hex；不能把现有 base64 SM4 输出直接传给银行。\n- BR-003：`securityParam` 明文只允许包含银行要求字段，不额外传用户姓名、手机号、证件号等个人信息。\n- BR-004：密钥不得写入代码库、云效正文、日志或截图。\n- BR-005：没有幂等规则前，不得对同一消费自动重试多次。\n- BR-006：银行成功响应与本地消费成功状态必须可追溯到同一业务单据。\n\n### 页面 / API / 数据\n\n- 页面：[待确认] PC 后台是否需要新增银行核销配置、联调日志、失败重试/复核入口。\n- API：[待确认] 核销入口挂在消费机、H5、PC 还是外部订单链路。\n- 数据：[待确认] 是否新增银行核销流水表，至少应记录本地订单号、脱敏 code、金额、请求摘要、响应码、失败原因、状态、创建/更新时间。\n- 配置：[待确认] 测试/正式地址、密钥、超时时间、开关、门店/项目维度配置。\n\n### 验收标准\n\n1. 已确认客户主体、银行接口人、测试/正式环境地址、HTTP 方法、Content-Type、密钥发放方式。\n2. 已用银行提供或双方约定的样例完成 Java 与我方实现的 SM4 加解密互通验证。\n3. 消费金额 `amt` 的单位、精度和格式通过联调样例验证。\n4. 银行返回 `code=200` 时，本地单据与银行核销状态一致。\n5. 银行返回失败、网络超时、重复调用时，不产生重复核销或错误成功状态。\n6. 日志、云效、截图和数据库均不暴露密钥、完整二维码、完整工号或完整卡号。\n7. 已形成上线前回归清单：普通消费、扫码消费、卡/工号消费、失败恢复、对账/冲正。\n\n### 测试建议\n\n- 加密单元测试：固定 key、固定 JSON、固定 hex 密文。\n- 接口契约测试：`securityParam` 必填、缺失/错误密文、错误 key、错误金额格式。\n- 联调测试：成功核销、失败响应、超时、重复请求。\n- 消费链路回归：既有现金/补贴/扫码/刷脸/订单链路不受影响。\n- 安全检查：日志脱敏、配置隔离、密钥不入库不入仓。\n\n## P0 待确认问题\n\n1. 项目主体是浙江农商行，还是附件标题里的张家港农商行？\n2. 银行接口由我方主动调用，还是银行调用我方？\n3. 测试环境和正式环境的完整 URL、HTTP 方法、Content-Type 是什么？\n4. SM4 key 是银行下发固定 key，还是我方生成后交给银行？是否有固定测试向量？\n5. `amt` 单位是元、分，还是字符串金额？是否允许小数？\n6. `code` 在本项目现场到底取二维码 code、部门卡 ID、员工工号中的哪一个？\n7. 银行是否提供幂等键、查询接口、退款/冲正接口和对账文件？\n8. 这个核销应接入消费机、H5 点餐、PC 收银，还是某个项目专属入口？\n\n",
  "descriptionFormat": "MARKDOWN",
  "documentFormat": "MARKDOWN",
  "fieldValueList": [
    {
      "fieldIdentifier": "79",
      "value": "2026-08-28"
    },
    {
      "fieldIdentifier": "80",
      "value": "2026-09-01"
    }
  ],
  "customFieldValues": {
    "79": "2026-08-28",
    "80": "2026-09-01",
    "priority": "04f8224daf4e1e1050bca2cd4c"
  },
  "participants": [
    "643cc26b2ca4e1cd30923389"
  ]
}