JoyD/Claw/.trae/rules/项目规则.md

# 企业微信智控未来系统项目规则

## 1. 项目背景与目标

- **项目背景**：用户拥有一个未经认证的企业微信，包含应用"智控未来"，以及两台服务器（服务器A：公网服务器47.109.191.115 - pactgo.cn，配置SSL证书，外网可访问；服务器B：内网服务器，安装LMStudio，只能访问外网，外网无法直接访问）

- **项目目标**：使用Rust和官方原生微信小程序技术栈实现：用户通过企业微信应用"智控未来"和微信小程序进行聊天，下发任务。任务经服务器A（网关）通过WebSocket反向连接转发到服务器B（SmartClaw），B上的LMStudio进行AI处理后返回结果给用户。

- **核心架构**：WebSocket反向连接（B主动连接A），Embedded-Redis（仅A启动），HeedDB嵌入式数据库，原生小程序（WXML+WXSS+JS）。

## 2. 系统架构

### 2.1 整体架构

```mermaid
sequenceDiagram
    participant User as 用户
    participant WeChat as 企业微信/小程序
    participant Gateway as 网关服务（服务器A）
    participant SmartClaw as SmartClaw服务（服务器B）
    participant LMStudio as LMStudio

    User->>WeChat: 发送消息/任务
    WeChat->>Gateway: HTTPS回调请求
    Gateway->>SmartClaw: WebSocket转发任务
    SmartClaw->>SmartClaw: 处理任务（智能控制核心逻辑）
    SmartClaw->>LMStudio: HTTP调用LMStudio API
    LMStudio-->>SmartClaw: SSE流式返回结果
    SmartClaw-->>Gateway: WebSocket回传结果
    Gateway-->>WeChat: HTTPS回调响应
    WeChat-->>User: 显示结果
```

### 2.2 组件说明

| 组件 | 职责 | 技术栈 |
|------|------|--------|
| 企业微信应用 | 用户交互界面，接收用户消息和任务 | 企业微信JS-SDK |
| 微信小程序 | 用户交互界面，接收用户消息和任务 | WXML + WXSS + JavaScript（官方原生） |
| 网关服务（服务器A） | 接收HTTPS请求，WebSocket反向连接，Embedded-Redis多用户管理 | Rust + Actix Web + Embedded-Redis |
| SmartClaw服务（服务器B） | WebSocket客户端，处理任务，调用LMStudio，HeedDB存储 | Rust + Actix Web + HeedDB |
| 智能控制核心逻辑 | 核心业务逻辑，处理用户任务，调用LMStudio | Rust |
| LMStudio | 提供AI能力，SSE流式响应 | 第三方工具 |

## 3. 技术选型

### 3.1 后端技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| Rust | 1.70+ | 后端开发语言 |
| Actix Web | 4.0+ | Web框架，处理HTTP/WebSocket请求 |
| Tokio | 1.0+ | 异步运行时 |
| Serde | 1.0+ | 序列化/反序列化 |
| Reqwest | 0.11+ | HTTP客户端 |
| Embedded-Redis | 最新版 | 嵌入式Redis（仅网关服务启动） |
| HeedDB | 最新版 | 嵌入式K/V数据库（Sled底层） |

### 3.2 前端技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| WXML + WXSS + JavaScript | 最新版 | 微信小程序官方原生技术栈 |
| 企业微信JS-SDK | 最新版 | 企业微信网页开发 |
| 微信开发者工具 | 最新版 | 官方IDE，完整API支持 |
| wx.request() | 原生API | HTTP客户端 |
| wx.connectSocket() | 原生API | WebSocket通信 |

## 4. 网络通信方案

### 4.1 企业微信/小程序与网关服务通信

- **企业微信**：使用企业微信回调机制，网关服务提供HTTPS接口接收企业微信的消息推送，回调地址：`https://pactgo.cn/wecom`
- **微信小程序**：使用HTTPS接口与网关服务通信，实现消息发送和任务下发，接口地址：`https://pactgo.cn/api/v1/`

### 4.2 网关服务与SmartClaw服务通信

由于SmartClaw服务在内网中，外网不能访问它，采用**WebSocket反向连接方案**：

1. **SmartClaw服务主动连接**：服务器B启动时，主动WebSocket连接到服务器A（wss://pactgo.cn/ws/control）
2. **单一连接**：服务器B与服务器A之间只建立一个WebSocket连接，不需要列表管理
3. **长连接保持**：维持持久WebSocket连接，支持心跳检测和断线重连
4. **双向通信**：服务器A通过WebSocket发送任务，服务器B处理完成后回传结果
5. **零配置**：使用Embedded-Redis（仅网关服务启动），无需独立Redis服务

### 4.2.1 WebSocket连接管理

- **服务器B与服务器A**：只建立一个WebSocket连接，无需列表管理
- **其他设备与服务器A**：通过WebSocket连接到服务器A的 `/ws/task` 路径，需要使用连接列表进行管理
- **连接管理**：使用 `ConnectionManager` 结构体管理设备与服务器A的WebSocket连接，支持多用户多设备场景

### 4.3 SmartClaw服务与LMStudio通信

- 使用LMStudio提供的HTTP API接口进行通信
- 支持SSE流式响应，实时返回AI处理结果
- 服务器B上的LMStudio监听地址：http://127.0.0.1:1234

## 5. 安全考虑

### 5.1 网络安全

- 所有通信使用HTTPS加密（企业微信强制要求）
- 服务器A配置防火墙，只开放443端口（HTTPS）
- 服务器B只允许来自服务器A的WebSocket连接
- 使用有效SSL证书（Let's Encrypt）

### 5.2 认证与授权

- 企业微信应用使用CorpID和Secret进行认证，回调地址：`https://pactgo.cn/wecom`
- 微信小程序使用AppID和AppSecret进行认证，接口地址：`https://pactgo.cn/api/v1/`
- 服务器间WebSocket通信使用预共享密钥认证
- 多用户多设备状态管理使用Embedded-Redis

### 5.3 数据安全

- 敏感数据加密存储（HeedDB嵌入式数据库支持事务）
- 定期备份数据
- 实现访问控制，确保只有授权用户能访问相关功能
- 多用户多设备状态管理使用Embedded-Redis

## 6. 项目结构

```
Claw/
├── Server/                     # 后端服务
│   ├── gateway/                # 网关服务（服务器A）
│   │   ├── src/               # 源代码
│   │   ├── target/            # 编译产出
│   │   └── Cargo.toml         # 项目配置
│   ├── SmartClaw/             # 智能控制服务（服务器B）
│   │   ├── src/               # 源代码
│   │   ├── target/            # 编译产出
│   │   └── Cargo.toml         # 项目配置
│   └── shared/                # 共享代码
│       ├── src/               # 源代码
│       ├── target/            # 编译产出
│       └── Cargo.toml         # 项目配置
├── client/                     # 客户端代码
│   ├── wechat_app/            # 微信小程序（官方原生技术栈）
│   │   ├── pages/             # 页面目录（index, chat, task, user）
│   │   ├── utils/             # 工具函数（api.js, util.js, constant.js）
│   │   ├── components/        # 自定义组件（message, task-card, user-avatar）
│   │   ├── assets/            # 静态资源（images, icons）
│   │   ├── app.js             # 应用入口文件
│   │   ├── app.json           # 应用配置文件
│   │   ├── app.wxss           # 应用全局样式
│   │   ├── project.config.json # 项目配置文件
│   │   └── sitemap.json       # 站点地图配置
│   └── web/                   # 企业微信网页应用（可选）
│       ├── index.html         # 网页入口
│       ├── css/               # 样式文件
│       ├── js/                # JavaScript文件
│       └── assets/            # 静态资源
├── build/                      # 构建产物
│   ├── gateway/               # 网关服务构建产物
│   ├── SmartClaw/             # 智能控制服务构建产物
│   └── client/                # 客户端构建产物
├── docs/                       # 项目文档
├── scripts/                    # 脚本文件
│   ├── build.sh               # 构建脚本
│   ├── deploy_gateway.sh      # 网关服务部署脚本
│   └── deploy_smart_claw.sh   # 智能控制服务部署脚本
├── .gitignore                  # Git忽略文件
├── Cargo.toml                  # 根Rust项目配置（workspace）
├── nginx.conf                  # nginx反向代理配置
├── ssl/                        # SSL证书目录
│   ├── pactgo.cn-chain.pem     # SSL证书链
│   └── pactgo.cn-key.pem       # SSL私钥
└── README.md                   # 项目说明
```

## 7. 实施步骤

1. **准备阶段**:
   * 创建项目基础结构
   * 初始化Git仓库
   * 初始化Rust和前端项目

2. **后端开发**:
   * 开发服务器A后端（网关服务）
   * 开发服务器B后端（SmartClaw服务）
   * 测试服务器间通信

3. **前端开发**:
   * 开发微信小程序（官方原生技术栈：WXML+WXSS+JS）
   * 配置企业微信应用（企业微信JS-SDK）

4. **部署与测试**:
   * 编写部署脚本
   * 部署到服务器
   * 功能测试
   * 性能测试
   * 安全测试

5. **文档编写**:
   * 编写项目文档
   * 编写API文档
   * 编写部署文档
   * 编写使用文档

## 8. 企业微信配置详情

### 8.1 企业微信应用配置

**应用基本信息：**
- 应用名称：智控未来
- 应用主页： https://pactgo.cn
- 回调地址： https://pactgo.cn/wecom
- 使用CorpID和Secret进行认证

**回调地址说明：**
- 企业微信会将用户消息和事件推送到此地址
- 必须是HTTPS协议（企业微信强制要求）
- 路径为 `/wecom`，对应网关服务的 `/api/v1/wecom` 路由
- 支持GET（验证）和POST（消息推送）请求

### 8.2 网络通信路径

**完整的消息流转路径：**
```
用户发送消息 → 企业微信 → https://pactgo.cn/wecom → Nginx → 网关服务(/api/v1/wecom) → 处理消息
```

**路径映射关系：**
| 外部URL | Nginx Location | 代理目标 | 网关路由 | 处理函数 |
|---------|----------------|----------|----------|----------|
| `https://pactgo.cn/wecom` | `/wecom` | `/wecom` | `/wecom` | `handle_wechat_callback` |

### 8.3 消息处理流程

1. **URL验证（GET请求）：**
   - 企业微信首次配置时会发送GET请求进行URL验证
   - 网关服务需要正确响应验证参数
   - 验证通过后企业微信才会发送实际消息

2. **消息推送（POST请求）：**
   - 用户在企业微信应用中发送消息
   - 企业微信将消息POST到回调地址
   - 网关服务接收并处理消息
   - 返回正确响应给企业微信

### 8.4 路径一致性检查

**企业微信配置路径：**
- 回调地址：`https://pactgo.cn/wecom`

**Nginx代理配置：**
```nginx
location /wecom {
    proxy_pass http://127.0.0.1:8000/api/v1/wecom;
}
```

**网关服务路由：**
```rust
.route("/wecom", web::post().to(handle_wechat_callback))
```

**验证结果：** ✅ 路径完全一致

## 9. 注意事项
</tool_call>

1. **网络通信**:
   * 服务器B在内网中，使用WebSocket反向连接方案：SmartClaw服务主动连接网关服务的WebSocket
   * 维持持久WebSocket连接，支持心跳检测和断线重连
   * 使用Embedded-Redis进行多用户多设备状态管理
   * **重要：企业微信回调地址必须保持一致**
     - 企业微信配置：`https://pactgo.cn/wecom`
     - Nginx代理：`/wecom` → `/api/v1/wecom`
     - 网关服务路由：`/wecom`
     - 确保路径完全一致，否则消息无法到达网关服务

2. **安全考虑**:
   * 所有通信使用HTTPS加密（企业微信强制要求）
   * 服务器A配置防火墙，只开放443端口（HTTPS）
   * 服务器B只允许来自服务器A的WebSocket连接
   * 使用有效SSL证书（Let's Encrypt）
   * 实现认证与授权机制（AppID、CorpID、API密钥）

3. **性能考虑**:
   * 优化WebSocket反向连接，实现长连接和心跳检测
   * 合理使用Embedded-Redis进行多用户状态管理
   * 合理使用LMStudio，支持流式响应（SSE）
   * 使用HeedDB嵌入式数据库，零配置高性能
   * 实现异步处理，提供任务状态反馈

4. **兼容性**:
   * 考虑Windows Server 2012的环境（静态链接编译）
   * 确保代码在目标环境中能正常运行
   * 网关服务需配置Embedded-Redis和SSL证书
   * SmartClaw服务需配置HeedDB和LMStudio连接

5. **部署环境**:
   * 服务器A：Windows Server 2012系统
   * 服务器B：Windows Server 2012系统，安装LMStudio

## 9. 部署配置详情

### 9.1 企业微信应用配置

**必须配置的参数：**
- **应用名称**：智控未来
- **应用主页**：https://pactgo.cn
- **回调地址**：https://pactgo.cn/wecom
- **CorpID**：企业微信的企业ID
- **Secret**：应用的密钥
- **Token**：用于签名验证
- **EncodingAESKey**：消息加解密密钥

**回调地址验证：**
- 企业微信会发送GET请求到 `https://pactgo.cn/wecom` 进行URL验证
- 网关服务必须正确响应验证参数
- 验证通过后才会开始推送消息

### 9.2 Nginx配置验证

**关键配置项：**
```nginx
server {
    listen 443 ssl;
    server_name pactgo.cn;
    
    # 企业微信回调 - 必须正确配置
    location /wecom {
        proxy_pass http://127.0.0.1:8000/api/v1/wecom;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # 企业微信回调特殊处理
        proxy_read_timeout 30s;
        proxy_connect_timeout 10s;
    }
}
```

**配置检查清单：**
- [ ] SSL证书有效且未过期
- [ ] 443端口已开放
- [ ] `/wecom` 路径正确代理到网关服务
- [ ] 超时设置合理（建议30秒）

### 9.3 网关服务配置

**必须实现的路由：**
```rust
// 企业微信回调 - 必须匹配企业微信配置
.route("/wecom", web::post().to(handle_wechat_callback))

// 其他路由
.route("/wechat/miniprogram/callback", web::post().to(handle_wechat_miniprogram_callback))
.route("/ws/control", web::get().to(websocket_handler))
```

**处理函数要求：**
- 必须实现GET方法用于URL验证
- 必须实现POST方法用于消息处理
- 必须正确验证签名
- 必须返回正确的响应格式

### 9.4 路径一致性检查

**完整路径映射：**
| 外部URL | Nginx Location | 代理目标 | 网关路由 | 处理函数 |
|---------|----------------|----------|----------|----------|
| `https://pactgo.cn/wecom` | `/wecom` | `/api/v1/wecom` | `/wecom` | `handle_wechat_callback` |
| `https://pactgo.cn/api/v1/wechat/miniprogram/callback` | `/api/v1/wechat/miniprogram/callback` | `/api/v1/wechat/miniprogram/callback` | `/wechat/miniprogram/callback` | `handle_wechat_miniprogram_callback` |

**验证命令：**
```bash
# 测试企业微信回调地址
curl -X GET "https://pactgo.cn/wecom?msg_signature=xxx&timestamp=xxx&nonce=xxx&echostr=xxx"

# 测试微信小程序回调地址
curl -X POST "https://pactgo.cn/api/v1/wechat/miniprogram/callback" \
  -H "Content-Type: application/json" \
  -d '{"code":"test_code"}'
```

## 10. 开发计划

### 10.1 阶段一：基础设施搭建

- 配置服务器环境
- 安装必要的软件和依赖
- 搭建开发环境

### 10.2 阶段二：后端开发

- 开发网关服务（服务器A）的Web服务（Embedded-Redis多用户管理）
- 开发SmartClaw服务（服务器B）的Web服务（WebSocket客户端）
- 实现WebSocket反向连接通信（B主动连接A）
- 开发智能控制核心逻辑
- 集成LMStudio API（SSE流式响应）

### 10.3 阶段三：前端开发

- 开发微信小程序（官方原生技术栈：WXML+WXSS+JS）
- 配置企业微信应用（企业微信JS-SDK）
  - 应用名称：智控未来
  - 应用主页： https://pactgo.cn
  - 回调地址： https://pactgo.cn/wecom
  - 使用CorpID和Secret进行认证

### 10.4 阶段四：测试与部署

- 功能测试
- 性能测试
- 安全测试
- 部署到生产环境

### 10.5 阶段五：运维与监控

- 配置监控系统
- 制定运维计划
- 建立故障处理流程

## 10. 风险评估

| 风险 | 影响 | 应对措施 |
|------|------|----------|
| 企业微信未经认证 | 可能限制部分功能 | 尽量使用企业微信开放的基础功能，避免需要认证的高级功能 |
| SmartClaw服务在内网 | 外网无法直接访问 | 使用WebSocket反向连接方案：B主动连接A |
| LMStudio性能 | 可能影响处理速度 | 优化智能控制核心逻辑，支持SSE流式响应 |
| 网络延迟 | 可能影响用户体验 | 优化WebSocket长连接，实现心跳检测和断线重连 |
| SSL证书配置 | 影响企业微信回调 | 使用Let's Encrypt自动化证书管理 |
| 多用户并发 | 可能影响系统性能 | 使用Embedded-Redis进行多用户状态管理 |

## 11. 结论

基于以上分析，本项目在技术、网络和成本方面都是可行的。采用WebSocket反向连接架构，使用官方原生微信小程序技术栈，实现用户通过企业微信和微信小程序与系统进行交互，完成AI任务的下发、处理和结果返回。系统具备多用户多设备管理能力，支持高并发和零配置部署。

建议按照开发计划分阶段实施，确保系统的稳定性和可靠性。同时，要注意安全防护，保护用户数据和系统资源。