Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

贯穿案例：mini-shop

本目录定义全书共用的模拟案例包。案例不对应真实业务或真实仓库，目标是让不同章节复用同一组代码、同一组变更和同一组 Agent 任务。

案例目标

mini-shop 模拟一个极小的订单计价系统，覆盖本书主线：

源码结构 -> AST/符号/调用 -> 代码图谱 -> 变更影响面 -> Agent 上下文 -> 验证报告

它故意保持很小，但足够体现：

  1. 跨模块调用：order 依赖 pricing 和 payment

  2. 同名方法歧义：多处出现 save / calculate

  3. 测试关联：改计价逻辑会影响订单测试

  4. Agent 风险：只看局部文件时容易漏改调用方和测试

仓库结构

examples/mini-shop/
  README.md
  src/main/java/com/minishop/
    order/
      OrderController.java
      OrderService.java
      OrderRepository.java
    pricing/
      PricingService.java
      DiscountPolicy.java
    payment/
      PaymentClient.java
  src/test/java/com/minishop/
    order/
      OrderServiceTest.java
    pricing/
      PricingServiceTest.java

核心业务故事

用户创建订单时：

  1. OrderController.create 接收请求

  2. OrderService.createOrder 组装订单

  3. PricingService.calculateTotal 计算总价

  4. DiscountPolicy.apply 应用折扣

  5. PaymentClient.charge 发起支付

  6. OrderRepository.save 持久化订单

贯穿任务

任务 ID
场景
用于章节

T1

从 PricingService.calculateTotal 源码提取 AST

part2/source-to-ast

T2

解析 calculateTotal 的符号、参数类型和方法引用

part2/symbols-scopes-types

T3

构建 order/pricing/payment 调用图

part3/code-graph-model

T4

PR-42：修改折扣逻辑后的影响面分析

part4/change-impact-verification

T5

Agent 任务：调整 VIP 折扣，需要正确上下文包

part5/agent-context-engineering

T6

生成验证报告：相关测试、风险路径、查询轨迹

part6/ai-change-verification-report

PR-42 变更摘要

假设一次未完成修改：

  • 文件：pricing/DiscountPolicy.java

  • 目标：VIP 折扣从 0.9 改为 0.85

  • 风险：

    • PricingService.calculateTotal 直接受影响

    • OrderService.createOrder 间接受影响

    • OrderServiceTest 和 PricingServiceTest 需要更新断言

    • 日志文本中的 calculate 字符串不应被误判为调用

Agent 常见错误

如果 Agent 只读取 DiscountPolicy.java：

  1. 可能只改常量，不更新测试

  2. 可能不知道 OrderService 依赖该折扣结果

  3. 可能用字符串搜索误匹配日志文本

  4. 可能无法说明影响路径，导致 Review 无法审计

正确上下文至少应包含：

  • 目标符号：DiscountPolicy.apply

  • 直接调用方：PricingService.calculateTotal

  • 上层调用方：OrderService.createOrder

  • 相关测试：PricingServiceTest、OrderServiceTest

  • 架构约束：pricing 不应直接依赖 payment

使用约定

  1. 正文引用案例时统一写 mini-shop，不要另起一套虚构业务。

  2. 例子优先使用 Java，因为类型和声明结构更适合讲解 AST/符号。

  3. 如需对照其他语言，可补充 TypeScript/Python 片段，但不替换主案例。

  4. 所有报告、JSON、查询接口示例都应基于本案例的实体命名。

相关文件

标准产物（artifacts）

为便于各章引用同一输入输出，examples/mini-shop/artifacts/ 提供：

文件
用途

code-graph.json

最小代码图谱

pr-42.diff

模拟 PR Diff

impact-report-pr-42.json

影响面分析结果

agent-context-pack.json

Agent 上下文包

verification-report-pr-42.md

验证报告

后续写作与实践实现应以这些契约为准。

标准产物路径

产物
路径

代码图谱

examples/mini-shop/artifacts/code-graph.json

PR diff

examples/mini-shop/artifacts/pr-42.diff

影响面报告

examples/mini-shop/artifacts/impact-report-pr-42.json

Agent 上下文包

examples/mini-shop/artifacts/agent-context-pack.json

验证报告

examples/mini-shop/artifacts/verification-report-pr-42.md

正文与练习引用上述路径时，实体 ID 以图谱为准（例如 method:DiscountPolicy#apply）。

全书跟做主线（建议 90 分钟）

把下面顺序当作阅读/实践主线；各章细节都服务于这条链。

步
动作
打开的文件
对应章节

1

读关键路径与测试断言（180.0）

src/**、两个 Test

part2/part4

2

读 PR-42 diff

artifacts/pr-42.diff

part3 变更分析、part4 影响面

3

对照图谱实体与调用边

artifacts/code-graph.json

part3 图谱、part6 建图

4

对照影响面报告

artifacts/impact-report-pr-42.json

part4 影响面、part6 影响面实现

5

读 Agent 上下文包

artifacts/agent-context-pack.json

part5 上下文/查图

6

对照验证报告并理解人工确认项

artifacts/verification-report-pr-42.md

part5 Review、part6 验证报告

金标数字：

  • 折扣：0.9 → 0.85

  • 示例总价：180.0 → 170.0

  • 变更实体：method:DiscountPolicy#apply

  • 架构规则：pricing 不得依赖 payment

源码保持改前状态，便于你自己应用 diff 并复算。

Previous术语表
Next版本与勘误

Last updated