first commit

TESTING.md

@@ -0,0 +1,139 @@
+# PostfixAdmin-RS 0.0.1-dev - test checklist
+
+## 1. Static / compiler gate
+
+Run on Rust 1.99.1:
+
+```bash
+cargo fmt --check
+cargo check --all-targets
+cargo test --all-targets
+cargo clippy --all-targets -- -D warnings
+```
+
+Then start the isolated development database:
+
+```bash
+POSTFIXADMIN_RS_DEV_RESET=1 bash dev.sh
+```
+
+Expected test accounts are printed by `dev.sh`.
+
+## 2. UI / i18n
+
+- Login page starts in English when there is no `pa_language` value in localStorage.
+- Language selector is available on login and in the top bar.
+- Switching EN <-> PL does not log the user out and reloads the current page.
+- API endpoints and JSON error payloads remain English.
+- Theme selector still works independently of the language selector.
+- Forms, confirmations and prompts use application modals, not browser `prompt/confirm` dialogs.
+
+## 3. Mock DB regression
+
+As global admin test: domains, mailboxes, aliases, alias domains, admins, fetchmail, DKIM, TOTP/application passwords and logs. Verify permission restrictions with domain-admin and mailbox-user test accounts.
+
+## 4. Production DB through SSH - read-only first
+
+```bash
+cp .env.example .env
+$EDITOR .env
+bash dev.sh
+```
+
+`.env.example` is prefilled for `host.linuxiarz.pl`; set the SSH username and database password before starting. SSH mode forces `database.read_only=true` unless `POSTFIXADMIN_RS_DEV_DB_WRITES=1` is explicitly set.
+
+In read-only mode verify:
+
+- login for global admin, domain admin and mailbox user,
+- domain/mailbox/alias lists,
+- quota/status fields,
+- schema warnings and password scheme detection,
+- fetchmail/vacation/DKIM list pages that exist in the production schema,
+- every write attempt returns an English API error and does not alter data.
+
+Do not enable writes until a database backup exists and a dedicated test domain/account has been selected.
+
+## 5. Production DB write test
+
+Only after backup:
+
+```bash
+POSTFIXADMIN_RS_DEV_DB_MODE=ssh POSTFIXADMIN_RS_DEV_DB_WRITES=1 bash dev.sh
+```
+
+Use a dedicated test domain. Exercise create/update/delete for one domain, mailbox and alias; verify Postfix/Dovecot behaviour and the PostfixAdmin log table. Do not change `password.scheme` during this test.
+
+
+## Mailbox-user regression
+
+Zaloguj sie jako mailbox-user i sprawdz:
+
+- nawigacja nie pokazuje Domains, Mailboxes, Administrators, Logs, Broadcast ani System; DKIM moze byc widoczny tylko jako read-only, gdy istnieje backend DKIM i `[dkim].user_read_only=true`;
+- Overview nie pokazuje panelu `Enabled modules`, tylko dane wlasnej skrzynki, self-alias i quota progress;
+- `/mailboxes` zwraca tylko zalogowana skrzynke, a `/aliases` tylko jej self-alias;
+- Aliases pokazuje domene jako read-only i nie pozwala zmienic adresu/domeny;
+- Security od razu pokazuje formularz zmiany hasla, bez technicznego opisu cookies/CSRF;
+- Vacation pokazuje formularz wlasnego autorespondera tylko gdy `features.vacation=true` i `vacation_control=true`;
+- Filters pojawia sie tylko gdy `[sieve].enabled=true`;
+- DKIM usera pokazuje tylko rekordy jego domeny, z pelnym `selector._domainkey.domain IN TXT "..."`, bez klucza prywatnego i bez akcji zapisu.
+
+ManageSieve mozna przetestowac przez ten sam SSH host bez IMAP:
+
+```bash
+POSTFIXADMIN_RS_DEV_DB_MODE=ssh \
+POSTFIXADMIN_RS_DEV_SIEVE_ENABLED=true \
+bash dev.sh
+```
+
+W tym samym trybie `dev.sh` domyslnie synchronizuje publiczne rekordy Rspamd DKIM przez SSH. Prywatne klucze pozostaja na serwerze. W logu startowym oczekuj linii `DKIM: Rspamd public DNS records synced over SSH`.
+
+Pierwszy test Sieve pozostaw read-only. Do PUT/DELETE/activate dodaj dopiero po wyborze konta testowego:
+
+```bash
+POSTFIXADMIN_RS_DEV_SIEVE_WRITES=1
+```
+
+Sprawdz list/get/check, a nastepnie create/save/activate/rename/delete. Po zmianie hasla w Security ponownie sprawdz Sieve w tej samej sesji.
+
+## 6. Rspamd DKIM
+
+Test first with the development mock. On the mail host test `rspamadm configtest`, generation/adoption, DNS TXT display, mapping updates and reload. Keep a backup of `dkim_signing.conf` and existing key files.
+
+## Current readiness
+
+The source tree contains development mock coverage and a guarded production-DB tunnel path. It should be treated as **test-ready, not production-ready**, until the compiler/test/clippy gate above passes on Rust 1.99.1 and the production schema has completed the read-only regression checklist.
+
+## MySQL/MariaDB through sqlx::Any
+
+PostfixAdmin commonly stores boolean flags such as `active`, `superadmin`,
+`backupmx`, `smtp_active`, Fetchmail SSL flags and Vacation state as
+`TINYINT(1)`. SQLx `Any` does not map MySQL `TINY` result metadata directly.
+PostfixAdmin-RS therefore casts these flags to a portable signed integer in
+SELECT projections before decoding them.
+
+If a test build reports `Any driver does not support MySql type ... Tiny`,
+include the failing endpoint and SQL-related log line in the bug report; raw
+flag columns must not be selected without the normalization helper.
+
+## UI and quota checks
+
+- Switch domains in Mailboxes and Aliases: a top loading bar and spinner must be visible while requests are in flight.
+- Mailbox quota renders a progress bar. When `quota2`/`quota` usage is available it is used as the numerator; otherwise configured mailbox quota is compared with the domain max quota.
+- Medium/high quota thresholds default to 55/90 percent and are configurable under `[defaults]`.
+- Theme icon must render after upgrades; the icon sprite is served under a content-hashed URL.
+
+## Debian package
+
+Run `./scripts/build-deb.sh`. Expected output is `packages/postfixadmin-rs_0.0.1~dev_<arch>.deb` plus `.sha256`. Install on a disposable Debian-compatible host first and configure `/etc/postfixadmin-rs/config.toml` before enabling the service. Verify `getent passwd postfixadmin`, `systemctl cat postfixadmin-rs` (User/Group must be `postfixadmin`), and permissions `root:postfixadmin 0640` on the config file.
+
+## Local Rust quality gate
+
+Run this before packaging or committing changes:
+
+```bash
+./scripts/quality.sh
+```
+
+It formats the Rust sources first, then runs `cargo check`, `cargo test`, and
+`cargo clippy --all-targets -- -D warnings`. The Debian builder runs the same
+format/test/lint sequence inside its writable Docker worktree.