# Yunke — release candidate for master (PR #232, `dev-chen`)

Part of the [AI Voice Agent](/docs/modules_handbook/shared/voice-agent/readMe.md).
Prepared 2026-10-27 on dev-yc for the release owner's review. Everything the release
needs is on `dev-chen`, the head of PR #232 against `master`; nothing is deployed and
nothing on the main site was touched. Every runtime control stays off.

## What it does

Assembles everything the Yunke integration needs in the one PR the owner reviews, on
top of current `master`.

| Layer | Commit(s) | Note |
| --- | --- | --- |
| Base | `origin/master` 72ee84462 (PR #231, 2026-10-26) | the release branch |
| Yunke integration | `dev-chen` up to 1c9ba5be8 = PR #232 as first opened | 74 voice-agent commits on master |
| Bounded CLI self-test | `fix(voice-agent): bound approved owner tests outside business hours` | from dev-yc |
| Funnel lane + offline loop test | `feat(voice-agent): route Yunke funnel sends onto the network lane…`, `refactor(voice-agent): give Yunke funnel sends their own lane key` | from dev-yc |
| Records and route statement | `docs(voice-agent): record the dev-yc console-managed self-test…`, `…describe the funnel-to-collection loop…`, `…name the Yunke lane key…` | from dev-yc |
| This page | `docs(voice-agent): release candidate for master` | — |

`dev-chen` is a clean descendant of `master`: no merge, no conflict.
`php scripts/check-migration-constants.php` and `php scripts/check-suite-links.php` pass.

## How it works

### What the deployer should know

- **The release target is `master`** (PR #232). On 2026-10-27 the live checkout that
  Apache serves for `app.propertylab.com.my` (`/var/www/html/peta`, vhost `peta-le-ssl.conf`)
  was on branch `dev-wk` at d534b431e — a commit on no pushed branch — with 15 uncommitted
  files, while its database had already run master's 2026-10-26 migrations. How master
  reaches that checkout (`deploy-update.sh --branch master`, or a merge the owner makes) is
  the deployer's decision; this page assumes the deployed tree ends up containing master
  plus PR #232.
- **One PR.** Everything below is on `dev-chen`; nothing is to be opened elsewhere.

### Migrations new to production — 7, all additive

Relative to `master` the PR adds exactly seven migrations; production has run none of
them (checked read-only on 2026-10-27). They add tables, nullable columns and defaulted
columns only; none moves or rewrites data:

| Migration | Change |
| --- | --- |
| `2026_10_23_100000_add_provider_to_ai_call_profiles` | `provider` string default `retell` + index, `provider_settings` json nullable — existing 13 profiles become explicit Retell |
| `2026_10_23_110000_add_routing_to_ai_call_profiles` | `ab_split`, `redial_policy` json nullable |
| `2026_10_25_090000_create_yunke_app_call_bindings_table` | new table |
| `2026_10_25_110000_add_watch_fields_to_yunke_app_call_bindings` | `last_checked_at`, `last_check_reason` nullable |
| `2026_10_26_100000_add_review_fields_to_yunke_app_call_bindings` | `review_required_at`, `review_reason` nullable |
| `2026_10_26_110000_add_followup_policy_to_ai_call_profiles` | `followup_policy` json nullable |
| `2026_10_26_130000_create_yunke_connections` | new table (encrypted credentials, flags, probe fields) |

`ai_call_profiles` has 13 rows: each ALTER is instant.

### Configuration — nothing new to set

- No new `.env` key is required. With no `yunke_connections` row the runtime falls back to
  config, and the `YUNKE_*` keys are absent on the main site, so all five controls, the
  recording copy, the watch alerts and the App read are **false**. Saving the first console
  record moves control to the database.
- Keep `YUNKE_FUNNEL_QUEUE` **unset** in production: Horizon has network, and a Yunke funnel
  send then stays on the default / `redis-broadcast` lanes that `supervisor-1` and
  `supervisor-broadcast` already drain. The lane key is a dev-box device.
- `AI_ROUNDS_QUEUE` is unchanged by this candidate.
- `config:cache`, `npm run build` (new Vue pages) and `horizon:terminate` (changed and new
  job classes) are all part of `scripts/deploy-update.sh`. The scheduler needs no change:
  `voice-agent:yunke-watch` is registered but gated by its three controls.

### Deploy — `scripts/deploy-update.sh`, with checks and stop conditions

| Step | Check | Stop when |
| --- | --- | --- |
| 1 Backup (`mysqldump`, the script's default) | dump file exists and is non-trivial in size | no dump → stop |
| 2 Pull master after the PR merges | `git rev-parse HEAD` is the merge commit; `git status` clean apart from the deployer's known local files | unexpected diff → stop |
| 3 `migrate --force` | `migrations` table gains exactly the seven names above | any failure → **stop the release**; see Recovery, do not blanket-rollback |
| 4 `config:cache`, `npm run build` | no build errors | build error → stop before restarting workers |
| 5 `horizon:terminate` | Horizon master PID and supervisors restart (start time changes) | Horizon not back within a minute → stop, inspect |
| 6 Smoke | `/` 200; a Retell funnel send still records SENT; `/manage/calls/yunke` opens for a platform super admin and shows "Not configured" | 403/500 → stop |

### Recovery

- **A migration fails:** stop. Identify which of the seven; the earlier ones in the batch
  are additive and can stay (old code ignores new columns and tables) or be reversed with
  `migrate:rollback --step=1` for that batch after reading the error. Restore the dump only
  for data damage, which these migrations cannot cause. Never `migrate:fresh`.
- **The code misbehaves:** the script's `AUTO_ROLLBACK` returns to the previous commit; the
  new tables and columns can remain.
- **Yunke-specific:** nothing can run until a platform super admin saves sessions and
  enables controls, so a rollback after a failed smoke has no Yunke state to unwind.

### Post-release checks, read-only

- `migrations` holds the seven names; `yunke_connections` has 0 rows; `yunke_app_call_bindings` 0 rows.
- `ai_call_profiles.provider` is `retell` for all 13 rows; existing AI-call funnel rules keep sending (compare `funnel_automation_sends` SENT count before/after).
- `YunkeRuntime::state()` reports `saved=false` and every flag false.
- Horizon supervisors restarted; no new `SendFunnelAiCall` rows in `failed_jobs`.
- `/manage/calls/yunke` is reachable only with `manage-calls` + platform super admin.

### After release, in this order

1. Own-number funnel loop on the main site, exactly as the dev-yc pack: sessions saved in
   the console, read-only check, controls on, a paused cap-1 profile with a ≤20-minute
   sub-window inside 10:00–21:00, one dedicated funnel with one AI-call rule, one real
   registration, one task, collection, duplicate check, then pause everything.
2. Only then decide the customer pilot, using the console's market mode rather than the
   allowlist, which is per-number E.164, 500 max and pauses the controls on every save. Then
   decide the after-call follow-ups, action by action.

## Related files

- [yunke-live-acceptance.md](/docs/modules_handbook/shared/voice-agent/yunke-live-acceptance.md) — approvals, stop drill, pilot.
- [yunke-funnel-loop.md](/docs/modules_handbook/shared/voice-agent/yunke-funnel-loop.md) — the loop and its offline test.
- PR #232 — https://github.com/property-lab/petav3/pull/232
- [yunke-console.md](/docs/modules_handbook/shared/voice-agent/yunke-console.md) — controls and their prerequisites.
- `scripts/deploy-update.sh`, [deploy.md](/docs/modules_handbook/production-setup/deploy.md), [horizon.md](/docs/modules_handbook/production-setup/horizon.md), [scheduler.md](/docs/modules_handbook/production-setup/scheduler.md).


## Tests run on this branch (2026-10-27, dev-yc, isolated test database)

- `vendor/bin/phpunit` on `tests/Feature/VoiceAgent/` (whole folder), `FunnelAiCallAutomationTest`,
  `FunnelAutomationReminderTest`, `AiRoundsTest`, `PaymentAiCallTest`, `AiCallPdfWorkflowTest`,
  `AgentLeadAiCallerTest`, `FcmInspectorRedactionTest` and the two Yunke unit tests:
  **552 tests, 7,123 assertions, all passing** (one pre-existing PHPUnit deprecation).
- `npx vitest run resources/js/Pages/Manage/Calls/Yunke`: **7 passing**.
- `scripts/check-migration-constants.php` and `scripts/check-suite-links.php` pass.
- The test database was rebuilt from this branch's migration set, which exercises the seven
  new migrations on an empty schema. Not run here: the full suite, or anything on the main site.
