11comm前端组技术文档

Appearance

2026-03-19

11comm 智慧社区项目 ​

项目技术架构 ​

本项目是一个基于 Vue 3 + TypeScript 的全栈管理后台，采用 Monorepo 结构管理多个子项目。

核心技术栈 ​

层级技术选型
前端框架Vue 3 + Vite + TypeScript
UI 组件库Element Plus + Plus Pro Components
状态管理Pinia
后端框架Nitro v3 (Nitro v3 + H3)
数据库Neon Serverless Postgres
ORMDrizzle ORM
类型库@01s-11comm/type (同构运行时库)

Schema 架构 (Trinity Pattern) ​

项目采用 Schema 驱动开发模式，所有数据库表定义遵循 Trinity Pattern：

  1. Drizzle Table - 数据库表定义
  2. Zod Schemas - 运行时验证（insertXxxSchema, selectXxxSchema, updateXxxSchema）
  3. TypeScript Types - 静态类型（NewXxx, Xxx, UpdateXxx）

Schema 文件位置：apps/type/src/business/{domain}/{module}/schema.ts

例如：

  • 字典管理：apps/type/src/business/dev-team/config-manage/dictionary/schema.ts
  • 房产管理：apps/type/src/business/property-manage/house-property-manage/schema.ts
  • 费用管理：apps/type/src/business/property-manage/expense-manage/house-charge/schema.ts

API 开发规范 ​

所有 Nitro 接口遵循统一的开发规范：

  • 使用 defineHandler 与 nitro/h3 导入
  • 响应必须使用 JsonVO<T> 类型注解约束
  • 统一使用 message 字段（不是 msg）
  • 入参通过 readValidatedBody + Zod Schema 校验
  • Insert 操作使用 as unknown as NewX 类型回填
  • 错误响应包含 error 和 stack 字段

详见：Nitro API 开发技能

类型共享架构 ​

项目使用 @01s-11comm/type 作为前后端共享的类型库：

  • 位置：apps/type/src/
  • 导出方式：按业务路径组织，使用 index.ts 统一导出
  • 依赖：被 apps/admin 和 apps/type 自身引用

数据库迁移 ​

使用 Drizzle ORM 进行数据库版本管理：

bash
# 生成迁移文件
pnpm db:generate

# 执行迁移
pnpm db:migrate

# 推送 schema 变更（开发环境）
pnpm db:push

# 填充种子数据（TRUNCATE + 重新插入）
pnpm db:seed

# 核弹级重置（DROP 全部表 → 重建 → 填充数据）
pnpm db:reset

详见：Schema 开发规范

套用的模板 ​

本项目套用是 pure-admin 模板。

项目部署 ​

点此阅读文档。

package.json 命令 ​

1. 开发命令 ​

命令说明
pnpm dev启动开发服务器（通过 turbo 调度）
pnpm vite:dev直接使用 vite 启动开发服务器
pnpm docs:dev启动 VitePress 文档开发服务器

2. 构建命令 ​

2.1 构建模式说明 ​

本项目支持两种构建模式：

  1. 纯客户端构建（SPA） - 构建纯前端单页应用，不包含服务端代码
  2. Nitro 全栈构建 - 构建包含 Nitro 服务端的全栈应用

2.2 构建命令列表 ​

命令说明构建模式
pnpm build构建生产环境（等同于 build:prod）纯客户端构建（SPA）
pnpm build:prod构建生产环境客户端版本纯客户端构建（SPA）
pnpm build:prod:cloudflare构建 Cloudflare 部署版本（包含 Nitro 服务端）Nitro 全栈构建 ⭐
pnpm build:prod:vercel构建 Vercel 部署版本（包含 Nitro 服务端）Nitro 全栈构建 ⭐
pnpm build:staging构建预发布环境客户端版本纯客户端构建（SPA）
pnpm build:github构建 GitHub Pages 部署客户端版本纯客户端构建（SPA）
pnpm docs:build构建 VitePress 文档-

2.3 重要说明 ​

⚠️ 生产环境部署必须使用 Nitro 全栈构建命令

  • Cloudflare 部署：使用 pnpm build:prod:cloudflare
  • Vercel 部署：使用 pnpm build:prod:vercel

区别：

  • 纯客户端构建：只生成 .output/public/ 目录，包含静态 HTML/CSS/JS 文件
  • Nitro 全栈构建：生成 .output/server/ 和 .output/public/ 目录，包含服务端 API 和客户端文件

验证方法：

bash
# Nitro 全栈构建成功后，应该存在以下文件：
ls .output/nitro.json        # Nitro 配置文件
ls .output/server/index.mjs  # 服务端入口文件

3. 预览和测试命令 ​

命令说明
pnpm preview预览构建产物
pnpm preview:build构建后预览构建产物
pnpm test启动 Vitest 测试（jsdom 环境，用于前端组件测试）
pnpm test:nitro启动 Nitro 接口测试（node 环境，需要先运行 pnpm dev）

4. 代码质量命令 ​

命令说明
pnpm lint运行 ESLint 和 Prettier
pnpm lint:eslint运行 ESLint 检查并修复
pnpm lint:prettier运行 Prettier 格式化代码
pnpm format格式化代码（等同于 lint:prettier）
pnpm typecheck运行 TypeScript 类型检查

5. Drizzle ORM 数据库命令 ​

命令说明
pnpm db:generate生成数据库迁移文件（根据 schema 变更生成 SQL）
pnpm db:migrate执行数据库迁移（应用迁移文件）
pnpm db:push推送 schema 变更到数据库（开发环境快速同步）
pnpm db:studio启动 Drizzle Studio（可视化数据库管理界面）
pnpm db:drop删除迁移文件（谨慎使用）
pnpm db:seedTRUNCATE 全部表数据，重新填充种子数据
pnpm db:reset核弹级重置：DROP 全部表 → 重建表结构 → 填充数据

5.1 种子数据命令详细说明 ​

项目使用 Direct Seed 架构，Seed 模块直接使用 Drizzle ORM Insert 类型定义数据，无中间 SQL 文件层。详细使用指南请参阅：种子数据命令使用指南

命令说明
pnpm db:seedTRUNCATE CASCADE 清空全部表 → 按依赖顺序重新填充数据。适用于 seed 数据变更、表结构未变
pnpm db:resetDROP 全部表 → 清除迁移历史 → 从 schema 重推表结构 → 填充数据。适用于 schema 变更后从零重建

6. 环境变量命令 ​

命令说明
pnpm env:pull从 Vercel 项目拉取环境变量到本地 .env

7. 其他命令 ​

命令说明
pnpm rm:types删除生成的类型文件（清理用）
pnpm clean:cache清理缓存并重新安装依赖
pnpm svgo优化 SVG 文件
最近更新