npm package: @robsun/keystone-web-core
Description: Keystone 平台前端核心包，提供平台级路由、页面与基础能力（登录、组织与权限、审批、任务中心、通知、设置、帮助中心）。
Latest version: 0.5.0

﻿# @robsun/keystone-web-core

Keystone 平台前端核心包，提供平台级路由、页面与基础能力（登录、组织与权限、审批、任务中心、通知、设置、帮助中心）。

## 安装

```bash
pnpm add @robsun/keystone-web-core
```

## 依赖要求

该包使用以下 peerDependencies：

- `react` `^19.2.0`
- `react-dom` `^19.2.0`
- `react-router-dom` `^7.10.1`
- `antd` `^6.0.1`
- `@ant-design/icons` `^6.1.0`

核心依赖（已内置）：

- `i18next` `^24.2.3` - 国际化框架
- `react-i18next` `^15.5.1` - React 国际化绑定
- `i18next-browser-languagedetector` `^8.0.4` - 浏览器语言检测

## 最小接入

1) `vite.config.ts`

```ts
import { createKeystoneViteConfig } from '@robsun/keystone-web-core/vite'

export default createKeystoneViteConfig({
  server: {
    port: 3000,
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
      },
    },
  },
})
```

2) `src/app.config.ts`

```ts
import type { KeystoneWebConfig } from '@robsun/keystone-web-core'

export const appConfig: Partial<KeystoneWebConfig> = {
  brand: {
    name: 'Keystone',
    shortName: 'KS',
    appName: 'Keystone',
    platformName: 'Keystone 平台',
  },
  approval: {
    businessTypes: [{ value: 'general', label: '通用流程' }],
  },
}
```

3) `src/main.tsx`

```tsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { KeystoneApp, setKeystoneConfig } from '@robsun/keystone-web-core'
import { appConfig } from './app.config'
import '@robsun/keystone-web-core/styles/keystone.css'

setKeystoneConfig(appConfig)

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <KeystoneApp />
  </StrictMode>
)
```

## 分层导出

为保持单包且降低耦合，支持分层入口导入：

```ts
import { KeystoneApp } from '@robsun/keystone-web-core/app'
import { api, setAuthTokenProvider } from '@robsun/keystone-web-core/runtime'
import { ProTable } from '@robsun/keystone-web-core/ui'
import { setKeystoneConfig } from '@robsun/keystone-web-core/platform'
```

## 配置项说明（KeystoneWebConfig）

- `brand`：品牌名、Logo、平台名等
- `auth`：登录/恢复密码页文案
- `dashboard`：仪表盘标题与指标
- `approval`：审批业务类型映射（`value/label`）
- `modules`：模块开关（默认启用 `keystone`）
- `help`：帮助中心开关
- `ui`：Ant Design 主题与本地化
  - `theme`：Ant Design 主题配置
  - `locale`：Ant Design 本地化配置（日期本地化由 i18n 自动同步，无需手动设置 dayjs）
  - `i18n`：多语言配置
    - `defaultLocale`：默认语言（默认 `'zh-CN'`）
    - `supportedLocales`：支持的语言列表（默认 `['zh-CN', 'en-US']`）
    - `fallbackLocale`：回退语言（默认 `'zh-CN'`）
    - `persistKey`：本地存储键名（默认 `'ks-language'`）
    - `detection`：是否自动检测浏览器语言（默认 `true`）

## 多语言支持

Keystone 内置中英文双语支持，默认语言为中文。所有 UI 文案、表单验证消息、系统提示均支持国际化。

### 支持的语言

- `zh-CN` - 简体中文（默认）
- `en-US` - 英语

### 语言配置

在 `app.config.ts` 中配置语言选项：

```ts
export const appConfig: Partial<KeystoneWebConfig> = {
  brand: {
    name: 'Keystone',
    // ...
  },
  ui: {
    i18n: {
      defaultLocale: 'zh-CN',                    // 默认语言
      supportedLocales: ['zh-CN', 'en-US'],      // 支持的语言
      fallbackLocale: 'zh-CN',                   // 回退语言（翻译缺失时使用）
      persistKey: 'ks-language',                 // localStorage 存储键名
      detection: true,                           // 自动检测浏览器语言
    },
  },
}
```

### 语言切换

用户可通过界面右上角的语言切换器选择语言，选择会自动保存到浏览器本地存储（localStorage）。下次访问时会自动应用上次选择的语言。

### 翻译覆盖范围

- 认证模块：登录、密码恢复
- 系统管理：用户、角色、部门、权限管理
- 审批中心：流程配置、工作台、记录查询
- 通知中心：通知列表、详情
- 帮助中心：搜索、导航
- 通用组件：表单验证、数据导入导出、确认对话框
- 错误消息：所有系统错误提示

## 帮助中心文档

帮助文档按语言目录组织：`help/<locale>/**/*.md`（例如 `help/zh-CN/...`、`help/en-US/...`）。
默认会加载包内 `src/modules/keystone/help`，也可以合并项目内帮助目录（项目优先）。

```ts
createKeystoneViteConfig({
  helpExtraDirs: ['./src/modules'],
  helpLocales: ['zh-CN', 'en-US'],
  helpDefaultLocale: 'zh-CN',
})
```

如需完全覆盖，使用 `helpDir` 或 `helpDirs`：

```ts
createKeystoneViteConfig({
  helpDirs: ['./src/help'],
  helpLocales: ['zh-CN', 'en-US'],
  helpDefaultLocale: 'zh-CN',
})
```

## 样式

必须引入预构建样式：

```ts
import '@robsun/keystone-web-core/styles/keystone.css'
```

若需重新构建样式（仅维护者使用）：

```bash
pnpm -C packages/keystone-web-core styles:build
```

## 发布（维护者）

发布到 npmjs.org（预发布会自动生成 dist）：

```bash
npm login
pnpm -C packages/keystone-web-core publish --no-git-checks
```