feat: user tag

schema/network-setting.yaml

@@ -265,6 +265,22 @@ UsersNetworkSetting:
           items:
             type: string
           description: This field is for fallback role IDs. If the user does not have any role, this role will be assigned to the user.
+    tags:
+      type: object
+      description: Tag configuration for users
+      properties:
+        maxTagsPerNetwork:
+          type: integer
+          minimum: 1
+          maximum: 1000
+          default: 100
+          description: Maximum number of tags allowed per network
+        maxUsersPerBulkAssignment:
+          type: integer
+          minimum: 1
+          maximum: 1000
+          default: 100
+          description: Maximum number of users allowed per bulk tag assignment operation
 
 PublicUsersNetworkSetting:
   type: object

schema/tag.yaml

@@ -0,0 +1,263 @@
+Tag:
+  type: object
+  properties:
+    tagId:
+      type: string
+      description: Unique identifier for the tag (MongoDB ObjectId)
+      example: "507f1f77bcf86cd799439011"
+    publicId:
+      type: string
+      description: Public identifier for the tag (same as _id)
+      example: "507f1f77bcf86cd799439011"
+    networkId:
+      type: string
+      description: Network identifier this tag belongs to
+      example: "507f1f77bcf86cd799439012"
+    name:
+      type: string
+      description: Tag name (1-20 characters)
+      example: "VIP"
+    type:
+      type: string
+      enum: [user]
+      description: Type of tag
+      example: "user"
+    description:
+      type: string
+      description: Optional tag description (max 140 characters)
+      example: "VIP members with premium access"
+    backgroundColor:
+      type: string
+      pattern: "^#[0-9A-F]{6}$"
+      description: Hex color code for tag background
+      example: "#FF5733"
+    textColor:
+      type: string
+      pattern: "^#[0-9A-F]{6}$"
+      description: Hex color code for tag text
+      example: "#FFFFFF"
+    metadata:
+      type: object
+      description: Custom metadata for the tag
+      additionalProperties: true
+      example: { "priority": 1, "category": "premium" }
+    usersCount:
+      type: integer
+      description: Number of users assigned to this tag
+      example: 150
+    isDeleted:
+      type: boolean
+      description: Soft deletion flag
+      example: false
+    createdAt:
+      type: string
+      format: date-time
+      description: Tag creation timestamp
+      example: "2024-01-08T10:00:00.000Z"
+    updatedAt:
+      type: string
+      format: date-time
+      description: Tag last update timestamp
+      example: "2024-01-08T10:00:00.000Z"
+
+CreateTagRequest:
+  type: object
+  required:
+    - name
+    - type
+  properties:
+    name:
+      type: string
+      minLength: 1
+      maxLength: 20
+      description: Tag name
+      example: "VIP"
+    publicId:
+      type: string
+      minLength: 1
+      description: Optional custom public identifier for the tag
+      example: "vip-tag"
+    type:
+      type: string
+      enum: [user]
+      description: Type of tag (currently only 'user' is supported)
+      example: "user"
+    description:
+      type: string
+      maxLength: 140
+      description: Optional tag description
+      example: "VIP members with premium access"
+    backgroundColor:
+      type: string
+      pattern: "^#[0-9A-F]{6}$"
+      description: Hex color code for tag background
+      example: "#FF5733"
+    textColor:
+      type: string
+      pattern: "^#[0-9A-F]{6}$"
+      description: Hex color code for tag text
+      example: "#FFFFFF"
+    metadata:
+      type: object
+      description: Custom metadata for the tag
+      additionalProperties: true
+      example: { "priority": 1, "category": "premium" }
+
+UpdateTagRequest:
+  type: object
+  properties:
+    name:
+      type: string
+      minLength: 1
+      maxLength: 20
+      description: Tag name
+      example: "Premium VIP"
+    description:
+      type: string
+      maxLength: 140
+      description: Tag description
+      example: "Premium VIP members"
+    backgroundColor:
+      type: string
+      pattern: "^#[0-9A-F]{6}$"
+      description: Hex color code for tag background
+      example: "#FF5733"
+    textColor:
+      type: string
+      pattern: "^#[0-9A-F]{6}$"
+      description: Hex color code for tag text
+      example: "#FFFFFF"
+    metadata:
+      type: object
+      description: Custom metadata for the tag
+      additionalProperties: true
+      example: { "priority": 2 }
+
+QueryTagsResponse:
+  type: object
+  properties:
+    tags:
+      type: array
+      items:
+        $ref: '#/Tag'
+    paging:
+      type: object
+      properties:
+        next:
+          type: string
+          description: Pagination token for next page
+          example: "20"
+        previous:
+          type: string
+          description: Pagination token for previous page
+          example: "0"
+
+UserTagAssignment:
+  type: object
+  properties:
+    tagId:
+      type: string
+      description: Tag identifier
+      example: "507f1f77bcf86cd799439011"
+    assignedAt:
+      type: string
+      format: date-time
+      description: When the tag was assigned
+      example: "2024-01-08T10:00:00.000Z"
+
+AssignTagsToUserRequest:
+  type: object
+  required:
+    - tagIds
+  properties:
+    tagIds:
+      type: array
+      items:
+        type: string
+      maxItems: 10
+      description: Array of tag IDs to assign (max 10 tags per user)
+      example: ["507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012"]
+
+AssignTagsToUserResponse:
+  type: object
+  properties:
+    success:
+      type: boolean
+      description: Whether all tags were assigned successfully
+      example: true
+    assigned:
+      type: array
+      items:
+        type: string
+      description: Successfully assigned tag IDs
+      example: ["507f1f77bcf86cd799439011"]
+    skipped:
+      type: array
+      items:
+        type: object
+        properties:
+          tagId:
+            type: string
+            example: "507f1f77bcf86cd799439012"
+          reason:
+            type: string
+            enum: [TAG_NOT_FOUND, TAG_LIMIT_EXCEEDED, TAG_ALREADY_ASSIGNED]
+            example: "TAG_NOT_FOUND"
+      description: Tags that were skipped with reasons
+
+AssignTagToUsersRequest:
+  type: object
+  required:
+    - userIds
+  properties:
+    userIds:
+      type: array
+      items:
+        type: string
+      maxItems: 100
+      description: Array of user IDs (max from network setting, default 100)
+      example: ["user123", "user456"]
+
+AssignTagToUsersResponse:
+  type: object
+  properties:
+    success:
+      type: boolean
+      description: Whether all assignments were successful
+      example: true
+    assigned:
+      type: array
+      items:
+        type: string
+      description: Successfully assigned user IDs
+      example: ["user123"]
+    failed:
+      type: array
+      items:
+        type: object
+        properties:
+          userId:
+            type: string
+            example: "user456"
+          reason:
+            type: string
+            enum: [USER_NOT_FOUND, TAG_LIMIT_EXCEEDED, TAG_ALREADY_ASSIGNED]
+            example: "TAG_LIMIT_EXCEEDED"
+      description: Failed assignments with reasons
+
+CountByIdsResponse:
+  type: object
+  properties:
+    counts:
+      type: array
+      items:
+        type: object
+        properties:
+          tagId:
+            type: string
+            description: Tag identifier
+            example: "507f1f77bcf86cd799439011"
+          userCount:
+            type: integer
+            description: Number of users assigned to this tag
+            example: 42

swagger.yaml

@@ -151,6 +151,22 @@ paths:
     $ref: "./v1/invitation/index.yaml#/count"
   /api/v1/invitations/{invitationId}/resend:
     $ref: "./v1/invitation/index.yaml#/invitationId-resend"
+  # Tag Management
+  /api/v1/tags:
+    $ref: "./v1/tag/index.yaml#/root"
+  /api/v1/tags/count:
+    $ref: "./v1/tag/index.yaml#/count"
+  /api/v1/tags/countByIds:
+    $ref: "./v1/tag/index.yaml#/countByIds"
+  /api/v1/tags/{tagId}:
+    $ref: "./v1/tag/index.yaml#/_tagId"
+  # User Tag Assignment
+  /api/v4/users/{userId}/tags:
+    $ref: "./v4/user/index.yaml#/_userId-tags"
+  /api/v4/users/{userId}/tags/{tagId}:
+    $ref: "./v4/user/index.yaml#/_userId-tags_tagId"
+  /api/v4/users/tags/{tagId}/users:
+    $ref: "./v4/user/index.yaml#/tags_tagId-users"
   /api/v1/me/following-feeds:
     $ref: "./v1/following-feed/index.yaml#/root"
   /api/v3/content-feeds:
@@ -618,6 +634,12 @@ paths:
     $ref: "./webhook/user/index.yaml#/user.didUnflag"
   /webhook/user.didUpdate:
     $ref: "./webhook/user/index.yaml#/user.didUpdate"
+  /webhook/tag.created:
+    $ref: "./webhook/tag/index.yaml#/tag.created"
+  /webhook/tag.updated:
+    $ref: "./webhook/tag/index.yaml#/tag.updated"
+  /webhook/tag.deleted:
+    $ref: "./webhook/tag/index.yaml#/tag.deleted"
   /webhook/v3.comment.didAddReaction:
     $ref: "./webhook/comment-v3/index.yaml#/comment.didAddReaction"
   /webhook/v3.comment.didCreate:
@@ -889,3 +911,24 @@ components:
     BearerAuth:
       type: "http"
       scheme: "bearer"
+  schemas:
+    Tag:
+      $ref: "./schema/tag.yaml#/Tag"
+    CreateTagRequest:
+      $ref: "./schema/tag.yaml#/CreateTagRequest"
+    UpdateTagRequest:
+      $ref: "./schema/tag.yaml#/UpdateTagRequest"
+    QueryTagsResponse:
+      $ref: "./schema/tag.yaml#/QueryTagsResponse"
+    UserTagAssignment:
+      $ref: "./schema/tag.yaml#/UserTagAssignment"
+    AssignTagsToUserRequest:
+      $ref: "./schema/tag.yaml#/AssignTagsToUserRequest"
+    AssignTagsToUserResponse:
+      $ref: "./schema/tag.yaml#/AssignTagsToUserResponse"
+    AssignTagToUsersRequest:
+      $ref: "./schema/tag.yaml#/AssignTagToUsersRequest"
+    AssignTagToUsersResponse:
+      $ref: "./schema/tag.yaml#/AssignTagToUsersResponse"
+    CountByIdsResponse:
+      $ref: "./schema/tag.yaml#/CountByIdsResponse"

v1/tag/count-by-ids.yaml

@@ -0,0 +1,23 @@
+get:
+  summary: "Count Users by Tag IDs"
+  tags:
+    - "Tag"
+  security:
+    - BearerAuth: []
+  description: |
+    Count the number of users assigned to each specified tag. Admin only.
+
+    **Usage:**
+    - Accepts up to 20 tag IDs
+    - Returns per-tag user counts
+  parameters:
+    - $ref: "./parameter.yaml#/tagIds"
+  responses:
+    200:
+      $ref: "./response.yaml#/count-by-ids-response-200"
+    400:
+      $ref: "../../global/error.yaml#/BadRequestError"
+    403:
+      $ref: "../../global/error.yaml#/ForbiddenError"
+    500:
+      $ref: "../../global/error.yaml#/UnexpectedError"

v1/tag/count-tags.yaml

@@ -0,0 +1,24 @@
+get:
+  summary: "Count Tags"
+  tags:
+    - "Tag"
+  security:
+    - BearerAuth: []
+  description: |
+    Count tags matching filter criteria. Requires VIEW_USER_TAG_MANAGEMENT admin permission.
+
+    **Filtering:**
+    - By type (currently only 'user')
+    - By deletion status
+    - By keyword (case-insensitive search on name field)
+  parameters:
+    - $ref: "./parameter.yaml#/type"
+    - $ref: "./parameter.yaml#/isDeleted"
+    - $ref: "./parameter.yaml#/keyword"
+  responses:
+    200:
+      $ref: "./response.yaml#/count-tags-response-200"
+    403:
+      $ref: "../../global/error.yaml#/ForbiddenError"
+    500:
+      $ref: "../../global/error.yaml#/UnexpectedError"