---
# System prepended metadata

title: 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.<br>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.<br>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.<br>2. [cite\_start]**[cite: 245] In "Monitoring Task", referencing a "Protected Asset" is optional and immutable after creation.**<br>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.<br>2. If created by an Account Manager, system assigns them automatically.<br>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".<br>2. Supports Create/Edit/Delete tags.<br>3. Tags are not shared across tasks.<br>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".<br>2. [cite\_start]**[cite: 245] Scope setup flow: (a) Select Platforms -\> (b) Input Keywords.**<br>3. Allows 1-to-many Platforms.<br>4. Allows 1-to-many Keywords.<br>5. [cite\_start]**[cite: 245] Must allow input of "Crawl Limit", default is 500.**<br>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).<br>2. Schedule belongs to "Task" and drives all "Active" phases.<br>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.<br>2. [cite\_start]**[cite: 245] Optionally specify "Default Translation Language".**<br>3. [cite\_start]**[cite: 245] Optionally define "Highlighted Terms".**<br>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".<br>2. [cite\_start]**[cite: 245] Strategy includes: Title, Applicable Language, Prompt, Priority, and "Action".**<br>3. [cite\_start]**[cite: 245] Actions: Mark as Relevant, Less Relevant, Excluded, Move To Trash.**<br>4. Supports drag-and-drop for Priority.<br>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.<br>2. Allows adjustment before creation.<br>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.<br>2. [cite\_start]**[cite: 245] Pausing a Task pauses all its "Active" Phases.**<br>3. [cite\_start]**[cite: 245] Phase States: Active, Paused, Completed.**<br>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.<br>2. Support filtering by Status.<br>3. Support sorting by Date/Name.<br>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.<br>2. [cite\_start]**[cite: 245] Editable: Task Name, Owner, Tag Library, Schedule.**<br>3. [cite\_start]**[cite: 245] Phase Snapshot (Scope, Strategies, Language, Currency, Terms) is Read-Only.**<br>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".<br>2. Must record Source Identifier and Detected Language.<br>3. [cite\_start]**[cite: 245] Raw Data (Brand, Item Specifics) is stored.**<br>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".<br>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.<br>2. Read Finding's Language.<br>3. [cite\_start]**[cite: 247] Lookup Phase strategies matching Language (or Any), sort by Priority.**<br>4. Load Task's "Protected Asset" and Finding's Raw Data as context.<br>5. Execute Prompts sequentially.<br>6. [cite\_start]**[cite: 247] On Match: Stop testing, execute Action (Relevant, Less Relevant, Excluded, Move To Trash).**<br>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.<br>2. Users can manually add comments.<br>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.<br>2. [cite\_start]**[cite: 247] Add one or more Tags from the Task's "Tag Library" (Tagging).**<br>3. [cite\_start]**[cite: 247] Remove Tags (Untagging); does not delete the Tag itself.**<br>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.<br>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.<br>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.<br>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).<br>2. [cite\_start]**[cite: 253] "Statistical Report" scope is Single Phase (pure data due to snapshots).**<br>3. [cite\_start]**[cite: 253] "Insights Report" scope is Multi-Phase (Trend/Difference analysis).**<br>4. [cite\_start]**[cite: 253] Generate secure temporary download link and email notification.**<br>5. Record in System Log. |
| **Closing Mechanism** | Client Account | I want to "Archive" a task after completion to freeze evidence. | 1. Task status "Archived".<br>2. Stop "Auto-Retain", set data to Read-Only.<br>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.<br>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.<br>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.