Team and Role 功能 產品需求文件 - CAFECA-IO/iSunFA GitHub Wiki

產品需求文件 (Teams 與 Roles)

1. 文件概況

1.1 修訂紀錄

日期 修訂人緣 版本 修改內容
2024/12/12 Murky v1.0 初版
2024/12/17 Murky v1.1 開會後修改User Story, 但仍有地方需要後續討論
2024/12/20 Murky v1.2 修改Team Authorization負責的權限範圍,修改共享與移轉ledger

1.2 會議記錄

日期 主持人 主旨 連結
2024/12/17 Murky & Straw 確認UserStory與api劃分 Link
2024/12/18 Straw & Jodie 討論Teams功能細節 Link
2024/12/18 Murky & Shirely 依照上一場會議內容以後端角度確認User Story Link
2024/12/19 Anna, Emily, Julian, Liz, Straw 依照上一場會議內容討論 後端API缺少的內容 Ticket, Meeting Report

2. 功能介紹

2.1 功能簡介

  • 藉由團隊功能讓多名用戶能一起協作會計帳本的記帳
  • 本篇不包含 "媒合(Matching)"和"訂閱(Subscription)"功能

所屬畫面範圍如下

image

2.2 User Story

Warning

  • 本篇不執行媒合與訂閱功能

2.2.1 名詞解釋

  • User: ISunFa的使用者

  • Role: User 點進ISunFa之後選擇的身份,會影響到User可以用ISunFa的哪些功能,有:

    1. Accountant
    2. 試用版
    3. 資方
  • Team: 團隊,一個或複數個User的集合,一個User會參與 一至多個Team,分成以下兩種:

    • 個人Team: 每個User加入ISunFa時會被綁定在一個預設只有該UserTeam(但之後還是可以增加User)
    • 一般Team: 可由User創立,可以增加複數位User
  • Team Authorisation: 一位User 在 一個 Team 中,被授權的等級,影響User 是否可以對Team進行特定功能的操作,以及可以看到Team中的哪些東西,有以下等級:

    • Owner
    • Administrator
    • Editor
    • Viewer
  • ledger: 帳本(Alpha 版中的 Company),ISunFa功能操作時的目標對象,一個個人Team 可以新增管理多個 Ledger, 一般Team 會自動(需要討論)擁有旗下 User 的個人Team裡面的ledger,並管理編輯、閱覽權限

2.2.2 Role

  1. 選擇與切換 Role
    • 身為一個 User
      • 我希望可以依據我的使用需求選擇適合的 Role,並且切換不同的 Role 以使用對應的功能,
      • 所以我需要能夠新增或切換我的 Role,且每個 UserRole 不會重複。
  2. 針對不同 Role 提供專屬功能
    • 身為一個 User
      • 我希望在選擇 Role 後,可以看到該 Role 的專屬功能(例如資方的薪資功能、會計師的記帳功能),
      • 所以我需要 ISunFa 根據我選擇的 Role 顯示對應的專屬功能,同時提供必要的共用功能。

2.2.3 Team 相關

  1. 建立與加入 Team

    • 身為一個User
    • 我希望能與其他 User 合作處理業務和管理 ledger
    • 所以我需要能夠建立 Team 邀請他人加入,或被邀請加入其他人建立的 Team,此外Team需要有獨立的UUID(不是database的id,要再多一個String的 index)
      • 此外我需要可以檢視所有我參加的Team,並可以看到我在該Team中的Team Authorization以及Team訂閱Plan
  2. 邀請未註冊的 User

    • 身為一個User
    • 我希望在未註冊 ISunFa 帳戶的情況下也能被邀請加入 Team
    • 所以我需要邀請者能通過 Email 發送邀請連結給我,若我已有帳戶,則在邀請輸入欄位顯示我的頭像與名稱。
    • 邀請加入team的Email,不論是不是在ISunFa有帳號,都應該要使用 loginUrl?token=haskTeamToken的方法實做,藉由google oath2 傳遞token, 在登入時session(或別的地方)同時存在token與User, 就可以直接把team加入該User。
    • 如果已經在IsunFa內的帳號,邀請時只有打開Email通知的用戶才會收到邀請email
    • 如果已經在IsunFa內的帳號,不論是否打開Email通知,都應該要收到小鈴鐺通知,並且可以從小鈴鐺通知裡加入team
  3. Ledger公開與非公開

    • 身為一個 TeamUser
    • 我希望可以與Team的其他User共同協助記帳,並在必要時可以將自己的ledger移交到其他Team
    • 所以我需要ledger的共編與轉移的功能(請看 813項)
  4. Owner 的權限

    • 身為 Team中為 OwnerUser
    • 我希望可以全面管理 Team
    • 所以我需要以下權限:
      • 一個team只有一個owner
      • 邀請和刪除User
      • 可以調整User成為 AdministratorEditorViewer
      • 刪除Team
      • 檢視team Meta Data(Team Icon, Team name, ,Team Website link, Team Description, Total Count of User, Total Count of ledger)
      • 修改team Meta Data(Team Icon, Team name, ,Team Website link, Team Description)
      • 可以看到Team裡面有哪些User以及這些User的權限
      • 新增與編輯 ledger (編輯指的是使用ISunFa的記帳功能)
      • 編輯ledger Meta data
      • 設定收款管道
      • 調整Team的訂閱方案 (Team Plan)
      • Owner目前不能轉移Owner權限
      • 以及其他 AdministratorEditorViewer的功能
  5. Administrator 的權限

    • 身為 Team中為 Administrator,我是事務所/公司的成員
    • 我希望可以負責管理OwnerAdministrator以外的成員 (EditorViewer)
    • 所以我需要以下權限:
      • 能新增User,User可以成為 EditorViewer
      • 檢視team Meta Data(Team Icon, Team name, ,Team Website link, Team Description, Total Count of User, Total Count of ledger)
      • 修改team Meta Data(Team Icon, Team name, ,Team Website link, Team Description)
      • 可以看到Team裡面有哪些User以及這些User的權限
      • 新增與編輯 ledger (編輯指的是使用ISunFa的記帳功能)
      • 編輯ledger Meta data
      • 可以編輯ledgermetadata
      • 可以用Teams接案
      • 以及其他EditorViewer的功能
  6. Editor 的權限

    • 身為 Team中為 Editor,我是事務所/公司的成員
    • 我希望可以主要負責管理ledger
    • 所以我需要以下的權限:
      • 可以新增與編輯ledger (編輯指的是使用ISunFa的記帳功能)
      • 編輯ledger Meta data
      • 可以看到Team裡面有哪些User以及這些User的權限
      • 以及其他Viewer的功能
  7. Viewer 的權限

    • 身為 Team中為 ViewerUser ,我是屬於事務所/公司之外的成員
    • 我希望能檢視ISunFa 的帳本,並幫忙記帳(ex: 工讀生),
    • 所以我需要以下權限
      • 檢視team Meta Data(Team Icon, Team name, ,Team Website link, Team Description, Total Count of User, Total Count of ledger)
      • 可以看到Team裡面有哪些User以及這些User的權限
      • 編輯ledger (編輯指的是使用ISunFa的記帳功能)
      • 可以查看 ledger
  8. ledger 共同編輯

    • 身為 TeamUser
    • 我希望可以跟其他User一起進行記帳活動,但又希望可以區分給全部User或僅有部分User可以操作
    • 所以我需要可以設定 ledgerTeam 中的共享狀態,分為公開與非公開,並由 OwnerAdmin或創立ledgerUser可以更改共享狀態
      • 公開:Team裡面的User接可以連接到公開ledger,並可以查看與編輯ledger
      • 非公開:只有 1. Owner 2. Admin 3. 創立ledgerUser可以查看與編輯ledger
  9. 重大操作的通知

    • 身為一個 User
    • 我希望在 Team 中有重大操作時能即時收到通知,
    • 所以我需要在以下情況下收到通知:
      • 有人邀請我加入某個 Team
      • 有人為我開啟或關閉某個 ledger 的權限。(需要討論)
      • 有人調整我在 一般Team 的權限等級。(需要討論)
      • 當我是 Team Owner 時,有人的ledger加入我的 Team
  10. Teams數量的限制

    • 身為ISunFa的營運商
    • 我希望可以限制User可以擁有的Team的數量
    • 所以我需要 以 UserRole去計算,每個Role 最多只能有三個Team,其中一個是個人Team,另外兩個是`一般Team
  11. Ledger數量限制

    • 身為ISunFa的營運商
    • 我希望可以限制用戶可以建立的Ledger數量
    • 所以我需要以 Team去計算,免費版Team只可以建立一個ledger,付費版不限制Ledger
  12. AI使用次數上限

    • 身為ISunFa的營運商
    • 我希望可以限制免費版用戶可以使用的AI分析次數
    • 所以我需要可以紀錄免費版的team使用多少次的AI分析紀錄
  13. ledger可以進行team之間的轉移

    • 身為TeamOwnerAdministrator
    • 我希望可以將ledger移轉到不同team之下,方便我移轉工作給不同的事務所/公司或是個人
    • 所以我希望可以填寫我想藉由填寫轉移的TeamTeam ID 進行ledger轉移。另外我希望是由對方teamOwnerAdministrator按下確認才進行轉移。
  14. Team只要填寫名稱就可以建立

    • 身為TeamOwner
    • 我希望建立Team流程可以更加的簡潔
    • 建立Team一開始只需填寫其Team name 即可完成建立。其他資訊皆為後續點擊Team詳細資訊進行選填:團隊簡介(選填)、團隊相關連結(選填)、團隊銀行帳戶(媒合使用選填)。

2.2.4 媒合 (Matching)

於下次執行,這邊先紀錄,仍需要討論

  1. Role 與 發布工作的權限
    • 身為一個 Role資方 或 accountantUser
      • 我希望可以透過ISunFa發布工作,但又希望只有一定權限的User才可以作到
      • 所以我需要透過 一般TeamOwnerAdministrator Userteam來發布工作
  2. Role 與工作媒合的限制
    • 身為一個 Role資方User
      • 我希望只有經過 KYC 認證的其他 User 才能承接我發布的工作,
      • 所以我需要 KYC 認證作為工作媒合的必要條件。
  3. 根據 KYC 區分專業等級
    • 身為一個 Role資方User
    • 我希望能根據 User 的 KYC 認證結果區分其專業等級,並在發布工作時選擇適合的等級來承接任務,
    • 所以我需要在 KYC 認證後將 User 依照Role分為不同的Level(如 Normal、CPA),且承接工作時只能看到符合自己等級的任務。
  4. 完成任務後的支付流程
    • 身為一個 Role資方User
    • 我希望在確認工作完成後再支付款項給承接工作的 Team
    • 所以我需要一個工作確認畫面來核對工作進度並從 Team 的錢包支付。
  5. KYC 必要性
    • 身為一個 Role工讀生AccountantUser
    • 我希望在接案前完成個人 KYC 認證,
    • 所以我需要在媒合之前通過審核,才有資格承接工作。

2.2.4 Subscription

於下次撰寫與執行

3. 產品架構

3.1 Pseudo Functions

表格按方向鍵左、右可以滑動表格

1. Role 與 KYC

功能名稱 功能描述 涉及角色 API 使用者故事編號
createUserRole(userId, roleId) (已經有) 新增使用者的 Role,並更新對應的功能可用性。 User, Role POST /user/:userId/role 2.2.2-1
selectRole(已經有) 切換使用者的 Role,以便使用不同功能。 User, Role PUT user/:userId/selected_role 2.2.2-1
前端使用selectedRoleRef (在userContext裡面)拿阻擋特定頁面的功能? 切換使用者的 Role,以便使用不同功能。 User, Role userContext 2.2.2-1
getRoleAllowAPI(roleId) 根據 Role 提供允許Access 的 前端 page url, 可以寫成constant 或從後端拿取 User, Role constants/role或是 GET /role/:roleId/allow 2.2.2-2
createKYC(userId, kyc data) 使用bookeeperaccount的role時,接案要使用 User, KYCBookeeper, KYCAccount 目前分成 KYCBookeeperKYCAccount 兩種,可以分成兩個不同api /user/:userId/bookkeeper/user/:userId/account 2.2.4-5
validateKYC(userId) 對某個使用者更改他完成 KYC的狀態,作為承接工作或分配專業等級的依據。 User, KYCBookeeper, KYCAccount PUT /user/:userId/bookkeeper/approved, PUT /user/:userId/account/approved 2.2.4-2, 2.2.4-3

Role的頁面保護可能可以這樣寫

import { GetServerSideProps } from "next";

export const getServerSideProps: GetServerSideProps = async (context) => {
  const { req } = context;

  // 從後端或 Cookies 獲取用戶角色
  const userRole = req.cookies.role || "guest";

  if (userRole !== "admin") {
    return {
      redirect: {
        destination: "/not-authorized",
        permanent: false,
      },
    };
  }

  return {
    props: {}, // 頁面正常渲染
  };
};

const AdminPage = () => {
  return <div>只有管理員可以看見此頁面</div>;
};

export default AdminPage;

2. Team 相關

功能名稱 功能描述 涉及角色 API(第一個userId指的是發出命令的User,第二個UserId指被影響的對象) 使用者故事編號
createDefaultTeamWhenUserCreated(不是api) User創立帳號時需要預設綁定到一個Team User, Teams 不是api 2.2.3-8
createTeam(userId, teamDetails) 允許使用者建立新的 Team 並成為 Owner User, Teams, Role(Owner) Post /user/:userId/team/ 2.2.3-1
searchUserByEmail(email) 邀請其他人加入Team的時候,需要先找找看User是否存在,存在的話要顯示User Icon User Get /user/:userId/email/:email 2.2.3-2
inviteToTeam(teamId, email) 邀請其他人加入 Team,Email發送邀請連結(CreateInvitation)。 Role(Owner, Admin), User, Invitation Post /user/:userId/team/:teamId/invitation 2.2.3-2
inviteToTeamCallback(userId, invitationId) 不確定要怎麼實做,

- 希望用戶點入邀請碼連結之後可以導引到的callback,可以加入teams,還沒有帳號的話直接先創帳號??
- 已經有帳號的會被直接加到Team嗎?還是說一定要點Email的連結
User, Role(viewer), Team, Invitation Get /user/:userId/team/:teamId/invitation/:invitationId 2.2.3-2
setTeamAuthorisation(userIdChangeOther, teamId, userIdBeChanged, level) 設定 Team 成員的權限等級(Owner、Administrator、Viewer),須檢查只有team owner可以 Role(Owner), User, Team Put /user/:userId/team/:teamId/auth/:authId(可以看是要用database 的teamAuthId直接改,還是把user-team relation 放在body) 2.2.3-3, 2.2.3-4
editTeamMeta(teamId, metaDetails) 編輯 Team 的基本資訊(名稱、網站、描述)。 User, Role(Owner), Teams Put /user/:userId/team/:teamId/metadata 2.2.3-4
editTeamCashFlowSetting(teamId, cashFlowDetails) 編輯Team有關 金流方面的設定 User, Role(Owner), Teams Put /user/:userId/team/:teamId/cashflow(金流可能可以單獨拆出一個table?) 2.2.3-4
removeTeamMember(teamId, userId) Team 中移除成員。(他的帳本也一起被剔除嗎?) User, Role(Owner), Teams Delete /user/:userId/team/:teamId/user/:userId (api可能要改動) 2.2.3-4
viewTeamMembers(teamId) 查看 Team 中的成員列表及其權限。 User, Teams Get /user/:userId/team/:teamId/member 2.2.3-6
autoShareLedger(userId, teamId) (不是api,這個只是用戶被invite到一個team時的動作) 當使用者加入 一般Team 時,自動將其個人 ledger 分享至該 Team 並通知 Owner。預設Owner與上傳的人有權限看 User, Teams, ledger 2.2.3-7
adjustLedgerPermissions(teamId, ledgerId, permissions) 調整 ledger 的可讀或可寫權限。這邊設計成一個ledger可以是 全部權限都可以看/owner, admin可以, Owner可以看,另外也可以設定 特定User可以看,特定User可以看是和前三項是 OR的關係 User, Team, teamAuth, ledger Put /user/:userId/team/:teamId/user/:userId/company/:companyId 2.2.3-7
notifyUserOnAction(actionDetails)(不是api) 當有重大操作(如權限調整、成員加入、ledger 加入等)時通知相關使用者。 System Pusher 通知 2.2.3-9

3. Matching

  • 不包含於本次產品需求文件中

4. Subscription

  • 不包含於本次產品需求文件中

3.2 Component

這邊可以放前端 Component的的規劃

4. Interface與 Database 設計

4.1 Database修改

尚未完工

4.2 API應該回傳的Interface

尚未完工

5. 驗收標準

尚未完工

⚠️ **GitHub.com Fallback** ⚠️