# AGENT.md — violin-home

> 面向 AI agent 的工程导览：模块关系、路由约定、与后端的契约、扩展点。
> 代码即事实，本文件是索引；如代码与本文档冲突，**以代码为准**。

---

## 项目定位

violin-home 是 **violin 微服务套件的统一前端门户**，部署在 `https://www.violin-home.cn/`。

- 认证：**Authentik OIDC**，回调路径 `/auth/callback`，前端把 code POST 到 `violin-auth` 服务换 token
- 后端：依赖 violin-auth（认证）/ violin-bookmark（书签）/ violin-calendar（日历）/ violin-onenote / violin-cloud / 等子服务
- 域名：生产 `https://www.violin-home.cn/`；本地 dev 走 `.env.development` 的 `VITE_APP_URL`

---

## 技术栈

| 维度 | 选型 |
|------|------|
| 框架 | Vue 3.5 + Composition API (`<script setup>`) |
| 构建 | Vite 5 |
| 语言 | TypeScript 5.6 |
| UI | Element Plus 2.8 + Icons |
| 状态 | Pinia 2.2 |
| 路由 | vue-router 4.4（**memory history**，不是 hash / web） |
| HTTP | axios 1.7 |
| 图表 | ECharts 5 |
| Markdown | md-editor-v3 4 |
| 日期 | dayjs（**已废弃 moment**） |
| Mock | vite-plugin-mock 3（**仅 dev 启用**） |
| 拖拽 | vuedraggable 4 |
| 样式 | SCSS（Dart Sass 1.79，**已删除 node-sass**） |

---

## 目录结构

```
violin-home/
├── public/                       静态资源（不打包）
│   ├── blog/*.ts                 博客元数据（按业务模块拆分）
│   └── reset/                    Authentik reset 入口（reset.html 等）
├── src/
│   ├── api/                      axios 接口封装（每个业务一个文件）
│   ├── components/               公共组件
│   │   ├── common/               通用组件
│   │   ├── layout/               顶层布局
│   │   ├── login/                登录 / 注册 / sorryPage
│   │   ├── cloud/                云盘 + aplayer 音乐
│   │   ├── illustration/         插画
│   │   ├── customPic/            自定义图片
│   │   └── operate/              操作组件
│   ├── const/                    全局常量
│   ├── entity/                   实体类型（TypeScript interface）
│   ├── router/                   路由表（**统一指向 @/view/**）
│   ├── service/                  服务层（独立于 axios 的工具服务）
│   ├── store/                    Pinia stores
│   ├── style/                    全局样式（mixin.scss 在 vite.config.ts 里自动注入）
│   ├── types/                    类型声明（*.d.ts）
│   ├── utils/                    工具函数（auth 令牌管理、request axios 封装、date、number）
│   ├── view/                     **页面视图（业务页）** — 单数 view
│   ├── App.vue
│   ├── env.d.ts
│   ├── main.ts
│   └── permission.ts             路由守卫
├── mock/                         vite-plugin-mock 的 mock 数据
├── authentik-deploy/             Authentik 部署相关（helm values、reset 脚本）
├── .env.development              本地开发
├── .env.test                     测试环境
├── .env.production               生产环境
├── Dockerfile
├── Jenkinsfile
├── nginx.conf
├── vite.config.ts
└── tsconfig.json
```

---

## 路由约定

**全部路由指向 `@/view/`**（单数），包括 `/auth/callback`：
- `router/index.ts` 是**唯一**的路由表
- 路由 meta.name 是侧边栏展示的中文名
- `/auth/callback` 由 `view/auth/callback.vue` 处理 OIDC 回调（拿 code → POST `/auth/oidc/callback` 到 violin-auth → 存 token）

**禁止**新建 `views/`（复数）目录。

---

## 认证流程（OIDC）

```
浏览器 → Authentik 登录页（不在本工程）
       ↓ 回调到 https://www.violin-home.cn/auth/callback?code=...&state=...
       ↓
view/auth/callback.vue
       ↓ POST { code, redirect_uri } → VITE_APP_URL + '/auth/oidc/callback'
       ↓
violin-auth 服务（cn.violin.auth.service.OAuthService.oidcAuthorize）
       ↓ 返回 { token, user_id, name }
       ↓
utils/auth.setToken / setTenant 存到 cookie + localStorage
       ↓ 跳到 /
```

**关键约定**：
- `redirect_uri` 必须和 Authentik 应用的配置完全一致（`VITE_OIDC_REDIRECT_URI`）
- `state` 必须校验（防 CSRF），前后端都用 `sessionStorage.oidc_state` 缓存
- token 由 `setToken()` 存到 cookie（`js-cookie`），后续 axios 请求拦截器自动加 `Authorization: Bearer <token>`

---

## HTTP 封装（utils/request.ts）

- `baseURL` = `import.meta.env.VITE_APP_URL`
- 请求拦截器：从 `js-cookie` 读 token，加到 header
- 响应拦截器：401 → 跳 `/login`；5xx → ElMessage 报错

每个业务模块在 `src/api/` 下有自己的文件（如 `api/bookmark.ts`），导出按业务分组的函数：
```ts
import { service } from '@/utils/request'
export const getBookmarks = (params: PageQuery) =>
  service({ url: '/api/v1/bookmark', method: 'get', params })
```

---

## 状态管理（Pinia）

`src/store/` 下每个业务一个 store（settings、strategy、table、tenant）。**禁止**把所有状态塞进一个 store。

- `tenant` store 管当前 customer（对应后端的 customerId）
- `settings` store 管用户偏好
- `strategy` store 管 CTA 策略模板
- `table` store 管通用表格筛选/分页状态

---

## 与后端子服务的对应

| 路径前缀 | 后端服务 | 端口（K8s 内） |
|---------|---------|--------------|
| `/auth/**` | violin-auth | 8080 |
| `/api/v1/bookmark/**` | violin-bookmark | 8081 |
| `/api/v1/calendar/**` | violin-calendar | 8082 |
| `/api/v1/onenote/**` | violin-onenote | 8083 |
| `/api/v1/cloud/**` | violin-cloud | 8084 |
| `/api/v1/trader/**` | violin-trader | 8085 |
| `/api/v1/user/**` | violin-auth（user 模块） | 8080 |

路由由 K8s ingress 统一反向代理；前端只关心 `VITE_APP_URL` 单一域名。

---

## 构建与运行

```bash
# 安装依赖（推荐 pnpm，yarn 也行）
npm install

# 本地 dev（启动 mock）
npm run dev

# 生产构建（先类型检查，再打包）
npm run build

# 测试环境构建
npm run build:test

# 预览构建产物
npm run preview
```

Node：v18+（**不要**用 v14/16，老的 sass-loader/node-sass 不兼容）。

---

## 已知坑（不要"清理"它们）

### 1. `view/` 单数 vs `views/` 复数

**永远只创建 `view/` 单数目录**。`views/` 是历史遗物，已删除过又留下空目录。

### 2. node-sass 已废弃

`package.json` 里**没有** `node-sass`。如果你看到 `npm install` 报 `node-sass` 相关错误，是因为旧依赖被缓存，**不要**手动加回 `node-sass`，用 Dart Sass（`sass: ^1.79`）即可。

### 3. axios 0.x → 1.x

升级到 axios 1.7 后，`axios.create()` 配置有少量变化（如 `paramsSerializer`）。如果你看到 `interceptor is not a function` 之类的报错，看下拦截器是否还兼容旧签名。

### 4. Vue Router 4 用 memory history

`createMemoryHistory()` 而非 `createWebHistory()` / `createWebHashHistory()`。刷新页面会丢路由——如果要做刷新保留路由，需要切到 `createWebHistory()` 并配合 K8s ingress 重写。

### 5. vite-plugin-mock 仅 dev 启用

生产构建不会带 mock（`localEnabled: command === 'serve'`）。如果发现生产缺数据，看下是不是依赖了 mock。

---

## 相关项目

- `violin-auth` — 认证服务（OIDC + JWT 签发）
- `violin-bookmark` / `violin-calendar` / `violin-onenote` / `violin-cloud` / `violin-trader` — 业务子服务
- `violin-common` / `violin-core` — 后端共享框架
- `violin-parent` — 后端父 POM