메뉴
YWeb 框架编码总规范。基于 FastAPI + SQLAlchemy 的 Web 框架，采用 Active Record + DDD 分层架构。在编写任何基于 yweb 框架的代码时使用此技能，包括 API 开发、ORM 操作、认证授权、缓存、异常处理等场景。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
YWeb 基础设施模块规范。在使用缓存（@cached）、异常处理（Err/register_exception_handlers）、日志（get_logger）、配置（AppSettings/YAML）、文件存储（本地/OSS/S3）、定时任务（Scheduler）、限流（setup_ratelimit）时使用。
YWeb DDD 分层架构与 API 设计规范。在创建或修改 API 路由、Service 层、领域模型、DTO 时使用。涵盖瘦 API 原则、服务层拆分、Model 设计、DTO 转换、响应格式等。
YWeb ORM 使用规范。在编写数据库模型定义、CRUD 操作、查询过滤、分页、软删除、事务管理、批量操作、关系定义等数据层代码时使用。基于 SQLAlchemy 的 Active Record 模式。
YWeb 认证授权与权限管理规范。在实现用户登录、JWT Token 处理、权限校验、角色管理、组织架构、OAuth 集成等功能时使用。
审查和改进 pytest 测试的真实性，防止 Happy Path、浅层、实现驱动、同义反复等虚假测试；在测试失败时执行先诊断后改码流程。用于测试评审、测试重构、失败排查场景。
YWeb 框架 Pytest 单元测试编写规范。适用于 yweb-core 底层框架本身，以及通过 pip install yweb 安装后基于该框架开发的任何上层应用。涵盖测试目录结构、conftest 编写、fixture 模式、ORM 测试、API 测试、Service 测试、Domain 测试、Mock 策略、异步测试等场景。
| name | yweb-framework |
| description | YWeb 框架编码总规范。基于 FastAPI + SQLAlchemy 的 Web 框架，采用 Active Record + DDD 分层架构。在编写任何基于 yweb 框架的代码时使用此技能，包括 API 开发、ORM 操作、认证授权、缓存、异常处理等场景。 |
本技能是 YWeb 框架所有编码规范的总入口。具体规范细节请查阅对应文档，不要凭猜测编码。
重要原则：所有编码规范的详细要求均以
yweb-core/docs/下的文档为准。遇到不确定的用法时，必须先阅读对应文档再编码。
YWeb 是基于 FastAPI + SQLAlchemy 的 Python Web 框架，核心特点：
ValueError 表达业务规则违反，不定义自定义异常类comment 参数Resp.OK() / Resp.NotFound() 等统一响应；响应模型使用 DTO 类BaseModel（不是 DTO）@cached 装饰器，注意 TTL 设置和失效策略@transactional 装饰器| 主题 | 文档路径 | 说明 |
|---|---|---|
| DDD 分层架构 | yweb-core/docs/webapi_development_standards/ddd-layered-architecture-guide.md | 分层架构、各层职责、服务层拆分原则 |
| API 层设计 | yweb-core/docs/webapi_development_standards/api_layer_design_guide.md | 瘦 API 原则、Schema 设计、响应返回规范 |
| Model 与 Service 设计 | yweb-core/docs/webapi_development_standards/model_and_service_design_guide.md | Model 字段规范、Service 层设计规范 |
| DTO 与响应处理 | yweb-core/docs/webapi_development_standards/dto_response_guide.md | DTO 基础、字段映射、响应格式规范 |
| API 与 Service 开发规范 | yweb-core/docs/webapi_development_standards/development_guide.md | 项目结构、导入规范、完整开发示例 |
| 主题 | 文档路径 | 说明 |
|---|---|---|
| ORM 基础指南 | yweb-core/docs/03_orm_guide.md | 数据库初始化、模型定义、CRUD、分页、软删除 |
| ORM 详细功能文档 | yweb-core/docs/orm_docs/README.md | 完整 ORM 功能索引（20+ 篇详细文档） |
| ORM 事务提交行为 | yweb-core/docs/orm_commit_behavior_outside_transaction.md | 事务外提交行为说明 |
| ORM 提交抑制机制 | yweb-core/docs/orm_commit_suppression_mechanism.md | 提交抑制机制说明 |
| 主题 | 文档路径 | 说明 |
|---|---|---|
| 认证模块指南 | yweb-core/docs/06_auth_guide.md | JWT、Session、OAuth、API Key 等认证方式 |
| 认证流程详解 | yweb-core/docs/webapi_development_standards/auth_flow_guide.md | JWT 认证流程、缓存优化、自动失效 |
| JWT Token 规范 | yweb-core/docs/webapi_development_standards/jwt_auth_guide.md | 双 Token 机制、前后端规范 |
| 权限管理 | yweb-core/docs/08_permission_guide.md | RBAC 框架、角色/权限管理 |
| 组织管理 | yweb-core/docs/07_organization_guide.md | 组织架构管理模块 |
| 主题 | 文档路径 | 说明 |
|---|---|---|
| 缓存 | yweb-core/docs/11_cache_guide.md | @cached 装饰器、缓存后端、失效策略 |
| 异常处理 | yweb-core/docs/05_exception_handling.md | 全局异常处理器、Err 快捷类、验证约束 |
| 配置管理 | yweb-core/docs/02_config_guide.md | YAML + 环境变量配置、AppSettings |
| 日志 | yweb-core/docs/04_log_guide.md | get_logger、日志轮转、敏感数据过滤 |
| 文件存储 | yweb-core/docs/10_storage_guide.md | 本地/OSS/S3 存储、文件验证 |
| 定时任务 | yweb-core/docs/09_scheduler_guide.md | APScheduler 封装、Builder 模式、持久化 |
| 快速开始 | yweb-core/docs/01_quickstart.md | 框架安装与基础示例 |
当需要编写或修改 yweb 相关代码时：
yweb-core/docs/orm_docs/ 下的专题文档