docs: consolidate repository guides and preserve audit history

2026-09-11 14:22:41 +02:00
parent 115441a409
commit 682a3028bb
404 changed files with 3402 additions and 2621 deletions
@@ -0,0 +1,76 @@
+# Smart Gmail Job Correspondence Integration Progress
+
+## Branch
+- main
+
+## Status
+- Core Phase 1 Gmail correspondence feature is now implemented in code.
+- Remaining gap is deployment/runtime rollout on the live host, not missing product logic in this repo.
+
+## Completed
+
+### Foundation
+- Gmail OAuth connect/disconnect/status flow preserved.
+- Durable Gmail sync-state fields added and surfaced from `GET /api/gmail/status`.
+- Per-job correspondence UI shows Gmail sync diagnostics.
+
+### Ingestion and storage
+- Imported Gmail correspondence stores:
+  - direction
+  - Gmail labels JSON
+  - attachment metadata JSON
+- Gmail payload parsing extracts labels and attachment metadata.
+- Message-level deduplication remains in place.
+- Linked-thread refresh continues to import only new thread messages.
+
+### Matching and routing
+- Deterministic scoring extracted to `JobTrackerApi/Services/GmailJobMatchingService.cs`.
+- Review queue backend exists at `GET /api/gmail/review-candidates`.
+- Review decisions persist through `POST /api/gmail/review-decision`.
+- Manual sync now exists at `POST /api/gmail/manual-sync`.
+- Manual sync applies a bounded historical window and excludes spam/trash by default.
+- High-confidence matches now auto-link during manual sync.
+- Medium-confidence matches remain in review.
+- Low-confidence job-like threads can be marked as suggested jobs.
+- Suggested-job surfaces now exist via:
+  - `GET /api/gmail/suggested-jobs`
+  - `POST /api/gmail/create-suggested-job`
+
+### Correspondence UX
+- Global inbox exists at `/correspondence`.
+- Gmail review page exists at `/correspondence/review`.
+- Review page now supports:
+  - manual sync
+  - routing filters
+  - review notes
+  - link/review/reject/suggested actions
+  - create-job flow from suggested Gmail threads
+- Per-job correspondence workspace now supports:
+  - linked-thread refresh
+  - unlink thread from current job
+  - move/relink thread to another existing job
+- Backend relink/unlink endpoints now exist:
+  - `POST /api/gmail/relink-thread`
+  - `POST /api/gmail/unlink-thread`
+
+### Phase 2 prep
+- Future seam remains in place at `JobTrackerApi/Services/GmailCorrespondenceEnrichment.cs`.
+- Design doc remains in place at `docs/gmail-correspondence-phase1.md`.
+
+### Deployment hardening
+- Added deploy smoke-check logic to `deploy/deploy.sh`.
+- Deploy now fails if `${APP_PUBLIC_BASE_URL}/api/auth/config` returns HTML or non-JSON instead of backend auth config JSON.
+
+## Verification completed
+- `dotnet test JobTrackerApi.Tests/JobTrackerApi.Tests.csproj --filter GmailControllerTests /p:DisableSourceControlManagerQueries=true`
+- `cd job-tracker-ui && CI=true ./node_modules/.bin/react-scripts test --runInBand --watch=false src/correspondence-gmail-import.test.tsx src/gmail-review-page.test.tsx src/correspondence-inbox-page.test.tsx`
+- `dotnet build './Job tracker.sln' -c Release`
+
+## Runtime note
+- Live host check shows `https://jobs.cesnimda.uk/api/auth/config` currently returns the frontend HTML shell (`x-powered-by: Express`) instead of backend JSON.
+- That is a deployment/proxy mismatch outside the app code in this checkout.
+- The new deploy smoke-check was added so future deploys fail fast on that condition.
+
+## Resume notes
+- If the live site still shows 404s for `/api/...`, the running service is not the repo’s Dockerized frontend+backend path.
+- The CRA/Express-style live response and websocket attempts to `:3000/ws` suggest an old dev-style frontend process or wrong reverse-proxy target is still serving the domain.