feat(backend): persist tasks and generated message history

- add EntityTask domain and CRUD API backed by PostgreSQL

- relate generated messages directly to tasks and delete on task removal

- move preview generation to backend Llama endpoint

- migrate frontend task APIs from localStorage to backend endpoints

- update tests and CLAUDE rules for backend-owned LLM/persistence
This commit is contained in:
2026-03-27 02:46:56 -03:00
parent f2a16b5cf6
commit ebcea643c4
20 changed files with 1181 additions and 244 deletions

View File

@@ -0,0 +1,81 @@
package com.condado.newsletter.controller
import com.condado.newsletter.dto.EntityTaskCreateDto
import com.condado.newsletter.dto.EntityTaskResponseDto
import com.condado.newsletter.dto.EntityTaskUpdateDto
import com.condado.newsletter.service.EntityTaskService
import jakarta.validation.Valid
import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.DeleteMapping
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.PathVariable
import org.springframework.web.bind.annotation.PostMapping
import org.springframework.web.bind.annotation.PutMapping
import org.springframework.web.bind.annotation.RequestBody
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController
import java.util.UUID
/**
* REST controller for task CRUD operations.
*/
@RestController
@RequestMapping("/api/v1/tasks")
class EntityTaskController(
private val entityTaskService: EntityTaskService
) {
/** Lists active tasks across all entities. */
@GetMapping
fun getAllActive(): ResponseEntity<List<EntityTaskResponseDto>> =
ResponseEntity.ok(entityTaskService.findAllActive())
/** Lists all tasks for one entity. */
@GetMapping("/entity/{entityId}")
fun getByEntity(@PathVariable entityId: UUID): ResponseEntity<List<EntityTaskResponseDto>> =
ResponseEntity.ok(entityTaskService.findByEntity(entityId))
/** Returns one task by id. */
@GetMapping("/{taskId}")
fun getById(@PathVariable taskId: UUID): ResponseEntity<EntityTaskResponseDto> {
val task = entityTaskService.findById(taskId) ?: return ResponseEntity.notFound().build()
return ResponseEntity.ok(task)
}
/** Creates a task. */
@PostMapping
fun create(@Valid @RequestBody dto: EntityTaskCreateDto): ResponseEntity<EntityTaskResponseDto> =
ResponseEntity.status(HttpStatus.CREATED).body(entityTaskService.create(dto))
/** Updates a task. */
@PutMapping("/{taskId}")
fun update(
@PathVariable taskId: UUID,
@Valid @RequestBody dto: EntityTaskUpdateDto
): ResponseEntity<EntityTaskResponseDto> {
val task = entityTaskService.update(taskId, dto) ?: return ResponseEntity.notFound().build()
return ResponseEntity.ok(task)
}
/** Inactivates a task. */
@PostMapping("/{taskId}/inactivate")
fun inactivate(@PathVariable taskId: UUID): ResponseEntity<EntityTaskResponseDto> {
val task = entityTaskService.inactivate(taskId) ?: return ResponseEntity.notFound().build()
return ResponseEntity.ok(task)
}
/** Activates a task. */
@PostMapping("/{taskId}/activate")
fun activate(@PathVariable taskId: UUID): ResponseEntity<EntityTaskResponseDto> {
val task = entityTaskService.activate(taskId) ?: return ResponseEntity.notFound().build()
return ResponseEntity.ok(task)
}
/** Deletes a task and all linked generated-message history. */
@DeleteMapping("/{taskId}")
fun delete(@PathVariable taskId: UUID): ResponseEntity<Void> {
entityTaskService.delete(taskId)
return ResponseEntity.noContent().build()
}
}

View File

@@ -0,0 +1,49 @@
package com.condado.newsletter.controller
import com.condado.newsletter.dto.GeneratedMessageHistoryResponseDto
import com.condado.newsletter.dto.TaskPreviewGenerateRequestDto
import com.condado.newsletter.service.TaskGeneratedMessageService
import jakarta.validation.Valid
import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.DeleteMapping
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.PathVariable
import org.springframework.web.bind.annotation.PostMapping
import org.springframework.web.bind.annotation.RequestBody
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController
import java.util.UUID
/**
* REST endpoints for task generated-message history and server-side preview generation.
*/
@RestController
@RequestMapping("/api/v1/tasks/{taskId}/generated-messages")
class TaskGeneratedMessageController(
private val taskGeneratedMessageService: TaskGeneratedMessageService
) {
/** Lists generated-message history for one task. */
@GetMapping
fun getAllByTask(@PathVariable taskId: UUID): ResponseEntity<List<GeneratedMessageHistoryResponseDto>> =
ResponseEntity.ok(taskGeneratedMessageService.list(taskId))
/** Generates a new test message via backend Llama call and persists it. */
@PostMapping("/generate")
fun generate(
@PathVariable taskId: UUID,
@Valid @RequestBody request: TaskPreviewGenerateRequestDto
): ResponseEntity<GeneratedMessageHistoryResponseDto> =
ResponseEntity.status(HttpStatus.CREATED).body(taskGeneratedMessageService.generateAndSave(taskId, request))
/** Deletes one persisted generated message for a task. */
@DeleteMapping("/{messageId}")
fun delete(
@PathVariable taskId: UUID,
@PathVariable messageId: UUID
): ResponseEntity<Void> {
taskGeneratedMessageService.delete(taskId, messageId)
return ResponseEntity.noContent().build()
}
}

View File

@@ -0,0 +1,48 @@
package com.condado.newsletter.dto
import com.condado.newsletter.model.EntityTask
import jakarta.validation.constraints.NotBlank
import jakarta.validation.constraints.NotNull
import java.time.LocalDateTime
import java.util.UUID
data class EntityTaskCreateDto(
@field:NotNull val entityId: UUID,
@field:NotBlank val name: String,
@field:NotBlank val prompt: String,
@field:NotBlank val scheduleCron: String,
@field:NotBlank val emailLookback: String
)
data class EntityTaskUpdateDto(
@field:NotNull val entityId: UUID,
@field:NotBlank val name: String,
@field:NotBlank val prompt: String,
@field:NotBlank val scheduleCron: String,
@field:NotBlank val emailLookback: String
)
data class EntityTaskResponseDto(
val id: UUID,
val entityId: UUID,
val name: String,
val prompt: String,
val scheduleCron: String,
val emailLookback: String,
val active: Boolean,
val createdAt: LocalDateTime?
) {
companion object {
fun from(task: EntityTask): EntityTaskResponseDto =
EntityTaskResponseDto(
id = task.id!!,
entityId = task.virtualEntity.id!!,
name = task.name,
prompt = task.prompt,
scheduleCron = task.scheduleCron,
emailLookback = task.emailLookback,
active = task.active,
createdAt = task.createdAt
)
}
}

View File

@@ -0,0 +1,51 @@
package com.condado.newsletter.dto
import com.condado.newsletter.model.GeneratedMessageHistory
import jakarta.validation.Valid
import jakarta.validation.constraints.NotBlank
import jakarta.validation.constraints.NotNull
import java.time.LocalDateTime
import java.util.UUID
data class GeneratedMessageHistoryResponseDto(
val id: UUID,
val taskId: UUID,
val label: String,
val content: String,
val createdAt: LocalDateTime
) {
companion object {
fun from(model: GeneratedMessageHistory): GeneratedMessageHistoryResponseDto =
GeneratedMessageHistoryResponseDto(
id = model.id!!,
taskId = model.task.id!!,
label = model.label,
content = model.content,
createdAt = model.createdAt
)
}
}
data class TaskPreviewEntityDto(
@field:NotBlank val id: String,
@field:NotBlank val name: String,
@field:NotBlank val email: String,
@field:NotBlank val jobTitle: String,
val personality: String? = null,
val scheduleCron: String? = null,
@field:NotNull val contextWindowDays: Int,
@field:NotNull val active: Boolean
)
data class TaskPreviewTaskDto(
@field:NotBlank val entityId: String,
@field:NotBlank val name: String,
@field:NotBlank val prompt: String,
@field:NotBlank val scheduleCron: String,
@field:NotBlank val emailLookback: String
)
data class TaskPreviewGenerateRequestDto(
@field:Valid @field:NotNull val entity: TaskPreviewEntityDto,
@field:Valid @field:NotNull val task: TaskPreviewTaskDto
)

View File

@@ -0,0 +1,53 @@
package com.condado.newsletter.model
import jakarta.persistence.CascadeType
import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.FetchType
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.JoinColumn
import jakarta.persistence.ManyToOne
import jakarta.persistence.OneToMany
import jakarta.persistence.Table
import org.hibernate.annotations.CreationTimestamp
import java.time.LocalDateTime
import java.util.UUID
/**
* Represents a configurable task belonging to a virtual entity.
*/
@Entity
@Table(name = "entity_tasks")
class EntityTask(
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "entity_id", nullable = false)
val virtualEntity: VirtualEntity,
@Column(nullable = false)
val name: String,
@Column(columnDefinition = "TEXT", nullable = false)
val prompt: String,
@Column(name = "schedule_cron", nullable = false)
val scheduleCron: String,
@Column(name = "email_lookback", nullable = false)
val emailLookback: String,
@Column(nullable = false)
val active: Boolean = true,
@CreationTimestamp
@Column(name = "created_at", updatable = false, nullable = false)
val createdAt: LocalDateTime? = null
) {
@Id
@GeneratedValue(strategy = GenerationType.UUID)
var id: UUID? = null
@OneToMany(mappedBy = "task", cascade = [CascadeType.ALL], orphanRemoval = true)
val generatedMessages: MutableList<GeneratedMessageHistory> = mutableListOf()
}

View File

@@ -0,0 +1,37 @@
package com.condado.newsletter.model
import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.FetchType
import jakarta.persistence.JoinColumn
import jakarta.persistence.ManyToOne
import jakarta.persistence.Table
import java.time.LocalDateTime
import java.util.UUID
/**
* Stores generated test messages for a task, so the history survives page reloads and restarts.
*/
@Entity
@Table(name = "generated_message_history")
class GeneratedMessageHistory(
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "task_id", nullable = false)
val task: EntityTask,
@Column(nullable = false)
val label: String,
@Column(columnDefinition = "TEXT", nullable = false)
val content: String,
@Column(name = "created_at", nullable = false)
val createdAt: LocalDateTime = LocalDateTime.now()
) {
@Id
@GeneratedValue(strategy = GenerationType.UUID)
var id: UUID? = null
}

View File

@@ -0,0 +1,11 @@
package com.condado.newsletter.repository
import com.condado.newsletter.model.EntityTask
import com.condado.newsletter.model.VirtualEntity
import org.springframework.data.jpa.repository.JpaRepository
import java.util.UUID
interface EntityTaskRepository : JpaRepository<EntityTask, UUID> {
fun findAllByActiveTrue(): List<EntityTask>
fun findAllByVirtualEntity(virtualEntity: VirtualEntity): List<EntityTask>
}

View File

@@ -0,0 +1,12 @@
package com.condado.newsletter.repository
import com.condado.newsletter.model.GeneratedMessageHistory
import org.springframework.data.jpa.repository.JpaRepository
import java.util.UUID
interface GeneratedMessageHistoryRepository : JpaRepository<GeneratedMessageHistory, UUID> {
fun findAllByTask_IdOrderByCreatedAtDesc(taskId: UUID): List<GeneratedMessageHistory>
fun countByTask_Id(taskId: UUID): Long
fun deleteByIdAndTask_Id(id: UUID, taskId: UUID): Long
fun deleteAllByTask_Id(taskId: UUID)
}

View File

@@ -0,0 +1,116 @@
package com.condado.newsletter.service
import com.condado.newsletter.dto.EntityTaskCreateDto
import com.condado.newsletter.dto.EntityTaskResponseDto
import com.condado.newsletter.dto.EntityTaskUpdateDto
import com.condado.newsletter.model.EntityTask
import com.condado.newsletter.repository.EntityTaskRepository
import com.condado.newsletter.repository.GeneratedMessageHistoryRepository
import com.condado.newsletter.repository.VirtualEntityRepository
import org.springframework.stereotype.Service
import org.springframework.transaction.annotation.Transactional
import java.util.UUID
/**
* Service layer for CRUD operations on entity tasks.
*/
@Service
class EntityTaskService(
private val entityTaskRepository: EntityTaskRepository,
private val virtualEntityRepository: VirtualEntityRepository,
private val generatedMessageHistoryRepository: GeneratedMessageHistoryRepository
) {
/** Returns active tasks only. */
fun findAllActive(): List<EntityTaskResponseDto> =
entityTaskRepository.findAllByActiveTrue().map { EntityTaskResponseDto.from(it) }
/** Returns all tasks for one virtual entity, including inactive ones. */
fun findByEntity(entityId: UUID): List<EntityTaskResponseDto> {
val entity = virtualEntityRepository.findById(entityId).orElse(null) ?: return emptyList()
return entityTaskRepository.findAllByVirtualEntity(entity).map { EntityTaskResponseDto.from(it) }
}
/** Returns one task by id. */
fun findById(taskId: UUID): EntityTaskResponseDto? =
entityTaskRepository.findById(taskId).map { EntityTaskResponseDto.from(it) }.orElse(null)
/** Creates a new task. */
@Transactional
fun create(dto: EntityTaskCreateDto): EntityTaskResponseDto {
val entity = virtualEntityRepository.findById(dto.entityId)
.orElseThrow { IllegalArgumentException("Virtual entity not found: ${dto.entityId}") }
val task = EntityTask(
virtualEntity = entity,
name = dto.name,
prompt = dto.prompt,
scheduleCron = dto.scheduleCron,
emailLookback = dto.emailLookback,
active = true
)
return EntityTaskResponseDto.from(entityTaskRepository.save(task))
}
/** Updates one existing task. */
@Transactional
fun update(taskId: UUID, dto: EntityTaskUpdateDto): EntityTaskResponseDto? {
val existing = entityTaskRepository.findById(taskId).orElse(null) ?: return null
val entity = virtualEntityRepository.findById(dto.entityId)
.orElseThrow { IllegalArgumentException("Virtual entity not found: ${dto.entityId}") }
val updated = EntityTask(
virtualEntity = entity,
name = dto.name,
prompt = dto.prompt,
scheduleCron = dto.scheduleCron,
emailLookback = dto.emailLookback,
active = existing.active,
createdAt = existing.createdAt
).apply { id = existing.id }
return EntityTaskResponseDto.from(entityTaskRepository.save(updated))
}
/** Marks task as inactive. */
@Transactional
fun inactivate(taskId: UUID): EntityTaskResponseDto? {
val existing = entityTaskRepository.findById(taskId).orElse(null) ?: return null
val updated = EntityTask(
virtualEntity = existing.virtualEntity,
name = existing.name,
prompt = existing.prompt,
scheduleCron = existing.scheduleCron,
emailLookback = existing.emailLookback,
active = false,
createdAt = existing.createdAt
).apply { id = existing.id }
return EntityTaskResponseDto.from(entityTaskRepository.save(updated))
}
/** Marks task as active. */
@Transactional
fun activate(taskId: UUID): EntityTaskResponseDto? {
val existing = entityTaskRepository.findById(taskId).orElse(null) ?: return null
val updated = EntityTask(
virtualEntity = existing.virtualEntity,
name = existing.name,
prompt = existing.prompt,
scheduleCron = existing.scheduleCron,
emailLookback = existing.emailLookback,
active = true,
createdAt = existing.createdAt
).apply { id = existing.id }
return EntityTaskResponseDto.from(entityTaskRepository.save(updated))
}
/** Deletes a task and all generated messages linked to it. */
@Transactional
fun delete(taskId: UUID) {
generatedMessageHistoryRepository.deleteAllByTask_Id(taskId)
entityTaskRepository.deleteById(taskId)
}
}

View File

@@ -0,0 +1,47 @@
package com.condado.newsletter.service
import com.fasterxml.jackson.annotation.JsonIgnoreProperties
import com.fasterxml.jackson.annotation.JsonProperty
import org.springframework.beans.factory.annotation.Value
import org.springframework.stereotype.Service
import org.springframework.web.client.RestClient
/** Calls a local Llama/Ollama endpoint to generate test task messages. */
@Service
class LlamaPreviewService(
private val restClient: RestClient,
@Value("\${llama.base-url:http://localhost:11434}") private val baseUrl: String,
@Value("\${llama.model:gemma3:4b}") private val model: String
) {
/**
* Generates one message from the provided prompt.
*/
fun generate(prompt: String): String {
val response = restClient.post()
.uri("${baseUrl.trimEnd('/')}/api/generate")
.body(LlamaGenerateRequest(model = model, prompt = prompt, stream = false))
.retrieve()
.body(LlamaGenerateResponse::class.java)
?: throw IllegalStateException("Llama returned an empty response")
val text = response.response?.trim().orEmpty()
if (text.isBlank()) {
throw IllegalStateException("Llama returned an empty message")
}
return text
}
private data class LlamaGenerateRequest(
val model: String,
val prompt: String,
val stream: Boolean
)
@JsonIgnoreProperties(ignoreUnknown = true)
private data class LlamaGenerateResponse(
@JsonProperty("response")
val response: String?
)
}

View File

@@ -0,0 +1,96 @@
package com.condado.newsletter.service
import com.condado.newsletter.dto.GeneratedMessageHistoryResponseDto
import com.condado.newsletter.dto.TaskPreviewGenerateRequestDto
import com.condado.newsletter.model.GeneratedMessageHistory
import com.condado.newsletter.repository.EntityTaskRepository
import com.condado.newsletter.repository.GeneratedMessageHistoryRepository
import org.springframework.stereotype.Service
import org.springframework.transaction.annotation.Transactional
import java.util.UUID
/**
* Handles generation and persistence of task test-message history.
*/
@Service
class TaskGeneratedMessageService(
private val generatedMessageHistoryRepository: GeneratedMessageHistoryRepository,
private val entityTaskRepository: EntityTaskRepository,
private val llamaPreviewService: LlamaPreviewService
) {
/** Lists persisted generated messages for a task. */
fun list(taskId: UUID): List<GeneratedMessageHistoryResponseDto> =
generatedMessageHistoryRepository
.findAllByTask_IdOrderByCreatedAtDesc(taskId)
.map { GeneratedMessageHistoryResponseDto.from(it) }
/**
* Generates a new message using local Llama, persists it, and returns it.
*/
@Transactional
fun generateAndSave(taskId: UUID, request: TaskPreviewGenerateRequestDto): GeneratedMessageHistoryResponseDto {
val task = entityTaskRepository.findById(taskId)
.orElseThrow { IllegalArgumentException("Task not found: $taskId") }
val prompt = buildPrompt(request)
val generatedContent = llamaPreviewService.generate(prompt)
val nextLabel = "Message #${generatedMessageHistoryRepository.countByTask_Id(taskId) + 1}"
val saved = generatedMessageHistoryRepository.save(
GeneratedMessageHistory(
task = task,
label = nextLabel,
content = generatedContent
)
)
return GeneratedMessageHistoryResponseDto.from(saved)
}
/** Deletes one history item from a task. */
@Transactional
fun delete(taskId: UUID, messageId: UUID) {
generatedMessageHistoryRepository.deleteByIdAndTask_Id(messageId, taskId)
}
private fun buildPrompt(request: TaskPreviewGenerateRequestDto): String {
val entity = request.entity
val task = request.task
val personality = entity.personality?.takeIf { it.isNotBlank() } ?: "Not provided"
val entityCron = entity.scheduleCron?.takeIf { it.isNotBlank() } ?: "Not provided"
val lookbackLabel = when (task.emailLookback) {
"last_day" -> "Last 24 hours"
"last_month" -> "Last month"
else -> "Last week"
}
return listOf(
"You are preparing a test email message for a scheduled task in Condado Abaixo da Media SA.",
"",
"ENTITY DETAILS",
"- Entity ID: ${entity.id}",
"- Name: ${entity.name}",
"- Email: ${entity.email}",
"- Job Title: ${entity.jobTitle}",
"- Personality: $personality",
"- Entity Schedule Cron: $entityCron",
"- Context Window Days: ${entity.contextWindowDays}",
"- Active: ${entity.active}",
"",
"TASK DETAILS",
"- Task Name: ${task.name}",
"- Task Prompt: ${task.prompt}",
"- Task Schedule Cron: ${task.scheduleCron}",
"- Email Lookback: $lookbackLabel",
"",
"INSTRUCTIONS",
"- Write exactly one email message.",
"- The message must be written by ${entity.name} (${entity.jobTitle}) as the sender persona.",
"- Use an extremely formal corporate tone.",
"- Keep the content casual, mundane, and slightly nonsensical.",
"- Reflect the entity personality and task prompt faithfully.",
"- Output plain text only with no markdown fences."
).joinToString("\n")
}
}

View File

@@ -48,6 +48,10 @@ openai:
api-key: ${OPENAI_API_KEY}
model: ${OPENAI_MODEL:gpt-4o}
llama:
base-url: ${LLAMA_BASE_URL:http://localhost:11434}
model: ${LLAMA_MODEL:gemma3:4b}
springdoc:
swagger-ui:
path: /swagger-ui.html