docs: update IA and functional map to v3 (roles, UX review)#18
Merged
singyichen merged 5 commits intomainfrom Apr 2, 2026
Merged
docs: update IA and functional map to v3 (roles, UX review)#18singyichen merged 5 commits intomainfrom
singyichen merged 5 commits intomainfrom
Conversation
Update functional map and information architecture to reflect the professor-confirmed four roles: Super Admin, Data Creator / Project Leader, Annotator, and Reviewer. Add Journey D for Super Admin, expand Journey A to full project lifecycle from Project Leader view, and adjust role-settings descriptions accordingly. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…insights - Add Super Admin role, rename admin → project_leader - Add task-type-specific dashboard cards and empty states for all pages - Add Config Builder with Visual/Code dual mode and template entry point - Add annotation workspace History tab and labeling instruction modal - Add relation extraction task type and task-type-aware dataset analysis - Add .serena/ to .gitignore Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add role-specific dashboard views (Project Leader / Annotator / Reviewer / Super Admin) - Expand task-new to 3-step flow with Config Builder (Visual/Code modes, template library) - Add relation extraction task type (Entity + Relation + Triple) - Add task-detail details: assign annotators, Dry/Official Run publish, data isolation, export - Add annotation-workspace: forced instruction modal, History tab - Add reviewer direct edit capability - Expand dataset-stats with task-type-specific metrics - Expand dataset-quality with IAA methods per task type (Cohen/Fleiss Kappa, Krippendorff's Alpha, Entity-level F1, Triple-level agreement) - Add work-log note: settlement record only, payroll handled externally - Update role-settings node names to match IA identifiers Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…state - Remove 生成式標記 task type from all locations (IA + functional map) - Split 單句任務 into Classification and Scoring/Regression (5 task_types total) - Add Reviewer Navbar definition (儀表板 | 標記審查 | 資料集分析) - Clarify Reviewer entry points for annotation-workspace and task-detail (read-only) - Add task status transition chain to task-detail (草稿→Dry Run進行中→等待IAA確認→Official Run進行中→已完成) - Add Dry Run completion notification mechanism (auto status switch + Dashboard badge) - Fix annotation-workspace entry: separate Annotator / Reviewer paths - Fix task-detail export: remove self-loop, clarify as in-page Toast action - Update flowchart: add Reviewer→task-detail read-only edge, Dry Run→Dashboard badge edge - Update Journey A: show state transition and badge notification step - Bump functional map to v3 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Review Summary by QodoUpdate IA v3 and functional map with confirmed roles, Config Builder, and task-type-aware analysis
WalkthroughsDescription• Updated IA and functional map to v3 with confirmed four-role model (project_leader, annotator, reviewer, super_admin) • Expanded dashboard with role-specific views and empty states for all pages • Redesigned task creation with 3-step Config Builder flow supporting Visual/Code modes • Added task-type-aware dataset analysis with 5 distinct task types and IAA methods • Implemented Dry Run state machine with notification mechanism and Reviewer direct-edit capability • Removed payroll page and 生成式標記 scope; added .serena/ to .gitignore Diagramflowchart LR
IA["IA v2"] -->|"4 confirmed roles<br/>role-specific dashboard<br/>empty states"| IAv3["IA v3"]
FM["Functional Map v1"] -->|"full sync with IA v3<br/>5 task types<br/>Dry Run state machine"| FMv3["Functional Map v3"]
TaskFlow["Task Creation"] -->|"3-step flow<br/>Config Builder<br/>Visual/Code modes"| TaskNew["Enhanced task-new"]
Analysis["Dataset Analysis"] -->|"task-type-specific metrics<br/>IAA methods<br/>anomaly detection"| AnalysisV3["Enhanced dataset-stats/quality"]
Reviewer["Reviewer Features"] -->|"direct edit capability<br/>Navbar navigation<br/>Dry Run standard answer"| ReviewerV3["Enhanced annotation-workspace"]
File Changes1. docs/functional-map/functional-map.md
|
Code Review by Qodo
1.
|
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
- §1 Annotator: add 標記員管理模組（僅自己的工時）to accessible modules - §1 Project Leader: remove 標記任務（唯讀）— contradicted by §2 access matrix (❌) - §3 nav diagram: add DASH→WLOG edge for Annotator personal path - specs/001-sso-login: replace GitHub OAuth with Email/Password throughout - Process flow: add email/password branch in sequence diagram - Step table: split step 2 into 2a (Google) / 2b (Email/Password) - User Story 1: update acceptance criteria for both login methods - User Story 2: remove GitHub scenario, add admin-created email account - Edge cases: replace GitHub no-email case with forgot-password policy - FR-001/FR-002: remove GitHub, add bcrypt password validation - Entity model: provider=(google|email), add hashed_password field, update role enum - SC-009: replace GitHub provider merge with email/password provider merge Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
| | 審核員 | `reviewer` | 審查標記結果、協助產出標準答案、查看品質報告 | 儀表板、標記任務模組（審查模式）、資料集分析模組 | | ||
| | 系統超級管理員 | `super_admin` | 平台維護、跨專案使用者管理、帳號與角色設定 | 全部模組 + 系統管理模組 | | ||
|
|
||
| > **注意：** Reviewer 可以是同一位 Project Leader 擔任（雙重角色）。系統以 **role** 判斷權限，而非 user，同一使用者可同時持有多個角色。 |
There was a problem hiding this comment.
🔴 IA claims multi-role support but spec defines role as a single-value enum field
The IA document at docs/ia/information-architecture.md:19 states: "同一使用者可同時持有多個角色" (a user can simultaneously hold multiple roles). However, the User entity definition at specs/001-sso-login/spec.md:185 defines role as a single-value enum: role（annotator | project_leader | reviewer | super_admin）. The JWT payload at specs/001-sso-login/spec.md:187 also contains a singular role field. A single role field cannot represent multiple simultaneous roles. This is a cross-document data model contradiction — developers implementing RBAC will either build single-role (matching the spec) and break the IA's dual-role use case (e.g., a user who is both project_leader and reviewer), or build multi-role (matching the IA) and diverge from the spec's entity definition and JWT structure.
Prompt for agents
The IA document (docs/ia/information-architecture.md:19) claims users can hold multiple roles simultaneously, but the User entity in specs/001-sso-login/spec.md:185 defines role as a single-value enum field (annotator | project_leader | reviewer | super_admin), and the JWT at line 187 also carries a singular role field.
To resolve this, choose one approach:
1. If multi-role is intended: Update the User entity in spec.md to use a roles array or a separate user_roles join table instead of a single role field. Also update the JWT payload to contain a roles array instead of a single role. This requires changes in spec.md sections: Key Entities (line 185) and Session/JWT (line 187).
2. If single-role is intended: Update the IA note at line 19 to clarify that a user holds exactly one role at a time, and that dual responsibilities (e.g., Project Leader who also reviews) are handled by switching context or by having the project_leader role implicitly include review capabilities.
Both documents are authoritative references for development, so they must agree on the data model.
Was this helpful? React with 👍 or 👎 to provide feedback.
Comment on lines
+185
to
+186
| - **User（使用者）**：代表已驗證身份。關鍵屬性：`id`、`email`、`name`、`avatar_url`、`provider`（google | email）、`provider_id`（Google 帳號 ID，Email/Password 帳號為 null）、`hashed_password`（Email/Password 帳號用，Google 帳號為 null）、`role`（annotator | project_leader | reviewer | super_admin）、`created_at`。 | ||
| - 首次 Google 登入預設 `role = annotator`。Email / Password 帳號建立時由管理員指定角色。 |
There was a problem hiding this comment.
🟡 Incomplete role terminology migration: FR-011 and SC-008 still reference non-existent "admin" role
This PR systematically renamed the admin role to super_admin and project_leader throughout the IA and spec documents. The User entity at specs/001-sso-login/spec.md:185 now defines roles as annotator | project_leader | reviewer | super_admin. However, FR-011 (specs/001-sso-login/spec.md:152) still says "預設 admin 帳號" and SC-008 (specs/001-sso-login/spec.md:198) still says "預設 admin 帳號". Since admin is no longer a valid role in the new four-role system, these two references are stale and will cause confusion during implementation of the database seed migration — developers may create an account with a role that doesn't exist in the enum.
Prompt for agents
The PR updated the role enum in the User entity (specs/001-sso-login/spec.md:185) from admin/researcher/annotator to project_leader/annotator/reviewer/super_admin, but two references to the old admin role were missed:
1. FR-011 at line 152: Change "預設 admin 帳號" to "預設 super_admin 帳號" (this is the seed account for first deployment)
2. SC-008 at line 198: Change "預設 admin 帳號" to "預設 super_admin 帳號" (the success criterion for the seed account)
Both should reference super_admin to match the new role system defined at line 185.
Was this helpful? React with 👍 or 👎 to provide feedback.
|
|
||
| **Project Leader 視角：** | ||
| - **任務總覽卡：** 所有任務列表，每筆顯示任務名稱、任務類型、當前狀態（草稿 / Dry Run 進行中 / 等待 IAA 確認 / Official Run 進行中 / 已完成）、整體完成率進度條 | ||
| - **待處理事項區：** IAA 結果待確認（附快速連結至 `dataset-quality`）、Dry Run 已全員完成待啟動 Official Run |
There was a problem hiding this comment.
🟡 Navigation diagram missing Dashboard → dataset-quality direct link described in section 4
The Dashboard description at docs/ia/information-architecture.md:135 specifies that the Project Leader's "待處理事項區" has a "快速連結至 dataset-quality", and line 201 further confirms: "Project Leader 從 badge 連結進入 dataset-quality 查看 IAA 結果". However, the navigation diagram in section 3 (lines 82–107) only shows DASH → STATS → QUALITY (via dataset-stats), with no direct DASH → QUALITY edge. Since the navigation diagram is the authoritative implementation reference (per § 6: "有沒有跨模組的資料依賴？→ § 3 頁面導覽結構圖"), this missing edge means the direct Dashboard-to-quality-page navigation path may not be implemented.
Prompt for agents
The Dashboard section at docs/ia/information-architecture.md:135 describes a direct quick-link from Dashboard to dataset-quality for IAA confirmation, and line 201 confirms this navigation path. However, the navigation diagram in section 3 (around lines 87-91) does not include a DASH → QUALITY edge.
Add a new edge in the navigation diagram after line 87 (DASH --> STATS):
DASH -->|IAA 待確認| QUALITY
This ensures the diagram matches the textual description and implementers will create the correct navigation route.
Was this helpful? React with 👍 or 👎 to provide feedback.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
task_types), removed 生成式標記 scopeChanges
docs/ia/information-architecture.mddocs/functional-map/functional-map.md.gitignore.serena/(Serena MCP local config)Test plan
🤖 Generated with Claude Code