c8966477b9
Complete implementation of the production line incident response system (生產線異常即時反應系統) including: Backend (FastAPI): - User authentication with AD integration and session management - Chat room management (create, list, update, members, roles) - Real-time messaging via WebSocket (typing indicators, reactions) - File storage with MinIO (upload, download, image preview) Frontend (React + Vite): - Authentication flow with token management - Room list with filtering, search, and pagination - Real-time chat interface with WebSocket - File upload with drag-and-drop and image preview - Member management and room settings - Breadcrumb navigation - 53 unit tests (Vitest) Specifications: - authentication: AD auth, sessions, JWT tokens - chat-room: rooms, members, templates - realtime-messaging: WebSocket, messages, reactions - file-storage: MinIO integration, file management - frontend-core: React SPA structure 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
144 lines
5.1 KiB
Markdown
144 lines
5.1 KiB
Markdown
# Frontend Architecture Design
|
|
|
|
## Context
|
|
Task Reporter needs a frontend to enable factory personnel to use the incident response system. The application must work on internal network only, support real-time collaboration, and integrate with existing backend APIs.
|
|
|
|
**Stakeholders**: Line operators, supervisors, engineers, managers
|
|
**Constraints**: On-premise deployment, internal network only, no external CDN
|
|
|
|
## Goals / Non-Goals
|
|
|
|
### Goals
|
|
- Provide intuitive UI for incident management workflow
|
|
- Enable real-time collaboration via WebSocket
|
|
- Support file upload with image preview
|
|
- Work offline-first where possible (local state)
|
|
- Responsive design for desktop and tablet
|
|
|
|
### Non-Goals
|
|
- Mobile app (web responsive is sufficient)
|
|
- Offline mode with sync (requires backend changes)
|
|
- Multi-language i18n (Chinese-only for initial release)
|
|
- PWA capabilities (not required for internal use)
|
|
|
|
## Decisions
|
|
|
|
### 1. Framework: React 18 + Vite
|
|
**Decision**: Use React 18 with Vite for fast development and build
|
|
**Rationale**:
|
|
- Vite provides fast HMR and build times
|
|
- React 18 concurrent features for better UX
|
|
- Large ecosystem and team familiarity
|
|
- Static build can be served by FastAPI
|
|
|
|
**Alternatives considered**:
|
|
- Vue 3: Good option, but team has more React experience
|
|
- Next.js: SSR not needed for internal SPA
|
|
- Vanilla JS: Too much boilerplate for complex app
|
|
|
|
### 2. State Management: Zustand + React Query
|
|
**Decision**: Use Zustand for client state, React Query for server state
|
|
**Rationale**:
|
|
- Zustand: Minimal boilerplate, TypeScript-friendly
|
|
- React Query: Automatic caching, refetching, optimistic updates
|
|
- Clear separation between client and server state
|
|
|
|
**Alternatives considered**:
|
|
- Redux Toolkit: More boilerplate than needed
|
|
- Context only: Not suitable for complex state
|
|
- SWR: React Query has better DevTools
|
|
|
|
### 3. Styling: Tailwind CSS
|
|
**Decision**: Use Tailwind CSS for utility-first styling
|
|
**Rationale**:
|
|
- Fast development with utility classes
|
|
- Consistent design system
|
|
- Small bundle size with purging
|
|
- Good for component-based architecture
|
|
|
|
**Alternatives considered**:
|
|
- CSS Modules: More boilerplate
|
|
- Styled Components: Runtime overhead
|
|
- Ant Design: Too opinionated, Chinese license concerns
|
|
|
|
### 4. WebSocket: Native WebSocket with reconnection
|
|
**Decision**: Use native WebSocket API with custom reconnection logic
|
|
**Rationale**:
|
|
- Backend uses native WebSocket (not Socket.IO)
|
|
- Simple protocol, no heavy library needed
|
|
- Custom reconnection gives more control
|
|
|
|
**Alternatives considered**:
|
|
- Socket.IO client: Backend doesn't use Socket.IO
|
|
- SockJS: Unnecessary fallbacks for modern browsers
|
|
|
|
### 5. Directory Structure
|
|
```
|
|
frontend/
|
|
├── src/
|
|
│ ├── components/ # Reusable UI components
|
|
│ │ ├── common/ # Buttons, inputs, modals
|
|
│ │ ├── chat/ # Chat-related components
|
|
│ │ ├── room/ # Room management components
|
|
│ │ └── file/ # File upload/preview
|
|
│ ├── pages/ # Route pages
|
|
│ │ ├── Login.tsx
|
|
│ │ ├── RoomList.tsx
|
|
│ │ ├── RoomDetail.tsx
|
|
│ │ └── NotFound.tsx
|
|
│ ├── hooks/ # Custom React hooks
|
|
│ │ ├── useAuth.ts
|
|
│ │ ├── useWebSocket.ts
|
|
│ │ └── useRoom.ts
|
|
│ ├── stores/ # Zustand stores
|
|
│ │ ├── authStore.ts
|
|
│ │ └── chatStore.ts
|
|
│ ├── services/ # API client functions
|
|
│ │ ├── api.ts # Axios instance
|
|
│ │ ├── auth.ts
|
|
│ │ ├── rooms.ts
|
|
│ │ └── files.ts
|
|
│ ├── types/ # TypeScript types
|
|
│ ├── utils/ # Utility functions
|
|
│ └── App.tsx # Root component
|
|
├── public/
|
|
├── index.html
|
|
├── package.json
|
|
├── vite.config.ts
|
|
├── tailwind.config.js
|
|
└── tsconfig.json
|
|
```
|
|
|
|
## Risks / Trade-offs
|
|
|
|
### Risk: WebSocket connection stability
|
|
**Mitigation**: Implement exponential backoff reconnection, connection status indicator, message queue for offline messages
|
|
|
|
### Risk: Large file uploads blocking UI
|
|
**Mitigation**: Use chunked uploads with progress indicator, background upload queue
|
|
|
|
### Risk: Token expiry during long sessions
|
|
**Mitigation**: Auto-refresh tokens before expiry, graceful re-authentication flow
|
|
|
|
## API Integration
|
|
|
|
### Authentication
|
|
- POST `/api/auth/login` - Returns internal token
|
|
- Store token in localStorage
|
|
- Attach `Authorization: Bearer {token}` to all requests
|
|
|
|
### WebSocket Connection
|
|
- Connect to `/api/ws/{room_id}?token={token}`
|
|
- Handle message types: message, edit_message, delete_message, typing, system
|
|
|
|
### File Upload
|
|
- POST `/api/rooms/{room_id}/files` with multipart/form-data
|
|
- Display progress during upload
|
|
- Show thumbnail for images after upload
|
|
|
|
## Open Questions
|
|
- [ ] Should we bundle the frontend with FastAPI or serve separately?
|
|
- **Answer**: Bundle with FastAPI for simpler deployment (single container)
|
|
- [ ] Image thumbnail generation - frontend or backend?
|
|
- **Answer**: Backend generates thumbnails, frontend displays from MinIO URL
|