增加 stats 接口设计

api/controllers/admin/__init__.py

@@ -6,3 +6,4 @@ bp = Blueprint("admin_api", __name__, url_prefix="/admin")
 api = ExternalApi(bp)
 
 from .auth import login
+from .stats import stats

api/controllers/admin/stats/stats.py

@@ -0,0 +1,151 @@
+from flask import Blueprint
+from flask_restful import Api, Resource # type: ignore
+
+from controllers.admin import api
+
+class RiskStats(Resource):
+    def get(self):
+        """Get risk level statistics.
+        ---
+        tags:
+          - admin
+        summary: Get risk level user counts
+        description: Get counts of users at different risk levels and their changes
+        security:
+          - JWT: []
+        parameters:
+          - name: start_date
+            in: query
+            type: string
+            format: date
+            required: true
+            description: Start date of the statistics period (YYYY-MM-DD)
+          - name: end_date
+            in: query  
+            type: string
+            format: date
+            required: true
+            description: End date of the statistics period (YYYY-MM-DD)
+        responses:
+          200:
+            description: Risk statistics retrieved successfully
+            schema:
+              type: object
+              properties:
+                high_risk_count:
+                  type: integer
+                  description: Current number of high risk users
+                daily_changes:
+                  type: object
+                  properties:
+                    from_yesterday:
+                      type: integer
+                      description: Change in high risk users compared to yesterday
+                    from_last_week:
+                      type: integer 
+                      description: Change in high risk users compared to last week
+          400:
+            description: Invalid date parameters
+        """
+        pass
+
+class UserStats(Resource):
+    def get(self):
+        """Get daily user statistics.
+        ---
+        tags:
+          - admin  
+        summary: Get daily active and new user counts
+        description: Get statistics of daily active users and new users
+        security:
+          - JWT: []
+        parameters:
+          - name: start_date
+            in: query
+            type: string
+            format: date
+            required: true
+            description: Start date of the statistics period (YYYY-MM-DD)
+          - name: end_date
+            in: query
+            type: string 
+            format: date
+            required: true
+            description: End date of the statistics period (YYYY-MM-DD)
+        responses:
+          200:
+            description: User statistics retrieved successfully
+            schema:
+              type: object
+              properties:
+                daily_stats:
+                  type: array
+                  items:
+                    type: object
+                    properties:
+                      date:
+                        type: string
+                        format: date
+                      active_users:
+                        type: integer
+                        description: Number of active users on this date
+                      new_users:
+                        type: integer
+                        description: Number of new users on this date
+          400:
+            description: Invalid date parameters
+        """
+        pass
+
+class ConversationStats(Resource):
+    def get(self):
+        """Get daily conversation statistics.
+        ---
+        tags:
+          - admin
+        summary: Get daily conversation counts and averages
+        description: Get statistics of daily total conversations and average conversations per user
+        security:
+          - JWT: []
+        parameters:
+          - name: start_date
+            in: query
+            type: string
+            format: date
+            required: true
+            description: Start date of the statistics period (YYYY-MM-DD)
+          - name: end_date
+            in: query
+            type: string
+            format: date 
+            required: true
+            description: End date of the statistics period (YYYY-MM-DD)
+        responses:
+          200:
+            description: Conversation statistics retrieved successfully
+            schema:
+              type: object
+              properties:
+                daily_stats:
+                  type: array
+                  items:
+                    type: object
+                    properties:
+                      date:
+                        type: string
+                        format: date
+                      total_conversations:
+                        type: integer
+                        description: Total number of conversations on this date
+                      avg_conversations_per_user:
+                        type: number
+                        format: float
+                        description: Average conversations per active user on this date
+          400:
+            description: Invalid date parameters
+        """
+        pass
+
+api.add_resource(RiskStats, '/risk-stats')
+api.add_resource(UserStats, '/user-stats') 
+api.add_resource(ConversationStats, '/conversation-stats')