@c0x12c/ai-toolkit 1.15.0

package/skills/api-endpoint-creator/examples.md

@@ -0,0 +1,522 @@
+# API Endpoint Creator - Code Examples
+
+This file has real patterns from the codebase. **Follow these patterns exactly**.
+
+---
+
+## Complete Example: Project Management Endpoint
+
+Shows the full flow from Controller → Manager → Repository.
+
+### 1. Controller Layer
+
+**File**: `app/api-application/src/main/kotlin/com/yourcompany/controller/admin/ProjectController.kt`
+
+```kotlin
+package com.yourcompany.controller.admin
+
+import com.yourcompany.auth.contract.model.UserAuthentication
+import com.yourcompany.client.request.{domain}.CreateProjectRequest
+import com.yourcompany.client.request.{domain}.UpdateProjectRequest
+import com.yourcompany.client.response.{domain}.ProjectResponse
+import com.yourcompany.client.response.{domain}.ProjectListResponse
+import com.yourcompany.exception.throwOrValue
+import com.yourcompany.{domain}.contract.ProjectManager
+import io.micronaut.http.annotation.*
+import io.micronaut.scheduling.TaskExecutors
+import io.micronaut.scheduling.annotation.ExecuteOn
+import io.micronaut.security.annotation.Secured
+import io.micronaut.validation.Validated
+import io.swagger.v3.oas.annotations.tags.Tag
+import jakarta.validation.Valid
+import java.util.UUID
+
+@ExecuteOn(TaskExecutors.IO)
+@Validated
+@Controller("/api/v1/admin")
+@Tag(name = "Projects", description = "Project management API")
+@Secured(OAuthSecurityRule.ADMIN)
+class ProjectController(
+  private val projectManager: ProjectManager
+) {
+
+  @Get("/projects")
+  suspend fun listProjects(
+    @QueryValue page: Int?,
+    @QueryValue limit: Int?,
+    @QueryValue status: String?
+  ): ProjectListResponse {
+    return projectManager.list(
+      page = page ?: 1,
+      limit = limit ?: 20,
+      status = status
+    ).throwOrValue()
+  }
+
+  @Get("/project")
+  suspend fun getProject(
+    @QueryValue id: UUID
+  ): ProjectResponse {
+    return projectManager.byId(id).throwOrValue()
+  }
+
+  @Post("/project")
+  suspend fun createProject(
+    @Valid @Body request: CreateProjectRequest
+  ): ProjectResponse {
+    return projectManager.create(request).throwOrValue()
+  }
+
+  @Post("/project/update")
+  suspend fun updateProject(
+    @QueryValue id: UUID,
+    @Valid @Body request: UpdateProjectRequest
+  ): ProjectResponse {
+    return projectManager.update(id, request).throwOrValue()
+  }
+
+  @Post("/project/delete")
+  suspend fun deleteProject(
+    @QueryValue id: UUID
+  ): Boolean {
+    return projectManager.deleteById(id).throwOrValue()
+  }
+}
+```
+
+**Controller Pattern Key Points**:
+- `@ExecuteOn(TaskExecutors.IO)` for suspend function support
+- `@Controller` defines base path
+- `@Secured(OAuthSecurityRule.ADMIN)` for admin-only access
+- All IDs as `@QueryValue` (never path params)
+- Methods are `suspend` for coroutines
+- **Thin controllers**: Only delegate to manager
+- Use `.throwOrValue()` to unwrap `Either`
+- NO inline data classes
+
+---
+
+### 2. Manager Interface
+
+**File**: `app/module-{domain}/module-api/src/main/kotlin/com/yourcompany/insight/contract/ProjectManager.kt`
+
+```kotlin
+package com.yourcompany.{domain}.contract
+
+import arrow.core.Either
+import com.yourcompany.client.request.{domain}.CreateProjectRequest
+import com.yourcompany.client.request.{domain}.UpdateProjectRequest
+import com.yourcompany.client.response.{domain}.ProjectResponse
+import com.yourcompany.client.response.{domain}.ProjectListResponse
+import com.yourcompany.exception.ClientException
+import java.util.UUID
+
+interface ProjectManager {
+  suspend fun list(
+    page: Int,
+    limit: Int,
+    status: String?
+  ): Either<ClientException, ProjectListResponse>
+
+  suspend fun byId(id: UUID): Either<ClientException, ProjectResponse>
+
+  suspend fun create(
+    request: CreateProjectRequest
+  ): Either<ClientException, ProjectResponse>
+
+  suspend fun update(
+    id: UUID,
+    request: UpdateProjectRequest
+  ): Either<ClientException, ProjectResponse>
+
+  suspend fun deleteById(id: UUID): Either<ClientException, Boolean>
+}
+```
+
+**Manager Interface Key Points**:
+- All methods return `Either<ClientException, T>`
+- Use `suspend` for async operations
+- No implementation details
+
+---
+
+### 3. Manager Implementation
+
+**File**: `app/module-{domain}/module-impl/src/main/kotlin/com/yourcompany/insight/impl/DefaultProjectManager.kt`
+
+```kotlin
+package com.yourcompany.{domain}.impl
+
+import arrow.core.Either
+import arrow.core.left
+import arrow.core.right
+import com.yourcompany.database.DatabaseContext
+import com.yourcompany.client.request.{domain}.CreateProjectRequest
+import com.yourcompany.client.request.{domain}.UpdateProjectRequest
+import com.yourcompany.client.response.{domain}.ProjectResponse
+import com.yourcompany.client.response.{domain}.ProjectListResponse
+import com.yourcompany.exception.ClientError
+import com.yourcompany.exception.ClientException
+import com.yourcompany.{domain}.contract.ProjectManager
+import com.yourcompany.postgresql.entity.ProjectEntity
+import com.yourcompany.postgresql.repository.ProjectRepository
+import com.yourcompany.postgresql.repository.EmployeeRepository
+import org.jetbrains.exposed.sql.transactions.transaction
+import java.util.UUID
+
+class DefaultProjectManager(
+  private val db: DatabaseContext,
+  private val projectRepository: ProjectRepository,
+  private val employeeRepository: EmployeeRepository
+) : ProjectManager {
+
+  override suspend fun byId(id: UUID): Either<ClientException, ProjectResponse> {
+    val entity = projectRepository.byId(id)
+      ?: return ClientError.PROJECT_NOT_FOUND.asException().left()
+
+    val ownerName = entity.ownerEmployeeId?.let {
+      employeeRepository.byId(it)?.name
+    }
+
+    return ProjectResponse.from(entity, ownerName).right()
+  }
+
+  override suspend fun create(
+    request: CreateProjectRequest
+  ): Either<ClientException, ProjectResponse> {
+    val entity = ProjectEntity(
+      name = request.name,
+      description = request.description,
+      ownerEmployeeId = request.ownerEmployeeId,
+      githubOrg = request.githubOrg
+    )
+
+    val inserted = transaction(db.primary) {
+      projectRepository.insert(entity)
+    }
+
+    return ProjectResponse.from(inserted, ownerName = null).right()
+  }
+
+  override suspend fun update(
+    id: UUID,
+    request: UpdateProjectRequest
+  ): Either<ClientException, ProjectResponse> {
+    projectRepository.byId(id)
+      ?: return ClientError.PROJECT_NOT_FOUND.asException().left()
+
+    val updated = transaction(db.primary) {
+      projectRepository.update(
+        id = id,
+        name = request.name,
+        description = request.description,
+        ownerEmployeeId = request.ownerEmployeeId,
+        status = request.status,
+        githubOrg = request.githubOrg
+      )
+    } ?: return ClientError.PROJECT_NOT_FOUND.asException().left()
+
+    val ownerName = updated.ownerEmployeeId?.let {
+      employeeRepository.byId(it)?.name
+    }
+
+    return ProjectResponse.from(updated, ownerName).right()
+  }
+
+  override suspend fun deleteById(id: UUID): Either<ClientException, Boolean> {
+    val deleted = transaction(db.primary) {
+      projectRepository.deleteById(id)
+    }
+
+    return if (deleted != null) {
+      true.right()
+    } else {
+      ClientError.PROJECT_NOT_FOUND.asException().left()
+    }
+  }
+}
+```
+
+---
+
+### 4. Response Model with Companion Object
+
+**File**: `app/module-client/src/main/kotlin/com/yourcompany/client/response/insight/ProjectResponse.kt`
+
+```kotlin
+package com.yourcompany.client.response.{domain}
+
+import com.yourcompany.postgresql.entity.ProjectEntity
+import java.time.Instant
+import java.util.UUID
+
+data class ProjectResponse(
+  val id: UUID,
+  val name: String,
+  val description: String?,
+  val ownerEmployeeId: UUID?,
+  val ownerName: String?,
+  val status: String,
+  val githubOrg: String?,
+  val createdAt: Instant,
+  val updatedAt: Instant?
+) {
+  companion object {
+    fun from(
+      entity: ProjectEntity,
+      ownerName: String?,
+      contributorCount: Int = 0
+    ): ProjectResponse = ProjectResponse(
+      id = entity.id,
+      name = entity.name,
+      description = entity.description,
+      ownerEmployeeId = entity.ownerEmployeeId,
+      ownerName = ownerName,
+      status = entity.status,
+      githubOrg = entity.githubOrg,
+      createdAt = entity.createdAt,
+      updatedAt = entity.updatedAt
+    )
+  }
+}
+
+data class ProjectListResponse(
+  val items: List<ProjectResponse>,
+  val total: Int,
+  val page: Int,
+  val limit: Int,
+  val hasMore: Boolean
+)
+```
+
+**Response Model Key Points**:
+- `companion object { fun from() }` for entity-to-response conversion
+- Extra params for data not in the entity (ownerName, counts)
+- Lives in `module-client/response/` directory
+
+---
+
+### 5. Request Model
+
+**File**: `app/module-client/src/main/kotlin/com/yourcompany/client/request/insight/ProjectRequests.kt`
+
+```kotlin
+package com.yourcompany.client.request.{domain}
+
+import java.util.UUID
+
+data class CreateProjectRequest(
+  val name: String,
+  val description: String? = null,
+  val ownerEmployeeId: UUID? = null,
+  val githubOrg: String? = null
+)
+
+data class UpdateProjectRequest(
+  val name: String? = null,
+  val description: String? = null,
+  val ownerEmployeeId: UUID? = null,
+  val status: String? = null,
+  val githubOrg: String? = null
+)
+```
+
+---
+
+### 6. Factory Bean
+
+**File**: `app/module-{domain}/module-impl/src/main/kotlin/com/yourcompany/runtime/factory/{Domain}ManagerFactory.kt`
+
+```kotlin
+package com.yourcompany.runtime.factory
+
+import com.yourcompany.database.DatabaseContext
+import com.yourcompany.{domain}.contract.ProjectManager
+import com.yourcompany.{domain}.impl.DefaultProjectManager
+import com.yourcompany.postgresql.repository.ProjectRepository
+import com.yourcompany.postgresql.repository.EmployeeRepository
+import io.micronaut.context.annotation.Factory
+import jakarta.inject.Singleton
+
+@Factory
+class {Domain}ManagerFactory {
+
+  @Singleton
+  fun provideProjectManager(
+    db: DatabaseContext,
+    projectRepository: ProjectRepository,
+    employeeRepository: EmployeeRepository
+  ): ProjectManager {
+    return DefaultProjectManager(
+      db = db,
+      projectRepository = projectRepository,
+      employeeRepository = employeeRepository
+    )
+  }
+}
+```
+
+---
+
+### 7. Retrofit Client
+
+**File**: `app/module-client/src/main/kotlin/com/yourcompany/client/ProjectClient.kt`
+
+```kotlin
+package com.yourcompany.client
+
+import com.yourcompany.client.request.{domain}.CreateProjectRequest
+import com.yourcompany.client.request.{domain}.UpdateProjectRequest
+import com.yourcompany.client.response.{domain}.ProjectResponse
+import com.yourcompany.client.response.{domain}.ProjectListResponse
+import retrofit2.http.*
+import java.util.UUID
+
+interface ProjectClient {
+
+  @GET("/api/v1/admin/projects")
+  suspend fun listProjects(
+    @Header("Authorization") authorization: String,
+    @Query("page") page: Int? = null,
+    @Query("limit") limit: Int? = null,
+    @Query("status") status: String? = null
+  ): ProjectListResponse
+
+  @GET("/api/v1/admin/project")
+  suspend fun getProject(
+    @Header("Authorization") authorization: String,
+    @Query("id") id: UUID
+  ): ProjectResponse
+
+  @POST("/api/v1/admin/project")
+  suspend fun createProject(
+    @Header("Authorization") authorization: String,
+    @Body request: CreateProjectRequest
+  ): ProjectResponse
+
+  @POST("/api/v1/admin/project/update")
+  suspend fun updateProject(
+    @Header("Authorization") authorization: String,
+    @Query("id") id: UUID,
+    @Body request: UpdateProjectRequest
+  ): ProjectResponse
+
+  @POST("/api/v1/admin/project/delete")
+  suspend fun deleteProject(
+    @Header("Authorization") authorization: String,
+    @Query("id") id: UUID
+  ): Boolean
+}
+```
+
+---
+
+## Error Handling Patterns
+
+### Pattern 1: Not Found
+```kotlin
+val entity = repository.byId(id)
+  ?: return ClientError.PROJECT_NOT_FOUND.asException().left()
+return ProjectResponse.from(entity, ownerName).right()
+```
+
+### Pattern 2: Already Exists
+```kotlin
+val existing = repository.byEmail(email)
+if (existing != null) {
+  return ClientError.EMAIL_ALREADY_IN_USE.asException().left()
+}
+```
+
+### Pattern 3: Multiple Validations
+```kotlin
+val existing = repository.byId(id)
+  ?: return ClientError.NOT_FOUND.asException().left()
+
+if (existing.ownerId != currentUserId) {
+  return ClientError.UNAUTHORIZED.asException().left()
+}
+```
+
+---
+
+## Anti-Patterns to AVOID
+
+**Wrong: Business logic in controller**
+```kotlin
+@Post("/project")
+suspend fun create(@Valid @Body request: CreateProjectRequest): ProjectResponse {
+  if (request.name.isBlank()) { throw BadRequestException("Name required") }
+  val entity = repository.insert(...)
+  return ProjectResponse.from(entity)
+}
+```
+
+**Correct: Thin controller**
+```kotlin
+@Post("/project")
+suspend fun create(@Valid @Body request: CreateProjectRequest): ProjectResponse {
+  return projectManager.create(request).throwOrValue()
+}
+```
+
+---
+
+**Wrong: Path parameters**
+```kotlin
+@Get("/project/{id}")
+suspend fun getProject(@PathVariable id: UUID): ProjectResponse
+```
+
+**Correct: Query parameters**
+```kotlin
+@Get("/project")
+suspend fun getProject(@QueryValue id: UUID): ProjectResponse
+```
+
+---
+
+**Wrong: Manager throws exceptions**
+```kotlin
+override suspend fun byId(id: UUID): ProjectResponse {
+  val entity = repository.byId(id)
+    ?: throw NotFoundException("Project not found")
+  return ProjectResponse.from(entity)
+}
+```
+
+**Correct: Manager returns Either**
+```kotlin
+override suspend fun byId(id: UUID): Either<ClientException, ProjectResponse> {
+  val entity = repository.byId(id)
+    ?: return ClientError.PROJECT_NOT_FOUND.asException().left()
+  return ProjectResponse.from(entity, ownerName).right()
+}
+```
+
+---
+
+## Summary Checklist
+
+**Controller**:
+- [ ] Has `@ExecuteOn(TaskExecutors.IO)`
+- [ ] Has `@Secured(...)`
+- [ ] Uses `@QueryValue` for IDs (no path params)
+- [ ] Methods are `suspend`
+- [ ] Only delegates to manager
+- [ ] Uses `.throwOrValue()`
+- [ ] NO inline data classes
+
+**Manager**:
+- [ ] Returns `Either<ClientException, T>`
+- [ ] Uses `ClientError.{NAME}.asException().left()` for errors
+- [ ] Uses `.right()` for success
+- [ ] NO `!!` operators
+- [ ] Converts entities using `Response.from(entity)`
+
+**Models**:
+- [ ] Response models in `module-client/response/`
+- [ ] Request models in `module-client/request/`
+- [ ] Response has `companion object { fun from() }`
+
+**Follow these patterns exactly for consistent code.**