# Form 16 – Submission Status Screen, Alerts, Validations & Versions

This document describes the **submission status screen** shown to the dealer after submitting Form 16A, and related features: alerts, validations, and submission versions.

---

## 1. Submission status screen (post-submit)

**URL (after submit):** `http://localhost:3001/form16/submit/result` (or same path on your host).

**When it appears:** After the dealer uploads Form 16A, OCR extraction runs (Gemini/regex), they correct TAN/deductor if needed, and click **Submit Form 16A**. The app then navigates to this result screen with a status.

### 1.1 Statuses

| Status       | UI label                          | When it happens |
|-------------|------------------------------------|-----------------|
| **success** | Matched & Credit Note Generated    | Form 16A matched 26AS and a credit note was generated. *(Currently backend does not return this at submit time; matching is async. Can be shown when opening the request detail if a credit note exists.)* |
| **mismatch**| Value Mismatch                     | Form 16A details did not match 26AS data. *(Requires backend to perform sync validation and return this.)* |
| **duplicate** | Duplicate Submission             | Same Form 16A (or same dealer + FY + quarter) already submitted. API returns 400 with duplicate message. |
| **error**   | Request Received                   | Submission accepted; request created and is being processed. Shown for every successful `POST /form16/submissions` until sync matching is implemented. |

### 1.2 Process flow (timeline on the screen)

1. **Form 16A Uploaded** – completed once file is uploaded and OCR ran.
2. **Validation** – completed (or failed for duplicate).
3. **26AS Matching** – pending until matching runs; completed on success; failed on mismatch/duplicate.
4. **Credit Note** – pending until a credit note is generated; completed on success.

### 1.3 Actions on result screen

- **Success:** “Back to My Requests”; auto-redirect after 5 seconds.
- **Request Received (error):** “View Request”, “Try Again”, “Back to My Requests”.
- **Duplicate:** “Back to New Submission”, “Back to My Requests”.
- **Mismatch:** “Resubmit Form 16A”, “Back to My Requests”.

State is passed via React Router `location.state` and persisted in `sessionStorage` under `form16_submission_result` so a refresh still shows the result.

---

## 2. Alerts (admin-configured)

Form 16 alerts are driven by **admin config** (e.g. `Form16AdminConfig`). Relevant keys:

| Config key                     | Purpose |
|--------------------------------|---------|
| `alertSubmitForm16Enabled`    | Whether to send “submit Form 16” alerts to dealers. |
| `alertSubmitForm16FrequencyDays`  | Frequency (days) for the alert. |
| `alertSubmitForm16FrequencyHours`| Frequency (hours) for the alert. |
| `alertSubmitForm16Template`   | Message template; placeholders e.g. `[Name]`, `[DueDate]`. |

Notifications (success/failure) use:

- `notificationForm16SuccessCreditNote` – e.g. “Form 16 submitted successfully. Credit note: [CreditNoteRef].”
- `notificationForm16Unsuccessful` – e.g. “Form 16 submission was unsuccessful. Issue: [Issue].”

These are stored in the workflow admin config (e.g. `form16` or `FORM16` config blob) and used by backend/cron for sending alerts and notifications.

---

## 3. Validations

- **Client-side (submit page):**  
  - Financial year and quarter required.  
  - File must be PDF.  
  - TAN and deductor name required (from OCR or manual).  
  - Toast errors if validation fails.

- **Backend (`POST /form16/submissions`):**  
  - Required: `financialYear`, `quarter`, `form16aNumber`, `tanNumber`, `deductorName`.  
  - `tdsAmount` and `totalAmount` must be valid numbers ≥ 0.  
  - Duplicate check: if the backend detects an existing submission (e.g. same certificate or same dealer + FY + quarter), it returns **400** with a message containing “duplicate” or “already exist”; the frontend then shows the **duplicate** status on the result screen.  
  - No synchronous 26AS matching or credit note creation at submit time in the current implementation; validation status is updated asynchronously (e.g. `form16a_submissions.validation_status`).

---

## 4. Submission versions

- **Model:** `form16a_submissions.version` (number; default 1).  
- **Submit payload:** Optional `version` in the create-submission payload (e.g. for “resubmit” or revised certificate).  
- **UI note (Form16Submit):** “If you submit multiple versions for the same quarter, only the latest approved version will be processed.”  
- Version is stored per submission row; business logic (e.g. “latest approved”) is applied when listing or matching (backend / RE views).

---

## 5. Where things live in the repo

| Item | Location |
|------|----------|
| Submission result screen | `src/pages/Form16/components/RequestSubmissionSuccess.tsx` |
| Result page (route + state) | `src/pages/Form16/Form16SubmissionResult.tsx` |
| Submit page (navigate to result) | `src/pages/Form16/Form16Submit.tsx` |
| Status chip / timeline | `src/pages/Form16/components/StatusChip.tsx`, `TimelineStep.tsx` |
| Route | `App.tsx`: `/form16/submit/result` |
| Form 16 config (alerts, notifications) | Backend admin config; frontend `Form16AdminConfig` (e.g. under admin settings). |

---

## 6. Local URL

Form 16 (submit and result) is under the same app; typical local URL:

- Submit: `http://localhost:3001/form16/submit`  
- Result: `http://localhost:3001/form16/submit/result` (after submit or when state is in `sessionStorage`).

Replace `3001` with your frontend port if different.