create-dwy 0.19.0 → 0.20.0

package/templates/ai-tools/skills/DolphinDB/dwy-dolphindb/references/review-rules/anti-patterns.md

@@ -1,7 +1,7 @@
 # DolphinDB 反模式与最佳实践
 
 > 何时引用：审查 DDB 代码 / SQL / Python SDK 用法，命中具体反模式时引用对应章节。
-> 来源：dwy-dolphindb skill 内部规则（基于真实踩坑总结，非官方文档可替代）。
+> 来源：真实踩坑。语言语义以本文件为准，直到官方文档改写了这条语义。字节上限、分区数、行数以当前 server 文档和报错为准，下面的数字是当时的上限。
 
 ## 类型陷阱
 
@@ -55,6 +55,8 @@ DDB 和 Python/SQL **相反**！老手都踩过。要小数结果用 `\`。
 
 ### 5. SYMBOL ≤255 字节 / STRING 64KB / BLOB 64MB 静默截断（**1.30.23 / 2.00.11 起**）
 
+255 字节、64KB、64MB 是这些版本起的已知上限。连上的 server 文档或实际报错不同，以那次为准。
+
 | 类型 | 上限 | 超限行为 |
 |---|---|---|
 | `SYMBOL` | **≤ 255 字节** | **整批 append 直接抛异常**，写入失败 |

package/templates/ai-tools/skills/DolphinDB/dwy-dolphindb/references/review-rules/change-checklist.md

@@ -7,18 +7,18 @@
 
 - [ ] WHERE 是否命中分区列？分区列是否被函数包裹（`year()` / `date()` / `temporalAdd()`）？
 - [ ] 范围条件用了 `between ... and ...` 或两个独立条件？没有链式比较 `a <= col <= b`？
-- [ ] 单次 `append` ≤ 500K 行？循环里有 `del + gc.collect()`？
+- [ ] 单次 `append` 低于当前 server 的单消息上限？写作时常见约 500K 行，以本次报错为准。循环里有 `del + gc.collect()`？
 - [ ] 大文件用 pyarrow `read_table + slice`，不是 `pd.read_feather` 全量加载？
 - [ ] 拼接 DDB 脚本时，外部输入有正则白名单校验？（防注入）
 - [ ] `pool.run()` 用 `await`（原生 async），`Session.run()` 用 `asyncio.to_thread()`？
-- [ ] 连接池大小 ≤ CPU 核数 × 2（社区版 4 worker → pool 3）？
+- [ ] 连接池大小按本次 worker？2 核 8G、4 worker 的先验是 pool 3，不是所有集群的上限。
 - [ ] `select` 只取需要的列？没有 `select *`？
 - [ ] 多次聚合查询能否合并为一次？
 - [ ] 多因子横向查询用了 `pivot by`，不是 Python 端 merge？
 - [ ] backtick 列名定义在单行内？
 - [ ] 分页用 `limit offset, count`（**不是** `LIMIT x OFFSET y`）？
-- [ ] 新建库表：单分区估算大小落在引擎区间？总分区数远低于 65536？二级高基数列走 `HASH` 不是 `VALUE`？
-- [ ] 写入 SYMBOL 列前校验 ≤ 255 字节？STRING/BLOB 有长度断言防静默截断？
+- [ ] 新建库表：单分区估算大小落在引擎区间？总分区数低于该节点 `maxPartitionNumPerQuery`（默认常见 65536）？二级高基数列走 `HASH` 不是 `VALUE`？
+- [ ] 写入 SYMBOL 列前校验当前版本字节上限（常见 255）？STRING/BLOB 有长度断言防静默截断？
 - [ ] 删数据用 `dropPartition`，不是 `delete from`？
 - [ ] pandas → DDB：`uint` 是否 `.astype('int64')`？NaN→int 是否 `.fillna(0)`？
 - [ ] Session / Pool 有 `try/finally close()`？

package/templates/ai-tools/skills/DolphinDB/dwy-dolphindb/references/review-rules/lethal-violations.md

@@ -1,20 +1,20 @@
 # 10 条致命违规（零容忍）
 
-> 何时引用：审查 DDB 代码 / SQL / Python SDK 用法。命中任意一条都属于零容忍违规，必须修复。
-> 来源：dwy-dolphindb skill 内部规则（非官方文档可替代）。
+> 何时引用：审查 DDB 代码 / SQL / Python SDK 用法。
+> 分区剪枝、注入、连接池变量这些是语言约束，命中就要改。行数、字节、分区数是当时 server 的上限。官方文档或这次报错更准时，以那次为准，不要用本表压过当前版本文档。
 
 | # | 违规 | 后果 |
 |---|---|---|
 | 1 | 分区列被函数包裹（`date(col)` / `year(col)` / `temporalAdd(col,...)`） | 全表扫 → OOM |
 | 2 | 链式比较 `a <= col <= b` | 不触发剪枝 → 全表扫 |
-| 3 | 单次 `append` > 500K 行 | TSDB 报 `exceeds max limit` |
+| 3 | 单次 `append` 超过当前 server 的单消息上限（写作时常见约 500K 行） | TSDB 报 `exceeds max limit`。不是永远 500K |
 | 4 | 未校验外部输入拼到脚本 | 脚本注入 |
 | 5 | 连接池里 upload + run（变量跨连接不可见） | 变量找不到 |
 | 6 | `select *`（30+ 列全传） | 浪费带宽和内存 |
 | 7 | 分页用 `LIMIT x OFFSET y` | DDB 不支持 OFFSET 关键字（要用 `limit offset, count`） |
 | 8 | `asyncio.to_thread(pool.run, script)` | SDK v3 `pool.run` 已是原生 async |
-| 9 | SYMBOL 列写入未校验 ≤255 字节 | 整批写入失败 |
-| 10 | 单分区 < 100MB 且总分区数 > 65536 | 触达 `maxPartitionNumPerQuery` 上限 |
+| 9 | SYMBOL 列写入未校验当前版本字节上限（1.30.23 / 2.00.11 起常见 255 字节） | 整批写入失败。以本次 server 文档为准 |
+| 10 | 单分区过小且总分区数超过该节点 `maxPartitionNumPerQuery`（默认常见 65536） | 触达查询分区上限。配置改过就用配置值 |
 
 ## 审查输出格式
 

package/templates/ai-tools/skills/DolphinDB/dwy-dolphindb/references/review-rules/perf-baselines.md

@@ -1,9 +1,9 @@
 # 性能基线（DolphinDB 3.0 社区版 2 核 8G）
 
 > 何时引用：评估查询/写入性能、判断是否需要优化、配置 dolphindb.cfg。
-> 来源：dwy-dolphindb skill 内部规则 + 社区版实测数据。
+> 来源：一次 2 核 8G 社区版实测。有 `getClusterPerf`、license 或节点配置时以实测为准。偏离下表不是违规。超过表只说明要排查。
 
-## 资源预算（死守）
+## 资源预算（这次 2 核 8G 的冷启动先验）
 
 ```
 总内存 8 GB
@@ -29,7 +29,7 @@ where TradeDate between 2024.01.01 and 2024.01.05
 
 ## 配置调优（社区版 dolphindb.cfg）
 
-社区版固定 2 核 8G，可调的关键参数：
+下面是 2 核 8G 社区版的起点。许可或机器不同，按本次核数和内存重算，不要照抄。
 
 | 参数 | 建议值 | 说明 |
 |---|---|---|
@@ -54,7 +54,7 @@ where TradeDate between 2024.01.01 and 2024.01.05
 | Python 拉 100 万行 → DataFrame | 2-5s |
 | `PartitionedTableAppender` 写入 | 200-400 万行/s |
 
-**超过基线 2-3x 必须排查**：剪枝是否生效（`select [HINT_EXPLAIN]`）、索引是否覆盖、并发是否争抢同分区。
+**比这张表慢 2-3 倍要排查**，不是判死刑：剪枝是否生效（`select [HINT_EXPLAIN]`）、索引是否覆盖、并发是否争抢同分区。机器不同，时延表本身就作废。
 
 ## 分区粒度目标
 
@@ -63,7 +63,7 @@ where TradeDate between 2024.01.01 and 2024.01.05
 | TSDB | 400 MB - 1 GB |
 | OLAP | 100 MB - 300 MB |
 
-总分区数 < 65536，否则触达 `maxPartitionNumPerQuery` 上限。
+总分区数不要超过该节点的 `maxPartitionNumPerQuery`。默认常见 65536，配置改过就用配置值，不要死守 65536。
 
 ## 连接池大小
 

package/templates/ai-tools/skills/Python/dwy-eapi/SKILL.md

@@ -1,226 +1,85 @@
 ---
 name: dwy-eapi
-description: "dwyeapi FastAPI 后端基础设施使用指南。涉及以下任何主题，**必须**使用此 skill（即使用户没有明确说 'dwyeapi' / 'eapi'）：FastAPI 项目搭建 / Pydantic Settings 配置 / 异步 SQLAlchemy / Redis 缓存 / JWT 认证 / bcrypt 密码哈希 / 异常体系（AppError / NotFoundError / BusinessError）/ 统一响应信封（ApiResponse / PageData）/ 分页 / 日志（loguru）/ 健康检查 / PII 脱敏 / 时区敏感的时间处理 / 异步任务（ARQ）/ 邮件验证码发送。本 skill 是 @dwydev/eapi 的唯一权威导航来源。"
-eapi_baseline_version: "0.9.0"
+description: "Use when building or changing FastAPI backends that use dwyeapi: Pydantic Settings, async SQLAlchemy, Redis, JWT/bcrypt, AppError/NotFoundError/BusinessError, ApiResponse/PageData, pagination, loguru, health checks, PII masking, timezone-aware dt, ARQ tasks, email verification codes, Gmail alias canonicalization, common email-domain allowlist. The single navigation skill for dwyeapi."
 ---
 
-# dwyeapi 后端基础设施使用指南
+# dwyeapi
 
-Python 3.11+ FastAPI 基础设施包，全异步。单文件模块设计（每个能力一个 .py），便于直接读源码。
+FastAPI 基础设施包。本文件只做**路由**：探测安装版本 → 选文档线 → 不够再读源码（先 clone tag，拿不到再读虚拟环境）。
 
-本 skill 索引基于 dwyeapi **0.9.0**。消费方版本可能不同 — 见 [版本兼容规则](#版本兼容规则)。
+对外只有这一个 skill。`v0/` `v1/` 不是独立 skill，禁止当多个入口用。
 
-## 模块清单（13 个）
+## 每次写 dwyeapi 代码前（强制）
 
-| 模块 | 用途 |
-|------|------|
-| `config` | Pydantic BaseSettings + 运行环境识别 (is_dev / is_prod / get_environment) |
-| `exceptions` | AppError 异常体系 + FastAPI 全局 handler 注册 |
-| `database` | 异步 SQLAlchemy engine/session 工厂 + Base + TimestampMixin |
-| `dependencies` | FastAPI 依赖注入工厂（如 get_db） |
-| `security` | JWT 令牌 + bcrypt 密码哈希（无状态） |
-| `cache` | 异步 Redis 连接管理（懒单例） |
-| `response` | 统一 API 响应信封 `ApiResponse[T]` + `PageData[T]` |
-| `pagination` | 分页参数 PaginationParams + offset/limit 计算 |
-| `dt` | 中国时区敏感的全局时间工具（替代 datetime.now） |
-| `logger` | loguru 全局日志（按天 + 按大小轮转、stdlib 拦截） |
-| `masking` | PII 数据脱敏（手机/邮箱/身份证/银行卡/姓名/地址/IP/车牌） |
-| `health` | 健康检查路由工厂（只探活、不探依赖） |
-| `tasks` | 异步任务系统（基于 ARQ，需 `pip install dwyeapi[tasks]`） |
-| `providers.email` | 邮件验证码发送（可插拔，默认 Resend，可继承注入腾讯 SES / SMTP 等） |
-
----
-
-## 查 API 标准动作（核心：每次写 dwyeapi 代码前都做）
-
-dwyeapi 的源码 docstring 写得非常详尽（含设计意图、边界行为、Args/Returns/Raises、典型陷阱）。**本文档不再镜像签名表格** —— 因为表格信息密度低于源码 docstring，且会随版本漂移。需要某个 API 的精确签名/语义时，按下面顺序拿：
-
-### 第一步：定位 dwyeapi 真实版本和安装路径
-
-```bash
-# 拿版本
-pip show dwyeapi | grep -i version
-#  或：python -c "import dwyeapi; print(dwyeapi.__version__)"
-
-# 拿包安装目录
-python -c "import dwyeapi; print(dwyeapi.__file__)"
-# 输出形如 /path/to/.venv/lib/python3.12/site-packages/dwyeapi/__init__.py
-# dirname 后的目录就是 dwyeapi 包根，模块都在里面
-```
-
-### 第二步：读模块源码（按存在性回退）
-
-```
-a. 优先：<site-packages>/dwyeapi/{module}.py
-   —— 下游消费方默认场景。每个模块单文件，含模块级 docstring + 所有公开函数/类的 Args/Returns/Raises
-
-b. 次选：<dwy-shared-root>/backend/src/dwyeapi/{module}.py
-   —— 仅当在 dwy-shared monorepo 内或并列 clone 时可用，内容相同
-
-c. 都拿不到 → 退到本文档下方的 [模块清单](#模块清单13-个)（粗略，仅做导航）
-```
-
-### 第三步：tasks 模块查详细文档
-
-tasks 模块功能丰富（注册 / 提交 / 查询 / 取消 / 进度），单独维护一份完整集成指南：
-
-```
-references/tasks-integration-guide.md
-```
-
-只在用到 tasks 时读，平时不必加载。
-
-### 第四步：冲突时永远信源码
-
-本 SKILL.md 是导航 + 心智模型，**不是 API 真相**。当文档描述与 site-packages 中的 `.py` 不一致：无条件以源码为准。
-
----
+1. **探测安装版本**（按顺序，命中即停）
+   ```bash
+   python -c "import dwyeapi; print(dwyeapi.__version__)"
+   ```
+   失败则读项目 `pyproject.toml` / `uv.lock` 里 `dwyeapi` 约束。
+   仍失败：按 `v0` 给脚手架，并声明「未探测到安装版本」。
 
-## 版本兼容规则
+2. **选线**：读同目录 `versions.yml`。`0.y.z` → `v0/`，`1.y.z` → `v1/`，`2.y.z` → `v2/`。目录不存在（例如装了 1.x 但还没有 `v1/`）→ 不要用 `v0` 冒充；按下面「读源码」拿该版本代码，并说明文档线未建。
 
-- 本 skill `eapi_baseline_version: 0.9.0`，模块清单、踩坑提示都基于这个版本
-- 消费方装的是不同版本（更新或更旧）时，**必须**按"查 API 标准动作"流程读 .py，不要默认本文档准确
-- dwyeapi < 0.9.0 可能没有 dt / tasks / providers 模块：先 `ls <site-packages>/dwyeapi/` 确认存在再用
-- 主版本号变更（0.x → 1.x）时，本文档的索引可能完全失效：先 `ls <site-packages>/dwyeapi/` 重建认知
+3. **读文档**：先 `shared/`（跨大版本不变），再该线 `vN/`。能力标了版本下限（如 `canonicalize_email` ≥0.9.6）时，安装版本低于下限 → 当不存在。
 
----
-
-## 重要约束与已知陷阱
-
-源码读得出来但容易忽略的"踩坑经验"，写后端代码时遵守：
-
-### 业务层架构（service / router 分层）
-
-- **service 层**抛业务异常（`NotFoundError("用户")` / `BusinessError("余额不足", code="INSUFFICIENT_BALANCE")` 等），不感知 HTTP 概念
-- **router 层**不写 try/except，由 `register_exception_handlers(app)` 统一转成 `ApiResponse` 信封 JSON
-- **禁止**在 service 层抛 `HTTPException` —— 会绕过统一 handler，破坏响应结构一致性
-
-### 时间处理（避免时区 bug）
-
-- 业务时间统一中国时区，**禁止 `datetime.now()`**，统一走 `dwyeapi.dt`
-- `dt.now()` 返回 naive datetime（Asia/Shanghai，用于数据库存储）
-- `dt.utc_now()` 返回 aware UTC datetime（用于 JWT exp 等协议字段）
-- 这两个不能混用：数据库列存 naive 中国时间、JWT exp 存 UTC aware
-
-### 配置
-
-- **没有 `debug` 字段**，所有调试开关统一用 `is_dev()`：避免两个维度（debug + environment）冲突
-- `environment` 默认 `"prod"`（误配置时保守）：生产环境必须显式关闭 docs/redoc/openapi 三个端点（`docs_url="/docs" if is_dev() else None`），否则路由元信息会泄露给攻击者
-- `BaseSettings` 必填三个字段：`database_url` / `redis_url` / `secret_key`（继承时不能给默认值）
-
-### Redis 连接
-
-- `cache.configure(redis_url)` 启动时调用一次（lifespan）；`cache.get_redis()` 首次调用懒建立连接
-- `close_redis()` 可重复调用（安全幂等），lifespan 关闭阶段调用
-- 未 configure 直接 `get_redis()` 会抛 `RuntimeError`
-
-### tasks 模块
-
-- 需要 `pip install dwyeapi[tasks]` 单独装 extra（避免不用任务的项目背 ARQ 依赖）
-- 任务函数签名固定 `async def task(ctx: TaskContext, params: dict)`，第一个参数 ctx 由框架注入
-- 取消机制是协作式：任务函数内必须主动 `await ctx.is_cancelled()` 检查，否则取消信号无效
-- 完整细节读 `references/tasks-integration-guide.md`
+4. **文档不够 / 和记忆冲突 / 下限对不上** → 读代码，顺序如下（命中即停）：
+   1. clone 安装版本对应 tag（见下）
+   2. tag 不存在 / clone 失败 → 读**当前虚拟环境**里已安装的 `dwyeapi` 源码
+   3. 虚拟环境也没有 → **停下来问人**，禁止猜 API，禁止拿旁边 dwy-shared master 冒充
 
-### 邮件 Provider
+## 读源码
 
-- 内置仅 `resend`。业务用其他通道（腾讯 SES / SMTP / 自建）：继承 `EmailProviderBase` 实现 `_send` → `register_email_provider("name", factory)` → `.env` 设 `EMAIL__PROVIDER=name`
-- 验证码生成 + Redis 存储 + 品牌化模板 由基类全部复用，子类只管"发出去"
+### 1. clone tag（优先）
 
-### 日志
-
-- `logger.configure()` 启动时调用一次；`logger.close()` 在 lifespan 结束时调用
-- `intercept_stdlib=True`（默认）会把 stdlib logging（uvicorn / SQLAlchemy 等）也接管到统一 sink
-- 多进程部署时必须 `enqueue=True`（默认）——避免日志文件竞争写
-
-### 健康检查
-
-- `create_health_router()` **只**探活、**不**触达 PostgreSQL / Redis 等依赖
-- 理由：健康端点常对公网开放，内置 dependency check 会被攻击者用来 DoS 放大数据库/缓存
-- 需要 readiness 的业务自行实现并限制内网访问
-
----
-
-## 典型项目接入流程
-
-```python
-# config.py
-from dwyeapi.config import BaseSettings
-
-class Settings(BaseSettings):
-    app_name: str = "My API"
-    service_name: str = "my-api"
-
-settings = Settings()  # 从 .env / 环境变量读 database_url、redis_url、secret_key
-
-# database.py
-from dwyeapi.database import create_async_engine_factory, create_session_factory
-from dwyeapi.dependencies import create_get_db
-from dwyeapi import is_dev
-
-engine = create_async_engine_factory(settings.database_url, echo=is_dev())
-session_factory = create_session_factory(engine)
-get_db = create_get_db(session_factory)
-
-# main.py
-from contextlib import asynccontextmanager
-from fastapi import FastAPI
-from dwyeapi import cache, logger, is_dev
-from dwyeapi.exceptions import register_exception_handlers
-from dwyeapi.health import create_health_router
-
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    logger.configure(level="INFO", log_dir="./logs", filename="app")
-    cache.configure(settings.redis_url)
-    yield
-    await cache.close_redis()
-    logger.close()
-
-app = FastAPI(
-    lifespan=lifespan,
-    docs_url="/docs" if is_dev() else None,
-    redoc_url="/redoc" if is_dev() else None,
-    openapi_url="/openapi.json" if is_dev() else None,
-)
-register_exception_handlers(app)
-app.include_router(create_health_router(service_name=settings.service_name, version="1.0.0"))
+```bash
+VER=0.9.6                          # 换成第 1 步探测到的版本
+TAG="dwyeapi@${VER}"
+DEST=".dwy/eapi-src/${VER}"        # 项目内缓存，已 gitignore
+
+if [ ! -d "$DEST/backend/src/dwyeapi" ]; then
+  git clone --depth 1 --branch "$TAG" \
+    --filter=blob:none --sparse \
+    https://github.com/danweiyuancircle/dwy-ai-experience.git \
+    "$DEST"
+  git -C "$DEST" sparse-checkout set backend/src/dwyeapi
+fi
+# 只读 $DEST/backend/src/dwyeapi/ 的模块 docstring
 ```
 
----
-
-## 响应契约速查（前后端对齐用）
+- `--branch` 必须是 `dwyeapi@x.y.z`，禁止 clone 默认 branch。
+- 必须 sparse，只要 `backend/src/dwyeapi`。
 
-所有接口返回统一信封：
+### 2. 虚拟环境（clone 拿不到时）
 
-```json
-{
-  "code": "SUCCESS",
-  "message": "success",
-  "data": { ... },
-  "timestamp": 1775625000
-}
+```bash
+python -c "import dwyeapi, os; print(os.path.dirname(dwyeapi.__file__))"
+# 输出形如 .venv/lib/python3.11/site-packages/dwyeapi
+# 读该目录下模块 docstring
 ```
 
-- 成功：`code = "SUCCESS"`，`data` 是业务载荷（单体或 `PageData[T]`）
-- 失败：`code` 是业务错误码（如 `NOT_FOUND` / `BUSINESS_ERROR` / `VALIDATION_ERROR` 等），HTTP 状态保持语义（404 就是 404）
-- 校验错误 `VALIDATION_ERROR`：`data.errors: [{field, message}]`，field 含 `body.` / `query.` / `path.` 前缀
-
-构造响应：用 `ApiResponse.ok(data)` 或 `ApiResponse.page(items, total, page, page_size)`，不直接实例化 `ApiResponse`。
+editable 安装时这个路径就是消费方正在跑的代码，当作安装版本真相。
 
-错误响应**不要业务代码构造** —— 直接 `raise NotFoundError("用户")`，handler 自动转。
+文档与源码冲突：信源码。clone 与 venv 都读到且不一致：以 **venv** 为准（editable / 热修），回复里写明。
 
----
+## 文档地图
 
-## 防腐层硬性约束（写代码前必读）
+| 路径 | 何时读 |
+|------|--------|
+| `shared/layering.md` | 分层、禁 HTTPException |
+| `shared/timezone.md` | 禁 `datetime.now` |
+| `shared/response-envelope.md` | ApiResponse 信封 |
+| `shared/anticorruption.md` | 禁止直调 redis/jwt/logging |
+| `v0/index.md` | 0.x 模块清单、接入、陷阱 |
+| `v0/providers-email.md` | 邮件 Provider 注册表 |
+| `v0/email-canonical.md` | Gmail 规范化（≥0.9.6）+ 常见域名白名单 / 发码校验（≥0.10.0） |
+| `v0/breaking.md` | 0.x 内部 breaking |
+| `references/tasks-integration-guide.md` | 只用 tasks 时读 |
 
-dwyeapi 把基础设施细节封装在自有 API 后面。业务代码**禁止**直接调下面这些底层 API，违反会导致升级困难、行为不一致：
+## 禁止
 
-| 禁止 | 改用 |
+| 借口 | 实际 |
 |------|------|
-| `datetime.now()` / `datetime.utcnow()` | `dt.now()` / `dt.utc_now()` |
-| `import logging; logging.getLogger()` | `from dwyeapi import logger; logger.get_logger()` |
-| 手写 `from redis.asyncio import Redis` 全局变量 | `cache.configure()` + `cache.get_redis()` |
-| 手写 JWT encode/decode（含 `import jwt`） | `security.create_token()` / `security.decode_token()` |
-| 直接 `raise HTTPException(404, ...)` | `raise NotFoundError("资源名")` |
-| 自己写 `{"code": ..., "data": ...}` dict 当响应 | `ApiResponse.ok(data)` / `ApiResponse.page(...)` |
-| 自己写 `?page=&page_size=` Query 参数 | `params: PaginationParams = Depends()` |
+| 读旁边 dwy-shared master | 消费方版本可能不同。先 clone 安装版本的 tag，不行再读本项目 venv |
+| 文档是 0.9，装的 0.9.6，差不多 | 有下限的能力必须对照版本 |
+| tag 没有就猜 / 直接停 | clone 失败后读 venv；venv 也没有才停 |
+| 再开一个 `dwy-eapi-v0` skill | 对外只有 `dwy-eapi` |

package/templates/ai-tools/skills/Python/dwy-eapi/shared/anticorruption.md

@@ -0,0 +1,13 @@
+# 防腐层
+
+业务代码禁止直调底层 API：
+
+| 禁止 | 改用 |
+|------|------|
+| `datetime.now()` / `datetime.utcnow()` | `dt.now()` / `dt.utc_now()` |
+| `import logging; logging.getLogger()` | `from dwyeapi import logger; logger.get_logger()` |
+| 手写 `from redis.asyncio import Redis` 全局变量 | `cache.configure()` + `cache.get_redis()` |
+| 手写 JWT encode/decode（含 `import jwt`） | `security.create_token()` / `security.decode_token()` |
+| 直接 `raise HTTPException(404, ...)` | `raise NotFoundError("资源名")` |
+| 自己写 `{"code": ..., "data": ...}` dict | `ApiResponse.ok(data)` / `ApiResponse.page(...)` |
+| 自己写 `?page=&page_size=` Query | `params: PaginationParams = Depends()` |

package/templates/ai-tools/skills/Python/dwy-eapi/shared/layering.md

@@ -0,0 +1,5 @@
+# 分层
+
+- **service 层**抛业务异常（`NotFoundError("用户")` / `BusinessError("余额不足", code="INSUFFICIENT_BALANCE")`），不感知 HTTP。
+- **router 层**不写 try/except，由 `register_exception_handlers(app)` 统一转成 `ApiResponse` 信封。
+- **禁止**在 service 层抛 `HTTPException` —— 会绕过统一 handler。

package/templates/ai-tools/skills/Python/dwy-eapi/shared/response-envelope.md

@@ -0,0 +1,20 @@
+# 响应信封
+
+所有接口返回：
+
+```json
+{
+  "code": "SUCCESS",
+  "message": "success",
+  "data": {},
+  "timestamp": 1775625000
+}
+```
+
+- 成功：`code = "SUCCESS"`，`data` 是业务载荷（单体或 `PageData[T]`）
+- 失败：`code` 是业务错误码（`NOT_FOUND` / `BUSINESS_ERROR` / `VALIDATION_ERROR`），HTTP 状态保持语义
+- 校验错误 `VALIDATION_ERROR`：`data.errors: [{field, message}]`，field 含 `body.` / `query.` / `path.` 前缀
+
+构造：`ApiResponse.ok(data)` 或 `ApiResponse.page(items, total, page, page_size)`，不直接实例化成功态。
+
+错误响应不要业务代码拼信封 —— `raise NotFoundError("用户")`，handler 自动转。

package/templates/ai-tools/skills/Python/dwy-eapi/shared/timezone.md

@@ -0,0 +1,7 @@
+# 时间
+
+业务时间统一中国时区。**禁止 `datetime.now()` / `datetime.utcnow()`**，走 `dwyeapi.dt`。
+
+- `dt.now()`：naive（Asia/Shanghai），数据库存储
+- `dt.utc_now()`：aware UTC，JWT exp 等协议字段
+- 两者不能混用

package/templates/ai-tools/skills/Python/dwy-eapi/v0/breaking.md

@@ -0,0 +1,15 @@
+# 0.x 内部 breaking
+
+0.x 的 minor 也可以不兼容。整条线仍用 `v0/`，破坏点记在这里。细节 clone `dwyeapi@x.y.z`，不要另开 `v0.10/` 目录。
+
+完整段落以该 tag 的 `backend/CHANGELOG.md` 为准。
+
+| 版本 | 破坏点 |
+|------|--------|
+| 0.6.0 | 信封改为 `ApiResponse[T]` / `PageData[T]`；删除 `success` / `fail` / `paginated`；`code` 成功态从 int `200` 改为 `"SUCCESS"` |
+| 0.9.0 | 删除 `MockEmailProvider`、`AliyunEmailProvider`、整个 `providers.sms`；`EMAIL__PROVIDER` 改为自由字符串；mock/阿里云改业务 `register_email_provider` |
+| 0.10.0 | `send_code` 默认校验常见邮箱域名；非白名单抛 `EMAIL_DOMAIN_NOT_ALLOWED`。B2B 设 `EMAIL__REQUIRE_COMMON_DOMAIN=false` |
+
+0.9.6 起新增 `dwyeapi.email` 与 Redis key 规范化，对旧调用方兼容（发码 key 折到同一收件箱）。能力下限见 `email-canonical.md`。
+
+常见域名白名单：`send_code` 默认启用 `require_common_email_domain`（≥0.10.0，`EMAIL__REQUIRE_COMMON_DOMAIN=true`）。B2B 可关。

package/templates/ai-tools/skills/Python/dwy-eapi/v0/email-canonical.md

@@ -0,0 +1,43 @@
+# 邮箱规范化与常见域名白名单（≥0.9.6）
+
+安装版本 `< 0.9.6`：没有 `dwyeapi.email`，不要 import。
+
+```python
+from dwyeapi.email import canonicalize_email, is_folded_alias, GMAIL_DOMAINS
+
+canonicalize_email("Bai.Wen+1@Gmail.com")  # baiwen@gmail.com
+canonicalize_email("a.b@googlemail.com")   # ab@gmail.com
+canonicalize_email("a+x@icloud.com")       # a+x@icloud.com
+is_folded_alias("a+x@gmail.com")           # True
+is_folded_alias("A@gmail.com")           # False
+```
+
+- 注册查重、登录查找、用户表写入 **必须** 走 `canonicalize_email`
+- Gmail 把 plus / 点号 / `googlemail.com` 当成同一收件箱，不折会开多个号、绕过发码冷却
+- 其它域名只做 strip + lower，保留 `+` 与点
+- `send_code` / `verify_code` 的 Redis key 已自动规范化；发信信封仍用用户输入地址
+
+## 常见域名白名单（≥0.10.0）
+
+安装版本 `< 0.10.0`：没有 `is_common_email_domain`，不要 import。一次性邮箱会换马甲域，黑名单跟不上。
+
+**`send_code` 默认校验**（`EMAIL__REQUIRE_COMMON_DOMAIN=true`）。不在白名单：抛 `BusinessError(code="EMAIL_DOMAIN_NOT_ALLOWED")`，不发信、不写 Redis。B2B 可关。
+
+```python
+from dwyeapi.email import require_common_email_domain
+from dwyeapi.providers.email import EmailSettings
+
+# 发码已默认走白名单；业务也可在注册/换绑再调一次
+email = require_common_email_domain(raw)
+
+# .env
+# EMAIL__REQUIRE_COMMON_DOMAIN=true
+# EMAIL__EXTRA_ALLOW_DOMAINS=chances.com.cn
+# EMAIL__ALLOW_EDU=true
+# EMAIL__ALLOW_EDU_CN=true
+```
+
+- 精确匹配 `COMMON_EMAIL_DOMAINS`（qq / 163 / gmail / outlook / icloud / proton 等），`mail.qq.com` 不等于 `qq.com`
+- 默认放行美国 `.edu`（`columbia.edu`）与 `edu.cn` / `*.edu.cn`；**不**放行 `edu.kg` / `edu.pl` 等国家教育后缀
+- 企业 / 机构域用 `extra_allow` / `EMAIL__EXTRA_ALLOW_DOMAINS`（如 `chances.com.cn`），不要把公司域写进框架常量表
+- 自定义 provider 的 factory 必须把 `require_common_domain` / `extra_allow_domain_list()` / `allow_edu` / `allow_edu_cn` 传给 `EmailProviderBase`

package/templates/ai-tools/skills/Python/dwy-eapi/v0/index.md

@@ -0,0 +1,103 @@
+# dwyeapi 0.x
+
+精确签名以安装版本的源码为准（见上级 SKILL.md：先 clone tag，拿不到再读 venv）。本页是 0.x 导航与陷阱。
+
+跨大版本不变的分层 / 时区 / 信封 / 防腐层在 `shared/`。
+
+## 模块清单（当前 0.9 线）
+
+| 模块 | 用途 | 下限 |
+|------|------|------|
+| `config` | BaseSettings + `is_dev` / `is_prod` / `get_environment` | |
+| `exceptions` | AppError + FastAPI handler | |
+| `database` | 异步 engine/session + Base + TimestampMixin | |
+| `dependencies` | `get_db` 工厂 | |
+| `security` | JWT + bcrypt | |
+| `cache` | 异步 Redis | |
+| `response` | `ApiResponse[T]` + `PageData[T]` | ≥0.6.0 |
+| `pagination` | PaginationParams + paginate | |
+| `dt` | 中国时区时间工具 | ≥0.7 左右；`timedelta`/`after` ≥0.9.4 |
+| `logger` | loguru | |
+| `masking` | PII 脱敏 | |
+| `email` | Gmail 规范化 + 常见域名白名单 | 规范化 ≥0.9.6；白名单 / 发码校验 ≥0.10.0 |
+| `health` | 只探活健康检查 | ≥0.7.0 |
+| `tasks` | ARQ 异步任务，需 `[tasks]` | ≥0.7 后 |
+| `providers.email` | 邮件验证码，内置 resend | 工厂注册表 ≥0.9.0 |
+
+`<0.9.0` 可能没有 dt / tasks / providers。先 `ls` 安装目录或 clone 该 tag 再调用。
+
+## 接入骨架
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from dwyeapi import cache, logger, is_dev
+from dwyeapi.config import BaseSettings
+from dwyeapi.database import create_async_engine_factory, create_session_factory
+from dwyeapi.dependencies import create_get_db
+from dwyeapi.exceptions import register_exception_handlers
+from dwyeapi.health import create_health_router
+
+class Settings(BaseSettings):
+    app_name: str = "My API"
+    service_name: str = "my-api"
+
+settings = Settings()
+engine = create_async_engine_factory(settings.database_url, echo=is_dev())
+session_factory = create_session_factory(engine)
+get_db = create_get_db(session_factory)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    logger.configure(level="INFO", log_dir="./logs", filename="app")
+    cache.configure(settings.redis_url)
+    yield
+    await cache.close_redis()
+    logger.close()
+
+app = FastAPI(
+    lifespan=lifespan,
+    docs_url="/docs" if is_dev() else None,
+    redoc_url="/redoc" if is_dev() else None,
+    openapi_url="/openapi.json" if is_dev() else None,
+)
+register_exception_handlers(app)
+app.include_router(create_health_router(service_name=settings.service_name, version="1.0.0"))
+```
+
+## 0.x 陷阱
+
+### 配置
+
+- **没有 `debug` 字段**，调试开关用 `is_dev()`
+- `environment` 默认 `"prod"`。非 dev 必须关掉 docs/redoc/openapi
+- `BaseSettings` 必填：`database_url` / `redis_url` / `secret_key`（子类不能给默认值）
+
+### Redis
+
+- `cache.configure(redis_url)` 启动时一次；`get_redis()` 懒连接
+- `close_redis()` 可重复调用
+- 未 configure 直接 `get_redis()` → `RuntimeError`
+
+### tasks
+
+- `pip install dwyeapi[tasks]`
+- 签名 `async def task(ctx: TaskContext, params: dict)`
+- 取消是协作式：必须 `await ctx.is_cancelled()`
+- 细节：`references/tasks-integration-guide.md`
+
+### 日志
+
+- `logger.configure()` 启动一次；`logger.close()` 在 lifespan 结束
+- `intercept_stdlib=True`（默认）接管 uvicorn / SQLAlchemy
+- 多进程必须 `enqueue=True`（默认）
+
+### 健康检查
+
+- `create_health_router()` **只**探活，**不**碰 PostgreSQL / Redis
+- readiness 业务自建并限制内网
+
+### 邮件 / Gmail
+
+- Provider：`v0/providers-email.md`
+- 规范化 / 常见域名白名单：`v0/email-canonical.md`（规范化 ≥0.9.6；白名单 / 发码校验 ≥0.10.0）