# Digital App v2.0.0 — Deployment, SQL & Endpoints

This build uses **dynamic admin-created forms only**. The old hard-coded NIN/NEC/TIN/Business Licence screens and their token endpoints are not part of the new app package.

## 1. What changed

### Admin (login required)
- Admin login remains separate from normal users.
- Create/edit/delete forms.
- Create dynamic inputs: text, multiline, number, date, select, image and signature.
- Upload one or more template pages.
- Drag fields directly over the template in Position Editor.
- Set page, x/y position, width, height, font size, bold, uppercase and alignment.
- Create tokens, copy them, reset usage, delete them and **recharge the same token** by adding generations without changing its code.
- Token manager shows the linked account phone when a user has attached that token to an account.

### Normal user account (optional)
- Account is NOT required to open or use public forms.
- Create account with phone number + password (name is optional).
- Login session is saved in the Flutter app.
- See active token and copy it.
- See total generations used, remaining generations and all tokens linked to the account.
- Activate a newly purchased token by entering its code.
- If admin recharges the same code, user refreshes the account and continues using the same token.
- User can select another active token when several tokens exist.

### Form token flow
- **Guest:** fills form -> pastes token -> Verify -> Generate/Print.
- **Logged-in user:** fills form -> selects an active account token -> Verify -> Generate/Print. No token typing is required.
- `token_verify.php` only validates availability.
- `token_consume.php` performs an atomic usage increment and generation log when the document is generated.

### Background remover
The app continues to use the local package supplied in the original project:

`packages/background_remover`

No replacement background-removal library was added.

## 2. Database

Use:

`database_update_2026_09_05.sql`

It is designed for either:
- the original supplied database, or
- a database that already received the first dynamic-forms migration.

It adds/updates:
- `users.role`
- `users.active_code_id`
- user timestamps
- nullable user email so phone-only accounts are possible
- `codes.user_id`
- `codes.expires_at`
- `codes.updated_at`
- `admin_sessions`
- `user_sessions`
- `forms`
- `form_templates`
- `form_fields`
- `generation_logs.user_id`

The existing supplied user with `id=1` remains the administrator.

## 3. API deployment

Upload the contents of the API ZIP to the same server root currently serving:

`https://app.hudumatz.online`

Required writable directory:

`uploads/templates/`

Recommended permissions: `755` or `775`, depending on hosting configuration.

After upload test:

`GET https://app.hudumatz.online/api/v2/health.php`

## 4. Legacy server cleanup

The new ZIP does not contain the old endpoints. If they already exist on the server, delete them after backup:

- `/api/verfy_tocken.php`
- `/api/update_token_status.php`
- `/api/mkoa.php`
- `/api/office.php`
- `/api/wilaya.php`
- `/login.php`
- `/verify.php`
- `/forgotpassword.php`

A copy of this cleanup list is included as `LEGACY_FILES_TO_DELETE_FROM_SERVER.txt`.

Do not delete `/api/v2/` or `/uploads/templates/`.

## 5. Public form endpoints

### GET `/api/v2/forms_list.php`
Returns active forms created by admin.

### GET `/api/v2/form_detail.php?id={FORM_ID}`
Returns the dynamic form, template pages, fields and placement configuration.

### POST `/api/v2/token_verify.php`
Guest body:

```json
{"token":"TOKEN_CODE"}
```

Logged-in user body with `Authorization: Bearer USER_SESSION`:

```json
{"token_id":123}
```

### POST `/api/v2/token_consume.php`
Guest:

```json
{"form_id":1,"token":"TOKEN_CODE"}
```

Logged-in user:

```json
{"form_id":1,"token_id":123}
```

For logged-in calls, send `Authorization: Bearer USER_SESSION`.

## 6. User account endpoints

### POST `/api/v2/user_register.php`

```json
{"phone":"0712345678","password":"secret123","fullname":"Optional Name"}
```

### POST `/api/v2/user_login.php`

```json
{"phone":"0712345678","password":"secret123"}
```

### GET `/api/v2/user_me.php`
Header:

`Authorization: Bearer USER_SESSION`

Returns:
- user profile
- active token
- all linked tokens
- total used generations
- total remaining generations

### POST `/api/v2/user_token_redeem.php`
Links a purchased token to the logged-in account and makes it active.

```json
{"token":"TOKEN_CODE"}
```

### POST `/api/v2/user_token_select.php`

```json
{"token_id":123}
```

### POST `/api/v2/user_logout.php`
Invalidates the current user session.

## 7. Admin endpoints

All admin endpoints require:

`Authorization: Bearer ADMIN_SESSION`

- `POST /api/v2/admin_login.php`
- `GET /api/v2/admin_forms_list.php`
- `GET /api/v2/admin_form_detail.php?id={id}`
- `POST /api/v2/admin_form_save.php`
- `POST /api/v2/admin_form_delete.php`
- `POST /api/v2/admin_template_upload.php`
- `POST /api/v2/admin_template_delete.php`
- `GET /api/v2/admin_tokens_list.php`
- `POST /api/v2/admin_token_create.php`
- `POST /api/v2/admin_token_recharge.php`
- `POST /api/v2/admin_token_reset.php`
- `POST /api/v2/admin_token_delete.php`

Recharge example:

```json
{"id":123,"add_files":10}
```

This preserves the token code and adds 10 generations.

## 8. Flutter setup

The new app version is `2.0.0+2`.

From the project directory:

```bash
flutter clean
flutter pub get
flutter run
```

Release Android App Bundle:

```bash
flutter build appbundle --release
```

The account session uses `shared_preferences`, so run `flutter pub get` before building.

## 9. Expected first-run behavior

If admin has not created any forms, Home intentionally shows **no legacy fallback forms**. Admin must:

1. Open Admin Login.
2. Create a form.
3. Save it.
4. Upload template page(s).
5. Add inputs.
6. Open Position Editor and arrange every field over the template.
7. Save positions.
8. Set form Active.

Only then will the form appear to ordinary users.

## 10. Branding

User-facing core screens include:

**Developed by digital tz**