# Replacing the Yunke Android phone

Part of the [Yunke console](/docs/modules_handbook/shared/voice-agent/yunke-console.md).
Added 2026-11-05. This is an offline credential handoff, not vendor device registration,
automatic session renewal or a live device check. No migration is required.

## What it does

**Phone Call → Yunke → Replace phone** imports the current session from a replacement
Android phone using the **same company and user**. Operators keep the saved Web Cookie,
recipient allowlist, profiles, scenarios, funnel rules and existing call bindings.
Only the App token changes. All five controls pause and the old Web probe is invalidated.
The operator explicitly checks the Web session and decides when to resume.

This feature does not obtain a stable vendor API key, log in to the App, create a task,
place a call, cancel accepted tasks, download audio or renew an expired Web Cookie.
The current platform connection still represents one execution identity, not a fleet.

## How it works

### First setup on an environment with no saved connection

**Replace phone** stays disabled until a connection is saved, because it has no saved
identity to compare against. On a new environment, save **Account & sessions** first with
company code, user id and Web Cookie read from the `taskPage` request headers, leaving the
App token blank and the allowlist empty, then run the read-only check. Replace phone then
adds the token. That save invalidates the first check, so run the check once more.

### Operator sequence

1. Stop accepted tasks on the old phone using the existing phone-side procedure.
   Local pause cannot cancel tasks already accepted by Yunke.
2. On the new phone, use the existing enterprise account and connect/authenticate the box.
   Do not call an App login API to fetch credentials: concurrent App login previously
   invalidated the phone's session. Changing phones alone does not require a new company,
   user, profile or valid Web Cookie.
3. In the existing saved console connection, choose **Replace phone** and download
   `yunke-pair-phone.py`. Run it on the computer connected to the new phone. Start with
   the report, which holds no token or Cookie and is safe to share:

       python3 yunke-pair-phone.py --inspect

   It prints the installed App version, the log files present and, from the newest log
   holding an account record, whether that record can be exported. It ends with the exact
   export command to run next, for example:

       python3 yunke-pair-phone.py --date 2026-11-04 --output yunke-phone-pairing.json

   `--date` is needed only when the newest record is not in today's log, because the helper
   never moves to an older log by itself. `--max-bytes` widens the read when a large log
   may hold the record earlier than the last 2 MiB. `--inspect --pull-apk <folder>` also
   copies the installed APK for offline reading and prints its SHA-256.

   Python 3.8+ and an already authorized USB/wireless ADB connection are required.
   Use `--adb "/path/to/adb"` if it is not on PATH and `--serial <device>` if multiple
   authorized phones are present. Use the installed Python command on Windows if it
   is named `python` rather than `python3`. The helper does not install tools, connect
   to a wireless address, elevate permissions, launch the App or change phone settings.
4. Import that JSON file. The browser checks the company and user before allowing save;
   the server checks again against the current encrypted connection under its row lock.
   A mismatch, missing account or unreadable saved credentials rejects the operation.
   Use the account settings flow if intentionally changing identity.
5. Choose **Update phone session & pause**. The server accepts only the identity and
   new token; incoming Cookie, allowlist, clearing or runtime fields cannot change them.
   No vendor request is made by this save.
6. Delete the private local pairing file. It contains a login secret, not a public
   diagnostic. The helper creates it exclusively with mode `0600` on POSIX; use a
   private local folder and appropriate filesystem permissions on other systems.
   Default `yunke-phone-pairing*.json` filenames are ignored by Git as a second precaution.
7. Run the existing **Check read-only session** if authorized to write probe metadata
   to this environment. The Web check makes one bounded query, stores its local result
   and never places a call. Keep automation paused until the operator explicitly resumes
   it under the normal prerequisites. Expired Web cookies require separate replacement.

### Session source and limits

The helper only reads: the authorized device list, the phone's date, the installed App
version (`dumpsys package`), log file names and sizes, and a bounded tail of
`/sdcard/.yunke_log/aioutbound/log_YYYY-MM-DD` (2 MiB by default, 64 MiB at most).
It uses the last `AccountManage` record, exporting only `company`, `userId`, `token` as `company_code`, `user_id`, `app_token`. The file also records
`source_log_date`, `source_record_time`, `app_version`, `app_version_code`, `captured_at`
and `validity: unverified`; the console reads only the three credential fields.
No full log or account object is saved. No token is printed. A malformed, incomplete,
masked or `personal` last record never falls back to an older valid-looking record.

An explicit `--date` reaches back at most 7 days on the phone's clock and is validated
before it touches the fixed log path. It is refused when a newer log holds an account
record or a session failure (`token incorrect`, `code=-10000`), or when a newer log is too
large to rule that out. A log with no record, a missing file and denied permission are
reported separately, because none of them means the token is invalid.

This log source was observed on App **2.0.20**, and a real export worked on **2.0.33** on
2026-11-05. The 2.0.33 APK writes the record in two places: `mAccountBean=` at a phone-number
login and `init json=` each time the App process starts. So the log of the day a phone logged
in can hold none, as this phone's did, and a later start writes one. A version that logs the
record differently reports "no account record". Stop there and read the log's shape with its values masked rather than
logging in again to manufacture one. Missing files, missing fields, ordinary
permission failures, ambiguous devices and ADB errors stop the helper. Do not root,
install hooks, re-login to manufacture logs or guess another source. The server cannot
prove that a submitted token belongs to the phone from its contents alone: the file
is an operator-supplied session, not cryptographic proof of device identity.

`captured_at` is the export time, not proof the login session is fresh. A matching
identity is not proof the token is valid. The console has no read-only App check to
certify the token or device. The Web probe tests only Web credentials; a
separately approved own-number call is still needed for live replacement acceptance.
No login or call verification happened during this implementation. The phone evidence so far
is one real export, and one read of `taskPage` with that token that returned success; see the
[progress ledger](/docs/modules_handbook/shared/voice-agent/yunke-pdf-progress.md).

Saved secrets stay encrypted and absent from page props, flash input and diagnostics.
The browser clears the file selection and token when closing, changing identity,
finishing successfully or receiving a save error. Importing a new invalid file clears
the previous token. An asynchronous old file read cannot restore a closed/changed form.
Existing workers pick up the new credentials through the normal runtime refresh.
Token replacement does not clear calls, reconcile uncertain tasks or reset daily caps.
If Dev and Production use the same phone identity, maintain a single active task writer.

## Related files

- `scripts/yunke-pair-phone.py`, `scripts/tests/test_yunke_pair_phone.py` — bounded
  local export and synthetic/mocked ADB coverage.
- `PhonePairing.vue`, Yunke `Index.vue`, `console.test.js` — helper download,
  local JSON import, identity checks and secret clearing.
- `YunkeController`, `PhonePairingRequest`, `YunkeConnectionRepository`, `routes/web.php`
  — platform-superadmin/permission guard, transactional update and helper download.
- `YunkeConsoleTest.php` — preserved settings, paused gates, identity refusal,
  encrypted/hidden secrets and local-only helper download.

## Reference usage

An existing platform connection for the original account is saved first. Use
`GET /manage/calls/yunke/connection/phone/helper` to download the public helper code;
submit only `company_code`, `user_id`, `app_token` to
`PUT /manage/calls/yunke/connection/phone`. Both routes require the console's existing
permissions and platform super-admin identity. Use the account form to replace an
expired Cookie; do not resubmit stale company, allowlist or profile values during
a same-account phone replacement. Deployment and enabling remain separate actions.
