# CHORD_LIBRARY.md

## PM-APP-13 和弦查询消费者契约

范围固定为标准调弦六弦、0–12品、78位置。和弦资料来自固定 `chords-db` 提交 `df06fa7b425cf5fd29485ff6591236b3557e3fac`，本地保存于 `data/chords-db/`；`source.json` 保留上游提交、许可证和抓取身份，`verified.js` 是冻结的通过记录。96组（12根音×8公式）均有候选，403把位中345接纳、58拒绝；拒绝原因见 `admission-report.json`。

`src/chord-validation.js` 是消费者准入层：检查0–12品、正品位换算 `actualFret = relative + baseFret - 1`、最大跨度、手指/横按、缺音/外音及逐弦MIDI。它是消费者可操作性门槛，不等于人人可按或Owner听感验收。

`src/chord-library.js` 提供：

- `parseChordQuery(query)`：接受 `C`、`Cm`、`CM7`、降号根音和组成音转位如 `C/G`；不支持的后缀、非组成音slash会抛出明确错误。
- `listChordVoicings(input)` / `getChordView(input)`：只返回已核把位；无结果返回空或 `null`，不会截半或临时造指法。
- `chordBoardModel(view)`：复用冻结引擎指板模型与消费者布局。
- `exportChord(input, format)`：`json`、`svg`、`diagram`。JSON固定 `capo: 0`、`stringOrder: "6-to-1"`，包含逐弦品位、手指、横按、MIDI、音名、级数、最低音与转位。

UI 的根音、类型、把位选择和逐弦表均来自上述数据；音频 `playChord()` 先整组下载/解码，全部成功才发声，失败为零声部并保留重试。可见音源仍为Owner批准的FreePats FSS钢弦录音。