照片列表支持分页

test/integration/server_test.dart

@@ -254,12 +254,16 @@ void main() {
 
         final response = await server.get('/api/v1/album/$albumId/photo');
         expect(response.statusCode, 200);
-        final photos = jsonDecode(response.body) as List;
+        final body = jsonDecode(response.body) as Map;
+        final photos = body['items'] as List;
         expect(photos, isNotEmpty);
         expect(photos.first['fileName'], 'image.png');
         expect(photos.first['mimeType'], 'image/png');
         expect(photos.first['width'], 640);
         expect(photos.first['height'], 480);
+        expect(body['total'], 1);
+        expect(body['page'], 1);
+        expect(body['size'], 20);
       });
 
       test(
@@ -272,12 +276,135 @@ void main() {
 
           final response = await server.get('/api/v1/album/$albumId/photo');
           expect(response.statusCode, 200);
-          final photos = jsonDecode(response.body) as List;
+          final body = jsonDecode(response.body) as Map;
+          final photos = body['items'] as List;
           expect(photos, isEmpty);
+          expect(body['total'], 0);
         },
       );
     });
 
+    group('Pagination', () {
+      test(
+        'returns first page with default size when no query params',
+        () async {
+          final photos = List.generate(
+            25,
+            (i) => ('photo_$i.png', _createTestPng()),
+          );
+          server = await TestServer.start(testAlbums: {'paged_album': photos});
+          final listResponse = await server.get('/api/v1/album');
+          final albums = jsonDecode(listResponse.body) as List;
+          final albumId = albums.first['id'];
+
+          final response = await server.get('/api/v1/album/$albumId/photo');
+          final body = jsonDecode(response.body) as Map;
+          expect(body['total'], 25);
+          expect(body['page'], 1);
+          expect(body['size'], 20);
+          expect((body['items'] as List).length, 20);
+        },
+      );
+
+      test('respects custom page and size parameters', () async {
+        final photos = List.generate(
+          10,
+          (i) => ('photo_$i.png', _createTestPng()),
+        );
+        server = await TestServer.start(testAlbums: {'small_album': photos});
+        final listResponse = await server.get('/api/v1/album');
+        final albums = jsonDecode(listResponse.body) as List;
+        final albumId = albums.first['id'];
+
+        final response = await server.get(
+          '/api/v1/album/$albumId/photo?page=2&size=3',
+        );
+        final body = jsonDecode(response.body) as Map;
+        expect(body['total'], 10);
+        expect(body['page'], 2);
+        expect(body['size'], 3);
+        expect((body['items'] as List).length, 3);
+      });
+
+      test('returns partial last page', () async {
+        final photos = List.generate(
+          5,
+          (i) => ('photo_$i.png', _createTestPng()),
+        );
+        server = await TestServer.start(testAlbums: {'five_photos': photos});
+        final listResponse = await server.get('/api/v1/album');
+        final albums = jsonDecode(listResponse.body) as List;
+        final albumId = albums.first['id'];
+
+        final response = await server.get(
+          '/api/v1/album/$albumId/photo?page=2&size=3',
+        );
+        final body = jsonDecode(response.body) as Map;
+        expect(body['total'], 5);
+        expect(body['page'], 2);
+        expect(body['size'], 3);
+        expect((body['items'] as List).length, 2);
+      });
+
+      test('returns empty items when page exceeds total', () async {
+        final photos = List.generate(
+          3,
+          (i) => ('photo_$i.png', _createTestPng()),
+        );
+        server = await TestServer.start(testAlbums: {'three_photos': photos});
+        final listResponse = await server.get('/api/v1/album');
+        final albums = jsonDecode(listResponse.body) as List;
+        final albumId = albums.first['id'];
+
+        final response = await server.get(
+          '/api/v1/album/$albumId/photo?page=10&size=5',
+        );
+        final body = jsonDecode(response.body) as Map;
+        expect(body['total'], 3);
+        expect(body['page'], 10);
+        expect(body['size'], 5);
+        expect((body['items'] as List), isEmpty);
+      });
+
+      test('page=1 returns items from the beginning', () async {
+        final photos = List.generate(
+          5,
+          (i) => ('photo_$i.png', _createTestPng()),
+        );
+        server = await TestServer.start(testAlbums: {'ordered_photos': photos});
+        final listResponse = await server.get('/api/v1/album');
+        final albums = jsonDecode(listResponse.body) as List;
+        final albumId = albums.first['id'];
+
+        final response = await server.get(
+          '/api/v1/album/$albumId/photo?page=1&size=2',
+        );
+        final body = jsonDecode(response.body) as Map;
+        final items = body['items'] as List;
+        expect(items.length, 2);
+        expect(items[0]['fileName'], 'photo_0.png');
+        expect(items[1]['fileName'], 'photo_1.png');
+      });
+
+      test('uses defaults when page/size are invalid strings', () async {
+        server = await TestServer.start(
+          testAlbums: {
+            'defaults_album': [('image.png', _createTestPng())],
+          },
+        );
+        final listResponse = await server.get('/api/v1/album');
+        final albums = jsonDecode(listResponse.body) as List;
+        final albumId = albums.first['id'];
+
+        final response = await server.get(
+          '/api/v1/album/$albumId/photo?page=abc&size=xyz',
+        );
+        final body = jsonDecode(response.body) as Map;
+        expect(body['page'], 1);
+        expect(body['size'], 20);
+      });
+    });
+
     group('Photo endpoints', () {
       test('GET /api/v1/photo/<id> with invalid id returns 400', () async {
         server = await TestServer.start();
@@ -304,7 +431,8 @@ void main() {
         final albumId = albums.first['id'];
 
         final photosResponse = await server.get('/api/v1/album/$albumId/photo');
-        final photos = jsonDecode(photosResponse.body) as List;
+        final photosBody = jsonDecode(photosResponse.body) as Map;
+        final photos = photosBody['items'] as List;
         final photoId = photos.first['id'];
 
         final response = await server.get('/api/v1/photo/$photoId');
@@ -346,7 +474,8 @@ void main() {
         final albumId = albums.first['id'];
 
         final photosResponse = await server.get('/api/v1/album/$albumId/photo');
-        final photos = jsonDecode(photosResponse.body) as List;
+        final photosBody = jsonDecode(photosResponse.body) as Map;
+        final photos = photosBody['items'] as List;
         final photoId = photos.first['id'];
 
         final response = await server.get('/api/v1/photo/$photoId/file');
@@ -370,7 +499,8 @@ void main() {
           final photosResponse = await server.get(
             '/api/v1/album/$albumId/photo',
           );
-          final photos = jsonDecode(photosResponse.body) as List;
+          final photosBody = jsonDecode(photosResponse.body) as Map;
+          final photos = photosBody['items'] as List;
           final photoId = photos.first['id'];
 
           final response = await server.get('/api/v1/photo/$photoId/file');
@@ -415,7 +545,8 @@ void main() {
           final photosResponse = await server.get(
             '/api/v1/album/$albumId/photo',
           );
-          final photos = jsonDecode(photosResponse.body) as List;
+          final photosBody = jsonDecode(photosResponse.body) as Map;
+          final photos = photosBody['items'] as List;
           final photoId = photos.first['id'];
 
           // This will fail because vips CLI is not available,
@@ -468,7 +599,8 @@ void main() {
         final albumId = albums.first['id'];
 
         final photosResponse = await server.get('/api/v1/album/$albumId/photo');
-        final photos = jsonDecode(photosResponse.body) as List;
+        final photosBody = jsonDecode(photosResponse.body) as Map;
+        final photos = photosBody['items'] as List;
         final photoId = photos.first['id'];
 
         final response = await server.get('/api/v1/photo/$photoId');