feat(server/notices): GET /v1/notices(合并+unread_count)+ POST /read + openapi 扩展

server/api/openapi.yaml

@@ -857,10 +857,10 @@ paths:
   /notices:
     get:
       operationId: listNotices
-      summary: 获取公告列表
+      summary: 获取公告列表（含未读数）
       description: |
-        返回当前有效公告。同一份内容亦以多镜像签名静态 JSON 发布，客户端优先拉静态副本，
-        失败时回落到本端点。
+        返回当前用户可见的公告（全员广播 ∪ 定向），按发布时间倒序，并附带 unread_count。
+        同一份内容亦以多镜像签名静态 JSON 发布，客户端优先拉静态副本，失败时回落到本端点。
       tags: [Notices]
       responses:
         "200":
@@ -869,12 +869,39 @@ paths:
             application/json:
               schema:
                 type: object
-                required: [notices]
+                required: [notices, unread_count]
                 properties:
                   notices:
                     type: array
                     items:
                       $ref: "#/components/schemas/Notice"
+                  unread_count:
+                    type: integer
+                    description: 未读公告数
+                    example: 2
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "500":
+          $ref: "#/components/responses/Internal"
+
+  /notices/read:
+    post:
+      operationId: markNoticesRead
+      summary: 标记公告已读
+      description: 将当前用户的公告已读水位推进到当前时间，清空 unread_count。
+      tags: [Notices]
+      responses:
+        "200":
+          description: 标记成功
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok]
+                properties:
+                  ok:
+                    type: boolean
+                    example: true
         "401":
           $ref: "#/components/responses/Unauthorized"
         "500":
@@ -1319,12 +1346,17 @@ components:
 
     Notice:
       type: object
-      required: [id, title_zh, title_en, body_zh, body_en, published_at]
+      required: [id, type, title_zh, title_en, body_zh, body_en, published_at, unread]
       properties:
         id:
           type: string
           format: uuid
           description: 公告 UUID
+        type:
+          type: string
+          enum: [important, feature, news, reward, version, promo]
+          description: 公告类型，驱动客户端图标/分组展示
+          example: news
         title_zh:
           type: string
           description: 公告中文标题
@@ -1339,10 +1371,17 @@ components:
         body_en:
           type: string
           description: 公告英文正文（Markdown）
+        link:
+          type: string
+          description: 公告关联链接（可选，跳转详情/活动页）
         published_at:
           type: string
           format: date-time
           description: 发布时间（UTC ISO-8601）
+        unread:
+          type: boolean
+          description: 相对当前用户已读水位是否未读
+          example: true
 
     # ── Pay（pay v2 统一支付网关代理）──────────────────────