fastapp-cli 0.1.0__tar.gz → 0.3.0__tar.gz

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapp-cli
-Version: 0.1.0
+Version: 0.3.0
 Summary: FastAPI 项目脚手架：一条命令生成完整可运行的 FastAPI 工程
 Author: aidenmo
 License: MIT
@@ -31,11 +31,12 @@ fastapp create my-server
 - **分层架构**：`api / schemas / crud / services / models` 分层，内置泛型 CRUD / Service 基类
 - **开箱即用的工程能力**：统一响应 / 异常体系、TraceID 中间件、loguru 日志、pydantic-settings 多环境配置
 - **分页 CRUD + 过滤**：基于 fastapi-pagination 与 fastapi-filter 的完整示例（`/api/v1/items`）
-- **Celery 骨架**：默认 redis broker，本地无 redis 时启动自动降级 `memory://` 并告警
+- **Celery 可选**：`--celery` 启用时生成完整任务骨架（默认 redis broker，本地无 redis 时启动自动降级 `memory://` 并告警）；默认不启用
 - **Alembic 迁移**：接入 SQLModel.metadata，含 autogenerate 过滤钩子
 - **优雅降级**：MySQL 缺席不阻塞启动，`/api/v1/health` 返回 `database: up/down`
 - **工程化配套**：Makefile、scripts/、pre-commit、ruff + mypy + pytest 配置全套
-- **可选部署文件**：`--pm2` / `--docker` 按需生成
+- **可选部署文件**：`--pm2` / `--docker` 按需生成（pm2.config.js，celery 未启用时对应启动命令自动注释）
+- **AI Agent 友好**：生成项目自带 `docs/agent_guide.md` 开发参考文档（架构、核心方法清单、扩展流程）
 
 ## 安装
 
@@ -60,8 +61,9 @@ fastapp create <project_name> [options]
 |---|---|---|
 | `project_name` | 必填 | 项目名；小写字母/数字/连字符，如 `my-server` |
 | `--description` | 交互提问 | 项目描述 |
-| `--pm2 / --no-pm2` | 交互提问 | 是否生成 `pm2.config.json` |
+| `--pm2 / --no-pm2` | 交互提问 | 是否生成 `pm2.config.js` |
 | `--docker / --no-docker` | 交互提问 | 是否生成 `Dockerfile` |
+| `--celery / --no-celery` | 交互提问（默认不启用） | 是否启用 Celery 异步任务 |
 | `--python` | `3.12` | 目标 Python 版本（写入 `.python-version`） |
 | `--author` | `git config user.name` | 作者署名 |
 | `--force` | 关 | 目标目录已存在时覆盖重建 |
@@ -70,7 +72,7 @@ fastapp create <project_name> [options]
 全部关键项通过 flag 提供时零交互：
 
 ```bash
-fastapp create my-server --description "demo" --no-pm2 --no-docker
+fastapp create my-server --description "demo" --no-pm2 --no-docker --no-celery
 ```
 
 生成完成后：
@@ -82,7 +84,7 @@ make dev        # 访问 /api/v1/docs
 
 ## 生成项目依赖
 
-fastapi、sqlmodel、alembic、celery[redis]、fastapi-pagination、fastapi-filter、loguru、pydantic-settings 等，dev 组含 pytest / ruff / mypy / pre-commit。
+fastapi、sqlmodel、alembic、fastapi-pagination、fastapi-filter、loguru、pydantic-settings 等，dev 组含 pytest / ruff / mypy / pre-commit；`--celery` 启用时额外引入 celery[redis] 与 flower。
 
 ## 开发 fastapp-cli 自身
 

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/README.md

@@ -11,11 +11,12 @@ fastapp create my-server
 - **分层架构**：`api / schemas / crud / services / models` 分层，内置泛型 CRUD / Service 基类
 - **开箱即用的工程能力**：统一响应 / 异常体系、TraceID 中间件、loguru 日志、pydantic-settings 多环境配置
 - **分页 CRUD + 过滤**：基于 fastapi-pagination 与 fastapi-filter 的完整示例（`/api/v1/items`）
-- **Celery 骨架**：默认 redis broker，本地无 redis 时启动自动降级 `memory://` 并告警
+- **Celery 可选**：`--celery` 启用时生成完整任务骨架（默认 redis broker，本地无 redis 时启动自动降级 `memory://` 并告警）；默认不启用
 - **Alembic 迁移**：接入 SQLModel.metadata，含 autogenerate 过滤钩子
 - **优雅降级**：MySQL 缺席不阻塞启动，`/api/v1/health` 返回 `database: up/down`
 - **工程化配套**：Makefile、scripts/、pre-commit、ruff + mypy + pytest 配置全套
-- **可选部署文件**：`--pm2` / `--docker` 按需生成
+- **可选部署文件**：`--pm2` / `--docker` 按需生成（pm2.config.js，celery 未启用时对应启动命令自动注释）
+- **AI Agent 友好**：生成项目自带 `docs/agent_guide.md` 开发参考文档（架构、核心方法清单、扩展流程）
 
 ## 安装
 
@@ -40,8 +41,9 @@ fastapp create <project_name> [options]
 |---|---|---|
 | `project_name` | 必填 | 项目名；小写字母/数字/连字符，如 `my-server` |
 | `--description` | 交互提问 | 项目描述 |
-| `--pm2 / --no-pm2` | 交互提问 | 是否生成 `pm2.config.json` |
+| `--pm2 / --no-pm2` | 交互提问 | 是否生成 `pm2.config.js` |
 | `--docker / --no-docker` | 交互提问 | 是否生成 `Dockerfile` |
+| `--celery / --no-celery` | 交互提问（默认不启用） | 是否启用 Celery 异步任务 |
 | `--python` | `3.12` | 目标 Python 版本（写入 `.python-version`） |
 | `--author` | `git config user.name` | 作者署名 |
 | `--force` | 关 | 目标目录已存在时覆盖重建 |
@@ -50,7 +52,7 @@ fastapp create <project_name> [options]
 全部关键项通过 flag 提供时零交互：
 
 ```bash
-fastapp create my-server --description "demo" --no-pm2 --no-docker
+fastapp create my-server --description "demo" --no-pm2 --no-docker --no-celery
 ```
 
 生成完成后：
@@ -62,7 +64,7 @@ make dev        # 访问 /api/v1/docs
 
 ## 生成项目依赖
 
-fastapi、sqlmodel、alembic、celery[redis]、fastapi-pagination、fastapi-filter、loguru、pydantic-settings 等，dev 组含 pytest / ruff / mypy / pre-commit。
+fastapi、sqlmodel、alembic、fastapi-pagination、fastapi-filter、loguru、pydantic-settings 等，dev 组含 pytest / ruff / mypy / pre-commit；`--celery` 启用时额外引入 celery[redis] 与 flower。
 
 ## 开发 fastapp-cli 自身
 

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fastapp-cli"
-version = "0.1.0"
+version = "0.3.0"
 description = "FastAPI 项目脚手架：一条命令生成完整可运行的 FastAPI 工程"
 readme = "README.md"
 requires-python = ">=3.10"

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/src/fastapp_cli/__init__.py

@@ -1,3 +1,3 @@
 """fastapp-cli: FastAPI 项目脚手架."""
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/src/fastapp_cli/create.py

@@ -68,13 +68,18 @@ def create(
     pm2: bool = typer.Option(
         None,
         "--pm2/--no-pm2",
-        help="是否生成 pm2.config.json（未指定时交互提问）",
+        help="是否生成 pm2.config.js（未指定时交互提问）",
     ),
     docker: bool = typer.Option(
         None,
         "--docker/--no-docker",
         help="是否生成 Dockerfile（未指定时交互提问）",
     ),
+    celery: bool = typer.Option(
+        None,
+        "--celery/--no-celery",
+        help="是否启用 Celery 异步任务（未指定时交互提问，默认不启用）",
+    ),
     python_version: str = typer.Option(
         "3.12",
         "--python",
@@ -122,6 +127,7 @@ def create(
     desc = prompts.ask_description(description)
     use_pm2 = prompts.ask_use_pm2(pm2)
     use_docker = prompts.ask_use_docker(docker)
+    use_celery = prompts.ask_use_celery(celery)
     author_name = author or _git_user_name() or "fastapp-cli"
 
     # 3. 渲染
@@ -132,6 +138,7 @@ def create(
         "author_name": author_name,
         "use_pm2": use_pm2,
         "use_docker": use_docker,
+        "use_celery": use_celery,
         "year": datetime.now(timezone.utc).year,
         "fastapp_cli_version": __version__,
     }

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/src/fastapp_cli/prompts.py

@@ -1,6 +1,6 @@
 """混合模式交互提问.
 
-关键项（描述 / pm2 / Dockerfile）在未通过 flag 提供时交互提问；
+关键项（描述 / pm2 / Dockerfile / celery）在未通过 flag 提供时交互提问；
 flag 已提供则跳过提问，实现零交互。
 """
 
@@ -33,3 +33,10 @@ def ask_use_docker(provided: bool | None) -> bool:
     if provided is not None:
         return provided
     return typer.confirm("是否包含 Dockerfile?", default=False)
+
+
+def ask_use_celery(provided: bool | None) -> bool:
+    """是否启用 Celery 异步任务：未指定时交互提问，默认不启用."""
+    if provided is not None:
+        return provided
+    return typer.confirm("是否启用 Celery 异步任务?", default=False)

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/.env.development.example.j2

@@ -16,6 +16,7 @@ MYSQL_DB={{ project_name | replace('-', '_') }}_dev
 # 打印 SQL 方便排查
 SQL_ECHO=true
 
-# 本地 Redis
+{% if use_celery %}# 本地 Redis
 CELERY_BROKER_URL=redis://localhost:6379/0
 CELERY_RESULT_BACKEND=redis://localhost:6379/1
+{% endif %}

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/.env.example.j2

@@ -17,7 +17,7 @@ MYSQL_DB={{ project_name | replace('-', '_') }}
 # 是否打印 SQL（开发环境使用）
 SQL_ECHO=false
 
-# ========== Celery（redis，缺席时应用启动自动降级 memory://） ==========
+{% if use_celery %}# ========== Celery（redis，缺席时应用启动自动降级 memory://） ==========
 CELERY_BROKER_URL=redis://localhost:6379/0
 CELERY_RESULT_BACKEND=redis://localhost:6379/1
 CELERY_TASK_DEFAULT_QUEUE=default
@@ -27,3 +27,4 @@ FLOWER_HOST=0.0.0.0
 FLOWER_PORT=5555
 # 基本认证（可选），格式：user:password，多个用逗号分隔
 # FLOWER_BASIC_AUTH=admin:admin
+{% endif %}

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/.env.j2

@@ -17,7 +17,7 @@ MYSQL_PASSWORD=
 MYSQL_DB={{ project_name | replace('-', '_') }}_dev
 SQL_ECHO=true
 
-# ========== Celery（本地无 redis 时启动自动降级 memory://） ==========
+{% if use_celery %}# ========== Celery（本地无 redis 时启动自动降级 memory://） ==========
 CELERY_BROKER_URL=redis://localhost:6379/0
 CELERY_RESULT_BACKEND=redis://localhost:6379/1
 CELERY_TASK_DEFAULT_QUEUE=default
@@ -25,3 +25,4 @@ CELERY_TASK_DEFAULT_QUEUE=default
 # ========== Flower ==========
 FLOWER_HOST=0.0.0.0
 FLOWER_PORT=5555
+{% endif %}

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/README.md.j2

@@ -3,7 +3,7 @@
 > {{ project_description }}
 > 由 [fastapp-cli](https://pypi.org/project/fastapp-cli/) v{{ fastapp_cli_version }} 生成于 {{ year }}，作者：{{ author_name }}
 
-FastAPI + SQLModel + Celery 工程模板，含分层架构、统一响应 / 异常 / TraceID / 日志、分页 CRUD、Alembic 迁移与完整测试。
+FastAPI + SQLModel{% if use_celery %} + Celery{% endif %} 工程模板，含分层架构、统一响应 / 异常 / TraceID / 日志、分页 CRUD、Alembic 迁移与完整测试。
 
 ## 快速开始
 
@@ -20,7 +20,8 @@ make dev        # 或 uv run uvicorn app.main:app --reload
 | 组件 | 默认 | 缺席时行为 |
 |---|---|---|
 | MySQL | `.env` 中配置 | 启动不阻塞，`/api/v1/health` 返回 `database: "down"`，数据接口统一返回 500 |
-| Redis (Celery) | `redis://localhost:6379` | 启动不阻塞，自动降级为 `memory://` broker 并输出告警日志 |
+{% if use_celery %}| Redis (Celery) | `redis://localhost:6379` | 启动不阻塞，自动降级为 `memory://` broker 并输出告警日志 |
+{% endif %}
 
 生产环境只需在 `.env` 配置真实 MySQL / Redis 地址，无需改代码。
 
@@ -35,14 +36,14 @@ make migrate      # alembic upgrade head
 make revision m="add xxx"   # 生成迁移脚本
 ```
 
-Celery：
+{% if use_celery %}Celery：
 
 ```bash
 bash scripts/celery_worker.sh    # worker
 bash scripts/celery_beat.sh      # 定时任务
 bash scripts/celery_flower.sh    # 监控面板（:5555）
 ```
-
+{% endif %}
 ## 目录结构
 
 ```text
@@ -62,7 +63,10 @@ app/
 
 ## 扩展指南
 
+> AI Agent / 新成员开发前请先阅读 [docs/agent_guide.md](docs/agent_guide.md)——包含架构说明、核心方法清单（优先复用）、标准开发流程与编码规范。
+
 1. **新增业务域**：仿照 `item` 五件套（model / schema / crud / service / endpoint），在 `models/__init__.py` 注册新模型，在 `api/v1/router.py` 挂载新路由；
 2. **生成迁移**：`make revision m="add xxx table"` 后检查 `alembic/versions/`，再 `make migrate`；
 3. **接入真实认证**：替换 `app/api/deps.py::get_current_user` 的占位实现；
-4. **新增 Celery 任务**：在 `app/tasks/` 中使用 `@celery_app.task` 装饰器编写。
+{% if use_celery %}4. **新增 Celery 任务**：在 `app/tasks/` 中使用 `@celery_app.task` 装饰器编写。
+{% endif %}

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/app/core/celery_app.py.j2

@@ -1,4 +1,4 @@
-"""Celery 应用实例.
+{% if use_celery %}"""Celery 应用实例.
 
 主应用与 worker 共用 ``build_celery_app`` 构造入口：
 
@@ -60,3 +60,4 @@ celery_app.conf.beat_schedule = {
     #     "schedule": crontab(hour=2, minute=0),
     # },
 }
+{% endif %}

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/app/core/config.py.j2

@@ -80,7 +80,7 @@ class Settings(BaseSettings):
     DB_POOL_SIZE: int = 10
     DB_MAX_OVERFLOW: int = 20
 
-    # ========== Celery 配置 ==========
+{% if use_celery %}    # ========== Celery 配置 ==========
     CELERY_BROKER_URL: str = "redis://localhost:6379/0"
     CELERY_RESULT_BACKEND: str = "redis://localhost:6379/1"
     CELERY_TASK_DEFAULT_QUEUE: str = "default"
@@ -90,6 +90,7 @@ class Settings(BaseSettings):
     FLOWER_PORT: int = 5555
     # 基本认证，格式：user:password，多个用逗号分隔
     FLOWER_BASIC_AUTH: str | None = None
+{% endif %}
 
     @property
     def is_production(self) -> bool:

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/app/main.py.j2

@@ -12,8 +12,8 @@ from loguru import logger
 from sqlalchemy import text
 
 from app.api.v1.router import api_router
-from app.core.celery_app import celery_app, degrade_to_memory
-from app.core.config import settings
+{% if use_celery %}from app.core.celery_app import celery_app, degrade_to_memory
+{% endif %}from app.core.config import settings
 from app.core.database import engine
 from app.core.exceptions import register_exception_handlers
 from app.core.logging import setup_logging
@@ -30,7 +30,7 @@ def _probe_database() -> None:
         logger.warning("数据库未就绪，数据接口将返回 500，请配置 .env: {}", exc)
 
 
-def _probe_redis() -> None:
+{% if use_celery %}def _probe_redis() -> None:
     """启动时探测 redis（带超时），不可达时 Celery 自动降级为 memory broker."""
     broker_url = settings.CELERY_BROKER_URL
     if broker_url.startswith("memory"):
@@ -52,18 +52,18 @@ def _probe_redis() -> None:
         logger.warning("redis 未就绪，Celery 已降级为 memory broker: {}", exc)
 
 
-@asynccontextmanager
+{% endif %}@asynccontextmanager
 async def lifespan(_: FastAPI) -> AsyncIterator[None]:
     """应用生命周期.
 
-    - 启动：初始化日志、探测数据库 / redis（缺席降级，不阻塞启动）
+    - 启动：初始化日志、探测数据库{% if use_celery %} / redis（缺席降级，不阻塞启动）{% endif %}
     - 关闭：优雅释放资源
     """
     setup_logging()
     logger.info("{} starting | env={} | debug={}", settings.APP_NAME, settings.APP_ENV, settings.DEBUG)
     _probe_database()
-    _probe_redis()
-
+{% if use_celery %}    _probe_redis()
+{% endif %}
     yield
 
     logger.info("{} stopped", settings.APP_NAME)
@@ -71,6 +71,10 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]:
 
 def create_app() -> FastAPI:
     """工厂函数：创建 FastAPI 应用实例."""
+    if settings.DEBUG:
+        # DEBUG 模式下打印全部配置，便于本地排查；生产环境（DEBUG=false）不输出，避免泄露敏感配置
+        logger.debug("settings: {}", settings.model_dump())
+
     app_ = FastAPI(
         title=settings.APP_NAME,
         # 注意：固定 False。DEBUG 环境变量仅控制日志级别与 SQL echo；

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/app/tasks/sample_tasks.py.j2

@@ -1,4 +1,4 @@
-"""Celery 示例任务."""
+{% if use_celery %}"""Celery 示例任务."""
 
 from __future__ import annotations
 
@@ -26,3 +26,4 @@ def sample_task(self, name: str = "world") -> dict:
     logger.info("[task={}] sample_task running, name={}", self.request.id, name)
     time.sleep(1)
     return {"message": f"hello, {name}"}
+{% endif %}

fastapp_cli-0.3.0/src/fastapp_cli/templates/project/docs/agent_guide.md.j2

@@ -0,0 +1,307 @@
+# {{ project_name }} — AI Agent 开发参考文档
+
+> 本文档面向 AI Agent（或新加入的开发者），目标是帮助你在不了解项目历史的情况下，快速掌握项目设计并**正确地**进行开发。
+> 核心原则：**优先复用已有方法与基础设施，不要重复造轮子。**
+
+## 1. 项目概述与整体架构
+
+本项目是由 fastapp-cli v{{ fastapp_cli_version }} 生成的 FastAPI 工程，技术栈：
+
+| 层次 | 技术 | 说明 |
+|---|---|---|
+| Web 框架 | FastAPI | 工厂函数 `create_app` 创建，lifespan 管理启动/关闭 |
+| ORM | SQLModel (SQLAlchemy) | PEP 695 泛型 CRUD 基类 |
+| 数据库 | MySQL（默认）/ SQLite（测试） | SQLAlchemy 引擎，连接池参数已调优 |
+| 迁移 | Alembic | 增量迁移，`MANAGED_TABLES` 约束只管理业务表 |
+{% if use_celery %}| 异步任务 | Celery + Redis | redis 不可达时自动降级 memory broker |
+{% endif %}| 分页 | fastapi-pagination | 统一分页响应结构 |
+| 过滤 | fastapi-filter | 声明式查询过滤器 |
+| 日志 | loguru | 拦截标准 logging，全链路 trace_id |
+| 配置 | pydantic-settings | 多环境 `.env` 加载 |
+| 包管理 | uv | 依赖分组（dev 组含 pytest/ruff/mypy） |
+| 质量工具 | ruff + mypy + pytest | 必须全绿才能合入 |
+
+**分层架构（自上而下的调用方向，禁止跨层 / 反向依赖）：**
+
+```text
+Endpoint (app/api/v1/endpoints/)   路由层：参数解析、依赖注入、组装 Response
+    ↓ 调用
+Service (app/services/)            业务层：业务规则、事务编排，继承 ServiceBase
+    ↓ 调用
+CRUD (app/crud/)                   数据访问层：只做数据读写，继承 CRUDBase
+    ↓ 操作
+Model (app/models/)                SQLModel 表模型 + Pydantic 校验二合一
+```
+
+**横切能力（在 core 中，所有层可直接使用）：** 统一响应 / 统一异常 / TraceID / 日志 / 配置 / 数据库会话。
+
+**请求处理链路：**
+
+```text
+TraceIDMiddleware (最外层，生成/透传 X-Trace-Id)
+  → CORS
+    → register_exception_handlers 注册的异常处理器（兜底所有异常）
+      → Endpoint（注入 DBSession / CurrentUser）
+        → Response[T] 自动注入 trace_id
+```
+
+## 2. 目录结构及各模块职责
+
+```text
+.
+├── app/
+│   ├── main.py                  # create_app 工厂 + lifespan（DB{% if use_celery %}/redis{% endif %} 探测，缺席降级不阻塞启动）
+│   ├── core/                    # 横切基础设施（禁止在此写业务逻辑）
+│   │   ├── config.py            #   settings 配置中心（多环境 .env 加载）
+│   │   ├── database.py          #   engine / get_session / init_db
+│   │   ├── logging.py           #   setup_logging / with_trace / InterceptHandler
+│   │   ├── exceptions.py        #   AppExceptionError 体系 + 全局异常处理器
+│   │   ├── middleware.py        #   TraceIDMiddleware（trace_id 生成与响应头注入）
+│   │   ├── context_var.py       #   trace_id_var / get_trace_id
+{% if use_celery %}│   │   └── celery_app.py        #   build_celery_app / degrade_to_memory / celery_app 单例
+{% endif %}│   ├── api/
+│   │   ├── deps.py              #   DBSession / CurrentUser 依赖（认证占位）
+│   │   └── v1/
+│   │       ├── router.py        #   v1 总路由，新业务路由在此挂载
+│   │       └── endpoints/       #   health.py（健康检查）、items.py（分页 CRUD 示例域）
+│   ├── models/                  # SQLModel 表模型；新模型必须在 __init__.py 注册
+│   │   ├── base.py              #   IDMixin / TimestampMixin / utcnow
+│   │   └── item.py              #   Item 示例模型
+│   ├── schemas/                 # Pydantic Schema：入参 / 出参 / 过滤器
+│   │   ├── common.py            #   Response / PageParams / PageResult / PageResponse
+│   │   └── item.py              #   ItemCreate / ItemUpdate / ItemRead / ItemFilter
+│   ├── crud/                    # 数据访问层
+│   │   ├── base.py              #   CRUDBase 泛型基类（核心复用点）
+│   │   └── item.py              #   CRUDItem(CRUDBase[Item])
+│   ├── services/                # 业务逻辑层
+│   │   ├── base.py              #   ServiceBase 泛型基类（核心复用点）
+│   │   └── item_service.py      #   ItemService(ServiceBase[CRUDItem])
+│   ├── tasks/{% if use_celery %}                   # Celery 任务（sample_tasks.py 为示例）
+│   └── utils/                   # 通用工具扩展位（空）
+{% else %}                   # 预留任务目录
+│   └── utils/                   # 通用工具扩展位（空）
+{% endif %}├── alembic/                     # 迁移环境（env.py 已配置 MANAGED_TABLES 白名单过滤）
+├── docs/                        # 本文档 + SQLModel定义示例.md（建模规范）
+├── scripts/                     # start.sh{% if use_celery %} / celery_worker.sh / celery_beat.sh / celery_flower.sh{% endif %}
+├── tests/                       # pytest：conftest 用 sqlite 内存库，无需真实 MySQL
+├── alembic.ini / Makefile / pyproject.toml
+└── .env / .env.example          # 配置文件（.env 入库，敏感信息按环境覆盖）
+```
+
+## 3. 已有核心方法与工具函数清单（优先复用）
+
+> **强制要求：开发新功能前先检索本清单。能用现有方法解决的，必须调用现有方法，禁止重写等价实现。**
+
+### 3.1 数据访问层 — `CRUDBase`（`app/crud/base.py`）
+
+泛型基类 `CRUDBase[ModelType: SQLModel]`，所有业务 CRUD 继承它即可获得以下能力，**任何手写 select/commit 循环前必须先确认此处没有现成方法**：
+
+| 方法 | 签名 | 说明 |
+|---|---|---|
+| `get` | `(db: Session, obj_id: Any) -> ModelType \| None` | 按主键查询 |
+| `get_or_404` | `(db: Session, obj_id: Any) -> ModelType` | 按主键查询，不存在抛 `NotFoundError` |
+| `get_by_field` | `(db: Session, field: str, value: Any) -> ModelType \| None` | 按任意字段查单个（字段不存在抛 `ValueError`） |
+| `get_page_multi` | `(db: Session, *, filter_params: Filter \| None = None) -> PageResponse[Any]` | 分页 + 过滤 + 排序查询 |
+| `get_multi` | `(db: Session, *, filter_params: Filter \| None = None) -> Sequence[ModelType]` | 非分页列表查询 |
+| `count` | `(db: Session, query: Select \| SelectOfScalar \| None = None) -> int` | 记录总数（可传入自定义 query） |
+| `create` | `(db: Session, *, obj_in: BaseModel \| dict[str, Any]) -> ModelType` | 创建单条（自动 model_dump、commit、refresh） |
+| `create_multi` | `(db: Session, *, objs_in: list[...]) -> list[ModelType]` | 批量创建 |
+| `update` | `(db: Session, *, db_obj: ModelType, obj_in: BaseModel \| dict[str, Any]) -> ModelType` | 更新（`exclude_unset` 语义，只更新显式传入字段） |
+| `create_or_update` | `(db: Session, *, obj_in, unique_fields: str \| Sequence[str] \| None = None) -> ModelType` | 按唯一字段 upsert（未指定时用主键） |
+| `create_or_update_multi` | `(db: Session, *, objs_in: list[...], unique_fields=None) -> list[ModelType]` | 批量 upsert（同一事务提交） |
+| `remove` | `(db: Session, *, obj_id: int) -> ModelType` | 按主键删除（不存在抛 404） |
+| `remove_multi` | `(db: Session, *, obj_ids: list[Any]) -> list[ModelType]` | 批量删除 |
+| `exists` | `(db: Session, *, obj_id: Any) -> bool` | 判断是否存在 |
+
+使用示例（新增业务域的 CRUD 通常只需一行继承）：
+
+```python
+from app.crud.base import CRUDBase
+from app.models.product import Product
+
+class CRUDProduct(CRUDBase[Product]):
+    pass  # 复杂查询逻辑才在此扩展
+```
+
+### 3.2 业务层 — `ServiceBase`（`app/services/base.py`）
+
+泛型基类 `ServiceBase[CRUDType: CRUDBase]`，内部持有 `self.db` 与 `self.crud`，方法返回值标注为 `Any`（由子类按业务模型收窄）：
+
+| 方法 | 签名 | 说明 |
+|---|---|---|
+| `create` | `(obj_in: BaseModel \| dict) -> Any` | 创建 |
+| `create_multi` | `(objs_in: list) -> list[Any]` | 批量创建 |
+| `create_or_update` | `(obj_in, unique_fields=None) -> Any` | upsert |
+| `create_or_update_multi` | `(objs_in, unique_fields=None) -> list[Any]` | 批量 upsert |
+| `get` | `(obj_id: int) -> Any` | 获取单个，不存在抛 `NotFoundError` |
+| `update` | `(obj_id: int, obj_in) -> Any` | 更新（不存在抛 `NotFoundError`） |
+| `delete` | `(obj_id: int) -> Any` | 删除 |
+| `list_objs` | `(filter_params: Filter \| None = None) -> Sequence[Any]` | 列表查询 |
+| `list_page_objs` | `(filter_params: Filter \| None = None) -> PageResponse[Any]` | 分页查询 |
+
+使用示例（纯 CRUD 型业务，Service 通常也只是继承）：
+
+```python
+from app.crud.product import CRUDProduct
+from app.services.base import ServiceBase
+
+class ProductService(ServiceBase[CRUDProduct]):
+    def activate(self, obj_id: int) -> None:  # 自定义业务方法
+        obj = self.get(obj_id)
+        self.crud.update(self.db, db_obj=obj, obj_in={"is_active": True})
+```
+
+### 3.3 API 依赖（`app/api/deps.py`）
+
+| 名称 | 类型 | 说明 |
+|---|---|---|
+| `DBSession` | `Annotated[Session, Depends(get_session)]` | 端点中直接作参数注解，获取数据库会话 |
+| `CurrentUser` | `Annotated[str, Depends(get_current_user)]` | 当前登录用户。非生产环境返回 `settings.MOCK_USER`；生产环境抛 `UnauthorizedError`（认证占位，接入真实认证时只改 `get_current_user`） |
+
+```python
+@router.post("", response_model=Response[ProductRead])
+def create_product(payload: ProductCreate, service: ProductServiceDep, current_user: CurrentUser) -> Response[ProductRead]:
+    data: ProductRead = service.create(payload)
+    return Response(data=data)
+```
+
+### 3.4 统一响应与分页（`app/schemas/common.py`）
+
+| 名称 | 说明 |
+|---|---|
+| `Response[T]` | 统一响应体 `{code, message, data, trace_id}`；`code=0` 为成功；trace_id 自动从请求上下文注入 |
+| `PageParams` | 分页入参（`page` / `page_size`，`size` 的 URL alias 为 `page_size`） |
+| `PageResult[T]` | 分页数据结构 `{total, page, page_size, content}` |
+| `PageResponse[T]` | 分页统一响应（继承 `Response[PageResult[T]]`），作为端点 `response_model` 使用 |
+
+### 3.5 统一异常（`app/core/exceptions.py`）
+
+**业务代码中禁止直接 `raise HTTPException` 或返回错误 dict**，统一抛以下异常，由全局异常处理器转换成统一返回体 `{code, message, data, trace_id}`：
+
+| 异常 | HTTP 状态码 | 业务码 | 默认消息 |
+|---|---|---|---|
+| `AppExceptionError(message, *, code, status_code, data)` | 400 | 1 | 业务异常基类，自定义业务异常继承它 |
+| `NotFoundError` | 404 | 40400 | 资源不存在 |
+| `UnauthorizedError` | 401 | 40100 | 未认证或凭证已失效 |
+| `ForbiddenError` | 403 | 40300 | 无访问权限 |
+| `ConflictError` | 409 | 40900 | 资源冲突 |
+
+```python
+from app.core.exceptions import ConflictError, NotFoundError, AppExceptionError
+
+raise NotFoundError(message="订单不存在")
+raise AppExceptionError(message="余额不足", code=10001, status_code=400)
+```
+
+未捕获异常统一返回 HTTP 500 + `{"code": 50000, "message": "服务器内部错误"}`，不会裸抛堆栈（应用实例固定 `debug=False`，勿改）。
+
+### 3.6 模型公共字段（`app/models/base.py`）
+
+| 名称 | 说明 |
+|---|---|
+| `IDMixin` | 主键 `id: int`（primary_key + index） |
+| `TimestampMixin` | `create_time` / `update_time`，数据库自动生成与刷新，JSON 序列化为 `%Y-%m-%d %H:%M:%S` |
+| `utcnow()` | 当前时间（`default_factory` 用） |
+| `FormattedDatetime` | 可复用的 datetime 序列化类型标注 |
+
+新表模型标准写法：
+
+```python
+from sqlmodel import Field
+from app.models.base import IDMixin, TimestampMixin
+
+class ProductBase(TimestampMixin):
+    name: str = Field(max_length=128, description="名称")
+
+class Product(IDMixin, ProductBase, table=True):
+    __tablename__ = "t_product"
+```
+
+### 3.7 配置（`app/core/config.py`）
+
+- 单例 `settings`：所有环境变量集中于此，**禁止在业务代码中直接读 `os.environ`**。
+- 加载顺序（后者覆盖前者）：`.env` → `.env.{APP_ENV}` → 系统环境变量。
+- 常用字段：`APP_NAME` / `APP_ENV`（development|production|test）/ `DEBUG` / `API_V1_PREFIX` / `ALLOWED_ORIGINS` / `DATABASE_URI`（未设置时自动按 `MYSQL_*` 拼装）/ `SQL_ECHO`{% if use_celery %} / `CELERY_BROKER_URL`{% endif %} / `MOCK_USER`。
+- 属性：`settings.is_production` / `settings.is_test`。
+- 新增配置项：在 `Settings` 类中加字段 + 默认值，并在 `.env.example` / `.env` 中补充说明。
+
+### 3.8 数据库（`app/core/database.py`）
+
+| 名称 | 说明 |
+|---|---|
+| `engine` | 全局引擎。sqlite（测试）与 MySQL（连接池 + `pool_recycle=3600` + `REPEATABLE READ` + 3 秒连接超时）已分别调优，勿重复配置 |
+| `get_session()` | FastAPI 依赖，yield 语法保证 Session 关闭；**通过 `DBSession` 注解使用**，不要自建 Session |
+| `init_db()` | 本地/测试快速建表（生产用 alembic 迁移） |
+
+{% if use_celery %}### 3.9 Celery（`app/core/celery_app.py`）
+
+| 名称 | 说明 |
+|---|---|
+| `celery_app` | 全局单例（worker 与 web 共用），新任务直接 `@celery_app.task` |
+| `build_celery_app(broker_url, backend_url, *, name)` | 构造入口（自定义 broker 时使用） |
+| `degrade_to_memory(celery)` | 降级为 memory broker/backend（lifespan 探测失败时自动调用，勿手动调用） |
+
+新任务示例：
+
+```python
+from app.core.celery_app import celery_app
+
+@celery_app.task
+def send_notice(user_id: int) -> str:
+    ...
+```
+
+{% endif %}{% if use_celery %}### 3.10{% else %}### 3.9{% endif %} 日志与 TraceID（`app/core/logging.py`、`app/core/context_var.py`）
+
+| 名称 | 说明 |
+|---|---|
+| `setup_logging()` | lifespan 启动时自动调用，勿重复调用 |
+| `logger`（loguru） | 业务代码统一 `from loguru import logger`；标准 logging 已被拦截转发到 loguru |
+| `with_trace` | 装饰器：把请求 trace_id 透传到后台任务（`BackgroundTasks.add_task` 场景**必须**用它包裹） |
+| `get_trace_id()` | 获取当前请求 trace_id（无上下文返回空串） |
+
+## 4. 新增功能的标准开发流程
+
+### 4.1 新增业务域（以 `product` 为例，五件套 + 两处注册 + 迁移 + 测试）
+
+1. **Model**：`app/models/product.py`，继承 `IDMixin, TimestampMixin`（见 §3.6 示例）；在 `app/models/__init__.py` 中 import 并加入 `__all__`（否则 alembic autogenerate 无法发现）。
+2. **Schema**：`app/schemas/product.py`，定义 `ProductCreate` / `ProductUpdate` / `ProductRead`（继承 `ProductBase` + `id` 字段）与 `ProductFilter(Filter)`（`Constants.model` 指向模型，过滤字段用 `__ilike` / `__gte` 等后缀，参考 `app/schemas/item.py`）。
+3. **CRUD**：`app/crud/product.py`，`class CRUDProduct(CRUDBase[Product]): pass`。
+4. **Service**：`app/services/product_service.py`，`class ProductService(ServiceBase[CRUDProduct])`，业务规则写在这里。
+5. **Endpoint**：`app/api/v1/endpoints/product.py`，仿照 `items.py`：`get_service` 依赖 + `ServiceDep` + 各路由方法返回 `Response[...]` / `PageResponse[...]`。
+6. **注册路由**：`app/api/v1/router.py` 中 `include_router(product_router, prefix="/products", tags=["Products"])`。
+7. **迁移**：`make revision m="add t_product"` → 检查 `alembic/versions/` 生成脚本 → `make migrate`。注意 `alembic/env.py` 用 `MANAGED_TABLES` 白名单过滤，新表模型注册到 `app/models/__init__.py` 后会被自动纳入。
+8. **测试**：在 `tests/` 下仿照 `tests/api/test_items.py` 编写（conftest 已用 sqlite 内存库，无需真实 MySQL），运行 `make test && make lint`。
+
+### 4.2 其他扩展场景
+
+| 场景 | 做法 |
+|---|---|
+| 新增配置项 | `Settings` 类加字段 + `.env.example` 补说明 |
+| 接入真实认证 | 只替换 `app/api/deps.py::get_current_user` 实现，端点代码不动 |
+| 新增中间件 | `app/core/middleware.py` 实现，并在 `main.py::create_app` 注册；**注意注册顺序**：TraceIDMiddleware 必须最后添加（处于最外层） |
+{% if use_celery %}| 新增 Celery 定时任务 | `app/tasks/` 写任务，`celery_app.conf.beat_schedule` 中注册（该文件内有注释示例） |
+{% endif %}| 自定义业务异常 | 继承 `AppExceptionError`，类属性覆盖 `status_code` / `code` / `message`，全局处理器自动生效 |
+| 复杂查询 | 在业务 CRUD 子类中扩展方法，保持 Service 只编排不写 SQL 细节 |
+
+## 5. 编码规范与注意事项
+
+### 5.1 强制规范
+
+1. **统一响应**：所有端点 `response_model` 必须是 `Response[T]` 或 `PageResponse[T]`；错误场景抛异常（§3.5），禁止返回裸 dict / 直接 `HTTPException`。
+2. **禁止 `FastAPI(debug=True)`**：`main.py` 中已固定 `debug=False`。`DEBUG=true` 仅控制日志级别、SQL echo 与 uvicorn reload；传 True 会导致 Starlette 绕过统一异常处理器返回原始堆栈。
+3. **分层依赖方向**：endpoint → service → crud → model，单向依赖；core 不依赖业务层。
+4. **复用优先**：新写任何 select/commit/upsert/分页逻辑前，先查 §3 清单；CRUDBase / ServiceBase 未覆盖的场景才在子类扩展。
+5. **模型注册**：新模型必须加入 `app/models/__init__.py`，否则 `init_db()` 与 alembic autogenerate 均无法感知。
+6. **质量门禁**：提交前 `make format && make test && make lint`（ruff + mypy）必须全绿。类型注解用 PEP 695 语法（`class Foo[T]`），SQLModel `inspect()` 返回可空处沿用既有的 `cast(...)` + `# type: ignore[union-attr]` 惯例。
+7. **导入风格**：`from __future__ import annotations` 置于模块首行（docstring 之后）；第三方与本地导入分组，遵循 isort 规则（ruff 强制）。
+
+### 5.2 注意事项
+
+- **时间字段**：一律通过 `TimestampMixin`；JSON 输出格式 `%Y-%m-%d %H:%M:%S` 由 `FormattedDatetime` 统一处理，勿自行 strftime。
+- **Session 生命周期**：请求内通过 `DBSession` 注入；后台任务/脚本中用 `with Session(engine) as session:`，不要复用请求 Session。
+- **降级行为**：MySQL{% if use_celery %} / Redis 缺席不阻塞启动（health 返回 down、Celery 降级 memory）。本地开发无需强制装依赖，但数据接口在无库时统一返回 500{% else %} 缺席不阻塞启动（health 返回 down）。本地开发无需强制装数据库，数据接口在无库时统一返回 500{% endif %}。
+- **测试环境**：测试用 sqlite 内存库（`tests/conftest.py`），依赖 sqlite 不支持的特性时需显式跳过。
+- **`.env` 提交策略**：`.env` 与 `.env.example` 入库作默认配置；敏感信息（生产密码）放 `.env.production`（不入库）或真实环境变量。
+- **docs/**：`SQLModel定义示例.md` 是建模规范，新表定义先对照该文档。
+- **业务域隔离**：`item` 域为示例，可整体替换为实际业务；删除时同步清理 `router.py` 挂载与对应测试。

fastapp_cli-0.3.0/src/fastapp_cli/templates/project/pm2.config.js.j2

@@ -0,0 +1,50 @@
+{% if use_pm2 %}module.exports = {
+  apps: [
+    {
+      name: "{{ project_name }}-server",
+      script: "bash scripts/start.sh",
+      out_file: "./logs/server.log",
+      err_file: "./logs/server.log",
+    },
+{% if use_celery %}
+    {
+      name: "{{ project_name }}-worker",
+      script: "bash scripts/celery_worker.sh",
+      out_file: "./logs/celery.log",
+      err_file: "./logs/celery.log",
+    },
+    {
+      name: "{{ project_name }}-beat",
+      script: "bash scripts/celery_beat.sh",
+      out_file: "./logs/celery_beat.log",
+      err_file: "./logs/celery_beat.log",
+    },
+    {
+      name: "{{ project_name }}-flower",
+      script: "bash scripts/celery_flower.sh",
+      out_file: "./logs/flower.log",
+      err_file: "./logs/flower.log",
+    },
+{% else %}
+    // {
+    //   name: "{{ project_name }}-worker",
+    //   script: "bash scripts/celery_worker.sh",
+    //   out_file: "./logs/celery.log",
+    //   err_file: "./logs/celery.log",
+    // },
+    // {
+    //   name: "{{ project_name }}-beat",
+    //   script: "bash scripts/celery_beat.sh",
+    //   out_file: "./logs/celery_beat.log",
+    //   err_file: "./logs/celery_beat.log",
+    // },
+    // {
+    //   name: "{{ project_name }}-flower",
+    //   script: "bash scripts/celery_flower.sh",
+    //   out_file: "./logs/flower.log",
+    //   err_file: "./logs/flower.log",
+    // }
+{% endif %}
+  ],
+};
+{% endif %}

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/pyproject.toml.j2

@@ -7,12 +7,12 @@ requires-python = ">=3.12"
 
 dependencies = [
     "alembic>=1.18.4",
-    "celery[redis]>=5.6.3",
-    "fastapi>=0.136.1",
+{% if use_celery %}    "celery[redis]>=5.6.3",
+{% endif %}    "fastapi>=0.136.1",
     "fastapi-filter[sqlalchemy]>=2.0.1",
     "fastapi-pagination>=0.15.13",
-    "flower>=2.0.1",
-    "httpx>=0.28.1",
+{% if use_celery %}    "flower>=2.0.1",
+{% endif %}    "httpx>=0.28.1",
     "loguru>=0.7.3",
     "pydantic>=2.13.3",
     "pydantic-settings>=2.14.0",
@@ -180,9 +180,9 @@ exclude = [
 # 说明：这些库通常没有官方 type stubs，忽略可以避免 "Cannot find implementation" 报错
 [[tool.mypy.overrides]]
 module = [
-    "celery.*",
+{% if use_celery %}    "celery.*",
     "flower.*",
-    "sqlmodel.*",       # SQLModel 的类型推断对 mypy 不友好，建议忽略
+{% endif %}    "sqlmodel.*",       # SQLModel 的类型推断对 mypy 不友好，建议忽略
 ]
 ignore_missing_imports = true
 

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/scripts/celery_beat.sh.j2

@@ -1,4 +1,4 @@
-#!/usr/bin/env bash
+{% if use_celery %}#!/usr/bin/env bash
 # 启动 Celery Beat（定时任务调度）
 set -euo pipefail
 
@@ -7,3 +7,4 @@ cd "$(dirname "$0")/.."
 LOG_LEVEL="${LOG_LEVEL:-INFO}"
 
 exec uv run celery -A app.core.celery_app.celery_app beat -l "${LOG_LEVEL}"
+{% endif %}

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/scripts/celery_flower.sh.j2

@@ -1,4 +1,4 @@
-#!/usr/bin/env bash
+{% if use_celery %}#!/usr/bin/env bash
 # 启动 Flower（Celery 任务监控面板）
 set -euo pipefail
 
@@ -20,3 +20,4 @@ exec uv run celery -A app.core.celery_app.celery_app flower \
     --port="${PORT}" \
     --loglevel="${LOG_LEVEL}" \
     ${BASIC_AUTH_ARG}
+{% endif %}

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/src/fastapp_cli/templates/project/scripts/celery_worker.sh.j2

@@ -1,4 +1,4 @@
-#!/usr/bin/env bash
+{% if use_celery %}#!/usr/bin/env bash
 # 启动 Celery Worker
 set -euo pipefail
 
@@ -13,3 +13,4 @@ exec uv run celery -A app.core.celery_app.celery_app worker \
     -c "${CONCURRENCY}" \
     -l "${LOG_LEVEL}" \
     -n "worker@%h"
+{% endif %}

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/tests/test_create.py

@@ -33,6 +33,7 @@ def test_create_smoke_full_flags(tmp_path: Path, monkeypatch) -> None:
             "--description", "smoke test",
             "--pm2",
             "--docker",
+            "--celery",
             "--no-git",
         ],
     )
@@ -46,7 +47,8 @@ def test_create_smoke_full_flags(tmp_path: Path, monkeypatch) -> None:
         "app/main.py",
         "app/api/v1/endpoints/items.py",
         "tests/conftest.py",
-        "pm2.config.json",
+        "pm2.config.js",
+        "app/core/celery_app.py",
         "Dockerfile",
     ):
         assert (root / rel).exists(), f"缺少 {rel}"
@@ -59,6 +61,26 @@ def test_create_smoke_full_flags(tmp_path: Path, monkeypatch) -> None:
     assert "make dev" in result.output
 
 
+def test_create_default_no_celery(tmp_path: Path, monkeypatch) -> None:
+    """--no-celery（默认）：不生成 celery 文件，pm2 命令被注释."""
+    monkeypatch.chdir(tmp_path)
+    result = runner.invoke(
+        app,
+        [
+            "create", "demo-server",
+            "--description", "x",
+            "--pm2", "--no-docker", "--no-celery", "--no-git",
+        ],
+    )
+    assert result.exit_code == 0, result.output
+
+    root = tmp_path / "demo-server"
+    assert not (root / "app/core/celery_app.py").exists()
+    assert not (root / "app/tasks/sample_tasks.py").exists()
+    pm2_text = (root / "pm2.config.js").read_text(encoding="utf-8")
+    assert "//   script: \"bash scripts/celery_worker.sh\"" in pm2_text
+
+
 def test_create_existing_dir_rejected(tmp_path: Path, monkeypatch) -> None:
     """目标目录已存在且未指定 --force 时拒绝."""
     monkeypatch.chdir(tmp_path)
@@ -83,18 +105,19 @@ def test_create_invalid_name_rejected(tmp_path: Path, monkeypatch) -> None:
 
 
 def test_create_interactive_flow(tmp_path: Path, monkeypatch) -> None:
-    """零 flag 交互路径：通过输入补全描述 / pm2 / Dockerfile."""
+    """零 flag 交互路径：通过输入补全描述 / pm2 / Dockerfile / celery."""
     monkeypatch.chdir(tmp_path)
-    # 描述输入（回车取默认）、pm2 回答 y、Dockerfile 回答 n
+    # 描述输入（回车取默认）、pm2 回答 y、Dockerfile 回答 n、celery 回答 n（默认）
     result = runner.invoke(
         app,
         ["create", "demo-server", "--no-git"],
-        input="\ny\nn\n",
+        input="\ny\nn\nn\n",
     )
     assert result.exit_code == 0, result.output
     root = tmp_path / "demo-server"
-    assert (root / "pm2.config.json").exists()
+    assert (root / "pm2.config.js").exists()
     assert not (root / "Dockerfile").exists()
+    assert not (root / "app/core/celery_app.py").exists()
 
 
 def test_create_git_init(tmp_path: Path, monkeypatch) -> None:
@@ -104,7 +127,7 @@ def test_create_git_init(tmp_path: Path, monkeypatch) -> None:
     monkeypatch.chdir(tmp_path)
     result = runner.invoke(
         app,
-        ["create", "demo-server", "--description", "x", "--no-pm2", "--no-docker"],
+        ["create", "demo-server", "--description", "x", "--no-pm2", "--no-docker", "--no-celery"],
     )
     assert result.exit_code == 0, result.output
     assert (tmp_path / "demo-server" / ".git").is_dir()

{fastapp_cli-0.1.0 → fastapp_cli-0.3.0}/tests/test_render.py

@@ -15,6 +15,7 @@ BASE_CTX: dict[str, object] = {
     "author_name": "tester",
     "use_pm2": False,
     "use_docker": False,
+    "use_celery": True,
     "year": 2026,
     "fastapp_cli_version": "0.1.0",
 }
@@ -70,7 +71,7 @@ def test_render_project_full(tmp_path: Path) -> None:
         assert (out / rel).exists(), f"缺少 {rel}，实际输出 {len(written)} 个文件"
 
     # 条件文件默认不生成
-    assert not (out / "pm2.config.json").exists()
+    assert not (out / "pm2.config.js").exists()
     assert not (out / "Dockerfile").exists()
 
     # 变量注入
@@ -90,9 +91,52 @@ def test_render_project_conditional_files(tmp_path: Path) -> None:
     out = tmp_path / "proj"
     render_project(out, ctx)
 
-    pm2 = out / "pm2.config.json"
+    pm2 = out / "pm2.config.js"
     dockerfile = out / "Dockerfile"
     assert pm2.exists()
     assert dockerfile.exists()
-    assert "demo-server" in pm2.read_text(encoding="utf-8")
+    pm2_text = pm2.read_text(encoding="utf-8")
+    assert "demo-server" in pm2_text
+    # celery 启用：worker/beat/flower 为生效条目
+    assert "celery_worker.sh" in pm2_text
+    assert "//   name:" not in pm2_text
     assert "python3.12" in dockerfile.read_text(encoding="utf-8")
+
+
+def test_render_project_no_celery(tmp_path: Path) -> None:
+    """use_celery=False：celery 文件不生成，pm2 中对应命令为注释，依赖剔除."""
+    from fastapp_cli.render import render_project
+
+    ctx = dict(BASE_CTX, use_celery=False, use_pm2=True)
+    out = tmp_path / "proj"
+    render_project(out, ctx)
+
+    # celery 相关文件不生成
+    for rel in (
+        "app/core/celery_app.py",
+        "app/tasks/sample_tasks.py",
+        "scripts/celery_worker.sh",
+        "scripts/celery_beat.sh",
+        "scripts/celery_flower.sh",
+    ):
+        assert not (out / rel).exists(), f"{rel} 不应生成"
+
+    # pm2.config.js 中 celery 启动命令被注释
+    pm2_text = (out / "pm2.config.js").read_text(encoding="utf-8")
+    assert "//   name:" in pm2_text
+    assert "//   script: \"bash scripts/celery_worker.sh\"" in pm2_text
+    # server 条目仍生效
+    assert 'name: "demo-server-server"' in pm2_text
+
+    # pyproject 无 celery/flower 依赖
+    pyproject = (out / "pyproject.toml").read_text(encoding="utf-8")
+    assert "celery" not in pyproject
+    assert "flower" not in pyproject
+
+    # main.py 无 celery 探测
+    main_text = (out / "app" / "main.py").read_text(encoding="utf-8")
+    assert "celery" not in main_text
+    assert "_probe_redis" not in main_text
+
+    # DEBUG 打印已注入
+    assert "settings.DEBUG" in main_text

fastapp_cli-0.1.0/src/fastapp_cli/templates/project/pm2.config.json.j2

@@ -1,47 +0,0 @@
-{% if use_pm2 %}
-{
-  "apps": [
-    {
-      "name": "{{ project_name }}-server",
-      "script": "bash scripts/start.sh",
-      "output": "./logs/server.log",
-      "error": "./logs/server-error.log",
-      "env": {
-        "HOST": "0.0.0.0",
-        "PORT": "8000",
-        "APP_ENV": "production",
-        "WORKERS": "1"
-      }
-    },
-    {
-      "name": "{{ project_name }}-worker",
-      "script": "bash scripts/celery_worker.sh",
-      "output": "./logs/celery.log",
-      "error": "./logs/celery-error.log",
-      "env": {
-        "CONCURRENCY": "4",
-        "QUEUE": "default",
-        "LOG_LEVEL": "INFO"
-      }
-    },
-    {
-      "name": "{{ project_name }}-beat",
-      "script": "bash scripts/celery_beat.sh",
-      "log_file": "./logs/celery_beat.log",
-      "env": {
-        "LOG_LEVEL": "INFO"
-      }
-    },
-    {
-      "name": "{{ project_name }}-flower",
-      "script": "bash scripts/celery_flower.sh",
-      "log_file": "./logs/flower.log",
-      "env": {
-        "FLOWER_HOST": "0.0.0.0",
-        "FLOWER_PORT": "5555",
-        "LOG_LEVEL": "INFO"
-      }
-    }
-  ]
-}
-{% endif %}