SE的规范驱动开发方法

概述

该项目展示了 规范驱动的开发方法 使用工具 GitHub规范工具包 (https://github.com/github/spec-kit)我急于尝试一种规范驱动的开发方法，该方法专为售前技术工程师设计，以便在短期客户参与期间（通常为2-3天）快速原型化企业解决方案。因此，我迅速从客户那里收集了一些对企业级MCP注册门户和应用程序的需求。

对于这个项目，本文档记录了过程用于使用SpecKit创建功能齐全的企业MCP（模型上下文协议）注册表。

想看看它是什么样子的吗？ 看看 screenshots/ 应用程序运行中的可视化示例目录。

挑战

售前技术工程师面临着一个独特的挑战：他们需要与客户互动，收集需求，并交付能够展示技术能力的工作原型——所有这些都需要在极其紧迫的时间框架内完成。传统的发展方法太慢；纯粹的模型缺乏可信度；演示很酷，但有时不够具体到客户的规格。SpecKit通过将规范的严谨性与人工智能辅助的快速开发相结合，弥合了这一差距。

学习：GitHub Copilot作为编码合作伙伴

在整个项目中， GitHub Copilot 被证明是一个卓越的编码代理和开发合作伙伴。给我印象最深的是它在整个SpecKit过程中保持上下文和连贯性的能力——尽管参与的复杂性和多阶段性，但它从未迷失方向。

主要观察结果:

上下文保留：Copilot了解两个功能分支（前端和后端）的全部范围，记住架构决策、命名约定和在流程早期建立的设计模式。

超越代码生成：这不仅仅是关于编写TypeScript和Python。无缝生成复制副本：

- PowerShell脚本：Entra ID应用程序注册和管理组设置的完全自动化 - SQL脚本：具有适当索引、约束和触发器的PostgreSQL模式 - 配置文件: .env 模板、CORS设置、SOAP配置 - 文档：安装指南、API文档和故障排除说明

复杂集成处理：该项目需要协调多个企业系统：

- Microsoft Entra ID（身份验证、基于组的授权） - Azure PostgreSQL（连接池、SSL/TLS、特定于环境的配置） - 带JWT验证的FastAPI后端 - React前端，带有STROBrowser库

Copilot自信地浏览了这些依赖关系，为每个集成点提出了正确的模式。

真正的“伙伴编码”体验：Copilot感觉自己不像是在指导一个工具，而是一个知识渊博的结对程序员，他：

- 预期的后续实施步骤 - 发现潜在问题（FastAPI中的路由排序、JSONB序列化） - 与宪法原则相一致的建议最佳做法 - 适应反馈和课程修正，而不会失去动力

SpecKit工艺校准：副驾驶在每个阶段都表现出色：

- 指定：帮助将模糊的需求转化为结构化的用户故事 - 计划：生成符合宪法约束的技术架构 - 任务：将计划分解为具有依赖关系的细粒度、可操作的任务 - 实施：跨多种语言和框架生成生产质量代码

归根结底：对于使用SpecKit的解决方案工程师来说，GitHub Copilot不仅仅是一个生产力工具，它是一个力量倍增器，使与客户的快速原型制作真正可行。结构化规范（SpecKit）和上下文代码生成（Copilot）的结合可以在几天内而不是几周内交付可工作的企业应用程序。

什么是SpecKit？

SpecKit是一个 规范驱动开发（SDD） 颠覆传统开发的方法论：不是编写希望与需求相匹配的代码，而是编写可执行的规范 *生成* 代码。规范成为真理的来源——代码只是它的表达。

权力倒置：几十年来，规范服务于代码。SpecKit颠倒了这一点：代码服务于规范。当规范更改时，代码会重新生成。意图和实现之间没有差距，只有转换。

为什么这对解决方案工程师来说是完美的:

速度：在几天内，而不是几周内，将模糊的客户想法转化为可工作的原型。使用SpecKit命令，传统上需要12个多小时的文档工作的规范现在需要15分钟(/speckit.specify, /speckit.plan, /speckit.tasks).

客户信心：用客户的语言（业务需求）而不是技术术语与客户相处。当人工智能处理代码转换时，利益相关者仍然可以阅读规范。

快速旋转客户改变主意了吗？更新规范并重新生成——枢轴成为系统的重新生成，而不是手动重写。非常适合销售周期中的“让我给你看看”时刻。

设计质量：宪法原则（预先确立）防止过度工程和范围蔓延。每一个技术决策都可以追溯到特定的要求，从而创造即时的可信度。

可重复使用资产：规格成为组合件。类似的客户需求？从一个经过验证的规范开始，并对其进行调整。每次参与都会构建一个经过证明的模式库。

过程：宪法→ 指定→ 阐明→ Plan → 任务→ 实施。每一步都是结构化的，人工智能辅助的，并产生客户可以审查和批准的工件。你永远不会“低头编码”——在人工智能处理实施细节的同时，你不断地与利益相关者进行验证。

这不是要取代工程，而是要通过自动化从客户需求到工作演示的机械翻译来提高解决方案工程师的效率，让您专注于理解需求和建立关系。

______________________________________________________________________

起点：原始客户需求

在应用SpecKit流程之前全部我从客户那里得到了在初步讨论中捕捉到的原始、非结构化的需求：

原始客户要求（前端）

要求1：一个可定制的、用户友好的web界面，用于查看、搜索和管理注册的MCP端点。用户应该有一种方法来输入MCP端点，并在webapp中发现和注册它。 为什么它很重要：跨团队集中发现和管理所有MCP服务器。为管理员和开发人员提供透明度，而无需访问API。允许按类别、元数据和所有权进行浏览——这是企业治理和采用的关键。

要求2：管理员必须能够批准、拒绝或删除MCP端点注册，然后才能发现它们。当用户输入要注册的MCP端点时，他们会进入 待定状态 直到管理员批准。 为什么它很重要：确保企业内只暴露经过审查和安全的端点。支持合规性和数据治理策略。启用受控的入职工作流程，以防止未经授权或实验性端点进入生产注册表。

要求3：能够存储和管理丰富的元数据，如端点名称、IP/主机、所有者、审批状态和可用工具。对于注册过程，请将此信息存储在 本地数据存储 目前。 为什么它很重要：元数据为发现、审计和集成提供了必要的上下文。实现下游自动化（例如，审批工作流、所有权跟踪）。支持内部编目标准和分类框架（例如，按业务部门或数据类型）。

要求4：用户必须登录到web应用程序。所有用户将使用相同的目录登录，并且应该能够将某些用户指定为 管理员. 为什么它很重要：该系统将有可以注册MCP端点的用户，这些用户需要被跟踪。一些用户将是管理员，他们有权查看注册的MCP服务器并对其进行批准。

这些规格适用于 web应用程序前端。这最终将连接到 FastAPI后端 使用已定义的API端点来执行更复杂的操作。本规范的目标是启动UI/UX，然后将其连接到后端。

更新的客户需求（后端）

验证前端后，客户返回了：

要求5：创建支持前端应用程序当前功能的后端FastAPI应用程序。更新前端应用程序以使用此新后端。 为什么它很重要：后端需要替换当前运行应用程序的IndexedDB。后端应实现支持前端功能所需的尽可能多的路由/端点。

要求6：生成脚本以在Azure中的PostgreSQL中创建数据库表。 为什么它很重要：系统可能会更改数据库，并需要重建数据库中的表和对象。

就是这样。 没有用户故事，没有验收标准，没有技术架构，只有高级业务需求。在接下来的部分中，您将看到的其他内容都是 通过SpecKit流程生成.

______________________________________________________________________

SpecKit流程：一步一步

该项目遵循中定义的精确SpecKit工作流程 instructions.md。它是这样展开的：

第0阶段：宪法

命令: /speckit.constitution

在编写任何代码之前，该项目建立了其宪法--一套指导所有决策的不可谈判的原则：

确立的核心原则：

先清理代码：优先考虑可读性和可维护性

- 清晰、描述性的命名约定 - 小型、集中的功能和组件 - 过度注释的自文档化代码 - 反映特征边界的逻辑文件组织

简单的用户体验：直观的界面需要最少的学习

- 清晰的视觉层次 - 实现目标所需的最小点击量 - 一致的交互模式 - 所有用户操作的即时反馈

响应式设计：跨所有设备的无缝体验

- 移动优先，逐步增强 - 触摸友好的互动元素（最小44×44px） - 适应视口变化的流体布局

最小依赖性：精心论证的外部图书馆

- 首选标准库解决方案 - 选择重点库而不是整体框架 - 定期依赖性审计 - 锁定版本以防止破坏更改

无测试 *（不可协商）*：零自动化测试

- 无单元、集成或端到端测试 - 没有测试框架或测试基础设施 - 通过干净的代码和手动验证进行质量保证 - 所有精力都集中在生产代码质量上

技术栈已锁定:

前端：React 19.2.0，TypeScript 5.9.3，Vite 7.2.2，顺风CSS
后端：Python 3.13+、FastAPI、PostgreSQL、Azure部署

为什么这很重要：宪法防止了范围蔓延，建立了明确的技术边界，并确保了两个独立功能分支之间的一致性。“无测试”原则对于快速原型制作尤为重要——所有的努力都投入到可证明的功能中。

______________________________________________________________________

第1阶段：规范-前端（分支001）

命令: /speckit.specify

收集需求: 客户需要一个企业范围的MCP（模型上下文协议）服务器注册表，其中：

多个部门可以注册其MCP端点
一个简单的审批流程将控制发布的内容
Microsoft Entra ID将处理身份验证和授权
指定管理员可以批准或拒绝注册

分支: 001-mcp-registry-ui

已创建规范: specs/001-mcp-registry-ui/spec.md

用户故事定义：

US1-用户身份验证（优先级P1）:

用户通过Microsoft Entra ID，使用SWATlibraries进行身份验证
系统通过Entra ID安全组成员身份区分“管理员”和“用户”角色
受保护的路由强制执行身份验证边界

US2-浏览和搜索MCP注册表（优先级P1）:

用户可以查看所有已批准的MCP端点
跨端点名称、所有者、元数据进行实时搜索/过滤
每个端点的详细元数据视图
红色和白色配色方案应用一致

US3-注册新的MCP端点（优先级P2）:

用户提交带有元数据（名称、URL、所有者、工具）的新端点
提交内容进入“待定”状态，等待批准
“我的注册”视图显示用户提交的内容
表单验证确保数据质量

US4-管理员审批工作流（优先级P2）:

管理员查看待处理的注册
批准、拒绝或删除终结点
使用时间戳跟踪状态更新
普通用户无法访问管理功能

关键决策：

数据存储：IndexedDB仅用于初始前端实现（将在第2阶段被后端取代）
认证：带有基于Entra ID组的角色检测的SOAP浏览器库
UI框架：使用Tailwind CSS进行响应式设计
调色板：红色和白色主题（具体的十六进制代码推迟到实现）

作出澄清 （通过 /speckit.clarify):

管理员检测：Entra ID安全组成员身份（“MCP注册表管理员”）
存储机制：容量50MB+的IndexedDB
工具规格：逗号分隔的列表输入
已拒绝端点：保留“已拒绝”状态以进行审核跟踪
颜色决定：推迟到设计阶段

______________________________________________________________________

第2阶段：规划-前端（分支001）

命令: /speckit.plan

可交付成果: specs/001-mcp-registry-ui/plan.md

规划阶段将规范转化为技术架构：

技术决策：

项目结构:

frontend/src/
├── components/
│   ├── auth/           # Authentication components (LoginButton, UserProfile)
│   ├── endpoints/      # Endpoint display (EndpointCard, EndpointList)
│   ├── admin/          # Admin features (ApprovalQueue, ApprovalCard)
│   ├── layout/         # Layout components (Header, Footer, Navigation)
│   └── common/         # Reusable UI (Button, Input, Modal)
├── pages/              # Route-level components
│   ├── Dashboard.tsx
│   ├── Register.tsx
│   ├── MyRegistrations.tsx
│   └── AdminApprovals.tsx
├── services/           # Business logic and data access
│   ├── auth.service.ts
│   ├── db.service.ts
│   └── endpoint.service.ts
├── types/              # TypeScript interfaces
├── utils/              # Utility functions
└── config/             # Configuration (MSAL setup)

依赖性得到证明:

@azure/msal浏览器 & @azure/msal反应：Entra ID身份验证所需
德克西：用于结构化数据存储的IndexedDB包装器
反应路由器dom：客户端路由
热烤面包：用户通知

绩效目标:

10秒内进行身份验证
搜索结果过滤时间\<500ms
视口支持：320px至1920px
管理员操作在2秒内完成

宪法合规性检查: ✅ 干净代码优先：基于组件的架构，边界清晰\ ✅ 简单的用户体验：直观的工作流程（单次搜索，简单的表单）\ ✅ 响应式设计：顺风移动优先\ ✅ 最小依赖关系：只添加基本库\ ✅ 无测试：提供手动验证清单

______________________________________________________________________

第3阶段：任务分解-前端（分支001）

命令: /speckit.tasks

可交付成果: specs/001-mcp-registry-ui/tasks.md

规格被细分为 85项可操作任务 按用户故事组织：

任务分配:

设置（第一阶段）：5项任务-项目初始化
基础的 （第2阶段）：15项任务-核心基础设施（阻止所有用户故事）
US1-身份验证 （第3阶段）：10个任务-登录/角色检测
US2-浏览/搜索 （第4阶段）：12项任务-注册表浏览
US3-注册 （第5阶段）：14项任务-端点提交
US4-行政审批 （第6阶段）：16项任务-审批工作流程
波兰语 （第7阶段）：13项任务——跨领域改进

并行机遇：标记了23个任务 [P] 可以并行运行（不同的文件，没有依赖关系）

MVP范围：42个任务（设置+基础+US1+US2）提供了核心浏览功能

执行策略:

完成基础阶段（阻止其他一切）
实现US1（身份验证）-启用所有其他故事
并行开发：US2（浏览）+US3（注册）
顺序：US4（管理员批准）要求US3存在
核心后的波兰相特征稳定

人工验证：每个阶段都包括特定的手动测试用例（每个构成没有自动测试）

______________________________________________________________________

第4阶段：实施-前端（分支001）

命令: /speckit.implement

交付物：完整的前端应用程序 frontend/

建造内容：

验证系统:

Entra ID集成的SOAP配置(src/config/msal.config.ts)
跨应用程序提供用户状态的身份验证上下文(src/context/AuthContext.tsx)
强制身份验证的受保护路由(src/components/common/ProtectedRoute.tsx)
通过Entra ID组成员身份进行管理员角色检测

数据层:

带Dexie的IndexedDB模式（用户、端点、注册）
服务层抽象数据操作(src/services/api.service.ts)
用于编译时安全的TypeScript类型(src/types/)

用户界面:

仪表盘：通过实时搜索浏览已批准的端点
注册页面：提交新的MCP端点并进行验证
我的注册：跟踪提交状态（待定/批准/拒绝）
管理员审批 *（仅限管理员）*：审查和批准/拒绝提交
响应式设计：移动优先，尾风CSS，红/白主题

已实现的关键功能:

Microsoft Entra ID单点登录
基于角色的访问控制（管理员vs用户）
实时搜索/过滤（\<500ms响应）
表单验证（URL格式，必填字段）
带有时间戳的状态跟踪
Toast通知以获取用户反馈
优雅故障处理的错误边界

支持脚本 （PowerShell）：

Setup-EntraIDAdminGroup.ps1：创建Entra ID应用程序注册和管理组
Add-UserToAdminGroup.ps1：分配管理员权限
List-AdminGroupMembers.ps1：审核管理员用户

前端交付：

✅ 功能齐全的React TypeScript应用程序\ ✅ 使用Entra ID进行工作身份验证\ ✅ 通过IndexedDB完成CRUD操作\ ✅ 响应式设计（320px-1920px视口）\ ✅ 管理员审批工作流程\ ✅ 没有自动测试（根据宪法）

______________________________________________________________________

第5阶段：规范-后端（分支002）

命令: /speckit.specify *（第二次迭代）*

需求更新: 通过前端验证，客户需要从基于浏览器的存储转移到集中式数据库，该数据库将：

支持整个组织的多个用户
将数据持久化到单个浏览器会话之外
启用报告和审计跟踪
部署到Azure以实现企业可扩展性

分支: 002-fastapi-postgres-backend

已创建规范: specs/002-fastapi-postgres-backend/spec.md

用户故事定义：

US1-MCP注册表数据的API端点（优先级P1）:

RESTful端点取代IndexedDB功能
CRUD操作：创建、检索、更新、删除注册
过滤、分页、搜索功能
正确的HTTP状态码和错误处理

US2-用户管理和身份验证支持（优先级P1）:

在每个请求中验证Entra ID令牌
根据令牌声明创建/更新用户记录
基于Entra ID组成员身份的管理员角色检测
用户配置文件端点

US3-数据库模式和迁移脚本（优先级P1）:

PostgreSQL数据库，包含用户、注册、审计日志表
用于创建架构的SQL脚本
临时迁移（可以多次安全运行）
频繁查询列的索引
外键关系

US4-前端集成更新（优先级P2）:

将IndexedDB调用替换为对后端的HTTP请求
向API调用添加身份验证头
优雅地处理API错误
完全删除IndexedDB代码

US5-Azure PostgreSQL数据库配置（优先级P2）:

连接到Azure托管的PostgreSQL
SSL/TLS加密实施
环境特定配置
连接池提高性能

关键决策：

后端框架：FastAPI（现代、异步、自动OpenAPI文档）
数据库：PostgreSQL和JSONB用于灵活的元数据存储
认证：在每个请求中验证Entra ID JWT令牌
包管理: uv 快速解析Python依赖关系（比pip快10-100倍）
日志记录：与Azure Application Insights兼容的结构化JSON日志记录

已解决的边缘案例:

并发重复提交：数据库唯一约束
请求过程中的连接丢失：尝试重新连接的HTTP 503
令牌过期：HTTP 401，带有前端重新身份验证提示
状态更新冲突：数据库事务+乐观锁定

______________________________________________________________________

第6阶段：规划-后端（002分支）

命令: /speckit.plan

可交付成果: specs/002-fastapi-postgres-backend/plan.md

技术架构：

项目结构:

backend/
├── src/
│   ├── main.py                  # FastAPI application entry point
│   ├── config.py                # Environment configuration
│   ├── database.py              # PostgreSQL connection pool
│   ├── dependencies.py          # FastAPI dependencies (auth)
│   ├── auth/
│   │   └── entra_validator.py  # JWT token validation
│   ├── models/                  # Pydantic models (internal)
│   │   ├── user.py
│   │   ├── registration.py
│   │   └── audit_log.py
│   ├── schemas/                 # Pydantic schemas (API contracts)
│   │   ├── user.py
│   │   └── registration.py
│   ├── services/                # Business logic
│   │   ├── user_service.py
│   │   └── registration_service.py
│   └── routers/                 # API endpoints
│       ├── health.py
│       ├── users.py
│       └── registrations.py
├── scripts/
│   └── db/
│       ├── init_schema.sql      # Database schema
│       └── README.md            # Database setup instructions
├── pyproject.toml               # Python dependencies (uv)
└── README.md                    # Backend setup guide

设计的API端点:

GET /health -监测健康检查
POST /users -从Entra ID令牌创建/更新用户
GET /users/me -当前用户配置文件
GET /users/{user_id} -特定用户详细信息
POST /registrations -提交新端点注册
GET /registrations -列出注册（带过滤器）
GET /registrations/{id} -具体注册细节
GET /registrations/my -当前用户的提交
PATCH /registrations/{id}/status -批准/拒绝（仅限管理员）
DELETE /registrations/{id} -删除注册（仅限管理员）

数据库模式:

-- Users table
CREATE TABLE users (
    user_id UUID PRIMARY KEY,
    entra_id VARCHAR(255) UNIQUE NOT NULL,
    email VARCHAR(255) NOT NULL,
    display_name VARCHAR(255),
    is_admin BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- Registrations table
CREATE TABLE registrations (
    registration_id UUID PRIMARY KEY,
    endpoint_url VARCHAR(500) UNIQUE NOT NULL,
    endpoint_name VARCHAR(200) NOT NULL,
    description TEXT,
    owner_contact VARCHAR(255),
    available_tools JSONB,
    status VARCHAR(20) CHECK (status IN ('Pending', 'Approved', 'Rejected')),
    submitter_id UUID REFERENCES users(user_id),
    approver_id UUID REFERENCES users(user_id),
    submitted_at TIMESTAMP DEFAULT NOW(),
    approved_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- Audit log for compliance
CREATE TABLE audit_log (
    log_id UUID PRIMARY KEY,
    registration_id UUID REFERENCES registrations(registration_id),
    user_id UUID REFERENCES users(user_id),
    action VARCHAR(50),
    previous_status VARCHAR(20),
    new_status VARCHAR(20),
    metadata JSONB,
    timestamp TIMESTAMP DEFAULT NOW()
);

-- Indexes for performance
CREATE INDEX idx_registrations_status ON registrations(status);
CREATE INDEX idx_registrations_submitter_id ON registrations(submitter_id);
CREATE INDEX idx_registrations_created_at ON registrations(created_at DESC);

依赖项:

快速API：Web框架
Uvicorn：ASGI服务器
asyncpg：PostgreSQL异步驱动程序
媒染剂：数据验证
巨蟒何塞：JWT令牌验证
python dotenv：环境变量
python json记录器：结构化日志记录

绩效目标:

API响应时间：95%的请求\<200ms
数据库连接池：10-20个连接
支持：100个并发请求而不会降级
健康检查：响应时间\<100ms

______________________________________________________________________

第7阶段：任务分解-后端（分支002）

命令: /speckit.tasks

可交付成果: specs/002-fastapi-postgres-backend/tasks.md

后端被攻破 51项可操作任务 分为9个阶段：

任务分配:

第1阶段-设置：5个任务-项目初始化、依赖关系
第2阶段-基础：8个任务-数据库架构、连接池
第3阶段-数据模型：6个任务-Pydantic模型和模式
第4阶段-身份验证：4个任务-JWT验证、管理员检查
第5阶段-服务：8个任务-业务逻辑层
第6阶段-API路线：10个任务-RESTful端点
第7阶段-应用程序设置：4个任务-FastAPI配置、CORS、日志记录
第8阶段-前端集成：3个任务-替换IndexedDB
第9阶段-Azure配置：3个任务-Azure PostgreSQL设置

关键路径 （仅限MVP-US1）：

Phase 1 (Foundation) 
  → Phase 2 (Database) 
    → Phase 3 (Models) 
      → Phase 4 (Auth) 
        → Phase 5 (Services) 
          → Phase 6 (Routes) 
            → Phase 7 (App Setup)

并行机遇:

第2阶段（数据库）+第3阶段（模型）-不同的关注点
第4阶段（认证）+第5阶段（服务）-独立系统
US2（用户管理）+US3（数据库）-单独的域
第8阶段（前端）+第9阶段（Azure）-不同层次

MVP推荐：任务T001-T045（第1-7阶段）

提供具有所有CRUD端点的工作FastAPI后端
数据库模式和PostgreSQL连接
Entra ID认证和授权
用于监控的健康检查端点
用于前端访问的CORS配置

推迟到第二阶段:

第8阶段：前端集成（让后端先稳定下来）
阶段9:Azure部署（首先在本地测试）

______________________________________________________________________

第8阶段：实施-后端（分支002）

命令: /speckit.implement

交付物：在中完成后端应用程序 backend/

建造内容：

数据库层 (scripts/db/init_schema.sql):

三张桌子： users, registrations, audit_log
维护引用完整性的外键关系
防止重复注册的独特约束
经常查询的列上的索引（状态、提交者id、创建日期）
带有自动更新触发器的时间戳
检查枚举验证的约束（状态、操作）

连接管理 (src/database.py):

asyncpg连接池（10-20个连接）
启动/关闭生命周期管理
连接健康检查
Azure的SSL/TLS支持
自动重新连接时的错误处理

认证 (src/auth/entra_validator.py):

JWT令牌验证（签名、颁发者、受众、过期）
索赔提取（entra_id、电子邮件、display_name）
用于管理员检测的组成员身份解析
FastAPI依赖关系： get_current_user, require_admin
HTTP 401表示令牌无效，403表示权限不足

数据模型:

Pydantic模型 (src/models/)：具有验证的内部表示
API架构 (src/schemas/)：请求/响应合同
Python 3.13+类型提示的类型安全
用于灵活元数据的JSONB处理（可用工具）

业务逻辑 (src/services/):

用户服务：根据Entra ID创建/更新用户，管理员状态检查
注册服务：带业务规则的CRUD操作

- 创建：默认“待定”状态，跟踪提交者 - 获取：筛选（状态、提交者、搜索）、分页 - 更新：状态转换（待定→ 批准/拒绝），跟踪批准人 - 删除：仅限管理员删除

重复检测：HTTP 409在违反唯一约束时发生冲突
数据一致性事务管理

API终点 (src/routers/):

端点	方法	描述	身份验证
`/health`	GET	使用数据库状态进行健康检查	无
`/users`	POST	从令牌创建/更新用户	用户
`/users/me`	GET	当前用户配置文件	用户
`/users/{user_id}`	GET	特定用户详细信息	用户
`/registrations`	POST	提交新端点	用户
`/registrations`	GET	列出注册（可过滤）	用户
`/registrations/my`	GET	当前用户的提交	用户
`/registrations/{id}`	GET	注册详细信息	用户
`/registrations/{id}/status`	PATCH	批准/拒绝注册	管理员
`/registrations/{id}`	DELETE	删除注册	管理员

应用程序设置 (src/main.py):

带有自动OpenAPI文档的FastAPI应用程序
CORS配置允许前端源
结构化JSON日志记录（调试、信息、警告、错误、严重）
启动事件：初始化数据库连接池
关机事件：优雅地关闭连接
常见错误的异常处理程序（404、409、422、500、503）

配置 (src/config.py):

使用python dotenv加载环境变量
启动时所需的设置验证
支持多种环境（开发、暂存、生产）

环境变量 (.env.example):

DATABASE_URL=postgresql://user:password@localhost:5432/mcp_registry
AZURE_CLIENT_ID=your-entra-app-client-id
AZURE_TENANT_ID=your-entra-tenant-id
ENTRA_ADMIN_GROUP_ID=your-admin-group-object-id
CORS_ORIGINS=http://localhost:5173
LOG_LEVEL=INFO

集成阶段：

前端更新 （第8阶段-任务T046-T048）：

已替换IndexedDB 使用HTTP API调用(frontend/src/services/api.service.ts)

- 对后端端点的Fetch/Axios请求 - 带有STROAccess令牌的授权标头 - 用于环境灵活性的基本URL配置

错误处理:

- HTTP状态码映射（401403404409500） - 用户友好的错误消息 - 令牌过期检测→ 重新身份验证提示 - 网络错误恢复

清理:

- 移除 db.service.ts 和 db.schema.ts - 更新了要使用的组件导入 api.service.ts - 已验证没有剩余的IndexedDB引用

集成过程中应用的修复:

路线订购：FastAPI按顺序匹配路由；移动特定路线(/my)参数化路线之前(/{id})
管理员同步：实现了每次请求时从Entra ID组成员身份到数据库的自动管理状态同步
代币声明：增强提取以支持多个索赔来源（电子邮件、upn、unique_name、preferred_username）
JSONB处理：Python列表和PostgreSQL JSONB（JSON字符串序列化）之间的正确转换
Pydantic序列化：固定HttpUrl→ API响应的字符串转换，已添加 from_attributes 配置
调试日志记录：在整个身份验证流程中添加了全面的日志记录，以进行故障排除

后端交付：

✅ 功能齐全的FastAPI后端，带有RESTful API\ ✅ 具有规范化模式的PostgreSQL数据库\ ✅ 对每个请求进行Entra ID JWT令牌验证\ ✅ 通过组成员身份检测管理员角色\ ✅ 带过滤和分页的CRUD操作\ ✅ 结构化JSON日志记录\ ✅ 前端CORS配置\ ✅ 健康检查端点\ ✅ 没有自动测试（根据宪法）\ ✅ 前端已成功集成，IndexedDB已删除

______________________________________________________________________

项目可交付成果

前端(`001-mcp-registry-ui`)

技术：React 19.2.0+TypeScript 5.9.3+Vite 7.2.2+顺风CSS

特性:

✅ Microsoft Entra ID身份验证
✅ 基于角色的访问控制（管理员与用户通过Entra ID组）
✅ 通过实时搜索浏览已批准的MCP端点
✅ 注册新的MCP端点并进行验证
✅ 跟踪注册状态（待定/批准/拒绝）
✅ 管理员审批工作流（批准/拒绝/删除）
✅ 响应式设计（320px-1920px视口）
✅ 红色和白色主题
✅ Toast通知以获取用户反馈
✅ 优雅失败的错误边界

代码行：约3500条线路（估计）

开发时间：2天（使用SpecKit流程）

已创建的文件：45+组件、服务、类型和配置文件

后端(`002-fastapi-postgres-backend`)

技术：Python 3.13++快速API+PostgreSQL+Azure

特性:

✅ 具有10个端点的RESTful API
✅ PostgreSQL数据库，有3个表
✅ Entra ID JWT令牌验证
✅ 通过Entra ID组检测管理员角色
✅ 带过滤和分页的CRUD操作
✅ 重复检测（唯一约束）
✅ 结构化JSON日志记录
✅ CORS配置
✅ 健康检查端点
✅ Azure的SSL/TLS支持
✅ 连接池（10-20个连接）
✅ 自动OpenAPI文档

代码行：约1800条线路（估计）

开发时间：1.5天（使用SpecKit流程）

已创建的文件：20多个模块、模式、服务和SQL脚本

支持脚本

PowerShell自动化:

Setup-EntraIDAdminGroup.ps1：一个命令Entra ID设置
Add-UserToAdminGroup.ps1：管理员用户管理
List-AdminGroupMembers.ps1：行政审计

文档:

ENTRA-ID-SETUP.md：手动Entra ID配置指南
ENTRA-API-SETUP.md：API权限配置
backend/README.md：后端设置和运行说明
frontend/README.md：前端设置和开发指南

______________________________________________________________________

关键SpecKit成果

规格质量

精确度：每个需求都追溯到用户故事→ 验收标准→ 任务→ code

完整性:

前端：4个用户故事，21个功能需求，85个任务
后端：5个用户故事，31个功能需求，51个任务

清晰度：非技术利益攸关方可以理解规范；开发人员可以毫无歧义地实现

发展速度

传统方法 （估计）：

需求收集：1周
设计和架构：1周
前端开发：2-3周
后端开发：2周
集成和测试：1-2周
总计：7-9周

SpecKit方法 （实际）：

宪法：0.5天
前端规格+计划+任务：0.5天
前端实施：2天
后端规格+计划+任务：0.5天
后端实施+集成：1.5天
总计：5天

加速：比传统开发快约10倍

代码质量

指标（估计）：

复杂性：低（最多3级嵌套，函数平均\<30行）
可维护性指数：高（描述性命名，结构清晰）
重复：最低（估计\<5%）
类型安全：100%（TypeScript+Python类型提示）

宪法合规性:

✅ 始终遵循干净的代码原则
✅ 简单的用户体验，认知负荷最小
✅ 跨视口验证响应式设计
✅ 证明并记录依赖关系
✅ 零自动测试（仅手动验证）

文档作为人工制品

生活文档：规范仍然准确，因为它们推动了实现——而不是事后编写的

可追溯性:

用户故事→ 功能要求→ Task → 代码文件
每个功能决策都记录了其基本原理

入职：新开发人员可以通过阅读规范（而不是逆向工程代码）来理解系统

______________________________________________________________________

经验教训

什么方法奏效了

宪法第一：制定基本规则防止了项目中期关于测试、依赖关系和代码风格的争论

用户故事组织：将规格分解为具有明确优先级的故事，实现增量交付（2.5天内MVP）

任务粒度85个以上的前端任务意味着没有任务需要超过2个小时；进展是可见和可追踪的

并行机遇：已标记的任务 [P] 启用了无合并冲突的并发工作

人工验证：如果没有自动化测试，手动验证清单可以确保质量（比为原型编写测试更快）

分支隔离：前端和后端的独立分支允许独立的进度和明确的规范边界

人工智能辅助实施：人工智能工具将编码速度提高了5-10倍，而人工监督保持了架构的一致性

遇到的挑战

规范完整性：初始规格遗漏了边缘情况（重复提交、并发更新）；实施过程中需要澄清

集成假设：前端假设后端API形状与最终实现略有不同；需要少量重构

Entra ID复杂性：Microsoft Entra ID配置比预期更复杂（组声明、令牌验证）；PowerShell脚本缓解了这一问题

JSONB处理：PostgreSQL JSONB序列化需要显式处理（Python列表→ JSON字符串）；在集成测试期间被捕获

路线订购：FastAPI路由匹配已排序（/my-before/{id}）；在运行时错误之前不明显

下一次迭代的改进

更严格的合同：在规划阶段定义API合同（OpenAPI规范），以防止前端/后端漂移

环境平等：使用Docker Compose确保开发环境与生产环境匹配（Azure PostgreSQL，Entra ID）

增量集成：一次集成一个端点，而不是从IndexedDB进行大规模迁移

边缘案例工作坊：在实施之前，专门讨论故障模式和边缘案例

架构版本控制：在预期模式演变的项目章程中纳入迁移策略

______________________________________________________________________

售前工程师：使用SpecKit

何时使用SpecKit

理想场景:

客户参与：2-5天的原型冲刺，收集实时需求
概念证明：证明拟议解决方案的技术可行性
试点项目：全面产品承诺前的第一阶段实施
销售演示：显示客户特定工作流程的定制演示

不适合:

长期生产应用程序（测试和可扩展性比速度更重要）
要求不明确的项目（SpecKit需要具体的规范）
维护现有代码库（SpecKit用于绿地开发）

如何运行SpecKit参与

第0天-准备:

审查SpecKit方法(instructions.md)
准备人工智能工具（GitHub Copilot、ChatGPT、Claude等）
设置开发环境（IDE、Git、Docker，如果需要）

第1天-要求和章程:

早晨：召开客户会议以收集需求（用户故事、痛点）
下午:

- 跑 /speckit.constitution 确立项目原则 - 跑 /speckit.specify 记录要求 - 跑 /speckit.clarify 与客户解决歧义

第2天-规划和设置:

早晨:

- 跑 /speckit.plan 创建技术架构 - 跑 /speckit.tasks 分解实施

下午:

- 安装项目（依赖关系、配置） - 开始基础任务（数据库模式、身份验证设置）

第3-4天-实施:

跑 /speckit.implement 人工智能辅助开发指挥部
系统地完成任务（基础→ MVP → 增强功能）
频繁提交任务引用（例如，“T023：实施管理员角色检查”）
完成每个功能的手动验证

第5天-集成和演示:

早晨：最终整合和抛光
下午：带有实时演练的客户演示
总结：提供代码库、文档和部署指南

成功指标

对于客户:

3-5天内完成工作原型（传统方法为数周）
每天都有明显的进展（不是“我们还在设计”）
记录建造内容的准确规范
对技术可行性的信心

对于工程师:

明确的范围边界（构造防止特征蠕变）
结构化的工作流程减少了决策疲劳
未来阶段的可重复使用规范
值得投资组合的代码质量（即使是原型）

销售团队:

销售周期内的技术信誉
能力的具体展示
缩短销售周期（可行性证明）
与竞争对手的区别（显示工作代码，而不是幻灯片）

______________________________________________________________________

技术堆栈摘要

前端

框架：React 19.2.0
语言：TypeScript 5.9.3
生成工具：快速7.2.2
样式：顺风CSS
认证：@azure/msal浏览器，@azure/msal反应
路由：响应路由器dom
通知：热烤面包
数据存储：最初为IndexedDB（Dexie），迁移到API调用

后端

框架：FastAPI
语言：Python 3.13+
数据库：PostgreSQL（用于PostgreSQL的Azure数据库）
数据库驱动：asyncpg（异步连接池）
认证：python jose（JWT验证）
验证：Pydantic
日志记录：python json记录器（结构化json）
服务器：乌维科恩（ASGI）
程序包管理器：紫外线（比pip快10-100倍）

基础设施

认证：Microsoft Entra ID（以前为Azure AD）
数据库：PostgreSQL的Azure数据库（强制SSL/TLS）
部署目标：Azure（容器服务或应用服务）
跨域资源共享：为本地开发和生产域配置

开发工具

版本控制：带有功能分支的Git
AI协助：GitHub Copilot、Claude、ChatGPT
手动测试：REST客户端（Postman、curl）、浏览器DevTools
文档：Markdown规范 specs/ 目录

______________________________________________________________________

存储库结构

mcp-project-speckit/
├── README.md                          # This file
├── instructions.md                    # SpecKit step-by-step process
├── .specify/
│   └── memory/
│       └── constitution.md            # Project constitution (principles)
├── specs/
│   ├── 001-mcp-registry-ui/           # Frontend specifications
│   │   ├── spec.md                    # User stories and requirements
│   │   ├── plan.md                    # Technical architecture
│   │   ├── tasks.md                   # Implementation tasks (85 tasks)
│   │   ├── data-model.md              # Data structures and types
│   │   ├── quickstart.md              # Manual verification guide
│   │   └── contracts/
│   │       ├── indexeddb-schema.md    # Database schema contract
│   │       └── validation-schema.md   # Validation rules
│   └── 002-fastapi-postgres-backend/  # Backend specifications
│       ├── spec.md                    # User stories and requirements
│       ├── plan.md                    # Technical architecture
│       ├── tasks.md                   # Implementation tasks (51 tasks)
│       ├── data-model.md              # Database schema and models
│       ├── quickstart.md              # Backend setup and testing
│       └── contracts/
│           ├── api-endpoints.md       # API contract documentation
│           └── database-schema.sql    # SQL schema reference
├── frontend/                          # React TypeScript application
│   ├── src/
│   │   ├── components/                # UI components (auth, admin, layout, etc.)
│   │   ├── pages/                     # Route-level components
│   │   ├── services/                  # API and business logic
│   │   ├── types/                     # TypeScript type definitions
│   │   ├── utils/                     # Utility functions
│   │   ├── config/                    # MSAL and app configuration
│   │   └── context/                   # React context (auth state)
│   ├── package.json                   # Dependencies and scripts
│   ├── vite.config.ts                 # Vite build configuration
│   ├── tailwind.config.js             # Tailwind CSS theme
│   └── README.md                      # Frontend setup guide
├── backend/                           # FastAPI Python application
│   ├── src/
│   │   ├── main.py                    # FastAPI app entry point
│   │   ├── config.py                  # Environment configuration
│   │   ├── database.py                # PostgreSQL connection pool
│   │   ├── dependencies.py            # FastAPI dependencies
│   │   ├── auth/                      # JWT token validation
│   │   ├── models/                    # Pydantic internal models
│   │   ├── schemas/                   # API request/response schemas
│   │   ├── services/                  # Business logic layer
│   │   └── routers/                   # API endpoint routes
│   ├── scripts/
│   │   └── db/
│   │       ├── init_schema.sql        # Database creation script
│   │       └── README.md              # Database setup guide
│   ├── pyproject.toml                 # Python dependencies (uv)
│   ├── .env.example                   # Environment variables template
│   └── README.md                      # Backend setup and running guide
├── Setup-EntraIDAdminGroup.ps1        # Automated Entra ID setup
├── Add-UserToAdminGroup.ps1           # Admin user management
├── List-AdminGroupMembers.ps1         # Admin audit script
├── ENTRA-ID-SETUP.md                  # Manual Entra ID guide
└── ENTRA-API-SETUP.md                 # API permissions guide

______________________________________________________________________

入门指南

先决条件

Node.js 18+（前端）
python 3.13+（用于后端）
PostgreSQL 14+（本地或Azure）
Azure订阅 （适用于Entra ID和Azure PostgreSQL）
Git 用于版本控制

快速开始

1.克隆存储库:

git clone https://github.com/yourusername/mcp-project-speckit.git
cd mcp-project-speckit

2.设置Entra ID （自动）：

cd mcp-project-speckit
.\Setup-EntraIDAdminGroup.ps1

这将创建：

Entra ID应用程序注册
管理员安全组
输出tenant_id、client_id、admin_group_id进行配置

3.设置后端:

cd backend

# Install dependencies with uv
uv pip install -e .

# Create .env from template
cp .env.example .env
# Edit .env with your Entra ID values and database URL

# Initialize database
psql -U your_user -d your_database -f scripts/db/init_schema.sql

# Run backend
uvicorn src.main:app --reload --port 8000

4.设置前端:

cd frontend

# Install dependencies
npm install

# Create .env from template
cp .env.example .env
# Edit .env with your Entra ID client_id and tenant_id

# Run frontend
npm run dev

5.访问申请:

前端： http://localhost:5173
后端API： http://localhost:8000
API文件： http://localhost:8000/docs （自动OpenAPI文档）

6.让自己成为管理员:

.\Add-UserToAdminGroup.ps1 -UserEmail your.email@yourdomain.com

人工验证

由于该项目遵循“无测试”原则，因此使用手动验证清单：

前端：参见 specs/001-mcp-registry-ui/quickstart.md

后端：参见 specs/002-fastapi-postgres-backend/quickstart.md

______________________________________________________________________

下一步（未来增强功能）

SpecKit过程是为迭代开发而设计的。以下是合乎逻辑的下一阶段：

第3阶段：审计记录（分支003）

用户故事：完整的合规审计跟踪

跟踪所有注册状态更改
记录谁做了更改以及何时做了更改
可查询的审核历史端点
将审计日志导出为CSV/JSON

预估工作量：使用SpecKit 1-2天

第4阶段：端点健康监测（分支004）

用户故事：验证MCP端点是否可访问

对批准的终点进行定期健康检查
状态仪表板（健康/降级/故障）
端点故障的自动警报
历史正常运行时间跟踪

预估工作量：使用SpecKit 2-3天

第5阶段：高级搜索和分类（分支005）

用户故事：增强了可发现性

端点标签/类别系统
分面搜索（按类别、所有者、工具筛选）
已保存的搜索查询
端点建议

预估工作量：使用SpecKit 2天

第6阶段：测试接口（分支006）

用户故事：直接从注册表测试MCP服务器

每个端点的交互式测试面板
发送示例请求，查看响应
工具能力验证
性能指标（延迟、吞吐量）

预估工作量：使用SpecKit 3-4天

第7阶段：部署和可扩展性（分支007）

用户故事：生产就绪部署

Docker容器化
Azure容器应用或应用服务部署
水平缩放配置
前端资产CDN
监控和警报（应用程序洞察）

预估工作量：使用SpecKit 2-3天

______________________________________________________________________

结论

这个项目展示了 规格套件 用于客户参与场景中快速、规范驱动的开发。通过遵循结构化的流程——构成、规范、规划、任务分解、实施——我们在 5天这通常需要7-9周的时间。

关键要点：

规格驱动一切：明确的要求消除歧义，减少返工
宪法防止混乱：预先制定的基本规则防止项目中期辩论
任务粒度促进进度：85+个小任务提供可见、可跟踪的进度
AI加速：AI工具（GitHub Copilot、Claude）在良好规范的指导下将实现速度提高了5-10倍
分支隔离：前端和后端的单独规范支持并行进度
手动验证工作：对于原型，手动测试比自动测试套件更快、更实用
文档作为人工制品：规范仍然准确，因为它们推动了实施

对于售前工程师：

SpecKit不仅仅是一种开发方法——它是一种 客户参与框架。使用它可以：

在销售周期中展示技术能力
在几天而不是几周内交付工作原型
与工程团队建立信誉
通过可行性证明缩短销售周期
为常见场景创建可重用的模板

对于开发团队：

即使在销售环境之外，SpecKit原则也适用：

绿地项目：更快地从想法到工作代码
原型设计：在承诺之前验证技术方法
文件优先：作为活文档的规范
AI配对编程：AI编码助手的结构化提示

______________________________________________________________________

资源

文档

流程指南: instructions.md -一步一步的SpecKit工作流程
宪法: .specify/memory/constitution.md -项目原则
前端规格: specs/001-mcp-registry-ui/
后端规格: specs/002-fastapi-postgres-backend/

设置指南

Entra ID设置: ENTRA-ID-SETUP.md
Entra API设置: ENTRA-API-SETUP.md
后端设置: backend/README.md
前端设置: frontend/README.md

脚本

自动入境者ID设置: Setup-EntraIDAdminGroup.ps1
行政管理: Add-UserToAdminGroup.ps1
行政审计: List-AdminGroupMembers.ps1

外部参考

模型上下文协议（MCP） -什么是MCP服务器
Microsoft Entra ID -身份验证平台
FastAPI文档 -后端框架
React文档 -前端框架
Azure PostgreSQL -数据库托管

______________________________________________________________________

联系与反馈

该项目是作为客户参与场景规范驱动开发的实验而创建的。欢迎反馈、提问和建议。

项目维护人员：\[您的姓名\]\ 组织：\[贵公司\]\ 目的：售前工程方法演示

______________________________________________________________________

*使用SpecKit生成-一种用于快速原型制作的规范驱动开发方法。*

最后更新：2025年11月12日

MCP Project Speckit

快速接入

详细介绍

SE的规范驱动开发方法

概述

挑战

学习：GitHub Copilot作为编码合作伙伴

什么是SpecKit？

起点：原始客户需求

原始客户要求（前端）

更新的客户需求（后端）

SpecKit流程：一步一步

第0阶段：宪法

确立的核心原则：

第1阶段：规范-前端（分支001）

用户故事定义：

关键决策：

第2阶段：规划-前端（分支001）

技术决策：

第3阶段：任务分解-前端（分支001）

第4阶段：实施-前端（分支001）

建造内容：

前端交付：

第5阶段：规范-后端（分支002）

用户故事定义：

关键决策：

第6阶段：规划-后端（002分支）

技术架构：

第7阶段：任务分解-后端（分支002）

第8阶段：实施-后端（分支002）

建造内容：

集成阶段：

后端交付：

项目可交付成果

前端(001-mcp-registry-ui)

后端(002-fastapi-postgres-backend)

支持脚本

关键SpecKit成果

规格质量

发展速度

代码质量

文档作为人工制品

经验教训

什么方法奏效了

遇到的挑战

下一次迭代的改进

售前工程师：使用SpecKit

何时使用SpecKit

如何运行SpecKit参与

成功指标

技术堆栈摘要

前端

后端

基础设施

开发工具

存储库结构

入门指南

先决条件

快速开始

人工验证

下一步（未来增强功能）

第3阶段：审计记录（分支003）

第4阶段：端点健康监测（分支004）

第5阶段：高级搜索和分类（分支005）

第6阶段：测试接口（分支006）

第7阶段：部署和可扩展性（分支007）

结论

关键要点：

对于售前工程师：

对于开发团队：

资源

文档

设置指南

脚本

外部参考

联系与反馈

目录标签

接入字段

权限和风险

来源信息

前端(`001-mcp-registry-ui`)

后端(`002-fastapi-postgres-backend`)