@newpeak/barista-cli 0.1.131 → 0.1.133

package/skills/barista-cli/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: barista-cli
+description: >-
+  Barista CLI — 让 AI 助手通过命令行操控企业生产管理系统。
+  【Liberica】生产管理 SaaS（70+ 模块：基础资料/供应链/库存/生产/BOM/计划/质量/财务/HR/团队等）。
+  用户为租户企业员工，通过 tenant + username 登录。
+  【Arabica】Liberica 在线订阅平台（套餐/订阅下单/发票/企业管理）。
+  用户为会员（个人账号），通过 account + password 登录。
+  Actions: list, get, create, update, delete, submit, cancel, review, batch-review,
+  enable, disable, copy, track, export, import, compute, release, complete, register.
+---
+
+# Barista CLI — AI 操控企业生产管理系统
+
+## 系统关系
+
+**Liberica** = 生产管理 SaaS（制造企业 ERP）。用户=**租户企业员工**，登录=tenant+username+password。
+**Arabica** = Liberica 在线订阅平台。用户=**会员**（个人账号），登录=account+password。
+
+两者用户体系完全独立，但有业务流程关联：
+
+```
+会员注册 Arabica → 登录 → 注册企业 → 选套餐下单 → 获得 Liberica 权限
+→ 员工登录 Liberica → 日常生产管理（采购/库存/生产/销售等）
+```
+
+## When to Apply
+
+| 场景 | 系统 | 判断 |
+|------|------|------|
+| 生产数据（订单/库存/物料/BOM/工单/质量/财务/HR） | **Liberica** | 涉及制造企业日常运营 |
+| 订阅/套餐/购买/发票/企业注册 | **Arabica** | 涉及购买 Liberica 服务 |
+| 先看用户意图对应哪个业务领域 | 判断后再选系统 | 不确定时问用户 |
+
+## CRITICAL: 关键陷阱（AI 必须遵守）
+
+### 1. 邮箱用户名登录
+```bash
+# ✅ 正确：用位置参数
+barista liberica auth login dev shanghai admin@shanghai.newpeaksh.com 123456
+# ❌ 错误：--username 遇到 @ 会报 A0900006
+barista liberica auth login --username admin@shanghai.newpeaksh.com
+```
+
+### 2. teams issues 的 --tenant 被忽略
+```bash
+# ✅ 正确：先切换 context
+barista context use-tenant coffee
+barista liberica teams issues update <id> --status CLOSED --assign-to <uid>
+
+# ❌ 错误：--tenant coffee 被忽略，使用配置中的默认 tenant
+barista liberica teams issues update <id> --status CLOSED --tenant coffee
+```
+
+**已知忽略 --tenant 的命令**：teams issues update/close/get/delete
+
+### 3. teams issues close 需要 --assign-to
+```
+A1506: 负责人ID列表不能为空
+# 用 update 代替 close：
+barista liberica teams issues update <id> --status CLOSED --assign-to <userId>
+```
+
+### 4. 日期字段用 epoch ms
+```bash
+# ✅ 正确：Date.now() → 1746547200000
+# ❌ 错误："2025-05-06" 导致 B0001
+```
+影响命令：transfer-out-forms create（stockDate）、finance invoices create（invoiceDate）
+
+### 5. Liberica vs Arabica 登录差异
+| | Liberica | Arabica |
+|--|----------|---------|
+| 命令 | `barista liberica auth login <env> <tenant> <username> <password>` | `barista arabica auth login <env> <account> <password>` |
+| 有无 tenant | 有 | 无 |
+| 用户类型 | 企业员工 | 会员 |
+| 注册 | 无注册命令 | `barista arabica auth register` |
+
+### 6. 两个独立的问题系统
+- `liberica issue submit` — 向开发团队上报需求/BUG（通过 Typica → GitLab Issue）
+  - 默认上报到 **CLI 项目**（barista）
+  - `--project-code arabica` 上报到 **Arabica 项目**
+  - `--project-code liberica` 上报到 **Liberica 项目**
+  - `--type BUG|REQUIREMENT|QUESTION` 指定问题类型
+  - 可用 `validate-project <code>` 验证项目代号是否有效
+- `liberica teams issues` — 团队内部项目的问题管理（本地 DB）
+- 关闭已上报的 issue：在 teams issues 中过滤 BARISTA 项目 ID `2048236204222570498`
+
+### 7. token 存储
+- Token 存在系统密钥链（keytar），fallback 到 AES-256-GCM 加密文件
+- Liberica key 格式：`liberica:{environment}:{tenant}`
+- Arabica key 格式：`arabica:{environment}`（无 tenant）
+
+## 安全规则
+
+所有写操作（create/update/delete/batch-*）必须先 dry-run 再 force：
+
+```typescript
+// 1. 预览
+const preview = await $`barista liberica <resource> <action> --dry-run --json`
+const { success, data } = JSON.parse(preview.stdout)
+if (!success) throw new Error(data.error?.message)
+
+// 2. 验证 preview 内容是否正确
+
+// 3. 执行
+const result = await $`barista liberica <resource> <action> --force --json`
+```
+
+## 如何查找命令
+
+当需要查找具体命令时，使用 search.py 按用户意图搜索。search.py 位于技能安装目录下的 `scripts/search.py`：
+
+```bash
+# 示例路径（根据你的 AI 平台调整）：
+python3 .claude/skills/barista-cli/scripts/search.py "<用户意图>" [--domain <domain>]
+# 或使用 barista 内置搜索：
+barista skills query "<用户意图>" [--domain <domain>]
+```
+
+**domain 选项**：
+
+| domain | 搜索范围 |
+|--------|----------|
+| 不传 | 所有服务 |
+| `liberica` | 仅 Liberica |
+| `liberica.purchase-orders` | Liberica 采购订单模块 |
+| `liberica.finance.invoices` | Liberica 财务发票子模块 |
+| `arabica` | 仅 Arabica |
+| `arabica.plans` | Arabica 套餐模块 |
+
+**示例**：
+```bash
+python3 search.py "采购订单 列表" --domain liberica
+python3 search.py "创建入库单"
+python3 search.py "subscription" --domain arabica
+python3 search.py "invoice" --domain arabica.invoices
+```
+
+## JSON 响应格式
+
+所有命令的 `--json` 输出遵循统一格式：
+
+```json
+{
+  "success": true,
+  "data": {
+    "items": [...],
+    "pagination": { "page": 1, "size": 20, "total": 150 }
+  },
+  "meta": { "requestId": "...", "timestamp": "...", "environment": "dev", "tenant": "..." }
+}
+```
+
+错误格式（两种）：
+```json
+{ "success": false, "code": "B0301", "message": "TOKEN解析失败" }
+{ "success": false, "error": { "code": "A150001", "message": "..." } }
+```
+
+## 常见错误
+
+| 错误 | 含义 | 修复 |
+|------|------|------|
+| B0301 | Liberica token 过期/invalid | `barista liberica auth login <env> <tenant> <username> <password>` |
+| A0307 | 获取 token 失败 | 同上 |
+| Arabica 登录失败 | 会员 token 过期 | `barista arabica auth login <env> <account> <password>` |
+| A958001 | teams issues 的 tenant 不对 | `barista context use-tenant <正确tenant>` 重试 |
+| A1506 | 负责人 ID 列表为空 | 用 `update --status CLOSED --assign-to <id>` 代替 close |
+| B0001 | 系统执行出错 | 检查日期格式（epoch ms）、必填参数 |
+| A0900006 | 错误的账号 | 邮箱用位置参数，不用 --username |
+| A1504 | HTTP 方法错误 | CLI 一般自动处理（list→GET，create→POST） |
+
+## 内置 JSON 输出
+
+```typescript
+// AI 在 Claude Code / OpenCode 中执行：
+const result = await $`barista liberica <resource> <action> --json`
+const { success, data, error } = JSON.parse(result.stdout)
+
+if (!success) {
+  if (error?.code === 'B0301') { /* need re-login */ }
+  throw new Error(error?.message)
+}
+const items = data?.items || []
+```
+
+## ⚠️ 通用约束
+
+1. ID 字段必须用 `string` 类型（后端返回 BigInteger 超出 JS number 精度）
+2. 不加 `X-TENANT-ID` header（tenant 在 JWT 中）
+3. Authorization 不加 `Bearer` 前缀
+4. 分页 1-based 直传