| | | 1 | | using Chronicis.Shared.DTOs; |
| | | 2 | | |
| | | 3 | | namespace Chronicis.Api.Services; |
| | | 4 | | |
| | | 5 | | /// <summary> |
| | | 6 | | /// Centralised service for walking article parent hierarchies. |
| | | 7 | | /// Replaces duplicated parent-walk logic formerly in ArticleService, |
| | | 8 | | /// PublicWorldService, SearchController, ArticlesController, and WorldsController. |
| | | 9 | | /// </summary> |
| | | 10 | | public interface IArticleHierarchyService |
| | | 11 | | { |
| | | 12 | | /// <summary> |
| | | 13 | | /// Build an ordered breadcrumb trail from the root (optionally including the world) |
| | | 14 | | /// down to the specified article. |
| | | 15 | | /// </summary> |
| | | 16 | | Task<List<BreadcrumbDto>> BuildBreadcrumbsAsync(Guid articleId, HierarchyWalkOptions? options = null); |
| | | 17 | | |
| | | 18 | | /// <summary> |
| | | 19 | | /// Build a slash-separated path string from slugs (e.g. "world-slug/parent-slug/child-slug"). |
| | | 20 | | /// Convenience wrapper around <see cref="BuildBreadcrumbsAsync"/>. |
| | | 21 | | /// </summary> |
| | | 22 | | Task<string> BuildPathAsync(Guid articleId, HierarchyWalkOptions? options = null); |
| | | 23 | | |
| | | 24 | | /// <summary> |
| | | 25 | | /// Build a human-readable display path of titles joined with " / ". |
| | | 26 | | /// Optionally strips the first level (world root) for display in link suggestions / backlinks. |
| | | 27 | | /// </summary> |
| | | 28 | | Task<string> BuildDisplayPathAsync(Guid articleId, bool stripFirstLevel = true); |
| | | 29 | | } |
| | | 30 | | |
| | | 31 | | /// <summary> |
| | | 32 | | /// Options that control how the hierarchy walk behaves. |
| | | 33 | | /// </summary> |
| | | 34 | | public class HierarchyWalkOptions |
| | | 35 | | { |
| | | 36 | | /// <summary> |
| | | 37 | | /// When true, only articles with Public visibility are included in the walk. |
| | | 38 | | /// If a non-public article is encountered mid-chain the walk stops. |
| | | 39 | | /// </summary> |
| | 42 | 40 | | public bool PublicOnly { get; set; } = false; |
| | | 41 | | |
| | | 42 | | /// <summary> |
| | | 43 | | /// When true, a World breadcrumb is prepended to the result. |
| | | 44 | | /// Requires the target article to have a WorldId. |
| | | 45 | | /// </summary> |
| | 35 | 46 | | public bool IncludeWorldBreadcrumb { get; set; } = true; |
| | | 47 | | |
| | | 48 | | /// <summary> |
| | | 49 | | /// When true, virtual group breadcrumbs (Campaigns, Player Characters, Wiki) |
| | | 50 | | /// are inserted between the World breadcrumb and the article chain. |
| | | 51 | | /// Only meaningful when <see cref="IncludeWorldBreadcrumb"/> is also true. |
| | | 52 | | /// </summary> |
| | 20 | 53 | | public bool IncludeVirtualGroups { get; set; } = false; |
| | | 54 | | |
| | | 55 | | /// <summary> |
| | | 56 | | /// When true (default), the target article itself is included as the last breadcrumb. |
| | | 57 | | /// Set to false when you only need the ancestor chain above the article. |
| | | 58 | | /// </summary> |
| | 37 | 59 | | public bool IncludeCurrentArticle { get; set; } = true; |
| | | 60 | | |
| | | 61 | | /// <summary> |
| | | 62 | | /// Pre-resolved world metadata. When supplied, skips the world lookup query. |
| | | 63 | | /// Required when <see cref="IncludeVirtualGroups"/> is true. |
| | | 64 | | /// </summary> |
| | 29 | 65 | | public WorldContext? World { get; set; } |
| | | 66 | | } |
| | | 67 | | |
| | | 68 | | /// <summary> |
| | | 69 | | /// Pre-resolved world information to avoid redundant DB lookups |
| | | 70 | | /// when the caller already has it. |
| | | 71 | | /// </summary> |
| | | 72 | | public class WorldContext |
| | | 73 | | { |
| | | 74 | | public Guid Id { get; set; } |
| | | 75 | | public string Name { get; set; } = string.Empty; |
| | | 76 | | public string Slug { get; set; } = string.Empty; |
| | | 77 | | } |