dotnet-vue-fullstack-dev

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 契约、状态码与错误体与前端处理一致
• 权限：后端强制校验，前端仅做 UX 隐藏
• 分页/排序/筛选参数命名前后端一致
• 并发与重复提交（按钮节流、幂等键）按需处理

执行顺序

1. 先确认当前仓库的 API、状态管理、目录分层和脚本约定。
2. 先定契约和错误处理，再分别落后端实现与前端消费。
3. 联调时优先检查权限、分页筛选、错误体和重复提交。
4. 若框架文档、组件库文档和业务代码冲突，以当前仓库约定为准。

相关 skill

• /dotnet-vue-code-style — 代码风格与格式化规范
• /dotnet-vue-stack-review — 代码审查清单
• /dotnet-vue-build-quality — 构建与质量门禁

用户需求

以下是用户提供的功能需求或开发问题，请按上述规范给出设计与实现建议：

$ARGUMENTS