129 lines
3.3 KiB
Markdown
129 lines
3.3 KiB
Markdown
---
|
|
description: Add new entity with full CRUD to existing feature
|
|
---
|
|
|
|
# Add Entity and Routes
|
|
|
|
Add a new entity with complete CRUD operations to an **existing feature**.
|
|
|
|
## When to Use
|
|
|
|
**Use this when:**
|
|
- Adding new data entity to existing feature
|
|
- Need full CRUD infrastructure (Create, Read, Update, Delete, List)
|
|
- Example: Add `profile` entity to `user_management` feature
|
|
|
|
**Don't use when:**
|
|
- Creating new feature → Use `/venturo-go:new-feature`
|
|
- Adding lightweight endpoint only → Use `/venturo-go:add-endpoint`
|
|
|
|
## Workflow
|
|
|
|
### Interactive Discovery
|
|
|
|
Ask these questions:
|
|
|
|
1. **Which feature?** (List from `features/` directory)
|
|
2. **Entity name?** (singular, e.g., `product`, `order`, `profile`)
|
|
3. **Database table name?** (usually plural)
|
|
4. **Table exists?** (Yes = generate from schema, No = design schema)
|
|
5. **Entity fields?** (if designing new schema)
|
|
6. **Relationships?** (foreign keys, joins)
|
|
7. **HTTP operations?** (CRUD, batch, custom actions)
|
|
8. **Base URL path?** (e.g., `/products`, `/orders`)
|
|
9. **Authentication?** (public, authenticated, role-based, permission-based)
|
|
10. **Business rules?** (validation, state transitions, side effects)
|
|
11. **External services?** (email, storage, notifications)
|
|
|
|
Present plan and ask for confirmation.
|
|
|
|
### Implementation Phases
|
|
|
|
Execute these 9 phases in order:
|
|
|
|
1. **Migration** - `phases/new-entity/01-migration.md`
|
|
2. **Domain Entity** - `phases/new-entity/02-domain-entity.md`
|
|
3. **DTOs** - `phases/new-entity/03-dtos.md`
|
|
4. **Repository** - `phases/new-entity/04-repository.md`
|
|
5. **Service** - `phases/new-entity/05-service.md`
|
|
6. **HTTP Handler** - `phases/new-entity/06-handler.md`
|
|
7. **Routes & Errors** - `phases/new-entity/07-routes.md`
|
|
8. **Code Quality** - `phases/shared/code-quality.md`
|
|
9. **Documentation** - `phases/shared/documentation.md`
|
|
|
|
## Common Patterns
|
|
|
|
**Simple CRUD Entity:**
|
|
- Basic create, read, update, delete
|
|
- Example: Product, Category, Tag
|
|
|
|
**Entity with Relationships:**
|
|
- References other entities
|
|
- Example: Order (belongs to User)
|
|
|
|
**Entity with State Machine:**
|
|
- Status transitions + business rules
|
|
- Example: Order (draft → pending → confirmed → shipped)
|
|
|
|
**Entity with Soft Delete:**
|
|
- Uses GORM `DeletedAt` field
|
|
- Never permanently deleted
|
|
|
|
**Entity with Audit Trail:**
|
|
- Tracks `CreatedBy`, `UpdatedBy`
|
|
- Populated from auth context
|
|
|
|
## File Naming Conventions
|
|
|
|
- Entities: `entity.{entity}.go` (singular)
|
|
- DTOs: `request.{entity}.go`, `response.{entity}.go`
|
|
- Handlers: `http.{entity}.go`
|
|
- Repositories: `repo.{entity}.go`
|
|
- Services: `service.{entity}.go`
|
|
- Errors: `errors.{feature}.go` (shared)
|
|
|
|
## Example
|
|
|
|
```
|
|
User: /venturo-go:add-entity
|
|
|
|
Claude: Which feature?
|
|
- user_management
|
|
- email_sender
|
|
|
|
User: user_management
|
|
|
|
Claude: Entity name? (singular)
|
|
|
|
User: profile
|
|
|
|
Claude: Database table name?
|
|
|
|
User: user_profiles
|
|
|
|
Claude: Does table exist?
|
|
|
|
User: No
|
|
|
|
Claude: What fields?
|
|
|
|
User:
|
|
- bio: text
|
|
- avatar_url: string
|
|
- phone: string, unique
|
|
- user_id: uuid, foreign key
|
|
|
|
[Presents plan, proceeds with phases]
|
|
```
|
|
|
|
## Tips
|
|
|
|
- Start with database schema design
|
|
- Use code generation for standard CRUD: `make gen-crud`
|
|
- Follow naming conventions strictly
|
|
- Add validation tags to DTOs
|
|
- Use feature-specific errors
|
|
- Test incrementally
|
|
- Add database indexes for performance
|
|
- Apply proper authentication
|