@umacloud/knowledge 1.0.15 → 1.0.17

package/development/01-standards/code-review-and-pr-hygiene.md

@@ -0,0 +1,85 @@
+---
+id: code-review-and-pr-hygiene
+title: 代码评审标准与 PR 卫生规范（商业级必读）
+domain: development
+category: 01-standards
+difficulty: intermediate
+tags: [code-review, pr, pull-request, review-standards, small-pr, blocking-vs-nit, review-sla, atomic-commit, 代码评审, 评审, pr卫生, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 代码评审标准与 PR 卫生规范（商业级必读）
+
+> 代码评审不是挑刺仪式，也不是橡皮图章。它是**在缺陷进入主干前**拦住它、并让知识在团队里扩散的工程动作。
+> 评审能不能起作用，一半取决于**作者把 PR 准备得多好评审**，一半取决于**评审者关注什么、用什么口吻**。
+> 商业级团队对两端都有硬标准：小而聚焦的 PR + 有重点、可执行、对事不对人的评审。
+
+## 1. 评审到底在查什么（优先级从高到低）
+
+| 关注点 | 看什么 |
+|---|---|
+| **正确性** | 逻辑对不对、边界/错误/并发有没有处理、会不会破坏现有行为 |
+| **安全** | 越权、注入、输入校验、敏感信息泄露、危险默认配置 |
+| **测试** | 改动有没有对应测试，测试是否覆盖关键路径与边界，而非只测 happy path |
+| **可维护性** | 命名、结构、复杂度、是否引入难以理解或难以删除的耦合 |
+| **契约/兼容** | 接口/数据变更是否破坏消费方、是否需要版本化与迁移 |
+| **可观测性** | 关键路径有没有日志/指标，错误是否可定位 |
+| **风格** | 一致性——但**自动化能管的（格式化/lint）不靠人评审** |
+
+把人力评审用在机器查不了的地方（正确性、设计、安全语义），格式/风格交给自动化。
+
+## 2. 作者侧：把 PR 准备到"好评审"
+
+- **小而聚焦**：一个 PR 只做一件事。大 PR 评审质量断崖式下降——评审者看不动就只能盖章。难以拆分的大改动要拆成一串可独立评审、可独立回滚的小 PR。
+- **自审先行**：提交前自己先过一遍 diff，删调试代码、补测试、跑通构建+lint+测试，别把机器能发现的问题丢给评审者。
+- **说清楚 why**：PR 描述写"为什么这么改、影响范围、如何验证、如何回滚"，而不是把标题复述一遍。让评审者**不用猜**。
+- **关联需求**：链接到对应需求/任务/缺陷，让改动可追溯（见 `experts/product-manager/prd-template-and-structure` 的可追溯矩阵）。
+- **标注重点**：主动指出"这块我不确定""这里请重点看",引导评审注意力。
+- **绿灯再请评**：CI 没过别请人评审；让评审者帮你跑 lint 是浪费。
+
+## 3. 评审者侧：有效且尊重
+
+- **及时**：评审是阻塞别人的事，设 SLA（如一个工作日内首轮响应），别让 PR 烂在队列里。评审优先级高于自己写新代码。
+- **分清阻塞与建议**：明确标注哪些是**必须改（blocking）**、哪些是**可选建议（nit/suggestion）**。不要用一堆口味问题卡住一个正确的 PR。
+- **具体、可执行**：指出问题要给出原因和（可能的）改法，"这里不好"不是有效评审。
+- **问而非命令**：用"这里在 X 情况下会不会 Y？"代替"改成 Z"，把判断权留给作者、把上下文逼出来。
+- **对事不对人**：评审代码不评审人；任何人都会写 bug，评审是协作不是审判。
+- **该夸就夸**：好的设计/测试值得肯定，评审不只是找问题。
+- **认知边界**：看不懂的地方要问，不假装看懂盖章；批准 = 你为这段代码的正确性背了书。
+
+## 4. PR / 提交卫生
+
+- **原子提交**：每个提交是一个自洽的逻辑单元，信息说清"做了什么、为什么"，便于排查与回滚。
+- **干净历史**：合并前清理无意义的 "fix typo"、"wip" 提交噪音，让历史可读。
+- **不夹带**：重构和功能改动分开 PR——把格式化大改和逻辑改动混在一个 PR 里，评审者根本看不出真正的变化。
+- **改动可回滚**：PR 粒度要让"出事单独回滚这一个改动"成为可能。
+
+## 5. 自动化兜底（人只做机器做不了的）
+
+- **格式/lint/类型/测试/安全扫描**进 CI 必过门禁，**不进人工评审**（见 `testing/01-standards/ci-test-gates-and-coverage`）。
+- **必评审 + 必过 CI** 作为合并保护：主干受保护，绕不过。
+- **覆盖关键变更**：安全/支付/权限等高风险路径要求更强评审（如指定领域评审人）。
+- 评审清单可参考 `development/03-checklists/pr-checklist`。
+
+## 6. 反模式（出现即不合格）
+
+1. **巨型 PR**：上千行混合改动，评审者看不动只能盖章，缺陷直接漏进主干。
+2. **橡皮图章**："LGTM" 秒批，根本没看；批准却不负责。
+3. **风格暴政**：用一堆个人口味的 nit 卡住正确的 PR，不分阻塞与建议。
+4. **人肉跑 lint**：把格式化/风格交给人评审，浪费人力还不一致。
+5. **对人不对事**：评审带情绪、贬低作者，让人不敢提 PR。
+6. **PR 无上下文**：描述空白或只复述标题，评审者全靠猜。
+7. **重构夹带功能**：格式化与逻辑改动混一个 PR，真正的变化被淹没。
+8. **评审烂队列**：PR 几天没人看，阻塞交付、催生"绕过评审直接合"。
+9. **作者不自审**：把调试代码、未过 CI 的改动丢给评审者收拾。
+
+## 7. 最低交付 checklist
+
+- [ ] PR 小而聚焦，一个 PR 一件事；大改动拆成可独立评审/回滚的小 PR。
+- [ ] 作者提交前自审、补测试、本地构建+lint+测试通过，CI 绿灯再请评。
+- [ ] PR 描述写清 why/影响范围/如何验证/如何回滚，并关联需求。
+- [ ] 评审有 SLA，及时响应，不阻塞队列。
+- [ ] 评审区分 blocking 与建议，意见具体、可执行、对事不对人。
+- [ ] 格式/lint/类型/测试/安全扫描走 CI 门禁，不占人工评审。
+- [ ] 主干受"必评审 + 必过 CI"保护；高风险路径加强评审。
+- [ ] 提交原子、历史干净，重构与功能改动分离。

package/development/01-standards/golang-complete.md

@@ -5,8 +5,8 @@ domain: development
 category: 01-standards
 difficulty: intermediate
 tags: [complete, development, golang, 并发模型, 性能优化, 接口设计, 标准库精选, 核心语法]
-quality_score: 70
-last_updated: 2026-06-15
+quality_score: 91
+last_updated: 2026-06-29
 ---
 # Go 语言完整工程指南
 

package/development/01-standards/python-design-patterns.md

@@ -5,8 +5,8 @@ domain: development
 category: 01-standards
 difficulty: intermediate
 tags: [agent, checklist, design, development, patterns, python, python特有模式, 创建型模式]
-quality_score: 70
-last_updated: 2026-06-15
+quality_score: 92
+last_updated: 2026-06-29
 ---
 # Python设计模式完整知识体系
 

package/development/01-standards/typescript-advanced-types.md

@@ -5,8 +5,8 @@ domain: development
 category: 01-standards
 difficulty: intermediate
 tags: [advanced, development, types, typescript, 与框架集成, 内置工具类型, 基础类型系统回顾, 完整指南]
-quality_score: 70
-last_updated: 2026-06-15
+quality_score: 91
+last_updated: 2026-06-29
 ---
 # TypeScript 高级类型系统完整指南
 

package/development/03-checklists/production-readiness-checklist.md

@@ -5,8 +5,8 @@ domain: development
 category: 03-checklists
 difficulty: intermediate
 tags: [checklist, development, production, readiness, 可靠性与容灾, 合规与审计, 基础设施与部署, 安全]
-quality_score: 70
-last_updated: 2026-06-15
+quality_score: 90
+last_updated: 2026-06-29
 ---
 # 生产就绪检查清单 (Production Readiness Checklist)
 
@@ -169,11 +169,11 @@ last_updated: 2026-06-15
 
 ---
 
-## 参考
+## 相关规范
 
-- Google SRE Book: Production Readiness Review — https://sre.google/sre-book/evolving-sre-engagement-model/
-- AWS Well-Architected Framework — https://aws.amazon.com/architecture/well-architected/
-- The Twelve-Factor App — https://12factor.net/
+- 服务级一次性 go/no-go 决策门：`operations/01-standards/production-readiness-review`
+- 每次发布的 pass/fail 门禁：`cicd/release-readiness-gate`
+- 配置与环境治理：`architecture/01-standards/configuration-and-environment-management`
 
 ---
 

package/development/09-maturity/quarterly-audit-template.md

@@ -1,16 +1,14 @@
 ---
 id: quarterly-audit-template
-title: quarterly-audit-template
+title: 季度审计模板
 domain: development
 category: 09-maturity
 difficulty: intermediate
-tags: [audit, development, quarterly, template, 季度审计模板]
+tags: [审计, audit, 季度审计, 模板, 成熟度, 治理, development]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## 季度审计模板
+# 季度审计模板
 
 ### 审计概览
 - 审计周期：

package/development/11-ui-excellence/ui-aesthetic-system.md

@@ -1,16 +1,14 @@
 ---
 id: ui-aesthetic-system
-title: ui-aesthetic-system
+title: UI美学系统总册
 domain: development
 category: 11-ui-excellence
 difficulty: intermediate
-tags: [aesthetic, development, system, ui美学系统总册]
+tags: [ui, 美学系统, aesthetic, 设计系统, 视觉规范, 前端, development]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## UI美学系统总册
+# UI美学系统总册
 
 ### 目标
 - 让界面同时满足“好看、好用、好做、可持续演进”。

package/development/13-implementation-assets/knowledge-gates-execution.md

@@ -1,16 +1,14 @@
 ---
 id: knowledge-gates-execution
-title: knowledge-gates-execution
+title: 知识门禁执行手册
 domain: development
 category: 13-implementation-assets
 difficulty: intermediate
-tags: [development, execution, gates, knowledge, 知识门禁执行手册]
+tags: [知识门禁, gates, 执行, 落地, 治理, development]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## 知识门禁执行手册
+# 知识门禁执行手册
 
 ### 目标
 - 把开发知识规则接入发布链路，避免知识与交付脱节。

package/development/api-contract-and-versioning-guide.md

@@ -1,16 +1,14 @@
 ---
 id: api-contract-and-versioning-guide
-title: api-contract-and-versioning-guide
+title: API 契约与版本治理指南
 domain: development
-category: api-contract-and-versioning-guide.md
+category: 01-standards
 difficulty: intermediate
-tags: [and, api, contract, development, guide, versioning, 契约与版本治理指南]
+tags: [api, 契约, contract, 版本治理, versioning, 兼容性, development]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## API 契约与版本治理指南
+# API 契约与版本治理指南
 
 ### 目标
 - 保证前后端与外部调用方在接口演进中保持稳定兼容。

package/development/api-governance-complete.md

@@ -1,16 +1,14 @@
 ---
 id: api-governance-complete
-title: api-governance-complete
+title: API治理完整知识库
 domain: development
-category: api-governance-complete.md
+category: 01-standards
 difficulty: intermediate
-tags: [api, api治理完整知识库, complete, development, governance]
+tags: [api, 治理, governance, 契约优先, 版本, 网关, development]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## API治理完整知识库
+# API治理完整知识库
 
 ### 1. 契约优先
 - 接口先定义契约，再进入实现。

package/development/backend-engineering-complete.md

@@ -1,16 +1,14 @@
 ---
 id: backend-engineering-complete
-title: backend-engineering-complete
+title: 后端工程完整知识库
 domain: development
-category: backend-engineering-complete.md
+category: 01-standards
 difficulty: intermediate
-tags: [backend, complete, development, engineering, 后端工程完整知识库]
+tags: [后端, backend, 分层架构, 服务设计, 工程规范, development]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## 后端工程完整知识库
+# 后端工程完整知识库
 
 ### 1. 分层架构
 - 路由层只做协议适配与参数接收。

package/development/code-review-quality-complete.md

@@ -1,43 +1,20 @@
 ---
 id: code-review-quality-complete
-title: code-review-quality-complete
+title: 代码评审与质量（已并入：代码评审标准与 PR 卫生规范）
 domain: development
-category: code-review-quality-complete.md
+category: development
 difficulty: intermediate
-tags: [code, complete, development, quality, review, 代码评审与质量完整知识库]
-quality_score: 70
-last_updated: 2026-06-15
+tags: [code-review, pr, quality, superseded, pointer, 代码评审, 已并入]
+quality_score: 60
+last_updated: 2026-06-29
 ---
-# 开发：Excellent（11964948@qq.com）
+# 代码评审与质量（本文档已并入）
 
-## 代码评审与质量完整知识库
+> 本文档原为占位草稿，内容已被更完整、可落地的标准取代，不再单独维护。
 
-### 1. 评审原则
-- 评审关注正确性、可维护性、安全性、性能、可观测性。
-- 评审意见必须具体、可执行、可验证。
-- 对高风险变更执行严格评审等级。
+**权威文档：[`development/01-standards/code-review-and-pr-hygiene.md`](01-standards/code-review-and-pr-hygiene.md)**
+——代码评审标准与 PR 卫生规范（商业级必读）。
 
-### 2. PR质量标准
-- PR必须聚焦单一主题。
-- 变更必须包含测试与文档更新。
-- 变更说明需覆盖影响范围与回滚策略。
+它覆盖并超出了本文档原有的全部内容：评审优先级（正确性/安全/测试/可维护性/契约/可观测性/风格）、作者侧把 PR 准备到"好评审"、评审者侧有效且尊重、PR/提交卫生、自动化兜底、反模式与最低交付 checklist。
 
-### 3. 安全评审清单
-- 是否存在越权风险与输入校验缺失。
-- 是否可能泄露敏感信息。
-- 是否存在危险默认配置。
-
-### 4. 性能评审清单
-- 是否引入额外高复杂度计算。
-- 是否增加高频链路IO与序列化开销。
-- 是否影响缓存命中与数据库负载。
-
-### 5. 可运维性评审清单
-- 是否补充关键日志与指标。
-- 是否可在异常时快速定位问题。
-- 是否可安全回滚到上一个稳定版本。
-
-### 6. 评审闭环
-- 阻断级问题必须修复后才可合并。
-- 复发问题应沉淀到评审清单与模板。
-- 评审质量按缺陷逃逸率持续优化。
+配套清单见 [`development/03-checklists/pr-checklist.md`](03-checklists/pr-checklist.md)。

package/development/concurrency-reliability-complete.md

@@ -1,16 +1,14 @@
 ---
 id: concurrency-reliability-complete
-title: concurrency-reliability-complete
+title: 并发与稳定性完整知识库
 domain: development
-category: concurrency-reliability-complete.md
+category: 01-standards
 difficulty: intermediate
-tags: [complete, concurrency, development, reliability, 并发与稳定性完整知识库]
+tags: [并发, concurrency, 稳定性, reliability, 线程, 锁, development]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## 并发与稳定性完整知识库
+# 并发与稳定性完整知识库
 
 ### 1. 并发模型
 - 共享资源必须定义并发访问策略。

package/development/database-engineering-complete.md

@@ -1,16 +1,14 @@
 ---
 id: database-engineering-complete
-title: database-engineering-complete
+title: 数据库工程完整知识库
 domain: development
-category: database-engineering-complete.md
+category: 01-standards
 difficulty: intermediate
-tags: [complete, database, development, engineering, 数据库工程完整知识库]
+tags: [数据库, database, 数据模型, 索引, 事务, 性能, development]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## 数据库工程完整知识库
+# 数据库工程完整知识库
 
 ### 1. 数据模型设计
 - 核心表必须定义主键、唯一约束、审计字段。

package/development/engineering-effectiveness-complete.md

@@ -1,16 +1,14 @@
 ---
 id: engineering-effectiveness-complete
-title: engineering-effectiveness-complete
+title: 工程效能完整知识库
 domain: development
-category: engineering-effectiveness-complete.md
+category: 01-standards
 difficulty: intermediate
-tags: [complete, development, effectiveness, engineering, 工程效能完整知识库]
+tags: [工程效能, effectiveness, 研发效率, 流程标准化, devex, development]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## 工程效能完整知识库
+# 工程效能完整知识库
 
 ### 1. 流程标准化
 - 从需求到发布定义统一流程节点。

package/development/engineering-standards-deep-dive.md

@@ -1,16 +1,14 @@
 ---
 id: engineering-standards-deep-dive
-title: engineering-standards-deep-dive
+title: 开发环节深度知识库
 domain: development
-category: engineering-standards-deep-dive.md
+category: 01-standards
 difficulty: intermediate
-tags: [deep, development, dive, engineering, standards, 开发环节深度知识库]
+tags: [工程规范, engineering-standards, 开发规范, 分层, 编码标准, development]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## 开发环节深度知识库
+# 开发环节深度知识库
 
 ### 目标
 - 让实现质量稳定、可回归、可协作，避免“个人风格驱动”。

package/development/frontend-engineering-complete.md

@@ -1,16 +1,14 @@
 ---
 id: frontend-engineering-complete
-title: frontend-engineering-complete
+title: 前端工程完整知识库
 domain: development
-category: frontend-engineering-complete.md
+category: 01-standards
 difficulty: intermediate
-tags: [complete, development, engineering, frontend, 前端工程完整知识库]
+tags: [前端, frontend, 组件化, 模块边界, 工程规范, development]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## 前端工程完整知识库
+# 前端工程完整知识库
 
 ### 1. 分层与模块边界
 - 页面层负责编排，组件层负责复用，服务层负责数据访问。

package/development/performance-capacity-complete.md

@@ -1,16 +1,14 @@
 ---
 id: performance-capacity-complete
-title: performance-capacity-complete
+title: 性能与容量完整知识库
 domain: development
-category: performance-capacity-complete.md
+category: 01-standards
 difficulty: intermediate
-tags: [capacity, complete, development, performance, 性能与容量完整知识库]
+tags: [性能, performance, 容量, capacity, 性能预算, 压测, development]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## 性能与容量完整知识库
+# 性能与容量完整知识库
 
 ### 1. 性能预算
 - 定义核心接口 P95、P99、吞吐量目标。

package/development/refactor-migration-complete.md

@@ -1,16 +1,14 @@
 ---
 id: refactor-migration-complete
-title: refactor-migration-complete
+title: 重构与迁移完整知识库
 domain: development
-category: refactor-migration-complete.md
+category: 01-standards
 difficulty: intermediate
-tags: [complete, development, migration, refactor, 重构与迁移完整知识库]
+tags: [重构, refactor, 迁移, migration, 技术债, development]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## 重构与迁移完整知识库
+# 重构与迁移完整知识库
 
 ### 1. 重构触发条件
 - 缺陷密度持续偏高。

package/development/refactoring-and-techdebt-playbook.md

@@ -1,16 +1,14 @@
 ---
 id: refactoring-and-techdebt-playbook
-title: refactoring-and-techdebt-playbook
+title: 重构与技术债治理手册
 domain: development
-category: refactoring-and-techdebt-playbook.md
+category: 02-playbooks
 difficulty: intermediate
-tags: [and, development, playbook, refactoring, techdebt, 重构与技术债治理手册]
+tags: [重构, refactoring, 技术债, tech-debt, 治理, development]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## 重构与技术债治理手册
+# 重构与技术债治理手册
 
 ### 目标
 - 在不影响业务连续性的前提下，持续降低系统复杂度与维护成本。

package/development/security-in-development-complete.md

@@ -1,16 +1,14 @@
 ---
 id: security-in-development-complete
-title: security-in-development-complete
+title: 开发安全完整知识库
 domain: development
-category: security-in-development-complete.md
+category: 01-standards
 difficulty: intermediate
-tags: [complete, development, security, 开发安全完整知识库]
+tags: [安全, security, 安全左移, 开发安全, 漏洞, development]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## 开发安全完整知识库
+# 开发安全完整知识库
 
 ### 1. 安全左移
 - 在需求与设计阶段完成威胁建模。

package/devops/01-standards/docker-complete.md

@@ -5,8 +5,8 @@ domain: devops
 category: 01-standards
 difficulty: intermediate
 tags: [complete, compose, devops, docker, dockerfile, 实战, 最佳实践, 核心概念]
-quality_score: 70
-last_updated: 2026-06-15
+quality_score: 90
+last_updated: 2026-06-29
 ---
 # Docker 完整指南
 

package/devops/01-standards/terraform-complete.md

@@ -5,8 +5,8 @@ domain: devops
 category: 01-standards
 difficulty: intermediate
 tags: [complete, devops, terraform, 实战配置, 工作流, 核心概念, 概述, 模块设计]
-quality_score: 70
-last_updated: 2026-06-15
+quality_score: 90
+last_updated: 2026-06-29
 ---
 # Terraform 完整指南
 
@@ -1491,7 +1491,7 @@ jobs:
         uses: actions/github-script@v7
         with:
           script: |
-            const output = `#### Terraform Plan 📋
+            const output = `#### Terraform Plan
             \`\`\`
             ${{ steps.plan.outputs.stdout }}
             \`\`\`