refactor(accent): split into api/accent/ package (no behavior change)

[torrid-fish]

目的

把 api/accent_marker.py (493L) + api/furigana_marker.py (152L) 兩個 monolithic 檔案拆成 api/accent/ package，並加上 README.md 把 marking pipeline + accent_marking_type 約定寫清楚。

純結構性 refactor，正常路徑 JSON 回應與 refactor 前 byte-identical。

Asterisk on "0 behavior change"：為了配合 Copilot review 反饋，api/accent/furigana.py 在 response.json() 外多包了一層 try/except ValueError，把「Yahoo 回傳 invalid JSON」這條冷門 error path 從 unhandled exception 改成回 FuriganaResponse(status=500, error=...) envelope。pre-refactor 的 furigana_marker.py 在這條 path 上會直接 raise。其它所有 endpoint behavior 完全 byte-identical。

Base = main，跟 PR #46 (feat/docker-compose) 是 sibling，merge 順序無關。下游 #47 (feat/reading-overrides) 與 #51 (spike/local-unidic) merge 之後再 rebase。

Layout

api/accent/
├── __init__.py     # re-exports accent_router, furigana_router (供 main.py 使用)
├── README.md       # marking pipeline + AccentInfo semantics
├── models.py       # Pydantic schemas (兩 endpoint 共用)
├── furigana.py     # Yahoo Furigana HTTP client (data layer)
├── ojad.py         # OJAD scrape (HTTP + BeautifulSoup parse)
├── align.py        # align_accent + 相關 constants & helpers
├── pipeline.py     # MarkAccent orchestrator (從 mark_accent handler 抽出)
└── routes.py       # FastAPI routers + thin endpoint handlers

依賴方向（無循環）：

flowchart LR
  routes[routes.py]
  pipeline[pipeline.py]
  align[align.py]
  furigana[furigana.py]
  ojad[ojad.py]
  models[models.py]

  routes --> pipeline
  routes --> furigana
  pipeline --> align
  pipeline --> furigana
  pipeline --> ojad
  align -.-> models
  furigana -.-> models
  ojad -.-> models
  pipeline -.-> models
  routes -.-> models

Loading

main.py 變更

- from api import accent_marker, dict_query, furigana_marker, sentence_query, usage_query
+ from api import dict_query, sentence_query, usage_query
+ from api.accent import accent_router, furigana_router

  app.include_router(
-     accent_marker.router, prefix=\"/api\", dependencies=[Depends(get_api_key)]
+     accent_router, prefix=\"/api\", dependencies=[Depends(get_api_key)]
  )
  app.include_router(
-     furigana_marker.router, prefix=\"/api\", dependencies=[Depends(get_api_key)]
+     furigana_router, prefix=\"/api\", dependencies=[Depends(get_api_key)]
  )

剩下的 main.py 改動是 0 — auth、middleware、其他 router 都原封不動。跟 PR #46 在 main.py 的改動（移除 auth/security 區塊）在不同行，rebase 無衝突。

命名說明

兩個 endpoint 共用 {status, result, error} envelope shape，只是 result element type 不同。為了 FastAPI response_model typing 明確，仍保留兩個 Response class：

• FuriganaResponse (result: list[WordResult] | None)
• AccentResponse (result: list[WordAccentResult] | None)

JSON 輸出 byte-identical with 原本兩個 module 各自定義的 `Response` class。

README 內容

包含：

• 兩個 endpoint 的用途
• Mermaid data flow diagram（text → Yahoo + OJAD → align → output）
• WordAccentResult / AccentInfo 欄位與 accent_marking_type 0/1/2 對應 OJAD CSS class 的對照表
• Accent shape 速查（平板 / 頭高 / 中高 / 尾高 偵測條件）
• 各檔案責任分工 + 依賴方向
• alignment 演算法概述（含 numeric / punct / kana 分支）
• 擴充指引（之後 feat(accent): reading override layer + streaming MarkAccent endpoint #47 的 override layer、feat(accent): local UniDic + POS-driven patches (closes #48, #50) #51 的 POS-driven patches 都會在此補章節）

Verification

uv run ruff check api/accent/ main.py        # ✓ All checks passed
uv run mypy api/accent/ main.py              # ✓ no issues in 8 files

# byte-identical output check (input: 「3月5日(土)に学校で会いましょう。今日は寒いですね。」)
diff baseline_accent.json   refactor_accent.json    # ✓ no diff
diff baseline_furigana.json refactor_furigana.json  # ✓ no diff

下游 PR 影響

PR	行動
#46 (feat/docker-compose)	對 post-refactor main rebase。main.py 改動在不同區塊，預期 auto-merge
#47 (feat/reading-overrides)	重做：regex override 層的改動 map 到 api/accent/<新檔>，新增 reading_overrides.py 放進 package
#51 (spike/local-unidic)	重做：fugashi swap + POS patches + 一系列 polish 改動 map 到新 layout；postprocess passes 拆到新檔 postprocess.py

Out of scope

• 改 endpoint API contract / response schema
• 重寫 align_accent 內部演算法（後續 PR 會升級為 Needleman-Wunsch DP）
• 加 unit test (main 沒有 test 基礎，留給後續)
• 把舊 module 留成 backward-compat shim（main.py 是唯一 Python consumer，直接更新）

🤖 Generated with Claude Code

[wade00754]

LGTM. But I have identified some additional issues in align.py and will review whether they still exist in future PRs.

[torrid-fish]

@copilot resolve the merge conflicts in this pull request

[Copilot]

@copilot resolve the merge conflicts in this pull request

Resolved by merging origin/main and fixing the main.py conflict to keep the api.accent router refactor while aligning with current main behavior. Included in commit 0a403cd.

[github-actions]

🛡️ PR Quality Check Summary

✅ PR Title: Passed (Length: 69/75, Format: OK). refactor(accent): split into api/accent/ package (no behavior change)
✅ Branch Name: Follows naming convention (refactor/accent-package)
✅ Commit Messages: All 5 commit(s) passed (Length, Format, Case)
✅ Conflicts: No merge conflict markers found
✅ Python Quality: All checks passed.

---

🎉 All checks passed!