# Route Spec

## Route ID
`posts-comments-create`

## Endpoint
`POST /api/v1/posts/{postId}/comments`

## Human Description
Creates a public comment on a post with text and optional image, optionally as a reply to an existing comment. Threads are one level deep. Hub-scoped discussion/chat is handled by hub discussion endpoints.

## Authentication
- Required: `yes`

## Request
### Headers
- `Content-Type: application/json`

### Body
```json
{
  "text": "I disagree because...",
  "assetId": "ast_optional_image",
  "parentCommentId": "cmt_optional_parent"
}
```

### Validation Rules
- At least one of `text` or `assetId` is required.
- `text`: max 2000 chars.
- `assetId`: optional, must be an owned completed `post_image` media/image asset.
- `parentCommentId`: optional, must reference an existing non-deleted comment on the same post; returns `COMMENT_NOT_FOUND` otherwise.
- Threads are one level deep. If `parentCommentId` points at a comment that is itself a reply, the new comment is attached to that thread's root comment.
- Viewer must be allowed to see the post. For `private_locked_hub`, the viewer must be the author or an active member of at least one selected hub.

## Responses
### Success: `201 Created`
```json
{"success": true, "message": "Comment created", "data": {"commentId": "cmt_1"}}
```

### Error: `401 Unauthorized`
When returned:
- Missing or invalid access token.

Body:
```json
{"success": false, "error": {"code": "UNAUTHORIZED", "message": "Authentication required.", "details": {}}}
```

### Error: `404 Not Found`
When returned:
- Post does not exist.
- Post is private locked hub content and the viewer is not the author or an active member of one selected hub.
- `parentCommentId` does not reference an existing comment on this post (`COMMENT_NOT_FOUND`).

Body:
```json
{"success": false, "error": {"code": "POST_NOT_FOUND", "message": "Post does not exist.", "details": {}}}
```

### Error: `422 Unprocessable Entity`
When returned:
- Invalid comment payload.

Body:
```json
{"success": false, "error": {"code": "VALIDATION_FAILED", "message": "Please fix highlighted fields.", "details": {}}}
```

## Data & Caching Dependencies
- **Spanner Tables:** `comments, post_feed_activity_events, notifications (Write), posts, post_hub_targets, hub_memberships (Read)`
- **Redis Cache:** `None`
- **GCS Storage:** `None`
- **Edge Cache (CDN):** `No`

## Side Effects
- Creates a public comment record under the target post.
- Increments post discussion/comment counters.
- Creates `post_commented` notification for the post owner when commenter is not the owner.
- Records a `post_commented` feed activity event for Home feed friend-interaction discovery.