Add WorkTrace module specification

2026-03-13 21:49:50 +00:00
parent adbe430761
commit 44be28c087
1 changed files with 339 additions and 0 deletions
--- a/work_trace/SPEC.md
+++ b/work_trace/SPEC.md
@@ -0,0 +1,339 @@
+# WorkTrace — Odoo Module Specification
+
+**Module Name:** `work_trace`
+**Display Name:** WorkTrace
+**Version:** 18.0.1.0.0
+**Category:** Productivity / Field Operations
+**Author:** tocmo0nlord
+**License:** LGPL-3
+
+---
+
+## Overview
+
+WorkTrace is a custom Odoo 18 module designed to consolidate and organize daily field work activities into a single unified calendar view. It captures location history, travel distances, time spent at locations, credit card expenses, and receipts — all mapped to a daily work journal. The organized data will serve as the foundation for future integration with Autotask (PSA) for timecard submission, expense reporting, and PO/project reconciliation.
+
+---
+
+## Goals
+
+1. Eliminate manual data entry across multiple platforms
+2. Build a single source of truth for daily work activities inside Odoo
+3. Enable accurate expense and timecard submissions tied to project/ticket numbers
+4. Lay the groundwork for future Autotask API integration
+
+---
+
+## Feature Set
+
+---
+
+### Feature 1: Location & Travel Tracking
+
+**Source:** Google Timeline (GPS coordinates)
+
+#### Description
+Import location history from Google Timeline to reconstruct the user's daily travel. Each location pinpoint is translated into a human-readable address or business name and displayed on the Odoo calendar.
+
+#### Capabilities
+- Import Google Timeline data (JSON export or API)
+- Translate GPS coordinates to street address / business name via OpenStreetMap Nominatim
+- Calculate distance traveled between each location stop
+- Calculate time spent at each location
+- Display travel path on a map view inside Odoo
+- Toggle calendar integration ON/OFF per day or globally
+
+#### Data Points Captured
+| Field | Description |
+|---|---|
+| Timestamp | Date and time of location pinpoint |
+| Coordinates | Latitude / Longitude |
+| Address | Resolved street address |
+| Business Name | Resolved place name (if applicable) |
+| Time at Location | Duration spent at location |
+| Distance from Previous | Calculated travel distance (miles/km) |
+| Travel Mode | Driving / Walking / Transit (if available from Timeline) |
+
+#### Calendar Integration
+- Each location stop creates a calendar event block
+- Events show: address, time spent, distance traveled
+- Color-coded by location type (office, client site, hotel, transit)
+- Toggle: Enable/Disable location events on calendar
+
+---
+
+### Feature 2: Credit Card Expense Tracking
+
+**Source:** Citi Card financial statements
+
+#### Description
+Import daily credit card transactions from Citi Card statements and map them to the calendar. The user reviews each transaction and accepts, modifies, or rejects it before it is finalized as an expense entry.
+
+#### Capabilities
+- Import Citi Card statements (CSV, OFX, or PDF format)
+- Parse transactions: date, merchant, amount, category
+- Map each transaction to the corresponding calendar day
+- Present a review queue: Accept / Modify / Reject per transaction
+- Accepted transactions become Odoo expense entries
+- Link expenses to projects / Autotask ticket numbers
+- Support for multi-currency transactions
+
+#### Transaction Review Workflow
+Import Statement -> Parse Transactions -> Review Queue
+    -> Accept   -> Create Expense Entry -> Link to Project/PO
+    -> Modify   -> Edit details -> Create Expense Entry
+    -> Reject   -> Archive (excluded from reporting)
+
+#### Data Points Captured
+| Field | Description |
+|---|---|
+| Transaction Date | Date of purchase |
+| Merchant Name | Vendor / store name |
+| Amount | Transaction amount |
+| Currency | Transaction currency |
+| Category | Auto-categorized (fuel, meals, lodging, etc.) |
+| Status | Pending / Accepted / Rejected |
+| Project Link | Autotask ticket / PO number |
+
+---
+
+### Feature 3: Receipt Management
+
+**Source:** Synology NAS photo library + Work email
+
+#### 3A — Photo Receipts (Synology)
+
+##### Description
+Receipt photos stored on Synology NAS are scanned, and relevant data is extracted using OCR. Receipt date is cross-referenced with photo EXIF data (receipt date takes priority). Receipts are matched to the corresponding calendar day and linked to expense entries.
+
+##### Capabilities
+- Connect to Synology NAS via API or mapped folder
+- Monitor designated receipt folder for new uploads
+- Extract receipt data via EasyOCR (GPU-accelerated, NVIDIA 5080 + CUDA):
+  - Vendor name
+  - Date of purchase
+  - Total amount
+  - Line items (if legible)
+- Cross-reference: Receipt date (primary) vs. EXIF date (secondary)
+- Match receipt to calendar day and existing expense entry
+- Manual override: reassign receipt to different date/expense
+- Preview receipt image inside Odoo calendar/expense view
+
+##### Date Priority Logic
+IF receipt_date extracted by OCR -> use receipt_date
+ELSE IF EXIF date available -> use EXIF date
+ELSE -> flag for manual date assignment
+
+#### 3B — Email Receipts (Hotels / Flights / Car Rentals)
+
+##### Description
+Receipts for hotels, flights, and car rentals are received via work email. These are automatically scanned, parsed, and added to the calendar as travel expense entries.
+
+##### Email Ingestion Method
+Dedicated forwarding email monitored by Odoo via Fetchmail (IMAP).
+Forward hotel/flight/car rental confirmations to a designated address (e.g., receipts@yourdomain).
+Odoo polls this inbox and parses incoming emails automatically.
+
+##### Data Points Captured
+| Field | Description |
+|---|---|
+| Vendor | Hotel / Airline / Car rental company |
+| Confirmation # | Booking reference |
+| Check-in / Check-out | For hotels |
+| Flight dates | Departure / Arrival |
+| Total Amount | Cost of booking |
+| Dates | Matched to calendar |
+
+---
+
+### Feature 4: Daily Work Journal (Calendar Hub)
+
+#### Description
+The Odoo calendar becomes the central hub for all WorkTrace data. Each day displays a consolidated view of:
+- Location stops and travel
+- Time at each location
+- Credit card transactions
+- Receipts (photo + email)
+- Manual time entries (timecard)
+
+#### Capabilities
+- Unified day view: location + expenses + receipts
+- Manual time entry per project/ticket
+- Link any calendar event to an Autotask ticket number
+- Daily summary: total travel distance, total expenses, total hours
+- Notes/comments per day
+- Export day summary to PDF or Excel
+
+---
+
+### Feature 5: Timecard Management
+
+#### Description
+Track hours worked per day, linked to Autotask project ticket numbers. Time entries are auto-suggested from location data (time at client site) and can be manually adjusted.
+
+#### Capabilities
+- Auto-suggest time entries from location stops
+- Manual time entry: project, ticket number, description, hours
+- Daily/weekly timecard view
+- Submit timecard for approval workflow
+- Export timecard (CSV, PDF) for Autotask submission
+
+---
+
+### Feature 6: Project & PO Linking
+
+#### Description
+All expenses, time entries, and receipts can be linked to a project identified by an Autotask ticket number. This organizes all daily activities under their respective projects.
+
+#### Capabilities
+- Autotask ticket number field on all expense/time entries
+- Group expenses and time by ticket/project
+- Per-project expense summary
+- Per-project time summary
+- Future: Direct sync to Autotask via API
+
+---
+
+### Feature 7: Export & Reporting
+
+#### Description
+Once data is organized, export it in formats suitable for submission or external system import.
+
+#### Export Formats
+| Report | Format | Contents |
+|---|---|---|
+| Expense Report | PDF / Excel | All accepted expenses, grouped by project |
+| Timecard | PDF / Excel / CSV | Hours per project per day |
+| Travel Log | PDF | Locations, distances, times |
+| Daily Summary | PDF | Full day: location + expenses + time |
+| Autotask Import | CSV | Future: formatted for Autotask import |
+
+---
+
+## Additional Features Recommended
+
+| Feature | Description |
+|---|---|
+| Mileage Reimbursement | Auto-calculate mileage reimbursement based on IRS standard rate |
+| Per Diem Tracking | Track daily meal/lodging allowances |
+| OCR Confidence Score | Flag low-confidence OCR extractions for manual review |
+| Duplicate Detection | Detect duplicate receipts or transactions |
+| Offline Mode | Queue entries when no internet, sync when back online |
+| Mobile Responsive | Full mobile UI for field use |
+| Notification System | Remind user to review pending transactions daily |
+| Audit Log | Track all changes to expense entries |
+| Manager Approval Workflow | Submit expense reports for manager sign-off |
+| Synology Webhook | Auto-trigger receipt scan when new photo is uploaded |
+
+---
+
+## Future Integration: Autotask (PSA)
+
+> Phase 2 — Out of scope for initial development
+
+- Connect to Autotask REST API
+- Push approved timecards to Autotask tickets
+- Push approved expenses to Autotask expense reports
+- Pull ticket/project list from Autotask for linking
+- Two-way sync: status updates reflected in Odoo
+
+---
+
+## Technical Stack
+
+| Component | Technology |
+|---|---|
+| Backend | Odoo 18 (Python) |
+| Frontend | OWL (Odoo Web Library) |
+| Geocoding | OpenStreetMap Nominatim (free, no API key required) |
+| OCR | EasyOCR (GPU-accelerated via CUDA, NVIDIA 5080) |
+| Email Ingestion | Odoo Fetchmail (IMAP) — dedicated forwarding address |
+| Synology Integration | Synology NAS API / DSM |
+| Map View | Leaflet.js + OpenStreetMap tiles |
+| Export | QWeb PDF / xlsxwriter |
+
+---
+
+## Data Flow Diagram
+
+[Google Timeline] ──────────────────┐
+[Citi Card Statement] ───────────── │
+[Synology Receipt Photos] ──────── ►│ WorkTrace Module ──► [Odoo Calendar]
+[Work Email Receipts] ──────────── │                  ──► [Expense Entries]
+[Manual Time Entry] ────────────── ┘                  ──► [Timecard]
+                                                       ──► [Export / Reports]
+                                                       ──► [Autotask (Phase 2)]
+
+---
+
+## Module Structure (Planned)
+
+work_trace/
+├── __init__.py
+├── __manifest__.py
+├── models/
+│   ├── wt_location_log.py
+│   ├── wt_expense_entry.py
+│   ├── wt_receipt.py
+│   ├── wt_timecard.py
+│   └── wt_project_link.py
+├── views/
+│   ├── wt_calendar_view.xml
+│   ├── wt_location_log_views.xml
+│   ├── wt_expense_entry_views.xml
+│   ├── wt_receipt_views.xml
+│   └── wt_timecard_views.xml
+├── wizards/
+│   ├── wt_import_timeline_wizard.py
+│   ├── wt_import_statement_wizard.py
+│   └── wt_export_report_wizard.py
+├── static/
+│   └── description/
+│       └── icon.png
+├── security/
+│   └── ir.model.access.csv
+├── data/
+│   └── wt_data.xml
+└── README.md
+
+---
+
+## Development Phases
+
+### Phase 1 — Core Foundation
+- [ ] Module scaffold and manifest
+- [ ] Location log model + Google Timeline import
+- [ ] Geocoding (coordinates → address)
+- [ ] Basic calendar integration
+
+### Phase 2 — Expenses
+- [ ] Credit card statement import (Citi)
+- [ ] Transaction review workflow
+- [ ] Expense entry model
+
+### Phase 3 — Receipts
+- [ ] Synology NAS connection
+- [ ] OCR receipt extraction (EasyOCR + GPU)
+- [ ] Email receipt ingestion (Fetchmail)
+- [ ] Receipt matching to expenses
+
+### Phase 4 — Timecard & Projects
+- [ ] Timecard model
+- [ ] Autotask ticket number linking
+- [ ] Project-based grouping
+
+### Phase 5 — Export & Reporting
+- [ ] PDF/Excel export
+- [ ] Expense report generation
+- [ ] Timecard export
+
+### Phase 6 — Autotask Integration (Future)
+- [ ] Autotask REST API connection
+- [ ] Timecard push
+- [ ] Expense push
+- [ ] Ticket/project pull
+
+---
+
+*Generated: 2026-03-13*
+*Status: Planning*