# 模块目录：业务责任与工程落点提案

> 2026-10-01 · v0.1.0 · 规划提案，非已建工程或已批准ADR。  
> Wave归属只在[活动编排](WAVE-REQ-PORTFOLIO.md)维护；逐REQ目标在[范围卡](REQ-DETAILS.md)维护。本文回答模块有哪些、谁拥有事实、页面和代码放在哪里。

## 1. 目录的三个层次

1. **业务模块**按事实和办理责任划分；不按小程序、后台、控制中心分三套业务。
2. **使用入口**按任务组织。后台保留全局视野和客户下钻；控制中心处理通用运行机制；作业端登记受控现场事实。一个业务模块可以有多个入口，入口不能各自维护订单或资金状态。
3. **工程目录**隔离独立实现和分支写入范围。下面是目标路径提案，不代表仓库已有这些目录，也不确定微服务数量、数据库、队列或部署拓扑；S2形成正式架构后确认实际路径。

业务边界引用[上下文取舍](../architecture/07-bounded-context/BOUNDARY-DECISIONS.md)。模块不是一级菜单，REQ不是模块：同一模块可以跨多个wave增长；同一REQ可以包含多个Owner的协作，但不能互写源事实。

## 2. 业务模块目录

| 模块 / 事实Owner | 内部能力目录 | 用户和管理者从这里完成什么 | 实现责任前缀 |
| --- | --- | --- | --- |
| Identity 身份与权限 | accounts、organizations、roles、sessions、service-principals、service-areas | 登录、任职、角色/对象/字段范围、会话撤销、受限自动主体；不把账号停用当作客户资料删除 | `identity/` |
| Customer 客户与生活安排 | profiles、addresses、consents、meal-plans、personal-recipes、service-records、lifecycle、campaigns | 全局客户查找/下钻、地址同意、个人菜卡/餐次、服务沟通、合并/数据处理、团长活动关系 | `customer/` |
| Catalog 商品与经营内容 | media、products、specifications、recipes、publication、homepage | 商品规格、公共菜谱映射、媒体用途、首页编排与发布；不拥有售价、库存或在线个性决策 | `catalog/` |
| Supply 来源与质量 | receiving、lots、quality、ledger、availability、allocation、transformation、trace、recall | 到货证据、质量隔离/放行、物料去向/更正、可信可用性、加工守恒、公开追溯、召回影响 | `supply/` |
| Demand 配送安排与持续服务 | instructions、confirmations、capacity-promises、fee-policies、continuous-service | 一次配送的明确同意、服务接受与到期；消费原始能力；批准后维护长期合同/权益/周期 | `demand/` |
| Commerce 交易与售后 | pricing、benefits、checkout、orders、purchase-batches、funds、settlement、changes、aftersales | 从报价到成交、原款核验/额度、取消换单、实重结算、退款、分项售后；事实区分但同属交易责任 | `commerce/` |
| Fulfillment 作业与交付 | capacity、execution、workstations、measurements、packages、delivery、returns | 能力发布、开工/停止裁决、任务与采用重量、封包交接签收、回收事实 | `fulfillment/` |
| Finance 核算 | economic-sources、rules、posting、journals、periods、opening | 来源接收、会计解释、平衡分录、期间门禁、更正冲销、批准范围的期初交接 | `finance/` |
| Channel 外部销售适配 | providers、authorizations、mappings、observations、imports、outbound、statements | 渠道授权、观察映射、标准交易导入、回传未知恢复、外部账单观察；支付Provider仍归Commerce | `channel/` |
| Analytics 经营分析 | definitions、ingestion、projections、quality、rebuild、publication、exports | 可回源指标、质量解释、重建验证和受控导出；禁止修改商业或会计源事实 | `analytics/` |
| Platform 通用支撑 | commands、messages、jobs、audit、files、configuration、monitoring、response、automation、adapters | 持久原结果、消息恢复、证据可用性、审计、技术参数、通用监控响应和受控动作 | `platform/`，不是业务状态Owner |

### 仍需确定的两项归属

- **分享归因**：团长资格/活动关系已有Customer候选归属，但在线归因裁决、奖励及商业权益的Owner尚未确定。先收口来源证据和用途，REQ-DW-SHARE-ATTRIBUTION在S2确定裁决Owner后才创建对应写模块；不能暂塞Analytics再悄悄写业务。
- **推荐决策**：静态菜谱/编排归Catalog，个人偏好/同意归Customer。在线规则、实验分配和决策结果归属尚未定；REQ-DW-RECOMMENDATION-DECISIONS先定Owner，再确定工程目录。`decision-owner-pending`是规划状态，不能创建同名业务模块来掩盖未知。

## 3. 后台模块与办理入口

沿用[当前后台信息架构](../design/prototypes/admin-console/INFORMATION-ARCHITECTURE.md)，不增加“我的工作”、接待或交班作为顶层结构。全局经营概览是跨域只读组合，不建立第十二份事实。

| 后台任务组 | 核心办理入口 | 客户下钻中的对应内容 |
| --- | --- | --- |
| 交易 | 报价权益、订单及变更、原款、退款、售后 | 当前客户的订单/批次、资金去向、变更和售后；沿用同一详情与动作 |
| 配送安排 | 待确认/已确认安排、承诺/能力冲突、费政策 | 该客户未来各日安排、同意/受托依据、到期及未结结果 |
| 商品内容 | 商品规格、公共菜谱、首页媒体、发布回退 | 只引用购买或计划相关商品，不复制商品编辑权限 |
| 来源质量 | 到货、批次/物料去向、质量决定、追溯召回 | 与该客户订单/包裹有关的来源摘要和质量处置 |
| 作业交付 | 作业/称重、工位、包裹/配送、回收、能力 | 该客户任务与包裹证据；后台查看或受控复核不能伪造现场事实 |
| 客户 | 档案、地址偏好、菜卡/餐次、沟通事项、同意/资料处理、批准后的活动 | 客户上下文入口；沟通记录不代替售后裁决或配送授权 |
| 财务 | 经济来源、分录、更正、期间、规则、试算/期初 | 与客户交易相关的可授权查看来源，不向普通客服暴露完整财务账 |
| 渠道 | 授权映射、导入/回传、账单观察 | 外部来源与标准订单关联；限制外部账户和字段范围 |
| 经营分析 | 指标、质量、重建发布、导出 | 根据权限读取客户相关口径；不默认允许个体画像/跨用途分析 |
| 身份权限 | 员工任职、组织角色、区域范围、会话和服务主体 | 查询有效授权解释；客户上下文不授予身份管理权 |
| 系统支撑 | 能力目录、异常恢复、通知、文件、调度、参数、审计 | 关联该客户对象的原命令/事件/证据；没有业务授权就不能执行恢复写动作 |

页面按“列表定位→对象判断→动作预告→办理→查看结果/未结责任”组织。客户下钻只增加作用范围和返回上下文；菜单可见、敏感字段可见、对象可操作分别授权。控制中心另外挂载监控目标/策略/事件/自动化任务，引用同一对象和动作，不另做订单管理系统。

现有原型中的工作事项可作为通用未结责任对象，不能借此恢复个人工作台。菜单最终取舍以模块设计卡和实际任务为依据，不把上述子目录一律转成侧栏。

## 4. 目标工程目录

以下前缀供REQ规划引用，均为**拟建路径**。工程地基REQ负责确认包/工具接口与实际命令；领域REQ在S2/S4进一步给出文件级write_paths。现有`docs/design/prototypes/`、`docs/dev/`与`web/e2e/`继续作为各自文档/验证入口，不移动用户已有成果。

```text
apps/
  customer-miniapp/src/{app,modules}/     # 小程序自助与标准购买旅程
  admin-console/src/{app,modules}/        # 全局管理 + 客户下钻
  control-center/src/{app,modules}/       # 通用监控、响应、自动化
  operations-app/src/{app,modules}/       # 作业、设备、扫描和现场事实
services/
  business/                              # 业务代码承载区，不规定部署单元
    internal/modules/
      identity/ customer/ catalog/ supply/ demand/
      commerce/ fulfillment/ finance/ channel/ analytics/
    internal/platform/                   # 通用运行、监控与动作能力
    internal/experience/                  # 按入口组合查询/协议适配，不保存第二套事实
packages/
  model-bindings/                         # 生成的TS/Go绑定，源不是这里
  api-clients/                            # 同源接口消费者，分Owner生成输出
  surface-kit/                           # Foundation消费、布局/请求态/挂载接口
  contract-adapters/                     # 隔离Fixture、Stub、Fake及适配模式
docs/
  architecture/data-model/{common,<owner>}/  # 唯一原生JSON Schema + 样例
  architecture/state/                    # 既有状态主讲与可执行定义
  dev/contracts/                         # 各REQ的CONTRACTS/SYNC/FE/BE引用同一源
  dev/tasks/                             # 文件级责任、阅读清单、交接断言
  design/prototypes/                     # 模块当前stories/flows/场景/页面
database/migrations/{<owner>,platform}/   # Owner分路径，合并前分配全局执行次序
infra/{environments,security,observability,recovery}/
tests/{contract,integration,recovery}/    # 消费既有AC/CASE，不建立另一份分母
web/e2e/<module>/                        # 同模块当前UI验证，禁止按REQ另存副本
tools/{model-generation,build,development}/
```

`services/business/`是逻辑承载提案，不等于一个进程；Go module划分、api/worker入口和真实工具版本在工程/S2设计中确定。保留项目栈方向，不在需求规划擅定Go、Taro或React的具体版本。作业端目标包含移动/设备适配，具体现场客户端形式与设备能力要在相关REQ定案。

### 子模块使用约定

- 范围卡中的`B: commerce/orders`指`services/business/internal/modules/commerce/orders/`；`P: commands`指`services/business/internal/platform/commands/`。
- `C/A/X/O: <module>`依次指小程序、后台、控制中心、作业端的`src/modules/<module>/`。没有入口就明确写无页面，不机械铺四端。
- `M: <owner>/<slice>`指项目唯一模型区的该Owner切片。**是归属提案，不能生成一份REQ私有Schema**。对象实际定义与原生依赖闭包在相关S3收口。
- 领域模块按需要设置`domain/`、`application/`、`ports/`、`adapters/`，不为凑目录建空层；跨域只经公开接口、消息或只读查询，不能引用对方Repository写源表。
- 单端模块按`pages/`、`components/`、`queries/`、`commands/`组织实际需要的内容；DTO来自生成或边界验证，展示映射可以本地存在，但不得复制业务状态裁决。
- 模型区、生成配置、app根路由、数据库总次序、依赖锁文件、共享环境是受控公共路径。REQ卡列出有关模块并不授权自由修改这些共享文件。

## 5. 源、输出和文档责任

| 产物 | 唯一主讲 | 谁可以改变 | 消费方怎么获得 |
| --- | --- | --- | --- |
| 字段/类型/合法结构 | 项目原生模型及既有状态定义 | 对应事实Owner，公共类型归共享基线责任 | FE/BE/SYNC精确引用，同源生成或边界验证 |
| 操作/时序/错误/恢复 | 当前REQ的SYNC，跨REQ共享操作遵守同一源 | 命令Owner；变更审查全部消费者 | CONTRACTS声明Operation/Slot及依赖闭包 |
| 布局与任务呈现 | Foundation + 模块当前设计包 | 布局责任维护挂载槽；业务REQ维护模块内容 | 端侧消费语义token、公开接口和当前场景 |
| 域状态/资金/现场事实 | 各Owner的命令与持久事实 | 有权限且满足守卫的Owner命令 | 查询/事件/投影；禁止后台或引擎直接改表 |
| 生成Client/绑定 | 从上述原生源生成 | 指定生成责任，分Owner输出 | 下游固定版本；禁止手工改生成字段 |
| 业务组合入口 | 显式组合Owner | 见范围卡/交接计划 | 其他REQ只交付组件/公开能力，不共改页面根 |

## 6. 为什么这样分，何时重开

采用按域共用模型、各端独立入口的布局，便于同域功能一次联调、单个客户下钻复用全局详情、资金/物料/现场各自守恒。代价是公开操作和组合责任必须提前说明，不能只靠目录自然保证隔离。

按系统复制整个业务会产生多份状态/规则；按41个REQ建永久代码目录会把一次开发批次变成业务边界；按十域立即部署十个服务会过早增加运行责任。当前都不选。真正出现独立不变量、部署/团队需求或不可维护依赖时，回S2审查边界与迁移，不凭菜单或分支数量拆服务。

待验证：仓库还没有正式产品骨架；数据库/队列/部署及多REQ控制面隔离尚未确定；在线归因/推荐Owner未定。主会话维护目录提案，工程/各域/集成负责人在实际执行前落实；源码落点变化同步范围卡、TASK和消费者，不隐式改冻结合同。