TASHIKA Docs

Appearance

運用・保守性 ​

本ドキュメントは、TASHIKAプラットフォームの運用・保守性に関する要件を定義します。

NOTE

分類は IPA 非機能要求グレード 大項目 C に準拠しています。 コンプライアンス要件は compliance.md を参照。

OP-001: 保守性 (Maintainability) ​

指標目標値
デプロイ頻度週1回以上（継続的デリバリー）
CI/CDパイプライン所要時間≤ 15分
障害検知時間（MTTD）≤ 5分
障害復旧時間（MTTR）≤ 1時間（Sev1障害）
テストカバレッジBackend ≥ 90%, Frontend ≥ 80%
技術的負債静的解析 Quality Gate 通過必須

年度別ロジックの保守方針 ​

  • 税計算ロジックは年度ごとにバージョン管理し、過去年度のロジックを保持
  • 過去年度の帳票再出力は「生成済みバイナリの再ダウンロード」を基本とし、ロジック再実行は避ける
  • 確定済み帳票のバイナリ保存により、年度別ロジック分離の実装コストを最小化
  • → CR-005 参照

Architecture Decision Records (ADR) ​

重要なアーキテクチャ・技術的判断は、Architecture Decision Record（ADR）として記録・管理する。

項目内容
保管場所設計ドキュメント内の所定ディレクトリに連番（ADR-001, ADR-002, ...）で保管
記録対象技術スタック選定、アーキテクチャパターン採用・却下、重大なトレードオフ判断
ステータス管理Proposed → Accepted → Deprecated / Superseded by ADR-xxx
フォーマットMarkdown。タイトル・ステータス・コンテキスト・判断・結果の構造

OP-002: 相互運用性 (Interoperability) ​

要件説明
API標準REST API（OpenAPI 3.1 準拠）を公開し、外部システムとの連携を容易にする
入力フォーマットXML（電子的控除証明書）、CSV（給与データ一括）、JSON（API）
出力フォーマットXML（e-Tax/eLTAX法定フォーマット）、PDF（源泉徴収票等）、CSV（エクスポート）、JSON（API）
文字コードUTF-8 を基本とする。e-Tax/eLTAX の Shift_JIS 要件には出力時に変換
日付形式ISO 8601（内部表現）。和暦表示は表示層で変換
e-Tax XML国税庁が公開する最新の法定XMLスキーマに準拠（年次更新対応）
eLTAX XML地方税電子化協議会が公開する最新の給与支払報告書XMLスキーマに準拠

API バージョンライフサイクル ​

フェーズ期間対応
Current無期限（次バージョンリリースまで）機能追加・バグ修正の対象
Deprecated最低6か月Deprecation ヘッダーと Sunset ヘッダーをレスポンスに付与。新規連携での利用を非推奨とする
SunsetDeprecated 期間終了後エンドポイントを停止し 410 Gone を返却

非推奨ポリシー:

  • バージョン非推奨の告知は 最低6か月前 に行う
  • Deprecation: true および Sunset: <ISO 8601 date> レスポンスヘッダーで機械的に通知
  • OpenAPI 仕様に deprecated: true を設定し、生成クライアントに警告を伝搬
  • 非推奨期間中は既存機能の互換性を維持し、バグ修正のみ提供

破壊的変更の定義:

以下のいずれかに該当する変更は破壊的変更（Breaking Change）とみなし、メジャーバージョンアップ（/api/v2/）を必要とする:

  • 既存エンドポイントの削除またはURLパス変更
  • 必須リクエストパラメータの追加
  • レスポンスフィールドの削除または型変更
  • エラーコード体系の変更
  • 認証・認可の要件変更（スコープ追加等）

OP-003: データベースマイグレーション (Database Migration) ​

データベーススキーマの変更は、サービス稼働を維持したまま安全に適用できること。

基本原則 ​

原則説明
前進のみ (Forward-Only)ロールバックマイグレーションは作成しない。問題が発生した場合は新しい前進マイグレーションで修正する
ゼロダウンタイムマイグレーションはアプリケーションの無停止デプロイ（Blue/Green）と両立すること
後方互換性新旧バージョンのアプリケーションが同時にDBにアクセスしても正常動作すること

CI 統合 ​

  • マイグレーションは CI パイプラインで自動検証すること
  • 本番適用前に、ステージング環境で本番相当のデータ量を用いたマイグレーションの所要時間を計測すること
  • 長時間ロックを伴う操作（大テーブルへのインデックス追加等）は非ブロッキングに実行すること

RLS 整合性 ​

  • 新規テナントスコープテーブルの追加時は、マイグレーション内で RLS ポリシーも同時に設定すること
  • RLS ポリシーの欠落を CI で自動検出する仕組みを整備すること