Dashboard Feature: A Deep Dive

Streamlining Your Workflow: A Deep Dive into the Dashboard Feature

Hey there, let's dive into the fascinating world of the dashboard feature! This is the central hub you'll land on after logging in, and it's designed to give you a quick overview of everything you need to know about your users' plans. We're talking about a user-friendly interface that puts all the critical information right at your fingertips. It's like having a command center for your daily tasks, ensuring you stay on top of your game. We're going to go through every part to learn how it all works, so buckle up!

Dashboard Overview: Your Daily Command Center

Understanding the Dashboard

Dashboard serves as your primary interface upon login. It's all about providing a comprehensive view of each user's plan status. The aim is to simplify your work, make sure you know what's happening with everyone you're helping, and make things easier for you. The main purpose of the dashboard is to get you quick updates on everyone's plans. This lets you see what you need to do right away, without having to dig around.

Essential Display Elements

The dashboard is split into sections, each of which tells you something different. Let's break down these items.

• Staff Information: You'll see your name, role, and the permissions you have. This section makes sure you know who you are and what you can do.

• User List Table: This table is the star of the show, and it's where you'll find all the important info about your users. Let's go through each part:

  • Full Name: Click on the user's name, and you'll be taken to their individual support plan page. This makes it easy to access detailed info.
  • Plan Progress: See which stage of their plan each user is in, such as assessment or draft. This helps you know what to focus on.
  • Next Update: See when each plan is due for renewal, and how many days are left. This helps you schedule your work.
  • Monitoring Deadline: If monitoring is required, you'll see the deadline and how many days are left. This makes sure you don't miss any important checks.
  • Details: This lets you access more data like individual support plans, assessments, and PDF lists. Plus, you can update or delete user info.

  If there are no users registered, a message will display: "No users registered". This makes sure the page stays clean and easy to use.

Key Functionality

The dashboard is more than just a place to view information; it also allows you to act. Here's what you can do:

• New User Registration: Start the process of registering new users. This will include a review process.
• User Information Changes: Modify user information. This function will also follow a review process.
• User Removal: Delete users, if needed. As with the other actions, this involves a review process.

This setup makes sure you can see the details you need, manage the important stuff, and get things done fast. With these elements, the dashboard is meant to make things easy.

In-Depth Design: Dashboard and Billing Features

Alright, guys, let's get down to the nitty-gritty of the dashboard and billing functions. We'll check out the backend and frontend designs, so you understand how the data moves and how it all comes together.

1. Backend Design: The Data Source

The backend is the engine that provides all the data the frontend needs. We design the APIs to retrieve information efficiently in a single API call.

1.1. API Endpoints

Here's a simple table showing the API endpoint that you'll be working with:

1.2. Response Data Schema (schemas/dashboard.py)

We're super strict when it comes to how data is structured. The frontend uses this contract to display the UI. Here's the basic format:

# app/schemas/dashboard.py
from pydantic import BaseModel
from datetime import date
from typing import List, Optional
from app.models.enums import SupportPlanStep, BillingStatus

class DashboardRecipient(BaseModel):
    """ダッシュボードに表示する利用者一人のサマリー"""
    id: uuid.UUID
    full_name: str
    furigana: str
    current_cycle_number: int
    latest_step: Optional[SupportPlanStep] # 最新の未完了ステップ
    next_renewal_deadline: Optional[date]
    monitoring_due_date: Optional[date]

class DashboardData(BaseModel):
    """ダッシュボード全体のデータ"""
    office_name: str
    current_user_count: int
    max_user_count: int
    billing_status: BillingStatus
    recipients: List[DashboardRecipient]

1.3. Service Layer Logic (services/dashboard_service.py)

When GET /api/v1/dashboard is called, this service builds the DashboardData. This is what happens behind the scenes:

1. The service finds the office the logged-in staff belongs to based on staff information.
2. Gets the office name and billing status (billing_status).
3. Counts the number of users (WelfareRecipient) linked to the office as current_user_count.
4. For each user, it does the following (using selectinload to avoid the N+1 problem): a. Gets the SupportPlanCycle record where is_latest_cycle=True. b. From the SupportPlanStatus associated with that cycle, it finds the first record where completed=False as latest_step. c. Retrieves the cycle's next_renewal_deadline and the related status's monitoring_due_date.
5. Finally, it packages the data into the DashboardData schema and sends it back.

2. Frontend Design: The Data Display & Processor

The frontend takes the data from the backend and formats it for the UI. It handles both displaying and transforming the data.

2.1. Data Retrieval

The frontend uses @tanstack/react-query's useQuery hook (or SWR) to fetch data from the /api/v1/dashboard endpoint.

const { data, isLoading, error } = useQuery({
  queryKey: ['dashboard'],
  queryFn: () => api.get('/dashboard')
});

• While isLoading is true, a spinner will be shown.
• If an error occurs, an error message will be shown.
• If data.recipients is empty, a message saying "No users registered" will be displayed.

2.2. Data Processing and Display Logic

The frontend transforms the raw data into something easy to read and display in the UI.

• Plan Progress: We use an object to map the latest_step enum values (like 'staff_meeting') to text and colors.

const stepDisplayMap = {
  assessment: { text: "アセスメント", color: "bg-blue-100 text-blue-800" },
  draft_plan: { text: "個別原案", color: "bg-purple-100 text-purple-800" },
  staff_meeting: { text: "担当者会議", color: "bg-pink-100 text-pink-800" },
  monitoring: { text: "モニタリング", color: "bg-orange-100 text-orange-800" }
};

• Next Renewal Date & Monitoring Deadline: We use the date-fns library to calculate the days remaining dynamically. This calculation happens within the UI component.

import { differenceInDays, format } from 'date-fns';

const renderDeadline = (deadline) => {
  if (!deadline) return '---';
  const daysLeft = differenceInDays(new Date(deadline), new Date());

  if (daysLeft < 0) return <span className="text-red-500">期限切れ</span>;
  if (daysLeft <= 30) return <span className="text-yellow-500">残り{daysLeft}日</span>;
  return `残り{daysLeft}日`;
};

2.3. User Information (Buttons)

• The "Individual Support Plan", "PDF Viewing", "Assessment Sheet", and "Edit" buttons use Next.js's <Link> component to take users to the appropriate pages.
• The "Delete" button shows a confirmation modal when clicked. If confirmed, it calls DELETE /api/v1/recipients/{recipient_id}.

keikakun_back (Backend Structure)

Here's the structure of the backend:

keikakun_back/
└── app/
    ├── api/
    │   └── v1/
    │       └── endpoints/
    │           ├── dashboard.py         # 【新規】GET /api/v1/dashboard エンドポイントを定義するファイル
    │           ├── recipients.py        # 関連: POST /recipients (課金チェック), DELETE /recipients/{id}
    │           └── stripe.py            # 【新規】POST /stripe/create-checkout-session など決済関連エンドポイント
    ├── crud/
    │   ├── crud_office.py             # 関連: 事業所の利用者数をカウントするために利用
    │   ├── crud_welfare_recipient.py  # 関連: 利用者と関連情報を取得
    │   └── crud_support_plan_cycle.py # 関連: 利用者の最新サイクル情報を取得
    ├── models/
    │   └── office.py                  # 関連: billing_status, stripe_customer_id カラムを持つ
    ├── schemas/
    │   └── dashboard.py               # 【新規】DashboardData, DashboardRecipient のPydanticスキーマを定義
    └── services/
        ├── dashboard_service.py       # 【新規】ダッシュボード情報（利用者サマリー）を構築するビジネスロジック
        └── stripe_service.py          # 【新規】Stripe APIとの連携、Webhook処理などのビジネスロジック

keikakun_front (Frontend Structure)

Here’s the structure of the frontend:

keikakun_front/
└── app/
    ├── dashboard/
    │   ├── components/
    │   │   ├── DashboardHeader.tsx    # 【新規】ヘッダー部分（事業所名、利用者数/上限など）
    │   │   ├── DashboardTable.tsx     # 【新規】利用者一覧テーブルの骨格
    │   │   ├── DashboardTableRow.tsx  # 【新規】テーブルの各行。データ加工ロジックを含む
    │   │   └── CreateRecipientButton.tsx # 【新規】課金ロジックを含む「+」ボタン
    │   ├── hooks/
    │   │   └── useDashboard.ts        # 【新規】useQueryを使って /api/v1/dashboard からデータを取得するカスタムフック
    │   └── page.tsx                   # ダッシュボードページのメインコンポーネント(サーバーコンポーネント)
    ├── office/
    │   └── billing/
    │       ├── components/
    │       │   └── BillingModal.tsx   # 【新規】課金プラン選択モーダル
    │       └── page.tsx               # (任意) 専用の課金ページ
    └── lib/
        ├── api/
        │   └── dashboard.ts           # (任意) ダッシュボードAPIの呼び出しをまとめた関数
        └── utils/
            └── dateUtils.ts           # (任意) date-fnsを使った日付関連の共通ヘルパー関数