lasserh/DeutschLernen
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(backend/story-integration): Phase 2 - Backend Services

Browse source 
Implement story integration backend services:
- Create StoryService (Application/Services/StoryService.cs) with full CRUD operations
- Create StoryGenerationService (Application/Services/StoryGenerationService.cs) for AI-powered story generation
  - Uses IMistralService for text generation
  - Uses ITtsService for audio generation
  - Splits stories into segments per lesson
- Create StoryUnlockService (Application/Services/StoryUnlockService.cs) for progress management
  - Handles lesson completion → story segment unlocking
- Create StoryController (Presentation/Controllers/StoryController.cs) with 12 endpoints:
  - GET /api/story/levels - list levels with stories
  - GET /api/story/levels/{levelId}/segments - get segments for level
  - GET /api/story/segments/{id} - get specific segment
  - POST /api/story/segments - create segment (Admin)
  - PUT /api/story/segments/{id} - update segment (Admin)
  - DELETE /api/story/segments/{id} - delete segment (Admin)
  - POST /api/story/levels/{levelId}/generate - generate story with AI (Admin)
  - POST /api/story/segments/{segmentId}/audio - generate audio (Admin)
  - GET /api/story/levels/{levelId}/progress - get user progress
  - POST /api/story/segments/{segmentId}/complete - mark as completed
  - GET /api/story/levels/{levelId}/next - get next segment
  - GET /api/story/segments/{segmentId}/unlocked - check if unlocked
  - GET /api/story/segments/{segmentId}/audio - get audio URL
  - GET /api/story/levels/{levelId}/lessons-with-stories - get lessons with story status
- Register all services in Program.cs DI container
- Update feature document to reflect Phase 2 completion

Next: Phase 3 - AI Integration (unit tests for services)

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
Lasse Rune Hansen 2026-06-13 13:37:16 +02:00
parent bf5e7883ee
commit 6693165f83
8 changed files with 1580 additions and 170 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

553
GermanApp/Application/Services/StoryGenerationService.cs
View file

@ -1,238 +1,483 @@
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using GermanApp.Application.DTOs;
using GermanApp.Domain.Entities;
using GermanApp.Domain.Interfaces; using GermanApp.Domain.Interfaces;
using Microsoft.Extensions.Logging; using Microsoft.Extensions.Logging;
namespace GermanApp.Application.Services; namespace GermanApp.Application.Services;
/// <summary> /// <summary>
/// Application service for generating stories using Mistral AI. /// Application service for generating stories using AI.
/// This is part of the Application layer. /// This is part of the Application layer and uses MistralService for text generation.
/// </summary> /// </summary>
public class StoryGenerationService public class StoryGenerationService
{ {
private readonly IMistralService _mistralService; private readonly IMistralService _mistralService;
private readonly IStoryRepository _storyRepository;
private readonly ITtsService _ttsService;
private readonly ILogger<StoryGenerationService> _logger; private readonly ILogger<StoryGenerationService> _logger;
/// <summary> /// <summary>
/// Creates a new StoryGenerationService. /// Creates a new StoryGenerationService.
/// </summary> /// </summary>
/// <param name="mistralService">The Mistral text generation service</param> /// <param name="mistralService">Mistral service for text generation</param>
/// <param name="storyRepository">Repository for story segments</param>
/// <param name="ttsService">TTS service for audio generation</param>
/// <param name="logger">Logger for service operations</param> /// <param name="logger">Logger for service operations</param>
public StoryGenerationService( public StoryGenerationService(
IMistralService mistralService, IMistralService mistralService,
IStoryRepository storyRepository,
ITtsService ttsService,
ILogger<StoryGenerationService> logger) ILogger<StoryGenerationService> logger)
{ {
_mistralService = mistralService; _mistralService = mistralService;
_storyRepository = storyRepository;
_ttsService = ttsService;
_logger = logger; _logger = logger;
} }
/// <summary> /// <summary>
/// Generates a story based on the given parameters. /// Generates a complete story for a level and divides it into segments.
/// </summary> /// </summary>
/// <param name="level">The CEFR level (A1, A2, B1, B2, C1)</param> /// <param name="levelId">The level ID</param>
/// <param name="topic">The story topic or theme</param> /// <param name="theme">The theme for the story</param>
/// <param name="vocabularyWords">List of German vocabulary words to include in the story</param> /// <param name="lessons">List of lessons in the level with their vocabulary</param>
/// <param name="length">Approximate word count for the story</param>
/// <param name="cancellationToken">Cancellation token</param> /// <param name="cancellationToken">Cancellation token</param>
/// <returns>The generated story text in German</returns> /// <returns>Response DTO with the full story and segments</returns>
public virtual async Task<string> GenerateStoryAsync( public virtual async Task<StoryGenerationResponseDto> GenerateStoryAsync(
string level, int levelId,
string topic, string theme,
IReadOnlyList<string> vocabularyWords, IReadOnlyList<Lesson> lessons,
int length = 200,
CancellationToken cancellationToken = default) CancellationToken cancellationToken = default)
{ {
_logger.LogInformation( _logger.LogInformation(
"Generating story: Level={Level}, Topic={Topic}, VocabularyCount={Count}, Length={Length}", "Generating story for level {LevelId} with theme '{Theme}'",
level, topic, vocabularyWords?.Count ?? 0, length); levelId, theme);
// Extract vocabulary from all lessons
var allVocabulary = ExtractVocabularyFromLessons(lessons);
if (!allVocabulary.Any())
{
_logger.LogWarning("No vocabulary found for level {LevelId}", levelId);
throw new InvalidOperationException("Cannot generate story: No vocabulary available");
}
// Build the prompt for Mistral
var prompt = BuildStoryPrompt(levelId, theme, allVocabulary, lessons.Count);
_logger.LogDebug("Story generation prompt: {Prompt}", prompt);
// Generate the full story
var fullStory = await _mistralService.GenerateStoryAsync(
GetLevelCode(levelId),
theme,
allVocabulary,
500, // Approximate word count
cancellationToken);
if (string.IsNullOrWhiteSpace(fullStory))
{
_logger.LogError("Failed to generate story: Empty response from AI service");
throw new InvalidOperationException("Failed to generate story: Empty response");
}
_logger.LogInformation("Generated story text (length: {Length} chars)", fullStory.Length);
// Split the story into segments (one per lesson)
var segments = SplitStoryIntoSegments(fullStory, lessons.Count);
if (segments.Count != lessons.Count)
{
_logger.LogWarning(
"Story split into {SegmentCount} segments but expected {LessonCount}",
segments.Count, lessons.Count);
// Adjust: if we have fewer segments, duplicate the last one
// If we have more, combine some
segments = AdjustSegmentCount(segments, lessons.Count);
}
// Create story segment entities
var createdSegments = new List<StorySegment>();
for (int i = 0; i < segments.Count; i++)
{
var segment = StorySegment.Create(
levelId,
lessons[i].Id,
segments[i],
i + 1, // Order starts at 1
$"{theme} - Part {i + 1}",
theme,
2); // Estimated reading minutes
createdSegments.Add(segment);
}
// Save all segments
foreach (var segment in createdSegments)
{
await _storyRepository.AddAsync(segment, cancellationToken);
}
_logger.LogInformation("Created {Count} story segments for level {LevelId}",
createdSegments.Count, levelId);
// Convert to DTOs
var segmentDtos = createdSegments.Select(StorySegmentDto.FromEntity).ToList();
return new StoryGenerationResponseDto(
levelId,
theme,
segments.Count,
fullStory,
segmentDtos);
}
/// <summary>
/// Generates a story segment for a specific lesson.
/// </summary>
/// <param name="levelId">The level ID</param>
/// <param name="lessonId">The lesson ID</param>
/// <param name="theme">The theme for the story</param>
/// <param name="vocabulary">Vocabulary words to include</param>
/// <param name="order">The order of this segment</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>The created story segment DTO</returns>
public virtual async Task<StorySegmentDto> GenerateSegmentAsync(
int levelId,
int lessonId,
string theme,
IReadOnlyList<string> vocabulary,
int order,
CancellationToken cancellationToken = default)
{
_logger.LogInformation(
"Generating story segment for level {LevelId}, lesson {LessonId}, order {Order}",
levelId, lessonId, order);
if (!vocabulary.Any())
{
_logger.LogWarning("No vocabulary provided for segment generation");
throw new InvalidOperationException("Cannot generate segment: No vocabulary available");
}
// Build prompt for a single segment
var prompt = BuildSegmentPrompt(GetLevelCode(levelId), theme, vocabulary);
_logger.LogDebug("Segment generation prompt: {Prompt}", prompt);
// Generate the segment
var content = await _mistralService.GenerateStoryAsync(
GetLevelCode(levelId),
theme,
vocabulary,
100, // Approximate word count for a segment
cancellationToken);
if (string.IsNullOrWhiteSpace(content))
{
_logger.LogError("Failed to generate story segment: Empty response from AI service");
throw new InvalidOperationException("Failed to generate segment: Empty response");
}
// Create and save the segment
var segment = StorySegment.Create(
levelId,
lessonId,
content,
order,
$"{theme} - Part {order}",
theme,
2);
var created = await _storyRepository.AddAsync(segment, cancellationToken);
_logger.LogInformation("Created story segment with ID: {Id}", created.Id);
return StorySegmentDto.FromEntity(created);
}
/// <summary>
/// Generates audio for a story segment.
/// </summary>
/// <param name="segmentId">The segment ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>The updated segment DTO with audio URL</returns>
public virtual async Task<StorySegmentDto?> GenerateAudioAsync(
int segmentId,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Generating audio for story segment: {SegmentId}", segmentId);
var segment = await _storyRepository.GetByIdAsync(segmentId, cancellationToken);
if (segment == null)
{
_logger.LogWarning("Segment not found: {SegmentId}", segmentId);
return null;
}
if (!string.IsNullOrEmpty(segment.AudioUrl))
{
_logger.LogInformation("Segment already has audio: {SegmentId}", segmentId);
return StorySegmentDto.FromEntity(segment);
}
// Generate audio file path
var audioPath = $"/audio/story/level{segment.LevelId}-segment{segment.Order}.wav";
try try
{ {
var story = await _mistralService.GenerateStoryAsync( // Generate audio using the TTS service directly
level, await _ttsService.GenerateAudioToFileAsync(
topic, segment.Content,
vocabularyWords, audioPath,
length, null,
"de",
cancellationToken); cancellationToken);
// Validate the generated story // Update segment with audio URL
ValidateStory(story, level, vocabularyWords); segment.UpdateAudioUrl(audioPath);
await _storyRepository.UpdateAsync(segment, cancellationToken);
_logger.LogInformation("Story generated successfully"); _logger.LogInformation("Generated audio for segment {SegmentId}: {AudioPath}",
return story; segmentId, audioPath);
return StorySegmentDto.FromEntity(segment);
} }
catch (Exception ex) catch (Exception ex)
{ {
_logger.LogError(ex, "Failed to generate story"); _logger.LogError(ex, "Failed to generate audio for segment {SegmentId}", segmentId);
throw new AiServiceException( throw;
"Failed to generate story: " + ex.Message,
AiErrorCode.Temporary);
} }
} }
/// <summary> /// <summary>
/// Generates a story for a specific lesson. /// Generates audio for all segments that don't have audio yet.
/// </summary> /// </summary>
/// <param name="lessonTitle">The lesson title for context</param> /// <param name="levelId">Optional level ID to limit generation to</param>
/// <param name="level">The CEFR level</param>
/// <param name="vocabularyWords">List of vocabulary words from the lesson</param>
/// <param name="length">Approximate word count</param>
/// <param name="cancellationToken">Cancellation token</param> /// <param name="cancellationToken">Cancellation token</param>
/// <returns>The generated story text</returns> /// <returns>List of segments that had audio generated</returns>
public virtual async Task<string> GenerateLessonStoryAsync( public virtual async Task<IReadOnlyList<StorySegmentDto>> GenerateAudioForAllSegmentsAsync(
string lessonTitle, int? levelId = null,
string level,
IReadOnlyList<string> vocabularyWords,
int length = 250,
CancellationToken cancellationToken = default) CancellationToken cancellationToken = default)
{ {
_logger.LogInformation( _logger.LogInformation("Generating audio for all segments needing audio");
"Generating lesson story: Lesson={Lesson}, Level={Level}, VocabularyCount={Count}",
lessonTitle, level, vocabularyWords?.Count ?? 0);
return await GenerateStoryAsync( var segments = await _storyRepository.GetSegmentsNeedingAudioAsync(cancellationToken);
level,
lessonTitle,
vocabularyWords,
length,
cancellationToken);
}
/// <summary> if (levelId.HasValue)
/// Generates multiple stories for different levels.
/// </summary>
/// <param name="topic">The common topic for all stories</param>
/// <param name="vocabularyByLevel">Dictionary mapping CEFR levels to vocabulary words</param>
/// <param name="lengthByLevel">Dictionary mapping CEFR levels to story lengths</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>Dictionary mapping levels to generated stories</returns>
public virtual async Task<IDictionary<string, string>> GenerateStoriesByLevelAsync(
string topic,
IDictionary<string, IReadOnlyList<string>> vocabularyByLevel,
IDictionary<string, int>? lengthByLevel = null,
CancellationToken cancellationToken = default)
{
_logger.LogInformation(
"Generating stories for multiple levels: Topic={Topic}, LevelCount={Count}",
topic, vocabularyByLevel?.Count ?? 0);
var results = new Dictionary<string, string>();
lengthByLevel ??= new Dictionary<string, int>();
foreach (var kvp in vocabularyByLevel)
{ {
var level = kvp.Key; segments = segments.Where(s => s.LevelId == levelId.Value).ToList();
var vocabulary = kvp.Value; }
var length = lengthByLevel.TryGetValue(level, out var l) ? l : 200;
_logger.LogInformation("Found {Count} segments needing audio", segments.Count);
var results = new List<StorySegmentDto>();
foreach (var segment in segments)
{
try try
{ {
var story = await GenerateStoryAsync( var result = await GenerateAudioAsync(segment.Id, cancellationToken);
level, if (result != null)
topic, {
vocabulary, results.Add(result);
length, }
cancellationToken);
results[level] = story;
_logger.LogInformation("Generated story for level: {Level}", level);
} }
catch (Exception ex) catch (Exception ex)
{ {
_logger.LogError(ex, "Failed to generate story for level {Level}", level); _logger.LogError(ex, "Failed to generate audio for segment {SegmentId}", segment.Id);
results[level] = string.Empty;
} }
} }
_logger.LogInformation("Generated audio for {Count} segments", results.Count);
return results; return results;
} }
/// <summary> /// <summary>
/// Validates the generated story meets basic requirements. /// Extracts vocabulary words from lessons.
/// This is a placeholder - in a real implementation, vocabulary would be stored in the lesson.
/// </summary> /// </summary>
/// <param name="story">The generated story text</param> /// <param name="lessons">List of lessons</param>
/// <param name="level">The target CEFR level</param> /// <returns>List of vocabulary words</returns>
/// <param name="vocabularyWords">The vocabulary words that should be included</param> private IReadOnlyList<string> ExtractVocabularyFromLessons(IReadOnlyList<Lesson> lessons)
/// <exception cref="InvalidOperationException">Thrown when story validation fails</exception>
private void ValidateStory(
string story,
string level,
IReadOnlyList<string>? vocabularyWords)
{ {
if (string.IsNullOrWhiteSpace(story)) // For now, extract from lesson titles and topics
// In a real implementation, lessons would have a VocabularyWords collection
var vocabulary = new List<string>();
foreach (var lesson in lessons)
{ {
_logger.LogError("Generated story is empty"); // Extract words from title (simple word splitting)
throw new InvalidOperationException("Generated story is empty"); var titleWords = lesson.Title.Split(new[] { ' ', ',', '.', '!', '?' },
StringSplitOptions.RemoveEmptyEntries);
vocabulary.AddRange(titleWords);
// Extract words from topic
var topicWords = lesson.Topic.Split(new[] { ' ', ',', '.', '!', '?' },
StringSplitOptions.RemoveEmptyEntries);
vocabulary.AddRange(topicWords);
} }
// Check minimum length based on level // Remove duplicates and filter
var minLength = GetMinStoryLength(level); return vocabulary
if (story.Length < minLength) .Where(w => !string.IsNullOrWhiteSpace(w))
.Where(w => w.Length > 2) // Skip very short words
.Distinct()
.OrderBy(w => w)
.ToList();
}
/// <summary>
/// Builds a prompt for full story generation.
/// </summary>
/// <param name="levelId">The level ID</param>
/// <param name="theme">The story theme</param>
/// <param name="vocabulary">List of vocabulary words</param>
/// <param name="segmentCount">Number of segments to generate</param>
/// <returns>The prompt string</returns>
private string BuildStoryPrompt(int levelId, string theme, IReadOnlyList<string> vocabulary, int segmentCount)
{
var levelCode = GetLevelCode(levelId);
var vocabularyString = string.Join(", ", vocabulary.Take(20)); // Limit to first 20 words
if (vocabulary.Count > 20)
{ {
_logger.LogWarning( vocabularyString += ", ...";
"Generated story is too short: {Length} characters (min: {Min})",
story.Length, minLength);
// Don't throw - just log warning, AI might generate short stories
} }
// Check if vocabulary words are included (if provided) return $@"Write a {segmentCount}-part continuous story for a German {levelCode} learner.
if (vocabularyWords != null && vocabularyWords.Count > 0) The story theme is: {theme}.
{ Include these German words and phrases: {vocabularyString}.
var storyLower = story.ToLower(); Use only {levelCode} level vocabulary and grammar.
var missingWords = vocabularyWords Write each part as a separate paragraph.
.Where(w => !string.IsNullOrWhiteSpace(w)) Make the story engaging and appropriate for language learners.";
.Where(w => !storyLower.Contains(w.ToLower())) }
.ToList();
if (missingWords.Count > vocabularyWords.Count * 0.5) /// <summary>
/// Builds a prompt for a single story segment.
/// </summary>
/// <param name="levelCode">The level code (A1, A2, etc.)</param>
/// <param name="theme">The story theme</param>
/// <param name="vocabulary">List of vocabulary words</param>
/// <returns>The prompt string</returns>
private string BuildSegmentPrompt(string levelCode, string theme, IReadOnlyList<string> vocabulary)
{
var vocabularyString = string.Join(", ", vocabulary.Take(15));
if (vocabulary.Count > 15)
{
vocabularyString += ", ...";
}
return $@"Write a short story segment (5-8 sentences) for a German {levelCode} learner.
The theme is: {theme}.
Include these German words: {vocabularyString}.
Use only {levelCode} level vocabulary and grammar.
Make it engaging and appropriate for language learners.";
}
/// <summary>
/// Splits a full story text into segments.
/// </summary>
/// <param name="story">The full story text</param>
/// <param name="segmentCount">Number of segments to create</param>
/// <returns>List of story segments</returns>
private List<string> SplitStoryIntoSegments(string story, int segmentCount)
{
var segments = new List<string>();
// Split by double newlines (paragraphs)
var paragraphs = story.Split(new[] { "\n\n", "\n\r\n", "\r\n\r\n" },
StringSplitOptions.RemoveEmptyEntries);
if (paragraphs.Length >= segmentCount)
{
// Take the first segmentCount paragraphs
for (int i = 0; i < segmentCount; i++)
{ {
_logger.LogWarning( segments.Add(paragraphs[i].Trim());
"Many vocabulary words missing from story: {MissingCount}/{TotalCount}",
missingWords.Count, vocabularyWords.Count);
} }
} }
else
{
// Need to split paragraphs further
// Calculate how many paragraphs per segment we need
var paragraphsPerSegment = Math.Max(1, paragraphs.Length / segmentCount);
for (int i = 0; i < segmentCount; i++)
{
var start = i * paragraphsPerSegment;
var end = Math.Min((i + 1) * paragraphsPerSegment, paragraphs.Length);
var segmentText = string.Join(" ", paragraphs[start..end]).Trim();
segments.Add(segmentText);
}
}
return segments;
} }
/// <summary> /// <summary>
/// Gets the minimum expected story length based on CEFR level. /// Adjusts the segment count to match the expected number.
/// </summary> /// </summary>
/// <param name="level">The CEFR level</param> /// <param name="segments">Current list of segments</param>
/// <returns>Minimum character count</returns> /// <param name="targetCount">Target number of segments</param>
private int GetMinStoryLength(string level) /// <returns>Adjusted list of segments</returns>
private List<string> AdjustSegmentCount(List<string> segments, int targetCount)
{ {
return level.ToUpper() switch if (segments.Count == targetCount)
return segments;
if (segments.Count < targetCount)
{ {
"A1" => 100, // Duplicate the last segment to fill
"A2" => 150, while (segments.Count < targetCount)
"B1" => 200, {
"B2" => 300, segments.Add(segments[^1]);
"C1" => 400, }
_ => 100 }
else
{
// Combine segments to reduce count
var result = new List<string>();
var combineCount = (int)Math.Ceiling((double)segments.Count / targetCount);
for (int i = 0; i < segments.Count; i += combineCount)
{
var end = Math.Min(i + combineCount, segments.Count);
var combined = string.Join(" ", segments[i..end]).Trim();
result.Add(combined);
}
segments = result;
}
return segments;
}
/// <summary>
/// Gets the level code (A1, A2, etc.) from the level ID.
/// This is a temporary implementation - in a real app, we would look this up.
/// </summary>
/// <param name="levelId">The level ID</param>
/// <returns>The level code</returns>
private string GetLevelCode(int levelId)
{
// This is a placeholder - the actual mapping should come from the database
return levelId switch
{
1 => "A1",
2 => "A2",
3 => "B1",
4 => "B2",
5 => "C1",
_ => "A1"
}; };
} }
/// <summary>
/// Tests the story generation service.
/// </summary>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>True if service is working, false otherwise</returns>
public virtual async Task<bool> TestServiceAsync(CancellationToken cancellationToken = default)
{
try
{
// Generate a simple test story
var story = await GenerateStoryAsync(
"A1",
"Test",
new List<string> { "Hallo", "Welt" },
50,
cancellationToken);
return !string.IsNullOrWhiteSpace(story);
}
catch (Exception ex)
{
_logger.LogError(ex, "Story generation service test failed");
return false;
}
}
} }

487
GermanApp/Application/Services/StoryService.cs Normal file
View file

@ -0,0 +1,487 @@
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using GermanApp.Application.DTOs;
using GermanApp.Domain.Entities;
using GermanApp.Domain.Interfaces;
using Microsoft.Extensions.Logging;
namespace GermanApp.Application.Services;
/// <summary>
/// Application service for managing story segments.
/// This is part of the Application layer.
/// </summary>
public class StoryService
{
private readonly IStoryRepository _storyRepository;
private readonly IStoryProgressRepository _progressRepository;
private readonly ILogger<StoryService> _logger;
/// <summary>
/// Creates a new StoryService.
/// </summary>
/// <param name="storyRepository">Repository for story segments</param>
/// <param name="progressRepository">Repository for story progress</param>
/// <param name="logger">Logger for service operations</param>
public StoryService(
IStoryRepository storyRepository,
IStoryProgressRepository progressRepository,
ILogger<StoryService> logger)
{
_storyRepository = storyRepository;
_progressRepository = progressRepository;
_logger = logger;
}
/// <summary>
/// Gets a story segment by its ID.
/// </summary>
/// <param name="id">The segment ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>The story segment DTO, or null if not found</returns>
public virtual async Task<StorySegmentDto?> GetByIdAsync(int id, CancellationToken cancellationToken = default)
{
_logger.LogInformation("Getting story segment by ID: {Id}", id);
var segment = await _storyRepository.GetByIdAsync(id, cancellationToken);
if (segment == null)
{
_logger.LogWarning("Story segment not found: {Id}", id);
return null;
}
return StorySegmentDto.FromEntity(segment);
}
/// <summary>
/// Gets all story segments for a specific level.
/// </summary>
/// <param name="levelId">The level ID</param>
/// <param name="includeInactive">Whether to include inactive segments</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>List of story segment DTOs</returns>
public virtual async Task<IReadOnlyList<StorySegmentDto>> GetByLevelAsync(
int levelId,
bool includeInactive = false,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Getting story segments for level: {LevelId}", levelId);
var segments = await _storyRepository.GetByLevelAsync(levelId, includeInactive, cancellationToken);
return segments.Select(StorySegmentDto.FromEntity).ToList();
}
/// <summary>
/// Gets all story segments for a specific lesson.
/// </summary>
/// <param name="lessonId">The lesson ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>List of story segment DTOs</returns>
public virtual async Task<IReadOnlyList<StorySegmentDto>> GetByLessonAsync(
int lessonId,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Getting story segments for lesson: {LessonId}", lessonId);
var segments = await _storyRepository.GetByLessonAsync(lessonId, cancellationToken);
return segments.Select(StorySegmentDto.FromEntity).ToList();
}
/// <summary>
/// Creates a new story segment.
/// </summary>
/// <param name="dto">The DTO containing segment data</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>The created story segment DTO</returns>
public virtual async Task<StorySegmentDto> CreateAsync(
CreateStorySegmentDto dto,
CancellationToken cancellationToken = default)
{
_logger.LogInformation(
"Creating story segment: LevelId={LevelId}, Order={Order}, Title={Title}",
dto.LevelId, dto.Order, dto.Title);
// Check if a segment with the same level and order already exists
var existing = await _storyRepository.GetByOrderRangeAsync(
dto.LevelId, dto.Order, dto.Order, cancellationToken);
if (existing.Any())
{
_logger.LogError(
"Story segment with LevelId={LevelId} and Order={Order} already exists",
dto.LevelId, dto.Order);
throw new InvalidOperationException(
$"A story segment with Order={dto.Order} already exists for level {dto.LevelId}");
}
// Create the entity
var segment = StorySegment.Create(
dto.LevelId,
dto.LessonId,
dto.Content,
dto.Order,
dto.Title,
dto.Theme,
dto.EstimatedReadingMinutes);
// Save to repository
var created = await _storyRepository.AddAsync(segment, cancellationToken);
_logger.LogInformation("Created story segment with ID: {Id}", created.Id);
return StorySegmentDto.FromEntity(created);
}
/// <summary>
/// Updates an existing story segment.
/// </summary>
/// <param name="id">The segment ID</param>
/// <param name="dto">The DTO containing updated data</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>The updated story segment DTO, or null if not found</returns>
public virtual async Task<StorySegmentDto?> UpdateAsync(
int id,
UpdateStorySegmentDto dto,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Updating story segment: {Id}", id);
var segment = await _storyRepository.GetByIdAsync(id, cancellationToken);
if (segment == null)
{
_logger.LogWarning("Story segment not found for update: {Id}", id);
return null;
}
// Apply updates
if (dto.Content != null)
segment.UpdateContent(dto.Content);
if (dto.Title != null)
segment.UpdateTitle(dto.Title);
if (dto.Theme != null)
segment.UpdateTheme(dto.Theme);
if (dto.Order != null)
segment.UpdateOrder(dto.Order.Value);
if (dto.EstimatedReadingMinutes != null)
segment.UpdateEstimatedReadingMinutes(dto.EstimatedReadingMinutes.Value);
if (dto.LessonId != null)
segment.UpdateLesson(dto.LessonId);
if (dto.IsActive != null)
{
if (dto.IsActive.Value)
segment.Activate();
else
segment.Deactivate();
}
// Save changes
await _storyRepository.UpdateAsync(segment, cancellationToken);
_logger.LogInformation("Updated story segment: {Id}", id);
return StorySegmentDto.FromEntity(segment);
}
/// <summary>
/// Deletes a story segment by its ID.
/// </summary>
/// <param name="id">The segment ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>True if the segment was deleted, false if not found</returns>
public virtual async Task<bool> DeleteAsync(int id, CancellationToken cancellationToken = default)
{
_logger.LogInformation("Deleting story segment: {Id}", id);
var exists = await _storyRepository.ExistsAsync(id, cancellationToken);
if (!exists)
{
_logger.LogWarning("Story segment not found for deletion: {Id}", id);
return false;
}
await _storyRepository.DeleteAsync(id, cancellationToken);
_logger.LogInformation("Deleted story segment: {Id}", id);
return true;
}
/// <summary>
/// Gets the next segment to unlock for a user after completing a lesson.
/// </summary>
/// <param name="levelId">The level ID</param>
/// <param name="completedLessonOrder">The order of the completed lesson</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>The next story segment DTO, or null if none</returns>
public virtual async Task<StorySegmentDto?> GetNextSegmentToUnlockAsync(
int levelId,
int completedLessonOrder,
CancellationToken cancellationToken = default)
{
_logger.LogInformation(
"Getting next segment to unlock for level {LevelId} after lesson {LessonOrder}",
levelId, completedLessonOrder);
var segment = await _storyRepository.GetNextSegmentToUnlockAsync(
levelId, completedLessonOrder, cancellationToken);
if (segment == null)
{
_logger.LogInformation("No segment to unlock for level {LevelId} after lesson {LessonOrder}",
levelId, completedLessonOrder);
return null;
}
return StorySegmentDto.FromEntity(segment);
}
/// <summary>
/// Checks if a user has unlocked a specific story segment.
/// </summary>
/// <param name="userId">The user ID</param>
/// <param name="segmentId">The segment ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>True if the segment is unlocked</returns>
public virtual async Task<bool> IsSegmentUnlockedAsync(
int userId,
int segmentId,
CancellationToken cancellationToken = default)
{
return await _progressRepository.IsSegmentUnlockedAsync(userId, segmentId, cancellationToken);
}
/// <summary>
/// Checks if a user has completed (read/listened to) a specific story segment.
/// </summary>
/// <param name="userId">The user ID</param>
/// <param name="segmentId">The segment ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>True if the segment is completed</returns>
public virtual async Task<bool> IsSegmentCompletedAsync(
int userId,
int segmentId,
CancellationToken cancellationToken = default)
{
return await _progressRepository.IsSegmentCompletedAsync(userId, segmentId, cancellationToken);
}
/// <summary>
/// Gets all segments that need audio generation.
/// </summary>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>List of story segment DTOs needing audio</returns>
public virtual async Task<IReadOnlyList<StorySegmentDto>> GetSegmentsNeedingAudioAsync(
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Getting story segments needing audio generation");
var segments = await _storyRepository.GetSegmentsNeedingAudioAsync(cancellationToken);
return segments.Select(StorySegmentDto.FromEntity).ToList();
}
/// <summary>
/// Updates the audio URL for a story segment.
/// </summary>
/// <param name="id">The segment ID</param>
/// <param name="audioUrl">The audio URL</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>The updated story segment DTO, or null if not found</returns>
public virtual async Task<StorySegmentDto?> UpdateAudioUrlAsync(
int id,
string audioUrl,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Updating audio URL for story segment: {Id}", id);
var segment = await _storyRepository.GetByIdAsync(id, cancellationToken);
if (segment == null)
{
_logger.LogWarning("Story segment not found for audio update: {Id}", id);
return null;
}
segment.UpdateAudioUrl(audioUrl);
await _storyRepository.UpdateAsync(segment, cancellationToken);
_logger.LogInformation("Updated audio URL for story segment: {Id}", id);
return StorySegmentDto.FromEntity(segment);
}
/// <summary>
/// Gets a user's progress through a story.
/// </summary>
/// <param name="userId">The user ID</param>
/// <param name="levelId">The level ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>Story progress DTO</returns>
public virtual async Task<StoryProgressDto> GetUserProgressAsync(
int userId,
int levelId,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Getting story progress for user {UserId} in level {LevelId}",
userId, levelId);
// Get all segments for the level
var segments = await _storyRepository.GetByLevelAsync(levelId, false, cancellationToken);
if (!segments.Any())
{
_logger.LogWarning("No story segments found for level: {LevelId}", levelId);
return new StoryProgressDto(
levelId,
"Unknown",
0,
0,
0,
Array.Empty<StorySegmentProgressDto>());
}
// Get user's progress for this level
var userProgress = await _progressRepository.GetByUserAndLevelAsync(userId, levelId, cancellationToken);
var totalSegments = segments.Count;
var unlockedSegments = userProgress.Count;
var highestUnlocked = await _progressRepository.GetHighestUnlockedOrderAsync(
userId, levelId, cancellationToken);
// Build segment progress list
var segmentProgress = new List<StorySegmentProgressDto>();
foreach (var segment in segments)
{
var isUnlocked = await _progressRepository.IsSegmentUnlockedAsync(
userId, segment.Id, cancellationToken);
var isCompleted = await _progressRepository.IsSegmentCompletedAsync(
userId, segment.Id, cancellationToken);
segmentProgress.Add(new StorySegmentProgressDto(
segment.Id,
segment.Order,
segment.Title,
isUnlocked,
isCompleted));
}
// Get level name from first segment (or use code as fallback)
var levelName = segments.First().Level?.Name ?? segments.First().Level?.Code ?? "Unknown";
return new StoryProgressDto(
levelId,
levelName,
totalSegments,
unlockedSegments,
highestUnlocked,
segmentProgress);
}
/// <summary>
/// Unlocks the next story segment for a user after completing a lesson.
/// </summary>
/// <param name="userId">The user ID</param>
/// <param name="levelId">The level ID</param>
/// <param name="completedLessonOrder">The order of the completed lesson</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>The unlocked story segment DTO, or null if none to unlock</returns>
public virtual async Task<StorySegmentDto?> UnlockNextSegmentAsync(
int userId,
int levelId,
int completedLessonOrder,
CancellationToken cancellationToken = default)
{
_logger.LogInformation(
"Unlocking next story segment for user {UserId} in level {LevelId} after lesson {LessonOrder}",
userId, levelId, completedLessonOrder);
// Get the next segment to unlock
var segment = await _storyRepository.GetNextSegmentToUnlockAsync(
levelId, completedLessonOrder, cancellationToken);
if (segment == null)
{
_logger.LogInformation(
"No segment to unlock for user {UserId} in level {LevelId} after lesson {LessonOrder}",
userId, levelId, completedLessonOrder);
return null;
}
// Check if user already has this segment unlocked
var alreadyUnlocked = await _progressRepository.IsSegmentUnlockedAsync(
userId, segment.Id, cancellationToken);
if (alreadyUnlocked)
{
_logger.LogInformation(
"Segment {SegmentId} already unlocked for user {UserId}",
segment.Id, userId);
return StorySegmentDto.FromEntity(segment);
}
// Create progress record
var progress = StoryProgress.Create(userId, levelId, segment.Id);
await _progressRepository.AddAsync(progress, cancellationToken);
_logger.LogInformation(
"Unlocked segment {SegmentId} for user {UserId} in level {LevelId}",
segment.Id, userId, levelId);
return StorySegmentDto.FromEntity(segment);
}
/// <summary>
/// Marks a story segment as completed (read/listened to) for a user.
/// </summary>
/// <param name="userId">The user ID</param>
/// <param name="segmentId">The segment ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>True if the segment was marked as completed, false if not found or already completed</returns>
public virtual async Task<bool> MarkSegmentAsCompletedAsync(
int userId,
int segmentId,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Marking segment {SegmentId} as completed for user {UserId}",
segmentId, userId);
var progress = await _progressRepository.GetByUserAndSegmentAsync(
userId, segmentId, cancellationToken);
if (progress == null)
{
_logger.LogWarning(
"Progress record not found for user {UserId} and segment {SegmentId}",
userId, segmentId);
return false;
}
if (progress.IsCompleted)
{
_logger.LogInformation("Segment already completed for user {UserId}", userId);
return false;
}
progress.MarkAsCompleted();
await _progressRepository.UpdateAsync(progress, cancellationToken);
_logger.LogInformation("Marked segment {SegmentId} as completed for user {UserId}",
segmentId, userId);
return true;
}
}

183
GermanApp/Application/Services/StoryUnlockService.cs Normal file
View file

@ -0,0 +1,183 @@
using System.Threading;
using System.Threading.Tasks;
using GermanApp.Application.DTOs;
using GermanApp.Domain.Entities;
using GermanApp.Domain.Interfaces;
using Microsoft.Extensions.Logging;
namespace GermanApp.Application.Services;
/// <summary>
/// Application service for managing story segment unlocking.
/// This service is called when a user completes a lesson to unlock the next story segment.
/// This is part of the Application layer.
/// </summary>
public class StoryUnlockService
{
private readonly StoryService _storyService;
private readonly IUserProgressRepository _userProgressRepository;
private readonly ILessonRepository _lessonRepository;
private readonly ILogger<StoryUnlockService> _logger;
/// <summary>
/// Creates a new StoryUnlockService.
/// </summary>
/// <param name="storyService">Service for story segment operations</param>
/// <param name="userProgressRepository">Repository for user progress</param>
/// <param name="lessonRepository">Repository for lessons</param>
/// <param name="logger">Logger for service operations</param>
public StoryUnlockService(
StoryService storyService,
IUserProgressRepository userProgressRepository,
ILessonRepository lessonRepository,
ILogger<StoryUnlockService> logger)
{
_storyService = storyService;
_userProgressRepository = userProgressRepository;
_lessonRepository = lessonRepository;
_logger = logger;
}
/// <summary>
/// Called when a user completes a lesson.
/// Checks if the user should unlock a new story segment and does so.
/// </summary>
/// <param name="userId">The user ID</param>
/// <param name="lessonId">The lesson ID that was completed</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>True if a new segment was unlocked, false otherwise</returns>
public virtual async Task<bool> HandleLessonCompletionAsync(
int userId,
int lessonId,
CancellationToken cancellationToken = default)
{
_logger.LogInformation(
"Handling lesson completion for user {UserId}, lesson {LessonId}",
userId, lessonId);
// Get the lesson to find its level and order
var lesson = await _lessonRepository.GetByIdAsync(lessonId, cancellationToken);
if (lesson == null)
{
_logger.LogWarning("Lesson not found: {LessonId}", lessonId);
return false;
}
// Check if this lesson completion qualifies for unlocking a story segment
// We need to check if the user has actually completed this lesson
var isCompleted = await _userProgressRepository.HasUserCompletedLessonAsync(
userId, lessonId, cancellationToken);
if (!isCompleted)
{
_logger.LogInformation(
"Lesson {LessonId} not marked as completed for user {UserId}",
lessonId, userId);
return false;
}
// Get the next story segment to unlock
var nextSegment = await _storyService.GetNextSegmentToUnlockAsync(
lesson.LevelId,
lesson.Order,
cancellationToken);
if (nextSegment == null)
{
_logger.LogInformation(
"No story segment to unlock for user {UserId} after lesson {LessonId}",
userId, lessonId);
return false;
}
// Check if user already has this segment unlocked
var alreadyUnlocked = await _storyService.IsSegmentUnlockedAsync(
userId, nextSegment.Id, cancellationToken);
if (alreadyUnlocked)
{
_logger.LogInformation(
"Segment {SegmentId} already unlocked for user {UserId}",
nextSegment.Id, userId);
return false;
}
// Unlock the segment
var unlockedSegment = await _storyService.UnlockNextSegmentAsync(
userId,
lesson.LevelId,
lesson.Order,
cancellationToken);
if (unlockedSegment != null)
{
_logger.LogInformation(
"Unlocked story segment {SegmentId} for user {UserId} after completing lesson {LessonId}",
unlockedSegment.Id, userId, lessonId);
return true;
}
return false;
}
/// <summary>
/// Checks if a user has unlocked a specific story segment.
/// </summary>
/// <param name="userId">The user ID</param>
/// <param name="segmentId">The segment ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>True if the segment is unlocked</returns>
public virtual async Task<bool> IsSegmentUnlockedAsync(
int userId,
int segmentId,
CancellationToken cancellationToken = default)
{
return await _storyService.IsSegmentUnlockedAsync(userId, segmentId, cancellationToken);
}
/// <summary>
/// Checks if a user has completed (read/listened to) a specific story segment.
/// </summary>
/// <param name="userId">The user ID</param>
/// <param name="segmentId">The segment ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>True if the segment is completed</returns>
public virtual async Task<bool> IsSegmentCompletedAsync(
int userId,
int segmentId,
CancellationToken cancellationToken = default)
{
return await _storyService.IsSegmentCompletedAsync(userId, segmentId, cancellationToken);
}
/// <summary>
/// Marks a story segment as completed for a user.
/// </summary>
/// <param name="userId">The user ID</param>
/// <param name="segmentId">The segment ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>True if the segment was marked as completed</returns>
public virtual async Task<bool> MarkSegmentAsCompletedAsync(
int userId,
int segmentId,
CancellationToken cancellationToken = default)
{
return await _storyService.MarkSegmentAsCompletedAsync(userId, segmentId, cancellationToken);
}
/// <summary>
/// Gets a user's story progress for a level.
/// </summary>
/// <param name="userId">The user ID</param>
/// <param name="levelId">The level ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>Story progress DTO</returns>
public virtual async Task<StoryProgressDto> GetUserProgressAsync(
int userId,
int levelId,
CancellationToken cancellationToken = default)
{
return await _storyService.GetUserProgressAsync(userId, levelId, cancellationToken);
}
}

2
GermanApp/Infrastructure/Data/Repositories/StoryProgressRepository.cs
View file

@ -57,7 +57,7 @@ public class StoryProgressRepository : IStoryProgressRepository
.Select(p => p.StorySegment != null ? p.StorySegment.Order : 0) .Select(p => p.StorySegment != null ? p.StorySegment.Order : 0)
.MaxAsync(cancellationToken); .MaxAsync(cancellationToken);
return highestOrder == null ? 0 : highestOrder; return highestOrder ?? 0;
} }
public async Task<bool> IsSegmentUnlockedAsync( public async Task<bool> IsSegmentUnlockedAsync(

2
GermanApp/Infrastructure/Data/Repositories/StoryRepository.cs
View file

@ -129,7 +129,7 @@ public class StoryRepository : IStoryRepository
.Select(s => s.Order) .Select(s => s.Order)
.MaxAsync(cancellationToken); .MaxAsync(cancellationToken);
return maxOrder == null ? 0 : maxOrder; return maxOrder ?? 0;
} }
public async Task<bool> ExistsAsync(int id, CancellationToken cancellationToken = default) public async Task<bool> ExistsAsync(int id, CancellationToken cancellationToken = default)

489
GermanApp/Presentation/Controllers/StoryController.cs Normal file
View file

@ -0,0 +1,489 @@
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using GermanApp.Application.DTOs;
using GermanApp.Application.Services;
using GermanApp.Domain.Interfaces;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
namespace GermanApp.Presentation.Controllers;
/// <summary>
/// API controller for story operations.
/// This is part of the Presentation layer.
/// </summary>
[ApiController]
[Route("api/[controller]")]
[Authorize]
public class StoryController : ControllerBase
{
private readonly StoryService _storyService;
private readonly StoryGenerationService _generationService;
private readonly StoryUnlockService _unlockService;
private readonly ILevelRepository _levelRepository;
private readonly ILessonRepository _lessonRepository;
private readonly ILogger<StoryController> _logger;
/// <summary>
/// Creates a new StoryController.
/// </summary>
/// <param name="storyService">Service for story operations</param>
/// <param name="generationService">Service for story generation</param>
/// <param name="unlockService">Service for story unlocking</param>
/// <param name="levelRepository">Repository for levels</param>
/// <param name="lessonRepository">Repository for lessons</param>
/// <param name="logger">Logger for controller operations</param>
public StoryController(
StoryService storyService,
StoryGenerationService generationService,
StoryUnlockService unlockService,
ILevelRepository levelRepository,
ILessonRepository lessonRepository,
ILogger<StoryController> logger)
{
_storyService = storyService;
_generationService = generationService;
_unlockService = unlockService;
_levelRepository = levelRepository;
_lessonRepository = lessonRepository;
_logger = logger;
}
/// <summary>
/// Gets all levels that have stories.
/// </summary>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>List of levels with story segments</returns>
[HttpGet("levels")]
public async Task<ActionResult<IReadOnlyList<LevelWithStoriesDto>>> GetLevelsWithStoriesAsync(
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Getting levels with stories");
var levels = await _levelRepository.GetAllOrderedAsync(cancellationToken);
var result = new List<LevelWithStoriesDto>();
foreach (var level in levels)
{
var segments = await _storyService.GetByLevelAsync(level.Id, false, cancellationToken);
var hasStories = segments.Count > 0;
result.Add(new LevelWithStoriesDto(
level.Id,
level.Name,
level.Code,
level.Order,
hasStories,
segments.Count));
}
return Ok(result);
}
/// <summary>
/// Gets all story segments for a specific level.
/// </summary>
/// <param name="levelId">The level ID</param>
/// <param name="includeInactive">Whether to include inactive segments</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>List of story segments for the level</returns>
[HttpGet("levels/{levelId}/segments")]
public async Task<ActionResult<IReadOnlyList<StorySegmentDto>>> GetSegmentsByLevelAsync(
int levelId,
[FromQuery] bool includeInactive = false,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Getting story segments for level {LevelId}", levelId);
var segments = await _storyService.GetByLevelAsync(levelId, includeInactive, cancellationToken);
if (!segments.Any())
{
_logger.LogWarning("No story segments found for level {LevelId}", levelId);
return NotFound();
}
return Ok(segments);
}
/// <summary>
/// Gets a specific story segment by ID.
/// </summary>
/// <param name="id">The segment ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>The story segment</returns>
[HttpGet("segments/{id}")]
public async Task<ActionResult<StorySegmentDto>> GetSegmentByIdAsync(
int id,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Getting story segment by ID: {Id}", id);
var segment = await _storyService.GetByIdAsync(id, cancellationToken);
if (segment == null)
{
_logger.LogWarning("Story segment not found: {Id}", id);
return NotFound();
}
return Ok(segment);
}
/// <summary>
/// Creates a new story segment (Admin only).
/// </summary>
/// <param name="dto">The DTO containing segment data</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>The created story segment</returns>
[HttpPost("segments")]
[Authorize(Roles = "Admin")]
public async Task<ActionResult<StorySegmentDto>> CreateSegmentAsync(
[FromBody] CreateStorySegmentDto dto,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Creating story segment");
try
{
var created = await _storyService.CreateAsync(dto, cancellationToken);
return CreatedAtAction(nameof(GetSegmentByIdAsync), new { id = created.Id }, created);
}
catch (InvalidOperationException ex)
{
_logger.LogError(ex, "Failed to create story segment");
return Conflict(ex.Message);
}
}
/// <summary>
/// Updates an existing story segment (Admin only).
/// </summary>
/// <param name="id">The segment ID</param>
/// <param name="dto">The DTO containing updated data</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>The updated story segment</returns>
[HttpPut("segments/{id}")]
[Authorize(Roles = "Admin")]
public async Task<ActionResult<StorySegmentDto>> UpdateSegmentAsync(
int id,
[FromBody] UpdateStorySegmentDto dto,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Updating story segment {Id}", id);
var updated = await _storyService.UpdateAsync(id, dto, cancellationToken);
if (updated == null)
{
_logger.LogWarning("Story segment not found for update: {Id}", id);
return NotFound();
}
return Ok(updated);
}
/// <summary>
/// Deletes a story segment (Admin only).
/// </summary>
/// <param name="id">The segment ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>No content if successful</returns>
[HttpDelete("segments/{id}")]
[Authorize(Roles = "Admin")]
public async Task<IActionResult> DeleteSegmentAsync(
int id,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Deleting story segment {Id}", id);
var deleted = await _storyService.DeleteAsync(id, cancellationToken);
if (!deleted)
{
_logger.LogWarning("Story segment not found for deletion: {Id}", id);
return NotFound();
}
return NoContent();
}
/// <summary>
/// Generates a story for a level using AI.
/// </summary>
/// <param name="levelId">The level ID</param>
/// <param name="request">The generation request</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>The generated story with segments</returns>
[HttpPost("levels/{levelId}/generate")]
[Authorize(Roles = "Admin")]
public async Task<ActionResult<StoryGenerationResponseDto>> GenerateStoryAsync(
int levelId,
[FromBody] StoryGenerationRequestDto request,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Generating story for level {LevelId} with theme '{Theme}'",
levelId, request.Theme);
try
{
// Get all lessons for the level
var lessons = await _lessonRepository.GetByLevelAsync(levelId, cancellationToken);
if (!lessons.Any())
{
_logger.LogWarning("No lessons found for level {LevelId}", levelId);
return BadRequest("No lessons found for this level");
}
var response = await _generationService.GenerateStoryAsync(
levelId,
request.Theme,
lessons,
cancellationToken);
return Ok(response);
}
catch (Exception ex)
{
_logger.LogError(ex, "Failed to generate story for level {LevelId}", levelId);
return StatusCode(500, ex.Message);
}
}
/// <summary>
/// Generates audio for a specific story segment.
/// </summary>
/// <param name="segmentId">The segment ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>The updated segment with audio URL</returns>
[HttpPost("segments/{segmentId}/audio")]
[Authorize(Roles = "Admin")]
public async Task<ActionResult<StorySegmentDto>> GenerateSegmentAudioAsync(
int segmentId,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Generating audio for story segment {SegmentId}", segmentId);
try
{
var result = await _generationService.GenerateAudioAsync(segmentId, cancellationToken);
if (result == null)
{
_logger.LogWarning("Segment not found or audio generation failed: {SegmentId}", segmentId);
return NotFound();
}
return Ok(result);
}
catch (Exception ex)
{
_logger.LogError(ex, "Failed to generate audio for segment {SegmentId}", segmentId);
return StatusCode(500, ex.Message);
}
}
/// <summary>
/// Gets the user's progress through a story for a level.
/// </summary>
/// <param name="levelId">The level ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>The user's story progress</returns>
[HttpGet("levels/{levelId}/progress")]
public async Task<ActionResult<StoryProgressDto>> GetUserProgressAsync(
int levelId,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Getting story progress for user in level {LevelId}", levelId);
var userId = GetUserId();
var progress = await _unlockService.GetUserProgressAsync(userId, levelId, cancellationToken);
return Ok(progress);
}
/// <summary>
/// Marks a story segment as completed (read/listened to).
/// </summary>
/// <param name="segmentId">The segment ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>No content if successful</returns>
[HttpPost("segments/{segmentId}/complete")]
public async Task<IActionResult> MarkSegmentAsCompletedAsync(
int segmentId,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Marking segment {SegmentId} as completed", segmentId);
var userId = GetUserId();
var success = await _unlockService.MarkSegmentAsCompletedAsync(
userId, segmentId, cancellationToken);
if (!success)
{
_logger.LogWarning("Failed to mark segment {SegmentId} as completed for user {UserId}",
segmentId, userId);
return NotFound();
}
return NoContent();
}
/// <summary>
/// Gets the next story segment for a user to read.
/// </summary>
/// <param name="levelId">The level ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>The next segment to read</returns>
[HttpGet("levels/{levelId}/next")]
public async Task<ActionResult<StorySegmentDto?>> GetNextSegmentAsync(
int levelId,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Getting next story segment for user in level {LevelId}", levelId);
var userId = GetUserId();
// Get user's progress
var progress = await _unlockService.GetUserProgressAsync(userId, levelId, cancellationToken);
// Find the first unlocked but not completed segment
foreach (var segmentProgress in progress.Segments.OrderBy(s => s.Order))
{
if (segmentProgress.IsUnlocked && !segmentProgress.IsCompleted)
{
var segment = await _storyService.GetByIdAsync(segmentProgress.SegmentId, cancellationToken);
if (segment != null)
{
return Ok(segment);
}
}
}
// If no segment is unlocked, check if we can unlock one
// This would typically be triggered by lesson completion, but we can check here too
return Ok(null); // No segment available
}
/// <summary>
/// Checks if a specific segment is unlocked for the current user.
/// </summary>
/// <param name="segmentId">The segment ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>True if unlocked</returns>
[HttpGet("segments/{segmentId}/unlocked")]
public async Task<ActionResult<bool>> IsSegmentUnlockedAsync(
int segmentId,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Checking if segment {SegmentId} is unlocked", segmentId);
var userId = GetUserId();
var isUnlocked = await _unlockService.IsSegmentUnlockedAsync(userId, segmentId, cancellationToken);
return Ok(isUnlocked);
}
/// <summary>
/// Gets the audio file for a story segment.
/// </summary>
/// <param name="segmentId">The segment ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>The audio file</returns>
[HttpGet("segments/{segmentId}/audio")]
public async Task<IActionResult> GetSegmentAudioAsync(
int segmentId,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Getting audio for segment {SegmentId}", segmentId);
var segment = await _storyService.GetByIdAsync(segmentId, cancellationToken);
if (segment == null || string.IsNullOrEmpty(segment.AudioUrl))
{
_logger.LogWarning("Segment not found or no audio: {SegmentId}", segmentId);
return NotFound();
}
// In a real implementation, return the actual file
// For now, return the URL
return Ok(new { AudioUrl = segment.AudioUrl });
}
/// <summary>
/// Gets all lessons in a level with their associated story segments.
/// </summary>
/// <param name="levelId">The level ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>List of lessons with story segment status</returns>
[HttpGet("levels/{levelId}/lessons-with-stories")]
public async Task<ActionResult<IReadOnlyList<LessonWithStoryStatusDto>>> GetLessonsWithStoryStatusAsync(
int levelId,
CancellationToken cancellationToken = default)
{
_logger.LogInformation("Getting lessons with story status for level {LevelId}", levelId);
var lessons = await _lessonRepository.GetByLevelAsync(levelId, cancellationToken);
var segments = await _storyService.GetByLevelAsync(levelId, false, cancellationToken);
var result = new List<LessonWithStoryStatusDto>();
foreach (var lesson in lessons)
{
var lessonSegments = segments.Where(s => s.LessonId == lesson.Id).ToList();
result.Add(new LessonWithStoryStatusDto(
lesson.Id,
lesson.Title,
lesson.Order,
lesson.Topic,
lessonSegments.Count > 0,
lessonSegments.Count));
}
return Ok(result);
}
/// <summary>
/// Gets the current user's ID from the JWT claims.
/// </summary>
/// <returns>The user ID</returns>
private int GetUserId()
{
var userIdClaim = User.FindFirst("sub") ?? User.FindFirst("nameidentifier");
if (userIdClaim == null || !int.TryParse(userIdClaim.Value, out var userId))
{
throw new UnauthorizedAccessException("User ID not found in token");
}
return userId;
}
}
/// <summary>
/// DTO for level with story information.
/// </summary>
public record LevelWithStoriesDto(
int Id,
string Name,
string Code,
int Order,
bool HasStories,
int StorySegmentCount);
/// <summary>
/// DTO for lesson with story segment status.
/// </summary>
public record LessonWithStoryStatusDto(
int Id,
string Title,
int Order,
string Topic,
bool HasStorySegment,
int StorySegmentCount);

6
GermanApp/Program.cs
View file

@ -138,6 +138,8 @@ try
builder.Services.AddScoped<IQuizRepository, QuizRepository>(); builder.Services.AddScoped<IQuizRepository, QuizRepository>();
builder.Services.AddScoped<IQuizQuestionRepository, QuizQuestionRepository>(); builder.Services.AddScoped<IQuizQuestionRepository, QuizQuestionRepository>();
builder.Services.AddScoped<IQuizOptionRepository, QuizOptionRepository>(); builder.Services.AddScoped<IQuizOptionRepository, QuizOptionRepository>();
builder.Services.AddScoped<IStoryRepository, StoryRepository>();
builder.Services.AddScoped<IStoryProgressRepository, StoryProgressRepository>();
// ============================================ // ============================================
// INFRASTRUCTURE LAYER - AI Services // INFRASTRUCTURE LAYER - AI Services
@ -200,6 +202,10 @@ try
builder.Services.AddScoped<SpeechExerciseService>(); builder.Services.AddScoped<SpeechExerciseService>();
builder.Services.AddScoped<AudioGenerationService>(); builder.Services.AddScoped<AudioGenerationService>();
builder.Services.AddScoped<AiFallbackService>(); builder.Services.AddScoped<AiFallbackService>();
// Register Story services
builder.Services.AddScoped<StoryService>();
builder.Services.AddScoped<StoryUnlockService>();
builder.Services.AddScoped<ICommandHandler<CreateLessonCommand, LessonDto>, CreateLessonCommandHandler>(); builder.Services.AddScoped<ICommandHandler<CreateLessonCommand, LessonDto>, CreateLessonCommandHandler>();
// Note: QuizQuestionService requires IQuizRepository, ILessonRepository, and ProgressService which are registered above // Note: QuizQuestionService requires IQuizRepository, ILessonRepository, and ProgressService which are registered above

26
docs/features/story-integration.md
View file

@ -1,7 +1,7 @@
# Feature: Story Integration # Feature: Story Integration
> **Status**: 🚀 In Progress > **Status**: 🚀 In Progress
> **📊 Current Progress**: Phase 1 ✅ Complete (Database & Models), Phase 2 Started (Backend Services) > **📊 Current Progress**: Phase 1-2 ✅ Complete (Database & Models, Backend Services), Phase 3 Started (AI Integration)
> **Priority**: High > **Priority**: High
> **Complexity**: High > **Complexity**: High
> **Estimate**: 8-12 hours > **Estimate**: 8-12 hours
@ -142,11 +142,11 @@ Order: 1
- [ ] Create and apply migration for StorySegments and StoryProgress tables - [ ] Create and apply migration for StorySegments and StoryProgress tables
### Phase 2: Backend Services (2-3 hours) ### Phase 2: Backend Services (2-3 hours)
- [ ] Create StoryService with CRUD operations - [x] Create StoryService with CRUD operations (Application/Services/StoryService.cs)
- [ ] Create StoryGenerationService for AI integration - [x] Create StoryGenerationService for AI integration (Application/Services/StoryGenerationService.cs)
- [ ] Implement story segment generation using MistralService - [x] Implement story segment generation using MistralService
- [ ] Implement audio generation using AudioGenerationService - [x] Implement audio generation using ITtsService
- [ ] Create StoryUnlockService for progress management - [x] Create StoryUnlockService for progress management (Application/Services/StoryUnlockService.cs)
- [ ] Write unit tests for services - [ ] Write unit tests for services
### Phase 2: Backend Services (2-3 hours) ### Phase 2: Backend Services (2-3 hours)
@ -191,8 +191,8 @@ Order: 1
| Milestone | Date | Status | | Milestone | Date | Status |
|-----------|------|--------| |-----------|------|--------|
| Database & Models | June 13, 2025 | ✅ | | Database & Models | June 13, 2025 | ✅ |
| Backend Services | - | 🚀 In Progress | | Backend Services | June 13, 2025 | ✅ |
| AI Integration | - | ⏳ | | AI Integration | - | 🚀 In Progress |
| Audio Generation | - | ⏳ | | Audio Generation | - | ⏳ |
| Frontend Integration | - | ⏳ | | Frontend Integration | - | ⏳ |
| User Progress | - | ⏳ | | User Progress | - | ⏳ |
@ -212,11 +212,11 @@ Order: 1
- [x] Create Infrastructure/Data/Repositories/StoryProgressRepository.cs - [x] Create Infrastructure/Data/Repositories/StoryProgressRepository.cs
- [x] Add DbSets and configurations to AppDbContext - [x] Add DbSets and configurations to AppDbContext
- [x] Update Level, Lesson, and User entities with navigation properties - [x] Update Level, Lesson, and User entities with navigation properties
- [ ] Create Application/Services/StoryService.cs - [x] Create Application/Services/StoryService.cs
- [ ] Create StoryGenerationService (adapt existing from AI Services) - [x] Create Application/Services/StoryGenerationService.cs (uses IMistralService, ITtsService)
- [ ] Create StoryUnlockService for progress management - [x] Create Application/Services/StoryUnlockService.cs (handles lesson completion → story unlocking)
- [ ] Create Presentation/Controllers/StoryController.cs - [x] Create Presentation/Controllers/StoryController.cs (12 endpoints)
- [ ] Register services in Program.cs - [x] Register services in Program.cs (IStoryRepository, IStoryProgressRepository, StoryService, StoryGenerationService, StoryUnlockService)
- [ ] Write unit tests - [ ] Write unit tests
- [ ] Write integration tests - [ ] Write integration tests