菜单
YWeb DDD 分层架构与 API 设计规范。在创建或修改 API 路由、Service 层、领域模型、DTO 时使用。涵盖瘦 API 原则、服务层拆分、Model 设计、DTO 转换、响应格式等。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
YWeb 基础设施模块规范。在使用缓存（@cached）、异常处理（Err/register_exception_handlers）、日志（get_logger）、配置（AppSettings/YAML）、文件存储（本地/OSS/S3）、定时任务（Scheduler）、限流（setup_ratelimit）时使用。
YWeb ORM 使用规范。在编写数据库模型定义、CRUD 操作、查询过滤、分页、软删除、事务管理、批量操作、关系定义等数据层代码时使用。基于 SQLAlchemy 的 Active Record 模式。
YWeb 认证授权与权限管理规范。在实现用户登录、JWT Token 处理、权限校验、角色管理、组织架构、OAuth 集成等功能时使用。
YWeb 框架编码总规范。基于 FastAPI + SQLAlchemy 的 Web 框架，采用 Active Record + DDD 分层架构。在编写任何基于 yweb 框架的代码时使用此技能，包括 API 开发、ORM 操作、认证授权、缓存、异常处理等场景。
审查和改进 pytest 测试的真实性，防止 Happy Path、浅层、实现驱动、同义反复等虚假测试；在测试失败时执行先诊断后改码流程。用于测试评审、测试重构、失败排查场景。
YWeb 框架 Pytest 单元测试编写规范。适用于 yweb-core 底层框架本身，以及通过 pip install yweb 安装后基于该框架开发的任何上层应用。涵盖测试目录结构、conftest 编写、fixture 模式、ORM 测试、API 测试、Service 测试、Domain 测试、Mock 策略、异步测试等场景。
| name | yweb-ddd-architecture |
| description | YWeb DDD 分层架构与 API 设计规范。在创建或修改 API 路由、Service 层、领域模型、DTO 时使用。涵盖瘦 API 原则、服务层拆分、Model 设计、DTO 转换、响应格式等。 |
YWeb 采用 Active Record + DDD 分层思想，三层架构：
API 层 (路由) → Service 层 (业务编排) → Domain 层 (领域模型)
关键原则：
validate_xxx() 方法中| 层 | 职责 | 禁止 |
|---|---|---|
| API 层 | 参数验证、DTO 转换、异常→HTTP 响应、调用 Service | 业务逻辑、事务管理、数据库操作 |
| Service 层 | 跨聚合协调、事务管理、权限检查 | HTTP 感知、直接返回 Response |
| Domain 层 | 单聚合业务规则、数据验证、状态变更 | 调用其他聚合、HTTP 感知 |
| 场景 | 推荐方式 | 说明 |
|---|---|---|
| 子对象有独立生命周期、需独立增删改查 | OneToOne / ManyToOne | 两张表，外键关联 |
| 子对象是聚合内部状态、无独立主键 | OwnsOne | 单表展开，值对象语义 |
典型 OwnsOne 场景：地址、金额区间、联系方式、审计信息、时间窗口等。
详见 yweb-core/docs/orm_docs/21_owns_one.md。
DTO（来自 yweb），使用 from_entity() / from_page() 转换BaseModel@dataclass 装饰器_field_mapping 进行字段映射，使用 _value_processors 进行值处理（字段类型应与处理器转换后的类型一致）Resp.OK() / Resp.Fail() / Resp.NotFound() 等PageResponseValueError，转为 Resp.Fail()编码前必须阅读对应文档以获取完整规范和示例：
| 主题 | 文档路径 |
|---|---|
| DDD 分层架构全貌 | yweb-core/docs/webapi_development_standards/ddd-layered-architecture-guide.md |
| API 层设计规范（瘦 API 原则） | yweb-core/docs/webapi_development_standards/api_layer_design_guide.md |
| Model 与 Service 层设计规范 | yweb-core/docs/webapi_development_standards/model_and_service_design_guide.md |
| DTO 与响应处理规范 | yweb-core/docs/webapi_development_standards/dto_response_guide.md |
| API 与 Service 开发综合规范 | yweb-core/docs/webapi_development_standards/development_guide.md |
ddd-layered-architecture-guide.md 确定分层api_layer_design_guide.mdmodel_and_service_design_guide.mddto_response_guide.mddevelopment_guide.md 中的完整示例