Refactoring and fixes on API v3

[ildyria]

Fixes #4717

Summary by CodeRabbit

• New Features

  • Unified album and photo bucket recomputation under the lychee:recompute-buckets command.
  • Timeline headers and grouping now appear only when the relevant album or photo timeline setting is enabled.
  • Shared album views now consistently hide publicly owned albums when configured for separate shared content.

• Bug Fixes

  • Photo and album layouts now remain continuous when timeline display is disabled.

• Documentation

  • Updated command references across technical documentation and service guidance.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: ebc18d09-4d37-4940-b643-d213d89abb6e

📥 Commits

Reviewing files that changed from the base of the PR and between 6ea3493 and 5b8dab1.

📒 Files selected for processing (1)

• app/Console/Commands/RecomputeBuckets.php

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

The PR replaces separate album and photo bucket commands with lychee:recompute-buckets. It updates related tests and documentation. It also gates virtualized timeline headers and filters public shared-root albums in separate_shared_only mode.

Changes

Bucket recomputation command

Layer / File(s)	Summary
Unified bucket recomputation app/Console/Commands/RecomputeBuckets.php, app/Console/Commands/RecomputeAlbumBuckets.php, app/Console/Commands/RecomputePhotoBuckets.php	The new command recomputes album and photo bucket IDs in separate chunked passes. The previous commands are deleted.
Unified recomputation coverage tests/Precomputing/CoverSelection/RecomputeBucketsCommandTest.php, tests/Precomputing/CoverSelection/RecomputeAlbumBucketsCommandTest.php	Tests now cover album and photo recomputation, empty tables, configuration changes, and per-album settings through the unified command.
Command reference updates app/Services/*BucketComputer.php, database/migrations/..., docs/specs/...	Comments, deployment instructions, specifications, and the architecture map now use lychee:recompute-buckets.

Gallery display filtering

Layer / File(s)	Summary
Album timeline display gates resources/js/composables/album/dragAndSelect.ts, resources/js/v8/components/gallery/albumModule/Virtualized/Album*ViewVirtual.vue, resources/js/v8/components/gallery/albumModule/Virtualized/AlbumThumbGridVirtual.vue	Album header rendering and hit-box layout now require the applicable album timeline setting.
Photo timeline display gates resources/js/composables/album/dragAndSelect.ts, resources/js/v8/components/gallery/albumModule/Virtualized/PhotoGridVirtual.vue	Photo header rendering and row packing now require the photo timeline setting.
Shared root album filtering resources/js/v8/components/gallery/albumModule/Virtualized/AlbumRootGridVirtual.vue, resources/js/v8/components/gallery/albumModule/Virtualized/AlbumRootListViewVirtual.vue	Public albums are excluded from shared-root views when shared_albums_visibility_mode is separate_shared_only.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Severity of issue fixed: Medium

Merge Risk: 🟡 Moderate · up to 5b8da

Separate-shared-only views may filter public albums while drag selection still accounts for them, causing misaligned interactions. Bucket recomputation coverage also does not fully prove child-album behavior, so these correctness risks should be resolved before merge.

🚥 Pre-merge checks | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 15 functions across 6 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

• Fix all pre-merge checks with AI

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit reads each line,
The patch grows clear beneath the moon,
Small changes hop in place,
Tests guard the garden path,
Reviews bloom before the dawn.}

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

resources/js/composables/album/dragAndSelect.ts (1)

291-295: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Filter public shared albums before computing drag boxes.

When shared_albums_visibility_mode is separate_shared_only, the root virtual views remove public albums before row chunking. This path still includes them. A public album before a directly shared album shifts later hit boxes. Drag selection can then miss or select the wrong visible album.

Proposed fix

-				(album) => !album.is_nsfw || lycheeStore.are_nsfw_visible,
+				(album) =>
+					(!album.is_nsfw || lycheeStore.are_nsfw_visible) &&
+					!(
+						scope === "shared" &&
+						albumsStore.rootConfig?.shared_albums_visibility_mode === "separate_shared_only" &&
+						album.is_public
+					),

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 5fb80e4e-b477-495d-8597-c709878cecb8

📥 Commits

Reviewing files that changed from the base of the PR and between 17bcae8 and 6ea3493.

📒 Files selected for processing (16)

• app/Console/Commands/RecomputeAlbumBuckets.php
• app/Console/Commands/RecomputePhotoBuckets.php
• app/Services/AlbumBucketComputer.php
• app/Services/PhotoBucketComputer.php
• database/migrations/2026_09_05_120004_remove_owner_id_album_sorting.php
• docs/specs/3-reference/api-design.md
• docs/specs/3-reference/database-schema.md
• docs/specs/4-architecture/knowledge-map.md
• resources/js/composables/album/dragAndSelect.ts
• resources/js/v8/components/gallery/albumModule/Virtualized/AlbumListViewVirtual.vue
• resources/js/v8/components/gallery/albumModule/Virtualized/AlbumRootGridVirtual.vue
• resources/js/v8/components/gallery/albumModule/Virtualized/AlbumRootListViewVirtual.vue
• resources/js/v8/components/gallery/albumModule/Virtualized/AlbumThumbGridVirtual.vue
• resources/js/v8/components/gallery/albumModule/Virtualized/PhotoGridVirtual.vue
• tests/Precomputing/CoverSelection/RecomputeAlbumBucketsCommandTest.php
• tests/Precomputing/CoverSelection/RecomputeBucketsCommandTest.php

💤 Files with no reviewable changes (3)

• app/Console/Commands/RecomputePhotoBuckets.php
• app/Console/Commands/RecomputeAlbumBuckets.php
• tests/Precomputing/CoverSelection/RecomputeAlbumBucketsCommandTest.php

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.93%. Comparing base (17bcae8) to head (5b8dab1).
⚠️ Report is 1 commits behind head on master.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.