# 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