cloudoll 4.3.0__tar.gz → 4.4.0__tar.gz

{cloudoll-4.3.0 → cloudoll-4.4.0}/CHANGELOG.md

@@ -1,5 +1,95 @@
 # Changelog
 
+简体中文见 [CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md)。
+
+## 4.4.0
+
+Defect-fix release; backward compatible. Python 3.9+ remains supported.
+
+### Database
+
+- `for_update()` row locks now require your own transaction. Outside one, the lock
+  was released by the commit that `for_update()` issued itself and protected
+  nothing; such a call now raises instead of silently doing nothing.
+- A transaction cancelled or timed out while waiting for a connection gives that
+  connection back to the pool, so long-running services stop losing connections.
+- Model fields are hashable again: columns can go into sets and serve as dict
+  keys (deduplicating columns, excluding groups of fields).
+- `SUM(DISTINCT column)` and similar aggregate deduplication now happens inside
+  the aggregate, so values are deduplicated before being combined, and a literal
+  inside an aggregate is no longer bound twice.
+- URL query parameters in an AWS datasource string are no longer handed to the
+  driver as unknown connection options.
+
+### Web and templates
+
+- A response that has already started streaming keeps its body when an error
+  occurs; the JSON error handler no longer rewrites it. Streaming and SSE
+  endpoints stay intact.
+- Page responses no longer repeat `charset` in `Content-Type`.
+- `session` options (`key`, `max_age`, `httponly`, `secure`, `domain`, `path`,
+  `samesite`) apply to encrypted cookie, Redis and Memcached storage alike.
+- `render_view()` keywords are `Response` options only, and the template context
+  is the positional mapping. A stray keyword now raises `TypeError` instead of
+  being silently merged into the context.
+- Development servers bind to 127.0.0.1 by default and no longer occupy
+  `port + 1`.
+- `server.ignore_dirs` is honoured for directories such as `logs`, so writing logs
+  no longer triggers a reload.
+- The scaffolded authorization middleware now matches its documentation: it is an
+  async decorator, lets static paths through, and lets downstream failures reach
+  the error layer instead of being flattened into a 500 that echoes the exception
+  text.
+
+### Command line and new projects
+
+- `cloudoll create` no longer copies `__pycache__` and `.pyc` files into the new
+  project.
+- The last component of a project name must be letters, digits, underscore, dot
+  or dash; names with spaces or shell characters are refused, as is an existing
+  target directory.
+- A failed creation exits with a non-zero status and removes the half-written
+  project instead of leaving it behind.
+- New projects write independent JWT and session keys to `.env`, which
+  `.gitignore` keeps out of version control. Local starts no longer warn about a
+  random process-local session key, and logins survive a restart or an added
+  worker.
+
+### Mail and utilities
+
+- Building a `cloudoll.mail.smtp.Client` no longer reaches the network, and one
+  client stays usable across sends and server idle timeouts: each `send()` opens
+  its own connection, carries one copy of the body, and closes the connection even
+  when the send fails.
+- Missing credentials and an empty recipient address now raise a readable error
+  before anything is sent.
+- `cloudoll.utils` - reversible encryption, keyed digests, random strings and the
+  distributed ID generator - is now official API with a
+  [utilities](https://cloudoll.chuchur.com/utils) page and regression tests. None
+  of them is a password hash; store user passwords with bcrypt or argon2.
+- New [mail](https://cloudoll.chuchur.com/mail) page documents sending limits
+  (SMTPS 465 only, no STARTTLS, no retry or queue). The dead POP3 draft under
+  `cloudoll/mail` is gone - Cloudoll does not receive mail.
+
+### Upgrade notes
+
+- `for_update()` outside a transaction and unexpected `render_view()` keywords now
+  raise rather than misbehaving quietly; audit those two call shapes before
+  upgrading.
+- `cloudoll create` rejects names it used to accept, such as `my shop`, because
+  they reached a shell unsafely.
+- Projects created before this release keep an old `config/conf.local.yaml`
+  without a session key; add `session.secret_key` (or set
+  `CLOUDOLL_SESSION_SECRET`) so sessions survive restarts and multiple workers.
+- Existing `.env` files need the new `CLOUDOLL_SESSION_SECRET` entry; `.env` has
+  always been ignored by the project's `.gitignore`.
+
+### Documentation
+
+- JWT middleware examples use `web.RequestKey` instead of a plain string key, so
+  aiohttp stops warning about it.
+- The quick start and session pages describe how a new project injects its keys.
+
 ## 4.3.0
 
 ### ORM queries and writes
@@ -56,9 +146,6 @@ Backward-compatible feature release. Pydantic 2 (`>=2.0,<3`) is now a core
 runtime dependency. Existing handlers and explicit ORM engine bindings remain
 supported. Python 3.9+ remains supported by the CI matrix.
 
-Publication date is recorded by the release tag/PyPI; preparing these files does
-not publish the package.
-
 - Correct lifecycle callback and JWT payload type declarations for strict
   checking with current dependency annotations.
 - Include HTTP method and actual request path in exception logs; emit 4xx access
@@ -76,8 +163,8 @@ not publish the package.
 
 ## 4.0.0
 
-Release notes for 4.0.0. Publication date is recorded by the release tag/PyPI;
-preparing these files does not publish the package.
+This release contains breaking changes to configuration, security, ORM and the
+application lifecycle. Read the migration guide before upgrading.
 
 ### Breaking changes and migration
 

{cloudoll-4.3.0 → cloudoll-4.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudoll
-Version: 4.3.0
+Version: 4.4.0
 Summary: Assist in quickly creating distributable microservices based on aiohttp, with a focus on simplicity and ease of use.
 Author-email: Qiu <smallerqiu@gmail.com>
 License-Expression: MIT
@@ -54,7 +54,7 @@ Dynamic: license-file
 
 English | [简体中文](README.zh-CN.md)
 
-Cloudoll 4.3.0 is an aiohttp-based Python library for routing, middleware,
+Cloudoll 4.4.0 is an aiohttp-based Python library for routing, middleware,
 templates, sessions, JWT, database access and application scaffolding.
 
 ## AI-assisted development
@@ -71,8 +71,8 @@ does not have `cloudoll ai --help`, consult its matching README and source first
 Python 3.9+ is required. Install only the optional drivers you use:
 
 ```sh
-python -m pip install 'cloudoll==4.3.0'
-python -m pip install 'cloudoll[mysql,postgres,cache]==4.3.0'
+python -m pip install 'cloudoll==4.4.0'
+python -m pip install 'cloudoll[mysql,postgres,cache]==4.4.0'
 ```
 
 The AWS extra requires Python 3.10+. Aurora remains untested; see
@@ -87,7 +87,8 @@ python -m pip install -r requirements.txt
 cloudoll start -n myapp
 ```
 
-The generated project targets 4.3.0 and receives a random JWT secret. Controllers
+The generated project targets 4.4.0 and receives random JWT and session secrets
+in `.env`. Controllers
 and authentication middleware are examples: replace demo credentials and supply
 your own authorization and upload policies before deployment.
 
@@ -172,8 +173,8 @@ python -m ruff check cloudoll tests
 python -m mypy
 python -m pytest -q -m 'not integration' -k 'not aws'
 python -m build
-python tests/check_wheel.py dist/cloudoll-4.3.0-py3-none-any.whl
-python tests/check_release.py dist/cloudoll-4.3.0-py3-none-any.whl
+python tests/check_wheel.py dist/cloudoll-4.4.0-py3-none-any.whl
+python tests/check_release.py dist/cloudoll-4.4.0-py3-none-any.whl
 ```
 
 Native integration tests require explicitly configured disposable databases.

{cloudoll-4.3.0 → cloudoll-4.4.0}/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-Cloudoll 4.3.0 is an aiohttp-based Python library for routing, middleware,
+Cloudoll 4.4.0 is an aiohttp-based Python library for routing, middleware,
 templates, sessions, JWT, database access and application scaffolding.
 
 ## AI-assisted development
@@ -19,8 +19,8 @@ does not have `cloudoll ai --help`, consult its matching README and source first
 Python 3.9+ is required. Install only the optional drivers you use:
 
 ```sh
-python -m pip install 'cloudoll==4.3.0'
-python -m pip install 'cloudoll[mysql,postgres,cache]==4.3.0'
+python -m pip install 'cloudoll==4.4.0'
+python -m pip install 'cloudoll[mysql,postgres,cache]==4.4.0'
 ```
 
 The AWS extra requires Python 3.10+. Aurora remains untested; see
@@ -35,7 +35,8 @@ python -m pip install -r requirements.txt
 cloudoll start -n myapp
 ```
 
-The generated project targets 4.3.0 and receives a random JWT secret. Controllers
+The generated project targets 4.4.0 and receives random JWT and session secrets
+in `.env`. Controllers
 and authentication middleware are examples: replace demo credentials and supply
 your own authorization and upload policies before deployment.
 
@@ -120,8 +121,8 @@ python -m ruff check cloudoll tests
 python -m mypy
 python -m pytest -q -m 'not integration' -k 'not aws'
 python -m build
-python tests/check_wheel.py dist/cloudoll-4.3.0-py3-none-any.whl
-python tests/check_release.py dist/cloudoll-4.3.0-py3-none-any.whl
+python tests/check_wheel.py dist/cloudoll-4.4.0-py3-none-any.whl
+python tests/check_release.py dist/cloudoll-4.4.0-py3-none-any.whl
 ```
 
 Native integration tests require explicitly configured disposable databases.

{cloudoll-4.3.0 → cloudoll-4.4.0}/README.zh-CN.md

@@ -2,11 +2,11 @@
 
 [English](README.md) | 简体中文
 
-生产配置、资源关闭期限、JWT 验证、JSON 日志与监控接入见 [生产运行契约](docs/production.md)；版本兼容及发布检查见 [维护政策](docs/maintenance.md)，安全问题报告见 [SECURITY.md](SECURITY.md)。
+生产配置、资源关闭期限、JWT 验证、JSON 日志与监控接入见 [生产运行契约](docs/production.md)；版本兼容及发布检查见 [维护政策](docs/maintenance.md)；各版本变化见 [更新日志](CHANGELOG.zh-CN.md)，安全问题报告见 [SECURITY.md](SECURITY.md)。
 
 Cloudoll 是一个基于 aiohttp 的 Python Web 开发库，提供路由自动注册、中间件、模板渲染、会话管理、JWT、数据库访问及命令行脚手架，帮助快速构建 Web 应用和微服务。
 
-本文适用于 Cloudoll 4.3.0。从 3.x 升级前请阅读下方迁移说明。
+本文适用于 Cloudoll 4.4.0。从 3.x 升级前请阅读下方迁移说明。
 
 ## AI 辅助开发
 
@@ -25,10 +25,10 @@ Cloudoll 是一个基于 aiohttp 的 Python Web 开发库，提供路由自动
 
 ## 安装
 
-安装 4.3.0：
+安装 4.4.0：
 
 ```sh
-python -m pip install 'cloudoll==4.3.0'
+python -m pip install 'cloudoll==4.4.0'
 ```
 
 在当前仓库目录安装源码：
@@ -41,16 +41,16 @@ python -m pip install -e .
 
 ```sh
 # MySQL
-python -m pip install 'cloudoll[mysql]==4.3.0'
+python -m pip install 'cloudoll[mysql]==4.4.0'
 
 # PostgreSQL
-python -m pip install 'cloudoll[postgres]==4.3.0'
+python -m pip install 'cloudoll[postgres]==4.4.0'
 
 # AWS 数据库驱动
-python -m pip install 'cloudoll[aws]==4.3.0'
+python -m pip install 'cloudoll[aws]==4.4.0'
 
 # Redis / Memcached 会话或 Redis 数据库
-python -m pip install 'cloudoll[cache]==4.3.0'
+python -m pip install 'cloudoll[cache]==4.4.0'
 ```
 
 源码开发时可用 `python -m pip install -e '.[mysql,postgres,cache,dev]'` 安装。
@@ -89,7 +89,7 @@ myapp/
 └── templates/
 ```
 
-脚手架中的鉴权中间件和登录接口用于演示。正式使用前，应替换示例账号、密码和业务鉴权逻辑。新建项目会获得独立的 JWT 密钥。
+脚手架中的鉴权中间件和登录接口用于演示。正式使用前，应替换示例账号、密码和业务鉴权逻辑。新建项目会在 `.env` 里获得相互独立的 JWT 与 Session 密钥。
 
 ### 手动创建应用
 
@@ -546,8 +546,8 @@ cloudoll restart -n myapp
 python -m pip install -e '.[mysql,postgres,cache,dev]'
 python -m pytest -q -m 'not integration' -k 'not aws'
 python -m build
-python tests/check_wheel.py dist/cloudoll-4.3.0-py3-none-any.whl
-python tests/check_release.py dist/cloudoll-4.3.0-py3-none-any.whl
+python tests/check_wheel.py dist/cloudoll-4.4.0-py3-none-any.whl
+python tests/check_release.py dist/cloudoll-4.4.0-py3-none-any.whl
 ```
 
 最后一条命令用于验证构建出的 wheel，版本号变化后请调整文件名。测试使用模拟数据库连接及本机 HTTP 服务；真实数据库连接和 AWS 故障切换需要单独的集成环境。

cloudoll-4.4.0/cloudoll/__init__.py

@@ -0,0 +1 @@
+__version__ = "4.4.0"

{cloudoll-4.3.0 → cloudoll-4.4.0}/cloudoll/ai/docs/changelog.md

@@ -6,10 +6,57 @@ icon: logs
 
 # 更新日志
 
-按版本倒序记录 Cloudoll 的主要变化。当前使用方法请以本站 4.3.0 文档为准，历史功能不代表当前仍保留相同 API。
+按版本倒序记录 Cloudoll 的主要变化。当前使用方法请以本站 4.4.0 文档为准，历史功能不代表当前仍保留相同 API。
 
 历史版本日期为对应源码提交日期。各版本源码可通过表格中的链接查看。
 
+## 4.4.0
+
+缺陷修复版本，向后兼容；Python 3.9+ 仍然支持。
+
+### 数据库
+
+- `for_update()` 行锁必须在调用方自己的事务里使用。以前脱离事务的写法会临时开一个事务，锁随提交立刻释放，实际什么都没锁住；现在这样的调用直接报错。
+- 开启事务时获取连接超时或被取消，已借到的连接会归还连接池，服务跑久了不再慢慢耗光连接。
+- 模型字段恢复可哈希，可以放进 `set` 或作为字典键（列去重、批量排除字段）。
+- `SUM(DISTINCT column)` 等聚合去重编译到聚合函数内部，去重发生在求和之前；聚合里的字面量不再被重复绑定参数。
+- AWS 数据源串里的 URL 查询参数不再作为未知参数传给驱动。
+
+### Web 与模板
+
+- 已经开始输出的响应不再被 JSON 错误处理改写坏，流式与 SSE 接口出错时保留原响应。
+- 页面响应的 `Content-Type` 不再出现两个 `charset`。
+- `session` 的 `key`、`max_age`、`httponly`、`secure`、`domain`、`path`、`samesite` 在加密 Cookie、Redis、Memcached 三种存储下都生效。
+- `render_view()` 的关键字参数只归一处：模板上下文按位置传字典，关键字参数一律是 `Response` 选项，传错直接抛 `TypeError`，不再被当成上下文吞掉。
+- 默认监听 127.0.0.1，开发模式不再额外占用配置端口 +1。
+- `server.ignore_dirs` 对 `logs` 等目录生效，写日志不再触发热重载。
+- 脚手架的鉴权中间件示例与文档一致：async 装饰器写法，放行静态资源，不再把后续处理器的异常吞成带错误文本的 500。
+
+### 命令行与新建项目
+
+- `cloudoll create` 不再把 `__pycache__`、`.pyc` 复制进新项目。
+- 项目名最后一段只能是字母、数字、下划线、点、短横线；带空格或 shell 元字符的名字被拒绝，已存在的目标目录也会报错。
+- 创建失败时退出码非 0，并回收只写了一半的目录，不会留下半个项目。
+- 新项目在 `.env` 里同时生成 JWT 与 Session 两把独立密钥，配置读取环境变量，`.gitignore` 忽略 `.env`。本地启动不再出现“使用随机进程本地密钥”的告警，重启和多 worker 之间登录状态不再丢失。
+
+### 邮件与工具函数
+
+- 邮件客户端构造时不再立刻联网，发送过一次或服务器空闲断开后仍能继续使用：每次 `send()` 自建连接、只带一份正文，失败时也会关闭连接。
+- 缺少账号或授权码、收件人为空时立即给出可读错误，不再留给服务器报认证失败。
+- `cloudoll.utils` 的可逆加密、单向摘要、随机字符串、分布式 ID 成为正式 API，见[工具函数](/utils)。存用户密码请改用 bcrypt/argon2，这些工具都不是口令哈希。
+- 新增[发送邮件](/mail)页；`cloudoll/mail` 下从未生效的 POP3 草稿文件被移除，库本身不提供收信能力。
+
+### 升级提示
+
+- 在事务外调用 `for_update()`、给 `render_view()` 传多余关键字，以前是静默出错，现在会抛异常；升级前先检查这两类调用。
+- `cloudoll create` 开始拒绝带空格和 shell 元字符的项目名。
+- 老项目请自行补上 `session.secret_key` 或 `CLOUDOLL_SESSION_SECRET`，否则重启、多 worker 之间仍会丢登录状态。
+
+### 文档
+
+- JWT 中间件示例改用 `web.RequestKey`，避免 aiohttp 的字符串键告警。
+- [快速开始](/)与 [Cookie 与 Session](/session-cookie)说明新项目的密钥注入方式。
+
 ## 4.3.0
 
 ### ORM 查询与写入
@@ -43,8 +90,6 @@ icon: logs
 
 ## 4.1.0
 
-本节对应 4.1.0 源码变更；实际发布状态以 PyPI 为准。
-
 - [默认数据源](/database#默认数据源与模型绑定)：orm.default、模型 __datasource__、独立类级查询、query() 与 transaction()，保留显式 use(engine)。
 - datasource_context 为独立任务和测试提供作用域绑定；事务复用现有引擎机制，应用与并发任务保持隔离。
 - [请求参数校验](/validation)：Pydantic 2 支持 Body、Query、Form、Path，重复数组参数和结构化 HTTP 400，兼容旧接口与流式上传。

{cloudoll-4.3.0 → cloudoll-4.4.0}/cloudoll/ai/docs/config.md

@@ -14,9 +14,21 @@ CLI 默认读取项目根目录的 `config/conf.local.yaml`。选择生产配置
 cloudoll start -n myapp -env prod -m production
 ```
 
-`-env prod` 选择文件，`-m production` 选择运行模式，两者不是同一个开关。通过 `--host` / `--port` 可覆盖监听地址；未传入时使用配置。入口参数 `-e app` 是模块名，不是 `app.py`。
+`-env prod` 选择文件，`-m production` 选择运行模式，两者不是同一个开关。通过 `--host` / `--port` 可覆盖监听地址；未传入时使用配置。配置也缺省时，监听地址为本机回环 `127.0.0.1`、端口 `9001`；需要对外提供服务时显式写入 `server.host: 0.0.0.0` 或使用 `--host 0.0.0.0`。开发模式只有工作进程监听业务端口，监督进程不占用其他端口。入口参数 `-e app` 是模块名，不是 `app.py`。
 
-配置必须是 YAML 映射；加载时使用安全 YAML 解析和严格环境变量展开。缺少环境变量会报错。Cloudoll 没有自动加载项目 `.env` 文件的逻辑，应由 shell、容器或进程管理器注入变量。
+配置必须是 YAML 映射；加载时使用安全 YAML 解析，并通过 EnvYAML 严格展开环境变量。默认情况下，缺少引用的环境变量会报错。
+
+### `.env` 文件
+
+EnvYAML 会自动读取当前工作目录下的 `.env`。从项目根目录启动时，可将配置中引用的变量放在根目录的 `.env` 中，也可以由 shell、容器或进程管理器注入。
+
+- 可通过进程环境变量 `ENV_FILE` 指定其他文件；从不同目录启动时，建议使用绝对路径。
+- 默认 `.env` 路径相对于当前工作目录，不是 YAML 所在目录；`get_config(..., root=...)` 只指定 YAML 配置的根目录，不改变 `.env` 的查找位置。
+- 当前 EnvYAML 实现中，文件中的变量会覆盖同名进程环境变量，再用于 YAML 占位符展开。生产环境应避免残留本地 `.env` 覆盖部署配置。
+- 文件变量仅进入 EnvYAML 配置，不会写入 `os.environ`；直接使用 `os.getenv()` 或 `os.environ` 的业务代码不能因此读到这些变量。
+- `-env prod` 选择 `config/conf.prod.yaml`，不会自动切换为 `.env.prod`；需要时通过 `ENV_FILE` 指定。
+
+不要提交包含密码或密钥的 `.env`；可提交仅包含变量名和占位值的 `.env.example`。
 
 显式指定的配置文件不存在会抛 FileNotFoundError，不再返回空配置继续启动。核心配置节、端口/请求大小、布尔开关、资源关闭期限和 JWT 策略会在应用创建时校验，on_create 修改后再次校验。业务自定义键仍可使用；数据库驱动参数由相应引擎校验。
 

{cloudoll-4.3.0 → cloudoll-4.4.0}/cloudoll/ai/docs/cookie-and-session.md

@@ -78,9 +78,14 @@ session:
   max_age: 86400
   httponly: true
   secure: false
+  domain: .example.com
+  path: /
+  samesite: Lax
 ```
 
-也可只在进程环境设置 CLOUDOLL_SESSION_SECRET。未配置时生成应用进程本地随机密钥，重启会使旧 Session 失效，多进程间也不能共享；生产必须使用一致的随机密钥。更换密钥会使原 Cookie 失效。
+`domain`、`path`、`samesite` 属于 Session Cookie 本身，Cookie、Redis、Memcached 三种存储都读取同一份配置；Redis 存储下不要把这三个键写进 `redis` 子配置。`samesite` 只接受 `Strict`、`Lax`、`None`；`None` 表示不下发该属性，使用浏览器默认策略。`path` 决定浏览器在哪些路径回传 Session Cookie，改成子路径后原路径下的请求将不再带会话。HTTPS 生产环境使用 `secure: true`，此时 `samesite: None` 还要求浏览器允许跨站发送，仅在确有跨站回调时使用。
+
+`cloudoll create` 生成的项目已在 `config/conf.local.yaml` 写好 `session.secret_key: $CLOUDOLL_SESSION_SECRET`，并把随机密钥连同 JWT 密钥一起写入项目根目录的 `.env`，开箱即用、重启不掉线；`.env` 已被 `.gitignore` 忽略，生产环境改用环境变量注入同名变量。也可只在进程环境设置 CLOUDOLL_SESSION_SECRET。两处都没有时框架生成应用进程本地随机密钥并记录一次告警，重启会使旧 Session 失效，多进程间也不能共享；生产必须使用一致的随机密钥。更换密钥会使原 Cookie 失效。
 
 Cookie 容量有限，不要保存大对象、密码或完整业务数据。客户端加密 Cookie 模式无法仅靠退出操作撤销其他地方留存的旧 Cookie；需要集中撤销时使用服务端存储及业务级会话控制。
 

{cloudoll-4.3.0 → cloudoll-4.4.0}/cloudoll/ai/docs/database.md

@@ -6,7 +6,7 @@ icon: database
 
 # 数据库与 ORM
 
-本页介绍 Cloudoll 4.3.0 的原生 MySQL/PostgreSQL 接口，包括保存点、流式查询与 SQL 日志。从 3.x 升级请先阅读[升级说明](/migration)。
+本页介绍 Cloudoll 4.4.0 的原生 MySQL/PostgreSQL 接口，包括保存点、流式查询与 SQL 日志。从 3.x 升级请先阅读[升级说明](/migration)。
 
 ## 应用代码默认使用实体
 
@@ -26,7 +26,7 @@ Python API 的准确拼写是 `order_by` 和大写 `As`，不是 `orderby` / `as
 ## 安装与连接
 
 ```sh
-python -m pip install 'cloudoll[mysql,postgres]==4.3.0'
+python -m pip install 'cloudoll[mysql,postgres]==4.4.0'
 ```
 
 Web 应用在 [database 配置](/config)中声明连接，由框架建立、关闭，通过 `request.app.db.别名` 获取。不要每个请求创建一个池，也不要在请求结束时关闭共享池。
@@ -251,7 +251,8 @@ present = await User.where(User.email == "alice@example.test").exists()
 ```
 
 `join(..., kind="left" | "inner" | "right")` 默认仍是 LEFT JOIN，保持兼容。
-`distinct()` 对整行投影去重；字段 `User.id.distinct().count()` 生成 COUNT(DISTINCT ...)。
+`distinct()` 对整行投影去重；字段 `User.id.distinct().count()` 生成 COUNT(DISTINCT ...)，
+聚合后的 `User.amount.sum().distinct()` 同样生成 SUM(DISTINCT ...)，去重的是聚合输入值而不是聚合结果行。
 `one_dict()` 返回字典或 None，不把别名/聚合列装进实体；原有 one/one_model 返回规则不变。
 `exists()` 返回布尔值，保留筛选、分组和 offset，最多读取一行且不消费原查询；它不保证并发唯一性。
 `count()` 忽略分页、排序和行锁，保留去重、分组与 HAVING。
@@ -411,7 +412,8 @@ async with Inventory.transaction():
 
 `for_update(nowait=True)` 遇到锁竞争立即报错；
 `for_update(skip_locked=True)` 跳过已锁行，适合任务领取，不适合完整性报表。两选项互斥。
-调用方必须显式管理事务；不会自动开启事务或重试。锁查询不能使用只读 stream()。
+调用方必须显式管理事务；事务外执行锁查询直接抛 TransactionError，不会自开事务后立刻提交，也不会自动重试。
+锁查询不能使用只读 stream()。
 聚合、DISTINCT、外联表的锁定限制由数据库决定，示例只锁普通实体行。
 新增能力在原生 MySQL 8.4 / PostgreSQL 16 验证，不将该结果等同于 Aurora 验证。
 

{cloudoll-4.3.0 → cloudoll-4.4.0}/cloudoll/ai/docs/jwt.md

@@ -42,8 +42,15 @@ def issue_token(request, authenticated_user_id: int) -> str:
 
 ```python
 # middlewares/auth.py
+from aiohttp import web
+
 from cloudoll.web import middleware, render_error
 
+# 请求上下文里的键用 web.RequestKey 声明：写字符串会触发 NotAppKeyWarning，
+# 键名也只在各文件里重复拼写，改名时编译器帮不上忙。
+USER: web.RequestKey[dict] = web.RequestKey("user")
+
+
 @middleware
 async def auth(request, handler):
     if request.path.startswith("/api/"):
@@ -60,11 +67,11 @@ async def auth(request, handler):
                 response = render_error("token 无效或已过期", status=401)
                 response.headers["WWW-Authenticate"] = "Bearer"
                 return response
-            request["user"] = user
+            request[USER] = user
     return await handler(request)
 ```
 
-业务路由用 `request["user"]` 读取已验证 payload；仍需检查账号状态、资源归属和权限。未认证通常返回 401；身份有效但无权限通常返回 403。
+业务路由用 `request[USER]` 读取已验证 payload；仍需检查账号状态、资源归属和权限。中间件没有写入时（路径不在 `/api/` 下、或该路由被 `sa_ignore` 放行）`request[USER]` 抛 `KeyError`，需要容忍未登录时读 `request.get(USER)`，未设置返回 None。未认证通常返回 401；身份有效但无权限通常返回 403。
 
 `@post("/api/login", sa_ignore=True)` 可由该中间件识别为免 token 路由，但登录接口仍必须验证凭证。签名错误、过期、缺失所需声明等无效凭证返回 None；缺少 key、非法 leeway 等配置错误会抛异常，不应统一当作用户登录失败。库不会自动发送认证 HTTP 响应。
 

cloudoll-4.4.0/cloudoll/ai/docs/mail.md

@@ -0,0 +1,74 @@
+---
+title: 邮件
+order: 135
+icon: router
+---
+
+# 发送邮件
+
+`cloudoll.mail.smtp.Client` 是一个直白的 SMTPS 发信客户端，用于告警、报表这类自己拼装正文的场景。它不依赖 `Application`，也不读取 `config/conf.*.yaml`；连接参数由调用方传入，可以放在进程环境或自己的配置里。
+
+库只提供发送，不提供收取邮件，也没有队列、定时与重试。需要投递保障时，把发信交给业务侧重试队列或专业邮件服务。
+
+## 用法
+
+```python
+from cloudoll.mail import smtp
+
+client = smtp.Client(
+    smtp_server="smtp.example.com",
+    account="alert@example.com",
+    account_name="监控告警",
+    password="授权码",          # 邮箱服务商签发的发信授权码，不是登录密码
+    port=465,
+)
+client.subject = "磁盘使用率超过 90%"
+client.content = "host: db-01\nused: 92%"
+client.add_to_addr("运维", "ops@example.com")
+client.add_to_addr("张三", "zhangsan@example.com")
+client.send()
+```
+
+构造函数不碰网络，只保存参数；连接和登录发生在 `send()`。因此可以在模块导入时创建客户端，也可以反复用同一个客户端发信——每次 `send()` 都会新建一条连接并在结束时关闭。
+
+## 配置项
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `smtp_server` | 必填 | SMTP 主机名，缺失时构造即抛 `ValueError`。 |
+| `port` | `465` | 端口，始终用 `SMTP_SSL` 连接。 |
+| `account` | `""` | 登录账号，同时作为发件地址。 |
+| `account_name` | `""` | 显示在 `From` 里的发件人名称，支持中文。 |
+| `password` | `""` | 发信授权码。账号或授权码为空时 `send()` 抛 `KeyError`，不会先连服务器。 |
+| `debug_level` | `0` | 透传 `smtplib.SMTP.set_debuglevel()`，非 0 时把 SMTP 会话过程打到标准输出，其中含登录交互，只在本机排查时开启。 |
+
+只支持 465 端口的隐式 TLS（SMTPS）。587 的 STARTTLS 升级方式没有实现，需要时改用 `smtplib` 自己发送。
+
+## 收件人、正文与附件
+
+`add_to_addr(名称, 地址)` 可以调用多次，它们同属一条邮件的收件人列表；地址为空抛 `KeyError`。`content` 是正文，正文类型由 `mime_type` 决定，默认 `plain`，改成 `"html"` 后正文按 HTML 发送。
+
+```python
+client.mime_type = "html"
+client.content = "<h1>周报</h1><p>见附件</p>"
+client.addfile("/data/report.pdf")
+```
+
+`addfile(路径)` 接收绝对路径，按文件名猜测 MIME 类型（猜不到时按 `application/octet-stream`），读取内容并做 Base64 编码。每个附件依次拿到从 0 开始的 Content-ID，可直接内嵌进 HTML 正文：
+
+```python
+client.addfile("/data/img/logo.png")    # cid:0
+client.addfile("/data/img/chart.png")   # cid:1
+client.mime_type = "html"
+client.content = '<img src="cid:0"><img src="cid:1">'
+```
+
+`addhtml(html)` 是另附一个 HTML 部分，与设置 `mime_type = "html"` 不同：前者正文里同时存在纯文本和 HTML 两个部分，后者只有 HTML 一个部分。标题和正文用普通属性赋值即可，中文无需手工编码。
+
+## 失败与重发
+
+`send()` 不吞异常，登录失败、连接中断、收件人被拒都会原样抛出 `smtplib` / `ssl` 的异常，由调用方决定是否重试。发送中途失败时连接同样会关闭，客户端可以继续复用。
+
+重复调用 `send()` 发送的是标题、正文、收件人和附件的当前快照：改动 `content` 后再发，下一封就是新内容，不会把上一封的正文带过来。附件部分会随客户端保留，重发时仍在。
+
+密钥按快速开始的做法从环境注入，不要把授权码写进仓库。批量投递请在业务侧控制节奏，遵守所用服务商的发信频率限制。

{cloudoll-4.3.0 → cloudoll-4.4.0}/cloudoll/ai/docs/start.md

@@ -9,7 +9,7 @@ path: /
 
 Cloudoll 是基于 aiohttp 的异步 Python Web 库，提供路由、模板、Session、ORM 和 CLI。
 
-> 本文档按 Cloudoll 4.3.0 源码更新，实际发布状态以 PyPI 为准。从 3.x 升级前，请先阅读[升级说明](/migration)，确认配置和 API 的兼容性变化。
+> 本文档按 Cloudoll 4.4.0 源码更新，实际发布状态以 PyPI 为准。从 3.x 升级前，请先阅读[升级说明](/migration)，确认配置和 API 的兼容性变化。
 
 ## 环境与安装
 
@@ -18,8 +18,8 @@ Cloudoll 是基于 aiohttp 的异步 Python Web 库，提供路由、模板、Se
 ```sh
 python3 -m venv .venv
 source .venv/bin/activate
-python -m pip install 'cloudoll==4.3.0'
-python -m pip install 'cloudoll[mysql,postgres,cache]==4.3.0'
+python -m pip install 'cloudoll==4.4.0'
+python -m pip install 'cloudoll[mysql,postgres,cache]==4.4.0'
 ```
 
 Windows PowerShell 激活命令为 `.venv\Scripts\Activate.ps1`。只使用 Web 功能时不需要安装数据库 extras。
@@ -38,7 +38,9 @@ cd myapp
 cloudoll start -n myapp
 ```
 
-默认读取 `config/conf.local.yaml`，默认端口 9001。在生成的 `controllers/home/index.py` 中替换已有首页处理器（不要重复注册同一路由）：
+项目名的最后一段只能由字母、数字、下划线、点、短横线组成（不能带空格和 shell 元字符，也不能是 `.` 或 `..`）；它同时用作提示的 `-n` 服务名和 pid 文件名。名字不合法、目标目录已存在或复制中途出错都会报错并以退出码 2 结束，中途出错时刚建好的目录会被回收，不会留下半个项目。
+
+默认读取 `config/conf.local.yaml`，默认端口 9001。配置保留 `$CLOUDOLL_JWT_SECRET`、`$CLOUDOLL_SESSION_SECRET` 两个占位符，脚手架另在项目根目录把两个互不相同的随机密钥写入 `.env`（已被 `.gitignore` 忽略），新项目开箱就带有稳定的 Session 密钥；生产环境改用环境变量注入，不要提交 `.env`。`.env` 按当前工作目录读取，请在项目根目录启动。未设置 Session 密钥时框架退回进程本地随机密钥并告警，重启或多 worker 之间旧会话都会失效。在生成的 `controllers/home/index.py` 中替换已有首页处理器（不要重复注册同一路由）：
 
 ```python
 from cloudoll.web import get
@@ -54,7 +56,7 @@ curl http://127.0.0.1:9001/
 
 响应包含 `name`、默认的 `message: "OK"`、`code: 200` 和动态生成的毫秒级 `timestamp`。返回字符串、列表等也会包装在 `data` 中；如果需要原样 JSON，返回 `aiohttp.web.json_response(...)`。纯文本使用 `render(text="Hello")`。
 
-开发模式会监听 Python 文件变化并重启工作进程，另使用业务端口加一的辅助端口；它不是生产进程守护工具。配置文件修改后请重启。
+开发模式会监听 Python 文件变化并重启工作进程；只有工作进程监听业务端口，监督进程不开辅助端口，业务端口加一被其他程序占用也不影响启动。它不是生产进程守护工具。配置文件修改后请重启。
 
 ## 手动创建最小应用
 

cloudoll-4.4.0/cloudoll/ai/docs/utils.md

@@ -0,0 +1,74 @@
+---
+title: 工具函数
+order: 145
+icon: config
+---
+
+# 工具函数
+
+`cloudoll.utils` 里是与 Web 层、数据库都无关的小工具：可逆加密、单向摘要、随机字符串、分布式 ID。它们可以在任意脚本里直接导入，不需要 `Application`。
+
+## 可逆加密
+
+需要在之后取回原文时用 `CryFernet`（AES-128-CBC + HMAC，来自 `cryptography` 的 Fernet 令牌格式）：
+
+```python
+import os
+
+from cryptography.fernet import Fernet
+from cloudoll.utils.password import CryFernet
+
+KEY = os.environ["CLOUDOLL_CRYPTO_KEY"]  # 与数据库密码同级对待，见配置文件
+
+crypt = CryFernet(KEY)
+token = crypt.encrypt("sk-abcdef")
+assert crypt.decrypt(token) == "sk-abcdef"
+```
+
+密钥必须是 32 字节 url-safe base64 编码，新密钥用 `Fernet.generate_key().decode()` 生成，只放在进程环境里，见[配置文件](/config)。构造时密钥不合法会立即报错；换密钥后旧 token 一律解不开（抛 `InvalidToken`），所以轮换要先解密再重新加密。
+
+同一明文每次得到的 token 都不同（内含时间戳和随机 IV），因此 token 不能作为等值判断的键，也不能直接当唯一索引；需要可比较的定长值时用下一节的摘要。
+
+## 单向摘要
+
+```python
+from cloudoll.utils.password import hash as keyed_hash
+
+digest = keyed_hash("alice", "pepper")  # sha256("alice" + "pepper") 的十六进制
+```
+
+结果是 64 位小写十六进制，同样的输入永远得到同样的结果，适合做幂等键、缓存键、数据指纹。`key` 传 `None` 或空串都表示不加 pepper。
+
+**不要用它存用户密码。** `hash()` 没有盐、没有迭代次数，同一密码的摘要固定，彩虹表和 GPU 暴力破解对它有效；用户密码要用 bcrypt、argon2 这类专用慢哈希（额外依赖由业务引入），框架不内置密码存储方案。
+
+## 随机字符串
+
+```python
+from cloudoll.utils.password import generator
+
+make_token = generator(32)  # 返回函数，每次调用给一个新的随机串
+make_with_symbols = generator(16, True)
+
+value = make_token()
+assert len(value) == 32
+```
+
+`generator()` 返回的是生成器函数，不是字符串；字母表默认 `A-Za-z0-9`（62 个字符），`use_special=True` 时追加 `string.punctuation`（共 94 个）。取值用 `secrets`，可用于随机口令、邀请码、临时密钥。强度按字母表规模算：16 位字母数字约 95 bit，需要更高就加长。随机串本身不带校验，要防篡改仍需签名或加密。
+
+## 分布式 ID
+
+```python
+from cloudoll.utils.snowflake import IdWorker
+
+worker = IdWorker(worker_id=1, datacenter_id=1)
+order_id = worker.next_id()
+```
+
+位分配与 Twitter Snowflake 一致：12 位序列号、5 位 `worker_id`、5 位 `datacenter_id`，高位是相对 2010-11-04 的毫秒时间戳。结果是 63 位以内的正整数，可以直接存 BigInt 字段。
+
+- `worker_id`、`datacenter_id` 只接受 0 到 31，越界抛 `ValueError`。
+- 一个 `worker_id + datacenter_id` 组合同时只能有一个实例在发号。多进程部署时每个进程都要分到不同编号，否则同一毫秒可能发出相同 ID。
+- 单实例内 ID 严格递增，多线程共用同一实例是安全的（内部加锁）。同一毫秒内用完 4096 个序列号后，`next_id()` 会等到下一毫秒再返回。
+- 检测到时钟回拨时抛异常，而不是返回可能重复的 ID。NTP 大步回调、虚机时钟漂移都会触发；不能接受异常的业务要自己降级（例如改用数据库序列）。
+
+IdWorker 只负责生成 ID，不做持久去重，也不保证跨实例的全局有序。需要"绝不重复"时给该列加数据库唯一约束，见[数据库](/database)。