# Yunke App batch tasks — offline adapter

Part of the [AI Voice Agent](/docs/modules_handbook/shared/voice-agent/readMe.md).
Built 2026-10-25 from APK 2.0.20 static evidence, SHA-256
`100ffdb27f72b96f82013314e2eb73fe8b4e0501746811c173eb41d3c1f36bc9`.
All response and binding fixtures are synthetic, not vendor-certified contracts.

## What it does

Builds a new App batch-task request, parses a supplied creation response, and
inspects a Web task-result row against explicit local bindings. Both classes are
pure: no HTTP transport, credentials, configuration lookup, models, queues or
notifications. No command, route, scheduled job or ConversationalCaller uses them.
Yunke remains unavailable for dialing through the application; existing default-off
switches are unchanged.

### Separately authorized live sample (2026-10-25)

The user approved one owner-number test outside the application runtime. An isolated
Mac process used this request builder and response parser, then sent the request with
the phone's restored, explicitly verified enterprise session. One create attempt returned
a literal string task ID; one child row matched its parent and approved number. The
phone's native scheduler placed one call on the MY SIM, and the user confirmed success.
No ADB dial, production funnel, database writeback or notification was used.

The test used an HH:mm scheduled period. Resume-to-dial took about nine minutes,
consistent with the statically observed ten-minute polling loop; this is one observation,
not a latency guarantee. First dial triggered a verified pause. After upload the task
had taskStatus=4/isPaused=0, and another pause was refused for a task outside the
not-started/in-progress states. The App was stopped and phone idle verified. A pause
flag alone is insufficient to classify the task's lifecycle or prove cancellation.

The [S2 evidence](/docs/modules_handbook/shared/voice-agent/yunke-app-read.md#authorized-single-number-task-sample-s2-2026-10-25)
includes explicit native child/callActionId payloads, a nonempty App results page,
28305 ms recording metadata with three transcript segments, and summary readback.
App result-list id matched the per-call ID; App taskDetailPage id remained the child,
without a callId field. Neither response is the Web row expected by the inspector below.
The classes remain pure and no production transport or settlement is enabled.
The separately disabled [binding/result processor](/docs/modules_handbook/shared/voice-agent/yunke-app-results.md)
now provides single-recipient create claims, durable returned IDs and fake-tested
settlement for explicitly bound S2-shaped results. It does not add a task-sending transport
or change this Web inspector's held-only behavior.

## How it works

### Request and creation response

`YunkeAppTaskAdapter::createRequest()` returns a descriptor for
`POST https://phone3.yunkecn.com/phone-ai-call/app/aiCallOut/save`; it never sends it.
The company and executing user are explicit inputs from an authenticated identity.
The descriptor excludes session headers/credentials; any future authorized transport
must supply the normal verified App session, not V3 headers or a guessed identity.
The manual-customer branch sends `customerSource=3`, `execlDataList`, matching
`createUserId/userId`, empty clue allocations, `forceClueTransfer=0`, and
`redialCount=0`. Customer fields are limited to cellphone, customerName,
customerCompany, position, otherInfo and additionalNotes. Phone strings are kept
unchanged. No external UUID, existing taskId or arbitrary option is accepted.

An ordinary task has isScheduled=0. A scheduled descriptor requires all four
fields: positive integer startTime/endTime with an ordered date range,
comma-separated weekdays 1–7, and scheduledTimePeriods as a JSON STRING holding a
nonempty array of startTime/endTime string pairs. S2 observed HH:mm periods on one
device/session; other time formats and vendor timezone handling remain unverified.
Templates and other creation branches are outside this adapter. The zero redialCount
is not proof that the phone will
never redial; App cache/detail fallback behavior still needs real acceptance.

`parseCreateResponse()` accepts an HTTP status and body, not a response fetched
by this class. HTTP 2xx and code 10000 (integer or string) are required; optional
success must be boolean true. Only nonempty literal string data is a taskId,
kept byte-exactly, including leading zeros and large quoted values. Numeric or
object-shaped IDs are not guessed. Outcomes are:

- accepted/task_id_returned: server success with a string task ID;
- accepted/no_task_id: success with null/empty data, not a correlated call;
- rejected: clear HTTP or business refusal, never an empty success;
- unknown: timeout/no response, HTTP 408/5xx, unreadable or contradictory envelopes,
  or unrecognized ID shapes. It may have created a task: do not automatically retry.

No vendor message, token or raw response is returned in these outcomes. Sensitive
arguments are redacted from PHP exception backtraces. This App contract is
separate from Open V3/AES; its string taskId behavior must not be assumed for V3.

### Result correlation and isolation

`YunkeAppResultInspector::inspect()` takes a Web taskDetailPage row, explicit
bindings, and trusted authenticated company/user context. The row must carry
string taskId, id (SUBTASK), and callId. If companyCode/userId are present they
must match the context. Conflicting subTaskId/callActionId aliases are invalid.

Each supplied binding requires company_code, user_id, task_id, sub_task_id,
call_action_id and local_uuid. All five vendor identity/ID components must match
exactly, with exactly one candidate. Task ID alone is insufficient. No lookup or
binding is generated from phone, task name, timestamps, notes, generic history.id
or local CallRecordDbBean.callId (which may hold a subtask ID). The Web callId to
App callActionId relationship must be independently established before a binding
is supplied; the adapter does not certify that relationship.

Wrong identity is rejected; malformed IDs/analysis/bindings are invalid;
missing IDs, no binding or multiple candidates are unmatched. These isolated
outcomes contain no local UUID or customer facts. The original input remains
with the caller; there is no persistent quarantine table or automatic write.
Even one exact match is only held/status_unverified, never settlement-ready.
Repeated inspection returns the same outcome and changes neither input.

A valid JSON-object aiRawResult is decoded under facts.analysis; facts.row keeps
the source row separately. Its summary and intent fields are vendor facts, not
petaV3 analysis.custom_analysis_data. History tipType=1 is not automatically high
intent: the real manual C1 sample had that history label alongside medium model
intent. No workflow callStatus becomes a terminal call outcome here. No turns,
cost, follow-up, redial or notification are produced.

The static scheduled-task loop waits 600000 ms after each fetch. Creating a task
could cause an already-active phone scheduler to dial it. Do not treat task
creation as a harmless live probe; no live creation is authorized by this adapter.

## Reference usage

The runnable consumers are the two unit tests below. The batch test uses a local
Illuminate HTTP Factory with preventStrayRequests and a fixed fake response; the
application adapter never obtains that transport. Tests extend PHPUnit TestCase,
not the application TestCase: no Laravel bootstrap, database, queue or actual
account is involved.

Run only these files:

```text
vendor/bin/phpunit tests/Unit/VoiceAgent/YunkeAppTaskAdapterTest.php tests/Unit/VoiceAgent/YunkeAppResultInspectorTest.php
```

Before a live integration: verify account creation entitlement/fees, the actual
create response across supported branches, reliable cloud-only per-customer and
per-attempt associations, final status semantics, session lifecycle, duplicate/unknown
creates, cancellation, scheduler
latency and vendor redials. The manual 129-second call proves a known call ID can
retrieve a transcript, but has no task association and does not satisfy these gates.
S2 verifies one scheduled-task path without removing the remaining production gates.

## Related files

- [YunkeAppTaskAdapter](/src/Common/VoiceAgent/YunkeApp/YunkeAppTaskAdapter.php) — request descriptor and response outcomes.
- [YunkeAppResultInspector](/src/Common/VoiceAgent/YunkeApp/YunkeAppResultInspector.php) — pure exact-ID inspection.
- [YunkeAppTaskAdapterTest](/tests/Unit/VoiceAgent/YunkeAppTaskAdapterTest.php) — fake request/response contracts.
- [YunkeAppResultInspectorTest](/tests/Unit/VoiceAgent/YunkeAppResultInspectorTest.php) — binding, isolation and namespace regressions.

No frontend, migrations, seeders, environment settings, HTTP routes or schedules.
