API 参考

提示

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

本文档概述了 KanTime 后端提供的核心 API 接口。所有接口都以 /api/v1 为前缀。

认证 (Authentication)

• 路径: /auth
• 描述: 处理用户登录和令牌生成。
• 主要接口:
  • POST /login: 用户通过用户名和密码登录，成功后返回 JWT access_token。

用户 (Users)

• 路径: /users
• 描述: 管理系统用户、角色、部门和薪酬。
• 权限: 大部分操作需要 user_manage 权限。
• 主要接口:
  • POST /: 创建新用户。
  • GET /: 获取用户列表（分页）。
  • GET /me: 获取当前登录用户的详细信息。
  • GET /{user_id}: 获取指定用户的详细信息。
  • PUT /{user_id}: 更新用户信息。
  • DELETE /{user_id}: 软删除用户。
  • PUT /{user_id}/roles: 同步（设置）用户的全局角色。
  • POST /{user_id}/roles: 为用户分配单个全局角色。
  • DELETE /{user_id}/roles/{role_id}: 移除用户的单个全局角色。
  • PUT /{user_id}/departments: 同步（设置）用户的部门。
  • POST /{user_id}/departments: 为用户分配部门。
  • DELETE /{user_id}/departments/{department_id}: 从用户移除部门。

项目 (Projects)

• 路径: /projects
• 描述: 管理项目及其成员、客户和工时。
• 权限: 访问权限基于用户的全局角色或项目内角色。
• 主要接口:
  • POST /: 创建新项目。
  • GET /: 获取当前用户可访问的项目列表（分页）。
  • GET /{project_id}: 获取项目详情，包括成员、客户、成本等。
  • PUT /{project_id}: 更新项目信息。
  • DELETE /{project_id}: 归档（软删除）项目。
  • GET /{project_id}/members: 获取项目成员列表。
  • POST /{project_id}/members: 为项目添加成员。
  • POST /{project_id}/members/batch: 批量为项目添加成员。
  • PUT /{project_id}/members/{user_id}: 更新项目成员的角色。
  • DELETE /{project_id}/members/{user_id}: 从项目中移除成员。
  • POST /{project_id}/members/delete-batch: 批量从项目中移除成员。
  • POST /{project_id}/clients: 为项目关联客户。
  • DELETE /{project_id}/clients/{client_id}: 从项目移除客户关联。
  • GET /{project_id}/timesheets: 获取项目下的工时单列表。

工时单 (Timesheets)

• 路径: /timesheets
• 描述: 管理工时记录和审批流程。
• 权限: 权限与用户角色（普通用户、项目经理、管理员）紧密相关。
• 主要接口:
  • POST /: 创建一个新的草稿工时单。
  • POST /batch: 批量创建新的草稿工时单。
  • GET /: 根据权限获取工时单列表（分页，支持筛选）。
  • GET /{timesheet_id}: 获取工时单详情及其审批历史。
  • PUT /{timesheet_id}: 更新草稿状态的工时单。
  • DELETE /{timesheet_id}: 删除草稿状态的工时单。
  • POST /{timesheet_id}/submit: 提交工时单，启动审批流。
  • POST /{timesheet_id}/approve: (项目经理) 批准工时单。
  • POST /{timesheet_id}/reject: (项目经理) 拒绝工时单。
  • POST /{timesheet_id}/withdraw: (提交者) 撤回待审批的工时单。
  • POST /{timesheet_id}/request-change: (提交者) 对已批准的工时单申请变更。
  • POST /{timesheet_id}/approve-change: (项目经理) 批准变更申请。
  • POST /{timesheet_id}/reject-change: (项目经理) 拒绝变更申请。

客户 (Clients)

• 路径: /clients
• 描述: 管理客户信息。
• 权限: 需要 client_manage 或 client_view 权限。
• 主要接口:
  • POST /: 创建新客户。
  • GET /: 获取客户列表（分页）。
  • GET /{client_id}: 获取单个客户信息。
  • PUT /{client_id}: 更新客户信息。
  • DELETE /{client_id}: 删除客户。

部门 (Departments)

• 路径: /departments
• 描述: 管理部门信息。
• 权限: 任何已认证的用户。
• 主要接口:
  • GET /: 获取所有部门的列表。

角色 (Roles)

• 路径: /roles
• 描述: 管理角色信息。
• 权限: 任何已认证的用户。
• 主要接口:
  • GET /: 获取所有角色的列表，可按 scope (如 global, project) 筛选。

成本记录 (Cost Records)

• 路径: /projects/{project_id}/cost-records 或 /cost-records
• 描述: 管理项目的直接成本。
• 权限: 需要 global_admin 角色。
• 主要接口:
  • GET /projects/{project_id}/cost-records: 获取指定项目的所有成本记录。
  • POST /projects/{project_id}/cost-records: 为指定项目创建一条新的成本记录。
  • PUT /cost-records/{record_id}: 更新指定的成本记录。
  • DELETE /cost-records/{record_id}: 删除指定的成本记录。
  • GET /cost-record-types: 获取所有成本记录类型的列表。

薪酬 (Salaries)

• 路径: /users/{user_id}/salaries 或 /salaries
• 描述: 管理用户的薪酬历史。
• 权限: 需要 global_admin 角色。
• 主要接口:
  • GET /users/{user_id}/salaries: 获取指定用户的薪酬历史。
  • POST /users/{user_id}/salaries: 为指定用户添加新的薪酬记录。
  • PUT /salaries/{salary_id}: 更新指定的薪酬记录。
  • DELETE /salaries/{salary_id}: 删除指定的薪酬记录。