monorepo

Imported from Liu-Shuaiwen/monorepo (AGENTS.md). Install upstream with npx skills add Liu-Shuaiwen/monorepo. Copyright stays with the author.

AGENTS

本文件为在本仓库中运行的 AI 助手提供约定和注意事项。

作用范围

• 本文件适用于仓库根目录 my-monorepo 下的所有子目录（apps/、packages/ 等）。
• 如在子目录中新增 AGENTS.md，则以更近一级目录中的规则为准。

技术栈概览

• 包管理与工作区：pnpm (Workspace Monorepo 结构)。
• 前端核心：Vue 3 + TypeScript + Vite (全线统一)。
• 样式方案：Tailwind CSS 4 + 原生 CSS 变量。
• 状态管理：Pinia (Vue)，采用单向数据流架构 (Logic -> Store)。
• 测试框架：Vitest + Vue Test Utils + fast-check (属性测试)。
• 应用层 (apps/)：
  • apps/web：C 端用户前台应用 (Vue 3)。
  • apps/admin：B 端管理后台 (Vue 3)。
• 共享包 (packages/)：
  • packages/ui：纯 Vue 3 组件库。
    • 所有组件均位于 src/vue/ (或其他 Vue 目录)，严禁引入 React 组件。
  • packages/logic：业务逻辑层（Services, Strategies, Composables）。
  • packages/store：共享状态层（Pinia Stores，纯 State + Getters + Setters）。
  • packages/types：全域共享 TypeScript 类型定义。
  • packages/utils：纯工具函数（无副作用）+ 错误处理 + 验证器。
  • packages/mock：Mock 数据生成器（用于开发和测试）。

安装、运行与构建

注意：本项目强制使用 pnpm，禁止使用 npm 或 yarn。

• 初始化：
  • 在根目录执行：pnpm install
• 开发环境（Root Level Command）：
  • pnpm dev:web：启动 C 端应用 (Web)
  • pnpm dev:admin：启动管理后台 (Admin)
• 生产构建：
  • pnpm build:all：构建整个工作区（包含所有应用和包）
  • pnpm build:web / pnpm build:admin：单独构建应用
  • pnpm build:ui：单独构建 UI 组件库
• 测试命令：
  • pnpm test：运行所有测试
  • pnpm test:coverage：运行测试并生成覆盖率报告
  • pnpm test:e2e：运行 E2E 测试（Playwright）
  • pnpm test:e2e:ui：以 UI 模式运行 E2E 测试
• 代码质量命令：
  • pnpm lint：运行 ESLint 检查
  • pnpm lint:fix：运行 ESLint 并自动修复
  • pnpm format：使用 Prettier 格式化代码
  • pnpm format:check：检查代码格式
• 版本管理命令：
  • pnpm changeset：创建变更集
  • pnpm version：消费变更集并更新版本
  • pnpm release：构建并发布包
• 其他常用命令：
  • 针对特定包运行命令：pnpm --filter <package_name> <command>
    • 例：pnpm --filter @my-monorepo/ui add lodash

代码风格与约定

ESLint + Prettier

项目使用 ESLint 9.x 扁平配置和 Prettier 进行代码质量和格式化：

• ESLint 配置：eslint.config.js（扁平配置格式）
• Prettier 配置：.prettierrc
• 忽略文件：.prettierignore

代码风格规则：

• 使用单引号
• 使用分号
• 2 空格缩进
• 尾随逗号（ES5 风格）
• 100 字符行宽

Git Hooks

项目使用 Husky + lint-staged 在提交前自动检查代码：

• pre-commit：运行 lint-staged

• lint-staged 规则：

  • .ts、.vue 文件：ESLint + Prettier
  • .json、.md、.css 文件：Prettier

• 语言与文件规范：

  • 全面使用 TypeScript (.ts) 和 Vue SFC (.vue)。
  • 严禁新增 .js、.jsx 或 .tsx 文件。
  • 共享类型定义在 packages/types 中统一管理。

• Vue 组件规范：

  • 必须使用 <script setup lang="ts">。
  • Props 定义推荐使用泛型语法：defineProps<Props>()。
  • 组件名称采用 PascalCase (如 UserCard.vue)。

• TypeScript 配置：

  • 启用 strict 模式。
  • 启用 noUncheckedIndexedAccess（数组/对象索引访问需处理 undefined）。
  • 严禁使用 any，必须定义明确接口。

• 共享包职责边界：

  • packages/ui：
    • 基础组件：通用的原子级 UI 组件（UiButton, UiCard, UiForm 等）。
    • 业务组件：可复用的业务级组件：
      • charts/：图表组件（UiPressureChart, UiFlowGauge）
      • map/：地图组件（UiVehicleMap）
      • dashboard/：监控面板（UiMonitoringDashboard）
    • 遗留清理：如发现 .tsx 文件，应计划重构为 .vue。
  • packages/store：
    • 状态容器：纯 Pinia Stores，仅包含 State、Getters 和 Setters。
    • 严禁在 Store 中包含 API 调用或复杂业务逻辑。
    • 被 packages/logic 依赖，由 Logic 层驱动状态更新。
  • packages/logic：
    • Services：API 交互层（如 AuthService），处理 HTTP 请求。
    • Strategies：复杂业务规则策略（如 VehicleMonitorStrategy），封装变化点。
    • Composables：Vue 组合式函数，封装业务流程并调用 Services/更新 Store。
      • useAdminAuthLogic：Admin 认证逻辑
      • useAdminVehicleLogic：车辆监控逻辑
      • useWebUserLogic：C 端用户逻辑
    • Utils：请求管理器（重试、超时、取消功能）。
  • packages/utils：
    • 纯函数集合（格式化、计算、ID生成）。
    • 错误处理：AppError 类、错误码枚举、类型守卫。
    • 验证器：validateUser, validateVehicle, validateAlarm 等。
    • 严禁包含任何含有副作用或状态的代码。
  • packages/types：
    • 全局数据模型（User, Vehicle），避免在应用层重复定义 interface。
  • packages/mock：
    • SeededRandom：可复现的随机数生成器。
    • 生成器：generateVehicle, generateVehicles, generateScenarioVehicles。
    • 用于开发环境和测试的 Mock 数据。

应用层目录结构约定

• apps/web/src (C 端前台)：

  • layouts/：用户端公共布局（如 MainLayout.vue）。
  • pages/：页面级视图，组合展示 packages/ui 组件。
  • stores/：前端状态管理，复用 @my-monorepo/logic 中的核心计算逻辑。
  • composables/：视图相关的复用逻辑（UI 交互状态等）。
  • router/：前台路由配置。

• apps/admin/src (B 端后台)：

  • pages/：管理后台页面，按功能模块组织（Dashboard、车辆管理等）。
  • components/：后台特定业务组件（非通用 UI 组件）。
  • stores/：后台状态，连接视图与 packages/logic。
  • services/：后台特有的 API 适配层（如 HTTP 拦截器配置）。
  • strategies/：后台特有的策略扩展（如报警分发策略）。
  • composables/：后台视图逻辑复用（表格操作、表单验证等）。
  • utils/：后台内部工具函数（非通用逻辑）。
  • types/：后台视图专用类型（如 TableColumnConfig）。
  • env.d.ts：Vue 类型声明文件（必须存在）。

Monorepo 结构与依赖管理

my-monorepo/
├── .changeset/       # Changesets 版本管理配置
├── .github/
│   └── workflows/    # GitHub Actions CI/CD
├── .husky/           # Git Hooks (pre-commit)
├── apps/
│   ├── web/          # C端前台 (Vue 3, User Facing)
│   └── admin/        # B端后台 (Vue 3, Admin Dashboard)
├── e2e/              # E2E 测试 (Playwright)
│   ├── admin/        # Admin 应用 E2E 测试
│   └── playwright.config.ts
├── mocks/            # MSW API Mock 服务
│   ├── handlers/     # 请求处理器
│   ├── browser.ts    # 浏览器端配置
│   └── server.ts     # Node 端配置（测试用）
├── packages/
│   ├── ui/           # 统一组件库 (Vue 3 Only)
│   ├── logic/        # 业务逻辑 (Services, Strategies, Composables)
│   ├── store/        # 共享状态 (Pinia Stores, Pure State)
│   ├── types/        # 共享类型定义 (Interfaces, Enums)
│   ├── utils/        # 纯工具函数 + 错误处理 + 验证器
│   └── mock/         # Mock 数据生成器
├── docs/             # 项目文档
├── eslint.config.js  # ESLint 9.x 扁平配置
├── .prettierrc       # Prettier 配置
├── package.json      # Root scripts & workspaces
├── vitest.config.ts  # 测试配置
└── pnpm-workspace.yaml

• 新增应用：
  • 放在 apps/<name>。
  • 根据需要在根 package.json 中添加对应的 dev:<name>、build:<name> 等脚本。
• 新增共享包：
  • 放在 packages/<name>，确保：
    • pnpm-workspace.yaml 中的通配（packages/*）能够匹配到新包（通常无需修改）。
    • package.json 至少包含：name、version、main、types、scripts.build。
• 依赖管理（务必使用 pnpm）：
  • 不要在本仓库中使用 npm 或 yarn 安装依赖。
  • 给某个包添加依赖：在该包目录下执行 pnpm add <pkg> 或 pnpm add -D <pkg>。
  • pnpm.overrides 只能在根目录 package.json 中配置，子包中的配置无效。
  • 共享依赖尽量通过 workspace 机制（workspace:*）引用已有包：
    • @my-monorepo/ui：UI 组件库
    • @my-monorepo/store：共享状态
    • @my-monorepo/logic：业务逻辑
    • @my-monorepo/utils：工具函数
    • @my-monorepo/types：类型定义
    • @my-monorepo/mock：Mock 数据生成

Vite 配置注意事项

• 路径别名：每个应用的 vite.config.ts 必须配置所有使用的 workspace 包别名：

  resolve: {
    alias: {
      '@': resolve(__dirname, 'src'),
      '@my-monorepo/logic': resolve(__dirname, '../../packages/logic/src'),
      '@my-monorepo/store': resolve(__dirname, '../../packages/store/src'),
      '@my-monorepo/types': resolve(__dirname, '../../packages/types/src'),
      '@my-monorepo/utils': resolve(__dirname, '../../packages/utils/src'),
      '@my-monorepo/ui': resolve(__dirname, '../../packages/ui/src'),
    },
  }

• Vue 类型声明：每个应用的 src/ 目录下必须有 env.d.ts 文件：

  /// <reference types="vite/client" />
  declare module '*.vue' {
    import type { DefineComponent } from 'vue';
    const component: DefineComponent<object, object, unknown>;
    export default component;
  }

测试规范

• 测试文件位置：packages/<name>/__tests__/
• 命名约定：
  • 单元测试：*.test.ts
  • 属性测试：*.property.ts 或 *.property.test.ts
• 属性测试：使用 fast-check 库，最少运行 100 次迭代
• 组件测试：使用 Vue Test Utils + jsdom 环境
• 快照测试：复杂组件使用 toMatchSnapshot()
• E2E 测试：使用 Playwright，配置在 e2e/playwright.config.ts
  • Admin 应用测试：e2e/admin/
  • Web 应用测试：e2e/web/

API Mock 服务

项目使用 MSW (Mock Service Worker) 进行 API 模拟：

• 配置位置：mocks/
• 浏览器端：mocks/browser.ts
• Node 端（测试）：mocks/server.ts
• 请求处理器：mocks/handlers/index.ts

在开发环境启用 MSW：

// main.ts
import { worker } from '../mocks/browser';

if (import.meta.env.DEV && import.meta.env.VITE_ENABLE_MSW === 'true') {
  worker.start({ onUnhandledRequest: 'bypass' });
}

CI/CD

项目使用 GitHub Actions 进行持续集成：

• 配置文件：.github/workflows/ci.yml
• 触发条件：push 到 main/develop 分支，或创建 PR
• 任务：
  • lint：ESLint + Prettier 检查
  • typecheck：TypeScript 类型检查
  • test：单元测试 + 覆盖率
  • build：构建所有应用和包

版本管理

项目使用 Changesets 进行版本管理：

• 配置文件：.changeset/config.json
• 创建变更集：pnpm changeset
• 更新版本：pnpm version
• 发布：pnpm release

UI 组件使用说明

重要：本项目全线使用 Vue 3。

• 基础组件导入：

  import { UiButton, UiTable, UiCard, UiForm } from '@my-monorepo/ui/vue';

• 业务组件导入：

  import { 
    UiPressureChart,
    UiFlowGauge,
    UiVehicleMap,
    UiMonitoringDashboard
  } from '@my-monorepo/ui/vue';

业务逻辑与状态管理说明

• 导入 Store（@my-monorepo/store）：

  import { useAdminAuthStore, useAdminVehicleStore } from '@my-monorepo/store';
  
  const authStore = useAdminAuthStore();
  const isLoggedIn = authStore.isAuthenticated;

• 导入 Logic（@my-monorepo/logic）：

  import { useAdminAuthLogic, useAdminVehicleLogic } from '@my-monorepo/logic';
  
  const authLogic = useAdminAuthLogic();
  await authLogic.login(credentials);

• 导入共享类型（@my-monorepo/types）：

  import type { User, UserRole, SpecialVehicle, VehicleType } from '@my-monorepo/types';

• 导入工具函数（@my-monorepo/utils）：

  import { formatPrice, delay, generateId } from '@my-monorepo/utils';
  import { AppError, ErrorCode, isAppError } from '@my-monorepo/utils';
  import { validateUser, validateVehicle } from '@my-monorepo/utils';

• 导入 Mock 数据（@my-monorepo/mock）：

  import { generateVehicle, generateVehicles, generateScenarioVehicles } from '@my-monorepo/mock';

错误处理规范

• 使用统一的 AppError 类：

  import { AppError, ErrorCode, isAppError } from '@my-monorepo/utils';
  
  try {
    await someOperation();
  } catch (error) {
    if (isAppError(error)) {
      // 处理已知错误
    }
    throw AppError.fromError(error);
  }

对 AI 助手的特别说明

• 变更原则：

  • Vue Only：所有新功能必须使用 Vue 3 实现。
  • 清理债：如果在修改过程中遇到 .tsx 文件，请提示用户或尝试将其重构为 .vue。
  • 单源真理：类型定义以 packages/types 为准，组件复用以 packages/ui 为准。

• 一致性要求：

  • 语法：必须使用 <script setup lang="ts">。
  • 样式：优先使用 Tailwind CSS 类名。

• 类型安全：

  • 新增类型前，必须先检查 packages/types/src/index.ts 是否已存在。
  • 严禁使用 any，必须定义明确接口。
  • 注意 noUncheckedIndexedAccess：数组索引访问需要处理 undefined。

• 依赖管理：

  • 严禁使用 npm 或 yarn。必须使用 pnpm。
  • pnpm.overrides 只能在根目录配置。

• 自检清单：

  • 是否复用了 packages/ui 中的现有组件？
  • 是否引入了非 Vue 的代码（严禁）？
  • 是否复用了 packages/utils 中的工具函数？
  • 是否复用了 packages/types 中的类型？
  • 是否将页面级组件放置在 pages/ 目录？
  • 是否在 vite.config.ts 中配置了所需的路径别名？
  • 是否存在 env.d.ts 文件用于 Vue 类型声明？