技术决策原则库
用途：把「已经吃过亏的判断」固化下来，供评审、方案设计、事故复盘时直接调用。 维护规则：只增不改。原则需要调整时不修改原文，在条目下追加「修订记录」，保留判断的演化过程。 编号规则：
P01–P17沿用.workbuddy/memory/MEMORY.md的原始编号，跨文档引用编号与标题均可。 每条统一四段式：结论 / 来源 / 边界 / 反面案例。缺「边界」的原则等于没写——只知道结论不知道适用范围，一定会被误用。
一、架构与暴露面
P01 H5 页面归属与责任
结论：谁提供 H5，谁负责配套接口与安全防护（Token 鉴权、防刷）。「开发成本高」不构成推翻已评审方案的理由。
来源：2026-09-02 冷饮 H5 对齐会，王建朝裁定。
边界：适用于跨团队、跨系统的 H5 交付，判断口径是责任主体是否分离，不是"是否用了 H5"。同团队内部前后端一体开发时不适用。
反面案例：「开发成本高」曾被作为推翻已评审方案的论据提出，该论据不成立——成本问题应回到排期与资源侧解决，不应转化为安全责任的下沉或豁免。
P02 公网暴露范式与鉴权落点
结论：ToC H5 不通过集成网关（TSE 仅内网、有限流与安全限制）；走独立公网域名 + 独立 Pod，Controller 迁公网、Service 留内网走 RPC，入口强制鉴权（App Key/Secret + Token + 参数加密）。
来源：2026-09-01 小智 App 接入盘点任务 H5 评审。
边界：⚠️ 两种实现并存，口径待统一。9.01 为应用层拆分（Controller 迁公网 + RPC）；9.07「扫码错误记录与 H5 外网访问方案评审」改用 H5 + Nginx 部署外网 Pod、二级目录 /api 反代内网接口（网关层转发）。两者层级不同，不可混用描述。凡涉公网暴露的方案评审，必须先回答两个问题：用哪种范式？鉴权落在哪一层？
反面案例：Nginx 反代模式下若鉴权落点未明确（Nginx 侧或内网服务侧），内网接口等同于对外裸奔——此时"暴露了但看起来有网关"比明确不暴露更危险。
P03 ToC 与 ToB 接口物理分离
结论：ToC 公网接口与 ToB 内网管理接口物理分离；新功能立项需提前确定部署位置与暴露面。
来源：2026-09 公网暴露系列评审沉淀。
边界：约束部署拓扑与网络可达性，不约束代码仓库是否同仓。立项阶段未定部署位置的功能，不进入开发排期。
反面案例：（暂无实例，待补）
P04 功能隔离靠代码不靠规范
结论：某事业部不支持某功能时，一律在代码层按事业部判断隐藏入口，不依赖配置人员的注意力和配置规范。
来源：2026-09 营销活动中心功能差异化需求评审。
边界：适用于事业部维度的能力差异（如冷饮事业部不支持普通激励叠加奖品）。若差异属于运营策略变化、需要频繁调整的，仍走配置——判断标准是"这个差异会不会变"。
反面案例：依赖配置规范约束的结果是，配置人员一次疏忽就把不该出现的入口开出去，而事后无法从代码侧证明"本不该出现"。
P05 录入类字段需区间校验
结论：录入类字段需有合理区间校验，避免人工录入错误流入下游。
来源：2026-09 营销活动中心录入类字段问题复盘。
边界：适用于人工录入的日期、数量、金额、比例类字段。系统生成或接口透传的字段不强制，但需在上游明确取值范围。
反面案例：生产日期缺少年份上限校验，错误年份直接流入下游业务与报表，事后需按数据修复流程回溯。
P06 异步依赖必须前置等待
结论：依赖异步结果的后续动作，必须等异步完成再执行，或做排队延后重试；不做前置等待即为缺陷。
来源：2026-09-11 RPC 与退款链路问题沟通。
边界：适用于跨域数据依赖，如退款时依赖上游拆单结果。若上游提供可靠的完成通知，以通知为准；只有轮询/查表方式的，必须显式处理"查不到"分支。
反面案例：退款时若上游拆单有延迟，指定物料在物料域查不到，直接导致退款失败或数据丢失。
P07 并发写入的状态一致性
结论：当"实时写 A + 异步写 B"且 B 用于反查状态时，必须在写 B 之前拦截重复，而不是事后修数。
来源：2026-09-04 盘点签收故障修复评审。
边界：适用于双写且其中一个写路径异步、并被用于状态查询的场景。纯追加型日志不适用。
反面案例：并发下出现失败状态覆盖成功状态——修数能救回数据，但救不回已经被错误状态驱动的下游行为。
P08 消息消费与落库必须原子
结论：消费确认（ack / 位点前进）必须发生在落库成功之后。异常分支一律显式处理，禁止「吞异常 + 上游已确认」。
来源：2026-09-14 营销活动中心 Scan Detail 丢失约 3 万条复盘；与 9.11「catch 后中断赋值即发 MQ」属同一缺陷形态。
边界：适用于所有"消费即确认"的消息中间件。若业务允许丢消息（如埋点），需在方案里显式声明并说明补偿方式。
反面案例：消息正常消费但未落库，丢失在重启和异常分支里静默发生，直到业务侧对不上账才被发现——3 万条 Scan Detail 即此形态。
P09 MCP 工具接入的权限责任
结论：平台（EdBody）仅透传用户身份信息，权限校验由 MCP 工具侧自行实现。接入前须明确用户信息获取字段约定与安全校验方案。
来源：2026-09-03 EdBody 平台宣讲，刘振源答疑。
边界：⚠️ 与 2026-09-11《智能体建设规范》中「智能体权限不得突破用户原有权限」存在收紧，两者是否一致待核查。新接入的 MCP 工具按较严口径执行。
反面案例：若默认平台侧已完成鉴权，工具侧不做校验，则任何拿到透传身份的调用方都能越权访问该工具的全部数据。
二、数据治理与生产变更
P10 先堵后修
结论：先上堵漏代码 → 观察确认无新增脏数据 → 再修历史数据，严禁边漏边修。
来源：2026-09-04 盘点签收故障修复评审，王建朝口径。
边界：所有批量历史数据修复适用。修数 SQL 必须带创建时间下限以命中分区键；备份表与修复语句的 WHERE 条件必须逐字一致，否则备份无法回滚。
反面案例：边漏边修会让修复永远追不上新增，且修数后的数据无法证明"干净"——你无法区分残留脏数据是修复前的还是修复期间新产生的。
P11 临时数据脚本三要求
结论：临时脚本必须幂等、上线前全量测试（含并发）、执行完毕立即下线 Controller 入口。
来源：2026-09 数据脚本相关评审沉淀。
边界：适用于一次性修数、回补、迁移脚本。常驻型任务不适用，但需走正式的调度与监控配置。
反面案例：过期 Controller 入口残留是最常见的形态——脚本下线了但接口还在，任何知道路径的人都能重复触发一次全量修复。
P12 故障原因禁用技术大类词
结论：禁止用「RPC 异常 / 超时 / 网络抖动」这类技术大类词描述根因。故障表强制填三要素：具体服务 + 具体接口 + 具体代码分支。
来源：2026-09-11 RPC 问题沟通，王建朝口径。
边界：适用于故障表、复盘文档、监控告警的原因字段。监控系统的原始告警分类不在此约束内，但转写进故障表时必须下钻。
反面案例：dubbo、Spring Cloud 服务全都能叫 RPC，用大类词既定位不到服务与代码，也会让故障表看起来像同一类问题反复发作，掩盖真实频次与趋势。806 那次 RPC 问题即因此拖了一个月。
P13 异常处理 SOP 三步与闭环
结论：① 解决异常、恢复生产 → ② 识别影响范围（产出可交付清单：受影响业务线 / 涉及表与数据量 / 修复 SQL 的时间范围与分区键 / 回滚兜底）→ ③ 把修复任务关联进后续待办形成闭环。
来源：2026-09-11 RPC 问题沟通。
边界：核心是不能等中台监控或业务反馈驱动修复。配套要求：所有问题统一进一张台账，字段至少含发现来源、影响范围、根因、责任人、排期、关联待办编号。
反面案例：806 的 RPC 问题拖了一个月才想起修，原因是"发现了没人认领、没人排期"——恢复了生产不等于处理完毕，第 ② ③ 步缺失就会出现这种悬空。
P14 重启升级后必须做写通校验
结论：服务重启或升级后，必须做一次数据写通 + 消费位点校验，并纳入发布 checklist。
来源：2026-09-11 同期问题梳理。
边界：适用于依赖异步加载、消息消费、缓存预热的服务。纯无状态网关类服务可豁免。
反面案例：SR 升级重启后若做一次写通校验，当天即可发现 Load 中断；实际从 9.7 升级到 9.11 恢复，间隔 4 天无人发现。
P15 生产变更敬畏与小众数据库治理
结论：① insert overwrite / delete 等高风险 SQL 须技术视角禁限或特殊审批，DDL 前全量备份并演练；② SR 表数据修饰一律禁用 SQL 直改，统一由 Java 程序 + Stream Load 分批更新脚本执行；③ 上线评审表固定检查 SR 操作 / 新老接口兼容 / PDA·App 版本兼容；④ 重大节日前封版，杜绝倒排期；⑤ 建 UAT/PET 生产数据回灌机制。
来源：2026-09-30 B 端出货明细表误清空事故（insert overwrite 触发 SR 分区匹配未命中，4.9 亿条数据被覆盖，已恢复），2026-10-10 复盘；SR 修复方式于 2026-10 StarRocks 异常数据修复方案评审确立。
边界：与 P10、P14 及数据修复评审红线同根因链。测试环境难复现生产问题（数据量/分区/SQL 条件差异），因此"测试环境验证通过"不能替代 UAT 回灌。
反面案例：4.9 亿条数据被一次 insert overwrite 覆盖——分区匹配未命中时，覆盖范围从预期分区扩大到全表，且此类操作没有中间态可回退。
三、协作与能力开放
P16 MCP 工具工程实践
结论：① 工具 schema 是给 LLM 看的 API 文档，enum/默认值约束不足会致 LLM 盲猜入参，须运行时校验 + 错误信息附可用列表兜底；② 解析器不应硬编码模型输出格式层级（如标题 ###），应按语义识别并显式暴露解析质量（parse_status OK/DEGRADED）；③ 身份支持「平台参数注入优先 + HTTP 令牌回落」双通道；④ 接入凭证（PAT）与登录 JWT 解耦，mcp_ 前缀 + 仅存 SHA-256 哈希 + 自助签发页。
来源：2026-10 BRD 评审 MCP 复盘。
边界：适用于面向 LLM 暴露的工具与对外开放的 MCP 服务。内部 RPC 接口不适用（调用方是代码，不是模型）。
反面案例：解析器硬编码 ### 标题层级，模型换一种输出格式就静默降级——调用方拿到的是"成功但内容为空"，比直接报错更难排查。
P17 能力开放的共赢杠杆
结论：把己方能力开放给其他团队/工具时，共赢不取决于「开放」这个动作，而取决于是否把己方约束改造成对对方的兼容。
来源：2026-10 BRD 评审 MCP 开放复盘。
边界：适用于跨团队能力开放、工具接入、平台对接。三处实证：凭证侧把「懂 JWT」降为「自助签发一个 PAT」；身份侧做双通道，接入方无需重构鉴权；质量侧把静默降级转为对外可见的 parse_status。
反面案例：只开放接口、不改造约束，等于把己方的接入门槛原样转嫁给对方——对方要么放弃接入，要么各自造一套适配，最终形成比不开放更高的总成本。
附：与其他资产的关系
| 资产 | 关系 |
|---|---|
.workbuddy/memory/MEMORY.md | 本页为原则正文真源，MEMORY.md 仅保留条目索引与指针 |
docs/project/doc-site-refactor-plan.md | 本页由该方案阶段 1 产出 |
docs/meeting-minutes/ | 每条原则的「来源」可回溯到具体评审记录 |
docs/work-log/ | 原则的反面案例多数对应具体日期的故障或复盘 |