Root / src / .github / copilot-instructions.md

Copilot Instructions for dpz.core

项目架构概览

  • 本项目为多模块 ASP.NET Core 平台，服务于个人内容管理系统。
  • 核心项目：Dpz.Core.Web（ASP.NET Core MVC），是最早的项目，其他模块均为后续扩展。
  • 主要组件：
    • Dpz.Core.Web：核心 MVC 项目，管理后台、页面渲染。
    • Dpz.Core.WebApi：RESTful Web API，内容管理、用户系统、互动、社区、第三方集成。
    • Dpz.Core.Auth：认证服务，OpenID Connect，JWT。
    • Dpz.Core.MongodbAccess：MongoDB 数据访问层。
    • 其他如备份、对象存储、任务调度、枚举、基础实体等模块。
  • 数据流：前端/第三方通过 Web API 或 MVC 访问，认证由独立服务提供，数据存储于 MongoDB，对象存储用又拍云。

开发与运维流程

  • 构建：
    • 推荐 VS Code 任务或命令行：
      • dotnet build src/Dpz.Core.Web/Dpz.Core.Web.csproj
      • dotnet run 直接运行 WebApi
  • 测试：
    • 各模块有独立测试项目（如 Dpz.Core.Backup.Test），使用 dotnet test。
  • Docker 部署：
    • 生产/预发布/测试环境均有专用 Dockerfile 和环境变量，详见 README.md。
  • 配置：
    • 主要配置集中于 appsettings.json，环境变量可覆盖。
    • 配置中心依赖 AgileConfig，需保证服务可访问。
  • 日志与监控：
    • 日志采用 Serilog，建议生产环境接入 Seq。
    • 后台任务调度用 Hangfire，Dashboard 路径 /jobs。
    • API 文档集成 Scalar，路径 /scalar/v1。

项目约定与模式

  • 控制器路由统一为 api/[Controller]，RESTful 风格。
  • 认证统一用 JWT Bearer，权限策略通过 [Authorize(Policy = "System")] 控制。
  • 限流保护用 [RequireRateLimiting] 特性。
  • 支持多种序列化格式（JSON、XML、MessagePack），通过 Header 或 QueryString 指定。
  • 日期格式化通过 date_format 参数。
  • 关键配置、环境变量、端口映射等详见 README.md 注意事项。

编码约定

格式与风格

  • 缩进使用 4 个空格
  • 每行代码的最大长度：100
  • if、for、foreach、while 等代码块，即使只有一行代码，也请使用大括号
  • 命名空间使用文件作用域命名空间（file-scoped namespace）
  • 命名空间应该使用 项目名.目录(.子目录)

命名规范

  • 私有字段成员使用 _ 前缀，并使用驼峰命名（如 _myField）
  • 不应该存在公开的字段
  • 参数、变量使用驼峰命名（camelCase）
  • 类、结构体、接口、方法、属性、事件等使用 Pascal 命名（PascalCase）

返回值与参数

  • 返回单个对象时，需要根据语义返回可空引用类型或不可空引用类型
  • 返回集合/数组时，除必要外（如 byte[]?），如果没有数据都应该返回空集合/数组
  • 参数类型应该尽可能抽象，返回值的类型应该尽可能具体
  • 语义冲突时，入参和出参应该分离，而不是共用一个类型

其他约定

  • 记录日志时，禁止拼接字符串，应使用结构化日志
  • IEnumerable<T> 类型不应该重复枚举
  • 如果只有一个构造函数的情况下，应该使用主构造函数

前端开发约定（Dpz.Core.Web）

参考目录

  • CSS 参考 wwwroot/css/ 下的文件
  • JS 参考 wwwroot/js/modules/ 下的文件

JavaScript 约定

  • JS 入口在 app.js 中，也可随页面加载，需兼容 pjax
  • JS 统一使用 ES 模块（ESM）
  • JS 按功能和模块分为不同的文件

CSS 约定

  • CSS 需遵循 BEM 命名规范
  • 样式应在单独文件中：页面专有样式如 index.css、article.css；公共样式以 _ 开头命名（如 _pagination.css、_nav.css）
  • 新增 CSS 需在 Views/Shared/_IncludeCssFilePartial.cshtml 中引用（开发环境单独引用，生产环境合并后引用）

兼容性与响应式

  • 支持 Chromium 内核、Firefox 浏览器
  • 自适应浅色、深色模式
  • 响应式设计（PC 端、平板端、手机端均有良好表现）
  • 风格统一

关键文件/目录

  • Dpz.Core.WebApi/README.md：API、部署、配置、开发指南。
  • Dpz.Core.Auth/：认证服务实现。
  • Dpz.Core.MongodbAccess/：数据访问层。
  • Dpz.Core.Backup/、Dpz.Core.Backup.Test/：备份与测试。
  • appsettings.json、Dockerfile、Controllers/、Models/、Service/：核心配置与业务代码。

外部依赖与集成

  • MongoDB、又拍云对象存储、AgileConfig 配置中心、Seq 日志中心、独立认证服务。

参考

如需补充或澄清，请告知具体模块或流程。