build: /spec-feature add-hello-endpoint

.sdlc/features/add-hello-endpoint/spec.md

@@ -0,0 +1,60 @@
+# Feature: Add /hello endpoint to API service
+
+## Problem Statement
+
+The API service currently lacks a simple, unauthenticated endpoint that can be used for:
+1. Basic connectivity testing by clients during development and debugging
+2. Quick verification that the API is reachable and responding correctly
+3. A minimal example endpoint for onboarding new developers to the codebase patterns
+
+While `/api/v1/health` exists, it is designed for infrastructure health checks (liveness/readiness probes) rather than application-level connectivity testing by end users or client applications.
+
+## User Stories
+
+- As a **frontend developer**, I want a simple `/hello` endpoint so that I can quickly verify my client is correctly configured to call the API
+- As a **new team member**, I want to see a minimal handler implementation so that I can understand the codebase patterns before building more complex endpoints
+- As a **QA engineer**, I want a simple endpoint that returns predictable data so that I can use it in integration test smoke checks
+
+## Acceptance Criteria
+
+- [ ] `GET /api/v1/hello` returns HTTP 200 with a JSON response
+- [ ] Response body follows the standard `{data, meta}` envelope pattern
+- [ ] Response `data` contains at minimum a `message` field with value `"Hello, World!"`
+- [ ] Endpoint does NOT require authentication (public route)
+- [ ] Endpoint is documented in OpenAPI spec with appropriate tags and response schema
+- [ ] Handler follows the `app.Wrap()` pattern for error-returning handlers
+- [ ] Handler has unit tests with at least one happy-path test case
+- [ ] Response includes `request_id` in meta (automatically via middleware)
+
+## Technical Constraints
+
+- Must follow existing patterns in `services/api/internal/api/handlers/`
+- Must use `httpresponse.OK()` for the response (not bare `json.Encoder`)
+- OpenAPI spec must be updated in `services/api/internal/api/spec.go`
+- Route must be registered in `services/api/internal/api/routes.go`
+- No new dependencies required
+
+## Dependencies
+
+- Existing `pkg/app`, `pkg/httpresponse`, and `pkg/openapi` packages (already in place)
+- API service scaffold (already exists at `services/api/`)
+
+## Out of Scope
+
+- Parameterized greeting (e.g., `/hello/{name}`) - keep it simple
+- Localization of the greeting message
+- Rate limiting specific to this endpoint
+- Any database or external service calls
+- Authentication variants (authenticated hello)
+
+## Open Questions
+
+1. **Response payload**: Should the response include additional fields beyond `message`? For example:
+   - `timestamp` - current server time
+   - `version` - API version string
+
+   _Recommendation: Keep it minimal with just `message` to match the feature's purpose as a simple connectivity check._
+
+2. **Tag grouping**: Should this endpoint have its own OpenAPI tag (e.g., "Hello") or be grouped under "Health"?
+
+   _Recommendation: Use a dedicated "Hello" tag to distinguish it from infrastructure health checks._