重置项目上下文与规范文档

docs/integrations/alipay/README.md

@@ -0,0 +1,30 @@
+# 支付宝接入契约
+
+## 元数据
+
+- Owner：支付适配维护人
+- 实现：`pkg/alipay/`，`github.com/smartwalle/alipay/v3 v3.2.29`
+- 核验日期：2026-08-07
+- 环境：支付宝沙箱或生产商户；本文不保存凭证
+
+## 当前实际使用范围
+
+系统使用手机网站支付 `TradeWapPay` 生成签名支付 URL，并处理异步通知；未发现退款、转账或当面付调用。`payment.PaymentNo` 写入 `out_trade_no`，金额从分转为元字符串，产品码固定为 `QUICK_WAP_WAY`，有效期存在且晚于当前时间时写入 `time_expire`。
+
+## 配置、认证与关键字段
+
+配置来自支付配置记录：AppID、应用私钥、支付宝公钥、通知地址和返回地址。SDK 使用 RSA2 完成请求签名与通知验签。请求关键字段为 `notify_url`、`return_url`、`subject`、`out_trade_no`、`total_amount`、`product_code`、`time_expire`。
+
+通知只有 `trade_status=TRADE_SUCCESS` 或 `TRADE_FINISHED` 才进入成功处理；处理前还需匹配商户支付号、配置和金额。业务支付号承担幂等标识，重复通知由现有支付状态条件保护。
+
+## 失败、超时与重试
+
+配置不完整或 SDK 生成 URL 失败映射为项目支付配置错误；通知签名、金额或状态不符按回调失败处理。创建支付 URL 不自动重试，避免重复业务意图；通知是否重发由支付宝控制，本系统必须保持回调幂等。SDK 超时未在本适配器单独覆盖。
+
+## 安全与验证
+
+私钥、公钥原文、完整通知报文和用户标识不得写入本文或普通日志。可复现静态证据：`pkg/alipay/wap.go`、`pkg/alipay/notify.go`、`internal/handler/callback/payment.go`。真实验收需在隔离商户完成下单、签名通知、错误金额和重复通知四个场景；本次 Context 重建不调用真实渠道。
+
+官方参考：<https://opendocs.alipay.com/open/203/107091>
+
+渠道版本、认证、字段、通知状态或重试语义变化时更新本文。

docs/integrations/fuiou/README.md

@@ -0,0 +1,28 @@
+# 富友接入契约
+
+## 元数据
+
+- Owner：支付适配维护人
+- 实现：`pkg/fuiou/`
+- 核验日期：2026-08-07
+- 来源：当前代码和商户接口约定；仓库未保存可公开的版本号
+
+## 当前实际使用范围
+
+系统仅使用微信预下单 `POST <ApiURL>/wxPreCreate` 与支付通知。交易类型为 `JSAPI`（公众号）或 `LETPAY`（小程序）；未发现退款、撤销或查单能力。
+
+## 配置、认证与传输
+
+运行配置包含 API 地址、机构号、商户号、终端号、RSA 私钥、公钥及通知地址。请求先生成 XML，再转换为 GBK，并对请求参数做双重 URL 编码；请求和响应使用 RSA 签名/验签。除 `reserved` 外的请求字段即使为空也参与 XML 与签名。
+
+关键请求字段包括 `mchnt_order_no`、`order_amt`（分）、`txn_begin_ts`、`notify_url`、`trade_type`、`sub_openid`、`sub_appid`。响应 `result_code=000000` 表示渠道成功，并返回富友流水号和 JSAPI 支付字段。
+
+## 幂等、失败与重试
+
+`mchnt_order_no` 是渠道业务幂等键；通知处理还需校验签名、商户订单号、金额及当前支付状态。非 `000000`、验签失败、解码失败或字段不匹配均不得推进支付状态。客户端未实现自动重试，调用方只有在可确认沿用同一商户订单号时才可重试。
+
+## 安全与验证
+
+RSA 私钥、公钥、机构和商户凭证不得进入文档或普通日志；通知日志必须脱敏。可复现静态证据：`pkg/fuiou/client.go`、`pkg/fuiou/wxprecreate.go`、`pkg/fuiou/types.go`、`internal/handler/callback/payment.go`。真实验收需使用隔离商户验证两种交易类型、签名失败、金额不符和重复通知；本次不调用真实渠道。
+
+端点、编码、签名字段、成功码或通知语义变化时更新本文。

docs/integrations/gateway/README.md

@@ -0,0 +1,30 @@
+# Gateway 接入契约
+
+## 元数据
+
+- Owner：IoT Gateway 适配维护人
+- 实现：`internal/gateway/`
+- 核验日期：2026-08-07
+- 证据：`internal/gateway/client.go`、`crypto.go`、`card_status.go`、`flow_card.go`、`device.go`
+
+## 当前实际使用范围
+
+Gateway 是运营商流量卡、实名、停复机、限速和设备信息的统一封装入口。具体路径、请求字段和响应字段以同目录详细协议与 `internal/gateway/*.go` 的实际调用交集为准；文档中出现但代码未调用的接口不视为系统能力。
+
+## 配置、认证与报文
+
+配置键为 `gateway.base_url`、`gateway.app_id`、`gateway.app_secret`、`gateway.timeout`。业务参数先包装为 `{"params": ...}`，使用 AppSecret 做 AES-128-ECB 加密；外层请求含 `appId`、`data`、`sign`、`timestamp`，签名使用 MD5。HTTP 方法统一为 POST，内容类型为 `application/json;charset=utf-8`。HTTP 200 且 Gateway `code=200` 才算成功，`data` 再按具体能力解码。
+
+## 超时、重试与幂等
+
+客户端默认超时 60 秒；生效配置可覆盖。默认最多重试 2 次，即最多 3 次尝试，退避为 100ms、200ms，更多重试时封顶 300ms。仅客户端超时、连接和 DNS 等网络级错误重试；用户 Context 取消、HTTP 非 200、响应解析失败和 Gateway 业务码失败不重试。每次尝试重新生成时间戳与签名。
+
+查询天然只读；停复机、限速等写操作的幂等和状态条件由调用它的业务 Service 承担，Gateway 客户端本身不提供幂等键。
+
+## 安全、错误与验证
+
+AppSecret、加密前业务数据、完整身份标识不得写入本文或普通日志；当前客户端存在请求结构日志，运行环境必须依赖日志脱敏策略。Gateway 错误映射为项目 `CodeGatewayError`、`CodeGatewayTimeout` 或 `CodeGatewayInvalidResp`。
+
+可复现静态证据：`internal/gateway/client.go`、`internal/gateway/crypto.go` 及同目录能力文件。真实写操作可能改变卡或设备状态，本次只允许静态核对和隔离账号只读验证，不调用生产写接口。
+
+协议、路径、认证、成功码、超时或重试分类变化时更新本文。

docs/integrations/object-storage/README.md

@@ -0,0 +1,32 @@
+# S3 兼容对象存储接入契约
+
+## 元数据
+
+- Owner：基础设施维护人
+- 实现：`pkg/storage/`
+- SDK：`github.com/aws/aws-sdk-go v1.55.5`
+- 核验日期：2026-08-07
+
+## 当前实际使用范围
+
+系统支持对象上传、下载、Head 元数据、删除、存在性判断，以及上传/下载预签名 URL；Provider 当前只接受 `s3`。未发现版本管理、生命周期或跨区域复制调用。
+
+## 配置、认证与字段
+
+配置键为 `storage.provider`、`storage.s3.endpoint`、`region`、`bucket`、`access_key_id`、`secret_access_key`、`use_ssl`、`path_style`，以及 `storage.presign.upload_expires`、`download_expires`、`storage.temp_dir`。默认上传 URL 有效期 15 分钟，下载 URL 有效期 24 小时，运行配置可覆盖。
+
+关键输入为对象 Key、Content-Type、Metadata 和可重复读取的数据流。预签名结果返回 URL、文件 Key 与过期时间；调用方必须保存 Key，不应把临时 URL 当作永久标识。
+
+## 幂等、失败与重试
+
+相同 Key 的上传按 S3 覆盖语义执行，唯一性由业务层保证；删除遵循服务端删除语义，存在性通过 Head 判断。适配器未额外实现重试策略，实际网络重试遵循 AWS SDK 默认行为；写操作重试前必须确保输入可重复读取。
+
+## 安全与验证
+
+AccessKey、SecretKey、私有对象 URL 和敏感 Metadata 不进入文档或普通日志。预签名 URL 仅在所需最短期限内分发，Bucket 权限、CORS 与生命周期由部署侧人工验收。
+
+可复现静态证据：`pkg/storage/s3.go`、`pkg/storage/service.go`、`pkg/storage/types.go`、`pkg/config/config.go`。真实验收需使用隔离 Bucket 完成上传、Head、下载、删除及过期 URL 验证；本次不访问生产 Bucket。
+
+官方参考：<https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html>
+
+SDK、端点兼容性、认证、对象语义或预签名期限变化时更新本文。

docs/integrations/sms/README.md

@@ -0,0 +1,28 @@
+# 短信网关接入契约
+
+## 元数据
+
+- Owner：通知适配维护人
+- 实现：`pkg/sms/`
+- 协议版本：渠道 SMS HTTP 1.6；仓库仅保留当前实现所需字段摘要
+- 核验日期：2026-08-07
+
+## 当前实际使用范围
+
+系统使用 `POST <gateway_url>/sms/api/sendMessageMass` 批量发送短信；未发现状态回执查询或上行短信处理。
+
+## 配置、认证与字段
+
+配置键为 `sms.gateway_url`、`sms.username`、`sms.password`、`sms.signature`、`sms.timeout`。默认配置超时为 10 秒，运行配置可覆盖。客户端把短信签名拼在正文前，提交 `userName`、`content`、`phoneList`、毫秒时间戳和 `sign`。签名算法为小写 `MD5(username + timestamp + MD5(password))`。
+
+响应关键字段为 `code`、`message`、`msgId`、`smsCount`；只有代码中定义的 `CodeSuccess` 才视为提交成功，其他状态转换为 `SMSError` 并保留渠道码。
+
+## 幂等、重试与安全
+
+客户端不自动重试，也不生成业务幂等键；调用方需以通知业务标识防重，并在网络结果不确定时先判断是否允许重发。密码、签名原文、完整手机号列表和完整正文不得记录；当前实现只输出手机号列表和最多 50 个字符的内容预览，部署侧仍需日志脱敏。
+
+## 验证
+
+可复现静态证据：`pkg/sms/client.go`、`pkg/sms/types.go`、`pkg/config/config.go`。真实验收需使用测试号码核对单条/批量、错误签名、超时和重复发送；本次 Context 重建不发送真实短信。
+
+协议版本、端点、认证、字段、成功码或重试语义变化时更新本文。

docs/integrations/wechat/README.md

@@ -0,0 +1,34 @@
+# 微信生态接入契约
+
+## 元数据
+
+- Owner：支付与微信生态维护人
+- 实现：`pkg/wechat/`
+- SDK：`github.com/ArtisanCloud/PowerWeChat/v3 v3.4.38`
+- 核验日期：2026-08-07
+
+## 当前实际使用范围
+
+系统使用公众号 OAuth、小程序 `code2session`、微信支付 JSAPI/H5 下单、查单、关单和支付通知。支付同时存在 PowerWeChat/v3 适配与仅配置 APIv2 Key 时使用的 v2 XML 适配；不得仅凭 SDK 文档推断其他微信能力。
+
+## 端点、配置与关键字段
+
+- 小程序：`GET https://api.weixin.qq.com/sns/jscode2session`，参数为 AppID、AppSecret、临时 code 和固定 `authorization_code`；响应必须含 OpenID、SessionKey，可选 UnionID；超时 10 秒。
+- 支付 v2：`POST https://api.mch.weixin.qq.com/pay/unifiedorder` 和 `/pay/orderquery`，XML + MD5 签名；关键字段为商户订单号、金额（分）、OpenID、交易类型、通知地址和客户端 IP。
+- 支付 v3/SDK：使用 AppID、商户号、APIv3 Key、证书序列号、私钥及通知地址，支持 JSAPI/H5、Query、Close 和 Notify。
+
+配置来自支付配置记录，不在本文列出具体值。v2 下单同时要求 `return_code=SUCCESS` 与 `result_code=SUCCESS`；查单以商户订单号关联本地支付。
+
+## 回调、幂等、失败与重试
+
+v2 按 API Key 验签，v3 按平台证书验签并解密通知。商户订单号是渠道幂等标识；通知还需核对金额、配置和本地状态，并以状态条件更新避免重复入账。小程序 `errcode!=0`、关键字段缺失、HTTP/解析失败均映射统一微信错误。
+
+适配器没有对创建支付做盲目自动重试；查单可由业务流程补偿，关单和回调按原商户订单号及状态保持幂等。
+
+## 安全与验证
+
+AppSecret、API Key、私钥、证书内容、SessionKey、完整 OpenID 和通知原文不得进入文档或普通日志。可复现静态证据：`pkg/wechat/miniapp.go`、`pkg/wechat/payment.go`、`pkg/wechat/payment_v2.go`、`internal/handler/callback/payment.go`。真实验收需隔离商户验证 JSAPI/H5、查关单、签名失败、金额不符与重复通知；本次不调用真实渠道。
+
+官方参考：<https://pay.weixin.qq.com/doc/v3/merchant/4012065342>
+
+SDK、API 版本、认证、通知或重试语义变化时更新本文。

docs/integrations/wecom/README.md

@@ -0,0 +1,41 @@
+# 企业微信接入契约
+
+## 元数据
+
+- Owner：企业微信审批维护人
+- 实现：`internal/infrastructure/wecom/`
+- 官方来源：企业微信开发者中心对应接口页；仓库仅保留当前调用交集
+- 核验日期：2026-08-07
+
+## 当前实际使用范围
+
+系统使用 access_token、部门与成员简表、审批模板详情、审批提交、审批详情/列表、临时素材上传，以及加密回调后的权威状态同步。未在代码调用链出现的企业微信接口不视为系统能力。
+
+## 端点与方法
+
+- `GET /cgi-bin/gettoken`
+- `GET /cgi-bin/department/list`
+- `GET /cgi-bin/user/simplelist`
+- `POST /cgi-bin/oa/gettemplatedetail`
+- `POST /cgi-bin/oa/applyevent`
+- `POST /cgi-bin/oa/getapprovaldetail`
+- `POST /cgi-bin/oa/getapprovalinfo`
+- `POST /cgi-bin/media/upload`
+
+基础地址来自 `wecom.base_url`；HTTP 超时来自 `wecom.timeout`，未配置时为 10 秒。CorpID 与应用 Secret 用于换取 access_token；审批控件 ID、类型和选项 Key 必须来自当前模板详情，不能由本系统猜测。
+
+## 回调、终态与补偿
+
+回调入口校验企业微信签名并进行 AES 解密，再按审批单号获取权威详情。回调并非唯一事实来源：审批列表/详情查询用于轮询补偿。提交 Consumer 区分 `SafeToRetry`：附件准备、取 token、构造请求或调用前的安全失败可释放实例等待重试；已无法确认是否提交成功的结果不得盲目重复创建审批。
+
+业务以本地审批实例和企业微信审批单号去重，终态只推进一次；`errcode/errmsg` 保存到集成日志并映射项目错误，不能直接暴露凭证或底层报文。
+
+## 安全与验证
+
+Secret、access_token、回调 AES Key、成员敏感字段、审批正文与附件 URL 必须脱敏。可信 IP、应用可见范围、模板、回调 URL 和素材权限属于部署侧人工配置。
+
+可复现静态证据：`internal/infrastructure/wecom/token_provider.go`、`directory_client.go`、`template_client.go`、`approval_submission_client.go`、`approval_detail_client.go`、`approval_info_client.go`、`approval_attachment_uploader.go`、`approval_submission_consumer.go`。真实验收需测试企业覆盖提交、加密回调、漏回调补偿、重复事件和未知提交结果；本次不访问真实企业。
+
+官方参考：<https://developer.work.weixin.qq.com/document/path/91902>
+
+端点、模板字段、认证、回调加密或补偿语义变化时更新本文。