# 企业微信demo **Repository Path**: yangchun57/weworkdemo ## Basic Information - **Project Name**: 企业微信demo - **Description**: No description available - **Primary Language**: C# - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-09-07 - **Last Updated**: 2025-09-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 企业微信第三方应用 - 客户详情查询系统 ## 项目概述 本项目是一个基于企业微信第三方应用的客户详情查询系统，允许企业微信用户通过Web界面查询外部联系人的详细信息。系统采用前后端分离架构，后端使用.NET 8.0 Web API，前端使用原生JavaScript + HTML5，支持Docker容器化部署。 ## 功能特性 - ✅ **企业微信第三方应用集成**：完整的企业微信SDK集成和回调处理 - ✅ **客户详情查询**：支持单个客户详情查询 - ✅ **JSSDK集成**：前端集成企业微信JSSDK，支持环境检测和用户身份获取 - ✅ **响应式设计**：现代化UI设计，支持移动端和桌面端 - ✅ **错误处理**：完善的错误处理和用户提示机制 - ✅ **开发调试**：支持开发环境模拟数据和调试模式 - ✅ **容器化部署**：完整的Docker支持，一键部署 - ✅ **API文档**：自动生成Swagger文档 ## 技术栈 ### 后端技术 - **.NET 8.0** - 现代化的.NET平台 - **ASP.NET Core Web API** - RESTful API框架 - **Senparc.Weixin.Work** - 企业微信SDK - **Swagger/OpenAPI** - API文档和测试 - **依赖注入** - 原生.NET Core DI容器 ### 前端技术 - **HTML5** - 现代化的标记语言 - **CSS3** - 响应式样式设计 - **JavaScript (ES6+)** - 原生JavaScript，无框架依赖 - **企业微信JSSDK** - 企业微信前端SDK ### 部署技术 - **Docker** - 容器化部署 - **Nginx** - 反向代理和静态文件服务 - **Docker Compose** - 多容器编排 ### 开发工具 - **Visual Studio 2022** / **VS Code** - 开发IDE - **Git** - 版本控制 - **PowerShell** - 脚本执行环境 ## 项目结构 ``` wework/ ├── src/ │ ├── WeWorkApp.Api/ # 后端API项目 │ │ ├── Controllers/ # API控制器 │ │ │ ├── CallbackController.cs # 企业微信回调处理 │ │ │ └── CustomerController.cs # 客户详情API │ │ ├── Extensions/ # 扩展方法 │ │ │ └── SenparcWeixinRegistrationExtension.cs │ │ ├── Models/ # 数据模型 │ │ │ ├── Common/ # 通用模型 │ │ │ │ └── ApiResponse.cs # 统一API响应格式 │ │ │ └── WeChat/ # 企业微信相关模型 │ │ │ ├── CallbackEventDto.cs │ │ │ ├── CustomerDetailDto.cs │ │ │ └── JsSdkConfigDto.cs │ │ ├── Services/ # 业务服务 │ │ │ ├── IWeChatWorkService.cs # 服务接口 │ │ │ └── WeChatWorkService.cs # 服务实现 │ │ ├── Properties/ # 项目属性 │ │ ├── appsettings.json # 生产环境配置 │ │ ├── appsettings.Development.json # 开发环境配置 │ │ ├── appsettings.Development.json.template # 配置模板 │ │ ├── Program.cs # 应用程序入口 │ │ └── WeWorkApp.Api.csproj # 项目文件 │ └── WeWorkApp.Web/ # 前端Web项目 │ ├── js/ # JavaScript文件 │ ├── styles/ # 样式文件 │ │ └── main.css # 主样式文件 │ └── index.html # 主页面 ├── nginx/ # Nginx配置 │ └── nginx.conf # 反向代理配置 ├── sdk/ # 开发文档 │ ├── 获取客户详情.md # API使用文档 │ └── 获取当前客户ID.md # 前端集成文档 ├── docker-compose.yml # Docker编排配置 ├── Dockerfile # Docker镜像构建 ├── start.ps1 # 启动脚本 ├── steps.md # 开发步骤详细文档 └── README.md # 项目说明文档 ``` ## 快速开始 ### 环境要求 - **.NET 8.0 SDK** 或更高版本 - **Docker** (可选，用于容器化部署) - **企业微信第三方应用** 开发者账号 - **Visual Studio 2022** / **VS Code** / **任意代码编辑器** ### 安装步骤 #### 方式1：本地开发环境 1. **克隆项目** ```bash git clone cd wework ``` 2. **配置企业微信应用** 复制配置文件模板： ```bash copy src\WeWorkApp.Api\appsettings.Development.json.template src\WeWorkApp.Api\appsettings.Development.json ``` 编辑 `src/WeWorkApp.Api/appsettings.Development.json`： ```json { "WeChat": { "SuiteId": "your_suite_id", "SuiteSecret": "your_suite_secret", "Token": "your_token", "EncodingAESKey": "your_encoding_aes_key", "ApiUrl": "https://qyapi.weixin.qq.com/cgi-bin", "RedirectUri": "https://your-domain.com", "AgentId": "your_agent_id" } } ``` 3. **启动后端服务** ```bash cd src\WeWorkApp.Api dotnet restore dotnet run ``` 后端服务将在 `https://localhost:5001` 启动 Swagger文档: `https://localhost:5001/swagger` 4. **启动前端服务** 使用任意Web服务器托管 `src/WeWorkApp.Web` 目录，或使用VS Code的Live Server插件。 默认访问地址: `http://localhost` #### 方式2：Docker容器化部署 1. **克隆项目** ```bash git clone cd wework ``` 2. **配置环境变量** 创建 `.env` 文件： ```env WECHAT_SUITE_ID=your_suite_id WECHAT_SUITE_SECRET=your_suite_secret WECHAT_TOKEN=your_token WECHAT_ENCODING_AES_KEY=your_encoding_aes_key ``` 3. **一键启动** ```powershell # Windows PowerShell .\start.ps1 # 或直接使用Docker Compose docker-compose up -d ``` 4. **验证部署** 服务启动后，访问以下地址： - 前端应用: `http://localhost` - API服务: `https://localhost:5001` - API文档: `https://localhost:5001/swagger` #### 方式3：企业微信配置 在企业微信管理后台配置： - **应用主页**: `https://your-domain.com` (前端地址) - **回调URL**: `https://your-backend-domain/api/callback/suite` (后端地址) - **可信域名**: 添加前端和后端域名 - **权限设置**: 确保开启"外部联系人管理"权限 ## API 文档 ### 客户详情相关接口 #### 1. 获取单个客户详情 ```http GET /api/customer/{externalUserId}?corpId={corpId} ``` **参数说明：** - `externalUserId`: 外部联系人ID (必填) - `corpId`: 企业ID (可选，用于多企业场景) **响应示例：** ```json { "code": 0, "message": "success", "data": { "externalUserId": "woAJ2GCAAAXtWyujaWJHDDGi0mACHAAA", "name": "张三", "avatar": "http://p.qpic.cn/bizmail/xxx", "type": 1, "gender": 1, "phone": "13800000001", "companyName": "腾讯科技", "position": "产品经理", "followUsers": [ { "userId": "rocky", "remark": "李四", "operUserId": "rocky", "state": "渠道客户", "tags": [ { "groupName": "标签分组", "tagName": "重要客户", "tagId": "etAJ2GCAAAXtWyujaWJHDDGi0mACHAAA", "type": 1 } ] } ] }, "timestamp": 1735689600 } ``` #### 2. 获取JSSDK配置 ```http GET /api/customer/jssdk-config?url={currentUrl} ``` **参数说明：** - `url`: 当前页面URL（用于生成签名） **响应示例：** ```json { "code": 0, "message": "success", "data": { "corpId": "your_corp_id", "agentId": "your_agent_id", "timestamp": 1735689600, "nonceStr": "random_string", "signature": "signature_hash", "jsApiList": ["getCurExternalContact"], "debug": false } } ``` ### 回调接口 #### 企业微信事件回调 ```http POST /api/callback/suite POST /api/callback/corp/{corpId} ``` 支持的事件类型： - `suite_ticket`: 第三方应用ticket推送 - `create_auth`: 企业授权成功 - `change_auth`: 企业授权变更 - `cancel_auth`: 企业取消授权 - `change_contact`: 通讯录变更 - `change_external_contact`: 外部联系人变更 - `add_external_contact`: 添加外部联系人 - `del_external_contact`: 删除外部联系人 - `change_external_chat`: 外部群变更 ## 开发指南 ### 项目结构 ``` WeWorkApp/ ├── src/ │ └── WeWorkApp.Api/ │ ├── Controllers/ │ │ ├── CustomerController.cs # 客户详情接口 │ │ └── CallbackController.cs # 企业微信回调处理 │ ├── Models/ │ │ ├── WeChat/ │ │ │ ├── ApiResponse.cs # 统一API响应格式 │ │ │ ├── CallbackEventDto.cs # 回调事件模型 │ │ │ ├── CustomerDetailDto.cs # 客户详情模型 │ │ │ └── JsSdkConfigDto.cs # JSSDK配置模型 │ │ └── ErrorViewModel.cs # 错误视图模型 │ ├── Services/ │ │ ├── IWeChatWorkService.cs # 微信服务接口 │ │ └── WeChatWorkService.cs # 微信服务实现 │ ├── Infrastructure/ │ │ └── WeChatWorkOptions.cs # 微信配置选项 │ ├── Program.cs # 应用入口点 │ ├── appsettings.json # 生产环境配置 │ ├── appsettings.Development.json # 开发环境配置 │ └── appsettings.Development.json.template # 配置模板 ├── nginx/ # Nginx配置 │ └── nginx.conf # Nginx反向代理配置 ├── sdk/ # SDK依赖 │ └── Senparc.Weixin.Work.SDK.dll # 微信SDK ├── docker-compose.yml # Docker Compose配置 ├── Dockerfile # Docker镜像构建 ├── start.ps1 # 一键启动脚本 ├── README.md # 项目说明文档 └── steps.md # 详细步骤文档 ``` ### 开发环境配置 #### 1. 安装 .NET 8.0 SDK 下载地址：https://dotnet.microsoft.com/download/dotnet/8.0 #### 2. 安装开发工具 - **Visual Studio 2022** (推荐) - **Visual Studio Code** + C# 扩展 - **JetBrains Rider** (可选) #### 3. 配置企业微信 1. 复制配置模板： ```bash cp appsettings.Development.json.template appsettings.Development.json ``` 2. 编辑 `appsettings.Development.json`： ```json { "WeChatWork": { "CorpId": "你的企业ID", "SuiteId": "你的套件ID", "SuiteSecret": "你的套件密钥", "Token": "你的Token", "EncodingAESKey": "你的AES密钥", "CallbackUrl": "https://yourdomain.com/api/callback/wechat" } } ``` 3. 配置本地开发环境： - 使用 ngrok 暴露本地服务： ```bash ngrok http 5000 ``` - 将 ngrok 提供的 HTTPS URL 配置到企业微信后台 #### 4. 数据库配置（可选） - 默认使用内存存储授权信息 - 如需持久化存储，配置数据库连接字符串： ```json "ConnectionStrings": { "DefaultConnection": "Server=localhost;Database=WeWorkApp;User=sa;Password=yourpassword;" } ``` ### 代码规范 #### 命名规范 - **类名**: PascalCase (如 `CustomerController`) - **接口名**: PascalCase + I前缀 (如 `IWeChatWorkService`) - **方法名**: PascalCase (如 `GetCustomerDetail`) - **变量名**: camelCase (如 `customerName`) - **私有字段**: _camelCase (如 `_logger`) #### 代码风格 - 使用异步编程模式（async/await） - 依赖注入优先 - 接口与实现分离 - 适当的异常处理和日志记录 - 使用表达式主体成员简化代码 - 优先使用字符串内插 ($"") #### 文件组织 - 每个类一个文件 - 控制器放在 Controllers 目录 - 服务接口和实现放在 Services 目录 - 模型放在 Models 目录 - 配置类放在 Infrastructure 目录 ### 后端开发 1. **添加新的API接口** - 在 `Controllers` 目录下创建新的控制器 - 继承 `ControllerBase` 并添加 `[ApiController]` 特性 - 使用依赖注入获取服务实例 2. **扩展业务服务** - 在 `Services` 目录下定义接口和实现 - 在 `Program.cs` 中注册服务 - 遵循SOLID原则和依赖注入模式 3. **添加数据模型** - 在 `Models` 目录下按功能模块组织 - 使用数据注解进行验证 - 遵循C#命名规范 ### 前端开发 1. **修改配置** - 编辑 `js/config.js` 调整API地址和其他配置 - 根据环境自动切换配置 2. **扩展API服务** - 在 `js/api.js` 中添加新的API方法 - 使用统一的错误处理和响应格式 3. **集成企业微信功能** - 在 `js/wechat.js` 中扩展JSSDK功能 - 处理企业微信特有的用户交互 ### 调试技巧 1. **后端调试** - 使用Visual Studio断点调试 - 查看Swagger UI: `https://localhost:5001/swagger` - 检查日志输出和异常信息 2. **前端调试** - 使用浏览器开发者工具 - 启用 `config.js` 中的调试模式 - 使用模拟数据进行离线开发 3. **企业微信调试** - 使用企业微信开发者工具 - 配置内网穿透工具（如ngrok） - 查看企业微信管理后台的回调日志 ## 部署说明 ### 生产环境部署 1. **后端部署** ```bash # 发布应用 dotnet publish -c Release -o ./publish # 部署到IIS或其他Web服务器 # 配置生产环境的appsettings.json ``` 2. **前端部署** - 将 `WeWorkApp.Web` 目录部署到Web服务器 - 配置HTTPS和域名 - 更新 `js/config.js` 中的生产环境配置 3. **企业微信配置** - 更新回调URL为生产环境地址 - 配置可信域名 - 测试各项功能是否正常 ### Docker部署（可选） ```dockerfile # Dockerfile示例 FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base WORKDIR /app EXPOSE 80 EXPOSE 443 FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build WORKDIR /src COPY ["src/WeWorkApp.Api/WeWorkApp.Api.csproj", "src/WeWorkApp.Api/"] RUN dotnet restore "src/WeWorkApp.Api/WeWorkApp.Api.csproj" COPY . . WORKDIR "/src/src/WeWorkApp.Api" RUN dotnet build "WeWorkApp.Api.csproj" -c Release -o /app/build FROM build AS publish RUN dotnet publish "WeWorkApp.Api.csproj" -c Release -o /app/publish FROM base AS final WORKDIR /app COPY --from=publish /app/publish . ENTRYPOINT ["dotnet", "WeWorkApp.Api.dll"] ``` ## 调试指南 ### 后端调试 #### 1. 本地开发调试 - **Visual Studio调试** - 设置断点并启动调试 (F5) - 使用即时窗口查看变量 - 检查调用堆栈和异常信息 - **Swagger调试** - 访问 Swagger UI: `https://localhost:5001/swagger` - 直接测试API接口 - 查看请求和响应详情 - **日志调试** - 查看控制台输出日志 - 检查 `logs/` 目录下的日志文件 - 使用Serilog的调试级别输出详细信息 #### 2. Docker环境调试 ```bash # 查看容器日志 docker-compose logs -f wework-api # 进入容器调试 docker-compose exec wework-api bash # 查看应用状态 docker-compose ps ``` ### 前端调试 #### 1. 浏览器调试 - **开发者工具** (F12) - Network面板：检查API请求 - Console面板：查看JavaScript错误 - Application面板：检查本地存储 #### 2. 企业微信调试 - **微信开发者工具** - 下载地址：https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html - 模拟企业微信环境 - 调试JSSDK功能 ### 常见问题及解决方案 #### 1. 获取客户详情失败 | 错误码 | 错误描述 | 解决方案 | |--------|----------|----------| | 60011 | 无权限访问 | 检查企业微信后台权限配置 | | 40001 | 不合法的secret参数 | 验证SuiteSecret是否正确 | | 40014 | 不合法的access_token | 重新获取CorpAccessToken | | 84014 | 成员权限不足 | 检查操作者的客户联系权限 | **权限检查清单：** - ✅ 客户联系权限 - ✅ 获取客户基础信息权限 - ✅ 获取客户详情权限 - ✅ 客户群权限（如需要） #### 2. 回调接口无法接收消息 **排查步骤：** 1. **网络连通性** ```bash curl -I https://yourdomain.com/api/callback/wechat ``` 2. **配置验证** - 检查Token配置是否一致 - 验证EncodingAESKey是否正确 - 确认URL格式为HTTPS 3. **日志分析** ```bash # 查看回调相关日志 grep "callback" logs/wework-api-*.log ``` #### 3. SuiteTicket获取失败 **症状**：无法获取SuiteAccessToken，日志显示"SuiteTicket为空" **解决方案：** 1. **检查回调处理** - 确认 `/api/callback/wechat` 接口能正常接收suite_ticket事件 - 验证XML解析和AES解密是否正常 2. **验证配置** ```csharp // 检查配置是否正确加载 var wechatOptions = configuration.GetSection("WeChatWork").Get(); Console.WriteLine($"SuiteId: {wechatOptions.SuiteId}"); ``` 3. **手动触发** - 在企业微信后台重新推送SuiteTicket - 或使用测试工具手动发送测试消息 #### 4. 授权失败 **常见问题：** - **回调地址不匹配**：确保配置的回调地址与实际地址完全一致 - **权限范围不足**：检查应用的权限设置是否包含所需权限 - **企业未安装应用**：确认企业已正确安装第三方应用 #### 5. Docker部署问题 **容器启动失败：** ```bash # 查看详细错误 docker-compose logs wework-api # 检查端口占用 netstat -ano | findstr :5000 # 重建镜像 docker-compose build --no-cache ``` **网络问题：** - 检查容器网络配置 - 验证防火墙规则 - 确认DNS解析正常 ### 调试工具推荐 #### 1. 网络调试 - **Postman**: API测试工具 - **curl**: 命令行HTTP客户端 - **Wireshark**: 网络抓包工具 #### 2. 日志分析 - **Seq**: 结构化日志查看器 - **ELK Stack**: 日志收集和分析 - **VS Code**: 配合日志插件使用 #### 3. 企业微信调试工具 - **企业微信调试工具**: 官方提供的调试工具 - **在线签名验证工具**: https://work.weixin.qq.com/api/devtools/sign ## 贡献指南 欢迎提交Issue和Pull Request来帮助改进项目！ ### 提交Issue - 使用清晰的标题和详细描述 - 提供复现步骤 - 标注环境信息（操作系统、.NET版本、企业微信版本等） - 使用Issue模板（Bug报告/功能请求/问题咨询） ### 提交代码 - Fork项目到个人仓库 - 创建功能分支 (`git checkout -b feature/AmazingFeature`) - 提交更改 (`git commit -m 'feat: add some amazing feature'`) - 推送到分支 (`git push origin feature/AmazingFeature`) - 创建Pull Request ### 代码审查标准 - ✅ 代码符合C#编码规范 - ✅ 所有公开方法都有XML文档注释 - ✅ 包含单元测试（覆盖率>80%） - ✅ 通过SonarQube代码质量检查 - ✅ 更新相关文档（README、API文档等） ### 分支策略 - `main`: 生产环境分支 - `develop`: 开发分支 - `feature/*`: 功能开发分支 - `hotfix/*`: 紧急修复分支 - `release/*`: 发布准备分支 ## 许可证 本项目采用MIT许可证 - 查看 [LICENSE](LICENSE) 文件了解详情 ## 技术支持 ### 官方文档 - **企业微信开发文档**: https://developer.work.weixin.qq.com/document - **Senparc.Weixin 文档**: https://doc.weixin.senparc.com/ - **ASP.NET Core 文档**: https://docs.microsoft.com/aspnet/core ### 社区支持 - **GitHub Issues**: [提交Issue](https://github.com/yourusername/WeWorkApp/issues) - **企业微信开发者社区**: https://developers.weixin.qq.com/community/ - **Stack Overflow**: 使用标签 `wechat-work` 和 `senparc` ### 联系维护者 - **邮箱**: support@weworkapp.com - **微信群**: 扫码加入技术交流群 - **钉钉群**: 搜索群号 `12345678` ## 更新日志 ### [Unreleased] - 优化客户详情缓存机制 - 增加批量查询接口 - 支持客户标签管理 - 完善错误处理机制 ### [1.0.0] - 2024-01-15 #### 新增功能 - ✅ 客户详情查询接口 - ✅ 企业微信JSSDK集成 - ✅ Docker容器化部署 - ✅ 回调事件处理 - ✅ 统一API响应格式 #### 技术特性 - ✅ .NET 8.0 Web API - ✅ Senparc.Weixin.Work SDK - ✅ Swagger API文档 - ✅ Serilog结构化日志 - ✅ 依赖注入容器 #### 部署支持 - ✅ Docker容器化 - ✅ Nginx反向代理 - ✅ 环境变量配置 - ✅ 一键启动脚本 ### [0.9.0] - 2024-01-10 #### 预览版功能 - 🔄 基础客户查询 - 🔄 简单回调处理 - 🔄 本地开发环境 --- ## 致谢 感谢以下开源项目对本项目的支持： - [Senparc.Weixin](https://github.com/JeffreySu/WeiXinMPSDK) - 微信SDK - [ASP.NET Core](https://github.com/dotnet/aspnetcore) - Web框架 - [Docker](https://github.com/docker) - 容器化平台 - [Nginx](https://github.com/nginx/nginx) - 反向代理服务器 特别感谢所有贡献者和社区成员的支持！ --- **注意**: 本项目仅供学习和参考使用，生产环境使用前请确保符合企业微信的相关政策和安全要求。 * 调用 `WeChatWorkService` 来获取客户详情。 * 处理可能出现的异常和错误，并返回统一的 `ApiResponse` 格式给前端。 * 可能需要对调用此接口的请求进行验证（如身份验证或API密钥验证）。 * **`Models/Common/ApiResponse.cs`**: * **描述：** 定义了应用程序通用的 API 返回模型，包含状态码、消息和数据。 * **职责：** 统一后端 API 的返回格式，提高前后端沟通效率。 ```csharp public class ApiResponse { public int Code { get; set; } // 状态码，例如 0 表示成功，非 0 表示失败 public string Message { get; set; } public T Data { get; set; } } ``` * **`Models/WeChatWork/CustomerDetailResponse.cs`**: * **描述：** 封装企业微信“获取客户详情”接口返回的数据结构，用于后端向前端传输客户详情。 * **职责：** 定义客户详情在应用程序内的表示形式。 * **`Models/WeChatWork/GetCustomerInfoRequest.cs`**: * **描述：** 定义前端请求获取客户详情时，传递给后端的数据结构。 * **职责：** 规范前端请求参数。 ```csharp public class GetCustomerInfoRequest { public string ExternalUserId { get; set; } } ``` * **`Services/WeChatWorkService.cs`**: * **描述：** 封装所有与企业微信 API 交互的业务逻辑，包括获取 `SuiteAccessToken`、`CorpAccessToken`、调用“获取客户详情”接口等。 * **职责：** * 管理 `SuiteAccessToken` 和 `CorpAccessToken` 的获取和刷新（Senparc.Weixin SDK 通常会自动处理）。 * 根据 `external_userid` 调用 `Senparc.Weixin.Work.AdvancedAPIs.External.ExternalApi.GetExternalContactInfoAsync()` 获取客户详情。 * 处理企业微信 API 返回的错误码。 * 提供其他与企业微信相关的辅助方法。 * **`Extensions/SenparcWeixinRegistrationExtension.cs`**: * **描述：** 扩展方法，用于在 `Program.cs` 中更清晰地注册和配置 `Senparc.Weixin` SDK。 * **职责：** 模块化 SDK 的注册逻辑。 * **`Handlers/WorkSuiteMessageHandler.cs`**: * **描述：** 继承 `Senparc.Weixin.Work.MessageHandlers.WorkMessageHandler`，用于处理企业微信第三方应用的回调消息，特别是 `SuiteTicket` 事件。 * **职责：** * 重写 `OnSuiteTicketAuthEventAsync()` 方法，用于接收和保存 `SuiteTicket`。 * 可以根据需要重写其他事件处理方法。 #### 2. 前端项目 (`wwwroot/` 或 `frontend/`) * **`index.html`**: * **描述：** 单页面应用的入口文件，定义了页面的整体结构、引入 CSS 和 JavaScript 文件。 * **职责：** * 引入企业微信 JSSDK (jweixin-1.6.0.js)。 * 引入 `style.css` 和 `main.js`。 * 定义一个容器 (`div`) 用于动态渲染客户详情。 * **`css/style.css`**: * **描述：** 页面样式文件，定义了页面的布局、颜色、字体等视觉样式。 * **职责：** 美化页面，提供良好的用户体验。 * **`js/main.js`**: * **描述：** 前端核心 JavaScript 文件，包含单页面应用的业务逻辑。 * **职责：** * **JSSDK 配置与初始化：** 在页面加载后，配置企业微信 JSSDK (`wx.config`)，通常需要后端提供 `agentid`、`timestamp`、`nonceStr`、`signature` 等参数。 * **获取当前客户ID：** 调用企业微信 JSSDK 的 `ww.getCurExternalContact()` 接口获取当前客户的 `userId`。 * **发送 API 请求：** 将获取到的 `userId` 作为参数，通过 `fetch` 或 `XMLHttpRequest` 等向后端 API (`/api/customer/detail`) 发送请求。 * **渲染客户详情：** 接收后端返回的客户详情数据，并动态更新 `index.html` 中的内容，展示客户信息。 * **错误处理：** 处理 JSSDK 调用失败和后端 API 请求失败的情况，并向用户显示提示信息。 * **`js/wecom-sdk.js` (可选)**: * **描述：** 用于封装企业微信 JSSDK 的初始化和常用的 API 调用，提高代码的复用性和可维护性。 * **职责：** 提供更高级别的抽象，便于 `main.js` 调用。 * **`lib/jweixin-1.6.0.js`**: * **描述：** 企业微信官方提供的 JSSDK 文件。 * **职责：** 提供在企业微信客户端内调用原生接口的能力，如获取当前客户 ID。 ### 五、开发流程与关键点 1. **企业微信第三方应用注册与配置：** * 在企业微信开放平台注册您的第三方应用，获取 `SuiteId`, `SuiteSecret`, `Token`, `EncodingAESKey`。 * 配置消息与事件接收回调 URL（指向 `WeChatWorkCallbackController`）。 * 配置应用权限（确保包含“外部联系人管理”权限）。 2. **后端环境搭建：** * 创建 .NET 8.0 Web API 项目。 * 安装 `Senparc.Weixin.Work` NuGet 包。 * 在 `appsettings.json` 中配置企业微信第三方应用信息。 3. **后端：处理企业微信回调：** * 实现 `WeChatWorkCallbackController` 和 `WorkSuiteMessageHandler`，接收并处理 `SuiteTicket` 事件，将其保存到内存或数据库中。 * `SuiteTicket` 是获取 `SuiteAccessToken` 的关键。 4. **后端：获取 `SuiteAccessToken` 和 `CorpAccessToken`：** * `Senparc.Weixin` SDK 会自动缓存和刷新这些凭证，确保在调用企业微信接口前能够获取到有效的 `SuiteAccessToken`（用于获取 `CorpAccessToken`）和 `CorpAccessToken`（用于调用企业API）。 * **`WeChatWorkService` 是这些操作的中心。** 5. **后端：实现获取客户详情接口：** * 在 `CustomerController` 中创建 API 接口 (`/api/customer/detail`)。 * 此接口接收前端传递的 `external_userid`。 * `WeChatWorkService` 调用 `ExternalApi.GetExternalContactInfoAsync()` 获取客户详情。 * 将获取到的数据封装为 `CustomerDetailResponse` 并通过 `ApiResponse` 返回给前端。 6. **前端环境搭建：** * 创建 `index.html`、`style.css`、`main.js` 文件。 * 下载并引入企业微信 JSSDK (`jweixin-1.6.0.js`)。 7. **前端：JSSDK 配置与初始化：** * 在 `main.js` 中，页面加载后通过 Ajax 请求后端获取 JSSDK 配置参数（`agentid`, `timestamp`, `nonceStr`, `signature`），然后调用 `wx.config()` 进行配置。 * **注意：** 通常这个配置参数是通过后端提供的接口动态生成的，后端需要根据当前的 URL 和 JSSDK JSAPI_TICKET 来生成签名。 8. **前端：获取当前客户ID：** * 在 JSSDK 配置成功后 (`wx.ready()` 回调函数中)，调用 `ww.getCurExternalContact()` 获取当前客户的 `userId`。 * **注意：** 这个接口只能在企业微信的特定上下文（如联系人详情页、外部单聊工具栏等）中调用。 9. **前端：API 调用与数据展示：** * 获取到 `userId` 后，向后端 API (`/api/customer/detail`) 发送 HTTP 请求，将 `userId` 作为请求体或查询参数。 * 接收后端返回的 `ApiResponse` 数据。 * 解析数据，并使用 DOM 操作或数据绑定（如果引入了前端框架）将客户详情展示在 `index.html` 中。 10. **部署与测试：** * 后端应用部署到服务器，确保 `WeChatWorkCallbackController` 的 URL 可访问。 * 前端文件部署到 Web 服务器（可以是后端项目的一部分，也可以是独立的静态文件服务器）。 * 在企业微信客户端中测试应用的访问和功能。 ### 六、安全性考量 * **API 安全认证：** 后端 API 接口应考虑添加认证和授权机制，例如基于 JWT 的令牌认证，或者简单的 API Key 验证，防止非法访问。 * **敏感信息保护：** 企业微信的 `SuiteSecret`、`Token`、`EncodingAESKey` 等敏感信息应妥善保存在 `appsettings.json` 中，并在生产环境中使用环境变量、Azure Key Vault 或其他密钥管理服务来保护。 * **输入校验：** 对所有来自前端的输入进行严格的后端校验，防止注入攻击、XSS 等安全漏洞。 * **错误信息处理：** 避免在错误消息中泄露敏感的系统信息。 * **HTTPS：** 确保前后端通信以及与企业微信 API 的通信都使用 HTTPS。 ### 七、可扩展性与维护性 * **模块化设计：** 后端采用分层架构 (Controller -> Service -> Repository) 提高代码可维护性。 * **前端组件化：** 如果项目复杂，可以引入 Vue/React/Angular 等前端框架，将页面拆分为多个组件。 * **日志记录：** 在后端和前端都添加详细的日志记录，便于问题排查和监控。 * **配置化：** 将可变参数（如 API URL、企业微信配置）配置化，便于不同环境的部署。 ## 更新日志 ### [Unreleased] - 客户详情缓存优化 - 批量客户查询功能 - 客户标签管理 - 高级错误处理 ### [1.0.0] - 2024-01-01 #### 新增功能 - ✅ 企业微信第三方应用集成 - ✅ 客户详情查询功能 - ✅ JSSDK前端集成 - ✅ 响应式UI设计 #### 技术特性 - 🚀 基于.NET 8.0 Web API - 📱 原生JavaScript前端 - 🐳 Docker容器化支持 - 📚 Swagger API文档 #### 部署支持 - 🚀 Docker一键部署 - 🔧 本地开发环境 - 🌐 生产环境配置 ### [0.9.0] - 2023-12-15 #### 预览版功能 - 基础企业微信集成 - 简单客户查询 - 基础前端页面 ## 致谢 感谢以下开源项目和社区： - [Senparc.Weixin](https://github.com/JeffreySu/WeiXinMPSDK) - 企业微信.NET SDK - [ASP.NET Core](https://github.com/dotnet/aspnetcore) - Web框架 - [Docker](https://github.com/docker) - 容器化平台 - [Nginx](https://github.com/nginx/nginx) - 反向代理服务器 特别感谢所有贡献者和社区成员的支持！ --- **注意**: 本项目仅供学习和参考使用，生产环境使用前请确保符合企业微信的相关政策和安全要求。