@umacloud/knowledge 1.0.1

package/architecture/system-architecture-deep-dive.md

@@ -0,0 +1,37 @@
+---
+id: system-architecture-deep-dive
+title: system-architecture-deep-dive
+domain: architecture
+category: system-architecture-deep-dive.md
+difficulty: intermediate
+tags: [architecture, deep, dive, system, 架构环节深度知识库]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 开发：Excellent（11964948@qq.com）
+
+## 架构环节深度知识库
+
+### 目标
+- 在性能、稳定性、可维护性与演进成本之间建立可持续平衡。
+
+### 架构基线
+- 分层边界：接口层、应用层、领域层、基础设施层职责清晰。
+- 依赖方向：高层依赖抽象，基础设施依赖不得反向污染业务层。
+- 同步与异步：强一致链路优先同步，高耗时与低耦合能力采用异步事件。
+- 数据一致性：明确强一致、最终一致与补偿策略。
+
+### 非功能指标
+- 性能：关键接口 P95、P99 时延阈值。
+- 可用性：SLO、错误预算、降级策略。
+- 安全性：鉴权、审计、敏感数据保护策略。
+- 可观测性：日志、指标、追踪三件套。
+
+### 决策机制
+- 重大架构决策必须记录 ADR。
+- 涉及跨模块影响的变更必须给出回滚方案。
+- 每次架构升级必须配套容量评估与回归计划。
+
+### 常见失败模式
+- 过早微服务化导致交付复杂度飙升。
+- 无统一异常与超时策略导致故障蔓延。

package/backend/01-standards/analytics-and-growth.md

@@ -0,0 +1,65 @@
+---
+id: analytics-and-growth
+title: 数据埋点、分析与增长标准（商业级必读）
+domain: backend
+category: 01-standards
+difficulty: intermediate
+tags: [埋点, analytics, 数据分析, 事件追踪, event-tracking, 漏斗, ab测试, 留存, 增长, 隐私合规, 商业级]
+quality_score: 92
+last_updated: 2026-06-19
+---
+
+# 数据埋点、分析与增长标准（商业级必读）
+
+> "不能度量就不能改进"。商业产品必须能看清用户行为、转化、留存——纯底座常只做功能、完全不埋点。本标准给出商业级数据体系要点。
+
+## 1. 埋点设计（先有规范再埋）
+
+- **统一事件模型**：`event_name`(动词+对象，如 `order_paid`)、`properties`(上下文)、`user_id`/`anonymous_id`、`timestamp`、`platform`。
+- 维护**埋点字典(tracking plan)**：事件、属性、触发时机统一定义并评审，避免命名混乱、重复、漏埋。
+- 命名一致(snake_case)、属性类型稳定；版本化管理。
+- 关键转化路径(注册→激活→付费)必埋；核心业务动作必埋。
+
+## 2. 采集与上报
+
+- 用成熟分析平台(GA4 / 神策 / 友盟 / PostHog / Amplitude / Mixpanel)或自建，封装统一 SDK，别在业务里散落上报。
+- **客户端 + 服务端双埋点**：关键转化(支付/下单)以**服务端**为准(防丢失/作弊)，行为/UI 用客户端。
+- 批量 + 异步上报，失败重试，弱网缓存补传；不阻塞主流程。
+- 标识：登录前 anonymous_id，登录后与 user_id 关联打通。
+
+## 3. 核心指标与分析
+
+- 关注**北极星指标** + 关键指标：激活率、留存(次日/7日/30日)、转化漏斗、付费/ARPU、活跃(DAU/MAU)。
+- 建漏斗分析(各步流失)、留存曲线、分群(cohort)、路径分析。
+- 业务指标看板 + 异常告警(转化骤降、支付失败率)。
+
+## 4. 实验与增长
+
+- **A/B 测试**：科学分流(稳定分桶)、单一变量、足够样本与显著性、防偷看；记录实验与结论。
+- Feature flag 灰度 + 实验解耦发布。
+- 增长闭环：埋点→分析→假设→实验→上线→再分析。
+
+## 5. 隐私与合规（必须）
+
+- 采集**最小必要**；敏感数据/PII 脱敏或不采集。
+- **用户同意**(GDPR/个保法 cookie/追踪同意)；提供退出(opt-out)/Do Not Track；iOS 追踪需 ATT。
+- 数据存储/传输加密；遵守留存期限；第三方 SDK 数据流向透明(隐私政策声明)。
+
+## 6. 反模式（出现即不合格）
+
+- 只做功能、零埋点，上线后看不清用户行为与转化。
+- 埋点命名混乱/无字典/重复漏埋；事件属性类型不稳定。
+- 关键转化只客户端埋(丢失/可作弊)，不服务端兜底。
+- A/B 偷看结果/分桶不稳定/无显著性就下结论。
+- 采集 PII 不脱敏、无用户同意、不合规(无 ATT/无 opt-out)。
+
+## 7. 最低交付 checklist
+
+- [ ] 统一事件模型 + 埋点字典(评审/版本化)；关键转化路径必埋。
+- [ ] 用成熟平台/统一 SDK；客户端+服务端双埋(关键转化服务端为准)；异步重试补传。
+- [ ] anonymous→user 标识打通；核心指标看板(激活/留存/漏斗/付费)+异常告警。
+- [ ] A/B 稳定分桶+单变量+显著性；feature flag 灰度。
+- [ ] 最小采集+PII 脱敏+用户同意(GDPR/个保法/ATT)+opt-out+隐私声明。
+
+---
+**参考**：GA4/PostHog/Amplitude 埋点最佳实践、Tracking Plan、AARRR/北极星指标、A/B 测试统计、GDPR/个保法、Apple ATT。

package/backend/01-standards/api-and-error-conventions.md

@@ -0,0 +1,120 @@
+---
+id: api-and-error-conventions
+title: API 设计与错误处理规范（商业级后端必读）
+domain: backend
+category: 01-standards
+difficulty: intermediate
+tags: [api设计, rest, 错误处理, error, 状态码, 分页, pagination, 版本, versioning, 幂等, idempotency, dto, 契约, 商业级]
+quality_score: 95
+last_updated: 2026-06-19
+---
+
+# API 设计与错误处理规范（商业级后端必读）
+
+> 框架无关的 HTTP API 硬性规范。每个商业级接口都要遵守：一致的资源命名、统一的错误信封、正确的状态码、分页/过滤/排序、版本与幂等。前端按契约对接，混乱的 API 会让整个项目腐化。
+
+## 1. 资源与 URL 命名
+
+- 资源用**名词复数**：`/api/v1/orders`、`/api/v1/orders/{id}/items`。不要用动词 URL（`/getOrders` ❌）。
+- 层级表达从属：`/users/{id}/orders`；超过两层从属考虑顶层资源 + 过滤。
+- 用 HTTP 方法表达动作：`GET`(查) `POST`(建) `PUT`(整体替换) `PATCH`(局部更新) `DELETE`(删)。
+- 非 CRUD 的动作用子资源或动作端点：`POST /orders/{id}/cancel`（而非 `POST /cancelOrder`）。
+- 全小写、连字符或直接复数名词；查询参数用 `snake_case` 或 `camelCase` 全项目统一。
+
+## 2. 状态码（用对，不要一律 200）
+
+| 场景 | 码 |
+|---|---|
+| 查询成功 / 更新成功 | 200 |
+| 创建成功（返回新资源，带 `Location`）| 201 |
+| 成功但无返回体（删除）| 204 |
+| 参数/格式校验失败 | 422（或 400）|
+| 未认证（没登录/token 失效）| 401 |
+| 已认证但无权限 | 403 |
+| 资源不存在 | 404 |
+| 冲突（重复、版本冲突、状态不允许）| 409 |
+| 限流 | 429 |
+| 服务端异常 | 500（不泄露细节）|
+
+- 创建返回 201 + 新资源 + `Location` 头；删除返回 204。
+- 不要"业务失败也回 200 再在 body 里塞 `success:false`"——用正确状态码。
+
+## 3. 统一错误信封（全项目一致）
+
+所有错误返回同一结构，便于前端统一处理：
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": [
+      { "field": "email", "message": "Must be a valid email address" }
+    ],
+    "request_id": "req_01H..."
+  }
+}
+```
+
+- `code`：机器可读的稳定错误码（`NOT_FOUND` / `FORBIDDEN` / `CONFLICT` / `VALIDATION_ERROR` / `RATE_LIMITED` / `INTERNAL`）。前端按 `code` 分支，不靠 message 文案。
+- `message`：人类可读、安全（500 绝不暴露栈/SQL/内部路径）。
+- `details`：字段级校验错误数组。
+- `request_id`：贯穿日志，便于排查。
+- 错误映射集中在接口层一个 error handler/filter，不在每个 controller 里重复 try/catch。
+
+## 4. 请求与响应契约
+
+- 入参：用 DTO + schema 校验（Zod/Joi/Pydantic/Bean Validation），失败 422 + 字段错误。
+- 出参：只返回该接口需要的字段（Output DTO），**不要直接吐 ORM entity**（泄露内部字段、关系、敏感列）。
+- 时间用 ISO-8601 UTC（`2026-06-19T08:00:00Z`）；金额用最小单位整数（分）或带币种的 decimal，**不要用 float**。
+- 布尔/枚举值稳定；新增字段向后兼容，删字段要走版本。
+
+## 5. 列表：分页 + 过滤 + 排序（列表接口必做）
+
+- 分页两种主流：
+  - **offset/limit**：`?limit=20&offset=40`，简单但深翻页慢。
+  - **cursor**：`?limit=20&cursor=xxx`，大数据/无限滚动首选，稳定不漏不重。
+- 返回分页元信息：`{ data: [...], page: { limit, next_cursor | total } }`。
+- 过滤用明确参数（`?status=paid&created_after=...`），排序 `?sort=-created_at`（`-` 表降序）。
+- 列表默认有上限（如 max limit 100），防止一次拉全表。
+
+## 6. 版本与演进
+
+- URL 版本前缀 `/api/v1/`（或 header 版本）。破坏性变更升大版本。
+- 非破坏（加字段、加可选参数）不升版；破坏（删字段、改语义、改必填）必须升版并保留旧版过渡。
+- 弃用用 `Deprecation`/`Sunset` 头提示。
+
+## 7. 幂等与并发
+
+- `POST` 创建类提供 **幂等键**（`Idempotency-Key` 头）防重复提交/重复扣款。
+- 更新用乐观锁（`version`/`updated_at` 比对），冲突回 409，别静默覆盖。
+- 钱、库存等关键写操作必须在事务内 + 幂等。
+
+## 8. 鉴权与安全基线
+
+- 受保护端点声明鉴权（Bearer JWT / Session）；状态变更端点（非公开的 POST/PUT/PATCH/DELETE）必须鉴权。
+- 鉴权在中间件统一做；授权（这个用户能否操作这条资源）在服务层校验，别只靠路由。
+- 永不在响应里回传密码哈希、token、内部 id 之外的敏感字段。
+- 限流（按 IP/用户/端点）保护登录、发码、支付等。
+
+## 9. 反模式（出现即不合格）
+
+- 动词 URL、一律 200、错误结构每个接口不一样。
+- 直接返回 ORM entity；500 把栈/SQL 暴露给客户端。
+- 列表无分页/无上限、深翻页拉全表。
+- 金额用 float；时间不带时区。
+- 破坏性变更不升版本直接改线上契约。
+- 创建/支付类接口无幂等，重复提交重复下单。
+
+## 10. 最低交付 checklist
+
+- [ ] 资源名词化 URL + 正确 HTTP 方法 + 正确状态码（201/204/401/403/404/409/422/429）。
+- [ ] 全项目统一错误信封（code/message/details/request_id），错误映射集中处理。
+- [ ] 入参 DTO+schema 校验；出参 DTO，不泄露 entity；时间 UTC、金额整数。
+- [ ] 列表有分页+过滤+排序+默认上限。
+- [ ] 版本前缀；破坏性变更升版。
+- [ ] 关键写操作幂等 + 事务 + 乐观锁。
+- [ ] 受保护端点鉴权 + 服务层授权 + 关键端点限流。
+
+---
+**参考**：REST 成熟度模型、RFC 7807 Problem Details、Stripe/GitHub API 设计惯例、12-Factor。

package/backend/01-standards/application-layering-and-packaging.md

@@ -0,0 +1,160 @@
+---
+id: application-layering-and-packaging
+title: 应用分层与分包标准（商业级后端必读）
+domain: backend
+category: 01-standards
+difficulty: intermediate
+tags: [分层架构, 服务层, 分包, 依赖倒置, clean-architecture, layered, service-layer, repository, dto, domain, transaction, 事务边界, package-by-feature, 商业级]
+quality_score: 95
+last_updated: 2026-06-19
+---
+
+# 应用分层与分包标准（商业级后端必读）
+
+> 这是**框架无关**的硬性结构标准。任何商业级后端——无论用 NestJS / Spring Boot / FastAPI / Express / Go——都必须遵守分层、依赖方向与分包规则。写代码前先按本标准定下骨架，再填实现。把所有逻辑塞进 controller、或 service 里直接写 SQL、或 controller 直接调 repository，都是**不合格**的，质量审查会打回。
+
+## 0. 一句话原则
+
+**分层隔离关注点，依赖一律向内（朝业务核心）流。** 业务逻辑不依赖框架、数据库、传输协议；它们是可替换的外设。
+
+## 1. 四层模型与各层职责（MUST / MUST NOT）
+
+```
+HTTP/gRPC/MQ ─▶ ① 接口层 Interface ─▶ ② 应用层 Application(Service) ─▶ ③ 领域层 Domain
+                                              │
+                                              └─▶ ④ 基础设施层 Infrastructure(Repository/Adapter) ─▶ DB/缓存/第三方
+依赖方向：① → ② → ③（向内）；④ 实现 ② / ③ 定义的接口（依赖倒置，箭头也朝内）
+```
+
+### ① 接口层 / Interface（controller、handler、route、resolver、consumer）
+**只做传输相关的事**：解析请求、调用一个应用服务方法、把结果/异常映射成响应。
+- MUST：参数/请求体反序列化 → DTO；鉴权与限流（中间件）；把领域/应用异常映射为 HTTP 状态码；只依赖应用层。
+- MUST NOT：写业务规则；直接调用 repository / ORM；直接拼 SQL；持有事务；返回 ORM entity 给客户端。
+- 标准动作链：`parse → authorize → call service → map response`。
+
+### ② 应用层 / Application（service、use-case、interactor）
+**编排用例**：协调领域对象、仓储、基础设施服务，完成一个业务用例。**这是"服务层"，见 §2 重点展开。**
+- MUST：无状态；一个 public 方法 = 一个用例 = 一个事务边界（Unit of Work）；输入/输出都是 DTO；编排顺序、调用领域方法、提交/回滚事务、处理应用级失败（如外部服务不可用的补偿）。
+- MUST NOT：写 HTTP 细节（状态码、header）；写持久化细节（SQL、ORM 查询构造）；承载本应属于领域的不变量规则（那是贫血模型反模式）。
+
+### ③ 领域层 / Domain（entity、value object、domain service、领域事件）
+**业务的真相**：表达业务概念、规则与不变量，**有行为不只是数据**。
+- MUST：把不变量（invariant）封装进实体方法（如 `order.cancel()` 内部校验状态机），而非散落在 service 的 if；用值对象（Value Object）表达 Money/Email/PhoneNumber 等带约束的概念；纯内存、零框架依赖、可独立单测。
+- MUST NOT：依赖框架注解以外的运行时框架、依赖 DB、依赖 HTTP。
+- 反模式：**贫血领域模型**（entity 只有 getter/setter，所有逻辑堆在 service）——禁止。
+
+### ④ 基础设施层 / Infrastructure（repository 实现、ORM、HTTP 客户端、消息、缓存、文件存储）
+**与外部世界对接**：实现内层定义的接口。
+- MUST：repository 把领域对象 ↔ 持久化模型互转；封装一切 SQL/ORM/网络；实现领域/应用层声明的端口接口（依赖倒置）。
+- MUST NOT：把业务规则写进 repository；让领域层 import 基础设施的具体类。
+
+## 2. 服务层（Service Layer）怎么写——重点
+
+服务层是商业项目最容易写烂的一层。规则：
+
+1. **无状态 + 用例粒度**：每个 public 方法对应一个明确用例（`registerUser`、`placeOrder`、`cancelSubscription`），命名是动词+领域名词，不是 `UserService.handle()` 这种万能方法。
+2. **方法即事务边界（Unit of Work）**：在服务方法的开始/结束界定事务；用例内要么全成功要么全回滚。事务**绝不**下沉到 repository（repository 不该 commit），也**绝不**上浮到 controller。
+3. **收发 DTO，绝不泄露 entity**：服务方法接收 input DTO（已在边界校验），返回 output DTO；**永远不要把 ORM entity 直接返回给上层/客户端**（会泄露内部结构、产生懒加载陷阱、破坏契约）。
+4. **编排，不堆砌领域逻辑**：服务负责"调用顺序/事务/跨聚合协调/调外部服务"；单个聚合内部的规则放进领域实体方法。判断标准：如果一段 if 是"这个业务对象在什么状态下允许做什么"，它属于领域层；如果是"先扣库存再创建订单再发消息"，它属于服务层。
+5. **依赖抽象**：服务依赖 `OrderRepository`（接口）、`PaymentGateway`（接口），不依赖 `TypeOrmOrderRepository`、`StripeClient` 具体类——便于替换与单测（依赖倒置 + 注入）。
+6. **应用级失败处理**：外部支付超时、消息发送失败等，由服务层决定补偿/重试/标记，不让它冒泡成 500。
+
+```text
+// 用例：下单（服务层方法的标准骨架）
+placeOrder(input: PlaceOrderDTO): OrderDTO {
+  开启事务 {                                  // ② 事务边界在服务层
+    cart   = cartRepo.findOpen(input.userId)  // ④ 取数据
+    order  = Order.create(cart, input.address) // ③ 领域方法内部校验不变量
+    inventory.reserve(order.items)            // ③/④ 领域+基础设施
+    orderRepo.save(order)                     // ④ 持久化
+  } 提交/回滚
+  paymentGateway.authorize(order)             // ④ 外部服务（事务外，失败可补偿）
+  events.publish(OrderPlaced(order.id))       // 领域事件
+  return OrderDTO.from(order)                 // 收发 DTO，不返回 entity
+}
+```
+
+## 3. DTO / Entity / Domain Model / VO 的区分与映射
+
+| 概念 | 作用 | 出现在哪层 |
+|---|---|---|
+| **Input DTO** | 入参契约 + 边界校验（Zod/Joi/Pydantic/Bean Validation） | 接口层接收，传入服务层 |
+| **Output DTO / View Model** | 出参契约，只暴露该接口需要的字段 | 服务层产出，接口层返回 |
+| **Domain Entity / Aggregate** | 带行为与不变量的业务对象 | 领域层（内存中）|
+| **Value Object** | 不可变、带约束的小概念（Money、Email） | 领域层 |
+| **Persistence Model / ORM Entity** | 数据库表映射 | 基础设施层 |
+
+映射规则：
+- **input DTO → 领域对象：手写映射**（显式构造，校验业务不变量），不要用自动映射工具一把梭。
+- **领域对象 → output DTO：可用自动映射**（结构简单、方向安全）。
+- **领域对象 ↔ persistence model：在 repository 内互转**，领域层对 ORM 无感知。
+- 切忌"一个类贯穿所有层"（ORM entity 同时当 DTO 当领域模型）——这是商业项目腐化的头号原因。
+
+## 4. 校验放哪
+
+- **边界校验（格式/必填/范围）**：在接口层用 schema 校验 input DTO，失败返回 422 + 字段级错误。
+- **业务不变量（状态机/跨字段规则/唯一性）**：在领域层实体方法内强制（如不能取消已发货订单），或在服务层做需要查库的规则（如邮箱唯一）。
+- 永远不要只信前端校验。
+
+## 5. 错误处理跨层策略
+
+```
+领域层：抛领域异常（OrderAlreadyShippedError 等，带业务语义，不带 HTTP）
+应用层：不吞异常；需要补偿的应用级失败在此处理；其余向上抛
+接口层：集中异常映射 → HTTP（NotFound→404, Forbidden→403, Conflict→409, Validation→422, 未知→500 且不泄露细节、记录 requestId+stack）
+```
+
+## 6. 依赖注入与依赖倒置
+
+- 内层（领域/应用）**定义接口**（端口）；外层（基础设施）**提供实现**（适配器）。
+- 通过构造函数注入装配；禁止在领域/应用层 `new` 具体的基础设施类。
+- 收益：可替换数据库/第三方、领域逻辑可纯单测（mock 端口）。
+
+## 7. 分包（Package / 模块结构）——优先 package-by-feature
+
+**默认按功能分包（package-by-feature），而不是按层分包（package-by-layer）。** 业界共识：按功能分包可扩展性、封装性、可定位性更好，新增功能不动其它结构，且天然支持"模块化单体 → 拆微服务"的演进路径。经验法则：**先按功能分包，复杂度上来再在功能内部按层细分**。
+
+```
+src/
+├─ modules/                      # 按功能（限界上下文）分包 ← 推荐
+│  ├─ orders/
+│  │  ├─ interface/             # controller / route / dto(in,out)
+│  │  ├─ application/           # order.service.ts（用例、事务）
+│  │  ├─ domain/                # order.entity.ts, order-status.vo.ts, ports(repo接口)
+│  │  └─ infrastructure/        # order.repository.ts(实现), orm-models
+│  ├─ payments/
+│  └─ users/
+├─ shared/                       # 跨功能复用：errors, result, base-entity, value-objects
+└─ platform/                     # 框架装配：config, db, http server, di, middleware, logging
+```
+
+- 每个 feature 自带 interface/application/domain/infrastructure，内部遵守依赖方向。
+- feature 之间**通过应用层接口/领域事件通信**，不要跨 feature 直接调对方 repository 或 entity。
+- 尽量用 package-private/模块私有可见性，只导出该 feature 的公开 API（service 接口 + DTO）。
+- 不要过早上微服务："复杂度不够时不配拥有 Clean Architecture"；先模块化单体，边界清晰后再按 feature 抽服务。
+
+## 8. 常见反模式（出现即不合格）
+
+- Fat Controller：业务逻辑写在 controller。
+- Controller 直接调 repository / 直接写 SQL，跳过服务层。
+- 服务层返回或接收 ORM entity（泄露持久化结构）。
+- 贫血领域模型：entity 只有数据、规则全在 service。
+- 一个 `God Service` 几千行，方法不是用例粒度。
+- 事务写在 repository 或 controller 里。
+- 领域层 import ORM/HTTP/框架具体类。
+- 按层分包到极端（controllers/、services/、repositories/ 三个大目录），功能散落、改一个需求要翻三处。
+- 一个类（ORM entity）同时充当 DTO + 领域模型 + 持久化模型。
+
+## 9. 最低交付标准（写完后自检 checklist）
+
+- [ ] controller 不含业务规则，只 parse→authorize→call service→map response。
+- [ ] 每个 service 方法是一个用例，是事务边界，收发 DTO 而非 entity。
+- [ ] 领域不变量封装在 entity/VO 方法里，不在 service 用裸 if 散落。
+- [ ] repository 只做持久化，不含业务规则，不 commit 事务。
+- [ ] 内层只依赖接口（端口），具体实现靠注入；领域层零框架/DB 依赖。
+- [ ] 按 feature 分包，feature 内部按层；跨 feature 不互相调 repository/entity。
+- [ ] 跨层错误处理：领域抛语义异常→接口层集中映射 HTTP，500 不泄露细节。
+- [ ] input DTO 在边界校验；业务不变量在领域/服务校验。
+
+---
+**参考（commercial-grade 工程共识）**：Layered/Clean/Hexagonal Architecture（依赖向内）、Martin Fowler PoEAA（Service Layer、DTO）、DDD（聚合、值对象、避免贫血模型）、Package-by-Feature（模块化单体演进）。

package/backend/01-standards/auth-implementation.md

@@ -0,0 +1,104 @@
+---
+id: auth-implementation
+title: 认证与授权实现标准（商业级必读 · 全流程）
+domain: backend
+category: 01-standards
+difficulty: intermediate
+tags: [认证, 授权, auth, jwt, session, refresh-token, oauth, rbac, 密码重置, 邮箱验证, 登录, 注册, 权限, 商业级]
+quality_score: 96
+last_updated: 2026-06-19
+---
+
+# 认证与授权实现标准（商业级必读 · 全流程）
+
+> 认证是每个商业 app 的刚需，也是 AI 最容易写出**安全漏洞**的地方。本标准给出完整流程 + 安全要点。认证 = 你是谁（authentication），授权 = 你能做什么（authorization），两者都要做对。
+
+## 1. 选型：Session vs Token（先定再写）
+
+| | Session（服务端会话）| JWT/Token |
+|---|---|---|
+| 适合 | 传统 Web、需要随时吊销 | SPA/移动/多服务、无状态扩展 |
+| 存储 | 服务端(Redis) + cookie | 客户端持有 |
+| 吊销 | 天然可吊销 | 需黑名单/短过期 |
+
+- 单体 Web 优先 **session + HttpOnly cookie**（简单、可吊销、防 XSS 窃取）。
+- SPA/多服务用 **access token(短，15min) + refresh token(长，旋转)**；access 放内存，refresh 放 HttpOnly cookie。
+- **不要**把 JWT 放 localStorage（XSS 可窃取）。
+
+## 2. 注册（Registration）
+
+1. 校验 input（email 格式、密码强度：长度≥8 + 复杂度）。
+2. 检查 email 唯一（DB 唯一约束兜底，防并发重复）。
+3. **密码用 bcrypt/argon2 加盐哈希**存储（cost 合理），绝不明文/弱哈希。
+4. 创建用户（默认未验证状态）。
+5. 发**邮箱验证**链接（带签名 token，有过期）。
+6. 返回不泄露"该 email 是否已注册"（防枚举）。
+
+## 3. 登录（Login）
+
+1. 按 email 取用户；用户不存在也走一遍哈希比对（防时序枚举）。
+2. `bcrypt.compare` 校验密码；失败信息模糊（"账号或密码错误"）。
+3. **登录限流 + 失败锁定**（防爆破：N 次失败锁定/加验证码）。
+4. 成功 → 建 session 或签发 access+refresh token。
+5. 记录登录审计（时间、IP、UA）。
+
+## 4. Token 刷新与登出
+
+- **refresh token 旋转**：每次刷新签发新 refresh 并作废旧的（被盗用可检测：旧 refresh 被复用即全部吊销）。
+- access 过期 → 用 refresh 换新 access；refresh 过期 → 重新登录。
+- 登出：服务端使 session/refresh 失效（删除/加黑名单），清 cookie。
+- 维护 token 版本/会话表，支持"登出所有设备"。
+
+## 5. 密码重置（忘记密码）
+
+1. 提交 email → **无论是否存在都回相同响应**（防枚举）。
+2. 存在则发**一次性、短过期、签名**的重置 token（存哈希，用后即焚）。
+3. 用 token 设新密码 → 校验 token 有效未用未过期 → 更新哈希 → **作废该用户所有 session/refresh**（强制重登）。
+4. 重置链接走 HTTPS，token 不进日志。
+
+## 6. 邮箱验证
+
+- 注册后发签名验证 token（有过期）；点击验证后置 `email_verified`。
+- 未验证用户限制敏感操作；可重发验证（限流）。
+
+## 7. 授权（Authorization）—— 比认证更易漏
+
+- **每个受保护操作在服务层校验权限**，不能只靠"登录了"或前端隐藏。
+- **对象级授权（防 IDOR/BOLA）**：`GET /orders/{id}` 必须校验该 order 属于当前用户；不能凭 id 直取他人资源。
+- **RBAC**：用户-角色-权限模型；后台/管理端额外校验角色。复杂场景用策略/ABAC。
+- 默认拒绝，显式放行；最小权限。
+- 中间件做认证（解析 token/session → 当前用户），授权在业务层（能否操作这条资源）。
+
+## 8. OAuth / 第三方登录（如需）
+
+- 用成熟库/标准流程（Authorization Code + PKCE），不要自己手搓。
+- 校验 `state`(防 CSRF)、`nonce`；只信后端换 token，不在前端暴露 client secret。
+- 首次第三方登录映射/创建本地用户；处理 email 冲突。
+
+## 9. Cookie 与传输安全
+
+- 认证 cookie：`HttpOnly` + `Secure` + `SameSite=Lax/Strict`。
+- 全程 HTTPS；敏感端点防 CSRF（SameSite + token，或纯 Bearer）。
+- 不在响应/日志回传密码哈希、完整 token。
+
+## 10. 反模式（出现即不合格）
+
+- 明文/MD5/SHA1 存密码；JWT 放 localStorage；JWT 永不过期或 `alg:none`。
+- 登录无限流、错误信息暴露账号是否存在。
+- 只校验登录、不做对象级授权（可越权访问他人数据）。
+- 密码重置 token 长期有效/可复用/明文存/进日志；重置后不作废旧会话。
+- 自己手搓 OAuth；前端持有 client secret。
+- refresh token 不旋转、被盗无法检测。
+
+## 11. 最低交付 checklist
+
+- [ ] 先定 session vs token；JWT 不进 localStorage；cookie HttpOnly/Secure/SameSite。
+- [ ] 密码 bcrypt/argon2 哈希 + 强度校验 + email 唯一约束。
+- [ ] 登录限流/锁定 + 模糊错误 + 审计；access 短过期 + refresh 旋转。
+- [ ] 密码重置：防枚举 + 一次性短期签名 token + 重置后作废旧会话。
+- [ ] 邮箱验证流程。
+- [ ] 每个受保护操作做对象级授权（防 IDOR）+ RBAC + 默认拒绝最小权限。
+- [ ] OAuth 用标准库 + PKCE + state；全程 HTTPS + CSRF 防护。
+
+---
+**参考**：OWASP ASVS(认证/会话/访问控制)、OWASP Auth Cheat Sheet、OAuth 2.0/OIDC、RFC 6749/7636(PKCE)。

package/backend/01-standards/backend-framework-idioms.md

@@ -0,0 +1,74 @@
+---
+id: backend-framework-idioms
+title: 后端框架地道写法（Spring/NestJS/FastAPI/Express/Go · 官方惯例）
+domain: backend
+category: 01-standards
+difficulty: intermediate
+tags: [后端框架, spring-boot, nestjs, fastapi, express, gin, go, 分层, 依赖注入, dto, 事务, 中间件, 官方惯例, 商业级]
+quality_score: 94
+last_updated: 2026-06-19
+---
+
+# 后端框架地道写法（Spring/NestJS/FastAPI/Express/Go · 官方惯例）
+
+> 通用分层(controller→service→domain→repository)要落到**各框架的地道写法**。纯底座常写出"能跑但不地道"的代码。本标准把分层映射到主流框架的官方惯例。先按所选框架对号入座。
+
+## 通用（所有框架都遵守）
+
+- 四层 + 依赖向内（见《应用分层与分包》）：controller 仅传输 / service 用例+事务+收发 DTO / domain 业务规则 / repository 持久化。
+- **按 feature 分包**（不按技术层堆大目录）；shared 放公共件。
+- 入参 DTO + 校验；统一错误处理；DI 注入接口而非具体类。
+
+## Spring Boot（Java）
+
+- 分层注解：`@RestController`(传输) → `@Service`(业务+`@Transactional` 事务边界) → `@Repository`(Spring Data JPA)。
+- DTO + `@Valid` + Bean Validation 注解校验；**实体(@Entity) 不直接当响应**，转 DTO。
+- 全局异常用 `@RestControllerAdvice` + `@ExceptionHandler` 集中映射 HTTP。
+- 构造器注入(不用字段 @Autowired)；`application.yml` + profiles 分环境；配置类型安全(@ConfigurationProperties)。
+- 分包按 feature（`com.app.orders.{web,service,domain,repo}`）优于按层大目录。
+
+## NestJS（TypeScript）
+
+- **模块化按 feature**：每个 feature 一个 `@Module`，含 controller/service/dto/entity（**超过 ~20 controller 的纯分层会后悔**——按 feature）。
+- `@Controller`(传输) → `@Injectable() Service`(用例) → Repository(TypeORM/Prisma)；DI 注入。
+- DTO + **class-validator + ValidationPipe**(全局)校验；不返回 ORM entity，转 DTO/序列化。
+- 横切用 **Guards**(鉴权/授权)、**Interceptors**(日志/转换)、**Pipes**(校验/转换)、**ExceptionFilter**(统一错误)；放 SharedModule。
+- 事务在 service 层（QueryRunner / Prisma `$transaction`）。
+
+## FastAPI（Python）
+
+- 分层：`routers`(端点) → `services`(业务工作流) → `repositories`(DB 查询) → `schemas`(Pydantic 请求/响应校验)；core/db/shared 放基础设施；**business 按 feature 文件夹**。
+- **Pydantic 模型**做入参/出参校验与序列化；响应模型用 `response_model`，**不直接吐 ORM 对象**。
+- **依赖注入用 `Depends`**（DB session、当前用户、权限）；I/O 用 `async`。
+- SQLAlchemy 在 repository 封装；事务边界在 service；统一异常处理(exception_handler)。
+- API 版本化(`/v1`)、自动 OpenAPI 文档。
+
+## Express / NestJS-less Node（TypeScript）
+
+- 不要 fat route：route → controller → service → repository 分层；逻辑不写在路由回调里。
+- 校验用 zod/Joi 中间件；统一 **error-handling middleware**(最后挂载)；async 错误用包装器/`express-async-errors` 传到错误中间件。
+- 中间件做鉴权/日志/限流；配置/DI 显式装配；按 feature 组织。
+
+## Go（Gin/Echo/标准库）
+
+- Clean Architecture：handler(传输) → usecase/service(业务) → repository(接口+实现) → domain(实体)；依赖倒置，依赖注入接口。
+- 用 `context.Context` 传递取消/超时/请求范围值；**显式错误处理**(`if err != nil`)，错误包装(`fmt.Errorf("%w")`)。
+- 入参绑定+校验(validator)；不返回 DB model 直接序列化；事务在 service。
+- 不用全局可变状态；并发用 goroutine+channel 且注意同步。
+
+## 反模式（出现即不合格）
+
+- 把业务逻辑写在 controller/router/handler；controller 直连 DB/ORM。
+- 返回 ORM entity/DB model 给客户端；不转 DTO。
+- 不用框架的校验/DI/异常机制(各写各的)；事务写在错误层级。
+- 按技术层堆大目录(controllers/services/repos)而非 feature（NestJS/FastAPI 尤其）。
+- Spring 字段注入；Go 忽略 err / 全局可变状态；Express fat route 无错误中间件。
+
+## 最低交付 checklist
+
+- [ ] 按所选框架地道分层：Spring(@RestController/@Service/@Transactional/@Repository+@RestControllerAdvice)、NestJS(Module/Controller/Service/DTO+ValidationPipe/Guards/Filters)、FastAPI(routers/services/repositories/Pydantic/Depends/async)、Express(分层+错误中间件)、Go(clean arch+context+显式 err)。
+- [ ] 按 feature 分包；DTO 校验+不泄露 entity；DI 注入接口；事务在 service 层。
+- [ ] 框架原生机制做横切(校验/鉴权/异常/中间件)，不各写各的。
+
+---
+**参考（官方）**：Spring Boot 官方/分层、NestJS 官方(Modules/Providers/Pipes/Guards)、FastAPI 官方(Bigger Applications/Dependencies/SQL)、Express 错误处理、Go Clean Architecture。

package/backend/01-standards/background-jobs-and-async.md

@@ -0,0 +1,66 @@
+---
+id: background-jobs-and-async
+title: 后台任务与异步处理标准（商业级必读）
+domain: backend
+category: 01-standards
+difficulty: intermediate
+tags: [后台任务, 异步, async, 队列, queue, 定时任务, cron, worker, 幂等, 重试, 死信, dlq, 商业级]
+quality_score: 95
+last_updated: 2026-06-19
+---
+
+# 后台任务与异步处理标准（商业级必读）
+
+> 发邮件、处理上传、生成报表、对账、推送——耗时/可延迟的工作绝不能放在请求线程里让用户干等。本标准给出商业级的异步任务做法。
+
+## 1. 什么该异步
+
+- **耗时操作**（发邮件/短信、图片处理、报表生成、第三方慢调用）→ 入队列异步，请求快速返回。
+- **可延迟/批量**（清理、对账、统计聚合、过期处理）→ 定时任务。
+- **削峰**（突发写入）→ 队列缓冲。
+- 请求路径只做必须同步的事，其余抛给后台。
+
+## 2. 队列与 Worker
+
+- 用成熟队列（Redis+BullMQ / RabbitMQ / SQS / Celery / Sidekiq），不要自己用 DB 轮询硬撑（除非量小）。
+- 生产者入队（带任务类型+载荷+幂等键），Worker 消费；生产消费解耦、可独立扩展 Worker。
+- 任务载荷小（传 id 不传大对象）；幂等消费（见 §3）。
+
+## 3. 可靠性：幂等 + 重试 + 死信
+
+- **消费幂等**：同一任务可能投递多次（at-least-once），用任务 id/业务键去重，处理一次即可——尤其涉钱/发货/发邮件。
+- **重试 + 指数退避**：瞬时失败自动重试（限次数、退避），区分可重试(网络/限流)与不可重试(参数错)。
+- **死信队列(DLQ)**：超过重试仍失败的任务进 DLQ，告警 + 人工介入，不静默丢弃。
+- 任务可见性：记录状态(queued/processing/done/failed)、耗时、错误，可观测可重放。
+
+## 4. 定时任务（Cron）
+
+- 用调度器（cron / 平台 scheduler / k8s CronJob）触发，**幂等**（同一时刻可能多实例触发，要去重/加锁）。
+- 多实例下用分布式锁/leader 选举，避免重复跑。
+- 长任务有超时与监控；失败告警；不要让一个慢任务堆积。
+
+## 5. 与请求/事务的边界
+
+- 入队**在主事务提交之后**（或用 outbox 模式：业务与"待发消息"同事务写库，再由发送器投递），避免"事务回滚了但消息已发"或"消息发了但事务没提交"。
+- Worker 里涉及 DB 的操作自带事务与幂等。
+
+## 6. 反模式（出现即不合格）
+
+- 在请求线程里同步发邮件/处理大文件/调慢第三方，让用户干等。
+- 队列消费不幂等，重复投递导致重复扣款/重复发邮件。
+- 失败不重试或无限重试；失败任务静默丢弃（无 DLQ/告警）。
+- 定时任务多实例重复跑；长任务无超时堆积。
+- 用 DB 轮询当队列扛高并发；任务载荷塞大对象。
+- 事务未提交就入队（消息与数据不一致）。
+
+## 7. 最低交付 checklist
+
+- [ ] 耗时/可延迟工作入队列异步，请求快速返回。
+- [ ] 用成熟队列；生产消费解耦；载荷小传 id。
+- [ ] 消费幂等(去重) + 重试退避(区分可重试) + DLQ + 告警。
+- [ ] 定时任务幂等 + 多实例去重(分布式锁) + 超时监控。
+- [ ] 入队在事务提交后或用 outbox；Worker 内 DB 操作有事务+幂等。
+- [ ] 任务状态/耗时/错误可观测，可重放。
+
+---
+**参考**：消息队列模式、at-least-once + 幂等消费、Outbox 模式、指数退避、死信队列、分布式定时任务。