# 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)

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

```bash
# 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

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

#### 2. 設定後端

```bash
# 建立虛擬環境
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. 設定前端

```bash
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](.env.example) 取得完整設定說明。

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

### 可選設定
- `DIFY_API_KEY` - AI 報告功能
- `SYSTEM_ADMIN_EMAIL` - 系統管理員

---

## 部署

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

---

## 開發

### 資料庫遷移

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

# 執行遷移
alembic upgrade head

# 回滾
alembic downgrade -1
```

### 測試

```bash
pytest tests/
```

### 程式碼檢查

```bash
ruff check app/
```

---

## 授權

Private - 版權所有