深浅色
企业微信接入
这一篇是干什么的：把系统和你的企业微信连起来。连上之后，系统才能同步客户和员工，才能发消息、存聊天记录。
这件事分两半做：
- 在服务器上，把几把"钥匙"灌进系统。钥匙不走网页。
- 登录网页，填"明牌"参数，然后验证连接。
开始之前
| 要准备的 | 说明 |
|---|---|
| 企业微信管理员权限 | 能创建和管理自建应用 |
| 一个自建应用 | 企微后台 → 应用管理 → 创建。创建后拿到企业 ID、应用 ID、应用 Secret |
| 会话存档（可选） | 要聊天功能的话，先向企微申请开通。会拿到会话存档 Secret 和一份私钥文件 |
第一步：在服务器上灌密钥
连上服务器，进入系统目录，执行：
bash
./scripts/configure-wecom.sh
脚本会依次问你五件事。输入时屏幕上不显示内容，这是故意的（防止被旁边的人看到）：
| 它问什么 | 你填什么 | 必填吗 |
|---|---|---|
| Application Secret | 自建应用的 Secret | 必填 |
| Callback Token | 回调校验用的 Token | 没有可留空 |
| EncodingAESKey | 消息加解密用的 AESKey | 没有可留空 |
| Conversation archive Secret | 会话存档 Secret | 没开通可留空 |
| 会话存档私钥文件路径 | 私钥文件在服务器上的路径 | 没开通可留空 |
填完，脚本会把这些钥匙编码后写进 deploy/runtime.env（权限 600），然后重启后端、等自检通过。
它不会把钥匙打印到屏幕上，也不会写进代码仓库。
为什么钥匙要在服务器上灌，不在网页上填
网页是日常办公用的。浏览器里出现过的东西，可能被浏览器、插件、日志记住。钥匙走服务器文件，网页不接收、不回显，就少了一个泄露的口子。
第二步：登录网页，填企业 ID 和应用 ID
- 用管理员账号登录
https://你的域名/scrm/tools/ - 左边导航 → 设置 → 企业微信接入。首次还没配置时，登录后会自动进入这一页
- 填三样：
- 企业 ID：
ww开头那串 - 应用 ID：自建应用的 AgentID
- 会话存档 SDK 路径：服务器上的绝对路径，没开通就留空
- 企业 ID：
- 点保存
- 页面上会生成一个回调地址，点复制
第三步：到企业微信后台做四件事
- 把上一步复制的回调地址，填到自建应用的"接收消息"设置里
- 设置可信域名（你的系统域名）
- 设置可信 IP（你服务器的公网 IP）
- 设置应用可见范围（哪些员工能用）和需要开通的接口权限
第四步：点"验证连接"
回到系统页面，点验证连接。
系统只向企微读一次身份票据，确认钥匙配对了没有，不会给客户发任何消息。
页面上会显示连接状态，三种含义：
| 页面显示 | 什么意思 | 下一步 |
|---|---|---|
| 待配置 | 企业 ID、应用 ID 或应用 Secret 还缺 | 检查第一步和第二步 |
| 等待连接验证 | 参数存好了，还没验证过 | 点"验证连接" |
| 连接验证通过 | 凭证、网络白名单和基础权限都通了 | 可以开始用 |
"连接验证通过"不等于所有权限都开通了
它只说明最基础的对接通了。客户同步、群发、会话存档是三块独立的权限，建议分别用测试账号试一遍，确认都通了再给全公司用。
会话存档：聊天功能的前提
- 它是企业微信官方的收费能力，要单独申请、签协议，员工要同意。
- 开通并接好之后，"会话""客户会话"这些页面才会有内容。
- 没开通的话，这些页面是空的，系统会在顶部提示"会话存档未配置"。
出错了怎么办
| 现象 | 什么意思 | 怎么办 |
|---|---|---|
| 企微后台提示回调地址校验失败 | 企微访问不到你的回调地址 | 检查域名、HTTPS 是否正常，可信域名是否设置 |
| 验证连接失败 | 钥匙不对，或服务器连不上企微 | 重灌 Secret 再试；确认服务器能访问外网 |
| 页面提示"会话存档未配置" | 没开通，或密钥没灌 | 见上文"会话存档"一节 |
| 员工同步不到 | 应用可见范围没设置 | 到企微后台把可见范围加上 |
常见问题
Q：一套系统能接多个企业微信吗？
不能。一套系统绑定一个企业微信主体。多家公司要各自装一套。
Q：Secret 填错了怎么办？
重跑 ./scripts/configure-wecom.sh 覆盖就行，然后重新点"验证连接"。
Q：员工怎么进入系统？
员工在企业微信里通过身份授权进入，不用单独发账号。管理员用安装时生成的管理员账号登录。
Q：回调地址复制后还能变吗？
只要域名和路径前缀不变，地址就不变。如果之后改了路径前缀，要回企微后台更新。