@@ -1,9 +1,13 @@
 import { defineConfig } from 'vitepress'
 import { webappLoaderPlugin } from './plugins/webapp-loader'
+import { generateWhiteBookSidebar } from './sidebar-white-book'
 
 const GITHUB_OWNER = 'BioforestChain'
 const GITHUB_REPO = 'KeyApp'
 
+// 自动生成白皮书侧边栏
+const whiteBookSidebar = generateWhiteBookSidebar()
+
 /**
  * Base URL 配置
  * - 开发环境：使用 '/'
@@ -33,12 +37,14 @@ export default defineConfig({
     nav: [
       { text: '首页', link: '/' },
       { text: '下载', link: '/download' },
+      { text: '开发说明书', link: '/white-book/' },
       { text: 'Storybook', link: './storybook/' },
       { text: '贡献指南', link: '/contributing' },
       { text: '更新日志', link: '/changelog' },
     ],
 
     sidebar: {
+      '/white-book/': whiteBookSidebar,
       '/': [
         {
           text: '开始使用',
@@ -52,6 +58,7 @@ export default defineConfig({
           text: '开发者',
           items: [
             { text: '贡献指南', link: '/contributing' },
+            { text: '软件开发说明书', link: '/white-book/' },
           ],
         },
       ],
 
@@ -0,0 +1,152 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { DefaultTheme } from 'vitepress'
+
+type SidebarItem = DefaultTheme.SidebarItem
+
+interface FileMeta {
+  order: number
+  name: string
+  isDir: boolean
+  collapsed?: boolean
+}
+
+/**
+ * 从文件/目录名解析排序和显示名称
+ * 例如: "01-产品篇" -> { order: 1, name: "产品篇" }
+ * 例如: "Button.md" -> { order: 500, name: "Button" }
+ */
+function parseFileName(fileName: string, isDir: boolean): FileMeta {
+  // 移除 .md 扩展名
+  const baseName = fileName.replace(/\.md$/, '')
+  
+  const match = baseName.match(/^(\d+)-(.+)$/)
+  if (match) {
+    return {
+      order: parseInt(match[1], 10),
+      name: match[2],
+      isDir,
+    }
+  }
+  
+  // 特殊处理：附录放最后
+  if (baseName === '附录') {
+    return { order: 999, name: '附录', isDir, collapsed: true }
+  }
+  
+  // index 文件不单独显示
+  if (baseName === 'index') {
+    return { order: -1, name: '', isDir: false }
+  }
+  
+  return { order: 500, name: baseName, isDir }
+}
+
+/**
+ * 读取 markdown 文件获取标题
+ */
+function getTitle(filePath: string, fallback: string): string {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8')
+    const match = content.match(/^#\s+(.+)$/m)
+    if (match) {
+      return match[1].trim()
+    }
+  } catch {
+    // 文件不存在或读取失败
+  }
+  return fallback
+}
+
+/**
+ * 扫描目录生成侧边栏项
+ */
+function scanDirectory(
+  dirPath: string,
+  urlBase: string,
+  depth: number = 0
+): SidebarItem[] {
+  const items: Array<SidebarItem & { _order: number }> = []
+
+  let entries: fs.Dirent[]
+  try {
+    entries = fs.readdirSync(dirPath, { withFileTypes: true })
+  } catch {
+    return []
+  }
+
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue
+    
+    const entryPath = path.join(dirPath, entry.name)
+    const meta = parseFileName(entry.name, entry.isDirectory())
+    
+    // 跳过 index 文件（由父目录处理）
+    if (meta.order === -1) continue
+    
+    if (entry.isDirectory()) {
+      const subUrlBase = `${urlBase}${entry.name}/`
+      const indexPath = path.join(entryPath, 'index.md')
+      
+      // 检查是否有 index.md
+      const hasIndex = fs.existsSync(indexPath)
+      if (!hasIndex) continue
+      
+      const title = getTitle(indexPath, meta.name)
+      const children = scanDirectory(entryPath, subUrlBase, depth + 1)
+      
+      const item: SidebarItem & { _order: number } = {
+        _order: meta.order,
+        text: title,
+        link: subUrlBase,
+      }
+      
+      if (children.length > 0) {
+        item.items = children
+        // 深度 0（篇）：前3个展开，其余折叠
+        // 深度 1+（章/节）：默认展开
+        if (depth === 0) {
+          item.collapsed = meta.collapsed ?? meta.order > 3
+        }
+      }
+      
+      items.push(item)
+      
+    } else if (entry.name.endsWith('.md')) {
+      // 单独的 markdown 文件
+      const title = getTitle(entryPath, meta.name)
+      const link = `${urlBase}${entry.name.replace(/\.md$/, '')}`
+      
+      items.push({
+        _order: meta.order,
+        text: title,
+        link,
+      })
+    }
+  }
+
+  // 按 order 排序
+  items.sort((a, b) => a._order - b._order)
+
+  // 移除 _order 字段
+  return items.map(({ _order, ...rest }) => rest)
+}
+
+/**
+ * 生成白皮书侧边栏配置
+ */
+export function generateWhiteBookSidebar(): SidebarItem[] {
+  const whiteBookDir = path.resolve(__dirname, '../white-book')
+  const indexPath = path.join(whiteBookDir, 'index.md')
+
+  const rootTitle = getTitle(indexPath, '软件开发说明书')
+  const items = scanDirectory(whiteBookDir, '/white-book/', 0)
+
+  return [
+    {
+      text: rootTitle,
+      link: '/white-book/',
+      items,
+    },
+  ]
+}
@@ -32,6 +32,11 @@ features:
     details: 使用 Storybook 构建的现代化 React 组件库
     link: ./storybook/
     target: _self
+  - icon: 📚
+    title: 开发文档
+    details: 完整的软件开发说明书，涵盖产品、设计、架构、服务等
+    link: ./white-book/
+    linkText: 阅读文档
 ---
 
 ## 快速开始
@@ -48,3 +53,17 @@ features:
 | **DWEB** | [下载页面](./download) | [下载页面](./download) |
 
 查看 [下载页面](./download) 了解更多版本信息。
+
+## 开发文档
+
+[《软件开发说明书》](./white-book/) 是 BFM Pay 的完整技术文档，适合开发者和产品人员阅读。
+
+| 篇章 | 内容 | 推荐读者 |
+|------|------|---------|
+| [产品篇](./white-book/01-产品篇/) | 产品愿景、用户画像、用户故事 | 产品经理 |
+| [设计篇](./white-book/02-设计篇/) | 交互设计、视觉设计、设计原则 | 设计师 |
+| [架构篇](./white-book/03-架构篇/) | 技术选型、系统架构、导航、状态管理 | 前端开发 |
+| [服务篇](./white-book/04-服务篇/) | 服务架构、链服务接口、平台服务 | 后端开发 |
+| [组件篇](./white-book/05-组件篇/) | 组件体系、表单系统、开发规范 | 前端开发 |
+| [安全篇](./white-book/06-安全篇/) | 密钥管理、身份认证、DWEB授权 | 安全工程师 |
+| [测试篇](./white-book/08-测试篇/) | 测试策略、Vitest、Playwright | 测试工程师 |
@@ -0,0 +1,164 @@
+# 第一章：产品愿景
+
+> **让每个人都能安全、简单地管理自己的数字资产。**
+
+---
+
+## 1.1 产品定位
+
+BFM Pay 是一款**多链数字钱包移动应用**，目标是成为用户进入 Web3 世界的可信赖入口。
+
+### 核心理念
+
+我们相信：**复杂的区块链技术不应成为普通用户的障碍。**
+
+| 传统钱包的问题 | BFM Pay 的解决方案 |
+|--------------|-------------------|
+| 需要理解"助记词""Gas费"等概念 | 用通俗语言解释，引导式操作 |
+| 多个钱包管理不同链的资产 | 一个钱包，多链支持 |
+| 界面复杂，功能堆砌 | 渐进式复杂度，新手友好 |
+| 转错地址无法挽回 | 多重确认，地址簿管理 |
+
+### 产品形态
+
+```
+┌─────────────────────────────────────────┐
+│              BFM Pay                     │
+├─────────────────────────────────────────┤
+│                                         │
+│   ┌─────────┐       ┌─────────┐        │
+│   │   Web   │       │  DWEB   │        │
+│   │  版本   │       │  版本   │        │
+│   └────┬────┘       └────┬────┘        │
+│        │                 │              │
+│        └────────┬────────┘              │
+│                 │                       │
+│        ┌───────▼───────┐               │
+│        │   统一核心    │               │
+│        │  React + TS   │               │
+│        └───────────────┘               │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+- **Web 版本**：浏览器访问，无需安装
+- **DWEB 版本**：Plaoc 原生应用，更深度的系统集成
+
+---
+
+## 1.2 目标市场
+
+### 主要市场
+
+**BioforestChain 生态用户**
+- BFMeta、PMChain、CCChain 等链的持有者
+- 需要与 DWEB 应用交互的用户
+- 参与生态质押和投票的用户
+
+### 拓展市场
+
+**主流公链用户**
+- Ethereum、BSC、Tron 等链的持有者
+- 寻找多链管理方案的用户
+- 对安全性有较高要求的用户
+
+---
+
+## 1.3 价值主张
+
+### 对用户的价值
+
+```
+┌─────────────────────────────────────────────────┐
+│                                                 │
+│    🔐 安全      →  私钥本地存储，永不上传        │
+│                                                 │
+│    🌐 多链      →  一个钱包，管理所有链资产      │
+│                                                 │
+│    📱 便捷      →  随时随地，轻松转账收款        │
+│                                                 │
+│    🔗 生态      →  无缝连接 DWEB 应用           │
+│                                                 │
+└─────────────────────────────────────────────────┘
+```
+
+### 核心功能价值
+
+| 功能 | 用户价值 | 技术实现 |
+|-----|---------|---------|
+| 创建钱包 | 30秒拥有自己的数字身份 | 助记词生成 + 多链派生 |
+| 资产查看 | 一目了然的资产状况 | 多链余额聚合 |
+| 转账收款 | 像发微信一样简单 | 统一的转账流程 |
+| 跨链质押 | 参与生态建设，获取收益 | Mint/Burn 机制 |
+| DWEB 授权 | 安全地与应用交互 | Plaoc 协议 |
+
+---
+
+## 1.4 与 mpay 的关系
+
+BFM Pay 是 mpay 的**技术重构版本**，而非简单的 UI 改版。
+
+### 保留
+
+- ✅ 核心业务逻辑
+- ✅ 多链支持能力
+- ✅ DWEB 协议兼容
+- ✅ 用户数据格式
+
+### 提升
+
+| 方面 | mpay (Angular) | BFM Pay (React) |
+|-----|---------------|-----------------|
+| 框架 | Angular 15 | React 19 |
+| 状态管理 | Service + RxJS | TanStack Store/Query |
+| 导航 | Angular Router | Stackflow |
+| 组件库 | Ionic | shadcn/ui |
+| 测试 | Jasmine | Vitest + Playwright |
+| 文档 | 无 | Storybook |
+
+### 原则
+
+```
+参考，而非复制
+```
+
+- 理解 mpay 的业务逻辑，不是复制代码
+- 质疑原始实现，发现并修复问题
+- 使用现代化技术栈重新实现
+
+---
+
+## 1.5 成功指标
+
+### 用户体验指标
+
+| 指标 | 目标 |
+|-----|------|
+| 首次创建钱包时间 | < 60秒 |
+| 完成一笔转账时间 | < 30秒 |
+| 新用户次日留存率 | > 40% |
+| 用户满意度 (NPS) | > 50 |
+
+### 技术质量指标
+
+| 指标 | 目标 |
+|-----|------|
+| 单元测试覆盖率 | > 70% |
+| E2E 测试通过率 | 100% |
+| Lighthouse 性能分 | > 90 |
+| 首屏加载时间 | < 2秒 |
+
+---
+
+## 本章小结
+
+- BFM Pay 的愿景是让数字资产管理变得安全、简单
+- 核心定位是多链钱包，服务 BioforestChain 生态和主流公链用户
+- 是 mpay 的技术重构，保留业务逻辑，提升技术栈和用户体验
+- 成功需要同时满足用户体验和技术质量指标
+
+---
+
+## 下一章
+
+继续阅读 [第二章：用户画像](../02-用户画像/)，深入了解我们的目标用户。