# sdd_openspec

**Repository Path**: lihaiwu/sdd_openspec

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-17
- **Last Updated**: 2026-07-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Team KB — 团队知识库管理系统

《SDD 工程实战：用 OpenSpec 从零构建真实项目》配套示例项目。

> 📦 仓库地址：https://gitee.com/lihaiwu/sdd_openspec

## 分支说明

| 分支 | 说明 |
|------|------|
| `master` | 仅应用了 `init-team-kb` 的初始状态，适合从零开始跟随书中各章节动手实操 |
| `feature_apply` | 应用了全部 6 个 Change 后的完整状态，可直接对照书中最终效果 |

## 环境要求

- **Node.js** >= 20.19.0（检查：`node --version`）
- **npm** >= 10.0.0（检查：`npm --version`）

> 💡 `better-sqlite3` 提供预编译二进制，Node.js 20.x 无需额外安装编译工具。如果安装失败，尝试 `npm install --build-from-source` 或切换到 Node.js 20 LTS。

## 快速启动

```bash
# 1. 安装依赖
npm run install:all

# 2. 一键启动（前后端同时启动）
npm start                     # → 前端 http://localhost:3000
                              # → 后端 http://localhost:3001

# 或者分别启动：
cd server && npm start        # 终端1: 后端 http://localhost:3001
cd client && npm start        # 终端2: 前端 http://localhost:3000
```

打开浏览器访问 `http://localhost:3000`。

**停止服务：**

```bash
# 在对应的终端中按 Ctrl+C
# 或者执行：
cd server && npm stop         # 停止后端
cd client && npm stop         # 停止前端
# 或从根目录一键停止：
npm run stop                  # 停止全部
```

## 验证后端

```bash
curl http://localhost:3001/api/health
# → {"status":"ok","timestamp":"..."}
```

## 技术栈

| 层级 | 技术 |
|------|------|
| 前端 | React 18 + React Router v6 + axios |
| 后端 | Node.js 20 + Express 4.x |
| 数据库 | SQLite (better-sqlite3) |
| 认证 | JWT + bcryptjs |
| 规范驱动 | OpenSpec 1.4.1 |

## 功能模块

本书通过 6 个 OpenSpec Change 逐步构建以下功能。每个 Change 的 artifacts（proposal / specs / design / tasks）已在 `openspec/changes/` 目录中。

| 功能 | Change | 对应章节 |
|------|--------|----------|
| 项目骨架 | `init-team-kb` | 第 3 章 |
| 用户认证 | `add-user-auth` | 第 4 章 |
| 文章 CRUD | `add-article-crud` | 第 5 章 |
| 全文搜索 | `add-search` | 第 6 章 |
| 暗色模式 | `add-dark-mode` | 第 4 章 |
| 权限控制 | `add-permissions` | 第 8 章 |

### Apply 顺序

各 Change 之间有代码依赖关系，需要按以下顺序 apply：

```text
init-team-kb          ← 已 apply（项目骨架就绪，可直接运行）
    │
add-user-auth         ← 依赖 users 表、Express 框架
    │
add-dark-mode         ← 纯 UI 变更，可在 add-user-auth 之后任意 apply
    │
add-article-crud      ← 依赖认证中间件、users 表
    │
add-search            ← 依赖 articles 表
    │
add-permissions       ← 依赖认证中间件 + 文章路由
```

```bash
/opsx:apply add-user-auth      # 第一步：实现认证
/opsx:apply add-dark-mode      # 可与下一步并行
/opsx:apply add-article-crud   # 第二步：实现文章 CRUD
/opsx:apply add-search         # 第三步：实现搜索
/opsx:apply add-permissions    # 第四步：实现权限
```

## OpenSpec 工作流

本项目使用 OpenSpec 规范驱动开发方式构建：

```text
/opsx:propose → /opsx:apply → /opsx:verify → /opsx:archive
```

> ⚠️ 查看 artifacts 和归档历史需要安装 OpenSpec CLI：
> `npm install -g @fission-ai/openspec@latest`

## 创建管理员账号

项目默认注册的用户角色为 `user`，需要手动创建管理员账号：

```bash
# 1. 注册 admin 账号
curl -X POST http://localhost:3001/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"admin\",\"email\":\"admin@example.com\",\"password\":\"admin123456\"}"

# 2. 手动将角色提升为 admin
cd server && node -e "
const Database = require('better-sqlite3');
const db = new Database('./data/team-kb.db');
db.prepare('UPDATE users SET role = ? WHERE email = ?').run('admin', 'admin@example.com');
console.log('admin role set');
db.close();
"
```

## 查看数据库

推荐使用 VS Code 插件 **SQLite Viewer**（`alexcvzz.vscode-sqlite`），安装后直接在 VS Code 中打开 `server/data/team-kb.db` 文件即可浏览表结构和数据，无需额外安装命令行工具。