@wneng/create-keel 0.3.6 → 0.4.0

package/src/templates/root-files/files/AGENTS.md

@@ -45,7 +45,9 @@
 | `.claude/`   | AI        | Claude Code slash-commands                           |
 <% } %>
 
-### 1.1 单应用 vs 多应用模式
+<% if (it.options.database !== 'none') { %>> **数据库相关产物**（已启用 `database=<%= it.options.database %>`）：`server/db/`（迁移、种子<% if (it.options.database === 'elasticsearch') { %>、ES index template<% } %>、运维脚本入口）的归属规则见 [`docs/governance/database.md`](docs/governance/database.md)。<% if (it.options.backend === 'java') { %> Java + <%= it.options.database === 'elasticsearch' ? 'spring-data-elasticsearch' : 'Flyway' %> 因 Spring Boot classpath 约定，<%= it.options.database === 'elasticsearch' ? 'index template' : '迁移' %>文件实际在 `server/src/main/resources/<%= it.options.database === 'elasticsearch' ? 'index-templates/' : 'db/migration/' %>`。<% } %>
+
+<% } %>### 1.1 单应用 vs 多应用模式
 
 每个执行环境目录（`server/` `web/` `mobile/` `miniapp/` `agent/`）默认处于**单应用模式**。需要容纳第二个应用时切换到**多应用模式**：
 
@@ -176,7 +178,8 @@
 | `docs/assets/**` 或根 `.gitattributes` | `docs/governance/assets.md` |
 | `ops/**` 或 `deploy/**` | `docs/governance/deploy-ops.md`、`docs/governance/security.md` |
 | `tools/**` 或 `scripts/**` | `docs/governance/tools-scripts.md` |
-<% if (it.options.ci === 'gitee') { %>| `.gitee/**` | `docs/governance/ci.md`、`docs/governance/security.md` |
+<% if (it.options.database !== 'none') { %>| `server/db/**`（迁移 / 种子 / ES template / applier） | `docs/governance/database.md`、`contracts/dictionaries/`（如改字典 seed） |
+<% } %><% if (it.options.ci === 'gitee') { %>| `.gitee/**` | `docs/governance/ci.md`、`docs/governance/security.md` |
 <% } else { %>| `.github/**` | `docs/governance/ci.md`、`docs/governance/security.md` |
 <% } %>
 
@@ -205,6 +208,7 @@
 | ops / deploy 完整规则 | [`docs/governance/deploy-ops.md`](docs/governance/deploy-ops.md) |
 | tools / scripts 完整规则 | [`docs/governance/tools-scripts.md`](docs/governance/tools-scripts.md) |
 | 变更分级（六档 Tier） | [`docs/governance/change-tiers.md`](docs/governance/change-tiers.md) |
+| 数据库目录 / 迁移工具 / SQL 归属 | [`docs/governance/database.md`](docs/governance/database.md) |
 | 完整 checklist | [`docs/governance/checklists.md`](docs/governance/checklists.md) |
 | 治理细则索引 | [`docs/governance/README.md`](docs/governance/README.md) |
 

package/src/templates/server-python/files/README.md

@@ -1,4 +1,77 @@
 # server/
 
-Python backend for **<%= it.options.projectName %>**. Contract-first; see
-`contracts/openapi/api.yaml` for the authoritative API definition.
+Python backend for **<%= it.options.projectName %>**, built on **FastAPI**.
+
+> Contract First：路由 / 请求体 / 响应体应当与 [`../contracts/openapi/api.yaml`](../contracts/openapi/api.yaml) 对齐。新增端点的工作流见根 `AGENTS.md` §6（变更分级）+ `docs/governance/change-tiers.md`：端点新增 / 字段新增是 Tier 3，必须先冻结 contracts 再写实现。
+
+## 目录布局
+
+```
+server/
+├── pyproject.toml             # 依赖钉版本、ruff / mypy / pytest 配置
+├── app/
+│   ├── __init__.py            # re-export `app` 给 `python -m app`
+│   ├── main.py                # FastAPI 实例 + /healthz + CORS
+│   └── config.py              # pydantic-settings；从环境 / .env 读配置
+└── tests/
+    └── test_healthz.py        # ASGI smoke test
+```
+
+## 工具与版本
+
+| 项 | 值 |
+|---|---|
+| Python | 3.11+ |
+| Framework | FastAPI `0.115.5` |
+| ASGI server | uvicorn `0.32.0` |
+| Validation | pydantic `2.9.2` + pydantic-settings `2.6.1` |
+| Lint / format | ruff `0.6.8+` |
+| Type check | mypy `1.11.0+`（strict-ish） |
+| Test | pytest `8.3.0+` + pytest-asyncio + httpx |
+
+版本钉死见 `pyproject.toml`，并镜像到 `docs/03-工程规范与研发基础设施/tech-stack-server.md`。governance-lint 检测两边漂移并阻断 PR。
+
+## 常用命令
+
+```bash
+# 创建虚拟环境 + 装依赖
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+# 本地开发（热加载）
+uvicorn app.main:app --reload --port 8000
+# 浏览自动生成的 OpenAPI UI：http://127.0.0.1:8000/docs
+
+# 测试 / lint / format / typecheck
+pytest -q
+ruff check .
+ruff format --check .
+mypy .
+
+# 安全扫描
+pip-audit
+```
+
+## 配置
+
+环境变量优先级：CLI / 容器注入 > `.env` 文件 > `app/config.py` 默认值。
+
+|  变量 | 默认 | 说明 |
+|---|---|---|
+| `APP_NAME` | `<projectName>-server` | 显示在 OpenAPI title |
+| `APP_VERSION` | `0.1.0` | 显示在 OpenAPI version |
+| `CORS_ALLOW_ORIGINS` | `["http://localhost:5173","http://localhost:3000"]` | 逗号分隔；生产环境收紧 |
+
+## 部署
+
+打包 / 镜像 / 流水线归 `deploy/` 与 `ops/`，详见 [`../docs/governance/deploy-ops.md`](../docs/governance/deploy-ops.md)。最小生产命令示例：
+
+```bash
+uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
+```
+
+## 与契约的同步
+
+- API 端点：`contracts/openapi/api.yaml` → `app/main.py` 路由；改契约同 PR 改实现
+- 字典 / 枚举：`contracts/dictionaries/enums.yaml`（如启用）→ Pydantic Enum
+- 错误码：`contracts/errors/error-codes.yaml` → Exception → HTTP status 映射

package/src/templates/server-python/files/app-init.py

@@ -1 +1,11 @@
-"""Package marker. Implement per contracts/openapi/api.yaml."""
+"""<%= it.options.projectName %>-server.
+
+Application package. Entry point: app.main:app
+Run locally: `uvicorn app.main:app --reload`
+
+Contract First：路由实现见 contracts/openapi/api.yaml；新端点先改契约再写代码。
+"""
+
+from .main import app
+
+__all__ = ["app"]

package/src/templates/server-python/files/config.py

@@ -0,0 +1,40 @@
+"""Application configuration via pydantic-settings.
+
+环境变量映射规则：
+  - 全部大写、`_` 分隔
+  - 嵌套字段用 `__` 分隔（pydantic-settings 默认）
+  - 例：APP_NAME / APP_VERSION / CORS_ALLOW_ORIGINS=http://localhost:5173,http://localhost:3000
+
+`.env` 文件由 pydantic-settings 自动加载（项目根目录）。
+"""
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Runtime settings.
+
+    新增字段必须：
+      - 给默认值（不要让生产环境因缺一个变量启动崩溃）
+      - 同步更新根 `.env.example`（如启用 contracts-base fragment）
+      - 敏感字段（密钥、token）只能从环境变量读，绝不写默认值
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    app_name: str = Field(default="<%= it.options.projectName %>-server")
+    app_version: str = Field(default="0.1.0")
+
+    # CORS：逗号分隔字符串解析为列表
+    cors_allow_origins: list[str] = Field(
+        default_factory=lambda: ["http://localhost:5173", "http://localhost:3000"]
+    )
+
+
+settings = Settings()

package/src/templates/server-python/files/main.py

@@ -0,0 +1,62 @@
+"""<%= it.options.projectName %>-server entry point.
+
+Contract First：路由 / 请求体 / 响应体应当与 contracts/openapi/api.yaml 对齐。
+新增端点的工作流见根 AGENTS.md §6（变更分级）+ docs/governance/change-tiers.md：
+端点新增 / 字段新增是 Tier 3，必须先冻结 contracts/openapi/api.yaml 再写实现。
+"""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from .config import settings
+
+
+@asynccontextmanager
+async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
+    """启动 / 关闭钩子。
+
+    在这里做：
+      - 数据库连接池初始化（如启用 db）
+      - Elasticsearch 客户端初始化（如启用 db=elasticsearch）
+      - 后台任务启动
+    关闭时反向清理。
+    """
+    yield
+
+
+app = FastAPI(
+    title=settings.app_name,
+    version=settings.app_version,
+    description="Generated by @wneng/create-keel; implement per contracts/openapi/api.yaml.",
+    lifespan=lifespan,
+)
+
+# CORS — 默认放开本地前端开发常用端口；生产请通过环境变量收紧 allow_origins
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_allow_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/healthz", tags=["meta"])
+async def healthz() -> dict[str, str]:
+    """Liveness 探针。
+
+    部署时由 Kubernetes / Docker Compose 周期性调用；返回非 200 即视为不健康。
+    """
+    return {"status": "ok"}
+
+
+@app.get("/", tags=["meta"])
+async def root() -> dict[str, str]:
+    return {
+        "name": settings.app_name,
+        "version": settings.app_version,
+        "docs": "/docs",
+    }

package/src/templates/server-python/files/pyproject.toml

@@ -2,13 +2,20 @@
 name = "<%= it.options.projectName %>-server"
 version = "0.1.0"
 requires-python = ">=3.11"
-dependencies = []
+dependencies = [
+  "fastapi==0.115.5",
+  "uvicorn[standard]==0.32.0",
+  "pydantic==2.9.2",
+  "pydantic-settings==2.6.1",
+]
 
 [project.optional-dependencies]
 dev = [
   "ruff>=0.6.8",
   "mypy>=1.11.0",
   "pytest>=8.3.0",
+  "pytest-asyncio>=0.24.0",
+  "httpx>=0.27.0",
   "pip-audit>=2.7.0",
 ]
 
@@ -47,3 +54,9 @@ exclude = ["generated", ".venv"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+asyncio_mode = "auto"
+
+# 显式声明应用包，避免 setuptools 把 generated/ 误认为顶层包导致 build error
+[tool.setuptools.packages.find]
+include = ["app*"]
+exclude = ["tests*", "generated*"]

package/src/templates/server-python/files/test_healthz.py

@@ -0,0 +1,36 @@
+"""Smoke test for the healthz endpoint.
+
+CI 跑 `pytest -q` 时会运行；端到端验证：
+  - FastAPI app 能 import（语法、依赖、配置都对）
+  - lifespan 钩子能起、能落
+  - /healthz 返回 200 + {"status": "ok"}
+
+新加端点应在 tests/ 下补对应测试；契约级断言（响应 schema 一致性）由
+contracts/tests/contracts/ 下的契约测试覆盖，不在这里重复。
+"""
+
+import pytest
+from httpx import ASGITransport, AsyncClient
+
+from app.main import app
+
+
+@pytest.mark.asyncio
+async def test_healthz_returns_ok() -> None:
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        response = await client.get("/healthz")
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}
+
+
+@pytest.mark.asyncio
+async def test_root_returns_metadata() -> None:
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        response = await client.get("/")
+    assert response.status_code == 200
+    body = response.json()
+    assert body["name"].endswith("-server")
+    assert body["version"] == "0.1.0"
+    assert body["docs"] == "/docs"

package/src/templates/server-python/fragment.yaml

@@ -1,5 +1,5 @@
 name: server-python
-version: 1.0.0
+version: 1.1.0
 appliesWhen:
   backend: python
 priority: 30
@@ -12,6 +12,15 @@ files:
     render: true
   - from: files/app-init.py
     to: server/app/__init__.py
+    render: true
+  - from: files/main.py
+    to: server/app/main.py
+    render: true
+  - from: files/config.py
+    to: server/app/config.py
+    render: true
+  - from: files/test_healthz.py
+    to: server/tests/test_healthz.py
     render: false
   - from: files/generated-gitkeep
     to: server/generated/.gitkeep