# Project Context

## Purpose
**Production Line Incident Response System (生產線異常即時反應系統)**

An on-premise, centralized event response platform that transforms chaotic communication channels (LINE, Teams, radio) into structured, traceable data. Each production incident (equipment failure, material shortage, quality issues) gets a dedicated chat room where all messages, images, and documents are collected. The system uses on-premise AI (Ollama) to automatically generate professional .docx reports with timelines and embedded evidence.

**Business Value:**
- Reduce MTTR (Mean Time To Resolution) through information centralization
- Enable post-mortem analysis with complete digital audit trails
- Automate report generation from hours to minutes
- Keep sensitive production data inside corporate network

## Tech Stack
- **Backend**: Python (FastAPI) - API server with built-in WebSocket support (localhost:8000)
- **Database**: PostgreSQL v14+ - Metadata storage for users, incident rooms, messages (localhost:5432)
- **Object Storage**: MinIO - S3-compatible storage for images/PDFs/logs (localhost:9000)
- **AI**: Ollama - On-premise LLM for JSON blueprint generation (localhost:11434)
- **Frontend**: React (Vite) - Single-page application served as static files
- **Real-time**: WebSockets (native FastAPI support) - Bidirectional communication
- **Document Generation**: python-docx - Dynamic .docx assembly with embedded images

## Project Conventions

### Code Style
- **Python Backend**: Follow PEP 8, use type hints (Python 3.10+)
- **React Frontend**: ESLint + Prettier (configure as needed)
- Use descriptive variable names in English
- Comments and documentation in Traditional Chinese when needed for domain concepts

### Architecture Patterns
- **Single-server deployment**: All services (FastAPI, PostgreSQL, MinIO, Ollama) run on one internal server
- **Event-driven architecture**: Each incident is an independent chat room
- **Frontend-backend separation**: React SPA communicates with FastAPI via REST + WebSocket
- **On-premise first**: All services communicate via localhost, no external dependencies
- **Security**: All communication within corporate firewall, files never leave internal network

### Testing Strategy
- **TDD (Test-Driven Development)**: Write tests before implementation
- **Unit Tests (UT)**: Test individual functions (e.g., `prepare_ai_input`, `assemble_docx`)
- **Integration Tests (IT)**: Test cross-service flows (e.g., file upload → MinIO → DB → WebSocket broadcast)
- **End-to-End Tests (E2E)**: Full user workflows (login → create room → upload image → send message → generate report)
- Use pytest for backend testing
- Mock Ollama responses for deterministic AI testing

### Git Workflow
- **Specification-Driven Development (SDD)**: All features must align with spec requirements
- Use feature branches for each phase (e.g., `phase-1-backend-core`, `phase-2-realtime`)
- Commit messages in English, reference task IDs (e.g., "T-2.3: Implement MinIO upload service")

## Domain Context
**Manufacturing Operations:**
- **Incident types**: Equipment failure, material shortage, quality issues
- **Users**: Line operators, supervisors, engineers, managers
- **Workflow**: Incident reported → chat room created → team collaborates → AI generates report → supervisor reviews and closes
- **Critical requirement**: Audit trail for compliance and continuous improvement
- **Sensitive data**: Production photos, equipment logs, defect images (must stay on-premise)

## Important Constraints
- **No external cloud services**: All components (app, DB, storage, AI) must run on corporate servers
- **Network isolation**: System operates in internal network only
- **Data sovereignty**: Production data cannot leave corporate infrastructure
- **Scalability**: Initially single production line, may expand to multiple buildings/sites
- **Compliance**: May need to satisfy ISO 9001 or similar quality management audit requirements

## External Dependencies
- **Internal only**:
  - PostgreSQL server
  - MinIO cluster
  - Ollama AI inference server
- **No external APIs**: All services are self-hosted