ai-spec-dev 0.41.0 → 0.42.0

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

@@ -0,0 +1,211 @@
+# 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）。

package/demo-backend/src/controllers/bookmark.controller.test.ts

@@ -0,0 +1,255 @@
+import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
+import { Request, Response, NextFunction } from 'express';
+import {
+  getBookmarks,
+  createBookmark,
+  updateBookmark,
+  deleteBookmark,
+} from '../bookmark.controller';
+import * as bookmarkService from '../../services/bookmark.service';
+import { AppError } from '../../middleware/error.middleware';
+
+vi.mock('../../services/bookmark.service');
+
+const mockedBookmarkService = vi.mocked(bookmarkService);
+
+describe('Bookmark Controller', () => {
+  let mockRequest: Partial<Request>;
+  let mockResponse: Partial<Response>;
+  let mockNext: NextFunction;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockResponse = {
+      status: vi.fn().mockReturnThis(),
+      json: vi.fn().mockReturnThis(),
+      send: vi.fn().mockReturnThis(),
+    };
+    mockNext = vi.fn();
+  });
+
+  describe('getBookmarks', () => {
+    it('should return 200 with paginated bookmarks', async () => {
+      const mockBookmarks = [
+        {
+          id: '1',
+          title: 'Test',
+          url: 'https://test.com',
+          tags: ['test'],
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        },
+      ];
+      const mockTotal = 1;
+
+      mockRequest = {
+        query: { limit: '10', offset: '0' },
+      };
+
+      mockedBookmarkService.getBookmarks.mockResolvedValue({
+        bookmarks: mockBookmarks,
+        total: mockTotal,
+      });
+
+      await getBookmarks(
+        mockRequest as Request,
+        mockResponse as Response,
+        mockNext
+      );
+
+      expect(mockedBookmarkService.getBookmarks).toHaveBeenCalledWith(10, 0);
+      expect(mockResponse.status).toHaveBeenCalledWith(200);
+      expect(mockResponse.json).toHaveBeenCalledWith({
+        code: 200,
+        message: 'success',
+        data: {
+          bookmarks: mockBookmarks,
+          total: mockTotal,
+        },
+      });
+    });
+
+    it('should call next with error when service throws', async () => {
+      const mockError = new AppError('Database error', 500, 'INTERNAL_ERROR');
+      mockRequest = {
+        query: {},
+      };
+
+      mockedBookmarkService.getBookmarks.mockRejectedValue(mockError);
+
+      await getBookmarks(
+        mockRequest as Request,
+        mockResponse as Response,
+        mockNext
+      );
+
+      expect(mockNext).toHaveBeenCalledWith(mockError);
+    });
+  });
+
+  describe('createBookmark', () => {
+    it('should return 201 with created bookmark', async () => {
+      const mockBookmark = {
+        id: '1',
+        title: 'Test',
+        url: 'https://test.com',
+        tags: ['test'],
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      mockRequest = {
+        body: {
+          title: 'Test',
+          url: 'https://test.com',
+          tags: ['test'],
+        },
+      };
+
+      mockedBookmarkService.createBookmark.mockResolvedValue(mockBookmark);
+
+      await createBookmark(
+        mockRequest as Request,
+        mockResponse as Response,
+        mockNext
+      );
+
+      expect(mockedBookmarkService.createBookmark).toHaveBeenCalledWith({
+        title: 'Test',
+        url: 'https://test.com',
+        tags: ['test'],
+      });
+      expect(mockResponse.status).toHaveBeenCalledWith(201);
+      expect(mockResponse.json).toHaveBeenCalledWith({
+        code: 201,
+        message: 'success',
+        data: mockBookmark,
+      });
+    });
+
+    it('should call next with validation error for invalid URL', async () => {
+      const mockError = new AppError(
+        'Validation failed: "url" must be a valid URL',
+        400,
+        'VALIDATION_ERROR'
+      );
+      mockRequest = {
+        body: {
+          title: 'Test',
+          url: 'invalid-url',
+        },
+      };
+
+      mockedBookmarkService.createBookmark.mockRejectedValue(mockError);
+
+      await createBookmark(
+        mockRequest as Request,
+        mockResponse as Response,
+        mockNext
+      );
+
+      expect(mockNext).toHaveBeenCalledWith(mockError);
+    });
+  });
+
+  describe('updateBookmark', () => {
+    it('should return 200 with updated bookmark', async () => {
+      const mockBookmark = {
+        id: '1',
+        title: 'Updated',
+        url: 'https://updated.com',
+        tags: ['updated'],
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      mockRequest = {
+        params: { id: '1' },
+        body: {
+          title: 'Updated',
+          url: 'https://updated.com',
+          tags: ['updated'],
+        },
+      };
+
+      mockedBookmarkService.updateBookmark.mockResolvedValue(mockBookmark);
+
+      await updateBookmark(
+        mockRequest as Request,
+        mockResponse as Response,
+        mockNext
+      );
+
+      expect(mockedBookmarkService.updateBookmark).toHaveBeenCalledWith('1', {
+        title: 'Updated',
+        url: 'https://updated.com',
+        tags: ['updated'],
+      });
+      expect(mockResponse.status).toHaveBeenCalledWith(200);
+      expect(mockResponse.json).toHaveBeenCalledWith({
+        code: 200,
+        message: 'success',
+        data: mockBookmark,
+      });
+    });
+
+    it('should call next with 404 when bookmark not found', async () => {
+      const mockError = new AppError('Bookmark not found', 404, 'NOT_FOUND');
+      mockRequest = {
+        params: { id: 'non-existent-id' },
+        body: {
+          title: 'Updated',
+          url: 'https://updated.com',
+          tags: [],
+        },
+      };
+
+      mockedBookmarkService.updateBookmark.mockRejectedValue(mockError);
+
+      await updateBookmark(
+        mockRequest as Request,
+        mockResponse as Response,
+        mockNext
+      );
+
+      expect(mockNext).toHaveBeenCalledWith(mockError);
+    });
+  });
+
+  describe('deleteBookmark', () => {
+    it('should return 204 with no content', async () => {
+      mockRequest = {
+        params: { id: '1' },
+      };
+
+      mockedBookmarkService.deleteBookmark.mockResolvedValue(undefined);
+
+      await deleteBookmark(
+        mockRequest as Request,
+        mockResponse as Response,
+        mockNext
+      );
+
+      expect(mockedBookmarkService.deleteBookmark).toHaveBeenCalledWith('1');
+      expect(mockResponse.status).toHaveBeenCalledWith(204);
+      expect(mockResponse.send).toHaveBeenCalled();
+    });
+
+    it('should call next with 404 when bookmark not found', async () => {
+      const mockError = new AppError('Bookmark not found', 404, 'NOT_FOUND');
+      mockRequest = {
+        params: { id: 'non-existent-id' },
+      };
+
+      mockedBookmarkService.deleteBookmark.mockRejectedValue(mockError);
+
+      await deleteBookmark(
+        mockRequest as Request,
+        mockResponse as Response,
+        mockNext
+      );
+
+      expect(mockNext).toHaveBeenCalledWith(mockError);
+    });
+  });
+});

package/demo-backend/src/controllers/bookmark.controller.ts

@@ -0,0 +1,187 @@
+import { Request, Response, NextFunction } from 'express';
+import { AppError } from '../middleware/error.middleware';
+import * as bookmarkService from '../services/bookmark.service';
+
+interface BookmarkQueryParams {
+  limit?: string;
+  offset?: string;
+}
+
+interface CreateBookmarkBody {
+  title?: string;
+  url?: string;
+  tags?: string[];
+}
+
+interface UpdateBookmarkBody {
+  title?: string;
+  url?: string;
+  tags?: string[];
+}
+
+interface BookmarkParams {
+  id?: string;
+}
+
+export class BookmarkController {
+  static async getBookmarks(
+    req: Request<{}, {}, {}, BookmarkQueryParams>,
+    res: Response,
+    next: NextFunction
+  ) {
+    try {
+      const { limit: limitStr, offset: offsetStr } = req.query;
+      
+      const limit = limitStr ? parseInt(limitStr, 10) : 20;
+      const offset = offsetStr ? parseInt(offsetStr, 10) : 0;
+      
+      if (isNaN(limit) || limit <= 0) {
+        throw new AppError(400, '"limit" must be a positive integer');
+      }
+      
+      if (isNaN(offset) || offset < 0) {
+        throw new AppError(400, '"offset" must be a non-negative integer');
+      }
+      
+      const result = await bookmarkService.getBookmarks(limit, offset);
+      
+      res.status(200).json({
+        code: 200,
+        message: 'success',
+        data: {
+          bookmarks: result.bookmarks,
+          total: result.total
+        }
+      });
+    } catch (error) {
+      next(error);
+    }
+  }
+  
+  static async createBookmark(
+    req: Request<{}, {}, CreateBookmarkBody>,
+    res: Response,
+    next: NextFunction
+  ) {
+    try {
+      const { title, url, tags } = req.body;
+      
+      if (!title || typeof title !== 'string' || title.trim() === '') {
+        throw new AppError(400, '"title" is required and must be a non-empty string');
+      }
+      
+      if (!url || typeof url !== 'string') {
+        throw new AppError(400, '"url" is required and must be a string');
+      }
+      
+      try {
+        new URL(url);
+      } catch {
+        throw new AppError(400, '"url" must be a valid URL');
+      }
+      
+      if (tags !== undefined && !Array.isArray(tags)) {
+        throw new AppError(400, '"tags" must be an array of strings');
+      }
+      
+      if (tags && !tags.every(tag => typeof tag === 'string')) {
+        throw new AppError(400, '"tags" must be an array of strings');
+      }
+      
+      const bookmark = await bookmarkService.createBookmark({
+        title: title.trim(),
+        url: url.trim(),
+        tags: tags || []
+      });
+      
+      res.status(201).json({
+        code: 201,
+        message: 'success',
+        data: bookmark
+      });
+    } catch (error) {
+      next(error);
+    }
+  }
+  
+  static async updateBookmark(
+    req: Request<BookmarkParams, {}, UpdateBookmarkBody>,
+    res: Response,
+    next: NextFunction
+  ) {
+    try {
+      const { id } = req.params;
+      const { title, url, tags } = req.body;
+      
+      if (!id) {
+        throw new AppError(400, '"id" parameter is required');
+      }
+      
+      const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+      if (!uuidRegex.test(id)) {
+        throw new AppError(400, '"id" must be a valid UUID');
+      }
+      
+      if (!title || typeof title !== 'string' || title.trim() === '') {
+        throw new AppError(400, '"title" is required and must be a non-empty string');
+      }
+      
+      if (!url || typeof url !== 'string') {
+        throw new AppError(400, '"url" is required and must be a string');
+      }
+      
+      try {
+        new URL(url);
+      } catch {
+        throw new AppError(400, '"url" must be a valid URL');
+      }
+      
+      if (!tags || !Array.isArray(tags)) {
+        throw new AppError(400, '"tags" is required and must be an array of strings');
+      }
+      
+      if (!tags.every(tag => typeof tag === 'string')) {
+        throw new AppError(400, '"tags" must be an array of strings');
+      }
+      
+      const bookmark = await bookmarkService.updateBookmark(id, {
+        title: title.trim(),
+        url: url.trim(),
+        tags
+      });
+      
+      res.status(200).json({
+        code: 200,
+        message: 'success',
+        data: bookmark
+      });
+    } catch (error) {
+      next(error);
+    }
+  }
+  
+  static async deleteBookmark(
+    req: Request<BookmarkParams>,
+    res: Response,
+    next: NextFunction
+  ) {
+    try {
+      const { id } = req.params;
+      
+      if (!id) {
+        throw new AppError(400, '"id" parameter is required');
+      }
+      
+      const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+      if (!uuidRegex.test(id)) {
+        throw new AppError(400, '"id" must be a valid UUID');
+      }
+      
+      await bookmarkService.deleteBookmark(id);
+      
+      res.status(204).send();
+    } catch (error) {
+      next(error);
+    }
+  }
+}

package/demo-backend/src/index.ts

@@ -0,0 +1,17 @@
+import express from "express";
+import cors from "cors";
+
+const app = express();
+app.use(cors());
+app.use(express.json());
+
+app.get("/health", (_req, res) => {
+  res.json({ status: "ok" });
+});
+
+const PORT = process.env.PORT || 3001;
+app.listen(PORT, () => {
+  console.log(`Server running on http://localhost:${PORT}`);
+});
+
+export default app;