docs: define user service delivery policy
This commit is contained in:
Codex
@@ -79,6 +79,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
|
||||
- `docs/reference/devops-hygiene.md`：Git-backed deployment truth、dirty worktree/manual repair 边界、受限手动操作和 CI 私有仓库 source-auth 规则。
|
||||
- `docs/reference/release-governance.md`：`release/v1` 稳定维护线、`master` 集成线、CI/CD server 版本固定、master CLI 兼容和 feature flag 治理规则；决策记录见 GitHub issue #6。
|
||||
- `docs/reference/artifact-registry.md`：D601 host-managed CNCF Distribution registry、loopback-only 边界和 backend-core artifact CD 目标流程。
|
||||
- `docs/reference/user-service-delivery.md`：用户服务默认交付流程、CI 镜像构建与 registry、dev 自动测试、prod 拉镜像部署和 Decision Center 产品化需求管理规则。
|
||||
- `docs/reference/dev-environment.md`：D601 `unidesk-dev` persistent dev 环境、18083 dev frontend proxy、`deploy apply --env dev` 服务范围和 Rust backend-core 只在 D601 编译的边界。
|
||||
- `docs/reference/ci.md`：D601 k3s Tekton CI、只读主数据库性能门禁和 CLI 入口规则。
|
||||
- `docs/reference/dev-ci-runner.md`：`ci run-dev-e2e` 的 Git 控制 runner、短 launcher、结果目录和 no-CD 边界。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# UniDesk CI On D601 k3s
|
||||
|
||||
UniDesk CI is hosted on the D601 native k3s cluster with Tekton Pipelines and Tekton Triggers. It is CI only. CD remains separate from Tekton. No Tekton task may roll out production services. CI/CD runtime-version governance follows `docs/reference/release-governance.md` and [GitHub issue #6](https://github.com/pikasTech/unidesk/issues/6).
|
||||
UniDesk CI is hosted on the D601 native k3s cluster with Tekton Pipelines and Tekton Triggers. It is CI only. CD remains separate from Tekton. No Tekton task may roll out production services. CI/CD runtime-version governance follows `docs/reference/release-governance.md` and [GitHub issue #6](https://github.com/pikasTech/unidesk/issues/6). The default user-service release order is owned by `docs/reference/user-service-delivery.md`.
|
||||
|
||||
## Components
|
||||
|
||||
|
||||
@@ -40,7 +40,7 @@ The root `deploy.json` is the single desired-state source for both prod and dev.
|
||||
|
||||
The optional non-service execution declaration under `environments.dev` is intentionally not specified here. The only currently allowed declaration is `ci`, and its authoritative `repo`, `scriptPath`, `timeoutMs`, short launcher, host fetch boundary and no-CD rules are defined only in `docs/reference/dev-ci-runner.md`.
|
||||
|
||||
Environment mode never reads the local dirty working tree manifest. `deploy check --env ...`, `deploy plan --env ...` and `deploy apply --env ...` fetch `origin/master`, read `origin/master:deploy.json`, select `environments.<env>`, and report the manifest commit/blob, service commit IDs, target namespace, database fingerprint and Provider identity. `deploy apply --env dev` is currently enabled only for persistent D601 dev `backend-core` and `frontend`; all other D601 services remain rejected before runtime mutation. `deploy apply --env prod` remains disabled until the production environment executor and authorization policy are explicitly added. Production backend-core artifact CD is a separate executor because its build target is D601 CI while its runtime target is the master server.
|
||||
Environment mode never reads the local dirty working tree manifest. `deploy check --env ...`, `deploy plan --env ...` and `deploy apply --env ...` fetch `origin/master`, read `origin/master:deploy.json`, select `environments.<env>`, and report the manifest commit/blob, service commit IDs, target namespace, database fingerprint and Provider identity. `deploy apply --env dev` is currently enabled only for persistent D601 dev `backend-core` and `frontend`; all other D601 services remain rejected before runtime mutation. `deploy apply --env prod` remains disabled until the production environment executor and authorization policy are explicitly added. Production backend-core artifact CD is a separate executor because its build target is D601 CI while its runtime target is the master server. The default user-service delivery policy, including CI build, registry publication, dev validation, production CD and manual acceptance, is documented in `docs/reference/user-service-delivery.md`.
|
||||
|
||||
The current implementation has not yet enabled separate stable and integration dev lanes. Future lane names such as `dev-v1` and `dev-master`, or an equivalent nested schema, must be added as explicit `deploy.json` and CLI semantics before use. A deploy command must print the manifest ref it used and must not infer `release/v1` from a local branch, a dirty file, or an undocumented environment alias.
|
||||
|
||||
|
||||
@@ -229,16 +229,18 @@ D601 上必须显式使用原生 k3s kubeconfig：`KUBECONFIG=/etc/rancher/k3s/k
|
||||
|
||||
### Decision Center k3s-Managed
|
||||
|
||||
当前 Decision Center 作为 `id=decision-center` 的 `k3sctl-managed` 用户服务登记在 `config.json`，用于沉淀 Codex/人工会议后的会议记录、决议、目标、问题分级、停放事项、证据和按天工作日记。它只负责权威记录、Markdown 日记和展示，不承载通用聊天、LLM 会话窗口或自动参谋对话。
|
||||
当前 Decision Center 作为 `id=decision-center` 的 `k3sctl-managed` 用户服务登记在 `config.json`，用于沉淀 Codex/人工会议后的会议记录、决议、目标、问题分级、停放事项、证据和按天工作日记，同时也作为外部需求向内部目标分解的工作台。它只负责权威记录、Markdown 日记、需求管理和展示，不承载通用聊天、LLM 会话窗口或自动参谋对话。
|
||||
|
||||
- Orchestrator：`deployment.mode=k3sctl-managed`，`deployment.adapterServiceId=k3sctl-adapter`，`deployment.k3sServiceId=decision-center`，`backend.proxyMode=k3sctl-adapter-http`，`backend.nodeBaseUrl=k3s://decision-center`；正式链路只能是 `frontend/CLI -> backend-core -> k3sctl-adapter -> Kubernetes API service proxy -> Kubernetes Service decision-center:4277`。
|
||||
- 部署引用：后端源码位于 UniDesk 仓库 `src/components/microservices/decision-center`，Dockerfile 为 `src/components/microservices/decision-center/Dockerfile`；k3s manifest 为 `src/components/microservices/k3sctl-adapter/k3s/decision-center.k3s.json`，Kubernetes 运行清单为 `src/components/microservices/k3sctl-adapter/k3s/decision-center.k8s.yaml`，镜像名固定为 `unidesk-decision-center:d601`。主 server `docker-compose.yml` 不得加入该服务，也不得公开 `4277`。
|
||||
- 状态权威：Decision Center 必须写入主 PostgreSQL，权威记录表为 `decision_center_records`，日记表为 `decision_center_diary_entries`；不得使用浏览器 `localStorage`、IndexedDB、容器 writable layer 或本地 JSON 文件作为会议、决议、目标、问题或日记状态权威。D601 Pod 通过集群内 `d601-tcp-egress-gateway.unidesk.svc.cluster.local:15432` 访问主 PostgreSQL。
|
||||
- 记录数据模型：记录类型为 `meeting|decision|goal|blocker|debt|experiment`，等级为 `G0|G1|G2|G3|P0|P1|P2|P3|none`，状态为 `active|blocked|parked|done`，字段包含 `title`、Markdown `summary/body`、`linkedGoalId`、`tags`、`evidenceLinks`、`sourceSession`、`taskId`、`commitId`、`createdAt` 和 `updatedAt`。
|
||||
- 需求管理：Decision Center 里的 `goal` 记录应承接外部需求或长期目标，`decision` 记录应承接需求分解后的取舍，`blocker` 记录应承接当前阻塞，`experiment` 记录应承接验证性工作，`debt` 记录应承接必须偿还的技术/流程债。任何新需求都应先写成可验证的外部收益，再分解为这些内部记录，而不是先发散成内部审美或架构偏好。
|
||||
- 日记数据模型：基于 Markdown 的日记系统以“每天一篇”为最小单元，导入器识别 `# YYYY年M月D日`、`# YYYY-MM-DD` 或 `# YYYY/M/D` 标题并拆分为 `entry_date`、`month`、Markdown `body`、`source_file`、`content_hash` 与虚拟 `markdown_path=YYYY-MM/YYYY-MM-DD.md`；同一 `source_file + entry_date` 使用 upsert，内容未变时保持幂等。
|
||||
- 日记编辑：工作日记必须支持按真实日期创建当天条目，并支持按日期回看和编辑历史条目；数据库仍是唯一权威，前端只是编辑入口和展示入口。
|
||||
- API：只允许 `/health`、`/live`、`/logs` 和 `/api/` 前缀；允许 `GET`、`HEAD`、`POST`、`PUT` 和 `DELETE`。业务 API 包含 `GET /api/records`、`POST /api/records`、`GET|PUT|DELETE /api/records/:id`、`POST /api/meetings/import`、`POST /api/diary/import`、`GET /api/diary/entries`、`GET /api/diary/entries/:idOrDate` 和 `GET /api/diary/months`，错误必须返回结构化 JSON，便于 CLI 与 frontend 诊断。
|
||||
- CLI：`bun scripts/cli.ts decision upload <markdown-file>`、`decision list`、`decision show <id>`、`decision diary import/list/months/show` 和 `decision health` 只能通过 backend-core 用户服务代理访问 Decision Center，不得直连 D601 Service、NodePort 或 provider-gateway `microservice.http`。
|
||||
- UniDesk 前端：`用户服务 / Decision Center` React 页面展示权威记录筛选、当前 G0/G1 目标、P0/P1 blocker、停放事项、最近会议/决议和工作日记；日记视图按月份筛选并展示每天 Markdown 正文。默认不得展示裸 JSON，完整原始数据只能通过 `查看原始JSON` 打开。
|
||||
- CLI：`bun scripts/cli.ts decision upload <markdown-file>`、`decision list`、`decision show <id>`、`decision diary import/list/months/show` 和 `decision health` 只能通过 backend-core 用户服务代理访问 Decision Center，不得直连 D601 Service、NodePort 或 provider-gateway `microservice.http`。后续若增加日记编辑或需求管理 CLI，应保持同一代理边界。
|
||||
- UniDesk 前端：`用户服务 / Decision Center` React 页面展示权威记录筛选、当前 G0/G1 目标、P0/P1 blocker、停放事项、最近会议/决议和工作日记；它还应成为需求管理入口，让外部目标、内部拆解和每日工作记录在同一页面中可追溯。日记视图按月份筛选并展示每天 Markdown 正文，未来应支持当天自动创建与历史编辑。默认不得展示裸 JSON，完整原始数据只能通过 `查看原始JSON` 打开。
|
||||
|
||||
### MDTODO k3s-Managed
|
||||
|
||||
|
||||
@@ -34,6 +34,7 @@
|
||||
- observability.md (Logs and status visibility)
|
||||
- e2e.md (Delivery gate, Playwright frontend E2E, and database persistence checks)
|
||||
- ci.md (D601 k3s Tekton CI, read-only production database performance gate, master deploy.json dev namespace e2e harness, and trigger boundary)
|
||||
- user-service-delivery.md (Default user-service delivery flow and Decision Center product workflow policy)
|
||||
- dev-environment.md (D601 persistent dev environment, public dev frontend proxy, deploy dev scope, and Rust build boundary)
|
||||
- src/ (Component monorepo)
|
||||
- package.json (Component workspace metadata)
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
# 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 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:
|
||||
|
||||
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.
|
||||
- Every production release must finish with a manual acceptance step after the automated checks pass.
|
||||
|
||||
## 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, but it does not create a second deployment truth. The backend artifact remains the production deployment unit; the frontend page remains the user-visible acceptance surface.
|
||||
|
||||
## 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.
|
||||
|
||||
- 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.
|
||||
|
||||
Detailed service-level API and UI contracts remain in `docs/reference/microservices.md`.
|
||||
Reference in New Issue
Block a user