# BizChangefeed Model Layer Agent Instructions

## Overview

`biz_changefeed` is the **top-level business model** for CDC changefeed operations.
It orchestrates the full lifecycle of a changefeed from the user's perspective.

It sits above `app/models/ticdc/` which manages the kernel-level TiCDC resources.

## Relationship Between Layers

```
app/controllers/
    └── BizChangefeedModel          (this module - business logic, user-facing)
         └── TiCDCChangefeedModel   (app/models/ticdc/ - kernel resources)
              ├── clusterModel           (non-regional: via ClusterProxy)
              └── changefeedModelRegionalImpl  (regional: via Regional API)
```

## Operation Lifecycle

All mutating operations follow the same async pattern:

```
1. [sync]  Validate request
2. [sync]  Update BizChangefeed status to intermediate state (e.g. deleting)
3. [sync]  Start async workflow DAG
4. [async] Workflow executes actual operations step by step
5. [async] Final step updates status to terminal state (e.g. deleted)
```

### Status Transitions

```
Create:  (none) → creating → normal | failed
Delete:  normal → deleting → deleted
Pause:   normal → pausing  → paused
Resume:  paused → resuming → normal
```

**Key point**: After an API call returns, the operation is NOT complete.
The returned `WorkflowID` can be used to track progress.

### Delete Workflow DAG

```
CancelUnfinishedDagIns
    └── DeleteChangefeed          ← calls ticdc.DeleteChangefeed()
         └── DeleteOrScaleTiCDCCluster
              └── DeregisterClusterJob
                   └── FinalStep  ← sets status to deleted
```

## Key Files

```
app/models/biz_changefeed/
├── interface.go                        # BizChangefeedModel interface
├── impl/
│   ├── biz_changefeed.go              # Core CRUD operations
│   ├── biz_changefeed_metering.go     # Billing/metering logic
│   └── biz_changefeed_status_matrix.go # Status transition rules
└── mock/                               # Auto-generated mocks (DO NOT EDIT)

app/workflow/dag/biz_changefeed/
├── create.go                           # Create DAG definition
├── delete.go                           # Delete DAG definition
├── pause.go                            # Pause DAG definition
└── resume.go                           # Resume DAG definition

app/workflow/action/biz_changefeed/
├── del/
│   ├── delete_changefeed.go           # Calls ticdc.DeleteChangefeed()
│   ├── delete_or_scale_ticdc.go
│   ├── deregister_cluster_job.go
│   └── final_step.go
├── create/
└── ...
```

## Common Pitfalls

### 1. Checking status immediately after API call

The API returns before the workflow completes. If you need to verify
the final state, poll the status or check workflow completion.

### 2. Not using IsRegional when calling ticdc model

Always use `ChangefeedModelFactory.GetModel(isRegional)` to get the correct
implementation. Never call `TiCDCChangefeedModel` or `RegionalTiCDCChangefeedModel` directly.

```go
// Correct
a.changefeedModelFactory.GetModel(bizChangefeedEnt.IsRegional).DeleteChangefeed(ctx, req)

// Wrong - bypasses factory selection
a.ticdcChangefeedModel.DeleteChangefeed(ctx, req)
```

### 3. Status transition errors

Use `calBizChangefeedNextStatus()` to compute the next status.
Never set status directly without going through the status matrix -
it will reject invalid transitions and prevent corrupted states.