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](https://github.com/pikasTech/unidesk/issues/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 AgentRun 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. Legacy Code Queue remains an archive/read-only troubleshooting surface for old tasks, not a new-task dispatch path.

## 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.
- Lightweight closure evidence 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 surface; `/health.deploy` and `/live.deploy` are verified through service health or dry-run/live entry evidence, not through default contract tests.
- 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.