Beyond-KLE/backlog/README.md

保留課題

現在の実装が答えに依存せず進められる問い・検証・改善候補をまとめる。 保留中の対応範囲は各仕様書を正とし、運用はドキュメント運用ルールに従う。 項目の識別子は移動元のレイヤー名と番号を引き継ぐ。

PHY

PHY-P-2 KLE JSON取り込み時の照合基準

• 関連仕様: PHYレイヤー「KLE JSONの取り込み」
• 未決事項: 形状の許容誤差、ラベルの扱い、複数候補がある場合の決め方。
• 保留できる理由: 新規PHYとしての読み込みは、既存ノードとの照合なしで実装できる。
• 再開条件: 既存PHYへのKLE JSONの照合・更新に着手するとき。
• 完了条件: 照合規則と曖昧な候補の扱いを決め、KLE本家でキーの移動・追加・削除をしたJSONを取り込み、 意図したIDに対応づき、他レイヤーの参照を誤って付け替えないことを確認する。

PHY-P-6 キーキャップの見た目情報を持つ層

• 関連仕様: PHYレイヤー「KLE JSONの取り込み」、JSON Schemaの kleCompatibility
• 未決事項: キーキャップの見た目編集をBeyond KLEの範囲に含めるか、正式にはどの層で情報を持つか。 対象はキー単位の c, t, p, a, f系, l, n と、退避する sm, sb, st、ファイル単位の switchMount, switchBrand, switchType, backcolor, radii, background, css。
• 保留できる理由: 現行Schemaの kleCompatibility で、正式な所属層や編集機能を決めずに保持・書き戻しができる。
• 再開条件: 見た目の編集機能、または退避先から正式な所属層への移行を検討するとき。
• 完了条件: 扱う範囲と所属層をユーザーが決め、既存の退避情報を失わない保持・移行方法を定める。

PHY-P-8 ラベルをMAPに適用するか

• 関連仕様: PHYレイヤー「ラベル」
• 未決事項: ラベルをMAPへ適用するか。機械的に適用先を判断できるかは未確認で、候補を自動適用してユーザーが不要なものを落とす案もある。
• 保留できる理由: ラベルは参考情報として保持でき、MAPへの自動適用なしで各レイヤーを扱える。
• 再開条件: MAPのキーコード割り当てを補助する機能を検討するとき。
• 完了条件: 適用の要否と、適用する場合の候補提示・ユーザーによる取捨の流れをユーザーが決める。

PHY-P-12 部品の表裏を描画でどう扱うか

• 関連仕様: PHYレイヤー「部品ノード」
• 未決事項: エディタ上で表裏の描き分けが必要か。必要なら @ 始まりの予約グループ名だけで足りるか。
• 保留できる理由: 表裏を描き分けなくても配置は編集でき、実装面はPCB設計ツール側で決められる。
• 再開条件: 部品ノードと予約グループ名による描画を試作し、表示を評価するとき。
• 完了条件: 描き分けの要否を確認し、必要なら実装面の指定と混同しない表示方法を決める。

PHY-P-13 reframeと通常の移動・回転をエディタ上でどう区別するか

• 関連仕様: PHYレイヤー「クラスターの組み替え」
• 未決事項: reframeの操作系。クラスターへのフォーカス状態に紐づけて原点ハンドルと通常のハンドルを分ける案と、専用モードを設ける案がある。
• 保留できる理由: データ変換は定義済みで、通常の移動・回転とは別の明示的な操作として試作できる。
• 再開条件: クラスター編集を試作し、操作の分かりやすさを評価するとき。
• 完了条件: 配下が追随する操作と絶対配置を保つ操作を区別できる操作系をユーザーが決める。

PHY-P-14 クラスター原点の吸着先

• 関連仕様: PHYレイヤー「クラスターの組み替え」
• 未決事項: 吸着が必要か。候補はキーのローカル原点(左上角)・キー中心・境界矩形の角と中心で、相対グリッドとは別の機構になる。
• 保留できる理由: 数値入力だけで原点移動は成立する。
• 再開条件: 原点移動を試作し、操作性を評価するとき。
• 完了条件: 吸着の要否と、必要な場合の候補を決める。

ELC

ELC-P-1 光学スイッチの端子構成

• 関連仕様: ELCレイヤー「キーの端子」
• 未決事項: 発光側と受光側が独立した端子を持つのか、接点と同じ2端子として扱えるのか。
• 保留できる理由: 光学スイッチを対応範囲から外したまま、接点・アナログの配線を扱える。
• 再開条件: 光学スイッチの配線に対応するとき。
• 完了条件: 実在のPCBの回路図で端子数と配線の形を確認し、必要な端子構成を定める。

ELC-P-2 複数マルチプレクサ構成の作り

• 関連仕様: ELCレイヤー「ピンとピン提供者」
• 未決事項: 選択ピンを共有して共通ピンを分ける構成と、enableで切り替える構成の実配線・制御方法。 どちらが一般的かは未確認。前者は複数providerの select に同じ PinRef を書く形で表現できる。
• 保留できる理由: providerごとの参照を保存する形は維持でき、複数muxの走査出力を検証済みの構成に限定できる。
• 再開条件: 複数muxを使う構成のファームウェア出力に対応するとき。
• 完了条件: 実在のキーボードの配線でピン共有とenableの使い方を確認し、現行モデルでの表現と必要な制御を確かめる。

ELC-P-3 方式ごとの走査設定の確認

• 関連仕様: ELCレイヤー「配線トポロジを区分として持たない」
• 未決事項: 各方式で出力器が決められる走査方法と、ユーザーの追加指定が必要になる範囲。 接点マトリクスではダイオードの向き、directでは電源レールの参照から役割を判断できる範囲を確認する。
• 保留できる理由: 走査方向の決定・追加指定の責任は出力器側と決まり、ELCの配線保存はそのまま進められる。
• 再開条件: 各方式のファームウェア出力に着手するとき。
• 完了条件: 対象方式の配線と整合する走査方法を確認し、必要な出力設定と対応範囲を定める。 全方式で走査手順が一意に決まることの証明は求めない。

ELC-P-4 GPIOに直結したLEDの表し方

• 関連仕様: ELCレイヤー「LEDの識別番号」
• 未決事項: インジケータなど、チェーンに入らずマイコンのピンで直接点灯するLEDをELCにどう持つか。 LEDの部品ノードとピンの対応だけで足りるか、極性(ピン側がアノードかカソードか)も要るかを含む。
• 保留できる理由: チェーン方式(WS2812系)のLEDとキーの配線は、直結LEDと独立に扱える。
• 再開条件: インジケータLEDの出力に対応するとき、またはLED配線の編集画面の仕様を作るとき。
• 完了条件: 実在の基板で直結LEDの配線を確認し、ELCでの表し方と、ファームウェア出力に必要な情報を定める。

IDX

IDX-P-1 単一のorderから既存コミュニティレイアウトの並びを得られる範囲

• 関連仕様: IDXレイヤー「レイアウトバリアント」
• 未決事項: 採用済みの方式で既存コミュニティレイアウトの要求順を再現できる範囲の実測。 同じPHYキーIDを使う共通キー同士の要求順がレイアウト間で逆転する場合は、単一の order からの取捨では表せないが、その実例の有無は未確認。
• 保留できる理由: 全バリアントのキーを別々の要素として並べ、選択後に番号を詰める仕様は決定済み。 既存レイアウト全般との互換性を前提にせず実装できる。
• 再開条件: 既存コミュニティレイアウトとの互換出力を検証するとき。
• 完了条件: 実データのキーを共通キーとバリアント別のPHYキーに対応づけ、全体の order から各レイアウトの要求順を取捨で再現できるか確認する。 再現できないものが残る場合は、対応範囲と扱いを決める。

MAP

MAP-P-4 ON/OFF以外の入力への割り当て

• 関連仕様: MAPレイヤー「MAPデータと他レイヤーの関係」、PHYレイヤー「部品ノード」
• 未決事項: ロータリーエンコーダの回転のように、ON/OFFのキーではない入力へ割り当てる方法。 MAPはPHYのキーIDを参照するが、エンコーダはPHYで部品ノードとして置かれる。 参照先の種類、入力ごとの割り当て先(回転方向など)、VIAでの読み書きの対象にするかが未定。 アナログ値の解釈の所属は全体方針のP-1で扱い、この項目とは分ける。
• 保留できる理由: キーへの割り当てと実機との読み書きは、キー以外の入力を扱わなくても実装できる。
• 再開条件: エンコーダ等を載せたキーボードの割り当てをMAPで扱うとき。
• 完了条件: 対象とする入力の種類と、MAPからの参照方法・保存形式をユーザーが決め、VIAで読み書きする場合は必要なコマンドを確認する。

MAP-P-5 キーコードを表示するOS配列

• 関連仕様: MAPレイヤー「持たないもの」、HSTレイヤー
• 未決事項: MAPエディタがキーコードをどのOS配列の文字で表示するか。HSTのどのプロファイルを使うか。 少なくともUS/JISの切り替えは欲しい。利用者が増えれば他言語への対応も求められる。
• 保留できる理由: キーコードの割り当てと実機との読み書きは、表示に使うOS配列と独立して実装できる。
• 再開条件: MAPエディタの表示を実装するとき、またはHSTのP-2を決めるとき。
• 完了条件: 表示に使うHSTプロファイルの指定方法と置き場所をユーザーが決める。

MAP-P-6 QMKのdevelopブランチ・Community Modulesへの対応

• 関連仕様: MAPレイヤー「DynamicとStatic」
• 未決事項: 当面非対応としたdevelopブランチの機能とCommunity Modules(VIAモジュール以外)を、DynamicとStaticの対象に含めるか。 含める場合、developブランチのコミットの指定方法と、UIでの対応バージョンの示し方。
• 保留できる理由: QMK本家masterの公式機能だけで、Dynamicの読み書きとStaticの生成を実装できる。
• 再開条件: masterの機能だけでは足りない動作や設定が必要になったとき。 または、VIAのモジュール移行(qmk_firmware#26315)がdevelopに入ったとき。 VIAモジュールへの対応はmasterに入る前に済ませる(MAPレイヤー「DynamicとStatic」)。
• 完了条件: 対象に含める範囲と、対応バージョンの管理方法をユーザーが決める。

MAP-P-7 再ビルド時に実機の調整を失わないワークフロー

• 関連仕様: MAPレイヤー「DynamicとStatic」、MAPのP-3
• 未決事項: QMK本家のVIAは、実機に保存したVIAのデータ(キーマップ・マクロ・layout option)を、ビルド日時をもとにした値で検証し、一致しなければ初期化する(quantum/via.c の via_eeprom_is_valid()。実機では未検証)。 再ビルドしたファームウェアを書き込む前に、実機の調整をプロジェクトへ読み出す手順を、ワークフローでどう保証するか。警告、読み出しの強制、Firmware Generatorとの連携などが候補。
• 保留できる理由: 実機からの読み出しとStaticの初期キーマップへの反映はすでに仕様にある。手作業の手順で運用できる。
• 再開条件: Firmware Generatorでの書き込みや、プロジェクトと実機の状態管理(P-3)を設計するとき。
• 完了条件: 再ビルドの前に実機の調整を取り込めるワークフローをユーザーが決め、書き込み後にVIAのデータが初期化されることを実機で確認する。

MAP-P-8 QMK以外のファームウェアでのキーコード表記

• 関連仕様: MAPレイヤー「MAPデータと他レイヤーの関係」、全体方針のFirmware Generator
• 未決事項: MAPはQMKのキーコード表記を基本とする。KMK等のQMK以外のファームウェアへ出力するとき、QMK表記から変換するか、共通の表記を別に設けるか。
• 保留できる理由: 当面の対象ファームウェアはQMKだけで、QMK表記のまま保存・読み書き・出力できる。
• 再開条件: QMK以外のファームウェアへの出力や、実機との通信に着手するとき。
• 完了条件: QMK以外のファームウェアで使うキーコードの表現と、QMK表記との対応方法をユーザーが決める。

MAP-P-9 Cコードの生成とユーザーのCの組み込み

• 関連仕様: MAPレイヤー「MAPデータと他レイヤーの関係」「DynamicとStatic」、全体方針のFirmware Generator
• 未決事項: QMKのkeymap.jsonでは、タップダンス・コンボ・キーオーバーライドや、キーごとの設定(get_tapping_term 等のコールバック)を表現できない。 JSONを正本にしたままこれらをCとして生成する方法と、ユーザーが用意したC/hで一部を上書きする方法。 QMKのコールバックは1つの関数として定義するため、生成したCとユーザーのCが同じ関数を定義するとビルドできない。候補:
  • 生成した関数の先頭でユーザー用のフックを呼び、フックが処理しなかった場合はJSONの値を使う(有力)
  • ユーザーが引き受ける関数をJSONまたはhのプロトタイプで宣言し、Generatorはその関数を出力しない ACTION_TAP_DANCE_FN* やリーダーキーのように、本質的にCで書く動作をJSONから参照する方法も含む。 MAPの「キーマップ固有のコードには原則として対応しない」との関係も整理する。
• 保留できる理由: レイヤー別の割り当てとVIAでの読み書きは、keymap.jsonで表現できる範囲だけで実装できる。
• 再開条件: Firmware Generatorでタップダンス・コンボ・キーごとの設定等を出力するとき、またはP-1で動作定義とキーごとの設定の保存形式を決めるとき。
• 完了条件: 生成するCの構成と、ユーザーのC/hを組み込む方法をユーザーが決め、両方を含む構成でQMKのビルドが通ることを確認する。