# 小卖部经营沙盘

在模拟环境里让 AI（或你自己）经营一家社区小卖部，改变条件、重复实验，用来检验学术想法。
规则的唯一依据是 [docs/RULES.md](docs/RULES.md)，所有参数在 [config/default.yaml](config/default.yaml)。

## 常用命令

```bash
python3 -m sim.server                 # 打开网页 http://localhost:8765（回放、报表、实验对比、亲自经营）
python3 -m sim.run --format independent --seed 1          # 跑一次并保存回放（format: independent / franchise_light / franchise_share）
python3 -m sim.run --set store.area=60 market.residents=3000   # 改任意参数（点号路径）
python3 -m sim.experiment experiments/demo_checkout_display.yaml   # 跑一组对照实验
python3 tests/test_engine.py          # 引擎与会计自检
python3 tools/month_trace.py          # 按月看爬坡轨迹和校准指标
python3 tools/response_check.py       # 响应检验：模型的因果效应 vs 实证范围
python3 tools/sensitivity.py          # 全局敏感性分析（约 10 分钟）
python3 tools/price_curve.py          # 价格倍数 vs 利润（检查内部最优）
```

## 模型是怎么保证"准"的

- **参数**尽量用真实数据：居民按户生成（七普户规模、年龄、性别；城镇就业；收入五等份；分性别吸烟率），店铺端对齐 CCFA 便利店数据，成本用公开价格。每个关键参数的来源和可信度见 `config/params_meta.yaml` 和网页「参数影响」页。
- **函数关系**用实证效应检验：`python3 tools/response_check.py` 测"改 X，结果变多少"（短期/长期提价、竞争店开张、疫情、雨天、气温、陈列、差评），和文献范围比较，目标与出处在 `config/response_targets.yaml`。
- **哪些参数最要紧**：`python3 tools/sensitivity.py` 做全局敏感性分析（Morris 法），找出影响最大的参数；影响大又只能靠假设的参数，研究结论要对它做敏感性检验。
- **城市预设**：默认是典型中国城市社区；研究某个城市用 `config/regions/`（杭州、苏州、上海）。
- 数据缺口见规则文档第 14 节。

## 财务

经营所得税（个体工商户查账征收，200 万以内减半）、店主每月取生活费、经营贷（等额本息）、转让门店或退租关店、租约到期续约涨租。
店长动作：`loan: {amount, months}`、`exit: transfer | close`；网页「亲自经营」→「融资与退出」。

## 训练模型店长

```bash
python3 -m sim.rl train --gens 40 --out models/rl_econ.npz           # 训练神经网络店长（约 45 分钟，3 进程）
python3 -m sim.rl train --fixed --gens 25 --out models/fixed_econ.npz # 训练"调优固定策略"对照
python3 -m sim.rl curve models/rl_econ.npz                            # 用固定验证年份给各代考试（成长曲线）
python3 -m sim.rl eval models/rl_econ.npz --seeds val                 # 验证年份 201–230，用来选代、调参
python3 -m sim.rl eval models/rl_econ.npz --seeds test                # 考试年份 101–130，最终报告只用一次
python3 -m sim.rl eval models/rl_econ.npz --perturb '{"market.beta_d": 1.2}'   # 换市场参数重考，查是否钻漏洞
```

- 店长每周日读经营快照，定 6 个策略参数（两类价格、临期折扣、备货倍数、开关门时间），每天的订货由补货规则执行。
- 训练算法是进化策略：每代复制 16 个略有不同的店长，各经营 2 个随机年份（含随机突发事件），往赚得多的方向挪一点。
- 网页「店长训练」页：成长曲线（实时刷新），以及让第几代店长和规则版店长经营同一年、并排对比决策和利润。
- 训练目标可选 `--objective economic_profit | net_profit | revenue | survival`，不同目标会练出性格不同的店长。
- 在实验里用模型店长：`manager.type: rl`，`manager.rl_policy: models/rl_econ.npz`。
- 环境接口 `sim.rl.StoreEnv`（reset / step，与 Gymnasium 相同），可以接 PPO 等算法做对比。

## 突发事件

`events.list` 固定日程（做实验），`events.random: true` 随机抽取（类型、日期、强度都随机，强度范围在 `events.ranges`）。
九种：新店开张、涨租、门前施工、供应中断、疫情封控、价格战、热浪、差评、失窃激增；另有对手反击（份额过高时对手降价）。
`python3 tools/event_check.py` 逐个检查事件效果。

## 怎么做一个新实验

复制 `experiments/demo_checkout_display.yaml`，在 `groups` 里写每组要改的参数（点号路径，同 config），
`runs` 是每组重复次数（各组共用种子 1..runs，按种子配对比较），`primary` 事先指定主要指标（其余指标做 Holm 校正），
`sweep: {param, values}` 做敏感性分析。参数路径写错会直接报错。结果在 `runs/<实验名>/`：
`results.csv` 每次运行一行，`summary.json` 是均值、置信区间、p 值、效应量和复现信息，历史版本在 `history/`，网页「实验对比」页会自动列出。

## 目录

```
sim/catalog.py     商品与品类          sim/market.py     居民、选店、记忆
sim/store.py       货架与库存批次      sim/engine.py     主循环、收银排队、记账
sim/accounting.py  复式记账与三张表    sim/managers.py   店长（规则版、亲自经营）
sim/experiment.py  实验运行器          sim/replay.py     导出回放      sim/server.py  网页服务
sim/events.py      突发事件与对手反击  sim/rl.py         模型店长、训练、评估、StoreEnv
web/               网页               tools/cdp.mjs     无头浏览器截图/测试
```

新店长（强化学习、Claude）实现 `sim/managers.py` 里的 `initial(obs)` / `decide(obs)` 两个方法并登记到 `MANAGERS` 即可。