CSF

版本: v1.1 | 最后修订: 2026-07-07 | 项目: csf-core 🛡️ 规则语义变更须经Owner确认并全程记入日志。关键词: [cross-ref, 四形态, 声明兑现, 双向引用, 跨包, 责任分隔, 充分性验证] 适用场景: spec修改后cross-ref检查、新建跨包能力时、W-轻第2项

跨包责任分隔与 cross-ref

当一个业务能力被多个 spec / 多个域文件分别承载时，必须明确谁声明、谁兑现、谁验证，并通过 cross-ref 双向同步。

元约束：FLDD-开发执行.md §3 IT 设计 — 一致性 checklist 含跨主题包校验。

§ 1 四形态

按”声明方与兑现方”的关系分四种形态：

形态	关系	典型场景	cross-ref 方向
① 双向同期	A B 同期声明、同期兑现，互为前提	状态机定义 ↔ 各端 UI 页面同步实现	A ↔ B 双向引用，任一改动同期更新对方
② 下游声明 → 上游统一兑现	下游各自声明需求，上游统一实现	各模块声明计费规则 → 统一计费引擎汇总	上游文件列出”被本文件统一兑现的下游声明清单”
③ 上游兑现 → 下游引用	上游提供通用能力，下游按需引用	主框架提供回调接口 → 各模块调用	下游引用时显式标注”依赖上游 X 节”
④ 上游充分性验证	上游必须验证自己的实现覆盖全部已声明下游	回调接口是否覆盖全部调用场景	上游文件维护”全部已声明下游列表”+ 验证 checklist

§ 2 cross-ref 写法

每对跨包引用必须双向（除非显式标注为单向且原因说明）：

> 见 `模块A-spec.md § 3.2`（位于 {项目}/doc/domain/）
> 反向引用：见 `模块B-spec.md § 4.4`（位于 {项目}/doc/domain/）

禁止的写法：

❌ 只在 A 引 B，B 不知道被引（一次性改动易破）
❌ 引用具体行号（行号一变 link 即锈，必须引锚点 / § 号）
❌ 跨 git 仓库引用（不支持 IDE 跳转，必须落入同仓库）

§ 3 责任分隔判定流程

新建 / 修订一个跨包能力时按以下顺序判定：

画职责图：谁声明、谁兑现、谁触发、谁验证（四角色）
判形态：按 § 1 四形态对号入座
定 cross-ref：按 § 2 双向引用模板加锚点
跨包自检：所有声明方是否都被兑现方覆盖（W-轻 cross-ref 检查项）
更新索引：相关 spec 的 cross-ref 段同步更新

§ 4 示例模式（按形态分类）

以下示例描述每种形态的结构模式——声明方、兑现方、验证方各承担什么角色，cross-ref 怎么落。适配你的项目时，将模式中的角色替换为你的具体模块和文件。

§ 4.1 形态 ① 双向同期

模式：状态定义与多端 UI 同步
- 声明：domain/状态机定义.md 定义状态枚举和流转规则
- 同期兑现：spec/端A-页面.md + spec/端B-页面.md 各自实现同一状态机的 UI
- cross-ref：三个文件互引；任一文件改动状态枚举时，三方同步更新
模式：接口契约与多实现方
- 声明：domain/接口契约.md 定义数据结构和行为约定
- 兑现：多个模块各自实现该接口
- cross-ref：契约文件 ↔ 各实现方 spec 双向引用

§ 4.2 形态 ② 下游声明 → 上游统一兑现

模式：各模块声明需求 → 统一引擎汇总执行
- 下游声明：各模块 spec 内声明自己的规则/参数
- 上游兑现：统一引擎 spec 描述汇总和执行逻辑
- cross-ref：上游 spec 维护”全部声明本接口的模块清单”
模式：各模块注册钩子 → 框架串行调用
- 下游声明：各模块 spec 声明自己注册了哪个钩子
- 上游兑现：框架 spec 描述钩子链的串行执行逻辑
- cross-ref：框架 spec 列出”已注册该钩子的模块清单”

§ 4.3 形态 ③ 上游兑现 → 下游引用

模式：框架提供回调接口 → 各模块调用
- 上游兑现：框架 spec 定义回调接口（签名、时机、约定）
- 下游引用：各模块 spec 显式标注”调用上游 X 接口”
模式：数据模型定义 → 多模块复用
- 上游兑现：数据模型 spec 定义存储结构
- 下游引用：各消费者 spec 标注依赖的数据模型

§ 4.4 形态 ④ 上游充分性验证

模式：全部场景覆盖验证
- 验证表：上游 spec 维护 [声明方 → 场景 → 是否已兑现] 三列
- 自检：每新增一个声明方时回查验证表
模式：全部钩子覆盖验证
- 验证表：框架 spec 维护 [钩子名 → 注册方 → 执行位置] 三列
- 自检：每新增一个钩子实现时回查验证表

§ 5 反例（违反四形态的常见错误）

错误	后果	修正
下游各自实现”统一逻辑”（如各插件各自扣费）	计费规则散乱、改一处漏多处	改为形态 ②：下游只声明 feeDeclaration，上游统一兑现
上游随意修改接口签名	下游全部 silent broken	形态 ④ 验证表强制每次改签名时回查
cross-ref 单向	引用方改动后被引用方失忆	双向引用 + § 2 写法
引用具体行号	行号变 link 锈	改引 § 号 / 锚点

§ 6 与其他方法论的关系

关联	关系
W-协议.md § 4 W-轻第 2 项	spec 改完后必做 cross-ref 4 形态自检
FLDD-开发执行.md §3 IT 设计	一致性 checklist 包含跨主题包校验（即 cross-ref）
cos-context.md §A 收尾协议	收尾时检”涉及包是否同步更新 cross-ref”

This site is open source. Improve this page.