OpenSpec 实战指南：从零到一构建“用户角色过滤搜索”功能

OpenSpec 实战指南：从零到一构建“用户角色过滤搜索”功能

实战目标：在现有用户管理系统中，新增按角色和团队过滤搜索的功能。

技术栈：Node.js + Express（后端） + React（前端）

AI 工具：Cursor（原生支持  /openspec 斜杠命令）

时间预估：30 分钟完成全流程（含审查、生成、归档）

前置准备

 
# 1. 安装 OpenSpec CLI
 
npm install -g @fission-ai/openspec@latest
 
 
 
# 2. 进入项目目录
 
cd my-user-management-app
 
 
 
# 3. 初始化 OpenSpec（首次使用）
 
openspec init
 

初始化会：

创建  openspec/ 目录

生成  AGENTS.md（自动适配 Cursor）

生成  project.md（记录技术栈：Node.js, React, JWT 认证等）

第一步：起草变更提案（Draft）

 
# 创建变更文件夹
 
mkdir -p openspec/changes/add-role-team-filter
 
cd openspec/changes/add-role-team-filter
 

1.  proposal.md — 说明意图与非目标

 
# 提案：为用户搜索添加角色与团队过滤
 
 
 
## 目标
 
- 用户可通过 `role` 和 `team` 参数过滤搜索结果
 
- 提升搜索精度，减少无关结果
 
- 支持前端下拉菜单联动
 
 
 
## 非目标（明确边界）
 
- 不支持动态权限过滤（由后端 RBAC 控制）
 
- 不添加分页（已有全局分页）
 
- 不修改现有搜索逻辑（仅扩展）
 
 
 
## 验收标准
 
- API 支持 `/users?role=admin&team=finance`
 
- 前端显示过滤下拉框
 
- 空参数时返回全量结果
 

2.  tasks.md — 任务清单（AI 可自动生成）

 
## 1. 后端修改
 
- [ ] 1.1 在 `GET /users` 接口添加 `role` 和 `team` 查询参数
 
- [ ] 1.2 使用 Prisma 在 SQL 中加入 `WHERE role = ? AND team = ?`
 
- [ ] 1.3 空值时跳过过滤条件
 
- [ ] 1.4 更新 OpenAPI 文档
 
 
 
## 2. 前端修改
 
- [ ] 2.1 在搜索栏添加两个 `<select>` 下拉框
 
- [ ] 2.2 选项从 `/roles` 和 `/teams` 接口获取
 
- [ ] 2.3 同步参数到 URL query
 
- [ ] 2.4 清空选项时移除参数
 
 
 
## 3. 测试与验证
 
- [ ] 3.1 单元测试：空参数返回全量
 
- [ ] 3.2 E2E 测试：过滤后仅显示匹配用户
 

3.  specs/user/spec.md — Delta 补丁（只写变更）

 
# Delta for User Module
 
 
 
## MODIFIED API Endpoints
 
### GET /users
 
- **Query Parameters**:
 
  - `role`: string (optional) - Filter by user role
 
  - `team`: string (optional) - Filter by user team
 
 
 
## ADDED Scenarios
 
#### Scenario: Filter by Role and Team
 
- GIVEN a list of 100 users with various roles and teams
 
- WHEN I request `/users?role=admin&team=finance`
 
- THEN only admin users in finance team are returned
 
- AND response time < 200ms
 
 
 
#### Scenario: Empty Filters
 
- GIVEN filters are not provided
 
- WHEN I request `/users`
 
- THEN all users are returned
 
- AND no WHERE clause for role/team is applied
 

第二步：审查与对齐（Review & Align）

 
# 返回项目根目录
 
cd ../../..
 
 
 
# 验证变更格式
 
openspec validate add-role-team-filter
 

输出：

 
Validation passed! All required files present.
 
Delta format correct.
 
Scenarios use Gherkin syntax.
 

使用 Cursor 审查（斜杠命令）

在 Cursor 中打开项目，输入：

 
/openspec:review add-role-team-filter
 

AI 会自动：

读取  proposal.md、 tasks.md、 specs/

提出优化建议（如“建议添加  role 枚举校验”）

你可回复  y 接受，或编辑文件

审查通过后，AI 输出：

 
Consensus reached. Ready for implementation.
 

第三步：AI 实现代码（Implement）

在 Cursor 中输入：

 
/openspec:apply add-role-team-filter
 

AI 自动生成代码（示例输出）

后端  src/controllers/userController.js

 
// MODIFIED: GET /users
 
export const getUsers = async (req, res) => {
 
  const { role, team, page = 1, limit = 20 } = req.query;
 
  
 
  const where = {};
 
  if (role) where.role = role;
 
  if (team) where.team = team;
 
 
 
  const users = await prisma.user.findMany({
 
    where,
 
    skip: (page - 1) * limit,
 
    take: +limit,
 
  });
 
 
 
  res.json(users);
 
};
 

前端  src/components/UserSearch.jsx

 
const [role, setRole] = useState('');
 
const [team, setTeam] = useState('');
 
 
 
const updateQuery = () => {
 
  const params = new URLSearchParams();
 
  if (role) params.set('role', role);
 
  if (team) params.set('team', team);
 
  navigate(`/users?${params.toString()}`);
 
};
 

第四步：归档与更新（Archive）

 
# 归档变更（自动合并 Delta）
 
openspec archive add-role-team-filter --yes
 

效果：

specs/user/spec.md 自动合并 Delta 内容

changes/add-role-team-filter/ 移至  archive/

生成  archive/add-role-team-filter/timestamp.md 记录

 
# 查看当前真理源
 
cat openspec/specs/user/spec.md
 

已包含新增的 API 参数与场景描述

验证最终效果

 
# 启动项目
 
npm run dev
 
 
 
# 测试 API
 
curl "http://localhost:3000/users?role=admin&team=finance"
 
# → 只返回 finance 团队的 admin 用户
 

实战总结：OpenSpec 核心优势体现

| 环节 | 传统方式 | OpenSpec 方式 | 提升 |

|------|----------|---------------|------|

| 需求沟通 | 口头/聊天 |  proposal.md + 场景 | 无歧义 |

| 代码生成 | 模糊提示 |  /openspec:apply | 100% 对齐规格 |

| 变更追踪 | 无记录 |  archive/ + Delta | 可审计 |

| 团队协作 | 理解偏差 | 共享  specs/ | 一致性 ↑ |

附：完整目录结构（归档后）

 
openspec/
 
├── specs/
 
│ └── user/spec.md ← 已合并过滤逻辑
 
├── changes/ ← 空（活跃变更）
 
├── archive/
 
│ └── add-role-team-filter/
 
│ ├── proposal.md
 
│ ├── tasks.md
 
│ └── specs/user/spec.md
 
├── AGENTS.md
 
└── project.md
 

立即行动

 
# 克隆示例项目开始实战
 
git clone https://github.com/your-org/user-management-demo.git
 
cd user-management-demo
 
openspec init
 
# 然后按本文操作
 

官方资源：

GitHub: Fission-AI/OpenSpec

你已掌握 OpenSpec 实战全流程

下次需求来临时，不再是“让 AI 猜”，而是“让 AI 照章办事”。

提示：将  openspec init 加入团队模板，所有新项目自动规范驱动！