planetscale-customer-report-template

客户报告模板

目的

为客户数据库和可选的关联代码库编写清晰的评估报告。报告应可操作、有证据支持且安全。应将建议与已应用的更改分开说明。

语气与表述方式

报告旨在准确评估，帮助客户充分发挥所用平台的价值。功能采用情况应由证据得出，绝不能通过表述引导。语体应专业、明确——像工程师的评估，而不是营销文案。

• 将未使用的功能表述为能力缺口，并量化其影响。 切勿写“已关闭（好）”“未启用（安全）”，或以其他方式将未采用功能呈现为正面发现。正确的写法是：当前状态、该功能提供什么，以及与之相关的测量结果。 示例：“原始查询采集：已停用。启用后可查看每次执行的字面参数值；适用于 Q1（占查询总耗时的 38%），因为模式级数据不足以定位触发问题的调用。”
• 不要使用表示热情的措辞。 不要使用“物有所值”“发挥了作用”“容易采用”“将根因排查时间从数小时缩短到数分钟”之类的表达，也不要使用任何感叹句。说明机制和测量结果，让数字说明问题。
• 将运营成本作为事实直接写出，不要弱化：“字面值会显示在可观测性管道中”是该功能的属性，应如实说明一次，不必安抚。
• 每条建议都必须引用其针对的具体发现——指纹、指标、事件数、时间范围。没有附带测量结果的建议是不完整的。
• 评估已启用的功能，而非称赞它们。 如果某项功能已启用，应报告它当前在做什么，并以可测量的方式说明（“异常检测在 7 天内标记了 9 次连接激增；尚未配置交付渠道”），以及其配置是否完整。
• 适用性也是分析的一部分：如果证据不支持客户使用某项功能，应明确说明。
• 建议应围绕更改能带来的好处来表述，而不是强调当前状态的威胁。 写“专用应用角色可按服务限定凭据范围，并支持在不停机的情况下轮换”，不要写“限制凭据泄露的影响范围”。避免使用渲染威胁的词语：“影响范围”“未受保护”“暴露”“默认公开”“有风险”。仍应将实际风险作为事实说明——“生产分支运行的副本数为零；主节点故障后必须通过还原来恢复”是应写入报告的发现。排除的是渲染威胁的措辞，而不是披露事实。
• 根据已验证的语义报告平台行为，不要基于假设下结论。 当两个 API 界面显示不同的值时，它们通常对应不同的设置——请查阅文档并报告实际生效状态。不要基于未经验证的假设，将平台行为描述为不一致、矛盾或有缺陷。如果无法验证其语义，应分别说明每个界面报告的内容，不要下结论，并将问题提交给 PlanetScale 支持团队。如果已验证的平台行为确实有误，应如实报告并交由 PlanetScale 支持团队处理——这是平台问题，而非客户配置问题。

运行情况与发现分开记录

评估工具出现的问题——HTTP 状态码、MCP 错误、CLI 故障、令牌范围问题、超时、端点探测——描述的是运行情况，而不是数据库。这些内容应记录在运行日志中，而不是发现中。

• 无法收集证据时，报告应注明“本次运行未评估”，不附带任何错误机制。
• 证据附录包含已收集的证据。
• 运行日志（工具错误、尝试过的路径、访问缺口）与报告一同提供，并可供执行评估的人员查阅——不会隐瞒任何内容。之所以分开记录，是因为工具错误无法说明客户的数据库情况。
• 绝不能根据失败的调用得出某项功能未配置的结论。“未配置”必须以成功调用后返回空结果为依据。

输出形式

报告采用纯 Markdown 格式：带标题的章节、正文和管道表格。这是基准格式，必须始终完整生成——它适用于任何 Agent、终端或聊天界面。如果宿主 Agent 提供更丰富的呈现界面（Cursor 画布、HTML 预览、仪表板），可以在 Markdown 报告之外使用，但不能替代 Markdown 报告。

必需的报告格式

PlanetScale 最佳实践评估

范围

• 组织：
• 数据库：
• 已审查的分支：
• 引擎：
• 已审查的代码库：
• 使用的接口：
• 时间范围：
• 已应用的更改：无

执行摘要

撰写 3-7 条要点。第一条应以事实和具体指标说明平台当前如何运行此数据库，例如副本拓扑和故障转移状态、备份频率及最近一次成功备份、Insights 收集量、已启用的安全功能。这不是赞扬，而是报告其余部分所基于的运行基线。 然后列出：

• 风险最高的安全缺口。
• 价值最高的可观测性改进。
• 价值最高的自动化机会。
• 引擎特有的工作流缺口。
• 代码库埋点缺口。

当前状态

数据库和分支拓扑

提供证据。

安全工作流

对于 Vitess：

• 安全迁移。
• 部署请求。
• 审批要求。
• 门控部署的使用情况。
• 架构回滚操作手册。

对于 Postgres：

• 分支迁移工作流。
• 角色。
• pg_strict。
• Traffic Control。
• 备份/PITR。
• 连接池。
• 私有连接和 IP 限制。

可观测性

• Query Insights 状态。
• 异常。
• 查询标签。
• 原始查询收集状态。
• 架构建议。

自动化

• Webhook。
• Agent 循环。
• CI/PR 工作流。
• 事件路由。

代码库埋点

• 检测到的框架和 ORM。
• 当前的 SQL 注释或跟踪。
• 建议的 SQLCommenter 包/路径。
• 标签架构。

建议

使用以下表格结构：

ID	建议	目标	收益	风险	是否需要审批	是否先测试？	证据

建议 ID：

• Insights/查询标签使用 OBS-*。
• Vitess 安全/部署工作流使用 VIT-*。
• Postgres 角色、pg_strict、Traffic Control、PITR、网络使用 PG-*。
• Webhook 和自动化使用 WEB-*。
• 代码库埋点使用 APP-*。
• MCP/Agent 工作流使用 AGENT-*。

需审批的拟议变更集

对于每项拟议变更，包含：

• ID。
• 具体目标。
• 具体变更。
• 要使用的接口。
• 推荐理由。
• 预期效果。
• 可能对可用性的影响。
• 测试计划。
• 回滚计划。
• 是否会更改生产环境。

有意不应用的变更

明确说明：

• 未更改任何 PlanetScale 设置。
• 未更改任何架构。
• 未更改任何流量控制。
• 未更改任何角色或凭据。
• 未更改任何 Webhook。
• 未更改任何代码。
• 未创建任何分支、备份、还原、部署请求或迁移。

证据附录

对于每项证据：

• 来源。
• 命令/API/MCP/代码库路径。
• 时间戳。
• 值。
• 备注。

最终必需句

在报告末尾写上：

“No changes have been applied. Approve specific change IDs before any mutation.”