# Adoption data digitalization - full module implementation

This build is based on the supplied Laravel project and the supplied `adoption2` database structure.

## Database compatibility

The supplied database uses `childrens` and stores country in the `country` column. The original migration history in the project had conflicting `children`/`childrens` and approval migrations. Those legacy approval migrations were converted to no-ops and the base `childrens` migration was aligned with the supplied database structure.

The new migrations add:

- `case_id`, workflow state and review metadata to `childrens`.
- `case_status_histories` for a complete approval/rejection/resubmission audit trail.
- `search_requests` for information requests.
- `search_request_histories` for information-request status history.

Existing `file_number` values are copied to `case_id` when the new migration runs. Demo duplicates are intentionally not made unique retroactively; new case IDs are validated as unique.

## Case workflow

`submitted -> approved`

`submitted -> rejected -> resubmitted -> approved`

A rejected encoder-owned case displays the supervisor's correction comment and allows the encoder to edit and resubmit it.

## External PDF file transfer

No case PDF is uploaded through Laravel. The encoder records the Case ID. The application stores a relative case-file path such as:

`/children_data/{country}/{case_id}/{case_id}.pdf`

Configure the file-transfer root with:

`ADOPTION_FILES_ROOT=/srv/adoption-files`

The protected case-file endpoint resolves the stored path under the configured root (or the application's public directory for legacy demo paths) and requires authorization.

## Monitoring

The monitoring page provides date filtering and:

- total cases recorded
- approved/rejected/pending cases
- cases recorded per encoder
- encoder approved/rejected/pending totals
- search-request totals by status
- last-seven-day search-request counts

## Global case search

Authenticated users can search approved records using the global term or individual fields including:

- Case ID / file number
- child name
- mother/father name
- country/city/region
- agency/caregiver
- birth place/date
- family status
- phone/email/fax
- street address/remarks
- sex
- approved/adoption date

## Information search requests

Statuses:

`new -> assigned -> searching -> found/not_found -> information_provided -> closed`

Requests can also be cancelled.

Encoders can create requests and update requests they created or that are assigned to them. Supervisors/managers can assign and manage all requests.

## Public API

`POST /api/v1/search-requests`

Example JSON:

```json
{
  "requester_name": "John Doe",
  "requester_type": "adopted_child",
  "requester_email": "john@example.com",
  "requester_phone": "+251900000000",
  "child_name": "Example Name",
  "birth_date": "1987-04-12",
  "mother_name": "Example Mother",
  "father_name": "Example Father",
  "case_id": "00123",
  "request_description": "I am requesting information regarding my adoption."
}
```

Response:

```json
{
  "success": true,
  "request_number": "SR-20260922-ABC123",
  "status": "new",
  "message": "Your information search request has been received."
}
```

The public API never returns adoption records. It is rate limited to 10 requests per IP per minute.

## Roles

- `admin`
- `manager`
- `supervisor`
- `encoder`

The existing `approver` role is retained for compatibility.

Demo users created/updated by the permission seeder:

- `admin@example.com` / `password`
- `manager@example.com` / `password`
- `supervisor@example.com` / `password`
- `encoder@example.com` / `password`

Change demo passwords before production use.

## Deployment

1. Back up the production database.
2. Deploy the updated Laravel project.
3. Set `ADOPTION_FILES_ROOT` to the file-transfer root.
4. Run `php artisan migrate`.
5. Run `php artisan db:seed --class=RolesAndPermissionsSeeder` if roles/permissions need to be synchronized.
6. Clear/rebuild Laravel caches as appropriate for the environment.
7. Ensure the PHP/web-server account can read the external case-file directory.
8. Test approval, rejection, correction/resubmission, search, search-request workflow and the public API in a staging environment before production use.

## Enhancement pass: dashboard, logout, country labels, admin user management

The enhancement pass adds:

- Fixed AdminLTE logout by providing an authenticated `/logout2` endpoint that supports the sidebar GET action and invalidates the session.
- Added a `View more` link to every dashboard KPI card, including status-filtered case lists and open search requests.
- Replaced the dashboard country table with a horizontal Chart.js bar chart.
- Country display resolves numeric legacy values (`1`..`5`) through the `countries` table while continuing to support records that already store a country name.
- Search-by-country now accepts either the country name or the legacy numeric country value.
- Added admin-only user management: list/search/filter users, create user, edit user, assign/change role, reset password, and delete another user.
- Added `manage users` and `manage countries` permissions; country management is now admin-only.
- Added authorization checks for case viewing and protected deletion of approved cases.
- Added `open=1` filtering for information requests so dashboard open-request cards land on the correct filtered list.

The implementation intentionally does not alter existing demo data. It is compatible with the supplied database where `childrens.country` contains either a numeric country ID or a country name.