先改 OpenAPI 规范，再修改 Go API 和 React SPA

## 以 OpenAPI 规范为准，并分清每一层的职责 - 将 OpenAPI 规范视为路由、请求与响应 schema 以及共享模型的唯一事实来源。 - 在开发环境中，让 Go 后端与 React SPA 都能独立构建。 - 在生产环境中，优先将构建后的 SPA 嵌入后端二进制文件，并从同一来源提供 API 和 UI。 - 开发服务器仅用于方便代理；不要让开发专用端口或主机泄漏到生产代码中。 - 保持清晰的所有权：API 层负责传输，服务负责领域行为，存储负责持久化，前端负责呈现。 - 在创建平行路由、配置存储、事件通道或状态模型前，先扩展现有契约。 - 没有范围明确的需求和架构决策时，不要添加被明确推迟的子系统。 - 文档与实现不一致时，停止受影响的变更，并先解决事实来源之间的冲突。 ## 不手改生成文件，先改规范再重新生成 1. 检查规范、生成的接口、实现、测试和相关运维文档。 2. 编辑权威来源：API 形状改 OpenAPI 文件，设置改配置结构，UI 文本改消息目录。 3. 使用仓库规定的命令重新生成后端和前端产物。 4. 实现生成的接口，并且只更新直接受影响的服务和 UI wrapper。 5. 运行格式化、静态分析、范围明确的测试以及最小且相关的运行时检查。 6. 审查生成差异，确认规范生成了预期契约。 - 绝不要手动编辑生成文件；应修正规范或生成器配置。 - 绝不要注册绕过生成服务器接口的临时路由。 - 保持 operation identifier 唯一且稳定，因为它们会成为生成的方法名。 ## 把共享 schema 放在一处，让生成的类型与 API 一致 - 按领域拆分路径定义，同时将共享 schema、参数和响应保留在一个权威的 components 区域中。 - 重用共享引用，不要在路径文件之间复制几乎相同的 schema。 - 保留跨文件引用所需的生成器专用 import mapping 和 pruning 控制。 - 当 schema 映射上游库类型时，保持机器映射与 JSON property 同步。 - 声明每个序列化字段，并为非 Go 使用者将每个始终存在的字段标记为 required。 - 使用 OpenAPI 版本和生成器要求的形式表示 nullable 引用，并测试生成结果。 - 当运行时一致性很重要时，从后端实际提供的 API 文档生成前端类型。 - 如果仓库政策将差异用作契约审查证据，则提交生成的 API 类型。 - 将 API client 放在领域 wrapper 后面，使组件不依赖传输细节。 ## 返回结构化错误，不泄露内部错误信息 - 通过生成的服务器接口实现 endpoint，并按领域组织 handler 方法。 - 只使用一个共享 JSON 响应 helper 和一个中央错误分类器。 - 返回结构化错误，其中包含稳定的机器代码、呈现种类、安全的可选字段和请求标识符。 - 绝不要将内部或上游的原始错误文本复制到 client 响应中。 - 将字段验证细节放入专用 map，并为非字段错误保留一个通用 key。 - 将上游失败转换为稳定的原因标识符；原始 body 只能保留在受保护的日志中。 - 仅当动态文本经过确认可以安全显示时，才使用类型化的用户可见错误。 - 不要在分类器之外构造线上错误 envelope。 - 返回状态码和 JSON 错误，不要用 panic 控制流程。 - 将 panic 恢复视为经过结构化和记录的安全网，而不是正常行为。 ## 每个设置只定义一次，并标出需要重启的设置 - 在类型化配置结构中只定义一次设置；从中派生默认值、验证、schema metadata 和环境变量 key。 - 始终按同一优先级应用：默认值、设置文件、环境覆盖。 - 只持久化与内置默认值不同的值。 - 对每项新设置定义默认值、验证、UI 分类、敏感性、可见性和重启行为。 - 可热重载的设置必须有实时使用者或重载 hook；否则应标记为需要重启。 - 需要重启的值可以立即持久化，但在重启前必须固定在有效运行时视图中。 - 在 API 响应中遮盖敏感值，并将已遮盖的 placeholder 视为更新时的 no-op。 - 通过运行时 API 将程序专用设置保持为只读，并从反射出的 UI schema 中排除隐藏设置。 - 启动时与持久化前运行相同的 validator，使保存的配置不会破坏下一次启动。 - 原子写入设置，并将受管理的相对路径固定到稳定的数据根目录，而不是启动目录。 ## 统一日志格式，关闭服务时不遗留未完成的工作 - 在 HTTP 请求、生命周期事件和后台 worker 中使用同一 schema 的结构化日志。 - 将 handler 字段和错误附加到当前请求日志，而不是发出重复的逐请求事件。 - 后端日志只使用一种运维语言；UI 本地化由前端负责。 - 当请求 ID、真实 client 地址、请求日志和 panic 恢复依赖顺序时，保持中间件顺序不变。 - 除非中间件必须在请求日志开始前改变字段，否则将新中间件放在恢复边界内。 - 关闭时，先关闭长期事件订阅者，再 drain HTTP 服务器。 - 为正在处理的请求设置有上限的 drain 期限，并明确定义期限到达后的行为。 - 重启时，在替换或生成进程前完成服务清理。 - 让流式 handler 在 hub 关闭或请求取消时返回。 - 将每个后台 worker 注册到同一关闭序列中，避免遗留任何工作。 ## 使用稳定的查询键，用户变化时清空缓存 - 当后续 provider 依赖 query、locale、authentication 或 event context 时，明确 provider 顺序。 - 从 feature module 暴露 query-option factory，并将原始 API call 保留在领域 wrapper 中。 - 使用包含每个会改变身份的参数的稳定 query key。 - 仅在真正翻页时保留之前的列表数据；filter、user、tab 或 search identity 变化时将其丢弃。 - authentication session 变化时，清空该账户范围的 cache。 - 集中管理 optimistic update、rollback snapshot 和 invalidation，使同一 entity 的每份 cache 副本保持一致。 - 将 server event 视为 refresh 提示；权威 state 仍来自 query 或 state endpoint。 - 在 render path 内通过 reactive context 读取本地化 message function。 - 通过显式 static resolver 映射动态 translation key，并在各 locale 之间保持 placeholder shape 一致。 - 将人类可读的配置 label 放在前端 catalog 中，而不是后端 schema 中。 ## 单独保存登录会话，临时失败时不让用户退出登录 - 将 session credential 存入一个权限受限的专用 state file；绝不要混入一般设置。 - 将 refresh credential 视为 session authority，并将短期 access credential 视为可替换值。 - 在接近到期时主动刷新，并在 authentication failure 后使用 single-flight 协调只进行一次被动刷新。 - 遇到暂时失败时保留 session；仅在确认永久拒绝后才清除它。 - 让 authorization verifier 保持短期有效、容量受限且只能使用一次。 - 将粘贴的 callback value 发往上游前先验证，并返回已本地化且可操作的错误。 - 从 proxy discovery 结果中去除 credential，并保持 discovery 只读。 - 保护未认证 onboarding 写入，使其无法在 login 后修改设置。 - 使用 authentication 和应用专用 CSRF header 保护敏感 mutation endpoint。 - 绝不要向 client 暴露上游 authentication body、credential 或内部 package error。 ## 通过临时文件保存下载内容，不删除应用没有创建的文件 - 将 job 作为 transaction boundary，并原子持久化每次有意义的 state transition。 - 通过 event 发送高频 progress，不要在每个 tick 重写 persistent state。 - 将 payload 写入名称唯一的 temporary file，成功后才 rename；取消或失败时移除 partial file。 - 仅使用有上限的 exponential backoff 重试可重试的 failure。 - cleanup 前记录 application 是否创建了每个 final file；绝不要仅根据预期名称移除路径。 - 同时针对 disk content 和处理中 reservation 解决 collision，并使用有上限的 fallback strategy。 - restart recovery 时重新解析路径，除非已完成的 payload 已拥有其 destination。 - 启动时解析 path template，并在接受配置变更前再次验证。 - 清理每个 path segment，保留显式 root，按 byte 限制 filename，并按字符计算用户可见的截断。 - 按 job 固定 conversion 和 naming 决策，使热重载设置无法改变正在进行的工作。 ## 重新连接时补发错过的事件，无法补发时要求重新同步 - 将 persistent state 保持为权威来源，并将 event 视为优化手段。 - 为 event 提供稳定的 ID、timestamp、topic、type 和可重建 payload。 - reconnect 时，如果 buffer 中仍有数据，则 replay client 最后已知 ID 之后的 event。 - 无法 replay 时，只发出一个 resynchronization event，并要求 client 重新获取权威 state。 - 使用 keepalive，防止中间设备无声关闭 idle stream。 - 只有 job-level event 可以设置 aggregate job status；task event 只更新 task state，不重新计算 server 所有的 rule。 - reconnect 后以及收到 resynchronization signal 后，refresh 受影响的 view。 - throttle progress notification，但 terminal transition 和最后一次 progress update 应绕过 throttle。 - 通过小型 publisher interface，使 event transport 与 domain manager 保持独立。 ## 限制代理目标，验证签名后再更新应用 - 按精确 host policy 允许 proxy target，并重新检查每次 redirect，以防止 server-side request forgery。 - 让针对同一 resource 的并发 cache miss 共享请求，并在 cache 前拒绝超过上限的 body。 - 将 filesystem 视为 cache 的事实来源；定期以及每次写入后按最久未访问顺序驱逐内容来调整 size。 - 让 cache storage 可迁移，并与持久 user state 分离。 - 在 release build 时注入 update feed location 和 trusted signing key；缺少 trust material 时 fail closed。 - 在信任任何 version、URL、checksum 或 release note field 前验证 signed manifest。 - 替换 binary 前，根据 signed manifest 验证 downloaded archive。 - 将 update application 限制为 single-flight，在 development build 中拒绝，并要求 authentication 与 CSRF protection。 - 以确定方式解析 replacement executable，并拒绝有歧义的 archive。 - 仅在 verified replacement 准备就绪后，drain service 并 restart。 ## 在实际运行的应用上验证，并在发布或修改生产环境前停下 - 不跳过失败步骤，依次完成 generation、implementation、focused test 和 direct runtime verification。 - 验证 health endpoint、当前提供的 OpenAPI document、受影响的 API behavior 和直接受影响的 UI path。 - 当变更涉及相应范围时，运行 format、static analysis、race-sensitive backend test、frontend check 和 production build。 - 使用 focused test 确认 atomic persistence、restart semantics、secret masking 和 error non-disclosure。 - 对 release 工作验证严格的 semantic versioning、signed-feed continuity、checksum 和 platform archive resolution。 - 除非当前需求明确将其纳入范围，否则继续推迟已推迟的 feature。 - 避免无关 refactor、平行 state store、重复 error system 和投机性 infrastructure。 - 没有明确授权时，在 external release、destructive migration、credential change 或 production mutation 前停止。 - 报告变更内容、验证内容、仍在范围外的事项和任何未解决的契约冲突。