@umacloud/knowledge 1.0.1

package/backend/01-standards/file-upload-and-storage.md

@@ -0,0 +1,66 @@
+---
+id: file-upload-and-storage
+title: 文件上传与存储标准（商业级必读）
+domain: backend
+category: 01-standards
+difficulty: intermediate
+tags: [文件上传, upload, 存储, storage, s3, 对象存储, cdn, 校验, 预签名, presigned, 安全, 图片, 商业级]
+quality_score: 95
+last_updated: 2026-06-19
+---
+
+# 文件上传与存储标准（商业级必读）
+
+> 文件上传是常见功能，也是常见漏洞与体验坑（无大小/类型校验、存数据库、走应用服务器中转、可执行文件、无 CDN）。本标准给出商业级做法。
+
+## 1. 存哪里
+
+- 用**对象存储**（S3/OSS/COS/MinIO），**不要存数据库**（撑大库、难扩展、难走 CDN），也不要长期放应用服务器本地磁盘。
+- DB 只存**元数据 + 存储 key/URL**（文件名、大小、类型、上传者、时间）。
+- 静态/图片通过 **CDN** 分发 + 长缓存（内容哈希作 key 便于缓存失效）。
+
+## 2. 上传方式：优先预签名直传
+
+- 大文件/高并发优先**前端直传对象存储**（后端签发**预签名 URL**，前端直传，不经应用服务器中转）——省带宽、可扩展。
+- 流程：前端请求上传 → 后端校验权限/类型/大小并签发短期预签名 URL → 前端直传 → 回调后端落元数据。
+- 小文件可经后端中转，但要流式处理、限大小，别全读进内存。
+
+## 3. 校验（安全关键）
+
+- **大小限制**（前后端都限，后端为准）；超限拒绝。
+- **类型校验**：白名单允许的 MIME/扩展名；**校验真实内容**（magic bytes/文件头），不只信扩展名或客户端 MIME。
+- 图片做尺寸/像素限制，必要时重新编码（去除恶意载荷/EXIF 隐私）。
+- **重命名**存储（用随机/哈希名），不用用户原始文件名（防路径穿越/覆盖）。
+- 上传目录**不可执行**；绝不把上传文件当代码执行。
+
+## 4. 访问控制
+
+- 私有文件用**预签名下载 URL（短期）**或经鉴权的代理，不要公开可枚举的 URL。
+- 公开资源也避免可猜测的顺序 id（用随机 key）。
+- 校验下载者对该文件的权限（对象级授权，防越权下别人文件）。
+
+## 5. 体验与可靠性
+
+- 前端：进度条、loading、错误态、可取消；大文件分片/断点续传。
+- 失败重试；上传完成才落元数据（避免半成品记录）。
+- 限制单用户上传频率/配额；清理孤儿文件（有记录无文件/有文件无记录）。
+- 病毒扫描（用户可下载的内容平台尤其需要）。
+
+## 6. 反模式（出现即不合格）
+
+- 文件存数据库 BLOB；长期存应用服务器本地盘。
+- 无大小/类型校验；只信扩展名/客户端 MIME；用原始文件名直存。
+- 大文件全读进内存中转；同步阻塞上传。
+- 私有文件用公开可枚举 URL；不校验下载权限。
+- 上传目录可执行；不重命名导致覆盖/穿越。
+
+## 7. 最低交付 checklist
+
+- [ ] 文件存对象存储，DB 只存元数据；公开资源走 CDN + 内容哈希。
+- [ ] 大文件预签名直传(短期 URL)；小文件流式 + 限大小。
+- [ ] 大小限制 + 类型白名单 + 真实内容校验 + 随机重命名 + 目录不可执行。
+- [ ] 私有文件短期预签名/鉴权代理 + 对象级授权下载。
+- [ ] 进度/错误/取消/重试；上传成功才落元数据；配额 + 孤儿清理。
+
+---
+**参考**：S3/对象存储最佳实践、预签名 URL、OWASP 文件上传 Cheat Sheet、CDN 缓存策略。

package/backend/01-standards/graphql-api-complete.md

@@ -0,0 +1,416 @@
+---
+id: graphql-api-complete
+title: GraphQL API 完整指南
+domain: backend
+category: 01-standards
+difficulty: intermediate
+tags: [api, backend, complete, dataloader, graphql, resolver, schema, subscription]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# GraphQL API 完整指南
+
+## 概述
+
+GraphQL 是 Facebook 开发的 API 查询语言和运行时，允许客户端精确指定所需数据。与 REST 相比，GraphQL 解决了 over-fetching 和 under-fetching 问题，提供强类型 Schema、内省能力和实时订阅支持。
+
+### 何时选择 GraphQL
+
+- 多端（Web/iOS/Android）数据需求差异大
+- 页面需要聚合多个资源的数据
+- 需要实时数据推送（Subscription）
+- API 演进频繁，需要向后兼容
+- 前端团队需要自主决定数据形状
+
+### 何时选择 REST
+
+- 简单 CRUD 操作
+- 文件上传/下载为主
+- 缓存需求强（HTTP 缓存天然支持）
+- 团队 GraphQL 经验不足
+
+---
+
+## Schema 设计
+
+### SDL (Schema Definition Language)
+
+```graphql
+# 类型定义
+type User {
+  id: ID!
+  email: String!
+  name: String!
+  role: Role!
+  posts(first: Int = 10, after: String): PostConnection!
+  createdAt: DateTime!
+}
+
+type Post {
+  id: ID!
+  title: String!
+  content: String!
+  author: User!
+  tags: [Tag!]!
+  status: PostStatus!
+  publishedAt: DateTime
+  createdAt: DateTime!
+}
+
+type Tag {
+  id: ID!
+  name: String!
+  posts(first: Int = 10, after: String): PostConnection!
+}
+
+# 枚举
+enum Role {
+  USER
+  EDITOR
+  ADMIN
+}
+
+enum PostStatus {
+  DRAFT
+  PUBLISHED
+  ARCHIVED
+}
+
+# 自定义标量
+scalar DateTime
+scalar JSON
+
+# 连接（Relay 规范分页）
+type PostConnection {
+  edges: [PostEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type PostEdge {
+  node: Post!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+
+# 输入类型
+input CreatePostInput {
+  title: String!
+  content: String!
+  tags: [ID!]
+  status: PostStatus = DRAFT
+}
+
+input UpdatePostInput {
+  title: String
+  content: String
+  tags: [ID!]
+  status: PostStatus
+}
+
+# Query
+type Query {
+  user(id: ID!): User
+  me: User!
+  posts(
+    first: Int = 20
+    after: String
+    status: PostStatus
+    search: String
+  ): PostConnection!
+  post(id: ID!): Post
+}
+
+# Mutation
+type Mutation {
+  createPost(input: CreatePostInput!): Post!
+  updatePost(id: ID!, input: UpdatePostInput!): Post!
+  deletePost(id: ID!): Boolean!
+  login(email: String!, password: String!): AuthPayload!
+}
+
+type AuthPayload {
+  token: String!
+  user: User!
+}
+
+# Subscription
+type Subscription {
+  postPublished: Post!
+  commentAdded(postId: ID!): Comment!
+}
+```
+
+---
+
+## Resolver 实现
+
+### Node.js (Apollo Server)
+
+```typescript
+import { GraphQLResolveInfo } from "graphql";
+
+const resolvers = {
+  Query: {
+    me: (_parent: unknown, _args: unknown, context: Context) => {
+      if (!context.user) throw new AuthenticationError("未认证");
+      return context.user;
+    },
+
+    posts: async (_parent: unknown, args: PostsArgs, context: Context) => {
+      const { first = 20, after, status, search } = args;
+      return context.dataSources.postAPI.getPosts({ first, after, status, search });
+    },
+
+    post: async (_parent: unknown, { id }: { id: string }, context: Context) => {
+      const post = await context.dataSources.postAPI.getPostById(id);
+      if (!post) throw new NotFoundError(`Post ${id} not found`);
+      return post;
+    },
+  },
+
+  Mutation: {
+    createPost: async (_parent: unknown, { input }: { input: CreatePostInput }, context: Context) => {
+      if (!context.user) throw new AuthenticationError("未认证");
+      return context.dataSources.postAPI.createPost({
+        ...input,
+        authorId: context.user.id,
+      });
+    },
+
+    updatePost: async (_parent: unknown, { id, input }: { id: string; input: UpdatePostInput }, context: Context) => {
+      if (!context.user) throw new AuthenticationError("未认证");
+      const post = await context.dataSources.postAPI.getPostById(id);
+      if (!post) throw new NotFoundError(`Post ${id} not found`);
+      if (post.authorId !== context.user.id && context.user.role !== "ADMIN") {
+        throw new ForbiddenError("无权修改");
+      }
+      return context.dataSources.postAPI.updatePost(id, input);
+    },
+  },
+
+  // 字段级 Resolver
+  User: {
+    posts: (parent: User, args: ConnectionArgs, context: Context) => {
+      return context.dataSources.postAPI.getPostsByAuthor(parent.id, args);
+    },
+  },
+
+  Post: {
+    author: (parent: Post, _args: unknown, context: Context) => {
+      // 使用 DataLoader 避免 N+1
+      return context.loaders.userLoader.load(parent.authorId);
+    },
+    tags: (parent: Post, _args: unknown, context: Context) => {
+      return context.loaders.tagLoader.load(parent.id);
+    },
+  },
+};
+```
+
+---
+
+## DataLoader (N+1 解决方案)
+
+```typescript
+import DataLoader from "dataloader";
+
+// 创建 DataLoader
+function createLoaders(db: Database) {
+  return {
+    userLoader: new DataLoader<string, User>(async (ids) => {
+      const users = await db.user.findMany({
+        where: { id: { in: [...ids] } },
+      });
+      const userMap = new Map(users.map(u => [u.id, u]));
+      return ids.map(id => userMap.get(id) || new Error(`User ${id} not found`));
+    }),
+
+    tagLoader: new DataLoader<string, Tag[]>(async (postIds) => {
+      const postTags = await db.postTag.findMany({
+        where: { postId: { in: [...postIds] } },
+        include: { tag: true },
+      });
+      const tagMap = new Map<string, Tag[]>();
+      for (const pt of postTags) {
+        const tags = tagMap.get(pt.postId) || [];
+        tags.push(pt.tag);
+        tagMap.set(pt.postId, tags);
+      }
+      return postIds.map(id => tagMap.get(id) || []);
+    }),
+  };
+}
+
+// 在 Context 中每请求创建新实例
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  context: ({ req }) => ({
+    user: getUserFromToken(req.headers.authorization),
+    loaders: createLoaders(db),
+    dataSources: { postAPI: new PostAPI(db) },
+  }),
+});
+```
+
+---
+
+## 订阅 (Subscription)
+
+```typescript
+import { PubSub } from "graphql-subscriptions";
+
+const pubsub = new PubSub();
+
+const resolvers = {
+  Mutation: {
+    createPost: async (_parent, { input }, context) => {
+      const post = await context.dataSources.postAPI.createPost(input);
+      if (post.status === "PUBLISHED") {
+        pubsub.publish("POST_PUBLISHED", { postPublished: post });
+      }
+      return post;
+    },
+  },
+
+  Subscription: {
+    postPublished: {
+      subscribe: () => pubsub.asyncIterator(["POST_PUBLISHED"]),
+    },
+    commentAdded: {
+      subscribe: (_parent, { postId }) =>
+        pubsub.asyncIterator([`COMMENT_ADDED_${postId}`]),
+    },
+  },
+};
+```
+
+---
+
+## 安全
+
+### 查询深度与复杂度限制
+
+```typescript
+import depthLimit from "graphql-depth-limit";
+import { createComplexityLimitRule } from "graphql-validation-complexity";
+
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  validationRules: [
+    depthLimit(7),                              // 查询深度限制
+    createComplexityLimitRule(1000, {            // 查询复杂度限制
+      scalarCost: 1,
+      objectCost: 5,
+      listFactor: 10,
+    }),
+  ],
+});
+```
+
+### 速率限制
+
+```typescript
+import { RateLimitDirective } from "graphql-rate-limit-directive";
+
+const typeDefs = gql`
+  directive @rateLimit(limit: Int!, duration: Int!) on FIELD_DEFINITION
+
+  type Mutation {
+    login(email: String!, password: String!): AuthPayload!
+      @rateLimit(limit: 5, duration: 60)
+    createPost(input: CreatePostInput!): Post!
+      @rateLimit(limit: 10, duration: 60)
+  }
+`;
+```
+
+### 字段级授权
+
+```typescript
+const resolvers = {
+  User: {
+    email: (parent, _args, context) => {
+      // 仅自己或管理员可见邮箱
+      if (context.user?.id === parent.id || context.user?.role === "ADMIN") {
+        return parent.email;
+      }
+      return null;
+    },
+  },
+};
+```
+
+---
+
+## 性能优化
+
+### 持久化查询 (Persisted Queries)
+
+```typescript
+// 客户端发送 query hash 而非完整 query
+// POST /graphql
+// { "extensions": { "persistedQuery": { "version": 1, "sha256Hash": "abc123..." } } }
+
+import { ApolloServerPluginCacheControl } from "@apollo/server/plugin/cacheControl";
+
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  persistedQueries: { ttl: 900 }, // 15 分钟 TTL
+  plugins: [ApolloServerPluginCacheControl({ defaultMaxAge: 60 })],
+});
+```
+
+### 查询批处理
+
+```typescript
+// 客户端批量发送多个查询
+// POST /graphql
+// [{ "query": "..." }, { "query": "..." }]
+
+// Apollo Client 配置
+const link = new BatchHttpLink({
+  uri: "/graphql",
+  batchMax: 5,        // 最多 5 个查询合批
+  batchInterval: 20,  // 20ms 窗口
+});
+```
+
+---
+
+## 常见反模式
+
+| 反模式 | 问题 | 正确做法 |
+|--------|------|----------|
+| 不用 DataLoader | N+1 查询 | 每请求创建 DataLoader 实例 |
+| 无深度/复杂度限制 | DoS 攻击 | 设置 depthLimit + complexityLimit |
+| Schema 暴露内部结构 | 信息泄露 | 以客户端需求设计 Schema |
+| 巨型 Resolver 函数 | 难维护 | 拆分为 Service + DataSource |
+| 忽略错误处理 | 敏感信息泄露 | 统一错误格式，隐藏内部细节 |
+| Subscription 用轮询实现 | 浪费资源 | 用 WebSocket + PubSub |
+
+---
+
+## Agent Checklist
+
+- [ ] Schema 遵循 Relay 规范分页（Connection / Edge / PageInfo）
+- [ ] 所有关联字段使用 DataLoader 避免 N+1
+- [ ] 设置查询深度限制（推荐 <= 7 层）
+- [ ] 设置查询复杂度限制
+- [ ] 敏感字段实现字段级授权
+- [ ] Mutation 使用 Input 类型参数化
+- [ ] 错误返回统一格式，不暴露内部堆栈
+- [ ] 登录等敏感操作设置速率限制
+- [ ] 生产环境禁用 Introspection（或仅限内部）
+- [ ] Subscription 使用 WebSocket，生产环境用 Redis PubSub
+- [ ] Schema 变更有向后兼容策略（@deprecated 标记）
+- [ ] 接入 APM 监控 Resolver 级别性能

package/backend/01-standards/llm-application-standard.md

@@ -0,0 +1,78 @@
+---
+id: llm-application-standard
+title: AI/LLM 应用开发标准（商业级 · RAG/Agent/护栏/成本）
+domain: backend
+category: 01-standards
+difficulty: advanced
+tags: [ai, llm, 大模型, rag, 检索增强, prompt, 提示注入, prompt-injection, 护栏, guardrails, agent, 智能体, 成本, 评测, 流式, 向量, 商业级]
+quality_score: 95
+last_updated: 2026-06-19
+---
+
+# AI/LLM 应用开发标准（商业级 · RAG/Agent/护栏/成本）
+
+> AI 应用是当下最热的商业方向，也是纯底座最容易做不规范的地方（无护栏、易被提示注入、成本失控、不可评测）。本标准给出生产级 LLM 应用要点。
+
+## 1. 架构与抽象
+
+- **抽象 LLM 供应商**：封装统一接口（chat/embeddings/tools），便于切换模型/供应商、做降级与多模型路由，不要把某家 SDK 散落业务。
+- 模型分层路由：**60-80% 的查询用更小更便宜的模型即可**，复杂的才上大模型——可显著降本(50-70%)。
+- 流式输出（SSE）提升体感；超时/重试/限流/熔断（外部模型会抖动）。
+- Prompt 用**模板 + 版本管理**，与代码一起评审，不要散落硬编码字符串。
+
+## 2. RAG（检索增强生成）
+
+- 标准管线：**切分(chunk) → 向量化(embedding) → 向量库检索 → 重排(rerank) → 拼上下文 → 生成**。
+- 切分要语义合理（按结构/语义而非定长硬切）；保留来源元数据（用于引用与权限）。
+- 检索质量决定一切：合适的相似度 + 数量 + rerank；中文注意分词/向量模型选型。
+- **引用来源**：让模型基于检索内容回答并给出处，减少幻觉；用 thinking/answer 分段标记提升复杂问答准确率。
+- 评估检索召回/命中，别只看生成。
+
+## 3. 安全：提示注入与护栏（非可选）
+
+- **直接提示注入**：用户输入试图覆盖系统指令——系统提示与用户输入分离、最小信任用户输入、关键约束放系统侧并防覆盖。
+- **间接提示注入（RAG/Agent 关键风险）**：恶意指令藏在**被检索的文档/网页/工具返回**里。必须：对检索内容**文档可信度评分/来源过滤**、把检索内容当**数据而非指令**对待。
+- **输入/输出护栏(guardrails)**：过滤/审核输入与输出（敏感词、PII、越权、有害内容、越狱），检测对抗行为。
+- **工具/Agent 护栏**：工具**白名单** + 参数校验 + 权限校验（Agent 不能调用它不该调的工具/越权操作）；危险操作需确认。
+- 不把密钥/内部数据放进会发给模型的上下文；输出落库/执行前校验。
+
+## 4. Agent（智能体）
+
+- 明确**工具集 + 权限边界**；每个工具有 schema 校验与授权。
+- **防失控成本**：Agent 反复检索/调用不收敛会烧 token/延迟——设**步数/预算/超时上限** + 循环检测 + 兜底退出。
+- 关键动作（写库、发消息、花钱）需幂等 + 审计 + 必要时人工确认（human-in-the-loop）。
+- 可观测：记录每步思考/工具调用/结果，便于调试与审计。
+
+## 5. 成本与性能
+
+- 控制 token：精简 prompt/上下文、缓存(prompt cache/语义缓存重复问)、截断历史、小模型分流。
+- 监控每请求/每用户 **token 成本**；设配额/限流防滥用与成本爆炸。
+- 流式 + 提前返回提升体感；批处理离线任务。
+
+## 6. 评测与可观测（让 AI 可度量）
+
+- **LLM-as-judge**：用模型评估输出质量，在 **5-10% 生产流量**上跑，形成持续改进闭环。
+- 建评测集（黄金问答/标注），回归测试 prompt/模型变更，防"改了更差"。
+- 可观测：记录 prompt/响应/延迟/成本/反馈/检索命中（脱敏 PII），接 LLM 观测工具。
+- 收集用户反馈(赞/踩)闭环优化。
+
+## 7. 反模式（出现即不合格）
+
+- 无任何护栏，用户输入直接拼进系统提示（易被注入/越狱）。
+- RAG 把检索文档当指令信任（间接提示注入）；不评估检索质量。
+- Agent 无步数/预算上限（成本炸弹）、工具无白名单/权限校验。
+- prompt 硬编码散落、无版本；不监控 token 成本、不限流。
+- 不评测不可观测，改 prompt/模型凭感觉；幻觉无来源引用。
+- 密钥/敏感数据进模型上下文；输出不校验直接执行/落库。
+
+## 8. 最低交付 checklist
+
+- [ ] 抽象 LLM 供应商 + 模型分层路由(小模型分流) + 流式 + 超时重试限流。
+- [ ] RAG：合理切分+向量检索+rerank+来源引用+检索评估。
+- [ ] 护栏：输入输出过滤、提示注入(直接+间接/检索内容当数据)防护、工具白名单+参数/权限校验。
+- [ ] Agent：步数/预算/超时上限 + 循环检测 + 关键动作幂等/审计/人工确认。
+- [ ] 成本：token 监控 + 缓存 + 配额限流；prompt 模板+版本。
+- [ ] 评测：LLM-as-judge + 评测集回归 + 可观测(prompt/成本/延迟/反馈) + 用户反馈闭环。
+
+---
+**参考**：OWASP LLM Top 10（提示注入/不安全输出/过度代理）、RAG 生产实践、LLM Guardrails、LLM-as-judge 评测、各模型供应商官方最佳实践。