# openspec-book-demo

**Repository Path**: lxp4352/openspec-book-demo

## Basic Information

- **Project Name**: openspec-book-demo
- **Description**: 《SDD 工程实战：用 OpenSpec 从零构建真实项目》配套案例智能书城代码仓库。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-20
- **Last Updated**: 2026-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# openspec-book-demo

《SDD 工程实战：用 OpenSpec 从零构建真实项目》配套代码仓库。

## 项目简介

本仓库是「智能书城」在线商城系统的完整源码，该系统作为《SDD 工程实战：用 OpenSpec 从零构建真实项目》一书的贯穿案例，演示如何在实际项目中使用 OpenSpec 进行规范驱动开发。

## 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| 前端 | Vue 3 + TypeScript | Composition API 开发模式 |
| 状态管理 | Pinia | Vue 3 官方推荐的状态管理库 |
| 路由 | Vue Router 4 | SPA 路由管理 |
| 构建工具 | Vite | 新一代前端构建工具 |
| 后端 | Node.js + Express | RESTful API 服务 |
| ORM | Prisma | 类型安全的数据库访问层 |
| 数据库 | MySQL | 关系型数据库 |
| AI 工具 | Claude Code + OpenSpec | 规范驱动开发工作流 |

## 环境要求

- Node.js >= 20.19.0
- MySQL >= 8.0
- Git

## 快速启动

### 1. 克隆仓库

```bash
git clone https://gitee.com/lihaiwu/openspec-book-demo.git
cd openspec-book-demo/book-store
```

### 2. 创建数据库

```bash
# 使用 MySQL 客户端执行初始化脚本
mysql -u root -p < database/init.sql
```

### 3. 配置并启动后端

```bash
cd backend
npm install
cp .env.example .env

# 编辑 .env，修改以下配置：
#   DATABASE_URL="mysql://root:<你的密码>@localhost:3306/book_store"
#   JWT_SECRET="<随机字符串>"
#   JWT_REFRESH_SECRET="<另一个随机字符串>"

npx prisma migrate dev --name init   # 根据 schema.prisma 建表
npm run db:seed                       # 填充种子数据
npm run dev                           # 启动后端，默认 http://localhost:3000
```

### 4. 配置并启动前端

```bash
cd ../frontend
npm install
# 如果在 Windows + WSL 混合环境下开发，执行：
npm config set script-shell "C:\\Windows\\System32\\cmd.exe"
npm run dev                           # 启动前端，默认 http://localhost:5173
```

### 种子数据账号

| 角色 | 邮箱 | 密码 |
|------|------|------|
| 管理员 | admin@bookstore.com | Admin@123456 |
| 普通用户 | user@bookstore.com | User@123456 |

## 迭代标签

本书通过四轮迭代逐步构建智能书城系统，每轮迭代对应一个 Git 标签：

| 标签 | 对应章节 | 内容 | OpenSpec 工作流 |
|------|---------|------|----------------|
| `v0.1-init` | 14.1 | 项目脚手架初始化 | — |
| `v1.0-user-auth` | 14.3-14.6 | 用户认证模块（注册/登录/JWT/角色权限） | propose → apply → archive |
| `v2.0-book-mgmt` | 14.7-14.10 | 图书管理模块（CRUD/分类/搜索） | new → continue → verify → archive |
| `v3.0-cart-order` | 14.11-14.14 | 购物车 + 订单系统（并行变更+依赖管理） | propose → apply → bulk-archive |
| `v4.0-recommend` | 14.15-14.18 | 智能推荐引擎 + 系统收尾 | ff → apply → archive |

查看特定迭代阶段的代码：

```bash
git checkout v2.0-book-mgmt
```

## 项目结构

```
book-store/
├── database/              # 数据库初始化脚本
│   └── init.sql           #   建库 SQL
├── frontend/              # Vue 3 + TypeScript 前端
│   ├── src/
│   │   ├── api/           # API 请求封装（axios）
│   │   ├── components/    # 公用组件
│   │   ├── composables/   # Composition API 逻辑复用
│   │   ├── router/        # Vue Router 路由配置
│   │   ├── stores/        # Pinia 状态管理
│   │   └── views/         # 页面级组件
│   └── ...
├── backend/               # Node.js + Express 后端
│   ├── src/
│   │   ├── controllers/   # 路由处理器
│   │   ├── middleware/    # Express 中间件
│   │   ├── routes/        # Express 路由注册
│   │   ├── services/      # 业务逻辑层
│   │   └── validators/    # 请求参数校验
│   ├── prisma/
│   │   ├── schema.prisma  #   数据模型定义
│   │   └── seed.ts        #   种子数据（用户、分类、图书）
│   └── ...
└── openspec/              # 项目 OpenSpec 制品
    ├── project.md          #   项目上下文与编码约定
    ├── config.yaml         #   工作流配置与规则
    ├── specs/              #   主规范（5 个能力域）
    │   ├── user-auth/
    │   ├── book-management/
    │   ├── shopping-cart/
    │   ├── order-system/
    │   └── recommendation/
    └── changes/archive/    #   已归档的五轮迭代制品
        ├── 2026-06-10-add-user-auth/
        ├── 2026-06-10-add-book-management/
        ├── 2026-06-10-add-shopping-cart/
        ├── 2026-06-10-add-order-system/
        └── 2026-06-10-add-recommendation-engine/
```

## 许可证

MIT License