修改前后端共存的多模块代码库，不破坏构建

## 从代码库根目录开始，读取所有相关模块的规则 即使任务看起来只涉及一个子项目，也要从代码库根目录打开并统筹整个项目。将根级智能体指令作为基准，将嵌套的指令文件视为补充本地规则。 编辑前，识别任务可能影响的每个模块，并加载各模块的指令文件。跨模块任务必须遵守所有相关的本地规则，而不能只遵守离首次拟议改动最近的文件所对应的规则。 ## 梳理各模块负责的内容，前后端一起修改 维护主要区域的职责图： - 公共API模块负责扩展点、服务契约和安全抽象； - 后端应用负责业务逻辑、响应式服务、路由、安全、迁移和打包； - 前端工作区负责管理界面和用户界面、共享包以及生成的API客户端； - 依赖平台模块负责应用和下游扩展所需的约束； - 开发者文档负责人类可读的架构与工作流程说明。 只要契约、载荷、身份验证、导航或用户体验跨越边界，就将后端和前端改动作为一个全栈任务处理。在同一次改动中同步公共契约、后端处理程序和前端用法。 ## API变更时重新生成客户端，不手动修改 每当公共请求或响应类型、路由、路由器契约、API模式注解、生成的模式、身份验证或会话行为发生变化时，都要评估对前端的影响。更新源契约后，通过代码库规定的命令重新生成API描述和客户端。 绝不能直接编辑生成的客户端文件。应修正契约或生成器输入，重新生成输出，并审查产生的差异。对生成输出进行破坏性改动，或更改下游使用者可能依赖的公共API之前，必须先征得确认。 ## 确认前端产物如何打包进后端构建 了解前端输出如何进入可部署的后端产物。如果后端构建会将编译后的界面嵌入应用资源，那么每次前端输出变更也会影响后端打包路径，必须在该路径上进行验证。 从根目录运行跨技术栈的统筹流程，使后端编译、界面打包和测试使用同一个依赖关系图。将构建时下载、预设扩展和复制的分发产物视为构建契约的一部分，而不是附带文件。 ## 版本和格式规则从指定的文件中读取 从指定的目录清单、属性文件、构建脚本和包清单中读取依赖版本、项目版本、语言发行版、插件版本及前端依赖。不得硬编码已有权威来源的版本。 将已配置的格式化工具和代码检查工具作为缩进、行宽及支持语法的权威依据。遵守声明的语言发行版，包括在有明确指定时使用`release 21`，并将根级格式化规则保留在构建所期望的作用域内。 ## 不在响应式代码中加入阻塞I/O，并守住数据库的位置 即使其他位置启用了虚拟线程，也不得在响应式执行路径中引入阻塞式输入或输出。保留项目选定的迁移引擎，不得擅自换用其他引擎，并将特定数据库方言的迁移保存在指定的数据库目录中。 将扩展模式、运行时JSON数据、特定配置文件的设置以及可覆盖的工作目录保留在各自的归属位置。文件型嵌入式数据库必须使用绝对文件路径；相对URI可能会在应用模块下创建多余目录，并改变实际打开的数据库。 ## 按改动的是后端还是前端来选择测试 根据实际范围选择检查： - 仅后端改动需要执行代码库格式化和受影响的后端测试； - 仅前端改动需要执行前端格式化、类型检查、代码检查以及相关单元测试； - 契约改动需要生成API描述、重新生成客户端、验证前端并执行后端测试； - 跨技术栈改动除了验证契约两端，还必须验证最终打包产物。 先运行聚焦检查，再根据需要扩大范围。为每项已更改的行为新增或更新测试；只要必需的持续集成检查仍然失败，就不得提交工作。 ## 推送前确认正确的上游，只暂存本任务的文件 推送或发起评审前，先识别当前代码库并检查其远程仓库。为该检出内容选择正确的上游；误用相关公共代码库或专有代码库的上游，可能导致高昂的回退成本。 从预定的上游基线开始工作，并遵循代码库的分支约定，例如`upgrade/gradle-X`、`feat/name`、`fix/name`或`improvement/name`。只暂存属于本任务的文件；当构建输出或数据库产物可能存在时，绝不能使用`git add -A`或`git add .`。 如果陈旧工作树锁定了主分支，应检查工作树列表，并且只明确移除已确认陈旧的条目。不得用大范围清理代替对实际锁定者的精确识别。 ## 数据库迁移和新增依赖先询问，绝不提交密钥 采用三级控制： - 始终从根目录工作，加载所有适用的嵌套规则，明确暂存文件，从源数据重新生成派生客户端，为变更的行为添加测试，并在评审说明中披露材料使用了AI辅助； - 更改公共API、添加构建依赖或包依赖、编写数据库迁移、修改安全配置或持续集成工作流程，以及破坏性替换生成输出之前，必须先征得确认； - 绝不能提交秘密信息、硬编码权威版本、向响应式路径添加阻塞操作、直接编辑生成的客户端，或在未确认正确上游的情况下发起评审。 即使实现本身很简单，这些边界也仍然适用。实现容易并不会降低兼容性、安全、数据或发布风险。 ## 避开数据库相对路径等常见的构建陷阱 保持已知的工具特定不变量： 1. 文件型嵌入式数据库的位置必须解析为绝对文件系统路径；相对路径形式可能创建多余的模块目录，并导致应用打开错误的数据库。 2. 构建包装器升级既需要指定版本的包装器命令，也需要第二条包装器生成命令；只运行第一条命令会使生成的包装器文件不一致。 3. 将代码库级的其他格式化配置保留在根目录。若将其移入应用子模块，可能会合并互不兼容的格式化任务，并在构建工具`9.x`中触发隐式依赖验证错误。 将这些陷阱记录在权威构建指南附近，并在每次更改受影响的配置时进行验证。