managed-portal/tasks/lessons.md

Lessons

2026-05-12

• Trigger: the user corrected the execution workflow for non-trivial tasks and required persistent task tracking.

• Rule: for any non-trivial task, create or update tasks/todo.md before substantive implementation, keep progress current, and do not mark done without review evidence.

• Preventive action: check for tasks/todo.md, tasks/lessons.md, and repository guidance files before editing code; if the user corrects process expectations, record the rule immediately.

• Trigger: the user required corrections to be persisted for future sessions.

• Rule: any user correction must be recorded in tasks/lessons.md as trigger -> rule -> preventive action.

• Preventive action: after any correction, update lessons before closing the task and mention the recorded rule in the final verification summary.

• Trigger: the user clarified that this repository is meant to run in mainland China environments.

• Rule: future code, build, deployment, and integration changes must consider mainland China network accessibility and should prefer China-friendly defaults where practical.

• Preventive action: when adding dependencies, mirrors, external endpoints, or download flows, explicitly check whether the default path works reliably in mainland China and add configuration or fallback when needed.

• Trigger: the user required deployment to use docker compose only and explicitly disallowed host environment changes.

• Rule: for remote rollout tasks in this repo, prefer repository-contained docker compose changes and do not install packages, edit host configs, or mutate global environment state unless the user explicitly approves it.

• Preventive action: when a deployment is blocked, first fix Dockerfiles, compose files, env files, and mounted paths inside the repo before considering any host-level workaround.

2026-05-15

• Trigger: the .11 OTA bundle host did not have a zip executable, and the current Python containers no longer exposed the historical lap overlay paths.
• Rule: OTA bundle publication must not assume host archive tools or historical runtime overlay paths are present.
• Preventive action: when cutting a release, package the ZIP with Python stdlib if zip is unavailable, treat overlay extraction as optional unless the paths are verified live in containers, and validate the final archive contents before upload.

2026-05-18

• Trigger: the user clarified that OTA installer updates should not keep repackaging and uploading the whole repository tree or fixed people_flow_project weights.
• Rule: managed-portal OTA releases should ship a minimal ZIP with deploy metadata and managed config only; people_flow_project weights should be reused from a stable host location unless the weights themselves changed or the host is new.
• Preventive action: when preparing OTA artifacts, use the minimal packaging script, exclude managed/people_flow_project/weights by default, and only publish a weights-bearing bundle for first-time installs or actual weight updates.

2026-05-19

• Trigger: the user corrected the OTA publication login for 10.8.0.1.

• Rule: the OTA web host 10.8.0.1 must be published with root, not xiaozheng.

• Preventive action: for future managed-portal OTA rollouts, verify publication access against root@10.8.0.1:/var/www/html/ai_deploy before treating upload as blocked.

• Trigger: the user clarified that all new installation targets are Ubuntu machines and asked for missing unzip to be handled automatically, with weights delivered separately.

• Rule: the managed-portal OTA installer should treat Ubuntu as the first-install baseline, auto-install unzip via apt-get when needed, and use a separate people-flow weights archive instead of forcing weights into the main ZIP.

• Preventive action: keep the main OTA ZIP minimal, publish people-flow-weights-<RELEASE_VERSION>.tar.gz alongside each release when weights are available, and validate that the installer still reuses shared weights on upgrades.