From ac4cea4658316fa332ef35510025f90dd15bea3b Mon Sep 17 00:00:00 2001
From: R2m1liA <15258427350@163.com>
Date: Fri, 26 Dec 2025 04:41:16 +0000
Subject: [PATCH] =?UTF-8?q?chore:=20=E6=B7=BB=E5=8A=A0=E5=BE=AE=E4=BF=A1?=
 =?UTF-8?q?=E4=BA=8B=E4=BB=B6=E6=8E=A8=E9=80=81=E7=B1=BB=E5=9E=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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

diff --git a/src/types/received-event.ts b/src/types/received-event.ts
new file mode 100644
index 0000000..8a4382d
--- /dev/null
+++ b/src/types/received-event.ts
@@ -0,0 +1,114 @@
+/**
+ * 微信公众号/服务号「接收事件推送」类型定义 
+ * 
+ * @remarks
+ * - 对应微信官方XML信息结构
+ * - 所有事件类型继承自 {@link WechatReceivedBaseEvent}
+ * - 通过 {@link Event} 字段区分不同事件类型
+ * @see 微信官方文档: https://developers.weixin.qq.com/doc/service/guide/product/message/Receiving_event_pushes.html
+ * 
+ * @packageDocumentation
+ */
+
+/**
+ * 「接收事件推送」事件类型字面量联合类型
+ * 
+ * @remarks
+ * 可用于类型收窄
+ */
+export type WechatReceivedEventType = | "subscribe"
+    | "unsubscribe"
+    | "SCAN"
+    | "LOCATION"
+    | "CLICK"
+    | "VIEW"
+
+/**
+ * 「接收事件推送」基础类型定义
+ * 
+ * @remarks
+ * 所有事件类型均包含这些公共字段
+ */
+export interface WechatReceivedBaseEvent {
+    /** 开发者微信号 */
+    ToUserName: string;
+    /** 发送方帐号（一个OpenID） */
+    FromUserName: string;
+    /** 消息创建时间 （整型） */
+    CreateTime: number;
+    /** 消息类型，event */
+    MsgType: "event";
+    /** 事件类型
+     * 
+     * @remarks
+     * 在具体事件类型中收窄为字面量类型(如"subscribe","CLICK"等)
+     */
+    Event: string;
+}
+
+/**
+ * 「接收事件推送」用户未关注时，进行关注后的事件推送
+ */
+export interface WechatReceivedSubscribeEvent extends WechatReceivedBaseEvent {
+    /** 事件类型: subscribe */
+    Event: "subscribe";
+    /** 事件KEY值，qrscene_为前缀，后面为二维码的参数值 */
+    EventKey?: string;
+    /** 二维码的ticket，可用来换取二维码图片 */
+    Ticket?: string;
+}
+
+/**
+ * 「接收事件推送」用户已关注时的事件推送
+ */
+export interface WechatReceivedScanEvent extends WechatReceivedBaseEvent {
+    /** 事件类型: SCAN */
+    Event: "SCAN";
+    /** 事件KEY值，是一个32位无符号整数，即创建二维码时的二维码scene_id */
+    EventKey: string;
+    /** 二维码的ticket，可用来换取二维码图片 */
+    Ticket: string;
+}
+
+/**
+ * 「接收事件推送」上报地理位置事件
+ */
+export interface WechatReceivedLocationEvent extends WechatReceivedBaseEvent {
+    /** 事件类型: LOCATION */
+    Event: "LOCATION";
+    /** 地理位置纬度 */
+    Latitude: string;
+    /** 地理位置经度 */
+    Longitude: string;
+    /** 地理位置精度 */
+    Precision: string;
+}
+
+/**
+ * 「接收事件推送」自定义菜单点击事件
+ */
+export interface WechatReceivedClickEvent extends WechatReceivedBaseEvent {
+    /** 事件类型: CLICK */
+    Event: "CLICK";
+    /** 事件KEY值，与自定义菜单接口中KEY值对应 */
+    EventKey: string;
+}
+
+/**
+ * 「接收事件推送」自定义菜单跳转链接事件
+ */
+export interface WechatReceivedViewEvent extends WechatReceivedBaseEvent {
+    /** 事件类型: VIEW */
+    Event: "VIEW";
+    /** 事件KEY值，设置的跳转URL */
+    EventKey: string;
+}
+
+/**
+ * 「接收事件推送」类型联合类型
+ */
+export type WechatReceivedEvent = WechatReceivedSubscribeEvent
+    | WechatReceivedScanEvent
+    | WechatReceivedLocationEvent
+    | WechatReceivedClickEvent
+    | WechatReceivedViewEvent;
\ No newline at end of file