makea-cli

给 Makea 同事（admin）、品牌（designer）和工厂（supplier）用的命令行工具，也是 Beeboo agent 的动作面：连的是线上正式环境，装好就能用，不用配环境变量、不用改配置文件。

第一次用时在浏览器里登录一次公司账号，之后在本机保存登录状态，即可查询用户、供应商等（具体能执行哪些命令取决于你的账号权限）。

怎么用（三步）

1. 安装（本机需要已安装 Python 3.10 或以上）

• 从本仓库安装（开发 / 内网 clone）： 在 makea-cli/ 目录执行
  python3 -m pip install -e .
  若提示找不到 python3，可改用 python。
• 不经过 GitHub： 把本包的 Python 发行版发布到公司私有 PyPI / Artifact Registry 等，同事执行
  python3 -m pip install makea-cli（或 pipx install makea-cli）即可；无需 clone 仓库。
• 可选 — 用 npm 只占一个全局命令名： 仓库里 npm/makea-cli/ 是一个 薄封装，npm install -g 后会把 makea-cli 指到 python3 -m makea_cli；仍需在同一台机器上先用 pip 装好同名 Python 包（npm 不会替你安装 Python 依赖）。适合已经用 npm 管理全局工具的团队。

2. 登录（只需做一次，或过期后再做）

 makea-cli auth

会自动打开浏览器，按公司流程登录即可。完成后可以关掉浏览器标签页。 3. 执行功能（示例）

 makea-cli admin list user
 makea-cli admin list supplier
 makea-cli admin list product-order
 makea-cli admin list sampling-order --product <product_reference_id>
 makea-cli admin list production-order --product <product_reference_id>

从「产品订单」JSON 下载附件： admin list product-order 返回的每条 result 里已有 user_id 和 available_documents（含 document_id、admin_user_id 等），一般 不必再调单独的 document metadata API。可直接： 若只有 product_reference_id，可用（建议加上设计师 user_id 避免扫全库）： 更多子命令与参数：

退出登录（清除本机保存的令牌）：

makea-cli auth --logout

登录信息保存在哪

保存在本机当前用户下的应用数据目录里（例如 macOS 常见为 ~/Library/Application Support/makea-cli/，Linux 常见为 ~/.config/makea-cli/），文件名类似 credentials.json。一般不用手动打开。

给技术同事：可选环境变量

日常同事 不需要 看本节。只有要连 非线上 或 自建环境 时，才用环境变量覆盖内置地址（默认值在 makea_cli/config.py 里）：

命令一览（0.2 语法）

makea-cli <persona> <verb> <noun> [参数] [--flags]。persona 说明谁在操作（admin / designer / supplier，后端按你的 token 校验；CLI 在发请求前也先比对本机登录的用户类型，不匹配 exit 3）；verb 说明读还是写：list get search download 是读，create update delete submit upload send set generate backfill 是写。

每条命令都有的开关：--describe 打印它的机器可读定义（flags、副作用、审批档位）；--json 强制纯 JSON（stdout 不是终端时默认就是）。读命令还有 --fields a,b,c 只保留这些字段；list 命令还有 --limit N（后端自己分页的就透传，不分页的在本地截断并在结果里写明 truncated / returned / omitted）；写命令还有 --dry-run（打印将要发出的请求，不发）和 --idempotency-key <k>。makea-cli --describe --json 打印全量 manifest。

写命令的审批档位（manifest 的 approval）是给 harness 的建议，不是 CLI 的门：auto 可以自动跑；ask 必须先让人确认；never agent 不许自己决定（人在终端照常能跑）。动钱的端点（payments / bank transfer / subscription）故意不进 CLI。

exit code：0 成功 · 2 用法错 · 3 未登录或身份与 persona 不匹配 · 4 后端拒绝（4xx，错误 JSON 在 stderr）· 5 没跑完（5xx / 网络 / 超时）——读命令直接重试即可；写命令可能已经生效了，重试前先读一遍状态。

0.1 的平铺命令名（list-users、submit-supplier-quote …）仍可用，作为隐藏的过渡别名转发到新命令并在 stderr 打一行提示；下一个 minor 版本删除。完整的改名对照表在 CHANGELOG.md。

admin

designer

supplier

其它：makea-cli auth [--logout] 登录/登出；makea-cli version 版本号。

大货定价（price tier / 颜色尺码 / pricing group）

一张 production order 的价格由三部分组成：

1. available_sizes / available_colors — 买家购物车的网格。cart key 是 "{尺码},{颜色}"，颜色段有 hex 就用 hex_code，没有才退回 color_name。所以颜色尽量都给 hex。
2. production_price_tiers + moq — 整单一套阶梯价。只在这张单没有 pricing group 时生效。
3. pricing_groups — 若干个各自计价的 cart key 分组。分组回答"谁共用一套价目表"，tier_basis / moq_basis 回答"按什么量去查这套表"（VARIANT 每个 cart key 各算各的，GROUP 按组内合计，ORDER 按全单合计）。

MOQ 的几种配法就是这两个旋钮的组合：

阶梯写法：--tier 100-199:7.50 --tier 200-499:7.40 --tier 500+:7.20。结尾的 +（或只写下限）表示不封顶，存成 max_qty=0；后端从低到高选，最后一个够 min_qty 的档位胜出。

单组覆盖：--tier-for 'S=100-199:22.45'、--moq-for 'S=100'，等号左边可以写组名、尺码、颜色名或 hex。

例（参考 Lacati 毯子那张报价的形态：三个尺寸各一套价，MOQ 100/组）：

makea-cli admin set production-variants <po_id> --sizes S,M,L --customized-color
makea-cli admin generate pricing-groups <po_id> --by style \
  --tier-for 'S=100-199:7.50'  --tier-for 'S=300+:7.20' \
  --tier-for 'M=100-199:22.45' --tier-for 'M=300+:21.85' \
  --tier-for 'L=100-199:33.05' --tier-for 'L=300+:32.25' \
  --moq 100 --moq-basis group --tier-basis VARIANT --dry-run

几条要记住的：

• 写命令都先打印 plan 再问一次；--dry-run 只看不发，--yes 跳过确认。默认打的是生产环境。
• 购物车里有、却没被任何组认领的 cart key，付款时会整单失败（不是按 0 计价）。plan 和保存结果都会把这些 key 列出来。
• 重跑 admin generate pricing-groups 会保留同名/同变体旧组的 group_id 和这次没指定的字段，所以"只改 MOQ"是安全的。
• 已经付过款的单，改这里不会动已经收的钱（发票读冻结值），只影响之后的扣款。

Claude / Cursor skills（可选）

仓库内 .claude/skills/ 下放有面向 agent 的操作说明，例如：

• supplier-user-id-migration — 供应商 ID 与 Cognito sub 对齐、与 admin backfill supplier-id 配套