# JalonTsui Fastapi Kit

> 面向 FastAPI 服务的公共基础设施包：应用配置、数据库、缓存、日志、错误体系、安全、中间件、分页与通用 Repository / Service 基类。
> 本文件是为 AI 助手优化的浓缩版速览，只保留约定与红线；实现细节以各模块 README 与源码为准。

## 基本信息

- 发行名（安装名）`jalontsui-fastapi-kit`，import 名 `jalontsui_fastapi_kit`，Python >= 3.11，已内置 `py.typed`。
- 可选 extras：`[mysql]`（asyncmy + pymysql）、`[captcha]`（Pillow）、`[storage]`（aioboto3），按需组合选装。
- 核心依赖仅 FastAPI / Pydantic / SQLAlchemy / Redis 等基础库；数据库驱动缺失时创建引擎会抛出带安装提示的中文报错。

## 关键约定（AI 生成代码必须遵守）

1. 统一响应：所有路由返回 `ApiResponse`，成功用 `ApiResponse.success(data=...)`，禁止裸返回 dict 或自定义响应结构。
2. 错误体系：业务异常继承 `BusinessException`，错误码定义在业务包继承 `ErrorCode` 的枚举中；业务码区间 200 成功 / 1xxx 系统 / 2xxx 用户认证 / 3xxx 业务校验 / 4xxx 数据访问 / 5xxx 外部服务。默认提示在应用启动时通过 `ErrorMessageRegistry.register(locale, error, message)` 注册；禁止直接修改包内 `errors/messages.py`。
3. 配置：业务 Settings 继承 `BaseAppSettings` 即获得全部配置分块（数据库、Redis、日志等）；环境变量名 = 字段名大写形式（如 `db_host` -> `DB_HOST`），不使用嵌套分隔符，配置文件路径由环境变量 `ENV_FILE` 指定（默认 `.env`）。凡随环境变化的值必须进 Settings，禁止硬编码。
4. 分页：统一使用 `PageResponse[T]` / `ScrollPageResponse[T]`（优先游标式），禁止在业务 Schema 中重复定义 total / page / next_cursor 等字段。
5. Schema 分层：`XXXBase` 只做字段定义；`XXXCreate` 承载输入校验器；`XXXUpdate` 字段全可选；`XXXOut` 补 id 与时间戳并设 `model_config = ConfigDict(from_attributes=True)`；输出模型禁止包含密码、token 等敏感字段。
6. 数据访问：继承 `BaseRepository`，业务层继承 `BaseService`；多步写操作用 `db.transaction` 可嵌套事务保证一致性。

## 最小可运行示例

```python
from fastapi import FastAPI

from jalontsui_fastapi_kit.config import BaseAppSettings
from jalontsui_fastapi_kit.db import create_async_engine_from_url
from jalontsui_fastapi_kit.errors import ErrorMessageRegistry, SystemError
from jalontsui_fastapi_kit.response import ApiResponse

class Settings(BaseAppSettings):
    app_name: str = "my-service"
    db_name: str = "my_db"

settings = Settings()
engine = create_async_engine_from_url(settings.build_db_async_url())

ErrorMessageRegistry.register("zh", SystemError.BAD_REQUEST, "请求参数错误")

app = FastAPI()

@app.get("/health")
async def health() -> ApiResponse[dict[str, str]]:
    return ApiResponse.success(data={"status": "ok"})
```

## 模块地图（详细文档）

| 模块 | 导入路径 | 详细文档 |
|------|----------|----------|
| 应用配置 | `jalontsui_fastapi_kit.config` | [config/README.md](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/config/README.md) |
| 数据库与事务 | `jalontsui_fastapi_kit.db` | [db/README.md](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/db/README.md) |
| 错误体系与异常处理 | `jalontsui_fastapi_kit.errors` | [errors/README.md](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/errors/README.md) |
| 统一响应 | `jalontsui_fastapi_kit.response` | — |
| 分页 Schema | `jalontsui_fastapi_kit.schemas.common` | [schemas/README.md](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/schemas/README.md) |
| Redis 缓存 | `jalontsui_fastapi_kit.cache` | [cache/README.md](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/cache/README.md) |
| 结构化日志 | `jalontsui_fastapi_kit.logging` | [logging/README.md](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/logging/README.md) |
| 中间件 | `jalontsui_fastapi_kit.middleware` | [middleware/README.md](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/middleware/README.md) |
| 健康检查 | `jalontsui_fastapi_kit.health` | [health/README.md](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/health/README.md) |
| 密码 / JWT / 验证码 | `jalontsui_fastapi_kit.security` | [security/README.md](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/security/README.md) |
| Repository / Service 基类 | `jalontsui_fastapi_kit.repositories` / `jalontsui_fastapi_kit.services` | [repositories/README.md](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/repositories/README.md) |
| 参数校验格式化 | `jalontsui_fastapi_kit.validation` | [validation/README.md](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/validation/README.md) |

## AI 工具接入

包内置命令行工具 `jalontsui-fastapi-kit`，把本包的使用规则落地到消费方项目，
也可直接生成 standalone FastAPI 服务骨架（模板内置 wheel，AI 可非交互驱动）：

```bash
jalontsui-fastapi-kit generate-ai-skill                          # 生成 AGENTS.md 到当前目录
jalontsui-fastapi-kit generate-ai-skill -d . --tool cursor       # 生成 .cursor/rules/jalontsui-fastapi-kit.mdc
jalontsui-fastapi-kit generate-ai-skill --tool kimi              # 生成 .kimi-code/skills/jalontsui-fastapi-kit/SKILL.md
jalontsui-fastapi-kit generate-ai-skill --tool claude            # 生成 .claude/skills/jalontsui-fastapi-kit/SKILL.md
jalontsui-fastapi-kit generate-ai-llms -o llms.txt               # 导出本文件
jalontsui-fastapi-kit generate-ai-style                          # 生成风格指南 SKILL.md（默认 kimi；--tool claude/cursor 可选）

# 生成 standalone 服务骨架（默认 mysql + 网关透传头认证 + Alembic）
jalontsui-fastapi-kit new-service --name my-service
# 全量示例：指定目录、PostgreSQL、Redis + Celery、不生成 scripts
jalontsui-fastapi-kit new-service --name my-service -d ./services --db postgresql --celery

# 增量生成/更新 VSCode launch.json 调试配置
# 发现契约（按序回退）：优先扫 <dir>/packages/*/src/<pkg>/（需 main.py 或 worker.py）；无 packages/ 且根自身无 src/<pkg> 时扫根级成员 <dir>/<member>/src/<pkg>/（uv workspace 成员直接放根下，隐藏目录不参与）；再回退 standalone，-d 即服务根（识别 src/<pkg>/）
# 路径假设：workspace 模式 ${workspaceFolder}/packages/<pkg>，根级成员模式 ${workspaceFolder}/<member>，standalone 模式 ${workspaceFolder}；解释器取根级 .venv（按平台生成，--interpreter 可覆盖）
jalontsui-fastapi-kit generate-vscode-launch                     # 增量更新 .vscode/launch.json（默认 -d .）
jalontsui-fastapi-kit generate-vscode-launch --pkg my-service --type celery
jalontsui-fastapi-kit generate-vscode-launch --force             # 全量重建（丢弃手工配置）
```

`new-service` 生成后：进入目录执行 `uv sync`，拷贝 `.env.example` 为 `.env`；
`uv run python scripts/export_openapi.py` 可验证 import 链（无需真实数据库）。

规则文本随包维护，升级包后重新执行 `generate-ai-skill` 即可同步最新约定；
`generate-ai-skill` 生成的规则内嵌"风格红线"浓缩节，全文风格指南用 `generate-ai-style` 生成 skill。
