crm.template

v1.0.0

Published

2 months ago

0High
0Medium
0Low

phil_litian

template-crm

基于 Vue 3 + Vite + TypeScript + Element Plus + Pinia + Vue Router + Module Federation 的 CRM 模板项目，开箱即用，统一工程规范与提交流程。

更详细的前端架构设计请参考 docs/architecture/frontend-architecture.md。

特性一览

⚡️ Vite 7 + Vue 3.5 + TypeScript 5.9，构建快速、类型严格
🧩 Element Plus UI 库，统一业务组件风格
🗂 Pinia 状态管理 + Vue Router 4 路由
🛰 Module Federation（host 端，meta-app），已接入 remoteApp 远端组件与 JDHttp
🛠 工程化脚本：phil admin CLI，支持 git-commit / changelog / release / cleanup / update-pkg
✅ 代码规范：Prettier + ESLint + Husky + Commitlint + lint-staged
🧪 Mock 数据：开发环境内置 vite-plugin-mock
🤖 AI 规则：内置团队 CSS / HTML / JS 编码规范（.claude/）

快速开始

环境要求

Node.js >= 20
pnpm >= 9（仓库锁文件为 pnpm-lock.yaml，禁止混用 npm / yarn）

安装与启动

# 安装依赖
pnpm install

# 本地开发
pnpm dev

# 类型检查 + 生产构建
pnpm build

# 本地预览构建产物
pnpm preview

启动后浏览器自动打开开发服务器（默认配置 server.open: true）。

目录结构

.
├── .claude/                 # AI 协作规范与团队前端架构文档
├── .husky/                  # Git 钩子
├── mock/                    # Mock 数据（按业务域组织，dev 环境启用）
├── public/                  # 公共静态资源
├── src/
│   ├── apis/                # 接口层（defHttp 包装 + 业务模块拆分）
│   ├── assets/              # 静态资源
│   ├── components/          # 公共组件（ui / business / layout）
│   ├── router/              # 路由（基于 unplugin-vue-router 自动生成）
│   ├── scripts/             # phil admin CLI 工程化脚本
│   ├── store/               # Pinia 全局状态
│   ├── types/               # 全局类型（含 remoteApp 远端声明）
│   ├── views/               # 业务页面（按业务域自治）
│   ├── App.vue
│   ├── main.ts              # 仅做插件挂载与启动
│   └── style.css
├── vite.config.ts
├── tsconfig.json
└── package.json

路径别名

| 别名 | 指向 | 用途 | | ---- | ------------ | ---------- | | @ | src | 业务代码根 | | @r | src/router | 路由 | | @s | src/store | Pinia | | @a | src/apis | 接口层 |

工程化 CLI（phil admin）

项目内置一套基于 cac 的 CLI 工具，统一封装日常工程操作。入口在 src/scripts/bin.ts，通过 pnpm pa 调用。

| 命令 | 说明 | | ------------------------------ | -------------------------------------------------------------------------- | | pnpm pa git-commit | 交互式生成符合 Conventional Commits 规范的提交信息（推荐用 pnpm commit） | | pnpm pa git-commit-verify | 校验当前 COMMIT_EDITMSG 是否符合规范（由 husky commit-msg 调用） | | pnpm pa changelog | 基于 conventional-changelog 生成本次发布的 CHANGELOG | | pnpm pa changelog -- --total | 生成全量 CHANGELOG |

常用快捷方式（已在 package.json 注册）：

pnpm commit       # = pnpm pa git-commit
pnpm changelog    # = pnpm pa changelog
pnpm cleanup      # = pnpm pa cleanup

CLI 配置位于 src/scripts/src/config/index.ts，支持：

自定义 gitCommitTypes / gitCommitScopes（中英文均已内置）
cleanupDirs 清理目录规则
ncuCommandArgs 升级参数
通过 package.json 的 phil 字段或外部 phil.config.* 文件覆盖默认配置（基于 c12）

Git 提交规范

项目使用 Conventional Commits 标准，并通过 husky + commitlint 在本地强制执行。

已注册的 type（详见 src/scripts/src/config/index.ts）：

| Type | 说明 | | ---------- | --------------------------------- | | feat | 新功能 | | feat-wip | 开发中的功能（部分代码） | | fix | 修复 Bug | | docs | 文档变更 | | typo | 代码或文档勘误 | | style | 代码风格变更（不影响语义） | | refactor | 代码重构（既不修 bug 也不加功能） | | perf | 性能优化 | | optimize | 代码质量优化 | | test | 测试相关 | | build | 构建系统或外部依赖变更 | | ci | CI 配置与脚本变更 | | chore | 其他不影响 src/test 的变更 | | revert | 还原先前的提交 |

已注册的 scope：projects / packages / components / hooks / utils / types / styles / deps / release / other

格式：<type>(<scope>): <description>，破坏性变更以 ! 开头。

推荐使用 pnpm commit 交互式生成提交信息，自动化选择 type / scope。

微前端（Module Federation）

本应用作为 host，federation name 固定为 meta-app，已对接远端 remoteApp：

远端组件：JDTable / JDForm / JDButton 等业务通用组件
远端 HTTP：JDHttp（即 defHttp），仅在 src/apis 层包装使用，业务模块不直接 import
shared 依赖：vue / element-plus（generate: false，由 remote 提供）

新增远端模块时，请同步在 src/types/remoteApp.d.ts 补齐类型声明，避免裸 any 导入。

代码规范

Prettier

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 100,
  "bracketSpacing": true,
  "arrowParens": "avoid",
  "endOfLine": "lf"
}

ESLint

使用 ESLint 9 flat config，集成 @eslint/js + typescript-eslint + eslint-plugin-vue，主要规则：

// eslint.config.ts
export default defineConfig(
  { ignores: ['**/*.cjs', 'src/assets/**', '.history/**', 'views/aichat/**', 'lib/**'] },
  [
    {
      files: ['**/*.{js,mjs,cjs,ts,mts,cts,vue}'],
      plugins: { js },
      extends: ['js/recommended'],
      languageOptions: { globals: globals.browser },
    },
    tseslint.configs.recommended,
    pluginVue.configs['flat/essential'],
    { files: ['**/*.vue'], languageOptions: { parserOptions: { parser: tseslint.parser } } },
    {
      rules: {
        '@typescript-eslint/no-explicit-any': 'off',
        'no-unused-expressions': 'off',
        '@typescript-eslint/no-unsafe-function-type': 'off',
        '@typescript-eslint/ban-ts-comment': 'off',
        '@typescript-eslint/no-empty-object-type': 'off',
        '@typescript-eslint/no-unused-expressions': 'off',
        'no-case-declarations': 'off',
        'no-undef': 'off',
        'no-used': 'off',
      },
    },
  ]
);

常用脚本

pnpm lint            # ESLint 检查
pnpm lint:fix        # ESLint 自动修复
pnpm format          # Prettier 格式化
pnpm format:check    # Prettier 检查

lint-staged 在 pre-commit 阶段自动对暂存文件执行 ESLint + Prettier。

Mock 数据

仅在 mode === 'development' 时启用（见 vite.config.ts）
Mock 文件按业务域组织在 mock/<domain>/，与 src/apis/modules/<domain> 一一对应
Mock 返回结构需与真实接口保持一致，类型来自 src/types/<domain>

常用脚本一览

| 脚本 | 作用 | | ------------------- | ---------------------------------------- | | pnpm dev | 启动 Vite 开发服务器 | | pnpm build | 类型检查 + 生产构建 | | pnpm preview | 本地预览构建产物 | | pnpm lint | 运行 ESLint | | pnpm lint:fix | ESLint 自动修复 | | pnpm format | Prettier 格式化 | | pnpm format:check | Prettier 检查 | | pnpm commit | 交互式生成 Conventional Commits 提交信息 | | pnpm changelog | 生成 CHANGELOG | | pnpm cleanup | 清理构建产物 | | pnpm sa | phil admin CLI 入口（等同 pnpm pa） |

AI Skills（.joycode）

项目在 .joycode/skills/ 目录下维护 AI 编码技能（Skill），用于指导 AI 助手按照项目约定生成代码。

添加 Skill

将 Skill 文件放入 .joycode/skills/ 目录，支持两种结构：

标准结构：.joycode/skills/<name>/SKILL.md（可包含 templates/、references/ 等子目录）
平铺结构：.joycode/skills/<dir>/<name>.md（文件需带 YAML frontmatter）

同步到 .claude

项目通过 scripts/sync-joycode-skills.sh 脚本将 .joycode/skills/ 同步到 .claude/skills/，使 Claude Code 也能识别这些 Skill。

# 手动同步
pnpm sync:skills

# 自动同步（pnpm install 时通过 prepare 钩子自动触发）
pnpm install

注意：新增或修改 Skill 后，请执行 pnpm sync:skills 确保同步生效。

文档

前端架构基线：docs/architecture/frontend-architecture.md
AI 生成代码规范：docs/architecture/ai-code-conventions.md
CLI 配置：src/scripts/src/config/index.ts
远端类型声明：src/types/remoteApp.d.ts