document: コメントの追加・取得・更新・削除サブコマンドを追加 (#23)

- xp document comment add <docid>: POST /api/v1/documents/{docid}/comments
- xp document comment get <docid>: GET /api/v1/documents/{docid}/comments
- xp document comment edit <docid> <seq>: PATCH /api/v1/documents/{docid}/comments/{seq}
- xp document comment delete <docid> <seq>: DELETE /api/v1/documents/{docid}/comments/{seq}
- schema document.comment.add/get/edit/delete を追加

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

Author: buty4649

README.md

@@ -124,6 +124,18 @@ xp document open 266248              # 既定のブラウザで書類を開く
 xp document open 266248 --no-browser # URLだけ出力（ブラウザは起動しない）
 ```
 
+### ドキュメントのコメント操作
+
+```sh
+xp document comment get 266248                              # コメント一覧
+xp document comment add 266248 --content "承認お願いします"  # コメント追加
+xp document comment add 266248 --content "重要" --attention  # 重要コメント
+xp document comment edit 266248 2 --content "修正後"         # 内容を更新
+xp document comment edit 266248 2 --attention 1              # 重要フラグだけ更新
+xp document comment delete 266248 2                          # コメント削除（確認あり）
+xp document comment delete 266248 2 -y                       # 確認なしで削除
+```
+
 ### ドキュメントのPDFダウンロード
 
 ```sh

cmd/document.go

@@ -43,6 +43,20 @@ var (
 	docStatusJQ      string
 
 	docOpenNoBrowser bool
+
+	docCommentAddContent    string
+	docCommentAddAttention  bool
+	docCommentAddOutput     string
+	docCommentAddJQ         string
+	docCommentGetOutput     string
+	docCommentGetJQ         string
+	docCommentEditContent   string
+	docCommentEditAttention string
+	docCommentEditOutput    string
+	docCommentEditJQ        string
+	docCommentDeleteYes     bool
+	docCommentDeleteOutput  string
+	docCommentDeleteJQ      string
 )
 
 var documentCmd = &cobra.Command{
@@ -140,6 +154,51 @@ Pass --no-browser (or -n) to print the URL without launching the browser.`,
 	RunE: runDocumentOpen,
 }
 
+var documentCommentCmd = &cobra.Command{
+	Use:   "comment",
+	Short: "Manage document comments",
+}
+
+var documentCommentAddCmd = &cobra.Command{
+	Use:   "add <docid>",
+	Short: "Add a comment to a document",
+	Long: `Add a comment to a document via POST /api/v1/documents/{docid}/comments.
+
+The comment body is provided with --content (required). Pass --attention
+to mark the comment as important.`,
+	Args: cobra.ExactArgs(1),
+	RunE: runDocumentCommentAdd,
+}
+
+var documentCommentGetCmd = &cobra.Command{
+	Use:   "get <docid>",
+	Short: "Get comments on a document",
+	Long:  `List comments on a document via GET /api/v1/documents/{docid}/comments.`,
+	Args:  cobra.ExactArgs(1),
+	RunE:  runDocumentCommentGet,
+}
+
+var documentCommentEditCmd = &cobra.Command{
+	Use:   "edit <docid> <seq>",
+	Short: "Update a comment",
+	Long: `Update a comment via PATCH /api/v1/documents/{docid}/comments/{seq}.
+
+At least one of --content / --attention must be provided. --attention accepts
+"0" (normal) or "1" (important); omit to leave unchanged.`,
+	Args: cobra.ExactArgs(2),
+	RunE: runDocumentCommentEdit,
+}
+
+var documentCommentDeleteCmd = &cobra.Command{
+	Use:   "delete <docid> <seq>",
+	Short: "Delete a comment",
+	Long: `Delete a comment via DELETE /api/v1/documents/{docid}/comments/{seq}.
+
+By default the command prompts for confirmation. Pass --yes to skip it.`,
+	Args: cobra.ExactArgs(2),
+	RunE: runDocumentCommentDelete,
+}
+
 var documentDownloadCmd = &cobra.Command{
 	Use:   "download <docid>",
 	Short: "Download a document as PDF",
@@ -164,6 +223,11 @@ func init() {
 	documentCmd.AddCommand(documentStatusCmd)
 	documentCmd.AddCommand(documentDownloadCmd)
 	documentCmd.AddCommand(documentOpenCmd)
+	documentCmd.AddCommand(documentCommentCmd)
+	documentCommentCmd.AddCommand(documentCommentAddCmd)
+	documentCommentCmd.AddCommand(documentCommentGetCmd)
+	documentCommentCmd.AddCommand(documentCommentEditCmd)
+	documentCommentCmd.AddCommand(documentCommentDeleteCmd)
 
 	f := documentSearchCmd.Flags()
 	f.StringVar(&docSearchBody, "body", "", "search condition JSON: inline, file path, or - for stdin")
@@ -201,6 +265,27 @@ func init() {
 
 	of := documentOpenCmd.Flags()
 	of.BoolVarP(&docOpenNoBrowser, "no-browser", "n", false, "print the URL without launching the browser")
+
+	caf := documentCommentAddCmd.Flags()
+	caf.StringVar(&docCommentAddContent, "content", "", "comment content (required)")
+	caf.BoolVar(&docCommentAddAttention, "attention", false, "mark as important comment (attentionflg=1)")
+	caf.StringVarP(&docCommentAddOutput, "output", "o", "", "output format: table|json (default: table on TTY, json otherwise)")
+	caf.StringVar(&docCommentAddJQ, "jq", "", "apply a gojq filter to the JSON response (forces JSON output)")
+
+	cgf := documentCommentGetCmd.Flags()
+	cgf.StringVarP(&docCommentGetOutput, "output", "o", "", "output format: table|json (default: table on TTY, json otherwise)")
+	cgf.StringVar(&docCommentGetJQ, "jq", "", "apply a gojq filter to the JSON response (forces JSON output)")
+
+	cef := documentCommentEditCmd.Flags()
+	cef.StringVar(&docCommentEditContent, "content", "", "new comment content (omit to leave unchanged)")
+	cef.StringVar(&docCommentEditAttention, "attention", "", "new attention flag: 0 (normal) | 1 (important); omit to leave unchanged")
+	cef.StringVarP(&docCommentEditOutput, "output", "o", "", "output format: table|json (default: table on TTY, json otherwise)")
+	cef.StringVar(&docCommentEditJQ, "jq", "", "apply a gojq filter to the JSON response (forces JSON output)")
+
+	cdf := documentCommentDeleteCmd.Flags()
+	cdf.BoolVarP(&docCommentDeleteYes, "yes", "y", false, "skip the interactive confirmation prompt")
+	cdf.StringVarP(&docCommentDeleteOutput, "output", "o", "", "output format: table|json (default: table on TTY, json otherwise)")
+	cdf.StringVar(&docCommentDeleteJQ, "jq", "", "apply a gojq filter to the JSON response (forces JSON output)")
 }
 
 func runDocumentSearch(cmd *cobra.Command, args []string) error {
@@ -440,6 +525,157 @@ func runDocumentOpen(_ *cobra.Command, args []string) error {
 	return nil
 }
 
+func runDocumentCommentAdd(cmd *cobra.Command, args []string) error {
+	docID, err := parseDocID(args[0])
+	if err != nil {
+		return err
+	}
+	if docCommentAddContent == "" {
+		return fmt.Errorf("--content is required")
+	}
+	client, err := newClientFromFlags(cmd.Context())
+	if err != nil {
+		return err
+	}
+	req := xpoint.AddCommentRequest{Content: docCommentAddContent}
+	if docCommentAddAttention {
+		req.AttentionFlg = 1
+	}
+	res, err := client.AddComment(cmd.Context(), docID, req)
+	if err != nil {
+		return err
+	}
+	return render(res, resolveOutputFormat(docCommentAddOutput), docCommentAddJQ, func() error {
+		w := tabwriter.NewWriter(os.Stdout, 0, 0, 2, ' ', 0)
+		defer w.Flush()
+		fmt.Fprintln(w, "DOCID\tSEQ\tMESSAGE_TYPE\tMESSAGE")
+		fmt.Fprintf(w, "%d\t%d\t%d\t%s\n", res.DocID, res.Seq, res.MessageType, res.Message)
+		return nil
+	})
+}
+
+func runDocumentCommentGet(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
+	}
+	res, err := client.GetComments(cmd.Context(), docID)
+	if err != nil {
+		return err
+	}
+	return render(res, resolveOutputFormat(docCommentGetOutput), docCommentGetJQ, func() error {
+		w := tabwriter.NewWriter(os.Stdout, 0, 0, 2, ' ', 0)
+		defer w.Flush()
+		fmt.Fprintln(w, "SEQ\tATTENTION\tWRITER\tWRITE_DATE\tCONTENT")
+		for _, cm := range res.CommentList {
+			attention := "-"
+			if cm.AttentionFlg {
+				attention = "*"
+			}
+			fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\n", cm.SeqNo, attention, cm.WriterName, cm.WriteDate, cm.Content)
+		}
+		return nil
+	})
+}
+
+func runDocumentCommentEdit(cmd *cobra.Command, args []string) error {
+	docID, err := parseDocID(args[0])
+	if err != nil {
+		return err
+	}
+	seq, err := parseSeq(args[1])
+	if err != nil {
+		return err
+	}
+	if !cmd.Flags().Changed("content") && !cmd.Flags().Changed("attention") {
+		return fmt.Errorf("at least one of --content / --attention is required")
+	}
+	req := xpoint.UpdateCommentRequest{}
+	if cmd.Flags().Changed("content") {
+		v := docCommentEditContent
+		req.Content = &v
+	}
+	if cmd.Flags().Changed("attention") {
+		switch docCommentEditAttention {
+		case "0":
+			v := 0
+			req.AttentionFlg = &v
+		case "1":
+			v := 1
+			req.AttentionFlg = &v
+		default:
+			return fmt.Errorf("--attention must be 0 or 1, got %q", docCommentEditAttention)
+		}
+	}
+	client, err := newClientFromFlags(cmd.Context())
+	if err != nil {
+		return err
+	}
+	res, err := client.UpdateComment(cmd.Context(), docID, seq, req)
+	if err != nil {
+		return err
+	}
+	return render(res, resolveOutputFormat(docCommentEditOutput), docCommentEditJQ, func() error {
+		w := tabwriter.NewWriter(os.Stdout, 0, 0, 2, ' ', 0)
+		defer w.Flush()
+		fmt.Fprintln(w, "DOCID\tSEQ\tMESSAGE_TYPE\tMESSAGE")
+		fmt.Fprintf(w, "%d\t%d\t%d\t%s\n", res.DocID, res.Seq, res.MessageType, res.Message)
+		return nil
+	})
+}
+
+func runDocumentCommentDelete(cmd *cobra.Command, args []string) error {
+	docID, err := parseDocID(args[0])
+	if err != nil {
+		return err
+	}
+	seq, err := parseSeq(args[1])
+	if err != nil {
+		return err
+	}
+	if !docCommentDeleteYes && !confirmDeleteComment(docID, seq) {
+		return fmt.Errorf("aborted")
+	}
+	client, err := newClientFromFlags(cmd.Context())
+	if err != nil {
+		return err
+	}
+	res, err := client.DeleteComment(cmd.Context(), docID, seq)
+	if err != nil {
+		return err
+	}
+	return render(res, resolveOutputFormat(docCommentDeleteOutput), docCommentDeleteJQ, func() error {
+		w := tabwriter.NewWriter(os.Stdout, 0, 0, 2, ' ', 0)
+		defer w.Flush()
+		fmt.Fprintln(w, "DOCID\tSEQ\tMESSAGE_TYPE\tMESSAGE")
+		fmt.Fprintf(w, "%d\t%d\t%d\t%s\n", res.DocID, res.Seq, res.MessageType, res.Message)
+		return nil
+	})
+}
+
+func parseSeq(s string) (int, error) {
+	n, err := strconv.Atoi(strings.TrimSpace(s))
+	if err != nil || n <= 0 {
+		return 0, fmt.Errorf("invalid seq %q: must be a positive integer", s)
+	}
+	return n, nil
+}
+
+func confirmDeleteComment(docID, seq int) bool {
+	fmt.Fprintf(os.Stderr, "Really delete comment seq=%d on document %d? [y/N]: ", seq, docID)
+	var ans string
+	_, _ = fmt.Fscanln(os.Stdin, &ans)
+	switch strings.ToLower(strings.TrimSpace(ans)) {
+	case "y", "yes":
+		return true
+	}
+	return false
+}
+
 // resolveDownloadPath decides the on-disk path for a downloaded PDF.
 //
 // When out is empty, the server-provided filename is used in the current

cmd/schema.go

@@ -26,6 +26,10 @@ Supported aliases map to the CLI's commands:
   document.delete   DELETE /api/v1/documents/{docid}
   document.download GET    /api/v1/documents/{docid}/pdf
   document.status   GET    /api/v1/documents/{docid}/status
+  document.comment.add    POST   /api/v1/documents/{docid}/comments
+  document.comment.get    GET    /api/v1/documents/{docid}/comments
+  document.comment.edit   PATCH  /api/v1/documents/{docid}/comments/{seq}
+  document.comment.delete DELETE /api/v1/documents/{docid}/comments/{seq}
   query.list        GET    /api/v1/query/
   query.exec        GET    /api/v1/query/{query_code}
 

internal/schema/document.comment.add.json

@@ -0,0 +1,52 @@
+{
+  "method": "POST",
+  "path": "/api/v1/documents/{docid}/comments",
+  "summary": "コメント追加",
+  "description": "指定された書類 ID にコメントを追加する。更新権限が必要。\n",
+  "parameters": [
+    {
+      "name": "docid",
+      "in": "path",
+      "type": "integer",
+      "required": true,
+      "description": "書類ID"
+    }
+  ],
+  "requestBody": {
+    "contentType": "application/json",
+    "description": "コメント追加リクエスト。required: content, attentionflg。\n",
+    "properties": {
+      "content": {
+        "type": "string",
+        "required": true,
+        "description": "コメント内容"
+      },
+      "attentionflg": {
+        "type": "integer",
+        "required": true,
+        "description": "重要コメントフラグ (0: 通常 / 1: 重要)"
+      }
+    }
+  },
+  "response": {
+    "type": "object",
+    "properties": {
+      "docid": {
+        "type": "integer",
+        "description": "書類ID"
+      },
+      "seq": {
+        "type": "integer",
+        "description": "コメント番号"
+      },
+      "message_type": {
+        "type": "integer",
+        "description": "メッセージタイプ (3: INFO 固定)"
+      },
+      "message": {
+        "type": "string",
+        "description": "メッセージ内容"
+      }
+    }
+  }
+}

internal/schema/document.comment.delete.json

@@ -0,0 +1,43 @@
+{
+  "method": "DELETE",
+  "path": "/api/v1/documents/{docid}/comments/{seq}",
+  "summary": "コメント削除",
+  "description": "指定された書類 ID に登録されているコメントを削除する。削除権限が必要。\n",
+  "parameters": [
+    {
+      "name": "docid",
+      "in": "path",
+      "type": "integer",
+      "required": true,
+      "description": "書類ID"
+    },
+    {
+      "name": "seq",
+      "in": "path",
+      "type": "integer",
+      "required": true,
+      "description": "コメント番号"
+    }
+  ],
+  "response": {
+    "type": "object",
+    "properties": {
+      "docid": {
+        "type": "integer",
+        "description": "書類ID"
+      },
+      "seq": {
+        "type": "integer",
+        "description": "コメント番号"
+      },
+      "message_type": {
+        "type": "integer",
+        "description": "メッセージタイプ (3: INFO 固定)"
+      },
+      "message": {
+        "type": "string",
+        "description": "メッセージ内容"
+      }
+    }
+  }
+}