102 lines
3.9 KiB
Markdown
102 lines
3.9 KiB
Markdown
# Mailshot Top-Level Requirements
|
|
|
|
## Document Context
|
|
|
|
This document is governed by `requirements/environment.md` and must be interpreted with that baseline in scope.
|
|
|
|
## Purpose
|
|
|
|
Define the migration goals for delivering the Mailshot feature as a WordPress plugin capability in this repository, replacing the prior Node.js server/front-end implementation approach.
|
|
|
|
## Inputs
|
|
|
|
Primary input specifications:
|
|
|
|
- `../feca2-app/requirements/mailshot.md`
|
|
- `../feca2-app/requirements/mailshot_data_source.md`
|
|
|
|
Local governing baseline:
|
|
|
|
- `requirements/environment.md`
|
|
- `requirements/test_environments.md`
|
|
|
|
## Migration Direction
|
|
|
|
1. Re-platform
|
|
- Move from the `feca2-app` Node.js runtime model to a WordPress plugin runtime model in this workspace.
|
|
- Preserve business intent of the mailshot feature while adapting implementation to WordPress/PHP architecture.
|
|
|
|
2. Source-of-truth shift
|
|
- Remove support for local database entities used previously as source-of-truth for mailshot data:
|
|
- issue
|
|
- page
|
|
- article
|
|
- advertiser
|
|
- ads
|
|
- Do not keep compatibility fallbacks for these local entities unless explicitly required later.
|
|
|
|
3. Data access model
|
|
- Access accounts, contacts, and renewals directly from the remote WordPress-side database environment.
|
|
- Remove dependency on local replicated data for those entities.
|
|
|
|
4. Mailshot persistence
|
|
- Create a dedicated database on the remote server to hold mailshot-specific tables and assets.
|
|
- Treat this remote mailshot database as authoritative for mailshot definitions/assets in the plugin implementation.
|
|
|
|
## Environment and Testing Goals
|
|
|
|
1. Remote data path in testing
|
|
- During testing, access remote database data via SSH tunnel.
|
|
- Test environments must explicitly show tunnel configuration and expected connectivity validation.
|
|
|
|
2. Verification scope
|
|
- Validate read access for accounts, contacts, and renewals from remote source.
|
|
- Validate read/write access for mailshot tables/assets in the new remote mailshot database.
|
|
- Validate that removed local-domain sources (issue/page/article/advertiser/ads) are not required by the migrated flow.
|
|
|
|
## Access Control Policy
|
|
|
|
1. Plugin settings access
|
|
- The plugin Setup/settings page is administrator-only.
|
|
- WordPress capability required: `manage_options`.
|
|
|
|
2. Operational feature access
|
|
- WordPress editors (and administrators) must be able to use all non-setup mailshot features.
|
|
- This includes full CRUD where available for:
|
|
- data sources
|
|
- mailshots
|
|
- attachments
|
|
- PDF assets
|
|
- Baseline WordPress capability for operational pages/endpoints: `edit_pages`.
|
|
|
|
## Research Outcomes (2026-04-20)
|
|
|
|
1. PDF engine suitability (`dompdf`)
|
|
- Outcome: **Accepted: suitable with constraints**.
|
|
- Decision basis is recorded in:
|
|
- `results/dompdf_investigation_findings_2026-04-20.md`
|
|
- Accepted constraint:
|
|
- non-appearing special characters are currently acceptable.
|
|
|
|
2. Nunjucks replacement
|
|
- Outcome: **Twig selected** as the PHP-side replacement direction.
|
|
- Decision basis is recorded in:
|
|
- `results/nunjucks_replacement_findings_2026-04-20.md`
|
|
- Template policy decision:
|
|
- use a minimal-helper approach;
|
|
- prefer inline template logic (for example `{% if x is not empty %}...{% endif %}`);
|
|
- avoid introducing helper functions unless explicitly required.
|
|
|
|
## Deliverables from This Requirement
|
|
|
|
1. Confirmed architecture decision for remote-only data access (accounts/contacts/renewals).
|
|
2. Confirmed plan for remote mailshot database creation and usage.
|
|
3. Research findings for `dompdf` viability and decision outcome.
|
|
4. Research findings for Nunjucks replacement and decision outcome.
|
|
|
|
## Out of Scope (Current Top-Level Phase)
|
|
|
|
- Detailed schema definitions for the new remote mailshot database.
|
|
- Full page-by-page UI requirements rewrite.
|
|
- Full implementation of the selected rendering/template stack.
|