Add territory management schema and update docs

Introduces a new territory management protocol with a Zod schema (`territory.zod.ts`) to support matrix organizations and flexible territory assignments. Updates documentation to explain the distinction between role and territory hierarchies, and modifies the spec index to export the new territory schema.

Author: hotlong

content/docs/concepts/security_architecture.md

@@ -39,24 +39,24 @@ If you are coming from the Microsoft/Dynamics ecosystem:
 *   **Security Role (User Level)** -> `allowRead: true`
 *   **Security Role (BU Level)** -> `allowRead: true` + `Sharing Rule (Share with Role)`
 *   **Security Role (Org Level)** -> `viewAllRecords: true`
-*   **Business Unit** -> `Role` (Functional) / `OrgUnit` (Physical)
+*   **Business Unit** -> `Role` (Functional Hierarchy)
 
-## 4. The Chinese Enterprise Extension (中国企业适配)
+## 4. Advanced: Matrix Management (Territory Management)
 
-In the context of Chinese enterprises, the hierarchy is often strictly defined by **legal entities and departments** (Organization), which is distinct from the **reporting line** (Role).
+For large global enterprises where a single reporting line ("Role") is insufficient, ObjectStack implements the **Territory Management** protocol (`src/system/territory.zod.ts`).
 
-*   **OrgUnit (组织机构)**: `src/system/org_unit.zod.ts`
-    *   **Group (集团)**
-    *   **Company (分公司)**
-    *   **Department (部门)**
-*   **Role (角色)**: `src/system/role.zod.ts`
-    *   Defines titles regardless of department (e.g., "Department Manager", "Accountant").
+This solves the "Matrix Organization" problem without breaking the strict Role hierarchy.
 
-**Example Assignment:**
-*   User: "Zhang San"
-*   OrgUnit: "Shanghai Branch / Sales Dept"
-*   Role: "Sales Manager"
+*   **Role Hierarchy (HR/Reporting)**: "Who reports to whom?" (Stable)
+    *   Example: A Sales Rep reports to a Sales Manager.
+*   **Territory Hierarchy (Market/Revenue)**: "Who owns which market?" (Flexible, Multi-assignment)
+    *   Example: A Sales Rep might be assigned to both "West Coast (Geo)" and "Healthcare (Industry)".
+
+**How it works:**
+1.  **Accounts/Deals** are assigned to **Territories** based on rules (e.g., `State = 'CA'`).
+2.  **Users** are assigned to **Territories**.
+3.  Users gain access to records in their Territories, *regardless* of their Role.
+
+This aligns with best practices from **Salesforce Enterprise Territory Management** and **Oracle Sales Cloud**.
 
-The **Sharing Engine** can then support rules like:
-> "Share records owned by [Shanghai Branch] with [Headquarters Audit Role]."
 

packages/spec/src/index.ts

@@ -34,7 +34,7 @@ export * from './system/api.zod';
 export * from './system/identity.zod';
 export * from './system/policy.zod';
 export * from './system/role.zod';
-export * from './system/org_unit.zod';
+export * from './system/territory.zod';
 export * from './system/license.zod';
 export * from './system/translation.zod';
 export * from './system/constants';

packages/spec/src/system/territory.zod.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+
+/**
+ * Territory Management Protocol
+ * Defines a matrix reporting structure that exists parallel to the Role Hierarchy.
+ * 
+ * USE CASE:
+ * - Enterprise Sales Teams (Geo-based: "EMEA", "APAC")
+ * - Industry Verticals (Industry-based: "Healthcare", "Financial")
+ * - Strategic Accounts (Account-based: "Strategic Accounts")
+ * 
+ * DIFFERENCE FROM ROLE:
+ * - Role: Hierarchy of PEOPLE (Who reports to whom). Stable. HR-driven.
+ * - Territory: Hierarchy of ACCOUNTS/REVENUE (Who owns which market). Flexible. Sales-driven.
+ * - One User can be assigned to MANY Territories (Matrix).
+ * - One User has only ONE Role (Tree).
+ */
+
+export const TerritoryType = z.enum([
+  'geography',      // Region/Country/City
+  'industry',       // Vertical
+  'named_account',  // Key Accounts
+  'product_line'    // Product Specialty
+]);
+
+/**
+ * Territory Model Schema
+ * A container for a version of territory planning.
+ * (e.g. "Fiscal Year 2024 Planning" vs "Fiscal Year 2025 Planning")
+ */
+export const TerritoryModelSchema = z.object({
+  name: z.string().describe('Model Name (e.g. FY24 Planning)'),
+  state: z.enum(['planning', 'active', 'archived']).default('planning'),
+  startDate: z.string().optional(),
+  endDate: z.string().optional(),
+});
+
+/**
+ * Territory Node Schema
+ * A single node in the territory tree.
+ */
+export const TerritorySchema = z.object({
+  /** Identity */
+  name: z.string().regex(/^[a-z_][a-z0-9_]*$/),
+  label: z.string().describe('Territory Label (e.g. "West Coast")'),
+  
+  /** Structure */
+  modelId: z.string().describe('Belongs to which Territory Model'),
+  parent: z.string().optional().describe('Parent Territory'),
+  type: TerritoryType.default('geography'),
+  
+  /** 
+   * Assignment Rules (The "Magic")
+   * How do accounts automatically fall into this territory?
+   * e.g. "BillingCountry = 'US' AND BillingState = 'CA'"
+   */
+  assignmentRule: z.string().optional().describe('Criteria based assignment rule'),
+  
+  /**
+   * User Assignment
+   * Users assigned to work this territory.
+   */
+  assignedUsers: z.array(z.string()).optional(),
+  
+  /** Access Level */
+  accountAccess: z.enum(['read', 'edit']).default('read'),
+  opportunityAccess: z.enum(['read', 'edit']).default('read'),
+  caseAccess: z.enum(['read', 'edit']).default('read'),
+});
+
+export type Territory = z.infer<typeof TerritorySchema>;
+export type TerritoryModel = z.infer<typeof TerritoryModelSchema>;