前端开发规约总览

本项目所有前端开发必须严格遵守的规约集合。这些规约确保代码质量、设计一致性、团队协作效率和长期可维护性。

📋 规约使用说明

核心目的：本规约集为前端开发提供明确的执行标准，涵盖从架构设计到代码细节的各个方面。

适用范围：

所有新开发的前端画面和组件
现有代码的修改和重构
AI辅助生成代码的审查标准
团队成员代码审查依据

强制等级：

⭐⭐⭐ 必须遵守：架构基础，违反将导致代码审查不通过
⭐⭐ 强烈推荐：最佳实践，除特殊原因外应遵守
⭐ 建议遵守：提高代码质量的建议

🏗️ 项目架构概览

技术栈约束

框架: Vue 3 + Nuxt 3 (SPA模式)
语言: TypeScript (strict模式)
UI库: Element Plus (必须通过atoms包装后使用)
状态管理: Pinia (stores/目录)
API调用: $fetch (禁止axios)
样式: CSS自定义属性 (设计令牌)
测试: Vitest (单元测试) + Playwright (E2E)
文档: Storybook (必须完全整备)

核心架构原则

SPA优先：不使用SSR/SSG，纯客户端渲染
类型安全：严格TypeScript，禁止any，明确unknown
设计令牌：所有样式必须使用CSS自定义属性
组件包装：Element Plus组件必须通过components/common包装
国际化：所有文本必须通过useI18n()获取，禁止硬编码
业务隔离：基础UI与业务逻辑严格分离

📋 共通检查清单（必须遵守）⭐⭐⭐

设计系统合规性

すべてのコンポーネントで Design Token を使用 (所有组件必须使用设计令牌)
色・余白・フォント・角丸すべてトークン必須 (颜色、间距、字体、圆角全部必须)
src\assets\styles\colors-primitive.css
src\assets\styles\tokens-ui.css
src\assets\styles\tokens.css
デザイントークンが適用され、ハードコード値がない (设计令牌已应用，无硬编码值)
禁止事项：
❌ #fff、#000 等硬编码色值
❌ px 单位（仅允许 rem）
❌ 固定幅・高（内容驱动）
❌ inline style
❌ マジックナンバー (魔法数字)

组件设计原则

子コンポーネントで margin を禁止 (子组件禁止使用margin)
親コンポーネントが gap / padding を管理 (父组件管理gap/padding)
コンポーネントサイズは内容ドリブン (组件尺寸由内容驱动)
コンポーネントタグが kebab-case (组件标签使用kebab-case)
再利用回数 3 回以上 → コンポーネント化必須 (复用3次以上必须组件化)
ネイティブHTMLコントロール禁止 (禁止原生HTML控件)
div+CSS代わりにel-row,el-col使用 (使用el-row/el-col替代div+css)

代码质量

TS 型定義は必ず用意 (必须提供TypeScript类型定义)
型定義が適切：any禁止、unknown明示
console.log 禁止 (禁止console.log)
JS/TS 変数は camelCase を使用 (变量使用camelCase)
コードのコメントは日本語で記述 (代码注释使用日语)
マジックナンバー禁止 (禁止魔法数字)
inline style 禁止 (禁止内联样式)
Props の直接変更禁止 (禁止直接修改Props)

开发流程

API は必ず composables へ集約 (API必须集中到composables)
Storybook は必須（完全整備） (Storybook必须完全整备)
共通コンポーネント：Storybook必須 (Storybook必须)
ページレベル：ページ層のみ作成 (仅创建页面层)
フォームには必ずバリデーション実装 (表单必须实现验证)
TODO コメントが仮実装箇所に付与されている (TODO注释添加到临时实现处)
ワイヤーフレーム/SVG の全要素が実装されていること (线框图/SVG所有元素已实现)
loading / error 处理実装済み (loading/error处理已实现)
送信中の多重クリック防止必須 (必须防止提交期间多次点击)

🏗️ フロント構造（Atomic Design + Domain）

ディレクトリ構成（Nuxt 3）

frontend/src/
├── pages/                  # ページコンポーネント（ファイルルート）
├── components/
│   ├── common/             # 基本UI（atoms）- Element Plus包装
│   │   └── atoms/          # 最小UI単位
│   │       ├── button/
│   │       ├── input/
│   │       └── ...
│   ├── domains/            # 業務領域コンポーネント
│   │   ├── atoms/          # ドメイン固有のatoms
│   │   ├── molecules/      # atoms組み合わせ（小機能）
│   │   ├── organisms/      # 複雑UI部件（完全機能）
│   │   └── templates/      # ページレイアウト骨格
│   └── [legacy]/           # レガシー・移行中
├── composables/            # 組み合わせ関数（API、ビジネスロジック）
├── stores/                 # Pinia状態管理
├── utils/                  # ユーティリティ関数
├── types/                  # TypeScript型定義
├── locales/                # 国際化（i18n）
├── middleware/             # ミドルウェア
├── plugins/                # プラグイン
└── assets/                 # 静的資産
    ├── styles/             # スタイル
    │   ├── colors-primitive.css  # 基本色
    │   ├── tokens.css            # デザイントークン
    │   └── tokens-ui.css         # UI語義トークン
    └── icons/              # カスタムアイコン

層別定義と責任 ⭐⭐⭐

1. Atoms - 最小UI単位

責務：単一UI要素、再利用可能な基本単位

// 例: src/components/common/atoms/button/tao-button.vue
// - Element Plus を包装
// - デザイントークン適用
// - ビジネスロジック無し
// - Props のみで制御

必須条件：

Element Plus原生コンポーネント包装
設計トークンで全スタイル定義
副作用なし（純粋コンポーネント）
Propsで完全制御可能

配置: src/components/common/atoms/

2. Molecules - Atoms の組み合わせ

責務：複数atomsの論理的組み合わせ、小機能実装

必須条件：

同一ページ内で3回以上使用時のみ作成
特定交互パターン実装（検索ボックス、フォーム行）
簡易バリデーション・状態ロジック可 -複数pages/organismsで再利用

配置: src/components/domains/[domain-name]/molecules/

3. Organisms - 複雑UI部件

責務：完全なUI部件、複数機能統合

必須条件：

完全な状態管理（Pinia連携可）
API連携・データ取得 -複数molecules/atoms組み合わせ
ページ間再利用可能

配置: src/components/domains/[domain-name]/organisms/

4. Templates - ページレイアウト骨格

責務：ページ構造定義、レイアウトフレーム

必須条件：

ページ構造区域定義のみ
3種類以上異なるページで使用
ビジネスロジック無し（占位エリアのみ）

配置: src/components/domains/[domain-name]/templates/

5. Pages - ルーティング単位

責務：Nuxt3ファイルベースルーティング

必須条件：

src/pages/ディレクトリに配置
URLパス対応
レイアウト選択可
organismsを組み合わせ

配置: src/pages/[route-path].vue

6. Composables - ロジック集約

責務：API呼び出し、ビジネスロジック、再利用関数

// 例: src/composables/useBookingApi.ts
export const useBookingApi = () => {
  // API呼び出し集約
  // ビジネスロジック
  // 状態管理統合
  return { /* ... */ }
}

必須条件：

すべてのAPI呼び出しをここに集約
エラーハンドリング実装
型安全（完全TypeScript）
再利用可能な関数形式

配置: src/composables/use[Feature]Api.ts

7. Stores - 状態管理（Pinia）

責務：グローバル状態管理

// 例: src/stores/useBookingStore.ts
export const useBookingStore = defineStore('booking', () => {
  // グローバル状態
  // アクション
  // ゲッター
})

配置: src/stores/use[Feature]Store.ts

8. Utils - ユーティリティ関数

責務：共通機能、計算ロジック、フォーマット

// 例: src/utils/dateUtils.ts
// 日付フォーマット、計算など

配置: src/utils/[util-name].ts

📡 通信仕様 ⭐⭐⭐

システム内部通信 (REST + JSON)

標準メッセージ構造：

{
  messageId: string,      // メッセージID（追跡用）
  data: T | null,         // レスポンスデータ
  error: {
    code: string,         // エラーコード
    message: string,      // エラーメッセージ（国際化済み）
    details?: any         // エラー詳細
  } | null
}

外部システム連携

RADIXX API：外部システム統合
SQS イベント通知：非同期イベント処理
最終的整合性のためのトランザクション補償：イベント駆動設計で最終一致性確保

API 呼び出し規約 ⭐⭐⭐

必須実装：

集中管理：すべてのAPI呼び出しを composables/ に集約

// 例: src/composables/useBookingApi.ts
export const useBookingApi = () => {
  const { $fetch } = useNuxtApp()

  // API呼び出し
  const fetchAvailability = async (params: SearchParams) => {
    try {
      return await $fetch('/api/availability', { query: params })
    } catch (error) {
      // エラーハンドリング
    }
  }

  return { fetchAvailability }
}

エラーハンドリング：統一エラー処理、ユーザーフレンドリーメッセージ
型安全：API レスポンス完全TypeScript型定義必須
ロード状態：loading状態管理実装
リトライ機構：ネットワークエラー時の適切なリトライロジック

$fetch 使用規約

禁止: axios使用禁止（$fetch を使用）
推奨：Nuxt3組み込み$fetch APIを優先使用
認証：認証トークンは自動付与（middleware/auth.ts）

📁 ディレクトリ構成（Nuxt3）⭐⭐⭐

frontend/
├── pages/               # ページコンポーネント（ファイルルート）
├── components/          # Atomic Design コンポーネント
│   ├── common/
│   │   └── atoms/       # 基本UI（Element Plus包装）
│   └── domains/         # 業務領域コンポーネント
│       ├── atoms/       # ドメイン固有atoms
│       ├── molecules/   # atoms組み合わせ
│       ├── organisms/   # 複雑UI部件
│       └── templates/   # ページレイアウト
├── composables/         # 組み合わせ関数（API、ロジック）
├── stores/              # Pinia状態管理
├── utils/               # ユーティリティ関数
├── types/               # TypeScript型定義
├── locales/             # 国際化（i18n）
│   ├── en/
│   │   └── common.ts    # 英語翻訳
│   └── ja/
│       └── common.ts    # 日本語翻訳
├── middleware/          # ミドルウェア（ルート保護など）
├── plugins/             # プラグイン（初期化など）
├── assets/
│   ├── styles/          # スタイルファイル
│   │   ├── colors-primitive.css  # 基本色定義
│   │   ├── tokens.css             # デザイントークン
│   │   └── tokens-ui.css          # UI語義トークン
│   ├── icons/           # カスタムアイコン
│   └── images/          # 画像資産
├── app.vue              # ルートコンポーネント
└── nuxt.config.ts       # Nuxt設定

├── pages/ # 页面组件（文件路由） ├── components/ # Atomic Design组件 │ ├── atoms/ # 原子组件（包装Element Plus） │ ├── molecules/ # 分子组件（小功能组合） │ ├── organisms/ # 有机体组件（复杂UI部件） │ ├── templates/ # 模板组件（页面布局） │ └── domains/ # 领域组件（业务特定） ├── composables/ # 组合式函数（API、业务逻辑） ├── stores/ # Pinia状态存储 ├── utils/ # 工具函数 ├── types/ # TypeScript类型定义 └── assets/ # 静态资源 ├── styles/ # 样式文件 │ ├── tokens.css # 设计令牌定义 │ └── tokens-ui.css # UI语义化令牌 └── icons/ # 自定义图标组件


---

## 🎨 コンポーネント規約

### コンポーネント配置規則 ⭐⭐⭐

**基本UI（Atoms）配置**：
- 基本UIコンポーネントは `src/components/common/atoms/` に配置
- すべて `<tao-xxx>` の命名規則に従う
- Element Plusコンポーネント包装時は元の機能を保持し、カスタマイズは設計令牌に依存

**業務領域コンポーネント配置**：
- ドメイン固有のatoms：`src/components/domains/[domain-name]/atoms/`
- molecules：`src/components/domains/[domain-name]/molecules/`
- organisms：`src/components/domains/[domain-name]/organisms/`

### 尺寸與布局 ⭐⭐⭐
- **サイズは内容ドリブン（auto）** (尺寸由内容驱动)
- **禁止使用原生HTML控件** (禁止使用原生HTML控件)
- **`div`+CSSレイアウトの代わりに`el-row`,`el-col`を使用** (使用el-row/el-col替代div + css布局)
- **子コンポーネントでのmargin禁止（親コンポーネントがgap/paddingを管理）** (子组件禁止margin，父组件管理)

### コンポーネント状態管理 ⭐⭐⭐
- **メイン層はemitを受け付けず、v-bindで一括処理** (主层使用v-bind而非emit)
- **基礎コントロール使用時はコードを熟読し、可能な限りコンポーネント自身の属性でスタイル実装** (优先使用组件属性而非custom styles)
- **再利用回数3回以上→コンポーネント化必須** (复用3次以上必须组件化)

### スタイル管理 ⭐⭐⭐
- **CSS式样はsrc\assets\styles\tokens.cssから取得** (使用tokens.css中的设计令牌)
- **尽可能用共通の式样、不足时往tokens.cssに追加** (尽可能使用现有令牌，不足时添加)
- **追加のCSS式样はtokens.css现存の内容に合わせる** (新增令牌符合现有命名)
- **禁止**：
  - ❌ `#fff`、`#000` ハードコード色
  - ❌ `12px` ハードコード寸法
  - ❌ 固定幅・高
  - ❌ inline style
  - ❌ マジックナンバー

### SFCブロック順序 ⭐⭐⭐
**必須順序**：
1. `<script setup lang="ts">` - TypeScript
2. `<template>` - テンプレート
3. `<style scoped>` - 設計令牌ベースの樣式

**禁止**：順序の逆転、ブロックの省略

### 国際化 (i18n) ⭐⭐⭐
- **画面上の文言はすべてi18n方式を使用** (所有文本使用i18n)
- **定義ファイル**：`src/locales/[lang]/common.ts`
- **参照方法**：`src/pages/booking/availability-inquiry.vue`を参考

**標準アクセスパターン**：
```typescript
t('common.navigation.xxx')    // ナビゲーション関連
t('common.booking.xxx')       // 予約関連
t('common.pages.xxx')         // ページ標題
t('common.header.xxx')        // ページヘッダー
t('common.buttons.xxx')       // ボタン文字
t('fields.xxx')               // フォームフィールド
t('messages.xxx')             // システムメッセージ

TypeScript规约 ⭐⭐⭐

型定義完備：すべてのProps、イベントに型定義必須
any禁止：明示的にunknownを使用
インターフェイス命名：I[ComponentName]Props、I[ComponentName]Events

コンポーネントタグ規約

kebab-case使用必須 (组件标签使用kebab-case)
例：<tao-button>, <user-form>, <booking-card>

コードコメント規約

日本語で記述 (使用日文注释)
複雑なロジック：必ず説明的なコメント追加
TODO/FIXME：仮実装時に必須記述 t(‘fields.xxx’) // フォームフィールド t(‘messages.xxx’) // システムメッセージ


---

## 🎨 デザイントークン体系 ⭐⭐⭐

### 設計令牌使用原則
**すべての色・余白・フォント・角丸はトークン必須** (所有颜色、间距、字体、圆角必须使用令牌)

### 令牌分類
1. **間距令牌**：`--spacing-*` (例：`--spacing-1`, `--spacing-2`)
2. **色令牌**：
   - 語義化：`--ui-primary`, `--ui-secondary`, `--ui-surface`
   - 原始色：`--color-*` (設計令牌内部のみ使用)
3. **フォント令牌**：`--font-*`, `--text-*`
4. **境界線令牌**：`--border-*`, `--radius-*`
5. **影令牌**：`--shadow-*`

### 禁止事項
- ❌ `#fff`、`#000` 等のハードコード色値
- ❌ `12px`、`1rem` 等のハードコード寸法値
- ❌ 固定幅（明確なビジネス要件がない限り）

### 拡張令牌規約
既存の令牌が要件を満たさない場合：
1. 既存令牌の組み合わせが使用可能かどうかを確認する
2. 新しい令牌を追加する場合は以下が必須：
   - `tokens.css` の適切なカテゴリーに追加
   - 既存の命名規則に従う（kebab-case、セマンティック優先）
   - 用途を説明する日文コメント追加
   - 既存設計システムとの整合性確保

---

## ⚙️ フロント技術規約 ⭐⭐⭐

### Vue 3 / Nuxt 3 规约
1. **Composition API优先**：使用`<script setup>`语法
2. **Props的直接変更禁止** (禁止直接修改Props)
3. **画面遷移が navigateTo()で実装されている** (页面跳转使用navigateTo())

### TypeScript规约
1. **strict模式必须启用**
2. **类型定义完备**：接口、类型别名必须明确定义
3. **泛型适当使用**：提高代码复用性和类型安全

### 状态管理 (Pinia)
1. **store命名**：`useXxxStore`格式
2. **持久化**：必要时使用sessionStorage持久化

### Vue 3 / Nuxt 3 规约
1. **Composition API优先**：使用`<script setup>`语法
2. **Props の直接変更禁止** (禁止直接修改Props)
3. **画面遷移が navigateTo()で実装されている** (页面跳转使用navigateTo())

### TypeScript规约
1. **strict模式必须启用**
2. **类型定义完备**：接口、类型别名必须明确定义
3. **泛型适当使用**：提高代码复用性和类型安全

### 状態管理 (Pinia)
1. **store命名**：`useXxxStore`格式
2. **持久化**：必要时使用sessionStorage持久化
3. **模块化**：按业务领域划分store

### 样式开发
1. **CSS Modules**：使用scoped样式
2. **设计令牌优先**：所有样式值必须来自设计令牌
3. **响应式设计**：使用CSS自定义属性实现响应式

---

## 📝 フォーム規約 ⭐⭐⭐

### 验证框架
- **Element Plus 標準バリデーションを使用** (使用Element Plus标准验证)
- **バリデーションが FormRules 形式で実装されている** (验证以FormRules形式实现)

### 实现规约
1. **formItem の prop は model と一致** (formItem的prop与model一致)
2. **formRef.validate() は必須** (必须调用formRef.validate())
3. **送信中の多重クリック防止必須** (必须防止提交期间多次点击)

### 验证规则定义
```typescript
// 使用FormRules验证
const rules: FormRules = {
  email: [
    { required: true, message: t('validation.required'), trigger: 'blur' },
    { type: 'email', message: t('validation.email'), trigger: 'blur' }
  ],
  password: [
    { required: true, message: t('validation.required'), trigger: 'blur' },
    { min: 8, message: t('validation.minLength', { length: 8 }), trigger: 'blur' }
  ]
}

表単状态管理

必须实现loading状态
必须实现错误状态显示
必须实现表单重置功能
必须实现表单数据持久化（草稿保存）

🔄 Git ワークフロー

分支策略

開発は feature/xxx (开发使用feature/xxx分支)
develop は保護ブランチ (develop是保护分支)
すべてのマージは PR 必須 (所有合并必须通过PR)

冲突处理

コンフリクト时は commit か stash (冲突时commit或stash)
同期：git reset —hard origin/develop (同步：git reset —hard origin/develop)

提交规约

提交信息格式：类型(范围): 描述
类型：feat、fix、docs、style、refactor、test、chore
描述：简明扼要的日文描述

代码审查

必须通过PR进行代码审查
审查重点：

规约符合性
设计令牌使用
类型安全性
国际化实现
测试覆盖

🧪 Storybook 規約 ⭐⭐⭐

ファイル構造

共通コンポーネント：Storybook必須 (所有UI组件必须有Storybook)

すべてのStoriesファイルはbutton.stories.tsフォーマットを参考

ページレベルStories：ページ層のみ作成 (仅创建页面层)

完全なJSDocコメント必須

OrganismsレベルStories：完全なargTypes補完必須

组件文档要求

必須内容：Props文档、Events文档、Slots文档
必須提供：使用示例、不同状态展示
必須実装：交互式控件（Controls）、操作日志（Actions）

テスト整合

Storybook与Vitest整合：組件テストケースはStorybookで実行可能
Playwright E2E테스트：主要なユーザーフロー必须有E2E테스트

📋 最終チェックリスト（提交前必须验证）⭐⭐⭐

视觉与设计

レイアウトがデザインと一致 (布局与设计一致)
ワイヤーフレーム/SVG の全要素が実装されている (线框图/SVG所有元素已实现)
デザイントークン完全適用 (设计令牌完全应用)

功能完整性

フォームバリデーション正常 (表单验证正常)
loading / error 処理実装済み (有loading/error处理)
画面遷移が navigateTo()で実装されている (页面跳转使用navigateTo())

代码质量

console.log なし (无console.log)
lint / build / type-check すべて通過 (lint/build/type-check全部通过)
SFC ブロック順序が正しい (SFC块顺序正确)
コンポーネントタグが kebab-case (组件标签为kebab-case)
ハードコード値なし (无硬编码值)

国际化

所有文本通过i18n获取 (所有文本通过i18n获取)
無硬コード日语/英语文本 (无硬编码日语/英语文本)
使用標準翻訳キー前綴 (使用标准翻译键前缀)

🛠️ 実施指南

新组件开发流程

需求分析：确认组件层次（atoms/molecules/organisms）
设计确认：验证设计令牌可用性
组件创建：参考现有组件模式
Storybook文档：立即添加完整文档
测试编写：单元测试和E2E测试
代码审查：提交PR进行审查

现有代码改造

逐步迁移：避免大规模破坏性更改
设计令牌替换：逐步替换硬编码样式
类型安全增强：添加具体类型，消除any
国际化整合：提取硬编码文本到翻译文件

AI辅助开发

提供完整上下文：包括本规约和项目标准
验证生成代码：严格检查规约符合性
补充业务逻辑：AI无法获取的业务细节

🔗 関連文档参照

核心标准文档

前端实现标准：docs/guidelines/implementation/frontend.md
组件设计指南：docs/guidelines/design/11_frontend-component-design-guidelines.md
命名规范指南：docs/guidelines/design/10_naming-conventions-guidelines.md

AI开发支持

AI前端开发上下文指南：ai-frontend-development-context.mdx
前端组件选择决策指南：component-selection-guide.mdx
前端开发者上手指南：frontend-onboarding-guide.mdx

実装教程

表单验证教程：frontend/docs/guides/validation.md
国际化教程：frontend/docs/guides/i18n.md
Mock数据实现教程：frontend/docs/guides/mock-implementation.md

設計システム

设计令牌定义：frontend/src/assets/styles/tokens.css
Storybook组件库：运行npm run storybook查看

📞 規約维护与升级

版本管理

当前版本：v1.0 (2026-02-09)
维护者：APJ-B2B前端开发团队
更新频率：随项目演进定期更新

变更流程

需求识别：团队反馈或架构演进需求
草案制定：新规约草案
团队評審：全員評審通過
文档更新：更新本规约及相关文档
团队通知：变更同步所有成员

问题反馈

规约不明确：记录具体场景，提交规约澄清请求
规约冲突：记录冲突点，提交团队讨论
规约过时：记录过时内容，提交更新建议

🎯 快速参考速查卡

组件选择速查

需求场景	解决方案	示例
按钮	`<tao-button>`	`<tao-button variant="primary">提交</tao-button>`
输入框	`<tao-input>`	`<tao-input v-model="text" placeholder="请输入">`
图标	`<icon-xxx>`	`<icon-search />` `<icon-close />`
表单	`<tao-form>` + `<tao-form-item>`	`<tao-form :rules="rules">`
复杂组件	创建`organisms/xxx.vue`	`organisms/user-form.vue`

样式速查

样式类型	正确写法	错误写法
颜色	`color: var(--ui-primary)`	`color: #ff0000`
间距	`padding: var(--spacing-2)`	`padding: 8px`
字体	`font-size: var(--text-md)`	`font-size: 14px`
圆角	`border-radius: var(--radius-md)`	`border-radius: 4px`

国际化速查

文本类型	翻译键格式	示例
页面标题	`t('common.pages.xxx')`	`t('common.pages.login')`
按钮文本	`t('common.buttons.xxx')`	`t('common.buttons.submit')`
表单字段	`t('fields.xxx')`	`t('fields.email')`
错误消息	`t('messages.xxx')`	`t('messages.invalidEmail')`

核心原則：規約不是束縛，而是高效協作的基石。嚴格遵守這些規約，確保代碼質量、設計一致性和團隊協作效率。當有疑問或特殊需求時，提交團隊討論決定，避免個人隨意決策。

最後更新: 2026-02-09 適用項目: APJ-B2B前端項目 相關標準: Atomic Design、TypeScript严格模式、設計令牌系統、Element Plus包装规范