Task_Reporter/openspec/project.md

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