pandax 0.0.1

package/skills/pandax-frontend-standards/SKILL.md

@@ -0,0 +1,468 @@
+---
+name: "pandax-frontend-standards"
+category: "frontend"
+description: "统一引用前端规范文档。Invoke when 前端开发涉及命名、目录结构、组件设计、API、Git、文案等规范问题，或需要先读取团队规范再执行任务。"
+---
+
+# Pandax 前端规范总览
+
+本 skill 是 Pandax 前端规范的统一入口。当前端任务涉及命名、目录、组件、API、Git、文案等规范问题时，先读取本 skill 明确的规范文档位置，再按规范执行。
+
+## 触发条件
+
+- 用户提到"按规范"、"符合规范"、"规范怎么定"
+- 开发前需要确认命名规则、目录结构、组件设计方式
+- 代码审查时发现风格不一致，需要引用规范
+- 新成员加入，需要了解前端项目约定
+- 其他 Pandax skill（如 component-review、api-mock）执行时需要引用规范
+
+## 规范文档位置
+
+项目内统一放在 `docs/standards/` 目录下：
+
+```text
+docs/standards/
+├── README.md              # 规范总览和索引
+├── code-style.md          # 代码风格与命名规范
+├── component.md           # 组件规范
+├── api.md                 # API 对接规范
+├── git-workflow.md        # Git 工作流规范
+└── copywriting.md         # 中文文案排版规范
+```
+
+如果项目中不存在 `docs/standards/`，则先询问用户规范文档存放在哪里，或按本 skill 的默认约定创建。
+
+## 规范条目速查
+
+### 1. 目录结构
+
+```text
+src/
+├── apis/                   # API 请求封装与接口定义
+├── assets/                # 静态资源（图片、字体、图标）
+├── components/            # 通用业务组件
+│   └── button/
+│       ├── index.ts
+│       ├── index.vue
+│       └── index.spec.ts
+├── composables/           # Vue 组合式函数（推荐）
+│   └── use-modal/
+│       ├── index.ts
+│       ├── Types.ts
+│       └── Config.ts
+├── hooks/                 # React Hooks 或 Vue 组合式函数（项目统一即可）
+├── directives/            # 自定义指令
+├── layouts/               # 页面布局组件
+├── router/                # 路由配置
+├── stores/                # 状态管理
+├── styles/                # 全局样式、变量、mixins
+├── types/                 # 全局类型定义
+├── utils/                 # 工具函数
+└── views/                 # 页面级组件
+```
+
+### 2. 文件与命名规范
+
+**总原则：** `src/` 目录下，**所有目录名统一使用全小写**（多词用短横线连接）；**入口文件 `index.*` 使用全小写**；**其他所有文件统一使用 PascalCase**。
+
+| 类型 | 命名方式 | 示例 |
+|------|---------|------|
+| Vue 单文件组件 | 全小写 | `components/user-profile/index.vue` |
+| 组件目录 | 全小写 + 短横线 | `components/user-profile/` |
+| 组件入口文件 | `index.ts` | `components/user-profile/index.ts` |
+| 工具函数文件 | PascalCase | `utils/DateUtil.ts` |
+| 常量文件 | PascalCase | `constants/ApiTimeout.ts` |
+| TypeScript 接口 | PascalCase | `types/UserInfo.ts` |
+| TypeScript 类型别名 | PascalCase | `types/FetchStatus.ts` |
+| 枚举 | PascalCase，成员 UPPER_SNAKE_CASE | `constants/StatusCode.ts` |
+| 测试文件 | 与被测文件同名 + `.spec.ts` | `components/user-profile/index.spec.ts` |
+
+#### 特殊目录后缀约定
+
+以下目录中的文件（除 `index.*` 外）必须按职责追加统一后缀：
+
+| 目录 | 文件命名后缀 | 示例 |
+|------|-------------|------|
+| `src/apis/` | `Api` | `UserApi.ts`、`OrderApi.ts` |
+| `src/services/` | `Service` | `UserService.ts`、`OrderService.ts` |
+| `src/utils/` | `Util` | `DateUtil.ts`、`StorageUtil.ts` |
+
+**注意：** 这些目录内的 `index.ts` 仍保持小写，用于统一导出。导出时也不得省略统一后缀，如 `export { UserApi } from './UserApi'`。
+
+### 3. 组件规范
+
+#### 通用原则
+
+- 单一组件文件行数不宜超过 300 行
+- Props 必须声明类型；可选 Props 设置默认值，必填 Props 不设置默认值
+- boolean 类型 props 命名应为形容词，如 `disabled`、`visible`
+- 事件名使用 `onXxx` 或 `xxxChange`
+- Vue 单文件组件使用 `scoped` 或 CSS Modules
+- React 优先使用 CSS Modules / styled-components
+
+#### Vue3 组件结构
+
+Vue3 组件目录采用**全小写 + 短横线**命名，组件内部文件统一如下：
+
+```text
+app-register/                 # 组件目录：全小写 + 短横线
+├── index.vue                 # 组件默认入口
+├── Prop.ts                   # Props 定义
+├── Type.ts                   # 组件相关 TypeScript 类型定义
+└── index.module.scss         # 组件样式（CSS Modules）
+```
+
+子组件同样遵循该结构，放在当前组件的 `components/` 目录下：
+
+```text
+app-register/
+├── index.vue
+├── Prop.ts
+├── Type.ts
+├── index.module.scss
+└── components/               # 当前组件的私有子组件
+    ├── sub-title/            # 子组件目录：全小写 + 短横线
+    │   ├── index.vue
+    │   ├── Prop.ts
+    │   ├── Type.ts
+    │   └── index.module.scss
+    └── info-card/
+        ├── index.vue
+        ├── Prop.ts
+        ├── Type.ts
+        └── index.module.scss
+```
+
+**原子化原则**：
+
+- 组件应尽可能原子化，一个组件只做一件事
+- 如果组件内部出现可复用的 UI 片段，应拆分为 `components/` 下的子组件
+- 子组件的拆分深度不超过 3 层，避免过度嵌套
+- 每个子组件同样遵循 `index.vue + Prop.ts + Type.ts + index.module.scss` 结构
+
+#### Vue3 组件代码组织
+
+必须使用 `<script setup lang="ts">` 语法。
+
+`index.vue` 内部按以下顺序和 `// #region` 注释块组织代码。即使某个区域暂时没有逻辑，也必须保留该区域注释和一句话说明，方便后续维护。
+
+```vue
+<script setup lang="ts">
+import { ref, computed, watch, onMounted } from 'vue';
+import { props } from './Prop';
+import type { FormState } from './Type';
+
+// #region Props - 组件属性定义
+// #endregion
+
+// #region Types - 组件内部类型
+// #endregion
+
+// #region State - 响应式数据
+const count = ref(0);
+const form = reactive<FormState>({ name: '' });
+// #endregion
+
+// #region Computed - 计算属性
+const doubleCount = computed(() => count.value * 2);
+// #endregion
+
+// #region Watch - 监听器
+watch(count, (newVal) => {
+  console.log(newVal);
+});
+// #endregion
+
+// #region Lifecycle - onBeforeMount
+// 在挂载开始之前调用：适合获取初始数据前的准备工作
+// 当前组件未使用
+// #endregion
+
+// #region Lifecycle - onMounted
+// 组件挂载完成后调用：适合发起请求、操作 DOM、订阅事件
+// onMounted(() => { fetchData() })
+// #endregion
+
+// #region Lifecycle - onBeforeUpdate
+// 组件更新前调用：适合获取更新前的 DOM 状态
+// 当前组件未使用
+// #endregion
+
+// #region Lifecycle - onUpdated
+// 组件更新后调用：适合操作更新后的 DOM
+// 当前组件未使用
+// #endregion
+
+// #region Lifecycle - onBeforeUnmount
+// 组件卸载前调用：适合移除事件监听、清理定时器
+// 当前组件未使用
+// #endregion
+
+// #region Lifecycle - onUnmounted
+// 组件卸载后调用：适合彻底清理副作用
+// 当前组件未使用
+// #endregion
+
+// #region Methods - 组件内部方法
+const increment = () => {
+  count.value++;
+};
+// #endregion
+
+// #region Expose - 对外暴露
+// defineExpose({ increment });
+// #endregion
+</script>
+```
+
+**代码组织约定**：
+
+- `import` 语句统一放在 `<script setup>` 最顶部，不需要包 region
+- 从 `Props` 开始，每个区域用 `// #region` / `// #endregion` 包裹
+
+**Region 顺序**：
+
+1. `Props` - 属性定义
+2. `Types` - 内部类型
+3. `State` - 响应式数据
+4. `Computed` - 计算属性
+5. `Watch` - 监听器
+6. `Lifecycle` - 生命周期钩子（按执行顺序）
+7. `Methods` - 组件方法
+8. `Expose` - 对外暴露
+
+**生命周期占位规则**：
+
+- 即使当前组件没有对应逻辑，也必须保留生命周期 region
+- 未使用的生命周期：写一句话用途说明 + `// 当前组件未使用` 占位
+- 已使用的生命周期：写一句话用途说明 + 一行注释示例（可选）
+- 禁止写空函数调用，如 `onBeforeMount(() => {})`
+
+这有助于：
+
+- 统一代码结构，降低阅读成本
+- 提示开发者未来可以在哪个阶段添加逻辑
+- 便于代码审查时快速定位生命周期使用
+
+### 4. 页面规范（views）
+
+#### 目录结构
+
+`src/views/` 下按业务模块组织页面，页面目录采用**全小写 + 短横线**命名：
+
+```text
+src/views/
+├── user-management/              # 用户管理模块
+│   ├── index.vue                 # 列表页（默认入口）
+│   ├── Prop.ts                   # 页面级 props（如有）
+│   ├── Type.ts                   # 页面相关类型
+│   ├── index.module.scss         # 页面样式
+│   ├── components/               # 本页面私有组件
+│   │   ├── user-form/
+│   │   │   ├── index.vue
+│   │   │   ├── Prop.ts
+│   │   │   ├── Type.ts
+│   │   │   └── index.module.scss
+│   │   └── user-filter/
+│   │       ├── index.vue
+│   │       ├── Prop.ts
+│   │       ├── Type.ts
+│   │       └── index.module.scss
+│   └── pages/                    # 用户管理下的子页面
+│       ├── create/               # 新建用户页
+│       │   └── index.vue
+│       ├── detail/               # 用户详情页
+│       │   └── index.vue
+│       └── edit/                 # 编辑用户页
+│           └── index.vue
+└── order-management/
+    ├── index.vue
+    ├── components/
+    └── pages/
+```
+
+#### 子页面命名规则
+
+| 位置 | 推荐命名 | 说明 |
+|------|---------|------|
+| `views/{module}/pages/` 下 | 简短动词 | 如 `create/`、`edit/`、`detail/`，上下文已明确 |
+| `views/` 顶层 | 完整语义 | 如 `user-create/`、`order-detail/`，避免歧义 |
+
+#### 新增/编辑复用规则
+
+新增和编辑页面 UI 相似时，**合并为同一个表单页**，目录名用 `form/`：
+
+```text
+user-management/
+├── index.vue
+└── pages/
+    └── form/                     # 新增/编辑共用页
+        ├── index.vue
+        ├── Prop.ts
+        ├── Type.ts
+        └── index.module.scss
+```
+
+路由配置：
+
+```ts
+{
+  path: '/user-management',
+  component: () => import('@/views/user-management/index.vue'),
+  children: [
+    { path: 'create', component: () => import('@/views/user-management/pages/form/index.vue') },
+    { path: 'edit/:id', component: () => import('@/views/user-management/pages/form/index.vue') },
+  ],
+}
+```
+
+页面内部通过路由参数判断模式：
+
+```ts
+// #region State - 响应式数据
+const route = useRoute();
+const id = computed(() => route.params.id as string | undefined);
+const isEdit = computed(() => !!id.value);
+// #endregion
+
+// #region Lifecycle - onMounted
+// 编辑模式时查询详情并回显
+// onMounted(() => { if (isEdit.value) fetchDetail(id.value) })
+// #endregion
+
+// #region Methods - 组件内部方法
+// const submit = async (values) => {
+//   if (isEdit.value) await updateUser({ ...values, id: id.value })
+//   else await createUser(values)
+// }
+// #endregion
+```
+
+#### 拆分原则
+
+满足以下任一条件时，才将新增和编辑拆分为两个独立页面：
+
+- 新增和编辑的 UI 差异超过 50%
+- 编辑页需要额外的大量权限控制或状态管理
+- 新增和编辑的表单字段差异很大
+
+否则一律合并为 `pages/form/`。
+
+#### 新增/编辑容器选择规则
+
+列表页中的新增/编辑操作，按以下优先级选择容器：
+
+1. **用户明确指定**：用户说用独立页面/弹窗/抽屉，就按用户要求
+2. **默认使用抽屉（Drawer）**：用户未指定时，默认用抽屉
+3. **独立页面**：需要独立路由、可被外部直接访问、或用户明确要求页面时
+4. **弹窗（Modal）**：用户明确要求弹窗时
+
+**目录结构对应关系**：
+
+| 容器类型 | 组件位置 | 路由 |
+|---------|---------|------|
+| 独立页面 | `views/user-management/pages/form/` | 有独立路由 |
+| 抽屉 | `views/user-management/components/user-form-drawer/` | 无独立路由 |
+| 弹窗 | `views/user-management/components/user-form-modal/` | 无独立路由 |
+
+**抽屉/弹窗组件拆分**：
+
+如果新增/编辑共用同一个表单，建议拆成容器 + 表单两层：
+
+```text
+user-management/
+├── components/
+│   ├── user-form-drawer/         # 抽屉容器（负责显隐、标题、底部按钮）
+│   │   ├── index.vue
+│   │   ├── Prop.ts
+│   │   ├── Type.ts
+│   │   └── index.module.scss
+│   └── user-form/                # 纯表单组件（业务字段、校验逻辑）
+│       ├── index.vue
+│       ├── Prop.ts
+│       ├── Type.ts
+│       └── index.module.scss
+```
+
+- `user-form-drawer`：负责 `visible`、标题、提交/取消按钮
+- `user-form`：负责表单字段、校验、收集数据
+
+如果不需要复用，也可以直接把表单写在抽屉组件内。
+
+**调用示例**：
+
+```ts
+// #region State - 响应式数据
+const drawerVisible = ref(false);
+const editingId = ref<string | undefined>(undefined);
+const isEdit = computed(() => !!editingId.value);
+// #endregion
+
+// #region Methods - 组件内部方法
+const openCreateDrawer = () => {
+  editingId.value = undefined;
+  drawerVisible.value = true;
+};
+
+const openEditDrawer = (id: string) => {
+  editingId.value = id;
+  drawerVisible.value = true;
+};
+
+const handleSubmit = async (values: UserFormData) => {
+  if (isEdit.value) {
+    await updateUser({ ...values, id: editingId.value });
+  } else {
+    await createUser(values);
+  }
+  drawerVisible.value = false;
+};
+// #endregion
+```
+
+### 5. API 规范
+
+- 所有请求必须通过统一的请求客户端
+- 按业务模块划分 API 文件，如 `apis/UserApi.ts`
+- 函数名使用 `动词 + 名词`，如 `getUserList`
+- 请求参数与响应数据必须定义 TypeScript 接口
+- Mock 数据与真实响应结构保持一致
+
+### 6. Git 规范
+
+- 分支命名：
+  - 功能分支：`feature/xxx`
+  - 修复分支：`fix/xxx`
+  - 热修复分支：`hotfix/xxx`
+- Commit message 使用 Conventional Commits
+  - `feat:` 新功能
+  - `fix:` 修复
+  - `docs:` 文档
+  - `style:` 格式调整
+  - `refactor:` 重构
+  - `test:` 测试
+  - `chore:` 构建/工具
+
+### 7. 文案规范
+
+- 中英文之间加空格
+- 中文与数字之间加空格
+- 中文标点使用全角
+- 界面文案避免机器翻译腔
+- 按钮使用具体动作，如"保存"、"确认删除"
+
+## 执行规则
+
+1. 当任务涉及规范问题时，先读取 `docs/standards/README.md`
+2. 根据具体场景读取对应规范文件：
+   - 命名 / 代码风格 → `code-style.md`
+   - 组件设计 → `component.md`
+   - API 对接 → `api.md`
+   - Git 提交 → `git-workflow.md`
+   - 中文文案 → `copywriting.md`
+3. 如果规范文件不存在，向用户说明缺少的文档，并建议使用本 skill 的默认约定
+4. 执行任务时严格遵循已读取的规范
+
+## 输出要求
+
+引用规范执行任务后，简要说明依据了哪条规范，方便用户理解和复核。