仓库自包含化：CI/文档/规范入库，升级 echarts，填关于页链接

.trellis/spec/frontend/api-and-state.md

@@ -0,0 +1,5 @@
+# API 层与状态管理规范
+
+- 所有请求经统一 request 封装(`src/api/request`):注入 JWT、401 统一跳登录、错误统一提示;组件内不直接 `fetch`/裸 axios。
+- 跨页面共享状态才进 Pinia;页面内状态用 `ref`/`computed` 就地管理,不把一切塞 store。
+- 请求函数返回类型化数据(`Promise<Instance[]>`),错误向上抛由封装层兜底,不在每个调用点重复 try/catch。

.trellis/spec/frontend/component-guidelines.md

@@ -0,0 +1,59 @@
+# Component Guidelines
+
+> How components are built in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's component conventions here.
+
+Questions to answer:
+- What component patterns do you use?
+- How are props defined?
+- How do you handle composition?
+- What accessibility standards apply?
+-->
+
+(To be filled by the team)
+
+---
+
+## Component Structure
+
+<!-- Standard structure of a component file -->
+
+(To be filled by the team)
+
+---
+
+## Props Conventions
+
+<!-- How props should be defined and typed -->
+
+(To be filled by the team)
+
+---
+
+## Styling Patterns
+
+<!-- How styles are applied (CSS modules, styled-components, Tailwind, etc.) -->
+
+(To be filled by the team)
+
+---
+
+## Accessibility
+
+<!-- A11y requirements and patterns -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- Component-related mistakes your team has made -->
+
+(To be filled by the team)

.trellis/spec/frontend/directory-structure.md

@@ -0,0 +1,36 @@
+# 前端目录结构
+
+> Vue 3 前端工程的目录职责与命名约定。
+
+## 目录职责
+
+```text
+oci-portal-dash/
+├── package.json        脚本 dev / build / typecheck / lint / format
+├── vite.config.ts      @ 别名指向 src/;dev 代理 /api → localhost:8080
+├── .env.development    VITE_MOCK=1,开发默认走内置 mock 数据
+├── index.html
+└── src/
+    ├── main.ts         应用入口,挂 Pinia 与 router
+    ├── App.vue         NConfigProvider 注入 Naive 主题
+    ├── assets/         main.css:Tailwind @theme 设计 token(浅色)+ html.dark 暗色变量覆盖与全局基础样式
+    ├── theme/          tokens.ts(JS 侧 token 唯一来源,含 darkTokens 暗色板)、naive.ts(亮暗两套 themeOverrides 同一工厂生成)
+    ├── types/          api.ts:与 docs/API接口文档.md 一一对应的 DTO 类型
+    ├── api/            request 封装(JWT 注入、401 跳登录、错误 hint 拼接)+ 按资源分模块;VITE_MOCK=1 时返回 mock.ts 数据
+    ├── stores/         Pinia:auth(令牌持久化)、app(侧栏收缩、暗色主题:默认跟随系统 + localStorage 记忆,驱动 html.dark 与 Naive darkTheme)、scope(全局作用域:租户/区域/区间,localStorage 按租户记忆)
+    ├── router/         路由与登录守卫
+    ├── composables/    useAsync(异步状态)、useFormat(时间/字节/OCID 格式化)、useRegionAlias(区域友好名)、useTransientPoll(过渡态自动轮询:实例电源 / 挂载操作后每 5 秒刷新至稳态)
+    ├── components/     StatusBadge、OcidText、CostChart 等复用组件;表单基座 FormModal / FormField(hint 问号 tooltip + error / feedback 下置提示)/ FormSection(分组标题)/ FilePicker(含 compact 单行态)/ AppInputNumber(数字框统一封装:右侧垂直上下箭头步进);tenant/ 下为租户详情各 tab 与失联占位 DeadPlaceholder(失联时整体替换 tab 内容),storage/ 下为引导卷编辑 / 挂载弹窗,task/ 下含 CronEditor 可视化编辑器与任务表单(tab 分类型),instance/ 下含 InstanceSpecForm(实例规格表单,创建实例弹窗与抢机任务共用),logs/ 下为日志页各 tab 面板(SystemLogPanel 系统日志、LogEventPanel 回传日志)
+    ├── layouts/        AppLayout(顶栏 + 内容区,顶栏右侧为全局作用域租户 / 区域选择器)、SidebarNav(分组导航、收缩态)
+    └── views/          页面:登录、总览、租户列表/详情、实例列表/详情、网络、VCN 详情、引导卷列表(编辑 / 挂载 / 删除以弹窗内联完成,无单独详情页)、任务、日志(tab 结构:「系统日志」操作留痕,预留回传日志)、设置(tab 结构:「通知」通知管理 + Telegram 配置,「任务」抢机熔断阈值)等
+```
+
+## 全局作用域约定
+
+租户 / 区域在顶栏右上角全局选择,区间在各资源列表页内选择,三者经 scope store 全站共享——实例 / 网络 / 引导卷页跟随同一作用域查询单租户数据,切页无需重选;选择按租户记忆在 localStorage,未开启多区域 / 多区间支持的租户对应选择器禁用锁定默认值。租户导入 / 修改 / 删除 / 测活、订阅新区域成功后经 `scope.refreshConfigs()` 即时刷新全局选择器,无需刷新页面。
+
+## 命名约定
+
+- `src/` 下按职责分层:`views/`(页面)、`components/`(复用组件)、`composables/`、`api/`(接口封装)、`stores/`(Pinia)、`types/`、`assets/`。
+- 组件文件 PascalCase(`TaskLogDrawer.vue`),composable/工具文件 camelCase,路由路径 kebab-case。
+- `api/` 模块按后端资源划分(`instances.ts`、`tasks.ts`…),函数名与接口语义对应,不散调 axios。

.trellis/spec/frontend/hook-guidelines.md

@@ -0,0 +1,51 @@
+# Hook Guidelines
+
+> How hooks are used in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's hook conventions here.
+
+Questions to answer:
+- What custom hooks do you have?
+- How do you handle data fetching?
+- What are the naming conventions?
+- How do you share stateful logic?
+-->
+
+(To be filled by the team)
+
+---
+
+## Custom Hook Patterns
+
+<!-- How to create and structure custom hooks -->
+
+(To be filled by the team)
+
+---
+
+## Data Fetching
+
+<!-- How data fetching is handled (React Query, SWR, etc.) -->
+
+(To be filled by the team)
+
+---
+
+## Naming Conventions
+
+<!-- Hook naming rules (use*, etc.) -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- Hook-related mistakes your team has made -->
+
+(To be filled by the team)

.trellis/spec/frontend/index.md

@@ -0,0 +1,44 @@
+# 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`、构建产物。

.trellis/spec/frontend/quality-guidelines.md

@@ -0,0 +1,51 @@
+# Quality Guidelines
+
+> Code quality standards for frontend development.
+
+---
+
+## Overview
+
+<!--
+Document your project's quality standards here.
+
+Questions to answer:
+- What patterns are forbidden?
+- What linting rules do you enforce?
+- What are your testing requirements?
+- What code review standards apply?
+-->
+
+(To be filled by the team)
+
+---
+
+## Forbidden Patterns
+
+<!-- Patterns that should never be used and why -->
+
+(To be filled by the team)
+
+---
+
+## Required Patterns
+
+<!-- Patterns that must always be used -->
+
+(To be filled by the team)
+
+---
+
+## Testing Requirements
+
+<!-- What level of testing is expected -->
+
+(To be filled by the team)
+
+---
+
+## Code Review Checklist
+
+<!-- What reviewers should check -->
+
+(To be filled by the team)

.trellis/spec/frontend/state-management.md

@@ -0,0 +1,51 @@
+# State Management
+
+> How state is managed in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's state management conventions here.
+
+Questions to answer:
+- What state management solution do you use?
+- How is local vs global state decided?
+- How do you handle server state?
+- What are the patterns for derived state?
+-->
+
+(To be filled by the team)
+
+---
+
+## State Categories
+
+<!-- Local state, global state, server state, URL state -->
+
+(To be filled by the team)
+
+---
+
+## When to Use Global State
+
+<!-- Criteria for promoting state to global -->
+
+(To be filled by the team)
+
+---
+
+## Server State
+
+<!-- How server data is cached and synchronized -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- State management mistakes your team has made -->
+
+(To be filled by the team)

.trellis/spec/frontend/styling-design-tokens.md

@@ -0,0 +1,111 @@
+# 样式与设计 Token 规范
+
+> Anthropic 风(warm editorial)设计体系:色板、字体、圆角与反模式清单。代码事实源:`src/theme/tokens.ts`(JS 侧唯一来源)与 `src/assets/main.css`(Tailwind `@theme`)。
+
+## 基本规则
+
+- 设计 token(色板、圆角、字体、间距)唯一来源是全局 CSS 变量(Tailwind `@theme`),Naive UI `themeOverrides` 从同一份取值;组件内禁止散落硬编码 hex。
+- Tailwind 工具类只用于布局、间距、排版;组件视觉(按钮/输入/表格)交给组件库主题,不用工具类二次描皮。
+- 间距遵循 4px 网格;圆角、阴影、配色遵守下方 token 与反模式清单。
+
+## 风格特征
+
+- **暖纸色底**:不用纯白,用象牙色 `#FAF9F5` 做主背景,靠 1px 细边框(hairline)和一层灰度差分层,几乎不用投影。
+- **单一强调色**:赤陶橙(terracotta)只出现在主按钮、激活态、品牌标记上,页面 95% 面积是黑白灰米。
+- **小圆角、扁平**:圆角 4–6px 量级;无渐变、无玻璃拟态、无 3D 浮雕、无大面积色块光晕。
+- **排版即装饰**:层级靠字号/字重/留白拉开;图标用细线性风格(lucide/tabler),不用 emoji 和彩色立体图标。
+- **克制的动效**:过渡 150–250ms、只做透明度/位移,无弹跳和视差。
+
+## 官方色值(Anthropic 官方 brand-guidelines)
+
+主色:
+
+| Token | 色值 | 用途 |
+| --- | --- | --- |
+| Dark | `#141413` | 主文本、深色背景 |
+| Light | `#FAF9F5` | 浅色背景、深底上的文本 |
+| Mid Gray | `#B0AEA5` | 次要元素、占位、禁用 |
+| Light Gray | `#E8E6DC` | 细微背景、分隔线、边框 |
+
+强调色:
+
+| Token | 色值 | 用途 |
+| --- | --- | --- |
+| Orange | `#D97757` | 主强调(按钮、激活、链接 hover) |
+| Blue | `#6A9BCC` | 次强调(信息、链接) |
+| Green | `#788C5D` | 三级强调(成功) |
+
+品牌橙近似变体(社区考证):`#C15F3C`(Crail,更深)与 `#CC785C`(Book Cloth),可用作橙色的 hover/active 深档。
+
+## 管理面板适配 token
+
+官方色板缺管理面板必需的语义色,按同色温补齐:
+
+| 语义 | 建议值 | 说明 |
+| --- | --- | --- |
+| 背景主 | `#FAF9F5` | 页面底 |
+| 背景面 | `#F0EEE6` | 侧栏、区块底(Light 与 Light Gray 之间) |
+| 卡片 | `#FFFFFF` | 白卡浮在暖底上,配 1px `#E8E6DC` 边框 |
+| 文本主/次 | `#141413` / `#6B6A63` | 次级文本由 Dark 与 Mid Gray 插值 |
+| 主强调 | `#D97757`,hover `#C15F3C` | |
+| 成功 / 信息 | `#788C5D` / `#6A9BCC` | 官方绿 / 蓝 |
+| 警告 | `#B8860B` 一档的暖赭 | 与暖色调和谐,避免高饱和黄 |
+| 危险 | `#BF4D43` 一档的砖红 | 避免纯红 `#FF0000` 系 |
+| 暗色模式 | 底 `#141413`、面 `#1F1E1D`、边框 `#33322E` | 文本反转用 Light |
+| 圆角 | 按钮/输入 4px,卡片 6px,最大不超过 8px | 拒绝大圆角 |
+| 阴影 | 无或 `0 1px 2px rgba(20,20,19,.05)` | 分层靠边框 |
+
+## 字体
+
+- 官方品牌字体 **Styrene**(无衬线)+ **Tiempos**(衬线)为商业授权,不可直接使用;官方开源替代:标题 **Poppins**、正文 **Lora**。
+- 本项目:UI 与数据全用无衬线(`Inter` 或 `Poppins`,中文回退 `PingFang SC` / `Noto Sans SC`);OCID、IP、日志等用等宽(`JetBrains Mono` / `ui-monospace`);衬线(Lora)只做登录页/大标题的编辑风点缀,可选。
+
+## 反模式清单(设计稿与代码评审逐条对照)
+
+大圆角(>8px 的按钮/卡片)、任何渐变(含品牌色渐变文字)、玻璃拟态/毛玻璃、霓虹光晕、彩色大投影、emoji 当图标、深紫深蓝"AI 感"配色、满屏色块卡片、弹跳动效。
+
+## Common Mistake: NModal 宽度不能用 Tailwind class
+
+**Symptom**:`<NModal preset="card" class="w-[480px]">` 弹窗实际渲染为全宽。
+
+**Cause**:naive-ui 的样式为运行时注入(CSSinJS,`<style>` 追加在 head 尾部),其 `.n-card{width:100%}` 与 Tailwind utilities 同特异性但**后加载**,覆盖 `w-[480px]`。
+
+**Fix / Prevention**:弹窗宽度一律用内联 style(优先级最高),与 FormModal.vue 同法:
+
+```html
+<!-- Bad:被 naive-ui 运行时样式覆盖 -->
+<NModal preset="card" class="w-[480px] max-w-[92vw]">
+
+<!-- Good -->
+<NModal preset="card" :style="{ width: '480px', maxWidth: 'calc(100vw - 24px)' }">
+```
+
+## Common Mistake:编辑 SFC 时残留 `defineProps<...>()()` 双括号
+
+**Symptom**:运行时 `ReferenceError: defineProps is not defined`(setup 内),但 `vue-tsc`、`vite build` 全绿——编译期完全静默。
+
+**Cause**:对 `defineProps<{...}>()` 做字符串替换时旧串漏了尾部 `()`,替换后残留成 `()()`。`@vue/compiler-sfc` 只识别「宏调用语句」,对「调用宏返回值」的表达式不做宏转换,把 `defineProps` 原样保留成运行时标识符。
+
+**Prevention**:替换 defineProps/defineEmits 行必须包含**完整语句(含结尾 `()`)**;宏相关改动后,不能只信 build 全绿,须实际打开一次使用该组件的页面(详情弹窗等惰性挂载组件尤其容易漏)。
+
+## Common Mistake:scoped style 中 `:global(...)` 后接后代选择器会丢失后代
+
+**Symptom**:`:global(html.dark) .totp-qr { ... }` 编译产物变成 `html.dark { ... }`——`.totp-qr` 整段丢失,规则错误落到 `html` 元素上(background/padding 直接作用于全页),目标元素完全不匹配。build 全绿、无告警。
+
+**Cause**:`@vue/compiler-sfc` 的 scoped 转换对「`:global()` 后跟普通后代选择器」的组合处理不可靠,后代部分被丢弃而非追加 scope id。
+
+**Fix / Prevention**:完整选择器整体放进 `:global()`:
+
+```css
+/* Bad:编译后 .totp-qr 丢失,规则落到 html.dark 本身 */
+:global(html.dark) .totp-qr { background: #f5f4ed !important; }
+
+/* Good:原样输出 html.dark .totp-qr(自命名 class 需保证全局唯一) */
+:global(html.dark .totp-qr) { background: #f5f4ed !important; }
+```
+
+验证方法:build 后 `grep -o 'html\.dark[^}]*}' dist/assets/<view>-*.css` 核对编译产物选择器,或线上 DevTools 看 computed style 是否命中。
+
+## 组件速查:NQrCode 去白底
+
+NQrCode 自带 inline `background-color:#FFF; padding:12px`(props 可控)。两主题都不垫任何色块的方案:`:padding="0" background-color="transparent"` + `:color="app.dark ? '#f5f4ed' : '#141413'"`——暗色下反色渲染(浅模块透明底),主流扫码器(iOS 相机 / Google Lens / 新版 ML Kit)可识别,扫不动时弹窗内的手动密钥是兜底。color 是响应式 prop,切主题自动重绘。(历史方案「html.dark 下垫 #f5f4ed 浅底」因用户不接受色块框已废弃。)

.trellis/spec/frontend/type-safety.md

@@ -0,0 +1,51 @@
+# Type Safety
+
+> Type safety patterns in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's type safety conventions here.
+
+Questions to answer:
+- What type system do you use?
+- How are types organized?
+- What validation library do you use?
+- How do you handle type inference?
+-->
+
+(To be filled by the team)
+
+---
+
+## Type Organization
+
+<!-- Where types are defined, shared types vs local types -->
+
+(To be filled by the team)
+
+---
+
+## Validation
+
+<!-- Runtime validation patterns (Zod, Yup, io-ts, etc.) -->
+
+(To be filled by the team)
+
+---
+
+## Common Patterns
+
+<!-- Type utilities, generics, type guards -->
+
+(To be filled by the team)
+
+---
+
+## Forbidden Patterns
+
+<!-- any, type assertions, etc. -->
+
+(To be filled by the team)

.trellis/spec/frontend/typescript-vue.md

@@ -0,0 +1,16 @@
+# TypeScript 与 Vue 组件规范
+
+## TypeScript
+
+- 开启 `strict`;禁止 `any`,未知类型用 `unknown` 后收窄。
+- 对象形状优先 `interface`,联合/工具类型用 `type`;类型导入写 `import type`。
+- 与后端交互的 DTO 类型集中在 `types/`,字段与 `docs/API接口文档.md` 一一对应,不在组件里手写内联响应类型。
+- 用 `const` 对象 + `as const` 代替 `enum`。
+
+## Vue 组件
+
+- 一律 `<script setup lang="ts">` 组合式 API;组件名 PascalCase 且多词(`InstanceTable`,避免与 HTML 元素冲突)。
+- `defineProps`/`defineEmits` 写完整类型;props 只读,不在子组件内改。
+- `v-for` 必须带 `key`,且不与 `v-if` 写在同一元素上。
+- 组件内样式一律 `scoped`;跨组件复用样式上提到全局 token 或工具类。
+- 复用逻辑抽 composable(`useXxx` 命名,放 `composables/`);单文件组件函数遵循 ≤30 行的项目约定。