IT엔지니어를 위한 일본어 기술 문서 작성법: 仕様書・設計書・障害報告書

1. 概要（がいよう）— 개요
2. 目的（もくてき）— 목적
3. 対象範囲（たいしょうはんい）— 대상 범위
4. 機能仕様（きのうしよう）— 기능 사양
5. 非機能要件（ひきのうようけん）— 비기능 요건
6. 制約事項（せいやくじこう）— 제약 사항
7. 用語定義（ようごていぎ）— 용어 정의

■ API仕様書

1. 概要
本書は、ユーザー管理APIの仕様を定義するものである。

(본 문서는 사용자 관리 API의 사양을 정의하는 것이다.)

2. エンドポイント一覧

| No. | メソッド | パス | 概要 |
|-----|---------|------|------|
| 1 | GET | /api/v1/users | ユーザー一覧取得 |
| 2 | POST | /api/v1/users | ユーザー新規作成 |
| 3 | PUT | /api/v1/users/{id} | ユーザー情報更新 |
| 4 | DELETE | /api/v1/users/{id} | ユーザー削除 |

3. リクエスト仕様

3.1 ユーザー新規作成（POST /api/v1/users）

リクエストボディ:
| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| name | string | ○ | ユーザー名（最大50文字）|
| email | string | ○ | メールアドレス |
| role | string | × | 権限（デフォルト: "user"）|

4. レスポンス仕様

正常時（200 OK）:
| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | integer | ユーザーID |
| name | string | ユーザー名 |
| created_at | datetime | 作成日時（ISO 8601） |

異常時（400 Bad Request）:
| 項目名 | 型 | 説明 |
|--------|-----|------|
| error_code | string | エラーコード |
| message | string | エラーメッセージ |

～を定義する（ていぎする）— ~을 정의하다
～を実装する（じっそうする）— ~을 구현하다
～に準拠する（じゅんきょする）— ~에 준거하다
～を考慮する（こうりょする）— ~을 고려하다
～とする — ~로 한다 (결정사항)
～ものとする — ~하는 것으로 한다 (규정)
～こと — ~할 것 (지시/요구)
～は任意とする — ~는 임의로 한다 (선택사항)

1. システム構成図（しすてむこうせいず）— 시스템 구성도
2. ネットワーク構成（ねっとわーくこうせい）— 네트워크 구성
3. 画面一覧（がめんいちらん）— 화면 목록
4. 画面遷移図（がめんせんいず）— 화면 전이도
5. テーブル定義（テーブルていぎ）— 테이블 정의
6. バッチ処理一覧（バッチしょりいちらん）— 배치 처리 목록
7. 外部インターフェース（がいぶインターフェース）— 외부 인터페이스

■ テーブル名: users（ユーザー）

物理名: users
論理名: ユーザーマスタ
スキーマ: public
備考: ユーザー情報を管理するマスタテーブル

| No. | 物理名 | 論理名 | 型 | 桁数 | NOT NULL | PK | デフォルト | 備考 |
|-----|--------|--------|-----|------|----------|-----|----------|------|
| 1 | id | ユーザーID | BIGINT | - | ○ | ○ | AUTO | シーケンス |
| 2 | name | ユーザー名 | VARCHAR | 50 | ○ | | | |
| 3 | email | メールアドレス | VARCHAR | 255 | ○ | | | ユニーク制約 |
| 4 | status | ステータス | SMALLINT | - | ○ | | 1 | 1:有効 2:無効 |
| 5 | created_at | 作成日時 | TIMESTAMP | - | ○ | | CURRENT | |
| 6 | updated_at | 更新日時 | TIMESTAMP | - | ○ | | CURRENT | |
| 7 | deleted_at | 削除日時 | TIMESTAMP | - | | | NULL | 論理削除用 |

インデックス:
| No. | インデックス名 | カラム | ユニーク | 備考 |
|-----|---------------|--------|---------|------|
| 1 | idx_users_email | email | ○ | ログイン検索用 |
| 2 | idx_users_status | status, created_at | × | ステータス検索用 |

■ 障害報告書

報告日: 2026年3月3日
報告者: 金 英珠（きん えいじゅ）
障害番号: INC-2026-0303-001

1. 障害概要（しょうがいがいよう）
発生日時: 2026年3月2日 14:30 JST
復旧日時: 2026年3月2日 15:45 JST
影響範囲: 決済サービス全体（約5,000ユーザーに影響）
障害レベル: A（重大）

2. 事象（じしょう）
決済処理サービスにおいて、クレジットカード決済のリクエストが
タイムアウトエラー（HTTP 504）を返す事象が発生した。

(결제 처리 서비스에서 신용카드 결제 요청이 타임아웃 에러(HTTP 504)를
반환하는 사상이 발생했다.)

3. 原因（げんいん）
データベースコネクションプールの枯渇が直接原因であった。
前日のバッチ処理で大量のトランザクションが発生し、
コネクションが正常に解放されなかったことが根本原因と判明した。

(데이터베이스 커넥션 풀의 고갈이 직접 원인이었다.
전날 배치 처리에서 대량의 트랜잭션이 발생하여
커넥션이 정상적으로 해제되지 않은 것이 근본 원인으로 판명되었다.)

4. 対応内容（たいおうないよう）
(1) 14:35 監視アラートにより障害を検知
(2) 14:40 担当チームにエスカレーション
(3) 14:50 DBコネクションプールの状態を確認、枯渇を確認
(4) 15:00 コネクションプールの再起動を実施
(5) 15:15 サービス復旧を確認
(6) 15:45 全ユーザーへの影響解消を確認、復旧宣言

5. 再発防止策（さいはつぼうしさく）
(1) コネクションプールの最大数を100から200に変更（短期）
(2) コネクションリーク検知の監視強化（短期）
(3) バッチ処理のトランザクション管理の見直し（中期）
(4) 自動フェイルオーバー機構の導入（長期）

6. 横展開（よこてんかい）
他のマイクロサービスにおいても同様のコネクションプール設定を
確認し、必要に応じて見直しを実施する。

(다른 마이크로서비스에서도 동일한 커넥션 풀 설정을 확인하고
필요에 따라 재검토를 실시한다.)

～が発生した — ~가 발생했다
～と判明した — ~로 판명되었다
～を確認した — ~을 확인했다
～を実施した — ~을 실시했다
～の恐れがある — ~의 우려가 있다
影響範囲は～に限定される — 영향 범위는 ~에 한정된다
根本原因（こんぽんげんいん）— 근본 원인 (root cause)
暫定対応（ざんていたいおう）— 임시 대응 (workaround)
恒久対応（こうきゅうたいおう）— 항구 대응 (permanent fix)
横展開（よこてんかい）— 횡전개 (다른 곳에도 적용)

■ 議事録

会議名: 次期システム基盤 定例会議
日時: 2026年3月3日（火）10:00-11:00
場所: 第3会議室 / Teams
出席者: 田中PM、鈴木リーダー、金（記録）
欠席者: なし

■ 議題と決定事項

1. Kubernetes移行スケジュールについて
  【決定】4月第2週からステージング環境で検証開始
  【TODO】金：検証計画書を3/10までに作成

2. モニタリング基盤の選定
  【議論】Prometheus + Grafana vs Datadog
  - コスト面ではPrometheusが有利
  - 運用負荷はDatadogが低い
  【決定】次回会議までに両方のPoCを実施し比較

3. 次回予定
  日時: 2026年3月10日（火）10:00-11:00
  議題: PoC結果報告、移行計画レビュー

～です・ます調（丁寧語）が基本
「確認しました」「実施します」「報告いたします」

例：
「本件について、以下の通り報告いたします。」
(본 건에 대해 아래와 같이 보고드립니다.)

より丁寧な敬語を使用
「ご確認いただけますでしょうか」
「ご不明な点がございましたら、お申し付けください」
「弊社にて調査を実施いたしました」

例：
「本障害につきまして、多大なるご迷惑をおかけしましたことを
深くお詫び申し上げます。」
(본 장애에 대해 큰 불편을 끼쳐드린 점 깊이 사과드립니다.)

件名: 【報告】○○システム 障害対応完了のご報告

○○部 ○○様

お疲れ様です。
システム開発部の金です。

標記の件について、以下の通りご報告いたします。

■ 対応結果
・対応日時: 2026/3/3 14:00-15:00
・対応内容: DBコネクションプールの設定変更
・結果: 正常に動作していることを確認済み

■ 今後の対応
・詳細な原因分析を今週中に実施予定

ご不明な点がございましたら、お気軽にお問い合わせください。

以上、よろしくお願いいたします。