fima-cli 0.0.0-stage → 1.4.0

package/README.md

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+# fima-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Fima 财务报销系统的命令行客户端，需要配合 `fima-web` 服务使用。
+
+## npm 安装
+
+运行环境：Node.js 22 及以上、Python 3.8 及以上。Python 只使用标准库，无需额外安装 pip 依赖。macOS / Linux 需确保 `python3` 在 PATH 中；Windows 支持 `py -3`、`python3` 或 `python`。
+
+```bash
+npm install -g fima-cli
+fima --version
+fima --help
+```
+
+也可以使用 `pnpm add -g fima-cli` 安装，或直接运行 `npx fima-cli --help`。
+
+启动 `fima-web` 后，先设置服务器地址，再执行 `fima login` 登录。
+
+## 服务器地址配置
+
+首次使用必须设置服务器地址；没有配置时，业务命令会提示设置并退出，不会自动连接本机默认服务。
+
+```bash
+# 首次设置：支持 IP:端口，未写协议时补全为 http://
+fima config set-url 127.0.0.1:8000
+
+# 更换服务器：使用同一条命令覆盖已保存的地址
+fima config set-url https://fima.example.com
+
+# 查看已保存地址及当前生效地址
+fima config show
+fima login
+```
+
+配置保存在 `~/.fima/config.json`，重开终端仍有效；可用 `FIMA_CONFIG_FILE` 指定其他配置文件。支持 HTTP/HTTPS URL、域名、IPv4 和方括号形式的 IPv6（如 `[::1]:8000`），也支持部署在子路径下的服务（如 `https://fima.example.com/expenses`）。地址不得包含账号密码、查询参数或片段，端口范围为 1–65535。
+
+地址优先级为 **`--url` > `FIMA_URL` > 已保存配置**。前两种方式仅临时覆盖，不会修改配置文件：
+
+```bash
+fima --url 192.168.1.10:8000 whoami
+FIMA_URL=https://fima.example.com fima whoami
+```
+
+登录 Cookie 与服务器地址绑定，更换服务器后需重新登录，旧 Cookie 不会发往新地址。升级前保存的、未绑定地址的旧会话也需要重新登录。`--help`、`--version` 和设置配置的命令无需服务器地址。
+
+## 从源码运行
+
+先启动 `fima-web`，然后直接使用：
+
+```bash
+./fima -v
+./fima -h
+./fima config set-url 127.0.0.1:8000
+./fima login
+./fima whoami
+./fima create --json '{"title":"上海客户拜访","category":"差旅费","amount":1280,"date":"2026-07-12","invoice":"./invoice.pdf","submit":true}'
+./fima list
+./fima show 1
+./fima manager-approve --json '{"id":1,"operator":"李主管","comment":"同意"}'
+./fima finance-approve --json '{"id":1,"operator":"陈会计","comment":"票据无误"}'
+./fima pay --json '{"id":1,"operator":"陈出纳","comment":"已模拟打款"}'
+./fima logout
+```
+
+从源码安装为全局命令（macOS / Linux）：
+
+```bash
+./install.sh
+fima -h
+```
+
+请使用服务管理员提供的账号登录。执行 `login` 会拉起浏览器中的专用登录框，账号密码只在网页中填写；CLI 会自动检测登录完成并把会话 Cookie 保存在 `~/.fima/session.json`（可用 `FIMA_COOKIE_FILE` 覆盖）。网页会明确提示“CLI 登录已完成”，此时直接关闭当前页面即可。可通过 `--timeout` 调整等待时长（默认 5 分钟）。后续业务请求会自动携带与当前服务器匹配的 Cookie；可通过 `whoami` 查看当前登录账号，`logout` 会退出登录并清除本地会话 Cookie。
+
+## 参数传递
+
+字段超过两个的命令统一通过 `--json` 传入一个 JSON 对象，避免 Agent 在长参数列表中遗漏或混淆字段。先执行 `fima <command> -h` 查看该命令的 JSON 结构。
+
+```bash
+# 创建报销单：title、amount、date 必填
+fima create --json '{"title":"上海客户拜访","amount":1280,"date":"2026-07-12","category":"差旅费","description":"客户现场拜访","invoice":"./invoice.pdf","submit":true}'
+
+# 流程操作：id 必填；reject 还必须提供 comment
+fima submit --json '{"id":1}'
+fima manager-approve --json '{"id":1,"operator":"李主管","comment":"同意"}'
+fima reject --json '{"id":1,"operator":"李主管","comment":"缺少行程单"}'
+```
+
+`list`、`show` 和 `upload` 仍使用简洁的普通参数：`fima list --status submitted`、`fima show 1`、`fima upload 1 ./invoice.pdf`。

package/bin/fima.cjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+const candidates = process.platform === 'win32'
+  ? [['py', '-3'], ['python3'], ['python']]
+  : [['python3']];
+const python = candidates.find(([command, ...args]) => {
+  const result = spawnSync(command, [
+    ...args, '-c', 'import sys; sys.exit(0 if sys.version_info >= (3, 8) else 1)',
+  ], { stdio: 'ignore' });
+  return !result.error && result.status === 0;
+});
+
+if (!python) {
+  console.error('错误：Fima CLI 需要 Python 3.8 或更高版本，请安装 Python 并将其加入 PATH。');
+  process.exit(1);
+}
+
+const [command, ...args] = python;
+const result = spawnSync(command, [
+  ...args, path.join(__dirname, '..', 'fima.py'), ...process.argv.slice(2),
+], { stdio: 'inherit' });
+
+if (result.error) {
+  console.error(`错误：无法启动 Fima CLI：${result.error.message}`);
+  process.exit(1);
+}
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+} else {
+  process.exit(result.status ?? 1);
+}

package/fima.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""Fima CLI - 通过命令行操作 Fima 财务报销系统。"""
+from __future__ import annotations
+import argparse, json, math, mimetypes, os, sys, tempfile, time, webbrowser
+from http.cookies import SimpleCookie
+from pathlib import Path
+from urllib.parse import quote, urlsplit, urlunsplit
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+VERSION="1.4.0"
+
+def config_file(): return Path(os.environ.get("FIMA_CONFIG_FILE", Path.home() / ".fima" / "config.json"))
+
+def normalize_url(value):
+    if not isinstance(value, str) or not value.strip():
+        fail("服务器地址不能为空，请提供 URL 或 IP:端口")
+    value=value.strip()
+    if any(c.isspace() or ord(c)<32 or ord(c)==127 for c in value) or "\\" in value:
+        fail("服务器地址不能包含空白、控制字符或反斜杠")
+    if "://" not in value:
+        value="http://"+value
+    try:
+        parsed=urlsplit(value)
+        host=parsed.hostname
+        port=parsed.port
+    except ValueError:
+        fail("服务器地址格式不正确，端口必须是 1–65535 的整数，IPv6 地址请使用方括号")
+    if parsed.scheme not in ("http", "https") or not host:
+        fail("服务器地址必须是有效的 HTTP/HTTPS URL 或 IP:端口")
+    if parsed.username is not None or parsed.password is not None:
+        fail("服务器地址不能包含账号密码，请使用 fima login 登录")
+    if "?" in value or "#" in value:
+        fail("服务器地址不能包含查询参数或片段")
+    if port == 0 or parsed.netloc.endswith(":"):
+        fail("服务器端口必须是 1–65535 的整数")
+    try:
+        host=host.encode("idna").decode("ascii")
+    except UnicodeError:
+        fail("服务器主机名格式不正确")
+    if ":" not in host and any(not (c.isalnum() or c in ".-_") for c in host):
+        fail("服务器主机名格式不正确")
+    authority=f"[{host}]" if ":" in host else host
+    if port is not None and (parsed.scheme, port) not in (("http", 80), ("https", 443)):
+        authority+=f":{port}"
+    return urlunsplit((parsed.scheme, authority, parsed.path.rstrip("/"), "", ""))
+
+def read_config():
+    try:
+        data=json.loads(config_file().read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return {}
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        fail("无法读取服务器配置，请运行 fima config set-url <地址> 重新设置")
+    if not isinstance(data, dict) or not isinstance(data.get("url"), str):
+        fail("服务器配置格式不正确，请运行 fima config set-url <地址> 重新设置")
+    return data
+
+def resolve_url(override=None):
+    if override is not None:
+        return normalize_url(override)
+    if "FIMA_URL" in os.environ:
+        return normalize_url(os.environ["FIMA_URL"])
+    saved=read_config().get("url")
+    if saved is None:
+        fail("尚未设置服务器地址，请先执行：fima config set-url <URL或IP:端口>\n例如：fima config set-url 127.0.0.1:8000")
+    return normalize_url(saved)
+
+def set_url(a):
+    url=normalize_url(a.server_url)
+    target=config_file(); temporary=None
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", dir=target.parent, delete=False) as f:
+            temporary=Path(f.name)
+            json.dump({"url":url}, f, ensure_ascii=False)
+            f.write("\n")
+        temporary.replace(target)
+    except OSError:
+        fail("无法保存服务器配置，请检查配置目录的写入权限")
+    finally:
+        if temporary is not None and temporary.exists():
+            temporary.unlink()
+    print(f"已保存服务器地址：{url}")
+    print("后续命令将使用该地址；新服务器请先执行 fima login。")
+    if a.url is not None or "FIMA_URL" in os.environ:
+        print("提示：--url 和 FIMA_URL 的优先级高于保存的配置。")
+
+def show_config(a):
+    saved=read_config().get("url")
+    print(f"已保存地址：{normalize_url(saved) if saved is not None else '未设置'}")
+    print(f"当前生效地址：{resolve_url(a.url)}")
+
+def cookie_file(): return Path(os.environ.get("FIMA_COOKIE_FILE", Path.home() / ".fima" / "session.json"))
+def load_cookie():
+    try:
+        session=json.loads(cookie_file().read_text(encoding="utf-8"))
+        if isinstance(session,dict) and session.get("url")==ARGS.url and isinstance(session.get("cookie"),str):
+            return session["cookie"]
+    except (OSError, UnicodeError, json.JSONDecodeError): pass
+    return None
+def save_cookie(value):
+    target=cookie_file(); target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps({"url":ARGS.url,"cookie":value}),encoding="utf-8"); target.chmod(0o600)
+def clear_cookie():
+    try: cookie_file().unlink()
+    except FileNotFoundError: pass
+
+def request(method,path,data=None,file=None,include_headers=False):
+    url=ARGS.url.rstrip("/")+path; headers={}; body=None
+    if cookie:=load_cookie(): headers["Cookie"]=cookie
+    if file:
+        p=Path(file)
+        if not p.is_file(): fail(f"文件不存在：{p}")
+        boundary="----FimaBoundary7MA4YWxk"; raw=p.read_bytes(); ctype=mimetypes.guess_type(p.name)[0] or "application/octet-stream"
+        body=(f"--{boundary}\r\nContent-Disposition: form-data; name=\"file\"; filename=\"{p.name}\"\r\nContent-Type: {ctype}\r\n\r\n".encode()+raw+f"\r\n--{boundary}--\r\n".encode())
+        headers["Content-Type"]=f"multipart/form-data; boundary={boundary}"
+    elif data is not None:
+        body=json.dumps(data,ensure_ascii=False).encode();headers["Content-Type"]="application/json"
+    try:
+        with urlopen(Request(url,data=body,headers=headers,method=method),timeout=10) as r:
+            result=json.loads(r.read())
+            return (result,r.headers) if include_headers else result
+    except HTTPError as e:
+        try: msg=json.loads(e.read()).get("error",str(e))
+        except Exception: msg=str(e)
+        fail(msg)
+    except URLError: fail(f"无法连接 Fima Web：{url}\n请检查服务是否启动，或执行 fima config set-url <地址> 更换服务器。")
+
+def fail(msg): print(f"错误：{msg}",file=sys.stderr);raise SystemExit(1)
+def json_object(value):
+    try: data=json.loads(value)
+    except json.JSONDecodeError as e: raise argparse.ArgumentTypeError(f"不是合法 JSON：{e.msg}")
+    if not isinstance(data,dict): raise argparse.ArgumentTypeError("JSON 必须是对象，例如：'{\"id\": 1}'")
+    return data
+def required(payload,key):
+    value=payload.get(key)
+    if value is None or value=="": fail(f"JSON 缺少必填字段：{key}")
+    return value
+def optional_string(payload,key,default=""):
+    value=payload.get(key,default)
+    if not isinstance(value,str): fail(f"JSON 字段 {key} 必须是字符串")
+    return value
+def positive_number(payload,key):
+    value=required(payload,key)
+    if isinstance(value,bool) or not isinstance(value,(int,float)) or not math.isfinite(value) or value<=0: fail(f"JSON 字段 {key} 必须是大于 0 的数字")
+    return value
+def allow_fields(payload,*fields):
+    unknown=set(payload)-set(fields)
+    if unknown: fail(f"JSON 包含不支持的字段：{', '.join(sorted(unknown))}")
+def fmt_money(x): return f"¥{float(x):,.2f}"
+def print_item(x,detail=False):
+    invoice=x.get("invoice_name") or "未上传"
+    print(f"{x['id']:>3}  {x['expense_no']:<20} {x['status_label']:<10} {fmt_money(x['amount']):>12}  {x['title']}  [{invoice}]")
+    if detail:
+        print(f"     申请人：{x['applicant']} / {x['department']}  日期：{x['expense_date']}  类别：{x['category']}")
+        print(f"     说明：{x.get('description') or '-'}")
+        for l in reversed(x.get("logs",[])): print(f"     · {l['created_at'].replace('T',' ')} {l['operator']}：{l['comment']}")
+
+def create(a):
+    payload=a.payload
+    allow_fields(payload,"title","amount","date","category","description","applicant","department","invoice","submit")
+    title=required(payload,"title"); date=required(payload,"date")
+    if not isinstance(title,str) or not isinstance(date,str): fail("JSON 字段 title 和 date 必须是字符串")
+    invoice=payload.get("invoice")
+    if invoice is not None and not isinstance(invoice,str): fail("JSON 字段 invoice 必须是文件路径字符串")
+    submit=payload.get("submit",False)
+    if not isinstance(submit,bool): fail("JSON 字段 submit 必须是 true 或 false")
+    data={"title":title,"category":optional_string(payload,"category","其他"),"amount":positive_number(payload,"amount"),"expense_date":date,"description":optional_string(payload,"description"),"applicant":optional_string(payload,"applicant","王小明"),"department":optional_string(payload,"department","产品研发部")}
+    x=request("POST","/api/expenses",data); print(f"已创建：{x['expense_no']}（ID: {x['id']}）")
+    if invoice is not None:
+        request("POST",f"/api/expenses/{x['id']}/invoice",file=invoice);print(f"已上传发票：{Path(invoice).name}")
+    if submit: request("POST",f"/api/expenses/{x['id']}/submit",{});print("已提交审核")
+def list_items(a):
+    rows=request("GET","/api/expenses"+(f"?status={a.status}" if a.status else ""));print(" ID  报销单号             状态               金额  事项  [发票]")
+    print("-"*90)
+    for x in rows: print_item(x)
+    print(f"\n共 {len(rows)} 条")
+def show(a): print_item(request("GET",f"/api/expenses/{a.id}"),True)
+def upload(a): x=request("POST",f"/api/expenses/{a.id}/invoice",file=a.file);print(f"发票已上传：{x['invoice_name']}")
+def action(a):
+    names={"submit":"提交审核","manager-approve":"主管审批通过","finance-approve":"财务审批通过","reject":"驳回","pay":"确认模拟打款"}
+    payload=a.payload; expense_id=required(payload,"id")
+    allow_fields(payload,"id","operator","comment")
+    if isinstance(expense_id,bool) or not isinstance(expense_id,int) or expense_id<=0: fail("JSON 字段 id 必须是正整数")
+    operator=optional_string(payload,"operator",a.default_operator)
+    comment=optional_string(payload,"comment",a.default_comment)
+    if a.command=="reject" and "comment" not in payload: fail("JSON 缺少必填字段：comment")
+    x=request("POST",f"/api/expenses/{expense_id}/{a.command}",{"operator":operator,"comment":comment});print(f"操作成功：{names[a.command]}，当前状态：{x['status_label']}")
+def login(a):
+    if a.timeout <= 0: fail("--timeout 必须大于 0")
+    session=request("POST","/api/cli-login",{})
+    browser_url=(ARGS.url.rstrip("/")+"/?cli_login="+quote(session["id"],safe="")+"&cli_token="+quote(session["browser_token"],safe=""))
+    print("正在打开浏览器，请在网页中完成登录。登录成功后可直接关闭该页面。")
+    if not webbrowser.open(browser_url, new=2): print(f"浏览器未自动打开，请访问：{browser_url}")
+    print("等待浏览器登录完成…", flush=True)
+    deadline=time.monotonic()+a.timeout
+    while time.monotonic()<deadline:
+        result=request("GET",f"/api/cli-login/{quote(session['id'],safe='')}?token={quote(session['poll_token'],safe='')}")
+        if result["status"]=="complete":
+            save_cookie(result["cookie"])
+            print(f"登录成功：{result['username']}（浏览器页面现在可以关闭）")
+            return
+        time.sleep(1)
+    fail("等待网页登录超时，请重新执行 fima login")
+def logout(a):
+    request("POST","/api/logout",{});clear_cookie();print("已退出登录")
+def whoami(a):
+    user=request("GET","/api/me");print(f"当前登录用户：{user.get('display_name') or user['username']} (@{user['username']})")
+
+parser=argparse.ArgumentParser(prog="fima",description="Fima 财务报销命令行工具",epilog="多字段命令使用 JSON：fima create --json '{\"title\": \"客户拜访\", \"amount\": 280, \"date\": \"2026-07-12\"}'")
+parser.add_argument("-v","--version",action="version",version=f"fima {VERSION}")
+parser.add_argument("--url",help="本次请求的服务器 URL 或 IP:端口；优先级：--url > FIMA_URL > 保存的配置")
+sub=parser.add_subparsers(dest="command",title="支持的指令",required=True)
+p=sub.add_parser("config",help="设置、更换或查看服务器地址")
+config_sub=p.add_subparsers(dest="config_command",required=True)
+c=config_sub.add_parser("set-url",help="保存或更换服务器 URL / IP:端口",description="保存服务器地址供后续命令使用；未写协议时默认 HTTP，更换服务器后需登录新服务器。")
+c.add_argument("server_url",metavar="ADDRESS",help="例如 https://fima.example.com 或 192.168.1.10:8000")
+c.set_defaults(func=set_url)
+c=config_sub.add_parser("show",help="查看保存的地址及当前生效地址");c.set_defaults(func=show_config)
+p=sub.add_parser("login",help="打开浏览器登录并保存 Cookie");p.add_argument("--timeout",type=int,default=300,help="等待网页登录完成的秒数（默认：300）");p.set_defaults(func=login)
+p=sub.add_parser("logout",help="退出登录并清除本地 Cookie");p.set_defaults(func=logout)
+p=sub.add_parser("whoami",help="查看当前登录账号");p.set_defaults(func=whoami)
+p=sub.add_parser("create",help="创建报销单（使用 JSON 传递字段）");p.add_argument("--json",dest="payload",required=True,type=json_object,metavar="JSON",help='JSON 对象；必填 title、amount、date；可选 category、description、applicant、department、invoice、submit');p.set_defaults(func=create)
+p=sub.add_parser("list",help="查看报销单列表");p.add_argument("--status",choices=["draft","submitted","manager_approved","finance_approved","paid","rejected"]);p.set_defaults(func=list_items)
+p=sub.add_parser("show",help="查看报销单详情和流转记录");p.add_argument("id",type=int);p.set_defaults(func=show)
+p=sub.add_parser("upload",help="上传或替换发票");p.add_argument("id",type=int);p.add_argument("file");p.set_defaults(func=upload)
+for cmd,help_text,default_operator in [("submit","提交报销单","王小明"),("manager-approve","主管审核通过","李主管"),("finance-approve","财务审核通过","陈会计"),("pay","确认模拟打款","陈出纳"),("reject","驳回报销单","李主管")]:
+    json_help='JSON 对象；必填 id；可选 operator、comment' if cmd!="reject" else 'JSON 对象；必填 id、comment；可选 operator'
+    p=sub.add_parser(cmd,help=f"{help_text}（使用 JSON 传递字段）");p.add_argument("--json",dest="payload",required=True,type=json_object,metavar="JSON",help=json_help);p.set_defaults(func=action,default_operator=default_operator,default_comment=help_text)
+ARGS=parser.parse_args()
+if __name__=="__main__":
+    if ARGS.command != "config":
+        ARGS.url=resolve_url(ARGS.url)
+    ARGS.func(ARGS)

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "fima-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.4.0",
+  "description": "Command-line client for the Fima expense reimbursement system",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chujianyun/fima-cli.git"
+  },
+  "bin": {
+    "fima": "bin/fima.cjs"
+  },
+  "files": [
+    "bin/fima.cjs",
+    "fima.py"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "npm test"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}