V1.0: Class 1 fax — real-world 4-page send to external number confirmed

Core features: - Class 1 T.30 protocol: full send/receive implementation - HDLC: DLE-stuffing, FCS strip, USR5637 bit-reversal handling - T.4 MH encoder/decoder (1728px A4 standard) - Document pipeline: PDF (Ghostscript), PNG, TIFF input - Width clamping: US Letter 1734px → 1728px fax standard - Cover page: CJK rasterization (TW/CN/JP/EN), TIFF + HTML output - OCR verification: Tesseract 5 with eng+chi_tra, CJK space-tolerant - API server (axum): health, send, jobs, cover, retry, cancel - Background worker: auto-poll queue, speed fallback, retry policy - Modem detection, pool management Real-world test results (2026-07-23): - V90 → 25153038: 4 pages, V.17 12000 bps, 2:33 ✅ - USR5637 → 25153038: 4 pages, V.17 12000 bps, 2:26 ✅ - Both faxes confirmed received on remote machine Tested: loopback (100% pixel match), multi-page, all input formats, cover pages, OCR verify, API endpoints, worker processing. 13 unit tests pass, 0 new clippy warnings.
2026-07-24 18:47:15 +08:00
parent d1e92b32fb
commit 55bca92691
155 changed files with 25024 additions and 916 deletions
@@ -0,0 +1,207 @@
+# Telfax Web UI
+
+Modern Web UI for Telfax Enterprise Fax Server built with **Tauri + Vue 3 + TypeScript**.
+
+## Features
+
+- **Dashboard**: Real-time status overview, send faxes directly
+- **Fax History**: View and manage fax jobs
+- **Modem Status**: Monitor modem health and status
+- **Settings**: Configure API connection and authentication
+
+## Tech Stack
+
+- **Frontend**: Vue 3 + TypeScript + Vite
+- **Styling**: Tailwind CSS
+- **State Management**: Pinia
+- **Routing**: Vue Router 4
+- **HTTP Client**: Axios
+- **Desktop App**: Tauri 2.0
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- Rust (for Tauri)
+- Telfax backend running on `http://localhost:3000`
+
+### Install Dependencies
+
+```bash
+cd web-ui
+npm install
+```
+
+### Run Development Server
+
+```bash
+# Web only (for development)
+npm run dev
+
+# Desktop app (with Tauri)
+npm run tauri dev
+```
+
+The app will be available at `http://localhost:1420`
+
+### Build for Production
+
+```bash
+# Build web app
+npm run build
+
+# Build desktop app (all platforms)
+npm run tauri build
+```
+
+## Configuration
+
+### Environment Variables
+
+Create `.env` file in `web-ui/` directory:
+
+```env
+VITE_API_URL=http://localhost:3000
+VITE_API_TOKEN=your-api-token-here
+```
+
+### Production Configuration
+
+1. Set API URL in `.env`:
+   ```env
+   VITE_API_URL=https://your-server.com
+   VITE_API_TOKEN=prod-admin-token-change-me-abc123xyz
+   ```
+
+2. Build and deploy:
+   ```bash
+   npm run build
+   ```
+
+3. Deploy `dist/` directory to your web server
+
+## Architecture
+
+```
+web-ui/
+├── src/
+│   ├── api/           # API client and types
+│   │   └── client.ts  # Axios client with interceptors
+│   ├── components/    # Reusable Vue components
+│   ├── router/        # Vue Router configuration
+│   │   └── index.ts
+│   ├── stores/        # Pinia stores
+│   │   └── fax.ts     # Fax state management
+│   ├── types/         # TypeScript interfaces
+│   │   └── index.ts
+│   ├── utils/         # Utility functions
+│   ├── views/         # Page components
+│   │   ├── Dashboard.vue
+│   │   ├── FaxHistory.vue
+│   │   ├── ModemStatus.vue
+│   │   └── Settings.vue
+│   ├── App.vue        # Root component
+│   ├── main.ts        # Application entry point
+│   └── style.css      # Global styles (Tailwind)
+├── src-tauri/         # Tauri backend (Rust)
+│   └── tauri.conf.json
+├── .env               # Environment variables
+├── package.json
+├── tailwind.config.js
+├── postcss.config.js
+└── vite.config.ts
+```
+
+## API Endpoints
+
+The Web UI connects to the Telfax backend REST API:
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/v1/status` | GET | Server status |
+| `/api/v1/modems` | GET | List modems |
+| `/api/v1/jobs` | GET | List fax jobs |
+| `/api/v1/jobs/:id` | GET | Get job details |
+| `/api/v1/fax/send` | POST | Send fax |
+| `/api/v1/jobs/:id/cancel` | POST | Cancel job |
+
+All endpoints require `Authorization: Bearer <token>` header.
+
+## Screenshots
+
+### Dashboard
+- Real-time statistics (total, pending, completed, failed jobs)
+- Quick send fax form
+- Active modems overview
+
+### Fax History
+- Table view of all fax jobs
+- Status badges
+- Cancel pending jobs
+
+### Modem Status
+- Modem health monitoring
+- Class and priority information
+- Status indicators (idle, busy, error, disabled)
+
+### Settings
+- API URL configuration
+- Authentication token management
+- App information
+
+## Desktop App Features
+
+When running as a Tauri desktop app:
+
+- Native window controls
+- System tray integration (optional)
+- Auto-update support (optional)
+- Offline mode (view cached data)
+- Native notifications
+
+## Troubleshooting
+
+### Development Issues
+
+1. **API Connection Failed**
+   - Check if Telfax backend is running
+   - Verify `.env` configuration
+   - Check CORS settings on backend
+
+2. **Build Errors**
+   - Run `npm install` to ensure dependencies
+   - Check Node.js version (18+)
+   - Clear cache: `rm -rf node_modules package-lock.json && npm install`
+
+3. **Tauri Build Fails**
+   - Ensure Rust is installed
+   - Check platform-specific dependencies
+   - Run `npm run tauri dev` first to test
+
+### Production Issues
+
+1. **Authentication Errors**
+   - Verify API token in Settings
+   - Check token permissions (admin/write/read)
+
+2. **Modem Not Detected**
+   - Check backend logs
+   - Verify modem device paths in backend config
+
+## License
+
+MIT License - See LICENSE file for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create feature branch: `git checkout -b feature/amazing-feature`
+3. Commit changes: `git commit -m 'Add amazing feature'`
+4. Push to branch: `git push origin feature/amazing-feature`
+5. Open Pull Request
+
+## Support
+
+- GitHub Issues: https://github.com/yourorg/telfax/issues
+- Documentation: `/docs`