Files
douba_shop/.trae/specs/wecom-addressbook-config/spec.md
Karlcarlo c7f85ffbda feat: 添加阿里云短信服务支持并优化验证码逻辑
- 引入 alibabacloud/dysmsapi-20170525 依赖,集成阿里云短信服务
- 将短信验证码从6位改为4位,优化用户体验
- 添加聚水潭商品按时间范围同步功能,支持分页拉取
- 增强Cron任务异常处理,添加错误日志记录
- 修复系统附件服务中图片路径处理逻辑
- 更新阿里云SDK相关组件至最新版本
- 添加think-trace调试扩展,便于问题排查
- 优化跨域中间件,使用str_contains替代strpos
2026-04-30 15:19:40 +08:00

77 lines
5.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 企业微信通讯录配置项使用逻辑与回调域名替代方案 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`:影响客户联系相关 API
- `wechat_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。
### 若做可选增强
- 影响后台“企业微信配置”表单展示字段。