---
name: step-02-plan
description: Plan controller structure - endpoints, DTOs, permissions
next_step: steps/step-03-generate.md
---

# Step 2: Plan Controller Structure

## YOUR TASK:

Design the complete controller structure based on analysis. Define endpoints, DTOs, and permissions.

**ULTRA THINK about REST conventions and SmartStack patterns.**

---

## EXECUTION SEQUENCE:

### 1. Determine Controller Type

**Based on {area} and analysis:**

| Indicator | → Controller Type |
|-----------|-------------------|
| Area = Auth | `auth` (login, logout, tokens) |
| Entity has all CRUD methods | `crud` (full CRUD) |
| Entity missing Create/Update | `readonly` (GET only) |
| User specifies custom | `custom` (specific endpoints) |

**If not auto_mode, confirm:**

```yaml
AskUserQuestion:
  header: "Type"
  question: "What type of controller?"
  options:
    - label: "CRUD Complet (Recommended)"
      description: "GET list, GET by ID, POST, PUT, PATCH, DELETE"
    - label: "Read-Only"
      description: "GET list, GET by ID only"
    - label: "Custom"
      description: "I'll specify the endpoints"
```

### 2. Plan Endpoints

**For CRUD controller:**

| Method | Route | Action | Permission |
|--------|-------|--------|------------|
| GET | `/{module}` | GetAll | `{permission_path}.read` |
| GET | `/{module}/{id}` | GetById | `{permission_path}.read` |
| POST | `/{module}` | Create | `{permission_path}.create` |
| PUT | `/{module}/{id}` | Update | `{permission_path}.update` |
| PATCH | `/{module}/{id}/status` | UpdateStatus | `{permission_path}.update` |
| DELETE | `/{module}/{id}` | Delete | `{permission_path}.delete` |

**For Auth controller:**

| Method | Route | Action | Permission |
|--------|-------|--------|------------|
| POST | `/auth/login` | Login | AllowAnonymous |
| POST | `/auth/logout` | Logout | Authorize |
| POST | `/auth/refresh` | RefreshToken | AllowAnonymous |
| POST | `/auth/change-password` | ChangePassword | Authorize |

### 3. Plan DTOs (if dto_mode)

**CreateDto:**
```
{entity}CreateDto:
  - Required properties from Entity.Create()
  - Validation attributes
  - No Id, CreatedAt, etc.
```

**UpdateDto:**
```
{entity}UpdateDto:
  - Updatable properties from Entity.Update()
  - Validation attributes
  - No Id, audit fields
```

**ResponseDto:**
```
{entity}ResponseDto:
  - All public properties
  - Formatted dates
  - Nested DTOs for relationships
```

### 4. Plan Permissions

**Permission structure:**

```csharp
public static class {module}
{
    public const string View = "{permission_path}.read";
    public const string Create = "{permission_path}.create";
    public const string Update = "{permission_path}.update";
    public const string Delete = "{permission_path}.delete";
}
```

**Permission seeds:**

```csharp
new Permission { Code = "{permission_path}.read", Name = "View {module}", ... }
new Permission { Code = "{permission_path}.create", Name = "Create {module}", ... }
new Permission { Code = "{permission_path}.update", Name = "Update {module}", ... }
new Permission { Code = "{permission_path}.delete", Name = "Delete {module}", ... }
```

### 5. Plan Services to Inject

**Required services:**

| Service | Required | Reason |
|---------|----------|--------|
| `IApplicationDbContext` | Always | DB access |
| `ICurrentUserService` | Always | User context |
| `ILogger<T>` | Always | Logging |
| `IPermissionService` | If roles/perms | Cache invalidation |
| `IPasswordService` | If auth | Password hashing |
| `IJwtService` | If auth | Token generation |

### 6. Confirmation (if not auto_mode)

**Show plan for approval:**

```
Controller Plan: {area}/{module}Controller

Endpoints:
  GET    /api/{area}/{module}           → GetAll
  GET    /api/{area}/{module}/{id}      → GetById
  POST   /api/{area}/{module}           → Create
  PUT    /api/{area}/{module}/{id}      → Update
  DELETE /api/{area}/{module}/{id}      → Delete

DTOs: {dto_mode ? "CreateDto, UpdateDto, ResponseDto" : "None (inline)"}

Permissions:
  {permission_path}.read
  {permission_path}.create
  {permission_path}.update
  {permission_path}.delete

Proceed with generation?
```

---

## OUTPUT FORMAT:

```
Plan Complete:

| Aspect | Details |
|--------|---------|
| Type | {controller_type} |
| Endpoints | {endpoint_count} |
| DTOs | {dto_count} |
| Permissions | 4 (CRUD) |
| Services | {service_count} |

-> Generating controller...
```

---

## NEXT STEP:

After plan confirmed (or auto_mode), proceed to `./step-03-generate.md`
