feat: an ordered backlog

A Backlog tab lists the tickets still to start in the order the team will
take them; drag them, or use the arrows, to reorder. Moving a ticket only
rewrites that ticket's rank, read from the event store, and board columns
follow the same order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

libs/api/tracker/presenters/src/lib/graphql/enums.ts

@@ -1,4 +1,5 @@
 import { registerEnumType } from '@nestjs/graphql';
+import { IssueSort } from '@task-stream/api/tracker/application';
 import {
   IssueLinkType,
   IssuePriority,
@@ -23,6 +24,10 @@ registerEnumType(IssueLinkType, { name: 'IssueLinkType' });
 registerEnumType(ProjectRole, { name: 'ProjectRole' });
 registerEnumType(ReleaseStatus, { name: 'ReleaseStatus' });
 registerEnumType(LinkDirection, { name: 'LinkDirection' });
+registerEnumType(IssueSort, {
+  name: 'IssueSort',
+  description: 'RECENT: last updated first. RANK: backlog order.',
+});
 registerEnumType(NotificationKind, {
   name: 'NotificationKind',
   description: 'Why someone is told',

libs/api/tracker/presenters/src/lib/graphql/inputs.ts

@@ -5,6 +5,7 @@ import {
   ProjectRole,
   StatusCategory,
 } from '@task-stream/api/tracker/domain';
+import { IssueSort } from '@task-stream/api/tracker/application';
 import { Type } from 'class-transformer';
 import {
   ArrayMaxSize,
@@ -180,6 +181,25 @@ export class ChangeIssueStatusInput {
   reason?: string | null;
 }
 
+@InputType()
+export class RankIssueInput {
+  @Field(() => ID) @IsUUID() issueId!: string;
+  @Field(() => ID, {
+    nullable: true,
+    description: 'The ticket that ends up right above (null: the top)',
+  })
+  @IsOptional()
+  @IsUUID()
+  aboveIssueId?: string | null;
+  @Field(() => ID, {
+    nullable: true,
+    description: 'The ticket that ends up right below (null: the bottom)',
+  })
+  @IsOptional()
+  @IsUUID()
+  belowIssueId?: string | null;
+}
+
 @InputType()
 export class AddChecklistItemInput {
   @Field(() => ID) @IsUUID() issueId!: string;
@@ -249,6 +269,10 @@ export class IssueFilterInput {
   @IsOptional()
   @IsUUID()
   parentId?: string;
+  @Field(() => IssueSort, { nullable: true, defaultValue: IssueSort.RECENT })
+  @IsOptional()
+  @IsEnum(IssueSort)
+  sort?: IssueSort;
   @Field({ nullable: true, description: 'Matches key, title or description' })
   @IsOptional()
   @IsString()

libs/api/tracker/presenters/src/lib/graphql/issue.resolver.ts

@@ -28,6 +28,7 @@ import {
   CreateIssueInput,
   IssueFilterInput,
   LinkIssuesInput,
+  RankIssueInput,
   UpdateChecklistItemInput,
   UpdateIssueInput,
 } from './inputs';
@@ -266,6 +267,19 @@ export class IssueResolver {
     return this.issuesService.setParent(me.id, issueId, parentId ?? null);
   }
 
+  @Mutation(() => CommandResultGql, {
+    description:
+      'Move a ticket in the backlog, between two others of the same project',
+  })
+  rankIssue(@CurrentUser() me: User, @Args('input') input: RankIssueInput) {
+    return this.issuesService.rank(
+      me.id,
+      input.issueId,
+      input.aboveIssueId ?? null,
+      input.belowIssueId ?? null,
+    );
+  }
+
   @Mutation(() => CommandResultGql, {
     description: "Add a step to a ticket's checklist",
   })

libs/api/tracker/presenters/src/lib/graphql/types.ts

@@ -167,6 +167,11 @@ export class IssueGql {
     description: 'The epic or ticket this one breaks down',
   })
   parent!: IssueParentGql | null;
+  @Field({
+    description:
+      'Place in the backlog and in its board column (ascending, compare as text)',
+  })
+  rank!: string;
   @Field(() => [ChecklistItemGql]) checklist!: ChecklistItemGql[];
   @Field(() => Int) commentCount!: number;
   @Field() createdAt!: string;

libs/api/tracker/presenters/src/lib/http/dto/requests.dto.ts

@@ -12,6 +12,7 @@ import {
   StatusCategory,
   TYPE_ICONS,
 } from '@task-stream/api/tracker/domain';
+import { IssueSort } from '@task-stream/api/tracker/application';
 import { Transform, Type } from 'class-transformer';
 import {
   ArrayMaxSize,
@@ -416,6 +417,15 @@ export class IssueSearchQueryDto extends PageQueryDto {
   @IsString()
   parent?: string;
 
+  @ApiPropertyOptional({
+    enum: IssueSort,
+    enumName: 'IssueSort',
+    description: 'RECENT (default): last updated first. RANK: backlog order.',
+  })
+  @IsOptional()
+  @IsEnum(IssueSort)
+  sort?: IssueSort;
+
   @ApiPropertyOptional({ description: 'Matches key, title or description' })
   @IsOptional()
   @IsString()
@@ -579,6 +589,30 @@ export class SetIssueReleaseDto {
   releaseId!: string | null;
 }
 
+export class RankIssueDto {
+  @ApiPropertyOptional({
+    type: String,
+    nullable: true,
+    example: 'WEB-4',
+    description:
+      'The ticket that ends up right above (id or key; null: the top)',
+  })
+  @IsOptional()
+  @IsString()
+  above?: string | null;
+
+  @ApiPropertyOptional({
+    type: String,
+    nullable: true,
+    example: 'WEB-9',
+    description:
+      'The ticket that ends up right below (id or key; null: the bottom)',
+  })
+  @IsOptional()
+  @IsString()
+  below?: string | null;
+}
+
 export class SetIssueParentDto {
   @ApiProperty({
     type: String,

libs/api/tracker/presenters/src/lib/http/dto/responses.dto.ts

@@ -179,6 +179,11 @@ export class IssueDto {
     description: 'The epic or ticket this one breaks down',
   })
   parent!: IssueParentDto | null;
+  @ApiProperty({
+    description:
+      'Place in the backlog and its board column (ascending, as text)',
+  })
+  rank!: string;
   @ApiProperty({ type: [ChecklistItemDto] }) checklist!: ChecklistItemDto[];
   @ApiProperty() commentCount!: number;
   @ApiProperty({ format: 'date-time' }) createdAt!: string;

libs/api/tracker/presenters/src/lib/http/issues.controller.ts

@@ -44,6 +44,7 @@ import {
   LinkTypeParamDto,
   MyIssuesQueryDto,
   PageQueryDto,
+  RankIssueDto,
   SetIssueParentDto,
   SetIssueReleaseDto,
   UpdateChecklistItemDto,
@@ -156,6 +157,7 @@ export class IssuesController {
       unassigned: query.unassigned,
       releaseId: query.releaseId,
       labels: query.label,
+      sort: query.sort,
       search: query.search,
       limit: query.limit,
       offset: query.offset,
@@ -323,6 +325,30 @@ export class IssuesController {
     );
   }
 
+  @Put('issues/:issue/rank')
+  @ISSUE
+  @ApiOperation({
+    summary: 'Move the ticket in the backlog',
+    description:
+      'Between the ticket that ends up above it and the one below (either may be left out for the top or the bottom). Board columns follow the same order.',
+  })
+  @ApiOkResponse({ type: CommandResultDto })
+  @ApiCommandErrors()
+  async rank(
+    @CurrentUser() me: User,
+    @Param('issue') issue: string,
+    @Body() body: RankIssueDto,
+  ) {
+    const ref = (value?: string | null) =>
+      value ? this.refs.issueId(me.id, value) : null;
+    return this.issues.rank(
+      me.id,
+      await this.refs.issueId(me.id, issue),
+      await ref(body.above),
+      await ref(body.below),
+    );
+  }
+
   @Post('issues/:issue/checklist')
   @ISSUE
   @ApiOperation({ summary: "Add a step to the ticket's checklist" })