@deepstorm/cli 0.1.0

package/dist/skills/reef-style-backend/fragments/java/test/spring-service-test/examples/user-service-integration-test.md

@@ -0,0 +1,56 @@
+```java
+@SpringBootTest
+@Transactional
+@ActiveProfiles("test")
+@Testcontainers
+class UserServiceIntegrationTest {
+
+    @Container @ServiceConnection
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");
+
+    @Autowired private UserService userService;
+
+    // ──── 读 ────
+
+    @Test @Sql("/user-service-test-data.sql")
+    void should_returnAllUsers() {
+        assertThat(userService.findAll())
+            .extracting(UserDTO::email)
+            .containsExactlyInAnyOrder("alice@test.com", "bob@test.com");
+    }
+
+    @Test
+    void should_throw_when_userNotFound() {
+        assertThatThrownBy(() -> userService.findById(999L))
+            .isInstanceOf(NotFoundException.class);
+    }
+
+    // ──── 写 ────
+
+    @Test
+    void should_createUser() {
+        UserDTO result = userService.create(new CreateUserRequest("new@test.com", "New User"));
+        assertThat(result.id()).isNotNull();
+        assertThat(result.email()).isEqualTo("new@test.com");
+    }
+
+    @Test
+    void should_throw_when_duplicateEmail() {
+        userService.create(new CreateUserRequest("dup@test.com", "First"));
+        assertThatThrownBy(() ->
+            userService.create(new CreateUserRequest("dup@test.com", "Second")))
+            .isInstanceOf(AlreadyExistsException.class);
+    }
+
+    // ──── 事务 ────
+
+    @Test
+    void should_rollback_on_failure() {
+        userService.create(new CreateUserRequest("a@test.com", "A"));
+        assertThatThrownBy(() ->
+            userService.create(new CreateUserRequest("a@test.com", "A Duplicate")))
+            .isInstanceOf(AlreadyExistsException.class);
+        // @Transactional 自动回滚，数据库只有一条 a@test.com
+    }
+}
+```

package/dist/skills/reef-style-backend/fragments/java/test/spring-service-test/quick-reference.md

@@ -0,0 +1,83 @@
+# Spring Service 测试规范
+
+`@SpringBootTest` + `@Transactional`：加载完整上下文，每个测试结束后事务回滚，互不影响。
+
+## 基础结构
+
+```java
+@SpringBootTest
+@Transactional
+@ActiveProfiles("test")
+class UserServiceTest {
+    @Autowired private UserService userService;
+    @Autowired private TestEntityManager entityManager;      // 直接操作数据库准备数据
+}
+```
+
+> **⚠️ 何时用 `@SpringBootTest` vs `@ExtendWith(MockitoExtension.class)`**
+> - **数据库交互**（Repository / 事务）→ `@SpringBootTest`
+> - **纯业务逻辑**（计算、校验、映射）→ `MockitoExtension`（更快）
+
+## 测试模式
+
+### 读操作
+
+```java
+@Test
+void should_returnUser_when_findById() {
+    User user = entityManager.persistAndFlush(new User("test@test.com", "Test"));
+    UserDTO result = userService.findById(user.getId());
+    assertThat(result).extracting(UserDTO::id, UserDTO::email)
+        .containsExactly(user.getId(), "test@test.com");
+}
+```
+
+### 写操作
+
+```java
+@Test
+void should_createUser() {
+    UserDTO result = userService.create(new CreateUserRequest("new@test.com", "New"));
+    assertThat(result.id()).isNotNull();
+    // 验证数据库真实写入
+    User saved = entityManager.find(User.class, result.id());
+    assertThat(saved).isNotNull();
+}
+```
+
+### 异常路径
+
+```java
+@Test
+void should_throw_when_duplicateEmail() {
+    entityManager.persistAndFlush(new User("dup@test.com", "Existing"));
+    assertThatThrownBy(() -> userService.create(
+        new CreateUserRequest("dup@test.com", "Duplicate")))
+        .isInstanceOf(AlreadyExistsException.class);
+}
+```
+
+### 事务回滚
+
+```java
+@Test
+void should_rollback_on_failure() {
+    userService.create(new CreateUserRequest("a@test.com", "A"));
+    assertThatThrownBy(() ->
+        userService.create(new CreateUserRequest("a@test.com", "A2")))
+        .isInstanceOf(AlreadyExistsException.class);
+    // @Transactional 自动回滚，数据库只有一条 a@test.com
+}
+```
+
+## 关键规则
+
+| 场景 | 做法 |
+|------|------|
+| 需要数据库交互 | `@SpringBootTest` + `TestEntityManager` |
+| 纯业务逻辑 | `@ExtendWith(MockitoExtension.class)` |
+| 测试隔离 | `@Transactional`（自动回滚） |
+| 测试配置 | `@ActiveProfiles("test")` |
+| 数据准备 | `entityManager.persistAndFlush()` 或 `@Sql` |
+
+> **注意：** `@Transactional` 不回滚 `@PostConstruct` 和异步操作（`@Async`）中的操作。

package/dist/skills/reef-style-backend/fragments/python/alembic-migration/quick-reference.md

@@ -0,0 +1,77 @@
+# Alembic 迁移实践
+
+## 初始化
+
+```bash
+# 初始化 Alembic
+alembic init -t async migrations
+
+# 配置 async 引擎（migrations/env.py 中）
+# target_metadata = Base.metadata
+```
+
+## 创建迁移
+
+```bash
+# ✅ 自动生成迁移（推荐）
+alembic revision --autogenerate -m "add user table"
+
+# ⚠️ 检查自动生成的内容是否正确后再提交
+# 自动生成不能 100% 检测到所有变更（如列重命名）
+
+# ✅ 手动创建空迁移（特殊场景）
+alembic revision -m "migrate data"
+```
+
+## 应用迁移
+
+```bash
+# 升级到最新
+alembic upgrade head
+
+# 回滚一个版本
+alembic downgrade -1
+
+# 查看历史
+alembic history
+
+# 查看当前版本
+alembic current
+```
+
+## 迁移文件规范
+
+```python
+"""add user table
+
+Revision ID: abc123
+Revises: 
+Create Date: 2026-06-25 10:00:00
+"""
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers
+revision = "abc123"
+down_revision = None
+
+def upgrade() -> None:
+    op.create_table(
+        "users",
+        sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column("name", sa.String(length=100), nullable=False),
+        sa.Column("email", sa.String(length=255), nullable=False),
+        sa.Column("created_at", sa.DateTime(), server_default=sa.func.now()),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("email"),
+    )
+
+def downgrade() -> None:
+    op.drop_table("users")
+```
+
+**规范：**
+- 每个迁移文件只做**一件事**（一个表或一个字段变更）
+- `upgrade()` 和 `downgrade()` 必须互逆
+- `down_revision` 必须正确指向前一个迁移
+- **禁止**在生产环境直接执行未经 review 的自动生成迁移

package/dist/skills/reef-style-backend/fragments/python/api-spec/quick-reference.md

@@ -0,0 +1,164 @@
+# API 规范（Python / FastAPI）
+
+## 速查
+
+| 场景 | 决策 |
+| --- | --- |
+| 资源路径 | 英文复数 kebab-case：`/api/v1/user-roles`，不用 camelCase |
+| 路径变量 | snake_case：`/api/v1/users/{user_id}` |
+| 自定义动作 | 遵循 REST 语义；无法用标准 CRUD 时用 `@router.post("/{id}:action")` |
+| 查询参数 | snake_case：`?status=active&page=1&page_size=20` |
+| 统一响应体 | `response_model` + `ApiResponse[T]` / `PageResponse[T]` 包装 |
+| 版本策略 | URL path 前缀 `/api/v1/` |
+| 错误响应 | 统一 JSON：`{"code": "USER_001", "message": "...", "detail": {}}` |
+| OpenAPI | FastAPI 自动生成，配合 `summary` / `description` / `tags` |
+| 分页 | `page`(1-based) + `page_size`(默认 20，最大 100) |
+
+## 核心规范
+
+### 资源命名
+
+- **资源用复数**：`/users`、`/orders`
+- **嵌套资源**：`/apps/{app_id}/users/{user_id}`
+- **路径 kebab-case**：/api/v1/user-roles，不是 `/api/v1/userRoles`
+- **路径参数 snake_case**：`{user_id}`，不是 `{userId}`
+- **查询参数 snake_case**：`created_before`、`sort_by`
+
+### 统一响应体
+
+```python
+from pydantic import BaseModel
+from typing import Generic, TypeVar, List, Optional
+
+T = TypeVar("T")
+
+
+# ✅ 单资源响应
+class ApiResponse(BaseModel, Generic[T]):
+    success: bool
+    data: Optional[T] = None
+    message: Optional[str] = None
+
+    @staticmethod
+    def success(data: T) -> "ApiResponse[T]":
+        return ApiResponse(success=True, data=data)
+
+    @staticmethod
+    def message(msg: str) -> "ApiResponse[T]":
+        return ApiResponse(success=True, message=msg)
+
+
+# ✅ 分页响应
+class PageResponse(BaseModel, Generic[T]):
+    items: List[T]
+    page: int
+    page_size: int
+    total: int
+    total_pages: int
+
+
+# ✅ 错误响应
+class ErrorResponse(BaseModel):
+    code: str
+    message: str
+    detail: dict = {}
+```
+
+```python
+# ✅ 好：统一响应
+from fastapi import APIRouter
+
+router = APIRouter(prefix="/api/v1/users", tags=["users"])
+
+@router.get("/{user_id}", response_model=ApiResponse[UserResponse])
+async def get_user(user_id: int, user_service: UserService = Depends()):
+    user = await user_service.get_user(user_id)
+    return ApiResponse.success(user)
+
+@router.get("", response_model=PageResponse[UserResponse])
+async def list_users(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    user_service: UserService = Depends(),
+):
+    return await user_service.list_users(page=page, page_size=page_size)
+
+# ❌ 坏：直接返回实体
+@router.get("/{user_id}")
+async def get_user(user_id: int):
+    return await user_service.get_user(user_id)  # ← 未包装，格式不一致
+```
+
+### 版本策略
+
+```python
+# ✅ 好：按版本分组
+# app/api/v1/users.py
+router_v1 = APIRouter(prefix="/api/v1/users", tags=["users-v1"])
+
+# app/api/v2/users.py
+router_v2 = APIRouter(prefix="/api/v2/users", tags=["users-v2"])
+```
+
+- **非破坏性变更**（新增字段、新增可选参数）：停留在当前版本
+- **破坏性变更**（重命名字段、删除字段）：创建 `/api/v2/...`
+- **废弃端点**：`@router.get("/...", deprecated=True)`
+
+### 分页约定
+
+```python
+# ✅ 好：标准分页
+class PaginationParams:
+    """分页参数依赖注入"""
+    def __init__(
+        self,
+        page: int = Query(1, ge=1, description="页码（从1开始）"),
+        page_size: int = Query(20, ge=1, le=100, description="每页数量"),
+    ):
+        self.page = page
+        self.page_size = page_size
+        self.offset = (page - 1) * page_size
+
+@router.get("", response_model=PageResponse[UserResponse])
+async def list_users(
+    pagination: PaginationParams = Depends(),
+    user_service: UserService = Depends(),
+):
+    items, total = await user_service.list_users(
+        skip=pagination.offset, limit=pagination.page_size
+    )
+    return PageResponse(
+        items=items, page=pagination.page,
+        page_size=pagination.page_size, total=total,
+        total_pages=-(-total // pagination.page_size),  # ceil division
+    )
+```
+
+### OpenAPI 文档
+
+FastAPI 自动基于 Pydantic model + 路由生成 OpenAPI。额外配置：
+
+```python
+# ✅ 好：在路由上添加接口描述
+@router.get(
+    "/{user_id}",
+    summary="获取用户详情",
+    description="根据用户 ID 获取完整的用户信息",
+    response_model=ApiResponse[UserResponse],
+    responses={
+        404: {"description": "用户不存在", "model": ErrorResponse},
+        403: {"description": "无权限", "model": ErrorResponse},
+    },
+)
+async def get_user(user_id: int, ...):
+    ...
+
+# ✅ 好：全局 OpenAPI 元信息
+app = FastAPI(
+    title="My App API",
+    description="用户管理系统 API",
+    version="1.0.0",
+    docs_url="/api/docs" if settings.ENV != "production" else None,
+    redoc_url=None,
+)
+```

package/dist/skills/reef-style-backend/fragments/python/dependency-management/quick-reference.md

@@ -0,0 +1,139 @@
+# 依赖管理规范（Python）
+
+## 速查
+
+| 场景 | 决策 |
+| --- | --- |
+| 包管理器 | `uv`（统一管理和运行） |
+| 声明依赖 | `uv add {package}` 或直接在 `pyproject.toml` 中声明 |
+| 版本声明 | 在 `pyproject.toml` 中指定主版本范围：`>=1.0,<2.0` |
+| 禁止通配符版本 | 禁止 `*` 或 `>=0.0.0` |
+| 禁止硬编码 | 禁止 `pip install package==1.0.0`（不可复现） |
+| 依赖分组 | `[project.dependencies]`（运行）+ `[project.optional-dependencies]`（dev） |
+| 锁定文件 | `uv.lock` — 提交到 Git |
+| CVE 检查 | `uv audit` 扫描已知漏洞 |
+| 版本升级 | 手动升级后运行 `uv lock` 更新锁定文件 |
+
+## 核心规范
+
+### pyproject.toml 结构
+
+```toml
+[project]
+name = "my-app"
+version = "0.1.0"
+requires-python = ">=3.10"
+
+dependencies = [
+    "fastapi>=0.115.0,<1.0.0",
+    "sqlalchemy>=2.0,<3.0",
+    "alembic>=1.14,<2.0",
+    "pydantic>=2.10,<3.0",
+    "pydantic-settings>=2.7,<3.0",
+    "httpx>=0.28,<1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0,<9.0",
+    "pytest-asyncio>=0.24,<1.0",
+    "ruff>=0.8,<1.0",
+    "mypy>=1.13,<2.0",
+    "httpx>=0.28,<1.0",
+]
+
+[tool.ruff]
+# ruff 配置...
+
+[tool.mypy]
+# mypy 配置...
+```
+
+**规范：**
+- 运行依赖在 `[project.dependencies]` 中声明
+- 开发/测试依赖在 `[project.optional-dependencies]` 中分组
+- 每组使用语义化版本范围：`>=min,<max`
+- 同一生态的库保持版本一致（如 FastAPI + Pydantic 需兼容）
+
+### 禁止通配符版本
+
+```toml
+# ❌ 坏：通配符或不限版本
+dependencies = [
+    "fastapi=*",
+    "sqlalchemy>=0.0.0",
+]
+
+# ✅ 好：限制主版本范围
+dependencies = [
+    "fastapi>=0.115.0,<1.0.0",
+    "sqlalchemy>=2.0,<3.0",
+]
+```
+
+### uv 命令速查
+
+```bash
+# 添加依赖
+uv add fastapi
+
+# 添加开发依赖
+uv add --dev pytest pytest-asyncio
+
+# 移除依赖
+uv remove fastapi
+
+# 更新锁文件（升级所有兼容版本）
+uv lock
+
+# 升级特定包
+uv lock --upgrade-package fastapi
+
+# 安全审计
+uv audit
+
+# 查看依赖树
+uv tree
+```
+
+```bash
+# ❌ 坏：直接 pip install（绕过 uv.lock）
+pip install fastapi==0.115.0
+
+# ✅ 好：用 uv 管理所有依赖
+uv add fastapi
+```
+
+### 版本升级规则
+
+| 升级类型 | 操作 | 验证 |
+|---------|------|------|
+| Major 升级 | 手动升级，独立 PR | 需检查 breaking changes + API 兼容性 |
+| Minor 升级 | `uv lock --upgrade-package {pkg}` | 运行完整测试套件 |
+| Patch 升级 | `uv lock --upgrade-package {pkg}` | 运行测试 + lint |
+
+### 安全审计
+
+```bash
+# 扫描 CVE
+uv audit
+
+# 输出示例：
+# Found 2 vulnerabilities:
+# - urllib3<2.2.3 (CVE-2024-37891, medium)
+# - requests<2.32.0 (CVE-2024-35195, medium)
+```
+
+**规范：**
+- 每次 CI 中运行 `uv audit`
+- 紧急 CVE（CVSS >= 7.0）：1 天内升级并验证
+- 无法立即升级时，加备注和缓解措施文档
+
+### 已知 CVE 常见的 Python 包
+
+| 包 | 受影响版本 | 最低安全版本 |
+|---|----------|------------|
+| urllib3 | < 2.2.3 | >= 2.2.3 |
+| requests | < 2.32.0 | >= 2.32.0 |
+| Jinja2 | < 3.1.5 | >= 3.1.5 |
+| cryptography | < 43.0.1 | >= 43.0.1 |

package/dist/skills/reef-style-backend/fragments/python/exception-handling/quick-reference.md

@@ -0,0 +1,177 @@
+# 异常处理规范（Python / FastAPI）
+
+## 速查
+
+| 场景 | 决策 |
+| --- | --- |
+| 业务异常 | 继承 `AppError(HTTPException)`，含 `code` + `status_code` + `detail` |
+| 全局捕获 | `@app.exception_handler(AppError)` 统一处理 |
+| 错误响应 | `{"code": "USER_001", "message": "...", "detail": {}}` |
+| 错误码 | `{MODULE}_{NNN}` 枚举 |
+| 参数校验失败 | FastAPI 自动处理 `RequestValidationError` |
+| 未知异常 | 兜底 500 — `GENERIC_001`，记录完整 traceback |
+| Service 层异常 | 抛出 `AppError` 子类，不在 Router 中 try-catch |
+
+## 核心规范
+
+### 业务异常继承层次
+
+```
+HTTPException (fastapi)
+└── AppError                    ← 抽象基类
+    ├── NotFoundError           (404)
+    ├── ConflictError           (409)
+    ├── ValidationError         (400)
+    ├── PermissionError         (403)
+    └── FailedPreconditionError (400)
+```
+
+```python
+from fastapi import HTTPException
+from starlette.status import *
+
+class AppError(HTTPException):
+    """业务异常基类。所有业务异常必须继承此类。"""
+    def __init__(self, status_code: int, code: str, message: str, detail: dict | None = None):
+        super().__init__(status_code=status_code, detail={
+            "code": code,
+            "message": message,
+            "detail": detail or {},
+        })
+
+# 子类
+class NotFoundError(AppError):
+    def __init__(self, code: str, resource_type: str, resource_id: any):
+        super().__init__(
+            status_code=HTTP_404_NOT_FOUND,
+            code=code,
+            message=f"{resource_type} not found: {resource_id}",
+            detail={"resource_type": resource_type, "resource_id": resource_id},
+        )
+
+class ConflictError(AppError):
+    def __init__(self, code: str, message: str):
+        super().__init__(status_code=HTTP_409_CONFLICT, code=code, message=message)
+
+class ValidationError(AppError):
+    def __init__(self, code: str, message: str, errors: list[dict] | None = None):
+        super().__init__(
+            status_code=HTTP_400_BAD_REQUEST,
+            code=code,
+            message=message,
+            detail={"errors": errors} if errors else {},
+        )
+
+class PermissionDeniedError(AppError):
+    def __init__(self, code: str = "AUTH_201", message: str = "无权限访问"):
+        super().__init__(status_code=HTTP_403_FORBIDDEN, code=code, message=message)
+```
+
+### 错误码枚举
+
+```python
+from enum import Enum
+
+class ErrorCode(str, Enum):
+    # User — 001~099 输入验证, 100~199 资源状态, 200~299 权限
+    USER_001 = "USER_001"    # 用户名已存在
+    USER_002 = "USER_002"    # 邮箱格式无效
+    USER_100 = "USER_100"    # 用户不存在
+    USER_101 = "USER_101"    # 用户已禁用
+    USER_200 = "USER_200"    # 无权操作该用户
+
+    # Order
+    ORDER_001 = "ORDER_001"  # 订单金额无效
+    ORDER_100 = "ORDER_100"  # 订单不存在
+    ORDER_101 = "ORDER_101"  # 订单状态不允许操作
+
+    # Auth
+    AUTH_001 = "AUTH_001"    # Token 已过期
+    AUTH_002 = "AUTH_002"    # Token 无效
+    AUTH_201 = "AUTH_201"    # 无权限访问
+
+    # Generic
+    GENERIC_001 = "GENERIC_001"  # 系统内部错误
+    GENERIC_404 = "GENERIC_404"  # 接口不存在
+```
+
+### 全局异常处理器
+
+```python
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from fastapi.exceptions import RequestValidationError
+
+app = FastAPI()
+
+
+# ✅ 业务异常统一处理
+@app.exception_handler(AppError)
+async def app_error_handler(request: Request, exc: AppError):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=exc.detail,
+    )
+
+
+# ✅ FastAPI 参数校验失败（Pydantic 校验）
+@app.exception_handler(RequestValidationError)
+async def validation_error_handler(request: Request, exc: RequestValidationError):
+    errors = [
+        {"field": err["loc"][-1], "message": err["msg"]}
+        for err in exc.errors()
+    ]
+    return JSONResponse(
+        status_code=422,
+        content={
+            "code": "VALIDATION_001",
+            "message": "参数校验失败",
+            "detail": {"errors": errors},
+        },
+    )
+
+
+# ✅ 兜底：未捕获异常 → 500
+@app.exception_handler(Exception)
+async def unexpected_error_handler(request: Request, exc: Exception):
+    logger.error("Unexpected error", exc_info=True)  # 完整 traceback 只打日志
+    return JSONResponse(
+        status_code=500,
+        content={
+            "code": "GENERIC_001",
+            "message": "系统内部错误",
+            "detail": {},
+        },
+    )
+```
+
+**规范：**
+- 不要在 Router 函数中写 try-except 包裹业务逻辑
+- 不要吞异常后返回 `None` 或空字典
+- 兜底 handler 必须 `logger.error(..., exc_info=True)`
+- `RequestValidationError` 的 detail 中返回具体字段错误信息
+
+### 异常使用示例
+
+```python
+# Service 层 — 直接抛异常
+class UserService:
+    async def get_user(self, user_id: int) -> UserResponse:
+        user = await user_repository.get_by_id(user_id)
+        if user is None:
+            raise NotFoundError(ErrorCode.USER_100, "User", user_id)
+        return UserResponse.from_orm(user)
+
+    async def create_user(self, request: CreateUserRequest) -> UserResponse:
+        existing = await user_repository.get_by_email(request.email)
+        if existing:
+            raise ConflictError(ErrorCode.USER_001, "邮箱已注册")
+        user = await user_repository.create(request)
+        return UserResponse.from_orm(user)
+
+# Router 层 — 不需要 try-catch
+@router.post("", response_model=ApiResponse[UserResponse])
+async def create_user(request: CreateUserRequest, user_service: UserService = Depends()):
+    user = await user_service.create_user(request)
+    return ApiResponse.success(user)
+```