目录结构
按源码说明项目根目录、前端和服务端目录的职责
本页以 imqi1-cms 当前源码为准，说明从仓库根目录到 app/pages、app/pages/admin 和 server 的目录职责。.nuxt/、.output/、.sessions/、.attachments/、.live-photos/、logs/ 等运行时或构建生成目录不属于日常源码修改范围。
根目录
目录树imqi1-cms/
├── app/ Nuxt 前端：页面、组件、组合式函数与样式
├── server/ Nitro 服务端：API、路由、中间件与服务端工具
├── shared/ 前后端共用的纯函数、常量和类型声明
├── test/ 单元、集成与端到端测试
├── prisma/ Prisma schema 与数据库相关文件
├── scripts/ 部署、数据、缓存和构建辅助脚本（独立子包）
├── docker/ Dockerfile 与 Docker Compose 编排文件
├── mini/ uni-app 小程序端子模块
├── public/ 不经过 Vue 打包的静态资源与上传目录
├── lib/ 站点配置类型与配置辅助代码
├── .github/ CI 工作流
├── site.config.ts 站点默认配置、功能开关和构建配置
├── nuxt.config.ts Nuxt、Nitro、PWA、ISR 与 CDN 配置
├── prisma.config.ts Prisma CLI 配置
├── package.json 根项目脚本和依赖
├── tsconfig.json TypeScript 配置
├── eslint.config.mjs ESLint 配置
├── components.json UI 组件生成配置
└── .env.example 环境变量模板源码仓库中还可能出现 .nuxt/、.output/、.sessions/、.attachments/、.compressed-live-photos/、.live-photos/ 和 logs/。这些目录分别用于 Nuxt 开发缓存、生产构建产物、会话、附件临时文件、实况照片压缩和运行日志，不应当作为业务源码提交或手工修改。
app/
app/ 是 Nuxt 4 的前端源码目录。页面路由由 pages/ 负责，复用界面放在 components/，跨页面状态和行为放在 composables/。
目录树app/
├── app.vue 应用根组件
├── pages/ 文件式路由，详见下文
├── components/ 页面和业务组件
│ ├── admin/ 后台专用组件
│ ├── markdown/ 正文 Markdown 渲染组件
│ ├── markdown-editor/ Markdown 编辑器及扩展
│ ├── site/ 站点头部、底部和导航组件
│ └── ui/ 通用 UI 基础组件
├── composables/ `useXxx` 组合式函数
├── utils/ 前端工具函数和 Markdown 工具
├── lib/ 前端私有库，例如 APlayer
├── plugins/ 客户端或服务端 Nuxt 插件
├── middleware/ 前端路由中间件
├── directives/ 自定义指令
├── assets/ 构建期 CSS、图标和表情资源
├── shiki/ 代码高亮主题
├── types/ 前端 API、组件和页面类型
└── router.options.ts Nuxt 路由选项修改前端页面时，通常从 app/pages 开始；需要复用 UI 时优先查找 app/components，需要跨页面复用逻辑时查找或新增 app/composables。服务端请求不要直接写进通用组件，按现有页面的 $fetch、useFetch 和类型定义模式调用 server/api。
app/pages/
Nuxt 根据文件路径生成 URL。方括号表示动态参数，[slug].vue 对应 :slug，[...slug].vue 对应可捕获多段路径的通配参数。
目录树app/pages/
├── index.vue 首页 `/`
├── about.vue 关于页 `/about`
├── archiving.vue 归档页 `/archiving`
├── category/[slug].vue 分类页 `/category/:slug`
├── tag/[slug].vue 标签页 `/tag/:slug`
├── content/[category]/[slug].vue 文章页 `/content/:category/:slug`
├── links.vue 友链页 `/links`
├── subscribes.vue 订阅页 `/subscribes`
├── changelogs.vue 更新日志 `/changelogs`
├── map.vue 地图页 `/map`
├── messages.vue 留言页 `/messages`
├── search.vue 搜索页 `/search`
├── agreement.vue 协议页 `/agreement`
├── sitemap.vue HTML 站点地图 `/sitemap`
├── login.vue 登录页 `/login`
├── 404.vue 404 页面
├── [...slug].vue 自定义页面和兜底内容路由
└── admin/ 后台页面，详见下一节文章、分类和标签的前台页面只负责展示和交互，数据由对应的 server/api 接口提供。后台页面通过 app/middleware/auth.global.ts 和后台布局共同限制访问；新增页面时需要同时考虑导航、权限和对应 API。
app/pages/admin/
后台页面使用 /admin 前缀，登录后由 AdminLayout.vue 提供统一布局。目录中的 index.vue 是后台首页，其他文件按后台功能分组。
目录树app/pages/admin/
├── index.vue 后台首页 `/admin`
├── contents/
│ ├── index.vue 文章列表 `/admin/contents`
│ └── edit.vue 新建或编辑文章 `/admin/contents/edit`
├── pages/
│ ├── index.vue 自定义页面列表 `/admin/pages`
│ └── edit.vue 新建或编辑页面 `/admin/pages/edit`
├── attachments/
│ ├── index.vue 全部附件 `/admin/attachments`
│ └── [id].vue 附件详情 `/admin/attachments/:id`
├── categories.vue 分类管理 `/admin/categories`
├── tags.vue 标签管理 `/admin/tags`
├── comments.vue 评论审核 `/admin/comments`
├── links.vue 友链管理 `/admin/links`
├── subscribes.vue 订阅源管理 `/admin/subscribes`
├── travels.vue 旅行地点管理 `/admin/travels`
├── changelogs.vue 更新日志管理 `/admin/changelogs`
├── cache.vue 缓存管理 `/admin/cache`
├── settings.vue 系统设置 `/admin/settings`
├── users.vue 用户与两步验证 `/admin/users`
└── [...slug].vue 后台兜底路由文章编辑页同时管理文章正文、分类、标签、封面、地图地点和附件；自定义页面编辑页复用文章编辑接口，但保存的是页面内容。后台页面只应通过登录后的会话调用后台 API，写请求还必须携带 CSRF token。
server/
server/ 是 Nitro 服务端目录。文件名中的 .get.ts、.post.ts、.put.ts、.patch.ts 和 .delete.ts 会参与生成 HTTP 方法；API 文件相对于 server/api/ 的路径会加上 /api/ 前缀。完整接口清单见 Server 接口。
目录树server/
├── api/ `/api/*` 接口，按公开、认证、后台和 mini 分组
├── routes/ 不带 `/api` 的服务端路由
│ ├── feed.get.ts `/feed` RSS
│ ├── sitemap.xml.get.ts `/sitemap.xml` XML 站点地图
│ ├── uploads/ 本地附件回源
│ └── _AMapService/ 高德地图服务端代理
├── middleware/ 请求级中间件，如 Referer 和 mini HMAC 鉴权
├── plugins/ Nitro 启动插件，如 CSP、Redis、RSS 定时任务
├── utils/ Prisma、缓存、邮件、Markdown、附件等服务端工具
├── lib/ 服务端私有模块，例如登录认证
├── types/ 服务端 API、认证和工具类型
└── runtime-assets/ 运行时二进制资源，如 IP 库和验证码字体server/api/
server/api 的目录名直接映射 URL：server/api/category/[slug].get.ts 对应 GET /api/category/:slug。动态文件名使用方括号；[...].options.ts 用于处理通配路径的 CORS 预检。
admin/：后台接口，统一检查登录会话；写接口还检查 CSRF。auth/：登录、登出、当前会话和两步验证。mini/：小程序接口，生产环境由server/middleware/mini-auth.ts统一检查 HMAC 签名。- 其余顶层文件：前台页面、评论、友链、地图、搜索、附件、二维码等公开接口。
server/routes/
server/routes 用于不希望出现在 /api 下的固定端点或资源回源。RSS 使用 /feed，XML 站点地图使用 /sitemap.xml，本地附件由 /uploads/* 兜底，高德代理由 /_AMapService/* 提供。
server/utils/、middleware/ 和 plugins/
server/utils/ 只放服务端可复用逻辑，不直接产生路由；middleware/ 在请求进入 handler 前运行，适合做统一鉴权和请求限制；plugins/ 在 Nitro 启动或响应阶段注册全局能力。修改接口行为前应先检查这些目录，避免重复实现已有的鉴权、CSRF、缓存和安全逻辑。