docs: add architecture and features documentation and update requirements and README

README.md

@@ -6,19 +6,43 @@ sdk: docker
 app_port: 7860
 ---
 
-# Bloom Ware
+# Bloom Ware - 個人化助理「小花」🌺
+
+**Bloom Ware** 的專屬個人化助理 **「小花」**，是由 **銘傳大學人工智慧應用學系** 的 **「槓上開發」** 團隊所精心研發的陪伴型人工智慧系統。
+
+🏆 **榮譽肯定：本專案於民國 115 年榮獲系上專題特優第一名！**
+
+## 關於小花 (About Xiao Hua)
+
+小花不只是一個普通的語音助理，而是一個具備「情感共鳴」與「上下文感知」能力的沉浸式對話夥伴。透過深度學習技術分析使用者的語氣與情緒，小花能夠主動切換至「關懷模式」，在使用者經歷低潮或負面情緒時，給予溫暖的心理支持與陪伴。
+
+## 🌟 核心特色 (Core Features)
+
+- **即時語音對話 (Real-time Voice Interaction)**：透過 WebSocket 實現極低延遲的 STT 與 TTS 雙向語音互動。
+- **語音聲紋登入 (Voice Authentication)**：結合 `SpeechBrain` 實現聽聲辨人，提供無密碼的流暢登入體驗。
+- **情感分析與關懷 (Emotion Detection & Care Mode)**：即時捕捉語音與文字中的情緒（如悲傷、憤怒、恐懼），自動提供同理心關懷。
+- **MCP 擴充助手 (Model Context Protocol)**：內建天氣、交通 (TDX)、地圖編碼與健康數據等生活助手功能，隨時為您提供所需資訊。
+- **長期記憶 (Long-Term Memory)**：整合 Firestore 與背景排程進行記憶摘要，讓小花記得與您的每一次重要對話。
+
+> 💡 **進階技術文件**：關於詳細的系統架構、API 說明與功能解析，請參閱 `docs/` 目錄下的完整文件。
+> - [系統架構說明 (Architecture)](/Users/baidongqu/Desktop/BM/docs/architecture.md)
+> - [核心功能詳解 (Features)](/Users/baidongqu/Desktop/BM/docs/features.md)
+> - [Hugging Face 部署指南](/Users/baidongqu/Desktop/BM/docs/huggingface-space-deployment.md)
+
+---
+
+## 🚀 部署與運行資訊 (Deployment & Run Information)
 
 Bloom Ware 目前以 **Hugging Face Docker Space** 方式部署到 `XiaoBai1221/Bloom_Ware`。
-後端是 `FastAPI`，入口在 `app.py`；登入頁由 `bloom-ware-login` 建成靜態檔後掛到 `/login`；主前端則由 `static/frontend` 提供。
 
-## Deployment Target
+### Deployment Target
 
 - Space: [`XiaoBai1221/Bloom_Ware`](https://hf.co/spaces/XiaoBai1221/Bloom_Ware)
 - SDK: `docker`
 - Exposed port: `7860`
 - Git remote: `hf`
 
-## Local Run
+### Local Run
 
 ```bash
 python3 -m venv .venv
@@ -29,7 +53,7 @@ ENABLE_BACKGROUND_JOBS=false PORT=7860 python app.py
 
 本地驗證網址：`http://127.0.0.1:7860`
 
-## Hugging Face Space Deploy
+### Hugging Face Space Deploy
 
 1. 在 Hugging Face Space `Settings -> Secrets` 補齊敏感環境變數。
 2. 不要提交 `.env`、Firebase 憑證 JSON、或任何本地設定檔。
@@ -37,14 +61,14 @@ ENABLE_BACKGROUND_JOBS=false PORT=7860 python app.py
 4. 直接推送到既有 Space remote：
 
 ```bash
-git add README.md Dockerfile .dockerignore requirements.txt requirements-dev.txt docs/huggingface-space-deployment.md
+git add README.md Dockerfile .dockerignore requirements.txt requirements-dev.txt docs/
 git commit -m "Prepare Bloom Ware for Hugging Face Space deployment"
 git push hf main
 ```
 
 若 Git 要求帳密，帳號用 Hugging Face 帳號，密碼改貼 **User Access Token**。
 
-## Required Secrets
+### Required Secrets
 
 至少補齊這些類型：
 
@@ -65,7 +89,7 @@ git push hf main
 - `ENABLE_BACKGROUND_JOBS=false`
 - `PORT=7860`
 
-## Notes
+### Notes
 
 - Space build context 已排除 `.env`、憑證 JSON、`tests/`、`.git/`，避免本地敏感檔被包進 Docker image。
 - `requirements.txt` 只保留 runtime 依賴；本地測試改裝 `requirements-dev.txt`。

docs/architecture.md

@@ -0,0 +1,39 @@
+# 系統架構說明 (System Architecture)
+
+Bloom Ware 「小花」專案採用現代化的前後端分離架構，結合多項領先的 AI 技術與穩定可擴展的後端框架。
+
+## 1. 後端架構 (Backend - FastAPI)
+
+後端採用 Python 的 **FastAPI** 框架，提供非同步、高效能的 API 服務與 WebSocket 長連接管理。
+
+- **`app.py`**: 應用的進入點。負責配置 Lifespan（啟動/關閉事件）、Middleware（如 CORS, CSP）、定義 WebSocket 的連線（`/ws`），並掛載靜態前端資源。
+- **`core/` (核心邏輯)**:
+  - **資料庫 (`database/`)**: 與 Firebase Firestore 進行連線，處理使用者資料、對話紀錄與記憶的 CRUD 操作。
+  - **驗證 (`auth.py`)**: 處理 JWT Token 生成與解析，並整合 Google OAuth 登入機制。
+  - **Pipeline (`pipeline.py`)**: 負責串接使用者的輸入到大語言模型（LLM）的資料流。
+  - **記憶體系統 (`memory_system.py`)**: 管理對話上下文，提供 AI 摘要。
+- **`features/` 與 `services/` (業務與 AI 服務)**:
+  - 封裝了與 OpenAI 溝通的 `ai_service.py`。
+  - `voice_binding.py`: 負責聲紋註冊狀態機管理。
+  - MCP (Model Context Protocol) 工具集：整合天氣、交通 (TDX)、位置查詢等外部 API。
+- **`websocket/`**:
+  - `manager.py`: 管理所有連線的使用者會話，處理訊息派發、連線逾時清理等。
+
+## 2. 前端架構 (Frontend)
+
+本系統將前端拆分為「登入驗證層」與「沉浸式互動層」。
+
+- **登入介面 (`bloom-ware-login/out`)**:
+  - 基於 **Next.js** 與 React 構建，編譯為靜態資源後由 FastAPI 掛載於 `/login` 路徑。
+  - 提供 Google 登入、一般信箱登入，以及跳轉至語音註冊的入口。
+- **主互動介面 (`static/frontend/`)**:
+  - 專注於 **沉浸式語音體驗** 的純靜態應用（HTML/CSS/JS）。
+  - 以「小花」的視覺形象（如動態花朵動畫）作為介面核心。
+  - 透過 WebRTC/MediaRecorder 擷取音訊，透過 WebSocket 傳送給後端，並將後端回傳的音訊進行播放，且畫面會隨情緒狀態與音量產生動態回饋。
+
+## 3. 基礎設施與部署 (Infrastructure)
+
+- **Docker 化**: 提供完整的 `Dockerfile`，確保在各種環境下執行的一致性。
+- **Hugging Face Space**: 系統原生設計為可直接部署於 Hugging Face Space 上，支援無伺服器架構的容器化執行。
+- **排程與背景任務**:
+  - 啟動時即開啟 `asyncio` 背景任務，定期清理過期的 WebSocket 會話、壓縮並總結歷史對話，確保長期執行的效能與穩定度。

docs/features.md

@@ -0,0 +1,36 @@
+# 核心功能詳解 (Core Features)
+
+「小花」不僅是一個對話機器人，更是具備感知能力的個人化助理。以下是系統內建的重點特色功能：
+
+## 1. 沉浸式即時語音對話
+
+為解決傳統一問一答的遲滯感，小花採用了全雙工概念的串流對話機制。
+- **WebSocket 通訊**: 前端將使用者的語音片段直接透過 WebSocket 傳遞，後端即時進行語音轉文字 (STT)、意圖分析、文字轉語音 (TTS)。
+- **動態 UI 反饋**: 當小花正在思考或說話時，前端的花朵視覺特效會根據當前的情緒與聲音頻率進行即時的波動（Pulse），創造出極強的生命力。
+
+## 2. AI 情感共鳴與「關懷模式」(Care Mode)
+
+這是「小花」最核心的亮點之一。
+- **情緒捕捉**: 後端在接收到使用者的語音與文字後，不僅分析語意，更會預測使用者的情感狀態（如快樂、中性、悲傷、憤怒、恐懼）。
+- **自動介入**: 若系統連續偵測到負面情緒，將無縫進入「關懷模式」。
+- **應答策略調整**: 在關懷模式下，小花會自動停用非必要的外部工具（如報天氣），專注於「傾聽」與「安撫」，並調整生成內容的 prompt，以更溫柔、具同理心的方式回應，直到使用者情緒平復。
+
+## 3. 無密碼的聽聲辨人 (Voice Authentication)
+
+除了傳統的帳號密碼與 Google OAuth，我們加入了生物辨識登入。
+- 整合了 `SpeechBrain` 的 ECAPA-TDNN 模型。
+- 使用者在註冊時錄製幾段語音（如「我是ＯＯＯ，開啟小花」）。
+- 登入時只需對著麥克風說話，系統便會比對聲紋餘弦相似度 (Cosine Similarity)，通過門檻後即可自動登入並載入該使用者的個人偏好與歷史記憶。
+
+## 4. MCP 生活助手整合 (Model Context Protocol)
+
+小花能主動使用多種工具來解決使用者的實際需求：
+- **環境感知**: 自動抓取使用者的經緯度與時區，並進行反向地理編碼 (Reverse Geocoding)。
+- **交通整合 (TDX)**: 串接台灣交通部 TDX 平台，可即時查詢台鐵、高鐵、捷運與公車動態。
+- **健康與天氣**: 查詢當前氣候，並能讀取 HealthKit 數據，關心使用者的日常作息與健康狀態。
+
+## 5. 智慧長期記憶系統
+
+有別於只能記住當前對話的傳統機器人，小花會與使用者共同成長。
+- **背景摘要**: 每日透過背景 Batch API 排程，將前一日的對話進行重點摘要（如：喜歡吃什麼、最近在煩惱什麼）。
+- **上下文注入**: 下次使用者連線時，系統會從 Firestore 中提取這些摘要記憶，作為背景 Context 注入給 LLM，讓對話擁有真正的「延續性」。

requirements.txt

@@ -41,3 +41,5 @@ transformers
 
 # Voice authentication (speaker recognition)
 speechbrain>=1.0.0
+httpx>=0.24.0
+PyJWT>=2.8.0