@lichidental/saas-cli 0.0.0-stage → 1.0.1

package/docs/api//346/216/245/345/217/243/350/257/264/346/230/216.md

@@ -0,0 +1,259 @@
+# 预约相关接口说明(中文导读 + curl)
+
+> **目标读者:后端工程师** — 需要用命令行(curl)手工调接口、或写后端对接代码的技术同学。
+> 只使用现成 CLI 命令的同学请看 `CLI使用手册.md`,不需要本文件。
+>
+> 机器可读的权威版本是 [openapi.yaml](./openapi.yaml),本文件是它的中文导读。
+> **两个文件如有出入,以 openapi.yaml 为准。**
+> 全部接口于 2026-10-12 在 test 环境实测;真实请求/响应样本见 `docs/samples/`。
+
+## 通用约定
+
+### 环境地址
+
+| 环境 | 地址 | 备注 |
+|---|---|---|
+| test(测试) | `https://test.saas.lichidental.com` | 样本采集环境,已实测 |
+| pre(预发) | `https://pre.saas.lichidental.com` | 未实测 |
+| prod(生产) | `https://saas.lichidental.com` | 未实测 |
+
+接口路径直接拼环境地址,例如 `POST https://test.saas.lichidental.com/user/saas/custom-mark/addCustomMark`。
+
+### 请求头
+
+| 头 | 必填 | 说明 |
+|---|---|---|
+| `token` | 是 | 登录凭据(浏览器登录后 localStorage.userInfo.token) |
+| `Content-Type` | 是 | `application/json;charset=UTF-8` |
+| `Version` | 建议 | 前端构建版本号(如 `v26.09.2.0`);后端会做版本校验,缺失或过旧可能返回 status 999 |
+| `channel` | 建议 | 固定 `html`(与 Version 一起用) |
+
+前端对 POST 请求不携带 clinicId 参数,诊所归属由 token 决定。
+
+### 响应格式
+
+所有接口 HTTP 状态码恒为 200,业务结果看响应体 `status` 字段。
+
+成功:
+
+```json
+{ "status": 200, "code": "SUCCESS", "message": "处理成功", "data": { } }
+```
+
+失败(示例为实测的错误 token 响应,注意 401 无 data 字段):
+
+```json
+{ "code": "UNAUTHORIZED", "message": "登录失效,请重新登录！", "status": 401 }
+```
+
+| status | 含义 | 处理 |
+|---|---|---|
+| 200 | 成功 | - |
+| 400 | 业务参数错误 | 按 message 修正 |
+| 401 | token 失效 | 重新登录 / 更换 token |
+| 403 | 无权限 | 联系管理员开权限 |
+| 410 | 营销中心无短信余额(短信相关) | 充值或换账号 |
+| 999 | 版本校验失败 | 检查 Version 头是否为当前构建版本 |
+| 30002 | 短信发送失败(短信相关) | 见 message |
+
+### 时间格式(重要,两处不一样)
+
+- **请求体里的时间**: `YYYY-MM-DD HH:mm:ss`(空格分隔,带秒)。预约短信接口例外: `YYYY-MM-DD HH:mm`(不带秒)。
+- **响应体里的时间**: ISO 格式,形如 `2026-11-01T11:00:00`(**中间是 T**,读响应时注意转换)。
+
+---
+
+## 1. 医生列表
+
+`POST /user/saas/t-lichi-user-store/getStoreUserListByParam`
+
+取"在职(0)+ 试用(2)、岗位=医生(1)"的员工,创建预约时用返回的 `userUid` 作为 `doctorId`。
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|---|---|---|---|---|
+| delFlags | number[] | 是 | 在职状态:0=在职 1=离职 2=试用 | `[0,2]` |
+| storeUserPostIds | number[] | 是 | 岗位:1=医生(其他:3=洁牙师 4=咨询师 6=护士 7=前台…) | `[1]` |
+
+响应:`data` 为员工数组,常用字段 `userUid`(字符串)、`storeUserName`(姓名)。完整字段见样本。
+
+```bash
+curl -X POST "https://test.saas.lichidental.com/user/saas/t-lichi-user-store/getStoreUserListByParam" \
+  -H "Content-Type: application/json;charset=UTF-8" \
+  -H "token: <你的token>" -H "Version: v26.09.2.0" -H "channel: html" \
+  -d '{"delFlags":[0,2],"storeUserPostIds":[1]}'
+```
+
+> 实测通过(2026-10-12,返回 19 条)。样本:[samples/getStoreUserListByParam.json](../samples/getStoreUserListByParam.json)
+
+## 2. 搜索患者
+
+`POST /user/saas/custom/customParamPageList`
+
+按关键词搜患者(paramText 支持姓名 / 手机号 / 病历号)。创建预约时用返回的 `customCode`。
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|---|---|---|---|---|
+| pageNum | number | 是 | 页码 | `1` |
+| pageSize | number | 是 | 每页条数 | `20` |
+| paramText | string | 否 | 搜索关键词;不传返回全部 | `"张"` |
+| dateType | number | 否 | 前端固定传 3(其他取值未验证) | `3` |
+
+响应:`data.total` 为总数,`data.list` 为患者数组,常用字段 `customCode` / `customName` / `customPhone` / `codeNum`(病历号)。
+
+> Windows(Git Bash)下 curl 直传中文会乱码,把 JSON 存成 UTF-8 文件再 `-d @file.json`(本示例即此方式)。
+
+```bash
+# body.json 内容(UTF-8 编码):{"paramText":"张","pageNum":1,"pageSize":20,"dateType":3}
+curl -X POST "https://test.saas.lichidental.com/user/saas/custom/customParamPageList" \
+  -H "Content-Type: application/json;charset=UTF-8" \
+  -H "token: <你的token>" -H "Version: v26.09.2.0" -H "channel: html" \
+  -d @body.json
+```
+
+> 实测通过(搜"张"共 9 条)。样本:[samples/customParamPageList.json](../samples/customParamPageList.json)
+
+## 3. 预约项目列表
+
+`POST /user/saas/treat-item/getTreatItemList`
+
+无参数(传 `{}` 即可)。返回**平铺数组**:`level=1` 为一级分类,`level=2` 为二级项目(用 `upTreatItemId` 关联一级分类的 `id`)。
+
+| 字段(响应元素) | 说明 |
+|---|---|
+| id | 项目 id(二级项目组装 treatItemJson 时用) |
+| treatItemName | 项目/分类名称 |
+| upTreatItemId | 上级分类 id(一级分类行为 0) |
+| level | 1=一级分类,2=二级项目 |
+
+```bash
+curl -X POST "https://test.saas.lichidental.com/user/saas/treat-item/getTreatItemList" \
+  -H "Content-Type: application/json;charset=UTF-8" \
+  -H "token: <你的token>" -H "Version: v26.09.2.0" -H "channel: html" -d '{}'
+```
+
+> 实测通过(共 42 个:10 个一级分类 + 32 个二级项目)。样本:[samples/getTreatItemList.json](../samples/getTreatItemList.json)
+
+## 4. 按患者识别就诊类型(初诊 / 复诊)
+
+`POST /user/saas/custom-mark/customMarkInfoByCustom`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| customCode | string | 是 | 患者编码 |
+
+响应:`data.visitType` — **1=初诊,0=复诊**(数字);组装新建预约请求时需转成字符串 `"1"`/`"0"`。`data.customMarkDtos` 为患者历史记录(结构见样本,一般不用)。
+
+```bash
+curl -X POST "https://test.saas.lichidental.com/user/saas/custom-mark/customMarkInfoByCustom" \
+  -H "Content-Type: application/json;charset=UTF-8" \
+  -H "token: <你的token>" -H "Version: v26.09.2.0" -H "channel: html" \
+  -d '{"customCode":"YONGCE26073100001"}'
+```
+
+> 实测通过(返回 visitType=0)。样本:[samples/customMarkInfoByCustom.json](../samples/customMarkInfoByCustom.json)
+
+## 5. 新建预约(写操作)
+
+`POST /user/saas/custom-mark/addCustomMark`
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|---|---|---|---|---|
+| customCode | string | 是 | 患者编码 | `"YONGCE26073100001"` |
+| doctorId | string | 是 | 医生 userUid(**字符串**,不要传数字) | `"26051131994"` |
+| markStartTime | string | 是 | 开始时间 `YYYY-MM-DD HH:mm:ss`(勿用 ISO) | `"2026-11-01 11:00:00"` |
+| markTimeLength | number | 是 | 时长(分钟)。前端可选值:15/30/45/60/75/90/105/120/135/150/165/180/195/210/225/240/300/360/420/480 | `30` |
+| treatItemJson | string | 是 | 项目 **JSON 字符串**(见下) | 见下 |
+| boolFirst | string | 否 | 就诊类型:`"1"`=初诊 `"0"`=复诊(字符串)。省略行为未验证,建议传 | `"0"` |
+| definitionCreateTime | string | 否 | 创建时间,格式同上。前端与 CLI 均传当前时间 | `"2026-10-12 11:01:51"` |
+| remark | string | 否 | 备注,可为空字符串 | `""` |
+
+treatItemJson 字符串解析后的元素结构(每项 4 个字段,全部必有):
+
+```json
+[{ "up_id": 84048, "up_title": "口腔", "id": 84050, "title": "口腔检查" }]
+```
+
+- `up_id` / `up_title`:一级分类的 id / 名称(来自项目列表 level=1)
+- `id` / `title`:二级项目的 id / 名称(来自项目列表 level=2)
+
+响应:`data.id` 为新建预约的 id(同时还有 `data.updateNum`,固定 1)。
+
+```bash
+# body.json(UTF-8 编码):
+# {"customCode":"YONGCE26073100001","doctorId":"26051131994","markStartTime":"2026-11-05 10:00:00",
+#  "markTimeLength":30,"treatItemJson":"[{\"up_id\":84048,\"up_title\":\"口腔\",\"id\":84050,\"title\":\"口腔检查\"}]",
+#  "boolFirst":"0","remark":""}
+curl -X POST "https://test.saas.lichidental.com/user/saas/custom-mark/addCustomMark" \
+  -H "Content-Type: application/json;charset=UTF-8" \
+  -H "token: <你的token>" -H "Version: v26.09.2.0" -H "channel: html" \
+  -d @body.json
+```
+
+> 实测通过(创建成功,返回 `{"status":200,...,"data":{"id":1260620,"updateNum":1}}`)。样本:[samples/addCustomMark.json](../samples/addCustomMark.json)
+
+## 6. 按患者 + 时间范围查询预约记录(列表展示,推荐)
+
+`POST /user/saas/custom-mark/customMarkListByCustom`
+
+**前端患者详情"就诊记录"与卡片"下次预约"tab 用的就是这个接口**,也是 CLI `reservation list` 的实现方式。按患者 + 时间范围查询,**服务端过滤生效**。
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|---|---|---|---|---|
+| customCode | string | 是 | 患者编码(精确过滤) | `"YONGCE26073100001"` |
+| startTime / endTime | string | 否 | 时间范围 `YYYY-MM-DD HH:mm:ss`(**实测服务端过滤生效**) | `"2026-10-15 00:00:00"` / `"2026-10-15 23:59:59"` |
+| pageSize | number | 否 | 每页条数(前端用 10;取全部可用 999) | `999` |
+| time | string | 否 | 分页游标:上一页最后一条的 markStartTime | - |
+
+响应:`data.cmList` 为预约数组,**已按 markStartTime 降序排序**(前端不排序,依赖后端顺序)。关键字段:
+
+| 字段 | 说明 |
+|---|---|
+| id | 预约 id |
+| customCode / doctorId | 患者编码 / 医生 userUid(字符串) |
+| status / visitStatus | 预约状态数字 / 就诊状态(显示规则见下表;主键是 visitStatus) |
+| isMark / isRegister | 是否预约 / 是否挂号(前端按 `!(isMark===0 && isRegister===1)` 剔除"仅挂号"记录) |
+| markDate / markStartTime / markEndTime | 预约日期与起止时间(**ISO 格式带 T**) |
+| markTimeLength | 时长(分钟) |
+| treatItemJson / remark | 项目 JSON 字符串 / 备注 |
+
+**状态显示规则**(前端看板的逻辑:以 `visitStatus` 为主键,不是直接用 `status`;CLI `list` 已照此实现):
+
+| visitStatus | status | 显示 |
+|---|---|---|
+| 1(预约未到) | 1 | 已预约 |
+| 1(预约未到) | 9 或其他 | 已确认 |
+| 2 | - | 已到店 |
+| 3 | - | 治疗中 |
+| 4(待收费) | 5 或 2 | 治疗中 |
+| 4(待收费) | 其他 | 待收费 |
+| 5 | - | 治疗完成 |
+| 6 | - | 已离店 |
+
+```bash
+curl -X POST "https://test.saas.lichidental.com/user/saas/custom-mark/customMarkListByCustom" \
+  -H "Content-Type: application/json;charset=UTF-8" \
+  -H "token: <你的token>" -H "Version: v26.09.2.0" -H "channel: html" \
+  -d '{"customCode":"YONGCE26073100001","startTime":"2026-10-15 00:00:00","endTime":"2026-10-15 23:59:59","pageSize":999}'
+```
+
+> 实测通过(当天只返回当天记录;不传时间范围返回全部 14 条且降序)。样本:[samples/customMarkListByCustom.json](../samples/customMarkListByCustom.json)
+
+## 7. 发送预约短信(未实测)
+
+`POST /user/saas/custom-mark/sendCustomMarkSms` ⚠️ **写操作,会给患者手机发短信**
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| customCode | string | 是 | 患者编码 |
+| markStartTime | string | 是 | 开始时间 `YYYY-MM-DD HH:mm`(**注意:此接口不带秒**,与 addCustomMark 不同) |
+
+> **未实测**:为避免给真实号码发短信,本接口未做实测。参数与前端调用一致(来源:前端 `src/api/reservation.ts` 的 `sendCustomMarkSmsApi`)。失败码:30002=短信发送失败,410=短信余额不足。
+
+---
+
+## 附:Windows 下 curl 中文乱码
+
+Git Bash 里 `curl -d '{"paramText":"张"}'` 会把中文按本地编码(GBK)发送,导致服务端存到乱码。解决方式:
+
+1. 把 JSON 存成 **UTF-8 无 BOM** 文件,用 `-d @body.json`(本文件示例均如此)
+2. 或直接用本 CLI 工具 / Postman / Apifox 等,无此问题

package/docs//345/274/200/345/217/221/346/214/207/345/215/227.md

@@ -0,0 +1,176 @@
+# 开发指南:如何新增一个 CLI 命令
+
+> **目标读者:维护 / 扩展本工具的开发者** — 在现有工程里新增命令时,按本指南的模板与 checklist 操作。
+> 普通使用者不需要阅读本文件。
+
+本工具后续会不断加命令(其他业务域的查询、造数等)。新增命令请按本指南的模板与 checklist 做,保持分层与输出契约一致。
+
+## 目录结构与分层规则
+
+```
+cli.mjs           入口:扫描 commands/**/*.mjs 自动注册;统一错误输出与退出码
+lib/              基础设施层(领域无关):http 传输 / errors 退出码 / output 输出 / config 配置 / match 名称匹配 / time 时间 / options 通用参数
+api/              接口 SDK 层:每个后端接口一个函数,按域分文件(与前端 src/api/*.ts 同名对应)
+commands/         命令层:一命令一文件,子目录=主题命名空间;文件名以 _ 开头的为内部模块(不注册)
+test/             node:test 测试(纯函数 + CLI 冒烟,不依赖网络)
+docs/             文档(见文末"文档要求")
+```
+
+**依赖方向固定为 `commands → api → lib`,禁止反向或跨层:**
+
+- `commands/*` 只做:解析参数 → 调 `api/*` → 用 `ctx.out` 输出。不直接 import `lib/http.mjs`,不写 fetch
+- `api/*` 只描述接口(路径 / 请求体 / 返回),不打印输出、不读配置;签名统一 `(http, params)`
+- `lib/*` 不包含任何具体业务接口
+
+## 命令执行链路示例(以 `saas-cli reservation doctors` 为例)
+
+先看"流水线"(各层怎么接力),再看"每一步具体做了什么"。
+
+### 流水线(分层视角)
+
+```
+命令行输入
+   │  saas-cli reservation doctors
+   ▼
+cli.mjs ────────────────────── 入口:认出"reservation doctors"是哪条命令
+   ▼
+commands/reservation/doctors.mjs ── 命令逻辑:查医生
+   ▼
+lib/context.mjs ────────────── 准备:找 token、按 --env 选服务器地址
+   ▼
+api/employee.mjs ───────────── 说清"调哪个接口、传什么参数"
+   ▼
+lib/http.mjs ───────────────── 真正发请求、检查返回
+   ▼
+后端服务器 ──────────────────── 返回数据
+   ▼
+数据原路返回,打印到屏幕
+```
+
+### 每一步具体做了什么
+
+```
+$ saas-cli reservation doctors
+│
+├─ 1. cli.mjs(入口)
+│    ├─ 创建命令行程序框架(名称/版本/--help)
+│    ├─ 扫描 commands/ 目录,自动发现 reservation、config 两组命令
+│    ├─ 加载 reservation/ 下的命令文件(doctors.mjs 等各自注册自己)
+│    └─ 解析参数 → 命中"reservation 组下的 doctors 命令"
+│
+├─ 2. doctors 命令开始执行(commands/reservation/doctors.mjs)
+│    ├─ lib/context.mjs 准备运行环境:
+│    │    ├─ 读选项:--env(默认 test)、--token、--json、--verbose
+│    │    ├─ 找 token,顺序是:命令行 --token → SAAS_TOKEN → 配置文件
+│    │    ├─ 没找到?→ 直接报错退出(提示 config set-token)
+│    │    └─ 找到 → 按 --env 选地址:test → test.saas.lichidental.com
+│    └─ 调 api/employee.mjs 的 listDoctors(),参数:{delFlags:[0,2], storeUserPostIds:[1]}
+│         = "在职+试用的、岗位是医生的员工"
+│
+├─ 3. 发请求(lib/http.mjs)
+│    ├─ 先取版本号:GET 该环境的 index.html,解析出 v26.09.2.0
+│    ├─ 拼请求:POST /user/saas/t-lichi-user-store/getStoreUserListByParam
+│    │    请求头带上:token(身份)、Version、Content-Type
+│    ├─ 发出请求(15 秒超时)
+│    └─ 检查返回的 status:
+│         ├─ 200 → 继续  ├─ 401 → 报"token 失效"(退出码 3)
+│         └─ 其它 → 原样报后端错误信息(退出码 1)
+│
+└─ 4. 输出结果(回到 doctors.mjs)
+     ├─ 默认:stdout 打印 "共 N 位医生: 1. 姓名 userUid:xxx ..."
+     ├─ 加 --json:stdout 打印 {ok:true, env, command, data:{doctors:[...]}}
+     └─ 结束后退出码 0;任何一步出错 → 1/2/3/4 并给出原因和解决办法
+```
+
+新增命令时,你的命令走同样形状的链路:`commands`(编排)→ `api`(接口)→ `lib/http`(传输),区别只在第 2 步调用的 api 函数与参数。
+
+## 新增命令 checklist
+
+1. **查 `api/`**:所需接口是否已封装?有则直接用;没有则在对应域文件加函数(见下"接口层新增")
+2. **写命令文件** `commands/<主题>/<命令名>.mjs`:导出 `register(topic)`,用模板(见下)
+3. **本地验证**:`saas-cli <主题> <命令> --help` 看帮助;`--dry-run`(写操作)预览;真实跑通一次
+4. **补测试**:纯逻辑(参数解析/数据变换)加到 `test/`;`npm test` 全绿
+5. **补文档**:更新 `AGENTS.md` 命令清单与正文 + `docs/CLI使用手册.md`;新接口补进 `docs/api/openapi.yaml` 与 `docs/api/接口说明.md`,并采集样本到 `docs/samples/`
+6. **确认输出契约**:成功走 `ctx.out.success(...)`,失败直接 `throw CliError`,不要自行 `console.log` 数据
+
+## 命令模板(可直接复制)
+
+```js
+// commands/<主题>/<命令名>.mjs
+import { addCommonOptions } from "../../lib/options.mjs"
+import { buildContext } from "../../lib/context.mjs"
+import { CliError, EXIT_CODES } from "../../lib/errors.mjs"
+import { someApi } from "../../api/xxx.mjs"
+
+export function register(topic) {
+  addCommonOptions(
+    topic
+      .command("命令名")
+      .description("一句话描述(会出现在 --help)")
+      .requiredOption("--必填参数 <值>", "说明")
+      .option("--可选参数 <值>", "说明")
+  ).action(async function () {
+    const opts = this.opts()               // 命令级 + 通用参数
+    const { env, out, http } = buildContext(this)   // 无网络请求的命令用 buildContext(this, { needHttp: false })
+
+    // 1) 参数校验(尽早抛出,避免发出不必要的请求)
+    if (/**(非法条件)**/) {
+      throw new CliError("哪里错了", { exitCode: EXIT_CODES.USAGE, hint: "怎么改" })
+    }
+
+    // 2) 调 api
+    const res = await someApi(http, { ... })
+
+    // 3) 输出:data 给 --json;humanText 给人读
+    out.success("命令名", env, { /* 结构化数据 */ }, "人读摘要(多行字符串)")
+  })
+}
+```
+
+## 接口层(api/)新增方法
+
+```js
+/**
+ * 一句话说明
+ * @returns data: { ... }(按实测响应写)
+ */
+export function someApi(http, { paramA }) {
+  return http.post("/user/saas/xxx/yyy", { paramA })
+}
+```
+
+- 路径写全(以 `/user/` 开头);请求体按前端调用 + 实测校准,**不要写猜测的字段**
+- 时间格式、必填性以实测为准;不确定的在注释里明确写"未验证"
+
+## 约定
+
+- **输出**:stdout 只放数据(人读摘要或 `--json`);日志/进度走 stderr(`ctx.out.log` / `ctx.out.verboseLog`)
+- **退出码**(lib/errors.mjs):0 成功 / 1 业务失败 / 2 用法错误 / 3 认证失败 / 4 网络错误
+- **错误**:抛 `CliError(message, { exitCode, hint })`;`hint` 写"怎么解决"(例:提示用哪个参数替代)。入口会统一转成人读或 `--json` 输出
+- **不加交互**:所有输入靠参数,禁止 prompt / 等待输入(AI 与脚本要能无人值守跑)
+- **写操作防护**:写命令必须支持 `--dry-run`;生产环境加 `--yes` 门槛(参考 `commands/reservation/create.mjs`)
+- **重名/歧义**:用 `lib/match.mjs` 的 `pickOne`(唯一命中才通过,多条列候选报错)
+- **JSDoc 类型**:公共函数(`lib/`、`api/`)与命令 `register` 都带 JSDoc 类型注释,核心数据结构集中定义在 `lib/types.mjs`;新增函数请照此补齐——IDE 的跳转 / 悬停 / 重命名提示依赖它
+- **命名**:命令文件用 kebab-case;api 文件名与前端 `src/api/*.ts` 保持一致
+
+## 测试与文档要求
+
+- `npm test` 必须全绿;新增纯逻辑函数应有对应用例(参考 `test/match.test.mjs`)
+- CLI 冒烟用例(无需网络):验证帮助输出、退出码、`--json` 错误结构(参考 `test/cli.test.mjs`)
+- 文档更新点(缺一不可):
+  - `AGENTS.md`(AI 入口):命令清单表格 + 命令详情 + recipe(如有新流程)
+  - `docs/CLI使用手册.md`:命令详解 + 常见问题
+  - `docs/api/openapi.yaml` + `docs/api/接口说明.md` + `docs/samples/`(涉及新接口时)
+
+## 接口样本采集方法(更新文档用)
+
+1. 用 `--verbose` 跑一次命令,stderr 会包含每个请求的 URL、请求体、原始响应:
+   ```bash
+   saas-cli <命令...> --verbose --json > out.json 2> err.txt
+   ```
+2. 从 `err.txt` 提取:以 `→ POST <url>` 开头的是请求,`  请求体: {...}` 是请求体,`← HTTP 200 {...}` 是响应
+3. 按 `docs/samples/` 现有格式写入样本文件:
+   ```json
+   { "endpoint": "POST /user/saas/...", "capturedAt": "YYYY-MM-DD", "env": "test", "note": "说明", "requestBody": { }, "response": { } }
+   ```
+4. **脱敏**:样本中不得包含 token;同时更新 `docs/api/openapi.yaml` 中对应 schema(字段类型/必填/示例都要与样本一致)

package/lib/config.mjs

@@ -0,0 +1,109 @@
+// lib/config.mjs — token 配置持久化(平台配置目录)
+// 新路径:Windows %APPDATA%\saas-cli\config.json / 其他 $XDG_CONFIG_HOME/saas-cli/config.json
+// 旧路径(create-saas-cli)保留只读兼容:自动沿用旧配置,下次写入时迁移到新路径
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+const APP_DIR = "saas-cli"
+const LEGACY_APP_DIR = "create-saas-cli"
+
+/** 平台配置目录 @param {string} name @returns {string} */
+function configDir(name) {
+  const base =
+    process.platform === "win32"
+      ? process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming")
+      : process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config")
+  return path.join(base, name)
+}
+
+/** 配置文件路径(平台感知:Windows 用 %APPDATA%,其他用 ~/.config) @returns {string} */
+export function getConfigPath() {
+  return path.join(configDir(APP_DIR), "config.json")
+}
+
+/** 旧版配置文件路径(仅兼容读取) @returns {string} */
+export function getLegacyConfigPath() {
+  return path.join(configDir(LEGACY_APP_DIR), "config.json")
+}
+
+/** 读取 JSON 配置文件,失败返回 null @param {string} file @returns {object|null} */
+function tryReadConfig(file) {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(file, "utf8"))
+    return cfg && typeof cfg === "object" ? cfg : null
+  } catch {
+    return null
+  }
+}
+
+let legacyNotified = false
+
+/**
+ * 读取配置;文件不存在或损坏时返回空配置。
+ * 新路径缺失时兼容读取旧版(create-saas-cli)目录,读到后原样返回(下次写入自然迁移)。
+ * @returns {{profiles: Record<string, {token?: string, updatedAt?: string}>}}
+ */
+export function readConfig() {
+  const cfg = tryReadConfig(getConfigPath())
+  if (cfg) return cfg
+  const legacy = tryReadConfig(getLegacyConfigPath())
+  if (legacy) {
+    if (!legacyNotified) {
+      legacyNotified = true
+      console.error("(提示)检测到旧版配置目录 create-saas-cli,已自动沿用;下次写入将迁移到 saas-cli")
+    }
+    return legacy
+  }
+  return { profiles: {} }
+}
+
+/** 写入配置(文件权限 600) @param {{profiles: Record<string, {token?: string, updatedAt?: string}>}} config @returns {string} 写入的文件路径 */
+export function writeConfig(config) {
+  const file = getConfigPath()
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 })
+  try {
+    fs.chmodSync(file, 0o600)
+  } catch {
+    // Windows 上 chmod 语义有限,忽略
+  }
+  return file
+}
+
+/**
+ * token 优先级:命令行 --token > 环境变量 SAAS_TOKEN > 配置文件当前环境
+ * @param {{cliToken?: string, env: string}} options
+ * @returns {{token: string|null, source: string|null}}
+ */
+export function resolveToken({ cliToken, env }) {
+  if (cliToken) return { token: cliToken, source: "命令行 --token" }
+  if (process.env.SAAS_TOKEN) return { token: process.env.SAAS_TOKEN, source: "环境变量 SAAS_TOKEN" }
+  const cfg = readConfig()
+  const token = cfg?.profiles?.[env]?.token
+  if (token) return { token, source: `配置文件(profile: ${env})` }
+  return { token: null, source: null }
+}
+
+/** 保存某环境的 token @param {string} env @param {string} token @returns {string} 写入的文件路径 */
+export function setToken(env, token) {
+  const cfg = readConfig()
+  if (!cfg.profiles || typeof cfg.profiles !== "object") cfg.profiles = {}
+  cfg.profiles[env] = { ...(cfg.profiles[env] || {}), token, updatedAt: new Date().toISOString() }
+  return writeConfig(cfg)
+}
+
+/** 删除某环境的 token @param {string} env @returns {string|null} 删除后写入的文件路径;该环境未配置时返回 null */
+export function removeToken(env) {
+  const cfg = readConfig()
+  if (!cfg?.profiles?.[env]) return null
+  delete cfg.profiles[env]
+  return writeConfig(cfg)
+}
+
+/** token 打码展示 @param {string|undefined|null} token @returns {string} */
+export function maskToken(token) {
+  if (!token) return "(未配置)"
+  if (token.length <= 8) return "****"
+  return `${token.slice(0, 4)}****${token.slice(-4)}`
+}

package/lib/context.mjs

@@ -0,0 +1,49 @@
+// lib/context.mjs — 命令运行上下文:全局选项 → 环境 / token / 输出 / HTTP 请求器
+import { CliError, EXIT_CODES } from "./errors.mjs"
+import { createOutput } from "./output.mjs"
+import { createHttp } from "./http.mjs"
+import { resolveToken } from "./config.mjs"
+
+/**
+ * 在命令 action 中构建运行上下文
+ * @param {import("commander").Command} cmd 当前命令
+ * @param {{needHttp?: boolean}} [options]
+ * @returns {{env: string, opts: any, out: import("./types.mjs").Output, http: import("./types.mjs").Http|null}}
+ */
+export function buildContext(cmd, { needHttp = true } = {}) {
+  const opts = cmd.optsWithGlobals()
+  const env = opts.env
+  const out = createOutput({ json: Boolean(opts.json), verbose: Boolean(opts.verbose) })
+
+  let http = null
+  if (needHttp) {
+    const { token, source } = resolveToken({ cliToken: opts.token, env })
+    if (!token) {
+      throw new CliError(`环境 ${env} 未配置 token`, {
+        exitCode: EXIT_CODES.USAGE,
+        hint:
+          `配置方式(任选其一):\n` +
+          `    1) saas-cli auth login --env ${env} --token <token>\n` +
+          `    2) 设置环境变量 SAAS_TOKEN=<token>\n` +
+          `    3) 命令后加 --token <token>`,
+      })
+    }
+    out.verboseLog(`token 来源:${source}`)
+    http = createHttp({ env, token, verbose: Boolean(opts.verbose), log: out.verboseLog })
+  }
+  return { env, opts, out, http }
+}
+
+/**
+ * 用显式指定的 token 构建上下文(auth 登录/验证场景:token 尚未保存或需要单独验证)
+ * @param {import("commander").Command} cmd 当前命令
+ * @param {string} token 显式 token(不查配置文件)
+ * @returns {{env: string, opts: any, out: import("./types.mjs").Output, http: import("./types.mjs").Http}}
+ */
+export function buildContextWithToken(cmd, token) {
+  const opts = cmd.optsWithGlobals()
+  const env = opts.env
+  const out = createOutput({ json: Boolean(opts.json), verbose: Boolean(opts.verbose) })
+  const http = createHttp({ env, token, verbose: Boolean(opts.verbose), log: out.verboseLog })
+  return { env, opts, out, http }
+}

package/lib/errors.mjs

@@ -0,0 +1,61 @@
+// lib/errors.mjs — 错误类型与退出码约定
+// 退出码:0 成功 / 1 业务失败 / 2 用法错误 / 3 认证失败 / 4 网络错误
+
+/**
+ * 退出码约定
+ * @typedef {{OK: number, BUSINESS: number, USAGE: number, AUTH: number, NETWORK: number}} ExitCodes
+ */
+
+/** @type {ExitCodes} */
+export const EXIT_CODES = {
+  OK: 0,
+  BUSINESS: 1,
+  USAGE: 2,
+  AUTH: 3,
+  NETWORK: 4,
+}
+
+export class CliError extends Error {
+  /**
+   * @param {string} message 面向使用者的错误描述
+   * @param {{code?: string|number, exitCode?: number, hint?: string}} [options]
+   */
+  constructor(message, { code = "ERROR", exitCode = EXIT_CODES.BUSINESS, hint } = {}) {
+    super(message)
+    this.name = "CliError"
+    this.code = code
+    this.exitCode = exitCode
+    this.hint = hint
+  }
+}
+
+/**
+ * 把后端统一响应 {status, code, message, data} 中 status!=200 的情况转成 CliError
+ * @param {import("./types.mjs").ApiResponse} payload
+ * @returns {CliError}
+ */
+export function mapApiError(payload) {
+  const status = payload?.status
+  const msg = payload?.message || `接口返回错误(status=${status})`
+  if (status === 401) {
+    return new CliError(`认证失败:${msg}`, {
+      code: 401,
+      exitCode: EXIT_CODES.AUTH,
+      hint: "token 已失效,请重新登录:saas-cli auth login --env <环境> --token <新token>",
+    })
+  }
+  if (status === 999) {
+    return new CliError(`版本校验失败:${msg}`, {
+      code: 999,
+      hint: "工具会自动读取目标环境的最新版本号;若持续出现,请确认本机能访问 <环境地址>/index.html",
+    })
+  }
+  if (status === 403) {
+    return new CliError(`无权限:${msg}`, {
+      code: 403,
+      exitCode: EXIT_CODES.AUTH,
+      hint: "当前 token 对应账号没有该操作权限,请联系管理员开通",
+    })
+  }
+  return new CliError(msg, { code: status ?? "ERROR" })
+}