shenjicore 0.6.4__tar.gz

shenjicore-0.6.4/.claude/skills/shenjicore/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: shenjicore
+description: "Use when writing or refactoring business code in a shenjicore project — creating or editing action/domain/dao/schema/common files, adding a new resource, or organizing business logic (imports, layering, service classes). Enforces the layered skeleton: one resource = one file = one namespace class, @classmethod static calls, single-class imports (no function zoos, no scattered exports), one-way dependencies, thin-shell actions, no mutable class state. Also governs plugin usage: auth/rbac/audit, redis cache-lock-rate-limit-queue, mysql/minio/file/scheduler/hikvision — use official plugins instead of reinventing (see references/plugins.md). 在 shenjicore 业务项目中写/改 action、domain、dao、schema 文件前必读本 skill。"
+---
+
+# shenjicore 业务代码组织
+
+## 何时使用
+
+- 创建或修改 `action/`、`domain/`、`dao/`、`schema/`、`common/` 任何文件。
+- 设计新资源的业务结构（接口、分层、导入方式）。
+- review 或重构业务模块（函数扎堆、导出遍布、反向依赖、SQL 上移）。
+- 用户问"业务逻辑应该放哪层 / 怎么组织"这类问题。
+
+## 核心规则（必须遵守）
+
+1. **一资源 = 一文件 = 一命名空间类**：`domain/user.py` 一个 `UserDomain`，
+   `dao/user.py` 一个 `UserDao(BaseDao)`；方法全 `@classmethod` 静态直调。
+2. **导入只到类名**：`from domain.user import UserDomain`。
+   禁止函数级导入（`from domain.user import add, update, ...`）、禁止跨层重新导出。
+3. **依赖单向**：`action → domain → dao`；`schema/common` 可被各层引用；
+   dao 不得 import domain/action。
+4. **action 是薄壳**：端点函数体无 if/for/while/raise，只收参 → `await XxxDomain.xxx()` → `ok()/page()`。
+5. **类 = 纯命名空间**：类内禁止可变状态；SQL 只在 dao（继承 `BaseDao`，
+   表名用 `cls.TABLE`，参数化）；错误码只在 `common/errors.py` 集中登记。
+6. **分层靠测试守护**：AST 薄壳断言 + fake dao 注入（模式抄 `examples/your_project/tests/`）。
+7. **有插件用插件，禁止重造轮子**：业务需求先对照插件总览（见下），
+   能用 `shenjicore.plugins.*` 的绝不手写——认证/授权/审计、缓存/锁/限流、
+   MySQL/对象存储/文件/定时/海康/对外 HTTP 调用（httpclient），官方插件都齐了。
+
+## 用插件，别重造轮子（写任何业务代码前先查）
+
+遇到以下需求 → 先想插件，详见 **`references/plugins.md`**（完整用法速查）：
+
+| 需求 | 插件 | 入口 |
+|---|---|---|
+| 登录/令牌/受保护路由 | `auth` | `login()` / `require_access_token` / `get_principal` |
+| 密码哈希 | `auth` | `hash_password` / `verify_password` |
+| 路由权限判定 | `rbac` | `require_permission` / `require_any_permission` |
+| 合规留痕 | `audit` | `@audit("...")` / `add_detail` / `audit_record` |
+| 缓存 / 分布式锁 / 限流 | `redis` | `cache_*` / `lock` / `try_lock` / `rate_limit_raise` |
+| 异步任务队列 | `redis` | `enqueue` / `run_worker`（任务须幂等） |
+| 任务平台（管控/进度/两阶段取消/重跑/归档） | `tasks` | `create_task` / `register_handler` / `run_task_worker` / `cancel_task`（v0.6.0+） |
+| 定时任务 | `scheduler` | `@cron` / `@interval_job`（只保证触发，业务自行入队） |
+| MySQL 数据访问 | `mysql` | `BaseDao` / `transaction()` / `QueryBuilder`；敏感字段 `encrypt_value` |
+| 文件上传/下载/导出 | `file` | `save_bytes` / `read_bytes` / `export_csv` / `make_router` |
+| 大文件直传对象存储（绕过服务器带宽） | `file`（minio 后端） | `create_direct_upload` → PUT put_url → `complete_direct_upload` |
+| 对象存储 | `minio` | `upload_bytes` / `presigned_get_url` / `ensure_bucket` |
+| 海康 NVR | `hikvision` | `get_snapshot` / `live_rtsp_url` / `VideoStream` |
+| 调用外部 HTTP API（推理/第三方） | `httpclient` | `request` / `get` / `post`（超时+重试） |
+
+反例自查：自己写 JWT、手拼 Redis 锁、循环 sleep 当定时、自造文件下载接口
+……都是重造轮子。插件配置项在 `common/config.py` 的 Settings 子类声明字段
+（类型契约），值写 `.env`；启用方式 `PLUGINS=[...]` 或 `create_app(plugins=[...])`。
+安全域三段式注册顺序：**auth → rbac → audit**。
+
+## 参考资料（按需加载，先看对应章节再动笔）
+
+- **`references/CONVENTIONS.md`** — 完整框架规范：命名约定、REST 方法、响应信封、
+  错误码段位、路由注册。写任何代码前查对应章节；与规范冲突以它为准。
+- **`references/plugins.md`** — 官方插件总览与用法速查：场景触发总表、每插件
+  配置/典型调用/要点、组合示例、反模式。涉及认证授权审计、缓存锁限流队列、
+  MySQL/文件/MinIO/海康/定时时必查。
+- **`references/layering.md`** — 分层细节：设计裁决（为何类命名空间而非函数扎堆/DI）、
+  每行代码放哪层的判定表、导入/状态硬规则、测试守护写法、反模式清单、DI 升级边界。
+- **`examples/your_project/`** — 可运行完整骨架（四层 + tests + README）。
+  写对应文件前先照抄其风格；测试守护直接复用。
+
+## 测试防 OOM（打穿内存必检项）
+
+**教训（2026-08-31 实证）**：回归测试传 `part_count=10**9`，`complete_upload` 物化
+`list(range(1, part_count+1))` ≈ 8GB → 测试进程 11.6GB RSS → 12GB WSL VM OOM →
+**整个 WSL 崩溃**（Windows 报"灾难性故障 Wsl/Service/E_UNEXPECTED"）。这不是测试
+失败，是环境被打穿；journal 只留一行 `Killed process (python) anon-rss:11.6GB`，
+错误表象是 dmesg 的 p9io 次生故障。**先查有没有物化点，再跑测试。**
+
+**写/改测试后、跑全量前，逐条过（命中即修）**：
+
+1. **物化超大容器**：`list(range(1, n+1))`、推导式/`.extend` 构造 ≥1e6 序列、
+   整文件 `read()`、分页全量攒列表——改惰性（迭代器/生成器；顺序完整性判定用
+   `len + 首尾`，不物化全表）。
+2. **业务硬限制不绕过**：S3 分片 ≤10000、导出 `max_rows`、`rows_per_file`、
+   Redis ttl——插件闸门本身要测，但**别在闸门内构造会物化的超大输入**（极端值
+   用例应选闸门边界内侧，如 2MB 分片 + 11GB → 5632 片，而不是 10007 片）。
+3. **超大字符串/字节**：`"x" * 1e9`、`b"\0" * 8e9`、超长 SQL/JSON 拼接。
+4. **递归/迭代失控**：无界递归、断言前不截断的无限迭代器、死循环兜底。
+
+**验证**：全量测试用 `/usr/bin/time -v pytest ...` 跑，读 `Maximum resident set
+size`——**>1GB 即停手排查**（本仓库基线 ~300MB）；疑似泄漏先 `ulimit -v <6G>` 限
+内存复现（malloc 失败进程自杀，VM 不死），别裸跑把 VM 打崩。
+
+## 完成自检（写完代码逐条过）
+
+1. 新资源四层各就各位，类名即命名空间，方法全 `@classmethod`？
+2. 导入只到类名一级？无函数级导入、无跨层导出、无深导入插件内部？
+3. action 端点体零控制流、只收参转发 + `ok()/page()`？
+4. domain 无 SQL、无魔法错误码、类内无可变状态；事务用 `transaction()`？
+5. dao 继承 `BaseDao`、SQL 参数化、表名 `cls.TABLE`？
+6. 错误码已在 `common/errors.py` 登记段位？
+7. 测试补齐：薄壳 AST 断言 + 关键 domain 业务（fake dao 注入）？
+8. 需求命中插件场景了吗？用的官方插件 API 而不是手写轮子；插件配置项
+   已在 Settings 声明 + .env 配置？（速查 `references/plugins.md`）
+9. **测试无 OOM 风险**：无 ≥1e6 级容器/字符串物化、无绕过插件闸门的极端输入；
+   全量跑前过一遍「测试防 OOM」清单？（验证命令：`/usr/bin/time -v pytest`，
+   峰值 RSS >1GB 即排查）
+
+## 分发到业务项目
+
+本 skill 自包含（规范 + 骨架都在目录内），业务项目整目录复制即可：
+
+```bash
+cp -r <shenjicore 路径>/.claude/skills/shenjicore <业务项目>/.claude/skills/
+```

shenjicore-0.6.4/.claude/skills/shenjicore/examples/your_project/.env.example

@@ -0,0 +1,34 @@
+# 复制为 .env 并填写（.env 不进版本库）
+APP_NAME=your_project
+API_PREFIX=/api
+LOG_LEVEL=info
+
+# mysql 插件必需
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_USER=root
+DB_PASSWORD=123456
+DB_DATABASE=your_project
+
+# mysql cipher 主密钥（base64 32 字节；不填则演示加密接口报 1022）
+# 生成: python -c "import base64,os; print(base64.b64encode(os.urandom(32)).decode())"
+# MYSQL_CIPHER_KEY=
+
+# ---- Auth 插件（启用 shenjicore.plugins.auth 时必填）----
+# JWT 签名密钥：≥32 字符随机串。生成随机密钥（把输出粘贴到下面）：
+#   python -c "import secrets; print(secrets.token_hex(32))"
+# AUTH_JWT_SECRET=<上一条命令的输出>
+# AUTH_ACCESS_TTL=1800
+# AUTH_REFRESH_TTL=604800
+# AUTH_TOKEN_STORE=memory
+# Redis 模式必填：
+# AUTH_REDIS_URL=redis://127.0.0.1:6379/0
+
+# 建表（示例表）:
+# CREATE TABLE user (
+#   id INT AUTO_INCREMENT PRIMARY KEY,
+#   name VARCHAR(50) NOT NULL,
+#   student_no VARCHAR(20) NOT NULL UNIQUE,
+#   password VARCHAR(200) NOT NULL,
+#   created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+# ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

shenjicore-0.6.4/.claude/skills/shenjicore/examples/your_project/README.md

@@ -0,0 +1,53 @@
+# your_project —— 分层示例（action / domain / dao / schema）
+
+**这是 shenjicore 推荐的业务分层骨架**：action 只做壳、业务全在
+domain、数据在 dao、参数在 schema。业务项目复制本目录即得正确分层。
+
+## 结构
+
+```
+your_project/
+  action/user.py     路由壳：收参 → await UserDomain.add(body) → ok()/page()
+  domain/user.py     业务：校验规则、参数组装、调 dao、结果翻译（全 @classmethod）
+  dao/user.py        数据：class UserDao(BaseDao) + TABLE 常量（免传表名）
+  schema/user.py     入参/出参（Pydantic，命名约定见 CONVENTIONS §4）
+  common/            业务错误码（集中定义）+ Settings（插件配置字段）
+  main.py            组装：create_app(settings, plugins=[MysqlPlugin()])
+  .env.example       配置样例（.env 不进版本库）
+  tests/             分层正确性守护：fake dao 注入 domain + 路由全链
+```
+
+## 三个核心约定
+
+1. **静态直调，无需实例化**：dao/domain 全 `@classmethod`——
+   `await UserDao.insert(...)` / `await UserDomain.add(body)`。
+2. **事务不传 session**：`async with transaction():` 上下文自动感知
+   事务（dao 方法零会话参数，事务内外行为一致）——见 `UserDomain.batch_create`。
+3. **action 禁止业务逻辑**：无校验/循环/条件分支/SQL；review 时
+   action 一眼看完接口做什么，细节进 domain。
+
+## 运行
+
+```bash
+cp .env.example .env   # 填写 DB_*（建表 SQL 在 .env.example 注释里）
+python -m uvicorn main:app --reload
+```
+
+接口（前缀 /api/user）：`POST /add`、`POST /batch`（事务演示）、
+`POST /update`、`POST /delete`、`GET /page?keyword=&page=&page_size=`。
+
+敏感字段演示：`UserDomain.add` 落库前用 mysql cipher 加密 password
+（`encrypt_value(data, context="user:login")`），出参永不外泄密文；
+`UserDomain.get_password` 展示解密（context 必须一致）。不配
+`MYSQL_CIPHER_KEY` 时相关接口报 1022（懒校验，其余接口不受影响）。
+
+## 测试
+
+```bash
+cd examples/your_project
+python -m pytest tests/ -q        # 无需 MySQL：domain 注入 fake dao
+```
+
+测试守护三件事：action 薄壳（AST 断言无控制流语句）、domain 业务
+（fake dao 注入，含密码加密与去重冲突）、路由全链（TestClient + 注入
+fake domain，无需真实数据库）。

shenjicore-0.6.4/.claude/skills/shenjicore/examples/your_project/action/user.py

@@ -0,0 +1,42 @@
+"""路由壳：收参 → 调 domain → 统一响应。**不写业务逻辑**。
+
+业务逻辑（校验/循环/条件分支/SQL）一律在 domain 层——action 只做
+转发，review 时一眼看出每个接口做什么。
+"""
+
+from domain.user import UserDomain
+from schema.user import UserBatchCreate, UserCreate, UserDelete, UserQuery, UserUpdate
+
+from shenjicore import APIRouter, ok, page
+
+router = APIRouter()
+
+
+@router.post("/add")
+async def add(body: UserCreate):
+    user_id = await UserDomain.add(body)
+    return ok(message="添加成功", data={"id": user_id})
+
+
+@router.post("/batch")
+async def batch_add(body: UserBatchCreate):
+    total = await UserDomain.batch_create(body)
+    return ok(message=f"批量创建 {total} 个用户", data={"total": total})
+
+
+@router.post("/update")
+async def update(body: UserUpdate):
+    await UserDomain.update(body)
+    return ok(message="更新成功")
+
+
+@router.post("/delete")
+async def delete(body: UserDelete):
+    await UserDomain.delete(body.id)
+    return ok(message="删除成功")
+
+
+@router.get("/page")
+async def page_users(query: UserQuery):
+    items, total = await UserDomain.page(query)
+    return page(items=items, total=total, page=query.page, page_size=query.page_size)

shenjicore-0.6.4/.claude/skills/shenjicore/examples/your_project/common/config.py

@@ -0,0 +1,15 @@
+"""项目配置：继承 ShenSettings（自动读 .env），插件需要的配置项声明字段。"""
+
+from shenjicore import ShenSettings
+
+
+class Settings(ShenSettings):
+    # mysql 插件必需配置（值写 .env，见 .env.example）
+    db_host: str
+    db_port: int
+    db_user: str
+    db_password: str
+    db_database: str
+
+    # mysql cipher 主密钥（base64 32 字节；可选——示例演示敏感字段加解密）
+    mysql_cipher_key: str | None = None

shenjicore-0.6.4/.claude/skills/shenjicore/examples/your_project/common/errors.py

@@ -0,0 +1,9 @@
+"""业务错误码：集中在 common/errors.py 定义（禁止散落各处、禁止魔法数字）。
+
+段位登记：本示例从 20000 起分配（每业务模块一段，每段 100 个）。
+"""
+
+from shenjicore import ErrorSpec
+
+USER_CONFLICT = ErrorSpec(20010, "用户已存在", http_status=409)
+USER_NOT_FOUND = ErrorSpec(20011, "用户不存在", http_status=404)

shenjicore-0.6.4/.claude/skills/shenjicore/examples/your_project/dao/user.py

@@ -0,0 +1,34 @@
+"""数据访问层：只做数据访问，不写业务规则。
+
+继承 BaseDao + TABLE 常量即可免传表名；全部 @classmethod 静态直调
+（类名即命名空间，无需实例化）。专属查询加在此层（方法内可写参数化
+SQL——BaseDao.query_one/execute 是唯一允许裸 SQL 的通道）。
+"""
+
+from shenjicore.plugins.mysql import BaseDao
+
+
+class UserDao(BaseDao):
+    TABLE = "user"
+
+    @classmethod
+    async def find_by_student_no(cls, student_no: str) -> dict | None:
+        """按学号查（业务去重/校验用；防注入参数化）。"""
+        return await cls.query_one(
+            "SELECT id, name, student_no FROM user WHERE student_no = %s",
+            (student_no,),
+        )
+
+    @classmethod
+    async def page_by_keyword(
+        cls, keyword: str | None, page: int, page_size: int
+    ) -> tuple[list[dict], int]:
+        """关键词分页（模糊查询示例；多表关联用 BaseDao.query() QueryBuilder）。"""
+        if keyword:
+            where = {"name__like": f"%{keyword}%"}
+        else:
+            where = None
+        return await cls.query_page(
+            where, select_cols="id, name, student_no", order_by="id DESC",
+            page=page, page_size=page_size,
+        )

shenjicore-0.6.4/.claude/skills/shenjicore/examples/your_project/domain/user.py

@@ -0,0 +1,76 @@
+"""业务层：业务逻辑的家（参数组装、校验规则、调 dao、结果翻译）。
+
+- 全部 @classmethod 静态直调：action 里 `await UserDomain.add(body)`。
+- **不写 SQL**（SQL 在 dao 层）；多语句原子性用 `transaction()` 上下文
+  （dao 方法零会话参数——事务内自动复用事务连接、事务外即写即生效）。
+- 业务错误码在这里抛（dao 层自动翻译底层错误如唯一键冲突 → 1011）。
+"""
+
+from common.errors import USER_CONFLICT, USER_NOT_FOUND
+from dao.user import UserDao
+from schema.user import UserBatchCreate, UserCreate, UserUpdate
+
+from shenjicore.plugins.mysql import transaction
+from shenjicore.plugins.mysql.cipher import decrypt_value, encrypt_value
+
+
+class UserDomain:
+    """用户业务：所有方法静态直调（类名即命名空间）。"""
+
+    @classmethod
+    async def add(cls, body: UserCreate) -> int:
+        """新增：学号去重 → 密码静态加密落库（cipher 演示）。"""
+        if await UserDao.find_by_student_no(body.student_no):
+            raise USER_CONFLICT.with_detail(f"学号已存在: {body.student_no}")
+        data = body.model_dump()
+        # context 绑定用途，防跨用途解密；密钥只存 .env 不进库
+        data["password"] = encrypt_value(data["password"], context="user:login")
+        return await UserDao.insert(data)
+
+    @classmethod
+    async def batch_create(cls, body: UserBatchCreate) -> int:
+        """批量创建（**事务演示**）：任一条失败整体回滚，不产生半批数据。"""
+        async with transaction():
+            total = 0
+            for user in body.users:
+                if await UserDao.find_by_student_no(user.student_no):
+                    raise USER_CONFLICT.with_detail(f"学号已存在: {user.student_no}")
+                data = user.model_dump()
+                data["password"] = encrypt_value(data["password"], context="user:login")
+                total += await UserDao.insert(data)
+        return total
+
+    @classmethod
+    async def update(cls, body: UserUpdate) -> None:
+        """更新：不存在报 404（dao 层自动翻译底层冲突错误）。"""
+        data = body.model_dump(exclude={"id"}, exclude_none=True)
+        affected = await UserDao.update(data, where={"id": body.id})
+        if not affected:
+            raise USER_NOT_FOUND.with_detail(f"用户不存在: {body.id}")
+
+    @classmethod
+    async def delete(cls, user_id: int) -> None:
+        """删除（示例用物理删除；软删用 BaseDao.soft_delete）。"""
+        affected = await UserDao.hard_delete(where={"id": user_id})
+        if not affected:
+            raise USER_NOT_FOUND.with_detail(f"用户不存在: {user_id}")
+
+    @classmethod
+    async def page(cls, query) -> tuple[list[dict], int]:
+        """分页：结果翻译（脱敏 password 字段，出参永不外泄密文）。"""
+        items, total = await UserDao.page_by_keyword(
+            query.keyword, query.page, query.page_size
+        )
+        for row in items:
+            row.pop("password", None)
+        return items, total
+
+    @classmethod
+    async def get_password(cls, student_no: str) -> str | None:
+        """读取敏感字段演示：解密（context 必须与加密时一致）。"""
+        row = await UserDao.query_one(
+            "SELECT password FROM user WHERE student_no = %s", (student_no,)
+        )
+        if row is None:
+            return None
+        return decrypt_value(row["password"], context="user:login")

shenjicore-0.6.4/.claude/skills/shenjicore/examples/your_project/main.py

@@ -0,0 +1,19 @@
+"""分层示例入口：组装配置 + mysql 插件 + 用户路由。
+
+启动（需要 MySQL；配置见 .env.example）::
+
+    cd examples/your_project
+    cp .env.example .env   # 填写 DB_* 与可选的 MYSQL_CIPHER_KEY
+    python -m uvicorn main:app --reload
+"""
+
+from action.user import router as user_router
+from common.config import Settings
+
+from shenjicore import create_app
+from shenjicore.plugins.mysql import MysqlPlugin
+
+settings = Settings()  # 自动读 .env
+
+app = create_app(settings, plugins=[MysqlPlugin()])
+app.include_router(user_router, prefix="/api/user", tags=["用户"])

shenjicore-0.6.4/.claude/skills/shenjicore/examples/your_project/schema/user.py

@@ -0,0 +1,39 @@
+"""入参/出参：schema 层只放 Pydantic 模型，无业务逻辑。"""
+
+from pydantic import BaseModel, Field
+
+
+class UserCreate(BaseModel):
+    """新增用户请求体（命名约定：XxxCreate）。"""
+
+    name: str = Field(min_length=1, max_length=50)
+    student_no: str = Field(min_length=1, max_length=20)
+    # 敏感字段演示：落库前加密（见 domain），出参永不含 password
+    password: str = Field(min_length=6)
+
+
+class UserUpdate(BaseModel):
+    """更新用户请求体（命名约定：XxxUpdate）。"""
+
+    id: int
+    name: str | None = None
+
+
+class UserDelete(BaseModel):
+    """删除请求体（命名约定：XxxDelete，含 ids 或 id）。"""
+
+    id: int
+
+
+class UserBatchCreate(BaseModel):
+    """批量创建（事务演示载体）。"""
+
+    users: list[UserCreate]
+
+
+class UserQuery(BaseModel):
+    """分页查询参数（命名约定：XxxQuery，含 page/page_size）。"""
+
+    page: int = 1
+    page_size: int = 20
+    keyword: str | None = None

shenjicore-0.6.4/.claude/skills/shenjicore/examples/your_project/tests/conftest.py

@@ -0,0 +1,8 @@
+"""示例测试环境：项目根加入 sys.path（直接运行本目录测试用）。"""
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))

shenjicore-0.6.4/.claude/skills/shenjicore/examples/your_project/tests/test_layered.py

@@ -0,0 +1,178 @@
+"""分层正确性守护：
+
+1. **action 薄壳断言**（AST）：端点函数体不含 if/for/while/raise——业务
+   逻辑进 domain，action 只转发。
+2. **domain 业务测试**（fake dao 注入）：去重冲突、密码加密落库、
+   批量事务冲突即中断。
+3. **路由全链**（TestClient + 注入 fake domain）：HTTP 层薄壳转发正确，
+   无需真实数据库。
+
+运行: ``cd examples/your_project && python -m pytest tests/ -q``
+（需要 shenjicore 已安装或可导入；pytest-asyncio auto 模式跑 async 用例）
+"""
+
+import ast
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+import pytest
+from action.user import router as user_router
+from fastapi.testclient import TestClient
+
+from shenjicore import create_app
+
+# ===========================================================================
+# 1. action 薄壳断言（AST：无控制流 = 无业务逻辑）
+# ===========================================================================
+
+def _endpoint_functions(module_path: str) -> dict[str, ast.AST]:
+    tree = ast.parse(Path(module_path).read_text(encoding="utf-8"))
+    return {
+        node.name: node
+        for node in ast.walk(tree)
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+        and not node.name.startswith("_")
+    }
+
+
+def test_action_is_thin_shell():
+    """action 端点函数体不得有 if/for/while/raise（业务逻辑禁止进 action）。"""
+    action_dir = Path(__file__).resolve().parent.parent / "action"
+    for py in sorted(action_dir.glob("*.py")):
+        funcs = _endpoint_functions(str(py))
+        assert funcs, f"{py.name} 没有端点函数"
+        for name, node in funcs.items():
+            for child in ast.walk(node):
+                assert not isinstance(
+                    child, (ast.If, ast.For, ast.While, ast.Raise)
+                ), f"{py.name}::{name} 含业务逻辑（{type(child).__name__}）——业务逻辑应放 domain 层"
+
+
+# ===========================================================================
+# 2. domain 业务测试（fake dao 注入，无需真实 MySQL）
+# ===========================================================================
+
+class FakeUserDao:
+    """记录调用 + 预置数据（替换 domain 里的 UserDao 用）。"""
+
+    inserted: list[dict] = []
+    conflict_student_no: str | None = None
+
+    @classmethod
+    async def find_by_student_no(cls, student_no: str) -> dict | None:
+        if student_no == cls.conflict_student_no:
+            return {"id": 1, "name": "已存在", "student_no": student_no}
+        return None
+
+    @classmethod
+    async def insert(cls, data: dict) -> int:
+        cls.inserted.append(data)
+        return len(cls.inserted)
+
+
+@pytest.fixture(autouse=True)
+def _reset_fake():
+    FakeUserDao.inserted = []
+    FakeUserDao.conflict_student_no = None
+
+
+@pytest.fixture(autouse=True)
+def _cipher_settings():
+    """注入 cipher 密钥配置（懒校验读取 _settings_holder，测试无需真实 .env）。"""
+    import base64
+
+    from shenjicore.plugins.mysql import _settings_holder
+
+    class FakeCipherSettings:
+        mysql_cipher_key = base64.b64encode(bytes(range(32))).decode()
+        mysql_cipher_key_file = None
+
+    _settings_holder.set(FakeCipherSettings())
+    yield
+    _settings_holder.set(None)
+
+
+def _inject_fake(monkeypatch) -> type:
+    """把 domain.user 里的 UserDao 替换为 FakeUserDao（业务方法走真逻辑）。"""
+    import domain.user as domain_user
+
+    monkeypatch.setattr(domain_user, "UserDao", FakeUserDao)
+    return FakeUserDao
+
+
+async def test_domain_add_encrypts_password(monkeypatch):
+    """domain 业务：密码落库前经 cipher 加密（v1 前缀），学号正确入库。"""
+    import domain.user as domain_user
+    from schema.user import UserCreate
+
+    _inject_fake(monkeypatch)
+    body = UserCreate(name="张三", student_no="001", password="secret123")
+    await domain_user.UserDomain.add(body)
+    assert FakeUserDao.inserted[0]["password"].startswith("v1:"), "密码必须加密落库"
+    assert FakeUserDao.inserted[0]["student_no"] == "001"
+
+
+async def test_domain_add_conflict_raises(monkeypatch):
+    """domain 业务：学号已存在 → 业务错误码 20010（409）。"""
+    import domain.user as domain_user
+    from schema.user import UserCreate
+
+    _inject_fake(monkeypatch)
+    FakeUserDao.conflict_student_no = "001"
+    body = UserCreate(name="张三", student_no="001", password="secret123")
+    with pytest.raises(Exception) as exc_info:
+        await domain_user.UserDomain.add(body)
+    assert exc_info.value.code == 20010
+
+
+async def test_domain_batch_aborts_on_conflict(monkeypatch):
+    """domain 业务：批量——中途冲突即抛错中断（事务语义由 transaction() 保证）。"""
+    import domain.user as domain_user
+    from schema.user import UserBatchCreate, UserCreate
+
+    _inject_fake(monkeypatch)
+    # 事务上下文注入 fake（真实 transaction() 需要 MySQL 连接池）——
+    # 单元测试只验证「冲突即中断」，原子性由 shenjicore transaction() 保证
+    @asynccontextmanager
+    async def _fake_transaction():
+        yield None
+
+    monkeypatch.setattr(domain_user, "transaction", _fake_transaction)
+    FakeUserDao.conflict_student_no = "002"  # 第二个用户冲突
+    body = UserBatchCreate(
+        users=[
+            UserCreate(name="甲", student_no="001", password="secret123"),
+            UserCreate(name="乙", student_no="002", password="secret123"),
+        ]
+    )
+    with pytest.raises(Exception) as exc_info:
+        await domain_user.UserDomain.batch_create(body)
+    assert exc_info.value.code == 20010
+    assert len(FakeUserDao.inserted) == 1, "冲突即中断：第二个用户未插入"
+
+
+# ===========================================================================
+# 3. 路由全链（注入 fake domain，无需真实数据库）
+# ===========================================================================
+
+def test_router_full_chain(monkeypatch):
+    """HTTP 全链：薄壳收参 → domain 处理 → 统一信封（code=0）。"""
+    import domain.user as domain_user
+
+    async def fake_add(body):
+        assert body.name == "张三"  # 收参正确
+        return 7
+
+    monkeypatch.setattr(domain_user.UserDomain, "add", fake_add)
+
+    app = create_app()
+    app.include_router(user_router, prefix="/api/user", tags=["用户"])
+    client = TestClient(app)
+
+    resp = client.post(
+        "/api/user/add",
+        json={"name": "张三", "student_no": "001", "password": "secret123"},
+    )
+    assert resp.status_code == 200
+    assert resp.json()["code"] == 0
+    assert resp.json()["data"]["id"] == 7