fix: address PR review comments

- orderIndex in createMilestoneRequest changed to *int so explicit 0
  is distinguishable from an omitted field; inline milestone loop in
  Create handler falls back to slice position when nil
- overdueOnly filter now includes status='overdue' in the IN clause so
  items already persisted with that status are not silently excluded
- removed blank identifier var _ = relational.SystemSecurityPlan{} and
  the relational import from models.go (import only needed in service.go)
- added DB-level FK absence comments on all four link tables explaining
  the intentional cross-bounded-context design decision
- added SSP-scoped routes /system-security-plans/:sspId/poam-items via
  RegisterSSPScoped; List and Create handlers inject the path param into
  filters/body automatically so clients don't repeat the SSP ID
- regenerated Swagger docs

Author: AKAbdulHanif

docs/docs.go

@@ -25776,6 +25776,7 @@ const docTemplate = `{
                     "type": "string"
                 },
                 "orderIndex": {
+                    "description": "OrderIndex is a pointer so that clients can explicitly set 0 without it\nbeing indistinguishable from an omitted field.",
                     "type": "integer"
                 },
                 "scheduledCompletionDate": {

docs/swagger.json

@@ -25770,6 +25770,7 @@
                     "type": "string"
                 },
                 "orderIndex": {
+                    "description": "OrderIndex is a pointer so that clients can explicitly set 0 without it\nbeing indistinguishable from an omitted field.",
                     "type": "integer"
                 },
                 "scheduledCompletionDate": {

docs/swagger.yaml

@@ -1522,6 +1522,9 @@ definitions:
       description:
         type: string
       orderIndex:
+        description: |-
+          OrderIndex is a pointer so that clients can explicitly set 0 without it
+          being indistinguishable from an omitted field.
         type: integer
       scheduledCompletionDate:
         type: string

internal/api/handler/api.go

@@ -51,9 +51,15 @@ func RegisterHandlers(server *api.Server, logger *zap.SugaredLogger, db *gorm.DB
 
 	poamService := poamsvc.NewPoamService(db)
 	poamHandler := NewPoamItemsHandler(poamService, logger)
+	// Flat route: /api/poam-items (supports ?sspId= query filter)
 	poamGroup := server.API().Group("/poam-items")
 	poamGroup.Use(middleware.JWTMiddleware(config.JWTPublicKey))
 	poamHandler.Register(poamGroup)
+	// SSP-scoped route: /api/system-security-plans/:sspId/poam-items
+	// The :sspId path param is automatically injected into list/create filters.
+	sspPoamGroup := server.API().Group("/system-security-plans/:sspId/poam-items")
+	sspPoamGroup.Use(middleware.JWTMiddleware(config.JWTPublicKey))
+	poamHandler.RegisterSSPScoped(sspPoamGroup)
 
 	riskHandler := NewRiskHandler(logger, db)
 	riskGroup := server.API().Group("/risks")

internal/api/handler/poam_items.go

@@ -30,6 +30,17 @@ func NewPoamItemsHandler(svc *poamsvc.PoamService, sugar *zap.SugaredLogger) *Po
 // Register mounts all POAM routes onto the given Echo group. JWT middleware
 // is applied at the group level in api.go.
 func (h *PoamItemsHandler) Register(g *echo.Group) {
+	h.registerRoutes(g)
+}
+
+// RegisterSSPScoped mounts all POAM routes under an SSP-scoped group
+// (e.g. /system-security-plans/:sspId/poam-items). The :sspId path param is
+// extracted and injected into list/create filters automatically.
+func (h *PoamItemsHandler) RegisterSSPScoped(g *echo.Group) {
+	h.registerRoutes(g)
+}
+
+func (h *PoamItemsHandler) registerRoutes(g *echo.Group) {
 	g.GET("", h.List)
 	g.POST("", h.Create)
 	g.GET("/:id", h.Get)
@@ -102,7 +113,9 @@ type createMilestoneRequest struct {
 	Description             string     `json:"description"`
 	Status                  string     `json:"status"`
 	ScheduledCompletionDate *time.Time `json:"scheduledCompletionDate"`
-	OrderIndex              int        `json:"orderIndex"`
+	// OrderIndex is a pointer so that clients can explicitly set 0 without it
+	// being indistinguishable from an omitted field.
+	OrderIndex *int `json:"orderIndex"`
 }
 
 type updateMilestoneRequest struct {
@@ -276,6 +289,15 @@ func (h *PoamItemsHandler) List(c echo.Context) error {
 	if err != nil {
 		return c.JSON(http.StatusBadRequest, api.NewError(err))
 	}
+	// When mounted under /system-security-plans/:sspId/poam-items, the sspId
+	// path param takes precedence over the query parameter.
+	if sspIDParam := c.Param("sspId"); sspIDParam != "" {
+		parsed, err := uuid.Parse(sspIDParam)
+		if err != nil {
+			return c.JSON(http.StatusBadRequest, api.NewError(fmt.Errorf("sspId path param must be a valid UUID")))
+		}
+		filters.SspID = &parsed
+	}
 	items, err := h.poamService.List(filters)
 	if err != nil {
 		return h.internalError(c, "failed to list poam items", err)
@@ -305,10 +327,14 @@ func (h *PoamItemsHandler) Create(c echo.Context) error {
 	if err := c.Bind(&in); err != nil {
 		return c.JSON(http.StatusBadRequest, api.NewError(err))
 	}
+	// When mounted under /system-security-plans/:sspId/poam-items, the sspId
+	// path param overrides the body field so the client doesn't have to repeat it.
+	if sspIDParam := c.Param("sspId"); sspIDParam != "" {
+		in.SspID = sspIDParam
+	}
 	if err := c.Validate(&in); err != nil {
 		return c.JSON(http.StatusBadRequest, api.NewError(err))
 	}
-
 	sspID, err := uuid.Parse(in.SspID)
 	if err != nil {
 		return c.JSON(http.StatusBadRequest, api.NewError(fmt.Errorf("sspId must be a valid UUID")))
@@ -376,19 +402,25 @@ func (h *PoamItemsHandler) Create(c echo.Context) error {
 	}
 	params.ControlRefs = controlRefs
 
-	for _, mr := range in.Milestones {
+	for i, mr := range in.Milestones {
 		if mr.Title == "" {
 			return c.JSON(http.StatusBadRequest, api.NewError(fmt.Errorf("milestone title is required")))
 		}
 		if mr.Status != "" && !poamsvc.MilestoneStatus(mr.Status).IsValid() {
 			return c.JSON(http.StatusBadRequest, api.NewError(fmt.Errorf("invalid milestone status: %s", mr.Status)))
 		}
+		// When orderIndex is omitted (nil), fall back to the slice position so
+		// ordering is still deterministic without requiring the client to set it.
+		msOrderIdx := i
+		if mr.OrderIndex != nil {
+			msOrderIdx = *mr.OrderIndex
+		}
 		params.Milestones = append(params.Milestones, poamsvc.CreateMilestoneParams{
 			Title:                   mr.Title,
 			Description:             mr.Description,
 			Status:                  mr.Status,
 			ScheduledCompletionDate: mr.ScheduledCompletionDate,
-			OrderIndex:              mr.OrderIndex,
+			OrderIndex:              msOrderIdx,
 		})
 	}
 
@@ -626,12 +658,16 @@ func (h *PoamItemsHandler) AddMilestone(c echo.Context) error {
 	if in.Status != "" && !poamsvc.MilestoneStatus(in.Status).IsValid() {
 		return c.JSON(http.StatusBadRequest, api.NewError(fmt.Errorf("invalid milestone status: %s", in.Status)))
 	}
+	var orderIdx int
+	if in.OrderIndex != nil {
+		orderIdx = *in.OrderIndex
+	}
 	m, err := h.poamService.AddMilestone(id, poamsvc.CreateMilestoneParams{
 		Title:                   in.Title,
 		Description:             in.Description,
 		Status:                  in.Status,
 		ScheduledCompletionDate: in.ScheduledCompletionDate,
-		OrderIndex:              in.OrderIndex,
+		OrderIndex:              orderIdx,
 	})
 	if err != nil {
 		return h.internalError(c, "failed to add milestone", err)

internal/api/handler/poam_items_integration_test.go

@@ -64,6 +64,9 @@ func (suite *PoamItemsApiIntegrationSuite) authedReq(method, path string, body [
 	return rec, req
 }
 
+// intPtr is a convenience helper that returns a pointer to an int literal.
+func intPtr(i int) *int { return &i }
+
 // ensureSSP seeds a SystemSecurityPlan row so that the Create handler's
 // EnsureSSPExists check passes. The SSP record only needs an ID.
 func (suite *PoamItemsApiIntegrationSuite) ensureSSP(id uuid.UUID) {
@@ -137,8 +140,8 @@ func (suite *PoamItemsApiIntegrationSuite) TestCreate_WithMilestonesAndLinks() {
 		Status:      "open",
 		SourceType:  "risk-promotion",
 		Milestones: []createMilestoneRequest{
-			{Title: "Patch staging", Status: "planned", ScheduledCompletionDate: &due, OrderIndex: 0},
-			{Title: "Patch production", Status: "planned", OrderIndex: 1},
+			{Title: "Patch staging", Status: "planned", ScheduledCompletionDate: &due, OrderIndex: intPtr(0)},
+			{Title: "Patch production", Status: "planned", OrderIndex: intPtr(1)},
 		},
 	}
 	raw, _ := json.Marshal(body)
@@ -578,7 +581,7 @@ func (suite *PoamItemsApiIntegrationSuite) TestAddMilestone() {
 		Description:             "Deploy patched version to staging",
 		Status:                  "planned",
 		ScheduledCompletionDate: &due,
-		OrderIndex:              0,
+		OrderIndex:              intPtr(0),
 	}
 	raw, _ := json.Marshal(body)
 	rec, req := suite.authedReq(http.MethodPost, fmt.Sprintf("/api/poam-items/%s/milestones", item.ID), raw)

internal/service/relational/poam/models.go

@@ -4,7 +4,6 @@ import (
 	"fmt"
 	"time"
 
-	"github.com/compliance-framework/api/internal/service/relational"
 	"github.com/google/uuid"
 	"gorm.io/gorm"
 )
@@ -150,6 +149,11 @@ func (m *PoamItemMilestone) BeforeCreate(_ *gorm.DB) error {
 // PoamItemRiskLink is the join table linking PoamItems to Risks.
 // Uses a composite primary key and OnDelete:CASCADE to match the Risk service
 // link table pattern (e.g., risk_evidence_links).
+//
+// Note: only the PoamItem side carries a DB-level FK constraint. The RiskID
+// column intentionally has no FK back to the risks table because Risks live in
+// a separate bounded context. Referential integrity on the Risk side is
+// enforced at the application layer (EnsureExists checks before link creation).
 type PoamItemRiskLink struct {
 	PoamItemID uuid.UUID `gorm:"type:uuid;primaryKey"       json:"poamItemId"`
 	RiskID     uuid.UUID `gorm:"type:uuid;primaryKey;index" json:"riskId"`
@@ -161,6 +165,7 @@ type PoamItemRiskLink struct {
 func (PoamItemRiskLink) TableName() string { return "ccf_poam_item_risk_links" }
 
 // PoamItemEvidenceLink is the join table linking PoamItems to Evidence records.
+// EvidenceID has no DB-level FK (same cross-context reasoning as PoamItemRiskLink).
 type PoamItemEvidenceLink struct {
 	PoamItemID uuid.UUID `gorm:"type:uuid;primaryKey"       json:"poamItemId"`
 	EvidenceID uuid.UUID `gorm:"type:uuid;primaryKey;index" json:"evidenceId"`
@@ -172,6 +177,7 @@ type PoamItemEvidenceLink struct {
 func (PoamItemEvidenceLink) TableName() string { return "ccf_poam_item_evidence_links" }
 
 // PoamItemControlLink is the join table linking PoamItems to Controls.
+// CatalogID/ControlID have no DB-level FK (same cross-context reasoning as PoamItemRiskLink).
 type PoamItemControlLink struct {
 	PoamItemID uuid.UUID `gorm:"type:uuid;primaryKey"             json:"poamItemId"`
 	CatalogID  uuid.UUID `gorm:"type:uuid;primaryKey;index"       json:"catalogId"`
@@ -184,6 +190,7 @@ type PoamItemControlLink struct {
 func (PoamItemControlLink) TableName() string { return "ccf_poam_item_control_links" }
 
 // PoamItemFindingLink is the join table linking PoamItems to Findings.
+// FindingID has no DB-level FK (same cross-context reasoning as PoamItemRiskLink).
 type PoamItemFindingLink struct {
 	PoamItemID uuid.UUID `gorm:"type:uuid;primaryKey"       json:"poamItemId"`
 	FindingID  uuid.UUID `gorm:"type:uuid;primaryKey;index" json:"findingId"`
@@ -199,6 +206,3 @@ type ControlRef struct {
 	CatalogID uuid.UUID `json:"catalogId"`
 	ControlID string    `json:"controlId"`
 }
-
-// Ensure the relational package is imported (used for SSP existence checks in the service).
-var _ = relational.SystemSecurityPlan{}

internal/service/relational/poam/queries.go

@@ -39,7 +39,9 @@ func ApplyFilters(query *gorm.DB, filters ListFilters) *gorm.DB {
 	if filters.OverdueOnly {
 		now := time.Now().UTC()
 		q = q.Where(
-			"ccf_poam_items.status IN ('open','in-progress') AND ccf_poam_items.planned_completion_date IS NOT NULL AND ccf_poam_items.planned_completion_date < ?",
+			// Include 'overdue' in the filter so that items already persisted with
+			// that status (a valid PoamItemStatus) are not silently excluded.
+			"ccf_poam_items.status IN ('open','in-progress','overdue') AND ccf_poam_items.planned_completion_date IS NOT NULL AND ccf_poam_items.planned_completion_date < ?",
 			now,
 		)
 	}