{"openapi":"3.1.0","info":{"title":"居家護理 AI 輔助系統","description":"\n護理語音經 **STT → 醫療名詞糾錯 → LLM 結構化** 產出護理紀錄 JSON。\n\n**互動文件**\n- [Swagger UI](/docs) — 線上試打 API\n- [ReDoc](/redoc) — 閱讀型文件\n- [OpenAPI JSON](/openapi.json) — 機器可讀規格\n\n**靜態頁面**\n- [API 文檔（中文）](/api-reference)\n- [API 測試頁](/api-test)\n- [糾錯字典管理](/mapping-editor)\n","version":"0.1.0"},"paths":{"/api/v1/nursing-record/analyze":{"post":{"tags":["nursing"],"summary":"一鍵分析護理語音（STT → 糾錯 → 結構化）","description":"**Content-Type:** `multipart/form-data`\n\n**流程：** 音檔 → Gemini STT → 醫療字典糾錯 → LLM 結構化 JSON\n\n**可選參數**\n- `stt_model`：指定 STT 模型（如 `gemini-2.5-flash`）\n- `llm_model`：指定 LLM 模型（如 `gemma-4-26b-a4b-it`）\n\n**回傳 `_meta`** 含各步驟所用模型與耗時（毫秒）","operationId":"analyze_nursing_record_api_v1_nursing_record_analyze_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_analyze_nursing_record_api_v1_nursing_record_analyze_post"}}},"required":true},"responses":{"200":{"description":"結構化護理紀錄 + 各步驟效能資訊","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Analyze Nursing Record Api V1 Nursing Record Analyze Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/stt/transcribe":{"post":{"tags":["nursing"],"summary":"步驟一：語音轉文字（STT）","description":"僅執行語音轉文字。回傳：\n- `transcript`：逐字稿\n- `model_used`：實際使用的模型\n- `elapsed_ms`：耗時毫秒\n- `segments`：多檔上傳時每段音檔的逐字稿與耗時","operationId":"api_stt_transcribe_api_v1_stt_transcribe_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_api_stt_transcribe_api_v1_stt_transcribe_post"}}},"required":true},"responses":{"200":{"description":"原始逐字稿 + 所用模型 + 耗時","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Api Stt Transcribe Api V1 Stt Transcribe Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/correction/apply":{"post":{"tags":["nursing"],"summary":"步驟二：醫療名詞糾錯","description":"將原始逐字稿進行醫療名詞糾錯（本地字典，不需 AI）。回傳：\n- `corrected_text`\n- `corrections`：各組替換統計\n- `correction_segments`：供前端高亮\n- `elapsed_ms`","operationId":"api_correction_apply_api_v1_correction_apply_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CorrectionRequest"}}},"required":true},"responses":{"200":{"description":"糾錯後文字 + 替換統計 + 分段資料","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Api Correction Apply Api V1 Correction Apply Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/llm/structure":{"post":{"tags":["nursing"],"summary":"步驟三：LLM 結構化萃取","description":"將糾錯後逐字稿透過 LLM 萃取結構化護理紀錄。回傳：\n- `record`：結構化護理紀錄（visit_info、modules、soapie、warnings、changes、low_confidence）\n- `model_used`\n- `elapsed_ms`","operationId":"api_llm_structure_api_v1_llm_structure_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructureRequest"}}},"required":true},"responses":{"200":{"description":"結構化護理紀錄 JSON + 所用模型 + 耗時","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Api Llm Structure Api V1 Llm Structure Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/llm/line-family-summary":{"post":{"tags":["nursing"],"summary":"LINE 家屬訊息摘要","description":"將護理口述逐字稿改寫為適合貼在 LINE 群組給家屬的訊息（溫暖、具同理心、說明現況）。\n建議傳入糾錯後逐字稿以減少口語誤聽。","operationId":"api_line_family_summary_api_v1_llm_line_family_summary_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LineFamilySummaryRequest"}}},"required":true},"responses":{"200":{"description":"依逐字稿產生適合 LINE 群組給家屬的溫暖摘要文字","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Api Line Family Summary Api V1 Llm Line Family Summary Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/history/brief":{"post":{"tags":["nursing"],"summary":"歷史紀錄 + 本次逐字稿：產生紀錄輔助提示","description":"將病患歷史紀錄與本次 STT 逐字稿融合，輸出護理師撰寫本次紀錄時可用的提示：\n- 可沿用的個案基線\n- 本次新資訊\n- 與歷史相比的變化\n- 本次紀錄建議補入重點\n- 需人工確認的缺漏/矛盾\n- 風險提醒與 SOAPIE 草稿","operationId":"api_history_brief_api_v1_history_brief_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_api_history_brief_api_v1_history_brief_post"}}},"required":true},"responses":{"200":{"description":"融合歷史紀錄與本次逐字稿後的條列重點、異動、風險與 SOAPIE 草稿","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Api History Brief Api V1 History Brief Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/tts/line-family-speech":{"post":{"tags":["nursing"],"summary":"家屬訊息語音合成 (TTS)","description":"使用 Gemini TTS 將「家屬訊息」文字合成語音，供預覽或下載後分享。\n`model` 留空則使用後端預設 TTS 模型；`voice_name` 見 Google 預建語音名稱（預設 Kore）。","operationId":"api_line_family_tts_api_v1_tts_line_family_speech_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LineFamilyTtsRequest"}}},"required":true},"responses":{"200":{"description":"將家屬訊息文字轉為語音（base64 + MIME）","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Api Line Family Tts Api V1 Tts Line Family Speech Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/available-models":{"get":{"tags":["nursing"],"summary":"取得可選模型清單","description":"回傳 STT / LLM 可選模型清單及目前後端預設值。","operationId":"get_available_models_api_v1_system_available_models_get","responses":{"200":{"description":"STT 與 LLM 可用模型 + 目前預設","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Available Models Api V1 System Available Models Get"}}}}}}},"/api/v1/system/mapping-dictionary":{"get":{"tags":["nursing"],"summary":"取得醫療糾錯字典","description":"回傳 `mapping`（鍵為錯誤/口語詞、值為標準寫法）與 `count`。","operationId":"get_mapping_dictionary_api_v1_system_mapping_dictionary_get","responses":{"200":{"description":"目前使用中的口語→標準詞對照表","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Mapping Dictionary Api V1 System Mapping Dictionary Get"}}}}}}},"/api/v1/system/mapping-dictionary/entries":{"post":{"tags":["nursing"],"summary":"新增或更新糾錯字典項目","description":"傳入 `entries` 物件（鍵: 口語/錯誤詞, 值: 標準詞），合併至目前字典。","operationId":"upsert_mapping_entries_api_v1_system_mapping_dictionary_entries_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MappingEntriesRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Upsert Mapping Entries Api V1 System Mapping Dictionary Entries Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/mapping-dictionary/delete":{"post":{"tags":["nursing"],"summary":"刪除單一糾錯字典項目","description":"傳入 `key`（口語/錯誤詞）來刪除。","operationId":"delete_mapping_entry_api_v1_system_mapping_dictionary_delete_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MappingDeleteRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Delete Mapping Entry Api V1 System Mapping Dictionary Delete Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/mapping-dictionary/reset":{"post":{"tags":["nursing"],"summary":"重設字典為內建預設","description":"清除所有自訂項目，恢復為系統內建預設字典。","operationId":"reset_mapping_api_v1_system_mapping_dictionary_reset_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Reset Mapping Api V1 System Mapping Dictionary Reset Post"}}}}}}},"/api/v1/system/mapping-dictionary/upload-csv":{"post":{"tags":["nursing"],"summary":"上傳 CSV 匯入糾錯字典","description":"上傳 CSV 匯入。CSV 格式為兩欄（口語/錯誤詞, 標準詞），支援 UTF-8。\n`mode`：`merge`（合併至目前字典）或 `replace`（完全取代）。","operationId":"upload_mapping_csv_api_v1_system_mapping_dictionary_upload_csv_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_mapping_csv_api_v1_system_mapping_dictionary_upload_csv_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Upload Mapping Csv Api V1 System Mapping Dictionary Upload Csv Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/mapping-dictionary/download-csv":{"get":{"tags":["nursing"],"summary":"下載目前糾錯字典為 CSV","description":"回傳目前字典的 CSV，可直接下載。","operationId":"download_mapping_csv_api_v1_system_mapping_dictionary_download_csv_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/":{"get":{"summary":"Serve Index","operationId":"serve_index__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api-reference":{"get":{"summary":"Serve Api Reference","operationId":"serve_api_reference_api_reference_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api-test":{"get":{"summary":"Serve Api Test","operationId":"serve_api_test_api_test_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/mapping-editor":{"get":{"summary":"Serve Mapping Editor","operationId":"serve_mapping_editor_mapping_editor_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"Body_analyze_nursing_record_api_v1_nursing_record_analyze_post":{"properties":{"audio_file":{"type":"string","contentMediaType":"application/octet-stream","title":"Audio File","description":"音檔欄位名固定為 `audio_file`。副檔名：.mp3、.wav、.m4a、.webm、.ogg"},"stt_model":{"type":"string","title":"Stt Model","description":"STT 模型 ID（空字串使用預設）","default":""},"llm_model":{"type":"string","title":"Llm Model","description":"LLM 模型 ID（空字串使用預設）","default":""}},"type":"object","required":["audio_file"],"title":"Body_analyze_nursing_record_api_v1_nursing_record_analyze_post"},"Body_api_history_brief_api_v1_history_brief_post":{"properties":{"history_files":{"items":{"type":"string","contentMediaType":"application/octet-stream"},"type":"array","title":"History Files","description":"病患歷史紀錄，可多檔上傳。支援 .html、.htm、.txt、.md、.json、.csv、.dat"},"transcript":{"type":"string","title":"Transcript","description":"本次 STT 逐字稿，建議使用糾錯後逐字稿"},"model":{"type":"string","title":"Model","description":"LLM 模型 ID（空字串使用預設）","default":""}},"type":"object","required":["history_files","transcript"],"title":"Body_api_history_brief_api_v1_history_brief_post"},"Body_api_stt_transcribe_api_v1_stt_transcribe_post":{"properties":{"audio_file":{"items":{"type":"string","contentMediaType":"application/octet-stream"},"type":"array","title":"Audio File","description":"音檔欄位名固定為 `audio_file`。可單檔或多檔重複欄位上傳。副檔名：.mp3、.wav、.m4a、.webm、.ogg"},"model":{"type":"string","title":"Model","description":"STT 模型 ID（空字串使用預設）","default":""}},"type":"object","required":["audio_file"],"title":"Body_api_stt_transcribe_api_v1_stt_transcribe_post"},"Body_upload_mapping_csv_api_v1_system_mapping_dictionary_upload_csv_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"CSV 檔案，兩欄：口語/錯誤詞, 標準詞"},"mode":{"type":"string","title":"Mode","description":"merge（合併）或 replace（完全取代）","default":"merge"}},"type":"object","required":["file"],"title":"Body_upload_mapping_csv_api_v1_system_mapping_dictionary_upload_csv_post"},"CorrectionRequest":{"properties":{"text":{"type":"string","title":"Text"}},"type":"object","required":["text"],"title":"CorrectionRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LineFamilySummaryRequest":{"properties":{"text":{"type":"string","title":"Text"},"model":{"type":"string","title":"Model","default":""}},"type":"object","required":["text"],"title":"LineFamilySummaryRequest"},"LineFamilyTtsRequest":{"properties":{"text":{"type":"string","title":"Text"},"model":{"type":"string","title":"Model","default":""},"voice_name":{"type":"string","title":"Voice Name","default":"Kore"},"language_code":{"type":"string","title":"Language Code","default":"zh-TW"}},"type":"object","required":["text"],"title":"LineFamilyTtsRequest"},"MappingDeleteRequest":{"properties":{"key":{"type":"string","title":"Key"}},"type":"object","required":["key"],"title":"MappingDeleteRequest"},"MappingEntriesRequest":{"properties":{"entries":{"additionalProperties":{"type":"string"},"type":"object","title":"Entries"}},"type":"object","required":["entries"],"title":"MappingEntriesRequest"},"StructureRequest":{"properties":{"text":{"type":"string","title":"Text"},"model":{"type":"string","title":"Model","default":""}},"type":"object","required":["text"],"title":"StructureRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"nursing","description":"護理紀錄分析與系統字典"}]}