Task_Reporter/README.md

Task Reporter

Task Reporter 是一個生產事件即時協作報告系統,專為製造業生產線異常事件的追蹤、協作與報告而設計。

功能特色

核心功能

• 事件房間管理 - 建立、管理生產異常事件的專屬聊天室
• 即時訊息 - WebSocket 即時通訊,支援文字訊息及打字指示器
• 檔案上傳 - 支援圖片、文件、日誌檔案上傳 (MinIO 儲存)
• AI 報告生成 - 透過 DIFY 整合自動生成事件報告 (Word 格式)
• LOT 批號追蹤 - 關聯受影響的生產批號

權限系統

• AD 整合認證 - 透過 Active Directory API 進行身份驗證
• 角色權限 - 房間擁有者 (Owner)、編輯者 (Editor)、檢視者 (Viewer)
• 開放房間存取 - 所有登入用戶可自由加入房間
• 系統管理員 - 特殊權限帳號,可管理所有房間

事件分類

• 類型: 設備故障、物料短缺、品質問題、其他
• 嚴重等級: 低、中、高、緊急
• 狀態: 進行中、已解決、已封存

---

專案架構

Task_Reporter/
├── app/                          # 後端 (FastAPI)
│   ├── core/                     # 核心設定
│   │   ├── config.py             # 環境變數設定
│   │   └── database.py           # 資料庫連線
│   ├── db/                       # 資料庫初始化
│   ├── modules/                  # 功能模組
│   │   ├── auth/                 # 認證模組
│   │   │   ├── models.py         # User, Session 模型
│   │   │   ├── router.py         # 認證 API
│   │   │   └── services/         # AD 客戶端
│   │   ├── chat_room/            # 聊天室模組
│   │   │   ├── models.py         # Room, RoomMember 模型
│   │   │   ├── router.py         # 房間管理 API
│   │   │   └── schemas.py        # Pydantic schemas
│   │   ├── realtime/             # 即時訊息模組
│   │   │   ├── models.py         # Message 模型
│   │   │   ├── router.py         # WebSocket 端點
│   │   │   ├── websocket_manager.py
│   │   │   └── services/         # 訊息服務
│   │   ├── file_storage/         # 檔案儲存模組
│   │   │   ├── models.py         # FileAttachment 模型
│   │   │   ├── router.py         # 檔案上傳 API
│   │   │   └── validators.py     # 檔案驗證
│   │   └── report_generation/    # 報告生成模組
│   │       ├── models.py         # Report 模型
│   │       ├── router.py         # 報告 API
│   │       └── services/         # DIFY 整合
│   └── main.py                   # FastAPI 入口
├── alembic/                      # 資料庫遷移
│   └── versions/                 # 遷移版本檔
├── frontend/                     # 前端 (React + Vite)
│   ├── src/
│   │   ├── components/           # React 元件
│   │   ├── hooks/                # 自訂 Hooks
│   │   ├── pages/                # 頁面元件
│   │   ├── services/             # API 服務
│   │   ├── stores/               # Zustand 狀態管理
│   │   ├── types/                # TypeScript 型別
│   │   └── utils/                # 工具函數
│   ├── package.json
│   └── vite.config.ts
├── scripts/                      # 工具腳本
│   └── migrate_orphan_files.py   # 孤立檔案遷移工具
├── tests/                        # 測試檔案
├── check-env.sh                  # 環境檢查腳本
├── start-dev.sh                  # 啟動開發環境
├── stop-dev.sh                   # 停止開發環境
├── start-prod.sh                 # 啟動生產環境
├── stop-prod.sh                  # 停止生產環境
├── .env.example                  # 後端環境變數範本
├── .env.docker.example           # Docker 環境變數範本
├── docker-compose.minio.yml      # MinIO Docker 設定
├── requirements.txt              # Python 依賴
├── alembic.ini                   # Alembic 設定
└── DEPLOYMENT.md                 # 部署指南

---

技術棧

後端

• FastAPI - 非同步 Web 框架
• SQLAlchemy 2.0 - ORM
• MySQL - 關聯式資料庫
• Alembic - 資料庫遷移
• MinIO - S3 相容物件儲存
• WebSocket - 即時通訊
• python-docx - Word 文件生成

前端

• React 18 - UI 框架
• TypeScript - 型別安全
• Vite - 建置工具
• TanStack Query - 資料同步
• Zustand - 狀態管理
• Tailwind CSS - 樣式框架

基礎設施

• MinIO - 物件儲存
• DIFY - AI 服務整合

---

快速開始

必要條件

• Python 3.11+
• Node.js 18+
• MySQL 8.0+
• Docker (用於 MinIO)

方式一: 使用內建腳本 (推薦)

# 1. 檢查環境是否就緒
./check-env.sh

# 2. 設定環境變數
cp .env.example .env
nano .env  # 填入 DATABASE_URL, FERNET_KEY 等

# 3. 建立虛擬環境並安裝依賴
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 4. 執行資料庫遷移
alembic upgrade head

# 5. 啟動開發環境 (MinIO + Backend + Frontend)
./start-dev.sh

# 停止服務
./stop-dev.sh

方式二: 手動啟動

1. 啟動 MinIO

docker-compose -f docker-compose.minio.yml up -d

2. 設定後端

# 建立虛擬環境
python3 -m venv venv
source venv/bin/activate

# 安裝依賴
pip install -r requirements.txt

# 設定環境變數
cp .env.example .env
# 編輯 .env 填入必要設定

# 執行資料庫遷移
alembic upgrade head

# 啟動後端
uvicorn app.main:app --reload --port 8000

3. 設定前端

cd frontend

# 安裝依賴
npm install

# 設定環境變數 (可選)
cp .env.example .env

# 啟動開發伺服器
npm run dev

存取應用

• 前端: http://localhost:3000
• 後端 API: http://localhost:8000/api
• API 文件: http://localhost:8000/docs
• MinIO Console: http://localhost:9001

內建腳本說明

腳本	說明
./check-env.sh	檢查環境設定 (Python, Node, MySQL, MinIO, 環境變數)
./start-dev.sh	啟動開發環境 (所有服務 + hot-reload)
./stop-dev.sh	停止開發環境
./start-prod.sh	啟動生產環境 (multi-worker backend)
./stop-prod.sh	停止生產環境

---

API 端點概覽

認證 (/api/auth)

• POST /login - 登入
• POST /logout - 登出
• GET /me - 取得目前用戶資訊
• POST /refresh - 更新 token

房間管理 (/api/rooms)

• GET / - 列出房間
• POST / - 建立房間
• GET /{room_id} - 取得房間詳情
• PATCH /{room_id} - 更新房間
• DELETE /{room_id} - 封存房間
• POST /{room_id}/join - 加入房間
• GET /{room_id}/members - 取得成員列表
• POST /{room_id}/lots - 新增 LOT 批號
• DELETE /{room_id}/lots/{lot} - 移除 LOT 批號

即時訊息 (/api/realtime)

• WebSocket /ws/{room_id} - 即時訊息連線
• GET /rooms/{room_id}/messages - 取得歷史訊息
• GET /rooms/{room_id}/online-users - 取得線上用戶

檔案管理 (/api/rooms/{room_id}/files)

• POST / - 上傳檔案
• GET / - 列出檔案
• GET /{file_id}/download - 下載檔案

報告生成 (/api/rooms/{room_id}/reports)

• POST /generate - 生成報告
• GET / - 列出報告
• GET /{report_id}/status - 報告狀態
• GET /{report_id}/download - 下載報告
• GET /{report_id}/markdown - 取得 Markdown 預覽

---

環境變數

詳見 .env.example 取得完整設定說明。

必要設定

• DATABASE_URL - MySQL 連線字串
• FERNET_KEY - 加密金鑰
• AD_API_URL - AD 認證 API
• MINIO_* - MinIO 連線設定

可選設定

• DIFY_API_KEY - AI 報告功能
• SYSTEM_ADMIN_EMAIL - 系統管理員

---

部署

詳見 DEPLOYMENT.md 取得完整的 1Panel 部署指南。

---

開發

資料庫遷移

# 建立新遷移
alembic revision --autogenerate -m "描述"

# 執行遷移
alembic upgrade head

# 回滾
alembic downgrade -1

測試

pytest tests/

程式碼檢查

ruff check app/

---

授權

Private - 版權所有