Add migration plan for WASM-based PDF editor component
A detailed migration plan has been added to replace the DevExpress PDF viewer in `EnvelopeSenderEditorPage.razor` with a new WebAssembly (WASM)-based PDF editor component. The plan outlines the scope, constraints, and implementation strategy, ensuring feature parity, backend compatibility, and minimal disruption to the existing user experience. Key decisions include creating a reusable `SenderPdfImageEditor` component, using server-side PDF rasterization, and removing `esid` and `IMemoryCache`-based session persistence. The document also defines testing and acceptance criteria to verify the migration's success, focusing on visual fidelity, functionality, and backend contract consistency.
This commit is contained in:
212
SENDER_EDITOR_WASM_PDF_EDITOR_IMPLEMENTATION_PLAN_en.md
Normal file
212
SENDER_EDITOR_WASM_PDF_EDITOR_IMPLEMENTATION_PLAN_en.md
Normal file
@@ -0,0 +1,212 @@
|
||||
# Sender Editor PDF Component Migration Plan
|
||||
|
||||
This plan is prepared to remove the DevExpress PDF viewer dependency from `EnvelopeGenerator.Server/EnvelopeGenerator.Server/Components/Pages/EnvelopeSenderEditorPage.razor` and move to a new WASM-based PDF editor component while preserving the current page design.
|
||||
|
||||
## 0) Scope and Non-Negotiable Rules
|
||||
|
||||
- **Scope**: Only the PDF editor/viewer area will change; the page action bar, popups, receiver management, and overall visual language must remain intact.
|
||||
- **Render mode target**: The `/sender/editor` flow will be implemented in `EnvelopeGenerator.Server.Client` and run in WebAssembly.
|
||||
- **Data compatibility**: The final `CreateEnvelopeCommand` payload shape, field units (`X`, `Y` in inches), receiver-field mapping, and save/send behavior must stay unchanged.
|
||||
- **To be removed**: `esid` query param + `IMemoryCache`-based editor session persistence will be removed completely.
|
||||
- **Library constraint**: `pdf.js` and DevExpress PDF viewer will not be used. For PDF rasterization, first verify whether DevExpress provides a suitable capability; if not, use a reliable, popular MIT-licensed alternative.
|
||||
- **Server-side pattern rule**: All new server-side work must follow the existing architecture; **Clean Architecture layers** and **MediatR pattern** must be preserved.
|
||||
- **Language rule (code side)**: All code and any code comments must always be in English.
|
||||
|
||||
---
|
||||
|
||||
## 1) Current Behavior Inventory (Parity Baseline)
|
||||
|
||||
**Goal:** Lock down all behaviors that must not break after migration.
|
||||
|
||||
**Tasks**
|
||||
- List the current editor flow:
|
||||
- PDF upload,
|
||||
- receiver add,
|
||||
- signature field placement,
|
||||
- field clearing,
|
||||
- draft save,
|
||||
- send.
|
||||
- Clarify current coordinate conversion:
|
||||
- Viewer click -> PDF points,
|
||||
- Save payload -> inches (`pt / 72`).
|
||||
- Capture current validation messages and popup behavior.
|
||||
- During this inventory phase, continuously add findings into this markdown under the relevant sections so it remains a living document.
|
||||
|
||||
**Output**
|
||||
- A short “parity checklist” is prepared and used throughout development.
|
||||
|
||||
---
|
||||
|
||||
## 2) Architecture Decisions and Packaging
|
||||
|
||||
**Goal:** Define technical boundaries of the new solution.
|
||||
|
||||
**Tasks**
|
||||
- Define the new reusable component:
|
||||
- Suggested name: `SenderPdfImageEditor`.
|
||||
- Location: `EnvelopeGenerator.Server/EnvelopeGenerator.Server.Client/Components/PdfEditor/`.
|
||||
- Define PDF rasterization strategy:
|
||||
- Convert PDF -> image pages on the server side.
|
||||
- First confirm whether this conversion is possible with DevExpress.
|
||||
- If DevExpress does not provide a suitable solution, choose a popular MIT-licensed engine (e.g., `Docnet.Core` / PDFium-based).
|
||||
- Document license validation and production suitability.
|
||||
- Draft API contract:
|
||||
- endpoint(s) returning page images after PDF upload/read,
|
||||
- page metadata (width/height in pt),
|
||||
- optional re-raster endpoint for higher zoom levels.
|
||||
|
||||
**Output**
|
||||
- “Component contract + API contract” is finalized.
|
||||
|
||||
---
|
||||
|
||||
## 3) Copy `/sender/editor` to WASM Page
|
||||
|
||||
**Goal:** Run the editor in `Server.Client` using SPA behavior.
|
||||
|
||||
**Tasks**
|
||||
- Create a new page:
|
||||
- `EnvelopeGenerator.Server/EnvelopeGenerator.Server.Client/Pages/EnvelopeSenderEditorPage.razor`
|
||||
- Temporary route: `/sender/editor2`
|
||||
- Keep the existing server-side `/sender/editor` page during development; both pages run in parallel.
|
||||
- Copy existing toolbar/receiver/popup markup as-is as much as possible.
|
||||
- Integrate client services (`EnvelopeService`, auth checks, receiver suggestion calls).
|
||||
|
||||
**Output**
|
||||
- WASM page is accessible, old UI layout is preserved, and PDF area works with a placeholder component.
|
||||
|
||||
---
|
||||
|
||||
## 4) Page-by-Page PDF to Image Conversion Service (With Priority Order)
|
||||
|
||||
**Goal:** Convert PDF into page-image list with near-identical visual fidelity.
|
||||
|
||||
**Tasks**
|
||||
- Add new application/service layer:
|
||||
- PDF bytes input,
|
||||
- raster output per page (PNG preferred for stable quality/transparency).
|
||||
- Evaluate client-side (WASM) rasterization feasibility if it is possible and does not hurt performance.
|
||||
- Priority order:
|
||||
1. DevExpress feasibility,
|
||||
2. If not suitable, MIT-licensed alternative,
|
||||
3. If needed, client-side rasterization option.
|
||||
- Return metadata:
|
||||
- page index,
|
||||
- image URL or base64,
|
||||
- page width/height (pt),
|
||||
- native image size in px.
|
||||
- Performance:
|
||||
- reasonable initial DPI (e.g., 144),
|
||||
- lazy/high-res render option for higher zoom levels.
|
||||
|
||||
**Output**
|
||||
- “PDF -> image pages + page metrics” endpoint/service is functional.
|
||||
|
||||
---
|
||||
|
||||
## 5) New Image-based PDF Viewer Features
|
||||
|
||||
**Goal:** Provide viewer UX similar to DevExpress viewer.
|
||||
|
||||
**Tasks**
|
||||
- Implement two display modes in `SenderPdfImageEditor`:
|
||||
- **Continuous mode**: pages stacked vertically,
|
||||
- **Single-page mode**: one page with next/prev navigation.
|
||||
- Add zoom controls:
|
||||
- zoom in/out,
|
||||
- fit width,
|
||||
- fit page.
|
||||
- Add page navigation:
|
||||
- page selector (n / total),
|
||||
- keyboard shortcuts (optional, phase 2).
|
||||
- Preserve UI consistency:
|
||||
- keep current sender editor color language and button style.
|
||||
|
||||
**Output**
|
||||
- Image-based viewer is fully functional.
|
||||
|
||||
---
|
||||
|
||||
## 6) Signature Field Management via DOM Overlay
|
||||
|
||||
**Goal:** Manage signature fields in a movable DOM layer instead of burning them into PDF bytes.
|
||||
|
||||
**Tasks**
|
||||
- Place an overlay layer on top of each page image.
|
||||
- Signature box lifecycle:
|
||||
- add (by click),
|
||||
- drag (move),
|
||||
- remove.
|
||||
- Normalize all interactions as page-relative coordinates.
|
||||
- Rendering:
|
||||
- receiver color,
|
||||
- receiver name,
|
||||
- box/badge style close to current placeholder visuals.
|
||||
- Preserve multi-receiver / multi-field support and receiver-field linkage.
|
||||
|
||||
**Output**
|
||||
- Users can move and delete each signature field independently.
|
||||
|
||||
---
|
||||
|
||||
## 7) Coordinate and Payload Parity (Critical)
|
||||
|
||||
**Goal:** Keep backend data type/unit behavior exactly unchanged.
|
||||
|
||||
**Tasks**
|
||||
- Convert overlay coordinates -> PDF points:
|
||||
- `xPt = normalizedX * pageWidthPt`
|
||||
- `yPt = normalizedY * pageHeightPt`
|
||||
- Keep points -> inches conversion on save/send:
|
||||
- `X = xPt / 72`, `Y = yPt / 72`.
|
||||
- Use the same DTO shape in `CreateEnvelopeCommand`.
|
||||
- Keep existing validation rules unchanged.
|
||||
|
||||
**Output**
|
||||
- Full backend contract parity with the old system.
|
||||
|
||||
---
|
||||
|
||||
## 8) Remove Session Cache Logic
|
||||
|
||||
**Goal:** Fully remove `esid` and memory cache dependency.
|
||||
|
||||
**Tasks**
|
||||
- Remove `SupplyParameterFromQuery(Name = "esid")`.
|
||||
- Remove `IMemoryCache` injection and `PersistSession` flow.
|
||||
- Manage editor state using component state + loaded envelope data only.
|
||||
- Clarify reset behavior after successful save/send.
|
||||
|
||||
**Output**
|
||||
- Session-id-based cache layer is removed completely.
|
||||
|
||||
---
|
||||
|
||||
## 9) Testing and Acceptance Criteria
|
||||
|
||||
**Goal:** Verify migration is complete and safe.
|
||||
|
||||
**Critical manual tests**
|
||||
- PDF upload -> are pages visually accurate?
|
||||
- Continuous/single-page mode transitions work correctly?
|
||||
- Overlay boxes keep correct position across zoom levels?
|
||||
- Add/drag/remove works stably on all pages?
|
||||
- Draft save and send payload format remains identical?
|
||||
- In edit mode (existing envelope), fields load and remain editable?
|
||||
|
||||
**Definition of done**
|
||||
- DevExpress PDF viewer is fully removed from the editor.
|
||||
- Users can edit signature box positions after placing them.
|
||||
- Backend contract and coordinate units remain unchanged.
|
||||
|
||||
---
|
||||
|
||||
## 10) Suggested Implementation Sequence (Short Sprint Plan)
|
||||
|
||||
1. **WASM page copy + route stabilization**
|
||||
2. **PDF raster API + renderer integration**
|
||||
3. **Image viewer (zoom + navigation + modes)**
|
||||
4. **Overlay signature layer (add/drag/remove)**
|
||||
5. **Save/Send payload parity verification**
|
||||
6. **Session/cache removal cleanup**
|
||||
7. **End-to-end testing and UI polish**
|
||||
Reference in New Issue
Block a user