@arela/uploader 1.0.2 → 1.0.4

package/docs/ARELA_SCAN_QUICKREF.md

@@ -0,0 +1,139 @@
+# Arela Scan Quick Reference
+
+## Setup
+
+### 1. Configure Backend
+
+Add `cli_registry` entity to TypeORM and run migration:
+
+```bash
+cd arela-api
+npm run migration:generate -- -n CreateCliRegistry
+npm run migration:run
+```
+
+### 2. Configure CLI
+
+Set environment variables in `.env`:
+
+```bash
+# Required
+ARELA_COMPANY_SLUG=your_company
+ARELA_SERVER_ID=server01
+UPLOAD_BASE_PATH=/path/to/files
+UPLOAD_SOURCES=2023|2024|2025
+
+# Optional
+ARELA_BASE_PATH_LABEL=data
+SCAN_EXCLUDE_PATTERNS=.DS_Store,Thumbs.db,desktop.ini
+SCAN_BATCH_SIZE=2000
+
+# API Configuration
+ARELA_API_URL=http://localhost:3010
+ARELA_API_TOKEN=your-token
+```
+
+## Commands
+
+### Scan Filesystem
+
+```bash
+# Basic scan with throughput display
+arela scan
+
+# Scan with percentage progress (counts files first)
+arela scan --count-first
+
+# Scan to specific API target
+arela scan --api cliente
+```
+
+### View Scan Instances
+
+```bash
+# List all registered instances
+curl -H "x-api-key: $TOKEN" \
+  http://localhost:3010/api/uploader/scan/instances
+
+# Get stale instances (no scan > 90 days)
+curl -H "x-api-key: $TOKEN" \
+  "http://localhost:3010/api/uploader/scan/stale-instances?days=90"
+```
+
+### Deactivate Instance
+
+```bash
+curl -X PATCH \
+  -H "x-api-key: $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"tableName":"file_stats_company_server_path"}' \
+  http://localhost:3010/api/uploader/scan/deactivate
+```
+
+## Files Modified
+
+### Backend
+
+- ✅ `src/uploader/entities/cli-registry.entity.ts` - New entity
+- ✅ `src/uploader/services/file-stats-table-manager.service.ts` - New service
+- ✅ `src/uploader/services/uploader.service.ts` - Added scan methods
+- ✅ `src/uploader/controllers/uploader.controller.ts` - Added scan endpoints
+- ✅ `src/uploader/uploader.module.ts` - Updated imports
+
+### CLI
+
+- ✅ `src/commands/ScanCommand.js` - New command
+- ✅ `src/services/ScanApiService.js` - New API service
+- ✅ `src/config/config.js` - Added scan configuration
+- ✅ `src/index.js` - Registered scan command
+- ✅ `.env.template` - Added scan variables
+- ✅ `docs/ARELA_SCAN_IMPLEMENTATION.md` - Documentation
+
+## Table Schema
+
+Each scan instance creates a table:
+
+```sql
+file_stats_<company>_<server>_<path>
+├── id (uuid)
+├── file_name (varchar)
+├── file_extension (varchar)
+├── directory_path (text)
+├── relative_path (text)
+├── absolute_path (text) [unique]
+├── size_bytes (bigint)
+├── modified_at (timestamp)
+├── scan_timestamp (timestamp)
+└── created_at (timestamp)
+```
+
+## Troubleshooting
+
+### Error: Missing configuration
+
+**Cause**: Required env vars not set
+**Fix**: Set `ARELA_COMPANY_SLUG` and `ARELA_SERVER_ID`
+
+### Error: Table name collision
+
+**Cause**: Same identifiers used with different base path
+**Fix**: Change server ID or base path label
+
+### Error: Cannot connect to API
+
+**Cause**: Backend not running or wrong URL
+**Fix**: Verify `ARELA_API_URL` and start backend
+
+## Next Steps
+
+1. ✅ Implement `arela scan` (DONE)
+2. ⏳ Implement `arela identify` (detect pedimentos from PDFs)
+3. ⏳ Implement `arela propagate` (propagate arela_path)
+4. ⏳ Implement `arela push` (upload files by RFC)
+
+## Performance Tips
+
+- Increase `SCAN_BATCH_SIZE` for better throughput (default: 2000)
+- Use `MAX_API_CONNECTIONS` to match backend replicas
+- Run scans during off-peak hours for large datasets
+- Use `--count-first` only when progress percentage is needed