leaudit-platform-backend/.claude/skills/coding-standards.md

---
name: coding-standards
description: 项目编码规范。在编写任何业务代码（控制器、服务层、模型、DTO/VO、配置）时必须遵循此规范。当用户要求"新增功能"、"写业务代码"、"添加服务"、"创建模型"、"写接口"、"添加 DTO"等涉及编码实现的场景时，都应使用此技能确保代码风格一致。即使用户没有明确提到"规范"，只要是在本项目中编写代码，就应当参照此技能。
---

# 项目编码规范

## 基础约定

- Python 3.12，使用现代类型语法：`list[str]`、`str | None`（不用 `List[str]`、`Optional[str]`）
- 文件编码 UTF-8
- Ruff 规则：行长 130，`__init__.py` 中忽略 F401
- 模块顶部第一行写 docstring（三引号），所有类和公开方法都写中文 docstring
- 完全面向对象编程，不允许类外部的模块级业务函数（配置模块除外）
- `domian` 是项目约定拼写（不是 `domain`），绝对不要"修正"

## 项目分层架构

```
Controller → Service（IXxxService 接口 + XxxServiceImpl 实现）→ Model（充血模型）
```

每一层的职责清晰：
- **控制器**：负责 HTTP 路由，从 DTO 拆值 → 调 Service → 返回响应。显式声明 `response_model`
- **服务层**：负责业务编排，调用 Model 的充血方法做持久化，**从 Model 实例组装 VO 返回**
- **模型层**（充血模型）：SQLAlchemy 实体 + 数据库操作方法（`@classmethod` 查询/写入），**禁止引用 DTO/VO/BO，禁止转换方法**

### DTO / VO / BO 分层规则

| 层级 | DTO | VO | BO |
|------|-----|----|----|
| Controller | 入参类型注解 | `response_model` 声明 + 接收 Service 返回 | — |
| Service | **禁止** | 组装并返回（对接 Controller） | 组装并返回（对接 Task/Handler） |
| Task / Handler | **禁止** | **禁止** | 入参接收 |
| Model | **禁止** | **禁止** | **禁止** |

- **DTO**（Data Transfer Object）：请求入参，**只允许出现在控制器层**。控制器负责从 DTO 中取值，以原始类型传给服务层
- **VO**（View Object）：响应出参，**由服务层负责组装并返回**。控制器通过 `response_model=Result[list[XxxVO]]` 显式声明响应模型
- **BO**（Business Object）：业务对象，当服务层需要向 Task / Handler 等其他层级传递数据时，必须用 BO 包裹做验证
- **Model 层充血模型**：字段定义 + 数据库操作方法（`@classmethod`），**禁止引用 DTO/VO/BO，禁止转换方法**（如 `ToVo`、`FromDto` 等）
- **服务层入参使用原始类型**（str、int 等），控制器负责 DTO → 原始类型的拆解；**服务层返回值使用 VO**（对接控制器）或 **BO**（对接 Task/Handler）

## 导入规范

**所有导入必须使用完整路径**，禁止裸名导入（如 `from models import User`、`from domian.Dto import XxxDTO`）。即使 `sys.path` 中已包含模块目录，也必须写完整的包路径，确保代码可读性和 IDE 可追踪。

```python
# fastapi_common 子模块——完整路径
from fastapi_common.fastapi_common_logger import logger
from fastapi_common.fastapi_common_web.controller import BaseController
from fastapi_common.fastapi_common_web.domain.responses import Result, StatusCodeEnum
from fastapi_common.fastapi_common_web.exception.Base.BusinessException import BusinessException
from fastapi_common.fastapi_common_sqlalchemy.base import Base
from fastapi_common.fastapi_common_sqlalchemy.database import GetAsyncSession

# 业务模块内部——也必须完整路径（以 fastapi_xxx 开头）
from fastapi_admin.config.app import APP_NAME
from fastapi_xxx.models import User
from fastapi_xxx.services import IUserService
from fastapi_xxx.services.impl.userServiceImpl import UserServiceImpl

# DTO 只在控制器层导入，VO 允许在控制器层和服务层导入
from fastapi_xxx.domian.Dto.userDto import UserCreateDTO       # ← 仅 controllers 层
from fastapi_xxx.domian.vo.userVo import UserVO                # ← controllers 层 + services 层
```

## 打包与目录约定

- 业务主包目录：`fastapi_modules/fastapi_xxx/`（`xxx` 为实际业务模块名）
- 业务分层包以裸名导入：`controllers`、`services`、`models`、`domian`、`handler`、`tasks`
- `pyproject.toml` 使用 `setuptools.packages.find` 自动发现包，不再手工维护 `packages = [...]`
- 新增业务模块时，目录命名必须使用下划线（`snake_case`），禁止连字符（`-`）

## 控制器层 (`fastapi_modules/fastapi_xxx/controllers/`)

继承 `BaseController`，在 `Init` 中用 `@self.router.get/post` 注册路由。放入 `fastapi_modules/fastapi_xxx/controllers/` 目录后自动被扫描注册，无需手动配置。

**控制器类内部除了 `Init` 外不允许定义任何额外方法**（包括私有方法）。控制器只负责：取参数 → 调 Service → 返回响应。

### 依赖获取方式

服务层依赖有两种来源：

1. **无状态服务**：在控制器 `Init` 中直接实例化，endpoint 通过闭包访问
2. **有状态 / lifespan 初始化的服务**：在 endpoint 内通过 `RequestObj.app.state.xxx` 直接获取，不需要额外方法

```python
# 示例 1：无状态服务——闭包访问
# fastapi_modules/fastapi_xxx/controllers/userController.py
"""用户控制器。"""

from fastapi_common.fastapi_common_web.controller import BaseController
from fastapi_common.fastapi_common_web.domain.responses import Result

from domian.Dto import UserCreateDTO
from domian.vo import UserVO
from services import IUserService
from services.impl.userServiceImpl import UserServiceImpl


class UserController(BaseController):
    """用户控制器。"""

    def __init__(self):
        super().__init__(prefix="/user", tags=["用户管理"])
        self.UserService: IUserService = UserServiceImpl()

        @self.router.get("/{UserId}", response_model=Result[list[UserVO]])
        async def GetUser(UserId: int):
            """获取用户详情

            根据用户 ID 查询用户信息。
            """
            # Service 返回 VO
            Data = await self.UserService.GetById(UserId)
            return Result.success(data=Data.model_dump())

        @self.router.post("/", response_model=Result[list[UserVO]])
        async def CreateUser(body: UserCreateDTO):
            """创建用户

            DTO 在控制器层拆解为原始类型传入 Service，Service 返回 VO。
            """
            Data = await self.UserService.Create(
                Name=body.name,
                Account=body.account,
                Password=body.password,
                Phone=body.phone,
            )
            return Result.success(data=Data.model_dump())
```

```python
# 示例 2：有状态服务——通过 RequestObj.app.state 直接获取
# fastapi_modules/fastapi_xxx/controllers/callbackController.py
"""回调控制器。"""

from fastapi import Query, Request, Response

from fastapi_common.fastapi_common_web.controller import BaseController


class CallbackController(BaseController):
    """回调控制器。"""

    def Init(self):
        super().Init(prefix="/callback", tags=["回调"])

        @self.router.get("/verify")
        async def VerifyCallback(
            RequestObj: Request,
            Signature: str = Query(..., description="签名"),
            Timestamp: str = Query(..., description="时间戳"),
            Nonce: str = Query(..., description="随机数"),
        ):
            """回调 URL 验证"""
            Service = RequestObj.app.state.callback_service
            Result = await Service.Verify(Signature, Timestamp, Nonce)
            return Response(content=Result, media_type="text/plain")
```

要点：
- endpoint 函数是普通函数（不带 `self`），通过闭包访问控制器实例属性
- 无状态服务在 `Init` 中直接实例化；有状态服务在 endpoint 内通过 `RequestObj.app.state` 直接获取
- **控制器类内部不允许任何额外方法**——不需要 `_get_xxx` 辅助方法，直接在 endpoint 中一行取出即可
- docstring 第一行 → OpenAPI summary，后续行 → description
- 所有路由统一挂载在 `/api` 前缀下

## 服务层 (`fastapi_modules/fastapi_xxx/services/`)

**这是最核心的规范，必须严格遵守。**

服务层采用接口/实现分层架构：

### 目录结构

```
fastapi_modules/fastapi_xxx/services/
├── __init__.py
├── userService.py            # IUserService 接口（抽象类）
├── orderService.py           # IOrderService 接口
└── impl/
    ├── __init__.py
    ├── userServiceImpl.py    # UserServiceImpl 实现
    └── orderServiceImpl.py   # OrderServiceImpl 实现
```

### 接口层命名：`IXxxService`

接口层使用 `I` 前缀，继承 `ABC`，所有方法标记 `@abstractmethod`。**服务层禁止引用 DTO，入参使用原始类型；返回值使用 VO（对接控制器）或 BO（对接 Task/Handler）。**

```python
# fastapi_modules/fastapi_xxx/services/userService.py
"""用户服务接口。"""

from abc import ABC, abstractmethod

from domian.vo import UserVO


class IUserService(ABC):
    """用户服务接口。"""

    @abstractmethod
    async def GetById(self, UserId: int) -> UserVO | None:
        """根据 ID 获取用户。"""
        ...

    @abstractmethod
    async def Create(self, Name: str, Account: str, Password: str, Phone: str | None = None) -> UserVO:
        """创建用户。"""
        ...

    @abstractmethod
    async def Update(self, UserId: int, **Fields) -> UserVO:
        """更新用户。"""
        ...

    @abstractmethod
    async def Delete(self, UserId: int) -> bool:
        """删除用户。"""
        ...
```

### 实现层命名：`XxxServiceImpl`

实现层放在 `services/impl/` 下，类名为 `XxxServiceImpl`，继承对应接口。**方法数必须与接口层严格一致，不允许多余的辅助方法。**

```python
# fastapi_modules/fastapi_xxx/services/impl/userServiceImpl.py
"""用户服务实现。"""

from fastapi_common.fastapi_common_logger import logger
from fastapi_common.fastapi_common_sqlalchemy.database import GetAsyncSession
from fastapi_common.fastapi_common_web.domain.responses import StatusCodeEnum
from fastapi_common.fastapi_common_web.exception.XxxException import XxxException
from fastapi_common.fastapi_common_utils.datetime_utils import FormatDatetime

from domian.vo import UserVO
from models import User
from services import IUserService


class UserServiceImpl(IUserService):
    """用户服务实现。"""

    async def GetById(self, UserId: int) -> UserVO | None:
        """根据 ID 获取用户。"""
        async with GetAsyncSession() as session:
            user = await session.get(User, UserId)
            if not user:
                raise XxxException(StatusCodeEnum.HTTP_404_NOT_FOUND, "用户不存在")
            # Service 层负责从 Model 实例组装 VO
            return UserVO(
                id=user.Id,
                name=user.Name,
                account=user.Account,
                phone=user.Phone,
                status=user.Status,
                createdAt=FormatDatetime(user.create_time) if user.create_time else None,
            )

    async def Create(self, Name: str, Account: str, Password: str, Phone: str | None = None) -> UserVO:
        """创建用户。"""
        async with GetAsyncSession() as session:
            # 调用 Model 充血方法创建用户
            user = await User.create(session, name=Name, account=Account, password=Password, phone=Phone)
            await session.commit()
            logger.info(f"创建用户成功: {user.Id}")
            return UserVO(
                id=user.Id,
                name=user.Name,
                account=user.Account,
                phone=user.Phone,
                status=user.Status,
                createdAt=FormatDatetime(user.create_time) if user.create_time else None,
            )

    async def Update(self, UserId: int, **Fields) -> UserVO:
        """更新用户。"""
        async with GetAsyncSession() as session:
            user = await session.get(User, UserId)
            if not user:
                raise XxxException(StatusCodeEnum.HTTP_404_NOT_FOUND, "用户不存在")
            for FieldName, Value in Fields.items():
                setattr(user, FieldName, Value)
            await session.commit()
            await session.refresh(user)
            return UserVO(
                id=user.Id,
                name=user.Name,
                account=user.Account,
                phone=user.Phone,
                status=user.Status,
                createdAt=FormatDatetime(user.create_time) if user.create_time else None,
            )

    async def Delete(self, UserId: int) -> bool:
        """删除用户。"""
        async with GetAsyncSession() as session:
            user = await session.get(User, UserId)
            if not user:
                raise XxxException(StatusCodeEnum.HTTP_404_NOT_FOUND, "用户不存在")
            await session.delete(user)
            await session.commit()
            logger.info(f"删除用户成功: {UserId}")
            return True
```

### 服务层铁律

1. **接口层定义了多少个方法，实现层就精确对应多少个方法**——不能增减
2. **不允许在实现类中添加任何私有方法**（如 `_build_query`、`_validate`、`_on_xxx` 等），除非用户主动要求。如果逻辑复杂需要拆分，应当拆到独立的工具类或 Model 的方法中；如果需要内部回调，使用 `Init` 中的闭包函数代替私有方法
3. **不允许类外部的模块级函数**——`from fastapi_common.fastapi_common_logger import logger` 是唯一的例外
4. **日志通道由调用栈自动推断**，无需手动指定

## 模型层 (`fastapi_modules/fastapi_xxx/models/`) — 充血模型

SQLAlchemy 2.x 声明式模型，**必须继承 `BaseModel`**（来自 `fastapi_common.fastapi_common_web.models`），不能直接继承 `Base`。`BaseModel` 是抽象基类，自动提供三个公共时间字段：

- `create_time`：INSERT 时由数据库写入当前时间
- `update_time`：INSERT 和 UPDATE 时自动更新
- `delete_time`：默认 NULL，非 NULL 表示已软删除

**模型是充血模型**，包含字段定义 + 数据库操作方法（`@classmethod` 查询/写入）。但**禁止引用 DTO/VO/BO，禁止转换方法**（如 `ToVo`、`FromDto` 等）。方法参数和返回值只使用原始类型或模型实例。VO 的组装由服务层负责。

```python
# fastapi_modules/fastapi_xxx/models/user.py
"""用户模型。"""

from sqlalchemy import String, select
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy.orm import Mapped, mapped_column

from fastapi_common.fastapi_common_web.models import BaseModel


class User(BaseModel):
    """用户表（充血模型）。"""

    __tablename__ = "sys_user"

    Id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    TenantId: Mapped[int] = mapped_column(comment="租户ID")
    Name: Mapped[str] = mapped_column(String(100), comment="用户名")
    Account: Mapped[str] = mapped_column(String(100), unique=True, comment="登录账号")
    Password: Mapped[str] = mapped_column(String(255), comment="密码哈希")
    Phone: Mapped[str | None] = mapped_column(String(20), comment="手机号")
    Status: Mapped[int] = mapped_column(default=1, comment="状态: 1启用 0禁用")
    # create_time / update_time / delete_time 自动继承自 BaseModel

    @classmethod
    async def get_by_account(cls, session: AsyncSession, account: str) -> "User | None":
        """按登录账号查询用户。"""
        return await session.scalar(select(cls).where(cls.Account == account))

    @classmethod
    async def create(cls, session: AsyncSession, name: str, account: str, password: str, phone: str | None = None) -> "User":
        """创建用户并刷新返回。"""
        user = cls(Name=name, Account=account, Password=password, Phone=phone)
        session.add(user)
        await session.flush()
        await session.refresh(user)
        return user
```

### 模型层铁律

1. **充血方法只做数据库操作**——查询、插入、更新、删除，不包含业务逻辑
2. **禁止引用 DTO/VO/BO**——方法参数使用原始类型（str、int 等）+ session，返回值为模型实例或原始类型
3. **禁止转换方法**——不允许 `ToVo()`、`FromDto()`、`UpdateFromDto()` 等，VO 组装由服务层负责
4. **充血方法使用 `@classmethod`**——接收 session 作为第一个参数（除 self 外），不在模型内部管理 session 生命周期

## 异常层 (`fastapi_common/fastapi_common_web/exception/`)

**每个业务模块必须在 `exception/` 下创建自己的异常类**，继承 `BusinessException`，文件名和类名都使用**大驼峰命名**。模块内抛异常时只使用自己的异常类，最终由全局异常中间件统一捕获并返回 `Result` 错误响应。

### 目录结构

```
fastapi_common/fastapi_common_web/exception/
├── __init__.py
├── Base/
│   ├── __init__.py
│   ├── BusinessException.py      ← 基类，所有模块异常继承它
│   └── status_code.py            ← StatusCode / StatusCodeEnum
├── InterceptorException.py        ← interceptor 模块异常（大驼峰文件名）
├── WxkfException.py               ← wxkf 模块异常（大驼峰文件名）
└── ...
```

### 异常类定义

```python
# fastapi_common/fastapi_common_web/exception/InterceptorException.py
"""拦截器模块异常。"""

from fastapi_common.fastapi_common_web.exception.Base.BusinessException import BusinessException


class InterceptorException(BusinessException):
    """拦截器模块业务异常。"""
```

### 使用方式

```python
# 在服务层实现中使用模块自己的异常类
from fastapi_common.fastapi_common_web.exception.InterceptorException import InterceptorException
from fastapi_common.fastapi_common_web.exception.Base.status_code import StatusCodeEnum

# 抛异常时使用模块专属异常类，而不是直接用 BusinessException
raise InterceptorException(StatusCodeEnum.HTTP_404_NOT_FOUND, "用户不存在")
raise InterceptorException(StatusCodeEnum.HTTP_401_UNAUTHORIZED, "用户名或密码错误")
```

### 异常层铁律

1. **禁止直接使用 `BusinessException` 抛异常**——每个模块必须用自己的 `XxxException`
2. 异常文件放在 `fastapi_common/fastapi_common_web/exception/` 下，**不放在业务模块内部**
3. 异常类只继承，不添加额外属性或方法（除非有特殊需求）
4. 全局异常中间件会捕获所有 `BusinessException` 及其子类，自动转换为 `Result` 错误响应

## DTO/VO/BO (`fastapi_modules/fastapi_xxx/domian/`)

使用 Pydantic v2 BaseModel。**DTO/VO/BO 的字段必须使用小驼峰命名（lowerCamelCase）**，这是强制规范，与 `fastapi_modules` 下的文件命名规范一致，也与前端 JSON 字段命名对齐。

### DTO（请求入参）— 只在控制器层

DTO 通过 endpoint 函数参数的类型注解声明，FastAPI 自动识别为请求体模型。**DTO 不允许进入服务层**，控制器负责从 DTO 中取值，以原始类型传给服务层。**字段必须小驼峰命名。**

```python
# fastapi_modules/fastapi_xxx/domian/Dto/userDto.py
"""用户 DTO。"""

from pydantic import BaseModel, Field


class UserCreateDTO(BaseModel):
    """创建用户请求。"""

    name: str = Field(..., description="用户名", max_length=100)
    account: str = Field(..., description="登录账号", max_length=100)
    password: str = Field(..., description="密码", min_length=6)
    phone: str | None = Field(None, description="手机号")
```

### VO（响应出参）— 控制器层 + 服务层

VO 通过路由装饰器的 `response_model=Result[list[XxxVO]]` 声明，由服务层组装返回。**VO 字段必须使用小驼峰命名（lowerCamelCase）**，这是强制规范，确保返回给前端的 JSON 字段统一为小驼峰。

```python
# fastapi_modules/fastapi_xxx/domian/vo/userVo.py
"""用户 VO。"""

from pydantic import BaseModel, Field


class UserVO(BaseModel):
    """用户响应。"""

    id: int = Field(..., description="用户ID")
    name: str = Field(..., description="用户名")
    account: str = Field(..., description="登录账号")
    phone: str | None = Field(None, description="手机号")
    status: int = Field(..., description="状态")
    createdAt: str | None = Field(None, description="创建时间")
```

### BO（业务对象）— 用于跨层传递验证

当数据需要从 Service 层传递到 Task / Handler 等其他层级时，**必须用 BO 包裹做验证**。Service 层内部如果不跨层传递，直接使用原始类型即可，不需要强制使用 BO。

```python
# fastapi_modules/fastapi_xxx/domian/bo/taskSubmitBo.py
"""任务提交 BO。"""

from pydantic import BaseModel, Field


class TaskSubmitBO(BaseModel):
    """任务提交业务对象（Service → Task 跨层传递时使用）。"""

    taskId: int = Field(..., description="任务ID")
    content: str = Field(..., description="提交内容")
    userId: int = Field(..., description="提交用户ID")
```

### DTO/VO/BO 铁律

1. **DTO 只允许出现在控制器层**——服务层、模型层、Task/Handler 层禁止引用 DTO
2. **VO 允许在控制器层和服务层使用**——服务层负责从 Model 实例组装 VO 并返回给控制器
3. **Model 层充血但不转换**——允许数据库操作方法（`@classmethod`），但禁止引用 DTO/VO/BO，禁止 `ToVo()`、`FromDto()` 等转换方法
4. **服务层入参使用原始类型**——控制器负责从 DTO 中拆解出原始类型传给服务层
5. **BO 用于跨层传递**——Service → Task/Handler 传递数据时必须用 BO 包裹验证，BO 不进入控制器层
6. **控制器路由必须显式声明 `response_model`**——`response_model=Result[list[XxxVO]]`，确保 OpenAPI 文档准确
7. **DTO/VO/BO 字段必须使用小驼峰命名（lowerCamelCase）**——如 `userId`、`userName`、`createdAt`，禁止蛇形命名（`user_id`）或大驼峰命名（`UserId`）

## 统一响应格式

所有接口统一返回 `Result` 结构。HTTP 标准码条目的 HTTP 响应码为真实状态码，纯业务码条目 HTTP 响应码为 200。

```python
from fastapi_common.fastapi_common_web.domain.responses import Result, PageResult, StatusCodeEnum

# 成功
return Result.success(Data=UserVo)

# 失败（使用预定义状态码，自带默认消息）
return Result.error(StatusCodeEnum.HTTP_404_NOT_FOUND)

# 失败（自定义消息）
return Result.error(StatusCodeEnum.HTTP_400_BAD_REQUEST, "手机号格式不正确")

# 业务异常（使用模块专属异常类，会被全局异常处理器捕获并自动转换为 Result 响应）
from fastapi_common.fastapi_common_web.exception.XxxException import XxxException

raise XxxException(StatusCodeEnum.HTTP_404_NOT_FOUND, "用户不存在")

# 分页响应
return Result.success(Data=PageResult(list=UserList, pagination=PaginationInfo))
```

## 日志规范

```python
from fastapi_common.fastapi_common_logger import logger

# 直接使用，通道由调用栈自动推断
logger.info(f"创建用户成功: {user.Id}")
logger.error(f"查询失败: {str(e)}")
logger.warning(f"用户已存在: {Account}")
```

通道自动推断规则：`/controllers/` → CONTROLLER、`/services/` → SERVICE、`/middleware/` → MIDDLEWARE、`/models/` → MODEL、`postgrest` → POSTGREST、`uvicorn` → UVICORN、`/db/` 或 `database` → DB 等。
日志同时写入 `App.log`（全量）和 `app-error.log`（WARNING+），按天滚动 + zip 压缩。

## 配置层 (`fastapi_admin/config/`)

配置采用 **TOML + .env 环境选定 + Pydantic Settings 校验** 三层架构：

```
TOML 文件 → os.environ 注入 → Pydantic Settings 校验 → 模块级变量导出
```

### 配置文件结构

```
backend/
├── .env                          ← 仅选定环境：APP_ENV=development
├── app.toml                      ← 基础公共配置（所有环境通用）
├── app.development.toml          ← 开发环境差异配置
├── app.production.toml           ← 生产环境差异配置
└── app.ai.toml                   ← AI 专用配置（最高优先级）
```

### 加载优先级（后覆盖前）

1. `app.toml` — 基础配置
2. `app.{APP_ENV}.toml` — 环境特定配置
3. `app.ai.toml` — AI 专用配置（最高优先级）
4. Docker `-e` 等已有环境变量 — 最高优先级（`setdefault` 不覆盖）

### TOML 配置文件格式

```toml
# app.toml — 使用 [SECTION] + KEY 结构，展平后变为 SECTION_KEY 环境变量
[APP]
HOST = "0.0.0.0"
PORT = 8000
CORS_ORIGINS = ["*"]

[JWT]
SECRET_KEY = "your-secret"
ACCESS_TOKEN_EXPIRE_MINUTES = 30

[DB]
HOST = "localhost"
PORT = 5432
NAME = "mydb"
```

### Pydantic Settings 定义（`_settings.py`）

```python
# fastapi_admin/config/_settings.py
class _Base(BaseSettings):
    """所有 Settings 的基类。"""
    model_config = {"env_file": None, "extra": "ignore"}

class AppSettings(_Base):
    """应用基础配置。"""
    APP_HOST: str = "0.0.0.0"
    APP_PORT: int = 8000

class DbSettings(_Base):
    """数据库配置。"""
    DB_HOST: str = ""
    DB_PORT: int = 5432
    DB_NAME: str = ""
    DB_USER: str = ""
    DB_PASSWORD: str = ""

    @property
    def ASYNCPG_DATABASE_URL(self) -> str:
        """计算属性：动态构建数据库 URL。"""
        return f"postgresql://{self.DB_USER}:{self.DB_PASSWORD}@{self.DB_HOST}:{self.DB_PORT}/{self.DB_NAME}"
```

### 模块级变量导出（`__init__.py`）

所有 Settings 实例的字段和 `@property` 会被自动导出为模块级变量，业务代码直接导入使用：

```python
# 任何模块中直接导入配置值
from fastapi_admin.config import APP_NAME, APP_PORT, JWT_SECRET_KEY, ASYNCPG_DATABASE_URL

# 或从特定子模块代理导入
from fastapi_admin.config.db import ASYNCPG_DATABASE_URL
from fastapi_admin.config.app import APP_PORT
```

### 新增配置项流程

1. 在 `app.toml` 中添加 `[SECTION].KEY`（展平后为 `SECTION_KEY`）
2. 在 `_settings.py` 中对应的 Settings 类添加字段（含类型和默认值）
3. 需要环境差异的配置在 `app.development.toml` / `app.production.toml` 中覆盖
4. 敏感值在环境特定 TOML 中配置或通过 Docker `-e` 注入，**不写默认值**
5. 如需计算属性（如 URL 拼接），在 Settings 类中用 `@property` 定义
6. **必须在 `__init__.pyi` 类型存根中声明新变量**，否则 IDE 无法识别动态导出的模块级变量

### 类型存根 (`__init__.pyi`)

由于 `__init__.py` 通过 `_export_settings()` 动态导出变量，IDE 无法静态推断类型。因此 `__init__.pyi` 必须同步维护，为每个导出变量提供类型声明：

```python
# fastapi_admin/config/__init__.pyi
"""类型存根文件 —— 为 IDE 静态分析提供动态导出变量的类型信息。"""

# APP
APP_ENV: str
APP_NAME: str
APP_PORT: int

# JWT
JWT_SECRET_KEY: str
JWT_ACCESS_TOKEN_EXPIRE_HOURS: int

# DB (PostgreSQL)
DB_HOST: str
DB_PORT: int
ASYNCPG_DATABASE_URL: str    # @property 计算属性也要声明

# 常量
ROOT_PATH: str
```

**铁律**：在 `_settings.py` 中新增字段或 `@property` 后，必须同步在 `__init__.pyi` 中添加对应的类型声明，否则 IDE 会报 "Cannot find reference" 错误

## 新增完整功能模块的清单

当新增一个完整的业务模块（如"用户管理"）时，需要创建以下文件：

| 序号 | 文件路径 | 作用 |
|------|----------|------|
| 1 | `fastapi_common/fastapi_common_web/exception/XxxException.py` | 模块专属异常类（继承 BusinessException） |
| 2 | `fastapi_modules/fastapi_xxx/models/xxx.py` | 充血模型（字段定义 + 数据库操作方法，禁止引用 DTO/VO/BO） |
| 3 | `fastapi_modules/fastapi_xxx/domian/Dto/xxxDto.py` | 请求 DTO（小驼峰文件名） |
| 4 | `fastapi_modules/fastapi_xxx/domian/vo/xxxVo.py` | 响应 VO（小驼峰文件名） |
| 5 | `fastapi_modules/fastapi_xxx/services/xxxService.py` | 服务接口 IXxxService（小驼峰文件名） |
| 6 | `fastapi_modules/fastapi_xxx/services/impl/xxxServiceImpl.py` | 服务实现 XxxServiceImpl（小驼峰文件名） |
| 7 | `fastapi_modules/fastapi_xxx/controllers/xxxController.py` | 控制器（小驼峰文件名） |

---

# 补充规范

以下规范是对通用规范的补充和覆盖，**与通用规范冲突时以本节为准**。

## 1. 新增业务模块注册流程

新增一个业务模块（如 `fastapi_xxx`）需要修改三处：

### 1.1 `backend/fastapi_admin/app.py` — 添加 sys.path

必须同时添加 **两级** 路径，缺一不可：

```python
_FASTAPI_MODULES_DIR = _PROJECT_ROOT / "fastapi_modules"                          # 使 importlib 能 import fastapi_xxx.controllers
_FASTAPI_XXX_DIR = _PROJECT_ROOT / "fastapi_modules" / "fastapi_xxx"              # 使模块内部裸名导入生效（from services import ...）
```

- `fastapi_modules` 目录：让控制器注册器 `importlib.import_module("fastapi_xxx.controllers")` 能找到包
- `fastapi_modules/fastapi_xxx` 目录：让模块内部的裸名导入生效（`from services import IAuthService`、`from domian.Dto import LoginDTO`）

### 1.2 `backend/pyproject.toml` — setuptools include

在 `[tool.setuptools.packages.find]` 的 `include` 列表中添加 `"fastapi_xxx*"`。

### 1.3 `backend/fastapi_admin/bootstrap_parts/controllers.py` — 注册控制器包

在 `controller_packages` 列表中添加入口：

```python
controller_packages = [
    "fastapi_xxx.controllers",
]
```

## 2. controllers 包级鉴权机制

控制器注册器 `register_controllers` 的扫描逻辑：
1. 导入 `controller_packages` 中的每个包
2. 如果包的 `__init__.py` 中有 `router = APIRouter(...)` 变量，将其记录为**包级路由器**
3. 递归遍历子包和模块，子包有 `router` 也会被记录
4. 注册 `BaseController` 子类时，通过 `resolve_target_router` **沿包路径向上查找**最近的包级路由器
5. 包级路由器上的 `dependencies` 会自动应用到其下所有控制器的路由

### 需要鉴权的控制器

在 `controllers/__init__.py` 中定义带 `dependencies` 的 `router`：

```python
"""控制器包（需要 JWT 鉴权）。"""

from typing import Any

from fastapi import APIRouter, Depends, Request

from fastapi_common.fastapi_common_security.security import verify_access_token


async def jwt_auth_dependency(RequestObj: Request) -> dict[str, Any]:
    """JWT 鉴权依赖。"""
    return verify_access_token(RequestObj)


router = APIRouter(dependencies=[Depends(jwt_auth_dependency)])
```

### 绕过鉴权的子包

在需要免鉴权的子包（如 `controllers/auth/`）的 `__init__.py` 中定义一个**空 router**（无 dependencies），**拦截 `resolve_target_router` 的向上查找**，使该子包下的控制器不走父包的鉴权 router：

```python
"""认证控制器包（无鉴权）。"""

from fastapi import APIRouter

router = APIRouter()
```

**原理**：`resolve_target_router` 从当前模块的包路径逐级向上查找 `package_routers`。如果 `controllers/auth/__init__.py` 没有 `router`，查找会继续向上命中 `controllers/__init__.py` 的带鉴权 router，导致 login 等接口也被鉴权拦截。定义空 `router` 即可在当前层级截断查找。

## 3. 文件命名规范

### `fastapi_modules` 下的业务模块 — 统一小驼峰文件名

**`fastapi_modules/` 下所有业务模块统一使用小驼峰命名（lowerCamelCase）**，包括：
- **`.py` 文件名**：`userInfoController.py`、`authServiceImpl.py`
- **DTO/VO/BO 的 Pydantic 字段名**：`userId`、`userName`、`createdAt`（禁止蛇形 `user_id` 或大驼峰 `UserId`）

**类名使用大驼峰命名（UpperCamelCase）**：`UserInfoController`、`LoginTokenVO`、`AuthServiceImpl`

```
controllers/
├── __init__.py
├── userInfoController.py     ← 小驼峰
└── auth/
    ├── __init__.py
    └── authController.py     ← 小驼峰

services/
├── __init__.py
├── userService.py            ← 小驼峰（IUserService 接口）
├── impl/
│   └── userServiceImpl.py    ← 小驼峰（UserServiceImpl 实现）
└── auth/
    ├── __init__.py
    ├── authService.py        ← 小驼峰
    └── impl/
        └── authServiceImpl.py

models/
├── __init__.py
└── user.py                   ← 小驼峰（单词本身就一个词的不需要驼峰）

domian/
├── Dto/
│   ├── __init__.py
│   ├── loginDto.py           ← 小驼峰
│   └── refreshTokenDto.py    ← 小驼峰
├── vo/
│   ├── __init__.py
│   ├── loginTokenVo.py       ← 小驼峰
│   └── userInfoVo.py         ← 小驼峰
└── auth/
    ├── Dto/
    │   ├── loginDto.py
    │   └── refreshTokenDto.py
    └── vo/
        └── loginTokenVo.py
```

```python
# controllers/userInfoController.py  ← 文件名小驼峰
class UserInfoController(BaseController):  # ← 类名大驼峰
    ...

# services/userService.py  ← 文件名小驼峰
class IUserService(ABC):  # ← 类名大驼峰
    ...

# services/impl/userServiceImpl.py  ← 文件名小驼峰
class UserServiceImpl(IUserService):  # ← 类名大驼峰
    ...

# domian/vo/userInfoVo.py  ← 文件名小驼峰
class UserInfoVO(BaseModel):  # ← 类名大驼峰
    ...
```

### `fastapi_modules` 以外的代码 — Python 蛇形命名

不在 `fastapi_modules` 下的代码（如 `fastapi_common`、`fastapi_admin` 等），除非 skills 中有特定规范，否则必须使用 Python 标准的**蛇形命名**（snake_case）。

## 4. 业务模块标准目录结构

```
fastapi_modules/fastapi_xxx/
├── __init__.py
├── controllers/                    ← 包级 __init__.py 挂 JWT 鉴权 router
│   ├── __init__.py                 ← router = APIRouter(dependencies=[Depends(jwt_auth)])
│   ├── userInfoController.py       ← 小驼峰，走包级鉴权
│   └── auth/                       ← 免鉴权子包
│       ├── __init__.py             ← router = APIRouter()（空，拦截向上查找）
│       └── authController.py       ← 小驼峰
├── services/
│   ├── __init__.py                 ← 导出 IUserService
│   ├── userService.py              ← 小驼峰
│   ├── impl/
│   │   └── userServiceImpl.py      ← 小驼峰
│   └── auth/                       ← 认证子模块
│       ├── __init__.py             ← 导出 IAuthService
│       ├── authService.py          ← 小驼峰
│       └── impl/
│           └── authServiceImpl.py
├── models/                         ← 充血模型
│   ├── __init__.py                 ← 导出 User 等模型
│   └── user.py                     ← 小驼峰（单词即一个词时无需驼峰）
├── domian/
│   ├── __init__.py
│   ├── Dto/
│   │   └── __init__.py
│   ├── vo/
│   │   ├── __init__.py
│   │   └── userInfoVo.py           ← 小驼峰
│   ├── bo/                          ← BO（按需，跨层传递时使用）
│   │   ├── __init__.py
│   │   └── taskSubmitBo.py          ← 小驼峰
│   └── auth/                       ← 认证子模块
│       ├── __init__.py
│       ├── Dto/
│       │   ├── __init__.py
│       │   ├── loginDto.py          ← 小驼峰
│       │   └── refreshTokenDto.py   ← 小驼峰
│       └── vo/
│           ├── __init__.py
│           └── loginTokenVo.py      ← 小驼峰
```