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, and D601-managed services such as Decision Center.

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.

Default Release Flow

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

CI builds the user-service image on D601 from a pushed Git commit.
CI publishes the commit-pinned image to the D601 host-managed registry.
The dev environment runs automated validation against that same commit-pinned artifact.
CD on the production side pulls the registry artifact and deploys it without rebuilding the source.
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 can list user-service CI build inputs such as serviceId, sourceRepo, dockerfile, image repository naming and the required artifact summary fields; it must not carry runtime topology or replace deploy.json.
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 registered service id, and reports serviceId, sourceCommit, sourceRepo, dockerfile, imageRef, tag, digest and digestRef.
The CI artifact producer is not a deploy executor. It must not mutate the production namespace, restart production services, or update deploy.json.
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 upstream images, not as CI.json.artifacts[] Dockerfile producers.
ci publish-user-service must reject 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, File Browser remains a recovery/diagnostic image-only path rather than a standard release path.

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.

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.
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.

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 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.
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.

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

8.8 KiB Raw Blame History