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:

<!-- #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)