uni-halo/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

uni-halo v3.0 is a multi-platform blog client built on the **Halo 2.x** headless CMS API. It targets WeChat mini-program (primary), H5, Alipay, and native apps. Built on the **unibest** scaffold with Vue 3 + TypeScript + Vite + UnoCSS.

## Commands

| Task | Command |
|------|---------|
| Install dependencies | `pnpm install` |
| Dev (H5) | `pnpm dev` or `pnpm dev:h5` |
| Dev (WeChat mini-program) | `pnpm dev:mp` or `pnpm dev:mp-weixin` |
| Dev (Alipay mini-program) | `pnpm dev:mp-alipay` |
| Dev (native app) | `pnpm dev:app` |
| Build (H5) | `pnpm build` or `pnpm build:h5` |
| Build (WeChat) | `pnpm build:mp` |
| Build (app) | `pnpm build:app` |
| Lint | `pnpm lint` |
| Lint + auto-fix | `pnpm lint:fix` |
| Type check | `pnpm type-check` |
| Run tests (watch) | `pnpm test` |
| Run tests (single) | `pnpm test:run` |
| Generate API client from OpenAPI | `pnpm openapi` |
| Upload to WeChat platform | `pnpm upload:mp` |

## Architecture

### Entry Flow
`src/main.ts` → creates Vue app → installs Pinia → route interceptor → request interceptor → i18n. On launch, `src/App.vue` fetches the uni-halo plugin configuration from the Halo server and stores it in the `uniHaloConfig` Pinia store.

### Routing (Convention-Based)
Pages in `src/pages/` are auto-registered by `@uni-helper/vite-plugin-uni-pages`. Use the `definePage()` macro at the top of page files to set metadata (navigation style, title, etc.). Sub-packages live in `src/subpkg-blog/` and `src/subpkg-demo/`.

Route guards in `src/router/interceptor.ts` intercept `navigateTo`, `reLaunch`, `redirectTo`, `switchTab`. Supports whitelist (default: login required) and blacklist strategies, configured in `src/router/config.ts`.

### HTTP Layer — Three Coexisting Strategies
1. **Custom `uni.request` wrapper** (`src/http/http.ts`) — GET/POST/PUT/DELETE helpers with transparent 401 token refresh (queues pending requests during refresh). Used by `src/api/login.ts`.
2. **Alova** (`src/http/alova.ts`) — Alova 3.3+ with `@alova/adapter-uniapp`, Halo-specific response handling. Used by `src/api/halo-base/*` and `src/api/halo-plugin/*`.
3. **vue-query** (`src/http/vue-query.ts`) — skeleton/option, not actively used.

Request interceptor (`src/http/interceptor.ts`) attaches `Authorization: Bearer <token>` to all requests.

### Authentication
Dual token mode support (single access token OR access+refresh pair), controlled by `VITE_AUTH_MODE` env var. Token store (`src/store/token.ts`) handles login (standard + WeChat mini-program), logout, and automatic refresh with computed expiry checks.

### API Layer
- `src/api/halo-base/` — Core Halo APIs: posts, categories, tags, comments, stats, trackers
- `src/api/halo-plugin/` — uni-halo plugin APIs: plugin config, moments, links, gallery, votes, douban, muyin, data stats
- `src/api/login.ts` — Auth APIs (login, register, WeChat login, token refresh)
- `src/api/types/` — TypeScript interfaces for API responses
- Types from `@halo-dev/api-client` (e.g., `ListedPostVo`, `PostVo`)

### State Management
Pinia with `pinia-plugin-persistedstate` using `uni.getStorageSync`/`uni.setStorageSync`. All stores use Composition API style (`defineStore` with setup function):
- `src/store/token.ts` — Authentication
- `src/store/user.ts` — User profile
- `src/store/config.ts` — uni-halo plugin configuration

### Custom Tabbar
Fully custom tabbar in `src/tabbar/` with its own Pinia store. Configurable strategy: no tabbar, native tabbar, or custom tabbar. Currently set to `CUSTOM_TABBAR` with 5 tabs.

## Coding Conventions

### Vue Components
- Use `<script setup lang="ts">` exclusively — script must be first, template second, style last
- Name components with `defineOptions({ name: '...' })`
- Define props with `interface` + `withDefaults(defineProps<IProps>(), {...})`
- Project-specific components prefixed with `uh-` (e.g., `uh-post-card`, `uh-image`)
- Global components in `src/components/`, page-local in `src/pages/xx/components/`
- UI library: wot-ui (`wd-*` components), auto-imported via easycom

### TypeScript
- Use `interface` for object types, `type` for union types
- Use `import type` for type-only imports
- Avoid `any`

### Styling
- Prefer UnoCSS atomic classes over custom CSS
- SCSS with `scoped` when custom styles are needed; follow BEM naming
- Use `rpx` units for cross-platform screen adaptation
- Safe-area utilities: `p-safe`, `pt-safe`, `pb-safe`
- UnoCSS shortcut `center` = `flex items-center justify-center`
- Theme color `primary` from wot-ui CSS variable `--wd-primary-color`

### Platform Conditional Compilation
Use uni-app directives for platform-specific code:
```vue
<!-- #ifdef H5 -->
<view>H5 only</view>
<!-- #endif -->

<!-- #ifdef MP-WEIXIN -->
<view>WeChat only</view>
<!-- #endif -->
```
Import boundaries must not be reordered by ESLint — `perfectionist/sort-imports` is disabled for this reason.

### Git
- Conventional commits enforced via commitlint (`@commitlint/config-conventional`)
- Write commit messages in Chinese
- Pre-commit runs lint-staged via Husky

### i18n
English and Simplified Chinese via vue-i18n. Locale files in `src/locale/` (en.json, zh-Hans.json).

## Path Aliases
- `@` → `./src`
- `@img` → `./src/static/images`

## Environment Configuration
Environment files in `env/` directory:
- `.env` — Base config (app title, port 9000, app IDs, auth mode)
- `.env.development` — Dev backend URL, console enabled
- `.env.test` — Test environment
- `.env.production` — Production (console stripped)