phptits
0d6cd37579
- Monorepo: NestJS API (Fastify) + React web (antd/ProComponents) + shared packages - PostgreSQL/Prisma (unified resources, relations graph, audit, events, jobs) - Auth/RBAC/workspace isolation, credential vault (AES-256-GCM) - Servers/SSH, Docker discovery & lifecycle, Job Center - Websites & deployments (git provider credential clone, env, health verification) - Domains/DNS (Cloudflare adapter), certificates (TLS probe), monitoring - Automation (cron/event/webhook HMAC + notifications), AI Gateway, MCP (29 tools) - AI chat window (LLM function-calling + rules fallback, SSE streaming, approvals) - Notes: Vditor WYSIWYG markdown editor, non-blocking autosave - Tests: 35 unit/security tests; UI audit clean (desktop+mobile, deep links)
241 lines
5.1 KiB
Markdown
241 lines
5.1 KiB
Markdown
# DevOS v1 ZCODE Development Specification
|
|
|
|
## 1. Purpose
|
|
This document converts the architecture into executable work units for an AI coding agent such as ZCODE, Codex, Cursor or Claude Code.
|
|
|
|
The agent must work from specifications instead of inventing architecture during implementation.
|
|
|
|
## 2. Repository Target
|
|
|
|
```text
|
|
devos/
|
|
├── apps/
|
|
│ ├── web/
|
|
│ └── api/
|
|
├── packages/
|
|
│ ├── ui/
|
|
│ ├── api-client/
|
|
│ ├── types/
|
|
│ └── auth/
|
|
├── packages/integrations/
|
|
├── prisma/
|
|
├── docs/
|
|
├── specs/
|
|
└── AGENTS.md
|
|
```
|
|
|
|
## 3. Initial Task Queue
|
|
|
|
### Task 001 — Monorepo
|
|
Create the workspace structure for web, API and shared packages.
|
|
|
|
Acceptance:
|
|
- package manager/workspaces configured
|
|
- TypeScript shared configuration
|
|
- lint/format/test commands
|
|
- build pipeline
|
|
|
|
### Task 002 — Backend Bootstrap
|
|
Create NestJS API with versioned `/api/v1` routing.
|
|
|
|
Acceptance:
|
|
- health endpoint
|
|
- configuration management
|
|
- structured logging
|
|
- error handling
|
|
- request ID
|
|
|
|
### Task 003 — Frontend Bootstrap
|
|
Create React + Ant Design application.
|
|
|
|
Acceptance:
|
|
- ProLayout
|
|
- routing
|
|
- authentication shell
|
|
- dashboard shell
|
|
- API client
|
|
- loading/error/empty states
|
|
|
|
### Task 004 — Database
|
|
Create PostgreSQL + Prisma setup.
|
|
|
|
Acceptance:
|
|
- migrations
|
|
- core identity/workspace/resource schema
|
|
- seed strategy
|
|
- database documentation
|
|
|
|
### Task 005 — Authentication
|
|
Implement authentication and current-user endpoint.
|
|
|
|
Acceptance:
|
|
- login/logout
|
|
- session/token strategy
|
|
- password/credential handling appropriate to chosen auth design
|
|
- authorization guards
|
|
|
|
### Task 006 — Workspace
|
|
Implement workspace and membership.
|
|
|
|
Acceptance:
|
|
- create/list/read workspace
|
|
- membership
|
|
- workspace isolation in service and query layers
|
|
|
|
### Task 007 — Resource System
|
|
Implement unified Resource abstraction.
|
|
|
|
Acceptance:
|
|
- CRUD
|
|
- typed resource type
|
|
- status
|
|
- metadata
|
|
- relation graph
|
|
- workspace scope
|
|
|
|
### Task 008 — Audit
|
|
Implement audit service and mutation hooks.
|
|
|
|
Acceptance:
|
|
- audit record for every mutation
|
|
- actor/workspace/resource/action
|
|
- request/correlation ID
|
|
- sensitive data masking
|
|
|
|
### Task 009 — Server Module
|
|
Implement Server resource and provider adapter.
|
|
|
|
Acceptance:
|
|
- create server
|
|
- credential reference
|
|
- connectivity check
|
|
- status
|
|
- SSH execution
|
|
- audit
|
|
- timeout/error handling
|
|
|
|
### Task 010 — Docker
|
|
Implement Docker discovery through Server integration.
|
|
|
|
Acceptance:
|
|
- list containers
|
|
- inspect container
|
|
- restart container
|
|
- resource relation
|
|
- audit
|
|
|
|
### Task 011 — Website
|
|
Implement Website domain model and UI.
|
|
|
|
Acceptance:
|
|
- website CRUD
|
|
- repository/server/domain relations
|
|
- status
|
|
- detail page
|
|
|
|
### Task 012 — Deployment
|
|
Implement deployment job model and asynchronous execution.
|
|
|
|
Acceptance:
|
|
- create deployment
|
|
- run deployment
|
|
- progress
|
|
- logs
|
|
- cancellation where safe
|
|
- verification
|
|
- success/failure events
|
|
|
|
### Task 013 — Domain
|
|
Implement domain and DNS provider adapter.
|
|
|
|
Acceptance:
|
|
- domain CRUD
|
|
- record read/update
|
|
- authorization
|
|
- audit
|
|
|
|
### Task 014 — Monitoring
|
|
Implement initial health checks.
|
|
|
|
Acceptance:
|
|
- website health
|
|
- server status
|
|
- monitor result history
|
|
- down/recovered events
|
|
|
|
### Task 015 — Event Bus
|
|
Implement internal domain events and persistence/dispatch model.
|
|
|
|
Acceptance:
|
|
- canonical event names
|
|
- correlation IDs
|
|
- durable execution for required events
|
|
|
|
### Task 016 — Automation
|
|
Implement Trigger → Condition → Action workflow model.
|
|
|
|
Acceptance:
|
|
- manual trigger
|
|
- event trigger
|
|
- cron design
|
|
- execution history
|
|
- retries/timeouts
|
|
|
|
### Task 017 — AI Gateway
|
|
Implement an AI run abstraction without allowing unrestricted execution.
|
|
|
|
Acceptance:
|
|
- create AI run
|
|
- plan
|
|
- tool registry
|
|
- risk evaluation
|
|
- approval state
|
|
- execution history
|
|
- verification result
|
|
|
|
### Task 018 — MCP
|
|
Expose selected DevOS capabilities through MCP.
|
|
|
|
Acceptance:
|
|
- server list/status
|
|
- website list/deploy
|
|
- deployment get
|
|
- domain list/records
|
|
- task/note tools when corresponding modules exist
|
|
- all requests pass normal authorization/audit/risk controls
|
|
|
|
## 4. Agent Execution Protocol
|
|
|
|
For each task:
|
|
1. Read relevant docs.
|
|
2. Inspect existing code.
|
|
3. State implementation plan internally.
|
|
4. Implement the smallest coherent change.
|
|
5. Add/update tests.
|
|
6. Run typecheck/lint/tests.
|
|
7. Verify API and UI contracts.
|
|
8. Update documentation.
|
|
9. Do not refactor unrelated code.
|
|
|
|
## 5. Stop Conditions
|
|
The coding agent must stop and ask for a human decision when:
|
|
- architecture requires a new major dependency
|
|
- a security boundary must change
|
|
- destructive production behavior is requested
|
|
- domain terminology conflicts with existing specifications
|
|
- an API breaking change is unavoidable
|
|
- two specification documents materially conflict
|
|
|
|
## 6. Priority
|
|
When requirements conflict, use this order:
|
|
1. Security
|
|
2. Explicit user requirement
|
|
3. Domain model
|
|
4. API contract
|
|
5. Architecture
|
|
6. UI convenience
|
|
7. Implementation preference
|
|
|
|
## 7. Important Constraint
|
|
Do not convert DevOS into microservices during V1 unless a concrete operational requirement proves modular monolith insufficient.
|