Blog Module - Feature List

1. Feature Overview

Blog module supports admin authoring and public consumption:

• Admin post lifecycle: create, update, delete, publish, unpublish
• Admin category lifecycle: create, update, delete with safety checks
• Product linking per post (blog_post_product)
• FAQ block per post (blog_post_faq)
• CTA block per post (blog_cta_block)
• Video block per post (blog_post_video) with per-video SEO metadata linkage
• Public listing/detail/category APIs
• Slug-history fallback for old blog URLs
• Redis-backed cache on public reads with admin mutation invalidation

2. Route Ownership and Surfaces

Swagger tags:

• Blog Posts (Admin)
• Blog (Admin)
• Blog

3. Admin Feature Matrix

4. Public/Mobile Feature Matrix

Equivalent mobile endpoints:

• GET /api/mobile/blogs
• GET /api/mobile/blogs/categories
• GET /api/mobile/blogs/:slug

5. Key Business Rules

• Public APIs return published posts only.
• Slug fallback is allowed only when target post is currently published.
• Category delete is blocked if any blog post references the category.
• Product linking from admin accepts published products only.
• FAQ/CTA are modeled as write-replace payloads on create/update.
• Videos are modeled as write-replace payloads on create/update.
• Each video requires a valid seoId; each seoId can be linked to only one blog video globally.
• Post search and category search use trigram-style behavior (ILIKE + similarity).

6. Slug Lifecycle

6.1 Admin slug generation

• Normalize input to URL-safe base slug.
• Check uniqueness against:
  • current post slugs (blog_post.slug)
  • historical slugs (blog_slug_history.old_slug)
• Collision strategy: slug, slug-1, slug-2, … up to max attempts, then timestamp fallback.

6.2 Slug history fallback (public)

GET /blogs/:slug resolution order:

1. Direct hit in blog_post.slug with status='published'
2. Fallback hit in blog_slug_history.old_slug joined to blog_post with status='published'

No redirect is emitted. Response always represents the current canonical post record.

7. Structured Data Surface

Public detail returns server-built structured-data payload:

• Article
• Article.video as VideoObject[] when post videos exist
• FAQPage (only when FAQ rows exist)
• BreadcrumbList

This is returned in API response so frontend can render JSON-LD script tags deterministically.

8. Cache Strategy

Public keyspaces:

• blog:posts:list:*
• blog:post:slug:*
• blog:categories:*

Invalidation behavior:

• Admin post mutations invalidate blog:*
• Admin category mutations invalidate blog:*

9. Rate Limiting

Admin blog endpoints use existing IP throttle guard with per-route policy:

• Reads: 30/min
• Writes: 10/min

Public blog endpoints are cache-backed and unauthenticated (@Public()), following existing shared public-module behavior.

10. Error UX Mapping

11. Release/QA Checklist

• Public list returns only published posts and correct pagination envelope.
• Public slug endpoint resolves both current and historical slugs.
• Historical slug fallback does not leak drafts.
• Category post counts reflect published-only rows.
• Admin post update persists product links in deterministic order.
• Admin FAQ/CTA create-update-delete flows persist correctly.
• Admin video create-update-delete flows persist correctly.
• Invalid/missing video seoId is rejected.
• Reusing a video seoId already linked to another post is rejected.
• blog:* invalidation runs on all admin mutations.
• Mobile-composed routes (/api/mobile/blogs/...) resolve correctly.

12. Integration Flows

12.1 Public Read Flow

1. Client requests GET /api/blogs (or /api/mobile/blogs).
2. Service computes deterministic cache key from query.
3. On cache miss, DB query fetches published posts + category info.
4. Response wrapped in ResponseDto with pagination metadata.

12.2 Slug Fallback Flow

1. Client requests GET /api/blogs/:slug.
2. Service attempts direct published-slug lookup.
3. If no direct hit, service checks slug-history join with published status guard.
4. If found, returns canonical current post payload; else BLOG_POST_NOT_FOUND.

12.3 Admin Mutation Flow

1. Admin calls create/update/delete/publish/unpublish.
2. Service applies transactional writes (post + relations).
3. Service writes activity record where applicable.
4. Service invalidates blog:* public cache namespace.

Time fields in this module should be handled as ISO-8601 instants by clients.

---

See Also

• Backend Reference: Blog - Backend Documentation
• API Contracts: Blog - API & Integration Guide