docs: Add deployment and project documentation with unified env config

- Add DEPLOYMENT.md for 1Panel deployment guide with troubleshooting - Add README.md with project architecture and quick start guide - Update .gitignore to exclude development docs (openspec/, CLAUDE.md, etc.) - Unify port configuration via .env (BACKEND_PORT, FRONTEND_PORT, MINIO_API_PORT, MINIO_CONSOLE_PORT) - Update start-dev.sh and check-env.sh to read ports from .env 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-08 13:08:02 +08:00
parent 44822a561a
commit 722f570766
6 changed files with 779 additions and 19 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,302 @@
+# 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 - 版權所有