@umacloud/knowledge 1.0.16 → 1.0.18

package/00-governance/governance-capabilities.md

@@ -2,7 +2,7 @@
 id: governance-capabilities
 title: UmaDev 治理能力全景图
 domain: 00-governance
-category: governance-capabilities.md
+category: 00-governance
 difficulty: intermediate
 tags: [00-governance, capabilities, engine, governance, knowledge, rule, tracker, validation]
 quality_score: 70

package/00-governance/knowledge-map.md

@@ -1,16 +1,14 @@
 ---
 id: knowledge-map
-title: knowledge-map
+title: 知识库地图（全环节）
 domain: 00-governance
-category: knowledge-map.md
+category: 00-governance
 difficulty: intermediate
-tags: [00-governance, knowledge, map]
+tags: [知识库, knowledge-base, 知识地图, index, 全环节, 治理, governance, 检索]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# knowledge-map
-
-## 知识库地图（全环节）
+# 知识库地图（全环节）
 
 ### 1. 目标
 - 建立可持续演进的项目知识系统，减少“只靠人记忆”带来的交付风险。

package/ai/01-standards/app-runtime-model-configurable.md

@@ -0,0 +1,76 @@
+---
+id: app-runtime-model-configurable
+title: 应用运行时模型可配置（别硬编码开发底座的厂商）
+domain: ai
+category: 01-standards
+difficulty: intermediate
+tags: [llm, 运行时模型, 可配置, provider-abstraction, openai-compatible, dashscope, qwen, 大模型, 多厂商, env, 配置, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+
+# 应用运行时模型可配置（别硬编码开发底座的厂商）
+
+> 常见踩坑：用某个 AI 编码工具开发一个“会在运行时调用大模型”的应用时，生成的后端把运行时的 LLM 直接写死成开发工具自己用的那家（例如 Anthropic/Claude + `ANTHROPIC_API_KEY`）。用户想让交付的应用跑通义千问 / OpenAI / 本地模型，还得手工改后端。**开发用的工具底座，和应用运行时调用的模型，是两件完全不同的事，绝不能混为一谈。**
+
+## 1. 核心原则
+
+- **两层模型分离**：「开发期借用的大脑（写代码的工具）」≠「应用运行时调用的模型」。后者是业务选型，由需求/用户决定，不是由你用什么工具写代码决定。
+- **运行时模型是配置项，不是常量**：模型 id、base URL、API Key 的环境变量名，三者都必须来自配置（环境变量 / 配置文件），代码里不出现写死的厂商端点或密钥。
+- **默认值跟随需求**：需求里点名了运行时模型/厂商（如“运行时用千问 Max”“用 DashScope”“用 OpenAI”），就把默认配置指向它；没点名时，生成一个清晰可替换的 provider 占位层，并在交付物里说明“运行时模型可配置、怎么切换”。
+- **绝不静默套用开发底座的厂商**：不要因为写代码时用的是某家工具，就把应用运行时也默认写成那家。
+
+## 2. Provider 抽象层（最小骨架）
+
+把对模型的调用收敛到一个薄抽象层，业务代码只依赖这个层，不直接耦合任意一家 SDK 的端点。
+
+- 三元组来自配置：`model`（模型 id）、`base_url`（接入地址）、`api_key`（从指定环境变量读取）。
+- 优先用 **OpenAI 兼容协议**的客户端：同一套 `base_url + api_key + model` 即可覆盖 OpenAI、DashScope/通义千问、DeepSeek、智谱 GLM、Moonshot/Kimi、本地 Ollama 等大多数主流厂商——换厂商是改配置，不是改代码。
+- 不兼容 OpenAI 协议的厂商（个别国产/自研网关），在抽象层内部各写一个 adapter，对外暴露统一接口。
+
+```bash
+# .env.example —— 运行时模型可配置（默认值跟随需求；未点名则留可替换占位）
+LLM_PROVIDER=openai-compatible
+LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1   # 例：通义千问 DashScope 兼容端点
+LLM_MODEL=qwen-max                                               # 切换模型只改这一行
+LLM_API_KEY_ENV=DASHSCOPE_API_KEY                                # 真正的密钥放在被引用的环境变量里
+DASHSCOPE_API_KEY=                                               # 由部署方注入，不进版本库
+```
+
+```ts
+// llm.ts —— 业务只调用这一层，端点/密钥/模型全部来自配置
+import OpenAI from "openai"; // OpenAI 兼容客户端可对接多数厂商
+
+const apiKeyEnv = process.env.LLM_API_KEY_ENV ?? "OPENAI_API_KEY";
+const client = new OpenAI({
+  baseURL: process.env.LLM_BASE_URL,          // 配置驱动，可指向千问/OpenAI/本地
+  apiKey: process.env[apiKeyEnv],             // 从“被指定的环境变量名”读取真实密钥
+});
+
+export async function chat(messages: { role: string; content: string }[]) {
+  return client.chat.completions.create({
+    model: process.env.LLM_MODEL ?? "gpt-4o-mini", // 默认值跟随需求；切换只改配置
+    messages,
+  });
+}
+```
+
+## 3. 落地清单（Checklist）
+
+- [ ] 运行时 `model` / `base_url` / `api_key` 全部来自环境变量或配置文件，源码里没有写死的厂商端点或密钥。
+- [ ] 需求点名了运行时厂商/模型 → 默认配置已指向它；未点名 → 留下清晰可替换的 provider 占位，且在 README/`.env.example` 写明如何切换。
+- [ ] 对接走 provider 抽象层，业务代码不直接依赖某一家 SDK 的硬编码端点。
+- [ ] 优先 OpenAI 兼容协议；非兼容厂商在抽象层内做 adapter，对外接口统一。
+- [ ] 密钥只从环境变量注入，`.env` 不进版本库，仓库里只放 `.env.example` 占位。
+- [ ] 交付物（README / 配置说明）明确写出“运行时模型可配置”，并给出切换到千问/OpenAI/本地模型的具体步骤。
+- [ ] 提供超时、重试、错误兜底；切换厂商不需要改业务代码，只改配置即可生效。
+- [ ] 不把开发所用工具底座的厂商（如 Anthropic/Claude）当成应用运行时的默认值。
+
+## 4. 反模式（出现即不合格）
+
+- 把应用运行时的 LLM 写死成开发工具自己用的那家（典型：默认 `ANTHROPIC_API_KEY` + Claude 端点），无视用户在需求里指定的运行时模型。
+- 厂商端点 / 模型 id / 密钥硬编码在业务代码里，换模型要改源码、重新构建。
+- 用户明确说“运行时用千问 / DeepSeek / 本地模型”，生成的代码却仍调另一家。
+- 只支持单一厂商、没有 provider 抽象层，后续接第二家要大改。
+- 把真实密钥写进源码或提交进版本库；没有 `.env.example` 占位与切换说明。
+- 没在交付物里说明运行时模型可配置，用户只能逆向源码才知道怎么换。

package/ai/agent-evaluation-benchmark.md

@@ -1,16 +1,14 @@
 ---
 id: agent-evaluation-benchmark
-title: agent-evaluation-benchmark
+title: Agent 评测与基准体系
 domain: ai
-category: agent-evaluation-benchmark.md
+category: 01-standards
 difficulty: intermediate
-tags: [agent, ai, benchmark, evaluation, 评测与基准体系]
+tags: [agent, 评测, benchmark, evaluation, 基准集, 发布门禁, 回归评测, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# agent-evaluation-benchmark
-
-## Agent 评测与基准体系
+# Agent 评测与基准体系
 
 ### 目标
 - 让 Agent 能力可量化、可回归、可持续优化。

package/ai/ai-agent-memory-context-management.md

@@ -1,16 +1,14 @@
 ---
 id: ai-agent-memory-context-management
-title: ai-agent-memory-context-management
+title: AI Agent上下文与记忆管理
 domain: ai
-category: ai-agent-memory-context-management.md
+category: 01-standards
 difficulty: intermediate
-tags: [agent, agent上下文与记忆管理, ai, context, management, memory]
+tags: [agent, 记忆管理, memory, context, 上下文压缩, 多轮对话, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# ai-agent-memory-context-management
-
-## AI Agent上下文与记忆管理
+# AI Agent上下文与记忆管理
 
 ### 目标
 - 在成本可控前提下提升多轮任务连续性与决策一致性。

package/ai/ai-cost-capacity-optimization-playbook.md

@@ -1,16 +1,14 @@
 ---
 id: ai-cost-capacity-optimization-playbook
-title: ai-cost-capacity-optimization-playbook
+title: AI成本与容量优化手册
 domain: ai
-category: ai-cost-capacity-optimization-playbook.md
+category: 02-playbooks
 difficulty: intermediate
-tags: [ai, ai成本与容量优化手册, capacity, cost, optimization, playbook]
+tags: [成本优化, cost, capacity, 容量规划, 模型路由, prompt压缩, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# ai-cost-capacity-optimization-playbook
-
-## AI成本与容量优化手册
+# AI成本与容量优化手册
 
 ### 目标
 - 在保证业务效果的前提下，实现可持续的AI成本与容量治理。

package/ai/ai-data-security-and-compliance-playbook.md

@@ -1,16 +1,14 @@
 ---
 id: ai-data-security-and-compliance-playbook
-title: ai-data-security-and-compliance-playbook
+title: AI数据安全与合规作战手册
 domain: ai
-category: ai-data-security-and-compliance-playbook.md
+category: 02-playbooks
 difficulty: intermediate
-tags: [ai, ai数据安全与合规作战手册, and, compliance, data, playbook, security]
+tags: [数据安全, compliance, 合规, 脱敏, 审计日志, 数据治理, ai, security]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# ai-data-security-and-compliance-playbook
-
-## AI数据安全与合规作战手册
+# AI数据安全与合规作战手册
 
 ### 目标
 - 确保AI系统在数据采集、处理、存储、传输全链路满足安全与合规要求。

package/ai/ai-domain-index-and-checklist.md

@@ -1,16 +1,14 @@
 ---
 id: ai-domain-index-and-checklist
-title: ai-domain-index-and-checklist
+title: AI领域索引与执行清单
 domain: ai
-category: ai-domain-index-and-checklist.md
+category: 03-checklists
 difficulty: intermediate
-tags: [ai, ai领域索引与执行清单, and, checklist, domain, index]
+tags: [索引, checklist, 执行清单, 上线门禁, ai, llm, rag, 核查清单]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# ai-domain-index-and-checklist
-
-## AI领域索引与执行清单
+# AI领域索引与执行清单
 
 ### 目标
 - 为AI需求、方案、上线、运行提供统一入口和核查清单。

package/ai/ai-governance-maturity-model.md

@@ -1,16 +1,14 @@
 ---
 id: ai-governance-maturity-model
-title: ai-governance-maturity-model
+title: AI治理成熟度模型
 domain: ai
-category: ai-governance-maturity-model.md
+category: 01-standards
 difficulty: intermediate
-tags: [ai, ai治理成熟度模型, governance, maturity, model]
+tags: [治理, 成熟度模型, maturity, governance, 能力评估, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# ai-governance-maturity-model
-
-## AI治理成熟度模型
+# AI治理成熟度模型
 
 ### 目标
 - 用统一量表评估AI研发和运营能力，指导分阶段治理提升。

package/ai/ai-model-selection-and-routing-strategy.md

@@ -1,16 +1,14 @@
 ---
 id: ai-model-selection-and-routing-strategy
-title: ai-model-selection-and-routing-strategy
+title: AI模型选型与路由策略
 domain: ai
-category: ai-model-selection-and-routing-strategy.md
+category: 02-playbooks
 difficulty: intermediate
-tags: [ai, ai模型选型与路由策略, and, model, routing, selection, strategy]
+tags: [模型选型, 路由, routing, model-selection, 多模型, 灰度, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# ai-model-selection-and-routing-strategy
-
-## AI模型选型与路由策略
+# AI模型选型与路由策略
 
 ### 目标
 - 在准确率、时延、成本和稳定性之间取得可量化最优平衡。

package/ai/ai-observability-and-oncall-runbook.md

@@ -1,16 +1,14 @@
 ---
 id: ai-observability-and-oncall-runbook
-title: ai-observability-and-oncall-runbook
+title: AI可观测性与值班Runbook
 domain: ai
-category: ai-observability-and-oncall-runbook.md
+category: 02-playbooks
 difficulty: intermediate
-tags: [ai, ai可观测性与值班runbook, and, observability, oncall, runbook]
+tags: [可观测性, observability, oncall, runbook, 值班, 告警, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# ai-observability-and-oncall-runbook
-
-## AI可观测性与值班Runbook
+# AI可观测性与值班Runbook
 
 ### 目标
 - 建立AI系统运行态监控、告警、处置、复盘的标准流程。

package/ai/ai-rag-engineering-playbook.md

@@ -1,16 +1,14 @@
 ---
 id: ai-rag-engineering-playbook
-title: ai-rag-engineering-playbook
+title: AI RAG工程作战手册
 domain: ai
-category: ai-rag-engineering-playbook.md
+category: 02-playbooks
 difficulty: intermediate
-tags: [ai, engineering, playbook, rag, rag工程作战手册]
+tags: [rag, 检索增强, retrieval, 召回, 重排序, 向量检索, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# ai-rag-engineering-playbook
-
-## AI RAG工程作战手册
+# AI RAG工程作战手册
 
 ### 目标
 - 构建高召回、高精度、低幻觉的检索增强生成系统。

package/ai/ai-red-team-and-safety-evaluation.md

@@ -1,16 +1,14 @@
 ---
 id: ai-red-team-and-safety-evaluation
-title: ai-red-team-and-safety-evaluation
+title: AI红队测试与安全评估
 domain: ai
-category: ai-red-team-and-safety-evaluation.md
+category: 01-standards
 difficulty: intermediate
-tags: [ai, ai红队测试与安全评估, and, evaluation, red, safety, team]
+tags: [红队, red-team, 安全评估, safety, 提示注入, 越权, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# ai-red-team-and-safety-evaluation
-
-## AI红队测试与安全评估
+# AI红队测试与安全评估
 
 ### 目标
 - 在上线前识别提示注入、越权调用、敏感泄漏、内容安全等高风险问题。

package/ai/ai-release-readiness-and-rollback-gate.md

@@ -1,16 +1,14 @@
 ---
 id: ai-release-readiness-and-rollback-gate
-title: ai-release-readiness-and-rollback-gate
+title: AI发布就绪与回滚门禁
 domain: ai
-category: ai-release-readiness-and-rollback-gate.md
+category: 02-playbooks
 difficulty: intermediate
-tags: [ai, ai发布就绪与回滚门禁, and, gate, readiness, release, rollback]
+tags: [发布门禁, 回滚, rollback, release-gate, 灰度, 就绪评估, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# ai-release-readiness-and-rollback-gate
-
-## AI发布就绪与回滚门禁
+# AI发布就绪与回滚门禁
 
 ### 目标
 - 将AI能力发布纳入可量化门禁，确保上线可控与可回退。

package/ai/llm-agent-engineering-deep-dive.md

@@ -1,16 +1,14 @@
 ---
 id: llm-agent-engineering-deep-dive
-title: llm-agent-engineering-deep-dive
+title: LLM 与 Agent 工程深度知识库
 domain: ai
-category: llm-agent-engineering-deep-dive.md
+category: 01-standards
 difficulty: intermediate
-tags: [agent, ai, deep, dive, engineering, llm, 工程深度知识库]
+tags: [llm, agent, 工程化, prompt, 工具调用, 编排, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# llm-agent-engineering-deep-dive
-
-## LLM 与 Agent 工程深度知识库
+# LLM 与 Agent 工程深度知识库
 
 ### 目标
 - 建立可控、可测、可审计的 AI 研发与运行标准。

package/ai/prompt-and-tool-guardrails.md

@@ -1,16 +1,14 @@
 ---
 id: prompt-and-tool-guardrails
-title: prompt-and-tool-guardrails
+title: Prompt 与工具调用护栏规范
 domain: ai
-category: prompt-and-tool-guardrails.md
+category: 01-standards
 difficulty: intermediate
-tags: [ai, and, guardrails, prompt, tool, 与工具调用护栏规范]
+tags: [prompt, 护栏, guardrails, 工具调用, 安全边界, 结构化输出, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# prompt-and-tool-guardrails
-
-## Prompt 与工具调用护栏规范
+# Prompt 与工具调用护栏规范
 
 ### 目标
 - 防止模型越权操作、错误调用工具或输出不可信内容。

package/architecture/02-playbooks/migration-playbook.md

@@ -11,10 +11,6 @@ quality_score: 70
 ---
 
 # 系统迁移作战手册
-# 功能：系统迁移全流程作战手册
-# 作用：指导团队完成系统迁移的评估、规划、执行、验证与切换
-# 创建时间：2026-03-28
-# 最后修改：2026-03-28
 
 ## 目标
 

package/architecture/02-playbooks/system-design-playbook.md

@@ -11,10 +11,6 @@ quality_score: 70
 ---
 
 # 系统设计作战手册
-# 功能：系统设计全流程作战手册
-# 作用：指导架构师完成从需求分析到详细设计的系统设计全过程
-# 创建时间：2026-03-28
-# 最后修改：2026-03-28
 
 ## 目标
 

package/architecture/adr-template-and-examples.md

@@ -1,16 +1,14 @@
 ---
 id: adr-template-and-examples
-title: adr-template-and-examples
+title: ADR 模板与示例规范
 domain: architecture
-category: adr-template-and-examples.md
+category: 01-standards
 difficulty: intermediate
-tags: [adr, and, architecture, examples, template, 模板与示例规范]
+tags: [adr, 架构决策, decision-record, 模板, 技术选型, architecture]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# adr-template-and-examples
-
-## ADR 模板与示例规范
+# ADR 模板与示例规范
 
 ### 目标
 - 对关键架构决策形成可追溯记录，降低后续误解与返工。

package/architecture/api-gateway-deep-dive.md

@@ -2,7 +2,7 @@
 id: api-gateway-deep-dive
 title: API网关深度指南
 domain: architecture
-category: api-gateway-deep-dive.md
+category: 01-standards
 difficulty: intermediate
 tags: [api, architecture, deep, dive, gateway, 主流api网关对比, 安全防护, 性能优化]
 quality_score: 70

package/architecture/distributed-transactions.md

@@ -2,7 +2,7 @@
 id: distributed-transactions
 title: 分布式事务处理完全指南
 domain: architecture
-category: distributed-transactions.md
+category: 01-standards
 difficulty: intermediate
 tags: [architecture, distributed, transactions, 分布式事务框架, 分布式事务模式, 参考资源, 常见问题, 最佳实践]
 quality_score: 70

package/architecture/microservices-complete.md

@@ -2,7 +2,7 @@
 id: microservices-complete
 title: 微服务架构完整指南
 domain: architecture
-category: microservices-complete.md
+category: 01-standards
 difficulty: intermediate
 tags: [architecture, complete, microservices, 可观测性, 数据管理, 服务发现, 服务拆分策略, 核心原则]
 quality_score: 70

package/architecture/service-governance.md

@@ -2,7 +2,7 @@
 id: service-governance
 title: 服务治理完全指南
 domain: architecture
-category: service-governance.md
+category: 01-standards
 difficulty: intermediate
 tags: [architecture, governance, service, 服务注册与发现, 核心能力, 概述, 熔断与降级, 负载均衡]
 quality_score: 70

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

@@ -1,16 +1,14 @@
 ---
 id: system-architecture-deep-dive
-title: system-architecture-deep-dive
+title: 架构环节深度知识库
 domain: architecture
-category: system-architecture-deep-dive.md
+category: 01-standards
 difficulty: intermediate
-tags: [architecture, deep, dive, system, 架构环节深度知识库]
+tags: [架构, system-architecture, 架构设计, 拆分, 演进, 技术选型, architecture]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# system-architecture-deep-dive
-
-## 架构环节深度知识库
+# 架构环节深度知识库
 
 ### 目标
 - 在性能、稳定性、可维护性与演进成本之间建立可持续平衡。

package/backend/01-standards/cjk-in-exports-and-documents.md

@@ -0,0 +1,107 @@
+---
+id: cjk-in-exports-and-documents
+title: 中文/CJK 与 i18n 在数据导出与生成文档中的正确性标准（商业级必读）
+domain: backend
+category: 01-standards
+difficulty: intermediate
+tags: [中文导出, cjk, i18n, 乱码, mojibake, csv, bom, excel, xlsx, pdf, 字体嵌入, content-disposition, 文件名, rfc5987, utf-8, gbk, 编码, 导出, 报表, 下载, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+
+# 中文/CJK 与 i18n 在数据导出与生成文档中的正确性标准（商业级必读）
+
+> 网页能跑通、界面也没问题，但一点「下载表格」导出的中文就变成 `乱码`/`口字框`/`?`——这是 demo 与可交付之间最典型的一道坎。导出文件（CSV/Excel/PDF）和生成文档脱离了浏览器的 UTF-8 渲染环境，进入 Excel/WPS/Numbers/PDF 阅读器这些**自己猜编码、自己挑字体**的程序，任何一个环节编码或字体不对，中文（以及一切非 ASCII：日文、韩文、带重音的拉丁文、西里尔文、阿拉伯文、表情符号）就坏掉。本标准把「中文导出不乱码」当作硬性交付项，逐格式给出确定性做法。
+
+## 1. CSV：写 UTF-8 必须带 BOM（否则 Excel/WPS 必乱码）
+
+- **Excel / WPS 打开 CSV 默认按系统 ANSI 代码页解析**（中文 Windows = GBK/GB18030），**不是** UTF-8。所以一个不带 BOM 的 UTF-8 CSV 在 Excel 里打开必然乱码。
+- **确定性修法**：在文件最前面写 UTF-8 BOM（字节 `EF BB BF`，字符 `U+FEFF`）。Excel/WPS 见到 BOM 就会按 UTF-8 解析，中文正常。
+  - 前端用 JS 生成下载时同理：`new Blob(["" + csv], { type: "text/csv;charset=utf-8" })`，把 `` 拼在最前。
+  - 后端写文件/响应体时把 `EF BB BF` 三字节写在最前，再写正文。
+- **BOM 的副作用**：BOM 会让朴素解析器把表头第一格读成带前导 `` 的脏字符串。所以：**给人/给 Excel 看的导出加 BOM；给机器/管道消费的 CSV 不加 BOM**（或读取端显式 strip BOM）。两类用途分清。
+- **分隔符**：RFC 4180 用逗号，但部分地区的 Excel（德/法等）按系统「列表分隔符」期望分号 `;`。需兼容时可在首行加 `sep=,`（Excel 私有提示）或按目标 locale 选分隔符。中文环境用逗号即可。
+- **引用/转义**：字段含分隔符、双引号或换行时，整字段用双引号包裹，内部双引号写成两个（`""`）。
+- **换行**：用 `CRLF`（`\r\n`）最稳；Python 写 csv 必须 `open(..., newline="")` 否则出现空行。
+- **长数字 / 前导零（手机号、身份证、订单号）**：Excel 会把长数字转科学计数法、抹掉前导零。修法优先**改用真正的 xlsx 并把该列设为文本格式**；CSV 内的兜底是把值写成 `="00123"`（强制文本），但见下一条注意注入。
+- **公式注入（CSV Injection，必须防）**：单元格以 `=` `+` `-` `@`（及 Tab/回车）开头时，Excel/WPS 打开会当公式执行，可被用于数据外泄甚至命令执行。**导出前对以这些字符开头的单元格加前缀单引号 `'` 或空格做无害化**；用 `="..."` 兜底前导零时要同时做注入清洗。
+
+## 2. Excel（.xlsx）：内部恒为 UTF-8，但单元格格式与字体仍要管
+
+- xlsx 本质是 zip 包里的 XML，内部**恒为 UTF-8**——内容不会乱码。**当消费方是 Excel/WPS 时，优先导出 xlsx 而不是 CSV**，直接绕开 CSV 的编码陷阱。
+- **数值/日期 locale**：日期写成真正的日期值 + 数字格式（number format），不要写本地化字符串，让消费端按其 locale 渲染；金额用数值 + 货币格式。超过 15 位的整数会丢精度，ID/手机号列设为**文本格式**。
+- **写库选成熟实现**：Python `openpyxl`/`xlsxwriter`、Node `exceljs`、Java Apache POI、Go `excelize`、.NET ClosedXML；不要手拼 XML/SpreadsheetML。
+- **单元格 CJK 字体**：内容编码无碍，但若**显式设置**单元格字体，要选目标机器上存在且含中文字形的字体（微软雅黑/宋体/思源黑体/Noto Sans CJK），否则显式指定一个无中文字形的西文字体反而显示成框。自动列宽要考虑 CJK 是双倍宽。
+
+## 3. PDF：默认 base-14 字体没有中文字形，必须嵌入 CJK 字体
+
+- PDF 的 14 个标准内置字体（Helvetica/Times/Courier/Symbol/ZapfDingbats）**只覆盖拉丁字符，没有任何 CJK 字形**。用它们画中文 → 缺字、口字框（tofu）、或整段空白。
+- **确定性修法**：**嵌入一款含 CJK 字形的字体并先注册再绘制**。选 Noto Sans CJK / 思源黑体（Source Han Sans）这类覆盖全的字体，或系统宋体/黑体。
+  - ReportLab：`pdfmetrics.registerFont(TTFont("NotoSansCJK", "...otf"))` 后再 `setFont`；或用内置 CID 字体（`STSong-Light` 等）。
+  - HTML→PDF（wkhtmltopdf / Puppeteer/headless Chrome）：**容器里必须装中文字体包**（如 `fonts-noto-cjk`），CSS `font-family` 指到它；瘦镜像（alpine/slim）默认无中文字体是「容器里中文全是框」的头号原因。
+  - jsPDF `addFont`；iText/PDFBox `PDFont` 且 `embedded=true`；Go `gofpdf` 用 `AddUTF8Font`。
+- **子集化（subsetting）**：只嵌入用到的字形。整套 CJK 字体 10–20MB，子集化后只剩几 KB。多数库默认子集化，要**验证**最终 PDF 体积没把整库塞进去。
+- **CJK 断行**：中文没有空格，渲染引擎要在汉字之间断行；只按空格断词的西文换行逻辑遇到长串中文会溢出版心。HTML→PDF 用 `word-break`/`line-break` 控制，或依赖引擎的 CJK 断行。
+- **粗体/斜体**：CJK 字体常无真正粗体字形，需嵌入对应字重，否则得到伪粗体。
+- **RTL（阿拉伯/希伯来）**：需要支持塑形（shaping）与从右到左排版的引擎 + 含该字形的字体，不能只换字体。
+
+## 4. HTML / 网页表格下载：charset、文件名编码、MIME 一个都不能错
+
+- **声明 charset**：导出响应头必须带 `Content-Type: text/csv; charset=utf-8`（HTML 页面再加 `<meta charset="utf-8">`）。不声明 charset，浏览器/Excel 只能猜，结果就是乱码。
+- **中文文件名必须用 RFC 5987/8187 扩展编码**：传统 `Content-Disposition: attachment; filename="发票.csv"` 不允许非 ASCII，会被乱码或截断。正确写法**同时给 ASCII 兜底和 `filename*`**：
+  ```
+  Content-Disposition: attachment; filename="invoice.csv"; filename*=UTF-8''%E5%8F%91%E7%A5%A8.csv
+  ```
+  `filename*` 的值是 `UTF-8''` + 对 UTF-8 字节做百分号编码后的文件名。
+- **MIME 类型要对**：CSV `text/csv`；xlsx `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`；PDF `application/pdf`。MIME 写错（如 xlsx 标成 `text/plain`）会让浏览器误处理或加错扩展名。
+- **前端 Blob 下载**：CSV 内容前拼 ``，`type` 带 `charset=utf-8`，用 `URL.createObjectURL` + 带 `download` 属性的 `<a>`，下载文件名做好编码。
+
+## 5. 下载链路端到端：每一步都可能毁掉中文
+
+1. **生成（内存里建字符串）**：源数据本身若已是乱码（GBK 库被当 latin1 读出来），出生即损坏。先确保 DB/连接 charset 是 `utf8mb4` 且读取按真实编码解码。
+2. **编码成字节**：**显式编码为 UTF-8**，别依赖平台默认（Windows 默认 cp1252/GBK）。Java `getBytes(StandardCharsets.UTF_8)`；Python 写文件 `encoding="utf-8"`（csv 还要 `newline=""`）。
+3. **声明 charset**：响应头 charset 必须与实际字节一致。
+4. **传输**：别让代理/网关/gzip/转码层二次编码；文件名不要被中间件二次百分号编码（双重编码）。
+5. **浏览器**：按 `Content-Disposition` 命名、按 charset 处理；CSV 只是落字节。
+6. **目标 App（Excel/WPS/Numbers）**：**Excel(Windows) 是最薄弱一环**——读 UTF-8 CSV 必须靠 BOM；Numbers/LibreOffice 多能自动探测；WPS 同 Excel。**改用 xlsx 可整体绕开这一步的不确定性。**
+
+## 6. 常见乱码根因与确定性修法对照
+
+- **编码不匹配**（声明 utf-8 实为 gbk，或反之）→ 全链路统一 UTF-8，响应头 charset 与字节一致。
+- **CSV 缺 BOM**，Excel 按系统 GBK 解析 → 加 UTF-8 BOM，或直接改 xlsx。
+- **PDF 缺字体嵌入** → 嵌入并注册 CJK 字体；容器装中文字体包。
+- **双重编码**（已 UTF-8 又被当 latin1 再编一次，典型形如 `中文` 这类乱码）→ 定位多余的那一次 decode/encode 去掉；全链路只做一次 `decode → 处理 → encode`。
+- **GBK vs UTF-8 历史数据**（旧库/旧文件是 GBK，新链路是 UTF-8）→ 读取时**按真实编码 GBK 解码再转 UTF-8**，不要直接当 UTF-8 读。
+- **中文文件名乱码/被截断** → 用 RFC 5987 `filename*=UTF-8''...`。
+- **口字框 / `?`**（字节其实对，是缺字形）→ 不是编码问题，换一款含该字形的字体。
+
+## 7. 推广到 i18n（不止中文）
+
+- 上述全部规则对**一切非 ASCII**同样适用：日文/韩文、带重音的拉丁文（é, ü）、西里尔文、希腊文、阿拉伯/希伯来文、数据里的表情符号。
+- 通用法则只有三条：(1) **全链路显式 UTF-8**，一次解码一次编码；(2) **给 Excel 的 CSV 加 BOM，给 PDF 嵌入含目标字形的字体**；(3) **文件名/响应头按 RFC 5987 + 正确 charset/MIME 声明**。覆盖范围最广的字体优先选 Noto/思源系列。
+
+## 8. 反模式（出现即不合格）
+
+- 导出 CSV 不加 UTF-8 BOM 就交付（Excel 打开必乱码）。
+- 用平台默认编码写文件，不显式指定 UTF-8。
+- PDF 生成不嵌入中文字体，靠 base-14 内置字体画中文（缺字/框）。
+- HTML→PDF 的瘦容器里不装中文字体包，线上中文全是框。
+- 中文文件名直接塞进 `filename="..."`，不做 RFC 5987 编码。
+- 响应不声明 `charset=utf-8`，MIME 类型写错。
+- CSV 导出不做公式注入无害化（`=`/`+`/`-`/`@` 开头单元格）。
+- 长数字/前导零（手机号/身份证）被 Excel 转科学计数法或抹零，列不设文本格式。
+- 中文导出「看代码觉得没问题」就交付，**没在真机用 Excel/WPS 实际打开验证**。
+
+## 9. 最低交付 checklist（中文/i18n 导出必须真机验证）
+
+- [ ] CSV 用 Excel **和** WPS 实际打开，中文不乱码（已加 UTF-8 BOM，或改用 xlsx）。
+- [ ] xlsx 内容、日期、长数字/前导零列正确（ID/手机号设文本格式）。
+- [ ] PDF 打开中文不缺字、不出框（已嵌入并注册 CJK 字体；容器装了中文字体包；体积没把整库塞进去）。
+- [ ] 中文文件名下载后不乱、不被截断（`Content-Disposition` 用 `filename*` + ASCII 兜底）。
+- [ ] 响应头 `Content-Type` 带正确 charset 与 MIME 类型。
+- [ ] CSV 已做公式注入无害化。
+- [ ] 全链路显式 UTF-8（DB 连接 / 读取 / 编码 / 声明），无双重编码。
+- [ ] 其它非 ASCII 内容（日韩/重音拉丁/RTL/emoji）按同规则一并验证。
+
+---
+**参考**：RFC 4180（CSV）、RFC 6266/5987/8187（Content-Disposition 与扩展文件名）、UTF-8 BOM、OpenXML/xlsx、Noto Sans CJK / 思源黑体 字体嵌入与子集化、CSV Injection 防护。相关：`frontend/01-standards/i18n-and-localization.md`、`frontend/02-playbooks/i18n-internationalization-playbook.md`、`backend/01-standards/file-upload-and-storage.md`。

package/backend/01-standards/django-complete.md

@@ -5,8 +5,8 @@ domain: backend
 category: 01-standards
 difficulty: intermediate
 tags: [backend, complete, django, framework, rest, 中间件, 数据库迁移, 概述]
-quality_score: 70
-last_updated: 2026-06-15
+quality_score: 91
+last_updated: 2026-06-29
 ---
 # Django 完整指南