fmode-code-lit/.claude/rules/modules

模块划分最佳实践

无构建项目最容易「长成一坨」：所有组件堆在 components/、所有逻辑塞进一个超大 service。 本篇给出功能模块 / 通用能力 / 业务模块的拆分准则与落地目录。

一、三种模块，三种归属

类型	定义	归属	是否可跨项目
通用能力（util skill）	与业务无关的纯能力：http、storage、format、debounce	utils/	✅ 可抽成包托管 Repose
通用组件（UI kit）	与业务无关的可复用 UI：弹窗、表格、表单、布局壳	components/	✅ 可抽成组件库
功能模块（feature）	一块完整业务功能：用户管理、订单、报表	modules/<feature>/	❌ 业务专属

判别法：换一个业务项目，它还有用吗？ 有用 → 通用（utils/components）；没用 → 功能模块。

二、推荐目录（功能模块化）

src/
  app.js
  components/                 # 跨模块通用 UI
    app-shell.js
    tabs-bar.js
    base-table.js
  modules/                    # 功能模块（一块一块业务）
    user/
      page-user-list.js       # 页面组件
      page-user-detail.js
      user-service.js         # 模块内 service
      user-model.js           # 模块内数据结构/转换
    order/
      page-order-list.js
      order-service.js
  services/                   # 跨模块共享 service（全局状态）
    auth-service.js
    dict-service.js
  utils/                      # 通用能力
    http.js
    storage.js
    format.js
  index.html

规则：

• 模块内聚：一个功能模块的页面、service、model 放在同一目录，便于整体搬走 / 整体删除。
• 跨模块共享才上提到 services/（如 auth、字典、权限）。
• 通用 UI 才留在顶层 components/；只在某模块用的组件放在该模块目录内。

三、模块的对外契约

一个功能模块只暴露页面组件（供路由挂载）与必要的 service。内部实现（子组件、model）不外泄。

modules/user/
  index.js            # 可选：统一出口
    export { PageUserList } from './page-user-list.js';
    export { userService } from './user-service.js';

• 别的模块不要深挖 modules/user/内部子组件.js。
• 需要跨模块调用的，通过模块出口或上提的共享 service。

四、Service 的粒度

粒度	例子	归属
全局域（登录、权限、字典）	auth-service	services/
模块域（仅本模块用）	user-service	modules/user/
❌ 万能 service	app-service（什么都塞）	拆掉

• 一个 service 一个关注点。
• 模块 service 若被第二个模块需要 → 上提到 services/（上提，而非复制）。

五、什么时候抽到 Repose（组件库 / 能力包）

满足全部以下条件才抽：

1. ≥2 个项目在用；
2. 接口稳定（属性/事件契约不频繁变）；
3. 无业务耦合（不依赖具体业务 model / 接口）。

抽出的产物：

• UI 组件库：一批 kebab-case 自定义元素，托管到 FMODE Repose，业务用 importmap 引入。
• 能力包：http、storage 等 utils 打成 ESM 包。

抽早了是负担。先用项目内 components/ utils/ 沉淀，稳定后再上提。

六、依赖方向（严格单向）

routes/modules  →  components  →  services  →  utils
       │                │              │
       └────────────────┴──────────────┘   禁止反向

• 上层可依赖下层，下层禁止反向依赖上层。
• utils 不认识 services / components。
• services 不 import Lit / 组件。
• 反向依赖一旦出现，说明职责放错了层。

七、模块划分 checklist

• 换业务就失效的代码，是否都收在 modules/<feature>/ 里？
• 跨模块共享的状态是否上提到 services/（而非每个模块各存一份）？
• 通用 UI 是否在 components/，且不 import 任何业务 model？
• 依赖方向是否单向（无 utils → services 之类的反向 import）？
• 是否有「万能 service / 万能组件」需要拆？
• 满足复用条件的组件 / 工具，是否已考虑上提 Repose？

八、反模式

反模式	症状	修复
上帝 service	一个 service 上千行，改哪都怕	按关注点拆分
组件内联业务	页面组件里 assert 校验 + fetch + 拼接口	逻辑下沉 service
utils 有状态	utils 里存了「上次结果」	移到 service
复制粘贴跨模块	两个模块各有一份 tableservice	上提共享
过早抽象	只有一个用户就搞组件库	先项目内沉淀