# Frontend Development Guidelines(oci-portal-dash 前端规范)

> Vue 3 前端(`oci-portal-dash/`)编码规范入口。

---

## 技术栈约束

Vue 3 + Vite + TypeScript + Naive UI + Tailwind CSS v4 + ECharts + Pinia。Naive UI 承担组件视觉(`themeOverrides`),Tailwind 只承载设计 token 与布局工具类。

---

## Guidelines Index

| Guide | 内容 |
|-------|------|
| [Directory Structure](./directory-structure.md) | src 分层、文件命名与全局作用域约定 |
| [TypeScript & Vue](./typescript-vue.md) | TS 严格模式与组件写法 |
| [Styling & Design Tokens](./styling-design-tokens.md) | Anthropic 风设计 token、字体与反模式清单 |
| [API & State](./api-and-state.md) | 请求封装与 Pinia 使用边界 |

---

## Pre-Development Checklist

写代码前确认:

- [ ] 读过 [Directory Structure](./directory-structure.md),文件放对层(views / components / composables / api / stores / types)
- [ ] 涉及颜色、圆角、间距时先看 [Styling & Design Tokens](./styling-design-tokens.md),禁止硬编码 hex
- [ ] 新增请求走 `api/` 统一封装,DTO 类型进 `types/`(与 `docs/API接口文档.md` 一一对应)
- [ ] 出 UI 设计稿前读 `../guides/design-workflow.md`

## Quality Check

提交前必过:

```bash
npm run lint        # ESLint(flat config,含 eslint-plugin-vue recommended)+ Prettier
npm run typecheck   # vue-tsc --noEmit
npm run build       # 类型检查 + 产物构建
```

- 提交信息沿用项目规范(中文、≤50 字),不采用 Conventional Commits。
- 依赖变更后 `package.json` 与 lockfile 一起提交;不提交 `node_modules`、构建产物。