Skip to content

Commit c53b247

Browse files
GaubeeGaubee
committed
🔧 storybook 现在也挂到gh-page
1 parent 0d4f869 commit c53b247

5 files changed

Lines changed: 373 additions & 8 deletions

File tree

‎.github/workflows/cd.yml‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -167,9 +167,24 @@ jobs:
167167
echo "=== webapp-beta directory ==="
168168
ls -la docs/public/webapp-beta/ | head -5
169169
170+
# ===== 构建 Storybook =====
171+
- name: Build Storybook
172+
run: pnpm build-storybook
173+
174+
- name: Prepare Storybook for VitePress
175+
run: |
176+
mkdir -p docs/public/storybook
177+
cp -r storybook-static/* docs/public/storybook/
178+
echo "Storybook copied to docs/public/storybook/"
179+
170180
# ===== 构建 VitePress 站点 =====
181+
# Base path: 仓库变量 VITEPRESS_BASE，默认使用 /{repo_name}/
171182
- name: Build VitePress site
172-
run: pnpm docs:build
183+
env:
184+
VITEPRESS_BASE: ${{ vars.VITEPRESS_BASE || format('/{0}/', github.event.repository.name) }}
185+
run: |
186+
echo "Building with VITEPRESS_BASE=$VITEPRESS_BASE"
187+
pnpm docs:build
173188
174189
# ===== 准备 GitHub Pages =====
175190
- name: Prepare GitHub Pages

‎docs/.vitepress/config.ts‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,23 @@ import { webappLoaderPlugin } from './plugins/webapp-loader'
44
const GITHUB_OWNER = 'BioforestChain'
55
const GITHUB_REPO = 'KeyApp'
66

7+
/**
8+
* Base URL 配置
9+
* - 开发环境：使用 '/'
10+
* - GitHub Pages：使用 '/KeyApp/'（通过 CI 环境变量设置）
11+
* - 自定义部署：通过 VITEPRESS_BASE 环境变量设置
12+
*
13+
* 注意：VitePress 的 Vue Router 需要绝对路径 base，不能用 './'
14+
*/
15+
const base = process.env.VITEPRESS_BASE ?? '/'
16+
717
export default defineConfig({
818
title: 'BFM Pay',
919
description: '多链钱包移动应用',
10-
// 使用相对路径，支持部署在任意子路径下
11-
base: './',
20+
base,
1221

13-
// webapp 目录由插件动态生成，忽略死链接检查
14-
ignoreDeadLinks: [/\.\/webapp/, /\.\/webapp-beta/],
22+
// webapp/storybook 目录由 CI 动态生成，忽略死链接检查
23+
ignoreDeadLinks: [/\.\/webapp/, /\.\/webapp-beta/, /\.\/storybook/],
1524

1625
head: [
1726
['link', { rel: 'icon', type: 'image/svg+xml', href: '/logo.svg' }],
@@ -24,6 +33,8 @@ export default defineConfig({
2433
nav: [
2534
{ text: '首页', link: '/' },
2635
{ text: '下载', link: '/download' },
36+
{ text: 'Storybook', link: './storybook/' },
37+
{ text: '贡献指南', link: '/contributing' },
2738
{ text: '更新日志', link: '/changelog' },
2839
],
2940

@@ -37,6 +48,12 @@ export default defineConfig({
3748
{ text: '更新日志', link: '/changelog' },
3849
],
3950
},
51+
{
52+
text: '开发者',
53+
items: [
54+
{ text: '贡献指南', link: '/contributing' },
55+
],
56+
},
4057
],
4158
},
4259

‎docs/contributing.md‎

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
# 贡献指南
2+
3+
本文档为开发者和贡献者提供项目开发、部署和贡献的详细指南。
4+
5+
## 快速开始
6+
7+
### 环境要求
8+
9+
- Node.js 20+
10+
- pnpm 9+
11+
- Git
12+
13+
### 本地开发
14+
15+
```bash
16+
# 克隆仓库
17+
git clone https://github.com/BioforestChain/KeyApp.git
18+
cd KeyApp
19+
20+
# 安装依赖
21+
pnpm install
22+
23+
# 启动开发服务器
24+
pnpm dev
25+
26+
# 启动 Storybook
27+
pnpm storybook
28+
29+
# 启动文档站点
30+
pnpm docs:dev
31+
```
32+
33+
### 常用命令
34+
35+
| 命令 | 说明 |
36+
|------|------|
37+
| `pnpm dev` | 启动开发服务器 (端口 5173) |
38+
| `pnpm dev:mock` | 使用 Mock 服务启动 (端口 5174) |
39+
| `pnpm build` | 构建生产版本 |
40+
| `pnpm test` | 运行单元测试 |
41+
| `pnpm test:storybook` | 运行 Storybook 测试 |
42+
| `pnpm storybook` | 启动 Storybook (端口 6006) |
43+
| `pnpm typecheck` | TypeScript 类型检查 |
44+
| `pnpm lint` | 代码检查 |
45+
| `pnpm docs:dev` | 启动文档站点 (端口 5200) |
46+
47+
## 项目结构
48+
49+
```
50+
KeyApp/
51+
├── src/ # 应用源码
52+
│ ├── components/ # React 组件
53+
│ ├── pages/ # 页面组件
54+
│ ├── stores/ # 状态管理 (TanStack Store)
55+
│ ├── services/ # 平台服务抽象
56+
│ ├── routes/ # 路由配置 (TanStack Router)
57+
│ ├── i18n/ # 国际化
58+
│ ├── styles/ # 全局样式
59+
│ ├── test/ # 测试工具
60+
│ └── types/ # TypeScript 类型定义
61+
├── docs/ # VitePress 文档站点
62+
│ ├── .vitepress/ # VitePress 配置
63+
│ └── public/ # 静态资源
64+
├── .storybook/ # Storybook 配置
65+
├── e2e/ # E2E 测试 (Playwright)
66+
└── scripts/ # 构建脚本
67+
```
68+
69+
## Fork 与自定义部署
70+
71+
### GitHub Pages 部署
72+
73+
Fork 本项目后，可以通过 **仓库变量** 自定义部署配置，无需修改任何代码。
74+
75+
#### 配置步骤
76+
77+
1. Fork 本仓库
78+
2. 进入仓库 Settings → Secrets and variables → Actions → Variables
79+
3. 添加以下变量（按需）：
80+
81+
| 变量名 | 说明 | 示例值 |
82+
|--------|------|--------|
83+
| `VITEPRESS_BASE` | 站点 base path | `/` 或 `/my-app/` |
84+
85+
#### 默认行为
86+
87+
如果不设置 `VITEPRESS_BASE` 变量，默认使用 `/{repo_name}/`（如 `/KeyApp/`）。
88+
89+
#### 自定义域名
90+
91+
使用自定义域名时，设置 `VITEPRESS_BASE=/`：
92+
93+
1. 添加仓库变量 `VITEPRESS_BASE` 值为 `/`
94+
2. 在 DNS 提供商配置 CNAME 记录指向 `{username}.github.io`
95+
3. 在仓库 Settings → Pages 中配置自定义域名
96+
97+
### 构建产物
98+
99+
CI/CD 会自动构建以下产物：
100+
101+
| 路径 | 说明 |
102+
|------|------|
103+
| `/` | VitePress 文档站点 |
104+
| `/webapp/` | Web 应用（稳定版） |
105+
| `/webapp-beta/` | Web 应用（测试版） |
106+
| `/storybook/` | Storybook 组件文档 |
107+
108+
## 开发规范
109+
110+
### 组件开发流程
111+
112+
1. **创建 Story** - 先在 Storybook 中定义组件的各种状态
113+
2. **编写测试** - 使用 Vitest 编写单元测试
114+
3. **实现组件** - 开发 React 组件
115+
4. **类型检查** - 运行 `pnpm typecheck` 确保类型安全
116+
117+
### 文件命名规范
118+
119+
```
120+
component-name.tsx # 组件实现
121+
component-name.stories.tsx # Storybook stories
122+
component-name.test.tsx # 单元测试
123+
```
124+
125+
### TypeScript 严格模式
126+
127+
项目启用了 TypeScript 严格模式，包括：
128+
129+
- `strict: true`
130+
- `noUncheckedIndexedAccess: true`
131+
- `exactOptionalPropertyTypes: true`
132+
- `noUnusedLocals: true`
133+
- `noUnusedParameters: true`
134+
135+
### 代码风格
136+
137+
- 使用 Prettier 格式化代码
138+
- 使用 oxlint 进行代码检查
139+
- 组件使用函数式写法
140+
- 优先使用 TypeScript 类型推断
141+
142+
## 服务实现
143+
144+
项目支持多平台服务实现，通过环境变量 `SERVICE_IMPL` 切换：
145+
146+
| 值 | 说明 |
147+
|----|------|
148+
| `web` | 浏览器环境（默认） |
149+
| `dweb` | DWEB/Plaoc 平台 |
150+
| `mock` | 测试/开发环境 |
151+
152+
```bash
153+
# 使用 Mock 服务开发
154+
SERVICE_IMPL=mock pnpm dev
155+
156+
# 构建 DWEB 版本
157+
SERVICE_IMPL=dweb pnpm build
158+
```
159+
160+
## 测试
161+
162+
### 单元测试
163+
164+
```bash
165+
# 运行所有单元测试
166+
pnpm test
167+
168+
# 运行特定文件
169+
pnpm test src/components/common/button.test.tsx
170+
171+
# 生成覆盖率报告
172+
pnpm test:coverage
173+
```
174+
175+
### Storybook 测试
176+
177+
```bash
178+
# 运行 Storybook 组件测试
179+
pnpm test:storybook
180+
```
181+
182+
### E2E 测试
183+
184+
```bash
185+
# 运行 E2E 测试
186+
pnpm e2e
187+
188+
# 带 UI 的 E2E 测试
189+
pnpm e2e:ui
190+
```
191+
192+
## 提交规范
193+
194+
### Commit Message 格式
195+
196+
```
197+
<type>(<scope>): <subject>
198+
199+
<body>
200+
201+
<footer>
202+
```
203+
204+
**Type 类型**：
205+
- `feat` - 新功能
206+
- `fix` - Bug 修复
207+
- `docs` - 文档更新
208+
- `style` - 代码格式（不影响功能）
209+
- `refactor` - 重构
210+
- `test` - 测试相关
211+
- `chore` - 构建/工具相关
212+
213+
### Pull Request
214+
215+
1. Fork 仓库并创建功能分支
216+
2. 确保所有测试通过：`pnpm test && pnpm typecheck`
217+
3. 提交 PR 到 `main` 分支
218+
4. 等待 CI 检查通过和代码审查
219+
220+
## 发布流程
221+
222+
### Beta 发布
223+
224+
每次推送到 `main` 分支会自动触发 Beta 发布：
225+
- 构建并部署到 GitHub Pages
226+
- 创建/更新 `beta` release
227+
228+
### 稳定版发布
229+
230+
创建版本标签触发稳定版发布：
231+
232+
```bash
233+
git tag v1.0.0
234+
git push origin v1.0.0
235+
```
236+
237+
## 常见问题
238+
239+
### TypeScript 类型错误
240+
241+
如果遇到 `exactOptionalPropertyTypes` 相关错误，确保可选属性不要显式传递 `undefined`：
242+
243+
```tsx
244+
// ❌ 错误
245+
<Component prop={undefined} />
246+
247+
// ✅ 正确 - 省略属性
248+
<Component />
249+
250+
// ✅ 或者类型定义允许 undefined
251+
interface Props {
252+
prop?: string | undefined
253+
}
254+
```
255+
256+
### 本地开发 base path
257+
258+
本地开发默认使用 `/`，无需配置。生产构建时通过环境变量设置：
259+
260+
```bash
261+
VITE_BASE_URL=/my-path/ pnpm build
262+
```
263+
264+
## 获取帮助
265+
266+
- [GitHub Issues](https://github.com/BioforestChain/KeyApp/issues) - 报告 Bug 或功能请求
267+
- [GitHub Discussions](https://github.com/BioforestChain/KeyApp/discussions) - 讨论和问答

‎docs/index.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,10 @@ features:
2727
- icon: 📱
2828
title: 跨平台
2929
details: 提供 Web 应用和 DWEB 原生应用，随时随地管理资产
30-
- icon: 🚀
31-
title: 极速体验
32-
details: 现代化技术栈，流畅的用户界面和交互体验
30+
- icon: 🧩
31+
title: 组件库
32+
details: 使用 Storybook 构建的现代化 React 组件库
33+
link: ./storybook/
3334
---
3435

3536
## 快速开始

0 commit comments

Comments
 (0)