# housekeep-orders-user

**Repository Path**: chen_chan_shang/housekeep-orders-user

## Basic Information

- **Project Name**: housekeep-orders-user
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-25
- **Last Updated**: 2026-05-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 家政抢单助手

这个仓库现在包含 4 个子系统：

- `backend/`：Spring Boot 3 + MySQL 后端
- `android-app/`：关键词提醒 Android 客户端
- `broadcast-app/`：Android 无障碍群发执行端
- `pc-agent/`：新的 PC 群发执行端，已包含 Java 原生 Windows 微信适配器

这次改动的重点是把微信群发能力从“仅 Android 无障碍执行”扩展成“后端统一调度 + PC Agent 执行”的架构，同时尽量复用现有广播任务表和状态回写逻辑。

## 为什么加 PC Agent

Android 无障碍驱动微信存在几个先天问题：

- 微信窗口树可能不稳定，甚至拿不到可遍历节点
- 用户自己的手机必须保持微信在前台
- 多账号、多群归属、多执行节点都很难管理

PC 方案更适合做“专用执行机”：

- 每个已登录微信号都作为一个独立会话管理
- 后端创建任务时就能指定执行微信号
- PC Agent 负责心跳、会话同步、群同步、任务领取和状态回写

## 新的群发架构

```mermaid
flowchart LR
    A["管理端 / App"] --> B["Spring Boot 后端"]
    B --> C["broadcast_task"]
    B --> D["send_record"]
    B --> E["pc_agent"]
    B --> F["wechat_session"]
    B --> G["group_entry(session scoped)"]
    H["Windows PC Agent"] --> B
    H --> I["微信 PC 客户端"]
```

## 这次已经实现的内容

### 后端

已新增：

- `PcAgent`：PC 执行节点
- `WechatSession`：某个 Agent 上识别到的微信登录会话
- `GroupEntry` 扩展为可绑定 `wechatSession + externalChatKey + chatType + lastSyncedAt`
- `BroadcastTask` 扩展为可绑定 `wechatSession + claimedByAgent + claimedAt`

已新增接口：

- `GET /api/pc-agents`
- `POST /api/pc-agents/heartbeat`
- `GET /api/pc-agents/sessions`
- `POST /api/pc-agents/sessions/sync`
- `POST /api/pc-agents/sessions/{sessionId}/groups/sync`
- `POST /api/broadcast-tasks/{id}/claim`
- `POST /api/broadcast-tasks/next`

已兼容保留：

- 现有 `POST /api/broadcast-tasks`
- 现有 `GET /api/broadcast-tasks`
- 现有 `GET /api/broadcast-tasks/{id}`
- 现有 `PUT /api/broadcast-tasks/{taskId}/records/{groupId}`
- 现有 `PUT /api/broadcast-tasks/{id}/complete`

兼容规则：

- 老的 Android 广播端继续可以用旧的 `CreateTaskRequest(templateId, groupIds)`
- 新的 PC 任务可以额外传 `sessionId`
- 如果不传 `sessionId`，后端会尝试从所选群里自动推断唯一会话

### PC Agent

`pc-agent/` 已实现一个 Java 版 PC 执行端：

- `heartbeat`
- `sessions sync`
- `groups sync`
- `claim next task`
- `update record`
- `complete task`
- `run-loop` 常驻轮询
- `windows-native` 纯 Java Windows 微信发送适配器

它已经把后端协议和 Windows 发信动作串起来了。当前原生适配器是启发式实现，依赖窗口前台激活、比例坐标点击和剪贴板粘贴。

### 测试

后端测试已覆盖：

- 原有广播任务属性测试
- 新增 PC 会话推断
- 跨会话建任务拒绝
- `next task` 领取逻辑

## 目录说明

```text
backend/
  pom.xml
  src/main/java/com/housekeep/alertserver/
android-app/
  app/
broadcast-app/
  app/
pc-agent/
  pom.xml
  src/main/java/com/housekeep/pcagent/
  config.example.json
  README.md
```

## 环境要求

- JDK `17`
- Maven `3.9+`
- MySQL `8`
- Maven `3.9+`

## 后端启动

### 1. 配置环境变量

后端不再把数据库和 OSS 密钥写死在仓库里，统一通过环境变量注入。

最少需要：

```bash
export MYSQL_HOST=localhost
export MYSQL_PORT=3306
export MYSQL_DB=housekeep_alert
export MYSQL_USER=root
export MYSQL_PASSWORD=123456
export SERVER_PORT=8080
```

如果你要用上传能力，再补：

```bash
export ALIYUN_OSS_ENDPOINT=https://oss-cn-beijing.aliyuncs.com
export ALIYUN_OSS_REGION=cn-beijing
export ALIYUN_OSS_ACCESS_KEY_ID=your-key
export ALIYUN_OSS_ACCESS_KEY_SECRET=your-secret
export ALIYUN_OSS_BUCKET_NAME=your-bucket
export ALIYUN_OSS_URL_PREFIX=https://your-bucket.oss-cn-beijing.aliyuncs.com
```

### 2. 启动 MySQL

如果你本地有 MySQL，直接建库即可：

```sql
create database housekeep_alert character set utf8mb4 collate utf8mb4_unicode_ci;
```

### 3. 启动 Spring Boot

仓库当前没有 Maven Wrapper，请先安装 Maven。

```bash
cd backend
mvn spring-boot:run
```

健康检查：

```bash
curl http://localhost:8080/health
```

## 数据库迁移注意

当前后端使用 `spring.jpa.hibernate.ddl-auto=update`。

这次结构调整涉及：

- 新增表 `pc_agent`
- 新增表 `wechat_session`
- `group_entry` 新增 `wechat_session_id / external_chat_key / chat_type / last_synced_at`
- `broadcast_task` 新增 `wechat_session_id / claimed_by_agent_id / claimed_at`

如果你是全新数据库，直接启动即可自动建表。

如果你是已有数据库，重点注意 `group_entry` 旧版本可能存在 `user_id + group_name` 唯一约束。JPA `update` 不一定会自动替你删除旧约束。如果你后面需要“同一用户在不同微信号下存在同名群”，建议手工检查并迁移这个约束。

## PC Agent 启动

### 1. 准备配置

```bash
cd pc-agent
cp config.example.json local.json
```

如果你是在 Windows 上接真实微信，建议直接：

```bash
cd pc-agent
cp windows-native.example.json local.json
```

把 `local.json` 里的这几个字段改成你自己的：

- `base_url`
- `auth_token`
- `agent_key`
- `sessions`
- `groups_by_session`
- `adapter` 里的窗口比例和延迟

### 2. 首次握手

先构建：

```bash
cd /Users/chenzhanshang/order/housekeep-orders-user/pc-agent
mvn package
```

然后执行：

```bash
java -jar target/pc-agent-0.1.0.jar --config local.json heartbeat
java -jar target/pc-agent-0.1.0.jar --config local.json sync
java -jar target/pc-agent-0.1.0.jar --config local.json list-sessions
java -jar target/pc-agent-0.1.0.jar --config local.json list-groups
```

### 3. 领取任务

```bash
java -jar target/pc-agent-0.1.0.jar --config local.json poll-next --session-id 1
```

常驻运行：

```bash
java -jar target/pc-agent-0.1.0.jar --config local.json run-loop
```

如果你要接 Windows 微信，可以直接从这两份开始：

- [windows-native.example.json](/Users/chenzhanshang/order/housekeep-orders-user/pc-agent/windows-native.example.json)
- [windows-command.example.json](/Users/chenzhanshang/order/housekeep-orders-user/pc-agent/windows-command.example.json)
- [windows-wechat-adapter.ps1](/Users/chenzhanshang/order/housekeep-orders-user/pc-agent/scripts/windows-wechat-adapter.ps1)

原生 Java 方案当前的工作方式是：

1. 枚举桌面微信窗口
2. 用配置好的会话信息匹配微信号
3. 按窗口比例定位搜索框和输入框
4. 搜索群聊并发送消息

如果返回任务详情，执行端就会：

1. 用对应微信会话打开群聊
2. 逐群发送
3. 每个群调用 `update-record`
4. 全部处理后调用 `complete-task`

## 新的群发业务流

1. PC Agent 启动并 `heartbeat`
2. PC Agent 同步本机微信会话
3. PC Agent 同步每个会话可见的群
4. 管理端按“微信账号 -> 群”选择目标
5. 创建广播任务
6. 对应会话的 Agent 调用 `/api/broadcast-tasks/next`
7. 逐条发送并回写结果
8. 所有记录终态后调用 `/complete`

## Android 端现状

### `android-app/`

这是关键词提醒客户端，和 PC 群发不是同一个东西。它主要负责：

- 登录
- 关键词规则
- 消息/订单提醒

### `broadcast-app/`

这是原来的 Android 群发执行端。它目前仍然保留，但建议定位成：

- 实验性方案
- 或专用安卓执行机方案

如果你的目标是稳定的多账号、多群、多设备调度，优先走 `PC Agent`。

## 关键接口示例

### Agent heartbeat

```http
POST /api/pc-agents/heartbeat
X-Auth-Token: ...
Content-Type: application/json

{
  "agentKey": "pc-office-01",
  "displayName": "Office PC",
  "hostName": "WIN-EXEC-01",
  "platform": "windows",
  "appVersion": "0.1.0"
}
```

### 同步微信会话

```http
POST /api/pc-agents/sessions/sync
X-Auth-Token: ...
Content-Type: application/json

{
  "agentKey": "pc-office-01",
  "sessions": [
    {
      "sessionKey": "wechat-main",
      "wechatDisplayName": "张三",
      "wechatNo": "zhangsan01",
      "wxid": "wxid_xxx",
      "status": "ONLINE"
    }
  ]
}
```

### 创建指定会话的群发任务

```http
POST /api/broadcast-tasks
X-Auth-Token: ...
Content-Type: application/json

{
  "templateId": 1,
  "groupIds": [10, 11],
  "sessionId": 3
}
```

### 领取下一条任务

```http
POST /api/broadcast-tasks/next
X-Auth-Token: ...
Content-Type: application/json

{
  "agentKey": "pc-office-01",
  "sessionId": 3
}
```

## 后续建议

下一步如果你继续往下做，优先顺序建议是：

1. 真正实现 Windows 微信会话发现器
2. 实现群聊枚举与增量同步
3. 实现 Windows 发送执行器
4. 管理端改成“先选微信账号，再选群”
5. 给任务增加重试、超时释放、死信处理