13 · Notepads 记事本

# API 设计约定
 
## 端点命名
- 全部使用 RESTful 风格：/resources/{id}
- 复数名词：/users, /orders, /products
- 版本号在 URL 中：/v1/users/{id}
 
## 响应格式
所有响应使用统一包装：
 
```json
{
  "code": 200,
  "message": "success",
  "data": { ... },
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 100
  }
}

之后在 Chat 或 Composer 中输入 `@api-patterns`，AI 就会**精确理解这套 API 约束**，生成的代码自然遵循这些约定。

---

## 03 Notepads 面板详解

Notepads 面板位于左侧活动栏，和文件浏览器、搜索、Git 同级。打开后你会发现几个关键区域：

### 列表区

显示所有已创建的 Notepad，按**最近修改时间**排序。每个条目显示：
- 名称（标题）
- 摘要（第一行内容预览）
- 更新时间

### 筛选与搜索

面板顶部有搜索框——你可以输入名称或关键词快速定位 Notepad。当你的 Notepad 数量多起来之后（10+ 个），这个搜索功能就变得非常实用。

### 分组管理

Cursor 允许你给 Notepad 添加**标签**或**前缀命名**来实现逻辑分组。比如：

| 分组 | 命名惯例 | 示例 |
|------|---------|------|
| 项目文档 | `doc-` 前缀 | `doc-prd`, `doc-api-design` |
| 编码约定 | `rule-` 前缀 | `rule-typescript`, `rule-test` |
| 架构笔记 | `arch-` 前缀 | `arch-db-schema`, `arch-auth-flow` |
| 团队规范 | `team-` 前缀 | `team-review-checklist`, `team-git-workflow` |

虽然没有官方的"文件夹"功能，但用前缀命名 + 搜索框的组合，已经足够管理几十个 Notepad。

### 编辑区

点击列表中的任意 Notepad，会在主编辑区打开它的内容——就像编辑一个普通文件。支持完整的 Markdown 语法，也**支持代码块**。

> **注意**：Notepad 和项目文件是不同的概念。Notepad 存储在 Cursor 的内部状态中（跨项目、跨会话持久），而文件是存储在磁盘上的项目代码。这意味着你换一个项目打开，Notepads 依然在。

---

## 04 如何引用：@NotepadName 精讲

引用 Notepad 的方式和你引用文件、符号、代码库完全一致——在输入框中输入 `@` 后接 Notepad 名称。

### 基础引用

```md
@api-patterns 请帮我按现有的 API 规范新建一个用户接口

用户：帮我写一个用户列表接口。

AI：（没有上下文）好的，我创建一个 Express 路由...

用户：@api-patterns 帮我写一个获取用户列表的接口。

AI：（读取 api-patterns 后）好的，按照你们的 API 规范：
- 端点：GET /v1/users
- 响应：统一包装格式
- 认证：需要 Bearer Token
- 分页参数：page 和 pageSize

# sprint-24-prd
 
## 功能：用户通知中心
- 用户能在右上角看到未读通知数量（小红点）
- 点击展开通知列表，最多显示 20 条
- 通知分三类：系统通知、评论回复、状态变更
- 点击通知跳转到对应页面
- 全部标记已读按钮
 
## 非功能需求
- 通知实时性：30 秒内推送到前端
- 未读数存在 Redis，不查数据库
- 通知列表分页，每页 10 条
 
## 排期
- 后端 API：本周三前
- 前端 UI：本周五前
- 联调测试：下周一

# arch-auth-flow
 
## 决策
采用 JWT + Refresh Token 双令牌方案
 
## 理由
1. 无状态认证，方便水平扩展
2. Refresh Token 实现"7 天免登录"，改善用户体验
3. Access Token 15 分钟过期，降低泄露风险
 
## 关键约束
- Access Token 不存数据库
- Refresh Token 存入 Redis，设置 7 天 TTL
- 刷新接口 /v1/auth/refresh 不做速率限制（但是要做 Token 轮换）
- 退出登录时删除 Redis 中的 Refresh Token
 
## 相关文件
- src/middleware/auth.ts
- src/services/auth.service.ts
- src/utils/jwt.ts

# rule-typescript
 
## 类型
- 优先使用 interface 而不是 type（对外 API 用 interface）
- 引入的第三方库类型用 import type
- 避免 any，用 unknown 代替
- 泛型参数用 T 开头：TItem, TResponse
 
## React
- 函数组件 + Hooks，不用类组件
- Props 接口命名为 ComponentNameProps
- Context + useReducer 管理全局状态，不用 Redux
- 自定义 Hook 用 use 前缀：useAuth, usePagination
 
## CSS
- Tailwind CSS 优先
- 复杂样式用 CSS Module
- 颜色变量从 tailwind.config.ts 中读取
- 响应式断点：sm(640) md(768) lg(1024) xl(1280)

# arch-db-schema
 
## 核心表
 
### users
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | UUID | PK | |
| email | VARCHAR(255) | UNIQUE NOT NULL | |
| name | VARCHAR(100) | NOT NULL | |
| role | ENUM('admin','user') | NOT NULL DEFAULT 'user' | |
| created_at | TIMESTAMP | NOT NULL DEFAULT NOW() | |
| updated_at | TIMESTAMP | NOT NULL | |
 
### orders
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | UUID | PK | |
| user_id | UUID | FK -> users.id | |
| status | ENUM(...) | NOT NULL | pending/paid/shipped/delivered/cancelled |
| total | DECIMAL(10,2) | NOT NULL | |
| created_at | TIMESTAMP | NOT NULL DEFAULT NOW() | |
 
### 关系
- users 1:N orders
- orders 1:N order_items
- order_items N:1 products

# rule-test
 
## 单元测试（Vitest）
- 测试文件放在 __tests__/ 目录下
- 命名：*.test.ts
- 每个测试用 describe + it 结构
- Mock 外部依赖，不 mock 内部函数
 
## 组件测试（Testing Library）
- 优先测试用户行为，不测试实现细节
- 使用 screen.getByRole / findByRole 定位元素
- 避免 data-testid（除非万不得已）
 
## 覆盖率要求
- 行覆盖率 >= 80%
- 分支覆盖率 >= 70%
- 核心逻辑（认证、支付）要求 100%

# doc-stripe-api
 
## 支付流程
1. 前端调用 POST /v1/payments/create-intent
2. 后端调用 stripe.paymentIntents.create() 创建
3. 返回 client_secret 给前端
4. 前端用 Stripe Elements 完成 3DS 认证
5. stripe webhook 通知 payment_intent.succeeded
6. 后端收到 webhook 后更新订单状态
 
## Webhook 验证
- 需要验证 stripe-signature 头
- 使用 stripe.webhooks.constructEvent()
- 本地测试用 stripe listen --forward-to localhost:3000/api/webhooks/stripe

一次性的背景说明 → 在 Chat 里直接打字告诉 AI
重复使用的背景知识 → 写成 Notepad，每次 @ 引用
全局生效的规则 → 写进 .cursorrules
只在当前对话有用的上下文 → 直接在对话中描述

项目 .cursorrules
  ├─ "使用 TypeScript 严格模式"
  ├─ "禁止使用 any 类型"
  ├─ "测试覆盖率必须 >= 80%"
  └─ "优先使用 named export"

个人 Notepads
  ├─ arch-auth-flow（你负责的认证模块设计文档）
  ├─ rule-test-strategy（你偏好的测试写法）
  └─ sprint-25-prd（当前迭代的需求要点）

@arch-auth-flow @api-patterns @sprint-25-prd 
请帮我实现用户注册功能，遵循所有已有的设计约束

@arch-auth-flow 我现在在编辑 @src/middleware/auth.ts，
请帮我检查这个中间件是否和我们既定的认证架构一致。
如果有不一致的地方，请搜索整个代码库 @codebase，
找出所有受影响的地方并给出修改方案。

# arch-decision-v2
 
## 更新历史
- v1 (2025-10-01): 初始版本，决定使用 PostgreSQL
- v2 (2025-12-15): 增加读写分离方案，引入 PgBouncer 连接池
 
## 当前方案
...