refactor(ai): OCR sidecar canonical naming cleanup — typhoon→np-dms, remove hardcoded keys, asyncio.to_thread, ADR-040/041

2026-06-20 16:37:04 +07:00
parent d418d791a4
commit a80ebef285
70 changed files with 5762 additions and 452 deletions
@@ -0,0 +1,59 @@
+# Session — 2026-06-20 (OCR Sidecar Refactor Speckit Workflow)
+
+## Summary
+
+Executed complete `/speckit.prepare` workflow for OCR Sidecar Refactor (ADR-040). Generated spec.md, plan.md, research.md, data-model.md, contracts/sidecar-api.md, quickstart.md, and tasks.md. Performed consistency analysis and fixed all identified issues (1 CRITICAL, 2 MEDIUM, 2 LOW).
+
+## ปัญหาที่พบ (Root Cause)
+
+None. This was a planning/specification workflow, not a bug fix session.
+
+## การแก้ไข (Fix)
+
+N/A - Specification generation workflow.
+
+## สิ่งที่ทำใน Session
+
+| ไฟล์ | การเปลี่ยนแปลง |
+| ----- | ------------------ |
+| `specs/100-Infrastructures/140-ocr-sidecar-refactor/spec.md` | Created feature specification with 5 user stories, 20 functional requirements, 8 success criteria |
+| `specs/100-Infrastructures/140-ocr-sidecar-refactor/plan.md` | Created implementation plan with technical context, constitution check, and phase structure |
+| `specs/100-Infrastructures/140-ocr-sidecar-refactor/research.md` | Created technical decisions documentation from ADR-040 |
+| `specs/100-Infrastructures/140-ocr-sidecar-refactor/data-model.md` | Created data contracts and entity relationships |
+| `specs/100-Infrastructures/140-ocr-sidecar-refactor/contracts/sidecar-api.md` | Created sidecar API specification |
+| `specs/100-Infrastructures/140-ocr-sidecar-refactor/quickstart.md` | Created deployment and testing guide |
+| `specs/100-Infrastructures/140-ocr-sidecar-refactor/tasks.md` | Created 63 implementation tasks organized by user story |
+| `specs/100-Infrastructures/140-ocr-sidecar-refactor/checklists/requirements.md` | Created specification quality validation checklist |
+
+## Analysis & Fixes
+
+| Issue | Severity | Fix |
+| ----- | -------- | --- |
+| C1 - Constitution Check ADR-019 | CRITICAL | Updated plan.md to acknowledge ADR-019 applies to backend services (parameter resolution in OcrService/SandboxOcrEngineService) |
+| U1 - Symlink resolution edge case | MEDIUM | Updated spec.md edge case to reference test T007 |
+| U2 - Ollama unavailability edge case | MEDIUM | Updated spec.md edge case to note handled by FastAPI exception handling per ADR-007 |
+| I1 - IP address inconsistency | LOW | Standardized IP to 192.168.10.100 in spec.md and plan.md |
+| I2 - Task description clarity | LOW | Changed tasks T022/T023 from "Verify" to "Retain" |
+
+## กฎที่ Lock แล้ว
+
+- OCR sidecar is a pure compute worker (no DB/storage access per ADR-023/023A)
+- Backend services handle all parameter governance (ai_execution_profiles, ai_prompts)
+- Adaptive OCR Residency must be preserved (vram_monitor.py, residency_policy.py retained)
+- CPU fallback for BGE-M3/FlagReranker must be preserved
+- Phase 2 (X-API-Key removal) is BLOCKED until ADR-041 consolidation completes
+
+## Verification
+
+- [x] All 5 user stories have acceptance criteria
+- [x] All 20 functional requirements have task coverage (100%)
+- [x] Constitution check passes with proper ADR-019 acknowledgment
+- [x] No ambiguities or duplications found
+- [x] All 5 analysis issues fixed
+- [x] Ready for `/speckit-implement`
+
+## Next Steps
+
+- Execute `/speckit-implement` to begin implementation
+- Start with MVP (User Stories 1-2: Security Hardening + GPU Resource Management)
+- User Story 5 (Network Isolation Auth Phase 2) remains BLOCKED until ADR-041 consolidation