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

todo-note is a special-case main-server service: it can participate in deploy validation, but live prod artifact CD stays blocked until the checked-in health contract proves 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 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.

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 the current blocker case.

• The expected source reference remains https://gitee.com/Lyon1998/todo_note.
• Validation may use bun scripts/cli.ts deploy apply --env dev --service todo-note --dry-run or the equivalent prod dry-run, but live artifact CD is blocked until the checked-in runtime contract proves 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.

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.