微信智能体助手 + 后端服务（完整中文使用手册）

本目录包含两个 Spring Boot + Maven 项目，用于模拟“微信群聊天记录 JSON 上报到后端并解析”的完整流程。

一、你现在得到的内容

1. 项目结构

• wechat-agent-assistant
  微信智能体助手模拟端，负责通过 POST 将 JSON 数组转发给后端。
• wechat-backend-service
  后端接收服务，负责接收 JSON、进行初步解析，并返回解析结果。

2. 已实现能力

• 发送端支持：
  • 查看当前后端目标地址；
  • 转发外部传入 JSON；
  • 一键发送样例 JSON。
• 后端支持：
  • 接收 JSON 数组；
  • 基础参数校验（key1 ~ key6 必填）；
  • 初步字段解析映射；
  • 统一校验异常返回。
• Nacos 支持：
  • 后端服务注册到 Nacos；
  • 后端从 Nacos 配置中心读取同名配置（可选导入，不影响本地无 Nacos 启动）。

3. 技术栈说明

• 开发语言：Java 17
• 框架：Spring Boot 3.3.5
• 构建：Maven
• 已接入：Nacos（注册中心 + 配置中心）
• 已预留依赖：MyBatis / JDBC / Redis（当前未启用业务逻辑）

---

二、使用手册

1. 环境准备

• JDK 17
• Maven 3.8+
• IDEA（推荐）
• （可选）Nacos Server（默认 127.0.0.1:8848）

2. 导入项目

在 IDEA 中分别导入以下两个 Maven 项目：

• wechat-agent-assistant
• wechat-backend-service

等待 Maven 依赖下载完成即可。

3. 默认端口

• 发送端：8080
• 后端：8081

---

三、启动顺序

建议按以下顺序启动：

1. 启动 wechat-backend-service
2. 再启动 wechat-agent-assistant

如果你启用了 Nacos，建议先启动 Nacos，再启动后端服务，最后启动发送端。

---

四、接口说明

1. 发送端（wechat-agent-assistant）

基础地址：http://localhost:8080

• GET /assistant/target
  查看当前转发目标地址。

• POST /assistant/forward
  接收你传入的 JSON 数组，并转发给后端。

• POST /assistant/push-sample
  发送内置样例 JSON（4 条记录）到后端。

2. 后端（wechat-backend-service）

基础地址：http://localhost:8081

• POST /api/chat-records/ingest
  接收 JSON 数组，做初步解析并返回结果。

---

五、联调示例

以下示例均可在终端执行（Windows PowerShell、CMD、Git Bash 均可，命令写法按实际环境微调）。

示例 1：一键发送样例数据

curl -X POST "http://localhost:8080/assistant/push-sample"

示例 2：发送你自己的 JSON 数组

curl -X POST "http://localhost:8080/assistant/forward" \
  -H "Content-Type: application/json" \
  -d "[{\"key1\":\"value1_1\",\"key2\":\"value2_1\",\"key3\":\"value3_1\",\"key4\":\"value4_1\",\"key5\":\"value5_1\",\"key6\":\"value6_1\"}]"

示例 3：直接调用后端接收接口

curl -X POST "http://localhost:8081/api/chat-records/ingest" \
  -H "Content-Type: application/json" \
  -d "[{\"key1\":\"u001\",\"key2\":\"张三\",\"key3\":\"text\",\"key4\":\"大家好\",\"key5\":\"2026-04-21 10:00:00\",\"key6\":\"group_01\"}]"

---

六、请求与解析映射说明

1. 请求 JSON 结构（单条）

{
  "key1": "value1",
  "key2": "value2",
  "key3": "value3",
  "key4": "value4",
  "key5": "value5",
  "key6": "value6"
}

2. 后端初步解析映射规则

• key1 -> senderId
• key2 -> senderName
• key3 -> messageType
• key4 -> content
• key5 -> messageTime
• key6 -> groupId

---

七、Nacos 配置与服务注册说明

后端 wechat-backend-service 已支持 Nacos：

• 默认 Nacos 地址：127.0.0.1:8848
• 默认服务名：wechat-backend-service
• 默认配置 DataId：wechat-backend-service.yaml

1. 可选环境变量

• NACOS_SERVER_ADDR：Nacos 地址（示例：127.0.0.1:8848）
• NACOS_USERNAME：Nacos 用户名
• NACOS_PASSWORD：Nacos 密码
• NACOS_NAMESPACE：命名空间 ID
• NACOS_DISCOVERY_GROUP：服务发现分组
• NACOS_CONFIG_GROUP：配置中心分组

2. 启动后验证

1. 打开 Nacos 控制台；
2. 在“服务管理”中查看是否存在 wechat-backend-service；
3. 若有配置中心数据，确认 DataId 为 wechat-backend-service.yaml 并生效。

---

八、常见问题

1. 后端启动失败，提示连接 Nacos 问题

• 先确认 Nacos 是否启动；
• 或临时不依赖 Nacos：保持当前 optional:nacos:... 配置即可，本地一般可继续启动；
• 再检查 NACOS_SERVER_ADDR 是否正确。

2. 调用 assistant/forward 返回 400

• 检查 JSON 是否为数组；
• 检查每条记录是否都包含 key1 ~ key6，且值非空字符串。

3. 发送端无法访问后端

• 检查后端是否已启动在 8081；
• 检查发送端配置：backend.base-url 和 backend.ingest-path；
• 可先调用 GET /assistant/target 查看当前目标地址。

---

九、后续可扩展方向（可选）

• MyBatis + MySQL 落库（保存解析后的聊天记录）
• Redis 去重（防止重复消息处理）
• 接口签名验签（提高安全性）
• 通过服务发现进行调用（发送端基于 Nacos 服务名访问后端）