oak-general-business

oak-general-business 是 Oak 框架的公共业务包，提供账号、应用、系统、登录令牌、用户关系、OAuth、消息通知、邮件短信模板、微信、文件/COS、共享前端组件与 feature 等通用能力。

这是一个 Oak business module，通常被业务应用通过 file:../oak-general-business 或包依赖方式消费。改动这里的代码应保持跨项目通用；只服务于单个业务应用的页面样式、路由或业务规则应放在消费端项目中。

主要目录

• src/entities：实体定义，是 schema、动作、状态、关系、索引和样式元数据的源头。
• src/oak-app-domain：由 Oak 生成的领域类型和元数据，通常通过命令重新生成。
• src/aspects：后端可调用的业务 API，例如登录、token、OAuth、应用配置等。
• src/features：前端 feature 组合与运行时状态，例如 application、token、extraFile。
• src/components：可复用 UI/Oak 组件，供消费端页面组合使用。
• src/endpoints、src/triggers、src/watchers、src/timers、src/routines：后端入口、生命周期逻辑和后台任务。
• src/registry.backend.ts、src/registry.frontend.ts：包级扩展注册入口。
• src/configuration/dependency.ts：当前应保持为空，除非本包确实新增 Oak 包级依赖。
• template：消费端项目初始化时复用的模板。
• test：现有测试与临时验证脚本。

常用命令

npm run make:domain
npm run build:lib
npm run build:es
npm run build
npm run test:build
npm run test:build:frontend
npm test
npm run test:token

常见验证顺序：

1. 修改实体或领域元数据后，先运行 npm run make:domain。
2. 修改共享包源码后，运行 npm run build:lib 和 npm run build:es，确保消费端使用的编译产物同步。
3. 修改前端 feature 或组件后，至少运行 npm run test:build:frontend。
4. 修改后端 aspect、trigger、endpoint、routine 等逻辑后，至少运行 npm run test:build，并补充相关 focused test。
5. 如果消费端通过 file:../oak-general-business 链接本包，先重建本包，再验证消费端应用。

开发注意事项

• 优先从 src/entities 和生成的 src/oak-app-domain 确认类型、动作、关系名和过滤条件，不要猜 Oak 生成结构。
• 共享包只承载可复用能力；消费端专属页面、路由、样式和业务规则不要放进本包。
• 前端用户可见文案优先走 locale，不要随意硬编码。
• 改动 generated domain、locale 或依赖组合时，使用 Oak 命令重新生成，不要手工修补生成产物。
• src/configuration/dependency.ts 是 Oak 组合文件，不是普通占位文件；没有真实包级依赖时不要添加内容。
• 提交前必须执行 git status 检查暂存区，确认没有误提交敏感配置。

敏感配置

以下文件或同类包含密码、密钥、token 的配置文件不应被暂存或提交：

• configuration/mysql.json
• configuration/mysql.*.json
• configuration/postgres.json
• configuration/postgres.*.json

如果发现敏感文件被暂存，先取消暂存再继续提交流程。