create-dwy 0.5.0 → 0.6.0

package/templates/claude-global/rules/{python-code-style.md → dwy-python-core.md}

@@ -1,18 +1,11 @@
 ---
-name: python-code-style
-description: Python + FastAPI 代码规范
-type: claude-rule
-tags: [python, fastapi, code-style]
+description: Python + FastAPI 基础风格(命名/类型/异步/配置/日志/错误处理等)
 paths:
   - "**/*.py"
   - "**/pyproject.toml"
-version: 1.0.0
-author: chances
 ---
 
-# Python + FastAPI 代码规范
-
-所有 Python / FastAPI 项目必须遵循以下规范。AI 生成或修改代码时，必须严格按照这些规则执行。
+# Python + FastAPI 基础风格
 
 ## 一、项目结构
 
@@ -133,6 +126,33 @@ known-first-party = ["app"]
 | 路由函数 | `snake_case` 动词开头 | `create_user()`、`list_orders()` |
 | Pydantic Schema | `PascalCase` + 用途后缀 | `UserCreate`、`UserResponse`、`UserUpdate` |
 
+### 禁止魔法字符串
+
+同一个字符串字面量在文件内出现 2 次及以上时，**必须**提取为常量。
+
+```python
+# ❌ 魔法字符串散落多处
+redis.set("user:token:123", token)
+cached = redis.get("user:token:123")
+
+# ✅ 提取为常量
+USER_TOKEN_KEY = "user:token:{user_id}"
+redis.set(USER_TOKEN_KEY.format(user_id=123), token)
+cached = redis.get(USER_TOKEN_KEY.format(user_id=123))
+
+# ❌ cache key、队列名、header 名等重复字面量
+request.headers.get("X-Request-Id")
+response.headers["X-Request-Id"] = rid
+
+# ✅ 跨模块共享的 key 放到常量模块
+# constants.py
+HEADER_REQUEST_ID = "X-Request-Id"
+CACHE_PREFIX_USER = "user:"
+TASK_QUEUE_DEFAULT = "default"
+```
+
+**判断标准：** 同一字符串在同一文件出现 ≥ 2 次 → 提取为常量。跨模块使用的 key → 提取到 `constants.py` 共享。
+
 ### 禁止的写法
 
 ```python
@@ -189,277 +209,6 @@ class UserProfile:
 - 不得使用 `Any` 作为"懒标注"，除非与外部动态库交互且无法确定类型
 - 使用 `Any` 时必须附注释说明原因
 
-## 五、FastAPI 路由与接口设计
-
-### 路由组织
-
-```python
-# routers/user.py
-from fastapi import APIRouter, Depends, status
-
-router = APIRouter(prefix="/users", tags=["users"])
-
-@router.post("/", status_code=status.HTTP_201_CREATED, response_model=UserResponse)
-async def create_user(
-    body: UserCreate,
-    service: UserService = Depends(get_user_service),
-) -> UserResponse:
-    return await service.create(body)
-```
-
-### 强制规则
-- 每个路由模块使用独立 `APIRouter`，在 `main.py` 中统一注册
-- **禁止**所有路由写在 `main.py` 中（超过 2 个路由必须拆分）
-- 路由函数只做：参数接收 → 调用 service → 返回结果，**不写业务逻辑**
-- 必须显式声明 `status_code` 和 `response_model`
-- 路由路径使用复数名词 + RESTful 风格
-
-### RESTful 路由规范
-
-| 操作 | 方法 | 路径 | 状态码 |
-|---|---|---|---|
-| 列表查询 | `GET` | `/users` | 200 |
-| 详情查询 | `GET` | `/users/{user_id}` | 200 |
-| 创建 | `POST` | `/users` | 201 |
-| 全量更新 | `PUT` | `/users/{user_id}` | 200 |
-| 部分更新 | `PATCH` | `/users/{user_id}` | 200 |
-| 删除 | `DELETE` | `/users/{user_id}` | 204 |
-
-### 分页查询
-
-```python
-# schemas/common.py
-class PaginationParams(BaseModel):
-    page: int = Field(default=1, ge=1)
-    page_size: int = Field(default=20, ge=1, le=100)
-
-class PaginatedResponse[T](BaseModel):
-    items: list[T]
-    total: int
-    page: int
-    page_size: int
-
-# routers/user.py
-@router.get("/", response_model=PaginatedResponse[UserResponse])
-async def list_users(
-    pagination: PaginationParams = Depends(),
-    service: UserService = Depends(get_user_service),
-) -> PaginatedResponse[UserResponse]:
-    return await service.list(pagination)
-```
-
-## 六、Pydantic Schema 规范
-
-### 强制规则
-- 请求和响应使用不同的 Schema，**禁止**复用同一个 Model
-
-```python
-# schemas/user.py
-
-class UserBase(BaseModel):
-    """共享字段基类"""
-    name: str = Field(max_length=50)
-    email: EmailStr
-
-class UserCreate(UserBase):
-    """创建请求"""
-    password: str = Field(min_length=8)
-
-class UserUpdate(BaseModel):
-    """更新请求 - 所有字段可选"""
-    name: str | None = Field(default=None, max_length=50)
-    email: EmailStr | None = None
-
-class UserResponse(UserBase):
-    """响应"""
-    id: int
-    is_active: bool
-    created_at: datetime
-
-    model_config = ConfigDict(from_attributes=True)
-```
-
-- **禁止**在响应 Schema 中暴露密码、内部 ID、敏感字段
-- 使用 `Field()` 添加校验约束（`min_length`、`ge`、`le`、`pattern` 等）
-- 更新 Schema 的字段必须全部可选（`None` 默认值）
-
-## 七、依赖注入
-
-### 强制规则
-- 数据库会话、当前用户、配置等通过 `Depends()` 注入
-- **禁止**在路由函数中直接创建数据库会话或实例化 service
-
-```python
-# dependencies.py
-from collections.abc import AsyncGenerator
-
-async def get_db() -> AsyncGenerator[AsyncSession]:
-    async with async_session_factory() as session:
-        yield session
-
-async def get_current_user(
-    token: str = Depends(oauth2_scheme),
-    db: AsyncSession = Depends(get_db),
-) -> User:
-    user = await authenticate(token, db)
-    if not user:
-        raise HTTPException(status_code=401, detail="认证失败")
-    return user
-
-def get_user_service(db: AsyncSession = Depends(get_db)) -> UserService:
-    return UserService(db)
-```
-
-```python
-# ❌ 路由中直接创建会话
-@router.get("/users/{user_id}")
-async def get_user(user_id: int):
-    async with async_session_factory() as db:
-        user = await db.get(User, user_id)
-        return user
-
-# ✅ 依赖注入
-@router.get("/users/{user_id}", response_model=UserResponse)
-async def get_user(
-    user_id: int,
-    service: UserService = Depends(get_user_service),
-) -> UserResponse:
-    return await service.get_by_id(user_id)
-```
-
-## 八、异常处理
-
-### 统一异常体系
-
-```python
-# exceptions.py
-from fastapi import FastAPI, Request, status
-from fastapi.responses import JSONResponse
-
-# 业务异常基类
-class AppError(Exception):
-    def __init__(self, message: str, code: str = "UNKNOWN_ERROR") -> None:
-        self.message = message
-        self.code = code
-
-class NotFoundError(AppError):
-    def __init__(self, resource: str, resource_id: int | str) -> None:
-        super().__init__(
-            message=f"{resource} 不存在",
-            code="NOT_FOUND",
-        )
-        self.resource = resource
-        self.resource_id = resource_id
-
-class BusinessError(AppError):
-    """业务规则校验失败"""
-    pass
-
-class PermissionDeniedError(AppError):
-    """权限不足"""
-    pass
-
-# 注册异常处理器
-def register_exception_handlers(app: FastAPI) -> None:
-    @app.exception_handler(NotFoundError)
-    async def not_found_handler(request: Request, exc: NotFoundError) -> JSONResponse:
-        return JSONResponse(
-            status_code=status.HTTP_404_NOT_FOUND,
-            content={"code": exc.code, "message": exc.message},
-        )
-
-    @app.exception_handler(BusinessError)
-    async def business_error_handler(request: Request, exc: BusinessError) -> JSONResponse:
-        return JSONResponse(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
-            content={"code": exc.code, "message": exc.message},
-        )
-
-    @app.exception_handler(PermissionDeniedError)
-    async def permission_denied_handler(request: Request, exc: PermissionDeniedError) -> JSONResponse:
-        return JSONResponse(
-            status_code=status.HTTP_403_FORBIDDEN,
-            content={"code": exc.code, "message": exc.message},
-        )
-```
-
-### 强制规则
-- **禁止**在 service 层抛出 `HTTPException`（service 不感知 HTTP）
-- service 层抛出业务异常，由异常处理器统一转换为 HTTP 响应
-- **禁止**裸 `except:` 或 `except Exception: pass`
-- 错误响应格式统一为 `{"code": "ERROR_CODE", "message": "描述"}`
-- **禁止**在错误消息中回显用户输入
-
-```python
-# ❌ service 中抛 HTTPException
-class UserService:
-    async def get_by_id(self, user_id: int) -> User:
-        user = await self.db.get(User, user_id)
-        if not user:
-            raise HTTPException(status_code=404)  # 耦合 HTTP
-        return user
-
-# ✅ service 中抛业务异常
-class UserService:
-    async def get_by_id(self, user_id: int) -> User:
-        user = await self.db.get(User, user_id)
-        if not user:
-            raise NotFoundError("用户", user_id)
-        return user
-```
-
-## 九、数据库与 ORM
-
-### 强制规则
-- 使用 **SQLAlchemy 2.0** 风格（声明式映射 + async）
-- 数据库迁移使用 **Alembic**，**禁止**手动执行 DDL
-- **禁止**在路由层直接写 SQL 查询
-
-```python
-# models/base.py
-from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
-from sqlalchemy import func
-from datetime import datetime
-
-class Base(DeclarativeBase):
-    pass
-
-class TimestampMixin:
-    created_at: Mapped[datetime] = mapped_column(server_default=func.now())
-    updated_at: Mapped[datetime] = mapped_column(server_default=func.now(), onupdate=func.now())
-
-# models/user.py
-class User(Base, TimestampMixin):
-    __tablename__ = "users"
-
-    id: Mapped[int] = mapped_column(primary_key=True)
-    name: Mapped[str] = mapped_column(String(50))
-    email: Mapped[str] = mapped_column(String(100), unique=True, index=True)
-    hashed_password: Mapped[str] = mapped_column(String(128))
-    is_active: Mapped[bool] = mapped_column(default=True)
-```
-
-### 异步数据库会话
-
-```python
-# config.py / database.py
-from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
-
-engine = create_async_engine(settings.database_url, echo=settings.debug)
-async_session_factory = async_sessionmaker(engine, expire_on_commit=False)
-```
-
-### 查询规范
-
-```python
-# ❌ 旧式查询
-session.query(User).filter(User.id == user_id).first()
-
-# ✅ SQLAlchemy 2.0 风格
-result = await session.execute(select(User).where(User.id == user_id))
-user = result.scalar_one_or_none()
-```
-
 ## 十、异步编程
 
 ### 强制规则
@@ -527,38 +276,88 @@ app.add_middleware(
 
 ### 强制规则
 - 使用 Pydantic Settings 管理配置
+- **必须使用嵌套模型分组**，禁止所有字段平铺在一个类中
 
 ```python
 # config.py
+from pydantic import BaseModel
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
-class Settings(BaseSettings):
-    # 应用
-    app_name: str = "My API"
-    debug: bool = False
-
-    # 数据库
-    database_url: str
-    db_pool_size: int = 5
+# 按领域拆分为独立的配置类（普通 BaseModel，不是 BaseSettings）
+class OssConfig(BaseModel):
+    endpoint: str = ""
+    access_key: str = ""
+    secret_key: str = ""
+    bucket: str = ""
 
-    # Redis
-    redis_url: str = "redis://localhost:6379"
+class AliyunSmsConfig(BaseModel):
+    access_key_id: str = ""
+    access_key_secret: str = ""
+    sign_name: str = ""
+    template_code: str = ""
 
-    # 认证
-    secret_key: str
-    access_token_expire_minutes: int = 30
+# 主 Settings 类组合嵌套模型
+class Settings(BaseSettings):
+    # eapi 内置字段（继承 BaseSettings 时自动包含）
+    # database_url, redis_url, secret_key, ...
 
-    # CORS
-    allowed_origins: list[str] = ["http://localhost:3000"]
+    # 项目专属 — 嵌套分组
+    app_name: str = "My App"
+    oss: OssConfig = OssConfig()
+    aliyun_sms: AliyunSmsConfig = AliyunSmsConfig()
 
     model_config = SettingsConfigDict(
         env_file=".env",
         env_file_encoding="utf-8",
+        env_nested_delimiter="__",  # 关键：启用嵌套分隔符
     )
 
 settings = Settings()
 ```
 
+**`.env` 文件中用 `__` 分隔层级：**
+
+```bash
+# 基础字段（eapi 内置）
+DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/mydb
+REDIS_URL=redis://localhost:6379/0
+SECRET_KEY=your-secret-key
+
+# 嵌套字段 — 用双下划线 __ 分隔
+OSS__ENDPOINT=http://localhost:9000
+OSS__ACCESS_KEY=minioadmin
+OSS__SECRET_KEY=minioadmin
+OSS__BUCKET=my-app
+
+ALIYUN_SMS__ACCESS_KEY_ID=AKID123
+ALIYUN_SMS__ACCESS_KEY_SECRET=secret456
+ALIYUN_SMS__SIGN_NAME=我的应用
+ALIYUN_SMS__TEMPLATE_CODE=SMS_123456
+```
+
+**代码中通过属性链访问：**
+
+```python
+# ✅ 分组清晰
+settings.oss.endpoint
+settings.oss.bucket
+settings.aliyun_sms.access_key_id
+
+# ❌ 禁止扁平命名
+settings.oss_endpoint
+settings.oss_access_key
+settings.aliyun_sms_access_key_id
+```
+
+### 分组原则
+
+| 场景 | 做法 |
+|------|------|
+| eapi 内置字段（database_url 等） | 保持顶层，不嵌套 |
+| 同一服务/SDK 的多个配置 | 拆成独立 `BaseModel` 嵌套 |
+| 只有 1 个字段 | 保持顶层，不必嵌套 |
+| 3 个以上同前缀字段 | 必须嵌套 |
+
 - **禁止**在代码中硬编码配置值（数据库地址、密钥、端口等）
 - **禁止**在模块顶层执行副作用（网络请求、数据库连接、文件读取）
 
@@ -592,49 +391,6 @@ logger.info("user_created", user_id=user_id)
 | `ERROR` | 错误但服务仍可用（单次请求失败） |
 | `CRITICAL` | 服务不可用（数据库连接断开、必要服务宕机） |
 
-## 十四、测试
-
-### 强制规则
-- 使用 `pytest` + `pytest-asyncio` + `httpx`
-- 使用 `TestClient` 或 `AsyncClient` 测试 API
-
-```python
-# conftest.py
-import pytest
-from httpx import ASGITransport, AsyncClient
-from app.main import app
-
-@pytest.fixture
-async def client():
-    async with AsyncClient(
-        transport=ASGITransport(app=app),
-        base_url="http://test",
-    ) as ac:
-        yield ac
-
-# test_user.py
-@pytest.mark.anyio
-async def test_create_user_returns_201(client: AsyncClient):
-    response = await client.post("/users/", json={
-        "name": "Alice",
-        "email": "alice@example.com",
-        "password": "securepass123",
-    })
-    assert response.status_code == 201
-    data = response.json()
-    assert data["name"] == "Alice"
-    assert "password" not in data  # 响应不包含密码
-
-@pytest.mark.anyio
-async def test_get_nonexistent_user_returns_404(client: AsyncClient):
-    response = await client.get("/users/99999")
-    assert response.status_code == 404
-```
-
-- 测试函数名描述行为而非实现
-- 测试数据使用 `pytest.fixture`，不要硬编码
-- 测试结构遵循 Arrange-Act-Assert
-
 ## 十五、函数与类设计
 
 ### 强制规则
@@ -847,32 +603,233 @@ async def create_user(body: UserCreate) -> UserResponse:
     ...
 ```
 
-## 十九、安全编码
+## 二十、dwyeapi 优先使用
+
+### 适用条件
+
+项目依赖中包含 `dwyeapi` 时，以下规则生效。
 
 ### 强制规则
-- SQL 查询必须使用参数化绑定，**禁止**字符串拼接
-- 用户输入必须校验后使用，**禁止**直接信任
-- 文件路径操作必须防止路径遍历攻击
-- 序列化/反序列化**禁止** `pickle.loads()` 处理不可信数据
-- 密码存储必须使用 `bcrypt` / `argon2`，**禁止**明文或 MD5/SHA
-- JWT 密钥从环境变量读取，**禁止**硬编码
+
+编写 FastAPI 后端代码时，**必须优先使用 eapi 已有的类和函数**，禁止重复实现。
+
+| 需求 | 使用 eapi | 禁止自建 |
+|------|----------|---------|
+| 配置管理 | `dwyeapi.config.BaseSettings` | 自写 Pydantic Settings 基类 |
+| ORM 基类 | `dwyeapi.database.Base` + `TimestampMixin` | 自定义 DeclarativeBase |
+| 异步引擎 | `create_async_engine_factory()` + `create_session_factory()` | 手动创建 engine/session |
+| 依赖注入 | `create_get_db(session_factory)` | 手写 get_db 生成器 |
+| 密码哈希 | `hash_password()` / `verify_password()` | 直接调用 bcrypt |
+| JWT | `create_token()` / `decode_token()` | 直接调用 python-jose |
+| 异常体系 | `NotFoundError` / `BusinessError` / `register_exception_handlers()` | 自定义异常 + 手写 handler |
+| 响应格式 | `success()` / `fail()` / `paginated()` | 自定义响应包装函数 |
+| 分页 | `PaginationParams` + `paginate()` | 自写分页参数类 |
+| Redis 缓存 | `cache.configure()` / `cache.get_redis()` | 手动管理 Redis 连接 |
+| 异步任务 | `tasks.setup_tasks()` / `@register` / `TaskContext` (需 `[tasks]` extra) | 手写 ARQ/Celery 集成 |
+
+### 决策流程
+
+```
+需要某项基础设施功能
+  → 1. 检查 eapi 是否已提供（查阅 dwy-eapi skill）
+    → 已提供：直接使用，不重复实现
+    → 未提供：自行实现，代码注释中说明 eapi 不覆盖此功能
+```
+
+## 二十一、代码简约原则
+
+### 核心思想
+
+代码只写**必要的逻辑**，不写"以防万一"的冗余代码。信任内部代码和框架保证，只在系统边界（用户输入、外部 API）做校验。
+
+### 禁止的冗余模式
 
 ```python
-# ❌ SQL 注入
-cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")
+# ❌ 不必要的 fallback — 值已经有明确来源
+name = user.name or ""           # user.name 不可能是 None
+result = data.get("key", None)   # get 默认就返回 None
+
+# ✅ 直接使用
+name = user.name
+result = data.get("key")
+
+# ❌ 不必要的类型转换 — 值已经是目标类型
+count = int(params.page)         # Pydantic 已校验为 int
+text = str(title)                # title 声明为 str
+
+# ✅ 直接使用
+count = params.page
+text = title
+
+# ❌ 不必要的条件检查 — 逻辑上不可能走到 else
+if task:
+    return task
+else:
+    return None                  # 上面已经 return 了
+
+# ✅ 直接返回
+return task
+
+# ❌ 不必要的默认值 — 调用方已保证传值
+def process(data: dict = None):  # 所有调用方都传了 data
+    if data is None:
+        data = {}
+
+# ✅ 去掉默认值和检查
+def process(data: dict):
+    ...
+
+# ❌ 不必要的异常兜底 — 掩盖真正的 bug
+try:
+    result = calculate(x)
+except Exception:
+    result = 0                   # 吞掉异常，bug 永远不会被发现
+
+# ✅ 让异常暴露，或只捕获预期的异常
+result = calculate(x)
+```
+
+### 判断标准
+
+写每一行防御代码前问自己：**这个情况在当前上下文下真的会发生吗？**
+
+- 如果**会** → 写防御，加注释说明什么情况下触发
+- 如果**不会** → 不写，信任上游保证
+- 如果**不确定** → 查看调用链确认，不要"以防万一"
 
-# ✅ 参数化查询
-cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
+## 代码自检（写代码时强制执行）
 
-# ❌ 路径遍历
-file_path = f"/uploads/{user_input_filename}"
+**每次生成或修改 Python 代码后，必须逐条验证以下清单。任何一条未通过 → STOP，立即修正后再继续。**
 
-# ✅ 路径安全校验
-safe_path = Path("/uploads") / Path(user_input_filename).name
+| # | 检查项 | 违规即 STOP |
+|---|--------|------------|
+| 1 | 所有公开函数有参数 + 返回值类型标注 | ✓ |
+| 2 | 无 `Any` 类型（除非有注释说明原因） | ✓ |
+| 3 | 使用 `list[int]` / `str \| None` 等现代语法，不用 `typing.List` / `Optional` | ✓ |
+| 4 | service 层不抛 `HTTPException`，只抛业务异常 | ✓ |
+| 5 | 无裸 `except:` 或 `except Exception: pass` | ✓ |
+| 6 | 路由函数只做参数接收 → 调用 service → 返回结果，无业务逻辑 | ✓ |
+| 7 | HTTP 请求用 `httpx`，不用 `requests` | ✓ |
+| 8 | 日志用 `%s` 占位符或 structlog，不用 f-string | ✓ |
+| 9 | 生命周期用 `lifespan`，不用 `@app.on_event` | ✓ |
+| 10 | 无可变默认参数 `def f(items=[])` | ✓ |
+| 11 | Pydantic Schema 请求/响应分离，不复用 | ✓ |
+| 12 | 嵌套不超过 3 层，函数体不超过 50 行 | ✓ |
+| 13 | 所有模块/类/函数有 docstring（Google 风格） | ✓ |
+| 14 | 依赖通过 `Depends()` 注入，不在路由中直接创建 | ✓ |
+| 15 | 项目依赖 eapi 时，未重复实现 eapi 已有功能 | ✓ |
 
-# ❌ 硬编码密钥
-SECRET_KEY = "my-super-secret-key"
+**不执行自检就提交代码 = 违规。**
 
-# ✅ 环境变量
-SECRET_KEY = settings.secret_key
+---
+
+## 错误处理规范(后端)
+
+**唯一方式：** 使用 eapi exceptions 体系。
+
+```python
+from dwyeapi.exceptions import (
+    NotFoundError,          # 404 — 资源不存在
+    BusinessError,          # 422 — 业务规则不允许
+    PermissionDeniedError,  # 403 — 无权限
+    AuthenticationError,    # 401 — 认证失败
+)
+
+# services 层
+async def get_user(db: AsyncSession, user_id: int) -> User:
+    user = await db.get(User, user_id)
+    if user is None:
+        raise NotFoundError("用户")     # → {"code": "NOT_FOUND", "message": "用户不存在"}
+    return user
+
+async def create_order(db: AsyncSession, data: OrderCreate) -> Order:
+    if data.amount <= 0:
+        raise BusinessError("订单金额必须大于 0", code="INVALID_AMOUNT")
+    ...
+```
+
+**禁止清单：**
+| 禁止写法 | 正确写法 |
+|---------|---------|
+| `raise HTTPException(status_code=404)` | `raise NotFoundError("资源名")` |
+| `try: ... except Exception: pass` | 只捕获预期的具体异常 |
+| 自定义异常类不继承 AppError | 项目异常必须继承 `AppError` |
+| 在 router 中 try/except 包 service 调用 | 让异常自然冒泡到 handler |
+
+---
+
+## 环境变量管理(后端:eapi BaseSettings + 嵌套分组)
+
+**必须使用嵌套模型分组配置**，禁止所有字段平铺。同一服务/SDK 的多个字段拆成独立 `BaseModel`。
+
+```python
+# app/config.py
+from pydantic import BaseModel
+from dwyeapi.config import BaseSettings
+
+class OssConfig(BaseModel):
+    endpoint: str = ""
+    access_key: str = ""
+    secret_key: str = ""
+    bucket: str = ""
+
+class Settings(BaseSettings):
+    # eapi 内置字段保持顶层：database_url, redis_url, secret_key, ...
+
+    # 项目专属 — 嵌套分组
+    app_name: str = "My App"
+    oss: OssConfig = OssConfig()
+```
+
+**`.env` 中用 `__` 双下划线分隔层级：**
+
+```bash
+DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/mydb
+OSS__ENDPOINT=http://localhost:9000
+OSS__ACCESS_KEY=minioadmin
+OSS__SECRET_KEY=minioadmin
+OSS__BUCKET=my-app
 ```
+
+**代码中通过属性链访问：** `settings.oss.endpoint`，禁止 `settings.oss_endpoint`。
+
+详细规则见 `dwy-python-core.md` 第十二节。
+
+---
+
+## 日志规范
+
+### 后端
+
+使用 Python 标准 `logging` 模块：
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+# 正确用法
+logger.info("用户 %s 登录成功", user_id)
+logger.error("导出任务失败: task_id=%s, error=%s", task_id, str(e))
+
+# 禁止
+print("debug info")                    # 禁止 print
+logger.info(f"用户 {user_id} 登录")    # 禁止 f-string（无法被日志聚合）
+```
+
+### 日志级别规则
+
+| 级别 | 用途 | 示例 |
+|------|------|------|
+| DEBUG | 开发调试信息，生产环境不输出 | 变量值、SQL 语句 |
+| INFO | 关键业务流程节点 | 用户登录、任务提交、导出完成 |
+| WARNING | 异常但可恢复的情况 | 重试成功、降级处理 |
+| ERROR | 错误但服务仍可用（单次请求失败） | 外部 API 超时、单个任务失败 |
+| CRITICAL | 服务不可用 | 数据库连接断开、必要服务宕机 |
+
+### 禁止事项
+
+- 禁止 `print()`，全部用 `logger`
+- 禁止在循环体内打 INFO/WARNING 日志（大量重复）
+- 禁止日志中包含密码、token、密钥等敏感信息
+- 禁止用 f-string 格式化日志消息（用 `%s` 占位符，支持日志聚合延迟求值）