@umacloud/knowledge 1.0.15 → 1.0.17

package/frontend/01-standards/i18n-and-localization.md

@@ -62,4 +62,4 @@ last_updated: 2026-06-19
 - [ ] locale 检测+切换持久化；后端邮件/通知可本地化；多语言 SEO(hreflang)。
 
 ---
-**参考**：ICU MessageFormat、`Intl` API、react-i18next/vue-i18n、CLDR 复数规则、RTL 逻辑属性、hreflang。
+**参考**：ICU MessageFormat、`Intl` API、react-i18next/vue-i18n、CLDR 复数规则、RTL 逻辑属性、hreflang。数据导出/生成文档（CSV/Excel/PDF）的中文不乱码见 `backend/01-standards/cjk-in-exports-and-documents.md`。

package/frontend/01-standards/react-hooks-complete.md

@@ -5,8 +5,8 @@ domain: frontend
 category: 01-standards
 difficulty: intermediate
 tags: [complete, frontend, hooks, react, typescript, 常见陷阱, 性能优化, 最佳实践]
-quality_score: 70
-last_updated: 2026-06-15
+quality_score: 90
+last_updated: 2026-06-29
 ---
 # React Hooks 深度指南
 
@@ -327,12 +327,12 @@ function Parent() {
   const [count, setCount] = useState(0);
   const [text, setText] = useState('');
   
-  // ❌ 不好:每次渲染都创建新函数
+  // [避免] 不好:每次渲染都创建新函数
   // const handleClick = () => {
   //   console.log('Clicked');
   // };
   
-  // ✅ 好:缓存函数引用
+  // [推荐] 好:缓存函数引用
   const handleClick = useCallback(() => {
     console.log('Clicked');
   }, []);
@@ -360,12 +360,12 @@ function Parent() {
 import React, { useState, useMemo } from 'react';
 
 function ProductList({ products, filter, sortBy }) {
-  // ❌ 不好:每次渲染都重新计算
+  // [避免] 不好:每次渲染都重新计算
   // const filteredProducts = products
   //   .filter(p => p.name.includes(filter))
   //   .sort((a, b) => a[sortBy] - b[sortBy]);
   
-  // ✅ 好:缓存计算结果
+  // [推荐] 好:缓存计算结果
   const filteredProducts = useMemo(() => {
     console.log('重新计算过滤和排序');
     return products
@@ -837,26 +837,26 @@ function LoginForm() {
 ### 规则 1: 只在顶层调用 Hooks
 
 ```javascript
-// ❌ 错误:在循环中调用
+// [避免] 错误:在循环中调用
 function BadComponent({ items }) {
   items.forEach(item => {
     const [state, setState] = useState(item); // 错误!
   });
 }
 
-// ✅ 正确:在顶层调用
+// [推荐] 正确:在顶层调用
 function GoodComponent({ items }) {
   const [states, setStates] = useState(items);
 }
 
-// ❌ 错误:在条件语句中调用
+// [避免] 错误:在条件语句中调用
 function BadComponent({ condition }) {
   if (condition) {
     const [value, setValue] = useState(0); // 错误!
   }
 }
 
-// ✅ 正确:条件逻辑在 Hook 内部
+// [推荐] 正确:条件逻辑在 Hook 内部
 function GoodComponent({ condition }) {
   const [value, setValue] = useState(0);
   
@@ -871,12 +871,12 @@ function GoodComponent({ condition }) {
 ### 规则 2: 只在 React 函数中调用
 
 ```javascript
-// ❌ 错误:在普通函数中调用
+// [避免] 错误:在普通函数中调用
 function handleClick() {
   const [count, setCount] = useState(0); // 错误!
 }
 
-// ✅ 正确:在组件或自定义 Hook 中调用
+// [推荐] 正确:在组件或自定义 Hook 中调用
 function MyComponent() {
   const [count, setCount] = useState(0);
   
@@ -918,12 +918,12 @@ const ChildComponent = memo(({ data, onClick }) => {
 ### 2. 正确使用依赖数组
 
 ```javascript
-// ❌ 缺少依赖
+// [避免] 缺少依赖
 useEffect(() => {
   fetchData(userId);
 }, []); // 缺少 userId 依赖
 
-// ✅ 完整依赖
+// [推荐] 完整依赖
 useEffect(() => {
   fetchData(userId);
 }, [userId]);
@@ -932,7 +932,7 @@ useEffect(() => {
 ### 3. 避免内联函数和对象
 
 ```javascript
-// ❌ 每次渲染都创建新函数/对象
+// [避免] 每次渲染都创建新函数/对象
 function Parent() {
   const [count, setCount] = useState(0);
   
@@ -944,7 +944,7 @@ function Parent() {
   );
 }
 
-// ✅ 使用 useCallback 和 useMemo
+// [推荐] 使用 useCallback 和 useMemo
 function Parent() {
   const [count, setCount] = useState(0);
   
@@ -988,7 +988,7 @@ function VirtualizedList({ items }) {
 ### 陷阱 1: 闭包陷阱
 
 ```javascript
-// ❌ 错误:闭包捕获旧值
+// [避免] 错误:闭包捕获旧值
 function Counter() {
   const [count, setCount] = useState(0);
   
@@ -1000,7 +1000,7 @@ function Counter() {
   }, []);
 }
 
-// ✅ 正确:使用函数式更新
+// [推荐] 正确:使用函数式更新
 function Counter() {
   const [count, setCount] = useState(0);
   
@@ -1015,7 +1015,7 @@ function Counter() {
   }, []);
 }
 
-// ✅ 或使用 ref
+// [推荐] 或使用 ref
 function Counter() {
   const [count, setCount] = useState(0);
   const countRef = useRef(count);
@@ -1034,7 +1034,7 @@ function Counter() {
 ### 陷阱 2: 无限循环
 
 ```javascript
-// ❌ 错误:导致无限循环
+// [避免] 错误:导致无限循环
 function BadComponent() {
   const [items, setItems] = useState([]);
   
@@ -1043,7 +1043,7 @@ function BadComponent() {
   }, [items]); // 依赖 items,导致循环
 }
 
-// ✅ 正确:使用函数式更新
+// [推荐] 正确:使用函数式更新
 function GoodComponent() {
   const [items, setItems] = useState([]);
   
@@ -1056,11 +1056,11 @@ function GoodComponent() {
 ### 陷阱 3: 直接修改状态
 
 ```javascript
-// ❌ 错误:直接修改状态
+// [避免] 错误:直接修改状态
 const [user, setUser] = useState({ name: 'Alice' });
 user.name = 'Bob'; // 不会触发重新渲染
 
-// ✅ 正确:创建新对象
+// [推荐] 正确:创建新对象
 setUser({ ...user, name: 'Bob' });
 ```
 
@@ -1068,16 +1068,16 @@ setUser({ ...user, name: 'Bob' });
 
 ## 最佳实践
 
-1. **✅ 使用函数式更新**: `setCount(prev => prev + 1)`
-2. **✅ 保持依赖数组完整**: 使用 eslint-plugin-react-hooks
-3. **✅ 拆分复杂状态**: 多个 useState 而非一个巨大对象
-4. **✅ 自定义 Hook 复用逻辑**: 避免复制粘贴
-5. **✅ 命名规范**: use 开头的自定义 Hook
-6. **✅ 合理使用 useMemo/useCallback**: 不要过度优化
-7. **✅ 错误边界**: 处理渲染错误
-8. **✅ 清理副作用**: useEffect 返回清理函数
-9. **✅ 测试 Hooks**: 使用 @testing-library/react-hooks
-10. **✅ TypeScript 支持**: 为 Hook 添加类型
+1. **[推荐] 使用函数式更新**: `setCount(prev => prev + 1)`
+2. **[推荐] 保持依赖数组完整**: 使用 eslint-plugin-react-hooks
+3. **[推荐] 拆分复杂状态**: 多个 useState 而非一个巨大对象
+4. **[推荐] 自定义 Hook 复用逻辑**: 避免复制粘贴
+5. **[推荐] 命名规范**: use 开头的自定义 Hook
+6. **[推荐] 合理使用 useMemo/useCallback**: 不要过度优化
+7. **[推荐] 错误边界**: 处理渲染错误
+8. **[推荐] 清理副作用**: useEffect 返回清理函数
+9. **[推荐] 测试 Hooks**: 使用 @testing-library/react-hooks
+10. **[推荐] TypeScript 支持**: 为 Hook 添加类型
 
 ---
 

package/frontend/01-standards/ui-states-and-resilient-data-fetching.md

@@ -0,0 +1,97 @@
+---
+id: ui-states-and-resilient-data-fetching
+title: UI 状态与健壮数据获取规范（商业级前端必读）
+domain: frontend
+category: 01-standards
+difficulty: intermediate
+tags: [ui-states, loading, empty, error, optimistic-update, data-fetching, retry, resilience, 状态, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# UI 状态与健壮数据获取规范（商业级前端必读）
+
+> 区分"demo 级"和"商业级"前端的，不是动效，而是**对每一种状态的处理**：加载、空、错误、部分、离线、并发。
+> 只画 happy path（有数据、网络好、不点重复）的界面，一上真实网络就白屏、转圈卡死、数据错乱。
+> 每个会取数或提交的界面，都必须显式设计完整的状态矩阵。
+
+## 1. 状态矩阵（每个数据视图都要覆盖）
+
+任何"从后端取数据"的视图，至少要显式处理这些状态——缺一即不合格：
+
+| 状态 | 含义 | UI 要求 |
+|---|---|---|
+| Loading（首次）| 还没有数据 | 骨架屏/占位，**不要**只放一个居中转圈占满屏 |
+| Loading（刷新）| 已有旧数据、在拉新 | 保留旧内容 + 局部加载指示（不闪白） |
+| Empty | 请求成功但无数据 | 友好空态：说明 + 引导操作（"还没有订单，去下单"），区分"无数据"与"加载中" |
+| Partial | 部分成功/分页中 | 显示已有 + "加载更多"/继续指示 |
+| Error | 请求失败 | 明确错误信息 + **重试按钮**，不要白屏或一直转 |
+| Success | 正常有数据 | 正常渲染 |
+| Forbidden | 无权限 | 明确"无权限"而非空态或报错 |
+| Offline | 无网络 | 离线提示 + 恢复后自动/手动重试 |
+
+**反模式**：把 Empty 当 Loading（无数据时永远转圈）、把 Error 当 Empty（失败却显示"暂无数据"误导用户）、加载时整屏白屏闪烁。
+
+## 2. 加载体验
+
+- **骨架屏优先**：列表/卡片/详情用与最终布局一致的骨架占位，避免布局跳动（CLS）。
+- **保留旧数据刷新**：翻页/筛选/轮询时保留当前内容做局部 loading，别清空成白屏（stale-while-revalidate 思路）。
+- **延迟显示 loading**：极快的请求（<300ms）可不显示 spinner，避免"闪一下"的抖动；超过阈值才显示。
+- **防止布局跳动**：为图片/异步内容预留尺寸，占位与真实内容同尺寸。
+
+## 3. 错误处理
+
+- **永远有出路**：任何错误态都要给"重试"或"返回"，绝不留死界面。
+- **可理解的信息**：把后端错误信封（`code/message`）映射成用户能懂的话；不要把原始 500 堆栈/技术错误码甩给用户。
+- **就近显示**：表单字段错误显示在字段旁，全局错误用 toast/横幅；区分"可重试的系统错误"和"用户需修正的输入错误"。
+- **错误边界（error boundary）**：组件级渲染异常要被边界捕获，降级为局部错误块，**不要整页崩白**。
+- **超时也是错误**：请求设超时，超时给明确反馈与重试，不要无限转圈。
+
+## 4. 健壮的数据获取
+
+- **客户端重试**：对幂等的 GET 失败做有限次指数退避+抖动重试；非幂等提交不自动重试（需幂等键，见 `backend/01-standards/idempotency-and-safe-retries`）。
+- **请求竞态（latest-wins）**：快速切换筛选/搜索时，旧请求的响应可能后到并覆盖新结果——必须取消过期请求或丢弃过期响应（按发起序号/AbortController），保证"显示的是最后一次请求的结果"。
+- **缓存与重验证**：列表数据可缓存并在后台重验证（stale-while-revalidate），先给旧值再悄悄刷新，提升感知速度。
+- **去抖/节流**：搜索框输入去抖（debounce），滚动/resize 节流，避免请求风暴。
+- **分页/无限滚动**：明确"加载更多/到底了/加载失败可重试"三态，别静默停住。
+
+## 5. 提交与乐观更新
+
+- **防重复提交**：提交中禁用按钮 + 显示进行态；双击/回车连发只触发一次。配合服务端幂等。
+- **乐观更新要可回滚**：先更新 UI 再发请求时，必须保存前值，**失败回滚**并提示，绝不让界面停留在"假成功"。
+- **明确的提交结果**：成功给确认（toast/跳转），失败保留用户输入（别清空表单）+ 显示原因。
+- **长操作**：耗时操作给进度/可取消，而不是冻结界面。
+
+## 6. 表单状态
+
+- 校验分层：即时（失焦校验单字段）+ 提交时整体校验；错误就近显示。
+- 提交中：禁用提交、显示 loading、阻止重复提交。
+- 失败：保留已填数据，定位到第一个错误字段。
+- 离开未保存：脏表单离开前提示，避免误丢输入。
+
+## 7. 可访问性与状态
+
+- 加载/错误/成功要对辅助技术可感知：用 `aria-live` 通知动态变化，loading 用 `aria-busy`，错误关联到字段（`aria-describedby`）。
+- 焦点管理：错误后把焦点移到错误区/首个错误字段；模态打开/关闭正确收发焦点。
+- 不要只用颜色传达状态（红=错），要有文字/图标兜底。
+
+## 8. 反模式（出现即不合格）
+
+1. **只做 happy path**：无 empty/error/loading 处理，真实网络下白屏或转圈不止。
+2. **空态当加载**：无数据时永远 spinner。
+3. **错误吞掉**：catch 后什么都不显示，用户面对死界面。
+4. **整页崩白**：单个组件抛错拖垮整页（无 error boundary）。
+5. **请求竞态覆盖**：快速切换后显示的是旧请求的结果。
+6. **乐观更新不回滚**：失败后界面停在假成功。
+7. **可重复提交**：双击下单两次、扣两次款。
+8. **加载闪白/布局跳动**：刷新清空内容、异步内容撑开布局。
+
+## 9. 最低交付 checklist
+
+- [ ] 每个取数视图覆盖 loading/empty/error/partial/forbidden/offline 全状态。
+- [ ] 错误态都有重试出口，错误信息对用户可理解。
+- [ ] 首次加载用骨架屏，刷新保留旧数据不闪白。
+- [ ] 组件级 error boundary 防整页崩。
+- [ ] 取数处理请求竞态（latest-wins / 取消过期请求）。
+- [ ] 提交防重复 + 乐观更新可回滚 + 失败保留输入。
+- [ ] 幂等的失败有限重试（退避+抖动），非幂等不自动重试。
+- [ ] 状态变化对辅助技术可感知（aria-live/focus 管理）。

package/frontend/01-standards/vue3-complete.md

@@ -5,8 +5,8 @@ domain: frontend
 category: 01-standards
 difficulty: intermediate
 tags: [complete, frontend, pinia, router, vue3, 响应式系统原理, 性能优化, 概述]
-quality_score: 70
-last_updated: 2026-06-15
+quality_score: 91
+last_updated: 2026-06-29
 ---
 # Vue 3 完整知识体系
 

package/high-quality-engineering-playbook.md

@@ -1,15 +1,13 @@
 ---
 id: high-quality-engineering-playbook
-title: high-quality-engineering-playbook
-domain: high-quality-engineering-playbook.md
+title: 高质量工程知识库（Web 全栈版）
+domain: development
 difficulty: intermediate
-tags: [engineering, high, high-quality-engineering-playbook.md, playbook, quality, 全栈版]
+tags: [高质量工程, engineering, web全栈, 工程规范, 全栈, development, 商业级]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## 高质量工程知识库（Web 全栈版）
+# 高质量工程知识库（Web 全栈版）
 
 ### 1. 目标与范围
 - 本知识库面向商业级 Web 应用，覆盖需求澄清、架构设计、交互体验、工程质量、上线运维与复盘。

package/incident/02-playbooks/chaos-engineering-playbook.md

@@ -10,11 +10,7 @@ difficulty: intermediate
 quality_score: 70
 ---
 
-# 开发：Excellent（11964948@qq.com）
-# 功能：混沌工程全流程作战手册
-# 作用：指导团队安全地实施混沌实验以验证系统韧性
-# 创建时间：2026-03-28
-# 最后修改：2026-03-28
+# 混沌工程作战手册
 
 ## 目标
 

package/incident/postmortem-and-response-deep-dive.md

@@ -1,16 +1,14 @@
 ---
 id: postmortem-and-response-deep-dive
-title: postmortem-and-response-deep-dive
+title: 事故响应与复盘深度知识库
 domain: incident
-category: postmortem-and-response-deep-dive.md
+category: 01-standards
 difficulty: intermediate
-tags: [and, deep, dive, incident, postmortem, response, 事故响应与复盘深度知识库]
+tags: [事故响应, postmortem, 复盘, incident-response, 根因分析, incident]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## 事故响应与复盘深度知识库
+# 事故响应与复盘深度知识库
 
 ### 目标
 - 把每次故障转化为可复用的组织能力，持续降低重复事故概率。

package/mobile/01-standards/flutter-complete.md

@@ -2,17 +2,15 @@
 title: Flutter 完整开发标准
 category: mobile/standards
 version: 1.0.0
-last_updated: 2026-03-20
-maintainer: Excellent（11964948@qq.com）
+last_updated: 2026-06-29
 knowledge_score: 9.3/10
 domain: mobile
 difficulty: intermediate
-quality_score: 70
+quality_score: 83
 ---
 
-# 开发：Excellent（11964948@qq.com）
+# Flutter 完整开发标准
 
-## Flutter 完整开发标准
 
 ### 1. 架构与分层
 - 遵循 Clean Architecture 或 MVVM 模式。
@@ -79,7 +77,6 @@ quality_score: 70
 
 ### Widget 组件示例
 ```dart
-// 开发：Excellent（11964948@qq.com）
 // 功能：用户头像组件
 // 作用：展示用户头像，支持默认头像和加载状态
 // 创建时间：2026-03-20
@@ -150,7 +147,6 @@ class UserAvatar extends StatelessWidget {
 
 ### 网络请求封装示例
 ```dart
-// 开发：Excellent（11964948@qq.com）
 // 功能：API 客户端封装
 // 作用：统一管理网络请求，包含认证和错误处理
 // 创建时间：2026-03-20
@@ -230,7 +226,6 @@ final apiClient = ApiClient();
 
 ### 状态管理示例（Provider）
 ```dart
-// 开发：Excellent（11964948@qq.com）
 // 功能：用户状态管理
 // 作用：管理用户登录状态和用户信息
 // 创建时间：2026-03-20

package/mobile/01-standards/react-native-complete.md

@@ -2,17 +2,15 @@
 title: React Native 完整开发标准
 category: mobile/standards
 version: 1.0.0
-last_updated: 2026-03-20
-maintainer: Excellent（11964948@qq.com）
+last_updated: 2026-06-29
 knowledge_score: 9.2/10
 domain: mobile
 difficulty: intermediate
-quality_score: 70
+quality_score: 83
 ---
 
-# 开发：Excellent（11964948@qq.com）
+# React Native 完整开发标准
 
-## React Native 完整开发标准
 
 ### 1. 架构与分层
 - 业务层、展示层、数据层严格分离。
@@ -79,7 +77,6 @@ quality_score: 70
 ### TypeScript 组件示例
 ```typescript
 /**
- * 开发：Excellent（11964948@qq.com）
  * 功能：用户头像组件
  * 作用：展示用户头像，支持默认头像和加载状态
  * 创建时间：2026-03-20
@@ -138,7 +135,6 @@ const styles = StyleSheet.create({
 ### 网络请求封装示例
 ```typescript
 /**
- * 开发：Excellent（11964948@qq.com）
  * 功能：API 客户端封装
  * 作用：统一管理网络请求，包含认证和错误处理
  * 创建时间：2026-03-20
@@ -201,7 +197,6 @@ export const apiClient = new ApiClient();
 ### FlatList 优化示例
 ```typescript
 /**
- * 开发：Excellent（11964948@qq.com）
  * 功能：用户列表组件
  * 作用：高性能渲染用户列表，支持下拉刷新和加载更多
  * 创建时间：2026-03-20

package/mobile/02-playbooks/mobile-performance.md

@@ -2,17 +2,15 @@
 title: 移动应用性能优化手册
 category: mobile/playbooks
 version: 1.0.0
-last_updated: 2026-03-20
-maintainer: Excellent（11964948@qq.com）
+last_updated: 2026-06-29
 knowledge_score: 9.0/10
 domain: mobile
 difficulty: intermediate
-quality_score: 70
+quality_score: 83
 ---
 
-# 开发：Excellent（11964948@qq.com）
+# 移动应用性能优化手册
 
-## 移动应用性能优化手册
 
 ### 执行步骤
 
@@ -88,7 +86,6 @@ quality_score: 70
 #### React Native 优化
 ```typescript
 /**
- * 开发：Excellent（11964948@qq.com）
  * 功能：优化 FlatList 性能
  * 作用：通过配置优化参数提升长列表渲染性能
  * 创建时间：2026-03-20
@@ -165,7 +162,6 @@ export default OptimizedList;
 
 #### Flutter 优化
 ```dart
-// 开发：Excellent（11964948@qq.com）
 // 功能：优化 ListView 性能
 // 作用：通过 const 和 builder 提升长列表渲染性能
 // 创建时间：2026-03-20
@@ -231,7 +227,6 @@ class _ItemTile extends StatelessWidget {
 #### React Native 性能监控
 ```typescript
 /**
- * 开发：Excellent（11964948@qq.com）
  * 功能：性能监控工具
  * 作用：记录和上报关键性能指标
  * 创建时间：2026-03-20
@@ -326,7 +321,6 @@ export const performanceMonitor = PerformanceMonitor.getInstance();
 
 #### Flutter 性能监控
 ```dart
-// 开发：Excellent（11964948@qq.com）
 // 功能：性能监控工具
 // 作用：记录和上报关键性能指标
 // 创建时间：2026-03-20

package/mobile/03-checklists/mobile-release-checklist.md

@@ -2,17 +2,15 @@
 title: 移动应用发布检查清单
 category: mobile/checklists
 version: 1.0.0
-last_updated: 2026-03-20
-maintainer: Excellent（11964948@qq.com）
+last_updated: 2026-06-29
 knowledge_score: 9.1/10
 domain: mobile
 difficulty: intermediate
-quality_score: 70
+quality_score: 85
 ---
 
-# 开发：Excellent（11964948@qq.com）
+# 移动应用发布检查清单
 
-## 移动应用发布检查清单
 
 ### 一、功能完整性检查
 

package/mobile/04-antipatterns/mobile-antipatterns.md

@@ -2,17 +2,15 @@
 title: 移动开发反模式库
 category: mobile/antipatterns
 version: 1.0.0
-last_updated: 2026-03-20
-maintainer: Excellent（11964948@qq.com）
+last_updated: 2026-06-29
 knowledge_score: 9.0/10
 domain: mobile
 difficulty: intermediate
-quality_score: 70
+quality_score: 88
 ---
 
-# 开发：Excellent（11964948@qq.com）
+# 移动开发反模式库
 
-## 移动开发反模式库
 
 ### 1. 性能反模式
 

package/observability/01-standards/observability-and-slo-operations.md

@@ -0,0 +1,88 @@
+---
+id: observability-and-slo-operations
+title: 可观测性与 SLO 运营规范（埋点契约/关联/错误预算，商业级必读）
+domain: observability
+category: 01-standards
+difficulty: advanced
+tags: [observability, structured-logging, metrics, tracing, correlation, slo, sli, error-budget, instrumentation-contract, cardinality, alerting, 可观测性, 结构化日志, 链路追踪, 错误预算, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 可观测性与 SLO 运营规范（商业级必读）
+
+> 监控回答"系统是不是挂了"，可观测性回答"**为什么挂、挂在哪、影响谁**"——尤其是面对**从没预想过**的故障，你能不能只靠已有的遥测数据查出来，而不必先发一版新代码加日志。
+> 商业级系统把"每个服务必须发出什么遥测"当成**埋点契约**来落地，把三类信号（日志/指标/追踪）用统一关联键打通，并用 **SLO + 错误预算**把"健康"从主观感受变成可运营的数字。
+
+## 1. 三类信号，各司其职
+
+| 信号 | 回答 | 特点 |
+|---|---|---|
+| 指标（metrics）| "坏了吗？坏多少？"（趋势、聚合）| 便宜、可长留、适合告警与看板 |
+| 日志（logs）| "具体发生了什么？"（离散事件细节）| 信息密度高、量大、要结构化 |
+| 追踪（traces）| "慢/错在调用链的哪一跳？"（请求穿越多服务的路径）| 定位跨服务瓶颈与故障点 |
+
+三者不是三选一，而是**互补**：指标发现异常 → 追踪定位到哪一跳 → 日志看那一跳的细节。关键是它们能**互相关联**（见 §3）。
+
+## 2. 埋点契约（每个服务必须发出的最小遥测）
+
+把"该发什么"标准化，避免每个服务各记各的、查问题时拼不起来：
+
+- **结构化日志**：JSON/键值，不是裸文本字符串。必带字段：时间戳（UTC、ISO-8601）、级别、服务名、**关联ID（request_id / trace_id）**、消息；事件相关的关键业务字段。
+- **请求/依赖指标**：每个入站端点与每个出站依赖发出请求量、错误率、延迟分布（直方图，能算分位）；资源侧发出利用率与饱和度。
+- **追踪**：入口生成/承接 trace，向所有下游**传播追踪上下文**，每个关键操作开 span，记录耗时与状态。
+- **业务指标**：注册、下单、支付、转化等业务事件计数——技术全绿但下单为零也是事故。
+- **健康检查**：存活/就绪端点，区分"进程活着"和"能正常服务"（依赖就绪）。
+
+## 3. 关联：把三类信号缝起来
+
+- **统一关联ID**：每个请求在入口生成 `request_id` / `trace_id`，**贯穿**该请求触发的所有日志、span、跨服务调用。出问题时凭一个 ID 就能把一次请求的日志、链路、指标全捞出来。
+- **上下文传播**：调用下游时透传追踪上下文（标准追踪头），让链路不断裂。
+- **日志带 trace_id**：每条日志都带当前 trace_id，实现"从一条慢链路一键跳到对应日志"。
+- **统一维度**：服务名、环境、版本、端点等标签在三类信号里取**一致的命名**，才能交叉关联。
+
+## 4. 基数（cardinality）纪律
+
+可观测性最容易失控、最容易烧钱的地方是**高基数标签**：
+
+- **指标标签不放无界值**：用户ID、请求ID、邮箱、完整 URL 等高基数值**绝不**做指标标签（会让时间序列爆炸、成本失控、查询变慢）。这些放**日志/追踪**里（它们按事件存，能承载高基数）。
+- **路径要模板化**：`/orders/123` 在指标里归一为 `/orders/{id}`，不要每个 id 一条序列。
+- **采样**：高流量追踪可采样（按比例 + 对错误/慢请求强制保留），平衡成本与可见性。
+- **日志分级与量控**：DEBUG 默认关；避免热路径里高频打无用日志把信号淹没、把成本拉高。
+
+## 5. SLI / SLO / 错误预算（把"健康"变成可运营的数字）
+
+- **SLI（指标）**：从用户视角度量服务质量的量——可用性（成功请求占比）、延迟（达标请求占比）、正确性等。盯**用户体验到的**，不是 CPU。
+- **SLO（目标）**：给 SLI 定目标，如"30 天内 99.9% 的请求成功且 p95 < 300ms"。SLO 要现实、可达、对齐业务。
+- **错误预算（error budget）**：100% 减去 SLO = 允许的"不达标额度"。99.9% 即每月约 0.1% 的预算。
+  - 预算**没烧光** → 可以快速发布、大胆迭代。
+  - 预算**烧光** → 冻结高风险变更、优先稳定性，直到回到预算内。
+  - 这把"该求快还是求稳"从拍脑袋变成**数据驱动**的决策（深做见 `operations/slo-sli-playbook`）。
+
+## 6. 告警：少而准，可执行
+
+- **基于症状告警**：对**用户感受到的**问题告警（错误率、延迟、SLO 燃尽），而不是对每个内部抖动（单台 CPU 高）告警。
+- **错误预算燃尽率告警**：按预算消耗速度告警——烧得快（短窗口高燃尽）才需立刻叫人，慢烧给工单即可。
+- **每条告警可执行**：触发即有人能做事，并指向 runbook；不可行动的告警要删，否则养出"告警疲劳"、真事故被淹。
+- **分级**：区分"立刻起床处理"和"工作时间看"，别什么都 P1。
+
+## 7. 反模式（出现即不合格）
+
+1. **裸文本日志**：非结构化字符串，无法检索、聚合、关联。
+2. **三信号各自为政**：日志、指标、追踪没有共同关联ID，出事拼不起来。
+3. **高基数炸指标**：把用户ID/请求ID/原始URL塞进指标标签，序列爆炸、成本失控。
+4. **只测技术指标不看业务**：CPU/内存全绿，但下单为零无人发现。
+5. **只有指标没有追踪**：知道"变慢了"但不知道慢在跨服务调用的哪一跳。
+6. **告警噪音**：成百上千条不可行动告警，真事故被淹，on-call 疲劳。
+7. **无 SLO**：没有"多好才算好"的定义，求快还是求稳全靠吵。
+8. **要查问题先加日志再发版**：遥测不足，未预想的故障无法靠现有数据定位。
+
+## 8. 最低交付 checklist
+
+- [ ] 全部日志结构化，带时间戳/级别/服务名/关联ID/消息。
+- [ ] 每个端点与依赖发出请求量/错误率/延迟分布；有关键业务指标。
+- [ ] 入口生成 trace_id 并贯穿日志与跨服务调用，追踪上下文全程传播。
+- [ ] 指标标签无高基数值，路径模板化；高流量追踪按需采样、错误强留。
+- [ ] 定义面向用户的 SLI 与现实的 SLO，落地错误预算并用于发布决策。
+- [ ] 告警基于用户症状与错误预算燃尽，条条可执行、指向 runbook、分级。
+- [ ] 健康检查区分存活与就绪。
+- [ ] 凭一个 request_id 能捞出一次请求的日志、链路与相关指标。

package/observability/01-standards/observability-standards.md

@@ -12,6 +12,8 @@ last_updated: 2026-06-14
 
 # 可观测性标准（日志 / 指标 / 追踪）
 
+> 本页是**具体配置片段速查**（日志字段示例、PromQL、告警表、健康检查 JSON）。可观测性的权威规范——埋点契约、三信号关联、基数纪律、SLI/SLO 与错误预算——见 `observability/01-standards/observability-and-slo-operations`，两者配合使用。
+
 ## 三柱可观测性
 
 ### 1. 结构化日志