# Item Comment

## Overview

Provides a chronological discussion thread on each item. Users can post, edit, and delete comments scoped to a single item. The feature is intentionally generic — visibility rules (internal-only vs externally visible, role-based filtering) are deferred to consuming domain modules that can extend PipelineItemComment with their own metadata via foreign key.

## Business Purpose

- Enable team discussion on individual items without leaving the pipeline view
- Provide an auditable record of human input on each item
- Serve as the substrate that domain modules extend with visibility, attachments, or other concerns

## Process Flow

```mermaid
flowchart TD
    A[User opens an item] --> B[User writes comment body]
    B --> C[CreatePipelineItemComment]
    C --> D[Comment persisted with createdAt]
    D --> E[Comment appears in item's chronological feed]
    E --> F{Author edits?}
    F -->|Yes| G[UpdatePipelineItemComment — body and updatedAt change]
    G --> E
    F -->|No| H{Author deletes?}
    H -->|Yes| I[DeletePipelineItemComment — comment removed from feed]
    H -->|No| E
```

## Scenario Patterns

- A team member posts a stage update on an item that other collaborators see in chronological order
- The author edits their own comment to fix a typo
- The author deletes a comment they posted by mistake
- A consuming domain module layers visibility metadata on top of PipelineItemComment to filter what external users see through a portal

## Test Cases

- Creating a comment with a valid body and existing item succeeds
- Creating a comment with an empty body is rejected
- Creating a comment on a non-existent item is rejected
- `createdAt` is set automatically at creation time
- Listing comments for an item returns them in `createdAt` ascending order
- An author can update the body of their own comment, and `updatedAt` advances
- A non-author cannot update another user's comment
- An author can delete their own comment, and it disappears from subsequent listings
- A non-author cannot delete another user's comment

## Reference Links

- [Linear Conceptual Model — Comments](https://linear.app/docs/conceptual-model)