adspecs 0.1.12

package/references/python-end-standard/02-/346/225/260/346/215/256/345/272/223/350/256/276/350/256/241/344/270/216/344/275/277/347/224/250/350/247/204/350/214/203.md

@@ -0,0 +1,226 @@
+# 数据库设计与使用规范
+
+> **版本**: v1.0 | **修订日期**: 2026-07-15
+> **技术栈**: SQLAlchemy 2.0+ / Alembic / SQLite (aiosqlite)
+
+---
+
+## 一、SQLAlchemy 基类
+
+### 1.1 声明式基类
+
+```python
+# app/models/base.py
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from sqlalchemy import Integer, String, Boolean, DateTime, func
+from datetime import datetime
+
+class Base(DeclarativeBase):
+    """SQLAlchemy 声明式基类"""
+    pass
+
+class TimestampMixin:
+    """时间戳 Mixin — 自动记录创建/更新时间"""
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime, server_default=func.now(), nullable=False
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime, server_default=func.now(), onupdate=func.now(), nullable=False
+    )
+
+class SoftDeleteMixin:
+    """软删除 Mixin"""
+    is_deleted: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
+
+class AuditMixin:
+    """审计 Mixin — 记录操作人"""
+    created_by: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    updated_by: Mapped[int | None] = mapped_column(Integer, nullable=True)
+```
+
+### 1.2 模型定义示例
+
+```python
+# app/models/warehouse.py
+from sqlalchemy import String, Integer, Text, Index
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from app.models.base import Base, TimestampMixin, SoftDeleteMixin, AuditMixin
+
+class Warehouse(Base, TimestampMixin, SoftDeleteMixin, AuditMixin):
+    """仓库模型"""
+    __tablename__ = "warehouses"
+    __table_args__ = (
+        Index("ix_warehouse_code", "code", unique=True),
+        Index("ix_warehouse_active", "is_active"),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    code: Mapped[str] = mapped_column(String(50), nullable=False, comment="仓库编码")
+    name: Mapped[str] = mapped_column(String(200), nullable=False, comment="仓库名称")
+    location: Mapped[str | None] = mapped_column(String(500), comment="位置")
+    is_active: Mapped[bool] = mapped_column(default=True, comment="是否启用")
+
+    # relationships
+    material_lots: Mapped[list["MaterialLot"]] = relationship(back_populates="warehouse")
+```
+
+---
+
+## 二、SQLite 特有注意事项
+
+| 事项           | 规范                                                       |
+|----------------|------------------------------------------------------------|
+| WAL 模式       | 生产环境必须启用 `PRAGMA journal_mode=WAL`                 |
+| 外键约束       | 默认关闭，必须执行 `PRAGMA foreign_keys=ON`               |
+| 类型亲和性     | 严格按模型定义列类型，避免隐式转换                         |
+| 并发写入       | SQLite 不支持并发写，Celery worker 必须 `--concurrency=1` |
+| 文件权限       | 数据库文件目录需要读写权限                                 |
+| 备份           | 定期 VACUUM + 文件拷贝                                    |
+
+### 引擎配置
+
+```python
+# app/core/database.py
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
+from sqlalchemy import text
+from app.core.config import settings
+
+engine = create_async_engine(
+    settings.DATABASE_URL,
+    echo=settings.DEBUG,
+    connect_args={"check_same_thread": False},
+)
+
+async_session = async_sessionmaker(engine, expire_on_commit=False, class_=AsyncSession)
+
+async def init_db():
+    """初始化数据库（启用 WAL 模式）"""
+    async with engine.connect() as conn:
+        await conn.execute(text("PRAGMA journal_mode=WAL"))
+        await conn.execute(text("PRAGMA foreign_keys=ON"))
+        await conn.commit()
+
+async def get_db():
+    """数据库会话依赖注入"""
+    async with async_session() as session:
+        try:
+            yield session
+        except Exception:
+            await session.rollback()
+            raise
+```
+
+---
+
+## 三、Alembic 迁移规范
+
+### 3.1 初始化
+
+```bash
+alembic init alembic
+# 修改 alembic.ini 的 sqlalchemy.url
+# 修改 alembic/env.py 导入 Base.metadata
+```
+
+### 3.2 迁移命名
+
+```bash
+alembic revision --autogenerate -m "add_warehouse_table"
+alembic revision --autogenerate -m "add_index_warehouse_code"
+```
+
+### 3.3 迁移规则
+
+| 规则       | 说明                                           |
+|------------|------------------------------------------------|
+| 自动生成   | 始终使用 `--autogenerate`，手动 review 后提交  |
+| 不可逆操作 | DROP TABLE/DROP COLUMN 前必须确认数据安全     |
+| 数据迁移   | 数据迁移和结构迁移分开为两个 revision          |
+| 测试       | 迁移后必须运行测试验证                         |
+| 提交       | 迁移文件必须纳入版本控制                       |
+
+---
+
+## 四、查询规范
+
+### 4.1 使用 select() 风格
+
+```python
+from sqlalchemy import select, func
+
+# 单条查询
+stmt = select(Warehouse).where(Warehouse.id == warehouse_id)
+result = await db.execute(stmt)
+warehouse = result.scalar_one_or_none()
+
+# 分页查询
+stmt = (
+    select(Warehouse)
+    .where(Warehouse.is_deleted == False, Warehouse.is_active == True)
+    .order_by(Warehouse.created_at.desc())
+    .offset((page - 1) * page_size)
+    .limit(page_size)
+)
+result = await db.execute(stmt)
+items = result.scalars().all()
+
+# 计数
+count_stmt = select(func.count()).select_from(Warehouse).where(Warehouse.is_deleted == False)
+total = (await db.execute(count_stmt)).scalar()
+```
+
+### 4.2 禁止事项
+
+- 禁止使用 `session.query()` 风格（SQLAlchemy 1.x 遗留）
+- 禁止字符串拼接 SQL
+- 禁止在循环中执行查询（N+1 问题）
+- 禁止不带 WHERE 的 UPDATE/DELETE
+
+---
+
+## 五、Repository 模式
+
+```python
+# app/repositories/warehouse.py
+class WarehouseRepository:
+    """仓库数据访问层"""
+
+    async def get_by_id(self, db: AsyncSession, warehouse_id: int) -> Warehouse | None:
+        return await db.get(Warehouse, warehouse_id)
+
+    async def get_by_code(self, db: AsyncSession, code: str) -> Warehouse | None:
+        stmt = select(Warehouse).where(Warehouse.code == code, Warehouse.is_deleted == False)
+        result = await db.execute(stmt)
+        return result.scalar_one_or_none()
+
+    async def get_page(
+        self, db: AsyncSession, page: int, page_size: int, filters: dict | None = None
+    ) -> tuple[list[Warehouse], int]:
+        base = select(Warehouse).where(Warehouse.is_deleted == False)
+        if filters:
+            if "name" in filters:
+                base = base.where(Warehouse.name.contains(filters["name"]))
+            if "is_active" in filters:
+                base = base.where(Warehouse.is_active == filters["is_active"])
+
+        count_stmt = select(func.count()).select_from(base.subquery())
+        total = (await db.execute(count_stmt)).scalar()
+
+        stmt = base.order_by(Warehouse.created_at.desc()).offset((page - 1) * page_size).limit(page_size)
+        result = await db.execute(stmt)
+        return result.scalars().all(), total
+
+warehouse_repo = WarehouseRepository()
+```
+
+---
+
+## 六、索引策略
+
+| 场景           | 索引类型         | 示例                                      |
+|----------------|------------------|-------------------------------------------|
+| 唯一约束       | Unique Index     | code, email                               |
+| 高频查询条件   | 普通索引         | is_active, status                         |
+| 组合查询       | 复合索引         | (warehouse_id, material_type)             |
+| 外键           | 自动创建         | relationship 自动生成                     |
+| 软删除过滤     | 部分索引         | WHERE is_deleted = False                  |

package/references/python-end-standard/03-Celery/345/274/202/346/255/245/344/273/273/345/212/241/350/247/204/350/214/203.md

@@ -0,0 +1,237 @@
+# Celery 异步任务规范
+
+> **版本**: v1.0 | **修订日期**: 2026-07-15
+> **技术栈**: Celery 5.4+ / Redis (Broker + Backend)
+
+---
+
+## 一、Celery 实例配置
+
+```python
+# app/tasks/celery_app.py
+from celery import Celery
+from app.core.config import settings
+
+celery_app = Celery(
+    "worker",
+    broker=settings.CELERY_BROKER_URL,
+    backend=settings.CELERY_RESULT_BACKEND,
+)
+
+celery_app.conf.update(
+    # 序列化
+    task_serializer="json",
+    accept_content=["json"],
+    result_serializer="json",
+
+    # 时区
+    timezone="Asia/Shanghai",
+    enable_utc=True,
+
+    # 任务执行
+    task_track_started=True,
+    task_time_limit=300,          # 硬超时 5 分钟
+    task_soft_time_limit=240,     # 软超时 4 分钟
+
+    # Worker（SQLite 场景）
+    worker_concurrency=1,         # SQLite 不支持并发写
+    worker_prefetch_multiplier=1,
+    worker_pool="solo",           # 单进程池
+
+    # 结果过期
+    result_expires=3600,
+
+    # Beat 定时任务
+    beat_schedule={},
+)
+```
+
+---
+
+## 二、任务定义规范
+
+### 2.1 命名规则
+
+```
+{action}_{entity}_task
+```
+
+示例: `sync_inventory_task`, `generate_report_task`, `send_notification_task`
+
+### 2.2 任务定义
+
+```python
+# app/tasks/inventory_tasks.py
+from app.tasks.celery_app import celery_app
+
+@celery_app.task(
+    name="inventory.sync_inventory",
+    bind=True,
+    autoretry_for=(ConnectionError, TimeoutError),
+    max_retries=3,
+    retry_backoff=True,
+    retry_backoff_max=600,
+)
+def sync_inventory_task(self, warehouse_id: int, material_type: str | None = None):
+    """同步库存数据"""
+    try:
+        # 任务逻辑（Celery 任务内使用同步数据库会话）
+        from app.core.database import SessionLocal
+        with SessionLocal() as db:
+            # ... 业务逻辑
+            db.commit()
+    except Exception as exc:
+        self.retry(exc=exc)
+```
+
+### 2.3 参数规范
+
+| 规则           | 说明                                           |
+|----------------|------------------------------------------------|
+| 可序列化       | 参数必须是 JSON 可序列化的（str/int/float/dict/list） |
+| 禁止传对象     | 禁止传递 SQLAlchemy Model 实例                  |
+| 传递 ID        | 通过 ID 在任务内部重新查询数据库                 |
+| 参数校验       | 任务开头进行参数校验，失败直接 raise             |
+
+---
+
+## 三、任务调用
+
+```python
+from app.tasks.inventory_tasks import sync_inventory_task
+
+# 异步调用
+result = sync_inventory_task.delay(warehouse_id=123, material_type="aluminum")
+
+# 指定 ETA
+from datetime import datetime, timedelta
+result = sync_inventory_task.apply_async(
+    kwargs={"warehouse_id": 123},
+    eta=datetime.utcnow() + timedelta(minutes=10),
+)
+
+# 获取结果（同步等待）
+result.get(timeout=60)
+
+# 检查状态
+result.status  # PENDING / STARTED / SUCCESS / FAILURE / RETRY
+result.ready() # bool
+```
+
+---
+
+## 四、错误处理与重试
+
+```python
+@celery_app.task(
+    bind=True,
+    autoretry_for=(ConnectionError,),
+    max_retries=3,
+    retry_backoff=True,
+    retry_backoff_max=600,
+    retry_jitter=True,
+)
+def process_order_task(self, order_id: int):
+    """处理订单"""
+    try:
+        # 业务逻辑
+        ...
+    except BusinessLogicError as exc:
+        # 业务错误不重试，直接记录
+        logger.error(f"Order {order_id} failed: {exc}")
+        raise
+    except ExternalServiceError as exc:
+        # 外部服务错误，手动重试
+        raise self.retry(exc=exc, countdown=60)
+```
+
+| 场景           | 策略                 |
+|----------------|----------------------|
+| 网络超时       | autoretry + backoff  |
+| 业务逻辑错误   | 不重试，记录日志     |
+| 数据不一致     | 不重试，告警通知     |
+| 外部服务故障   | 手动 retry + 固定间隔|
+
+---
+
+## 五、定时任务（Celery Beat）
+
+```python
+celery_app.conf.beat_schedule = {
+    "daily-inventory-sync": {
+        "task": "inventory.sync_inventory",
+        "schedule": crontab(hour=2, minute=0),  # 每天凌晨 2 点
+        "kwargs": {"warehouse_id": 0},
+    },
+    "weekly-report": {
+        "task": "report.generate_weekly_report",
+        "schedule": crontab(day_of_week="monday", hour=8, minute=0),
+    },
+}
+```
+
+---
+
+## 六、Worker 配置
+
+### 6.1 启动命令
+
+```bash
+# 开发环境
+celery -A app.tasks.celery_app worker --loglevel=debug --pool=solo
+
+# 生产环境（SQLite）
+celery -A app.tasks.celery_app worker --loglevel=info --pool=solo --concurrency=1
+
+# Beat 定时任务调度
+celery -A app.tasks.celery_app beat --loglevel=info
+```
+
+### 6.2 SQLite 注意事项
+
+| 事项         | 说明                                           |
+|--------------|------------------------------------------------|
+| 并发         | 必须 `--concurrency=1`，SQLite 不支持并发写    |
+| 连接池       | 每个任务创建新的数据库连接，任务结束关闭       |
+| 事务         | 任务内部手动 commit，不依赖外部事务            |
+| 长时间任务   | 拆分为多个短任务，避免长时间持有数据库锁       |
+
+---
+
+## 七、监控（Flower）
+
+```bash
+celery -A app.tasks.celery_app flower --port=5555
+# 访问 http://localhost:5555
+```
+
+---
+
+## 八、任务测试
+
+```python
+# tests/conftest.py
+@pytest.fixture(autouse=True)
+def celery_eager_mode(monkeypatch):
+    """测试时任务同步执行"""
+    from app.tasks.celery_app import celery_app
+    celery_app.conf.update(
+        task_always_eager=True,
+        task_eager_propagates=True,
+    )
+
+# tests/test_tasks/test_inventory.py
+def test_sync_inventory_task_success(db_session):
+    """测试库存同步任务成功"""
+    warehouse = WarehouseFactory()
+    db_session.add(warehouse)
+    db_session.commit()
+
+    result = sync_inventory_task.delay(warehouse_id=warehouse.id)
+    assert result.successful()
+
+def test_sync_inventory_task_invalid_id():
+    """测试无效仓库 ID"""
+    result = sync_inventory_task.delay(warehouse_id=99999)
+    assert result.failed()
+```

package/references/python-end-standard/04-Redis/344/275/277/347/224/250/350/247/204/350/214/203.md

@@ -0,0 +1,231 @@
+# Redis 使用规范
+
+> **版本**: v1.0 | **修订日期**: 2026-07-15
+> **技术栈**: Redis 7.0+ / redis-py (async)
+
+---
+
+## 一、连接管理
+
+```python
+# app/core/redis.py
+import redis.asyncio as redis
+from app.core.config import settings
+
+redis_client = redis.from_url(
+    settings.REDIS_URL,
+    encoding="utf-8",
+    decode_responses=True,
+    max_connections=20,
+)
+
+async def get_redis() -> redis.Redis:
+    return redis_client
+
+# 生命周期管理
+async def close_redis():
+    await redis_client.close()
+```
+
+---
+
+## 二、Key 命名规范
+
+### 2.1 格式
+
+```
+{app_prefix}:{module}:{entity}:{identifier}
+```
+
+冒号 `:` 分隔层级，便于 Redis CLI 和可视化工具浏览。
+
+### 2.2 示例
+
+| 用途         | Key 示例                                    |
+|--------------|---------------------------------------------|
+| 用户缓存     | app:user:profile:123                        |
+| 仓库列表     | app:warehouse:list:active                   |
+| 会话         | app:session:{token}                         |
+| 限流         | app:ratelimit:api:{user_id}:{endpoint}      |
+| 分布式锁     | app:lock:inventory_sync:{warehouse_id}      |
+| Celery 任务  | celery-task-meta-{task_id}（Celery 自动管理）|
+
+### 2.3 规则
+
+| 规则         | 说明                                           |
+|--------------|------------------------------------------------|
+| 前缀         | 所有 key 必须以 `app:` 开头                    |
+| 层级         | 冒号分隔，不超过 4 层                          |
+| 长度         | 不超过 128 字节                                |
+| 禁止空格     | 使用下划线或驼峰代替空格                       |
+| TTL          | 所有 key 必须设置过期时间                      |
+
+---
+
+## 三、缓存使用
+
+### 3.1 装饰器模式
+
+```python
+import json
+import functools
+
+def cached(key_template: str, ttl: int = 300):
+    """缓存装饰器"""
+    def decorator(func):
+        @functools.wraps(func)
+        async def wrapper(*args, **kwargs):
+            key = key_template.format(**kwargs)
+            r = await get_redis()
+            # 尝试读缓存
+            data = await r.get(key)
+            if data:
+                return json.loads(data)
+            # 执行函数
+            result = await func(*args, **kwargs)
+            # 写缓存
+            await r.setex(key, ttl, json.dumps(result, default=str))
+            return result
+        return wrapper
+    return decorator
+
+# 使用
+@cached(key_template="app:warehouse:detail:{warehouse_id}", ttl=600)
+async def get_warehouse_detail(warehouse_id: int):
+    return await warehouse_service.get_by_id(db, warehouse_id)
+```
+
+### 3.2 缓存失效策略
+
+| 策略         | 适用场景           | 实现                               |
+|--------------|--------------------|------------------------------------|
+| TTL 过期     | 所有缓存           | setex 设置过期时间                 |
+| 主动删除     | 数据更新时         | 更新/删除操作后 delete key         |
+| 模式删除     | 批量失效           | scan + delete（禁止 keys *）       |
+| 版本号       | 配置类数据         | key 中嵌入版本号，更新时递增       |
+
+```python
+# 缓存失效示例
+async def invalidate_warehouse_cache(warehouse_id: int):
+    r = await get_redis()
+    await r.delete(f"app:warehouse:detail:{warehouse_id}")
+    await r.delete("app:warehouse:list:active")
+```
+
+---
+
+## 四、分布式锁
+
+```python
+from redis.asyncio.lock import Lock
+
+async def with_inventory_lock(warehouse_id: int, func, *args, **kwargs):
+    """带分布式锁的库存操作"""
+    r = await get_redis()
+    lock_key = f"app:lock:inventory:{warehouse_id}"
+    lock = Lock(r, lock_key, timeout=30, blocking_timeout=5)
+
+    async with lock:
+        return await func(*args, **kwargs)
+
+# 使用
+await with_inventory_lock(warehouse_id=123, func=sync_inventory)
+```
+
+| 规则         | 说明                                           |
+|--------------|------------------------------------------------|
+| timeout      | 锁的最大持有时间，防止死锁                     |
+| blocking     | 获取锁时是否阻塞等待                           |
+| blocking_timeout | 阻塞等待的最大时间                         |
+| 唯一标识     | Lock 自动使用 UUID，确保释放安全               |
+
+---
+
+## 五、限流
+
+### 5.1 滑动窗口限流
+
+```python
+import time
+
+async def is_rate_limited(user_id: int, endpoint: str, limit: int = 100, window: int = 60) -> bool:
+    """滑动窗口限流"""
+    r = await get_redis()
+    key = f"app:ratelimit:{user_id}:{endpoint}"
+    now = time.time()
+
+    pipe = r.pipeline()
+    pipe.zremrangebyscore(key, 0, now - window)
+    pipe.zadd(key, {str(now): now})
+    pipe.zcard(key)
+    pipe.expire(key, window)
+    results = await pipe.execute()
+
+    return results[2] > limit
+```
+
+---
+
+## 六、数据结构选择
+
+| 场景           | 数据结构       | 示例                                  |
+|----------------|----------------|---------------------------------------|
+| 简单缓存       | String         | GET/SET user profile JSON             |
+| 对象属性       | Hash           | HSET user:123 name "Alice"            |
+| 列表/队列      | List           | LPUSH/RPOP 消息队列                   |
+| 去重集合       | Set            | SADD user:123:tags "vip"              |
+| 排行榜/排序    | Sorted Set     | ZADD leaderboard score member          |
+| 位操作         | Bitmap         | SETBIT user:active:20260715 user_id 1 |
+| 计数器         | String (INCR)  | INCR page:views:home                  |
+
+---
+
+## 七、序列化规范
+
+| 规则         | 说明                                           |
+|--------------|------------------------------------------------|
+| 格式         | 统一使用 JSON                                  |
+| 禁止 pickle  | 安全风险，禁止序列化 Python 对象               |
+| datetime     | 序列化为 ISO 8601 字符串                       |
+| Decimal      | 序列化为字符串                                 |
+| bytes        | Base64 编码后存储                              |
+
+---
+
+## 八、内存管理
+
+| 配置           | 推荐值          | 说明                               |
+|----------------|-----------------|------------------------------------|
+| maxmemory      | 根据服务器内存  | 设置最大内存限制                   |
+| maxmemory-policy | allkeys-lru   | 内存满时淘汰策略                   |
+| 过期时间       | 必须设置        | 所有 key 必须有 TTL                |
+| 大 key 监控    | redis-cli --bigkeys | 定期检查大 key                 |
+
+---
+
+## 九、测试规范
+
+```python
+# tests/conftest.py
+import fakeredis.aioredis
+
+@pytest.fixture
+async def redis_client():
+    """使用 fakeredis 隔离测试"""
+    fake = fakeredis.aioredis.FakeRedis(decode_responses=True)
+    yield fake
+    await fake.flushall()
+    await fake.close()
+
+# 测试示例
+async def test_cache_hit(redis_client):
+    await redis_client.setex("app:test:key", 60, "value")
+    result = await redis_client.get("app:test:key")
+    assert result == "value"
+```
+
+| 规则         | 说明                                           |
+|--------------|------------------------------------------------|
+| fakeredis    | 单元测试使用 fakeredis，不依赖真实 Redis       |
+| 隔离         | 每个测试前后 flushall                          |
+| 集成测试     | 使用独立 Redis DB（db=15）                     |

package/references/python-end-standard/index.md

@@ -0,0 +1,12 @@
+# 后端规则文件索引
+
+## 推荐读取顺序
+
+1. 01-Python后端编码规范.md
+2. 02-数据库设计与使用规范.md
+3. 03-Celery异步任务规范.md
+4. 04-Redis使用规范.md
+
+
+## 维护要求
+- 新增规则文件时，同步更新本索引和根目录 `claude.md`。