Files
marqdo/examples/code-as-docs/index.mq.md
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

135 lines
5.3 KiB
Markdown
Executable File
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
markup: occlusion
title: 代码即文档 · 周末咖啡手账
description: >-
一份可读可跑的周末手账:菜单是表,计价写在段落里,结账读起来像日记。
---
周六的咖啡馆手账——下面既是给人看的说明,也是可以 `marqdo run` 的程序。
**说明**性的加粗只是强调;真正算账的步骤也用粗体写在句子里,算完的值用斜体交回去。
---
## 单价
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 价 | any | 必填 | 同一币种下单件商品的标价 |
| 杯数 | any | 1 | 参与本次计价的杯数,未提供时使用正文默认值 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 逐行累加得到的订单总额 |
一杯标价为`价`的饮品,默认`杯数`=1。先把**总额 = 价 * 杯数**算清,再返回*总额*。
## 会员折
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 原价 | any | 必填 | 应用折扣之前的原始金额 |
| 折扣 | any | 0.85 | 价格乘数;0.85 表示支付原价的百分之八十五 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 下文显式返回的计算值或结构化结果;分支存在时遵循实际命中的分支。 |
会员单要原价`原价`;店里默认八五折,记作`折扣`=0.85。
先算**应付 = 原价 * 折扣**,再返回*应付*。
## 结账摘要
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 品名 | any | 必填 | 收据或摘要中显示的商品名称 |
| 价 | any | 必填 | 同一币种下单件商品的标价 |
| 杯数 | any | 1 | 参与本次计价的杯数,未提供时使用正文默认值 |
| 会员 | any | False | 是否采用本示例的会员折扣分支 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 包含商品、数量和实付金额的显示文案 |
客人点了`品名`,单价`价`,杯数`杯数`=1;是否`会员`=False。
按杯数问单价:**小计 = 单价 价=`价` 杯数=`杯数`**。
1. `会员`
我们先**实付 = [计算并保存 实付](会员折(原价=`小计`))**,供下一步使用。
我们先**标签 = "会员价"**,供下一步使用。
2. *
我们先**实付 = `小计`**,供下一步使用。
我们先**标签 = "原价"**,供下一步使用。
对账时拼成一句人话:
我们先**文案 = ((((((`品名` + " ×") + `杯数`) + " → ") + `标签`) + " ") + `实付`)**,供下一步使用。
完成上述步骤后,返回*文案*。
## 印章加一
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 印 | any | 必填 | 积分卡当前已有的印章数量 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 下文显式返回的计算值或结构化结果;分支存在时遵循实际命中的分支。 |
积分卡上的`印`,每喝一杯就**印 = 印 + 1**,接着返回*印*。
# main
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
这份手账把定价规则放在真正的结账函数里,入口只组织今天的几笔订单。菜单横表是品名到单价的记录,外卖行表则是多条带有数量和会员标记的订单;两者的数据形态不同,因此先按名称取价,再逐行传给同一个摘要函数。
会员示例与原价对照使用同一套参数和默认值,避免正文与实现各维护一份优惠规则。金额在本例中使用普通运行时数值,会员折扣可能产生小数;这里没有宣称采用专门的货币舍入模型。需要真实计费精度时应另行规定最小单位与舍入步骤,不能把展示摘要的文本当成准确记账凭证。
打印的是已经计算出的摘要,后续业务若要复用它应直接传递该值,而不是解析输出文字。最后给积分卡加一只改变演示中的印章值,不写入用户文件,也不代表某个真实账户已经更新。
今日黑板价目——表格给人扫一眼,程序当字典用:
`菜单` =
| 美式 | 拿铁 | 燕麦拿铁 |
|------|------|----------|
| 18 | 28 | 32 |
---
上午来了位会员,点两杯拿铁。品名写进`名`,价钱从菜单里取:
我们先**名 = "拿铁"**,供下一步使用。
我们先**价 = [名](access(`菜单`, `名`))**,供下一步使用。
我们先**摘要 = [计算并保存 摘要](结账摘要(品名=`名`, 价=`价`, 杯数=2, 会员=True))**,供下一步使用。
**打印 内容=`摘要`**
旁桌只要一杯普通美式,对照一下原价:
我们先**对照 = [计算并保存 对照](结账摘要(品名="美式", 价=[美式](access(`菜单`, "美式"))))**,供下一步使用。
**打印 内容=`对照`**
---
下午把外卖单抄成行表,一行一行结:
`今日订单` =
| @ | 品名 | 单价 | 杯数 | 会员 |
|---|------|------|------|------|
| 1 | 燕麦拿铁 | 32 | 1 | True |
| 2 | 美式 | 18 | 2 | False |
- [行](遍历 今日订单 为 行)
我们先**一行 = [计算并保存 一行](结账摘要(品名=[品名](access(`行`, "品名")), 价=[单价](access(`行`, "单价")), 杯数=[杯数](access(`行`, "杯数")), 会员=[会员](access(`行`, "会员"))))**,供下一步使用。
**打印 内容=`一行`**
打烊前给积分卡盖一个章:
我们先**印 = 41**,供下一步使用。
我们先**印 = [计算并保存 印](印章加一(印=`印`))**,供下一步使用。
**打印 内容=`印`**