# Handoff: TCN / OurVend machine arrival onboarding

## Goal
Figure out the exact arrival-day setup plan for 5 incoming TCN / OurVend vending machines:
- what must be done in person
- what can be done remotely
- exact setup order
- risks / blockers
- especially around:
  - power-on / first boot
  - machine identification
  - cloud login
  - inventory / slot config
  - product name / image / price
  - QR / third-party payment integration
  - payment success -> vend / dispense behavior

## Current known context
The user will **not be physically present** when the 5 machines arrive.
Another person may be on site to do the minimum necessary physical steps.

Ballbox likely wants to use its own QR payment flow as a third-party payment integration inside the Chinese app/cloud.

## Credentials and access
### OurVend / Yunshu cloud
- PC URL: `https://dnymer.ourvend.com/`
- Mobile H5 URL: `https://dnyh5.ourvend.com/#/login`
- Username: `cc`
- Password: `ys123456`

## Local folder with all gathered material
- `/mnt/rpi/tcn-machine-onboarding`

### Docs copied from laptop
Under:
- `/mnt/rpi/tcn-machine-onboarding/docs/`

Files present:
- `CZG-WXS- 2511-0189-JZ.pdf`
- `CZG-WXS- 2511-0189-JZ.txt`
- `（中英）云数后台操作说明文档(界面英文版).pdf`
- `（中英）云数后台操作说明文档(界面英文版).txt`
- `（中英）云数后台操作说明文档(界面英文版) 2.pdf`
- `（中英）云数后台操作说明文档(界面英文版) 2.txt`
- `Cloud System and Commercial Configuration Addendum for TCN-CSC-8C(V49).pdf`
- `Cloud System and Commercial Configuration Addendum for TCN-CSC-8C(V49).txt`
- `Cloud System and Commercial Configuration Addendum for TCN-CSC-8C(V49) (1).pdf`
- `Cloud System and Commercial Configuration Addendum for TCN-CSC-8C(V49) (1).txt`
- `Deep Research Report on TCN-CSC-8C(V49) Smart Touchscreen _ Advertising Vending Machine.pdf`
- `Deep Research Report on TCN-CSC-8C(V49) Smart Touchscreen _ Advertising Vending Machine.txt`

### Initial notes file
- `/mnt/rpi/tcn-machine-onboarding/README.md`

## Useful tutorial links already gathered
Included in:
- `/mnt/rpi/tcn-machine-onboarding/README.md`

Topics include:
- set price
- replace background image
- replace goods image
- replace help image
- replace standby image
- replace top shopping interface image
- test slot
- change price unit
- modify decimal point
- change slot number settings
- language settings
- failed counts lock machine
- merge slot
- split slot
- add/delete slot
- payment settings
- prefill money
- activate payment system
- debug menu
- choose 4G module
- printer config

## Fast findings already extracted
These are not final conclusions, but grounded enough to accelerate the next agent.

### Confirmed or strongly supported by docs
1. The cloud platform is Yunshu / OurVend.
2. Docs mention `www.ourvend.com` as the legacy/main login URL; active URLs above were provided by the user.
3. Multi-language UI exists.
4. Cloud panel includes modules for:
   - machine management
   - payment parameters
   - delivery records
   - alarms
   - machine advertisement
   - commodity / slot mapping
   - sales / statistics
5. Remote edit of:
   - commodity name
   - image
   - price
   - capacity
   - stock
   is documented.
6. But remote sync appears to depend on some remote feature/switch being enabled, e.g. wording like:
   - `remote function is enabled`
   - `remote track configuration switch`
7. Docs also mention refund handling for vend failure after successful payment.
8. Contract/addendum indicates the purchased machine config includes:
   - 4G module
   - online inventory and sales system
   - no included payment system hardware by default / payment installed locally
9. Contract text indicates base geometry roughly:
   - 6 trays
   - 8 slots per tray
   - MAX 240
10. There are VIP / paid functions in the cloud, including at least some remote editing and advertisement-related features.

### Important implication
The Chinese cloud likely handles machine ops, slot/product config, ads, and telemetry, but the actual payment architecture may still be partially external or custom. That makes the exact third-party payment flow and post-payment vend trigger critical.

## Ballbox-side context already known
Inside `/mnt/rpi/repos/ballbox` there is support for:
- `VendingMachine`
- `Product`
- QR order creation
- MercadoPago webhook intake
- admin surfaces for network and payments

Relevant facts from the repo review:
- order creation route: `/api/integrations/payments/orders`
- webhook route: `/notification/mercadopago`
- payment correlation uses canonical external reference:
  - `payment-vm_{vendingMachineId}-txn_{machineTxnId}`
- admin/network exists for creating and managing vending machines logically in Ballbox
- admin/payments exists for reconciliation / payment session review

Also, memory from a separate Ballbox payment-integration effort suggested:
- the machine Android / Chinese flow was not fully production-validated
- real launcher payload / callback / dispense contract was still a known gap

## AGENTS / machine helper context
This machine is `ballbox-first`.
Do not SSH into `ballbox-first` for local work.

Laptop helpers are documented in:
- `/mnt/rpi/pi-config/AGENTS.md`

Helpers available include:
- `laptop-read`
- `laptop-run`
- `laptop-rsync`
- `laptop-mount`
- `laptop-umount`
- `laptop-write`

## Failed attempt worth knowing
A request was made to use a subagent with model:
- `gemini-3.1-pro-preview`

That failed twice with no output from the subagent runner.
Do not assume that path currently works.

## What the next agent should do
### Main tasks
1. Inspect the local docs under `/mnt/rpi/tcn-machine-onboarding/docs`.
2. Log into the OurVend panel using the provided credentials.
3. Map the real panel structure and actual workflow for:
   - machine onboarding / machine list
   - inventory / slot management
   - product image and pricing updates
   - payment settings
   - any third-party payment integration path
   - any remote-control / remote-sync toggle
   - machine/device IDs and status surfaces
4. Determine the exact minimal in-person tasks on arrival day.
5. Determine the exact remote tasks the user can do beforehand or during the arrival.
6. Produce a short operator checklist in execution order.
7. Call out unknowns that still need docs, screenshots, or vendor answers.

### Key questions to answer
- Can inventory, product name, product image, and price be configured fully remotely from OurVend?
- Is slot mapping remote, or does it require local machine-side confirmation?
- What exact machine identifiers appear in the cloud panel, and how should they be mapped to physical machines?
- Is there a documented or discoverable third-party payment integration path?
- If third-party payment exists, how does the machine know when to vend?
- Is there a machine-side activation step required after remote config?
- Does first boot / network join / account binding require local touchscreen work?
- Can the cloud panel push settings to offline machines or only online ones?
- Are any required functions blocked behind VIP / paid modules?

## Expected output format
The next agent should ideally return:
1. `Panel map`
2. `Arrival-day setup order`
3. `Minimum in-person checklist`
4. `Remote checklist`
5. `Hard blockers / unknowns`
6. `Recommended pre-arrival prep`

## Suggested starting commands
- inspect docs:
  - `rg -n -i "payment|slot|commodity|remote|advertis|machine management|delivery|refund|inventory|price" /mnt/rpi/tcn-machine-onboarding/docs/*.txt`
- browse panel with browser tooling if available
- read notes:
  - `cat /mnt/rpi/tcn-machine-onboarding/README.md`

## Prompt to reuse
See sibling file if created separately, or use this handoff directly.