feat: reword phase to epic, update mkdocs
This commit is contained in:
169
docs/content/stories/epic4/4.1-blog-module.md
Normal file
169
docs/content/stories/epic4/4.1-blog-module.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# Story 4.1: Complete Blog Module
|
||||
|
||||
## Metadata
|
||||
- **Story ID**: 4.1
|
||||
- **Title**: Complete Blog Module
|
||||
- **Epic**: 4 - Sample Feature Module (Blog)
|
||||
- **Status**: Pending
|
||||
- **Priority**: High
|
||||
- **Estimated Time**: 10-12 hours
|
||||
- **Dependencies**: 3.1, 3.2, 3.3, 2.3
|
||||
|
||||
## Goal
|
||||
Create a complete sample blog module to demonstrate the framework, showing how to add routes, permissions, database entities, and services. This serves as a reference implementation for future developers.
|
||||
|
||||
## Description
|
||||
This story implements a complete blog module with blog posts, CRUD operations, proper authorization, and integration with the core platform. The module demonstrates all aspects of module development including domain models, repositories, services, API handlers, and module registration.
|
||||
|
||||
## Deliverables
|
||||
|
||||
### 1. Blog Module Structure
|
||||
- Create `modules/blog/` directory with proper structure:
|
||||
```
|
||||
modules/blog/
|
||||
├── go.mod
|
||||
├── module.yaml
|
||||
├── internal/
|
||||
│ ├── api/
|
||||
│ │ └── handler.go
|
||||
│ ├── domain/
|
||||
│ │ ├── post.go
|
||||
│ │ └── post_repo.go
|
||||
│ ├── service/
|
||||
│ │ └── post_service.go
|
||||
│ └── ent/
|
||||
│ └── schema/
|
||||
│ └── post.go
|
||||
└── pkg/
|
||||
└── module.go
|
||||
```
|
||||
- Initialize `go.mod` for blog module
|
||||
|
||||
### 2. Module Manifest (`modules/blog/module.yaml`)
|
||||
- Define module metadata (name, version, dependencies)
|
||||
- Define permissions (blog.post.create, read, update, delete)
|
||||
- Define routes with permission requirements
|
||||
|
||||
### 3. Blog Domain Model
|
||||
- `Post` domain entity in `modules/blog/internal/domain/post.go`
|
||||
- Ent schema in `modules/blog/internal/ent/schema/post.go`:
|
||||
- Fields: title, content, author_id (FK to user)
|
||||
- Indexes: author_id, created_at
|
||||
- Timestamps: created_at, updated_at
|
||||
- Generate Ent code for blog module
|
||||
|
||||
### 4. Blog Repository
|
||||
- `PostRepository` interface in `modules/blog/internal/domain/post_repo.go`
|
||||
- Implementation using Ent client (shared from core)
|
||||
- CRUD operations: Create, FindByID, FindByAuthor, Update, Delete
|
||||
- Pagination support
|
||||
|
||||
### 5. Blog Service
|
||||
- `PostService` in `modules/blog/internal/service/post_service.go`
|
||||
- Business logic for creating/updating posts
|
||||
- Validation (title length, content requirements)
|
||||
- Authorization checks (author can only update own posts)
|
||||
- Uses service clients for inter-service communication:
|
||||
- `IdentityServiceClient` - to get user information
|
||||
- `AuthzServiceClient` - for authorization checks
|
||||
- `AuditServiceClient` - for audit logging
|
||||
|
||||
### 6. Blog API Handlers
|
||||
- API handlers in `modules/blog/internal/api/handler.go`:
|
||||
- `POST /api/v1/blog/posts` - Create post
|
||||
- `GET /api/v1/blog/posts/:id` - Get post
|
||||
- `GET /api/v1/blog/posts` - List posts (with pagination)
|
||||
- `PUT /api/v1/blog/posts/:id` - Update post
|
||||
- `DELETE /api/v1/blog/posts/:id` - Delete post
|
||||
- Use authorization middleware for all endpoints
|
||||
- Register handlers in module's `Init()`
|
||||
|
||||
### 7. Blog Module Implementation
|
||||
- Module implementation in `modules/blog/pkg/module.go`:
|
||||
- Implement IModule interface
|
||||
- Define Init() fx.Option
|
||||
- Define Migrations()
|
||||
- Register module in init()
|
||||
|
||||
### 8. Integration
|
||||
- Update main `go.mod` to include blog module
|
||||
- Import blog module in `cmd/platform/main.go`
|
||||
- Run permission generation: `make generate`
|
||||
- Verify blog permissions are generated
|
||||
|
||||
### 9. Tests
|
||||
- Integration test in `modules/blog/internal/api/handler_test.go`:
|
||||
- Test creating post with valid permission
|
||||
- Test creating post without permission (403)
|
||||
- Test updating own post vs other's post
|
||||
- Test pagination
|
||||
- Unit tests for service and repository
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Create Module Structure**
|
||||
- Create directory structure
|
||||
- Initialize go.mod
|
||||
|
||||
2. **Create Module Manifest**
|
||||
- Create module.yaml
|
||||
- Define permissions and routes
|
||||
|
||||
3. **Create Domain Model**
|
||||
- Create Post entity
|
||||
- Create Ent schema
|
||||
- Generate Ent code
|
||||
|
||||
4. **Create Repository**
|
||||
- Create repository interface
|
||||
- Implement using Ent
|
||||
|
||||
5. **Create Service**
|
||||
- Create service with business logic
|
||||
- Add validation and authorization
|
||||
|
||||
6. **Create API Handlers**
|
||||
- Create handlers
|
||||
- Add authorization middleware
|
||||
- Register routes
|
||||
|
||||
7. **Create Module Implementation**
|
||||
- Implement IModule interface
|
||||
- Register module
|
||||
|
||||
8. **Integrate with Platform**
|
||||
- Import module in main
|
||||
- Generate permissions
|
||||
- Test integration
|
||||
|
||||
9. **Add Tests**
|
||||
- Create integration tests
|
||||
- Create unit tests
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Blog module loads on platform startup
|
||||
- [ ] `POST /api/v1/blog/posts` requires `blog.post.create` permission
|
||||
- [ ] User can create, read, update, delete posts
|
||||
- [ ] Authorization enforced (users can only edit own posts)
|
||||
- [ ] Integration test: full CRUD flow works
|
||||
- [ ] Audit logs record all blog actions
|
||||
- [ ] Permissions are generated correctly
|
||||
- [ ] Module migrations run on startup
|
||||
|
||||
## Related ADRs
|
||||
- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
|
||||
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
|
||||
- See module framework ADRs
|
||||
|
||||
## Files to Create/Modify
|
||||
- `modules/blog/module.yaml` - Module manifest
|
||||
- `modules/blog/go.mod` - Module dependencies
|
||||
- `modules/blog/internal/domain/post.go` - Domain model
|
||||
- `modules/blog/internal/ent/schema/post.go` - Ent schema
|
||||
- `modules/blog/internal/domain/post_repo.go` - Repository
|
||||
- `modules/blog/internal/service/post_service.go` - Service
|
||||
- `modules/blog/internal/api/handler.go` - API handlers
|
||||
- `modules/blog/pkg/module.go` - Module implementation
|
||||
- `go.mod` - Add blog module
|
||||
- `cmd/platform/main.go` - Import blog module
|
||||
|
||||
31
docs/content/stories/epic4/README.md
Normal file
31
docs/content/stories/epic4/README.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# Epic 4: Sample Feature Module (Blog)
|
||||
|
||||
## Overview
|
||||
Create a complete sample module (Blog) to demonstrate the framework, showing how to add routes, permissions, database entities, and services. The Blog module is an independent service that uses service clients to communicate with core services. Provide reference implementation for future developers.
|
||||
|
||||
## Stories
|
||||
|
||||
### 4.1 Complete Blog Module
|
||||
- [Story: 4.1 - Blog Module](./4.1-blog-module.md)
|
||||
- **Goal:** Create a complete sample blog module to demonstrate the framework.
|
||||
- **Deliverables:** Complete blog module with CRUD operations, permissions, database entities, services, API handlers, and integration tests
|
||||
|
||||
## Deliverables Checklist
|
||||
- [ ] Blog module directory structure created
|
||||
- [ ] Module manifest defines permissions and routes
|
||||
- [ ] Blog post domain model defined
|
||||
- [ ] Ent schema for blog posts created
|
||||
- [ ] Repository implements CRUD operations
|
||||
- [ ] Service layer implements business logic
|
||||
- [ ] API endpoints for blog posts working
|
||||
- [ ] Module integrated with core platform
|
||||
- [ ] Integration tests passing
|
||||
|
||||
## Acceptance Criteria
|
||||
- Blog module can be registered with core platform
|
||||
- Permissions are generated for blog module
|
||||
- CRUD operations work for blog posts
|
||||
- API endpoints require proper authentication
|
||||
- Module migrations run on startup
|
||||
- Blog posts are associated with users
|
||||
- Authorization enforced (users can only edit own posts)
|
||||
Reference in New Issue
Block a user