fix(merge): resolve conflicts with main v0.92.0 keeping path-param regression tests

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
2026-03-08 11:19:22 +00:00
parent c31b72810e
commit 2d754d52ef
22 changed files with 2256 additions and 122 deletions
@@ -844,6 +844,131 @@ problem.

 ---

+**GET** `/api/admin/users/local`
+
+List all local (email/password) user accounts with basic metadata.
+
+---
+
+**POST** `/api/admin/users/local`
+
+Create a new local user account (admin-only, immediately active — no email verification required).
+
+**Request body**:
+```json
+{
+  "email": "user@example.com",
+  "username": "alice",
+  "display_name": "Alice Smith",
+  "password": "securepassword",
+  "is_admin": false
+}
+```
+
+---
+
+**PATCH** `/api/admin/users/local/{local_user_id}`
+
+Update an existing local user account. Only the provided (non-null) fields are modified.
+If the email is changed, the associated `UserProfile.user_id` is also updated automatically.
+
+**Request body** (all fields optional):
+```json
+{
+  "email": "newemail@example.com",
+  "display_name": "Alice Wonderland",
+  "is_admin": true,
+  "is_active": false
+}
+```
+
+**Error Responses**:
+- `404`: Local user not found
+- `409`: New email already taken by another account
+
+---
+
+**POST** `/api/admin/users/local/{local_user_id}/send-password-reset`
+
+Send a password reset email to a local user on their behalf. Useful when a user is locked out.
+Returns `{"sent": true}` on success or `{"sent": false, "reason": "..."}` when SMTP is not
+configured or sending fails (never returns an error status so the admin always gets feedback).
+
+**Error Responses**:
+- `404`: Local user not found
+
+---
+
+**POST** `/api/admin/users/local/{local_user_id}/set-password`
+
+Directly set a new password for a local user without requiring an email token (last resort when
+email delivery is unavailable). The user should be advised to change their password after logging in.
+
+**Request body**:
+```json
+{
+  "password": "temporarypassword"
+}
+```
+
+**Error Responses**:
+- `404`: Local user not found
+- `422`: Password shorter than 8 characters
+
+---
+
+**DELETE** `/api/admin/users/local/{local_user_id}`
+
+Delete a local user account by numeric ID. The associated `UserProfile` is also removed. Documents
+owned by this user are **not** deleted. Returns `204 No Content` on success.
+
+---
+
+### Local Authentication (self-service)
+
+These endpoints are for local (email/password) users and do not require authentication.
+
+**POST** `/api/auth/request-password-reset`
+
+Send a password reset email. Always returns 200 to avoid leaking whether an email is registered.
+
+**Request body**:
+```json
+{ "email": "user@example.com" }
+```
+
+---
+
+**POST** `/api/auth/reset-password`
+
+Set a new password using a valid reset token (received via email).
+
+**Request body**:
+```json
+{
+  "token": "the-token-from-email",
+  "new_password": "newpassword",
+  "new_password_confirm": "newpassword"
+}
+```
+
+**Error Responses**:
+- `400`: Token is invalid or expired
+- `422`: Passwords do not match
+
+---
+
+**POST** `/api/auth/forgot-username`
+
+Send a username reminder email. Always returns 200 to avoid leaking whether an email is registered.
+
+**Request body**:
+```json
+{ "email": "user@example.com" }
+```
+
+---
+
 ### Settings Suggestions (Autocomplete)

 **GET** `/api/settings/{key}/suggestions`
@@ -1056,9 +1056,13 @@ Webhook URLs, secrets, and subscribed events are configured per-webhook via the

 ### Backup & Restore

-DocuElevate can automatically back up the SQLite database on a scheduled basis.
+DocuElevate automatically backs up the database on a scheduled basis.
 Backups are managed from the **Admin → Backup & Restore** dashboard.

+Supported database backends: **SQLite** (`.db.gz`), **PostgreSQL** (`.pgsql.gz`), **MySQL / MariaDB** (`.mysql.gz`).
+For PostgreSQL and MySQL backups the respective CLI client (`pg_dump` / `psql` or `mysqldump` / `mysql`) must be installed on the Celery worker host.
+See the [Database Configuration Guide](DatabaseConfiguration.md#backup-procedures) for setup details.
+
 | **Variable**                   | **Description**                                                                               | **Default**         |
 |--------------------------------|-----------------------------------------------------------------------------------------------|---------------------|
 | `BACKUP_ENABLED`               | Enable or disable automatic scheduled backups (`True`/`False`).                              | `True`              |
@@ -341,29 +341,91 @@ Disable `prepared_statements` when using PgBouncer in transaction mode.

 ## Backup Procedures

-### PostgreSQL
+DocuElevate's built-in **Backup & Restore** feature (Admin → Backup & Restore) supports all three
+database backends natively, using the native dump tools of each database.

-**Manual backup:**
+| Backend        | Backup tool  | Archive extension | Restore tool |
+|----------------|--------------|-------------------|--------------|
+| SQLite         | `sqlite3` (built-in Python) | `.db.gz`    | `sqlite3` (built-in Python) |
+| PostgreSQL     | `pg_dump`    | `.pgsql.gz`       | `psql`       |
+| MySQL/MariaDB  | `mysqldump`  | `.mysql.gz`       | `mysql`      |
+
+Passwords are passed via the `PGPASSWORD` (PostgreSQL) and `MYSQL_PWD` (MySQL) environment
+variables so they are never exposed on the process command line.
+
+### Prerequisites
+
+For PostgreSQL and MySQL backups the corresponding CLI client must be installed on the
+worker host (the container / server that runs Celery workers):
+
+```bash
+# PostgreSQL clients (Debian/Ubuntu)
+apt-get install -y postgresql-client
+
+# MySQL clients (Debian/Ubuntu)
+apt-get install -y default-mysql-client
+```
+
+The binaries required are:
+
+- **PostgreSQL**: `pg_dump` (backup) and `psql` (restore)
+- **MySQL / MariaDB**: `mysqldump` (backup) and `mysql` (restore)
+
+### Using the Admin Dashboard
+
+Navigate to **Admin → Backup & Restore** to:
+
+- Trigger manual backups (hourly / daily / weekly)
+- Download backup archives
+- Upload and restore a backup archive
+- Configure retention and remote storage destinations
+
+### PostgreSQL – manual backup/restore
+
+**Manual backup using DocuElevate's archive format (for use with the UI restore):**
+
+```bash
+pg_dump --format=plain --no-password \
+  -h localhost -U docuelevate docuelevate \
+  | gzip > docuelevate_$(date +%Y%m%d_%H%M).pgsql.gz
+```
+
+**Restore via the DocuElevate UI:**  upload the `.pgsql.gz` file on the Backup & Restore page.
+
+**Manual restore using native tools (custom format):**

 ```bash
 pg_dump -h localhost -U docuelevate -F c docuelevate > docuelevate_$(date +%Y%m%d_%H%M).dump
-```
-
-**Restore:**
-
-```bash
 pg_restore -h localhost -U docuelevate -d docuelevate docuelevate_20240101_1200.dump
 ```

 **Automated daily backup (cron example):**

 ```cron
-0 2 * * * pg_dump -h localhost -U docuelevate -F c docuelevate | gzip > /backups/docuelevate_$(date +\%Y\%m\%d).dump.gz
+0 2 * * * pg_dump --format=plain -h localhost -U docuelevate docuelevate | gzip > /backups/docuelevate_$(date +\%Y\%m\%d).pgsql.gz
 ```

 Use your cloud provider's automated backup feature when available (e.g., RDS automated snapshots, Cloud SQL backups).

-### SQLite
+### MySQL / MariaDB – manual backup/restore
+
+**Manual backup using DocuElevate's archive format (for use with the UI restore):**
+
+```bash
+MYSQL_PWD=yourpassword mysqldump --single-transaction --routines --triggers \
+  -h localhost -u docuelevate docuelevate \
+  | gzip > docuelevate_$(date +%Y%m%d_%H%M).mysql.gz
+```
+
+**Restore via the DocuElevate UI:**  upload the `.mysql.gz` file on the Backup & Restore page.
+
+**Manual restore using native tools:**
+
+```bash
+gunzip -c docuelevate_20240101_1200.mysql.gz | mysql -h localhost -u docuelevate -p docuelevate
+```
+
+### SQLite – manual backup/restore

 ```bash
 # Stop the application first, or use SQLite's online backup API
@@ -28,8 +28,29 @@ If OpenID Connect authentication is configured:
 3. Log in with your existing credentials on that platform
 4. You'll be redirected back to DocuElevate after successful authentication

-#### User Sessions
- Once authenticated, your session will remain active until you log out or it expires
+#### Local User Accounts
+If your administrator has created a local (email/password) account for you:
+
+1. You'll see a "Sign in with username" form on the login page
+2. Enter your **username or email address** — both are accepted
+3. Enter your password and click **Sign in**
+
+##### Forgot your password?
+If you can't remember your password:
+1. Click **Forgot password?** below the sign-in form
+2. Enter your email address and click **Send reset link**
+3. Check your inbox for a password reset email (valid for 24 hours)
+4. Click the link in the email and enter your new password
+
+##### Forgot your username?
+If you can't remember your username:
+1. Click **Forgot username?** below the sign-in form
+2. Enter your email address and click **Send username reminder**
+3. You'll receive an email with your username
+
+> **Tip:** You can always sign in with your email address directly — you don't need to look up your username.
+
+
 - Click the "Logout" button in the top navigation bar to end your session
 - For security, sessions automatically expire after a period of inactivity