JoyD/Claw/.trae/documents/project_structure_plan.md

# Claw项目 - 工程项目结构实施计划

## 项目背景

Claw项目是一个企业微信智控未来系统，包含两台服务器：

* 服务器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）。

## 项目结构设计

### 整体结构

```
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                   # 项目说明
```

### 模块功能描述

| 模块                     | 功能描述                                                                                        |
| ---------------------- | ------------------------------------------------------------------------------------------- |
| **Server/gateway**     | 网关服务（服务器A），负责接收企业微信和微信小程序的HTTPS请求，通过WebSocket反向连接转发到SmartClaw服务，返回处理结果。实现HTTP接口、Embedded-Redis（多用户多设备状态管理）、企业微信和小程序的回调处理。 |
| **Server/SmartClaw**   | 智能控制服务（服务器B），负责通过WebSocket主动连接网关服务，接收任务请求，调用LMStudio进行AI处理，返回处理结果。实现WebSocket客户端、LMStudio API集成、HeedDB嵌入式数据存储、内网管理接口。 |
| **Server/shared**      | 共享代码，包含网关服务和SmartClaw服务共用的代码，如数据结构、工具函数、常量定义、WebSocket消息格式等。 |
| **client/wechat\_app** | 微信小程序（官方原生技术栈：WXML+WXSS+JS），提供用户交互界面，实现用户登录、WebSocket实时通信、任务提交和状态查看功能。 |
| **client/web**         | 企业微信网页应用（可选），使用企业微信JS-SDK，提供与微信小程序相同的功能，方便用户在电脑端操作。 |
| **build**              | 构建产物目录，存放各服务和客户端的构建结果。                                                                      |
| **docs**               | 项目文档目录，存放项目说明、API文档、部署文档、使用文档等。                                                             |
| **scripts**            | 脚本文件目录，存放构建脚本、部署脚本等。                                                                        |

## 实施任务

### \[ ] Task 1: 创建项目基础结构

* **Priority**: P0

* **Depends On**: None

* **Description**:

  * 创建项目的基础目录结构，包括Server、client、build、docs、scripts等目录

  * 初始化Git仓库

  * 创建.gitignore文件，忽略编译产出目录和构建产物目录

* **Success Criteria**:

  * 项目目录结构创建完成，包括所有必要的子目录

  * Git仓库初始化成功

  * .gitignore文件配置合理，忽略编译产出和构建产物

* **Test Requirements**:

  * `programmatic` TR-1.1: 目录结构符合设计要求，包含所有必要的目录

  * `programmatic` TR-1.2: .gitignore文件存在且配置合理

  * `human-judgement` TR-1.3: 目录结构清晰、合理

* **Notes**: 按照整体结构设计创建目录，确保包含编译产出和构建产物目录

### [ ] Task 2: 初始化Server项目
- **Priority**: P0
- **Depends On**: Task 1
- **Description**:
  - 初始化网关服务（gateway）的Rust项目
  - 初始化智能控制服务（SmartClaw）的Rust项目
  - 初始化共享代码的Rust项目
  - 创建各自的Cargo.toml配置文件
  - 设置依赖项
- **Success Criteria**:
  - 所有Rust项目初始化成功
  - 各自的Cargo.toml配置正确
  - 依赖项设置合理
  - 编译产出目录结构正确
- **Test Requirements**:
  - `programmatic` TR-2.1: 各项目的Cargo.toml文件存在且配置正确
  - `programmatic` TR-2.2: 依赖项能正确安装
  - `programmatic` TR-2.3: 项目能成功编译，生成编译产出
- **Notes**: 使用Cargo初始化Rust项目，确保每个项目都有独立的编译产出目录

### [ ] Task 3: 开发网关服务
- **Priority**: P1
- **Depends On**: Task 2
- **Description**:
  - 创建网关服务（gateway）的代码
  - 实现HTTP接口
  - 实现与SmartClaw服务的WebSocket反向连接通信
  - 实现Embedded-Redis（多用户多设备状态管理）
  - 实现企业微信和小程序的HTTPS回调处理
- **Success Criteria**:
  - 网关服务代码开发完成
  - HTTP接口实现正确
  - 与SmartClaw服务的通信功能正常
  - 企业微信和小程序的回调处理正常
- **Test Requirements**:
  - `programmatic` TR-3.1: 服务能正常启动
  - `programmatic` TR-3.2: HTTP接口能正确响应
  - `human-judgement` TR-3.3: 代码结构清晰、注释完善
- **Notes**: 使用Actix Web框架，集成WebSocket服务端、Embedded-Redis（多用户多设备状态管理）、HTTPS接口、企业微信和小程序回调处理

### [ ] Task 4: 开发SmartClaw服务
- **Priority**: P1
- **Depends On**: Task 2
- **Description**:
  - 创建SmartClaw服务的代码
  - 实现WebSocket客户端主动连接网关服务
  - 实现智能控制核心逻辑
  - 集成LMStudio API（流式响应SSE）
  - 集成HeedDB嵌入式数据存储
- **Success Criteria**:
  - SmartClaw服务代码开发完成
  - WebSocket客户端主动连接功能正常
  - 智能控制核心逻辑实现正确
  - LMStudio API集成成功（支持SSE流式响应）
  - HeedDB嵌入式数据存储功能正常
- **Test Requirements**:
  - `programmatic` TR-4.1: 服务能正常启动
  - `programmatic` TR-4.2: WebSocket客户端主动连接功能正常
  - `programmatic` TR-4.3: LMStudio API集成成功（支持SSE流式响应）
  - `programmatic` TR-4.4: HeedDB嵌入式数据存储功能正常
  - `human-judgement` TR-4.5: 代码结构清晰、注释完善
- **Notes**: 使用Actix Web框架，集成WebSocket客户端、LMStudio API（SSE流式响应）、HeedDB嵌入式数据库

### \[ ] Task 5: 开发微信应用

* **Priority**: P1

* **Depends On**: Task 3

* **Description**:
  * 初始化微信小程序项目（官方原生技术栈：WXML+WXSS+JavaScript）
  * 开发用户界面（首页、聊天页、任务页、用户中心）
  * 实现用户登录授权（wx.login + wx.getUserProfile）
  * 实现与网关服务的WebSocket实时通信
  * 实现任务提交和状态查看功能
  * 配置小程序后台（服务器域名、业务域名）

* **Success Criteria**:
  * 微信小程序项目初始化成功（WXML+WXSS+JS）
  * 用户界面开发完成（首页、聊天、任务、用户中心）
  * 用户登录授权功能正常（wx.login + wx.getUserProfile）
  * WebSocket实时通信功能正常（wx.connectSocket）
  * 任务提交和状态查看功能实现正确
  * 小程序后台配置完成（服务器域名、WebSocket域名）

* **Test Requirements**:
  * `programmatic` TR-5.1: 微信小程序能正常运行（WXML+WXSS+JS）
  * `programmatic` TR-5.2: 用户登录授权功能正常（wx.login）
  * `programmatic` TR-5.3: WebSocket实时通信正常（wx.connectSocket）
  * `programmatic` TR-5.4: 任务提交和状态查看功能正常
  * `human-judgement` TR-5.5: 界面美观、交互流畅（原生小程序UI）

* **Notes**: 使用官方原生微信小程序技术栈（WXML+WXSS+JavaScript）

### \[ ] Task 6: 配置企业微信应用

* **Priority**: P2

* **Depends On**: Task 3

* **Description**:

  * 配置企业微信应用

  * 设置回调地址

  * 实现消息推送处理

* **Success Criteria**:

  * 企业微信应用配置完成

  * 回调地址设置正确

  * 消息推送处理功能实现正确

* **Test Requirements**:

  * `programmatic` TR-6.1: 企业微信回调能正确处理

  * `human-judgement` TR-6.2: 配置过程顺利

* **Notes**: 使用企业微信JS-SDK，配置回调地址为`https://pactgo.cn/wecom`

### [ ] Task 7: 编写构建和部署脚本
- **Priority**: P2
- **Depends On**: Task 3, Task 4, Task 5
- **Description**:
  - 编写构建脚本，生成构建产物
  - 编写网关服务的部署脚本，部署构建产物
  - 编写SmartClaw服务的部署脚本，部署构建产物
  - 编写配置文件
- **Success Criteria**:
  - 构建脚本编写完成，能生成构建产物
  - 部署脚本编写完成
  - 配置文件创建完成
  - 部署过程顺利
- **Test Requirements**:
  - `programmatic` TR-7.1: 构建脚本能正常执行，生成构建产物
  - `programmatic` TR-7.2: 部署脚本能正常执行
  - `human-judgement` TR-7.3: 部署过程文档清晰
- * **Notes**: 考虑Windows Server 2012的环境，确保构建产物能正确部署。网关服务需配置Embedded-Redis，SmartClaw服务需配置HeedDB和LMStudio连接。

### \[ ] Task 8: 编写项目文档

* **Priority**: P2

* **Depends On**: All

* **Description**:

  * 编写项目说明文档

  * 编写API文档

  * 编写部署文档

  * 编写使用文档

* **Success Criteria**:

  * 项目文档编写完成

  * API文档完整

  * 部署文档清晰

  * 使用文档详细

* **Test Requirements**:

  * `human-judgement` TR-8.1: 文档内容完整、清晰

  * `human-judgement` TR-8.2: 文档格式规范

* **Notes**: 使用Markdown格式

## 技术选型

### 后端

* **语言**: Rust 1.70+

* **框架**: Actix Web 4.0+

* **异步运行时**: Tokio 1.0+

* **序列化/反序列化**: Serde 1.0+

* **HTTP客户端**: Reqwest 0.11+

* **缓存和消息队列**: Embedded-Redis（仅网关服务启动）
* **数据存储**: HeedDB（嵌入式K/V数据库，Sled底层）

### 前端

* **微信小程序**: WXML + WXSS + JavaScript（官方原生技术栈）
* **企业微信网页**: 企业微信JS-SDK + HTML + CSS + JavaScript
* **开发工具**: 微信开发者工具（官方IDE）
* **HTTP客户端**: 原生wx.request() API
* **WebSocket**: 原生wx.connectSocket() API

## 实施步骤

1. **准备阶段**:

   * 创建项目基础结构

   * 初始化Git仓库

   * 初始化Rust和前端项目

2. **后端开发**:

   * 开发服务器A后端

   * 开发服务器B后端

   * 测试服务器间通信

3. **前端开发**:

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

4. **部署与测试**:

   * 编写部署脚本

   * 部署到服务器

   * 功能测试

   * 性能测试

   * 安全测试

5. **文档编写**:

   * 编写项目文档

   * 编写API文档

   * 编写部署文档

   * 编写使用文档

## 注意事项

1. **网络通信**:

   * 服务器B在内网中，使用WebSocket反向连接方案：SmartClaw服务主动连接网关服务的WebSocket

2. **安全考虑**:

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

3. **性能考虑**:

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

4. **兼容性**:

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

## 结论

通过以上实施计划，可以构建一个完整的企业微信智控未来系统，采用WebSocket反向连接架构，使用官方原生微信小程序技术栈，实现用户通过企业微信和微信小程序与系统进行交互，完成AI任务的下发、处理和结果返回。系统具备多用户多设备管理能力，支持高并发和零配置部署。