# 前端API参考

## 技术栈
- Vue 3 + Composition API + TypeScript
- Naive UI 组件库
- Pinia 状态管理
- Vue Router 路由
- Axios HTTP客户端
- Vite 构建工具

## 核心目录 (src/core/)

core目录是前端的核心基础设施层，提供通用的默认视图和覆盖机制。

### 目录结构
```
core/
├── components/          # 核心组件
│   ├── DynamicIcon.vue
│   ├── FilterBar.vue   # 通用过滤栏
│   ├── IconPicker.vue  # 图标选择器
│   └── ImageGallery.vue
├── features/           # 核心功能模块
│   ├── flows/          # 流程编辑器
│   ├── form_builder/   # 表单构建器
│   ├── schema_builder/ # Schema编辑器
│   └── workspace_builder/ # 工作区构建器
├── pagetype/           # PageType默认视图
│   ├── default.vue              # 默认详情页(1678行)
│   ├── default_list.vue         # 默认列表页(1936行)
│   ├── default_single.vue       # 单例PageType详情页
│   ├── default_toolbar.vue      # 详情页工具栏
│   ├── default_list_toolbar.vue # 列表页工具栏
│   ├── default_list_filterbar.vue # 列表页过滤栏
│   ├── default_list_actions.vue # 列表页操作列
│   └── form/                    # 表单字段组件
└── registry/           # 覆盖机制注册中心
    ├── pagetypeOverride.ts   # PageType视图覆盖
    ├── controlOverride.ts    # 控件覆盖
    └── sidebarOverride.ts    # 侧边栏覆盖
```

### PageType覆盖机制

**约定路径规则** (pagetypeOverride.ts):
```
views/pagetype/{pagetype}/
├── {pagetype}.vue                 # 详情页覆盖
├── {pagetype}_toolbar.vue         # 详情页工具栏覆盖
├── {pagetype}_list.vue            # 列表页覆盖
├── {pagetype}_list_toolbar.vue    # 列表页工具栏覆盖
├── {pagetype}_list_filterbar.vue  # 列表页过滤栏覆盖
└── {pagetype}_list_actions.vue    # 列表页操作列覆盖
```

**覆盖优先级**:
1. 按apps.txt顺序，后面的app优先
2. 路径越短越优先
3. 字母顺序

**使用示例**:
```typescript
import { resolvePagetypeDetailOverride } from '@/core/registry/pagetypeOverride'

// 自动解析user覆盖组件
const UserDetail = await resolvePagetypeDetailOverride('user')
// 如果存在 views/pagetype/user/user.vue 则返回该组件
// 否则返回 null，使用 core/pagetype/default.vue
```

### 默认视图功能

**default.vue (详情页)**:
- 根据PageType元数据自动渲染表单
- 支持子表、附件、关联字段
- 可覆盖工具栏(toolbar)组件
- 支持左/右侧边栏切换

**default_list.vue (列表页)**:
- 根据元数据动态渲染表格列
- 支持搜索、过滤、排序、分页
- 支持批量操作
- 支持列表/卡片视图切换
- 可覆盖toolbar/filterbar/actions组件

**default_single.vue (单例页)**:
- 用于issingle=1的PageType(如System Settings)
- 无列表视图，直接显示详情

## API封装 (shared/api/)

### 通用CRUD (common.ts)
```typescript
import { 
  api, createRecord, updateRecord, deleteRecord, 
  getRecord, getRecords, getPageTypeMeta, getCount 
} from '@/shared/api/common'

// RPC调用
const result = await api.call('module.method', { arg1: 'value' })

// 创建记录
const { success, data } = await createRecord('PageType', { field: 'value' })

// 更新记录
await updateRecord('PageType', 'name', { field: 'newValue' })

// 删除记录
await deleteRecord('PageType', 'name')

// 获取单条记录
const { data } = await getRecord('PageType', 'name')

// 获取带__onload数据的记录
const { data } = await getRecordWithOnload('PageType', 'name')

// 获取记录列表
const { data, total } = await getRecords(
  'PageType',
  [["status", "=", "Open"]],  // filters
  ['name', 'title'],           // fields
  'modified desc',             // orderBy
  0,                           // limitStart
  20                           // limitPageLength
)

// 获取PageType元数据
const { data: meta } = await getPageTypeMeta('PageType')

// 获取记录数
const { count } = await getCount('PageType')

// 搜索记录
const { data } = await searchWidget('PageType', '搜索关键词', {
  page_length: 20,
  filters: { status: 'Open' }
})
```

### 文件操作
```typescript
import { uploadFileToJingrow, uploadAttachment, deleteAttachment } from '@/shared/api/common'

// 上传文件
const { file_url, file_name } = await uploadFileToJingrow(file)

// 上传附件到文档
await uploadAttachment(file, 'PageType', 'pagename', isPrivate)

// 删除附件
await deleteAttachment('File-name')
```

### 认证API (auth.ts)
```typescript
import { loginApi, logoutApi, getUserInfoApi } from '@/shared/api/auth'

await loginApi(username, password)
await logoutApi()
const userInfo = await getUserInfoApi()
```

## 状态管理 (shared/stores/)

### 认证状态 (auth.ts)
```typescript
import { useAuthStore } from '@/shared/stores/auth'

const authStore = useAuthStore()

// 状态
authStore.user          // 当前用户对象
authStore.isLoggedIn    // 是否已登录
authStore.loading       // 加载状态

// 方法
await authStore.login(username, password)
await authStore.logout()
await authStore.initAuth()      // 初始化认证状态
await authStore.updateUserInfo() // 刷新用户信息
```

### 权限状态 (permissions.ts)
```typescript
import { usePermissionStore } from '@/shared/stores/permissions'

const permStore = usePermissionStore()

// 加载权限
await permStore.loadPermissions()

// 检查权限
permStore.hasPermission('PageType', 'read')
permStore.canRead('PageType')   // read或select权限
permStore.canWrite('PageType')  // write/create/delete等权限

// 获取可读取的PageType列表
permStore.readablePagetypes
```

### 菜单状态 (menu.ts)
```typescript
import { useMenuStore } from '@/shared/stores/menu'

const menuStore = useMenuStore()
menuStore.menuItems     // 菜单项
menuStore.workspaces    // 工作区列表
```

## 路由配置 (app/router/)

### 路由规则
```
/login              - 登录页
/signup             - 注册页
/app                - 仪表盘
/app/:entity        - PageType列表页
/app/:entity/:id    - PageType详情页
/workspace/:name    - 工作区页面
/flows              - 流程编辑器
/tools              - 工具列表
/local-jobs         - 本地任务列表
/scheduled-jobs     - 定时任务列表
```

### 路由参数获取
```typescript
import { useRoute } from 'vue-router'

const route = useRoute()
const pagetype = route.params.entity as string
const name = route.params.id as string
```

### 路由守卫
```typescript
// meta.requiresAuth 控制是否需要登录
{ path: '/admin', meta: { requiresAuth: true } }
```

## 国际化 (shared/i18n/)
```typescript
import { t } from '@/shared/i18n'

// 翻译
const text = t('Key')

// 带参数
const msg = t('Hello {name}', { name: 'World' })
```

## 组件规范

### 命名约定
- 组件: PascalCase (`UserList.vue`)
- composables: camelCase + `use` 前缀 (`useTable`)
- stores: camelCase + `use` 前缀 (`useAuthStore`)

### HTTP配置

Axios配置位于 `shared/utils/axiosConfig.ts`:
- Vite代理转发到后端
- 自动携带cookie
- 401响应自动登出（403错误不触发登出）
