Karlcarlo
c7f85ffbda
- 引入 alibabacloud/dysmsapi-20170525 依赖，集成阿里云短信服务 - 将短信验证码从6位改为4位，优化用户体验 - 添加聚水潭商品按时间范围同步功能，支持分页拉取 - 增强Cron任务异常处理，添加错误日志记录 - 修复系统附件服务中图片路径处理逻辑 - 更新阿里云SDK相关组件至最新版本 - 添加think-trace调试扩展，便于问题排查 - 优化跨域中间件，使用str_contains替代strpos
5.2 KiB
5.2 KiB
企业微信通讯录配置项使用逻辑与回调域名替代方案 Spec
Why
现网企业微信通讯录/客户联系能力依赖“接收事件服务器”回调地址（如 https://shop.douba.top/api/work/serve）来接收成员/部门/客户等变更事件。实际部署中可能遇到企业微信后台无法填写或无法通过校验（域名限制、HTTPS 证书、网络可达性、网关/WAF 等）导致无法上线。
本 Spec 的目标是：
- 梳理后端企业微信通讯录相关配置项在代码中的读取、组装与使用路径，便于定位配置错误。
- 给出当企业微信侧无法配置项目域名时的可行替代配置方式（运维/网络层方案 + 业务层降级方案）。
- （可选增强）提供独立的“企业微信回调地址”配置项，仅用于展示与复制，避免必须修改全站
site_url。
Current Behavior（现状）
1) 回调路由入口
- 企业微信回调入口固定为
/api/work/serve，路由映射到app\controller\api\v1\wechat\Wechat::work()，最终调用crmeb\services\wechat\Work::serve()。 - 后台配置表单中“服务器地址”字段为只读展示：
sys_config('site_url') . '/api/work/serve'。
2) 配置项来源与组装
企业微信配置通过两层组装后交给 EasyWeChat：
- 基础配置（用于验签/解密/加密回复）：
corp_id、token、aes_key- 映射到系统配置键：
wechat_work_corpid、wechat_work_token、wechat_work_aes_key
- 映射到系统配置键：
- 应用配置（用于调用不同能力 API）：按类型注入
secret/agent_id- 通讯录同步：
wechat_work_address_secret - 客户联系：
wechat_work_user_secret - 自建应用：
wechat_work_build_agent_id+wechat_work_build_secret
- 通讯录同步：
3) 回调验签与事件处理
Work::serve()调用 EasyWeChat Work Server 完成 URL 校验与消息解密；解密后消息交给app\listener\wechat\WorkListener分发。WorkListener处理的关键事件包含：- 通讯录事件：
change_contact（成员/部门增删改） - 客户事件：
change_external_contact - 客户群事件：
change_external_chat - 客户标签事件：
change_external_tag
- 通讯录事件：
Problems（常见问题）
- 直接在浏览器访问回调 URL 或用普通 HTTP 客户端随意请求，会触发 EasyWeChat 的解析失败，出现
Failed to decode request contents.；这不代表系统异常，只是请求不是企业微信回调协议（缺少echostr/msg_signature或正文不是企业微信 XML/加密格式）。 - 企业微信后台“接收事件服务器”校验失败，常见原因：
- URL 不可公网访问（内网/防火墙/白名单/运营商限制）
- HTTPS 证书链不完整/过期/不被信任
- 反向代理/WAF 改写了 query/body（导致
msg_signature校验失败） - 回调域名无法在企业微信侧配置（企业侧安全策略或域名限制）
What Changes（拟新增/调整）
A. 文档化与定位指引（必做）
- 输出一份“配置项—代码使用点—故障排查清单”的说明（本 Spec + checklist）。
- 明确哪些配置影响“回调校验”，哪些配置只影响“API 调用”。
B. 回调域名替代方案（不改代码即可落地）
- 允许使用“可在企业微信侧配置的域名/网关”作为回调入口，通过透明转发（反向代理/网关/隧道）转发到实际项目的
/api/work/serve。 - 允许在无法接入回调时，使用后台已有的“同步企业微信成员”能力做业务降级（非实时）。
C. 可选增强：增加独立的回调地址配置项（需要改代码）
新增系统配置键（示例）：wechat_work_callback_url
- 用途：仅用于后台表单展示/复制，默认值仍为
site_url . '/api/work/serve'。 - 不改变实际回调逻辑（仍然由路由
/api/work/serve接收）；目的是让运维能把“实际对外可用的回调域名”记录在系统里，减少误配。
Requirements
Requirement 1: 配置项可追溯
系统 SHALL 明确以下配置项的用途与作用范围：
wechat_work_corpid/wechat_work_token/wechat_work_aes_key：影响回调验签解密与企业微信身份wechat_work_address_secret：影响通讯录同步相关 API（拉部门、拉成员等）wechat_work_user_secret：影响客户联系相关 APIwechat_work_build_agent_id+wechat_work_build_secret：影响自建应用相关 API
Requirement 2: 当域名无法配置时可替代接入
在企业微信后台无法配置项目域名时，运维 SHALL 能选择以下一种方式完成回调接入：
- 方案 A：配置一个企业微信可接受的域名作为回调入口，并反向代理透明转发到本项目
/api/work/serve - 方案 B：无法接入回调时，使用后台“同步企业微信成员”接口进行人工/定时全量同步作为降级（承认非实时）
Requirement 3（可选）: 回调地址可配置展示
系统 SHOULD 提供 wechat_work_callback_url 配置项用于展示与复制，默认回退到 site_url . '/api/work/serve'。
Impact（影响面）
不改代码即可采用
- 仅影响运维部署方式与企业微信后台填写的回调 URL。
若做可选增强
- 影响后台“企业微信配置”表单展示字段。