@umacloud/knowledge 1.0.1

package/backend/02-playbooks/email-send-playbook.md

@@ -0,0 +1,130 @@
+---
+id: email-send-playbook
+title: 邮件发送实战手册（Transactional Email）
+domain: backend
+category: 02-playbooks
+difficulty: intermediate
+tags: [email, smtp, sendgrid, ses, transactional, template, queue, retry, dkim, spf, enterprise]
+quality_score: 91
+maintainer: platform-team@umadev.com
+last_updated: 2026-06-15
+---
+
+# 邮件发送实战手册（Transactional Email）
+
+## 服务商选择
+
+| 服务 | 特点 | 适合 |
+|------|------|------|
+| AWS SES | 便宜（$0.10/1000封） | 大量发送、AWS 生态 |
+| SendGrid | 功能丰富（模板/A-B 测试） | SaaS 产品 |
+| Resend | 开发者体验好 | 新项目快速集成 |
+| Postmark | 事务邮件送达率高 | 关键邮件（验证码/订单） |
+| 自建 SMTP | 可控但维护重 | 合规要求 |
+
+## 异步队列发送（必须！）
+
+```python
+# ❌ 同步发送（请求阻塞 3-5 秒等待 SMTP）
+@app.post("/register")
+def register(data):
+    user = create_user(data)
+    send_email(user.email, "Welcome!")  # SMTP 3-5s → 用户等
+    return user
+
+# ✅ 异步队列（请求毫秒返回，后台发邮件）
+@app.post("/register")
+def register(data):
+    user = create_user(data)
+    enqueue_job("send_welcome_email", user.id)  # 入队毫秒
+    return user
+
+@celery.task(bind=True, max_retries=3)
+def send_welcome_email(self, user_id):
+    user = db.query(User).get(user_id)
+    try:
+        email_service.send(
+            to=user.email,
+            template="welcome",
+            data={"name": user.name},
+        )
+    except SMTPException as e:
+        raise self.retry(exc=e, countdown=60 * (2 ** self.request.retries))
+        # 指数退避重试：60s → 120s → 240s
+```
+
+## HTML 邮件模板
+
+```html
+<!-- ✅ 邮件兼容 HTML（不是现代 CSS！ Outlook 用 Word 引擎） -->
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0"
+       style="background-color:#f4f4f5;padding:24px;font-family:Arial,sans-serif;">
+  <tr><td align="center">
+    <table role="presentation" width="600" style="background:#ffffff;border-radius:8px;padding:32px;">
+      <tr><td>
+        <h1 style="color:#1a1a1a;font-size:24px;margin:0 0 16px;">
+          Welcome to Acme!
+        </h1>
+        <p style="color:#52525b;line-height:1.6;">
+          Hi {{name}},<br><br>
+          Thanks for signing up. Click below to verify your email:
+        </p>
+        <!-- 按钮：用 table 包裹（邮件兼容） -->
+        <table role="presentation" cellpadding="0" cellspacing="0" style="margin:24px 0;">
+          <tr><td style="background:#2563eb;border-radius:6px;">
+            <a href="{{verify_url}}" style="display:inline-block;padding:12px 32px;
+               color:#ffffff;text-decoration:none;font-weight:600;">
+              Verify Email
+            </a>
+          </td></tr>
+        </table>
+      </td></tr>
+    </table>
+  </td></tr>
+</table>
+```
+
+### 邮件 HTML 规则
+- 用 `<table>` 布局（不用 flex/grid）
+- 内联样式（不用 `<style>` 标签 + class）
+- 用 `role="presentation"`（屏幕阅读器跳过布局 table）
+- 宽度 600px（移动端友好）
+- 图片用绝对 URL（`https://cdn.example.com/logo.png`）
+- 纯文本版本（multipart，防垃圾邮件过滤）
+
+## DNS 认证（送达率必须）
+
+### SPF（发件服务器授权）
+```
+# DNS TXT 记录
+example.com.  TXT  "v=spf1 include:_spf.google.com include:amazonses.com ~all"
+# ~all = 软失败（不严格拒绝），-all = 硬失败
+```
+
+### DKIM（邮件签名验证）
+```
+# DNS TXT 记录（由邮件服务商提供）
+selector._domainkey.example.com.  TXT  "v=DKIM1; k=rsa; p=MIGfMA0GCS..."
+# 收件方用公钥验证邮件签名
+```
+
+### DMARC（策略汇总）
+```
+# DNS TXT 记录
+_dmarc.example.com.  TXT  "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com"
+# p=none（只报告）/ quarantine（隔离）/ reject（拒绝）
+```
+
+## 生产检查清单
+- [ ] 异步队列发送（不阻塞请求）
+- [ ] 指数退避重试（3 次：60s/120s/240s）
+- [ ] SPF + DKIM + DMARC DNS 配置
+- [ ] HTML 邮件用 table 布局（不用 flex/grid）
+- [ ] 内联 CSS（不用 style 标签）
+- [ ] 同时发纯文本版本（multipart）
+- [ ] 图片用绝对 CDN URL
+- [ ] 取消订阅链接（营销邮件必须）
+- [ ] 退信处理（bounce/complaint → 标记不发）
+- [ ] 速率限制（防 SMTP 服务商封禁）
+- [ ] 邮件模板预览（开发环境真实渲染）
+- [ ] 发送日志 + 送达率监控

package/backend/02-playbooks/file-upload-s3-playbook.md

@@ -0,0 +1,153 @@
+---
+id: file-upload-s3-playbook
+title: 文件上传实战手册（S3/MinIO）
+domain: backend
+category: 02-playbooks
+difficulty: advanced
+tags: [file-upload, s3, minio, presigned-url, multipart, virus-scan, thumbnail, cdn, backend, enterprise]
+quality_score: 93
+maintainer: platform-team@umadev.com
+last_updated: 2026-06-15
+---
+
+# 文件上传实战手册（S3 / MinIO）
+
+## 上传模式对比
+
+| 模式 | 流程 | 适合 | 限制 |
+|------|------|------|------|
+| 直传后端 | 前端 → 后端 → S3 | 小文件（< 5MB） | 后端带宽瓶颈 |
+| Presigned URL | 前端 → S3 直传 | 大文件（推荐） | 后端不经手 |
+| Multipart | 分片直传 S3 | 超大文件（> 100MB） | 复杂 |
+
+## Presigned URL（推荐）
+
+```python
+# 后端生成 presigned URL
+@app.post("/api/upload/sign")
+def create_presigned_upload(filename: str, content_type: str, user=Depends(get_current_user)):
+    # 1. 生成唯一 key（防覆盖）
+    key = f"uploads/{user.id}/{uuid.uuid4()}/{filename}"
+
+    # 2. 校验类型（白名单）
+    allowed = {"image/jpeg", "image/png", "image/webp", "application/pdf"}
+    if content_type not in allowed:
+        raise HTTPException(400, "File type not allowed")
+
+    # 3. 生成 presigned PUT URL（5 分钟有效）
+    url = s3.generate_presigned_url(
+        "put_object",
+        Params={
+            "Bucket": "my-bucket",
+            "Key": key,
+            "ContentType": content_type,
+        },
+        ExpiresIn=300,
+    )
+
+    # 4. 返回 URL + key（前端直传 S3）
+    return {"uploadUrl": url, "key": key, "expiresIn": 300}
+```
+
+```typescript
+// 前端直传 S3（不经过后端）
+async function uploadFile(file: File) {
+  // 1. 向后端获取 presigned URL
+  const { uploadUrl, key } = await api.post('/api/upload/sign', {
+    filename: file.name,
+    contentType: file.type,
+  });
+
+  // 2. 直接 PUT 到 S3
+  await fetch(uploadUrl, {
+    method: 'PUT',
+    headers: { 'Content-Type': file.type },
+    body: file,
+  });
+
+  // 3. 通知后端上传完成（记录 key）
+  await api.post('/api/upload/confirm', { key });
+}
+```
+
+## 安全
+
+### 文件类型验证（多层）
+```python
+# ❌ 只检查扩展名（不安全）
+if filename.endswith('.jpg'):  # 改名就能绕过
+
+# ✅ 多层验证
+# 1. Content-Type 白名单
+allowed_types = {"image/jpeg", "image/png", "image/webp"}
+
+# 2. Magic bytes（文件头）验证
+import magic
+real_type = magic.from_buffer(file_content, mime=True)
+if real_type not in allowed_types:
+    raise HTTPException(400, "File type mismatch")
+
+# 3. 文件大小限制（presigned URL 配置）
+# 4. 文件名消毒（防路径穿越）
+safe_name = os.path.basename(filename)  # 去掉 ../
+key = f"uploads/{uuid.uuid4()}/{safe_name}"
+```
+
+### 病毒扫描
+```python
+# ClamAV 集成（后台异步扫描）
+@celery.task
+def scan_file(key: str):
+    obj = s3.get_object(Bucket="my-bucket", Key=key)
+    result = clamav.scan_stream(obj["Body"])
+    if result.infected:
+        s3.delete_object(Bucket="my-bucket", Key=key)  # 删除感染文件
+        db.update(File, key, status="rejected")
+    else:
+        db.update(File, key, status="clean")
+```
+
+## 图片处理
+
+```python
+# 上传后生成缩略图（异步）
+@celery.task
+def generate_thumbnails(key: str):
+    original = s3.get_object(Bucket="my-bucket", Key=key)["Body"].read()
+    for size in [(150, 150), (400, 400), (800, 800)]:
+        thumb = PIL.Image.open(io.BytesIO(original))
+        thumb.thumbnail(size)
+        buf = io.BytesIO()
+        thumb.save(buf, format="WEBP", quality=85)  # 转 WebP 省空间
+        thumb_key = key.replace("uploads/", f"thumbs/{size[0]}x{size[0]}/")
+        s3.put_object(Bucket="my-bucket", Key=thumb_key, Body=buf.getvalue(), ContentType="image/webp")
+```
+
+## CDN 分发
+
+```yaml
+# CloudFront / Cloudflare 分发
+# 用户上传后 → S3 → CloudFront CDN → 全球加速分发
+Distribution:
+  Origins:
+    - S3Origin:
+        DomainName: my-bucket.s3.amazonaws.com
+  DefaultCacheBehavior:
+    ViewerProtocolPolicy: redirect-to-https
+    CachePolicyId: managed-CachingOptimized
+    # 图片缓存 1 年（内容不变）
+    MinTTL: 0
+    DefaultTTL: 31536000
+```
+
+## 生产检查清单
+- [ ] 用 Presigned URL 直传 S3（不经后端）
+- [ ] Content-Type 白名单 + Magic Bytes 验证
+- [ ] 文件大小限制（presigned URL + 前端）
+- [ ] UUID 文件 key（防覆盖/路径穿越）
+- [ ] 异步病毒扫描（ClamAV）
+- [ ] 图片自动生成缩略图（WebP 格式）
+- [ ] CDN 分发静态文件
+- [ ] CORS 配置（S3 bucket 只允许前端域名）
+- [ ] 生命周期策略（自动删除临时文件）
+- [ ] 上传进度条（前端 UX）

package/backend/02-playbooks/typescript-enterprise-playbook.md

@@ -0,0 +1,133 @@
+---
+id: typescript-enterprise-playbook
+title: TypeScript 企业级实战手册
+domain: backend
+category: 02-playbooks
+difficulty: advanced
+tags: [typescript, ts, types, generics, error-handling, result-type, discriminated-union, branded-type, type-guard, enterprise]
+quality_score: 93
+maintainer: platform-team@umadev.com
+last_updated: 2026-06-15
+---
+
+# TypeScript 企业级实战手册
+
+> 基于 [Udacity: Handling errors like a pro](https://engineering.udacity.com/handling-errors-like-a-pro-in-typescript-d7a314ad4991) + [5 Commandments of Clean Error Handling](https://medium.com/with-orus/the-5-commandments-of-clean-error-handling-in-typescript-93a9cbdf1af5)
+
+## 类型系统最佳实践
+
+### 禁用 any，用 unknown + 收窄
+```typescript
+// ❌ any 放弃类型安全
+function parse(data: any) {
+  return data.user.name;  // 运行时崩溃？
+}
+
+// ✅ unknown + 类型守卫
+function parse(data: unknown): string {
+  if (typeof data === 'object' && data !== null && 'user' in data) {
+    const user = (data as any).user;
+    if (typeof user?.name === 'string') return user.name;
+  }
+  throw new Error('Invalid data');
+}
+```
+
+### 品牌类型（Branded Types）防混淆
+```typescript
+// ❌ UserID 和 OrderID 都是 string，容易传混
+type UserId = string;
+type OrderId = string;
+function getOrders(userId: UserId) { ... }
+getOrders(orderId);  // 编译通过但逻辑错误！
+
+// ✅ 品牌类型编译期区分
+type UserId = string & { readonly __brand: 'UserId' };
+type OrderId = string & { readonly __brand: 'OrderId' };
+function getOrders(userId: UserId) { ... }
+getOrders(orderId);  // 编译错误！类型不匹配
+```
+
+### 判别联合（Discriminated Unions）
+```typescript
+// ✅ 状态用判别联合，编译期穷尽检查
+type ApiState =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: User[] }
+  | { status: 'error'; error: string };
+
+function render(state: ApiState) {
+  switch (state.status) {
+    case 'idle':    return <Placeholder />;
+    case 'loading': return <Spinner />;
+    case 'success': return <List items={state.data} />;
+    case 'error':   return <Error msg={state.error} />;
+    // 漏一个 case 编译就报错（穷尽检查）
+  }
+}
+```
+
+## 错误处理：Result 模式
+
+```typescript
+// ❌ throw 不可预测（调用者不知道会抛什么）
+async function getUser(id: string): Promise<User> {
+  const res = await fetch(`/api/users/${id}`);
+  if (!res.ok) throw new Error('Failed');  // 调用者怎么知道？
+  return res.json();
+}
+
+// ✅ Result 类型让错误显式（编译期知道所有可能结果）
+type Result<T, E = string> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+async function getUser(id: string): Promise<Result<User, 'not_found' | 'network'>> {
+  try {
+    const res = await fetch(`/api/users/${id}`);
+    if (res.status === 404) return { ok: false, error: 'not_found' };
+    if (!res.ok) return { ok: false, error: 'network' };
+    return { ok: true, value: await res.json() };
+  } catch {
+    return { ok: false, error: 'network' };
+  }
+}
+
+// 调用者必须处理错误（编译期强制）
+const result = await getUser('123');
+if (!result.ok) {
+  // result.error 是 'not_found' | 'network'
+  console.log(result.error);
+} else {
+  // result.value 是 User
+  console.log(result.value.name);
+}
+```
+
+## 泛型约束
+
+```typescript
+// ❌ 无约束泛型（太宽松）
+function getProperty<T>(obj: T, key: any): any {
+  return (obj as any)[key];  // 类型安全丢失
+}
+
+// ✅ 泛型约束（编译期保证 key 存在）
+function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
+  return obj[key];  // 类型安全，返回 T[K]
+}
+
+const user = { name: 'Alice', age: 30 };
+const name = getProperty(user, 'name');  // string
+const age = getProperty(user, 'age');    // number
+// getProperty(user, 'email');  // 编译错误！
+```
+
+## 5 条错误处理戒律
+
+1. **确保 Error 是真正的 Error**（不要 throw 字符串/数字）
+2. **保留堆栈跟踪**（`Error.captureStackTrace` / `cause` 链）
+3. **用常量错误码**（不用动态字符串做匹配）
+4. **提供足够上下文**（错误含 input/userId/requestId）
+5. **区分可恢复 vs 不可恢复**（4xx 可重试，5xx 告警）

package/backend/02-playbooks/websocket-realtime-playbook.md

@@ -0,0 +1,154 @@
+---
+id: websocket-realtime-playbook
+title: WebSocket 实时通信实战手册
+domain: backend
+category: 02-playbooks
+difficulty: advanced
+tags: [websocket, socketio, realtime, redis, pub-sub, scaling, sticky-session, reconnection, chat, notification, enterprise]
+quality_score: 93
+maintainer: platform-team@umadev.com
+last_updated: 2026-06-15
+---
+
+# WebSocket 实时通信实战手册
+
+> 基于 [Ably: Scaling Socket.IO](https://ably.com/topic/scaling-socketio) + [OneUptime WebSocket Scaling 2026](https://oneuptime.com/blog/post/2026-01-26-websocket-scaling/view) + [websocket.org Scale Guide](https://websocket.org/guides/websockets-at-scale/)
+
+## 单节点 Socket.IO
+
+```typescript
+import { Server } from "socket.io";
+
+const io = new Server(httpServer, {
+  cors: { origin: "https://app.example.com", credentials: true },
+});
+
+// 认证中间件
+io.use((socket, next) => {
+  const token = socket.handshake.auth.token;
+  if (!verifyJWT(token)) return next(new Error("Unauthorized"));
+  socket.userId = decodeJWT(token).sub;
+  next();
+});
+
+io.on("connection", (socket) => {
+  // 加入用户专属 room（方便定向推送）
+  socket.join(`user:${socket.userId}`);
+
+  socket.on("message", (data) => {
+    // 广播到房间（聊天场景）
+    socket.to(`room:${data.roomId}`).emit("message", data);
+  });
+
+  socket.on("disconnect", () => {
+    console.log(`User ${socket.userId} disconnected`);
+  });
+});
+```
+
+## 多节点扩展（Redis Pub/Sub）
+
+```typescript
+// ❌ 多节点不共享状态——用户 A 连到 Node 1，B 连到 Node 2
+// Node 1 发消息，Node 2 的用户收不到！
+
+// ✅ Redis Adapter——跨节点同步事件
+import { createAdapter } from "@socket.io/redis-adapter";
+import { createClient } from "redis";
+
+const pubClient = createClient({ url: "redis://redis:6379" });
+const subClient = pubClient.duplicate();
+await Promise.all([pubClient.connect(), subClient.connect()]);
+
+io.adapter(createAdapter(pubClient, subClient));
+// 现在 Node 1 发消息 → Redis → Node 2 的用户也能收到
+```
+
+### 负载均衡配置
+```nginx
+# nginx — WebSocket 需要 sticky session 或 IP hash
+upstream websocket {
+  ip_hash;  # 同一用户始终连同一节点（减少 Redis 转发）
+  server node1:3000;
+  server node2:3000;
+  server node3:3000;
+}
+
+# WebSocket upgrade
+location /socket.io/ {
+  proxy_pass http://websocket;
+  proxy_http_version 1.1;
+  proxy_set_header Upgrade $http_upgrade;
+  proxy_set_header Connection "upgrade";
+  proxy_read_timeout 86400;  # 长连接超时（24h）
+}
+```
+
+## 断线重连 + 消息队列
+
+```typescript
+// 前端：断线时消息入队，重连后补发
+const messageQueue = [];
+let isConnected = false;
+
+socket.on("connect", () => {
+  isConnected = true;
+  // 重连后补发队列消息
+  while (messageQueue.length > 0) {
+    socket.emit("message", messageQueue.shift());
+  }
+});
+
+socket.on("disconnect", () => {
+  isConnected = false;
+});
+
+function sendMessage(data) {
+  if (isConnected) {
+    socket.emit("message", data);
+  } else {
+    messageQueue.push(data);  // 离线入队
+  }
+}
+
+// 自动重连配置
+const socket = io({
+  reconnection: true,
+  reconnectionAttempts: Infinity,
+  reconnectionDelay: 1000,      // 首次重连 1s
+  reconnectionDelayMax: 30000,  // 最大 30s
+});
+```
+
+## 心跳检测
+
+```typescript
+// 服务端配置心跳（默认已开启）
+const io = new Server(httpServer, {
+  pingInterval: 25000,   // 每 25s 发 ping
+  pingTimeout: 20000,    // 20s 没回 pong = 断开
+});
+// 自动检测死连接，触发 disconnect 事件清理资源
+```
+
+## 连接数优化（百万连接）
+
+| 调优项 | 推荐值 | 说明 |
+|--------|--------|------|
+| 文件描述符 | `ulimit -n 1000000` | 每连接占一个 fd |
+| 端口范围 | `net.ipv4.ip_local_port_range` | 出站连接端口 |
+| TCP keepalive | 60s | 检测死连接 |
+| 内存 | 50KB/连接 | 100 万连接 ≈ 50GB |
+| CPU | event-loop 不阻塞 | 重操作走 worker |
+
+## 生产检查清单
+- [ ] Redis Adapter（多节点事件同步）
+- [ ] 连接认证（JWT 验证 handshake）
+- [ ] 心跳检测（pingInterval + pingTimeout）
+- [ ] 断线重连 + 消息队列（前端补发）
+- [ ] 连接清理（disconnect 移除 room/session）
+- [ ] 负载均衡 sticky session（IP hash）
+- [ ] nginx WebSocket upgrade 配置
+- [ ] 文件描述符调优（ulimit）
+- [ ] 监控并发连接数 + 消息吞吐
+- [ ] 限流（防恶意连接洪水）