feat: sprints with burndown and carry-over

Plan sprints with dates and a goal, run one at a time per project, and
put tickets in them from the ticket page. The Sprints tab follows the one
under way with its progress and a burndown in tickets or points against
the ideal line. Closing a sprint sends what was left to the next one or
back to the backlog; the board can be filtered by sprint.

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

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

@@ -285,6 +285,11 @@ export class BoardQueryDto {
   @IsBoolean()
   unassigned?: boolean;
 
+  @ApiPropertyOptional({ format: 'uuid', description: 'Only this sprint' })
+  @IsOptional()
+  @IsUUID()
+  sprintId?: string;
+
   @ApiPropertyOptional({ type: Number, default: 50, minimum: 1, maximum: 200 })
   @IsOptional()
   @Type(() => Number)
@@ -451,6 +456,17 @@ export class IssueSearchQueryDto extends PageQueryDto {
   @IsString()
   parent?: string;
 
+  @ApiPropertyOptional({ format: 'uuid', description: 'Only this sprint' })
+  @IsOptional()
+  @IsUUID()
+  sprintId?: string;
+
+  @ApiPropertyOptional({ description: 'Only tickets in no sprint' })
+  @IsOptional()
+  @Transform(toBoolean)
+  @IsBoolean()
+  noSprint?: boolean;
+
   @ApiPropertyOptional({
     enum: IssueSort,
     enumName: 'IssueSort',
@@ -819,6 +835,66 @@ export class CreateReleaseDto {
 
 export class UpdateReleaseDto extends PartialType(CreateReleaseDto) {}
 
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+
+export class CreateSprintDto {
+  @ApiProperty({ example: 'Sprint 14', maxLength: 80 })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(80)
+  name!: string;
+
+  @ApiPropertyOptional({
+    type: String,
+    nullable: true,
+    maxLength: 500,
+    example: 'Pagos con tarjeta en producción',
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(500)
+  goal?: string | null;
+
+  @ApiProperty({ format: 'date', example: '2026-10-12' })
+  @Matches(DAY)
+  startDate!: string;
+
+  @ApiProperty({
+    format: 'date',
+    example: '2026-10-23',
+    description: 'Last day, included',
+  })
+  @Matches(DAY)
+  endDate!: string;
+}
+
+export class UpdateSprintDto extends PartialType(CreateSprintDto) {}
+
+export class CloseSprintDto {
+  @ApiPropertyOptional({
+    type: String,
+    nullable: true,
+    format: 'uuid',
+    description:
+      'Open sprint of the same project that takes the unfinished tickets; null or absent: back to the backlog',
+  })
+  @IsOptional()
+  @IsUUID()
+  carryOverTo?: string | null;
+}
+
+export class SetIssueSprintDto {
+  @ApiProperty({
+    type: String,
+    nullable: true,
+    format: 'uuid',
+    description: 'Open sprint of the project, or null for the backlog',
+  })
+  @ValidateIf((dto: SetIssueSprintDto) => dto.sprintId !== null)
+  @IsUUID()
+  sprintId!: string | null;
+}
+
 export class PublishReleaseDto {
   @ApiPropertyOptional({
     type: Boolean,

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

@@ -5,6 +5,7 @@ import {
   NotificationKind,
   ProjectRole,
   ReleaseStatus,
+  SprintStatus,
   SETTING_COLORS,
   StatusCategory,
   TYPE_ICONS,
@@ -135,6 +136,11 @@ export class IssueParentDto {
   @ApiProperty({ example: 'Pago con tarjeta' }) title!: string;
 }
 
+export class SprintRefDto {
+  @ApiProperty({ format: 'uuid' }) id!: string;
+  @ApiProperty({ example: 'Sprint 14' }) name!: string;
+}
+
 export class IssueDto {
   @ApiProperty({ format: 'uuid' }) id!: string;
   @ApiProperty({ format: 'uuid' }) projectId!: string;
@@ -163,6 +169,8 @@ export class IssueDto {
   assignee!: UserRefDto | null;
   @ApiProperty({ type: ReleaseRefDto, nullable: true })
   release!: ReleaseRefDto | null;
+  @ApiProperty({ type: SprintRefDto, nullable: true })
+  sprint!: SprintRefDto | null;
   @ApiProperty({ type: [String] }) labels!: string[];
   @ApiProperty({ type: String, nullable: true, description: 'Figma frame' })
   figmaUrl!: string | null;
@@ -255,6 +263,50 @@ export class CommentPageDto {
   @ApiProperty() total!: number;
 }
 
+export class SprintDto {
+  @ApiProperty({ format: 'uuid' }) id!: string;
+  @ApiProperty({ format: 'uuid' }) projectId!: string;
+  @ApiProperty({ example: 'Sprint 14' }) name!: string;
+  @ApiProperty({ type: String, nullable: true }) goal!: string | null;
+  @ApiProperty({ format: 'date' }) startDate!: string;
+  @ApiProperty({ format: 'date', description: 'Last day, included' })
+  endDate!: string;
+  @ApiProperty({ enum: SprintStatus, enumName: 'SprintStatus' })
+  status!: SprintStatus;
+  @ApiProperty({ type: String, nullable: true, format: 'date-time' })
+  startedAt!: string | null;
+  @ApiProperty({ type: String, nullable: true, format: 'date-time' })
+  closedAt!: string | null;
+  @ApiProperty({ format: 'date-time' }) createdAt!: string;
+  @ApiProperty() version!: number;
+}
+
+export class SprintProgressDto {
+  @ApiProperty() total!: number;
+  @ApiProperty({ description: 'Done or cancelled' }) finished!: number;
+  @ApiProperty({ minimum: 0, maximum: 100 }) percent!: number;
+  @ApiProperty() storyPoints!: number;
+  @ApiProperty() finishedStoryPoints!: number;
+}
+
+export class SprintBurndownDto {
+  @ApiProperty({ format: 'uuid' }) sprintId!: string;
+  @ApiProperty({ type: [String], format: 'date' }) dates!: string[];
+  @ApiProperty({
+    type: [Number],
+    nullable: true,
+    description: 'Tickets in the sprint (null: days to come)',
+  })
+  scope!: (number | null)[];
+  @ApiProperty({ type: [Number], nullable: true }) remaining!: (
+    | number
+    | null
+  )[];
+  @ApiProperty({ type: [Number], nullable: true })
+  remainingPoints!: (number | null)[];
+  @ApiProperty({ type: [Number] }) ideal!: number[];
+}
+
 export class ReleaseDto {
   @ApiProperty({ format: 'uuid' }) id!: string;
   @ApiProperty({ format: 'uuid' }) projectId!: string;

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

@@ -157,6 +157,8 @@ export class IssuesController {
       unassigned: query.unassigned,
       releaseId: query.releaseId,
       labels: query.label,
+      sprintId: query.sprintId,
+      noSprint: query.noSprint,
       sort: query.sort,
       search: query.search,
       limit: query.limit,

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

@@ -187,6 +187,7 @@ export class ProjectsController {
         labels: query.label,
         search: query.search,
         unassigned: query.unassigned,
+        sprintId: query.sprintId,
       },
       query.perColumn,
     );

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

@@ -0,0 +1,249 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  Param,
+  ParseUUIDPipe,
+  Patch,
+  Post,
+  Put,
+  Query,
+} from '@nestjs/common';
+import {
+  ApiCreatedResponse,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiTags,
+} from '@nestjs/swagger';
+import { User } from '@task-stream/api/identity/domain';
+import {
+  ApiOptionalPireonAuth,
+  ApiPireonAuth,
+  CurrentUser,
+} from '@task-stream/api/identity/presenters';
+import {
+  ApiCommandErrors,
+  ApiReadErrors,
+} from '@task-stream/api/shared/presenters';
+import {
+  IssuesService,
+  IssueSort,
+  SprintsService,
+} from '@task-stream/api/tracker/application';
+import { viewerOf } from '../common/viewer';
+import {
+  CloseSprintDto,
+  CreateSprintDto,
+  PageQueryDto,
+  SetIssueSprintDto,
+  UpdateSprintDto,
+} from './dto/requests.dto';
+import {
+  CommandResultDto,
+  IssuePageDto,
+  SprintBurndownDto,
+  SprintDto,
+  SprintProgressDto,
+} from './dto/responses.dto';
+import { Refs } from './refs';
+
+const PROJECT = ApiParam({
+  name: 'project',
+  description: 'Project id or key',
+  example: 'WEB',
+});
+const SPRINT = ApiParam({ name: 'sprint', format: 'uuid' });
+
+/** REST adapter of the sprint use cases: plan, run and close iterations. */
+@ApiTags('Sprints')
+@ApiPireonAuth()
+@Controller()
+export class SprintsController {
+  constructor(
+    private readonly sprints: SprintsService,
+    private readonly issues: IssuesService,
+    private readonly refs: Refs,
+  ) {}
+
+  @Get('projects/:project/sprints')
+  @ApiOptionalPireonAuth()
+  @PROJECT
+  @ApiOperation({
+    summary: "A project's sprints",
+    description: 'The one under way, the planned ones, then the closed ones.',
+  })
+  @ApiOkResponse({ type: [SprintDto] })
+  @ApiReadErrors()
+  async list(
+    @CurrentUser() me: User | undefined,
+    @Param('project') project: string,
+  ) {
+    return this.sprints.list(
+      viewerOf(me),
+      await this.refs.projectId(viewerOf(me), project),
+    );
+  }
+
+  @Post('projects/:project/sprints')
+  @PROJECT
+  @ApiOperation({ summary: 'Plan a sprint (owners and admins)' })
+  @ApiCreatedResponse({ type: CommandResultDto })
+  @ApiCommandErrors()
+  async create(
+    @CurrentUser() me: User,
+    @Param('project') project: string,
+    @Body() body: CreateSprintDto,
+  ) {
+    return this.sprints.create(me.id, {
+      ...body,
+      projectId: await this.refs.projectId(me.id, project),
+    });
+  }
+
+  @Get('sprints/:sprint')
+  @ApiOptionalPireonAuth()
+  @SPRINT
+  @ApiOperation({ summary: 'A sprint' })
+  @ApiOkResponse({ type: SprintDto })
+  @ApiReadErrors()
+  findOne(
+    @CurrentUser() me: User | undefined,
+    @Param('sprint', ParseUUIDPipe) sprint: string,
+  ) {
+    return this.sprints.findOne(viewerOf(me), sprint);
+  }
+
+  @Patch('sprints/:sprint')
+  @SPRINT
+  @ApiOperation({
+    summary: 'Rename, re-date or change the goal (not once closed)',
+  })
+  @ApiOkResponse({ type: CommandResultDto })
+  @ApiCommandErrors()
+  update(
+    @CurrentUser() me: User,
+    @Param('sprint', ParseUUIDPipe) sprint: string,
+    @Body() body: UpdateSprintDto,
+  ) {
+    return this.sprints.update(me.id, sprint, body);
+  }
+
+  @Delete('sprints/:sprint')
+  @SPRINT
+  @ApiOperation({
+    summary: 'Delete a sprint that never started',
+    description: 'Its tickets go back to the backlog.',
+  })
+  @ApiOkResponse({ type: CommandResultDto })
+  @ApiCommandErrors()
+  delete(
+    @CurrentUser() me: User,
+    @Param('sprint', ParseUUIDPipe) sprint: string,
+  ) {
+    return this.sprints.delete(me.id, sprint);
+  }
+
+  @Post('sprints/:sprint/start')
+  @SPRINT
+  @ApiOperation({
+    summary: 'Start a planned sprint (only one under way per project)',
+  })
+  @ApiCreatedResponse({ type: CommandResultDto })
+  @ApiCommandErrors()
+  start(
+    @CurrentUser() me: User,
+    @Param('sprint', ParseUUIDPipe) sprint: string,
+  ) {
+    return this.sprints.start(me.id, sprint);
+  }
+
+  @Post('sprints/:sprint/close')
+  @SPRINT
+  @ApiOperation({
+    summary: 'Close the sprint under way',
+    description:
+      'Unfinished tickets move to `carryOverTo` (another open sprint) or back to the backlog; finished ones stay as its record.',
+  })
+  @ApiCreatedResponse({ type: CommandResultDto })
+  @ApiCommandErrors()
+  close(
+    @CurrentUser() me: User,
+    @Param('sprint', ParseUUIDPipe) sprint: string,
+    @Body() body: CloseSprintDto,
+  ) {
+    return this.sprints.close(me.id, sprint, body.carryOverTo ?? null);
+  }
+
+  @Get('sprints/:sprint/progress')
+  @ApiOptionalPireonAuth()
+  @SPRINT
+  @ApiOperation({ summary: 'Finished tickets and points' })
+  @ApiOkResponse({ type: SprintProgressDto })
+  @ApiReadErrors()
+  progress(
+    @CurrentUser() me: User | undefined,
+    @Param('sprint', ParseUUIDPipe) sprint: string,
+  ) {
+    return this.sprints.progress(viewerOf(me), sprint);
+  }
+
+  @Get('sprints/:sprint/burndown')
+  @ApiOptionalPireonAuth()
+  @SPRINT
+  @ApiOperation({
+    summary: 'Open tickets and points, day by day, against the ideal line',
+  })
+  @ApiOkResponse({ type: SprintBurndownDto })
+  @ApiReadErrors()
+  burndown(
+    @CurrentUser() me: User | undefined,
+    @Param('sprint', ParseUUIDPipe) sprint: string,
+  ) {
+    return this.sprints.burndown(viewerOf(me), sprint);
+  }
+
+  @Get('sprints/:sprint/issues')
+  @ApiOptionalPireonAuth()
+  @SPRINT
+  @ApiOperation({ summary: 'Tickets in the sprint, in backlog order' })
+  @ApiOkResponse({ type: IssuePageDto })
+  @ApiReadErrors()
+  async issuesOf(
+    @CurrentUser() me: User | undefined,
+    @Param('sprint', ParseUUIDPipe) sprint: string,
+    @Query() query: PageQueryDto,
+  ) {
+    const found = await this.sprints.findOne(viewerOf(me), sprint);
+    const page = await this.issues.search(viewerOf(me), {
+      projectId: found.projectId,
+      sprintId: found.id,
+      sort: IssueSort.RANK,
+      limit: query.limit,
+      offset: query.offset,
+    });
+    return { ...page, items: await this.refs.issueDtos(page.items) };
+  }
+
+  @Put('issues/:issue/sprint')
+  @ApiParam({
+    name: 'issue',
+    description: 'Ticket id or key',
+    example: 'WEB-12',
+  })
+  @ApiOperation({ summary: 'Put the ticket in a sprint (null: the backlog)' })
+  @ApiOkResponse({ type: CommandResultDto })
+  @ApiCommandErrors()
+  async setIssueSprint(
+    @CurrentUser() me: User,
+    @Param('issue') issue: string,
+    @Body() body: SetIssueSprintDto,
+  ) {
+    return this.sprints.setIssueSprint(
+      me.id,
+      await this.refs.issueId(me.id, issue),
+      body.sprintId,
+    );
+  }
+}