From 1d9b180d5fe651a4e16184f11fad482dde631ceb Mon Sep 17 00:00:00 2001
From: unanmed <1319491857@qq.com>
Date: Wed, 9 Sep 2026 13:33:42 +0800
Subject: [PATCH] docs(test): describe individual test cases

---
 packages-user/data-base/src/map/eventPath.test.ts         | 1 +
 packages-user/data-base/src/map/eventView.test.ts         | 2 ++
 packages-user/data-base/src/map/mapLifecycle.test.ts      | 5 +++++
 packages-user/data-common/src/store/eventStore.test.ts    | 3 +++
 packages-user/data-state/src/coreEventLayer.test.ts       | 1 +
 packages-user/data-system/src/event/eventDispatch.test.ts | 6 ++++++
 6 files changed, 18 insertions(+)

diff --git a/packages-user/data-base/src/map/eventPath.test.ts b/packages-user/data-base/src/map/eventPath.test.ts
index b05af35..ca0c2bd 100644
--- a/packages-user/data-base/src/map/eventPath.test.ts
+++ b/packages-user/data-base/src/map/eventPath.test.ts
@@ -64,6 +64,7 @@ function createMapState() {
 }
 
 describe('MapState raw event path', () => {
+    // 验证 raw.events 能绑定到点事件视图，并选择 alias=event 的图层
     it('raw point events and event layer', () => {
         const mapState = createMapState();
         const map = mapState.fromRaw(createRaw());
diff --git a/packages-user/data-base/src/map/eventView.test.ts b/packages-user/data-base/src/map/eventView.test.ts
index 5d5edb2..fc0f5cb 100644
--- a/packages-user/data-base/src/map/eventView.test.ts
+++ b/packages-user/data-base/src/map/eventView.test.ts
@@ -8,6 +8,7 @@ vi.hoisted(() => {
 });
 
 describe('LayerEventView reference tracking', () => {
+    // 验证新增、删除和清空事件时 dirty 状态能随参考基准正确变化
     it('keeps dirty state in sync with set, delete, and clear', () => {
         const view = new LayerEventView();
 
@@ -29,6 +30,7 @@ describe('LayerEventView reference tracking', () => {
         expect(view.dirty()).toBe(false);
     });
 
+    // 验证 ref 返回稳定快照，并可通过恢复事件内容变回 clean 而不重设基准
     it('exposes a stable reference snapshot and restores it without markPure', () => {
         const view = new LayerEventView();
         view.set(10, 'first');
diff --git a/packages-user/data-base/src/map/mapLifecycle.test.ts b/packages-user/data-base/src/map/mapLifecycle.test.ts
index 0feb589..35518a6 100644
--- a/packages-user/data-base/src/map/mapLifecycle.test.ts
+++ b/packages-user/data-base/src/map/mapLifecycle.test.ts
@@ -94,6 +94,7 @@ function createMapState(
 }
 
 describe('MapLayer tile defaults snapshots conversion and movement', () => {
+    // 验证静态/动态图块默认事件、存档快照、转换和移动后的点事件归属
     it('tile defaults snapshots conversion and movement', () => {
         const { layer } = createMapState();
         const staticTile = layer.getTile(0, 0)!;
@@ -176,6 +177,7 @@ describe('MapLayer tile defaults snapshots conversion and movement', () => {
 });
 
 describe('MapLayer point event lifecycle', () => {
+    // 验证点事件的 dirty、存档覆盖、基准恢复和不同压缩模式
     it('point event lifecycle', () => {
         const { layer } = createMapState({ 1: { 5: 'raw-point' } });
         const point = layer.event(1, 0)!;
@@ -240,6 +242,7 @@ describe('MapLayer point event lifecycle', () => {
         expect(point.dirty()).toBe(false);
     });
 
+    // 验证只有点事件变化时 GameMap 仍保留对应图层存档
     it('map saves layers containing only point events', () => {
         const { map, layer } = createMapState({}, [0, 0, 0, 0]);
         layer.setZIndex(7);
@@ -267,6 +270,7 @@ describe('MapLayer point event lifecycle', () => {
         }
     });
 
+    // 验证 resize 裁剪范围外事件，resize2 清空全部点事件
     it('resize preserves in-range point events and resize2 clears them', () => {
         const { layer } = createMapState({
             0: { 1: 'top-left' },
@@ -280,6 +284,7 @@ describe('MapLayer point event lifecycle', () => {
         expect(layer.getPointEvent(0, 0)).toEqual(new Map());
     });
 
+    // 验证改变图层宽度后，保留的点事件会使用新索引继续查询
     it('reindexes preserved point events when the layer width changes', () => {
         const { layer } = createMapState({
             1: { 1: 'top-right' },
diff --git a/packages-user/data-common/src/store/eventStore.test.ts b/packages-user/data-common/src/store/eventStore.test.ts
index a57a359..cc6caa7 100644
--- a/packages-user/data-common/src/store/eventStore.test.ts
+++ b/packages-user/data-common/src/store/eventStore.test.ts
@@ -47,6 +47,7 @@ function createEvent() {
 }
 
 describe('GameEventStore public barrel behavior', () => {
+    // 验证使用注册时的 ID 可以取回同一个事件
     it('retrieves an event by the id used when adding it', () => {
         const store = new modules.GameEventStore();
         const event = createEvent();
@@ -56,12 +57,14 @@ describe('GameEventStore public barrel behavior', () => {
         expect(store.getEvent('event-id')).toBe(event);
     });
 
+    // 验证查询不存在的事件 ID 返回 null
     it('returns null for an unknown id', () => {
         const store = new modules.GameEventStore();
 
         expect(store.getEvent('missing-id')).toBeNull();
     });
 
+    // 验证重复 ID 会告警并由后写入事件覆盖旧事件
     it('warns and overwrites when an id is added twice', () => {
         const store = new modules.GameEventStore();
         const firstEvent = createEvent();
diff --git a/packages-user/data-state/src/coreEventLayer.test.ts b/packages-user/data-state/src/coreEventLayer.test.ts
index 578f47a..66b08ae 100644
--- a/packages-user/data-state/src/coreEventLayer.test.ts
+++ b/packages-user/data-state/src/coreEventLayer.test.ts
@@ -124,6 +124,7 @@ function createFloor(offset: number): LegacyFloor {
 }
 
 describe('CoreState legacy event-layer initialization', () => {
+    // 验证 legacy 地图初始化选择 event alias 图层且不改变其他装配结果
     it('selects the event alias layer without changing map assembly', () => {
         const maps = createFakeMapState();
         const initializer = Object.create(
diff --git a/packages-user/data-system/src/event/eventDispatch.test.ts b/packages-user/data-system/src/event/eventDispatch.test.ts
index e5fb6c7..848fd28 100644
--- a/packages-user/data-system/src/event/eventDispatch.test.ts
+++ b/packages-user/data-system/src/event/eventDispatch.test.ts
@@ -225,6 +225,7 @@ function invocation(id: string, trigger: EventTrigger): IGameEventInvocation {
 }
 
 describe('source-aware matching dispatch', () => {
+    // 验证地图绑定的点事件 ID 能经过 event layer 和 mover 执行一次
     it('executes a map-bound point id through the event layer and mover', async () => {
         const calls: EventCall[] = [];
         const fixture = createFixture({ 1: { 50: 'legacy-point-enter' } });
@@ -257,6 +258,7 @@ describe('source-aware matching dispatch', () => {
         });
     });
 
+    // 验证点、静态图块和动态图块按来源携带正确环境并过滤 trigger
     it('source-aware matching dispatch', async () => {
         const calls: EventCall[] = [];
         const fixture = createFixture({
@@ -317,6 +319,7 @@ describe('source-aware matching dispatch', () => {
         expect(calls[2].triggerLocator).toEqual({ x: 1, y: 0 });
     });
 
+    // 验证来源事件按排序顺序逐个 await，不会并行执行
     it('awaits each source before continuing to the next one', async () => {
         const calls: EventCall[] = [];
         let release: () => void = () => {};
@@ -384,6 +387,7 @@ describe('source-aware matching dispatch', () => {
 });
 
 describe('event execute modes and reductions', () => {
+    // 验证 cut 和 reduce 只作用于 trigger 匹配且实际执行的事件
     it('applies cut and reduce only to matching events', async () => {
         const calls: string[] = [];
         const fixture = createFixture();
@@ -475,6 +479,7 @@ describe('event execute modes and reductions', () => {
         ).resolves.toBe(true);
     });
 
+    // 验证未知事件 ID 只告警并跳过，后续合法事件仍继续执行
     it('warns for unknown ids and continues with valid events', async () => {
         const calls: string[] = [];
         const fixture = createFixture();
@@ -500,6 +505,7 @@ describe('event execute modes and reductions', () => {
 });
 
 describe('enter leave hit trigger hooks', () => {
+    // 验证 enter、leave、hit 使用正确 trigger 和角色/触发坐标
     it('maps enter leave and hit to their approved triggers and coordinates', async () => {
         const calls: EventCall[] = [];
         const fixture = createFixture(