first commit

2026-06-03 16:31:42 -03:00
commit 8c7e5fbbe4
92 changed files with 18226 additions and 0 deletions
--- a/backend/internal/calendar/routes.go
+++ b/backend/internal/calendar/routes.go
@@ -0,0 +1,740 @@
+package calendar
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"errors"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+
+	"mira/backend/internal/auth"
+	"mira/backend/internal/users"
+
+	"github.com/gin-gonic/gin"
+)
+
+type Routes struct {
+	store              Store
+	provider           Provider
+	commemorative      CommemorativeProvider
+	uploadMaxSizeBytes int64
+	uploadAllowedMIMEs map[string]bool
+	storageDriver      string
+	storageLocalPath   string
+}
+
+type RouteOptions struct {
+	UploadMaxSizeMB    int
+	UploadAllowedMIMEs []string
+	StorageDriver      string
+	StorageLocalPath   string
+}
+
+func NewRoutes(store Store, provider Provider, commemorative CommemorativeProvider, options RouteOptions) Routes {
+	allowedMIMEs := make(map[string]bool, len(options.UploadAllowedMIMEs))
+	for _, mime := range options.UploadAllowedMIMEs {
+		allowedMIMEs[strings.TrimSpace(mime)] = true
+	}
+	if options.UploadMaxSizeMB <= 0 {
+		options.UploadMaxSizeMB = 10
+	}
+	if options.StorageDriver == "" {
+		options.StorageDriver = "local"
+	}
+	if options.StorageLocalPath == "" {
+		options.StorageLocalPath = "/var/lib/mira/uploads"
+	}
+
+	return Routes{
+		store:              store,
+		provider:           provider,
+		commemorative:      commemorative,
+		uploadMaxSizeBytes: int64(options.UploadMaxSizeMB) * 1024 * 1024,
+		uploadAllowedMIMEs: allowedMIMEs,
+		storageDriver:      options.StorageDriver,
+		storageLocalPath:   options.StorageLocalPath,
+	}
+}
+
+func (r Routes) Register(router *gin.RouterGroup, requireAuth gin.HandlerFunc) {
+	router.Use(requireAuth)
+
+	router.GET("/week", func(c *gin.Context) {
+		c.JSON(http.StatusNotImplemented, gin.H{"message": "Dashboard semanal ainda nao implementado."})
+	})
+
+	router.GET("/holidays", r.holidays)
+	router.GET("/custom-dates", r.customDates)
+	router.POST("/custom-dates", r.createCustomDate)
+	router.PATCH("/custom-dates/:customDateId", r.updateCustomDate)
+	router.DELETE("/custom-dates/:customDateId", r.deleteCustomDate)
+	router.GET("/items", r.calendarItems)
+	router.POST("/items", r.createCalendarItem)
+	router.GET("/items/:itemId", r.getCalendarItem)
+	router.PATCH("/items/:itemId", r.updateCalendarItem)
+	router.DELETE("/items/:itemId", r.cancelCalendarItem)
+	router.GET("/items/:itemId/attachments", r.listAttachments)
+	router.POST("/items/:itemId/attachments", r.uploadAttachment)
+	router.GET("/attachments/:attachmentId/download", r.downloadAttachment)
+}
+
+func (r Routes) holidays(c *gin.Context) {
+	year := time.Now().Year()
+	if value := c.Query("year"); value != "" {
+		parsed, err := strconv.Atoi(value)
+		if err != nil || parsed < 1900 || parsed > 2199 {
+			c.JSON(http.StatusBadRequest, gin.H{"message": "Ano invalido."})
+			return
+		}
+		year = parsed
+	}
+
+	holidays, err := r.store.ListHolidaysByYear(c.Request.Context(), year)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel carregar feriados."})
+		return
+	}
+
+	if len(holidays) == 0 {
+		imported, err := r.provider.NationalHolidays(c.Request.Context(), year)
+		if err != nil {
+			c.JSON(http.StatusBadGateway, gin.H{"message": "Nao foi possivel consultar os feriados nacionais."})
+			return
+		}
+
+		if err := r.store.UpsertHolidays(c.Request.Context(), "brasilapi", imported); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel salvar feriados."})
+			return
+		}
+
+		holidays, err = r.store.ListHolidaysByYear(c.Request.Context(), year)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel carregar feriados."})
+			return
+		}
+	}
+
+	c.JSON(http.StatusOK, gin.H{"holidays": holidays})
+}
+
+func (r Routes) customDates(c *gin.Context) {
+	claims, ok := auth.ClaimsFromContext(c)
+	if !ok {
+		c.JSON(http.StatusUnauthorized, gin.H{"message": "Autenticacao obrigatoria."})
+		return
+	}
+
+	year := time.Now().Year()
+	if value := c.Query("year"); value != "" {
+		parsed, err := strconv.Atoi(value)
+		if err != nil || parsed < 1900 || parsed > 2199 {
+			c.JSON(http.StatusBadRequest, gin.H{"message": "Ano invalido."})
+			return
+		}
+		year = parsed
+	}
+
+	viewerUserID := ""
+	if claims.Role == users.RoleClientViewer {
+		viewerUserID = claims.UserID
+	}
+
+	if r.commemorative != nil {
+		initialDates, err := r.store.ListCustomDatesByYear(c.Request.Context(), year, "", viewerUserID)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel carregar datas personalizadas."})
+			return
+		}
+		hasImported := false
+		for _, date := range initialDates {
+			if date.Category == "feriados-brasil" {
+				hasImported = true
+				break
+			}
+		}
+		if !hasImported {
+			imported, err := r.commemorative.CommemorativeDates(c.Request.Context(), year)
+			if err == nil && len(imported) > 0 {
+				_ = r.store.UpsertExternalCommemorativeDates(c.Request.Context(), imported)
+			}
+		}
+	}
+
+	dates, err := r.store.ListCustomDatesByYear(c.Request.Context(), year, c.Query("client_id"), viewerUserID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel carregar datas personalizadas."})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"custom_dates": dates})
+}
+
+type createCustomDateRequest struct {
+	ClientID       string `json:"client_id"`
+	Name           string `json:"name" binding:"required,min=2"`
+	Description    string `json:"description"`
+	Date           string `json:"date" binding:"required"`
+	RecursAnnually bool   `json:"recurs_annually"`
+	Visibility     string `json:"visibility"`
+	Category       string `json:"category"`
+}
+
+func (r Routes) createCustomDate(c *gin.Context) {
+	claims, ok := auth.ClaimsFromContext(c)
+	if !ok || (claims.Role != users.RoleSuperAdmin && claims.Role != users.RoleAgencyUser) {
+		c.JSON(http.StatusForbidden, gin.H{"message": "Permissao insuficiente."})
+		return
+	}
+
+	var input createCustomDateRequest
+	if err := c.ShouldBindJSON(&input); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"message": "Informe os dados da data personalizada."})
+		return
+	}
+
+	if _, err := time.Parse("2006-01-02", input.Date); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"message": "Data invalida. Use o formato YYYY-MM-DD."})
+		return
+	}
+
+	visibility := strings.TrimSpace(input.Visibility)
+	if visibility == "" {
+		visibility = "agency"
+	}
+	if visibility != "agency" && visibility != "client" {
+		c.JSON(http.StatusBadRequest, gin.H{"message": "Visibilidade invalida."})
+		return
+	}
+
+	category := strings.TrimSpace(input.Category)
+	if category == "" {
+		category = "custom"
+	}
+
+	date, err := r.store.CreateCustomDate(c.Request.Context(), CreateCustomDateInput{
+		ClientID:       strings.TrimSpace(input.ClientID),
+		Name:           strings.TrimSpace(input.Name),
+		Description:    strings.TrimSpace(input.Description),
+		Date:           input.Date,
+		RecursAnnually: input.RecursAnnually,
+		Visibility:     visibility,
+		Category:       category,
+		CreatedBy:      claims.UserID,
+	})
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel criar a data personalizada."})
+		return
+	}
+
+	_ = r.store.RecordAudit(c.Request.Context(), claims.UserID, "custom_date.created", "commemorative_date", date.ID, map[string]any{
+		"name":      date.Name,
+		"client_id": date.ClientID,
+	})
+
+	c.JSON(http.StatusCreated, gin.H{"custom_date": date})
+}
+
+type updateCustomDateRequest struct {
+	ClientID       string `json:"client_id"`
+	Name           string `json:"name" binding:"required,min=2"`
+	Description    string `json:"description"`
+	Date           string `json:"date" binding:"required"`
+	RecursAnnually bool   `json:"recurs_annually"`
+	Visibility     string `json:"visibility"`
+}
+
+func (r Routes) updateCustomDate(c *gin.Context) {
+	claims, ok := auth.ClaimsFromContext(c)
+	if !ok || (claims.Role != users.RoleSuperAdmin && claims.Role != users.RoleAgencyUser) {
+		c.JSON(http.StatusForbidden, gin.H{"message": "Permissao insuficiente."})
+		return
+	}
+
+	var input updateCustomDateRequest
+	if err := c.ShouldBindJSON(&input); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"message": "Informe os dados da data personalizada."})
+		return
+	}
+
+	if _, err := time.Parse("2006-01-02", input.Date); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"message": "Data invalida. Use o formato YYYY-MM-DD."})
+		return
+	}
+
+	visibility := strings.TrimSpace(input.Visibility)
+	if visibility == "" {
+		visibility = "agency"
+	}
+	if visibility != "agency" && visibility != "client" {
+		c.JSON(http.StatusBadRequest, gin.H{"message": "Visibilidade invalida."})
+		return
+	}
+
+	date, err := r.store.UpdateCustomDate(c.Request.Context(), UpdateCustomDateInput{
+		ID:             c.Param("customDateId"),
+		ClientID:       strings.TrimSpace(input.ClientID),
+		Name:           strings.TrimSpace(input.Name),
+		Description:    strings.TrimSpace(input.Description),
+		Date:           input.Date,
+		RecursAnnually: input.RecursAnnually,
+		Visibility:     visibility,
+	})
+	if errors.Is(err, ErrCustomDateNotFound) {
+		c.JSON(http.StatusNotFound, gin.H{"message": "Data personalizada nao encontrada."})
+		return
+	}
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel atualizar a data personalizada."})
+		return
+	}
+
+	_ = r.store.RecordAudit(c.Request.Context(), claims.UserID, "custom_date.updated", "commemorative_date", date.ID, map[string]any{
+		"name":      date.Name,
+		"client_id": date.ClientID,
+	})
+
+	c.JSON(http.StatusOK, gin.H{"custom_date": date})
+}
+
+func (r Routes) deleteCustomDate(c *gin.Context) {
+	claims, ok := auth.ClaimsFromContext(c)
+	if !ok || (claims.Role != users.RoleSuperAdmin && claims.Role != users.RoleAgencyUser) {
+		c.JSON(http.StatusForbidden, gin.H{"message": "Permissao insuficiente."})
+		return
+	}
+
+	err := r.store.DeleteCustomDate(c.Request.Context(), c.Param("customDateId"))
+	if errors.Is(err, ErrCustomDateNotFound) {
+		c.JSON(http.StatusNotFound, gin.H{"message": "Data personalizada nao encontrada."})
+		return
+	}
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel excluir a data personalizada."})
+		return
+	}
+
+	_ = r.store.RecordAudit(c.Request.Context(), claims.UserID, "custom_date.deleted", "commemorative_date", c.Param("customDateId"), nil)
+	c.JSON(http.StatusOK, gin.H{"message": "Data personalizada excluida."})
+}
+
+func (r Routes) calendarItems(c *gin.Context) {
+	claims, ok := auth.ClaimsFromContext(c)
+	if !ok {
+		c.JSON(http.StatusUnauthorized, gin.H{"message": "Autenticacao obrigatoria."})
+		return
+	}
+
+	from := strings.TrimSpace(c.Query("from"))
+	to := strings.TrimSpace(c.Query("to"))
+
+	if from == "" || to == "" {
+		year := time.Now().Year()
+		if value := c.Query("year"); value != "" {
+			parsed, err := strconv.Atoi(value)
+			if err != nil || parsed < 1900 || parsed > 2199 {
+				c.JSON(http.StatusBadRequest, gin.H{"message": "Ano invalido."})
+				return
+			}
+			year = parsed
+		}
+
+		from = time.Date(year, 1, 1, 0, 0, 0, 0, time.UTC).Format("2006-01-02")
+		to = time.Date(year, 12, 31, 0, 0, 0, 0, time.UTC).Format("2006-01-02")
+	}
+
+	if _, err := time.Parse("2006-01-02", from); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"message": "Data inicial invalida. Use o formato YYYY-MM-DD."})
+		return
+	}
+	if _, err := time.Parse("2006-01-02", to); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"message": "Data final invalida. Use o formato YYYY-MM-DD."})
+		return
+	}
+
+	viewerUserID := ""
+	if claims.Role == users.RoleClientViewer {
+		viewerUserID = claims.UserID
+	}
+
+	items, err := r.store.ListCalendarItems(c.Request.Context(), ListCalendarItemsFilter{
+		ClientID:     strings.TrimSpace(c.Query("client_id")),
+		ViewerUserID: viewerUserID,
+		From:         from,
+		To:           to,
+	})
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel carregar postagens."})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"items": items})
+}
+
+type createCalendarItemRequest struct {
+	ClientID      string `json:"client_id" binding:"required"`
+	Title         string `json:"title" binding:"required,min=2"`
+	Description   string `json:"description"`
+	ContentType   string `json:"content_type"`
+	Status        string `json:"status"`
+	ScheduledDate string `json:"scheduled_date" binding:"required"`
+	CopyText      string `json:"copy_text"`
+	InternalNotes string `json:"internal_notes"`
+	ClientNotes   string `json:"client_notes"`
+}
+
+func (r Routes) createCalendarItem(c *gin.Context) {
+	claims, ok := auth.ClaimsFromContext(c)
+	if !ok || (claims.Role != users.RoleSuperAdmin && claims.Role != users.RoleAgencyUser) {
+		c.JSON(http.StatusForbidden, gin.H{"message": "Permissao insuficiente."})
+		return
+	}
+
+	var input createCalendarItemRequest
+	if err := c.ShouldBindJSON(&input); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"message": "Informe os dados da postagem."})
+		return
+	}
+
+	if _, err := time.Parse("2006-01-02", input.ScheduledDate); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"message": "Data invalida. Use o formato YYYY-MM-DD."})
+		return
+	}
+
+	contentType := strings.TrimSpace(input.ContentType)
+	if contentType == "" {
+		contentType = "post"
+	}
+
+	status := strings.TrimSpace(input.Status)
+	if status == "" {
+		status = "rascunho"
+	}
+	if !isValidCalendarItemStatus(status) {
+		c.JSON(http.StatusBadRequest, gin.H{"message": "Status invalido."})
+		return
+	}
+
+	item, err := r.store.CreateCalendarItem(c.Request.Context(), CreateCalendarItemInput{
+		ClientID:      strings.TrimSpace(input.ClientID),
+		Title:         strings.TrimSpace(input.Title),
+		Description:   strings.TrimSpace(input.Description),
+		ContentType:   contentType,
+		Status:        status,
+		ScheduledDate: input.ScheduledDate,
+		CopyText:      strings.TrimSpace(input.CopyText),
+		InternalNotes: strings.TrimSpace(input.InternalNotes),
+		ClientNotes:   strings.TrimSpace(input.ClientNotes),
+		CreatedBy:     claims.UserID,
+	})
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel criar a postagem."})
+		return
+	}
+
+	_ = r.store.RecordAudit(c.Request.Context(), claims.UserID, "calendar_item.created", "calendar_item", item.ID, map[string]any{
+		"title":     item.Title,
+		"client_id": item.ClientID,
+		"status":    item.Status,
+	})
+
+	c.JSON(http.StatusCreated, gin.H{"item": item})
+}
+
+func (r Routes) getCalendarItem(c *gin.Context) {
+	claims, ok := auth.ClaimsFromContext(c)
+	if !ok {
+		c.JSON(http.StatusUnauthorized, gin.H{"message": "Autenticacao obrigatoria."})
+		return
+	}
+
+	viewerUserID := ""
+	if claims.Role == users.RoleClientViewer {
+		viewerUserID = claims.UserID
+	}
+
+	item, err := r.store.FindCalendarItem(c.Request.Context(), c.Param("itemId"), viewerUserID)
+	if errors.Is(err, ErrCalendarItemNotFound) {
+		c.JSON(http.StatusNotFound, gin.H{"message": "Postagem nao encontrada."})
+		return
+	}
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel carregar a postagem."})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"item": item})
+}
+
+type updateCalendarItemRequest struct {
+	Title         *string `json:"title"`
+	Description   *string `json:"description"`
+	Status        *string `json:"status"`
+	ScheduledDate *string `json:"scheduled_date"`
+	CopyText      *string `json:"copy_text"`
+	InternalNotes *string `json:"internal_notes"`
+	ClientNotes   *string `json:"client_notes"`
+}
+
+func (r Routes) updateCalendarItem(c *gin.Context) {
+	claims, ok := auth.ClaimsFromContext(c)
+	if !ok || (claims.Role != users.RoleSuperAdmin && claims.Role != users.RoleAgencyUser) {
+		c.JSON(http.StatusForbidden, gin.H{"message": "Permissao insuficiente."})
+		return
+	}
+
+	var input updateCalendarItemRequest
+	if err := c.ShouldBindJSON(&input); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"message": "Dados invalidos."})
+		return
+	}
+
+	update := UpdateCalendarItemInput{ID: c.Param("itemId")}
+	if input.Title != nil {
+		update.UpdateTitle = true
+		update.Title = strings.TrimSpace(*input.Title)
+		if update.Title == "" {
+			c.JSON(http.StatusBadRequest, gin.H{"message": "Titulo invalido."})
+			return
+		}
+	}
+	if input.Description != nil {
+		update.UpdateDescription = true
+		update.Description = strings.TrimSpace(*input.Description)
+	}
+	if input.Status != nil {
+		update.UpdateStatus = true
+		update.Status = strings.TrimSpace(*input.Status)
+		if !isValidCalendarItemStatus(update.Status) {
+			c.JSON(http.StatusBadRequest, gin.H{"message": "Status invalido."})
+			return
+		}
+	}
+	if input.ScheduledDate != nil {
+		update.UpdateScheduledDate = true
+		update.ScheduledDate = strings.TrimSpace(*input.ScheduledDate)
+		if _, err := time.Parse("2006-01-02", update.ScheduledDate); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"message": "Data invalida. Use o formato YYYY-MM-DD."})
+			return
+		}
+	}
+	if input.CopyText != nil {
+		update.UpdateCopyText = true
+		update.CopyText = strings.TrimSpace(*input.CopyText)
+	}
+	if input.InternalNotes != nil {
+		update.UpdateInternalNotes = true
+		update.InternalNotes = strings.TrimSpace(*input.InternalNotes)
+	}
+	if input.ClientNotes != nil {
+		update.UpdateClientNotes = true
+		update.ClientNotes = strings.TrimSpace(*input.ClientNotes)
+	}
+
+	item, err := r.store.UpdateCalendarItem(c.Request.Context(), update)
+	if errors.Is(err, ErrCalendarItemNotFound) {
+		c.JSON(http.StatusNotFound, gin.H{"message": "Postagem nao encontrada."})
+		return
+	}
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel atualizar a postagem."})
+		return
+	}
+
+	_ = r.store.RecordAudit(c.Request.Context(), claims.UserID, "calendar_item.updated", "calendar_item", item.ID, map[string]any{
+		"title":  item.Title,
+		"status": item.Status,
+	})
+
+	c.JSON(http.StatusOK, gin.H{"item": item})
+}
+
+func (r Routes) cancelCalendarItem(c *gin.Context) {
+	claims, ok := auth.ClaimsFromContext(c)
+	if !ok || (claims.Role != users.RoleSuperAdmin && claims.Role != users.RoleAgencyUser) {
+		c.JSON(http.StatusForbidden, gin.H{"message": "Permissao insuficiente."})
+		return
+	}
+
+	item, err := r.store.FindCalendarItem(c.Request.Context(), c.Param("itemId"), "")
+	if errors.Is(err, ErrCalendarItemNotFound) {
+		c.JSON(http.StatusNotFound, gin.H{"message": "Postagem nao encontrada."})
+		return
+	}
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel carregar a postagem."})
+		return
+	}
+
+	if err := r.store.DeleteCalendarItem(c.Request.Context(), item.ID); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel excluir a postagem."})
+		return
+	}
+
+	_ = r.store.RecordAudit(c.Request.Context(), claims.UserID, "calendar_item.deleted", "calendar_item", item.ID, map[string]any{
+		"title":  item.Title,
+		"status": item.Status,
+	})
+
+	c.JSON(http.StatusOK, gin.H{"message": "Postagem excluida."})
+}
+
+func (r Routes) listAttachments(c *gin.Context) {
+	claims, ok := auth.ClaimsFromContext(c)
+	if !ok {
+		c.JSON(http.StatusUnauthorized, gin.H{"message": "Autenticacao obrigatoria."})
+		return
+	}
+
+	viewerUserID := ""
+	if claims.Role == users.RoleClientViewer {
+		viewerUserID = claims.UserID
+	}
+
+	attachments, err := r.store.ListAttachments(c.Request.Context(), c.Param("itemId"), viewerUserID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel carregar anexos."})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"attachments": attachments})
+}
+
+func (r Routes) uploadAttachment(c *gin.Context) {
+	claims, ok := auth.ClaimsFromContext(c)
+	if !ok || (claims.Role != users.RoleSuperAdmin && claims.Role != users.RoleAgencyUser) {
+		c.JSON(http.StatusForbidden, gin.H{"message": "Permissao insuficiente."})
+		return
+	}
+
+	c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, r.uploadMaxSizeBytes)
+	file, header, err := c.Request.FormFile("file")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"message": "Envie um arquivo valido."})
+		return
+	}
+	defer file.Close()
+
+	if header.Size > r.uploadMaxSizeBytes {
+		c.JSON(http.StatusBadRequest, gin.H{"message": "Arquivo acima do limite permitido."})
+		return
+	}
+
+	head := make([]byte, 512)
+	n, err := file.Read(head)
+	if err != nil && err != io.EOF {
+		c.JSON(http.StatusBadRequest, gin.H{"message": "Nao foi possivel ler o arquivo."})
+		return
+	}
+	if _, err := file.Seek(0, io.SeekStart); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel processar o arquivo."})
+		return
+	}
+
+	mimeType := http.DetectContentType(head[:n])
+	if len(r.uploadAllowedMIMEs) > 0 && !r.uploadAllowedMIMEs[mimeType] {
+		c.JSON(http.StatusBadRequest, gin.H{"message": "Tipo de arquivo nao permitido."})
+		return
+	}
+
+	storedFilename, err := randomStoredFilename(header.Filename)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel preparar o arquivo."})
+		return
+	}
+
+	itemDir := filepath.Join(r.storageLocalPath, c.Param("itemId"))
+	if err := os.MkdirAll(itemDir, 0o750); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel preparar o armazenamento."})
+		return
+	}
+
+	storagePath := filepath.Join(itemDir, storedFilename)
+	destination, err := os.OpenFile(storagePath, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o640)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel salvar o arquivo."})
+		return
+	}
+	defer destination.Close()
+
+	sizeBytes, err := io.Copy(destination, file)
+	if err != nil {
+		_ = os.Remove(storagePath)
+		c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel salvar o arquivo."})
+		return
+	}
+
+	attachment, err := r.store.CreateAttachment(c.Request.Context(), CreateAttachmentInput{
+		CalendarItemID:   c.Param("itemId"),
+		OriginalFilename: filepath.Base(header.Filename),
+		StoredFilename:   storedFilename,
+		MimeType:         mimeType,
+		SizeBytes:        sizeBytes,
+		StorageDriver:    r.storageDriver,
+		StoragePath:      storagePath,
+		CreatedBy:        claims.UserID,
+	})
+	if err != nil {
+		_ = os.Remove(storagePath)
+		c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel registrar o anexo."})
+		return
+	}
+
+	_ = r.store.RecordAudit(c.Request.Context(), claims.UserID, "attachment.created", "calendar_item_attachment", attachment.ID, map[string]any{
+		"calendar_item_id": attachment.CalendarItemID,
+		"filename":         attachment.OriginalFilename,
+		"mime_type":        attachment.MimeType,
+		"size_bytes":       attachment.SizeBytes,
+	})
+
+	c.JSON(http.StatusCreated, gin.H{"attachment": attachment})
+}
+
+func (r Routes) downloadAttachment(c *gin.Context) {
+	claims, ok := auth.ClaimsFromContext(c)
+	if !ok {
+		c.JSON(http.StatusUnauthorized, gin.H{"message": "Autenticacao obrigatoria."})
+		return
+	}
+
+	viewerUserID := ""
+	if claims.Role == users.RoleClientViewer {
+		viewerUserID = claims.UserID
+	}
+
+	attachment, err := r.store.FindAttachment(c.Request.Context(), c.Param("attachmentId"), viewerUserID)
+	if errors.Is(err, ErrAttachmentNotFound) {
+		c.JSON(http.StatusNotFound, gin.H{"message": "Anexo nao encontrado."})
+		return
+	}
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"message": "Nao foi possivel carregar o anexo."})
+		return
+	}
+
+	c.Header("Content-Type", attachment.MimeType)
+	c.Header("Content-Disposition", `attachment; filename="`+strings.ReplaceAll(attachment.OriginalFilename, `"`, "")+`"`)
+	c.File(attachment.StoragePath)
+}
+
+func randomStoredFilename(original string) (string, error) {
+	bytes := make([]byte, 16)
+	if _, err := rand.Read(bytes); err != nil {
+		return "", err
+	}
+	extension := strings.ToLower(filepath.Ext(original))
+	return hex.EncodeToString(bytes) + extension, nil
+}
+
+func isValidCalendarItemStatus(status string) bool {
+	switch status {
+	case "rascunho", "planejado", "em_producao", "em_revisao", "aprovado", "publicado", "cancelado":
+		return true
+	default:
+		return false
+	}
+}