在全栈 Monorepo 中修改代码，不破坏共享包

## 把每处更改放进负责它的模块 编辑之前，先梳理工作区。区分产品应用、可复用的 UI 包、共享业务逻辑、数据 schema 与 migration、类型包、配置 preset、文档、部署资源以及测试 harness。 将特定功能的行为放在负责该功能的应用或功能模块中。将可复用的领域逻辑和共享类型放在使用方明确的包中。让基础设施和部署配套文件与运行时源代码保持分离。单元测试应与其验证的稳定逻辑放在一起，而浏览器流程规范应放在应用的端到端测试区域。 不要仅仅为了避免修改某个包，就在应用内部复制共享逻辑。遵循依赖方向，并在共享包发生更改时验证所有下游使用方。 ## 重新构建预编译包，避开过期缓存 识别那些经过预编译后被复制到应用 public asset 中的包。运行中的应用可能导入的是包的 distribution output，而不是它的 source，因此只编辑 source 可能无法观察到变化。 更改预编译包或任何会影响其 bundle 的依赖项后： 1. 仅删除该包已知的 distribution output 和已复制的 artifact； 2. 对受影响的 dependency graph 绕过 build system cache； 3. 通过其官方 workspace task 重新构建该包； 4. 刷新或禁用 browser cache； 5. 只有在重新构建的 asset 仍未加载时，才重启 development server。 绝不要手动编辑已复制的 bundle 或生成 artifact。将 cache 失效处理视为验证流程的一部分，而不是 source 更改失败的证据。 ## 遵守共享的 lint 和类型规则 使用 repository 共享的 lint、format 和 compiler preset，不要使用 local override。遵循既定的 indent、行宽、引号、semicolon 和 import group 规则。 统一命名 component 及其文件夹，对 function 和 variable 使用 lower camel case，并只为真正的常量保留 upper snake case。将 mock 放在指定的 mock 位置，以保持解析行为和 import 顺序稳定。 在含义仍然清晰时优先使用类型推断，使用共享的 domain type，并避免使用无类型的逃生方式。将 component props 视为不可变数据。保持 component 职责集中、effect 范围收窄、hook 依赖正确；只有经测量确有需要时才使用 memoization，而不是把它当成习惯。 ## 分开服务器逻辑，用统一工厂生成缓存键 将 route 组合、service logic 和 feature module 分开。server action 应调用 service，并返回统一的成功或 error envelope。context provider 在 provider 外部被使用时必须明确失败，并且必须使用稳定的 snapshot 而不是可变引用来清理 effect。 对于一次 request 内的重复工作，使用 request-scoped memoization。对于跨 request 的高成本工作，使用获批的共享 cache abstraction 或明确的 distributed cache。如果 repository 已拒绝某个不稳定的 framework cache API，就不要引入它。 所有 cache key 都应通过规范的 key factory 创建。key 必须包含所有可能改变结果的维度，确保 user、tenant、environment、locale 或 feature mode 之间不会共享互不兼容的 entry。 ## 界面文字一律经过翻译，时区与语言分开处理 所有面向 user 的文本都应通过 translation function，并遵循既定的小写点分 key 约定。只保留一个 source locale file，作为唯一手动编写的翻译来源。绝不要手动编辑生成的 locale file；更改 source text 后，应运行 localization generator 和 key validator。 通过共享 helper 渲染面向 user 的日期和时间。显示所用的 locale 应来自应用的语言真值来源，绝不能来自隐式的 browser default。将 locale 与 time zone 视为彼此独立：locale 控制格式，time zone 控制所表示的时刻。 绝不要根据 locale 推断 time zone。除非产品定义了 time zone 的真值来源，否则应保留现有存储值的语义。storage、API、export、integration 和 log 应使用稳定的非本地化格式，例如明确的 UTC 或 ISO 表示。 ## 不混用各组织的数据，保持查询快速 按照 repository 的 tenant 边界（例如 organization 和 environment）限定每项 data operation 的范围。一致应用 soft-deletion filter，避免 inactive 或已删除的 record 通过其他 query 路径重新出现。 统计数量时，使用带 filter 的 count query，不要使用 offset 式 pagination 参数。并发运行彼此独立的 count query 与 data query。对于大型 dataset，优先使用 cursor pagination；按时间 filter 时，应包含已建立 index 的 ownership field。 审查 schema 和 migration 更改时，应同时检查所有受影响的 query 路径。data isolation 是一项跨领域不变量：缺少 tenant predicate 不是轻微的 performance 问题，而是潜在的数据边界故障。 ## 按用户风险而不是覆盖率数字选择测试 优化目标应是可信度，而不是 coverage 百分比： - 对关键 user journey、UI regression 和 component 行为使用浏览器端到端测试。 - 对 validator、transformer、evaluator、计算和 edge case 等稳定的 pure logic 使用 unit test。 - 通过 staging 手动检查判断 release 是否就绪，并针对重大问题形成 bug 修复、backport 和重新测试的闭环。 保持 browser test 目标集中、命名清晰，并明确标注耗时较长的 suite。通过共享 helper mock network 和 storage 边界。不要添加脆弱的 component snapshot、markup assertion、针对实现细节的 test、计时 hack、超大型 flow，或仅为提高 coverage 而创建的低价值 test。 review 前运行标准 unit suite；关键 flow 更改时运行 coverage；对于 journey risk，运行直接受影响的 end-to-end suite。 ## 及时更新文档和组件示例 遵循 documentation system 的 file contract、metadata field、heading rule，以及获批的 step 或 callout component。使用标准 notice 标记受限版本的 content，不要自行设计新的 badge 或措辞。 将 component example 放在 component 旁边，并通过其 public entry point 导入。按照 repository 的标准分组整理 control。覆盖 default state、受支持时的 disabled state、受支持时的 icon state、所有 variant 以及有意义的 edge case。 构建或审查 UI 之前，加载受影响界面的 design context。共享 design guidance 是 code convention 的补充，并始终是 token、component、motion 和 visual quality 的真值来源。 ## 只给 CI 工作流必需的权限 只向 automation token 授予各 workflow 所需的权限。hosted Linux job 开始时，应先执行获批的 runner hardening step，以便在 project code 执行之前约束 network 和 process 行为。 将 dependency lock 作为权威依据，并通过 repository 选定的 package manager 运行 workspace command。避免使用绕过 task graph、共享 environment 或 cache metadata 的一次性 install 或 build command。 更改 workflow 时，验证 event trigger、permission、secret 暴露、cache key、artifact 和 failure propagation。后续 step 显示为 green，不得掩盖前置条件的失败。 ## 提交附有测试结果和截图的拉取请求 完成之前，删除 dead code 和未使用的 import，运行权威的 lint command，并执行能够证明更改正确的最小 test set，以及任何直接受影响的更广泛 flow。 保持 commit 聚焦，并遵循 repository 的 commit convention。pull request 应说明问题、概述解决方案、链接到作为依据的 issue 或 specification，并指出 migration 或 environment 更改。 为 UI 工作附上可视化证据，并粘贴相关 lint、test、build 和 migration command 的结果。reviewer 应能够在无需从 diff 中重建整个工作过程的情况下，判断更改了什么、为什么它属于该模块、如何刷新了生成产物，以及验证了哪些风险。