# 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

