feat(template): restore deployment and guidance assets

Author: dlivxpr

docs/migration-traceability.toml

@@ -0,0 +1,7 @@
+---
+description: 按项目分层添加 FastAPI endpoint
+---
+
+为 `$ARGUMENTS` 添加 endpoint。
+
+先读取 `AGENTS.md`、相关 route/service/schema 和测试。明确 method、path、API Key 边界、request/response schema、status 与 error contract。按现有分层实现；数据库启用时保持 route → service → repository，并由 session manager 拥有 transaction。先通过公开 HTTP seam 写失败测试，再做最小实现。最后运行目标测试、Ruff、ty 和完整 pytest。

template/.omp/commands/add-endpoint.md.jinja

@@ -0,0 +1,7 @@
+---
+description: 根据 issue contract 诊断、实现并验证修复
+---
+
+修复 `$ARGUMENTS`。
+
+先读取 issue 与 `AGENTS.md`，复现问题并确定公开 seam。写一个能复现 regression 的失败测试，只修改根因，不扩大范围。逐步运行目标测试与 `uv run ty check`。完成后运行 Ruff、format check 和完整 pytest，报告实际验证证据与仍存在的风险。

template/.omp/commands/fix-issue.md.jinja

@@ -0,0 +1,7 @@
+---
+description: 审查改动的 contract、架构、安全与测试风险
+---
+
+审查 `$ARGUMENTS`。
+
+以仓库 `AGENTS.md` 和用户 contract 为标准，检查行为正确性、dependency 方向、resource lifecycle、transaction ownership、secret handling、能力开关边界与测试有效性。优先报告可复现缺陷，按严重度列出精确文件位置和触发条件。不要把风格偏好当成缺陷；没有发现时明确说明已检查范围与剩余验证风险。

template/.omp/commands/review.md.jinja

@@ -0,0 +1,14 @@
+---
+description: FastAPI route、dependency 与 response contract 约定
+globs:
+  - app/api/**/*.py
+---
+
+# API conventions
+
+- route 只处理 HTTP 输入、dependency、status、headers 与 response schema。
+- 业务规则进入 service；route 不直接访问 repository。
+- `/health`、`/health/live`、`/health/ready` 保持公开，业务 route 挂载 deployment API Key dependency。
+- dependency 优先使用 `Annotated` alias；测试结束后清理 `app.dependency_overrides`。
+- I/O route 使用 `async def`，显式声明 response model 与 status code。
+- 失败使用 `AppException`，不要在 route 自行拼装 error envelope。

template/.omp/rules/api-conventions.md.jinja

@@ -0,0 +1,15 @@
+---
+description: 服务分层、依赖方向与 lifecycle ownership
+globs:
+  - app/**/*.py
+  - cli/**/*.py
+---
+
+# Architecture
+
+- dependency 方向保持 `route → service → repository`；关闭数据库时为 `route → service`。
+- service 承载业务规则并抛出 domain exception。
+- repository 只负责数据访问，写路径使用 `flush()`/`refresh()`，不拥有 transaction。
+- API transaction 由 session manager 统一提交或回滚。
+- Redis、database、Taskiq 等 resource 必须有显式 owner，并在对应 process 关闭。
+- CLI 只负责参数与 process 启动，不复制业务逻辑。

template/.omp/rules/architecture.md.jinja

@@ -0,0 +1,14 @@
+---
+description: Python 格式、类型与 async 编码约定
+globs:
+  - "**/*.py"
+---
+
+# Code style
+
+- 使用 Python [[ python_version ]]、4 空格、双引号和 100 字符行宽。
+- 导入使用项目根 package 的绝对路径；Ruff 负责排序。
+- 类型使用现代 syntax，公开函数和 dependency boundary 必须完整标注。
+- I/O、database、HTTP 与 lifecycle 路径使用 async；不要在 event loop 中执行 blocking I/O。
+- 不添加只使用一次的 abstraction，也不保留兼容 alias 或 dead branch。
+- 修改后运行 `uv run ruff check .`、`uv run ruff format --check .` 和 `uv run ty check`。

template/.omp/rules/code-style.md.jinja

@@ -0,0 +1,14 @@
+---
+description: 异常 envelope、凭据与日志安全约定
+globs:
+  - app/**/*.py
+---
+
+# Exceptions and security
+
+- service 抛出具体 `AppException` 子类；异常类拥有 `code` 与 `status_code`。
+- error response 保持 `{ "error": { "code", "message", "details" } }`。
+- 未处理异常记录内部 traceback，但只返回安全的 `INTERNAL_ERROR`。
+- API Key 使用统一 dependency 和 constant-time compare；不要在 route 重复实现。
+- 日志、trace、错误和测试 fixture 不得输出 key、token、password 或 secret。
+- Request ID 通过 `X-Request-ID` 关联日志和 response。

template/.omp/rules/exceptions-security.md.jinja

@@ -0,0 +1,15 @@
+---
+description: Pydantic schema 与 database model 边界
+globs:
+  - app/schemas/**/*.py
+  - app/db/models/**/*.py
+---
+
+# Schemas and models
+
+- API input/output 使用显式 Pydantic schema，不直接暴露 database model。
+- create、update 与 response contract 分离；PATCH update 字段按 contract 可选。
+- response schema 需要 ORM 转换时使用 `ConfigDict(from_attributes=True)`。
+- validator 只表达稳定 domain invariant，不执行 I/O。
+- database-generated identifier 与 timestamp 在 response 中保持明确类型。
+- schema 变化同步检查 OpenAPI、测试、migration 和文档。

template/.omp/rules/schemas-models.md.jinja

@@ -0,0 +1,14 @@
+---
+description: 公开 seam、资源隔离与集成测试约定
+globs:
+  - tests/**/*.py
+---
+
+# Testing
+
+- 通过公开接口验证 observable contract，不断言 private helper 或模板源码细节。
+- HTTP 测试使用 HTTPX `AsyncClient` + `ASGITransport`。
+- 每个测试结束后清理 `app.dependency_overrides` 和创建的外部资源。
+- 外部基础设施行为使用真实 service；不要为测试加入业务 route、task 或 runtime fallback。
+- 每个 test 必须能对 plausible regression 失败；避免 tautology 和只检查 import。
+- 先运行最窄 test file，再运行完整 `uv run pytest`。