SmartVal

SmartVal 是一個以 Django 為核心的 full-stack 房屋估價平台原型。一般使用者可以輸入房屋條件，系統會透過 Celery 非同步任務呼叫 prototype XGBoost model 產生估價結果，並在結果頁呈現估價資訊、地圖與附近資料；登入使用者也可以收藏估價紀錄。

這個專案的核心不是把模型包裝成正式商用估價服務，而是展示如何把資料管理、機器學習推論、非同步任務、權限控管、後台管理、WebSocket 即時更新與測試整合成一個可操作的 Django web application。

介面展示

首頁估價表單

使用者可以在首頁輸入城市、行政區、房屋類型、屋齡、樓層、坪數與房間數，送出後由後端建立非同步估價任務。

系統後台首頁

Staff dashboard 集中呈現房屋庫存、估價量、合作仲介、成交買家資料與圖表統計，並提供後台資料管理入口。

我的估價收藏

登入使用者可以保存估價結果，在收藏頁面查看物件摘要、估價金額與重要條件，並移除不需要保留的紀錄。

專案動機

SmartVal 最初的靈感來自教授研究計畫中「需要一個房價預測介面」的需求探索。早期曾以 Streamlit 做過較簡單的房價預測介面；後來在 Django 全端設計課中，期末專題需要自行設計完整全端系統，因此將這個想法擴展成 Django 專案。

在後續開發中，SmartVal 逐漸從單純的預測介面，延伸成一個整合 Django / full-stack / backend / async / realtime 技術的完整作品。專案重點放在模型推論與 Web application 流程的整合，而不是單獨展示模型準確率。

專案定位

• 課程專案整理後的 GitHub portfolio prototype。
• 展示 Django full-stack system integration 與 backend workflow 設計。
• 模型是支援估價流程的 prototype XGBoost model，不是正式不動產估價服務。
• 展示資料使用 AI 生成的虛構房屋與人物資料，不包含真實交易資料或個人資訊。

🏘️ 功能展示

一般使用者

• 註冊、登入與登出。
• 在首頁輸入房屋條件並送出估價請求。
• 以 AJAX / form submit 建立 Celery 估價任務。
• 透過 task status polling 追蹤非同步任務狀態。
• 查看估價結果頁、地圖與附近資料。
• 將估價結果加入收藏。
• 查看收藏列表、收藏詳情並移除自己的收藏。

Staff / 後台

• Dashboard 統計與資料管理入口。
• House / Agent / Buyer 的列表、詳情、新增、編輯與刪除。
• Excel 匯入房屋資料。
• 透過 Channels / WebSocket 提供即時更新或通知。
• Staff-only permission control，避免一般使用者進入後台管理流程。

技術亮點

• Django full-stack 結構：專案以 Django class-based views 組織主要頁面流程，使用 forms 負責輸入驗證與欄位轉換，templates 呈現前台估價、收藏與後台管理介面，並透過 custom user model 保留後續擴充登入與權限欄位的彈性。
• 權限與資料邊界：後台 House / Agent / Buyer 管理頁以 LoginRequiredMixin 與 UserPassesTestMixin 限制 staff 使用者存取；收藏詳情、移除收藏與 task status 查詢則採 owner-scoped access control，確保一般登入使用者只能操作自己的估價與收藏資料。
• Celery + Redis 處理估價任務與 Excel import 等非同步流程。
• Django Channels / WebSocket 支援 dashboard 即時更新。
• XGBoost / scikit-learn / pandas / joblib model pipeline 整合到 web flow。
• Leaflet 與 Chart.js 用於地圖與視覺化呈現。
• Django regression tests 覆蓋權限、收藏、後台頁面、Excel 匯入與 task status 等關鍵行為。
• .env.example、.gitignore 與驗證 script 讓本機設定、敏感資訊排除與基本檢查流程更清楚。

🧱 系統架構

使用者估價流程

flowchart LR
    A[使用者瀏覽器] --> B[Django HomeView]
    B --> C[估價表單驗證]
    C --> D[派發 Celery 估價任務]
    D --> E[(Redis Broker / Result Backend)]
    E --> F[Celery Worker]
    F --> G[HousePriceService]
    G --> H[XGBoost Model Pipeline]
    G --> I[地理編碼與附近房屋查詢]
    I --> J[(House 資料庫)]
    H --> K[Celery 任務結果]
    I --> K
    K --> L[TaskStatusView polling]
    L --> M[Session 儲存估價結果]
    M --> N[估價結果頁]
    N --> O[加入收藏]
    O --> P[(ValuationRecord 資料庫)]

Loading

Staff Excel 匯入流程

flowchart LR
    A[Staff 上傳 Excel] --> B[ExcelUploadView]
    B --> C[Django Storage 暫存檔案]
    C --> D[派發 Celery 匯入任務]
    D --> E[(Redis Broker / Result Backend)]
    E --> F[Celery Worker]
    F --> G[讀取與驗證 Excel 工作表]
    G --> H[(House / Agent / Buyer 資料庫)]
    F --> I[Channels WebSocket 通知]
    I --> J[Dashboard / 匯入頁提示]
    H --> K[House / Agent / Buyer 列表頁]

Loading

App 結構

Path	Responsibility
apps.accounts	Custom user model、auth views/forms/templates。
apps.core	首頁估價、結果頁、收藏、dashboard、task status、ML service。
apps.house	House / Agent / Buyer models、CRUD、Excel import/export、signals。
config	Django settings split、URL/ASGI/WSGI、Celery、Channels routing。
scripts	本機驗證輔助工具，例如 JavaScript syntax check。

資料與模型說明

SmartVal 使用 AI 生成的虛構房屋資料與人物資料，不包含真實交易資料、真實買賣方資訊或可識別個資。這些資料用於展示估價流程、收藏列表、後台 CRUD、dashboard 統計與 Excel 匯入。

本 repo 不提供資料庫檔案、原始資料集或本機產生的 media uploads。clone 專案後可以建立空白資料庫並自行新增資料，或透過後台 Excel 匯入功能匯入自己的示範資料。

估價流程使用 apps/core/ml_models/smartval_model.pkl 作為 runtime model artifact。模型以 prototype XGBoost pipeline 支援網站估價流程，讓使用者送出房屋條件後可以看到完整的非同步推論、結果頁與收藏流程；它不是正式估價模型，也不應用於實際不動產交易決策。

⚙️ 安裝與啟動

估價功能除了啟動 Django server，還需要同時啟動：

1. Redis server
2. Celery worker
3. Django runserver

1. 建立 Python virtual environment

python -m venv venv
venv\Scripts\activate.bat
pip install -r requirements.txt

2. 建立本機設定檔與資料庫

copy .env.example .env
venv\Scripts\python.exe manage.py migrate

請以 .env.example 作為本機設定範本，不要將 .env 或任何 secret / credential commit 到 git。

3. 啟動 Redis

Windows 本機建議先安裝 Docker Desktop 與 WSL / Ubuntu，再用 Docker 執行 Redis：

docker run --name smartval-redis -p 6379:6379 -d redis:7

如果 container 已存在，之後可改用：

docker start smartval-redis

4. 啟動 Celery worker

Windows 上 Celery worker 需要使用 --pool=solo。建議在啟動 worker 前明確指定 development settings：

set DJANGO_SETTINGS_MODULE=config.settings.development
venv\Scripts\celery.exe -A config worker -l info --pool=solo

5. 啟動 Django server

另開一個 terminal：

set DJANGO_SETTINGS_MODULE=config.settings.development
venv\Scripts\python.exe manage.py runserver

啟動後開啟：

http://127.0.0.1:8000/

驗證方式

可使用以下指令檢查 Django、測試與前端 JavaScript 語法：

venv\Scripts\python.exe manage.py check
venv\Scripts\python.exe manage.py test apps --noinput
venv\Scripts\python.exe scripts\check_js_syntax.py

目前驗證狀態：

• Django system check passed。
• Django app tests passed，39 tests。
• First-party JavaScript syntax check passed，5 files checked。
• 在 Redis + Celery worker + Django runserver 同時啟動後，估價流程已完成本機 manual end-to-end test。

scripts/check_js_syntax.py 使用 Node.js 的 node --check，不需要 npm。

本機啟動注意事項

如果送出估價時前端 alert 顯示「連線發生錯誤，請稍後再試」，而 Django traceback 顯示：

Error 10061 connecting to 127.0.0.1:6379

通常代表 Redis 沒有在 127.0.0.1:6379 運行，或 Celery backend 無法連線到 Redis。請依序確認：

1. 確認 Docker Desktop 已啟動。
2. 執行 docker start smartval-redis，或重新建立 Redis container。
3. 重新啟動 Celery worker。
4. 重新啟動 Django runserver。
5. 回到首頁重新送出估價。

如果只啟動 Django server，估價任務可能無法被 worker 消化，或 task status 一直停在等待狀態。請確認 Redis 與 Celery worker 都已啟動，並在 Windows worker 指令中保留 --pool=solo。

後續方向

• 補充 model training / evaluation 文件，例如資料產生方式、feature engineering、評估指標與 model card。
• 加入 Docker Compose，將 Redis、Celery worker 與 Django server 的本機啟動流程整合成更一致的開發環境。
• 擴充估價流程 integration test、Excel import edge cases 與更多失敗情境測試。
• 評估合適的部署平台，讓 demo 環境能穩定展示完整估價流程。