# 03 技術規格（聽力練習模式）

> 給實作者（本機的我，或實驗室電腦上的 AI）。行為以 `02-contract.locked.md` 為準；本檔只說「怎麼做」。
> 裁決順序（主理人 2026-10-04）：①長期目標 ②使用者方便持續用下去。合約沒涵蓋的決策照這兩條判斷，並記進 04-implementation.md。

## 1. 資料夾與檔案

新系統放在 `C:\D槽\英文學習資料\app\`，**不改動** `toeic-drill-01.html`（主理人仍在用它練習）。

```
app/
  index.html          頁面骨架（只放結構）
  app.css             樣式
  js/book.js          ← 由 tools/extract_book.py 從 toeic-drill-01.html 產生：window.BOOK = {id, title, TITLE, W, Q}
  js/plan.js          純邏輯：一次學習、新學順序、複習排程（瀏覽器與 node 都能載入，不碰 DOM）
  js/store.js         進度存取：本機模式 / server 模式、舊進度匯入、匯出匯入、同步與衝突
  js/ui.js            畫面：這一次的三區、題目卡、左側面板／手機底部條、方法說明、耳朵缺口清單
  audio/book1/        錄音（toeic-drill-01-audio 的複本，654 檔）
  server.py           Python 標準函式庫寫的小 server：送靜態檔＋進度 API＋密碼
  config.example.json server 設定範例（密碼、port、資料庫路徑）
  tools/extract_book.py  從舊頁抽出題目資料
  tests/              自動測試（見第 7 節）
  guide.html          學習方法手冊子頁（正本；docs/reports/ 那份是 10/4 交付時的存檔）
  DEPLOY.md           實驗室電腦部署說明
```

- 不用框架、不用建置工具；JS 用一般 `<script>`（不用 ES module，才能在 `file://` 直接開）。
- 每個 js 檔用一個全域命名空間：`window.Plan`、`window.Store`、`window.UI`。`plan.js` 另外在 node 下 `module.exports = Plan`。

## 2. 進度資料：事件流水帳（2026-10-04 改版，原因見 04-implementation.md）

- **每個動作記一筆事件**：`{id, dev, n, t, type, ...欄位}`。`dev`＝這次開頁的代號（裝置代號＋隨機分頁碼），`n`＝這頁的流水號，`t`＝時間（毫秒，同一頁內嚴格遞增）。
- **進度＝重放所有事件**：`Plan.replay(events, book)`。先依 id 去重，再依 (t, dev, n) 排序，從空白進度逐筆套用（`Plan.apply`）。任何裝置、任何到達順序，重放結果都一樣。
- 事件種類：`legacy`（舊頁紀錄）、`reset`（匯入：整份換成檔案內容）、`answer {q,k,learn}`、`learn {q}`、`play {q}`、`seen {q,lv}`、`star {q,v}`、`mark {q,i}`、`remark {q,i}`（複習中「又沒聽到」）、`review {q,result}`、`cont`、`finish`、`tick {ms}`、`touch`、`pref {key,value}`、`clear`。
- 重放後的進度物件（給畫面讀）：
```js
{
  schema: 3, legacy, prefs: { speed, methodSeen },
  sessionsCompleted, session: { started, startedAt, activeMs, reviewPlan, reviewSnap, reviewResult, reviewMarks, newPlan, contDone },
  ans, seen, star, learned, marks, review, mastered, gaps, plays, heardFirst   // 欄位清單在 Plan.MAP_FIELDS（唯一一處）
}
```
- 切字規則只在 `Plan.sentenceParts`／`Plan.tokenSpans`（畫面與排程共用）。marks 存的是字的索引。

## 3. 一次學習與排程規則（plan.js，純函式）

- 新學順序：`6-1 … 10-10`，接著 `1-1 … 5-10`（停車場 P2 推薦值；改設定陣列即可）。
- **開新的一次**（`startPlan(state)`）：
  - `current = sessionsCompleted + 1`
  - reviewPlan：`review` 裡 `due <= current` 的句子，依 due、再依題號排序，取前 10；超過 10 句時改成挑「點過的字最多」的 10 句（D6），挑出來的仍照到期先後排（合約 13）。
  - newPlan：找順序上第一個「沒有 learned」的題，取**該組**裡所有還沒 learned 的題（最多 10）。全部學完 → 空陣列。
- 一題「學完」＝在這次作答了文法題（或該題早已作答，使用者按「這題用新方法練完了」）。學完時：
  - `learned[q] = current`
  - 若 `marks[q]` 非空 → `review[q] = {stage:0, due: current+1}`。
- 複習按鈕：
  - 間隔 `INTERVALS = [1, 4]`（D6，2026-10-05 授權代決）：連續 2 次「都聽出來」就算學會。
  - 「這次都聽出來了」：`stage+1`；stage 變成 2 → 移到 `mastered`、刪除 review；否則 `due = current + 4`。
    這一次在這句點了沒聽出來的字時，這個按鈕不能按（就算從別處送來，也一律算「還是有沒聽出來的」）。
  - 「還是有沒聽出來的」：`stage = 0`，`due = current + 1`；這次點的字另外記在 `session.reviewMarks`。
  - 今天的複習句不論在複習卡或「看全部題目」點字，都走 `clickInReview`：點了字＝自動算「還是有沒聽出來的」，原本的答案記在 `session.reviewAuto`；這次點的字全部取消時退回原本的答案（誤觸可以復原）。使用者自己按的按鈕會清掉這個記錄。
- 三區完成判定：複習＝reviewPlan 每句都有 reviewResult（或 reviewPlan 空）；新學＝newPlan 全部 learned（或空）；連續聽＝contDone。
- 「這次完成」：`sessionsCompleted += 1`，session 重設為未開始；下次載入時 `startPlan`。
- 不看日曆：所有計算只用次數。

## 4. 畫面（ui.js）

- 預設 view＝session（這一次的三區）；「看全部題目」切到 all，呈現與舊頁相同的 10 組（含統計、篩選、單字表、字族、翻譯、詳解、句子拆解、各種播放、語速）。
- 題目卡沿用舊頁的版面與行為；新增：
  - 播放鍵旁一行「看的時機」提示（文字照 02-preview.md 6-3）。
  - 句子每個字可點（切換 marks），被點的字變色；複習時上次點過的字淡色顯示。
  - 翻譯標題旁的提示字。
- 左側面板（≥1080px）：這一次的進度、已練分鐘、語速、耳朵缺口清單、匯出／匯入、同步狀態、重看方法。
- 手機（<1080px）：底部一條（進度摘要＋☰），點 ☰ 展開完整面板（由下往上的抽屜）。
- 已練分鐘：`document.visibilityState === "visible"` 且這次已開始時，每秒累加，存進 session.activeMs。
- 方法說明卡：`prefs.methodSeen` 為 false 時展開在最上方；「我懂了」→ true；「📖 重看方法」重新展開。
- 所有文案照 `02-preview.md` 第 6 節，不自行改寫；需要新增文案時記入 04-implementation.md。

## 5. 進度存取與同步（store.js）

- **模式判定**：載入時 `GET api/events?after=0`。200 → server 模式；401 → 問密碼（存在這台裝置）；使用者選「先不用」或 404（沒有 API，例如直接開檔）→ 本機模式；其他（連不上、5xx、回的不是 JSON）→ **離線開始**：用這台裝置上次的事件繼續，連上後補送（合約 35）。
- 本機快取（2026-10-05 第 2 關 r5 後改版）：
  - 事件存在 **IndexedDB**（資料庫 `tq-app`、表 `events`、主鍵 `id`）。每做一個動作只寫那一筆；空間是 localStorage 的上百倍。
  - 每筆可帶 `_a`＝確認它的 server 資料庫 epoch，只存在本機、不會送出。
  - IndexedDB 的寫入要等一下才完成，頁面在那之前關掉會被取消。所以寫入前先在 localStorage 的 `tq-app-pending-v5` 記一張「還沒寫完」的便條，寫完就撕掉；下次開頁發現便條就補寫。
  - 開不了 IndexedDB（3 秒沒回應、出錯、測試模擬器）→ 退回舊做法：全部事件以一段文字存在 localStorage 的 `tq-app-events-v5`。
  - 舊版存在 `tq-app-events-v5` 的事件，第一次用 IndexedDB 開頁時搬過去、再刪掉。
  - 其他（都很小，仍在 localStorage）：`tq-app-seq-v5`、`tq-app-epoch-v5`、`tq-app-complete-v5`（快取是完整流水帳時才是 1，才能開頁只拿新事件）、`tq-app-device`、`tq-app-token`。
- 「還沒送出」＝沒有被目前 epoch 確認的事件。本機模式、離線、其他分頁記的事件，都靠這個規則在連上時送出。
- 做一個動作：`Store.record(type, fields)` → 記事件、套用到畫面、存快取、排入送出（400ms 後 POST）。畫面立刻顯示「儲存中…」。
- 送出失敗 → 「連不上 server」，每 15 秒與 `online` 事件時重試。
- 拿別台的進度：每 30 秒（頁面看得到時）與切回頁面時 `GET ?after=上次流水號`；有新事件就重放並顯示「已載入另一台裝置的新進度」（保持捲動位置）。
- server 被還原（epoch 變了）→ 舊的確認標記全部不算，從頭拿完整清單，把 server 沒有的事件全部重送。
- 資料庫檔被直接蓋回（epoch 沒變，但 server 的流水號比這台記得的小）→ 同樣處理；先撕掉所有確認標記並覆寫本機副本。
- 同一瀏覽器另一個分頁記了事件 → IndexedDB 時用 `BroadcastChannel("tq-app-events")` 把那幾筆傳過來；localStorage 時用 `storage` 事件（存檔前也先和儲存區合併）。收到後合併、重放（所有模式）。
- 每一次學習的第一個動作前，自動記一筆 `plan` 事件（固定複習／新學清單與快照）；兩台同時開始時兩邊清單合併。
- 重放時單筆事件出錯只跳過並計數（`state.skipped`），不讓整份進度壞掉。題號不在這本書裡的事件整筆不理（不算出錯）。
- 晚到的複習答案（那一次已經結束）只在「那句的排程從快照到現在都沒變」時才算，避免很舊的快取蓋掉比較新的排程。
- 匯出：`{format:"toeic-events-v5", events, state}`（不含 `_a`）。匯入：任何格式（本程式匯出檔、schema 3、舊頁紀錄）都先算出進度，再記一筆 `reset` 事件（合約 33「換成檔案內容」）。
- 舊頁紀錄（`tq1v2`）：第一次使用、這台還沒有任何事件時，記一筆 `legacy` 事件（合約 32）。

## 6. server.py（Python 3.10+，只用標準函式庫）

- `ThreadingHTTPServer`；根目錄＝app/，靜態檔白名單（index.html、guide.html、app.css、js/、audio/）；支援 Range（iPhone Safari 播 mp3 需要）。
- SQLite：`events(seq INTEGER PRIMARY KEY AUTOINCREMENT, id TEXT UNIQUE, data TEXT, received_at TEXT)`。**只追加、永不修改或刪除**；同一個 id 再送一次會被忽略。這張表本身就是完整歷史。
- API（都要 `Authorization: Bearer <密碼>`；密碼在 config.json 存 sha256，比對用 `hmac.compare_digest`）：
  - `GET /api/events?after=N` → `{lastSeq, epoch, events:[...每筆含 seq]}`（先查 lastSeq，再只拿到那一號為止，兩次查詢中間的寫入不會被跳過）。數字參數超過 18 位一律回 400。
  - `POST /api/events` body `{events:[{id,...}]}`（最多 5000 筆、2MB）→ `{lastSeq, epoch}`
- `epoch`：資料庫的身分證（meta 表），建立時隨機產生；`python server.py --restore FILE` 還原備份時會換新，裝置因此知道要重送。
- 對外連線、HTTPS、防火牆見 DEPLOY.md（推薦 Tailscale；密碼必須走加密連線）。

## 7. 測試（第 1 關機器關）

- `tests/plan.test.js`：node 內建 `node:test`，測排程規則（合約 6–17、20、21）。
- `tests/server_test.py`：python `unittest`，起一個臨時 server 測事件 API、密碼、去重、永不覆蓋、靜態檔白名單、Range（合約 31、34、35、37）。
- `tests/e2e.js`：puppeteer-core ＋本機 Chrome，起 server、逐條跑畫面行為（合約 1–5、10–14、18–30、33、35、36、38、39），截圖存 `docs/work/2026-10-04-listening-mode/evidence/`。
- `tests/sync.test.js`＋`tests/sim.js`：在 node 裡同時跑好幾份真正的 plan.js＋store.js（假的 server、儲存區、計時器），測多台裝置、離線、空間不足、server 還原、兩個分頁、舊格式匯入、隨機操作後兩台一致。模擬器沒有 IndexedDB，所以這裡測的是 localStorage 那條路；IndexedDB 那條路由 e2e 測（r5-idb、r5-tabs、r5-close、r5-moved-up）。
- 執行（每個檔分開跑）：`node --test app/tests/plan.test.js`、`node --test app/tests/sync.test.js`、`python app/tests/server_test.py`、`node app/tests/e2e.js`。