# skill:新增 muse-module 业务模块(BC)

> **类型**:操作手册(skills) · **关联门禁**:[`../rules/bc-boundaries.md`](../rules/bc-boundaries.md)、[`../rules/contract-first.md`](../rules/contract-first.md)
> **何时用**:新增一个**业务域 BC(逻辑 owner)**。先确认确属新 BC(逻辑 owner 优先,勿与既有 7 BC 重叠,见 [`../knowledge/project-and-architecture.md`](../knowledge/project-and-architecture.md));复杂域先走评审版 spec。

---

## 标准步骤(参照既有 `muse-module-meta` 布局)

1. **建两子模块** `muse-cloud/muse-module-<x>/`:
   - `muse-module-<x>-api`:对外契约(DTO / ErrorCode / facade-api 接口),供他域**只读**消费。
   - `muse-module-<x>-server`:实现。父 pom 聚合两者(参照 `muse-module-meta/pom.xml`)。
2. **server 包结构对齐既有**(`cn/iocoder/muse/module/<x>/` 下):`controller`(admin/app)、`application`(service + facade 实现)、`dal`(dataobject + mysql Mapper)、`domain`、`convert`、`enums`。
3. **DB 迁移**:新增 `muse-cloud/sql/muse/V<下一版本>__<描述>.sql`;**切勿编辑历史迁移**。`ContractFirstGateTest` 会校验版本唯一 / 连续 / 命名 `V<版本>__<描述>.sql`。
4. **API 契约(契约先行)**:建 `docs/api-contracts/<x>/openapi.yaml`(OAS3,含 `openapi/info/paths`),并把 `"<x>"` 加入 [`ContractFirstGateTest.REQUIRED_API_DOMAINS`](../../muse-cloud/muse-server/src/test/java/cn/iocoder/muse/server/framework/contract/ContractFirstGateTest.java)(机械要求该域契约长存)。
5. **注册依赖**:在 [`muse-server/pom.xml`](../../muse-cloud/muse-server/pom.xml) 加 `muse-module-<x>-server`(参照既有 dependency 块)。
6. **守 BC 边界**:**不得 import 他域 `.dal`**;跨 BC 只走对外 API / facade-api。[`BcBoundaryArchTest`](../../muse-cloud/muse-server/src/test/java/cn/iocoder/muse/server/framework/arch/BcBoundaryArchTest.java) 机械兜底(新违例=红)。明确本域只产 Shadow 还是可写 Canonical,遵守双轨主权与 owner 写入边界。
7. **测试**:Mockito 单测(`BaseMockitoUnitTest`)覆盖业务分支;真库 / 真外部场景加 `*IT.java`(见 [`golden-journey-vertical-slice.md`](golden-journey-vertical-slice.md))。
8. **本地验证(JDK21)**:`mise exec -- mvn -B -pl muse-server -am test`(单构建,勿并发——并发写同一 `target` 会致 `NoSuchFileException` 假错);随 CI 阻断。

---

## 收尾沉淀
- 更新 [`../knowledge/project-and-architecture.md`](../knowledge/project-and-architecture.md) 的 BC 表(新增一行)。
- 维护该模块 `.agent`(目标 / 边界 / out-of-scope / 现状 / TODO;机制建设中)。
- 如该域需保持 completed 台账纪律,纳入 `P1rApiCoverageReportTest` 口径。