document: 承認状況取得サブコマンドを追加 (#20)

GET /api/v1/documents/{docid}/status を呼び出す `xp document status`
サブコマンドを追加。--history で全バージョンの承認履歴取得、
--jq で gojq フィルタに対応。

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: buty4649

README.md

@@ -97,6 +97,14 @@ cat search.json | xp document search --body -
 xp document search --size 100 --page 2
 ```
 
+### ドキュメントの承認状況取得
+
+```sh
+xp document status 266248                   # 最新版の承認状況（JSON）
+xp document status 266248 --history         # 全バージョンの承認履歴も含める
+xp document status 266248 --jq '.document.status.name'
+```
+
 ### ドキュメントのPDFダウンロード
 
 ```sh

cmd/document.go

@@ -38,6 +38,9 @@ var (
 	docDeleteJQ     string
 
 	docDownloadOutput string
+
+	docStatusHistory bool
+	docStatusJQ      string
 )
 
 var documentCmd = &cobra.Command{
@@ -112,6 +115,18 @@ By default the command prompts for confirmation. Pass --yes to skip it.`,
 	RunE: runDocumentDelete,
 }
 
+var documentStatusCmd = &cobra.Command{
+	Use:   "status <docid>",
+	Short: "Get document approval status",
+	Long: `Retrieve the approval status of a document via GET /api/v1/documents/{docid}/status.
+
+The response is returned as JSON and contains the current status, step,
+writer, last approver, and the approval flow. Pass --history to include
+approval histories for all past versions.`,
+	Args: cobra.ExactArgs(1),
+	RunE: runDocumentStatus,
+}
+
 var documentDownloadCmd = &cobra.Command{
 	Use:   "download <docid>",
 	Short: "Download a document as PDF",
@@ -133,6 +148,7 @@ func init() {
 	documentCmd.AddCommand(documentGetCmd)
 	documentCmd.AddCommand(documentEditCmd)
 	documentCmd.AddCommand(documentDeleteCmd)
+	documentCmd.AddCommand(documentStatusCmd)
 	documentCmd.AddCommand(documentDownloadCmd)
 
 	f := documentSearchCmd.Flags()
@@ -162,6 +178,10 @@ func init() {
 	df.StringVarP(&docDeleteOutput, "output", "o", "", "output format: table|json (default: table on TTY, json otherwise)")
 	df.StringVar(&docDeleteJQ, "jq", "", "apply a gojq filter to the JSON response (forces JSON output)")
 
+	sf := documentStatusCmd.Flags()
+	sf.BoolVar(&docStatusHistory, "history", false, "include approval histories for all versions")
+	sf.StringVar(&docStatusJQ, "jq", "", "apply a gojq filter to the JSON response")
+
 	dlf := documentDownloadCmd.Flags()
 	dlf.StringVarP(&docDownloadOutput, "output", "o", "", "output path: FILE, DIR/, or - for stdout (default: server-provided filename in current directory)")
 }
@@ -333,6 +353,25 @@ func runDocumentDelete(cmd *cobra.Command, args []string) error {
 	})
 }
 
+func runDocumentStatus(cmd *cobra.Command, args []string) error {
+	docID, err := parseDocID(args[0])
+	if err != nil {
+		return err
+	}
+	client, err := newClientFromFlags(cmd.Context())
+	if err != nil {
+		return err
+	}
+	raw, err := client.GetDocumentStatus(cmd.Context(), docID, docStatusHistory)
+	if err != nil {
+		return err
+	}
+	if docStatusJQ != "" {
+		return runJQ(raw, docStatusJQ)
+	}
+	return writeJSON(os.Stdout, raw)
+}
+
 func runDocumentDownload(cmd *cobra.Command, args []string) error {
 	docID, err := parseDocID(args[0])
 	if err != nil {

cmd/schema.go

@@ -25,6 +25,7 @@ Supported aliases map to the CLI's commands:
   document.update   PATCH  /api/v1/documents/{docid}
   document.delete   DELETE /api/v1/documents/{docid}
   document.download GET    /api/v1/documents/{docid}/pdf
+  document.status   GET    /api/v1/documents/{docid}/status
 
 Run without arguments to list supported aliases.`,
 	Args: cobra.MaximumNArgs(1),

internal/schema/document.status.json

@@ -0,0 +1,85 @@
+{
+  "method": "GET",
+  "path": "/api/v1/documents/{docid}/status",
+  "summary": "書類承認状況取得",
+  "description": "指定された書類 ID の最新版の承認状況を取得する。閲覧権限が必要。\n",
+  "parameters": [
+    {
+      "name": "docid",
+      "in": "path",
+      "type": "integer",
+      "required": true,
+      "description": "書類ID"
+    },
+    {
+      "name": "history",
+      "in": "query",
+      "type": "boolean",
+      "required": false,
+      "description": "true の場合、全バージョンの承認履歴情報を含めて返す。既定は false。"
+    }
+  ],
+  "response": {
+    "type": "object",
+    "properties": {
+      "document": {
+        "type": "object",
+        "description": "書類情報",
+        "properties": {
+          "docid": {
+            "type": "integer",
+            "description": "書類ID"
+          },
+          "title1": {
+            "type": "string",
+            "description": "件名1"
+          },
+          "title2": {
+            "type": "string",
+            "description": "件名2"
+          },
+          "form": {
+            "type": "object",
+            "description": "フォーム情報 (id, code, name)"
+          },
+          "route": {
+            "type": "object",
+            "description": "承認ルート情報 (code, name)"
+          },
+          "type": {
+            "type": "string",
+            "description": "フォーム種別 (standard: 通常フォーム / workflow: ワークフローフォーム)"
+          },
+          "status": {
+            "type": "object",
+            "description": "書類状態 (code: 0=下書き, 1=承認中, 2=保留中, 3=却下, 4=差し戻され, 5=差し戻し, 6=承認完了)"
+          },
+          "step": {
+            "type": "object",
+            "description": "ステップ情報 (max, current)"
+          },
+          "current_version": {
+            "type": "integer",
+            "description": "現在バージョン番号"
+          },
+          "writer": {
+            "type": "object",
+            "description": "申請者情報 (usercode, username, stampname, datetime)"
+          },
+          "lastaprv": {
+            "type": "object",
+            "description": "最終承認者情報 (usercode, username, stampname, datetime)"
+          },
+          "flow_versions": {
+            "type": "array",
+            "description": "最新バージョンの承認フロー結果。通常フォームの場合は空配列。"
+          },
+          "histories": {
+            "type": "array",
+            "description": "承認履歴情報 (version ごと)。クエリパラメータ history が true の場合に返る。通常フォームの場合は空配列。"
+          }
+        }
+      }
+    }
+  }
+}

internal/schema/schema_test.go

@@ -14,6 +14,7 @@ func TestAliases_Sorted(t *testing.T) {
 		"document.download",
 		"document.get",
 		"document.search",
+		"document.status",
 		"document.update",
 		"form.list",
 		"form.show",
@@ -140,6 +141,31 @@ func TestLookup_DocumentDownload(t *testing.T) {
 	}
 }
 
+func TestLookup_DocumentStatus(t *testing.T) {
+	op, err := Lookup("document.status")
+	if err != nil {
+		t.Fatalf("Lookup: %v", err)
+	}
+	if op["method"] != "GET" {
+		t.Errorf("method = %v", op["method"])
+	}
+	if op["path"] != "/api/v1/documents/{docid}/status" {
+		t.Errorf("path = %v", op["path"])
+	}
+	params, _ := op["parameters"].([]any)
+	if len(params) != 2 {
+		t.Fatalf("parameters = %v", params)
+	}
+	docid, _ := params[0].(map[string]any)
+	if docid["name"] != "docid" || docid["required"] != true {
+		t.Errorf("docid param = %v", docid)
+	}
+	history, _ := params[1].(map[string]any)
+	if history["name"] != "history" || history["in"] != "query" {
+		t.Errorf("history param = %v", history)
+	}
+}
+
 func TestLookup_DocumentDelete(t *testing.T) {
 	op, err := Lookup("document.delete")
 	if err != nil {

internal/xpoint/client.go

@@ -355,6 +355,24 @@ func (c *Client) DeleteDocument(ctx context.Context, docID int) (*DeleteDocument
 	return &out, nil
 }
 
+// GetDocumentStatus calls GET /api/v1/documents/{docid}/status.
+// When history is true, approval histories for every version are included.
+// The response shape is complex (form, status, step, flow_results, etc.),
+// so it is returned as raw JSON for the caller to interpret.
+func (c *Client) GetDocumentStatus(ctx context.Context, docID int, history bool) (json.RawMessage, error) {
+	path := fmt.Sprintf("/api/v1/documents/%d/status", docID)
+	var q url.Values
+	if history {
+		q = url.Values{}
+		q.Set("history", "true")
+	}
+	var out json.RawMessage
+	if err := c.do(ctx, http.MethodGet, path, q, nil, &out); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
 // DownloadPDF calls GET /api/v1/documents/{docid}/pdf and returns the PDF
 // bytes and the server-provided filename (parsed from Content-Disposition,
 // which may use RFC 5987 encoding). The filename is empty when the server

internal/xpoint/client_test.go

@@ -356,6 +356,52 @@ func TestDocumentURL(t *testing.T) {
 	}
 }
 
+func TestGetDocumentStatus(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet {
+			t.Errorf("method = %s, want GET", r.Method)
+		}
+		if r.URL.Path != "/api/v1/documents/999/status" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		if r.URL.Query().Has("history") {
+			t.Errorf("history query should be omitted, got %q", r.URL.Query().Get("history"))
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"document":{"docid":999,"status":{"code":1,"name":"承認中"}}}`))
+	}))
+	defer srv.Close()
+
+	c := clientForServer(srv)
+	raw, err := c.GetDocumentStatus(context.Background(), 999, false)
+	if err != nil {
+		t.Fatalf("GetDocumentStatus: %v", err)
+	}
+	var decoded map[string]any
+	if err := json.Unmarshal(raw, &decoded); err != nil {
+		t.Fatalf("raw not JSON: %v (%s)", err, string(raw))
+	}
+	doc, _ := decoded["document"].(map[string]any)
+	if doc["docid"].(float64) != 999 {
+		t.Errorf("docid = %v", doc["docid"])
+	}
+}
+
+func TestGetDocumentStatus_WithHistory(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if got := r.URL.Query().Get("history"); got != "true" {
+			t.Errorf("history = %q, want true", got)
+		}
+		_, _ = w.Write([]byte(`{"document":{"docid":1}}`))
+	}))
+	defer srv.Close()
+
+	c := clientForServer(srv)
+	if _, err := c.GetDocumentStatus(context.Background(), 1, true); err != nil {
+		t.Fatalf("GetDocumentStatus: %v", err)
+	}
+}
+
 func TestDownloadPDF(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.Method != http.MethodGet {