managed-portal/AGENTS.md

AGENTS.md

This file constrains future work in this repository. Follow it for all non-trivial changes.

Repository Snapshot

• Root purpose: managed-portal is a standalone management portal for managed services and web devices.
• Backend: Go service under cmd/managed-portal and internal/.
• Frontend: Vue 3 + Vite + Element Plus app under web/.
• Managed child services: Python projects under managed/people_flow_project/ and managed/store_dwell_alert/.
• Deployment assets: deploy/, root Dockerfile, managed_services.yaml.
• Primary default ports from the current README: backend 9080, frontend 13000, child service APIs 18081 and 18082.
• Operating environment: this repository is intended for use in mainland China, so future changes must account for China-network constraints and domestic deployment realities.

Repository Map

• cmd/managed-portal/: Go backend entrypoint.
• internal/config/: backend configuration loading.
• internal/managed/: managed service registry, runtime, remote client, orchestration logic.
• internal/server/: HTTP server and handlers.
• internal/webdevice/: web device proxying, rewriting, and related service logic.
• web/src/: frontend app, router, API client, and views.
• managed/people_flow_project/: Python people-flow service with src/, tests/, deployment scripts, and weights.
• managed/store_dwell_alert/: Python store-dwell-alert service with app/, tests/, deployment scripts, and weights.
• deploy/: Docker Compose deployment files and env files.
• docs/: rollout and integration documentation.
• tasks/: task plan, review evidence, and lessons learned.

Workflow Orchestration

1) Plan Node Default

• For any non-trivial task, enter plan mode before implementation.
• Treat a task as non-trivial if any of the following is true:
  • it needs 3 or more steps;
  • it involves architecture, sequencing, or cross-file decisions;
  • it requires a verification chain, not just a code edit.
• Write the specification, scope, risks, and validation approach before making substantive changes.
• If execution drifts, gets blocked, or a core assumption fails, stop and re-plan instead of forcing the current path.
• Validation steps are part of the plan and are never optional.

2) Subagent Strategy

• Prefer subagents for exploration, repository search, investigation, and parallel analysis.
• Keep one subagent focused on one clear tactical question.
• For complex tasks, split exploration into parallel subproblems to protect the main context window.
• Keep the main agent focused on decisions, edits, and verification.

3) Self-Improvement Loop

• At the start of a non-trivial task, quickly review tasks/lessons.md for rules relevant to the current work.
• Any user correction must update tasks/lessons.md.
• Record corrections in trigger -> rule -> preventive action form.
• Use recorded lessons to prevent repeating the same process or decision error.

4) Verification Before Done

• Do not mark work complete without verification evidence.
• When applicable, compare before and after behavior, not just changed files.
• Run the narrowest meaningful validation first, then widen only if needed.
• Report executable evidence such as tests, builds, lint, config checks, or log output.
• Ask whether the result meets a staff-engineer standard before closing the task.

5) Demand Elegance (Balanced)

• Before a non-trivial change, ask whether a simpler, more robust design is available.
• Replace obviously hacky solutions with the best reasonable implementation supported by current information.
• Do not over-design straightforward fixes.

6) Autonomous Bug Fixing

• Treat bug reports as requests to diagnose and fix, not as prompts for the user to drive every step.
• Use logs, failing behavior, and targeted tests to find the root cause.
• Close the loop with a fix plus validation inside task scope.
• When CI-like failures are in scope, investigate and repair them autonomously.

Task Management

1) Plan First

• Before substantive implementation on a non-trivial task, create or update tasks/todo.md.
• The plan must use checkboxes and include scope, risks, and validation intent.

2) Verify Plan

• Confirm the plan covers the user request, repository-specific risks, and the expected verification path before coding.

3) Track Progress

• Update tasks/todo.md as tasks are completed.
• Keep plan state accurate enough that another engineer could resume from it.

4) Explain Changes

• For each major step, provide a high-level explanation of what changed and why.

5) Document Results

• tasks/todo.md must contain a Review section with result and verification evidence.

6) Capture Lessons

• If the user corrected the process, assumptions, or implementation direction, update tasks/lessons.md before closing the task.

Core Principles

• Simplicity First: prefer the smallest change that fully solves the problem.
• No Laziness: find the real cause and avoid cosmetic patches.
• Minimal Impact: limit edits to the necessary surface and reduce regression risk.

China Mainland Environment Constraints

• Assume the software will run in mainland China networks by default.
• Prefer China-accessible defaults for package mirrors, container registries, and third-party endpoints when code or documentation needs a default choice.
• Do not hard-code dependencies on services that are commonly inaccessible or unstable from mainland China unless there is an explicit fallback or configurability.
• When adding build, install, or deployment steps, consider whether Go, Node, Python, Docker, and model-download paths need domestic mirror support.
• When integrating external APIs, downloads, or web assets, make network reachability, timeout behavior, and fallback strategy explicit.
• Keep region-specific choices configurable so the repo can still run elsewhere, but mainland China should be the default assumption.

Repo-Specific Change Rules

Backend Go Rules

• Backend entry code belongs in cmd/managed-portal/; business logic belongs in internal/.
• Keep configuration behavior coherent across internal/config/, deploy/, and the README when ports, env vars, or service addresses change.
• When editing service management logic, check adjacent tests in internal/managed/, internal/server/, and internal/webdevice/.
• Prefer focused package tests before full-repo Go tests.

Frontend Rules

• Frontend changes belong under web/src/ and should respect the current Vite + Vue 3 structure.
• When changing routes, views, or API calls, verify the corresponding backend endpoints or proxy paths still match.
• Prefer minimal UI changes consistent with the existing portal instead of introducing a new design language.

Managed Python Service Rules

• Treat managed/people_flow_project/ and managed/store_dwell_alert/ as embedded but separately testable projects.
• Keep edits contained to the relevant child service unless a shared contract change requires broader updates.
• Preserve deployment/runtime assumptions in each child project's scripts, configs, and tests.
• Be careful with large model weights and local config files; do not assume ignored assets exist in source control.

Deployment And Operations Rules

• For changes touching deploy/docker-compose.yml, env files, root Dockerfile, or child-service Docker assets, verify configuration consistency.
• For registry or service-address changes, keep managed_services.yaml, deployment files, and README examples aligned.
• Do not bulk-sync from external directories into this repo without a diff plan, overwrite-risk check, and rollback path.
• For dependency installation, image builds, or artifact downloads, prefer defaults that are reliable from mainland China or document the required mirror configuration.

Validation Matrix

• Go backend changes:
  • Prefer targeted go test commands for touched packages.
  • Use go test ./... when the change spans multiple backend packages or contracts.
• Frontend changes:
  • Prefer pnpm build in web/ for structural verification.
  • Use narrower checks when available, but do not skip build validation for meaningful UI or routing changes.
• Python child service changes:
  • Prefer targeted test files under each project's tests/ directory.
  • Expand to broader test runs only when the change crosses module boundaries.
• Deployment/configuration changes:
  • Validate with the narrowest config check available, such as compose config rendering or related test coverage.
• Documentation-only changes:
  • Verify file presence, required sections, and consistency with the current repository structure.

Required Artifacts For Non-Trivial Tasks

• tasks/todo.md: current checklist, scope, risks, and review evidence.
• tasks/lessons.md: updated whenever the user corrects the workflow or technical direction.
• Final response: concise summary, what was verified, and any residual risk or natural next step.

Definition Of Done

Do not close a non-trivial task until all of the following are true:

1. The request is fully covered.
2. Plan items in tasks/todo.md are updated.
3. Key verification has run and is reproducible.
4. tasks/todo.md includes a completed Review section.
5. tasks/lessons.md was updated for any user correction in the task.