# 外部能力与当前限制

API 路由存在不表示真实外部环境已联通。项目技术路线和试点验收状态明确要求用实际第三方回执验证。

| 能力 | 当前可依赖的行为 | 不能假设 |
| --- | --- | --- |
| 微信登录 | 居民 session 路由存在，调用微信登录适配流程 | 测试/生产 app 凭据、手机号授权、审核备案均已配置 |
| 微信支付 | V3 adapter 和 callback 验签/核销路径存在 | 未配置商户、证书或回调时可成功付款；请求超时等于支付失败 |
| 银行缴费 | `BANK` payment channel 接入点存在 | 银行签约、报文、签名和应答契约已经确认 |
| 门禁 | 设备、开门和结果记录接口存在 | 真实设备在线或响应成功；请求发出但结果未知不得显示成功，也不得自动盲目重试 |
| 福行 | 预约及 handover 记录/人工核对存在 | 真实提交、收单、线下履约/收费已打通；未知结果不得重复发送，先核对凭据 |
| 公众号通知 | 站内 inbox 有本地能力，触达尝试有状态记录 | 公众号模板和凭据就绪；未配置 adapter 不能伪造已送达，UNKNOWN 不自动重发 |
| 语音识别 | `voice-drafts` 支持文本草稿与人工确认 | ASR 已接入；确认草稿不会自动建业务订单 |
| 私有附件 | 服务端鉴权读取、S3 私有存储 adapter | 生产 bucket、真实订单恢复/备份及权限验收全部完成。附件访问失败须安全拒绝，不返回对象地址 |
| 商店外链 | 小区目录和 destination 校验路由存在 | 跳转成功代表快团团已售出商品；购买及交易由外部渠道完成 |

## 安全失败状态

- 未配置支付渠道应返回明确不可用错误（通常 503），不创建“已支付”结果。明确拒绝和结果未知必须区分；未知时保留支付锁并查单。
- 微信 callback 必须按渠道原始字节验签；金额、商户、币种或订单不符应隔离待核，不确认到账。回调成功应答不是可由前端模拟的 API。
- 门禁设备停用、离线、忙、超时分别作为失败/未知显示。前端不要把缺失结果映射为成功。
- 福行人工核对需授权员工记录决定、版本、请求标识及证据引用；待发送的预约不能手工标成已收。
- 私有照片、签名、联系资料只通过记录归属校验后的 API 读取；对象存储 key/URL 不向客户端暴露。

## 外部联调前置

正式 API 域名、测试凭据、银行/门禁/福行正式契约、微信支付商户参数、公众号模板和生产部署配置仍由受控联调环境提供。请将真实凭据注入 secret manager/环境变量，不写进前端包、文档、仓库或 issue。