# Phase 6 — Booking-linked chat

## Scope

A single private, text-only conversation belongs to each booking. It is not a quotation/request thread. Customers and the provider who owns the booking's business are participants. Staff with `chat.moderate` may read a conversation only after it has been reported; every moderation read and decision is audited.

## Access control

- Every page, poll, send and report resolves the booking from the route and checks the signed-in user against `bookings.customer_id` or the owning business's `owner_user_id`.
- Conversation IDs are not accepted from the browser for participant access; the unique booking ID is resolved server-side to the conversation.
- Staff cannot browse ordinary unreported conversations. Staff review routes require `chat.moderate`.
- Chat HTML and polling responses use private no-store caching. The PWA must never cache chat pages or responses.
- Text is escaped when rendered. The browser inserts polled messages with `textContent`.

## Contact filtering

Before inserting a message or notifying the other party, the server checks for common Kenyan mobile formats (07…, 01…, 254…, +254…), punctuation-separated digits, digit-spelled sequences, email addresses and links. Email and link filtering can be toggled in Admin → Settings. Blocked messages are not inserted and no message content is sent in an email or written to logs. Only the rule key and booking/sender IDs are recorded. Prices, quantities and ordinary dates are deliberately allowed.

This is a best-effort safety filter, not a foolproof detector. It can miss evasions and can occasionally need tuning. A filter hit does not suspend or ban anyone.

## Lifecycle and retention

- Chat is available for confirmed, checked-in, in-progress and disputed bookings.
- A completed booking remains chat-eligible for the configured grace period (default 24 hours).
- Cancellation, rejection and expiry close chat. Missed appointments get a grace window; rescheduling can reopen a closed chat.
- Ordinary users lose access to message history after closure. Reported history remains available only to authorised moderators.
- Closed ordinary chats are retained for 90 days by default. Reported chats are retained for 365 days after resolution by default. Unresolved reports are not purged by the chat retention query.
- `cron/run.php` performs lifecycle closure and retention cleanup. Configure it to run every five minutes on hosting.
- Deletion cannot guarantee immediate removal from backups. Protect backups and define a separate backup rotation schedule.

## Reports and notifications

Reports capture a reason and optional details. Resolution or dismissal requires a recorded decision. Report creation, moderator access, decision, and message-filter hits have audit events; audit metadata does not include message bodies. In-app alerts and optional email alerts link back to BizMtaani; email does not contain message text.

## Admin settings defaults

- Booking chat enabled: on
- Block email addresses: on
- Block external/contact links: on
- Completion / missed grace: 24 hours
- Ordinary closed chat retention: 90 days
- Reported chat retention after resolution: 365 days

## Acceptance testing

See `docs/TESTING.md` under “Phase 6 — booking-linked chat acceptance checks”. `php tests/phase6_chat_filter.php` runs filter regression tests without requiring a database.

## Remaining platform roadmap

This phase does not yet complete customer reviews and review moderation, a full dispute/appeal workflow, booking analytics and CSV exports (completion/cancellation rates by category/location), a PWA with a formally verified safe-cache policy, commission ledger readiness, formal Kenya Data Protection Act review, or backup/restore drills. Commission remains disabled and must never be applied retroactively.
