diff --git a/.cursorrules b/.cursorrules new file mode 100644 index 0000000..1cf4eb4 --- /dev/null +++ b/.cursorrules @@ -0,0 +1,131 @@ +# Project Rules for AI Assistants + +This file contains project-specific guidance for AI assistants working on the Job-List application. + +## Field Handling Guidelines + +### Date/Time Handling + +**Storage Format (PocketBase Database):** +- All date/time fields must be stored as **ISO 8601 UTC format** +- Example: `2025-12-21T18:30:00.000Z` +- **Null dates**: Use sentinel value `1900-01-01T00:00:00.000Z` to represent null/empty dates + +**Display Format (Frontend/UI):** +- Timezone: **US Central Standard Time (CST/CDT)** +- Time: **12-hour format** with am/pm (e.g., `6:30 pm`) +- Date: **Short US format** MM/dd/yyyy (e.g., `12/21/2025`) + +**Null/Empty Date Display:** +- Sentinel date (1900-01-01) with **no related note field** → display as **empty/blank** field +- Sentinel date (1900-01-01) with **related note field populated** → display **"See Notes"** + - Example: If `Due_Date` is sentinel and `Due_Date_Notes` has content, show "See Notes" +- Empty frontend field → store as sentinel date (1900-01-01) in PocketBase + +**Date Entry and Normalization:** +- Dates can be entered via **datepicker** (preferred) or **manual text entry** +- Manual entries must be normalized to full MM/dd/yyyy format: + - `1/1` → `01/01/2026` (add year based on logical context) + - `12/1` → `12/01/2025` (use current year if month hasn't passed) +- **Confirmation required** for manual entries: Show prompt "Did you mean MM/dd/yyyy?" before saving +- **Reject invalid dates** with error message explaining: + - Invalid format or date that doesn't fit normalization logic + - Suggest using related note field for explanations (e.g., `Due_Date_Notes` for `Due_Date`) +- **Validation**: Only allow valid dates OR completely empty - no partial/invalid entries + +**Conversion Rules (Bidirectional):** +- **Frontend → Backend**: Convert user input from CST → ISO UTC before saving to PocketBase +- **Backend → Frontend**: Convert PocketBase UTC data → CST for display (or "See Notes" for sentinel with notes) +- **Updates**: Any date/time change from either frontend or backend must trigger conversion and sync to maintain consistency across the application + +### Boolean Field Handling + +**Storage Format (PocketBase Database):** +- Stored as boolean values: `true` or `false` +- `null` values must be converted to `false` + +**Display Format (Frontend/UI):** +- Rendered as checkboxes +- Checked = `true` +- Unchecked = `false` + +**Conversion Rules (Bidirectional):** +- **Frontend → Backend**: Checkbox state (checked/unchecked) → boolean (`true`/`false`) → stored in PocketBase +- **Backend → Frontend**: PocketBase boolean value → checkbox state (checked/unchecked) +- **Updates**: Any change to checkbox state or boolean value must sync bidirectionally to maintain consistency + +### Calculated Fields + +#### Active Field (Boolean - Read-Only) + +**Trigger:** +- Automatically calculated when `Job_Status` field changes on the frontend + +**Calculation Logic:** +- `Active` = `true` if `Job_Status` equals any of: + - "Estimating" + - "Est Sent" + - "Est Hold" + - "Follow Up" + - "Awarded" + - "In Progress" + - "Billed In Progress" +- `Active` = `false` for all other `Job_Status` values + +**Frontend Behavior:** +- Display as **read-only** (checkbox or indicator) +- Automatically recalculate whenever `Job_Status` changes +- Sync calculated value to PocketBase after update + +#### Due_Date_Counter Field (Text - Read-Only) + +**Trigger:** +- Automatically calculated when `Due_Date` or `Due_Date_ASAP` field changes on the frontend +- Does NOT recalculate on `Job_Status` changes + +**Calculation Logic:** +1. If `Job_Status` ≠ "Estimating" → **"N/A"** +2. If `Due_Date_ASAP` = true → **"ASAP"** +3. If `Due_Date` is blank/sentinel (1900-01-01) → **blank/empty** +4. If `Due_Date` < Today → **"Passed due"** +5. If `Due_Date` = Today → **"Due today"** +6. Else → Calculate days remaining: **"[X] day"** (singular) or **"[X] days"** (plural) + +**Frontend Behavior:** +- Display as **read-only text field** +- Automatically recalculate whenever `Due_Date` or `Due_Date_ASAP` changes +- Sync calculated value to PocketBase after update + +#### Due_Date_ASAP Field (Boolean) + +**Purpose:** +- Mark jobs as urgent/ASAP with timestamp tracking + +**Behavior When Checked:** +- System automatically sets `Due_Date` to **TODAY's date** (system-generated timestamp) +- `Due_Date` field displays **"ASAP"** +- `Due_Date_Counter` displays **"ASAP"** +- Enables tracking: Days since ASAP was marked using the captured date + +**Behavior When Unchecked:** +- `Due_Date` reverts to blank/sentinel (1900-01-01) or allows manual date entry +- Normal date display and counter calculation resume + +**Design Rationale:** +- **ASAP scenario**: Captures specific timestamp for urgent items requiring immediate attention +- **Blank/No Due Date scenario**: Uses sentinel (1900-01-01) + `created_date` for flexible/TBD timing +- Key difference: ASAP provides explicit urgency tracking vs. general aging for non-urgent items + +## Pending Schema Updates + +**Fields to Add:** +- `Due_Date_Notes` (text field) - Explanatory notes for Due_Date +- `Start_Date_Notes` (text field) - Explanatory notes for Start_Date +- `Due_Date_ASAP` (boolean) - Flag for marking jobs as urgent/ASAP with timestamp tracking + +**Action Items:** +- Review current schema against planned fields +- Identify any other date fields that need corresponding note fields +- Implement field additions in PocketBase +- Update frontend forms and display logic +- Update Due_Date_Counter calculation logic to incorporate Due_Date_ASAP field diff --git a/package.json b/package.json index b832abf..90ef129 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "job-list", - "version": "1.0.0", + "version": "1.0.0-alpha2", "description": "Job-List", "type": "module", "scripts": {