fix(extension): wait for ERP entry readiness

2026-09-03 14:31:38 +08:00
1 parent 69ea6d2517
commit 500034bb63
@@ -0,0 +1,70 @@
+# Task: Add adaptive ERP readiness wait and assess extension auto-update
+
+## Identity
+
+- Task ID: 20260903-adaptive-wait-auto-update-7b3e9a2c
+- Mode: Feature
+- Branch: codex/20260903-adaptive-wait-auto-update-7b3e9a2c-adaptive-wait-auto-update
+- Worktree: /Users/inmanx/Documents/lwltAPI-adaptive-wait-auto-update-7b3e9a2c
+- Base commit: 69ea6d25178d75abf8d7fd728bd31c61764caa7d
+- Owner: codex
+- Status: Ready for Integration
+
+## Scope
+
+- Make `shared_plan_create` wait adaptively for the ERP scatter-plan list add button instead of failing immediately while the list document is still rendering.
+- Preserve a zero-delay fast path: check immediately, then poll the current main-frame document at a short interval only while the button is absent, with one bounded pre-write timeout.
+- Add focused regression coverage and publish a synchronized Chrome extension `0.5.166` source/package baseline, including the platform minimum version, mappings, release gate, archive, and release manifest.
+- Assess a server-published, client-auto-updated extension channel against Chrome's current supported distribution mechanisms; do not invent an extension ID/signing key or ship a partially operable self-update channel before the managed-device/Web Store choice is known.
+
+## Intent And Constraints
+
+- The supplied production log and retry behavior identify a pre-write page-readiness race: script injection completed, but `NewBuildB` was queried before the same-path ERP frame finished rendering.
+- Reacquire `Iframe_Home.contentDocument` during each readiness probe so a stale same-path `Document` object cannot satisfy navigation; proceed as soon as a connected, enabled add button exists.
+- Keep the wait entirely before the click and before any ERP write. Do not add automatic business-operation retry or weaken any existing product, form, preflight, write, or requery gate.
+- Follow `RELEASE-001`: extension source, version strings, platform minimum, mappings, tests, ZIP, archived superseded package/manifest, and `dist/release-manifest.json` must remain synchronized.
+- Chrome Manifest V3 remote-code restrictions remain intact. True silent updates must use Chrome Web Store distribution or a same-key signed CRX installed through supported enterprise policy; the existing unpacked ZIP workflow cannot silently replace itself.
+- Do not access ERP, reload/install extensions, deploy services, mutate tasks/runtime data, inspect secrets, create signing keys, or publish externally in this Feature task.
+- Other registered local tasks do not semantically conflict. The only related release-export task was read-only, and the main checkout remains owned by a separate migration/restart task.
+
+## Outcome
+
+- Added an adaptive pre-write readiness gate for `shared_plan_create`: the extension checks the current ERP list document immediately, then reacquires `Iframe_Home.contentDocument` every 100 ms only while the connected, enabled `NewBuildB` button is absent, with a 15-second total timeout.
+- `createSplitParentLive` now clicks the exact button/document returned by that gate. A timeout remains a fail-closed pre-write blocker and does not retry the business operation or weaken any existing form, save, or requery evidence gate.
+- Added a static regression that proves the zero-delay fast path, current-frame reacquisition, connected/enabled checks, bounded polling, and removal of the former immediate one-shot button query.
+- Synchronized the extension, platform minimum, lifecycle/plan mappings, business documentation, release gate, tests, and release manifest at `0.5.166`; built `dist/ltjt-order-assistant-0.5.166.zip` with SHA-256 `68aeda857f0bf596eed3c5012fb37c6292977935ff215ce1d133983a8dffe259`.
+- Archived the superseded `0.5.165` ZIP and its release manifest under `archive/releases/2026-09-03/`, with a non-current-history notice. No unique release artifact was deleted.
+- Confirmed the current manually loaded unpacked/ZIP extension cannot silently replace itself. Chrome-supported unattended updates require either Chrome Web Store distribution or a same-key signed CRX delivered by HTTPS and installed through enterprise policy on Windows/macOS.
+- Recommended an unlisted/private Chrome Web Store listing when the cloud PCs are unmanaged; if every PC is enrolled in AD/Azure AD, Chrome Enterprise Core, or another MDM, a self-hosted signed-CRX channel can instead use the project's server for `update.xml` and CRX publication.
+- Deliberately did not add a nonfunctional in-extension downloader: an extension cannot install its own ZIP/CRX, remote executable code remains prohibited under Manifest V3, and the correct manifest, signing, publication, and policy design depends on the user's managed-device answer. Either supported route needs one final manual migration away from the existing unpacked installation.
+- No ERP page, browser installation, extension runtime, signing key, Web Store listing, service, deployment, live task, or external system was changed.
+
+## Verification
+
+- Focused adaptive-entry regression: passed as part of the legacy suite.
+- `node --check chrome-extension/ltjt-order-assistant/inpage.js`: passed.
+- JSON parsing for the changed mappings and extension manifest: passed.
+- `unzip -t dist/ltjt-order-assistant-0.5.166.zip`: passed; the archive contains the same 19 files as the governed extension source.
+- `node --run check:repo`: 10/10 passed.
+- `node --run check`: passed.
+- `node --run test:control-plane`: 159/159 passed.
+- `node --run test:legacy`: 269/269 passed.
+- `node --run build`: passed.
+- `check_project_docs.py`: passed.
+- `check_doc_drift.py --task-id 20260903-adaptive-wait-auto-update-7b3e9a2c`: passed.
+- `git diff --check`: passed.
+- Full verification used a temporary symlink to the existing dependency tree in the isolated worktree; the symlink was removed afterward and is not part of the task output.
+
+## Follow-ups
+
+- Integrate and deploy/reload `0.5.166` only under separate authorization. Until then, the running browser extension remains unchanged, and this release still requires the existing manual installation procedure.
+- Ask whether all target cloud PCs are enterprise-managed. After that answer, implement exactly one supported unattended-update channel: Web Store publication for unmanaged PCs, or same-key signed CRX + HTTPS update manifest + managed install policy for enterprise-managed PCs.
+- For either channel, let Chrome own installation and periodic updates. An optional client action may call `chrome.runtime.requestUpdateCheck()` and report availability, but it must not force-reload the extension while an ERP task is active.
+
+## Promotion Candidates
+
+- Target documents: release/distribution architecture, operator deployment guidance, and the extension release decision record.
+- Proposed durable fact: unpacked extensions are development installations and cannot be silently self-updated; production unattended updates must use a Chrome-supported Web Store or enterprise-policy signed-CRX channel, preserve Manifest V3's no-remote-code boundary, and avoid reloading during an active ERP operation.
+- Evidence: Chrome's official extension distribution, self-hosting, update lifecycle, and Manifest V3 migration documentation; this task's source/package synchronization and full regression results.
+- Future-task impact: release automation must retain one stable extension identity and signing authority, publish monotonically increasing versions, expose a recoverable rollback path, and treat the one-time migration from unpacked installs as an operator-controlled rollout.
+- Human confirmation required: choose unmanaged/Web Store versus enterprise-managed/self-hosted distribution and identify who owns the stable extension identity/signing credentials. No secret or identity should be generated implicitly.