Initial commit

commands/add-endpoint.md

@@ -0,0 +1,141 @@
+---
+description: Add lightweight endpoint without full entity infrastructure
+---
+
+# Add Endpoint/Handler
+
+Add new HTTP endpoints to an existing feature **without creating full entity infrastructure**.
+
+## When to Use
+
+**Use this when:**
+- Adding report/analytics endpoints (statistics, dashboards)
+- Adding search/filter endpoints (advanced search, autocomplete)
+- Adding action endpoints (approve, cancel, activate)
+- Adding aggregation endpoints (totals, counts, summaries)
+- Adding small entities without full CRUD (comments, tags, notes)
+- Adding utility endpoints (export, import, validate)
+
+**Don't use when:**
+- Creating new feature → Use `/venturo-go:new-feature`
+- Adding full entity with CRUD → Use `/venturo-go:add-entity`
+
+## Workflow
+
+### Interactive Discovery
+
+Ask these questions:
+
+1. **Which feature?** (List from `features/`)
+2. **Endpoint type?** (Report, Search, Action, Aggregation, Utility, Small Entity, Custom)
+3. **Specific endpoint?** (HTTP method + path, e.g., `GET /users/statistics`)
+4. **Related to entity or feature-general?**
+   - Entity-specific (user statistics) → Add to existing handler
+   - Feature-general (dashboard) → Create new handler
+   - Operation-specific (bulk import) → Dedicated handler
+5. **Operation/handler name?**
+6. **Purpose?** (What data/action?)
+7. **Input required?** (URL params, query params, body, headers)
+8. **Return type?** (Single object, array, paginated list, success message, file)
+9. **Business logic?** (queries, calculations, external calls)
+10. **External services?** (email, storage, queue, cache)
+11. **Authorization?** (public, authenticated, role-based, permission-based)
+12. **New repository methods?** (queries, aggregations)
+13. **Modifies data?** (read-only vs write operations)
+
+Present plan and confirm before implementation.
+
+### Implementation Phases
+
+Execute these 8 phases:
+
+1. **Create DTOs** - `phases/add-endpoint/01-create-dtos.md`
+2. **Repository Methods** - `phases/add-endpoint/02-repository-methods.md`
+3. **Service Methods** - `phases/add-endpoint/03-service-methods.md`
+4. **HTTP Handlers** - `phases/add-endpoint/04-http-handlers.md`
+5. **Register Routes** - `phases/add-endpoint/05-register-routes.md`
+6. **Testing** - `phases/add-endpoint/06-testing.md`
+7. **Code Quality** - `phases/shared/code-quality.md`
+8. **Documentation** - `phases/shared/documentation.md`
+
+## Common Endpoint Patterns
+
+**Report/Analytics:**
+```
+GET /users/statistics?from_date=...&to_date=...
+GET /dashboard/summary
+```
+- Query parameters for filters
+- Aggregated data response
+- Read-only, often cached
+
+**Search/Filter:**
+```
+GET /products/search?q=keyword&category=...
+POST /orders/advanced-filter
+```
+- Search criteria in query or body
+- Paginated results
+
+**Action/Command:**
+```
+POST /orders/:id/cancel
+POST /users/:id/activate
+```
+- URL parameter for resource ID
+- Body for action parameters
+- Modifies state, idempotent
+
+**Aggregation:**
+```
+GET /sales/totals?group_by=month
+GET /inventory/summary
+```
+- Computed/derived data
+- Grouping and filtering
+
+**Utility:**
+```
+POST /users/export (returns file)
+POST /products/import (accepts file)
+```
+- File upload/download
+- Batch operations
+
+## Example
+
+```
+User: /venturo-go:add-endpoint
+
+Claude: Which feature?
+
+User: user_management
+
+Claude: Endpoint type?
+
+User: Report/Analytics
+
+Claude: Specific endpoint?
+
+User: GET /users/statistics
+
+Claude: Related to user entity or feature-general?
+
+User: Entity-specific (user)
+
+Claude: What data should statistics return?
+
+User: Total users, active users, new registrations this month, users by role
+
+[Presents plan, proceeds with phases]
+```
+
+## Tips
+
+- Keep it focused (one endpoint = one responsibility)
+- Reuse existing repository/service methods
+- Validate input with binding tags
+- Consider caching for expensive operations
+- Think about performance and scale
+- Apply proper authentication
+- Test edge cases