# 模块开发 ## 新建简单接口 ```sh pnpm module:new greeting pnpm format ``` 命令创建 `src/main/modules/greeting.ts`,在 `src/main/trpc/app-router.ts` 接入 router。接口的角色、输入、输出和执行函数在一个位置定义,不额外生成 contracts 路由或 handler 注册。已有模块和同名路由不会覆盖。带连字符的名字转换为驼峰命名空间,例如 my-tool 对应 trpc.myTool.echo。 生成的模块: ```ts import { z } from 'zod' import { router, procedure } from '../trpc/runtime' export function createGreetingRouter() { return router({ echo: procedure(['main']) .input(z.string().max(1000)) .output(z.string()) .query(({ input }) => input) }) } ``` Renderer 调用仍然是 `await trpc.greeting.echo.query('Hello')`。新增方法只修改模块;新增模块再接入一次应用组合。 ## 职责与依赖 | 位置 | 职责 | | --------------------------- | ----------------------------------------------------- | | contracts/src/.ts | 共享数据模型和 schema,例如 Settings、Note、FileGrant | | src/main/modules/ | 模块 router 和业务服务,直接调用,不按方法名二次分发 | | src/main/trpc/runtime.ts | context、角色中间件、统一错误处理 | | src/main/trpc/app-router.ts | 明确组合各模块 router | | src/main/trpc/events.ts | 组合类型化事件流 | | packages/desktop/rpc | 可信窗口、来源校验与请求容量 | | packages/electron-trpc | IPC 消息、订阅传输、取消与 listener 清理 | 复杂逻辑放在 service/repository 中,router 只负责边界校验和调用。factory 使用 `Pick` 声明依赖;主进程内部直接调用服务,模块不导入其他模块的注册实现。业务页面按子路径导入共享模型,例如 `@template/contracts/settings`。只有真正共享的模型需要添加到 contracts,过程专属 schema 就地定义。 每个 query/mutation 都声明 `.output(...)`,每个 procedure 用 `procedure(['main', 'settings'])` 明确授权角色。可用角色是 main/settings/about。缺失或不匹配的角色默认拒绝,修改授权属于安全变更,需更新权限回归测试。 renderer 只允许类型导入 `src/main/trpc/app-router.ts` 的 AppRouter,不能导入任何主进程运行时。客户端参数和结果由实际 procedure 推导。 共享外部依赖的固定版本放在 `pnpm-workspace.yaml` 的 catalog,各使用包显式声明 `catalog:`;peerDependencies 使用 `catalog:peers`,本地依赖使用 `workspace:*`。更新后执行 pnpm install 并提交 lockfile。 ## 事件 共享事件数据模型放在 contracts,在 events.ts 创建 `RpcEvent(schema)`。procedure 决定订阅角色,stream 负责校验每次载荷、按 owner 投递并复查来源: ```ts changed: procedure(['main']).subscription(({ ctx }) => events.files.subscribe(ctx)) // 主进程服务回调;窗口私有数据必须携带 owner。 events.files.emit(data, owner) ``` Renderer 使用 `trpc.files.changed.subscribe(undefined, { onData, onError })`,卸载时 unsubscribe。首次读数据前可等待 onStarted,避免初始化竞态。窗口刷新、关闭或传输销毁会自动退订;事件流自身也在根 Scope 中销毁。 ## 后台行为与资源清理 仅需要提供静态 API 的模块不注册生命周期模块。监听系统主题、定时任务等常驻行为使用 AppModule 并加入 `src/main/modules/index.ts` 的 lifecycleModules,声明依赖并用 scope.add 清理。它与 API router 组装分开,职责不会重复。带原生资源的 router factory 可以接收 Scope,例如菜单关闭回调。禁止在 import 时初始化数据库、注册 listener 或创建窗口。 不要提供凭据明文 IPC getter;需要凭据的业务请求在主进程执行,只向 renderer 返回允许展示的结果。意外异常统一脱敏;仅明确可公开的服务错误使用 PublicError。 ## 数据库与移除模块 数据库升级在 `src/main/migrations/index.ts` 追加连续版本;已发布迁移不可修改。业务 repository 属于对应模块,迁移由入口传给通用 SQLite 适配器。 从 app-router.ts 移除对应 router 即撤销 API。完全移除功能时,继续移除 UI、相关事件和后台模块;底层服务不再需要时,从 AppContext 和 bootstrap 删除构造与清理。用 pnpm check 和真实 Electron 测试验证,不以隐藏按钮代替授权撤销。