Przeglądaj źródła

chore(openapi): 重新生成规格与前端类型

生成产物,不要手改。本次变动来自三处:

- reactions 的写操作契约:DELETE 变成只有 204(无 content),POST 的 200/201
  响应体从 {type,count,selected,id} 换成完整的 reaction 资源
- /v3/progress 去掉 view 参数,order 带上白名单枚举
- 生成器对 204 的处理修正

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
visuddhinanda 3 tygodni temu
rodzic
commit
82e3651c3f

+ 45 - 26
dashboard-v6/src/api/schema.d.ts

@@ -7739,6 +7739,9 @@ export interface paths {
          *     201 不是手写的状态码:Laravel 的 ResourceResponse::calculateStatus() 看模型的
          *     wasRecentlyCreated,新建时自动给 201。这里不要改成固定 200——幂等端点区分
          *     「真的建了」与「早就有了」对调用方有用。
+         *     返回的是 reaction 资源本身(调用方需要 id 才能后续删除),**不含计数**。
+         *     计数是共享聚合值,归 `GET /v3/reactions/tally` 管;前端用乐观更新 ±1,
+         *     下次读 tally 时校正。见 v3-resource skill 硬规范第 2 条。
          *
          *     实现:`V3\MeReactionController@store`
          */
@@ -7762,6 +7765,8 @@ export interface paths {
         /**
          * 删除我自己的 reaction
          * @description 只能删自己那条(user_id 与当前用户不符返回 403)。
+         *     成功返回 **204 空体**:硬删就是删了,没有资源可回,计数也不在这里给
+         *     (见 v3-resource skill 硬规范第 2 条)。
          *
          *     实现:`V3\MeReactionController@destroy`
          */
@@ -7780,8 +7785,9 @@ export interface paths {
         };
         /**
          * 列出章节翻译进度
-         * @description 按 channel 查询各章节的翻译完成度。view 目前只支持 channel 一种口径,
-         *     传其它值返回 422。
+         * @description 按 channel 查询各章节的翻译完成度。分页与 meta 全由框架算。
+         *     原来有个 `view` 参数,但它只有 `channel` 一个合法值、传别的直接 422——
+         *     那不是业务路径开关而是噪音,已去掉(硬规范第 1 条)。
          *
          *     实现:`V3\ProgressController@index`
          */
@@ -34071,10 +34077,22 @@ export interface operations {
                 content: {
                     "application/json": {
                         data?: {
+                            id?: string;
                             type?: string;
-                            count?: number;
-                            selected?: boolean;
-                            id?: string | null;
+                            target_id?: string;
+                            target_type?: string;
+                            context?: string | null;
+                            created_at?: string;
+                            updated_at?: string;
+                            user?: {
+                                id?: string;
+                                nickName?: string;
+                                userName?: string;
+                                realName?: string;
+                                sn?: number;
+                                avatar?: string;
+                                roles?: string[];
+                            } | null;
                         };
                     };
                 };
@@ -34087,10 +34105,22 @@ export interface operations {
                 content: {
                     "application/json": {
                         data?: {
+                            id?: string;
                             type?: string;
-                            count?: number;
-                            selected?: boolean;
-                            id?: string | null;
+                            target_id?: string;
+                            target_type?: string;
+                            context?: string | null;
+                            created_at?: string;
+                            updated_at?: string;
+                            user?: {
+                                id?: string;
+                                nickName?: string;
+                                userName?: string;
+                                realName?: string;
+                                sn?: number;
+                                avatar?: string;
+                                roles?: string[];
+                            } | null;
                         };
                     };
                 };
@@ -34111,21 +34141,12 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description 成功 */
-            200: {
+            /** @description 删除成功,无响应体 */
+            204: {
                 headers: {
                     [name: string]: unknown;
                 };
-                content: {
-                    "application/json": {
-                        data?: {
-                            type?: string;
-                            count?: number;
-                            selected?: boolean;
-                            id?: string | null;
-                        };
-                    };
-                };
+                content?: never;
             };
             401: components["responses"]["ProblemUnauthorized"];
             /** @description 只能删除自己的 reaction */
@@ -34143,8 +34164,6 @@ export interface operations {
     get_api_v3_progress: {
         parameters: {
             query: {
-                /** @description 查询口径,目前只有 channel */
-                view: "channel";
                 /** @description channel uid 列表,**下划线分隔**(不是逗号) */
                 channels: string;
                 /** @description 只返回该层级及以上的章节,需联查 pali_texts */
@@ -34156,14 +34175,14 @@ export interface operations {
                 lang?: string;
                 /** @description 按典籍 id 过滤 */
                 book?: number;
-                /** @description 排序字段(progress_chapters 的列) */
-                order?: string;
+                /** @description 排序字段,白名单内 */
+                order?: "book" | "para" | "lang" | "progress" | "title" | "last_chapter_completed_at" | "completed_at" | "updated_at";
                 /** @description 排序方向 */
                 dir?: "asc" | "desc";
-                /** @description 每页数量 */
-                per_page?: number;
                 /** @description 页码 */
                 page?: number;
+                /** @description 每页数量,最大 200 */
+                per_page?: number;
             };
             header?: never;
             path?: never;

+ 4 - 19
openapi/public/assets/protocol/resources/auto/v3-me-reactions-reaction.yaml

@@ -6,6 +6,8 @@ delete:
   operationId: delete_api_v3_me_reactions_reaction_
   description: |-
     只能删自己那条(user_id 与当前用户不符返回 403)。
+    成功返回 **204 空体**:硬删就是删了,没有资源可回,计数也不在这里给
+    (见 v3-resource skill 硬规范第 2 条)。
 
     实现:`V3\MeReactionController@destroy`
   parameters:
@@ -17,25 +19,8 @@ delete:
         type: string
       description: 'reaction 的 uuid'
   responses:
-    200:
-      description: 成功
-      content:
-        application/json:
-          schema:
-            type: object
-            properties:
-              data:
-                type: object
-                properties:
-                  type:
-                    type: string
-                  count:
-                    type: integer
-                  selected:
-                    type: boolean
-                  id:
-                    type: string
-                    nullable: true
+    204:
+      description: 删除成功,无响应体
     401:
       $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'
     403:

+ 47 - 10
openapi/public/assets/protocol/resources/auto/v3-me-reactions.yaml

@@ -94,6 +94,9 @@ post:
     201 不是手写的状态码:Laravel 的 ResourceResponse::calculateStatus() 看模型的
     wasRecentlyCreated,新建时自动给 201。这里不要改成固定 200——幂等端点区分
     「真的建了」与「早就有了」对调用方有用。
+    返回的是 reaction 资源本身(调用方需要 id 才能后续删除),**不含计数**。
+    计数是共享聚合值,归 `GET /v3/reactions/tally` 管;前端用乐观更新 ±1,
+    下次读 tally 时校正。见 v3-resource skill 硬规范第 2 条。
 
     实现:`V3\MeReactionController@store`
   requestBody:
@@ -143,14 +146,31 @@ post:
               data:
                 type: object
                 properties:
+                  id:
+                    type: string
                   type:
                     type: string
-                  count:
-                    type: integer
-                  selected:
-                    type: boolean
-                  id:
+                  target_id:
+                    type: string
+                  target_type:
+                    type: string
+                  context:
+                    type: string
+                    nullable: true
+                  created_at:
+                    type: string
+                  updated_at:
                     type: string
+                  user:
+                    type: object
+                    properties:
+                      id: { type: string }
+                      nickName: { type: string }
+                      userName: { type: string }
+                      realName: { type: string }
+                      sn: { type: integer }
+                      avatar: { type: string }
+                      roles: { type: array, items: { type: string } }
                     nullable: true
     201:
       description: '首次创建。响应体与 200 同形,区别只在这一条是本次新建的'
@@ -162,14 +182,31 @@ post:
               data:
                 type: object
                 properties:
+                  id:
+                    type: string
                   type:
                     type: string
-                  count:
-                    type: integer
-                  selected:
-                    type: boolean
-                  id:
+                  target_id:
+                    type: string
+                  target_type:
+                    type: string
+                  context:
+                    type: string
+                    nullable: true
+                  created_at:
+                    type: string
+                  updated_at:
                     type: string
+                  user:
+                    type: object
+                    properties:
+                      id: { type: string }
+                      nickName: { type: string }
+                      userName: { type: string }
+                      realName: { type: string }
+                      sn: { type: integer }
+                      avatar: { type: string }
+                      roles: { type: array, items: { type: string } }
                     nullable: true
     401:
       $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'

+ 19 - 19
openapi/public/assets/protocol/resources/auto/v3-progress.yaml

@@ -5,26 +5,17 @@ get:
     - progress
   operationId: get_api_v3_progress
   description: |-
-    按 channel 查询各章节的翻译完成度。view 目前只支持 channel 一种口径,
-    传其它值返回 422。
+    按 channel 查询各章节的翻译完成度。分页与 meta 全由框架算。
+    原来有个 `view` 参数,但它只有 `channel` 一个合法值、传别的直接 422——
+    那不是业务路径开关而是噪音,已去掉(硬规范第 1 条)。
 
     实现:`V3\ProgressController@index`
   parameters:
-    -
-      name: view
-      in: query
-      schema:
-        type: string
-        enum:
-          - channel
-      description: '查询口径,目前只有 channel'
-      required: true
     -
       name: channels
       in: query
       schema:
         type: string
-        default: ''
       description: 'channel uid 列表,**下划线分隔**(不是逗号)'
       required: true
     -
@@ -51,8 +42,17 @@ get:
       in: query
       schema:
         type: string
+        enum:
+          - book
+          - para
+          - lang
+          - progress
+          - title
+          - last_chapter_completed_at
+          - completed_at
+          - updated_at
         default: completed_at
-      description: '排序字段(progress_chapters 的列)'
+      description: 排序字段,白名单内
     -
       name: dir
       in: query
@@ -64,19 +64,19 @@ get:
         default: desc
       description: 排序方向
     -
-      name: per_page
+      name: page
       in: query
       schema:
         type: integer
-        default: 10
-      description: 每页数量
+        default: 1
+      description: 页码
     -
-      name: page
+      name: per_page
       in: query
       schema:
         type: integer
-        default: 1
-      description: 页码
+        default: 10
+      description: '每页数量,最大 200'
   responses:
     200:
       description: 成功