odoo

查询 Odoo 数据，包括销售人员绩效、客户分析、订单、发票、CRM、会计、增值税、库存和 AR/AP。生成 WhatsApp 卡片、PDF、Excel。当用户明确提及 Odoo 或要求 Odoo 数据时使用。

## 概述（中文）

查询 Odoo 数据，包括销售人员绩效、客户分析、订单、发票、CRM、会计、增值税、库存和 AR/AP。生成 WhatsApp 卡片、PDF、Excel。当用户明确提及 Odoo 或要求 Odoo 数据时使用。

## 原文

# Odoo Financial Intelligence

**Read-only, Evidence-First, Ledger-Based Reports**

## Quick Reference: Common Odoo Models

| Model | What It Contains | Use For |
|-------|------------------|---------|
| `res.users` | Users/Salespeople | Find salesperson by name, get user_id |
| `sale.order` | Sales Orders | Revenue by salesperson, order counts, status |
| `account.move` | Invoices/Journal Entries | Invoice tracking, payments, P&L data |
| `res.partner` | Contacts/Customers | Customer info, top customers by revenue |
| `product.product` | Products | Product sales, inventory |
| `account.account` | Chart of Accounts | Financial reporting, balance sheet |
| `account.move.line` | Journal Lines | Detailed ledger entries |

## Security & Credentials

### Security Model

This skill implements a **defense-in-depth security model**:

1. **User Invocation Required**: This skill CANNOT be invoked autonomously by AI models
2. **Read-Only Enforcement**: All data modifications are blocked at the code level
3. **Credential Isolation**: Credentials stored only in local `.env` file, never transmitted elsewhere
4. **Network Boundaries**: Only connects to user-specified Odoo URL, no external telemetry

### Required Environment Variables

This skill **REQUIRES** Odoo connection credentials stored in `assets/autonomous-cfo/.env`:

| Variable | Description | Secret | Required |
|----------|-------------|--------|----------|
| `ODOO_URL` | Odoo instance URL (e.g., `https://your-odoo.com`) | No | **Yes** |
| `ODOO_DB` | Odoo database name | No | **Yes** |
| `ODOO_USER` | Odoo username/email | No | **Yes** |
| `ODOO_PASSWORD` | Odoo API key (recommended) or password | **Yes** | **Yes** |

**⚠️ CRITICAL**: These credentials are REQUIRED. The skill will not function without them.

**Setup:**
```bash
cd skills/odoo/assets/autonomous-cfo
cp .env.example .env
# Edit .env with your actual credentials
nano .env
```

### API Key vs Password

**For production, use an Odoo API key:**
1. Log into Odoo → Settings → Account Security → API Keys
2. Generate a new key (e.g., "Financial Reports Skill")
3. Use this key as `ODOO_PASSWORD`

**Why API keys?**
- Scoped permissions (can be read-only)
- Can be revoked independently
- Don't expose your main password
- Better audit trail in Odoo

### Authentication Methods

**XML-RPC (Legacy, default):**
- Password/API key sent in XML-RPC request body
- Supported by all Odoo versions

**JSON-RPC (Odoo 19+):**
- API key sent as `Authorization: Bearer <api_key>` header
- More efficient for large datasets
- Use `ODOO_RPC_BACKEND=json2` to enable

### Model Invocation Policy

**🚫 Model invocation is STRICTLY DISABLED.**

Per `skill.json`:
```json
"modelInvocation": {
  "disabled": true,
  "requiresUserInvocation": true
}
```

This means:
- AI models CANNOT invoke this skill automatically
- User MUST explicitly request Odoo operations
- Every invocation requires user intent

### Read-Only Enforcement

**⚠️ IMPORTANT: Client-Side Enforcement Limitation**

The skill implements **client-side** read-only enforcement. This means:
- Mutating methods are blocked in the Python code
- Blocked methods raise `PermissionError` if called
- However, a modified or compromised client could bypass this

**For Production Security:**
1. **Use a read-only Odoo user** (recommended)
2. Don't give modify permissions to the API key's user
3. Review Odoo access logs regularly

**Blocked Methods:**
- `create`, `write`, `unlink` (CRUD operations)
- `copy` (duplicate records)
- `action_post`, `action_confirm`, `button_validate` (workflow actions)

**Allowed Methods (Read-Only):**
- `search`, `search_read`, `read` (data retrieval)
- `search_count`, `fields_get` (metadata)
- `name_search`, `context_get`, `default_get` (helpers)

Attempting to call blocked methods raises `PermissionError`.

### Data Handling & Privacy

- **No Data Exfiltration:** Reports generated locally in `assets/autonomous-cfo/output/`
- **No Telemetry:** No usage data sent to external servers
- **Network Isolation:** Only connects to `ODOO_URL` specified in `.env`
- **Credential Security:** Password/API key never logged or displayed
- **Local Processing:** All chart generation, PDF creation happens locally

### Output Security

All outputs are local files only:
- `output/pdf_reports/` - PDF reports
- `output/whatsapp_cards/` - PNG image cards  
- `output/charts/` - Chart images
- `output/excel/` - Excel spreadsheets

No cloud upload, no external sharing, no data leaves your machine except to your specified Odoo instance.

### Installation

The skill requires a Python virtual environment with specific packages:

```bash
cd skills/odoo/assets/autonomous-cfo
./install.sh
```

Or manually:
```bash
cd skills/odoo/assets/autonomous-cfo
python3 -m venv venv
./venv/bin/pip install -r requirements.txt
```

**Dependencies:** `requests`, `matplotlib`, `pillow`, `fpdf2`, `openpyxl`

## Critical Rules

1. **NEVER assume** - Always ask clarifying questions before generating reports
2. **Multi-company check** - If multiple companies exist, ASK which one to use
3. **Ledger-based** - Use Chart of Accounts and journal entries (account.move.line), not just invoice summaries
4. **Verify periods** - Confirm date ranges with user before running
5. **No silent defaults** - Every assumption must be confirmed

## Before Any Report, Ask:

1. "Which company should I use?" (if multiple exist)
2. "What period? (from/to dates)"
3. "Which accounts or account types to include?"
4. "Any specific breakdown needed?" (by account, by partner, by journal, etc.)
5. "Output format preference?" (PDF, WhatsApp cards, or both)

## Entrypoint

Uses the venv with fpdf2, matplotlib, pillow for proper PDF/chart generation:

```bash
./skills/odoo/assets/autonomous-cfo/venv/bin/python ./skills/odoo/assets/autonomous-cfo/src/tools/cfo_cli.py <command>
```

Or from the skill directory:
```bash
cd skills/odoo/assets/autonomous-cfo && ./venv/bin/python src/tools/cfo_cli.py <command>
```

## Chart of Accounts Based Reporting

Reports should be built from:
- `account.account` - Chart of Accounts structure (code, name, type, internal_group)
- `account.move.line` - Journal entry lines (debit, credit, account_id, date)
- `account.journal` - Source journals (type: sale, purchase, cash, bank, general)

### Account Internal Groups
- **ASSET** - Assets (current, non-current, cash, receivables)
- **LIABILITY** - Liabilities (payables, taxes, accrued)
- **EQUITY** - Owner's equity
- **INCOME** - Revenue accounts
- **EXPENSE** - Cost and expense accounts
- **OFF_BALANCE** - Off-balance sheet accounts

### Common Account Types
- `asset_cash` - Bank and cash accounts
- `asset_receivable` - Accounts receivable
- `asset_current` - Current assets
- `liability_payable` - Accounts payable
- `income` - Revenue
- `expense` - Expenses

### Special Equity Types (Odoo-Specific)
- `equity` - Standard equity accounts (share capital, retained earnings)
- `equity_unaffected` - **Suspense account** for undistributed profits/losses (e.g., 999999)

**CRITICAL for Balance Sheet:**
Odoo's `equity_unaffected` is a SUSPENSE account. Do NOT use its ledger balance directly.

**Correct Equity Calculation:**
1. **Equity Proper** (type: `equity`) - Use ledger balance (credit - debit)
2. **Retained Earnings** (prior years) - Ledger balance from `equity_unaffected`
3. **Current Year Earnings** - Compute real-time: Income - Expenses

```
Total Equity = Equity Proper + Retained Earnings + Current Year Earnings
```

Where Current Year Earnings = Σ(income credit-debit) - Σ(expense debit-credit)

**Why this matters:** Odoo computes Current Year Earnings in real-time on the Balance Sheet. Using only the `equity_unaffected` ledger balance will cause the balance sheet to NOT balance.

## Automatic Reporting Standard Detection

The skill automatically detects the company's accounting stand