贡献代码

找到实现

从你正在改变的行为开始。对于桌面操作，请遵循 apps/desktop/src/app/routes.tsx 其页面适配器和功能屏幕。在其客户端或功能帮助程序中找到请求，端点架构位于 packages/api，处理程序在 apps/sidecar/src/http，及其下面的服务或存储库。

对于几何形状或 NC 输出更改，请从 packages/core 及其相邻的测试。对于持久性问题，请检查存储库查询并 packages/db/src/schema.ts。对于本机生命周期、文件对话框、钥匙串或更新程序行为，请检查 apps/desktop/src-tauri/src。这使得变更接近其实际责任。

工作区职责

如果可用，请使用模块的公共入口点。让 SQLite 访问远离核心几何体和客户端。功能屏幕不应绕过 sidecar 授权或嵌入服务器凭据。横切更改应明确更新每个受影响的边界。

故意更改共享合同

1. 在合约包中定义请求、响应和类型错误模式。
2. 实现处理程序及其服务/存储库行为，包括所有权检查。
3. 重新生成客户端并检查生成的输出是否是最新的。
4. 更新使用更改后的界面的桌面、配套、插件或外部客户端使用者。
5. 记录支持的输入、输出、故障行为和操作限制。

bun run generate
bun run generate:check
bun run --filter @cadcamfun/api typecheck
bun run --filter @cadcamfun/sidecar typecheck

生成的客户端是合约生成器的输出。当合约或生成器形状错误时修复它们；对生成输出的手写更正将在再生时丢失。保留现有的客户端语义或识别有意更改 API 的兼容性影响。

实施约定

用英语编写代码、注释和文档。保持导出的 TypeScript 接口显式并使用 unknown 加上对不可信值的模式验证。相对 TypeScript 导入使用 .ts 扩展。 CAD 距离使用毫米，绘图角度使用弧度；尊重明确的度值特征和 CAM 旋转输入。在后边界设置 NC 编号的格式。

效果代码使用固定版本的服务/层/错误 API。服务拥有外部依赖；作用域层拥有资源。避免在域模块内添加隐藏的进程配置读取。保持几何计算的纯粹性，并将文件系统、网络和数据库操作隔离在其适配器后面。

对于架构更改，请修改 schema.ts、生成迁移，并执行现有数据库的全新创建和升级。对于 UI 更改，请保持路由适配器较小并将交互逻辑放置在相关功能中。对于本机工作，请将几何和存储库逻辑保留在 sidecar/core 中，而不是将其移至 Rust 中。

审核前核实

• 针对更改的行为运行受影响的包的类型检查和有意义的测试。
• 对于错误修复，请演示失败情况及其更正结果。
• 对于共享合同，检查生成的客户端和受影响的消费者。
• 为了持久性，请使用隔离的数据库验证迁移行为和数据完整性。
• 对于本机或渲染交互，除了逻辑测试之外，还应测试实际的目标运行时。
• 更新用户/开发人员文档并解释仍然存在的操作限制。

根检查是 bun run typecheck 和 bun run test。 CI 还具有 Rust 和特定于同伴的作业。报告运行的内容以及任何故障或不可用的运行时覆盖范围；区分已配置的工作流程和成功运行。

保持变更可审查

保持生成的工件、依赖项更新、行为更改和文档更改可追溯到相同的具体目的。避免重新格式化不相关的模块。保留现有的用户工作并使用一次性数据目录进行实验。

请勿在补丁或屏幕截图中包含启动令牌、设备配对链接、模型密钥、数据库内容或签名凭据。示例应使用占位符。本地固定装置或模拟提供者可以验证确定性流程；记录仍然需要真正的提供商或本机集成的地方。

有用的检查

bun run --filter @cadcamfun/core typecheck
bun test packages/core
bun test apps/sidecar/test
bun test apps/desktop/src
bun run --cwd apps/mobile typecheck
bun run --cwd apps/mobile test
bun run --cwd packages/web check
bun run --cwd packages/web build

原生包装用途 scripts/build.ts;使用 --help 或 --dry-run 检查其阶段。单元测试与构建管道的类型检查阶段是分开的。请参阅发布指南以了解签名、目标架构和更新程序验证。

示例：更改项目验证

假设项目创建/更新规则发生更改。请求架构是 packages/api/src/projects.ts，HTTP 适配器是 apps/sidecar/src/http/projects.ts，持久性是通过以下方式实现的 ProjectRepo。该架构目前使 name 可选，而处理程序需要它来创建和更新。在保证架构有效的请求将会成功之前，请检查这两个级别。

1. 定义预期的输入情况：缺少名称、无效类型、空文本、可访问的组织和不可访问的组织。
2. 确定哪个条件是解码错误，哪个条件是业务验证。保留端点记录的状态/错误形状。
3. 在相关处理程序/服务边界添加断言，并验证未经授权或非成员调用者无法绕过规则。
4. 如果公共模式发生更改，请重新生成客户端系列和类型检查使用者。
5. 练习桌面表格并记录任何更改的请求要求。

创建当前使用 HTTP 201 返回一个裸项目行。列表/获取返回关系丰富的行。在不更新其合同和消费者的情况下，不要对这个系列强加通用的成功范围。其他端点系列有意使用不同的包络。

生成器入口点是 packages/api/scripts/generate-clients.ts。它的输出位于 src/client/generated 和 src/sdk/generated。对合约面的更改属于源合约；生成的输出应该是可重现的。

选择正确深度的回归

几何回归应该断言几何，而不仅仅是重复正在更改的计算。现有的碰撞测试提供了有用的模式：静止重叠是零时间的碰撞；即使端点清晰，中间旋转扫描也可能发生碰撞；不足的界限未解决；并将经过认证的间隙与密集的独立参考进行比较。

bun test packages/core/src/cam/kernel/collision.test.ts
bun run --filter @cadcamfun/core typecheck
bun test packages/core

为其他工作选择类似的边界。数据库迁移需要新鲜/升级案例和备份失败行为。流解析器需要分割帧和取消。 UI 保存更改需要目标选择、请求失败、重试以及重新打开保存的状态。除了前端类型检查之外，本机命令还需要验证和生命周期行为。

保持检查与变化成比例。内容编辑需要导航/模板验证；他们不需要发明新的领域测试。通过的窄测试仅支持其断言的行为，因此包括更改的公共表面所需的包或集成检查。

贡献文档

该网站位于 packages/web。文档页面使用 DocsLayout、目录、部分标识符和共享代码/标注/相关链接组件。保留这些页面约定和现有的视觉设计，同时改进内容。

1. 阅读您记录的每个行为的实现、清单和配置。
2. 使用受支持的命令或请求形状并说明必要的工作目录、凭据、数据路径和本机先决条件。
3. 描述结果及其故障模式。将示例标记为示例；仅在实际捕获时调用捕获的响应。
4. 添加或重命名路线时更新导航和检索元数据，并将每个本地链接修复到旧位置。
5. 运行索引检查和 Astro 构建，然后检查渲染的页面及其锚点。

bun run --cwd packages/web check
bun run --cwd packages/web typecheck
bun run --cwd packages/web build

有关已配置 CI 的声明应说明工作流程的作用。关于成功发布或运行时接受的声明需要特定的运行/工件作为证据。文档应区分已实施的行为、默认值和限制，而不应将内部计划说明转变为产品说明。

拉取请求清单

• bun run typecheck 从根部传递。
• bun run test 通过；新行为在代码旁边有一个测试。
• 合同变更重新生成： bun run generate:check 和 bun run --filter @cadcamfun/web check 很干净。
• 架构更改包括生成的迁移文件夹，并且绝不会编辑已应用的迁移。
• Rust 变化通过 cargo clippy 和 cargo test （CI 两者都运行）。
• 用户可见的行为反映在描述它的文档页面中。

CI 在每次推送时运行相同的命令，因此绿色本地运行是绿色拉取请求的最佳预测指标。

在 3D