fima-cli 0.0.0-stage → 1.3.0

package/README.md

@@ -1,3 +1,60 @@
-# 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` 登录，再使用业务指令。
+
+## 从源码运行
+
+先启动 `fima-web`，然后直接使用：
+
+```bash
+./fima -v
+./fima -h
+./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
+```
+
+服务默认地址为 `http://127.0.0.1:8000`，可设置 `FIMA_URL`，或在子命令前传入 `--url`，例如 `fima --url https://your-fima.example.com login`。请使用服务管理员提供的账号登录。执行 `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,141 @@
+#!/usr/bin/env python3
+"""Fima CLI - 通过命令行操作 Fima 财务报销系统。"""
+from __future__ import annotations
+import argparse, json, math, mimetypes, os, sys, time, webbrowser
+from http.cookies import SimpleCookie
+from pathlib import Path
+from urllib.parse import quote
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+VERSION="1.3.0"; DEFAULT_URL=os.environ.get("FIMA_URL","http://127.0.0.1:8000")
+
+def cookie_file(): return Path(os.environ.get("FIMA_COOKIE_FILE", Path.home() / ".fima" / "session.json"))
+def load_cookie():
+    try: return json.loads(cookie_file().read_text(encoding="utf-8"))["cookie"]
+    except (OSError, KeyError, json.JSONDecodeError): return None
+def save_cookie(value):
+    target=cookie_file(); target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps({"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请先运行：cd fima-web && python3 app.py")
+
+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",default=DEFAULT_URL,help=f"Fima Web 地址（默认：{DEFAULT_URL}）")
+sub=parser.add_subparsers(dest="command",title="支持的指令",required=True)
+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__": 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.3.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/"
+  }
+}