Group recitation collection

[Lungsangg]

RFC: Group Recitation Collections

Summary

Add group-owned recitation collections so Author Groups can curate ordered text lists for members and the public. This mirrors the existing user recitation collections but is managed through CMS.

Goals

• Groups can create multiple recitation collections.
• Collections contain ordered texts (text_id, display_order).
• CMS users with group permissions can manage collections.
• Public clients can view collections.
• Reuse existing text resolution, presigned URLs, and permission helpers.

Data Model

group_recitation_collections

Column	Notes
id	UUID PK
group_id	FK → author_groups
name	Collection name
img_url	S3 key
created_at / updated_at / deleted_at	Timestamps
created_by / updated_by	Audit fields

group_recitation_collection_items

Column	Notes
id	UUID PK
group_recitation_collection_id	FK
text_id	Text reference
display_order	Item order

Constraints

• UNIQUE(collection_id, text_id)
• Cascade delete on collection.

Permissions

Action	Permission
Read	require_can_read_group_content
Create	require_can_create_content
Update	require_can_edit_content
Delete	require_can_change_status

API

Public

Method	Endpoint
GET	/author/groups/{group_id}/recitation-collections
GET	/author/groups/{group_id}/recitation-collections/{collection_id}

CMS

Method	Endpoint
POST	/cms/groups/{group_id}/recitation-collections
GET	/cms/groups/{group_id}/recitation-collections
GET	/cms/groups/{group_id}/recitation-collections/{collection_id}
PUT	/cms/groups/{group_id}/recitation-collections/{collection_id}
DELETE	/cms/groups/{group_id}/recitation-collections/{collection_id}
POST	/cms/groups/{group_id}/recitation-collections/{collection_id}/items
PUT	/cms/groups/{group_id}/recitation-collections/{collection_id}/items/reorder
DELETE	/cms/groups/{group_id}/recitation-collections/{collection_id}/items/{item_id}

Implementation Phases

Phase 1

• Models
• Alembic migration
• Repository
• Unit tests

Phase 2

• Public read APIs
• Presigned image URLs
• Text metadata resolution
• Region & visibility filtering

Phase 3

• CMS CRUD
• Add/remove/reorder items
• Soft delete collections

Module Structure

pecha_api/group_recitation_collection/
├── models.py
├── repository.py
├── service.py
├── response_models.py
├── views.py
└── cms_views.py

Notes

• Store S3 key; return presigned URL.
• Soft delete collections using deleted_at.
• Cascade delete when a group is deleted.
• Reuse existing DTOs by adding group_id.
• Add GROUP_RECITATION_COLLECTION to region restriction handling.