# Installation - Sprint 21

## 1. Back up staging

Back up the current Sprint 20 application, database and private storage before applying this release.

## 2. Use this cumulative package

Sprint 21 already contains the cumulative backend and integration files from Sprints 9-20. Do not merge older cumulative ZIPs over it.

## 3. Database

Apply migrations in order through:

```text
database/migrations/015_advanced_reports_exports.sql
```

Then apply:

```text
database/views/015_report_factory_views.sql
database/seeds/015_report_templates.sql
```

Review the seed templates before production import.

## 4. Permissions

Assign these permissions using separation of duties:

- `reports.view`
- `reports.generate`
- `reports.approve`
- `reports.distribute`
- `reports.manage_templates`
- `reports.download`

Do not give one ordinary user every report permission. In particular, report authors should not be the sole approvers.

## 5. Storage

Create and protect:

```text
storage/reports
storage/test-exports
```

Recommended permissions are owner read/write and no public web access. The `public` directory must remain the only portal document root.

## 6. QR generation

The package uses:

```text
tools/qr_matrix.py
tools/vendor/qrcode/
```

Confirm that `python3` is available:

```bash
python3 tools/qr_matrix.py "https://portal.baffoes.com/test"
```

When Python is unavailable, PDF/DOCX/XLSX export still works, but QR images are omitted and hash verification remains available. No external QR service is contacted.

## 7. React integration

Merge:

```text
frontend-integration/src/reports
```

Register:

- `ReportBuilderPage`
- `ReportRunPage`

Add navigation according to user permissions.

## 8. Run tests

```bash
bash tests/lint.sh
php tests/report_export_unit.php
php tests/report_export_static.php
```

Then run the cumulative test suite.

## 9. Staging acceptance test

1. Create a project, financial records, risks and deliverables.
2. Generate PDF, DOCX and XLSX outputs.
3. Confirm the report appears in report history.
4. Download each output using a user with `reports.download`.
5. Verify that an unauthorized user is denied.
6. Have a second user approve the report.
7. Record a portal or email distribution.
8. Scan the QR code and confirm the verification endpoint returns the reference, status and content hash only.
9. Compare report figures with their source records.
10. Confirm report files cannot be opened directly by guessing a storage path.