# frontend

**Repository Path**: peiqike/frontend

## Basic Information

- **Project Name**: frontend
- **Description**: Vue模版
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-14
- **Last Updated**: 2026-06-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Frontend Starter

通用 Vue 项目母板。它从现有后台工程的基础设施经验中重新整理而来，初始状态不包含
公司、后台、地图或其他具体业务代码；使用母板创建的新项目可以按自身需求扩展。

母板能力边界以 [基础设施契约](docs/foundation-contract.md) 和
[`foundation-manifest.json`](docs/foundation-manifest.json) 为准。文档不是旁路说明：
`pnpm verify:foundation` 会校验必需依赖、脚本和关键文件。母板不永久禁止任何依赖、
业务名称或源码模式，衍生项目可以自由扩展。

## 技术栈

- Vue 3、TypeScript 6、Vite 8
- Vue Router、Pinia、Pinia persisted state（主题和语言等非敏感偏好）
- VueUse（浏览器能力与通用 Composition 工具）
- Vue I18n（中文/英文、持久化、DOM 与路由标题同步）
- Axios 通用 HTTP 客户端
- UI 组件库中立（原生控件示例，可由具体项目按需接入）
- SVG Sprite、Sass、date-fns
- ESLint、Prettier、Stylelint、EditorConfig
- Vitest、Vue Test Utils
- Husky、lint-staged、Commitlint、GitHub Actions
- OpenAPI Generator
- Knip 依赖使用检查与基础设施契约校验

## 开始使用

```bash
# 启用 Node 自带的 Corepack，使项目使用 package.json 锁定的 pnpm 版本。
corepack enable

# 根据 pnpm-lock.yaml 安装依赖；首次执行需要访问 npm registry。
pnpm install

# 创建开发模式的本机覆盖文件；该文件不会提交到 Git。
cp .env.example .env.development.local

# 启动 Vite 开发服务器，并监听源码变化进行热更新。
pnpm dev
```

开发、生产和本机覆盖文件的加载优先级，以及新增环境模式的方法，见
[环境变量与模式](docs/environment-variables.md)。

## 项目结构

完整目录树、逐文件职责、生成文件说明、业务放置规则和注释规范见
[项目结构与文件职责](docs/project-structure.md)。

写完代码后如何格式化、检查、提交、推送、打包和发布验收，见
[开发与提交操作手册](docs/development-workflow.md)。

语言资源、运行链路和新增语言步骤见
[国际化维护说明](docs/internationalization.md)。

为什么母板不预装 UI 组件库，以及子项目如何接入 Element Plus 等方案，见
[UI 组件库策略](docs/ui-library.md)。

## 新同事阅读顺序

第一次接手项目时，建议按以下顺序阅读：

1. 当前 `README.md`：了解项目定位、技术栈、启动方式和文档入口。
2. [开发与提交操作手册](docs/development-workflow.md)：掌握开发、格式化、提交、推送、打包和验收。
3. [项目结构与文件职责](docs/project-structure.md)：了解目录结构、关键文件、业务放置规则和修改边界。
4. [基础设施契约](docs/foundation-contract.md)：了解母板保证的能力、依赖策略和基建变更规则。
5. [环境变量与模式](docs/environment-variables.md)：掌握开发、生产、本机覆盖和新增环境模式。
6. 根据当前任务按需阅读 [命令参考](docs/commands.md)、[国际化维护说明](docs/internationalization.md)
   和 [UI 组件库策略](docs/ui-library.md)。

`docs/audits/` 记录历史变更与验收证据，`docs/superpowers/` 记录设计和实施过程；两者不是日常入门必读，
在追溯技术决策或审核基建变更时再查阅。

## 验证命令

完整命令用途、是否修改文件以及是否需要联网，见 [命令参考](docs/commands.md)。

```bash
# 仅执行 TypeScript/Vue 类型检查，不生成构建文件。
pnpm typecheck

# 检查 TypeScript、JavaScript 和 Vue 代码规范，不自动修改文件。
pnpm lint

# 对 Git 暂存文件执行 ESLint、Stylelint 和 Prettier 自动修复。
pnpm lint:staged

# 检查 Vue、CSS 和 SCSS 样式规范，不自动修改文件。
pnpm stylelint

# 以单次运行模式执行全部 Vitest 单元测试。
pnpm test

# 检查所有受管文件是否符合 Prettier 格式，不自动修改文件。
pnpm format:check

# 使用 Knip 检查未使用的依赖、文件和导出。
pnpm deps:unused

# 校验母板必需依赖、脚本和关键文件。
pnpm verify:foundation

# 根据 openapi/example.yaml 重建 src/api/generated；会修改生成目录。
pnpm api:generate

# 先执行类型检查，再生成 dist 生产构建产物。
pnpm build

# 执行母板完整离线验收：契约、Knip、质量检查、测试、生成和构建。
pnpm verify:full
```

联网检查所有直接依赖是否仍为最新稳定版：

```bash
# 联网查询 npm registry，检查直接依赖是否仍为最新稳定版。
pnpm deps:latest

# 联网查询 npm 安全公告，检查依赖树中的已知漏洞。
pnpm deps:audit
```

日常开发通常只需要 `pnpm dev`。Husky 会在提交时自动处理暂存文件，在推送时执行
`pnpm check`；GitHub Actions 使用 `pnpm verify:full` 做最终完整验收。`deps:latest` 和
`deps:audit` 属于联网检查，不包含在离线完整验收中。

## 使用原则

- `src/api/http` 不假设后端业务响应码，只处理 HTTP、Token 和错误标准化。
- 路由权限通过 `meta.requiresAuth` 表达，不内置角色、菜单或 ACL 模型。
- 页面文案使用 Vue I18n 语言键，语言选择由应用 Store 持久化。
- OpenAPI 使用本地 `openapi/example.yaml` 演示，替换输入文件即可接入真实后端。
- 登录页仅证明 Session Store 和路由守卫有效，接入项目时应替换为真实认证模块。
- 演示会话不持久化 access token；真实项目应根据 Web 或原生容器选择安全的认证介质。
- 顶部进度条、骨架屏和局部 Loading 属于项目体验层，母板不预设具体方案。
- 地图 SDK、Capacitor 和具体 UI 组件库未在核心母板中预装，衍生项目可作为独立能力接入。

## 文档即契约

- [基础设施契约](docs/foundation-contract.md)：能力清单、原项目对齐关系和业务边界。
- [命令参考](docs/commands.md)：全部脚本的用途、副作用和执行时机。
- [开发与提交操作手册](docs/development-workflow.md)：从开发、格式化到提交、打包的完整步骤。
- [项目结构与文件职责](docs/project-structure.md)：完整目录、文件作用和修改边界。
- [环境变量与模式](docs/environment-variables.md)：开发、生产、本机覆盖和自定义模式配置。
- [国际化维护说明](docs/internationalization.md)：语言资源、状态同步和扩展规则。
- [UI 组件库策略](docs/ui-library.md)：UI 中立边界和子项目接入步骤。
- [本阶段审计记录](docs/audits/2026-06-13-foundation-audit.md)：依赖升级与验证结果。
- [VueUse 接入记录](docs/audits/2026-06-14-vueuse-integration.md)：接入边界、真实用例和验证结果。
- [NProgress 移除记录](docs/audits/2026-06-14-nprogress-removal.md)：加载反馈的项目级边界。
- [date-fns 迁移记录](docs/audits/2026-06-14-date-fns-migration.md)：日期工具选型和迁移验证。
- [代码质量门禁记录](docs/audits/2026-06-14-code-quality-gates.md)：Git 钩子、CI 和仓库规范。
- [首次提交前终审](docs/audits/2026-06-14-pre-commit-review.md)：密钥、依赖、钩子、安全默认值和构建验收。
- [`foundation-manifest.json`](docs/foundation-manifest.json)：由脚本执行的机器可读规则。

## License

本项目采用 [MIT License](LICENSE)。