# Sharjino

Sharjino is a Persian-language building charge bot for Bale messenger, built with Laravel.

## Setup

1. Copy env:

```bash
cp .env.example .env
```

2. Set Bale keys in `.env`:

- `BALE_BOT_TOKEN`
- `BALE_API_BASE_URL` (default: `https://tapi.bale.ai`)
- `BALE_MANAGER_IDS` (comma-separated Bale user IDs)
- `BALE_WEBHOOK_SECRET`

3. Set Sharjino config in `.env`:

- `SHARJINO_BUILDING_NAME`
- `SHARJINO_DEFAULT_UNIT_COUNT`
- `SHARJINO_START_JALALI_YEAR`
- `SHARJINO_MANAGER_MOBILE`

4. Build DB:

```bash
ddev artisan migrate:fresh --seed
```

5. Run tests:

```bash
ddev artisan test
```

## Webhook

- Endpoint: `POST /webhook/bale`
- Controller: `app/Http/Controllers/Webhook/BaleWebhookController.php`
- Sender client: `app/Services/Messenger/BaleApiClient.php`

## End-user UX

Bot interaction is Persian and menu-driven with reply keyboard:

- `شروع`
- `انتخاب/تغییر واحد`
- `درخواست تخلیه واحد`
- `منوی اصلی`
- registration mobile capture uses keyboard button with `request_contact=true`

Manager entries appear only for users with manager permissions:

- `درخواست های در انتظار`
- `تایید تخلیه ها`

All keyboard buttons are permission/state-gated in `BaleBotService`.

## Conversation State

Conversation state is stored in Laravel Cache (`ConversationStateStore`) instead of DB for runtime bot flow.

## Core occupancy/debt rule

- Unit join request starts as `pending`.
- Only manager approval turns occupancy into `active`.
- Debt is linked to occupancy period (`monthly_charges.occupancy_id`), not unit only.
- New residents do not automatically inherit old resident debt.
- Vacate requires request and manager confirmation.

## Main tables

- `users`
- `buildings`
- `units`
- `unit_occupancies`
- `monthly_charges`
- `payments`
- `payment_items`
- `expenses`
- `audit_logs`
- `conversation_states`
- `roles`
- `permissions`
- `role_user`
- `permission_role`
# Sharjino

Sharjino is a Persian-language building charge bot for Bale messenger, built with Laravel.

## Setup

1. Copy env:

```bash
cp .env.example .env
```

2. Set Bale keys in `.env`:

- `BALE_BOT_TOKEN`
- `BALE_API_BASE_URL` (default: `https://tapi.bale.ai`)
- `BALE_MANAGER_IDS` (comma-separated Bale user IDs)
- `BALE_WEBHOOK_SECRET`

3. Set Sharjino config in `.env`:

- `SHARJINO_BUILDING_NAME`
- `SHARJINO_DEFAULT_UNIT_COUNT`
- `SHARJINO_START_JALALI_YEAR`
- `SHARJINO_MANAGER_MOBILE`

4. Build DB:

```bash
ddev artisan migrate:fresh --seed
```

5. Run tests:

```bash
ddev artisan test
```

## Webhook

- Endpoint: `POST /webhook/bale`
- Controller: `app/Http/Controllers/Webhook/BaleWebhookController.php`
- Sender client: `app/Services/Messenger/BaleApiClient.php`

## End-user UX

Bot interaction is Persian and menu-driven with reply keyboard:

- `شروع`
- `انتخاب/تغییر واحد`
- `درخواست تخلیه واحد`
- `منوی اصلی`

Manager entries appear only for users with manager permissions:

- `درخواست های در انتظار`
- `تایید تخلیه ها`

## Core occupancy/debt rule

- Unit join request starts as `pending`.
- Only manager approval turns occupancy into `active`.
- Debt is linked to occupancy period (`monthly_charges.occupancy_id`), not unit only.
- New residents do not automatically inherit old resident debt.
- Vacate requires request and manager confirmation.

## Main tables

- `users`
- `buildings`
- `units`
- `unit_occupancies`
- `monthly_charges`
- `payments`
- `payment_items`
- `expenses`
- `audit_logs`
- `conversation_states`
- `roles`
- `permissions`
- `role_user`
- `permission_role`
