二开约定

新增业务模块时

建议按下面顺序落地：

1. 明确业务域和菜单归属
2. 先补数据结构和状态机
3. 再补后端接口与领域服务
4. 最后补前端页面、按钮权限和文档

不建议的做法

• 把项目业务能力直接塞进框架通用模块
• 让上传、回调、通知等链路共享一套不清晰的状态字段
• 前端页面命名和后端领域名完全脱节

比较稳妥的边界

• 业务服务放在 app/Domain/<Topic>/
• 控制器只做鉴权、参数接收和响应组装
• 仓储只负责数据访问，不承载复杂业务规则
• 异步通知、推送和回调单独建任务或服务

文档同步要求

每次新增一个稳定业务模块，至少同步这几类文档：

• 使用手册中的操作页面
• 开发文档中的模块地图
• 涉及的配置项
• SQL 或数据变更说明