From 3b73e6cde399f9f34adb58272a8107afabeb3b5f Mon Sep 17 00:00:00 2001
From: R2m1liA <15258427350@163.com>
Date: Fri, 12 Dec 2025 07:20:29 +0000
Subject: [PATCH] =?UTF-8?q?chore:=20=E5=BE=AE=E4=BF=A1=E6=9C=8D=E5=8A=A1?=
 =?UTF-8?q?=E5=8F=B7=E6=8E=A5=E6=94=B6=E6=B6=88=E6=81=AF=E7=B1=BB=E5=9E=8B?=
 =?UTF-8?q?=E5=AE=9A=E4=B9=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/types/received-message.ts | 130 ++++++++++++++++++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 src/types/received-message.ts

diff --git a/src/types/received-message.ts b/src/types/received-message.ts
new file mode 100644
index 0000000..5f77cca
--- /dev/null
+++ b/src/types/received-message.ts
@@ -0,0 +1,130 @@
+/**
+ * 微信公众号/服务号「接收普通消息」类型定义
+ * 
+ * @remarks
+ * - 对应微信官方XML消息结构
+ * - 所有消息类型继承自 {@link WechatReceivedBaseMessage}
+ * - 通过 {@link MsgType} 字段区分不同消息类型
+ * - 见微信官方文档：https://developers.weixin.qq.com/doc/service/guide/product/message/Receiving_standard_messages.html
+ * 
+ * @packageDocumentation
+ */
+
+/**
+ * 「接收普通消息」基础类型定义
+ * 
+ * @remarks
+ * 所有消息类型均包含这些公共字段
+ */
+export interface WechatReceivedBaseMessage {
+    /** 开发者微信号 */
+    ToUserName: string;
+    /** 发送方帐号（一个OpenID） */
+    FromUserName: string;
+    /** 消息创建时间 （整型） */
+    CreateTime: number;
+    /** 消息类型
+     * 
+     * @remarks
+     * 在具体消息类型中收窄为字面量类型(如"text","image"等)
+     */
+    MsgType: string;
+    /** 消息id，64位整型 */
+    MsgId: string;
+    /** 消息数据id,消息来自文章时存在 */
+    MsgDataId?: string;
+    /** 多图文时的文章索引，从1开始，消息来自文章时存在 */
+    Idx?: string;
+}
+
+/**
+ * 「接收普通消息」文本消息
+ */
+export interface WechatReceivedTextMessage extends WechatReceivedBaseMessage {
+    /** 文本消息类型 */
+    MsgType: "text";
+    /** 文本消息内容 */
+    Content: string;
+}
+
+/**
+ * 「接收普通消息」图片消息
+ */
+export interface WechatReceivedImageMessage extends WechatReceivedBaseMessage {
+    /** 图片消息类型 */
+    MsgType: "image";
+    /** 图片链接 */
+    PicUrl: string;
+    /** 图片消息媒体id，可以调用多媒体文件下载接口拉取数据。 */
+    MediaId: string;
+}
+
+/**
+ * 「接收普通消息」语音消息
+ */
+export interface WechatReceivedVoiceMessage extends WechatReceivedBaseMessage {
+    /** 语音消息类型 */
+    MsgType: "voice";
+    /** 语音消息媒体id，可以调用多媒体文件下载接口拉取数据。 */
+    MediaId: string;
+    /** 语音格式，如amr，speex等 */
+    Format: string;
+    /** 16K采样率语音信息媒体id, 可以调用获取临时素材接口拉取数据，返回16K采样率amr/speex语音。 */
+    MediaId16K: string;
+}
+
+/**
+ * 「接收普通消息」视频消息
+ */
+export interface WechatReceivedVideoMessage extends WechatReceivedBaseMessage {
+    /** 视频消息类型，兼容普通视频与短视频 */
+    MsgType: "video" | "shortvideo";
+    /** 视频消息媒体id，可以调用多媒体文件下载接口拉取数据。 */
+    MediaId: string;
+    /** 视频消息缩略图的媒体id，可以调用多媒体文件下载接口拉取数据。 */
+    ThumbMediaId: string;
+}
+
+/**
+ * 「接收普通消息」地理位置消息
+ */
+export interface WechatReceivedLocationMessage extends WechatReceivedBaseMessage {
+    /** 地理位置消息类型 */
+    MsgType: "location";
+    /** 地理位置维度 */
+    Location_X: string;
+    /** 地理位置经度 */
+    Location_Y: string;
+    /** 地图缩放大小 */
+    Scale: string;
+    /** 地理位置信息 */
+    Label: string;
+}
+
+/**
+ * 「接收普通消息」链接消息
+ */
+export interface WechatReceivedLinkMessage extends WechatReceivedBaseMessage {
+    /** 链接消息类型 */
+    MsgType: "link";
+    /** 消息标题 */
+    Title: string;
+    /** 消息描述 */
+    Description: string;
+    /** 消息链接 */
+    Url: string;
+}
+
+/**
+ * 「接收普通消息」消息联合类型
+ * 
+ * @remarks
+ * 可通过MsgType进行类型收窄
+ */
+export type WechatReceivedMessage =
+    | WechatReceivedTextMessage
+    | WechatReceivedImageMessage
+    | WechatReceivedVoiceMessage
+    | WechatReceivedVideoMessage
+    | WechatReceivedLocationMessage
+    | WechatReceivedLinkMessage;
\ No newline at end of file