模块档案

模块档案是给人和 AI 共用的当前事实说明书。它回答：模块现在负责什么、拥有哪些对象、真实入口在哪里、哪些边界不能突破、改完如何验证。

历史不再堆在 module.md 里。每个模块只有一个集中日志：docs/changelogs/<module_key>.md；模块页和机器索引只保留 changelog_path 与 changelog_time。

什么时候用

场景	模块档案怎么帮忙
任务上下文过大或不明确	用 module_key、页面路径、API 路径和源码路径缩小上下文。
同一页面牵涉多个领域	写清唯一 owner、消费关系、上游、下游和禁止双写边界。
目标设计容易被当成现状	同时记录 current key、target key、证据等级和迁移出口。
需要追溯长期变化	按 changelog_path 读取集中日志，不在模块页复制历史。
项目模块还不确定	先登记候选和 pending_confirm，不把猜测写成正式事实。

推荐目录

.maw/modules.yaml
docs/modules/
  README.md
  <module-key>/
    module.md
    ai-context.md        # 可选
    route-api-index.md   # 可选
docs/changelogs/
  README.md
  <module-key>.md

三类文件各有唯一职责：

• .maw/modules.yaml：机器定位索引、当前证据和目标迁移映射。
• docs/modules/<module-key>/module.md：当前事实、安全边界、入口、验证和迁移出口。
• docs/changelogs/<module-key>.md：长期 material history。

复杂模块可以按需增加 pages/、backend/ 或 traceability.md，但这些是证据维度，不是新的正式模块。

最小 module.md

---
doc_key: docs.modules.order-list
doc_type: module
stage: v2
status: active
product_version: "2.0"
fact_mode: current
---

# 订单列表

> 当前实现：migrating
> 目标模块：`order-management`

## 1. 模块身份与证据

- module_key: `order-list`
- doc_status: confirmed
- confidence: high
- last_verified_commit: `abc1234`

## 2. 用户价值与当前基线

- 用户任务：查看、筛选订单并进入详情。
- 当前可用：按状态筛选、分页和详情跳转。
- 外部未验证：第三方物流状态联调。

## 3. 领域所有权

- 本模块拥有：订单查询 view model 与列表交互。
- 本模块消费：订单主账本的只读 projection。
- 本模块不拥有：支付、退款、发票和物流状态机。

## 4. 入口与契约

- 用户入口：`/orders`
- API prefix：`/api/orders`
- 代码根：`code/client/src/pages/orders`

## 7. 验收与验证

- 正常路径：筛选、分页和详情跳转。
- 权限与越权：跨组织订单不可见。

## 8. 2.0 迁移状态

- 目标 module_key：`order-management`
- 退出门：API、对象和表族拥有唯一 owner。

## 变更日志引用

- changelog_path: `docs/changelogs/order-list.md`
- changelog_time: `2026-07-12T10:00:00+08:00`

模块页不需要复制完整文件、operation 或表清单；机器索引负责精确定位，模块页解释长期有效的语义和边界。

modules.yaml 示例

schema_version: 2
modules:
  - key: order-list
    name: 订单列表
    type: leaf
    doc: docs/modules/order-list/module.md
    changelog_path: docs/changelogs/order-list.md
    changelog_time: "2026-07-12T10:00:00+08:00"
    source_paths:
      - code/client/src/pages/orders/**
      - code/server/src/routes/orders/**

changelog_time 必须是带时区 ISO 8601，只在集中日志内容实际变化时更新。只读检查、重复执行和普通措辞调整不刷新时间。

集中 changelog 怎么写

集中日志只记录会影响长期理解或兼容性的实质变化：

• 产品或领域边界；
• API、事件或数据兼容；
• 状态机、权限和安全约束；
• 数据迁移；
• 发布、回滚或交付语义；
• 模块合并、拆分、重命名、废弃或替代。

例行样式、小修复、测试补充和一次性执行流水由 Git 历史追溯，不写成长篇模块日志。

旧项目自动迁移

执行模块规则前先检查：

python3 ops/scripts/migrate-module-changelogs.py plan --format json

如果发现模块目录内的旧日志、机器索引旧字段或 module.md 内嵌历史，规则执行者会自动迁移，不要求用户逐份搬运：

python3 ops/scripts/migrate-module-changelogs.py migrate --execute --format json
python3 ops/scripts/migrate-module-changelogs.py check --format json

迁移会先合并去重，再写集中日志和新引用；全部写入成功后才删除旧格式。无法唯一归属或内容冲突时 fail closed。第二次执行必须是零变更。

常见错误

错误	修正方式
每个按钮都建一个模块	先按业务能力或页面/API 组合建模块。
模块档案只写目标愿望	写当前事实，并把 2.0 目标放入迁移状态。
Product Shell 重复声明领域 owner	Shell 只组合页面，领域模块拥有对象、API 和表族。
在模块页复制逐日历史	将 material history 写入集中日志。
旧项目手工搬日志	运行自动迁移器并做零变更复检。
改页面/API 后只改代码	同步模块事实；实质变化再更新集中日志。

下一步

继续阅读 内置指令，了解如何用 #模块地图、#模块发现 等短语维护模块结构。