From 4611df35ab7bf2fe09378ef7b3ed27da9c937397 Mon Sep 17 00:00:00 2001 From: Gustavo Bueno Date: Wed, 21 Oct 2026 19:17:26 -0300 Subject: [PATCH] feat(backlog): implementar expurgo de contexto (S2-05) e relacoes bidirecionais entre PBIs (S2-15) - S2-05 (PBI-02.2.4): expurgo transacional por projeto com confirmacao pelo nome, auditoria e preservacao dos demais projetos no backend e UI do AdminView - S2-15 (PBI-01.5.3): relacoes bidirecionais (depende de, similar a, substitui), deteccao de ciclos em dependencias, endpoints REST, schema OpenAPI e painel PbiRelationsPanel integrado ao PbiDetail --- backend/src/modules/admin/admin.controller.ts | 10 + backend/src/modules/admin/admin.purge.test.ts | 189 +++++++++ backend/src/modules/admin/admin.repository.ts | 69 ++++ backend/src/modules/admin/admin.routes.ts | 3 + backend/src/modules/admin/admin.service.ts | 49 ++- backend/src/modules/pbis/pbis.controller.ts | 41 +- .../modules/pbis/pbis.relations.repository.ts | 368 ++++++++++++++++++ .../modules/pbis/pbis.relations.service.ts | 58 +++ .../src/modules/pbis/pbis.relations.test.ts | 232 +++++++++++ backend/src/modules/pbis/pbis.routes.ts | 6 + database/init.sql | 14 + database/migrations/020_pbi_relations.sql | 41 ++ docs/api/openapi.yaml | 224 +++++++++++ frontend/src/api/api_backlog.ts | 45 +++ frontend/src/views/admin/AdminView.test.tsx | 87 ++++- frontend/src/views/admin/AdminView.tsx | 127 ++++++ frontend/src/views/backlog/PbiDetail.tsx | 8 + .../views/backlog/PbiRelationsPanel.test.tsx | 226 +++++++++++ .../src/views/backlog/PbiRelationsPanel.tsx | 302 ++++++++++++++ 19 files changed, 2090 insertions(+), 9 deletions(-) create mode 100644 backend/src/modules/admin/admin.purge.test.ts create mode 100644 backend/src/modules/pbis/pbis.relations.repository.ts create mode 100644 backend/src/modules/pbis/pbis.relations.service.ts create mode 100644 backend/src/modules/pbis/pbis.relations.test.ts create mode 100644 database/migrations/020_pbi_relations.sql create mode 100644 frontend/src/views/backlog/PbiRelationsPanel.test.tsx create mode 100644 frontend/src/views/backlog/PbiRelationsPanel.tsx diff --git a/backend/src/modules/admin/admin.controller.ts b/backend/src/modules/admin/admin.controller.ts index 4faa666..a788f98 100644 --- a/backend/src/modules/admin/admin.controller.ts +++ b/backend/src/modules/admin/admin.controller.ts @@ -33,4 +33,14 @@ export class AdminController { next(error); } }; + + purgeProject = async (req: Request, res: Response, next: NextFunction): Promise => { + try { + const projectId = typeof req.params.id === "string" ? req.params.id : ""; + res.json(await this.service.purgeProject(projectId, req.body, req.auth!.id)); + } catch (error) { + next(error); + } + }; } + diff --git a/backend/src/modules/admin/admin.purge.test.ts b/backend/src/modules/admin/admin.purge.test.ts new file mode 100644 index 0000000..3c5ff4b --- /dev/null +++ b/backend/src/modules/admin/admin.purge.test.ts @@ -0,0 +1,189 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { AdminService } from "./admin.service.js"; +import { createAdminRouter } from "./admin.routes.js"; +import { AdminController } from "./admin.controller.js"; +import { NotFoundError, ValidationError } from "../../shared/errors.js"; +import type { Request, Response } from "express"; + +test("S2-05: Expurgo transacional do contexto de um projeto", async (t) => { + const adminUserId = "11111111-1111-4111-8111-111111111111"; + const targetProjectId = "22222222-2222-4222-8222-222222222222"; + const otherProjectId = "33333333-3333-4333-8333-333333333333"; + + await t.test("valida UUID do projeto", async () => { + const service = new AdminService({ + counts: async () => ({} as any), + insertDemoChunks: async () => 0, + }); + + await assert.rejects( + () => service.purgeProject("id-invalido", { confirmacao_nome: "Projeto Alpha" }, adminUserId), + (err: unknown) => err instanceof ValidationError && err.message.includes("ID do projeto"), + ); + }); + + await t.test("exige digitação do nome para confirmar o expurgo (Cenário 3)", async () => { + const service = new AdminService({ + counts: async () => ({} as any), + insertDemoChunks: async () => 0, + }); + + await assert.rejects( + () => service.purgeProject(targetProjectId, {}, adminUserId), + (err: unknown) => err instanceof ValidationError, + ); + + await assert.rejects( + () => service.purgeProject(targetProjectId, { confirmacao_nome: " " }, adminUserId), + (err: unknown) => err instanceof ValidationError, + ); + }); + + await t.test("rejeita quando o nome digitado diverge do nome real do projeto", async () => { + const repoMock = { + counts: async () => ({} as any), + insertDemoChunks: async () => 0, + purgeProjectContext: async () => { + throw new ValidationError("O nome informado não confere com o nome do projeto."); + }, + }; + + const service = new AdminService(repoMock); + + await assert.rejects( + () => service.purgeProject(targetProjectId, { confirmacao_nome: "Nome Errado" }, adminUserId), + (err: unknown) => err instanceof ValidationError && err.message === "O nome informado não confere com o nome do projeto.", + ); + }); + + await t.test("lança NotFoundError quando o projeto não existe", async () => { + const repoMock = { + counts: async () => ({} as any), + insertDemoChunks: async () => 0, + purgeProjectContext: async () => { + throw new NotFoundError("Projeto não encontrado."); + }, + }; + + const service = new AdminService(repoMock); + + await assert.rejects( + () => service.purgeProject(targetProjectId, { confirmacao_nome: "Projeto Inexistente" }, adminUserId), + (err: unknown) => err instanceof NotFoundError && err.message === "Projeto não encontrado.", + ); + }); + + await t.test("remove o contexto indexado com sucesso e audita (Cenário 1 e 2 - preservação dos demais)", async () => { + let purgedTargetCalled = false; + let otherProjectTouched = false; + + // Simulação do repositório garantindo isolamento entre projetos + const chunksDatabase = new Map>([ + [targetProjectId, [{ id: "c-1", texto: "Chunk do projeto alvo" }, { id: "c-2", texto: "Outro chunk" }]], + [otherProjectId, [{ id: "c-3", texto: "Chunk do projeto preservado" }]], + ]); + + const auditLog: Array<{ acao: string; usuario_id: string; entidade_id: string; dados_json: any }> = []; + + const repoMock = { + counts: async () => ({} as any), + insertDemoChunks: async () => 0, + purgeProjectContext: async (projectId: string, confirmacaoNome: string, userId: string, justificativa?: string) => { + if (projectId !== targetProjectId) { + otherProjectTouched = true; + } + + const projectChunks = chunksDatabase.get(projectId) ?? []; + const count = projectChunks.length; + + // Limpa somente o projeto alvo + chunksDatabase.delete(projectId); + purgedTargetCalled = true; + + auditLog.push({ + acao: "EXPURGAR_CONTEXTO", + usuario_id: userId, + entidade_id: projectId, + dados_json: { + projeto_nome: confirmacaoNome, + chunks_removidos: count, + eventos_removidos: 0, + }, + }); + + return { + projeto_id: projectId, + projeto_nome: confirmacaoNome, + chunks_removidos: count, + eventos_removidos: 0, + status: "sucesso" as const, + message: "Contexto indexado do projeto expurgado com sucesso.", + }; + }, + }; + + const service = new AdminService(repoMock); + const result = await service.purgeProject( + targetProjectId, + { confirmacao_nome: "Projeto Alpha", justificativa: "Carga duplicada" }, + adminUserId, + ); + + assert.equal(purgedTargetCalled, true); + assert.equal(otherProjectTouched, false); + assert.equal(result.status, "sucesso"); + assert.equal(result.chunks_removidos, 2); + + // Verificação de preservação estrita do outro projeto (Cenário 2) + assert.equal(chunksDatabase.has(targetProjectId), false, "Projeto alvo deve ter os chunks removidos"); + assert.equal(chunksDatabase.has(otherProjectId), true, "Outro projeto deve permanecer intacto"); + assert.equal(chunksDatabase.get(otherProjectId)?.length, 1); + + // Verificação de auditoria + assert.equal(auditLog.length, 1); + assert.equal(auditLog[0]!.acao, "EXPURGAR_CONTEXTO"); + assert.equal(auditLog[0]!.entidade_id, targetProjectId); + assert.equal(auditLog[0]!.usuario_id, adminUserId); + }); + + await t.test("controller responde com JSON do expurgo", async () => { + let handled = false; + const fakeService = { + stats: async () => ({} as any), + loadDemo: async () => ({} as any), + purgeProject: async (id: string, body: any, userId: string) => { + handled = true; + return { + projeto_id: id, + projeto_nome: "Projeto Beta", + chunks_removidos: 5, + eventos_removidos: 2, + status: "sucesso" as const, + message: "Contexto indexado do projeto expurgado com sucesso.", + }; + }, + }; + + const controller = new AdminController(fakeService as any, {} as any); + + let jsonResponse: any = null; + const req = { + params: { id: targetProjectId }, + body: { confirmacao_nome: "Projeto Beta" }, + auth: { id: adminUserId, role: "admin" }, + } as unknown as Request; + + const res = { + json: (data: any) => { + jsonResponse = data; + }, + } as unknown as Response; + + await controller.purgeProject(req, res, () => {}); + + assert.equal(handled, true); + assert.equal(jsonResponse.status, "sucesso"); + assert.equal(jsonResponse.chunks_removidos, 5); + }); +}); diff --git a/backend/src/modules/admin/admin.repository.ts b/backend/src/modules/admin/admin.repository.ts index 17de41c..f3f652f 100644 --- a/backend/src/modules/admin/admin.repository.ts +++ b/backend/src/modules/admin/admin.repository.ts @@ -1,6 +1,7 @@ import { Pool } from "pg"; import { pool } from "../../database/db.js"; import { withTransaction } from "../../database/transaction.js"; +import { NotFoundError, ValidationError } from "../../shared/errors.js"; import { auditService } from "../audit/audit.service.js"; import { assertWritable, lockHierarchy } from "../projects/hierarchy-archive.js"; @@ -13,6 +14,15 @@ export interface AdminCounts { chunksIndexados: number; } +export interface PurgeProjectResult { + projeto_id: string; + projeto_nome: string; + chunks_removidos: number; + eventos_removidos: number; + status: "sucesso"; + message: string; +} + export class AdminRepository { constructor(private readonly db: Pool = pool) { } @@ -56,4 +66,63 @@ export class AdminRepository { }); } + + async purgeProjectContext( + projectId: string, + confirmacaoNome: string, + userId: string, + justificativa?: string, + ): Promise { + return withTransaction(this.db, async (client) => { + await lockHierarchy(client, "projeto", projectId); + + const projectRes = await client.query<{ id: string; nome: string }>( + "SELECT id, nome FROM projeto WHERE id = $1 FOR UPDATE", + [projectId], + ); + const project = projectRes.rows[0]; + if (!project) throw new NotFoundError("Projeto não encontrado."); + + if (confirmacaoNome.trim() !== project.nome.trim()) { + throw new ValidationError("O nome informado não confere com o nome do projeto."); + } + + const countRes = await client.query<{ count: number }>( + "SELECT COUNT(*)::int AS count FROM chunk WHERE projeto_id = $1", + [projectId], + ); + const chunksRemovidos = countRes.rows[0]?.count ?? 0; + + await client.query("DELETE FROM chunk WHERE projeto_id = $1", [projectId]); + + const eventsCountRes = await client.query( + "DELETE FROM indice_evento WHERE projeto_id = $1", + [projectId], + ); + const eventosRemovidos = eventsCountRes.rowCount ?? 0; + + await auditService.record({ + usuario_id: userId, + entidade_tipo: "projeto", + entidade_id: projectId, + acao: "EXPURGAR_CONTEXTO", + justificativa: justificativa ?? null, + dados_json: { + projeto_nome: project.nome, + chunks_removidos: chunksRemovidos, + eventos_removidos: eventosRemovidos, + }, + }, client); + + return { + projeto_id: projectId, + projeto_nome: project.nome, + chunks_removidos: chunksRemovidos, + eventos_removidos: eventosRemovidos, + status: "sucesso", + message: "Contexto indexado do projeto expurgado com sucesso.", + }; + }); + } } + diff --git a/backend/src/modules/admin/admin.routes.ts b/backend/src/modules/admin/admin.routes.ts index e855b3b..6fa3a37 100644 --- a/backend/src/modules/admin/admin.routes.ts +++ b/backend/src/modules/admin/admin.routes.ts @@ -14,7 +14,10 @@ export function createAdminRouter(controller = new AdminController(), authentica // Observabilidade do pipeline de ingestao (substitui o editor do n8n para // o admin acompanhar o worker). Query opcional: limit=1..100 (default 25). router.get("/ingestion", controller.ingestionSnapshot); + // S2-05: Expurgo transacional do contexto indexado por projeto + router.post("/projects/:id/purge", controller.purgeProject); return router; } export const adminRouter = createAdminRouter(); + diff --git a/backend/src/modules/admin/admin.service.ts b/backend/src/modules/admin/admin.service.ts index a58f0bd..4047739 100644 --- a/backend/src/modules/admin/admin.service.ts +++ b/backend/src/modules/admin/admin.service.ts @@ -1,14 +1,29 @@ import { z } from "zod"; -import { ValidationError } from "../../shared/errors.js"; -import { AdminRepository } from "./admin.repository.js"; +import { ValidationError, validateUuid } from "../../shared/errors.js"; +import { AdminRepository, type PurgeProjectResult } from "./admin.repository.js"; const demoSeedSchema = z.object({ projeto_id: z.string().uuid("Selecione um projeto válido para a carga demonstrativa.") }).strict(); +const purgeProjectSchema = z + .object({ + confirmacao_nome: z.string().trim().min(1, "Informe o nome do projeto para confirmar o expurgo.").optional(), + nome_confirmacao: z.string().trim().min(1, "Informe o nome do projeto para confirmar o expurgo.").optional(), + justificativa: z.string().trim().max(2000).optional(), + }) + .refine((data) => !!(data.confirmacao_nome || data.nome_confirmacao), { + message: "Informe o nome do projeto para confirmar o expurgo.", + path: ["confirmacao_nome"], + }); + export class AdminService { - constructor(private readonly repository: Pick = new AdminRepository()) {} + constructor( + private readonly repository: Pick & + Partial> = new AdminRepository(), + ) {} async stats() { - return { ...await this.repository.counts(), statusSistema: "operacional" }; + + return { ...(await this.repository.counts()), statusSistema: "operacional" }; } async loadDemo(input: unknown, userId: string) { @@ -16,8 +31,30 @@ export class AdminService { if (!parsed.success) throw new ValidationError("Informe o projeto de destino da carga demonstrativa.", parsed.error.flatten()); const inseridos = await this.repository.insertDemoChunks(parsed.data.projeto_id, userId); return { - projeto_id: parsed.data.projeto_id, inseridos, status: "sucesso", - message: inseridos ? "Dados demonstrativos carregados. Nenhuma indexação vetorial foi executada." : "Este projeto já possui a carga demonstrativa. Nenhum trecho foi duplicado.", + projeto_id: parsed.data.projeto_id, + inseridos, + status: "sucesso", + message: inseridos + ? "Dados demonstrativos carregados. Nenhuma indexação vetorial foi executada." + : "Este projeto já possui a carga demonstrativa. Nenhum trecho foi duplicado.", }; } + + async purgeProject(projectId: string, input: unknown, userId: string): Promise { + validateUuid(projectId, "ID do projeto"); + + const parsed = purgeProjectSchema.safeParse(input); + if (!parsed.success) { + const issue = parsed.error.issues[0]; + throw new ValidationError(issue?.message ?? "Informe o nome do projeto para confirmar o expurgo.", parsed.error.flatten()); + } + + const confirmacaoNome = (parsed.data.confirmacao_nome || parsed.data.nome_confirmacao)!; + if (!this.repository.purgeProjectContext) { + throw new Error("purgeProjectContext não configurado."); + } + return await this.repository.purgeProjectContext(projectId, confirmacaoNome, userId, parsed.data.justificativa); + } } + + diff --git a/backend/src/modules/pbis/pbis.controller.ts b/backend/src/modules/pbis/pbis.controller.ts index 9b32def..17eec64 100644 --- a/backend/src/modules/pbis/pbis.controller.ts +++ b/backend/src/modules/pbis/pbis.controller.ts @@ -1,5 +1,6 @@ import { Request, Response, NextFunction } from "express"; import { pbisService, PbisService } from "./pbis.service.js"; +import { pbiRelationsService, PbiRelationsService } from "./pbis.relations.service.js"; function getParamId(param: string | string[] | undefined): string { if (Array.isArray(param)) return param[0] ?? ""; @@ -7,7 +8,11 @@ function getParamId(param: string | string[] | undefined): string { } export class PbisController { - constructor(private readonly service: PbisService = pbisService) {} + constructor( + private readonly service: PbisService = pbisService, + private readonly relationsService: PbiRelationsService = pbiRelationsService, + ) {} + create = async (req: Request, res: Response, next: NextFunction): Promise => { try { @@ -69,6 +74,40 @@ export class PbisController { next(error); } }; + + listRelations = async (req: Request, res: Response, next: NextFunction): Promise => { + try { + const id = getParamId(req.params.id); + const result = await this.relationsService.list(id); + res.status(200).json(result); + } catch (error) { + next(error); + } + }; + + createRelation = async (req: Request, res: Response, next: NextFunction): Promise => { + try { + const id = getParamId(req.params.id); + const usuarioId = req.auth!.id; + const result = await this.relationsService.create(id, req.body, usuarioId); + res.status(201).json(result); + } catch (error) { + next(error); + } + }; + + deleteRelation = async (req: Request, res: Response, next: NextFunction): Promise => { + try { + const id = getParamId(req.params.id); + const relationId = getParamId(req.params.relationId); + const usuarioId = req.auth!.id; + await this.relationsService.remove(id, relationId, usuarioId); + res.status(204).send(); + } catch (error) { + next(error); + } + }; } export const pbisController = new PbisController(); + diff --git a/backend/src/modules/pbis/pbis.relations.repository.ts b/backend/src/modules/pbis/pbis.relations.repository.ts new file mode 100644 index 0000000..5e0a940 --- /dev/null +++ b/backend/src/modules/pbis/pbis.relations.repository.ts @@ -0,0 +1,368 @@ +import { Pool, PoolClient } from "pg"; +import { pool } from "../../database/db.js"; +import { withTransaction } from "../../database/transaction.js"; +import { ConflictError, NotFoundError, ValidationError } from "../../shared/errors.js"; +import { auditService } from "../audit/audit.service.js"; +import { assertWritable, lockHierarchy } from "../projects/hierarchy-archive.js"; + +export type PbiRelationType = "depende_de" | "similar_a" | "substitui"; + +export interface PbiRelationView { + id: string; + pbi_id: string; + relacionado_id: string; + codigo: string; + titulo: string; + status: string; + tipo: string; + prioridade: string; + tipo_relacao: PbiRelationType; + direcao: "saida" | "entrada"; + rotulo: string; + created_at: string; +} + +export interface PbiContextSummary { + id: string; + codigo: string; + titulo: string; + status: string; + projeto_id: string; + projeto_status: string; +} + +export class PbiRelationsRepository { + constructor(private readonly db: Pool = pool) {} + + async getPbiSummary(pbiId: string, client?: Pool | PoolClient): Promise { + const conn = client ?? this.db; + const res = await conn.query( + `SELECT + b.id, + b.codigo, + b.titulo, + b.status, + e.projeto_id, + p.status AS projeto_status + FROM pbi b + JOIN feature f ON f.id = b.feature_id + JOIN epico e ON e.id = f.epico_id + JOIN projeto p ON p.id = e.projeto_id + WHERE b.id = $1`, + [pbiId], + ); + return res.rows[0] ?? null; + } + + async listRelations(pbiId: string): Promise { + const pbi = await this.getPbiSummary(pbiId); + if (!pbi) throw new NotFoundError("PBI não encontrado."); + + const res = await this.db.query<{ + id: string; + pbi_origem_id: string; + pbi_destino_id: string; + tipo_relacao: PbiRelationType; + created_at: Date; + relacionado_id: string; + codigo: string; + titulo: string; + status: string; + tipo: string; + prioridade: string; + }>( + `SELECT + r.id, + r.pbi_origem_id, + r.pbi_destino_id, + r.tipo_relacao, + r.created_at, + CASE WHEN r.pbi_origem_id = $1 THEN r.pbi_destino_id ELSE r.pbi_origem_id END AS relacionado_id, + p.codigo, + p.titulo, + p.status, + p.tipo, + p.prioridade + FROM pbi_relacao r + JOIN pbi p ON p.id = (CASE WHEN r.pbi_origem_id = $1 THEN r.pbi_destino_id ELSE r.pbi_origem_id END) + WHERE r.pbi_origem_id = $1 OR r.pbi_destino_id = $1 + ORDER BY r.created_at DESC`, + [pbiId], + ); + + return res.rows.map((row) => { + const isSaida = row.pbi_origem_id === pbiId; + let rotulo: string; + + if (row.tipo_relacao === "depende_de") { + rotulo = isSaida ? "Depende de" : "É dependência de"; + } else if (row.tipo_relacao === "substitui") { + rotulo = isSaida ? "Substitui" : "Substituído por"; + } else { + rotulo = "Similar a"; + } + + return { + id: row.id, + pbi_id: pbiId, + relacionado_id: row.relacionado_id, + codigo: row.codigo, + titulo: row.titulo, + status: row.status, + tipo: row.tipo, + prioridade: row.prioridade, + tipo_relacao: row.tipo_relacao, + direcao: isSaida ? "saida" : "entrada", + rotulo, + created_at: row.created_at instanceof Date ? row.created_at.toISOString() : String(row.created_at), + }; + }); + } + + async checkDependencyCycle( + origemId: string, + destinoId: string, + client: PoolClient, + ): Promise<{ hasCycle: boolean; path: string[] }> { + // Procura se destinoId já depende de origemId (direta ou transitivamente) + try { + const cteRes = await client.query<{ path: string[] }>( + `WITH RECURSIVE dep_path AS ( + SELECT + pbi_origem_id, + pbi_destino_id, + ARRAY[pbi_origem_id::text, pbi_destino_id::text] AS path, + 1 AS depth + FROM pbi_relacao + WHERE pbi_origem_id = $1 AND tipo_relacao = 'depende_de' + + UNION ALL + + SELECT + r.pbi_origem_id, + r.pbi_destino_id, + dp.path || r.pbi_destino_id::text, + dp.depth + 1 + FROM pbi_relacao r + JOIN dep_path dp ON r.pbi_origem_id = dp.pbi_destino_id::uuid + WHERE r.tipo_relacao = 'depende_de' + AND NOT (r.pbi_destino_id::text = ANY(dp.path)) + AND dp.depth < 50 + ) + SELECT path FROM dep_path WHERE pbi_destino_id = $2 LIMIT 1`, + [destinoId, origemId], + ); + + if (cteRes.rows.length > 0 && cteRes.rows[0]?.path) { + return { hasCycle: true, path: cteRes.rows[0].path }; + } + } catch { + // Fallback em memória (caso execução em ambiente de teste com mock) + const allDeps = await client.query<{ pbi_origem_id: string; pbi_destino_id: string }>( + "SELECT pbi_origem_id, pbi_destino_id FROM pbi_relacao WHERE tipo_relacao = 'depende_de'", + ); + const adj = new Map(); + for (const row of allDeps.rows) { + const list = adj.get(row.pbi_origem_id) ?? []; + list.push(row.pbi_destino_id); + adj.set(row.pbi_origem_id, list); + } + + const queue: string[][] = [[destinoId]]; + const visited = new Set([destinoId]); + + while (queue.length > 0) { + const currPath = queue.shift()!; + const last = currPath[currPath.length - 1]!; + const neighbors = adj.get(last) ?? []; + + for (const neighbor of neighbors) { + if (neighbor === origemId) { + return { hasCycle: true, path: [...currPath, neighbor] }; + } + if (!visited.has(neighbor)) { + visited.add(neighbor); + queue.push([...currPath, neighbor]); + } + } + } + } + + return { hasCycle: false, path: [] }; + } + + async createRelation( + origemId: string, + destinoId: string, + tipo: PbiRelationType, + userId: string, + ): Promise { + if (origemId === destinoId) { + throw new ValidationError("Não é possível relacionar um item de trabalho consigo mesmo."); + } + + return withTransaction(this.db, async (client) => { + // Valida existência e busca detalhes dos dois PBIs + const [origem, destino] = await Promise.all([ + this.getPbiSummary(origemId, client), + this.getPbiSummary(destinoId, client), + ]); + + if (!origem) throw new NotFoundError("PBI de origem não encontrado."); + if (!destino) throw new NotFoundError("PBI de destino não encontrado."); + + // Trava e valida gravabilidade nos projetos envolvidos + await lockHierarchy(client, "projeto", origem.projeto_id); + await assertWritable(client, "projeto", origem.projeto_id); + if (destino.projeto_id !== origem.projeto_id) { + await lockHierarchy(client, "projeto", destino.projeto_id); + await assertWritable(client, "projeto", destino.projeto_id); + } + + // 1. Verificação de duplicidade existente + const existingSame = await client.query( + `SELECT id, tipo_relacao FROM pbi_relacao + WHERE (pbi_origem_id = $1 AND pbi_destino_id = $2) + OR (pbi_origem_id = $2 AND pbi_destino_id = $1)`, + [origemId, destinoId], + ); + + for (const row of existingSame.rows) { + if (row.tipo_relacao === tipo) { + if (tipo === "similar_a") { + throw new ConflictError(`Os itens ${origem.codigo} e ${destino.codigo} já estão relacionados como similares.`); + } + if (row.pbi_origem_id === origemId && row.pbi_destino_id === destinoId) { + throw new ConflictError(`A relação '${tipo}' já existe entre ${origem.codigo} e ${destino.codigo}.`); + } + } + if (tipo === "substitui" && row.tipo_relacao === "substitui") { + throw new ConflictError( + `Conflito: o item ${destino.codigo} já está registrado como substituto de ${origem.codigo}.`, + ); + } + } + + // 2. Prevenção de Ciclos em Dependências + if (tipo === "depende_de") { + const cycleCheck = await this.checkDependencyCycle(origemId, destinoId, client); + if (cycleCheck.hasCycle) { + // Busca os códigos para mensagem amigável + const codeMap = new Map(); + codeMap.set(origemId, origem.codigo); + codeMap.set(destinoId, destino.codigo); + + const idsToFetch = cycleCheck.path.filter((id) => !codeMap.has(id)); + if (idsToFetch.length > 0) { + const pbisRes = await client.query<{ id: string; codigo: string }>( + "SELECT id, codigo FROM pbi WHERE id = ANY($1::uuid[])", + [idsToFetch], + ); + for (const r of pbisRes.rows) codeMap.set(r.id, r.codigo); + } + + const pathFormatted = cycleCheck.path.map((id) => codeMap.get(id) ?? id).join(" -> "); + throw new ValidationError( + `Ciclo de dependência detectado: o item ${destino.codigo} já depende de ${origem.codigo} (${pathFormatted}). Não é permitido criar dependências circulares.`, + ); + } + } + + // 3. Inserção no banco + const insertRes = await client.query<{ id: string; created_at: Date }>( + `INSERT INTO pbi_relacao (pbi_origem_id, pbi_destino_id, tipo_relacao) + VALUES ($1, $2, $3) + RETURNING id, created_at`, + [origemId, destinoId, tipo], + ); + + const relationId = insertRes.rows[0]!.id; + const createdAt = insertRes.rows[0]!.created_at; + + // 4. Registro de Auditoria + await auditService.record( + { + usuario_id: userId, + entidade_tipo: "pbi", + entidade_id: origemId, + acao: "CRIAR_RELACAO_PBI", + dados_json: { + relacao_id: relationId, + pbi_origem_id: origemId, + pbi_origem_codigo: origem.codigo, + pbi_destino_id: destinoId, + pbi_destino_codigo: destino.codigo, + tipo_relacao: tipo, + }, + }, + client, + ); + + let rotulo: string; + if (tipo === "depende_de") rotulo = "Depende de"; + else if (tipo === "substitui") rotulo = "Substitui"; + else rotulo = "Similar a"; + + return { + id: relationId, + pbi_id: origemId, + relacionado_id: destinoId, + codigo: destino.codigo, + titulo: destino.titulo, + status: destino.status, + tipo: destino.status, + prioridade: "Must", + tipo_relacao: tipo, + direcao: "saida", + rotulo, + created_at: createdAt.toISOString(), + }; + }); + } + + async deleteRelation(pbiId: string, relationId: string, userId: string): Promise { + await withTransaction(this.db, async (client) => { + const relRes = await client.query<{ + id: string; + pbi_origem_id: string; + pbi_destino_id: string; + tipo_relacao: string; + }>( + "SELECT id, pbi_origem_id, pbi_destino_id, tipo_relacao FROM pbi_relacao WHERE id = $1 FOR UPDATE", + [relationId], + ); + const relation = relRes.rows[0]; + if (!relation) throw new NotFoundError("Relação não encontrada."); + + if (relation.pbi_origem_id !== pbiId && relation.pbi_destino_id !== pbiId) { + throw new NotFoundError("Relação não pertence ao PBI informado."); + } + + const pbi = await this.getPbiSummary(pbiId, client); + if (pbi) { + await lockHierarchy(client, "projeto", pbi.projeto_id); + await assertWritable(client, "projeto", pbi.projeto_id); + } + + await client.query("DELETE FROM pbi_relacao WHERE id = $1", [relationId]); + + await auditService.record( + { + usuario_id: userId, + entidade_tipo: "pbi", + entidade_id: pbiId, + acao: "REMOVER_RELACAO_PBI", + dados_json: { + relacao_id: relationId, + pbi_origem_id: relation.pbi_origem_id, + pbi_destino_id: relation.pbi_destino_id, + tipo_relacao: relation.tipo_relacao, + }, + }, + client, + ); + }); + } +} + +export const pbiRelationsRepository = new PbiRelationsRepository(); diff --git a/backend/src/modules/pbis/pbis.relations.service.ts b/backend/src/modules/pbis/pbis.relations.service.ts new file mode 100644 index 0000000..79ef9b6 --- /dev/null +++ b/backend/src/modules/pbis/pbis.relations.service.ts @@ -0,0 +1,58 @@ +import { z } from "zod"; +import { ValidationError, validateUuid } from "../../shared/errors.js"; +import { + PbiRelationsRepository, + pbiRelationsRepository, + type PbiRelationType, + type PbiRelationView, +} from "./pbis.relations.repository.js"; + +export const createRelationSchema = z + .object({ + pbi_destino_id: z.string({ required_error: "O PBI de destino é obrigatório." }).uuid("O PBI de destino deve ser um UUID válido."), + tipo_relacao: z + .string({ required_error: "O tipo de relação é obrigatório." }) + .trim() + .transform((val) => val.toLowerCase().replace(/\s+/g, "_")) + .pipe( + z.enum(["depende_de", "similar_a", "substitui"], { + errorMap: () => ({ message: "O tipo de relação deve ser 'depende_de', 'similar_a' ou 'substitui'." }), + }), + ), + }) + .strict(); + +export class PbiRelationsService { + constructor(private readonly repository: PbiRelationsRepository = pbiRelationsRepository) {} + + async list(pbiId: string): Promise<{ items: PbiRelationView[]; total: number }> { + validateUuid(pbiId, "ID do PBI"); + const items = await this.repository.listRelations(pbiId); + return { items, total: items.length }; + } + + async create(pbiOrigemId: string, input: unknown, userId: string): Promise { + validateUuid(pbiOrigemId, "ID do PBI de origem"); + + const parsed = createRelationSchema.safeParse(input); + if (!parsed.success) { + const issue = parsed.error.issues[0]; + throw new ValidationError(issue?.message ?? "Dados da relação inválidos.", parsed.error.format()); + } + + return await this.repository.createRelation( + pbiOrigemId, + parsed.data.pbi_destino_id, + parsed.data.tipo_relacao as PbiRelationType, + userId, + ); + } + + async remove(pbiId: string, relationId: string, userId: string): Promise { + validateUuid(pbiId, "ID do PBI"); + validateUuid(relationId, "ID da relação"); + await this.repository.deleteRelation(pbiId, relationId, userId); + } +} + +export const pbiRelationsService = new PbiRelationsService(); diff --git a/backend/src/modules/pbis/pbis.relations.test.ts b/backend/src/modules/pbis/pbis.relations.test.ts new file mode 100644 index 0000000..50191bb --- /dev/null +++ b/backend/src/modules/pbis/pbis.relations.test.ts @@ -0,0 +1,232 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { PbiRelationsService, createRelationSchema } from "./pbis.relations.service.js"; +import { PbiRelationsRepository, type PbiRelationView } from "./pbis.relations.repository.js"; +import { ConflictError, NotFoundError, ValidationError } from "../../shared/errors.js"; + +test("S2-15: Relações bidirecionais entre PBIs e prevenção de ciclos", async (t) => { + const pbiA = "11111111-1111-4111-8111-111111111111"; + const pbiB = "22222222-2222-4222-8222-222222222222"; + const pbiC = "33333333-3333-4333-8333-333333333333"; + const pbiD = "44444444-4444-4444-8444-444444444444"; + const userId = "99999999-9999-4999-8999-999999999999"; + + await t.test("valida schema de criação aceitando tipos com underscore ou espaço", () => { + assert.equal( + createRelationSchema.parse({ pbi_destino_id: pbiB, tipo_relacao: "depende_de" }).tipo_relacao, + "depende_de", + ); + assert.equal( + createRelationSchema.parse({ pbi_destino_id: pbiB, tipo_relacao: "depende de" }).tipo_relacao, + "depende_de", + ); + assert.equal( + createRelationSchema.parse({ pbi_destino_id: pbiB, tipo_relacao: "similar a" }).tipo_relacao, + "similar_a", + ); + assert.equal( + createRelationSchema.parse({ pbi_destino_id: pbiB, tipo_relacao: "substitui" }).tipo_relacao, + "substitui", + ); + + assert.throws( + () => createRelationSchema.parse({ pbi_destino_id: pbiB, tipo_relacao: "invalido" }), + (err: any) => err.name === "ZodError", + ); + assert.throws( + () => createRelationSchema.parse({ pbi_destino_id: "nao-uuid", tipo_relacao: "depende_de" }), + (err: any) => err.name === "ZodError", + ); + }); + + await t.test("impede relacionar um item consigo mesmo (Cenário 2)", async () => { + const service = new PbiRelationsService({ + listRelations: async () => [], + createRelation: async (origem: string, destino: string) => { + if (origem === destino) { + throw new ValidationError("Não é possível relacionar um item de trabalho consigo mesmo."); + } + return {} as any; + }, + deleteRelation: async () => {}, + } as any); + + await assert.rejects( + () => service.create(pbiA, { pbi_destino_id: pbiA, tipo_relacao: "depende_de" }, userId), + (err: unknown) => err instanceof ValidationError && err.message.includes("consigo mesmo"), + ); + }); + + await t.test("detecção de ciclo em dependências direta (A -> B, B -> A) (Cenário 2)", async () => { + // Simula grafo com A depende de B + const edges = new Map([[pbiA, [pbiB]]]); + + const repo = new PbiRelationsRepository({} as any); + const mockClient = { + query: async (sql: string, params: any[]) => { + // Fallback em memória acionado + if (sql.includes("pbi_relacao WHERE tipo_relacao = 'depende_de'")) { + const rows: Array<{ pbi_origem_id: string; pbi_destino_id: string }> = []; + for (const [orig, dests] of edges.entries()) { + for (const d of dests) rows.push({ pbi_origem_id: orig, pbi_destino_id: d }); + } + return { rows }; + } + throw new Error("Simula fallback do CTE"); + }, + } as any; + + // Tentando fazer B depender de A: + const checkDirect = await repo.checkDependencyCycle(pbiB, pbiA, mockClient); + assert.equal(checkDirect.hasCycle, true, "Deve detectar ciclo direto"); + assert.deepEqual(checkDirect.path, [pbiA, pbiB]); + + // Tentando fazer C depender de A (sem ciclo): + const checkNoCycle = await repo.checkDependencyCycle(pbiC, pbiA, mockClient); + assert.equal(checkNoCycle.hasCycle, false, "Não deve acusar ciclo quando não há caminho"); + }); + + await t.test("detecção de ciclo em dependências transitiva (A -> B -> C -> D, D -> A) (Cenário 2)", async () => { + // A -> B -> C -> D + const edges = new Map([ + [pbiA, [pbiB]], + [pbiB, [pbiC]], + [pbiC, [pbiD]], + ]); + + const repo = new PbiRelationsRepository({} as any); + const mockClient = { + query: async (sql: string) => { + if (sql.includes("pbi_relacao WHERE tipo_relacao = 'depende_de'")) { + const rows: Array<{ pbi_origem_id: string; pbi_destino_id: string }> = []; + for (const [orig, dests] of edges.entries()) { + for (const d of dests) rows.push({ pbi_origem_id: orig, pbi_destino_id: d }); + } + return { rows }; + } + throw new Error("Simula fallback do CTE"); + }, + } as any; + + // Tentando fazer D depender de A: fecha o ciclo D -> A -> B -> C -> D + const checkTransitive = await repo.checkDependencyCycle(pbiD, pbiA, mockClient); + assert.equal(checkTransitive.hasCycle, true, "Deve detectar ciclo transitivo"); + assert.deepEqual(checkTransitive.path, [pbiA, pbiB, pbiC, pbiD]); + }); + + await t.test("exibição bidirecional nos dois itens (Cenário 1)", async () => { + // Mock do repositório contendo relação A -> B (depende_de) e A <-> C (similar_a) + const relationsDb = [ + { + id: "rel-1", + pbi_origem_id: pbiA, + pbi_destino_id: pbiB, + tipo_relacao: "depende_de" as const, + created_at: new Date("2026-10-20T10:00:00Z"), + }, + { + id: "rel-2", + pbi_origem_id: pbiA, + pbi_destino_id: pbiC, + tipo_relacao: "similar_a" as const, + created_at: new Date("2026-10-20T11:00:00Z"), + }, + { + id: "rel-3", + pbi_origem_id: pbiA, + pbi_destino_id: pbiD, + tipo_relacao: "substitui" as const, + created_at: new Date("2026-10-20T12:00:00Z"), + }, + ]; + + const pbiInfo: Record = { + [pbiA]: { codigo: "PBI-01.1.1", titulo: "Autenticação", status: "concluido", tipo: "Funcional", prioridade: "Must" }, + [pbiB]: { codigo: "PBI-01.1.2", titulo: "Banco de dados", status: "concluido", tipo: "Funcional", prioridade: "Must" }, + [pbiC]: { codigo: "PBI-01.1.3", titulo: "Login Social", status: "rascunho", tipo: "Funcional", prioridade: "Should" }, + [pbiD]: { codigo: "PBI-01.1.4", titulo: "Auth Legada", status: "arquivado", tipo: "Funcional", prioridade: "Could" }, + }; + + const mockPool = { + query: async (sql: string, params: any[]) => { + if (sql.includes("FROM pbi b")) { + // getPbiSummary + const id = params[0]; + return { rows: [{ id, ...pbiInfo[id], projeto_id: "proj-1", projeto_status: "ativo" }] }; + } + if (sql.includes("FROM pbi_relacao r")) { + // listRelations + const pbiId = params[0]; + const matched = relationsDb.filter(r => r.pbi_origem_id === pbiId || r.pbi_destino_id === pbiId); + const rows = matched.map(r => { + const relId = r.pbi_origem_id === pbiId ? r.pbi_destino_id : r.pbi_origem_id; + return { + ...r, + relacionado_id: relId, + ...pbiInfo[relId], + }; + }); + return { rows }; + } + return { rows: [] }; + }, + } as any; + + const repo = new PbiRelationsRepository(mockPool); + + // Consulta pela visão do item A (origem) + const relsFromA = await repo.listRelations(pbiA); + assert.equal(relsFromA.length, 3); + + const depFromA = relsFromA.find(r => r.relacionado_id === pbiB); + assert.equal(depFromA?.rotulo, "Depende de"); + assert.equal(depFromA?.direcao, "saida"); + assert.equal(depFromA?.codigo, "PBI-01.1.2"); + + const simFromA = relsFromA.find(r => r.relacionado_id === pbiC); + assert.equal(simFromA?.rotulo, "Similar a"); + + const subFromA = relsFromA.find(r => r.relacionado_id === pbiD); + assert.equal(subFromA?.rotulo, "Substitui"); + assert.equal(subFromA?.direcao, "saida"); + + // Consulta pela visão do item B (destino da dependência) + const relsFromB = await repo.listRelations(pbiB); + assert.equal(relsFromB.length, 1); + const depFromB = relsFromB[0]!; + assert.equal(depFromB.relacionado_id, pbiA); + assert.equal(depFromB.rotulo, "É dependência de"); + assert.equal(depFromB.direcao, "entrada"); + assert.equal(depFromB.codigo, "PBI-01.1.1"); + + // Consulta pela visão do item C (destino da similaridade - simétrico) + const relsFromC = await repo.listRelations(pbiC); + assert.equal(relsFromC.length, 1); + const simFromC = relsFromC[0]!; + assert.equal(simFromC.relacionado_id, pbiA); + assert.equal(simFromC.rotulo, "Similar a"); + + // Consulta pela visão do item D (destino da substituição) + const relsFromD = await repo.listRelations(pbiD); + assert.equal(relsFromD.length, 1); + const subFromD = relsFromD[0]!; + assert.equal(subFromD.relacionado_id, pbiA); + assert.equal(subFromD.rotulo, "Substituído por"); + assert.equal(subFromD.direcao, "entrada"); + }); + + await t.test("rejeita relação duplicada com 409 Conflict", async () => { + const fakeRepo = { + createRelation: async () => { + throw new ConflictError("A relação 'depende_de' já existe entre os itens."); + }, + } as any; + + const service = new PbiRelationsService(fakeRepo); + + await assert.rejects( + () => service.create(pbiA, { pbi_destino_id: pbiB, tipo_relacao: "depende_de" }, userId), + (err: unknown) => err instanceof ConflictError && err.message.includes("já existe"), + ); + }); +}); diff --git a/backend/src/modules/pbis/pbis.routes.ts b/backend/src/modules/pbis/pbis.routes.ts index 78604ca..b4bf871 100644 --- a/backend/src/modules/pbis/pbis.routes.ts +++ b/backend/src/modules/pbis/pbis.routes.ts @@ -379,6 +379,12 @@ pbisRouter.patch("/:id/complete", canWrite, pbisController.complete); */ pbisRouter.get("/:id/quality", pbisController.quality); +// S2-15: Relações bidirecionais entre PBIs (depende de, similar a, substitui) e detecção de ciclos +pbisRouter.get("/:id/relations", pbisController.listRelations); +pbisRouter.post("/:id/relations", canWrite, pbisController.createRelation); +pbisRouter.delete("/:id/relations/:relationId", canWrite, pbisController.deleteRelation); + const archive = archiveHandlers("pbi"); pbisRouter.get("/:id/archive-impact", canWrite, archive.impact); pbisRouter.patch("/:id/archive", canWrite, archive.archive); + diff --git a/database/init.sql b/database/init.sql index 0df6d30..d89b27e 100644 --- a/database/init.sql +++ b/database/init.sql @@ -220,6 +220,16 @@ CREATE TABLE IF NOT EXISTS analise_repositorio ( concluido_em TIMESTAMPTZ ); +-- 20. Tabela: PBI_RELACAO (Relações entre PBIs / S2-15) +CREATE TABLE IF NOT EXISTS pbi_relacao ( + id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), + pbi_origem_id UUID NOT NULL REFERENCES pbi(id) ON DELETE CASCADE, + pbi_destino_id UUID NOT NULL REFERENCES pbi(id) ON DELETE CASCADE, + tipo_relacao VARCHAR(50) NOT NULL CHECK (tipo_relacao IN ('depende_de', 'similar_a', 'substitui')), + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + CONSTRAINT pbi_relacao_sem_auto_relacao CHECK (pbi_origem_id <> pbi_destino_id) +); + -- Índices de Otimização e Busca Vetorial CREATE INDEX IF NOT EXISTS idx_chunk_projeto_id ON chunk(projeto_id); CREATE INDEX IF NOT EXISTS idx_chunk_entidade ON chunk(entidade_tipo, entidade_id); @@ -229,6 +239,9 @@ CREATE INDEX IF NOT EXISTS idx_criterio_entidade ON criterio_aceitacao(entidade_ CREATE INDEX IF NOT EXISTS idx_analise_repositorio_projeto ON analise_repositorio(projeto_id); CREATE INDEX IF NOT EXISTS idx_analise_repositorio_usuario ON analise_repositorio(usuario_id); CREATE INDEX IF NOT EXISTS idx_analise_repositorio_created_at ON analise_repositorio(created_at DESC); +CREATE UNIQUE INDEX IF NOT EXISTS idx_pbi_relacao_unica ON pbi_relacao(pbi_origem_id, pbi_destino_id, tipo_relacao); +CREATE INDEX IF NOT EXISTS idx_pbi_relacao_origem ON pbi_relacao(pbi_origem_id); +CREATE INDEX IF NOT EXISTS idx_pbi_relacao_destino ON pbi_relacao(pbi_destino_id); -- Índice HNSW no pgvector para busca por similaridade de cosseno ultrarrápida CREATE INDEX IF NOT EXISTS idx_chunk_embedding ON chunk USING hnsw (embedding vector_cosine_ops); @@ -238,3 +251,4 @@ CREATE INDEX IF NOT EXISTS idx_documento_ingestao_pendente ON documento(processamento_proxima_tentativa, created_at) WHERE status_processamento IN ('pendente', 'processando'); + diff --git a/database/migrations/020_pbi_relations.sql b/database/migrations/020_pbi_relations.sql new file mode 100644 index 0000000..05c4f35 --- /dev/null +++ b/database/migrations/020_pbi_relations.sql @@ -0,0 +1,41 @@ +-- S2-15: Relações bidirecionais entre PBIs e prevenção de ciclos +-- Tabela pbi_relacao com constraints de tipo, auto-relação e unicidade + +DO $$ +BEGIN + -- Cria a tabela caso não exista (idempotente) + CREATE TABLE IF NOT EXISTS pbi_relacao ( + id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), + pbi_origem_id UUID NOT NULL REFERENCES pbi(id) ON DELETE CASCADE, + pbi_destino_id UUID NOT NULL REFERENCES pbi(id) ON DELETE CASCADE, + tipo_relacao VARCHAR(50) NOT NULL, + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP + ); +END $$; + +-- Garante constraint dos tipos permitidos: depende_de, similar_a, substitui +ALTER TABLE pbi_relacao + DROP CONSTRAINT IF EXISTS pbi_relacao_tipo_relacao_check; + +ALTER TABLE pbi_relacao + ADD CONSTRAINT pbi_relacao_tipo_relacao_check + CHECK (tipo_relacao IN ('depende_de', 'similar_a', 'substitui')); + +-- Impede auto-relação +ALTER TABLE pbi_relacao + DROP CONSTRAINT IF EXISTS pbi_relacao_sem_auto_relacao; + +ALTER TABLE pbi_relacao + ADD CONSTRAINT pbi_relacao_sem_auto_relacao + CHECK (pbi_origem_id <> pbi_destino_id); + +-- Unicidade da relação +CREATE UNIQUE INDEX IF NOT EXISTS idx_pbi_relacao_unica + ON pbi_relacao(pbi_origem_id, pbi_destino_id, tipo_relacao); + +-- Índices bidirecionais para consulta rápida +CREATE INDEX IF NOT EXISTS idx_pbi_relacao_origem + ON pbi_relacao(pbi_origem_id); + +CREATE INDEX IF NOT EXISTS idx_pbi_relacao_destino + ON pbi_relacao(pbi_destino_id); diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml index 080a57c..68be7d3 100644 --- a/docs/api/openapi.yaml +++ b/docs/api/openapi.yaml @@ -162,7 +162,71 @@ paths: '400': {description: Modo ou cursor inválido} '401': {description: Autenticação necessária} '403': {description: Somente administrador} + /api/v1/admin/projects/{id}/purge: + post: + operationId: purgeProjectContext + summary: Expurgo transacional do contexto indexado do projeto (PBI-02.2.4 / S2-05) + description: > + Remove todo o conteúdo indexado (tabela chunk e fila de eventos) do projeto informado, + exigindo a confirmação explícita do nome do projeto. Preserva intactos os demais projetos + e registra auditoria da operação administrativa. + security: + - cookieAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + format: uuid + description: ID do projeto a ser expurgado + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - confirmacao_nome + properties: + confirmacao_nome: + type: string + description: Digitação do nome exato do projeto para confirmar o expurgo + justificativa: + type: string + description: Justificativa opcional da operação de expurgo + responses: + '200': + description: Contexto do projeto expurgado com sucesso + content: + application/json: + schema: + type: object + properties: + status: + type: string + example: sucesso + message: + type: string + projeto_id: + type: string + format: uuid + projeto_nome: + type: string + chunks_removidos: + type: integer + eventos_removidos: + type: integer + '400': + $ref: '#/components/responses/ValidationError' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + description: Somente administrador + '404': + description: Projeto não encontrado /api/v1/projects/{projectId}/ai/requests: + post: operationId: runHarness summary: Executa o harness local vigente sem gravar conteúdo do item @@ -1223,7 +1287,118 @@ paths: '404': description: PBI não encontrado + /api/v1/pbis/{id}/relations: + get: + operationId: listPbiRelations + summary: Listar relações bidirecionais do PBI (PBI-01.5.3 / S2-15) + description: Lista todas as dependências, similaridades e substituições conectadas ao PBI (como origem ou destino). + security: + - cookieAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + format: uuid + responses: + '200': + description: Lista de relações do PBI + content: + application/json: + schema: + type: object + properties: + items: + type: array + items: + $ref: '#/components/schemas/PbiRelationView' + total: + type: integer + '401': + $ref: '#/components/responses/Unauthorized' + '404': + description: PBI não encontrado + post: + operationId: createPbiRelation + summary: Criar relação entre PBIs com detecção de ciclo (PBI-01.5.3 / S2-15) + description: Registra uma relação (depende_de, similar_a ou substitui) com outro PBI e impede ciclos de dependência. + security: + - cookieAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + format: uuid + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - pbi_destino_id + - tipo_relacao + properties: + pbi_destino_id: + type: string + format: uuid + description: ID do PBI de destino da relação + tipo_relacao: + type: string + enum: [depende_de, similar_a, substitui] + description: Tipo de relação entre os PBIs + responses: + '201': + description: Relação criada com sucesso + content: + application/json: + schema: + $ref: '#/components/schemas/PbiRelationView' + '400': + $ref: '#/components/responses/ValidationError' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + description: Perfil sem permissão de escrita + '404': + description: PBI de origem ou destino não encontrado + '409': + description: Conflito de relação existente ou projeto arquivado + + /api/v1/pbis/{id}/relations/{relationId}: + delete: + operationId: deletePbiRelation + summary: Remover relação de um PBI (PBI-01.5.3 / S2-15) + security: + - cookieAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + format: uuid + - name: relationId + in: path + required: true + schema: + type: string + format: uuid + responses: + '204': + description: Relação removida com sucesso + '401': + $ref: '#/components/responses/Unauthorized' + '403': + description: Perfil sem permissão de escrita + '404': + description: Relação ou PBI não encontrado + /api/v1/quality/pbis/{id}/quality: + get: summary: Calcula o indicador de completude sobre o checklist vigente do PBI (PBI-01.3.6 / S1-15) operationId: getPbiCompleteness @@ -3253,6 +3428,55 @@ components: created_by: {type: string, format: uuid, nullable: true} output_schemas: {type: object, description: Schemas JSON por operação e nível; schema_version 1, additionalProperties false} + + PbiRelationView: + type: object + required: + - id + - pbi_id + - relacionado_id + - codigo + - titulo + - status + - tipo + - prioridade + - tipo_relacao + - direcao + - rotulo + - created_at + properties: + id: + type: string + format: uuid + pbi_id: + type: string + format: uuid + relacionado_id: + type: string + format: uuid + codigo: + type: string + titulo: + type: string + status: + type: string + tipo: + type: string + prioridade: + type: string + tipo_relacao: + type: string + enum: [depende_de, similar_a, substitui] + direcao: + type: string + enum: [saida, entrada] + rotulo: + type: string + created_at: + type: string + format: date-time + + TechnologyOption: type: object required: [id, nome] diff --git a/frontend/src/api/api_backlog.ts b/frontend/src/api/api_backlog.ts index efcb703..c22c512 100644 --- a/frontend/src/api/api_backlog.ts +++ b/frontend/src/api/api_backlog.ts @@ -996,3 +996,48 @@ export async function getItemHistory( next_cursor: data.next_cursor ?? null, }; } + +export type PbiRelationType = "depende_de" | "similar_a" | "substitui"; + +export interface PbiRelation { + id: string; + pbi_id: string; + relacionado_id: string; + codigo: string; + titulo: string; + status: string; + tipo: string; + prioridade: string; + tipo_relacao: PbiRelationType; + direcao: "saida" | "entrada"; + rotulo: string; + created_at: string; +} + +export async function getPbiRelations(pbiId: string, signal?: AbortSignal): Promise { + const response = await apiRequest(`/pbis/${encodeURIComponent(pbiId)}/relations`, { signal }); + const data = await response.json(); + return Array.isArray(data.items) ? data.items : []; +} + +export async function createPbiRelation( + pbiId: string, + destinoId: string, + tipo: PbiRelationType, +): Promise { + const response = await apiRequest(`/pbis/${encodeURIComponent(pbiId)}/relations`, { + method: "POST", + body: JSON.stringify({ + pbi_destino_id: destinoId, + tipo_relacao: tipo, + }), + }); + return await response.json(); +} + +export async function deletePbiRelation(pbiId: string, relationId: string): Promise { + await apiRequest(`/pbis/${encodeURIComponent(pbiId)}/relations/${encodeURIComponent(relationId)}`, { + method: "DELETE", + }); +} + diff --git a/frontend/src/views/admin/AdminView.test.tsx b/frontend/src/views/admin/AdminView.test.tsx index b59b0e6..5eb863c 100644 --- a/frontend/src/views/admin/AdminView.test.tsx +++ b/frontend/src/views/admin/AdminView.test.tsx @@ -21,7 +21,7 @@ it("exige escolha explícita, envia o projeto e informa carga idempotente sem pr render(); const button = screen.getByRole("button", { name: "Carregar demonstração" }); expect(button).toBeDisabled(); - await screen.findByRole("option", { name: project.nome }); + await screen.findAllByRole("option", { name: project.nome }); expect(screen.queryByRole("option", { name: "Arquivado" })).toBeNull(); expect(button).toBeDisabled(); fireEvent.change(screen.getByLabelText("Projeto de destino"), { target: { value: project.id } }); @@ -41,8 +41,91 @@ it("exibe o erro do backend quando o projeto foi arquivado após a seleção", a return json({}); })); render(); - await screen.findByRole("option", { name: project.nome }); + await screen.findAllByRole("option", { name: project.nome }); fireEvent.change(screen.getByLabelText("Projeto de destino"), { target: { value: project.id } }); fireEvent.click(screen.getByRole("button", { name: "Carregar demonstração" })); expect(await screen.findByRole("alert")).toHaveTextContent("Projeto arquivado é somente leitura."); }); + +it("exige confirmação exata do nome do projeto para habilitar botão de expurgo e envia requisição transacional", async () => { + let purged = false; + const request = vi.fn((url: string, init?: RequestInit) => { + if (url.includes("/projects?")) { + return json({ items: [project], total: 1, limit: 50, offset: 0 }); + } + if (url.includes(`/admin/projects/${project.id}/purge`)) { + expect(init!.method).toBe("POST"); + const body = JSON.parse(init!.body as string); + expect(body.confirmacao_nome).toBe(project.nome); + expect(body.justificativa).toBe("Limpeza solicitada"); + purged = true; + return json({ + chunks_removidos: 15, + eventos_removidos: 3, + documentos_afetados: 2, + projeto_id: project.id, + nome: project.nome, + expurgado_em: "2026-10-21T10:00:00.000Z", + }); + } + return json({ projetos: 1, epicos: 0, features: 0, pbis: 0, documentos: 0, chunksIndexados: 15, statusSistema: "operacional" }); + }); + vi.stubGlobal("fetch", request); + + render(); + await screen.findAllByRole("option", { name: project.nome }); + + const purgeBtn = screen.getByRole("button", { name: "Expurgar contexto do projeto" }); + expect(purgeBtn).toBeDisabled(); + + // Seleciona o projeto a expurgar + fireEvent.change(screen.getByLabelText("Projeto para expurgo"), { target: { value: project.id } }); + expect(purgeBtn).toBeDisabled(); + + // Digita nome incorreto + const confirmInput = screen.getByLabelText(/Digite exatamente o nome do projeto/); + fireEvent.change(confirmInput, { target: { value: "Nome Errado" } }); + expect(purgeBtn).toBeDisabled(); + + // Digita nome correto + fireEvent.change(confirmInput, { target: { value: project.nome } }); + expect(purgeBtn).toBeEnabled(); + + // Preenche justificativa + fireEvent.change(screen.getByLabelText("Justificativa (opcional):"), { target: { value: "Limpeza solicitada" } }); + + // Executa o expurgo + fireEvent.click(purgeBtn); + + expect( + await screen.findByText(/Contexto indexado de "Projeto escolhido" expurgado com sucesso/i) + ).toBeInTheDocument(); + expect(purged).toBe(true); +}); + +it("exibe mensagem de erro quando o expurgo do projeto falha", async () => { + const request = vi.fn((url: string) => { + if (url.includes("/projects?")) { + return json({ items: [project], total: 1, limit: 50, offset: 0 }); + } + if (url.includes(`/admin/projects/${project.id}/purge`)) { + return json({ error: "Nome de confirmação não confere com o projeto." }, 400); + } + return json({ projetos: 1, epicos: 0, features: 0, pbis: 0, documentos: 0, chunksIndexados: 0, statusSistema: "operacional" }); + }); + vi.stubGlobal("fetch", request); + + render(); + await screen.findAllByRole("option", { name: project.nome }); + + fireEvent.change(screen.getByLabelText("Projeto para expurgo"), { target: { value: project.id } }); + const confirmInput = screen.getByLabelText(/Digite exatamente o nome do projeto/); + fireEvent.change(confirmInput, { target: { value: project.nome } }); + + const purgeBtn = screen.getByRole("button", { name: "Expurgar contexto do projeto" }); + fireEvent.click(purgeBtn); + + expect(await screen.findByRole("alert")).toHaveTextContent("Nome de confirmação não confere com o projeto."); +}); + + diff --git a/frontend/src/views/admin/AdminView.tsx b/frontend/src/views/admin/AdminView.tsx index 466a0b7..e2b286d 100644 --- a/frontend/src/views/admin/AdminView.tsx +++ b/frontend/src/views/admin/AdminView.tsx @@ -83,6 +83,50 @@ export const AdminView: React.FC = () => { } }; + const [purgeProjectId, setPurgeProjectId] = useState(""); + const [purgeConfirmName, setPurgeConfirmName] = useState(""); + const [purgeJustification, setPurgeJustification] = useState(""); + const [purging, setPurging] = useState(false); + const [purgeMessage, setPurgeMessage] = useState(""); + const [purgeError, setPurgeError] = useState(""); + + const selectedPurgeProject = projects.find(p => p.id === purgeProjectId); + + const handlePurgeProject = async () => { + if (!purgeProjectId || purging) return; + const selected = projects.find(p => p.id === purgeProjectId); + if (!selected) return; + + if (purgeConfirmName.trim() !== selected.nome.trim()) { + setPurgeError("O nome informado não confere com o nome do projeto."); + return; + } + + setPurging(true); + setPurgeMessage(""); + setPurgeError(""); + + try { + const res = await apiRequest(`/admin/projects/${purgeProjectId}/purge`, { + method: "POST", + body: JSON.stringify({ + confirmacao_nome: purgeConfirmName.trim(), + justificativa: purgeJustification.trim() || undefined, + }), + }); + const data = await res.json(); + setPurgeMessage(data.message || `Contexto indexado de "${selected.nome}" expurgado com sucesso.`); + setPurgeConfirmName(""); + setPurgeJustification(""); + void loadStats(); + } catch (err: unknown) { + const details = err instanceof ApiError ? (err.details as { message?: string; error?: string } | undefined) : undefined; + setPurgeError(details?.message ?? details?.error ?? (err instanceof Error ? err.message : "Não foi possível expurgar o contexto do projeto.")); + } finally { + setPurging(false); + } + }; + return (
@@ -161,6 +205,89 @@ export const AdminView: React.FC = () => {
+ + {/* Painel de Expurgo de Contexto (S2-05) */} +
+

Expurgo de Contexto do Projeto

+

+ Operação destrutiva e irreversível: o expurgo remove todo o conteúdo indexado (trechos e vetores do acervo) e a fila de indexação do projeto selecionado. Os demais projetos permanecem intactos. +

+ + {purgeMessage && ( +
+ {purgeMessage} +
+ )} + + {purgeError && ( +
+ {purgeError} +
+ )} + +
+ + +
+ + {selectedPurgeProject && ( + <> +
+ + setPurgeConfirmName(event.target.value)} + disabled={purging} + /> +
+ +
+ + setPurgeJustification(event.target.value)} + disabled={purging} + /> +
+ + )} + +
+ +
+
); }; + diff --git a/frontend/src/views/backlog/PbiDetail.tsx b/frontend/src/views/backlog/PbiDetail.tsx index b9b512b..bcf3e54 100644 --- a/frontend/src/views/backlog/PbiDetail.tsx +++ b/frontend/src/views/backlog/PbiDetail.tsx @@ -26,6 +26,7 @@ import { SuggestionsPanel } from "./SuggestionsPanel"; import { ProvenanceBadge } from "./ProvenanceBadge"; import { ItemHistoryView } from "./ItemHistoryView"; import { QualityPanelView as QualityPanel } from "./QualityPanelView"; +import { PbiRelationsPanel } from "./PbiRelationsPanel"; type PbiFields = Pick< PbiInput, @@ -802,6 +803,13 @@ export function PbiDetail({ readOnlyNote={readOnly ? "Item ou ancestral arquivado: as decisões ficam disponíveis somente para consulta." : undefined} /> + + { + afterEach(() => { + cleanup(); + vi.restoreAllMocks(); + }); + + it("renderiza lista vazia quando não há relações", async () => { + vi.spyOn(apiBacklog, "getPbiRelations").mockResolvedValue([]); + vi.spyOn(apiBacklogTree, "getProjectBacklogTree").mockResolvedValue(mockTree); + + render( + + ); + + expect(await screen.findByText("Nenhuma relação registrada")).toBeInTheDocument(); + }); + + it("renderiza relações existentes com rótulos e badges corretos", async () => { + vi.spyOn(apiBacklog, "getPbiRelations").mockResolvedValue(mockRelations); + vi.spyOn(apiBacklogTree, "getProjectBacklogTree").mockResolvedValue(mockTree); + + render( + + ); + + expect(await screen.findByText("Depende de")).toBeInTheDocument(); + expect(screen.getByText("É dependência de")).toBeInTheDocument(); + expect(screen.getByText("Login com OAuth")).toBeInTheDocument(); + expect(screen.getByText("Autenticação em 2 Fatores")).toBeInTheDocument(); + }); + + it("filtra o PBI atual dos candidatos no dropdown", async () => { + vi.spyOn(apiBacklog, "getPbiRelations").mockResolvedValue([]); + vi.spyOn(apiBacklogTree, "getProjectBacklogTree").mockResolvedValue(mockTree); + + render( + + ); + + await screen.findByLabelText("PBI Relacionado"); + const options = screen.getAllByRole("option"); + const optionTexts = options.map((opt) => opt.textContent); + + expect(optionTexts).toContain("[PBI-01.1] Login com OAuth"); + expect(optionTexts).toContain("[PBI-03.1] Recuperação de Senha"); + expect(optionTexts).not.toContain("[PBI-00.1] PBI Atual"); + }); + + it("cria uma nova relação com sucesso", async () => { + vi.spyOn(apiBacklog, "getPbiRelations").mockResolvedValueOnce([]).mockResolvedValueOnce([mockRelations[0]]); + vi.spyOn(apiBacklogTree, "getProjectBacklogTree").mockResolvedValue(mockTree); + const createSpy = vi.spyOn(apiBacklog, "createPbiRelation").mockResolvedValue(mockRelations[0]); + + render( + + ); + + await screen.findByLabelText("PBI Relacionado"); + fireEvent.change(screen.getByLabelText("PBI Relacionado"), { + target: { value: "pbi-target-1" }, + }); + + const submitBtn = screen.getByRole("button", { name: "Adicionar relação" }); + expect(submitBtn).toBeEnabled(); + fireEvent.click(submitBtn); + + await waitFor(() => { + expect(createSpy).toHaveBeenCalledWith("pbi-source", "pbi-target-1", "depende_de"); + }); + expect(await screen.findByText("Relação criada com sucesso.")).toBeInTheDocument(); + }); + + it("exibe alerta quando backend rejeita por ciclo de dependência", async () => { + vi.spyOn(apiBacklog, "getPbiRelations").mockResolvedValue([]); + vi.spyOn(apiBacklogTree, "getProjectBacklogTree").mockResolvedValue(mockTree); + vi.spyOn(apiBacklog, "createPbiRelation").mockRejectedValue( + new Error("Ciclo de dependência detectado: o item de destino já depende direta ou indiretamente deste PBI.") + ); + + render( + + ); + + await screen.findByLabelText("PBI Relacionado"); + fireEvent.change(screen.getByLabelText("PBI Relacionado"), { + target: { value: "pbi-target-1" }, + }); + + fireEvent.click(screen.getByRole("button", { name: "Adicionar relação" })); + + expect( + await screen.findByText(/Ciclo de dependência detectado/) + ).toBeInTheDocument(); + }); + + it("remove uma relação com sucesso", async () => { + vi.spyOn(apiBacklog, "getPbiRelations").mockResolvedValueOnce([mockRelations[0]]).mockResolvedValueOnce([]); + vi.spyOn(apiBacklogTree, "getProjectBacklogTree").mockResolvedValue(mockTree); + const deleteSpy = vi.spyOn(apiBacklog, "deletePbiRelation").mockResolvedValue(); + + render( + + ); + + const deleteBtn = await screen.findByRole("button", { name: /Remover relação com PBI-01.1/ }); + fireEvent.click(deleteBtn); + + await waitFor(() => { + expect(deleteSpy).toHaveBeenCalledWith("pbi-source", "rel-1"); + }); + expect(await screen.findByText("Relação removida com sucesso.")).toBeInTheDocument(); + }); + + it("bloqueia edição e exibe aviso em modo somente leitura", async () => { + vi.spyOn(apiBacklog, "getPbiRelations").mockResolvedValue(mockRelations); + vi.spyOn(apiBacklogTree, "getProjectBacklogTree").mockResolvedValue(mockTree); + + render( + + ); + + expect( + await screen.findByText(/Item ou projeto arquivado: as relações estão disponíveis apenas para consulta/) + ).toBeInTheDocument(); + expect(screen.queryByRole("button", { name: "Adicionar relação" })).toBeNull(); + expect(screen.queryByRole("button", { name: /Remover/ })).toBeNull(); + }); +}); diff --git a/frontend/src/views/backlog/PbiRelationsPanel.tsx b/frontend/src/views/backlog/PbiRelationsPanel.tsx new file mode 100644 index 0000000..7b3fd26 --- /dev/null +++ b/frontend/src/views/backlog/PbiRelationsPanel.tsx @@ -0,0 +1,302 @@ +import React, { useEffect, useState } from "react"; +import { + createPbiRelation, + deletePbiRelation, + getPbiRelations, + type PbiRelation, + type PbiRelationType, +} from "../../api/api_backlog"; +import { getProjectBacklogTree } from "../../api/api_backlog_tree"; +import { Alert, Badge, Button, EmptyState } from "../common/ui"; + +export interface PbiRelationsPanelProps { + pbiId: string; + projectId: string; + canEdit: boolean; + readOnly: boolean; +} + +interface CandidatePbi { + id: string; + codigo: string; + titulo: string; +} + +export function PbiRelationsPanel({ + pbiId, + projectId, + canEdit, + readOnly, +}: PbiRelationsPanelProps) { + const [relations, setRelations] = useState([]); + const [candidates, setCandidates] = useState([]); + const [loading, setLoading] = useState(true); + const [error, setError] = useState(null); + + const [targetPbiId, setTargetPbiId] = useState(""); + const [relationType, setRelationType] = useState("depende_de"); + const [submitting, setSubmitting] = useState(false); + const [actionError, setActionError] = useState(null); + const [actionSuccess, setActionSuccess] = useState(null); + const [deletingId, setDeletingId] = useState(null); + const [reloadTrigger, setReloadTrigger] = useState(0); + + // Load relations and candidate PBIs + useEffect(() => { + const controller = new AbortController(); + setLoading(true); + setError(null); + + Promise.all([ + getPbiRelations(pbiId, controller.signal), + getProjectBacklogTree(projectId, controller.signal).catch(() => null), + ]) + .then(([rels, tree]) => { + if (controller.signal.aborted) return; + setRelations(rels); + + if (tree && Array.isArray(tree.epics)) { + const pbis: CandidatePbi[] = []; + for (const epic of tree.epics) { + for (const feat of epic.features || []) { + for (const p of feat.pbis || []) { + if (p.id !== pbiId) { + pbis.push({ + id: p.id, + codigo: p.codigo, + titulo: p.titulo, + }); + } + } + } + } + setCandidates(pbis); + } + }) + .catch((err) => { + if (!controller.signal.aborted) { + setError(err?.message || "Não foi possível carregar as relações do PBI."); + } + }) + .finally(() => { + if (!controller.signal.aborted) { + setLoading(false); + } + }); + + return () => controller.abort(); + }, [pbiId, projectId, reloadTrigger]); + + const handleAddRelation = async (e: React.FormEvent) => { + e.preventDefault(); + if (!targetPbiId) { + setActionError("Selecione um PBI para relacionar."); + return; + } + + setSubmitting(true); + setActionError(null); + setActionSuccess(null); + + try { + await createPbiRelation(pbiId, targetPbiId, relationType); + setActionSuccess("Relação criada com sucesso."); + setTargetPbiId(""); + setReloadTrigger((v) => v + 1); + } catch (err: any) { + setActionError(err?.message || "Erro ao criar relação entre PBIs."); + } finally { + setSubmitting(false); + } + }; + + const handleDeleteRelation = async (relationId: string) => { + setDeletingId(relationId); + setActionError(null); + setActionSuccess(null); + + try { + await deletePbiRelation(pbiId, relationId); + setActionSuccess("Relação removida com sucesso."); + setReloadTrigger((v) => v + 1); + } catch (err: any) { + setActionError(err?.message || "Erro ao remover relação."); + } finally { + setDeletingId(null); + } + }; + + const getBadgeTone = (tipo: PbiRelationType) => { + switch (tipo) { + case "depende_de": + return "warning"; + case "substitui": + return "danger"; + case "similar_a": + return "info"; + default: + return undefined; + } + }; + + return ( +
+
+
+

Relações do PBI

+

+ Mapeamento bidirecional de dependências com detecção de ciclo, similaridades e substituições. +

+
+
+ + {readOnly && ( + + Item ou projeto arquivado: as relações estão disponíveis apenas para consulta. + + )} + + {error && ( + + {error} + + )} + + {actionError && ( +
+ + {actionError} + +
+ )} + + {actionSuccess && ( +
+ + {actionSuccess} + +
+ )} + + {/* Formulário para adicionar nova relação */} + {canEdit && !readOnly && ( +
+

Adicionar Nova Relação

+
+
+ + +
+ +
+ + +
+ + +
+
+ )} + + {loading ? ( +

Carregando relações…

+ ) : relations.length === 0 ? ( + + ) : ( +
    + {relations.map((rel) => ( +
  • +
    + + {rel.rotulo} + + +
    + + {rel.codigo || "PBI"}: + + {rel.titulo} + {rel.status && ( + + ({rel.status}) + + )} +
    +
    + + {canEdit && !readOnly && ( + + )} +
    • + ))} +
+ )} +
+ ); +}