补全注释

app.py

@@ -19,6 +19,11 @@ logger = logging.getLogger(__name__)
 
 
 def create_app():
+    """创建并配置 Flask 应用实例。
+
+    这里统一完成跨路由共享的初始化逻辑，包括配置加载、跨域、错误处理、
+    访问鉴权、健康检查以及蓝图注册。
+    """
     app = Flask(__name__)
     CORS(app)
     settings.load()
@@ -27,20 +32,28 @@ def create_app():
 
     @app.errorhandler(404)
     def not_found(e):
+        """将未匹配到的路径统一转换为 JSON 404 响应。"""
         return jsonify({'error': {'message': '未找到', 'type': 'not_found'}}), 404
 
     @app.errorhandler(405)
     def method_not_allowed(e):
+        """将不支持的请求方法统一转换为 JSON 405 响应。"""
         return jsonify({'error': {'message': '方法不允许', 'type': 'method_not_allowed'}}), 405
 
     @app.errorhandler(500)
     def internal_error(e):
+        """将未捕获的服务端异常统一包装为 JSON 500 响应。"""
         return jsonify({'error': {'message': '服务器内部错误', 'type': 'server_error'}}), 500
 
     # ─── 全局鉴权中间件 ──────────────────────────
 
     @app.before_request
     def check_access():
+        """在进入业务路由前校验访问密钥。
+
+        当配置了 `ACCESS_API_KEY` 时，除健康检查和管理面板相关路径外，
+        所有请求都必须携带正确的 Bearer Token 或 `x-api-key`。
+        """
         if not Config.ACCESS_API_KEY:
             return
 
@@ -61,6 +74,7 @@ def create_app():
 
     @app.route('/health', methods=['GET'])
     def health():
+        """返回服务健康状态和当前生效的上游地址。"""
         return jsonify({'status': 'ok', 'target': settings.get_url()})
 
     # ─── 注册路由蓝图 ────────────────────────────