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