# User Service Delivery Policy

本文中的 `mdtodo` 是遗留用户服务名；任务管理与迁移统一遵循 `$unidesk-tasktree`。

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, NC01-managed k8s services such as Decision Center and Todo Note, D601-managed k3s services such as 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 UniDesk-vendored NC01 service with a service-specific Pipelines-as-Code producer and Argo CD consumer. It is intentionally outside the generic D601 `ci publish-user-service` and `deploy apply --env ...` flow.

## 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 release-intent source for services owned by the generic deploy reconciler. NC01 YAML-first services use their service YAML and PaC/GitOps branch as desired-state truth instead; they must not be duplicated into `deploy.json` as an active consumer. The consolidation track is [GitHub issue #60](https://github.com/pikasTech/unidesk/issues/60).
- For artifacts whose `CI.json` producer is `ci publish-user-service`, the standard command 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 to that producer, reads `source.repo` and `source.dockerfile` from the catalog, rejects ad hoc `--repo` overrides, and reports `serviceId`, `sourceCommit`, `sourceRepo`, `dockerfile`, `imageRef`, `tag`, `digest` and `digestRef`. Services owned by another producer are rejected before any remote action and the CLI names the owning entrypoint.
- 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`, `code-queue-mgr`, `findjob`, `pipeline`, `met-nonlinear`, `k3sctl-adapter`, `mdtodo` and `claudeqq` as supported `publish-user-service` source-build services. Todo Note remains a supported source build, but its producer is `platform-infra pipelines-as-code`. `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 follows the same NC01 YAML-first and GitHub-backed operating model as Decision Center, while retaining its existing action/history API contract.

- Source is vendored at `src/components/microservices/todo-note`; `config/unidesk-host-k8s.yaml` is the runtime, Secret, storage and delivery source of truth.
- Production runs as private `unidesk/deployment/todo-note` and `unidesk/service/todo-note`. It has no NodePort, hostPort or separate public frontend.
- `CI.json` assigns the source build to `platform-infra pipelines-as-code`. `ci publish-user-service --service todo-note` must reject the request before contacting D601.
- The NC01 PaC consumer is `unidesk-host`, reusing Repository `sentinel-nc01-v03`; Tekton publishes a commit image, the GitOps branch pins its digest, and Argo CD owns the Todo Note Service/Deployment.
- Durable state is GitHub repo `pikasTech/decision-center-data`, branch `main`, base path `todo-note`. Decision Center keeps base path `data`, so the services share one repository without sharing object paths. PostgreSQL is an index/cache only.
- GitHub SSH credentials come only from the YAML-declared Secret sourceRef shared with Decision Center; CLI output exposes presence and fingerprints, never key material.
- Controlled release evidence is `platform-infra pipelines-as-code plan|apply|status|closeout --target NC01 --consumer unidesk-host`, followed by `microservice health todo-note` and storage diagnostics.
- CC01 migration completed through `POST /api/storage/import`: all six lists, 1167 history rows and the reminder-notification ledger were preserved; DB/Git hashes and a create/add/update/undo/redo/delete lifecycle passed before the old container and legacy Compose/deploy ownership were retired.

## 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. Its current production truth is NC01 k8s plus GitHub repo storage; the older D601 artifact-consumer text is migration history only.

- Production deploy must use the YAML-first NC01 k8s path from `config/unidesk-host-k8s.yaml`; the live objects are `unidesk/deployment/decision-center` and `unidesk/service/decision-center`.
- Durable data must be stored in GitHub repo `pikasTech/decision-center-data` branch `main` under `data`; PostgreSQL is only an index/cache and must not be treated as the durable truth.
- GitHub SSH access must be distributed through YAML-declared Secret sourceRefs, with operator output limited to object/key presence and fingerprints.
- 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 the GitHub repo 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 through the NC01 Decision Center lane and extend the focused E2E set with doc-number creation/upsert/list/detail uniqueness, GitHub storage 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.
