@newpeak/barista-cli 0.1.7 → 0.1.9

package/docs/commands/liberica/client-contacts/get.md

@@ -0,0 +1,133 @@
+# barista liberica client-contacts get
+
+获取单个客户联系人详情。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica client-contacts get <contact-id>` |
+| 功能描述 | 获取单个客户联系人详情 |
+| HTTP方法 | GET |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ⬜ 否 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/sales/
+        └── EnterpriseClientContactController.java
+            └── detail(@GetResource(path = "/detail"))
+                └── public ResponseData<MasterClientContactResponse> detail(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        MasterClientContactRequest masterClientContactRequest
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/pojo/request/
+        └── MasterClientContactRequest.java
+            └── clientContactId: Long (@NotNull on detail)
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/pojo/response/
+        └── MasterClientContactResponse.java
+            ├── clientContactId: Long
+            ├── clientId: Long
+            ├── clientContactName: String
+            ├── clientContactPhone: String
+            ├── clientContactTelephone: String
+            ├── clientContactEmail: String
+            ├── clientContactSex: String
+            ├── clientContactBirthday: Date
+            ├── clientContactQq: String
+            ├── clientContactWechat: String
+            ├── clientContactAddress: String
+            ├── defaultFlag: String (Y/N)
+            ├── remark: String
+            ├── createTime: String
+            └── updateTime: String
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica client-contacts get <contact-id> [options]
+```
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| contact-id | string | ✅ | 客户联系人ID (clientContactId) |
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 |
+|------|--------|------|------|--------|------|
+| — | — | — | — | — | 此命令无额外选项，ID 通过位置参数传入 |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| <contact-id> (位置参数) | clientContactId | string→Long | @NotNull, 必须为正整数 |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/pojo/response/
+        └── MasterClientContactResponse.java
+            └── MASTER_CLIENT_CONTACT_NOT_EXIST("01001207001", "租户客户联系人不存在")
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001207001 | 租户客户联系人不存在 | contact-id 不存在或不属于当前租户 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| 注解 | `@GetResource(path = "/detail")` | 无 requiredPermission |
+
+## 2.7 实现要点
+
+1. **位置参数**：`get` 命令使用 `<contact-id>` 位置参数指定联系人ID
+2. **错误处理**：联系人不存在时抛出 `MASTER_CLIENT_CONTACT_NOT_EXIST`，CLI 显示友好错误信息
+3. **tenantId来源**：来自 X-TENANT-ID header，后端自动按租户隔离数据
+4. **输出格式**：表格形式展示联系人详情，或 JSON 格式
+
+## 2.8 示例用法
+
+```bash
+# 获取联系人详情
+barista liberica client-contacts get 12345
+
+# JSON 输出
+barista liberica client-contacts get 12345 --json
+
+# 联系人不存在
+barista liberica client-contacts get 99999
+# 输出: Error: 租户客户联系人不存在 (01001207001)
+```

package/docs/commands/liberica/client-contacts/list.md

@@ -0,0 +1,143 @@
+# barista liberica client-contacts list
+
+查询客户联系人列表。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica client-contacts list` |
+| 功能描述 | 查询指定客户的联系人列表 |
+| HTTP方法 | GET |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ⬜ 否 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/sales/
+        └── EnterpriseClientContactController.java
+            └── list(@GetResource(path = "/list"))
+                └── public ResponseData<List<MasterClientContactResponse>> list(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        MasterClientContactRequest masterClientContactRequest
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/pojo/request/
+        └── MasterClientContactRequest.java
+            ├── clientId: Long (@NotNull)
+            ├── clientContactName: String (搜索关键词)
+            ├── pageNo: Long (分页页码)
+            └── pageSize: Long (分页大小)
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/pojo/response/
+        └── MasterClientContactResponse.java
+            ├── clientContactId: Long
+            ├── clientId: Long
+            ├── clientContactName: String
+            ├── clientContactPhone: String
+            ├── clientContactTelephone: String
+            ├── clientContactEmail: String
+            ├── clientContactSex: String
+            ├── clientContactBirthday: Date
+            ├── clientContactQq: String
+            ├── clientContactWechat: String
+            ├── clientContactAddress: String
+            ├── defaultFlag: String (Y/N)
+            ├── remark: String
+            ├── createTime: String
+            └── updateTime: String
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica client-contacts list [options]
+```
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --client-id | -c | string | ✅ | - | 客户ID | clientId |
+| --page | -p | number | ⬜ | 1 | 页码 | pageNo |
+| --size | -s | number | ⬜ | 20 | 每页条数 | pageSize |
+| --search | -S | string | ⬜ | - | 搜索关键词(姓名) | clientContactName |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| --client-id / -c | clientId | string→Long | @NotNull |
+| --page / -p | pageNo | number→Long | >= 1 |
+| --size / -s | pageSize | number→Long | 1-100 |
+| --search / -S | clientContactName | 直接传递 | 模糊查询 |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/exception/enums/
+        └── MasterClientContactExceptionEnum.java
+            └── MASTER_CLIENT_CONTACT_NOT_EXIST("01001207001", "租户客户联系人不存在")
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001207001 | 租户客户联系人不存在 | 客户ID不存在时 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| 注解 | `@GetResource(path = "/list")` | 无 requiredPermission（无需权限码） |
+
+**注意**：list 接口在 Controller 层无需权限校验，数据范围通过 tenantId 隔离。
+
+## 2.7 实现要点
+
+1. **必填参数**：--client-id 必须指定
+2. **分页默认值**：page=1, size=20
+3. **搜索行为**：clientContactName 支持模糊查询
+4. **无结果处理**：返回空列表，不抛出异常
+5. **tenantId来源**：来自 X-TENANT-ID header
+6. **输出格式**：表格形式展示联系人列表
+
+## 2.8 示例用法
+
+```bash
+# 列出客户的所有联系人
+barista liberica client-contacts list --client-id 12345
+
+# 指定页码和每页条数
+barista liberica client-contacts list --client-id 12345 --page 2 --size 50
+
+# 搜索联系人
+barista liberica client-contacts list --client-id 12345 --search "张"
+
+# JSON 输出（便于脚本处理）
+barista liberica client-contacts list --client-id 12345 --json
+```

package/docs/commands/liberica/client-contacts/update.md

@@ -0,0 +1,158 @@
+# barista liberica client-contacts update
+
+更新客户联系人信息。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica client-contacts update <contact-id>` |
+| 功能描述 | 修改客户联系人信息 |
+| HTTP方法 | POST |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ✅ 是 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/sales/
+        └── EnterpriseClientContactController.java
+            └── edit(@PostResource(path = "/edit", requiredPermission = true, requirePermissionCode = "EDIT_MASTER_CLIENT_CONTACT"))
+                └── public ResponseData<?> edit(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody @Validated(BaseRequest.edit.class) MasterClientContactRequest masterClientContactRequest
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/pojo/request/
+        └── MasterClientContactRequest.java
+            ├── clientContactId: Long (@NotNull on edit)
+            ├── clientContactName: String (@NotBlank, max=255)
+            ├── clientContactPhone: String (max=256)
+            ├── clientContactTelephone: String (max=256)
+            ├── clientContactEmail: String (max=512)
+            ├── clientContactSex: String (max=255)
+            ├── clientContactBirthday: Date
+            ├── clientContactQq: String (max=512)
+            ├── clientContactWechat: String (max=512)
+            ├── clientContactAddress: String (max=512)
+            ├── defaultFlag: String (max=1)
+            └── remark: String (max=255)
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/pojo/response/
+        └── MasterClientContactResponse.java
+            └── (同 get 接口)
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica client-contacts update <contact-id> [options]
+```
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| contact-id | string | ✅ | 客户联系人ID |
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--dry-run` | boolean | 预览模式 |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --name | -n | string | ⬜ | - | 姓名 | clientContactName |
+| --phone | -p | string | ⬜ | - | 手机号 | clientContactPhone |
+| --telephone | -t | string | ⬜ | - | 座机号 | clientContactTelephone |
+| --email | -e | string | ⬜ | - | 电子邮箱 | clientContactEmail |
+| --sex | -s | string | ⬜ | - | 性别 | clientContactSex |
+| --birthday | -b | string | ⬜ | - | 生日(YYYY-MM-DD) | clientContactBirthday |
+| --qq | -q | string | ⬜ | - | QQ号 | clientContactQq |
+| --wechat | -w | string | ⬜ | - | 微信号 | clientContactWechat |
+| --address | -a | string | ⬜ | - | 详细地址 | clientContactAddress |
+| --default | -d | boolean | ⬜ | - | 是否默认联系人 | defaultFlag |
+| --remark | -r | string | ⬜ | - | 备注 | remark |
+
+**注意**：所有字段在 update 时都是可选的，至少需要提供一个要更新的字段。
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| <contact-id> | clientContactId | string→Long | @NotNull |
+| --name / -n | clientContactName | 直接传递 | max=255 |
+| --phone / -p | clientContactPhone | 直接传递 | max=256 |
+| --telephone / -t | clientContactTelephone | 直接传递 | max=256 |
+| --email / -e | clientContactEmail | 直接传递 | max=512 |
+| --sex / -s | clientContactSex | 直接传递 | max=255 |
+| --birthday / -b | clientContactBirthday | string→Date | yyyy-MM-dd |
+| --qq / -q | clientContactQq | 直接传递 | max=512 |
+| --wechat / -w | clientContactWechat | 直接传递 | max=512 |
+| --address / -a | clientContactAddress | 直接传递 | max=512 |
+| --default / -d | defaultFlag | boolean→Y/N | max=1 |
+| --remark / -r | remark | 直接传递 | max=255 |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/exception/enums/
+        └── MasterClientContactExceptionEnum.java
+            └── MASTER_CLIENT_CONTACT_NOT_EXIST("01001207001", "租户客户联系人不存在")
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001207001 | 租户客户联系人不存在 | contact-id 不存在或不属于当前租户 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| PermissionConstants | `EDIT_MASTER_CLIENT_CONTACT` | 编辑客户联系人需要此权限 |
+| 注解 | `@PostResource(requirePermissionCode = "EDIT_MASTER_CLIENT_CONTACT")` | Controller方法上 |
+
+## 2.7 实现要点
+
+1. **位置参数**：contact-id 必须指定
+2. **可选字段**：所有业务字段都是可选的，至少提供一个
+3. **dry-run 模式**：预览模式下只显示将要更新的数据，不实际调用 API
+4. **输出格式**：成功后显示更新后的联系人信息
+5. **错误处理**：联系人不存在时显示友好错误信息
+
+## 2.8 示例用法
+
+```bash
+# 更新联系人姓名（dry-run 预览）
+barista liberica client-contacts update 12345 --name "新姓名" --dry-run
+
+# 实际更新
+barista liberica client-contacts update 12345 --name "新姓名" --phone "13900139000"
+
+# 更新多个字段
+barista liberica client-contacts update 12345 --email "new@example.com" --address "新地址"
+
+# JSON 输出
+barista liberica client-contacts update 12345 --name "新姓名" --json
+```

package/docs/commands/liberica/stock/ledger.md

@@ -0,0 +1,209 @@
+# 命令名称: barista liberica stock ledger
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica stock ledger` |
+| 功能描述 | 查询出入库台账（分页列表+汇总） |
+| HTTP方法 | GET |
+| 是否需要认证 | 是 |
+| 是否支持dry-run | 否 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/master/
+        └── MasterStockController.java
+            ├── commonStockJourneyPage(@GetResource(path = "/journey/page"))
+            │   └── public ResponseData<PageResult<StockJourneyResponse>> commonStockJourneyPage(
+            │           @RequestHeader("X-TENANT-ID") Long tenantId,
+            │           @ParameterObject StockJourneyQueryRequest stockJourneyQueryRequest
+            │       )
+            └── commonStockJourneyPageSummary(@GetResource(path = "/journey/page/summary"))
+                └── public ResponseData<StockJourneySummaryResponse> commonStockJourneyPageSummary(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @ParameterObject StockJourneyQueryRequest stockJourneyQueryRequest
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/pojo/request/
+        └── StockJourneyQueryRequest.java
+            ├── stockId: Long
+            ├── stockFormCode: String
+            ├── stockType: String
+            ├── stockFlag: String
+            ├── warehouseCode: String
+            ├── materialCode: String
+            ├── materialName: String
+            ├── materialType: String
+            ├── color: String
+            ├── lotNo: String
+            ├── lotCode: String
+            ├── sourceType: String
+            ├── sourceCode: String
+            ├── stockDate: Date
+            ├── stockDateCriteria: DateRange
+            └── postingMonth: Date
+```
+
+### Response DTO位置
+
+**列表项 DTO：**
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/pojo/response/
+        └── StockJourneyResponse.java
+            ├── stockId: Long
+            ├── stockFormCode: String
+            ├── stockType: String
+            ├── stockFlag: String
+            ├── warehouseCode: String
+            ├── materialCode: String
+            ├── materialNo: String
+            ├── materialName: String
+            ├── materialType: String
+            ├── color: String
+            ├── longX: BigDecimal
+            ├── wideY: BigDecimal
+            ├── highZ: BigDecimal
+            ├── sourceCode: String
+            ├── sourceType: String
+            ├── lotCode: String
+            ├── lotNo: String
+            ├── supplierLotNo: String
+            ├── inboundCount: BigDecimal
+            ├── outboundCount: BigDecimal
+            ├── materialUomCode: String
+            ├── unitPrice: BigDecimal
+            ├── localCurrency: String
+            ├── inboundAmount: BigDecimal
+            ├── outboundAmount: BigDecimal
+            ├── inboundDate: Date
+            ├── stockDate: Date
+            ├── outboundDate: Date
+            ├── postingMonth: Date
+            └── remark: String
+```
+
+**汇总 DTO：**
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/pojo/response/
+        └── StockJourneySummaryResponse.java
+            ├── totalInboundCount: BigDecimal
+            ├── totalOutboundCount: BigDecimal
+            ├── totalInboundAmount: BigDecimal
+            └── totalOutboundAmount: BigDecimal
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```bash
+barista liberica stock ledger [options]
+```
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev/test/prod-cn/prod-jp) |
+| `--tenant` | string | 租户代码（仅Liberica） |
+| `--dry-run` | boolean | 预览模式 |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| `--stock-id` |  | string | 否 | - | 出入库ID | stockId |
+| `--stock-form-code` |  | string | 否 | - | 出入库单编码 | stockFormCode |
+| `--stock-type` |  | string | 否 | - | 出入库单类型 | stockType |
+| `--stock-flag` |  | string | 否 | - | 出入库标志(inbound/outbound) | stockFlag |
+| `--warehouse-code` | -w | string | 否 | - | 仓库编码 | warehouseCode |
+| `--material-code` | -m | string | 否 | - | 物料编码 | materialCode |
+| `--material-name` |  | string | 否 | - | 物料名称（支持模糊查询） | materialName |
+| `--material-type` | -t | string | 否 | - | 物料规格 | materialType |
+| `--color` | -c | string | 否 | - | 颜色 | color |
+| `--lot-no` | -l | string | 否 | - | 批次号 | lotNo |
+| `--lot-code` |  | string | 否 | - | 系统批次号 | lotCode |
+| `--source-type` |  | string | 否 | - | 源单类型 | sourceType |
+| `--source-code` |  | string | 否 | - | 源单编码 | sourceCode |
+| `--start-date` |  | string | 否 | - | 出入库开始日期(YYYY-MM-DD) | stockDateCriteria.startDate |
+| `--end-date` |  | string | 否 | - | 出入库结束日期(YYYY-MM-DD) | stockDateCriteria.endDate |
+| `--posting-month` |  | string | 否 | - | 记账年月(YYYY-MM) | postingMonth |
+| `--summary` |  | boolean | 否 | false | 仅显示汇总数据 | 控制输出模式 |
+| `--page` | -p | number | 否 | 1 | 页码 | pageNo |
+| `--size` | -s | number | 否 | 20 | 每页条数 | pageSize |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| --stock-id | stockId | string→Long | 后端BigInteger，CLI使用string |
+| --stock-form-code | stockFormCode | 直接传递 | - |
+| --stock-type | stockType | 直接传递 | enum: STOCK_TYPE |
+| --stock-flag | stockFlag | 直接传递 | enum: STOCK_FLAG |
+| --warehouse-code | warehouseCode | 直接传递 | - |
+| --material-code | materialCode | 直接传递 | - |
+| --material-name | materialName | 直接传递 | - |
+| --material-type | materialType | 直接传递 | - |
+| --color | color | 直接传递 | - |
+| --lot-no | lotNo | 直接传递 | - |
+| --lot-code | lotCode | 直接传递 | - |
+| --source-type | sourceType | 直接传递 | enum: source_type |
+| --source-code | sourceCode | 直接传递 | - |
+| --start-date | stockDateCriteria.startDate | string→Date | yyyy-MM-dd |
+| --end-date | stockDateCriteria.endDate | string→Date | yyyy-MM-dd |
+| --posting-month | postingMonth | string→Date | yyyy-MM |
+| --page | pageNo | number-1 | 0-based分页 |
+| --size | pageSize | number | >0 |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/exception/enums/
+        ├── StockJourneyExceptionEnum.java
+        │   ├── STOCK_JOURNEY_NOT_EXIST("...001", "租户出入库台账不存在")
+        │   └── CAN_NOT_DELETE_MATERIAL_WITH_USED_IN_STOCK("...002", "物料已在库存中使用，不能删除")
+        ├── MasterStockExceptionEnum.java
+        │   ├── MASTER_STOCK_NOT_EXIST("...001", "租户库存不存在")
+        │   └── MASTER_STOCK_OUT_LOT_NOT_ENOUGH("...002", "租户成品出库单{}余量不够")
+        └── MasterWarehouseStockExceptionEnum.java
+            └── MASTER_WAREHOUSE_STOCK_NOT_EXIST("...001", "租户仓库库存不存在")
+```
+
+### 已知错误码示例
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| ...001 | 租户出入库台账不存在 | 查询的台账记录不存在 |
+| ...001 | 租户库存不存在 | 查询的库存记录不存在 |
+| ...002 | 租户成品出库单{}余量不够 | 出库操作余量不足 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| 菜单权限 | `MasterStockController` 类上的 `@Menu` 注解 | `stock_journey` 菜单，要求 `tenantStock` 角色 |
+| 接口访问 | Controller方法无单独 `@GetResource(requiredPermission = true)` | 通过菜单角色控制 |
+
+## 2.7 实现要点
+
+1. **双接口调用**：默认模式同时调用 `/journey/page/summary` 和 `/journey/page`，先显示汇总再显示列表
+2. **Summary模式**：当传入 `--summary` 时，仅调用 `/journey/page/summary`，不请求列表数据
+3. **分页转换**：CLI page 1 对应 API pageNo 0
+4. **ID类型**：stockId 后端为 Long/BigInteger，CLI 统一使用 string 类型避免精度丢失
+5. **日期格式**：--posting-month 使用 yyyy-MM 格式，转换为 Date 类型
+6. **stockFlag映射**：inbound 对应入库记录，outbound 对应出库记录；后端 StockJourneyResponse 根据 inboundCount 是否为空自动推断 stockFlag
+7. **输出格式**：默认表格输出，--json 返回结构化 JSON；汇总数据和列表数据在 JSON 中分层返回