create-dwy 0.15.0 → 0.16.1

package/templates/ai-tools/rules/Docker/dwy-docker.md

@@ -1,5 +1,5 @@
 ---
-description: Docker 通用规则（镜像固定版本、容器内存上限、日志大小限制）
+description: Docker 通用规则（镜像固定版本、容器内存上限、日志大小限制、配置变更重启姿势）
 ---
 
 # Docker 通用规则
@@ -69,3 +69,54 @@ services:
         max-size: "10m"
         max-file: "3"
 ```
+
+## 三、配置变更重启姿势（env_file / environment / .env）
+
+### 根因
+
+`docker compose restart` 只重启**已存在的容器进程**，**不会重读** `env_file` / `environment` / `.env`。env 变量只在**容器创建时**注入容器配置；restart 沿用旧容器的旧环境，新 env 永远进不去。
+
+### 现象（真实踩坑）
+
+预览机改了 `.env` 的 `DOLPHINDB_FACTOR__PORT=18560`，用 `docker compose restart` 加载 → preview 容器一直拿不到新值，因子 provider 静默回退到主库 8848，功能"看起来通了"实际走错库。当时报"已验证"是错的——只验了隧道连通，没验 app 实际配置（`printenv`）。
+
+release 环境没踩坑：deploy-bg 是 build 后 `up -d`，镜像变更触发容器重建，重建时重读了 env_file。
+
+### 强制规则
+
+**改了 env_file / environment / `.env` 后，必须重建容器，不能只 restart：**
+
+```bash
+# 正确：重建容器，重读 env
+docker compose up -d --force-recreate backend
+
+# 或更精准：只重建受影响服务，不动依赖
+docker compose up -d --force-recreate --no-deps backend
+
+# 错误：restart 不重读 env，新配置永远不生效
+docker compose restart backend
+```
+
+### 判断容器是否重建的速查
+
+| 操作 | 容器是否重建 | env 是否重读 |
+|------|------------|------------|
+| `docker compose restart` | 否（仅重启进程） | **否** |
+| `docker compose up -d`（镜像无变化） | 否 | 否 |
+| `docker compose up -d`（镜像有变化） | 是 | 是 |
+| `docker compose up -d --force-recreate` | 是 | 是 |
+| `docker compose up -d --env-file .env.prod`（换了 env 文件） | 是 | 是 |
+
+### 验证清单（改 env 后必跑）
+
+```bash
+# 1. 确认容器内实际生效的 env（不是宿主机的 .env）
+docker compose exec backend printenv | grep DOLPHINDB_FACTOR__
+
+# 2. 不要只验连通性，要验 app 实际读到的配置
+#    连通=隧道通，不代表 app 配置对
+```
+
+### 一句话
+
+> 配置改了别 restart，`up -d --force-recreate`。验证别只看连通，`printenv` 看容器内真值。

package/templates/ai-tools/rules/HarmonyOS/dwy-arkts-ui-build.md

@@ -8,7 +8,13 @@ paths:
 
 # ArkUI / 工程 / 运行时 避坑
 
-`dwy-arkts-strict.md` 管语言语法层；本文件管 **ArkUI 组件、V2 状态管理、资源（图标）、工程构建、运行时容错**。
+| 文件 | 层 |
+|---|---|
+| `dwy-arkts-strict.md` | 语言语法（arkts-no-*） |
+| **本文件** | 组件 API、V2 状态、资源、工程构建、设备/运行时 |
+| `dwy-arkts-ui-design.md` | UI 设计与交互（弹层关闭、加载三态等事前约束） |
+| `dwy-harmony-pitfalls.md` | 四栏踩坑归档 |
+
 均为真机/DevEco 构建实测踩坑（编译期或运行期暴露，命令行 tsc 查不出）。
 
 ## 1. sys.symbol 图标名 ≠ SF Symbols 名，必须查鸿蒙清单逐个映射
@@ -191,3 +197,46 @@ $NODE $HVIGOR --mode module -p module=entry@default -p product=default -p pageTy
 见 `dwy-arkts-strict.md` 第 9 条（cryptoFramework 签名规格 / 公钥 DER 格式 / TCPSocket 局域网）。
 补充：手撸 HTTP/2 的 HPACK 全字面量是否被对端（如 grpc-netty）接受、华为 IAP 需 AGC 后台
 配商品 + 真机华为账号、asset/Preferences 在不同设备的可用性，均真机才能定论。
+
+## 11. assembleHap 未配 signingConfigs → unsigned.hap
+
+- **现象**：`hvigorw assembleHap` 成功但日志 `Will skip sign 'hos_hap'`，产物 `entry-default-unsigned.hap`；真机拒装。
+- **根因**：`build-profile.json5` 的 `signingConfigs` 为空。
+- **正确做法**：DevEco → Project Structure → Signing Configs 自动签名写回工程；**模拟器**可装 unsigned；**真机**必须签名。
+- **适用**：CLI / CI 打包。
+
+## 12. 本地模拟器（HVD）命令行：`-hvd` + hdc `127.0.0.1:5555`
+
+- **现象**：不知如何脱离 IDE 起模拟器、装 HAP。
+- **正确做法**：
+  - 启动：`/Applications/DevEco-Studio.app/Contents/tools/emulator/Emulator -hvd "Pura 90"`（名见 `~/.Huawei/Emulator/deployed/*.ini`）。
+  - 设备：`hdc list targets` → 常见 `127.0.0.1:5555`。
+  - 安装：`hdc -t 127.0.0.1:5555 install entry/.../entry-default-unsigned.hap`。
+  - 启动：`hdc -t 127.0.0.1:5555 shell aa start -a EntryAbility -b <bundleName>`。
+- **适用**：无 GUI / 脚本化调试。
+
+## 13. 模拟器验不了局域网 TCP / mDNS / 设备发现
+
+- **现象**：模拟器里 app 连不上局域网电视、ADB、mDNS 服务。
+- **根因**：HVD 网络多为 NAT，**不是**与电脑同 Wi-Fi 的 peer；模拟器「代理设置」只影响 HTTP 出网，**不能**桥接局域网。
+- **正确做法**：依赖局域网原始 TCP / mDNS 的链路（ADB 5555、插件 28100、无线调试配对）必须 **鸿蒙真机 + 与目标设备同 Wi-Fi**。模拟器只做 UI / 导航 / 无网逻辑。
+- **适用**：任何局域网设备调试类 app。
+
+## 14. ScanKit `generateBarcode` 在模拟器常失败
+
+- **现象**：二维码区域一直 spinner / 空白，业务 payload（如配对码数字）已生成。
+- **根因**：`@kit.ScanKit` 的 `generateBarcode.createBarcode` 在 HVD 或部分镜像不可用。
+- **正确做法**：
+  1. 调用时显式 `backgroundColor` / `pixelMapColor` / `margin`。
+  2. `catch` 后 **纯逻辑矩阵兜底**（自研或库 → `image.createPixelMap` RGBA），保证有图。
+  3. UI：仅生成中 spinner；失败出文案，禁止永久 loading（见 `dwy-arkts-ui-design.md`）。
+- **适用**：任何依赖出码展示的页面。
+
+## 文件职责（与本目录其它规则）
+
+| 文件 | 管什么 |
+|---|---|
+| `dwy-arkts-strict.md` | 语言：禁用语法、arkts-no-* |
+| `dwy-arkts-ui-build.md`（本文件） | 组件 API、状态、资源、构建、运行时/设备坑 |
+| `dwy-arkts-ui-design.md` | **UI 设计规范**（弹层/顶栏/加载态/图标语义，事前约束） |
+| `dwy-harmony-pitfalls.md` | 踩坑四栏归档（现象/根因/做法/适用），新坑先记这里再回写规范 |

package/templates/ai-tools/rules/HarmonyOS/dwy-arkts-ui-design.md

@@ -0,0 +1,139 @@
+---
+description: HarmonyOS ArkUI UI 设计与交互规范（弹层/顶栏/加载态/图标语义，事前约束，避免 bindSheet 重叠等坑）
+paths:
+  - "**/*.ets"
+---
+
+# ArkUI UI 设计规范
+
+与 `dwy-arkts-ui-build.md`（怎么编译/踩过哪些 API 坑）配套：本文件管 **长什么样、交互怎么关、加载怎么显**。
+写页面 / sheet **先按本规范搭骨架**，再写业务。踩到新 UI 坑：先记 `dwy-harmony-pitfalls.md`，再回写本文件。
+
+## 1. 分层约定
+
+| 层 | 职责 | 典型 API |
+|---|---|---|
+| 系统 chrome | 系统提供的关闭/拖拽指示 | `bindSheet` 的 `showClose`、下拉关闭 |
+| 内容顶栏 | 标题 + 业务操作 +（可选）自绘关闭 | `SheetHeader` / 自绘 `Row` |
+| 内容区 | 表单、列表、图 | 业务组件 |
+
+**硬规则：系统关闭钮与内容自绘「关弹层」× 禁止同时出现。**
+
+## 2. bindSheet 关闭策略（二选一）
+
+### 2.1 模式 A：自绘关闭（工具页 / 表单 / 顶栏有右侧操作）
+
+适用：Shell、进程、性能、调试、代理、录屏、快捷指令、设备编辑、**配对弹层**、设备信息（有「复制全部」等）。
+
+```ets
+.bindSheet(this.open, this.content(), {
+  detents: [SheetSize.LARGE],
+  backgroundColor: Palette.device,
+  showClose: false, // 必须关系统 ×
+  onDisappear: () => { this.open = false; },
+})
+
+@Builder
+content(): void {
+  FooPage({ onClose: () => { this.open = false; } })
+}
+```
+
+内容顶栏结构（从左到右）：
+
+```
+[ 标题（layoutWeight 1，单行省略） ] [ 可选业务按钮 ] [ 关闭 × ]
+```
+
+- 关闭用 `sys.symbol.xmark`，固定触控约 `36×36`，勿与分段按钮同一 `Row` 抢宽。
+- 分段 / Tab 切换放在 **顶栏下一行**，整行 `width('100%')`，不得伸进系统 chrome 区域。
+
+### 2.2 模式 B：仅系统关闭（纯浏览 / 轻列表）
+
+适用：语言选择、截图预览、无业务顶栏操作的列表。
+
+```ets
+.bindSheet(this.open, this.content(), {
+  showClose: true,
+  onDisappear: () => { this.open = false; },
+})
+```
+
+- 内容 **禁止** 再画关闭 ×。
+- 顶栏右侧 **禁止** 放会与系统 × 重叠的控件（可放在内容区下方或用「完成」文字按钮在底部）。
+
+### 2.3 禁止
+
+| 禁止 | 原因 |
+|---|---|
+| `showClose: true` + `SheetHeader` / 自绘 × | 双 × 重叠 |
+| `showClose` 省略 + 自绘 × | 默认常带系统 ×，仍重叠 |
+| 系统 × 与「新增 / 复制全部 / 分段 Tab」同一视觉行 | 贴边、难点 |
+| 关闭回调空实现（`onClose` 未注入） | × 点了无反应 |
+
+## 3. 图标语义（禁止混用）
+
+| 语义 | 推荐符号 | 禁止 |
+|---|---|---|
+| 关弹层 | `xmark`（顶栏） | 与「清空」共用同一位置无说明 |
+| 清空输入 | `xmark_circle_fill`（输入框旁） | 当成关 sheet |
+| 返回上一页 | `chevron_left`（`PageHeaderBar`） | 用 × 表示返回 |
+| 删除 | `trash` | 用 × 表示删除条目 |
+
+输入弹层（键盘）：**关 sheet 用模式 B（系统 ×）**；清空用输入框旁圆形 ×，注释写明「清空非关闭」。
+
+## 4. 加载与空态（禁止永久 spinner）
+
+异步出图 / 出列表必须三态：
+
+| 状态 | UI |
+|---|---|
+| 加载中 | `LoadingProgress`（限在固定占位区域内） |
+| 成功 | 内容（图 / 列表） |
+| 失败 | 文案说明 + 可选重试；**禁止**继续转圈 |
+
+二维码 / 图片：
+
+1. 优先系统能力（如 ScanKit）。
+2. 失败必须有 **可见兜底**（纯逻辑绘制 / 占位文案），不能空白。
+3. 占位区 **固定宽高**，避免生成前后布局跳动。
+
+## 5. 顶栏与安全区
+
+- **Push 页**：`PageHeaderBar`（返回 + 标题 + trailing），前景在安全区内。
+- **Sheet**：见 §2；全屏背景可用，主交互勿进系统手势死角。
+- 标题：`maxLines(1)` + `TextOverflow.Ellipsis`，避免长文案挤掉按钮。
+- 触控目标：主要按钮高度建议 ≥ 40；图标按钮约 36×36。
+
+## 6. 布局与间距（基线）
+
+- 页面水平 padding 统一 **16 / 20**（工具页内容区常用 16–20）。
+- 卡片圆角与描边走 **设计 token**（如 `Palette.surface2` + `hairline`），禁止业务页散落硬编码色。
+- 列表/宫格：用 `List` / `Grid` + 间距系统，不用绝对 `offset` 拼主布局。
+- 固定视觉比例控件（二维码、D-pad）可用固定边长，**外层容器仍自适应宽度**。
+
+## 7. 颜色与动效
+
+- 颜色只从 `Palette`（或项目 token）取，禁止裸 `0xFF...` 散落业务页（生成图 RGBA 缓冲区除外）。
+- 动效优先项目统一 spring / 系统默认；新增动画参数与现有 `Motion` 一致。
+- 强调色用于主按钮；关闭/次要操作用 `Palette.sub`，删除用 `Palette.red`。
+
+## 8. 文案与国际化
+
+- 所有用户可见文案走 `loc('key')` + 资源表，禁止硬编码中文/英文（调试日志除外）。
+- 新 key 至少补齐 **开发语言 + en**；其它语言可后续补。
+
+## 9. 自检清单（PR / 提交前）
+
+- [ ] 每个 `bindSheet` 已显式 `showClose: true` 或 `false`（不省略）。
+- [ ] 自绘 × 的 sheet 已 `showClose: false` 且 `onClose` 接通。
+- [ ] 系统 × 的 sheet 内容无第二颗关闭钮、右侧无抢位控件。
+- [ ] 异步区有失败态，无永久 spinner。
+- [ ] 出码/出图有 ScanKit 失败兜底（若依赖）。
+- [ ] 图标名在 `id_defined.json` 存在（见 ui-build §1）。
+- [ ] 文案全部 `loc`。
+
+## 10. 与 iOS 对照时注意
+
+- iOS `sheet` + 导航栏 toolbar 关闭 ≠ 鸿蒙默认 `showClose`；移植时 **重新选 §2 模式**，不要两端各画一套再叠系统。
+- SF Symbols 名不能直接当 `sys.symbol`（见 ui-build §1）。

package/templates/ai-tools/rules/HarmonyOS/dwy-harmony-pitfalls.md

@@ -0,0 +1,72 @@
+---
+description: 鸿蒙踩坑四栏归档（现象/根因/正确做法/适用）。事前规范见 dwy-arkts-ui-design / dwy-arkts-ui-build / dwy-arkts-strict
+paths:
+  - "**/*.ets"
+  - "**/build-profile.json5"
+---
+
+# 鸿蒙开发坑清单（归档）
+
+> **事前约束**请先读：
+>
+> | 文件 | 用途 |
+> |---|---|
+> | `dwy-arkts-strict.md` | 语言禁用语法 |
+> | `dwy-arkts-ui-build.md` | 组件 API / 构建 / 设备与运行时 |
+> | `dwy-arkts-ui-design.md` | UI 弹层/顶栏/加载态规范 |
+>
+> 本文件只记 **已踩过的坑**（四栏）。新坑：先按格式追加 → 再把「正确做法」回写到对应规范文件，避免规范与归档脱节。
+
+## 分类索引
+
+- ArkUI 弹层 / 出码
+- 工程与设备网络
+
+---
+
+## ArkUI 弹层 / 出码
+
+### bindSheet 系统 × 与内容自绘 × / 顶栏按钮重叠
+
+- **现象**：右上两颗 ×，或系统 × 与「扫码/配对码」「新增」「复制全部」贴在一起。
+- **根因**：`showClose` 与内容自绘关闭/右侧操作同区叠放。
+- **正确做法**：见 `dwy-arkts-ui-design.md` §2（二选一）；禁止省略 `showClose`。
+- **适用**：所有 `bindSheet`。
+
+### 内容区 × 是清空不是关 sheet
+
+- **现象**：键盘输入框旁 × 被当成关弹层。
+- **根因**：语义是清空输入。
+- **正确做法**：见 `dwy-arkts-ui-design.md` §3。
+- **适用**：Keyboard / 搜索。
+
+### ScanKit 二维码模拟器空白 + 永久 spinner
+
+- **现象**：配对扫码页只转圈，无码图。
+- **根因**：HVD 上 `generateBarcode` 常失败；失败 UI 仍 loading。
+- **正确做法**：见 `dwy-arkts-ui-build.md` §14 + `dwy-arkts-ui-design.md` §4（兜底出图 + 三态）。
+- **适用**：出码展示。
+
+---
+
+## 工程与设备网络
+
+### unsigned.hap 真机装不上
+
+- **现象**：CLI 打包成功，真机安装失败。
+- **根因**：未配置 `signingConfigs`。
+- **正确做法**：见 `dwy-arkts-ui-build.md` §11。
+- **适用**：真机分发。
+
+### 模拟器代理设置无法让 ADB 连局域网电视
+
+- **现象**：在 HVD「代理设置」里配代理/DNS，仍连不上 `192.168.x.x:5555`。
+- **根因**：代理只走 HTTP 出网；app 用原始 TCP；HVD 为 NAT 非 LAN peer。
+- **正确做法**：见 `dwy-arkts-ui-build.md` §13；真机同 Wi-Fi。
+- **适用**：局域网调试类产品。
+
+### HVD 命令行启停
+
+- **现象**：不会脱离 IDE 起模拟器。
+- **正确做法**：见 `dwy-arkts-ui-build.md` §12。
+- **适用**：脚本化调试。

package/templates/ai-tools/rules/Python/dwy-python-backend.md

@@ -10,52 +10,6 @@ paths:
 
 ---
 
-## 零、优先使用 `dwyeapi` 基础框架库（强制）
-
-`dwyeapi` 是团队内部 PyPI 基础设施包，已封装后端项目所需的通用能力。**凡是 dwyeapi 已提供的能力，禁止自行实现，也禁止引入其他库重复造轮子。**
-
-### 必须复用 dwyeapi 的能力域
-
-| 能力域 | 内容 |
-|--------|------|
-| 配置管理 | 应用 Settings 基类、运行环境识别（dev / prod） |
-| 异常体系 | 业务异常基类与全局异常处理器注册 |
-| 统一响应 | `{ code, message, data, timestamp }` 包装 |
-| 分页 | 分页查询参数模型与分页响应封装 |
-| 数据库 | ORM 声明式基类、时间戳 Mixin、异步引擎与会话工厂 |
-| 依赖注入 | FastAPI `get_db` 工厂 |
-| 安全 | 密码哈希、JWT 创建与解码 |
-| 缓存 | 共享异步 Redis 客户端 |
-| 时间 | 业务时间统一入口（Asia/Shanghai） |
-| 脱敏 | PII 数据脱敏函数 |
-| 日志 | 全局日志配置与门面 |
-| 健康检查 | 健康检查路由工厂 |
-| 异步任务 | 耗时任务队列与上下文 |
-| 邮件 | 邮件验证码可插拔通道 |
-
-### 查阅方式（关键）
-
-**在编写任何后端代码前，以及调用任何 dwyeapi 提供的 API 之前，必须先用 `Skill` 工具加载 `dwy-eapi` skill 查阅当前最新接口。** 本文件**只规定约束与边界**，**不固化** dwyeapi 的具体模块路径、类名、函数签名、参数 —— 这些会随版本演进，固化在 rules 里会与实际包不同步。
-
-```
-Skill 工具调用：skill="dwy-eapi"
-```
-
-### 强制规则
-
-- 涉及上表任一能力域，**先查 skill 拿到当前 API，再写代码**
-- **禁止**自造异常基类，必须复用 dwyeapi 异常体系
-- **禁止**手写 bcrypt / PyJWT 调用，必须走 dwyeapi 安全模块
-- **禁止**自定义统一响应包装函数，必须用 dwyeapi 响应模块
-- **禁止**自定义分页模型，必须用 dwyeapi 分页模块
-- **禁止**自定义 `DeclarativeBase`，模型必须继承 dwyeapi 提供的基类
-- **禁止**在路由函数中直接创建数据库会话，必须用 dwyeapi 依赖工厂
-- **禁止**自建 Redis 连接池，必须用 dwyeapi 共享客户端
-- **禁止**在业务代码中直接使用 `datetime.now()`，必须用 dwyeapi 时间模块
-- **禁止**自行 `logging.basicConfig`，必须用 dwyeapi 日志模块
-
----
-
 ## 一、项目结构与业务聚合（强制）
 
 ### 核心原则
@@ -103,7 +57,7 @@ app/
 - 测试镜像功能聚合结构：`tests/users/test_router.py` / `tests/users/test_service.py`（详见第九节）
 
 ### 例外
-- 通用基础设施代码（如 dwyeapi 内部）可保持技术层结构
+- 通用基础设施代码（如基础框架库内部）可保持技术层结构
 
 ---
 
@@ -167,11 +121,11 @@ async def create_user(
 
 ### 统一响应格式
 
-所有成功 / 分页 / 错误响应统一走 dwyeapi 响应与异常模块（具体 API 与字段结构查 `dwy-eapi` skill），**禁止**自造响应包装函数，**禁止**在 router 中手动构造 `{"success": true, ...}` 等非标准格式。
+所有成功 / 分页 / 错误响应统一走项目级响应与异常模块，**禁止**自造响应包装函数，**禁止**在 router 中手动构造 `{"success": true, ...}` 等非标准格式。
 
 ### 分页
 
-分页参数模型与响应包装统一走 dwyeapi（具体 API 查 `dwy-eapi` skill），**禁止**自定义。
+分页参数模型与响应包装统一走项目级分页模块，**禁止**自定义。
 
 ---
 
@@ -234,7 +188,7 @@ class UserResponse(UserBase):
 
 - 数据库会话、当前用户、配置等**必须**通过 `Depends()` 注入
 - **禁止**在路由函数中直接创建数据库会话或实例化 service
-- `get_db` 依赖必须用 dwyeapi 提供的工厂生成（具体 API 查 `dwy-eapi` skill）
+- `get_db` 依赖必须用项目级工厂生成，**禁止**每个路由各自创建
 
 ```python
 # 反例：路由中直接创建会话
@@ -258,8 +212,8 @@ async def get_user(
 
 ### 强制规则
 
-- **必须**复用 dwyeapi 异常体系与全局处理器（具体异常类与注册方法查 `dwy-eapi` skill），**禁止**自造异常基类
-- 项目级扩展异常必须继承 dwyeapi 异常基类
+- **必须**复用项目级异常体系与全局处理器，**禁止**自造异常基类
+- 项目级扩展异常必须继承统一异常基类
 - **service 层**抛业务异常，**禁止**抛 `HTTPException`（service 不感知 HTTP）
 - **router 层**不写 `try / except`，由全局 handler 统一处理
 - **禁止**裸 `except:` 或 `except Exception: pass`
@@ -273,7 +227,7 @@ async def get_user(
 ### 强制规则
 
 - 必须使用 **SQLAlchemy 2.0** 声明式映射 + async
-- 模型继承 dwyeapi 提供的声明式基类与时间戳 Mixin（具体类名查 `dwy-eapi` skill），**禁止**自定义 `DeclarativeBase`
+- 模型继承项目级统一声明式基类与时间戳 Mixin，**禁止**每个模型各自定义 `DeclarativeBase`
 - 数据库迁移使用 **Alembic**，**禁止**手动执行 DDL
 - **禁止**在路由层直接写 SQL 查询
 - **禁止**使用 SQLAlchemy 1.x 风格的 `session.query(...)`
@@ -283,7 +237,7 @@ from sqlalchemy.orm import Mapped, mapped_column
 from sqlalchemy import String
 import uuid as uuid_lib
 
-class User(BaseFromDwyeapi, TimestampMixinFromDwyeapi):  # 实际基类名以 skill 为准
+class User(Base, TimestampMixin):  # 项目级统一基类与时间戳 Mixin
     __tablename__ = "users"
 
     id: Mapped[int] = mapped_column(primary_key=True)
@@ -328,10 +282,10 @@ user = result.scalar_one_or_none()
 
 | 规则 | 说明 |
 |------|------|
-| 存储算法 | **只允许 bcrypt**，必须走 dwyeapi 安全模块，**禁止**手写 bcrypt 调用或使用 MD5 / SHA / 明文 |
+| 存储算法 | **只允许 bcrypt**，必须走项目级统一安全模块，**禁止**散落手写 bcrypt 调用或使用 MD5 / SHA / 明文 |
 | 接口返回 | **永远不返回**密码字段，Response Schema 中不包含 |
 | 密码强度 | **长度 ≥ 8 字符**，且**必须**包含 **大写字母、小写字母、数字、特殊符号** 中的至少 **3 类** |
-| 密码长度上限 | Schema 必须 `max_length=72`（bcrypt 输入硬上限，超过会被静默截断），除非 dwyeapi 已做 SHA-256 预哈希 |
+| 密码长度上限 | Schema 必须 `max_length=72`（bcrypt 输入硬上限，超过会被静默截断），除非安全模块已做 SHA-256 预哈希 |
 | 登录错误 | 返回"用户名或密码错误"，**不区分**是用户名不存在还是密码错误 |
 | 强度校验位置 | Pydantic Schema 层用 `field_validator` 校验复杂度，**禁止**只校长度 |
 
@@ -361,12 +315,12 @@ class UserCreate(BaseModel):
         return v
 ```
 
-> 该 validator 建议下沉到 dwyeapi 提供统一的 `PasswordStr` 类型，避免每个项目重复实现。
+> 该 validator 建议下沉为项目级统一的 `PasswordStr` 类型，避免每个模块重复实现。
 
 ### 7.3 接口认证与授权
 
 - 所有 API **必须** JWT 认证（白名单除外：`/health` / `/auth/login` / `/auth/register`）
-- JWT 创建与解码**必须**走 dwyeapi 安全模块，**禁止**直接调用 PyJWT
+- JWT 创建与解码**必须**走项目级统一安全模块，**禁止**散落直接调用 PyJWT
 - Token 黑名单存 Redis（登出后失效，TTL = 剩余有效期）
 - Secret Key 必须从环境变量读取，**禁止**硬编码
 - Secret Key 长度与生成方式（按字节算，不按字符算）：
@@ -389,7 +343,7 @@ class UserCreate(BaseModel):
 
 - **禁止**直接返回 ORM 对象（可能暴露 password、内部 ID 等）
 - 列表接口**必须**分页，**禁止**返回全量数据
-- PII 字段（手机号 / 邮箱 / 身份证 / 银行卡 / 姓名 / 地址 / IP / 车牌）必须使用 dwyeapi 脱敏函数处理
+- PII 字段（手机号 / 邮箱 / 身份证 / 银行卡 / 姓名 / 地址 / IP / 车牌）必须使用项目级统一脱敏函数处理
 
 ### 7.5 错误处理安全
 
@@ -449,7 +403,7 @@ file_path = Path("/uploads") / safe_name
 
 ### 7.8 审计日志
 
-通过 dwyeapi 日志模块获取审计 logger，记录以下操作：
+通过项目级统一日志模块获取审计 logger，记录以下操作：
 
 | 操作 | 记录内容 |
 |------|---------|
@@ -510,8 +464,7 @@ AI 编写或审查后端代码时，**必须**检查以下违规模式，按严
 
 | 检查项 | 违规模式 | 严重程度 |
 |--------|---------|---------|
-| 重复造轮子 | 自造异常基类 / 自封装统一响应 / 手写 bcrypt 或 JWT 调用 / 自建 Redis 连接池 等 dwyeapi 已提供能力 | 高 |
-| 未查 skill | 调用 dwyeapi 能力域却未先查 `dwy-eapi` skill 拿当前 API | 高 |
+| 重复造轮子 | 自造异常基类 / 自封装统一响应 / 散落手写 bcrypt 或 JWT 调用 / 自建 Redis 连接池 等本应走项目级统一模块的能力 | 高 |
 | 技术层散落 | 顶级出现 `routers/` / `services/` / `models/` / `schemas/` 等技术层目录把不同功能文件混放，未按功能聚合 | 高 |
 | 测试与源码混放 | 测试文件放在源码目录中（如 `app/users/test_router.py`），未独立到测试目录 | 高 |
 | 密码明文 | `password` 字段出现在 Response Schema | **致命 → STOP** |
@@ -528,5 +481,5 @@ AI 编写或审查后端代码时，**必须**检查以下违规模式，按严
 | service 抛 HTTPException | service 层直接 `raise HTTPException` | 高 |
 | 路由中开会话 | 路由函数中 `async with session_factory()` | 高 |
 | 旧式查询 | `session.query(...)` 而非 `select(...)` | 高 |
-| `datetime.now()` 直用 | 业务代码直接 `datetime.now()` 而非走 dwyeapi 时间模块 | 高 |
+| `datetime.now()` 直用 | 业务代码直接 `datetime.now()` 而非走项目级统一时间模块 | 高 |
 | 物理删除业务数据 | 对业务数据执行物理删除 | 中 |

package/templates/ai-tools/rules/Python/dwy-python-base-lib.md

@@ -0,0 +1,89 @@
+---
+description: 团队内部 dwyeapi 基础框架库强制复用规范（配置 / 异常 / 响应 / 分页 / ORM / 安全 / 缓存 / 时间 / 脱敏 / 日志：禁重复造轮子）
+paths:
+  - "**/*.py"
+---
+
+# Python 后端 dwyeapi 基础库强制复用规范
+
+`dwy-python-backend` rule 的团队内补充。通用 FastAPI / SQLAlchemy / 安全编码规范见 `dwy-python-backend`；本文件只管「凡 dwyeapi 已提供的能力，禁止自行实现，也禁止引入其他库重复造轮子」。
+
+`dwyeapi` 是团队内部 PyPI 基础设施包，已封装后端项目所需的通用能力。
+
+---
+
+## 一、必须复用 dwyeapi 的能力域
+
+| 能力域 | 内容 |
+|--------|------|
+| 配置管理 | 应用 Settings 基类、运行环境识别（dev / prod） |
+| 异常体系 | 业务异常基类与全局异常处理器注册 |
+| 统一响应 | `{ code, message, data, timestamp }` 包装 |
+| 分页 | 分页查询参数模型与分页响应封装 |
+| 数据库 | ORM 声明式基类、时间戳 Mixin、异步引擎与会话工厂 |
+| 依赖注入 | FastAPI `get_db` 工厂 |
+| 安全 | 密码哈希、JWT 创建与解码 |
+| 缓存 | 共享异步 Redis 客户端 |
+| 时间 | 业务时间统一入口（Asia/Shanghai） |
+| 脱敏 | PII 数据脱敏函数 |
+| 日志 | 全局日志配置与门面 |
+| 健康检查 | 健康检查路由工厂 |
+| 异步任务 | 耗时任务队列与上下文 |
+| 邮件 | 邮件验证码可插拔通道 |
+
+### 查阅方式（关键）
+
+**在编写任何后端代码前，以及调用任何 dwyeapi 提供的 API 之前，必须先用 `Skill` 工具加载 `dwy-eapi` skill 查阅当前最新接口。** 本文件**只规定约束与边界**，**不固化** dwyeapi 的具体模块路径、类名、函数签名、参数 —— 这些会随版本演进，固化在 rules 里会与实际包不同步。
+
+```
+Skill 工具调用：skill="dwy-eapi"
+```
+
+---
+
+## 二、强制规则
+
+- 涉及上表任一能力域，**先查 skill 拿到当前 API，再写代码**
+- **禁止**自造异常基类，必须复用 dwyeapi 异常体系
+- **禁止**手写 bcrypt / PyJWT 调用，必须走 dwyeapi 安全模块
+- **禁止**自定义统一响应包装函数，必须用 dwyeapi 响应模块
+- **禁止**自定义分页模型，必须用 dwyeapi 分页模块
+- **禁止**自定义 `DeclarativeBase`，模型必须继承 dwyeapi 提供的基类
+- **禁止**在路由函数中直接创建数据库会话，必须用 dwyeapi 依赖工厂
+- **禁止**自建 Redis 连接池，必须用 dwyeapi 共享客户端
+- **禁止**在业务代码中直接使用 `datetime.now()`，必须用 dwyeapi 时间模块
+- **禁止**自行 `logging.basicConfig`，必须用 dwyeapi 日志模块
+
+---
+
+## 三、各能力域 dwyeapi 落点
+
+通用规范（路由 / Schema / ORM / 安全编码本身的要求）见 `dwy-python-backend` 对应章节；本节只说明这些规范在团队项目里**必须落到哪个 dwyeapi 模块**。
+
+| 能力 | 团队项目落点 | 对应通用规范 |
+|------|-------------|-------------|
+| 统一响应 / 异常 | dwyeapi 响应模块 + 异常体系（禁自造） | backend 二、五 |
+| 分页 | dwyeapi 分页模块（禁自定义） | backend 二 |
+| ORM 基类 / 时间戳 | 继承 dwyeapi 声明式基类与 Mixin | backend 六 |
+| `get_db` 依赖 | dwyeapi 依赖工厂 | backend 四 |
+| 密码哈希 | dwyeapi 安全模块（bcrypt，禁手写） | backend 7.2 |
+| JWT 创建 / 解码 | dwyeapi 安全模块（禁直接 PyJWT） | backend 7.3 |
+| PII 脱敏 | dwyeapi 脱敏函数 | backend 7.4 |
+| 审计日志 | dwyeapi 日志模块获取审计 logger | backend 7.8 |
+| 业务时间 | dwyeapi 时间模块（禁裸 `datetime.now()`） | backend 六 / 七 |
+| Redis 缓存 | dwyeapi 共享客户端（禁自建连接池） | backend 八 |
+
+> 密码复杂度校验建议下沉到 dwyeapi 提供统一的 `PasswordStr` 类型，避免每个项目重复实现。
+
+---
+
+## 四、违规检测清单（dwyeapi 相关）
+
+通用后端违规清单见 `dwy-python-backend` 第十节；涉及 dwyeapi 必须额外检查：
+
+| 检查项 | 违规模式 | 严重程度 |
+|--------|---------|---------|
+| 重复造轮子 | 自造异常基类 / 自封装统一响应 / 手写 bcrypt 或 JWT 调用 / 自建 Redis 连接池 等 dwyeapi 已提供能力 | 高 |
+| 未查 skill | 调用 dwyeapi 能力域却未先查 `dwy-eapi` skill 拿当前 API | 高 |
+| 密码弱存储 | 使用 MD5 / SHA 而非 dwyeapi 安全模块的 bcrypt | **致命 → STOP** |
+| `datetime.now()` 直用 | 业务代码直接 `datetime.now()` 而非走 dwyeapi 时间模块 | 高 |

package/templates/ai-tools/rules/Python/dwy-python-pitfalls.md

@@ -0,0 +1,49 @@
+---
+description: Python 后端开发避坑清单（FastAPI / SQLAlchemy / async / 依赖 / 部署踩坑），按分类持续追加
+paths:
+  - "**/*.py"
+  - "**/pyproject.toml"
+  - "**/uv.lock"
+---
+
+# Python 开发坑清单
+
+> 动手前先对照本清单避开已知坑；踩到新坑随手按四栏格式（现象 / 根因 / 正确做法 / 适用）追加到对应分类，没有合适分类就新建一个。
+>
+> 通用开发规范见 `dwy-python-core` / `dwy-python-backend` rule，本文件只记**非显而易见的实战坑**。
+
+## 分类索引
+
+- 依赖与环境（uv / venv / 版本）
+- async / 并发（事件循环、阻塞调用、连接池）
+- FastAPI / Pydantic（路由、Schema、校验、序列化）
+- SQLAlchemy / ORM（异步 session、懒加载、事务）
+- 部署与运行时（打包、环境变量、进程模型）
+- 排查方法论
+- 其他分类遇到再加
+
+---
+
+## 依赖与环境
+
+<!-- 待填：踩到坑按四栏格式追加 -->
+
+## async / 并发
+
+<!-- 待填 -->
+
+## FastAPI / Pydantic
+
+<!-- 待填 -->
+
+## SQLAlchemy / ORM
+
+<!-- 待填 -->
+
+## 部署与运行时
+
+<!-- 待填 -->
+
+## 排查方法论
+
+<!-- 待填 -->