核心：__split 纯函数#

整个应用的计算逻辑收敛在一个函数里：

1
__split(totalCents, weights, ...rest) → number[]

作者给这个函数立了四条不变量（无条件成立）：

这四条不变量就是一份可执行的规格文档。不需要读实现，光看这四条就知道函数的行为边界。

最大余数法 + 零头集中#

分摊算法用的是最大余数法：

1
// 1. 权重预处理：NaN 和负数 → 0
2
// 2. 退化处理：权重总和为 0 → 全部置 1
3
// 3. 按比例取整：floor(总额 × 权重/总权重)
4
// 4. 零头分配：剩余零头全部给余数最大的人

举个例子，__split(101, [1, 1, 1])：

1
// floor(101/3) = 33, 33, 33 → 剩余 2 分
2
// 余数分别是 0.67, 0.67, 0.67（相等）
3
// 按下标从小到大，第一个承担全部零头
4
// 结果：[35, 33, 33]

为什么零头要集中给一个人？ 作者的理由很实用——房东一眼能看出每月零头算在谁头上。这是工程思维：算法上的「公平」（轮流承担）在这里不如「可解释性」重要。

防御性边界处理#

函数对异常输入的处理也很教科书：

1
__split(100, [0, 0, 0])     // 权重全0 → 均分 [34, 33, 33]
2
__split(50, [NaN, -1, 30])  // NaN/负数 → 0 → [0, 0, 50]
3
__split(-100, [1, 2, 3])    // 负金额 → 守恒=-100
4
__split(0, [5, 5, 5])       // 零金额 → [0, 0, 0]

每个边界 case 都有明确的行为定义，不抛异常、不返回 NaN。

架构：数据驱动 + 全量重渲染#

页面架构极其简单：

1
配置数据（PERSONS / BILLS / DAYS）
2
    ↓ input 事件
3
render() 全量重渲染
4
    ↓ 每笔账单调 __split()

没有框架、没有虚拟 DOM、没有状态管理。因为数据量小（3 人 × 4 笔账单），全量重渲染的性能完全够用。在正确的场景用正确的复杂度——这也是工程能力。

学到的三件事#

1. 不变量比实现重要。 先定义行为约束，再写代码，测试和 review 都有据可依。
2. 金额必须用整数（分）计算。 浮点数在金额场景是万恶之源。
3. 零头集中不是 bug 是 feature。 工程决策要考虑业务可解释性，不只是数学正确性。

项目地址：github.com/Melusine-ichnose/bill-splitter

项目结构：一个文件训练，一个文件推理#

仓库结构非常干净（来自 README.md）：

1
DeepStudy/
2
├── SY8.py     # 定义 CNN 模型，完成训练、评估、模型保存与样例可视化
3
├── test.py    # 加载已训练模型，对测试集图像进行预测并以 3×3 网格展示
4
└── README.md

训练和推理拆成两个文件，但模型定义只有一份——test.py 通过 from DeepStudy.SY8 import CNN 直接导入，而不是复制一份过来。这个选择后面再展开，先看模型本身。

网络定义：为 28×28 量身定制的尺寸推导#

模型定义在 SY8.py：

1
class CNN(torch.nn.Module):
2
    def __init__(self):
3
        super().__init__()
4
        self.conv1 = torch.nn.Conv2d(1, 32, kernel_size=3, stride=1, padding=1)
5
        self.conv2 = torch.nn.Conv2d(32, 64, kernel_size=3, stride=1, padding=1)
6
        self.conv3 = torch.nn.Conv2d(64, 128, kernel_size=3, stride=1, padding=1)
7
        self.fc1 = torch.nn.Linear(128 * 3 * 3, 128)
8
        self.fc2 = torch.nn.Linear(128, 10)
9
        self.pool = torch.nn.MaxPool2d(2, 2)
10
        self.dropout = torch.nn.Dropout(0.5)
11

12
    def forward(self, x):
13
        x = torch.nn.functional.relu(self.conv1(x))
14
        x = self.pool(x)
15
        x = torch.nn.functional.relu(self.conv2(x))
16
        x = self.pool(x)
17
        x = torch.nn.functional.relu(self.conv3(x))
18
        x = self.pool(x)
19
        x = x.view(-1, 128 * 3 * 3)
20
        x = torch.nn.functional.relu(self.fc1(x))
21
        x = self.dropout(x)
22
        x = torch.nn.functional.log_softmax(self.fc2(x), dim=1)
23
        return x

三个卷积层完全同构：3×3 卷积、stride=1、padding=1，也就是说卷积只换通道数、不动空间尺寸，尺寸全靠后面的 MaxPool2d(2, 2) 减半。于是空间维度的演化是一条确定的直线：

1
28×28 → pool → 14×14 → pool → 7×7 → pool → 3×3（向下取整）

理解了这条线，x.view(-1, 128 * 3 * 3) 里的 3 * 3 就不是魔法数字，而是 28 连续三次减半（下取整）的结果。代价是这个网络是为 MNIST 硬编码的——输入一变，flatten 处直接 shape mismatch。对一个专攻 MNIST 的教学项目来说，这种取舍完全合理，但如果你要把它迁移到别的数据集，这三处地方（三个 conv 通道数、fc1 的输入维度、view 的参数）得连着改。

另一个细节：Dropout(0.5) 只放在 fc1 之后，三个卷积层一个都没加。这是教科书做法——卷积层的参数在感受野内共享，本身自带正则化，而过参数化最严重的全连接层才是过拟合的重灾区，dropout 该花在刀刃上。

log_softmax + NLLLoss：一对老搭档#

forward 的最后一层是 log_softmax(self.fc2(x), dim=1)，而 main 函数里配的损失函数是：

1
#负对数似然损失函数
2
criterion = torch.nn.NLLLoss()

这两个必须成对出现：log_softmax 输出的是对数概率，NLLLoss 做的事情只有一个——取出真实类别对应的那个 log 概率，取负。合起来正好是交叉熵。

初学者常见的疑惑是：为什么不直接 Softmax + CrossEntropyLoss？因为 PyTorch 的 CrossEntropyLoss 内部本来就是 log_softmax + NLLLoss 的合体，如果先手动 Softmax 再喂 CrossEntropyLoss，等于 softmax 算了两遍，而且第一遍没有 log-sum-exp 的数值保护，大 logits 下容易溢出。这里的写法是”分开放”的流派：网络自己保证输出语义是 log 概率，损失函数只管挑类别。两种流派都对，唯独”Softmax + CrossEntropyLoss”这个直觉组合是错的。

训练循环：教科书五步，一个都不能少#

主训练循环同样在 SY8.py：

1
for epoch in range(5):
2
    running_loss = 0.0
3
    for i, (x, y) in enumerate(train_data):
4
        optimizer.zero_grad()
5
        output = net.forward(x)
6
        loss = criterion(output, y)
7
        loss.backward()
8
        optimizer.step()
9
        running_loss += loss.item()
10
        if i % 200 == 199:
11
            print(f"[{epoch + 1}, {i + 1}] 损失: {running_loss / 200:.3f}")
12
            running_loss = 0.0
13

14
    accuracy = evaluate(test_data, net)
15
    print(f"第 {epoch + 1} 轮准确率: {accuracy * 100:.2f}%")

zero_grad → forward → loss → backward → step 这五步是 PyTorch 训练的骨架，其中最容易被初学者漏掉的是第一步。PyTorch 的梯度默认累积：loss.backward() 是往参数的 .grad 上做加法，不清零的话，上一个 batch 的梯度会叠加进这个 batch，等于在用一个脏梯度更新参数。这个坑几乎人人踩过，这里写对了。

日志节奏也处理得克制：不是每个 batch 都打印，而是攒够 200 个 batch 打一次平均损失，然后把 running_loss 清零重新累计。每 200 个 batch 一次、每个 epoch 结束评一次准确率——信息密度刚好够观察训练是否收敛，又不至于刷屏。

优化器与学习率没什么花哨的：

1
optimizer = torch.optim.Adam(net.parameters(), lr=0.001)

evaluate：朴素但正确的评估#

1
def evaluate(test_data, net):
2
    n_correct = 0
3
    n_total = 0
4
    with torch.no_grad():
5
        for (x, y) in test_data:
6
            outputs = net.forward(x)
7
            for i, output in enumerate(outputs):
8
                if torch.argmax(output) == y[i]:
9
                    n_correct += 1
10
                n_total += 1
11
    return n_correct / n_total

两个值得说的点：

1. torch.no_grad() 包住了整个循环。 评估不需要梯度，关掉自动求导的图构建能省显存、提速。评估函数忘写 no_grad 是另一个经典失误，尤其配合 retain_graph 相关的显存爆掉问题。
2. 逐样本的 Python 循环很朴素。 每个输出挨个 argmax 再比较，其实一行向量化就能干完：(outputs.argmax(dim=1) == y).sum().item()。MNIST 上无所谓，但这是从”能跑”到”会写”的分界线，值得留意。

比实现本身更有意思的是 main 里的这个调用位置：

1
print("初始准确率:", evaluate(test_data, net))

训练还没开始，先评估一次随机初始化的网络。在 MNIST 十分类上，随机网络准确率应该在 10% 附近——正好是瞎猜的水平。这个 baseline 一举两得：既验证了评估函数没有 bug（如果初始准确率明显不是 10%，多半是评估或数据加载出了问题），又给后面每轮的 99% 一个”从哪爬上来的”参照。很小的习惯，但反映出的工程意识不小时。

test.py：推理侧的三个细节#

推理脚本 test.py 不长，但每一步都踩在正确的点上：

1
def load_model(model_path):
2
    model = CNN()
3
    model.load_state_dict(torch.load(model_path))
4
    model.eval()
5
    return model
6

7
#预测单张图像
8
def predict_single_image(model, image_tensor):
9
    with torch.no_grad():
10
        output = model(image_tensor.unsqueeze(0))
11
        prediction = torch.argmax(output).item()
12
    return prediction

细节一：state_dict 保存与加载。 训练脚本结束时用的是 torch.save(net.state_dict(), 'mnist_cnn.pth')——只保存参数张量，不 pickle 整个模型对象。这带来了推理侧的一个必然结果：必须先实例化一个同结构的 CNN()，再把权重灌进去。这是 PyTorch 官方推荐的保存方式，比 pickle 整个对象更可移植（不依赖源码路径和类定义的 pickle 兼容性）。副作用是模型定义必须单点维护，于是 test.py 用 from DeepStudy.SY8 import CNN 导入——定义只有一份，保存和加载永远不会漂移。

细节二：model.eval() 不可省。 训练时 Dropout(0.5) 会随机置零一半的激活，推理时如果忘了 eval()，dropout 还在随机丢，预测结果就是随机化的——99% 的准确率会瞬间掉到不可用的水平。这个 bug 不报错、能跑完，只是结果莫名变差，属于最阴险的一类。这里写对了。

细节三：unsqueeze(0) 补 batch 维。 从数据集里取出的单张图是 (1, 28, 28) 三维张量，而 Conv2d 只接受 (batch, channel, h, w) 四维输入，所以推理前要 unsqueeze(0) 补上 batch 维变成 (1, 1, 28, 28)。单样本推理和批量的维度差异，是写推理代码时最常见的报错来源。

顺带一提，README 专门写了这个项目必须这样运行：

1
# 在 DeepStudy 的父目录中执行
2
python -m DeepStudy.test

原因正是上面的包导入：from DeepStudy.SY8 import CNN 是包导入语法，直接在仓库目录里 python test.py 会 import 失败，必须从父目录以模块方式跑。README 把这个坑提前写清楚了，省了后来者一次报错。

值得学习的地方#

读完整仓源码，我认为有四点值得带走：

1. 闭环完整。 不到两百行，训练、评估、保存、加载、推理、可视化全都有，而且职责边界清楚：SY8.py 只管”从数据到权重”，test.py 只管”从权重到预测”。入门项目最怕只写训练不写推理，权重存下来就没人管了。
2. Baseline 意识。 训练前先测一次随机准确率，10% 的数字同时验证了评估函数和数据管线。以后写任何训练脚本，我都建议保留这一行。
3. 组合拳用得规范。 log_softmax + NLLLoss、dropout 只放全连接层、state_dict 保存、eval() 切推理模式——这些不是炫技点，而是保证结果可复现、推理不翻车的地基。
4. 把坑写在文档里。 python -m 的运行方式、初始准确率预期、每轮准确率预期，README 都提前交代了。代码短，文档不糊弄。

作为 MNIST 级别的入门项目，DeepStudy 没有任何多余的东西，也没有缺关键的东西——这大概就是对”标准训练范式”四个字最好的注解。

项目地址：github.com/Melusine-ichnose/DeepStudy

第一步：先用起来，再读源码#

永远不要在没有使用过某个框架的情况下直接读它的源码。

正确姿势：

1. 先阅读官方文档的 Quick Start，把 demo 跑起来
2. 在自己的项目里实际使用它，踩几个坑
3. 带着「它是怎么做到的」这个问题去读源码

只有真正用过，你才会对框架的能力边界有体感，读源码时才知道哪些模块是重点。

第二步：从宏观架构入手#

打开一个项目，不要急着钻进某个类里。先做三件事：

1. 看目录结构：src/main 下有哪些顶级包？通常包名就是模块划分
2. 看 README 和官方架构文档：作者通常会介绍核心概念和设计哲学
3. 看依赖关系：pom.xml / package.json 能看出它依赖了哪些底层库

以 SpringBoot 为例，顶级结构里 spring-boot-autoconfigure 就是自动装配的核心，spring-boot-starter-* 是各种场景入口。先建立这张「地图」，后面才不会迷路。

第三步：跟踪核心链路#

每个框架都有几条「生命线」级的调用链路。抓住它们，就抓住了框架的骨架。

• Web 框架：一次 HTTP 请求从进来到响应的完整链路
• ORM 框架：一条 SQL 从方法调用到数据库执行的链路
• RPC 框架：一次远程调用的序列化、网络传输、反序列化链路

具体做法：找到一个入口方法（比如 Controller 的接口），用 IDE 的「调用层次结构」（Call Hierarchy）功能一路向下追，画出时序图。

第四步：关注设计模式与取舍#

源码阅读的精华在于理解作者为什么这么设计：

• 这里为什么用策略模式而不是 if-else？
• 这里为什么用事件驱动而不是直接调用？
• 这里的缓存为什么要分两级？

推荐边读边记笔记，把这些设计决策摘录下来，思考能不能用到自己的项目里。

第五步：输出倒逼输入#

读完不写等于白读。输出的形式可以很多：

• 写一篇源码解析博客（就像本站的文章）
• 给项目提一个小的 PR（修 typo 也好）
• 模仿它的设计，自己写一个 mini 版本

以 LangGraph 为例，如果你想真正理解它的状态图编排，最好的方式是动手写一个简化版的 Agent 循环执行框架。写的过程中遇到的问题，会逼着你回头把源码彻底吃透。

推荐几个值得精读的项目#

读源码没有捷径，但有方法。希望这篇文章能帮你少走弯路。

一、模块划分：一个角色一个 API 服务#

先看顶层结构。仓库不是单体大杂烩，而是按角色切了模块：

1
admin          独立的管理端启动器
2
buyer-api      买家端接口
3
seller-api     商家端接口
4
manager-api    平台运营端接口
5
common-api     公共接口
6
consumer       消息消费者 + 定时任务
7
framework      实体、服务层等公共业务代码
8
im-api         即时通讯
9
xxl-job        分布式调度

业务代码几乎全下沉在 framework 里，三个 API 模块只是薄薄的 Controller 层。买家、商家、平台三个角色各走各的服务，物理上就隔离开了——商家端被打穿不会波及买家端。这个拆法在商城这类多角色系统里非常实用。

二、多商户的根基：Trade → Order 两级拆单#

多商户商城和普通商城最本质的区别是：一次下单可能跨多个店铺，必须按店铺拆单。这套代码的建模方式是”交易（Trade）- 订单（Order）“两级结构。

TradeDTO（贯穿下单流程的视图对象）里有两条线索。一个是平台券和店铺券分开建模（来自 TradeDTO.java）：

1
/**
2
 * 使用平台优惠券，一笔订单只能使用一个平台优惠券
3
 */
4
private MemberCouponDTO platformCoupon;
5

6
/**
7
 * key 为商家id
8
 * value 为商家优惠券
9
 * 店铺优惠券
10
 */
11
private Map<String, MemberCouponDTO> storeCoupons;

平台券一张订单只能用一张，店铺券按商家 ID 分组、每个店铺各用各的——优惠券体系从数据结构上就按”平台/商户”分了层。

拆单发生在购物车阶段：购物车里每个 CartVO 就是一个店铺的商品集合，下单时一个 CartVO 生成一个 Order。所以 Order 实体里直接冗余了店铺字段（来自 Order.java）：

1
@ApiModelProperty("交易编号 关联Trade")
2
private String tradeSn;
3

4
@ApiModelProperty(value = "店铺ID")
5
private String storeId;
6

7
@ApiModelProperty(value = "店铺名称")
8
private String storeName;

入库的实现在 OrderServiceImpl.java 的 intoDB，整个方法包在一个事务里：

1
@Override
2
@Transactional(rollbackFor = Exception.class)
3
public void intoDB(TradeDTO tradeDTO) {
4
    //检查TradeDTO信息
5
    checkTradeDTO(tradeDTO);
6
    //存放购物车，即业务中的订单
7
    List<Order> orders = new ArrayList<>(tradeDTO.getCartList().size());
8
    //存放自订单/订单日志
9
    List<OrderItem> orderItems = new ArrayList<>();
10
    List<OrderLog> orderLogs = new ArrayList<>();
11

12
    //循环购物车
13
    tradeDTO.getCartList().forEach(item -> {
14
        Order order = new Order(item, tradeDTO);
15
        orders.add(order);
16
        ...
17
    });
18
    //批量保存订单
19
    this.saveBatch(orders);
20
    //批量保存 子订单
21
    orderItemService.saveBatch(orderItems);
22
    //批量记录订单操作日志
23
    orderLogService.saveBatch(orderLogs);
24
}

而支付是按交易维度进行的，TradeServiceImpl.java 的 payTrade 把一笔交易下的所有订单逐个推进支付流程：

1
@Override
2
@Transactional(rollbackFor = Exception.class)
3
public void payTrade(String tradeSn, String paymentName, String receivableNo) {
4
    LambdaQueryWrapper<Order> orderQueryWrapper = new LambdaQueryWrapper<>();
5
    orderQueryWrapper.eq(Order::getTradeSn, tradeSn);
6
    List<Order> orders = orderService.list(orderQueryWrapper);
7
    for (Order order : orders) {
8
        orderService.payOrder(order.getSn(), paymentName, receivableNo);
9
    }
10
    ...
11
}

用户付一次钱，N 个店铺的订单各自流转各自的发货、售后。这就是 B2B2C 的”一次支付、拆单履约”。

三、价格计算：可编排的渲染流水线#

价格计算是商城里最乱的部分——商品促销、满减、优惠券、运费、佣金层层叠加，还要区分购物车展示、结算页、各种营销下单等不同场景。这套代码的解法我特别喜欢：把每一步计算做成一个 Bean，用数组声明流水线的顺序。

先定义步骤接口（CartRenderStep.java）：

1
public interface CartRenderStep {
2

3
    RenderStepEnums step();
4

5
    void render(TradeDTO tradeDTO);
6
}

然后每种场景声明自己的步骤组合（RenderStepStatement.java）：

1
/**
2
 * 交易创建前渲染
3
 * 渲染购物车 生成SN 》分销人员佣金渲染 》平台佣金渲染
4
 */
5
public static RenderStepEnums[] tradeRender = {
6
        RenderStepEnums.CHECKED_FILTER,
7
        RenderStepEnums.CHECK_DATA,
8
        RenderStepEnums.SKU_PROMOTION,
9
        RenderStepEnums.FULL_DISCOUNT,
10
        RenderStepEnums.COUPON,
11
        RenderStepEnums.SKU_FREIGHT,
12
        RenderStepEnums.CART_PRICE,
13
        RenderStepEnums.CART_SN,
14
        RenderStepEnums.DISTRIBUTION,
15
        RenderStepEnums.PLATFORM_COMMISSION
16
};

执行器是 TradeBuilder.java，利用 Spring 把所有 CartRenderStep 实现类注入成列表，再按声明的顺序依次调用：

1
private void renderCartBySteps(TradeDTO tradeDTO, RenderStepEnums[] defaultRender) {
2
    for (RenderStepEnums step : defaultRender) {
3
        for (CartRenderStep render : cartRenderSteps) {
4
            try {
5
                if (render.step().equals(step)) {
6
                    render.render(tradeDTO);
7
                }
8
            } catch (ServiceException e) {
9
                throw e;
10
            } catch (Exception e) {
11
                log.error("购物车{}渲染异常：", render.getClass(), e);
12
            }
13
        }
14
    }
15
}

不同场景复用不同流水线：购物车展示只要校验、促销、满减、算价四步；结算页要加上优惠券和运费；积分/砍价这类单品购买跳过满减；普通下单则要再追加流水号、分销佣金、平台佣金。新增一种营销玩法，写一个 CartRenderStep 实现类、往数组里插一个枚举就行，价格计算这个”重灾区”被治理得井井有条。

那段异常处理也值得品：ServiceException 是业务校验失败（比如商品已下架），必须中断下单直接抛出；而其他未知异常只记日志、继续渲染——展示购物车时一个非关键步骤挂掉不应该让整个购物车打不开。区分”必须失败的异常”和”可以带病运行的异常”，这是业务系统里很见功力的细节。

四、未支付订单的自动关闭：定时任务兜底#

和上一篇座位预约系统一样，这套代码对”应该发生但用户没做”的事情也用了定时任务兜底。订单超时未支付要自动释放库存、关闭订单，实现在 CancelOrderTaskExecute.java：

1
@Override
2
public void execute() {
3
    Setting setting = settingService.get(SettingEnum.ORDER_SETTING.name());
4
    OrderSetting orderSetting = JSONUtil.toBean(setting.getSettingValue(), OrderSetting.class);
5
    if (orderSetting != null && orderSetting.getAutoCancel() != null) {
6
        //订单自动取消时间 = 当前时间 - 自动取消时间分钟数
7
        DateTime cancelTime = DateUtil.offsetMinute(DateUtil.date(), -orderSetting.getAutoCancel());
8
        LambdaQueryWrapper<Order> queryWrapper = new LambdaQueryWrapper<>();
9
        queryWrapper.eq(Order::getOrderStatus, OrderStatusEnum.UNPAID.name());
10
        //订单创建时间 <= 订单自动取消时间
11
        queryWrapper.le(Order::getCreateTime, cancelTime);
12
        List<Order> list = orderService.list(queryWrapper);
13
        List<String> cancelSnList = list.stream().map(Order::getSn).collect(Collectors.toList());
14
        for (String sn : cancelSnList) {
15
            orderService.systemCancel(sn, "超时未支付自动取消", false);
16
        }
17
    }
18
}

三个细节：超时时长从系统设置表里读而不是写死在代码里，运营可以在后台调；查询条件是”状态 = UNPAID 且创建时间早于临界点”，扫描完逐单走统一的 systemCancel 流程（而不是直接改状态，保证取消副作用一致）；任务类实现 EveryMinuteExecute 接口，由 consumer 模块统一驱动。订单状态本身则收敛在 OrderStatusEnum：UNPAID → PAID → UNDELIVERED → PARTS_DELIVERED → DELIVERED → COMPLETED，外加待自提、待核验、已关闭，所有操作都翻译成状态流转。

五、下单事件：事务提交后再发消息#

下单成功后的积分扣减、砍价收尾、消息通知这些周边动作，没有塞在下单事务里，而是走 RocketMQ 异步。这里有个容易踩坑的时序问题：如果事务还没提交就把消息发出去，消费者可能读到不存在的数据。

TradeServiceImpl.java 的处理分两步。先把 TradeDTO 整体写进缓存，MQ 消息体只携带一个 key：

1
//写入缓存，给消费者调用
2
cache.put(key, JSONUtil.toJsonStr(tradeDTO));
3
applicationEventPublisher.publishEvent(new TransactionCommitSendMQEvent("订单创建消息", rocketmqCustomProperties.getOrderTopic(),
4
        OrderTagsEnum.ORDER_CREATE.name(), key));

TransactionCommitSendMQEvent 借助 Spring 事件机制，把真正的 MQ 发送推迟到事务提交之后——避免”消息先到、数据未落库”。消费者端 OrderMessageListener.java 再从缓存取回完整数据：

1
case ORDER_CREATE:
2
    String key = new String(messageExt.getBody());
3
    TradeDTO tradeDTO = JSONUtil.toBean(cache.getString(key), TradeDTO.class);
4
    boolean result = true;
5
    for (TradeEvent event : tradeEvent) {
6
        try {
7
            event.orderCreate(tradeDTO);
8
        } catch (Exception e) {
9
            log.error("交易{}入库,在{}业务中，状态修改事件执行异常", ...);
10
            result = false;
11
        }
12
    }
13
    //如所有步骤顺利完成
14
    if (Boolean.TRUE.equals(result)) {
15
        //清除记录信息的trade cache key
16
        cache.remove(key);
17
    }
18
    break;

注入的是 List<TradeEvent>——每个下游业务实现同一个事件接口，消费者遍历广播，谁都不依赖谁。任何一个业务失败就保留缓存 key 不删除，配合消息重试还能再跑一轮。订单状态变更（STATUS_CHANGE）同理广播给所有 OrderStatusChangeEvent 实现。

六、商家端的数据隔离：每个查询都带着 storeId#

多商户系统最敏感的问题是越权：A 商家能不能改 B 商家的订单？这套代码的答案是把”判断归属”做成了惯用法。商家端控制器 OrderStoreController.java 里，凡是按订单号操作的地方都先过一道 OperationalJudgment.judgment：

1
@GetMapping(value = "/{orderSn}")
2
public ResultMessage<OrderDetailVO> detail(@NotNull @PathVariable String orderSn) {
3
    OperationalJudgment.judgment(orderService.getBySn(orderSn));
4
    return ResultUtil.data(orderService.queryDetail(orderSn));
5
}

服务层内部则统一从 UserContext 取当前登录商家的店铺 ID 作为查询条件，比如核验自提订单：

1
String storeId = Objects.requireNonNull(UserContext.getCurrentUser()).getStoreId();
2
Order order = this.getOne(new LambdaQueryWrapper<Order>()
3
        .in(Order::getOrderStatus, OrderStatusEnum.TAKE.name(), OrderStatusEnum.STAY_PICKED_UP.name())
4
        .eq(Order::getStoreId, storeId)
5
        .eq(Order::getVerificationCode, verificationCode));

没有做复杂的行级权限框架，就是最朴素的原则：商家端所有查询都显式带 storeId 条件。防重复提交则统一挂在方法注解上（@PreventDuplicateSubmissions），发货、改价、取消这些写操作全都加了一遍。

值得学习的地方#

1. 按角色拆 API 服务，业务下沉 framework。 多角色系统的天然切分线就是角色，物理隔离比一堆 if-else 判断身份可靠得多。
2. Trade → Order 两级模型支撑拆单。 平台券/店铺券分层、订单冗余店铺信息、支付按交易、履约按订单，“多商户”不是一个字段，而是一整套建模。
3. 渲染流水线治理价格计算。 步骤即 Bean、顺序即数组，扩展营销玩法不改老代码；同时区分业务异常（中断）与系统异常（降级继续）。
4. 事务提交后再发消息 + 缓存中转大报文。 消息只传 key，时序正确性和消息体大小两个问题一起解决。
5. 数据隔离靠纪律而不是框架。 商家端每个查询显式带 storeId，归属校验做成 OperationalJudgment 这样的惯用法，简单但有效。

作为一个学习样本，它把 B2B2C 商城会遇到的典型问题——拆单、价格叠加、异步履约、越权防护——都给出了一种可参考的工程解法，值得通读一遍。

项目地址：github.com/Melusine-ichnose/Multi-merchant-Mall-System

一、座位状态机：用数字流转约束业务规则#

自习室座位的核心是一个状态机。reservation 表的 status 字段定义了完整流转：

这个设计的价值在于：所有业务操作最终都收敛为状态变更。

• 用户签到 → 0 → 1
• 用户暂离 → 1 → 3
• 用户回来 → 3 → 1
• 暂离超时 → 3 → 4
• 使用结束 → 1 → -1

每个状态变更都绑定一个副作用（释放座位 / 扣信用分 / 记违规），代码路径非常清晰。

二、TimerTask：异常场景的自动兜底#

系统最复杂的地方不是正常流程，而是异常场景。预约了不来怎么办？暂离了一直不回来怎么办？

项目的答案是 TimerTask 定时任务：

1
// 伪代码示意：预约超时未签到自动判违规
2
TimerTask checkSignTimeout = new TimerTask() {
3
    @Override
4
    public void run() {
5
        // 找到所有 status=0 且超过签到时间的预约
6
        List<Reservation> timeoutList = reservationMapper
7
            .findTimeoutReservations(now());
8

9
        for (Reservation r : timeoutList) {
10
            r.setStatus(2); // 未及时签到
11
            seatService.release(r.getSeatId());
12
            creditService.deduct(r.getUserId(), 10); // 扣信用分
13
            violationService.record(r.getId(), "超时未签到");
14
        }
15
    }
16
};

定时任务每 N 分钟扫一次，把「应该发生但用户没做」的事情自动补掉。这是典型的最终一致性思路——不依赖用户操作，系统自己兜底。

三、信用分：约束行为的奖惩机制#

信用分是这个系统里很巧妙的约束设计：

• 初始 100 分
• 超时未签到 → 扣分
• 暂离超时 → 扣分
• 教师可手动加/扣分
• 信用分过低 → 限制预约权限

它不是简单的惩罚，而是用分数门槛间接控制资源分配。分数低的人自动失去预约资格，不需要管理员手动拉黑。

前端：双 UI 库的组合#

这个项目的前端架构也值得注意：

• PC 端管理界面 → Element UI 2.15（给管理员/教师用）
• 移动端 H5 → Vant 2.12（给学生用）

同一套后端 API，根据设备类型加载不同的 UI 库。Axios 统一封装，通过 devServer.proxy 把 /api 代理到后端 9003 端口。

总结#

这个项目的复杂度不高，但异常处理的设计意识很到位。定时任务兜底、状态机约束流转、信用分约束行为，这三板斧在很多业务系统里都适用。

项目地址：github.com/Melusine-ichnose/Seat-Reservation-System

整体架构：一张循环图#

项目的灵魂在 app/agent/graph.py，整个 Agent 就是一张 LangGraph 状态图：

1
START → planner → executor → reviewer ┐
2
                      ▲               │
3
                      └── not done ───┤
4
                                      │
5
                      done → responder → END

对应源码（来自 graph.py）：

1
graph = StateGraph(AgentState)
2

3
graph.add_node("planner", planner_node)
4
graph.add_node("executor", executor_node)
5
graph.add_node("reviewer", reviewer_node)
6
graph.add_node("responder", responder_node)
7

8
graph.add_edge(START, "planner")
9
graph.add_edge("planner", "executor")
10
graph.add_edge("executor", "reviewer")
11

12
# 条件边：reviewer 决定继续执行还是收尾
13
graph.add_conditional_edges(
14
    "reviewer",
15
    _route_after_review,
16
    {"executor": "executor", "responder": "responder"},
17
)
18

19
graph.add_edge("responder", END)

四个节点的职责划分非常清晰：

状态设计：AgentState#

LangGraph 的核心思想是节点之间不直接传参，而是读写共享状态。app/agent/state.py 定义了这个共享状态：

1
class AgentState(TypedDict):
2
    messages: Annotated[list[BaseMessage], add_messages]
3
    user_query: str
4
    plan: list[str]
5
    current_step_index: int
6
    step_results: list[str]
7
    is_complete: bool
8
    final_response: str
9
    review_iterations: int  # 防死循环计数器

两个值得注意的设计：

1. messages 用了 add_messages reducer：LangGraph 默认对状态字段是覆盖更新，但 messages 声明了 reducer 后，每个节点返回的新消息会自动追加合并而不是覆盖，对话历史就这样自然累积起来了。
2. review_iterations 显式计数：这是防止 Agent 死循环的关键，后面详细说。

Reviewer：最值得学的节点#

app/agent/nodes/reviewer.py 是整个项目里工程思考最密集的部分。它要回答一个问题：当前步骤算完成了吗？

1
MAX_REVIEW_ITERATIONS = 12  # 单次图执行最大评审次数
2
MAX_STEP_RETRIES = 2        # 单步最大重试次数

1
if iterations >= MAX_REVIEW_ITERATIONS:
2
    return {"review_iterations": iterations, "is_complete": True}

1
step_retries = state.get("step_retry_count", 0) + 1
2
if step_retries >= MAX_STEP_RETRIES:
3
    # 强制推进
4
    return {"current_step_index": next_index, ...}

1
if has_done:
2
    is_step_done = True
3
elif has_continue:
4
    is_step_done = False
5
else:
6
    # 无法识别时默认完成（安全侧，防死循环烧 token）
7
    is_step_done = True

1
def _autocomplete_single_step(messages: list) -> bool | None:
2
    last = messages[-1]
3
    if isinstance(last, ToolMessage):
4
        if content.startswith("错误"):
5
            return None   # 工具失败，交给 LLM 评审
6
        return True        # 工具成功 → 完成
7
    if isinstance(last, AIMessage):
8
        if last.content and not last.tool_calls:
9
            return True    # Executor 已直接产出答案 → 完成
10
    return None            # 不确定 → 走 LLM 评审

Executor：工具调用的经典模式#

executor_node 展示了 LangChain 体系下标准的工具调用循环：

1
response: AIMessage = await llm.ainvoke(messages)
2
tool_calls = getattr(response, "tool_calls", None) or []
3

4
for tool_call in tool_calls:
5
    tool = next((t for t in tools if t.name == tool_call["name"]), None)
6
    if tool is None:
7
        content = f"错误：未找到工具 '{tool_call['name']}'"
8
    else:
9
        try:
10
            result = await tool.ainvoke(tool_call["args"])
11
            content = str(result)
12
        except Exception as e:
13
            content = f"工具执行错误: {e}"
14
    new_messages.append(ToolMessage(content=content, ...))

要点：工具的异常从不向上抛，而是包成错误文本写进 ToolMessage。这样 LLM 下一轮能「看到」工具失败了，有机会自己换参数重试或换个工具——把错误也变成 LLM 可利用的上下文。

学到的三件事#

1. Agent 的可靠性来自工程防护，不是 Prompt。 双计数器 + 兜底判定这些「无聊」的代码，才是生产环境和玩具 Demo 的分水岭。
2. 把 LLM 放在路径的关键决策点上，其他地方尽量不调。 单步快速通道省的是真金白银的 token 和延迟。
3. 状态图（StateGraph）天然适合表达 Agent 循环。 比起手写 while 循环，图结构让「评审不过就回到 Executor」这种回边表达得直白且可视化（配合 LangSmith 能直接看到每次循环的轨迹）。

项目地址：github.com/Melusine-ichnose/TaskWeaver