329 lines
7.0 KiB
Markdown
329 lines
7.0 KiB
Markdown
# KanbanGit Domain Model
|
|
|
|
## Purpose
|
|
|
|
This document defines the canonical domain concepts, relationships, and invariants for KanbanGit. It is intended to guide future Laravel models, migrations, policies, services, frontend types, and UI behavior.
|
|
|
|
## Core entities
|
|
|
|
### User
|
|
|
|
Represents an authenticated person inside the application.
|
|
|
|
Responsibilities:
|
|
|
|
- Owns direct project permissions
|
|
- May belong to one or more teams
|
|
- May appear in user-type ticket fields
|
|
- Appears as the actor for worklog entries
|
|
- May hold application-wide admin access
|
|
|
|
### Team
|
|
|
|
Represents a named group of users.
|
|
|
|
Responsibilities:
|
|
|
|
- Groups users for permission assignment
|
|
- Carries project permissions that are inherited by its members
|
|
|
|
### Permission
|
|
|
|
Represents an action grant.
|
|
|
|
Permission scopes:
|
|
|
|
- Global admin access for application-wide administration
|
|
- Project-scoped `create`
|
|
- Project-scoped `view`
|
|
- Project-scoped `edit`
|
|
- Project-scoped `delete`
|
|
|
|
Assignment rules:
|
|
|
|
- Permissions may be assigned directly to a user
|
|
- Permissions may be assigned to a team
|
|
- A user's effective permissions are the union of direct permissions and team-inherited permissions
|
|
|
|
### Project
|
|
|
|
Represents the primary organizational boundary for workflow configuration and tickets.
|
|
|
|
Required properties:
|
|
|
|
- Name
|
|
- Project key
|
|
|
|
Owns:
|
|
|
|
- Board columns
|
|
- Ticket type definitions
|
|
- Ticket priority definitions
|
|
- Ticket field definitions
|
|
- Ticket link type definitions
|
|
- Tickets
|
|
- Repository connections
|
|
|
|
### BoardColumn
|
|
|
|
Represents one configurable column on a project's board.
|
|
|
|
Required properties:
|
|
|
|
- Project
|
|
- Label
|
|
- Position
|
|
|
|
Behavior:
|
|
|
|
- Defines a valid board status
|
|
- Controls board ordering through its position
|
|
|
|
### Ticket
|
|
|
|
Represents a project work item.
|
|
|
|
Required properties:
|
|
|
|
- Project
|
|
- Ticket key
|
|
- Sequence index
|
|
- Title
|
|
- Description
|
|
- Acceptance criteria
|
|
- Status context
|
|
- Type
|
|
- Priority
|
|
|
|
Optional properties:
|
|
|
|
- Parent ticket
|
|
- Block comment
|
|
|
|
Associated concepts:
|
|
|
|
- Custom field values based on project field definitions
|
|
- Ticket links
|
|
- Worklog entries
|
|
- Future branch references
|
|
- Future pull request references
|
|
|
|
### TicketType
|
|
|
|
Represents a project-specific ticket type label.
|
|
|
|
Required properties:
|
|
|
|
- Project
|
|
- Label
|
|
- System key
|
|
- Is built-in
|
|
|
|
Rules:
|
|
|
|
- Every project has built-in `Task` and `Parent` ticket types
|
|
- Built-in types cannot be deleted
|
|
- Built-in types may be renamed for display
|
|
- Additional custom ticket types may be added per project
|
|
|
|
### TicketPriority
|
|
|
|
Represents a project-specific priority label.
|
|
|
|
Required properties:
|
|
|
|
- Project
|
|
- Label
|
|
- Position
|
|
|
|
### TicketFieldDefinition
|
|
|
|
Represents one configurable field definition for tickets in a project.
|
|
|
|
Required properties:
|
|
|
|
- Project
|
|
- Label
|
|
- Field type
|
|
|
|
Initial field types:
|
|
|
|
- User
|
|
- Number
|
|
|
|
Future-safe expectation:
|
|
|
|
- The field type system is extensible
|
|
|
|
### TicketLinkType
|
|
|
|
Represents a project-specific label for linking tickets.
|
|
|
|
Required properties:
|
|
|
|
- Project
|
|
- Label
|
|
|
|
### TicketLink
|
|
|
|
Represents a relationship between two tickets.
|
|
|
|
Required properties:
|
|
|
|
- Source ticket
|
|
- Target ticket
|
|
- Link type
|
|
|
|
Behavior:
|
|
|
|
- Tickets expose linked tickets as a list
|
|
- The first documented product version only requires label-based linking
|
|
|
|
### WorklogEntry
|
|
|
|
Represents one audit-trail record for a ticket change.
|
|
|
|
Required properties:
|
|
|
|
- Ticket
|
|
- Actor user
|
|
- Change type
|
|
- Change summary
|
|
- Timestamp
|
|
|
|
### RepositoryConnection
|
|
|
|
Represents a project-level external repository configuration.
|
|
|
|
Required properties:
|
|
|
|
- Project
|
|
- Provider
|
|
- Repository identifier
|
|
|
|
Initial provider:
|
|
|
|
- Gitea
|
|
|
|
Future providers:
|
|
|
|
- GitHub
|
|
- GitLab
|
|
|
|
### BranchReference
|
|
|
|
Represents a branch associated with a ticket through a repository connection.
|
|
|
|
Required properties:
|
|
|
|
- Ticket
|
|
- Repository connection
|
|
- Branch name
|
|
|
|
Behavior:
|
|
|
|
- Branch matching is based on the ticket key prefix.
|
|
- The branch list may also be the entry point for creating a new branch from the ticket detail view.
|
|
- Branch creation depends on the current user's personal Git credentials for the selected repository connection.
|
|
|
|
### PullRequestReference
|
|
|
|
Represents a pull request associated with a ticket through a repository connection.
|
|
|
|
Required properties:
|
|
|
|
- Ticket
|
|
- Repository connection
|
|
- Pull request identifier
|
|
- Pull request title
|
|
|
|
## Relationships
|
|
|
|
- A user may belong to many teams.
|
|
- A team may contain many users.
|
|
- A project has many board columns.
|
|
- A project has many tickets.
|
|
- A project has many ticket type definitions.
|
|
- A project has many priority definitions.
|
|
- A project has many field definitions.
|
|
- A project has many link type definitions.
|
|
- A project has many repository connections.
|
|
- A ticket belongs to exactly one project.
|
|
- A ticket may have zero or one parent ticket.
|
|
- A ticket may have many child tickets.
|
|
- A ticket may have many worklog entries.
|
|
- A ticket may have many links to other tickets.
|
|
- A ticket may have many future branch references.
|
|
- A ticket may have many future pull request references.
|
|
|
|
## Invariants
|
|
|
|
### Project key and ticket key
|
|
|
|
- Project key length must not exceed 5 characters.
|
|
- Project key is normalized to uppercase.
|
|
- Project key must be unique across the application.
|
|
- Ticket key format is `PROJECTKEY-INDEX`.
|
|
- `INDEX` is unique within a project and increases monotonically.
|
|
- Ticket key is immutable after creation.
|
|
|
|
### Ticket lifecycle
|
|
|
|
- Every new ticket starts in the backlog.
|
|
- A ticket appears on the board only when assigned to a board column.
|
|
- Board column assignment must belong to the same project as the ticket.
|
|
|
|
### Ticket hierarchy
|
|
|
|
- A ticket may reference only one parent ticket.
|
|
- A parent reference is optional.
|
|
- Only a ticket whose type is `Parent` may be used as a parent target.
|
|
- A `Task` ticket may have a parent but may not be the parent of another ticket.
|
|
- Any custom non-`Parent` type may have a parent but may not be the parent of another ticket.
|
|
- A `Parent` ticket may itself have a parent, enabling nested parent trees.
|
|
|
|
### Ticket metadata
|
|
|
|
- Title is required and not unique.
|
|
- Description is part of the ticket record.
|
|
- Acceptance criteria is part of the ticket record.
|
|
- Priority must be one of the project's configured priority definitions.
|
|
- Type must be one of the project's configured ticket type definitions.
|
|
- Custom field values must conform to the selected field definition type.
|
|
|
|
### Blocked state
|
|
|
|
- A blocked ticket requires a non-empty comment.
|
|
- Blocked state must be reflected in board presentation.
|
|
|
|
### Worklog
|
|
|
|
- Every ticket change creates a corresponding worklog entry.
|
|
- Every worklog entry records the acting user.
|
|
|
|
### Permission inheritance
|
|
|
|
- Effective project permissions are evaluated per project.
|
|
- Direct user permissions and inherited team permissions are cumulative.
|
|
- Global admin access is evaluated separately from project permissions.
|
|
|
|
### Git references
|
|
|
|
- Branch and pull request matching is based on ticket-key-prefixed names.
|
|
- A reference is associated with a ticket when the branch name starts with that ticket's key.
|
|
|
|
## Canonical terminology
|
|
|
|
Use these terms consistently in future implementation work:
|
|
|
|
- `Project`
|
|
- `Project Key`
|
|
- `Ticket`
|
|
- `Ticket Key`
|
|
- `Board`
|
|
- `Board Column`
|
|
- `Backlog`
|
|
- `Parent Ticket`
|
|
- `Worklog Entry`
|
|
- `Repository Connection`
|