feat: per-project workflow settings, statistics and "my work" home

Per-project settings (owners/admins, «Configuración» tab): - Statuses with category (TODO, IN_PROGRESS, QA, DONE, CANCELLED), colour and "requires reason"; configurable transitions; ticket types (icon, colour) and areas. Defaults are the previous fixed values; projects created before keep them without migration. - Values are archived, never deleted: tickets, history and statistics keep referring to them. Validated in the domain (ProjectSettingsChangedEvent). - Releases, board, tracking and "my work" use categories, so custom statuses keep working. Status changes carry name/category metadata for history. - GraphQL: status/type/area are strings (breaking for clients sending enum literals); Project.settings, updateProjectSettings, statusCategory, myIssues(categories). REST: PUT /projects/{project}/settings, category filters. - Read model: statusCategory on issues (backfilled at startup). Statistics («Estadísticas» tab): - New issue_timeline projection; pure functions compute created vs resolved, cumulative flow, cycle/lead time (avg + p85), throughput per person, QA pass/fail and release burnup. GraphQL Project.analytics(days), Release.burnup; REST /projects/{project}/analytics, /releases/{id}/burnup. - Web: SVG charts with validated light/dark palette, crosshair tooltip, keyboard navigation, legend and data table. Home "Mi trabajo": my open tickets across projects grouped by category (QA failures first), tickets waiting for QA, upcoming releases and "Ir a…". Tests: domain/application specs, e2e scenario for settings and analytics, facade tests. Docs, READMEs, schema.gql/openapi.json and Word/PDF updated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 20:53:45 +02:00
parent 240ea9a539
commit 0e301ad545
143 changed files with 10291 additions and 1052 deletions
--- a/libs/api/tracker/presenters/src/lib/http/dto/requests.dto.ts
+++ b/libs/api/tracker/presenters/src/lib/http/dto/requests.dto.ts
@@ -5,16 +5,17 @@ import {
  PartialType,
 } from '@nestjs/swagger';
 import {
-  IssueArea,
  IssueLinkType,
  IssuePriority,
-  IssueStatus,
-  IssueType,
  ProjectRole,
+  SETTING_COLORS,
+  StatusCategory,
+  TYPE_ICONS,
 } from '@task-stream/api/tracker/domain';
 import { Transform, Type } from 'class-transformer';
 import {
  ArrayMaxSize,
+  IsArray,
  IsBoolean,
  IsEnum,
  IsIn,
@@ -29,6 +30,7 @@ import {
  Min,
  MinLength,
  ValidateIf,
+  ValidateNested,
 } from 'class-validator';

 /* REST request bodies and query strings, validated like the GraphQL inputs. */
@@ -46,6 +48,9 @@ const toList = ({ value }: { value: unknown }) =>
 const toBoolean = ({ value }: { value: unknown }) =>
  value === undefined ? undefined : value === true || value === 'true';

+/** Ids of statuses, types and areas (checked against the project's settings). */
+const SETTING_ID = /^[A-Za-z][A-Za-z0-9_]{0,29}$/;
+
 // ---- Projects ---------------------------------------------------------------

 export class CreateProjectDto {
@@ -89,6 +94,121 @@ export class AddMemberDto {
  role: ProjectRole = ProjectRole.MEMBER;
 }

+// ---- Project settings -------------------------------------------------------
+
+export class WorkflowStatusBodyDto {
+  @ApiProperty({
+    example: 'IN_REVIEW',
+    description: 'Never change an existing id',
+  })
+  @Matches(SETTING_ID)
+  id!: string;
+  @ApiProperty({ example: 'En revisión', maxLength: 40 })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(40)
+  name!: string;
+  @ApiProperty({ enum: StatusCategory, enumName: 'StatusCategory' })
+  @IsEnum(StatusCategory)
+  category!: StatusCategory;
+  @ApiProperty({ enum: SETTING_COLORS, enumName: 'SettingColor' })
+  @IsIn(SETTING_COLORS)
+  color!: string;
+  @ApiPropertyOptional({ default: false })
+  @IsOptional()
+  @IsBoolean()
+  requiresReason = false;
+  @ApiPropertyOptional({ default: false })
+  @IsOptional()
+  @IsBoolean()
+  archived = false;
+}
+
+export class StatusTransitionsBodyDto {
+  @ApiProperty({ example: 'IN_QA' }) @Matches(SETTING_ID) from!: string;
+  @ApiProperty({ type: [String], example: ['DONE', 'QA_FAILED'] })
+  @IsArray()
+  @ArrayMaxSize(50)
+  @Matches(SETTING_ID, { each: true })
+  to!: string[];
+}
+
+export class IssueTypeOptionBodyDto {
+  @ApiProperty({ example: 'SPIKE' }) @Matches(SETTING_ID) id!: string;
+  @ApiProperty({ example: 'Spike', maxLength: 40 })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(40)
+  name!: string;
+  @ApiProperty({ enum: TYPE_ICONS, enumName: 'TypeIcon' })
+  @IsIn(TYPE_ICONS)
+  icon!: string;
+  @ApiProperty({ enum: SETTING_COLORS, enumName: 'SettingColor' })
+  @IsIn(SETTING_COLORS)
+  color!: string;
+  @ApiPropertyOptional({ default: false })
+  @IsOptional()
+  @IsBoolean()
+  archived = false;
+}
+
+export class AreaOptionBodyDto {
+  @ApiProperty({ example: 'DATA' }) @Matches(SETTING_ID) id!: string;
+  @ApiProperty({ example: 'Datos', maxLength: 40 })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(40)
+  name!: string;
+  @ApiPropertyOptional({ default: false })
+  @IsOptional()
+  @IsBoolean()
+  archived = false;
+}
+
+export class ProjectSettingsBodyDto {
+  @ApiProperty({
+    type: [WorkflowStatusBodyDto],
+    description:
+      'In board order. Values cannot be removed: archive them instead.',
+  })
+  @IsArray()
+  @ArrayMaxSize(50)
+  @ValidateNested({ each: true })
+  @Type(() => WorkflowStatusBodyDto)
+  statuses!: WorkflowStatusBodyDto[];
+
+  @ApiProperty({ type: [StatusTransitionsBodyDto] })
+  @IsArray()
+  @ArrayMaxSize(50)
+  @ValidateNested({ each: true })
+  @Type(() => StatusTransitionsBodyDto)
+  transitions!: StatusTransitionsBodyDto[];
+
+  @ApiProperty({ type: [IssueTypeOptionBodyDto] })
+  @IsArray()
+  @ArrayMaxSize(50)
+  @ValidateNested({ each: true })
+  @Type(() => IssueTypeOptionBodyDto)
+  issueTypes!: IssueTypeOptionBodyDto[];
+
+  @ApiProperty({ type: [AreaOptionBodyDto] })
+  @IsArray()
+  @ArrayMaxSize(50)
+  @ValidateNested({ each: true })
+  @Type(() => AreaOptionBodyDto)
+  areas!: AreaOptionBodyDto[];
+}
+
+export class AnalyticsQueryDto {
+  @ApiPropertyOptional({ default: 90, minimum: 7, maximum: 365 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(7)
+  @Max(365)
+  days = 90;
+}
+
 export class ChangeMemberRoleDto {
  @ApiProperty({ enum: ProjectRole, enumName: 'ProjectRole' })
  @IsEnum(ProjectRole)
@@ -106,10 +226,10 @@ export class BoardQueryDto {
  @IsString()
  assigneeId?: string;

-  @ApiPropertyOptional({ enum: IssueArea, enumName: 'IssueArea' })
+  @ApiPropertyOptional({ example: 'FRONTEND', description: 'An area id' })
  @IsOptional()
-  @IsEnum(IssueArea)
-  area?: IssueArea;
+  @Matches(SETTING_ID)
+  area?: string;

  @ApiPropertyOptional({ default: 50, minimum: 1, maximum: 200 })
  @IsOptional()
@@ -162,37 +282,79 @@ export class PageQueryDto {

 // ---- Issues -----------------------------------------------------------------

+export class MyIssuesQueryDto extends PageQueryDto {
+  @ApiPropertyOptional({
+    default: true,
+    description:
+      'true: tickets assigned to me. false: any ticket of my projects (e.g. ?assignedToMe=false&category=QA)',
+  })
+  @IsOptional()
+  @Transform(toBoolean)
+  @IsBoolean()
+  assignedToMe = true;
+
+  @ApiPropertyOptional({
+    type: [String],
+    description: 'Status ids. Repeat the parameter or separate with commas',
+  })
+  @IsOptional()
+  @Transform(toList)
+  @Matches(SETTING_ID, { each: true })
+  status?: string[];
+
+  @ApiPropertyOptional({
+    enum: StatusCategory,
+    enumName: 'StatusCategory',
+    isArray: true,
+    description: 'Whatever each project calls its statuses',
+  })
+  @IsOptional()
+  @Transform(toList)
+  @IsEnum(StatusCategory, { each: true })
+  category?: StatusCategory[];
+}
+
+export class UpcomingReleasesQueryDto {
+  @ApiPropertyOptional({ default: 10, minimum: 1, maximum: 50 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(50)
+  limit = 10;
+}
+
 export class IssueSearchQueryDto extends PageQueryDto {
  @ApiPropertyOptional({
-    enum: IssueStatus,
-    enumName: 'IssueStatus',
-    isArray: true,
-    description: 'Repeat the parameter or separate with commas',
+    type: [String],
+    description: 'Status ids. Repeat the parameter or separate with commas',
  })
  @IsOptional()
  @Transform(toList)
-  @IsEnum(IssueStatus, { each: true })
-  status?: IssueStatus[];
+  @Matches(SETTING_ID, { each: true })
+  status?: string[];

  @ApiPropertyOptional({
-    enum: IssueType,
-    enumName: 'IssueType',
+    enum: StatusCategory,
+    enumName: 'StatusCategory',
    isArray: true,
  })
  @IsOptional()
  @Transform(toList)
-  @IsEnum(IssueType, { each: true })
-  type?: IssueType[];
+  @IsEnum(StatusCategory, { each: true })
+  category?: StatusCategory[];

-  @ApiPropertyOptional({
-    enum: IssueArea,
-    enumName: 'IssueArea',
-    isArray: true,
-  })
+  @ApiPropertyOptional({ type: [String], description: 'Ticket type ids' })
  @IsOptional()
  @Transform(toList)
-  @IsEnum(IssueArea, { each: true })
-  area?: IssueArea[];
+  @Matches(SETTING_ID, { each: true })
+  type?: string[];
+
+  @ApiPropertyOptional({ type: [String], description: 'Area ids' })
+  @IsOptional()
+  @Transform(toList)
+  @Matches(SETTING_ID, { each: true })
+  area?: string[];

  @ApiPropertyOptional({
    enum: IssuePriority,
@@ -241,13 +403,14 @@ class IssueFieldsDto {
  description?: string | null;

  @ApiPropertyOptional({
-    enum: IssueArea,
    type: String,
    nullable: true,
+    example: 'FRONTEND',
+    description: "An area id of the project's settings",
  })
  @IsOptional()
-  @IsEnum(IssueArea)
-  area?: IssueArea | null;
+  @Matches(SETTING_ID)
+  area?: string | null;

  @ApiPropertyOptional({ enum: IssuePriority, enumName: 'IssuePriority' })
  @IsOptional()
@@ -289,9 +452,12 @@ class IssueFieldsDto {
 }

 export class CreateIssueDto extends IssueFieldsDto {
-  @ApiProperty({ enum: IssueType, enumName: 'IssueType' })
-  @IsEnum(IssueType)
-  type!: IssueType;
+  @ApiProperty({
+    example: 'BUG',
+    description: "A ticket type id of the project's settings",
+  })
+  @Matches(SETTING_ID)
+  type!: string;

  @ApiProperty({
    example: 'El botón de pagar no responde en Safari',
@@ -318,10 +484,10 @@ export class CreateIssueDto extends IssueFieldsDto {
 }

 export class UpdateIssueDto extends IssueFieldsDto {
-  @ApiPropertyOptional({ enum: IssueType, enumName: 'IssueType' })
+  @ApiPropertyOptional({ example: 'FEATURE', description: 'A ticket type id' })
  @IsOptional()
-  @IsEnum(IssueType)
-  type?: IssueType;
+  @Matches(SETTING_ID)
+  type?: string;

  @ApiPropertyOptional({ maxLength: 255 })
  @IsOptional()
@@ -332,14 +498,18 @@ export class UpdateIssueDto extends IssueFieldsDto {
 }

 export class ChangeStatusDto {
-  @ApiProperty({ enum: IssueStatus, enumName: 'IssueStatus' })
-  @IsEnum(IssueStatus)
-  status!: IssueStatus;
+  @ApiProperty({
+    example: 'IN_REVIEW',
+    description:
+      "A status id of the project's settings, among the ticket's allowedTransitions",
+  })
+  @Matches(SETTING_ID)
+  status!: string;

  @ApiPropertyOptional({
    type: String,
    nullable: true,
-    description: 'Required for QA_FAILED and CANCELLED',
+    description: 'Required by statuses with requiresReason (e.g. QA_FAILED)',
  })
  @IsOptional()
  @IsString()
--- a/libs/api/tracker/presenters/src/lib/http/dto/responses.dto.ts
+++ b/libs/api/tracker/presenters/src/lib/http/dto/responses.dto.ts
@@ -1,12 +1,12 @@
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import {
-  IssueArea,
  IssueLinkType,
  IssuePriority,
-  IssueStatus,
-  IssueType,
  ProjectRole,
  ReleaseStatus,
+  SETTING_COLORS,
+  StatusCategory,
+  TYPE_ICONS,
 } from '@task-stream/api/tracker/domain';

 /*
@@ -25,6 +25,51 @@ export class ProjectMemberDto {
  role!: ProjectRole;
 }

+export class WorkflowStatusDto {
+  @ApiProperty({ example: 'IN_REVIEW', description: 'Stable id on tickets' })
+  id!: string;
+  @ApiProperty({ example: 'En revisión' }) name!: string;
+  @ApiProperty({ enum: StatusCategory, enumName: 'StatusCategory' })
+  category!: StatusCategory;
+  @ApiProperty({ enum: SETTING_COLORS, enumName: 'SettingColor' })
+  color!: string;
+  @ApiProperty({ description: 'Entering it needs a reason' })
+  requiresReason!: boolean;
+  @ApiProperty({ description: 'No new tickets or transitions into it' })
+  archived!: boolean;
+}
+
+export class StatusTransitionsDto {
+  @ApiProperty({ example: 'IN_QA' }) from!: string;
+  @ApiProperty({ type: [String], example: ['DONE', 'QA_FAILED'] })
+  to!: string[];
+}
+
+export class IssueTypeOptionDto {
+  @ApiProperty({ example: 'BUG' }) id!: string;
+  @ApiProperty({ example: 'Bug' }) name!: string;
+  @ApiProperty({ enum: TYPE_ICONS, enumName: 'TypeIcon' }) icon!: string;
+  @ApiProperty({ enum: SETTING_COLORS, enumName: 'SettingColor' })
+  color!: string;
+  @ApiProperty() archived!: boolean;
+}
+
+export class AreaOptionDto {
+  @ApiProperty({ example: 'FRONTEND' }) id!: string;
+  @ApiProperty({ example: 'Frontend' }) name!: string;
+  @ApiProperty() archived!: boolean;
+}
+
+export class ProjectSettingsDto {
+  @ApiProperty({ type: [WorkflowStatusDto], description: 'In board order' })
+  statuses!: WorkflowStatusDto[];
+  @ApiProperty({ type: [StatusTransitionsDto] })
+  transitions!: StatusTransitionsDto[];
+  @ApiProperty({ type: [IssueTypeOptionDto] })
+  issueTypes!: IssueTypeOptionDto[];
+  @ApiProperty({ type: [AreaOptionDto] }) areas!: AreaOptionDto[];
+}
+
 export class ProjectDto {
  @ApiProperty({ format: 'uuid' }) id!: string;
  @ApiProperty({ example: 'WEB', description: 'Prefix of the ticket keys' })
@@ -33,6 +78,8 @@ export class ProjectDto {
  @ApiProperty({ type: String, nullable: true }) description!: string | null;
  @ApiProperty({ type: UserRefDto }) owner!: UserRefDto;
  @ApiProperty({ type: [ProjectMemberDto] }) members!: ProjectMemberDto[];
+  @ApiProperty({ type: ProjectSettingsDto })
+  settings!: ProjectSettingsDto;
  @ApiProperty({ format: 'date-time' }) createdAt!: string;
  @ApiProperty({ format: 'date-time' }) updatedAt!: string;
  @ApiProperty({ description: 'Version of the aggregate (event count)' })
@@ -63,20 +110,21 @@ export class IssueDto {
  @ApiProperty({ example: 'WEB' }) projectKey!: string;
  @ApiProperty({ example: 12 }) number!: number;
  @ApiProperty({ example: 'WEB-12', description: 'Human key' }) key!: string;
-  @ApiProperty({ enum: IssueType, enumName: 'IssueType' }) type!: IssueType;
-  @ApiProperty({ enum: IssueArea, type: String, nullable: true })
-  area!: IssueArea | null;
+  @ApiProperty({ example: 'BUG', description: 'A ticket type id' })
+  type!: string;
+  @ApiProperty({ type: String, nullable: true, example: 'FRONTEND' })
+  area!: string | null;
  @ApiProperty() title!: string;
  @ApiProperty({ type: String, nullable: true }) description!: string | null;
-  @ApiProperty({ enum: IssueStatus, enumName: 'IssueStatus' })
-  status!: IssueStatus;
+  @ApiProperty({ example: 'IN_PROGRESS', description: 'A status id' })
+  status!: string;
+  @ApiProperty({ enum: StatusCategory, enumName: 'StatusCategory' })
+  statusCategory!: StatusCategory;
  @ApiProperty({
-    enum: IssueStatus,
-    enumName: 'IssueStatus',
-    isArray: true,
-    description: 'Statuses this ticket can move to next',
+    type: [String],
+    description: "Statuses this ticket can move to next (project's workflow)",
  })
-  allowedTransitions!: IssueStatus[];
+  allowedTransitions!: string[];
  @ApiProperty({ enum: IssuePriority, enumName: 'IssuePriority' })
  priority!: IssuePriority;
  @ApiProperty({ type: UserRefDto }) reporter!: UserRefDto;
@@ -104,8 +152,7 @@ export class IssuePageDto {
 }

 export class BoardColumnDto {
-  @ApiProperty({ enum: IssueStatus, enumName: 'IssueStatus' })
-  status!: IssueStatus;
+  @ApiProperty({ example: 'IN_PROGRESS' }) status!: string;
  @ApiProperty({ type: [IssueDto] }) issues!: IssueDto[];
  @ApiProperty({ description: 'Tickets in the column (may exceed `issues`)' })
  total!: number;
@@ -143,8 +190,8 @@ export class ReleaseDto {
 }

 export class CountByStatusDto {
-  @ApiProperty({ enum: IssueStatus, enumName: 'IssueStatus' })
-  key!: IssueStatus;
+  @ApiProperty({ example: 'IN_PROGRESS', description: 'Status id' })
+  key!: string;
  @ApiProperty() count!: number;
 }

@@ -213,3 +260,78 @@ export class CommandResultDto {
  })
  version!: number;
 }
+
+// ---- Statistics ---------------------------------------------------------------
+
+export class CreatedResolvedDto {
+  @ApiProperty({ format: 'date', description: 'Monday of the week' })
+  week!: string;
+  @ApiProperty() created!: number;
+  @ApiProperty() resolved!: number;
+}
+
+export class FlowSeriesDto {
+  @ApiProperty({ example: 'IN_PROGRESS' }) status!: string;
+  @ApiProperty({ type: [Number], description: 'One value per date' })
+  counts!: number[];
+}
+
+export class CumulativeFlowDto {
+  @ApiProperty({ type: [String], format: 'date' }) dates!: string[];
+  @ApiProperty({ type: [FlowSeriesDto] }) series!: FlowSeriesDto[];
+}
+
+export class DurationStatsDto {
+  @ApiProperty() count!: number;
+  @ApiProperty({ type: Number, nullable: true }) averageDays!: number | null;
+  @ApiProperty({
+    type: Number,
+    nullable: true,
+    description: '85% of tickets take at most this long',
+  })
+  p85Days!: number | null;
+}
+
+export class ThroughputDto {
+  @ApiProperty({ format: 'date' }) week!: string;
+  @ApiProperty({ type: UserRefDto, nullable: true }) user!: UserRefDto | null;
+  @ApiProperty() count!: number;
+}
+
+export class QaStatsDto {
+  @ApiProperty({ description: 'Left QA to a done status' }) passed!: number;
+  @ApiProperty({ description: 'Left QA back to work' }) failed!: number;
+  @ApiProperty({ type: Number, nullable: true, minimum: 0, maximum: 1 })
+  failureRate!: number | null;
+}
+
+export class ProjectAnalyticsDto {
+  @ApiProperty({ format: 'date-time' }) from!: string;
+  @ApiProperty({ format: 'date-time' }) to!: string;
+  @ApiProperty({ type: [CreatedResolvedDto] })
+  createdVsResolved!: CreatedResolvedDto[];
+  @ApiProperty({
+    type: CumulativeFlowDto,
+    description: 'Tickets in each status at the end of every day',
+  })
+  cumulativeFlow!: CumulativeFlowDto;
+  @ApiProperty({ type: DurationStatsDto, description: 'Start of work → done' })
+  cycleTime!: DurationStatsDto;
+  @ApiProperty({ type: DurationStatsDto, description: 'Creation → done' })
+  leadTime!: DurationStatsDto;
+  @ApiProperty({ type: [ThroughputDto] }) throughput!: ThroughputDto[];
+  @ApiProperty({ type: QaStatsDto }) qa!: QaStatsDto;
+}
+
+export class ReleaseBurnupDto {
+  @ApiProperty({ format: 'uuid' }) releaseId!: string;
+  @ApiProperty({ type: String, nullable: true, format: 'date' })
+  targetDate!: string | null;
+  @ApiProperty({ type: [String], format: 'date' }) dates!: string[];
+  @ApiProperty({
+    type: [Number],
+    description: 'Tickets in the release (not cancelled)',
+  })
+  scope!: number[];
+  @ApiProperty({ type: [Number] }) done!: number[];
+}