pikasTech-unidesk/docs/reference/user-service-delivery.md

User Service Delivery Policy

This document owns the default delivery path for UniDesk user services registered in config.json.microservices[], together with the paired frontend verification expectations for those services. It does not replace docs/reference/deploy.md, docs/reference/ci.md, docs/reference/dev-environment.md, or docs/reference/microservices.md; it states the default release order that future user-service work should follow unless a service-specific exception is documented.

Scope

User services are non-core business services mounted onto the UniDesk platform. They must remain deliverable without changing the base platform strategy. The default policy here applies to user services that are expected to reach production after validation, including the UniDesk user-service UI artifact (frontend), main-server direct services such as Baidu Netdisk, D601-managed k3s services such as Decision Center, MDTODO and ClaudeQQ, and D601 direct Docker/Compose services such as FindJob and Pipeline. Code Queue is a special dev-only artifact consumer in this policy; its production execution plane must not be deployed by the user-service artifact consumer.

This policy does not apply to:

• core platform services;
• CI/CD infrastructure itself;
• provider-gateway;
• k3sctl-adapter;
• release/v1 governance;
• one-off infrastructure repair actions.
• production Code Queue artifact deploy or rollout.

todo-note is a special-case main-server service because its source repository remains external. Its master-server Compose artifact consumer still follows the runtime contract: UNIDESK_TODO_NOTE_DEPLOY_* is injected at recreate time, and the consumer health probe combines the service /api/health response with that runtime metadata before checking deploy.commit and deploy.requestedCommit.

Default Release Flow

The default release flow for a user-service change is:

1. CI builds the user-service image on D601 from a pushed Git commit.
2. CI publishes the commit-pinned image to the D601 host-managed registry.
3. The dev environment runs automated validation against that same commit-pinned artifact.
4. CD on the production side pulls the registry artifact and deploys it without rebuilding the source.
5. Manual acceptance is performed after the live deployment has been verified.

Operating Rules

• CI may carry heavier dependency resolution, build cache, and test cost than CD.
• CD must stay low-dependency and fast.
• No user-service artifact may rely on a third-party registry as source of truth.
• No production deploy may rebuild the source from a dirty worktree.
• Commit-pinned image tags are the deployment truth; mutable latest tags are not.
• Root CI.json is an artifact catalog only. It lists CI producer inputs such as serviceId, artifact kind, source repository, repo-relative Dockerfile, image repository naming, upstream image digest/mirror metadata and the required artifact summary fields; it must not carry runtime topology or replace deploy.json.
• deploy.json is the only release-intent source for desired commits, image pins and deployment-time parameters that must stay consistent across CI, dev CD and prod CD. Runtime manifests, health metadata and helper config may mirror those values only as derived copies; if they diverge, deploy.json wins. The consolidation track is GitHub issue #60.
• The standard CI artifact producer is bun scripts/cli.ts ci publish-user-service --service <id> --commit <full-sha>. It accepts only a pushed Git commit and a service id registered in CI.json, reads source.repo and source.dockerfile from that catalog, rejects ad hoc --repo overrides, and reports serviceId, sourceCommit, sourceRepo, dockerfile, imageRef, tag, digest and digestRef.
• The producer dry-run preflight is bun scripts/cli.ts ci publish-user-service --service <id> --commit <full-sha> --dry-run. It is read-only and reports detailed missingChannels plus stable missingControlChannels for backend-core, database, provider and registry; any missing control channel is runnerDisposition=infra-blocked. The controlledPublish field names D601 unidesk-ci as the only controlled environment for the subsequent real publish.
• The CI artifact producer is not a deploy executor. It must not mutate the production namespace, restart production services, or update deploy.json.
• CI.json may list blocked source-build entries when the source input is known but the publish/CD boundary is not yet reviewed. It may also list upstream-image entries for image-only services such as File Browser; those entries pin upstream digest and mirror intent but must not be treated as Dockerfile builds.
• Every production release must finish with a manual acceptance step after the automated checks pass.
• Multi-service delivery programs may use Code Queue parallelization, but the supervisor must follow docs/reference/code-queue-supervision.md: tasks need self-contained prompts, isolated worktrees, bounded queue concurrency, explicit acceptance evidence, and infrastructure defects split into separate follow-up tasks when they block several lanes.

Upstream Image Services

Some registered user services are intentionally upstream-image consumers instead of source-built services. filebrowser and filebrowser-d601 are in this class.

• They must be cataloged as CI.json.artifacts[] entries with kind=upstream-image, not as Dockerfile source-build producers.
• ci publish-user-service must return a structured blocked result for them; there is no UniDesk Dockerfile build for these services.
• The release input is an upstream manifest digest or a digest-verified mirror in the D601 registry, not a Git commit tag built by Tekton.
• CD must be pull-only and must verify the image identity, OCI labels and service health through the UniDesk private proxy.
• Until the upstream digest has been resolved and mirrored or pinned for a future mirror producer, File Browser remains a recovery/diagnostic image-only path rather than a standard release path.

The current catalog covers frontend, baidu-netdisk, decision-center, project-manager, oa-event-flow, todo-note, code-queue-mgr, findjob, pipeline, met-nonlinear, k3sctl-adapter, mdtodo and claudeqq as supported publish-user-service source-build services. k3sctl-adapter is cataloged for artifact visibility, but it is not a user-service live deploy target in this policy. code-queue is cataloged but blocked by the D601 dev/prod boundary. filebrowser and filebrowser-d601 are cataloged as pinned upstream images, not source builds.

Frontend Pairing

Many user services are surfaced through the UniDesk frontend rather than through their own browser-exposed product. When a user-service backend has a paired UniDesk frontend page, the frontend change must be validated in the same dev/prod release window as the backend artifact. The frontend itself is also a reviewed artifact producer/consumer sample: its release unit is 127.0.0.1:5000/unidesk/frontend:<commit>, and the live UI must expose the same requested commit through image labels and /health.deploy.commit.

The paired frontend's default route must continue to expose the real user workflow. Diagnostics or status surfaces may exist for verification and recovery, but they must stay explicit secondary routes and must not replace the default product entry. The traceability record for this boundary is DC-DCSN-P0-2026-004.

Frontend

Frontend is the canonical user-service UI sample. It is not released by target-side source build as the standard path.

• The minimal standard artifact command is bun scripts/cli.ts ci publish-user-service --service frontend --commit <full-sha> --wait-ms 1200000.
• The expected artifact is 127.0.0.1:5000/unidesk/frontend:<commit> plus its registry digest from the CI output.
• The lightweight closure contract is bun scripts/frontend-artifact-lane-contract-test.ts. It checks deploy.json dev/prod desired commits, the CI.json producer entry, the observed registry digest, dev/prod /health.deploy.commit and deploy.requestedCommit, producer dry-run readiness, and dev/prod CD dry-run no-build targets.
• Dev CD consumes the same artifact with bun scripts/cli.ts deploy apply --env dev --service frontend; it imports the image into D601 native k3s, rolls out frontend-dev, syncs auth/session metadata from main-server config, and verifies /health.deploy.commit.
• Production CD consumes the same artifact with bun scripts/cli.ts deploy apply --env prod --service frontend; it recreates only the master-server Compose frontend service with --no-build --no-deps --force-recreate and verifies image labels plus /health.deploy.commit.
• server rebuild frontend remains a maintenance/local rebuild path only. It is not the standard versioned release truth for frontend.
• Production acceptance must explicitly verify the public /health payload, the requested commit, the running image label, and the expected UI routes for the changed user-service pages.

Baidu Netdisk

Baidu Netdisk is the canonical main-server direct user-service sample.

• The minimal standard artifact command is bun scripts/cli.ts ci publish-user-service --service baidu-netdisk --commit <full-sha> --wait-ms 1200000.
• The expected artifact is 127.0.0.1:5000/unidesk/baidu-netdisk:<commit> plus its registry digest from the CI output.
• Dev validation consumes the same artifact with bun scripts/cli.ts deploy apply --env dev --service baidu-netdisk; this is a pull-only Compose validation path, not a source build on the master server.
• Production CD consumes the same artifact with bun scripts/cli.ts deploy apply --env prod --service baidu-netdisk; it recreates only baidu-netdisk-backend and verifies image labels plus /health.deploy.commit.
• server rebuild baidu-netdisk remains a maintenance/local rebuild path only. It is not the standard versioned release truth for Baidu Netdisk.
• Production acceptance must explicitly verify microservice health baidu-netdisk, microservice proxy baidu-netdisk /api/transfers, private 4244 exposure, and live commit / artifact information.

Project Manager

Project Manager follows the same commit-pinned artifact flow as Baidu Netdisk, but the runtime target is the master-server Compose service project-manager.

• The minimal standard artifact command is bun scripts/cli.ts ci publish-user-service --service project-manager --commit <full-sha> --wait-ms 1200000.
• The expected artifact is 127.0.0.1:5000/unidesk/project-manager:<commit> plus its registry digest from the CI output.
• Dev CD consumes the same artifact with bun scripts/cli.ts deploy apply --env dev --service project-manager; prod CD consumes it with bun scripts/cli.ts deploy apply --env prod --service project-manager.
• server rebuild project-manager remains a maintenance/local rebuild path only. It is not the standard versioned release truth for Project Manager.
• Production acceptance must explicitly verify microservice health project-manager, microservice proxy project-manager /api/projects, private 4233 exposure, and live commit / artifact information.

OA Event Flow

OA Event Flow follows the same master-server Compose artifact flow as Project Manager.

• The minimal standard artifact command is bun scripts/cli.ts ci publish-user-service --service oa-event-flow --commit <full-sha> --wait-ms 1200000.
• The expected artifact is 127.0.0.1:5000/unidesk/oa-event-flow:<commit> plus its registry digest from the CI output.
• Dev CD consumes the same artifact with bun scripts/cli.ts deploy apply --env dev --service oa-event-flow; prod CD consumes it with bun scripts/cli.ts deploy apply --env prod --service oa-event-flow.
• server rebuild oa-event-flow remains a maintenance/local rebuild path only. It is not the standard versioned release truth for OA Event Flow.
• Production acceptance must explicitly verify microservice health oa-event-flow, microservice proxy oa-event-flow /api/diagnostics, private 4255 exposure, and live commit / artifact information.

Code Queue Manager

code-queue-mgr is the master-server internal sidecar control plane, so it follows artifact consumer validation but not unrestricted prod automation.

• The minimal standard artifact command is bun scripts/cli.ts ci publish-user-service --service code-queue-mgr --commit <full-sha> --wait-ms 1200000.
• The expected artifact is 127.0.0.1:5000/unidesk/code-queue-mgr:<commit> plus its registry digest from the CI output.
• Dev validation uses bun scripts/cli.ts deploy apply --env dev --service code-queue-mgr; prod dry-run uses bun scripts/cli.ts deploy apply --env prod --service code-queue-mgr --dry-run.
• Live prod apply requires explicit supervisor confirmation and is not the worker default.
• server rebuild code-queue-mgr remains a maintenance/local rebuild path only. It is not the standard versioned release truth for Code Queue Manager.
• Production acceptance must explicitly verify microservice health code-queue-mgr, the Compose container image label, and the live health payload.

Todo Note

Todo Note is an external-source main-server Compose service that follows the standard commit-pinned artifact consumer flow.

• The expected source reference remains https://gitee.com/Lyon1998/todo_note.
• The standard producer is bun scripts/cli.ts ci publish-user-service --service todo-note --commit <full-sha> --wait-ms 1200000; it fetches the external Gitee repo at that commit and builds that repo's Dockerfile, rather than treating Todo Note as UniDesk-owned source.
• Dev/prod CD require the D601 registry artifact 127.0.0.1:5000/unidesk/todo-note:<commit> published from that external source.
• Dev CD consumes the same artifact with bun scripts/cli.ts deploy apply --env dev --service todo-note; prod CD consumes it with bun scripts/cli.ts deploy apply --env prod --service todo-note.
• The Compose runtime injects UNIDESK_TODO_NOTE_DEPLOY_REF, UNIDESK_TODO_NOTE_DEPLOY_SERVICE_ID, UNIDESK_TODO_NOTE_DEPLOY_REPO, UNIDESK_TODO_NOTE_DEPLOY_COMMIT, and UNIDESK_TODO_NOTE_DEPLOY_REQUESTED_COMMIT; the consumer health probe must return matching deploy.commit and deploy.requestedCommit.
• server rebuild todo-note remains a maintenance/local rebuild path only. It is not the standard versioned release truth for Todo Note.

D601 Direct Compose Consumers

FindJob and Pipeline are D601 direct Docker/Compose user services. They differ from k3s-managed services because the artifact consumer operates on the D601 Docker host and the existing Compose project, not on Kubernetes manifests, containerd imports, or Kubernetes API service proxies.

• findjob consumes 127.0.0.1:5000/unidesk/findjob:<commit> and recreates only Compose service server in /home/ubuntu/findjob.
• pipeline consumes 127.0.0.1:5000/unidesk/pipeline:<commit> and recreates only Compose service pipeline-control in /home/ubuntu/pipeline.
• Dev validation currently means D601 registry pull + required image labels + config/compose dry-run + health contract. It is not yet a separate parallel dev instance.
• Production CD is pull-only and no-build: it verifies the registry manifest and image labels, writes deploy env/labels, and runs docker compose up -d --no-build --no-deps --force-recreate <service>.
• met-nonlinear has the same dry-run/plan shape, but live deploy is blocked until the long-running met-nonlinear-ts image contract can prove the requested commit label independently from the ML image Dockerfile.
• k3sctl-adapter has an artifact consumer plan/dry-run only. Real production deployment of that infrastructure bridge requires supervisor confirmation outside this policy.

Decision Center

Decision Center is the canonical example of a user service that doubles as a product workflow for requirements, decisions, and daily work diaries.

• The minimal standard artifact command is bun scripts/cli.ts ci publish-user-service --service decision-center --commit <full-sha> --wait-ms 1200000.
• The expected artifact is 127.0.0.1:5000/unidesk/decision-center:<commit> plus its registry digest from the CI output.
• Dev and prod CD both consume that same commit-pinned artifact contract through the D601 registry artifact consumer; dev lands in unidesk-dev, prod lands in the production k3s namespace, and both must prove deploy.commit and deploy.requestedCommit.
• Requirements and follow-up items should be represented with structured records such as goal, decision, blocker, debt, and experiment, with linked evidence and goal references.
• The service should act as a demand-management surface for external goals that need to be decomposed into internal tasks, blockers, and decisions.
• The document-management surface must support the engineering document number format DC-<TYPE>-<PRIORITY>-<YEAR>-<SEQ> defined in docs/reference/microservices.md, including unique docNo storage, 4-letter document type codes, P-level priority, signing metadata, replacement links and list/detail filtering by document number.
• The work-diary surface should support creating today's diary entry automatically from the real current date.
• Historical diary entries should be editable by date, with PostgreSQL remaining the source of truth.
• The resulting product surface should stay structured and reviewable, not collapse into an untracked chat log.
• Before any production deploy, the dev gate must pass first with the focused Decision Center E2E set covering microservice:decision-center-record-crud, microservice:decision-center-diary-lifecycle, frontend:decision-center-visible, frontend:decision-center-demand-management-visible, and frontend:decision-center-diary-visible; this is an automated user-service validation gate, not a production deploy.
• Document-management changes must first land in the D601 dev Decision Center service and extend the focused E2E set with doc-number creation/upsert/list/detail uniqueness, migration/backfill, frontend visibility and temporary body-prefix compatibility before production rollout.
• Production acceptance is manual after the dev gate and must explicitly verify health, records, diary editor, the paired frontend page, no public business ports, and live commit / artifact information.
• Acceptance notes may cite diagnostics/status pages as evidence, but those pages must be labeled as diagnostics and not as the default user workflow.

Detailed service-level API and UI contracts remain in docs/reference/microservices.md.

MDTODO

MDTODO is a k3s-managed user-service artifact consumer.

• The minimal standard artifact command is bun scripts/cli.ts ci publish-user-service --service mdtodo --commit <full-sha> --wait-ms 1200000.
• The expected artifact is 127.0.0.1:5000/unidesk/mdtodo:<commit> plus its registry digest from the CI output.
• The selected commit must include the UNIDESK_DEPLOY_* health metadata contract; bun scripts/issue-9-mdtodo-health-metadata-contract-test.ts is the focused local guard for /health.deploy and /live.deploy.
• Dev CD must run before prod CD and lands in unidesk-dev/mdtodo-dev; production CD lands in unidesk/mdtodo.
• Both paths must verify Deployment metadata and /health or /live deploy commit through the Kubernetes API service proxy.
• No MDTODO release may add NodePort, hostPort, public business ports or provider-gateway direct business backends.

ClaudeQQ

ClaudeQQ is a k3s-managed user-service artifact consumer built from the external https://gitee.com/lyon1998/agent_skills repository with UniDesk deployment assets overlaid.

• The minimal standard artifact command is bun scripts/cli.ts ci publish-user-service --service claudeqq --commit <full-sha> --wait-ms 1200000.
• The expected artifact is 127.0.0.1:5000/unidesk/claudeqq:<commit> plus its registry digest from the CI output.
• Dev CD must run before prod CD and lands in unidesk-dev/claudeqq-dev; production CD lands in unidesk/claudeqq.
• Both paths must verify Deployment metadata and service health through the Kubernetes API service proxy.
• No ClaudeQQ release may expose NapCat or backend ports through NodePort, hostPort, public business ports or provider-gateway direct business backends.

Code Queue

Code Queue is dev-only for this artifact-consumer policy.

• The minimal standard artifact command is bun scripts/cli.ts ci publish-user-service --service code-queue --commit <full-sha> --wait-ms 1200000.
• The expected artifact is 127.0.0.1:5000/unidesk/code-queue:<commit> plus its registry digest from the CI output.
• Dev CD may be planned only with deploy apply --env dev --service code-queue --dry-run or the equivalent artifact-registry dry-run from a Code Queue task. The dry-run must expose selfBootstrapGuard, requiresSupervisorApproval, commit tag/digest provenance and pull-only/no-build behavior; any real DEV apply that updates unidesk-dev scheduler/read/write/provider-egress-proxy objects requires human operator or supervisor authorization outside the running Code Queue task.
• Production artifact deploy, production rollout and production manifest mutation for code-queue are unsupported and must fail visibly.