chore: P1 验证通过 + 应用工厂抽取（修复循环导入）

- application/factory.py：应用工厂独立成模块，application 包保持轻量
  （修复 utils→application.constants 触发全量导入的循环依赖，P2 前置改造）
- app.py 改为 from application.factory import create_app
- tests/conftest.py：新增 flask_app 上下文 fixture
- test_response.py：R.ok/failed 在应用上下文中测试
- .flake8：修复 extend-ignore 行内注释导致 flake8 解析失败

验证：
- pytest 5 passed
- 应用完整构建 OK（MySQL/Redis 就绪）
- flake8 存量基线 154 条（F401×111 / E402×36 / 其余 7）已登记

Co-Authored-By: Claude <noreply@anthropic.com>

.flake8

@@ -25,7 +25,10 @@ exclude =
     dist
 
 # 与 black/isort 冲突项（必须忽略，否则与自动格式化互相打架）
+#   E203：切片冒号前空格（black 风格）
+#   W503：二元运算符换行（black 风格）
+#   E501：行过长（交由 black 处理）
 extend-ignore =
-    E203,   # 切片冒号前空格（black 风格）
+    E203,
-    W503,   # 二元运算符换行（black 风格）
+    W503,
-    E501,   # 行过长（交由 black 处理）
+    E501,

app.py

@@ -11,7 +11,7 @@
         → Gunicorn 通过 `app:app` 导入 app 对象，不执行 __main__ 块
 """
 
-from application import create_app
+from application.factory import create_app
 from config import FLASK_HOST, FLASK_PORT, FLASK_DEBUG, FLASK_USE_RELOADER
 
 # 创建应用实例

application/__init__.py

@@ -40,130 +40,22 @@
 # +======================================================================
 
 """
-应用工厂模块
+application 包
-负责创建和配置 Flask 应用实例
+=============================================================
+
+Flask 应用核心包。
+
+包结构：
+    - factory.py  应用工厂（create_app）
+    - constants/  常量定义
+    - forms/      表单验证
+    - middleware/ 请求/响应中间件
+    - models/     数据模型
+    - services/   业务逻辑
+    - views/      路由控制器
+
+说明：
+    应用工厂独立于 factory.py，保持本包导入轻量，避免包初始化时
+    触发全量导入（修复循环导入，支持单元测试与模块级导入）。
+    重构方向：本包后续整体迁移至 src/（见重构方案-v2.md）。
 """
-
-import os
-
-from flask import Flask
-from flask_cors import CORS
-from werkzeug.middleware.proxy_fix import ProxyFix
-
-from application.middleware.transaction import register_transaction
-from application.middleware import register_middleware
-from application.middleware.error_handler import register_error_handlers
-from application.middleware.op_log import register_operation_log
-from application.views import register_blueprint
-from config import DatabaseConfig, REDIS_URL
-from extensions import register_extends
-from utils.json import JSONEncoder
-
-
-def create_app():
-    """
-    创建并配置 Flask 应用实例
-
-    配置流程：
-        1. 创建 Flask 核心对象
-        2. 配置 Redis 连接
-        3. 加载数据库配置
-        4. 设置 JSON 序列化器
-        5. 配置跨域资源共享
-        6. 初始化数据库
-        7. 初始化 Redis 缓存
-        8. 注册路由蓝图
-        9. 初始化第三方扩展
-        10. 注册中间件
-
-    Returns:
-        Flask: 配置完成的应用实例
-    """
-    # ============================================================
-    # 创建 Flask 核心对象
-    # ============================================================
-    app = Flask(
-        __name__,
-        template_folder='../templates',
-        static_folder='../static'
-    )
-
-    # ============================================================
-    # Redis 配置（用于缓存和会话存储）
-    # ============================================================
-    app.config['REDIS_URL'] = REDIS_URL
-
-    # ============================================================
-    # 加载数据库配置
-    # ============================================================
-    app.config.from_object(DatabaseConfig)
-
-    # ============================================================
-    # 自定义 JSON 序列化器（支持 datetime 等特殊类型）
-    # ============================================================
-    app.json = JSONEncoder(app)
-
-    # ============================================================
-    # 跨域资源共享配置
-    # ============================================================
-    # 注意：origins="*" 与 supports_credentials=True 不兼容，
-    # 浏览器会拒绝携带凭证的通配符CORS响应。
-    # 配置了 CORS_ALLOWED_ORIGINS 时使用指定源（支持凭证），
-    # 未配置时使用通配符（不支持凭证）。
-    from config import CORS_ALLOWED_ORIGINS
-    if CORS_ALLOWED_ORIGINS:
-        allowed_origins = [origin.strip() for origin in CORS_ALLOWED_ORIGINS.split(',') if origin.strip()]
-        CORS(
-            app,
-            resources={r"/*": {"origins": allowed_origins}},
-            supports_credentials=True
-        )
-    else:
-        CORS(
-            app,
-            resources={r"/*": {"origins": "*"}},
-            supports_credentials=False
-        )
-
-    # ============================================================
-    # 可信代理配置（反向代理环境下获取真实客户端IP）
-    # ============================================================
-    # PROXY_NUM: 可信代理层数，默认0（无代理，不信任任何转发头）
-    # 设为1表示前面有1层可信代理（如Nginx），ProxyFix会从
-    # X-Forwarded-For 最右侧取1个IP作为真实客户端IP
-    proxy_num = int(os.getenv('PROXY_NUM', 0))
-    if proxy_num > 0:
-        app.wsgi_app = ProxyFix(app.wsgi_app, x_for=proxy_num, x_proto=proxy_num)
-
-    # ============================================================
-    # 注册操作日志自动记录中间件（必须在事务拦截器之前注册，
-    # 确保 after_request 中日志写入先于事务提交，日志随事务一起持久化）
-    # ============================================================
-    register_operation_log(app)
-
-    # ============================================================
-    # 注册 AOP 事务拦截器（核心：一行代码搞定所有事务）
-    # ============================================================
-    register_transaction(app)
-
-    # ============================================================
-    # 注册蓝图（路由分组管理）
-    # ============================================================
-    register_blueprint(app)
-
-    # ============================================================
-    # 初始化第三方扩展
-    # ============================================================
-    register_extends(app)
-
-    # ============================================================
-    # 注册中间件（请求/响应拦截处理）
-    # ============================================================
-    register_middleware(app)
-
-    # ============================================================
-    # 注册全局异常处理器（确保最后注册，能捕获所有环节异常）
-    # ============================================================
-    register_error_handlers(app)
-
-    return app

application/factory.py

@@ -0,0 +1,176 @@
+# +======================================================================
+# | DjangoAdmin 企业数字化开发平台 [ 赋能开发者，助力企业发展 ]
+# +----------------------------------------------------------------------
+# | Copyright (c) 2021-2026 一米阳光团队 版权所有
+# +----------------------------------------------------------------------
+# | 开源协议: Apache-2.0
+# | 重要声明: 未经书面许可，不得移除或修改本框架相关版权标识。
+# +----------------------------------------------------------------------
+# | 官方网站: https://www.djangoadmin.cn
+# +----------------------------------------------------------------------
+# | 研发团队: 一米阳光团队 荣誉出品
+# +======================================================================
+# | 版权和免责声明:
+# | 一、知识产权声明
+# | 本团队对该软件框架产品（以下简称“本产品”）拥有完整知识产权，包括但不限于商标权、专利权、
+# | 著作权、商业秘密等。前述权利均受中华人民共和国及相关国际法律法规保护。未经本团队书面授权，
+# | 任何个人或单位不得基于本产品本身申请任何形式的知识产权。
+# | 二、使用限制与禁止条款
+# | 您理解并同意，禁止将本产品用于以下任何行为：
+# | 1. 任何违反中华人民共和国法律法规的用途；
+# | 2. 任何侵害他人合法权益（包括但不限于人身权、财产权、知识产权等）的行为；
+# | 3. 任何危害国家安全、公共利益及社会道德风尚的行为。
+# | 三、责任豁免
+# | 因使用本产品而产生的任何损失或法律纠纷（包括但不限于直接损失、间接损失、附带损失、衍生损失
+# | 以及因违约、侵权等引发的责任），本团队均不承担任何法律责任。若因违规使用本产品导致任何第三
+# | 方提起索赔或行政机关进行调查，您应独立承担全部责任。
+# | 四、违约与法律责任
+# | 如发现任何违反本声明的行为，本团队有权：
+# | 1. 无条件配合公安机关及其他有权机关的调查取证工作；
+# | 2. 依法追究相关方的民事责任，并要求赔偿全部损失；
+# | 3. 保留进一步采取刑事控告等法律措施的权利。
+# | 五、许可范围说明
+# | 1、被授权方应视本产品源代码为核心机密信息，负有最高标准的保密与保管义务。禁止以任何形式（包
+# | 括但不限于直接或间接的分享、复制、传播、分发、转售、出租、开源、反向工程、反编译、反汇编或通
+# | 过网络服务提供给任何第三方）泄露、披露或处置源代码的全部或部分内容。任何未经授权的复制、使用、
+# | 传播行为均构成对本团队知识产权的严重侵权，本团队有权依法追究其全部法律责任，并要求赔偿因此造
+# | 成的一切经济损失及商誉损害。
+# | 2、本产品仅限于公司或个人在法律允许范围内，用于内部且合规的软件产品研发。具体权利义务以《软件
+# | 许可协议》附件为准。
+# +======================================================================
+
+"""
+应用工厂模块
+=============================================================
+
+负责创建和配置 Flask 应用实例。
+
+说明：
+    应用工厂从 application/__init__.py 独立至此模块，使 application
+    包保持轻量，避免包初始化时触发全量导入（修复循环导入，支持单元测试）。
+    重构方向：本模块后续迁移至 src/app.py（见重构方案-v2.md P2）。
+"""
+
+import os
+
+from flask import Flask
+from flask_cors import CORS
+from werkzeug.middleware.proxy_fix import ProxyFix
+
+from application.middleware.transaction import register_transaction
+from application.middleware import register_middleware
+from application.middleware.error_handler import register_error_handlers
+from application.middleware.op_log import register_operation_log
+from application.views import register_blueprint
+from config import DatabaseConfig, REDIS_URL
+from extensions import register_extends
+from utils.json import JSONEncoder
+
+
+def create_app():
+    """
+    创建并配置 Flask 应用实例
+
+    配置流程：
+        1. 创建 Flask 核心对象
+        2. 配置 Redis 连接
+        3. 加载数据库配置
+        4. 设置 JSON 序列化器
+        5. 配置跨域资源共享
+        6. 初始化数据库
+        7. 初始化 Redis 缓存
+        8. 注册路由蓝图
+        9. 初始化第三方扩展
+        10. 注册中间件
+
+    Returns:
+        Flask: 配置完成的应用实例
+    """
+    # ============================================================
+    # 创建 Flask 核心对象
+    # ============================================================
+    app = Flask(
+        __name__,
+        template_folder='../templates',
+        static_folder='../static'
+    )
+
+    # ============================================================
+    # Redis 配置（用于缓存和会话存储）
+    # ============================================================
+    app.config['REDIS_URL'] = REDIS_URL
+
+    # ============================================================
+    # 加载数据库配置
+    # ============================================================
+    app.config.from_object(DatabaseConfig)
+
+    # ============================================================
+    # 自定义 JSON 序列化器（支持 datetime 等特殊类型）
+    # ============================================================
+    app.json = JSONEncoder(app)
+
+    # ============================================================
+    # 跨域资源共享配置
+    # ============================================================
+    # 注意：origins="*" 与 supports_credentials=True 不兼容，
+    # 浏览器会拒绝携带凭证的通配符CORS响应。
+    # 配置了 CORS_ALLOWED_ORIGINS 时使用指定源（支持凭证），
+    # 未配置时使用通配符（不支持凭证）。
+    from config import CORS_ALLOWED_ORIGINS
+    if CORS_ALLOWED_ORIGINS:
+        allowed_origins = [origin.strip() for origin in CORS_ALLOWED_ORIGINS.split(',') if origin.strip()]
+        CORS(
+            app,
+            resources={r"/*": {"origins": allowed_origins}},
+            supports_credentials=True
+        )
+    else:
+        CORS(
+            app,
+            resources={r"/*": {"origins": "*"}},
+            supports_credentials=False
+        )
+
+    # ============================================================
+    # 可信代理配置（反向代理环境下获取真实客户端IP）
+    # ============================================================
+    # PROXY_NUM: 可信代理层数，默认0（无代理，不信任任何转发头）
+    # 设为1表示前面有1层可信代理（如Nginx），ProxyFix会从
+    # X-Forwarded-For 最右侧取1个IP作为真实客户端IP
+    proxy_num = int(os.getenv('PROXY_NUM', 0))
+    if proxy_num > 0:
+        app.wsgi_app = ProxyFix(app.wsgi_app, x_for=proxy_num, x_proto=proxy_num)
+
+    # ============================================================
+    # 注册操作日志自动记录中间件（必须在事务拦截器之前注册，
+    # 确保 after_request 中日志写入先于事务提交，日志随事务一起持久化）
+    # ============================================================
+    register_operation_log(app)
+
+    # ============================================================
+    # 注册 AOP 事务拦截器（核心：一行代码搞定所有事务）
+    # ============================================================
+    register_transaction(app)
+
+    # ============================================================
+    # 注册蓝图（路由分组管理）
+    # ============================================================
+    register_blueprint(app)
+
+    # ============================================================
+    # 初始化第三方扩展
+    # ============================================================
+    register_extends(app)
+
+    # ============================================================
+    # 注册中间件（请求/响应拦截处理）
+    # ============================================================
+    register_middleware(app)
+
+    # ============================================================
+    # 注册全局异常处理器（确保最后注册，能捕获所有环节异常）
+    # ============================================================
+    register_error_handlers(app)
+
+    return app

tests/conftest.py

@@ -2,18 +2,30 @@
 pytest 全局配置
 =============================================================
 
-P1 阶段仅搭建骨架，保证 `pytest` 可空跑。
+P1 阶段：
-测试 App 构建、数据库/Redis fixture 在 P8（测试完善阶段）补充：
+    - flask_app fixture：最小 Flask 应用（供 jsonify 等需应用上下文的功能测试）
-- app fixture：create_app() + 测试库 DATABASE_URL 覆盖
+    - 项目根目录加入 sys.path
-- db fixture：事务内建表/清库
+
-- client fixture：Flask test_client
+P8 阶段补充（测试完善）：
+    - app fixture：create_app() + 测试库 DATABASE_URL 覆盖
+    - db fixture：事务内建表/清库
+    - client fixture：Flask test_client
 """
 
 import os
 import sys
 
+import pytest
+from flask import Flask
+
 # 项目根目录加入 sys.path（tests/ 已有 __init__.py 时 pytest 通常自动处理，
 # 此处显式补充，兼容从任意目录启动 pytest 的场景）
 ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 if ROOT not in sys.path:
     sys.path.insert(0, ROOT)
+
+
+@pytest.fixture
+def flask_app():
+    """最小 Flask 应用实例（无数据库/中间件，仅提供应用上下文）。"""
+    return Flask(__name__)

tests/unit/test_core/test_response.py

@@ -3,6 +3,9 @@ R 统一响应格式单元测试
 
 验证 `R.ok()` / `R.failed()` 返回的 JSON 响应结构符合前后端约定：
 {code, data, msg, ok}（code=0 成功，非 0 失败）。
+
+说明：`R.ok()` 内部使用 `jsonify`，须在 Flask 应用上下文内调用
+（fixture：flask_app，见 tests/conftest.py）。
 """
 
 from utils import R
@@ -11,7 +14,8 @@ from utils import R
 class TestOk:
     """成功响应"""
 
-    def test_ok_default_format(self):
+    def test_ok_default_format(self, flask_app):
+        with flask_app.app_context():
             resp = R.ok()
         body = resp.get_json()
 
@@ -20,24 +24,28 @@ class TestOk:
         assert body["data"] is None
         assert body["msg"]
 
-    def test_ok_with_data(self):
+    def test_ok_with_data(self, flask_app):
+        with flask_app.app_context():
             resp = R.ok(data={"id": 1, "name": "张三"})
         body = resp.get_json()
 
         assert body["code"] == 0
         assert body["data"] == {"id": 1, "name": "张三"}
 
-    def test_ok_with_kwargs(self):
+    def test_ok_with_kwargs(self, flask_app):
+        with flask_app.app_context():
             resp = R.ok(data=[], total=100)
         body = resp.get_json()
 
+        assert body["code"] == 0
         assert body["total"] == 100
 
 
 class TestFailed:
     """失败响应"""
 
-    def test_failed_default_format(self):
+    def test_failed_default_format(self, flask_app):
+        with flask_app.app_context():
             resp = R.failed()
         body = resp.get_json()
 
@@ -45,7 +53,8 @@ class TestFailed:
         assert body["ok"] is False
         assert body["data"] is None
 
-    def test_failed_custom_code(self):
+    def test_failed_custom_code(self, flask_app):
+        with flask_app.app_context():
             resp = R.failed(msg="未授权访问", code=401)
         body = resp.get_json()
 

重构方案-v2.md

@@ -351,7 +351,7 @@ from src.core.database import db                # 统一 db 单例
 | 阶段 | 内容 | 验收标准 | 风险 |
 |---|---|---|---|
 | **P0 基线** | `git init`；`.gitignore` 补 `logs/ instance/ *.pyc`；基线提交 | git 仓库可用，可 `git reset --hard` 回滚 | 无 |
-| **P1 工具链** | pyproject.toml / requirements-dev.txt / .flake8 / .pre-commit / Makefile / pytest 骨架 | 现有代码 `flake8` 通过（或登记存量告警）；`pytest` 空跑通过 | 低 |
+| **P1 工具链** | pyproject.toml / requirements-dev.txt / .flake8 / .pre-commit / Makefile / pytest 骨架 | 现有代码 `flake8` 通过（或登记存量告警）；`pytest` 空跑通过。**已登记存量告警：154 条（F401×111 / E402×36 / 其余 7）；pytest 5 passed** | 低 |
 | **P2 core+common** | 建 `src/core/` `src/common/`；extensions/utils 打 shim；模型聚合器建 `src/models_registry.py` | `python app.py` 启动；`flask db migrate` 仍全量识别表；全接口冒烟 | 高（依赖面最大） |
 | **P3 模块搬迁** | 按 §2.5 顺序逐组迁移 23 个模块（models→forms→services→views），每批打 shim + 验证 | 每批后 `python app.py` 启动 + 该模块接口回归通过 | 中 |
 | **P4 服务层改造** | 26 个服务文件改「入参数据/出参数据」；router 取参包 R；引入 base_service/base_repository + BizError | 核心服务（auth/user/role/menu）单测可写可跑；接口回归全绿 | 高（最大工作量） |