feat(api-v13): aggregate 端点过滤器改名 file/book

- file 过滤 book 列（典籍文件号），book 过滤 book_id 列（真书号）
- 移除原 book/book_id 命名（v3 端点尚无消费者）
- 重新生成 OpenAPI 规格与 dashboard-v6 前端类型

api-v13/app/Http/Controllers/V3/TipitakaRelatedParagraphAggregateController.php

@@ -29,8 +29,8 @@ class TipitakaRelatedParagraphAggregateController extends Controller
      *
      * @unauthenticated
      *
-     * @queryParam book integer 典籍文件号过滤。
-     * @queryParam book_id integer 真书号过滤。
+     * @queryParam file integer 典籍文件号过滤（对应表里的 book 列）。
+     * @queryParam book integer 真书号过滤（对应表里的 book_id 列）。
      * @queryParam page integer 页码。Default: 1
      * @queryParam per_page integer 每页数量，最大 200。Default: 15
      */
@@ -50,8 +50,8 @@ class TipitakaRelatedParagraphAggregateController extends Controller
      *
      * @urlParam book_name string required SC 风格书名缩写（如 dn1、an2）。Example: dn1
      *
-     * @queryParam book integer 典籍文件号过滤。
-     * @queryParam book_id integer 真书号过滤。
+     * @queryParam file integer 典籍文件号过滤（对应表里的 book 列）。
+     * @queryParam book integer 真书号过滤（对应表里的 book_id 列）。
      * @queryParam page integer 页码。Default: 1
      * @queryParam per_page integer 每页数量，最大 200。Default: 15
      */

api-v13/app/Http/Requests/V3/AggregateTipitakaRelatedParagraphBookNameRequest.php

@@ -8,7 +8,9 @@ use Illuminate\Foundation\Http\FormRequest;
  * `GET /v3/tipitaka-related-paragraphs/aggregate/{book_name}` 的入参：
  * 列出该 SC 缩写下的 cs_para。book_name 在路径上。
  *
- * 其余参数是可选收窄过滤器；分页走 Laravel 默认的 page / per_page。
+ * 过滤器沿用 wikipali 的坐标命名：`file` 是典籍文件号（表里的 `book` 列，
+ * 1-217），`book` 是真书号（表里的 `book_id` 列）。其余参数是可选收窄过滤器；
+ * 分页走 Laravel 默认的 page / per_page。
  */
 class AggregateTipitakaRelatedParagraphBookNameRequest extends FormRequest
 {
@@ -26,8 +28,8 @@ class AggregateTipitakaRelatedParagraphBookNameRequest extends FormRequest
     public function rules(): array
     {
         return [
+            'file' => ['integer', 'min:1'],
             'book' => ['integer', 'min:1'],
-            'book_id' => ['integer', 'min:1'],
             'page' => ['integer', 'min:1'],
             'per_page' => ['integer', 'min:1', 'max:200'],
         ];

api-v13/app/Http/Requests/V3/AggregateTipitakaRelatedParagraphRequest.php

@@ -7,7 +7,9 @@ use Illuminate\Foundation\Http\FormRequest;
 /**
  * `GET /v3/tipitaka-related-paragraphs/aggregate` 的入参：列出所有 SC 缩写。
  *
- * 其余参数是可选收窄过滤器；分页走 Laravel 默认的 page / per_page。
+ * 过滤器沿用 wikipali 的坐标命名：`file` 是典籍文件号（表里的 `book` 列，
+ * 1-217），`book` 是真书号（表里的 `book_id` 列）。其余参数是可选收窄过滤器；
+ * 分页走 Laravel 默认的 page / per_page。
  */
 class AggregateTipitakaRelatedParagraphRequest extends FormRequest
 {
@@ -25,8 +27,8 @@ class AggregateTipitakaRelatedParagraphRequest extends FormRequest
     public function rules(): array
     {
         return [
+            'file' => ['integer', 'min:1'],
             'book' => ['integer', 'min:1'],
-            'book_id' => ['integer', 'min:1'],
             'page' => ['integer', 'min:1'],
             'per_page' => ['integer', 'min:1', 'max:200'],
         ];

api-v13/app/Services/V3/TipitakaRelatedParagraphService.php

@@ -91,8 +91,8 @@ class TipitakaRelatedParagraphService
     public function bookNames(array $filters): LengthAwarePaginator
     {
         return RelatedParagraph::query()
-            ->when(isset($filters['book']), fn (Builder $q) => $q->where('book', (int) $filters['book']))
-            ->when(isset($filters['book_id']), fn (Builder $q) => $q->where('book_id', (int) $filters['book_id']))
+            ->when(isset($filters['file']), fn (Builder $q) => $q->where('book', (int) $filters['file']))
+            ->when(isset($filters['book']), fn (Builder $q) => $q->where('book_id', (int) $filters['book']))
             ->where('cs_para', '>', 0)
             ->where('book_name', '!=', '')
             ->select('book_name')
@@ -111,8 +111,8 @@ class TipitakaRelatedParagraphService
     {
         return RelatedParagraph::query()
             ->where('book_name', $bookName)
-            ->when(isset($filters['book']), fn (Builder $q) => $q->where('book', (int) $filters['book']))
-            ->when(isset($filters['book_id']), fn (Builder $q) => $q->where('book_id', (int) $filters['book_id']))
+            ->when(isset($filters['file']), fn (Builder $q) => $q->where('book', (int) $filters['file']))
+            ->when(isset($filters['book']), fn (Builder $q) => $q->where('book_id', (int) $filters['book']))
             ->where('cs_para', '>', 0)
             ->select('cs_para')
             ->groupBy('cs_para')

api-v13/tests/Feature/TipitakaRelatedParagraphV3Test.php

@@ -140,6 +140,38 @@ it('lists cs_para of a book name', function () {
         ->and($json['meta']['total'])->toBe(2);
 });
 
+it('filters aggregate book names by file and book', function () {
+    makeRelatedParagraph(100, 2, 110, 4, 'an2');
+    makeRelatedParagraph(100, 3, 110, 5, 'an3');
+    makeRelatedParagraph(101, 2, 111, 4, 'an2');
+
+    // file 过滤 book 列：只剩 book=100 的两条
+    $json = $this->getJson('/api/v3/tipitaka-related-paragraphs/aggregate?file=100')->assertOk()->json();
+    expect($json['data'])->toBe([['book_name' => 'an2'], ['book_name' => 'an3']]);
+
+    // book 过滤 book_id 列：只剩 book_id=110 的两条
+    $json = $this->getJson('/api/v3/tipitaka-related-paragraphs/aggregate?book=110')->assertOk()->json();
+    expect($json['data'])->toBe([['book_name' => 'an2'], ['book_name' => 'an3']]);
+
+    // book 过滤 book_id 列：只剩 book_id=111 的一条
+    $json = $this->getJson('/api/v3/tipitaka-related-paragraphs/aggregate?book=111')->assertOk()->json();
+    expect($json['data'])->toBe([['book_name' => 'an2']]);
+});
+
+it('filters aggregate cs_para by file and book', function () {
+    makeRelatedParagraph(100, 2, 110, 4, 'an2');
+    makeRelatedParagraph(100, 3, 110, 5, 'an2');
+    makeRelatedParagraph(101, 2, 111, 4, 'an2');
+
+    // file 过滤 book 列：只剩 book=100 的两条
+    $json = $this->getJson('/api/v3/tipitaka-related-paragraphs/aggregate/an2?file=100')->assertOk()->json();
+    expect($json['data'])->toBe([['cs_para' => '4'], ['cs_para' => '5']]);
+
+    // book 过滤 book_id 列：只剩 book_id=111 的一条
+    $json = $this->getJson('/api/v3/tipitaka-related-paragraphs/aggregate/an2?book=111')->assertOk()->json();
+    expect($json['data'])->toBe([['cs_para' => '4']]);
+});
+
 it('validates the mutually exclusive lookup filters', function () {
     $this->getJson('/api/v3/tipitaka-related-paragraphs?book=1')
         ->assertStatus(422)

dashboard-v6/src/api/schema.d.ts

@@ -34704,10 +34704,10 @@ export interface operations {
     get_api_v3_tipitaka_related_paragraphs_aggregate: {
         parameters: {
             query?: {
-                /** @description 典籍文件号过滤 */
+                /** @description 典籍文件号过滤（对应表里的 book 列） */
+                file?: number;
+                /** @description 真书号过滤（对应表里的 book_id 列） */
                 book?: number;
-                /** @description 真书号过滤 */
-                book_id?: number;
                 /** @description 页码 */
                 page?: number;
                 /** @description 每页数量，最大 200 */
@@ -34739,10 +34739,10 @@ export interface operations {
     get_api_v3_tipitaka_related_paragraphs_aggregate_book_name_: {
         parameters: {
             query?: {
-                /** @description 典籍文件号过滤 */
+                /** @description 典籍文件号过滤（对应表里的 book 列） */
+                file?: number;
+                /** @description 真书号过滤（对应表里的 book_id 列） */
                 book?: number;
-                /** @description 真书号过滤 */
-                book_id?: number;
                 /** @description 页码 */
                 page?: number;
                 /** @description 每页数量，最大 200 */

openapi/public/assets/protocol/resources/auto/v3-tipitaka-related-paragraphs-aggregate-book-name.yaml

@@ -18,17 +18,17 @@ get:
       description: 'SC 风格书名缩写（如 dn1、an2）'
       example: dn1
     -
-      name: book
+      name: file
       in: query
       schema:
         type: integer
-      description: 典籍文件号过滤
+      description: '典籍文件号过滤（对应表里的 book 列）'
     -
-      name: book_id
+      name: book
       in: query
       schema:
         type: integer
-      description: 真书号过滤
+      description: '真书号过滤（对应表里的 book_id 列）'
     -
       name: page
       in: query

openapi/public/assets/protocol/resources/auto/v3-tipitaka-related-paragraphs-aggregate.yaml

@@ -10,17 +10,17 @@ get:
     实现：`V3\TipitakaRelatedParagraphAggregateController@index`
   parameters:
     -
-      name: book
+      name: file
       in: query
       schema:
         type: integer
-      description: 典籍文件号过滤
+      description: '典籍文件号过滤（对应表里的 book 列）'
     -
-      name: book_id
+      name: book
       in: query
       schema:
         type: integer
-      description: 真书号过滤
+      description: '真书号过滤（对应表里的 book_id 列）'
     -
       name: page
       in: query