Merge pull request #117 from LuSrackhall/ChaiFen-Keytone_album

#116 Chai fen keytone album

Author: LuSrackhall

frontend/src/components/Keytone_album.vue

@@ -0,0 +1,116 @@
+/**
+ * This file is part of the KeyTone project.
+ *
+ * Copyright (C) 2024 LuSrackhall
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ **/
+/**
+ * File: keytoneAlbumMappers.ts
+ *
+ * 目的（Why）
+ * - 收敛“配置数据 → UI 结构”的纯映射逻辑，避免在多个位置重复写 Object.entries + sort。
+ * - 让这些逻辑保持纯函数（输入 → 输出），便于单独审阅、复用与定位问题。
+ *
+ * 使用场景（Where used）
+ * - `useKeytoneAlbumSseSync.ts`：处理 SSE 推送的全量配置更新。
+ * - `Keytone_album.vue` 的 initData：初始化读取配置时复用相同映射，确保"初始化"和"SSE 更新"一致。
+ * - `Keytone_album.vue` 的 watch(audioFiles)：当 audioFiles 变化时，复用 mapAudioFilesArrayToSoundFileList。
+ *
+ * 设计约束（Constraints）
+ * - 不直接依赖 Vue 响应式：这里不操作 ref/reactive，仅返回新数组/Map。
+ * - 不做业务裁剪：除非历史实现里有明确的裁剪规则（例如：单键声效必须 down/up 至少一个存在）。
+ *
+ * Debug 指南
+ * - 映射结果不对：优先检查传入的 config（audio_files/sounds/key_sounds）结构是否与后端一致。
+ * - 排序不对：检查调用方传入的 naturalSort 是否与原实现一致。
+ */
+
+export type NaturalSortFn = (a: string, b: string) => number;
+
+export function mapAudioFilesConfigToArray(audioFilesConfig: any): Array<{ sha256: string; value: any }> {
+  if (!audioFilesConfig) return [];
+  return Object.entries(audioFilesConfig).map(([sha256, value]) => ({ sha256, value }));
+}
+
+export function mapAudioFilesArrayToSoundFileList(
+  audioFilesArray: Array<{ sha256: string; value: any }>,
+  naturalSort: NaturalSortFn
+): Array<{ sha256: string; name_id: string; name: string; type: string }> {
+  const tempSoundFileList: Array<{ sha256: string; name_id: string; name: string; type: string }> = [];
+
+  audioFilesArray.forEach((item) => {
+    if (item?.value?.name !== undefined && item?.value?.name !== null) {
+      Object.entries(item.value.name).forEach(([name_id, name]) => {
+        tempSoundFileList.push({
+          sha256: item.sha256,
+          name_id,
+          name: name as string,
+          type: item.value.type as string,
+        });
+      });
+    }
+  });
+
+  tempSoundFileList.sort((a, b) => naturalSort(a.name + a.type, b.name + b.type));
+  return tempSoundFileList;
+}
+
+export function mapSoundsConfigToList(
+  soundsConfig: any,
+  naturalSort: NaturalSortFn
+): Array<{ soundKey: string; soundValue: any }> {
+  if (!soundsConfig) return [];
+  const sounds = Object.entries(soundsConfig).map(([soundKey, soundValue]) => ({ soundKey, soundValue }));
+
+  sounds.sort((a: any, b: any) => {
+    const aName = (a.soundValue?.name as string) || a.soundKey;
+    const bName = (b.soundValue?.name as string) || b.soundKey;
+    return naturalSort(aName, bName);
+  });
+
+  return sounds;
+}
+
+export function mapKeySoundsConfigToList(
+  keySoundsConfig: any,
+  naturalSort: NaturalSortFn
+): Array<{ keySoundKey: string; keySoundValue: any }> {
+  if (!keySoundsConfig) return [];
+  const keySounds = Object.entries(keySoundsConfig).map(([keySoundKey, keySoundValue]) => ({
+    keySoundKey,
+    keySoundValue,
+  }));
+
+  keySounds.sort((a: any, b: any) => {
+    const aName = (a.keySoundValue?.name as string) || a.keySoundKey;
+    const bName = (b.keySoundValue?.name as string) || b.keySoundKey;
+    return naturalSort(aName, bName);
+  });
+
+  return keySounds;
+}
+
+export function mapSingleKeyConfigToKeysWithSoundEffect(singleConfig: any): Map<string, any> {
+  const keysWithSoundEffect = new Map<string, any>();
+  if (!singleConfig) return keysWithSoundEffect;
+
+  Object.entries(singleConfig).forEach(([dikCode, value]) => {
+    if ((value as any)?.down?.value || (value as any)?.up?.value) {
+      keysWithSoundEffect.set(dikCode, value);
+    }
+  });
+
+  return keysWithSoundEffect;
+}

frontend/src/components/keytone-album/composables/keytoneAlbumMappers.ts

@@ -0,0 +1,133 @@
+/**
+ * This file is part of the KeyTone project.
+ *
+ * Copyright (C) 2024 LuSrackhall
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ **/
+/**
+ * File: useKeytoneAlbumDependencyIssues.ts
+ *
+ * 目的（Why）
+ * - 将 `Keytone_album.vue` 中“依赖校验（Dependency validation）”相关的 computed + watch 抽离为 composable。
+ * - 使父组件只需要拿到 `dependencyIssues` 与 `checkItemDependencyIssues`，用于 UI 展示与标记。
+ *
+ * 输入/输出（API）
+ * - 输入：soundFileList / soundList / keySoundList / keysWithSoundEffect（均来自父组件的响应式状态）
+ * - 输出：
+ *   - `dependencyIssues`: Ref<DependencyIssue[]> 供 UI 组件展示（例如 DependencyWarning）
+ *   - `allDependencyIssues`: computed（便于调试/扩展）
+ *   - `checkItemDependencyIssues`: 给列表项快速判定是否存在依赖问题
+ *
+ * 与哪些文件配合（Integration）
+ * - 调用方：`frontend/src/components/Keytone_album.vue`
+ * - 依赖：`src/utils/dependencyValidator`
+ *
+ * 关键实现说明（Important details）
+ * - 历史原因：UI 选择器里 keySound 的 down/up value 可能被转换成“对象形态”（包含 soundKey/keySoundKey）。
+ *   但依赖校验器期望的是“字符串 key”形态。
+ *   因此这里对 keySoundList 做深拷贝，并把对象形态还原为字符串 key，再交给 validator。
+ * - 重要：这里的深拷贝是为了避免污染 UI 状态，确保依赖校验是只读的。
+ *
+ * 行为不变约束（Behavior parity）
+ * - `globalBinding` 目前仍为 undefined（与原实现一致），仅校验 singleKeyBindings。
+ * - watch 采用 deep: true（与原实现一致）。
+ */
+
+import { computed, ref, watch, type Ref } from 'vue';
+
+import {
+  createDependencyValidator,
+  hasItemDependencyIssues,
+  type AudioFile,
+  type DependencyIssue,
+  type KeySound,
+  type Sound,
+} from 'src/utils/dependencyValidator';
+
+type KeytoneKeySoundListItem = any;
+
+type Params = {
+  soundFileList: Ref<Array<any>>;
+  soundList: Ref<Array<any>>;
+  keySoundList: Ref<Array<KeytoneKeySoundListItem>>;
+  keysWithSoundEffect: Ref<Map<string, any>>;
+};
+
+export function useKeytoneAlbumDependencyIssues(params: Params) {
+  const dependencyIssues = ref<DependencyIssue[]>([]);
+
+  const allDependencyIssues = computed(() => {
+    const audioFiles = params.soundFileList.value as AudioFile[];
+    const sounds = params.soundList.value as Sound[];
+
+    const keySounds = params.keySoundList.value
+      .map((keySound) => {
+        const keySoundCopy = JSON.parse(JSON.stringify(keySound));
+
+        keySoundCopy.keySoundValue.down.value = keySoundCopy.keySoundValue.down.value.map((item: any) => {
+          if (item.type === 'sounds' && item.value && typeof item.value === 'object' && item.value.soundKey) {
+            return { type: 'sounds', value: item.value.soundKey };
+          }
+          if (item.type === 'key_sounds' && item.value && typeof item.value === 'object' && item.value.keySoundKey) {
+            return { type: 'key_sounds', value: item.value.keySoundKey };
+          }
+          return item;
+        });
+
+        keySoundCopy.keySoundValue.up.value = keySoundCopy.keySoundValue.up.value.map((item: any) => {
+          if (item.type === 'sounds' && item.value && typeof item.value === 'object' && item.value.soundKey) {
+            return { type: 'sounds', value: item.value.soundKey };
+          }
+          if (item.type === 'key_sounds' && item.value && typeof item.value === 'object' && item.value.keySoundKey) {
+            return { type: 'key_sounds', value: item.value.keySoundKey };
+          }
+          return item;
+        });
+
+        return keySoundCopy;
+      })
+      .filter(Boolean) as KeySound[];
+
+    if (audioFiles.length === 0 && sounds.length === 0 && keySounds.length === 0) {
+      return [];
+    }
+
+    const validator = createDependencyValidator(audioFiles, sounds, keySounds);
+
+    const globalBinding = undefined;
+
+    const singleKeyBindings = params.keysWithSoundEffect.value.size > 0 ? params.keysWithSoundEffect.value : undefined;
+
+    return validator.validateAllDependencies(globalBinding, singleKeyBindings);
+  });
+
+  watch(
+    [params.soundFileList, params.soundList, params.keySoundList, params.keysWithSoundEffect],
+    () => {
+      dependencyIssues.value = allDependencyIssues.value;
+    },
+    { deep: true }
+  );
+
+  const checkItemDependencyIssues = (itemType: 'audio_files' | 'sounds' | 'key_sounds', itemId: string) => {
+    return hasItemDependencyIssues(itemType, itemId, dependencyIssues.value);
+  };
+
+  return {
+    dependencyIssues,
+    allDependencyIssues,
+    checkItemDependencyIssues,
+  };
+}