ai-spec-dev 0.42.0 → 0.46.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spec-dev",
-  "version": "0.42.0",
+  "version": "0.46.0",
   "description": "AI-driven Development Orchestrator SDK & CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/demo-backend/.ai-spec-constitution.md

@@ -1,65 +0,0 @@
-# Project Constitution
-
-## 1. 架构规则 (Architecture Rules)
-- **分层架构**：项目采用三层架构 `routes → controllers → services → database`。
-- **禁止跨层调用**：
-  - `routes` 层仅负责定义路由和中间件，不能包含业务逻辑。
-  - `controllers` 层负责接收请求、调用 `services` 和返回响应，不能直接操作数据库。
-  - `services` 层封装核心业务逻辑，是唯一允许直接调用数据访问层（如 Prisma）的层级。
-- **模块组织**：功能模块按领域划分，每个模块包含独立的 `routes.ts`, `controller.ts`, `service.ts` 文件。
-
-## 2. 命名规范 (Naming Conventions)
-- **文件命名**：使用 `kebab-case`（如 `user-profile.controller.ts`）。
-- **变量/函数**：使用 `camelCase`（如 `getUserById`）。
-- **类/接口**：使用 `PascalCase`（如 `UserService`）。
-- **路由路径**：使用 `kebab-case`，资源名词复数（如 `/api/v1/user-profiles`）。
-
-## 3. API 规范 (API Patterns)
-- **路由前缀**：
-  - 客户端 API：`/api/v1/...`
-  - 管理端 API：`/api/v1/admin/...`
-- **统一响应结构**：
-  ```json
-  {
-    "code": 200,
-    "message": "success",
-    "data": {}
-  }
-  ```
-- **错误码规范**：
-  - `400`：客户端请求错误（参数错误、验证失败）
-  - `401`：未认证
-  - `403`：无权限
-  - `404`：资源不存在
-  - `500`：服务器内部错误
-- **认证/鉴权**：使用 `auth.middleware.ts` 保护需要认证的路由，位于 `middleware/` 目录。
-
-## 4. 数据层规范 (Data Layer Rules)
-- **数据库访问**：仅允许在 `service` 层使用 Prisma Client 进行数据库操作。
-- **模型命名**：Prisma model 使用 `PascalCase`（如 `UserProfile`），表名使用 `snake_case`（如 `user_profiles`）。
-- **事务处理**：复杂业务逻辑使用 Prisma 的 `$transaction` API 保证数据一致性。
-
-## 5. 错误处理规范 (Error Handling Patterns)
-- **统一错误中间件**：使用 `error.middleware.ts` 捕获所有错误，位于 `middleware/` 目录。
-- **错误抛出**：在 `service` 或 `controller` 中抛出 `AppError`（自定义错误类，包含 `code` 和 `message`）。
-- **已知错误码**：
-  - `VALIDATION_ERROR` (400)
-  - `UNAUTHORIZED` (401)
-  - `FORBIDDEN` (403)
-  - `NOT_FOUND` (404)
-  - `INTERNAL_ERROR` (500)
-
-## 6. 禁区 (Red Lines — Never Violate)
-- [ ] **禁止**在 `controller` 或 `route` 层直接操作数据库（必须通过 `service`）。
-- [ ] **禁止**创建重复的配置文件（如错误码、路由定义），必须追加到现有文件。
-- [ ] **禁止**使用 `any` 类型，必须定义明确的接口或类型。
-- [ ] **禁止**提交未通过 `vitest` 测试的代码。
-
-## 7. 测试规范 (Testing Rules)
-- **测试文件位置**：与源文件同目录，命名规则为 `*.test.ts` 或 `*.spec.ts`。
-- **测试覆盖**：必须为所有 `service` 和 `controller` 方法编写单元测试，关键业务流程需包含集成测试。
-- **测试框架**：使用 `vitest` 进行单元测试和集成测试，使用 `supertest` 进行 HTTP 接口测试。
-
-## 8. 共享配置文件清单 (Shared Config Files — Append-Only)
-
-(No shared config files detected — will be populated on first run)

package/demo-backend/package.json

@@ -1,21 +0,0 @@
-{
-  "name": "demo-backend",
-  "version": "0.1.0",
-  "private": true,
-  "scripts": {
-    "dev": "ts-node src/index.ts",
-    "build": "tsc",
-    "test": "vitest run"
-  },
-  "dependencies": {
-    "express": "^4.18.2",
-    "cors": "^2.8.5"
-  },
-  "devDependencies": {
-    "typescript": "^5.7.0",
-    "@types/express": "^4.17.21",
-    "@types/cors": "^2.8.17",
-    "ts-node": "^10.9.2",
-    "vitest": "^2.1.0"
-  }
-}

package/demo-backend/prisma/schema.prisma

@@ -1,22 +0,0 @@
-// This is your Prisma schema file,
-// learn more about it in the docs: https://pris.ly/d/prisma-schema
-
-generator client {
-  provider = "prisma-client-js"
-}
-
-datasource db {
-  provider = "postgresql"
-  url      = env("DATABASE_URL")
-}
-
-model Bookmark {
-  id        String   @id @default(uuid())
-  title     String
-  url       String
-  tags      String[]
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-
-  @@map("bookmarks")
-}

package/demo-backend/specs/feature-1-bookmark-id-uuid-title-string-required-url-str-v1.dsl.json

@@ -1,186 +0,0 @@
-{
-  "version": "1.0",
-  "feature": {
-    "id": "bookmark-management-system",
-    "title": "Bookmark 管理系统",
-    "description": "实现个人书签管理系统，支持创建、查看、编辑、删除网页书签，通过标签分类和分页浏览。"
-  },
-  "models": [
-    {
-      "name": "Bookmark",
-      "description": "书签数据模型，包含标题、URL和标签等信息",
-      "fields": [
-        {
-          "name": "id",
-          "type": "String",
-          "required": true,
-          "unique": true,
-          "description": ""
-        },
-        {
-          "name": "title",
-          "type": "String",
-          "required": true,
-          "unique": false,
-          "description": "书签标题"
-        },
-        {
-          "name": "url",
-          "type": "String",
-          "required": true,
-          "unique": false,
-          "description": "书签URL，需为有效URL格式"
-        },
-        {
-          "name": "tags",
-          "type": "String[]",
-          "required": false,
-          "unique": false,
-          "description": "标签数组"
-        },
-        {
-          "name": "createdAt",
-          "type": "DateTime",
-          "required": true,
-          "unique": false,
-          "description": "创建时间"
-        },
-        {
-          "name": "updatedAt",
-          "type": "DateTime",
-          "required": true,
-          "unique": false,
-          "description": "更新时间"
-        }
-      ],
-      "relations": []
-    }
-  ],
-  "endpoints": [
-    {
-      "id": "EP-001",
-      "method": "GET",
-      "path": "/api/v1/bookmarks",
-      "description": "获取书签分页列表",
-      "auth": false,
-      "request": {
-        "body": {},
-        "query": {
-          "limit": "integer (positive, default 20)",
-          "offset": "integer (non-negative, default 0)"
-        },
-        "params": {}
-      },
-      "successStatus": 200,
-      "successDescription": "返回书签数组及总数",
-      "errors": [
-        {
-          "status": 400,
-          "code": "VALIDATION_ERROR",
-          "description": "查询参数验证失败，如 limit 或 offset 无效"
-        },
-        {
-          "status": 500,
-          "code": "INTERNAL_ERROR",
-          "description": "服务器内部错误"
-        }
-      ]
-    },
-    {
-      "id": "EP-002",
-      "method": "POST",
-      "path": "/api/v1/bookmarks",
-      "description": "创建新书签",
-      "auth": false,
-      "request": {
-        "body": {
-          "title": "string (required, non-empty)",
-          "url": "string (required, valid URL format)",
-          "tags": "string array (optional)"
-        },
-        "query": {},
-        "params": {}
-      },
-      "successStatus": 201,
-      "successDescription": "返回新创建的书签信息",
-      "errors": [
-        {
-          "status": 400,
-          "code": "VALIDATION_ERROR",
-          "description": "请求体验证失败，如 title 为空或 url 格式无效"
-        },
-        {
-          "status": 500,
-          "code": "INTERNAL_ERROR",
-          "description": "服务器内部错误"
-        }
-      ]
-    },
-    {
-      "id": "EP-003",
-      "method": "PUT",
-      "path": "/api/v1/bookmarks/:id",
-      "description": "全量更新指定书签",
-      "auth": false,
-      "request": {
-        "body": {
-          "title": "string (required)",
-          "url": "string (required, valid URL format)",
-          "tags": "string array (required)"
-        },
-        "query": {},
-        "params": {
-          "id": "string (UUID format)"
-        }
-      },
-      "successStatus": 200,
-      "successDescription": "返回更新后的书签信息",
-      "errors": [
-        {
-          "status": 400,
-          "code": "VALIDATION_ERROR",
-          "description": "请求体验证失败"
-        },
-        {
-          "status": 404,
-          "code": "NOT_FOUND",
-          "description": "书签未找到"
-        },
-        {
-          "status": 500,
-          "code": "INTERNAL_ERROR",
-          "description": "服务器内部错误"
-        }
-      ]
-    },
-    {
-      "id": "EP-004",
-      "method": "DELETE",
-      "path": "/api/v1/bookmarks/:id",
-      "description": "删除指定书签",
-      "auth": false,
-      "request": {
-        "body": {},
-        "query": {},
-        "params": {
-          "id": "string (UUID format)"
-        }
-      },
-      "successStatus": 204,
-      "successDescription": "无响应体",
-      "errors": [
-        {
-          "status": 404,
-          "code": "NOT_FOUND",
-          "description": "书签未找到"
-        },
-        {
-          "status": 500,
-          "code": "INTERNAL_ERROR",
-          "description": "服务器内部错误"
-        }
-      ]
-    }
-  ],
-  "behaviors": []
-}

package/demo-backend/specs/feature-1-bookmark-id-uuid-title-string-required-url-str-v1.md

@@ -1,211 +0,0 @@
-# Feature Spec: Bookmark 管理系统
-
-## 1. 功能概述 (Overview)
-本功能旨在实现一个基础的个人书签管理系统。它允许用户创建、查看、编辑和删除网页书签，并支持通过标签进行简单分类和分页浏览，解决了个人或团队对常用网页链接进行集中存储和快速检索的需求。
-
-## 2. 背景与动机 (Background)
-- **当前问题**：用户或团队成员可能通过浏览器书签栏、笔记软件或聊天记录零散地保存网页链接，缺乏统一的管理界面，难以共享、检索和分类。
-- **构建理由**：作为系统的基础数据管理功能，为后续可能的搜索、分享、高级分类等功能奠定数据基础。
-- **用户价值**：提供一个集中、结构化的界面来管理个人或项目相关的网页资源，提升信息获取效率。
-
-## 3. 用户故事 (User Stories)
-- 作为 **用户**，我希望能 **创建一个新的书签（包含标题、URL和标签）**，以便 **保存我感兴趣的网页链接**。
-- 作为 **用户**，我希望能 **以分页列表的形式查看所有书签**，以便 **高效地浏览和找到目标书签**。
-- 作为 **用户**，我希望能 **编辑已保存书签的信息**，以便 **修正错误或更新信息**。
-- 作为 **用户**，我希望能 **删除不再需要的书签**，以便 **保持列表的整洁和相关性**。
-
-## 4. 功能需求 (Functional Requirements)
-
-### 4.1 核心功能
-- [ ] **Bookmark 数据模型**：实现包含 `id` (UUID), `title` (必填字符串), `url` (必填，需为有效URL格式), `tags` (字符串数组), `createdAt`, `updatedAt` 字段的模型。
-- [ ] **分页列表接口**：提供 `GET /api/v1/bookmarks` 接口，支持 `limit` 和 `offset` 查询参数进行分页，返回书签数组及总数。
-- [ ] **创建书签接口**：提供 `POST /api/v1/bookmarks` 接口，接收 `{ title, url, tags? }` 请求体，创建并返回新书签。
-- [ ] **更新书签接口**：提供 `PUT /api/v1/bookmarks/:id` 接口，接收完整书签信息，更新指定ID的书签。
-- [ ] **删除书签接口**：提供 `DELETE /api/v1/bookmarks/:id` 接口，删除指定ID的书签。
-- [ ] **排序**：所有列表查询结果默认按 `createdAt` 字段倒序排列。
-
-### 4.2 边界条件与错误处理
-- **输入验证**：
-    - `title`: 必填，非空字符串。
-    - `url`: 必填，需符合标准URL格式（可通过正则或URL构造函数验证）。
-    - `tags`: 可选，若提供则必须为字符串数组。
-    - `id` (路径参数): 必须为有效的UUID格式。
-    - `limit` (查询参数): 可选，正整数，默认20。
-    - `offset` (查询参数): 可选，非负整数，默认0。
-- **错误场景**：
-    - 请求体验证失败：返回 `400` 状态码，并在响应 `message` 中说明具体错误。
-    - 根据 `id` 查找不到资源（更新、删除、后续可能的获取详情）：返回 `404` 状态码。
-    - 服务器内部错误：返回 `500` 状态码。
-- **权限控制**：本次实现为简化版本，暂不涉及用户认证与鉴权，所有接口均为公开访问。未来可集成 `auth.middleware.ts` 进行保护。
-
-## 5. API 设计 (API Design)
-
-### 接口列表
-| Method | Endpoint | Auth Required | Description |
-|--------|----------|:-------------:|-------------|
-| GET | /api/v1/bookmarks | ❌ | 获取书签分页列表 |
-| POST | /api/v1/bookmarks | ❌ | 创建新书签 |
-| PUT | /api/v1/bookmarks/:id | ❌ | 全量更新指定书签 |
-| DELETE | /api/v1/bookmarks/:id | ❌ | 删除指定书签 |
-
-### 请求/响应示例
-
-**获取书签列表**
-
-```
-GET /api/v1/bookmarks?limit=2&offset=0
-```
-
-成功响应 (200)：
-```json
-{
-  "code": 200,
-  "message": "success",
-  "data": {
-    "bookmarks": [
-      {
-        "id": "550e8400-e29b-41d4-a716-446655440000",
-        "title": "Example Domain",
-        "url": "https://example.com",
-        "tags": ["example", "test"],
-        "createdAt": "2023-10-27T10:00:00.000Z",
-        "updatedAt": "2023-10-27T10:00:00.000Z"
-      }
-    ],
-    "total": 10
-  }
-}
-```
-
-**创建书签**
-
-```
-POST /api/v1/bookmarks
-Content-Type: application/json
-```
-
-请求体：
-```json
-{
-  "title": "GitHub",
-  "url": "https://github.com",
-  "tags": ["code", "repository"]
-}
-```
-
-成功响应 (201)：
-```json
-{
-  "code": 201,
-  "message": "success",
-  "data": {
-    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
-    "title": "GitHub",
-    "url": "https://github.com",
-    "tags": ["code", "repository"],
-    "createdAt": "2023-10-27T11:00:00.000Z",
-    "updatedAt": "2023-10-27T11:00:00.000Z"
-  }
-}
-```
-
-错误响应 (400 - URL格式无效)：
-```json
-{
-  "code": 400,
-  "message": "Validation failed: \"url\" must be a valid URL"
-}
-```
-
-**更新书签**
-
-```
-PUT /api/v1/bookmarks/6ba7b810-9dad-11d1-80b4-00c04fd430c8
-Content-Type: application/json
-```
-
-请求体：
-```json
-{
-  "title": "GitHub: Let’s build from here",
-  "url": "https://github.com",
-  "tags": ["code", "repository", "dev"]
-}
-```
-
-成功响应 (200)：
-```json
-{
-  "code": 200,
-  "message": "success",
-  "data": {
-    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
-    "title": "GitHub: Let’s build from here",
-    "url": "https://github.com",
-    "tags": ["code", "repository", "dev"],
-    "createdAt": "2023-10-27T11:00:00.000Z",
-    "updatedAt": "2023-10-27T11:05:00.000Z"
-  }
-}
-```
-
-错误响应 (404)：
-```json
-{
-  "code": 404,
-  "message": "Bookmark not found"
-}
-```
-
-**删除书签**
-
-```
-DELETE /api/v1/bookmarks/6ba7b810-9dad-11d1-80b4-00c04fd430c8
-```
-
-成功响应 (204 No Content)：无响应体。
-
-错误响应 (404)：
-```json
-{
-  "code": 404,
-  "message": "Bookmark not found"
-}
-```
-
-## 6. 数据模型 (Data Model)
-```prisma
-model Bookmark {
-  id        String   @id @default(uuid())
-  title     String
-  url       String
-  tags      String[]
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-
-  @@map("bookmarks")
-}
-```
-
-## 7. 非功能性需求 (Non-functional Requirements)
-- **性能**: 单次列表查询（带分页）响应时间应 < 200ms。预期支持数百条书签的并发读写。
-- **安全**: 对用户输入的 `url` 和 `title` 进行基本的清理，防止 XSS 等注入攻击（可在 service 层或通过中间件处理）。未来集成认证后，需确保用户只能操作自己的书签。
-- **可靠性**: `POST` 和 `PUT` 操作应保证幂等性（通过业务逻辑或数据库约束）。对于 `PUT` 操作，需先检查资源是否存在。
-- **可维护性**: 在关键业务路径（如创建、更新、删除）记录 `info` 级别日志。记录 `error` 级别日志并关联请求上下文。监控 API 的请求量、错误率和响应时间。
-
-## 8. 实施要点 (Implementation Notes)
-- **集成点**: 完全基于现有 Express + TypeScript + Prisma 技术栈。需与 `error.middleware.ts` 集成以处理 `AppError`。
-- **实施顺序**:
-    1. **数据模型**: 在 `prisma/schema.prisma` 中添加 `Bookmark` 模型，并运行迁移。
-    2. **服务层 (`service.ts`)**: 实现核心业务逻辑（CRUD、分页查询、输入验证）。
-    3. **控制器层 (`controller.ts`)**: 处理 HTTP 请求，调用 service，构造响应。
-    4. **路由层 (`routes.ts`)**: 定义 API 端点，将请求映射到控制器方法。
-    5. **测试**: 为 service 和 controller 编写单元测试，为 API 编写集成测试。
-- **技术注意事项**:
-    - 使用 Zod 或类似库在 service 层进行严格的输入验证。
-    - 分页查询使用 Prisma 的 `skip` 和 `take`，计数使用 `count` 方法。
-    - 严格遵循项目的三层架构 (`routes → controllers → services → database`)，禁止跨层调用。
-- **测试要点**:
-    - **Service 单测**: 验证 `createBookmark` 对无效 URL 的拒绝，`getBookmarks` 分页逻辑的正确性。
-    - **Controller 单测**: 验证对 service 的调用和对 HTTP 响应（状态码、格式）的正确构造。
-    - **API 集成测试**: 使用 `supertest` 模拟完整的 HTTP 请求流程，覆盖成功和错误场景（400, 404）。