数据模型

提示

本章节只针对开发者和测试人员阅读，普通用户可以跳过此章节。

KanTime 的核心数据模型围绕用户、项目和工时单构建。以下是主要数据实体及其关系的概述。

实体关系图 (ERD)

使用 Mermaid 语法绘制的实体关系图如下所示：

erDiagram
    USER {
        int id PK
        string username
        string email
        string nickname
        string hashed_password
        string status
    }

    PROJECT {
        int id PK
        string name
        string description
        date start_date
        date end_date
        string status
        string budget_value
        string cost_value
        bool timesheet_approval_required
    }

    TIMESHEET {
        int id PK
        int project_id FK
        int user_id FK
        decimal hours
        date work_date
        string status
        datetime submitted_at
        datetime approved_at
        int approver_id FK
    }

    TIMESHEET_AUDIT_LOG {
        int id PK
        int timesheet_id FK
        int changed_by_id FK
        datetime created_at
        string reason_for_change
    }

    ROLE {
        int id PK
        string name
        string scope
    }

    USER_ROLE_ASSIGNMENT {
        int user_id FK
        int role_id FK
        int scope_id "Nullable, for project scope"
    }

    CLIENT {
        int id PK
        string company_name
        string contact_person
        string email
    }

    PROJECT_CLIENT_ASSOCIATIONS {
        int project_id FK
        int client_id FK
    }

    COST_RECORD {
        int id PK
        int project_id FK
        int type_id FK
        string amount
        date incurred_date
    }

    COST_RECORD_TYPE {
        int id PK
        string name
    }

    SALARY_HISTORY {
        int id PK
        int user_id FK
        string monthly_salary
        date effective_date
    }

    USER ||--o{ USER_ROLE_ASSIGNMENT : "has"
    ROLE ||--o{ USER_ROLE_ASSIGNMENT : "is assigned in"
    PROJECT ||--o{ TIMESHEET : "contains"
    USER ||--o{ TIMESHEET : "records"
    PROJECT ||--o{ PROJECT_CLIENT_ASSOCIATIONS : "is associated with"
    CLIENT ||--o{ PROJECT_CLIENT_ASSOCIATIONS : "is associated with"
    USER ||--o{ SALARY_HISTORY : "has"
    PROJECT ||--o{ COST_RECORD : "has"
    COST_RECORD_TYPE ||--o{ COST_RECORD : "is of type"
    TIMESHEET ||--o{ TIMESHEET_AUDIT_LOG : "has"

核心模型说明

User (用户)

• 系统的基本操作单位。
• 通过 USER_ROLE_ASSIGNMENT 表与 ROLE 建立多对多关系。

Role (角色)

• 定义了一组权限。
• scope 字段是关键，它定义了角色的作用范围：
  • global: 全局角色，如 global_admin。
  • project: 项目角色，如 project_manager。

UserRoleAssignment (用户角色分配)

• 这是一个关联表，用于将用户和角色连接起来。
• scope_id 字段用于指定项目角色的作用域。例如，当一个用户被分配了 project_manager 角色时，scope_id 将会是对应项目的 id。对于全局角色，scope_id 为 NULL。

Project (项目)

• 核心业务对象，所有工时和成本都归属于某个项目。
• 通过 project_client_associations 表与 CLIENT 建立多对多关系。
• timesheet_approval_required: 布尔值，用于控制该项目下的工时单是否需要审批。
• budget_value: 项目预算金额。
• cost_value: 项目总成本的计算值。

Timesheet (工时单)

• 记录了某个用户在某个项目上于特定日期花费的工作时长。
• 包含一个 status 字段，用于驱动审批工作流。其值包括：
  • draft: 草稿
  • pending: 待审批
  • approved: 已批准
  • rejected: 已拒绝
  • pending_change: 待变更
  • submitted_at, approved_at, approver_id 是与审批流相关的字段，记录提交和批准的时间及人员。

TimesheetAuditLog (工时单审计日志)

• 记录了每一张工时单状态变更的详细历史，包括操作人、操作时间、变更前后的值以及原因，确保了审批流程的可追溯性。

Client (客户)

• 代表项目的客户，可以与多个项目关联。

SalaryHistory (薪酬历史)

• 记录了用户的历史薪酬和生效日期。此数据用于在计算项目人力成本时，根据工时单的日期动态获取当时的人力单价。
• monthly_salary 字段在数据库中是加密存储的。

CostRecord (成本记录)

• 记录与项目相关的直接成本，例如差旅、物料采购等。
• 关联到 Project 和 CostRecordType。

CostRecordType (成本记录类型)

• 成本记录的分类，例如“差旅费”、“物料费”等。