Detective - Product Requirements Document

# Detective - Product Requirements Document ## 1. Project Vision & Goals **Question:** What is the ultimate business goal of this project? * **Project Vision:** To become the ultimate guardian of a brand's "Intellectual Property Twin" (IP Twin). Utilizing cutting-edge technology to proactively monitor and protect brand value and reputation across the complex digital world (Domains, E-commerce, Social Media). * **Core Business Goals:** 1. **Consolidate Siloed Systems (Usability & Integration):** * **Goal:** Migrate features and data from the legacy Detective (especially the "Domain Monitoring" module) to the new Detective platform. * **Value:** Provide a seamless Single Sign-On (SSO) experience for clients and internal teams, ending the chaos of multiple concurrent systems. 2. **Establish a Scalable Unified Architecture (Scalability & Maintainability):** * **Goal:** Solve the issue where the legacy system cannot support further development. Build a new architecture with high functional extensibility. * **Value:** Ensure the design supports all existing business lines and reserves integration space for future modules. 3. **Replace Manual Work with Automation (Efficiency):** * **Goal:** Fully automate the monitoring process that currently relies on manual searching, pasting, classifying, and filtering. * **Value:** Significantly reduce operational costs and improve the efficiency, speed, and accuracy of data processing. 4. **Introduce AI-Assisted Decision Making (Labor Saving):** * **Goal:** Train AI models to assist (not replace) analysts in smart filtering and risk assessment. * **Value:** Resolve subjectivity and ambiguity in manual filtering, further increasing the infringement detection rate. ## 2. User Roles **Question:** Who is this system for, and what do they need to do? * **Account Manager:** IP Twins internal employee (replacing the original "Service Manager" role). Has cross-portfolio permissions. Responsible for setting up tasks, creating phases, manually triggering smart labeling services, executing cross-portfolio operations, reviewing findings, and serving as the designated "Task Owner." * **Client Account:** Brand side employees (Legal, Brand Protection teams). Responsible for reviewing reports and granting permissions to External Partners. * **External Partner:** Third parties (Law Firms, Consultants) authorized to assist in executing monitoring tasks and reviewing findings. * **System Administrator:** Technical administrator of the system, responsible for account and permission allocation. ## 3. Functional Requirements Functional requirements are divided into three stages based on the development and release sequence. ### 3.1 Minimum Viable Product (MVP) **Goal:** Establish a complete MVP containing monitoring setup, AI-assisted detection, core classification logic, and four-level audit logging. #### 3.1.1 Identity & Access Management | Feature | Role | User Story | Acceptance Criteria | | :--- | :--- | :--- | :--- | | **Account & Permission Management** | System Admin | I want to create Client Accounts and External Partner accounts and link them to specific Portfolios to establish an account system for brands. | 1. System must support creation interfaces for Portfolio, Client Account, External Partner, and Account Manager. 2. [cite\_start]**[cite: 243] Client Accounts must be linkable to one or more Portfolios.** | | **Account Manager Cross-Portfolio View** | Account Manager | As an Account Manager, I want cross-portfolio access so I can assist multiple brands with monitoring and takedowns. | 1. System must allow an Account Manager view to switch between or view data from all authorized Portfolios simultaneously. 2. [cite\_start]**[cite: 243] Account Manager operations must explicitly record the operator's identity in the "Finding Log".** | | **External Partner Authorization** | Client Account | I want to grant specific Portfolio access to External Partners so they can perform monitoring and enforcement within the authorized scope. | 1. System must provide an interface allowing Client Accounts to assign or revoke Portfolio access for External Partners. | #### 3.1.2 Monitoring Tasks | Feature | Role | User Story | Acceptance Criteria | | :--- | :--- | :--- | :--- | | **Task & Asset Setup** | Account Manager | I want to create a "Monitoring Task" and optionally reference a "Protected Asset" as background information. | 1. Creating a "Protected Asset" only requires Name, Description, and Cover Image. 2. [cite\_start]**[cite: 245] In "Monitoring Task", referencing a "Protected Asset" is optional and immutable after creation.** 3. [cite\_start]**[cite: 245] "Platform Type" is single-select and immutable after creation.** | | **Task Owner Assignment** | Account Manager, System Admin | As an Account Manager, I want to be automatically assigned as "Task Owner" upon creation; As Admin, I want to manually assign an "Account Manager". | 1. "Monitoring Task" entity must have a required "Account Manager" field. 2. If created by an Account Manager, system assigns them automatically. 3. If created by Admin, the interface forces manual selection of an Account Manager. | | **Task Tag Library Definition** | Account Manager | I want to define a set of task-specific tags (e.g., "Legal Review") to use when reviewing findings. | 1. Monitoring Tasks support a dedicated "Tag Library". 2. Supports Create/Edit/Delete tags. 3. Tags are not shared across tasks. 4. Changes are recorded in "Task Log". | | **Scope & Crawl Limit Setup** | Account Manager | I want to set at least one "Monitoring Scope" for the first "Phase" and set a crawl limit. | 1. Creating a Task creates the first Phase containing at least one "Monitoring Scope". 2. [cite\_start]**[cite: 245] Scope setup flow: (a) Select Platforms -\> (b) Input Keywords.** 3. Allows 1-to-many Platforms. 4. Allows 1-to-many Keywords. 5. [cite\_start]**[cite: 245] Must allow input of "Crawl Limit", default is 500.** 6. [cite\_start]**[cite: 245] Scope belongs to Phase and is immutable (Snapshot) after creation.** | | **Task Scheduling** | Account Manager | I want to (optionally) set a schedule expression to control frequency for all phases. | 1. Allows input of a "Schedule Expression" (Cron). 2. Schedule belongs to "Task" and drives all "Active" phases. 3. [cite\_start]**[cite: 245] This setting is mutable after creation.** | | **Phase Translation & Currency** | Account Manager | I want to set Reference Currency and Default Translation Language for a Phase to ensure consistency. | 1. If Platform Type is *Marketplace*, "Reference Currency" is required. 2. [cite\_start]**[cite: 245] Optionally specify "Default Translation Language".** 3. [cite\_start]**[cite: 245] Optionally define "Highlighted Terms".** 4. All three settings belong to Phase and are immutable (Snapshot). | | **AI Strategy Configuration** | Account Manager | I want to optionally configure "Smart Labeling Strategies" for a Phase to trigger AI classification later. | 1. Interface to Add/Edit "Smart Labeling Strategies". 2. [cite\_start]**[cite: 245] Strategy includes: Title, Applicable Language, Prompt, Priority, and "Action".** 3. [cite\_start]**[cite: 245] Actions: Mark as Relevant, Less Relevant, Excluded, Move To Trash.** 4. Supports drag-and-drop for Priority. 5. [cite\_start]**[cite: 245] Strategies are immutable (Snapshot) after Phase creation.** | | **Import Recent Settings** | Account Manager | I want to copy settings (Scope, Strategy, Currency, Language) from the previous phase when creating a new one. | 1. "Import settings from recent phase" function. 2. Allows adjustment before creation. 3. Upon creation, settings become locked snapshots. | | **Lifecycle Management** | Account Manager | I want to manage the lifecycle states of Tasks and Phases. | 1. Task States: Active, Paused, Completed, Archived, Trash Can. 2. [cite\_start]**[cite: 245] Pausing a Task pauses all its "Active" Phases.** 3. [cite\_start]**[cite: 245] Phase States: Active, Paused, Completed.** 4. Phases can only be manually ended, not manually started (unless new). | | **Phase List Management** | Account Manager | I want to search, filter, sort, and paginate through all phases in a task. | 1. Support keyword search by Phase Name. 2. Support filtering by Status. 3. Support sorting by Date/Name. 4. Support pagination. | | **Restricted Editing** | Account Manager | I want to edit Active/Paused tasks but generally be restricted from modifying core contexts/snapshots. | 1. Task Context (Portfolio, Asset, Platform Type) is Read-Only. 2. [cite\_start]**[cite: 245] Editable: Task Name, Owner, Tag Library, Schedule.** 3. [cite\_start]**[cite: 245] Phase Snapshot (Scope, Strategies, Language, Currency, Terms) is Read-Only.** 4. [cite\_start]**[cite: 245] Editable: Phase Name.** | | **Finding Creation & Update** | System | I want content to be captured, language detected, and created as a Finding immediately; status updated via "Auto-Retain". | 1. Initial status is always "Unmarked". 2. Must record Source Identifier and Detected Language. 3. [cite\_start]**[cite: 245] Raw Data (Brand, Item Specifics) is stored.** 4. [cite\_start]**[cite: 245] Scheduled jobs execute "Retain Action" to update active findings.** | | **Execution Tracking** | Account Manager | I want to see execution logs for every scheduled run in the "Phase". | 1. Triggering schedule adds a record to "Execution Log". 2. Record includes Status (Running, Success, Failed) and messages. | #### 3.1.3 Findings & Classification | Feature | Role | User Story | Acceptance Criteria | | :--- | :--- | :--- | :--- | | **Smart Labeling** | Account Manager | I want to manually trigger Smart Labeling to batch process "Unmarked" findings using my AI rules. | 1. Validate Phase has Strategies configured. 2. Read Finding's Language. 3. [cite\_start]**[cite: 247] Lookup Phase strategies matching Language (or Any), sort by Priority.** 4. Load Task's "Protected Asset" and Finding's Raw Data as context. 5. Execute Prompts sequentially. 6. [cite\_start]**[cite: 247] On Match: Stop testing, execute Action (Relevant, Less Relevant, Excluded, Move To Trash).** 7. [cite\_start]**[cite: 247] Automatically add a System Comment with the AI's reasoning.** | | **Comments (Collaboration)** | Account Manager / System | I want to see AI reasoning and collaborate with team members via comments. | 1. System adds "System Comment" (Level: Info) after Smart Labeling. 2. Users can manually add comments. 3. [cite\_start]**[cite: 247] Support Levels (Info, Warning, Danger) and 2-level nesting.** | | **Manual Tagging** | Account Manager / Partner | I want to manually assign Risk Categories or custom Tags during review. | 1. Manual selection of "Risk Category" from predefined list. 2. [cite\_start]**[cite: 247] Add one or more Tags from the Task's "Tag Library" (Tagging).** 3. [cite\_start]**[cite: 247] Remove Tags (Untagging); does not delete the Tag itself.** 4. [cite\_start]**[cite: 247] All manual changes recorded in "Finding Log".** | | **Manual Retain** | Account Manager | I want to manually submit a URL in a "Phase" to immediately crawl and create a finding. | 1. "Manual Retain" function in Phase UI. 2. Crawl URL, create Finding (Status: Unmarked), add to Task data pool. | ### 3.2 Statistics, Insights, & Closing **Goal:** Enable statistical and insight analysis based on "Phase" time units. #### 3.2.1 Insights Analysis | Feature | Role | User Story | Acceptance Criteria | | :--- | :--- | :--- | :--- | | **Real-time Dashboard** | Account Manager / Client | I want the dashboard to calculate based on current data instantly to see the latest threat posture. | 1. Calculation does not rely on historical snapshots. 2. Aggregate by Source Identifier to show "Top Offenders". | | **Dashboard Customization** | Account Manager / Client | I want to customize and share my dashboard. | 1. Allow layout customization and saving. 2. Share dashboard with other users in the same Portfolio. | #### 3.2.2 Reporting Export | Feature | Role | User Story | Acceptance Criteria | | :--- | :--- | :--- | :--- | | **Export & Share** | Client Account | I want to export "Finding List", "Statistical Report" (Single Phase), or "Insights Report" (Multi-Phase). | 1. Support 3 modes (List, Stats, Insights) and 2 formats (Spreadsheet, Document). 2. [cite\_start]**[cite: 253] "Statistical Report" scope is Single Phase (pure data due to snapshots).** 3. [cite\_start]**[cite: 253] "Insights Report" scope is Multi-Phase (Trend/Difference analysis).** 4. [cite\_start]**[cite: 253] Generate secure temporary download link and email notification.** 5. Record in System Log. | | **Closing Mechanism** | Client Account | I want to "Archive" a task after completion to freeze evidence. | 1. Task status "Archived". 2. Stop "Auto-Retain", set data to Read-Only. 3. Record in "Task Log". | ### 3.3 Audit Trail **Goal:** Implement four-level audit tracking for compliance. #### 3.3.1 Audit Logging | Feature | Role | User Story | Acceptance Criteria | | :--- | :--- | :--- | :--- | | **Four-Level Audit** | System Admin | I want all operations classified into four log levels for efficient auditing. | 1. Implement: System Log, Task Log, Phase Log, Finding Log. 2. [cite\_start]**[cite: 257] Must meet compliance for immutability, long-term storage, query, and export.** | ## 4. Key Non-Functional Requirements (Architecture Goals) **Question:** What quality attributes must the design possess? | ID | Quality Goal | Architecture Decision | Acceptance Criteria | | :--- | :--- | :--- | :--- | | **NFR 1** | **Extensibility** | Modular architecture (or Microservices) decoupled modules. | Adding new modules in Phase 2 requires no changes to the core "Monitoring Task" module. | | **NFR 2** | **Scalability** | Stateless core services supporting horizontal scaling. | System maintains service levels via dynamic scaling when load increases by 50%. | | **NFR 3** | **Cost Efficiency** | Periodic workloads (Crawlers) on Scale-to-Zero environments (FaaS/Cloud Run). | Non-core resources scale down to zero during idle times, reducing costs by \>50%. | | **NFR 4** | **Data Isolation** | Independent Databases/Schemas for core modules (DDD Bounded Contexts). | Database design respects Bounded Context boundaries. | | **NFR 5** | **Internationalization (I18n)** | Multi-level translation mechanism. | 1. Global UI Language. 2. [cite\_start]**[cite: 260] Content Translation (translating strategy/report text).** | | **NFR 6** | **Traceability** | Audit logs use specialized, immutable storage. | Storage guarantees data immutability. | ## Appendix A: Four-Level Audit Definitions | Log Level | Scope | Business Purpose | Key Trace Info | | :--- | :--- | :--- | :--- | | **1. System Log** | Access & Security | Highest level system events. | Login/Logout, Permissions, Role Assignment, User Creation, Export Events. | | **2. Task Log** | Task Lifecycle | Strategy creation and version evolution. | Task Creation, Status Change, Schedule Change, **Tag Library Change**. | | **3. Phase Log** | Phase Operations | Business decisions within execution phases. | Phase Creation, Manual End, Manual Retain. | | **4. Finding Log** | Finding Lifecycle | Complete trail of a single "Finding". | Status Transition, Risk Category Change, **Tagging/Untagging**, Comment Added, Smart Labeling Execution (w/ Operator). | ## Appendix B: Key Design Decisions **B.1 Why move "Monitoring Scope" and "Smart Labeling Strategy" from Task to Phase?** * **Decision:** Adopt "Snapshot Pattern" for maximum **Data Consistency** and **Traceability**. * **Consistency:** Ensures all findings in a Phase (e.g., "Q4 Phase") come from the exact same Scope and Rules. * **Traceability:** Makes "Statistical Reports" absolutely reliable. * **Avoid Confusion:** Solves the issue of "mid-stream changes" if scopes were mutable at the Task level. **B.2 Why "Import Recent Settings" when creating a Phase?** * **Decision:** To balance "Snapshot Consistency" with "Convenience". * **UX Optimization:** Avoids repetitive data entry while maintaining the immutability of the created snapshot. **B.3 Why are Core Task Fields (Asset, Platform Type) Immutable?** * **Decision:** Monitoring Task acts as an **Immutable Context Container**. * **Consistency:** Changing the Asset alters the background info for strategies, leading to inconsistent results. Locking Platform Type ensures the business scope remains valid. **B.4 Why do "Tags" belong to the "Monitoring Task"?** * **Decision:** To increase **Cohesion** and reduce **Coupling**. * **Cohesion:** Tags for Task A are irrelevant to Task B. * **Avoid Pollution:** Prevents a global tag list from becoming unmanageable. **B.5 Distinction: Risk Category vs. Tag** * **Risk Category:** Single, fixed classification (e.g., Suspected Abuse), determines relevance, synced with external systems. * **Tag:** Free text, user-defined, multiple allowed, belongs to the Task's **Tag Library** (e.g., "Legal Review"). **B.6 Why remove "Excluded Terms" and "Boolean Logic" from Monitoring Scope?** * **Decision:** Logic moved to **Smart Labeling Strategies**. * **Integrity:** Scope should be simple (fetch everything potentially relevant). * **Flexibility:** Business logic (exclusions) changes often; Strategies allow adjustment without breaking the locked Scope. * **Implementation:** achieved via "Action: Mark as Excluded" or "Action: Less Relevant". ## Change Log * **Terminology:** "Service Manager" -\> **"Account Manager"**; "Irrelevant" -\> **"Less Relevant"**; "Deleted" -\> **"Trash Can"**. * **Level Adjustment:** Moved "Reference Currency", "Default Translation Language", and "Highlighted Terms" to **Phase Level (Snapshot)**. * **New Field:** Added "Crawl Limit" to Monitoring Scope. * **Action Expansion:** Added **"Move To Trash"** action to Smart Labeling Strategies. * **Logic Change:** Removed "Excluded Terms/Boolean" from Scope; unified under Smart Labeling Strategies. * **Responsibility:** Explicitly defined "Account Manager" as the required Task Owner.