| name | dotnet-vue-fullstack-dev |
| description | .NET API + Vue 3 全栈开发指南：分层架构、契约设计、验证、认证授权与 UI 数据流。 触发词：全栈开发, API 设计, Pinia, 状态管理, DTO, 前后端联调, 接口对接. |
全栈开发：.NET API + Vue 前端
分层： 原则——“边界清晰、契约稳定、状态流明确、后端强制鉴权、前端只管体验”，与语言无关、长期有效。下文具体技术名（Pinia、FluentValidation、OpenAPI、async/await 等）为栈实现快照，换栈时映射到等价机制即可，以仓库实际选型为准。
围绕“边界清晰、契约稳定、状态流明确”组织后端与前端分工。正文只保留实现准则和联调检查点。
后端（API）
- 分层：Web 层只负责 HTTP、认证授权、模型绑定与结果映射；业务规则与持久化放在应用/领域与基础设施边界内，避免控制器膨胀。
- 契约：请求/响应 DTO 与领域实体分离；公开 API 使用稳定、版本化的形状，内部实现细节不泄漏到 JSON。
- 验证：入参在边界集中校验（数据注解、FluentValidation 等择一或组合），失败返回 可预期的错误结构与 HTTP 状态码。
- 异步：I/O 使用
async/await 到底；避免在请求路径上 Task.Result / .Wait()。
- 安全：默认鉴权；最小权限；敏感配置来自环境/密钥管理，不进仓库；日志中不落密码与令牌。
- 错误：区分客户端错误（4xx）与服务端故障（5xx）；必要时带 业务错误码 便于前端统一处理。
前端（Vue 3 + TypeScript）
- 状态：路由级与跨页共享用 Pinia（或项目选定方案）；组件内局部状态用
ref/reactive，避免全局滥用。
- 数据获取：API 调用集中在 api 模块或服务层，组件只编排 UI 与调用结果；统一处理 loading / 错误 / 空状态。
- 类型：优先 TypeScript；与后端契约对齐的 接口或生成类型（OpenAPI 等）减少漂移。
- 组件：可复用 UI 与页面容器分离；列表/表单模式保持 props 与事件清晰，避免隐式跨组件可变全局。
- 可访问性与 UX：关键操作有禁用与反馈；危险操作需确认；与后端错误消息映射为用户可读文案。
联调检查
执行顺序
- 先确认当前仓库的 API、状态管理、目录分层和脚本约定。
- 先定契约和错误处理，再分别落后端实现与前端消费。
- 联调时优先检查权限、分页筛选、错误体和重复提交。
- 若框架文档、组件库文档和业务代码冲突，以当前仓库约定为准。
相关 skill
/dotnet-vue-code-style — 代码风格与格式化规范/dotnet-vue-stack-review — 代码审查清单/dotnet-vue-build-quality — 构建与质量门禁
用户需求
以下是用户提供的功能需求或开发问题，请按上述规范给出设计与实现建议：
$ARGUMENTS
