fix: Flag 系统语义问题

dev.md

@@ -52,6 +52,7 @@
 - **不转发导出**：不允许一个文件导出不属于当前 monorepo 或当前文件夹的内容。
 - **无循环引用**：不允许出现循环引用。若遇到不得不循环引用的情况，应首先反思接口设计是否存在问题。
 - **无类型导入**：除非某些极其特殊的场景，否则不得出现 `import type` 引入，全部使用普通引入。
+- **引入位置**：只要模块引入了外部模块，那么此模块的第一行必须是 `import`，不得是注释。所有 `import` 中间不得加入任何注释，也不得加入任何空行，注释只允许出现在所有 `import` 之后。
 
 ### 命名规则
 

packages-user/data-base/src/flag/saveLoad.test.ts

@@ -67,7 +67,7 @@ describe('FlagSystem save and load round trips', () => {
     // 验证 loadState 在同实例上原地恢复字段值（#06-17-5）
     it('keeps field objects on loadState', () => {
         const system = new FlagSystem();
-        const before = system.insertField('score', 7);
+        const before = system.setField('score', 7);
 
         const saved = system.saveState();
         system.loadState(saved);

packages-user/data-base/src/flag/system.test.ts

@@ -48,7 +48,7 @@ beforeAll(async () => {
 /** 创建一个 Flag 系统及其中一个已插入字段，便于直接操作字段对象 */
 function createField<T>(key: PropertyKey, value: T) {
     const system = new modules.FlagSystem();
-    return { system, field: system.insertField(key, value) };
+    return { system, field: system.setField(key, value) };
 }
 
 describe('FlagSystem field container', () => {
@@ -57,7 +57,7 @@ describe('FlagSystem field container', () => {
         const system = new modules.FlagSystem();
         expect(system.occupied('score')).toBe(false);
 
-        system.insertField('score', 1);
+        system.setField('score', 1);
 
         expect(system.occupied('score')).toBe(true);
     });
@@ -108,7 +108,7 @@ describe('FlagSystem field container', () => {
     // 验证 deleteField 移除字段并恢复未占用状态
     it('deletes a field', () => {
         const system = new modules.FlagSystem();
-        system.insertField('temp', 1);
+        system.setField('temp', 1);
 
         system.deleteField('temp');
 

packages-user/data-base/src/flag/system.ts

@@ -9,7 +9,7 @@ export class FlagSystem implements IFlagSystem {
         return this.fieldMap.has(field);
     }
 
-    insertField<T>(field: PropertyKey, value: T): IFlagCommonField<T> {
+    setField<T>(field: PropertyKey, value: T): IFlagCommonField<T> {
         return this.getOrInsert(field, value);
     }
 

packages-user/data-base/src/flag/types.ts

@@ -1,6 +1,6 @@
-//#region 字段
+import { ISaveableContent } from '@user/data-common';
 
-import { ISaveableContent, SaveCompression } from '@user/data-common';
+//#region 字段
 
 export interface IFlagCommonField<T> {
     /** 此字段所处的 Flag 系统 */
@@ -56,7 +56,7 @@ export interface IFlagSystem extends ISaveableContent<IFlagSystemSave> {
      * @param field 字段名称
      * @param value 字段值
      */
-    insertField<T>(field: PropertyKey, value: T): IFlagCommonField<T>;
+    setField<T>(field: PropertyKey, value: T): IFlagCommonField<T>;
 
     /**
      * 获取指定字段对象
@@ -133,15 +133,6 @@ export interface IFlagSystem extends ISaveableContent<IFlagSystemSave> {
      * @param defaultValue 字段默认值
      */
     getFieldValueDefaults<T>(field: PropertyKey, defaultValue: T): T;
-
-    /**
-     * 读取 Flag 系统存档。存档中已存在的字段会复用原实例并在其实例上原地写值，
-     * 因此外部通过 {@link getField} / {@link getOrInsert} 持有的字段引用跨读档仍然有效；
-     * 存档中不存在的字段一律删除，即读档结果以存档为准。
-     * @param state Flag 系统存档
-     * @param compression 压缩级别
-     */
-    loadState(state: IFlagSystemSave, compression: SaveCompression): void;
 }
 
 //#endregion