create-dwy 0.7.1 → 0.9.0

package/templates/claude-global/rules/dwy-python-testing.md

@@ -1,5 +1,5 @@
 ---
-description: Python pytest 测试规范
+description: Python pytest 测试规范（目录组织、fixture、异步、AAA 结构）
 paths:
   - "**/tests/**/*.py"
   - "**/test_*.py"
@@ -9,14 +9,81 @@ paths:
 
 # Python pytest 测试规范
 
-## 十四、测试
+## 一、测试目录组织（强制）
+
+### 核心约束
+
+**测试目录与业务源码并列、独立存放。** 测试文件**禁止**混入源码目录（`src/` 或 `app/` 等）。
 
 ### 强制规则
+
+- 测试目录与源码目录平级、独立，常用名 `tests/`（也可按团队约定，但**必须**独立）
+- **禁止**在源码目录中放任何 `test_*.py` / `*_test.py` 文件
+- 测试目录内部结构应**镜像**对应源码结构，便于定位被测对象
+- 测试文件命名：`test_{被测模块名}.py`（pytest 默认发现规则）
+- 测试函数命名：`test_{被测行为}` —— 描述行为而非实现
+- 全局 fixture 放测试根目录的 `conftest.py`，子目录 fixture 放对应子目录的 `conftest.py`
+- pytest 配置在 `pyproject.toml` 显式声明：
+
+```toml
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+```
+
+- 测试依赖（`pytest` / `pytest-asyncio` / `httpx` / `pytest-mock` 等）放 `[dev]` 或 `[test]` extras，**禁止**进生产依赖
+- 跨包发布的代码不得 import 测试目录下的内容
+
+> 具体目录布局由项目结构决定（单包、monorepo 子包、扁平 `app/` 等），AI 自行判断；唯一不变的是"测试目录独立、与源码并列"。
+
+### 标准目录结构(仅供参考)
+
+```
+project/
+├── src/
+│   └── app/
+│       ├── routers/
+│       │   └── user.py
+│       ├── services/
+│       │   └── user.py
+│       ├── models/
+│       │   └── user.py
+│       └── main.py
+├── tests/                          # 测试根目录
+│   ├── conftest.py                 # 全局 fixture（client / db_session 等）
+│   ├── routers/
+│   │   ├── __init__.py
+│   │   └── test_user.py            # 测 app/routers/user.py
+│   ├── services/
+│   │   ├── __init__.py
+│   │   └── test_user.py            # 测 app/services/user.py
+│   └── models/
+│       ├── __init__.py
+│       └── test_user.py            # 测 app/models/user.py
+└── pyproject.toml
+```
+
+---
+
+## 二、技术栈
+
 - 使用 `pytest` + `pytest-asyncio` + `httpx`
-- 使用 `TestClient` 或 `AsyncClient` 测试 API
+- API 测试使用 `httpx.AsyncClient` 配合 `ASGITransport`，**禁止**使用同步 `TestClient` 测异步路由
+
+---
+
+## 三、Fixture
+
+### 强制规则
+
+- 测试数据使用 `pytest.fixture`，**禁止**在测试函数中硬编码业务数据
+- 数据库相关 fixture 必须保证测试间隔离（每个测试事务回滚或重建表）
+- 跨测试共享的 fixture 放 `conftest.py`，单文件用的 fixture 留在文件内
 
 ```python
-# conftest.py
+# tests/conftest.py
 import pytest
 from httpx import ASGITransport, AsyncClient
 from app.main import app
@@ -28,26 +95,61 @@ async def client():
         base_url="http://test",
     ) as ac:
         yield ac
+```
+
+---
+
+## 四、测试编写规范
+
+### 强制规则
+
+- 测试结构遵循 **Arrange-Act-Assert**（准备 → 调用 → 断言）
+- 一个测试只验证一个行为，**禁止**在一个 test 函数中堆多个不相关断言
+- 断言要具体（断言字段值），**禁止**只断言"不报错"
+- 必须覆盖：成功路径、失败路径（404 / 422 / 401 / 403）、边界值
+- 敏感字段（密码、token）**必须**显式断言**不在**响应中
+
+```python
+# tests/routers/test_user.py
+import pytest
+from httpx import AsyncClient
 
-# test_user.py
 @pytest.mark.anyio
-async def test_create_user_returns_201(client: AsyncClient):
-    response = await client.post("/users/", json={
+async def test_create_user_returns_201_without_password(client: AsyncClient):
+    # Arrange
+    payload = {
         "name": "Alice",
         "email": "alice@example.com",
         "password": "securepass123",
-    })
+    }
+
+    # Act
+    response = await client.post("/users/", json=payload)
+
+    # Assert
     assert response.status_code == 201
     data = response.json()
     assert data["name"] == "Alice"
-    assert "password" not in data  # 响应不包含密码
+    assert "password" not in data
+    assert "hashed_password" not in data
 
 @pytest.mark.anyio
 async def test_get_nonexistent_user_returns_404(client: AsyncClient):
-    response = await client.get("/users/99999")
+    response = await client.get("/users/00000000-0000-0000-0000-000000000000")
     assert response.status_code == 404
 ```
 
-- 测试函数名描述行为而非实现
-- 测试数据使用 `pytest.fixture`，不要硬编码
-- 测试结构遵循 Arrange-Act-Assert
+---
+
+## 五、违规检测清单
+
+| 检查项 | 违规模式 | 严重程度 |
+|--------|---------|---------|
+| 测试与源码混放 | 测试文件放在 `src/` 或 `app/` 内（如 `app/services/test_user.py`） | 高 |
+| 测试目录不规范 | 项目无 `tests/` 目录或 `pyproject.toml` 未配 `testpaths` | 高 |
+| 镜像结构断裂 | 测试目录结构与源码目录结构不对应，难以定位 | 中 |
+| 同步 TestClient | 异步路由用同步 `TestClient` 测试 | 高 |
+| 测试无断言 | 只调用接口不断言响应字段 | 高 |
+| 敏感字段未校验 | 用户接口测试未断言密码字段不在响应中 | 高 |
+| 测试数据硬编码 | 复用的测试数据不抽 fixture，散落在多个 test 函数中 | 中 |
+| 测试依赖泄漏 | `pytest` 等测试依赖进入生产依赖列表 | 高 |

package/templates/claude-global/rules/dwy-redis.md

@@ -0,0 +1,88 @@
+---
+description: Redis 安全与使用规范（必须用 dwyeapi 客户端、密码、绑定、危险命令禁用、key TTL 与前缀、敏感数据禁存）
+---
+
+# Redis 安全与使用规范
+
+适用于使用 Redis 作为缓存 / 会话存储 / Token 黑名单 / 速率限制存储的 Python 后端项目。
+
+---
+
+## 一、客户端使用（强制）
+
+- **必须**通过 dwyeapi 缓存模块获取共享异步 Redis 客户端（具体 API 查 `dwy-eapi` skill）
+- **禁止**业务代码中 `aioredis.from_url(...)` 自建连接池
+- **禁止**直接使用同步 `redis-py`（除非脚本类一次性任务）
+
+---
+
+## 二、服务端配置（强制）
+
+| 规则 | 说明 |
+|------|------|
+| 认证 | **必须**设置 `requirepass`，无密码 Redis 一律拒绝接入生产 |
+| 绑定地址 | `bind 127.0.0.1` 或内网地址，**禁止** `bind 0.0.0.0` |
+| 危险命令 | **禁用**或重命名 `FLUSHALL` / `FLUSHDB` / `CONFIG` / `KEYS` / `DEBUG` |
+| 内存上限 | 设 `maxmemory` 与 `maxmemory-policy`（推荐 `allkeys-lru`），防止 OOM |
+| 持久化 | 根据用途选择：缓存可关 AOF；会话 / 黑名单需 AOF everysec |
+
+```conf
+# redis.conf 关键项示例
+requirepass <strong-password>
+bind 127.0.0.1
+rename-command FLUSHALL ""
+rename-command FLUSHDB ""
+rename-command CONFIG ""
+rename-command KEYS ""
+rename-command DEBUG ""
+maxmemory 256mb
+maxmemory-policy allkeys-lru
+```
+
+---
+
+## 三、Key 设计规范（强制）
+
+| 规则 | 说明 |
+|------|------|
+| 必须 TTL | 所有 key **必须**显式设置过期时间（`ex` / `pexpire`），**禁止**遗留无 TTL 的 key |
+| 必须项目前缀 | 所有 key 必须有项目前缀，格式 `{app}:{domain}:{detail}`（如 `myapp:token:blacklist:abc123`） |
+| snake_case | key 段用 snake_case，**禁止**驼峰或中文 |
+| 不存敏感原文 | **禁止**存储密码、身份证、银行卡、token 原文（token 存哈希） |
+
+### 正反例
+
+```python
+# 反例
+await redis.set("abc123", "1")                       # 无前缀
+await redis.set("myapp:data:xxx", value)             # 无 TTL
+await redis.set("myapp:user:password", "123456")     # 存敏感原文
+await redis.set("myapp:userToken", "ey...")          # 驼峰命名
+
+# 正例
+await redis.set("myapp:token:blacklist:abc123", "1", ex=3600)
+await redis.set("myapp:cache:user:uuid:f7e2", json_data, ex=300)
+```
+
+---
+
+## 四、Pub/Sub 与 Stream 使用约束
+
+- 业务消息**禁止**用 Pub/Sub 当持久队列（Pub/Sub 无 ACK 与持久化）
+- 持久任务用 dwyeapi tasks 模块（基于 ARQ）或 Redis Stream
+- Stream 必须设消费者组 ACK 与死信处理
+
+---
+
+## 五、违规检测清单
+
+| 检查项 | 违规模式 | 严重程度 |
+|--------|---------|---------|
+| 绑定 0.0.0.0 | 服务对公网暴露 | **致命 → STOP** |
+| 无密码 | 生产 Redis 未设 `requirepass` | **致命 → STOP** |
+| 存敏感原文 | 密码 / 身份证 / token 明文存 Redis | **致命 → STOP** |
+| 自建连接池 | 业务代码 `aioredis.from_url(...)`，未走 dwyeapi 缓存模块 | 高 |
+| 危险命令未禁 | `FLUSHALL` / `KEYS` / `CONFIG` 等可在生产执行 | 高 |
+| Key 无 TTL | `redis.set()` 没有 `ex` 参数（业务上明确永久存储除外） | 中 |
+| Key 无前缀 | Key 无项目前缀，污染共享 Redis | 中 |
+| Pub/Sub 当队列 | 业务关键消息走 Pub/Sub | 高 |