介绍
# Odoo Financial Intelligence
**只读、证据优先、基于分类帐的报表**
## 快速参考：常用 Odoo 模型
| 模型 | 包含内容 | 用途 | |-------|------------------|---------| | `res.users` | 用户/销售员 | 按名称查找销售员，获取 user_id | | `sale.order` | 销售订单 | 按销售员统计收入、订单计数、状态 | | `account.move` | 发票/凭证 | 发票跟踪、付款、损益数据 | | `res.partner` | 联系人/客户 | 客户信息、按收入统计的前几名客户 | | `product.product` | 产品 | 产品销售、库存 | | `account.account` | 会计科目表 | 财务报表、资产负债表 | | `account.move.line` | 凭证行 | 详细的分类帐条目 |
## 安全与凭证
### 安全模型
此技能实现**纵深防御安全模型**：
1. **需要用户调用**：此技能不能由 AI 模型自主调用 2. **强制只读**：所有数据修改均在代码层面被阻止 3. **凭证隔离**：凭证仅存储在本地 `.env` 文件中，绝不传输到其他地方 4. **网络边界**：仅连接到用户指定的 Odoo URL，无外部遥测
### 必需的环境变量
此技能**需要**存储在 `assets/autonomous-cfo/.env` 中的 Odoo 连接凭证：
| 变量 | 描述 | 密码 | 必需 | |----------|-------------|--------|----------| | `ODOO_URL` | Odoo 实例 URL (例如 `https://your-odoo.com`) | 否 | **是** | | `ODOO_DB` | Odoo 数据库名称 | 否 | **是** | | `ODOO_USER` | Odoo 用户名/邮箱 | 否 | **是** | | `ODOO_PASSWORD` | Odoo API 密钥（推荐）或密码 | **是** | **是** |
**⚠️ 关键**：这些凭证是**必需**的。没有它们，该技能将无法运行。
**设置：** ```bash cd skills/odoo/assets/autonomous-cfo cp .env.example .env # Edit .env with your actual credentials nano .env ```
### API 密钥与密码
**对于生产环境，请使用 Odoo API 密钥：** 1. 登录 Odoo → 设置 → 账户安全 → API 密钥 2. 生成一个新密钥（例如，“Financial Reports Skill”） 3. 将此密钥用作 `ODOO_PASSWORD`
**为什么使用 API 密钥？** - 权限范围（可以是只读的） - 可以独立撤销 - 不会暴露您的主密码 - 在 Odoo 中有更好的审计跟踪
### 认证方法
**XML-RPC（旧版，默认）：** - 密码/API 密钥在 XML-RPC 请求正文中发送 - 所有 Odoo 版本均支持
**JSON-RPC (Odoo 19+)：** - API 密钥作为 `Authorization: Bearer <api_key>` 请求头发送 - 对于大型数据集效率更高 - 使用 `ODOO_RPC_BACKEND=json2` 启用
### 模型调用策略
**🚫 模型调用已严格禁用。**
根据 `skill.json`： ```json "modelInvocation": { "disabled": true, "requiresUserInvocation": true } ```
这意味着： - AI 模型不能自动调用此技能 - 用户必须明确请求 Odoo 操作 - 每次调用都需要用户意图
### 强制只读
该技能会阻止所有数据修改方法：
**被阻止的方法：** - `create`, `write`, `unlink` (CRUD 操作) - `copy` (复制记录) - `action_post`, `action_confirm`, `button_validate` (工作流操作)
**允许的方法（只读）：** - `search`, `search_read`, `read` (数据检索) - `search_count`, `fields_get` (元数据) - `name_search`, `context_get`, `default_get` (辅助工具)
尝试调用被阻止的方法将引发 `PermissionError`。
### 数据处理与隐私
- **无数据外泄**：报告在 `assets/autonomous-cfo/output/` 中本地生成 - **无遥测**：没有使用数据发送到外部服务器 - **网络隔离**：仅连接到 `.env` 中指定的 `ODOO_URL` - **凭证安全**：密码/API 密钥从不记录或显示 - **本地处理**：所有图表生成、PDF 创建均在本地进行
### 输出安全
所有输出仅限本地文件： - `output/pdf_reports/` - PDF 报告 - `output/whatsapp_cards/` - PNG 图片卡片 - `output/charts/` - 图表图片 - `output/excel/` - Excel 电子表格
无云端上传，无外部共享，除了您指定的 Odoo 实例外，没有数据会离开您的机器。
### 安装
该技能需要包含特定包的 Python 虚拟环境：
```bash cd skills/odoo/assets/autonomous-cfo ./install.sh ```
或手动安装： ```bash cd skills/odoo/assets/autonomous-cfo python3 -m venv venv ./venv/bin/pip install -r requirements.txt ```
**依赖项：** `requests`, `matplotlib`, `pillow`, `fpdf2`, `openpyxl`
## 关键规则
1. **绝不假设** - 在生成报告之前，务必询问澄清问题 2. **多公司检查** - 如果存在多个公司，请询问使用哪一个 3. **基于分类帐** - 使用会计科目表和凭证行 (account.move.line)，而不仅仅是发票汇总 4. **验证期间** - 运行前与用户确认日期范围 5. **无静默默认值** - 每一个假设都必须得到确认
## 在生成任何报告之前，请询问：
1. “我应该使用哪个公司？”（如果存在多个） 2. “什么时间段？（起止日期）” 3. “包含哪些科目或科目类型？” 4. “需要任何具体的细分吗？”（按科目、按合作伙伴、按日记账等） 5. “输出格式偏好？”（PDF、WhatsApp 卡片或两者）
## 入口点
使用安装了 fpdf2、matplotlib、pillow 的 venv 以正确生成 PDF/图表：
```bash ./skills/odoo/assets/autonomous-cfo/venv/bin/python ./skills/odoo/assets/autonomous-cfo/src/tools/cfo_cli.py <command> ```
或从技能目录： ```bash cd skills/odoo/assets/autonomous-cfo && ./venv/bin/python src/tools/cfo_cli.py <command> ```
## 基于会计科目表的报告
报告应基于以下内容构建： - `account.account` - 会计科目表结构（代码、名称、类型、internal_group） - `account.move.line` - 凭证行（借方、贷方、account_id、日期） - `account.journal` - 源日记账（类型：销售、采购、现金、银行、通用）
### 科目内部组 - **ASSET** - 资产（流动、非流动、现金、应收款） - **LIABILITY** - 负债（应付款、税费、应计） - **EQUITY** - 所有者权益 - **INCOME** - 收入科目 - **EXPENSE** - 成本和费用科目 - **OFF_BALANCE** - 资产负债表外科目
### 常见科目类型 - `asset_cash` - 银行和现金科目 - `asset_receivable` - 应收账款 - `asset_current` - 流动资产 - `liability_payable` - 应付账款 - `income` - 收入 - `expense` - 费用
### 特殊权益类型（Odoo 专用） - `equity` - 标准权益科目（股本、留存收益） - `equity_unaffected` - 未分配利润/损失的**暂记科目**（例如 999999）
**资产负债表关键点：** Odoo 的 `equity_unaffected` 是一个暂记科目。不要直接使用其分类帐余额。
**正确的权益计算：** 1. **权益本体** (类型: `equity`) - 使用分类帐余额 (贷方 - 借方) 2. **留存收益** (以前年度) - 来自 `equity_unaffected` 的分类帐余额 3. **本年收益** - 实时计算：收入 - 费用
``` Total Equity = Equity Proper + Retained Earnings + Current Year Earnings ```
其中，本年收益 = Σ(收入 贷方-借方) - Σ(费用 借方-贷方)
**为什么这很重要：** Odoo 会在资产负债表上实时计算本年收益。仅使用 `equity_unaffected` 分类帐余额会导致资产负债表不平。
## 自动报告标准检测
该技能会根据国家/司法管辖区自动检测公司的会计标准，并相应地格式化报告。
**支持的标准：** | 标准 | 司法管辖区 | 备注 | |----------|--------------|-------| | IFRS | 国际 | 大多数国家的默认标准 | | US GAAP | 美国 | SEC 注册人 | | Ind-AS | 印度 | 与 IFRS 趋同的印度 GAAP | | UK GAAP | 英国 | FRS 102 | | SOCPA | 沙特阿拉伯 | 采用 IFRS | | EU IFRS | 欧盟 | IAS 法规 | | CAS | 中国 | 中国会计准则 | | JGAAP | 日本 | 日本 GAAP | | ASPE | 加拿大 | 私营企业 | | AASB | 澳大利亚 | 澳大利亚标准 |
**检测逻辑：** 1. 从 `res.company` 查询公司所在国家 2. 将国家代码映射到报告标准 3. 应用特定于标准的格式化： - 数字格式 (1,234.56 vs 1.234,56) - 负数显示 ((123) vs -123) - 日期格式 (DD/MM/YYYY vs MM/DD/YYYY) - 报表标题 (资产负债表 vs 财务状况表) - 现金流方法（间接法 vs 直接法）
**覆盖：** ```python # Force a specific standard reporter.generate(..., standard="US_GAAP") ```
## 命令
### 销售 & CRM 查询
```bash # Salesperson performance - use direct RPC for flexibility ./venv/bin/python -c " from src.visualizers.whatsapp_cards import WhatsAppCardGenerator # Query sale.order by user_id, aggregate by month/status # Generate cards with generate_kpi_card() and generate_comparison_card() "
# Example RPC query for salesperson: # - sale.order (user_id, amount_total, state, date_order) # - account.move (invoice_user_id, amount_total, payment_state) # - res.users (salesperson info) # - res.partner (customer info) ```
### 预构建报告
```bash # Financial Health - cash flow, liquidity, burn rate, runway cfo_cli.py health --from YYYY-MM-DD --to YYYY-MM-DD --company-id ID
# Revenue Analytics - MoM trends, top customers cfo_cli.py revenue --from YYYY-MM-DD --to YYYY-MM-DD --company-id ID
# AR/AP Aging - overdue buckets cfo_cli.py aging --as-of YYYY-MM-DD --company-id ID
# Expense Breakdown - by vendor/category cfo_cli.py expenses --from YYYY-MM-DD --to YYYY-MM-DD --company-id ID
# Executive Summary - one-page CFO snapshot cfo_cli.py executive --from YYYY-MM-DD --to YYYY-MM-DD --company-id ID ```
### 直接 RPC 查询（高级）
对于预构建命令未涵盖的销售/CRM 数据，请使用直接 RPC：
```python # Query sales orders by salesperson orders = jsonrpc('sale.order', 'search_read', [[('user_id', '=', SALESPERSON_ID)]], {'fields': ['name', 'partner_id', 'amount_total', 'state', 'date_order']})
# Query invoices by salesperson invoices = jsonrpc('account.move', 'search_read', [[('invoice_user_id', '=', SALESPERSON_ID), ('move_type', '=', 'out_invoice')]], {'fields': ['name', 'partner_id', 'amount_total', 'payment_state']})
# Find salesperson by name users = jsonrpc('res.users', 'search_read', [[('name', 'ilike', 'name_here')]], {'fields': ['id', 'name', 'login']}) ```
### 即席报告
```bash # Custom comparison cfo_cli.py adhoc --from YYYY-MM-DD --to YYYY-MM-DD --metric-a "revenue" --metric-b "expenses"
# Examples: cfo_cli.py adhoc --metric-a "cash in" --metric-b "cash out" cfo_cli.py adhoc --metric-a "direct expenses" --metric-b "indirect expenses" ```
### 输出格式
```bash --output whatsapp # Dark theme 1080x1080 PNG cards --output pdf # Light theme A4 PDF --output excel # Excel workbook (.xlsx) --output both # PDF + WhatsApp cards --output all # PDF + Excel + WhatsApp cards ```
## 自动可视化
**报告默认情况下始终包含适当的可视化：**
| 报告 | 自动包含的图表 | |--------|---------------------| | 财务健康 | 现金头寸、烧钱率趋势、跑道 | | 收入 | 环比 趋势、前几名客户、增长 KPI | | 应收/应付账龄 | 账龄 bucket 饼图、逾期高亮 | | 费用 | 类别细分、趋势、前几名供应商 | | 管理层 | 所有 KPI 卡片、汇总图表 | | 资产负债表 | 资产/负债构成 | | 损益 | 收入 vs 费用、利润率趋势 | | 现金流 | 经营细分、现金趋势 |
**规则：** 如果可视化能使报告更清晰，请自动包含它。绝不要问“你想要图表吗？”——直接添加即可。
## 交互式参数收集
如果缺少必需的参数，技能将会询问：
1. **公司：** “哪个公司？”（列出可用选项） 2. **期间：** “什么时间段？（例如‘上个月’、‘2024 年第四季度’、自定义日期）” 3. **科目：** “哪些科目或组？”（例如‘所有收入’、‘仅银行账户’） 4. **细分：** “按什么分组？（月、客户、类别、科目）” 5. **输出：** “输出格式？（WhatsApp 卡片、PDF、两者）”
## 如何在聊天中使用
只需自然地询问：
**销售 & CRM：** - “[姓名] 销售员的业绩如何？” - “显示 [销售员] 的前几名客户” - “比较销售团队绩效” - “哪个销售员的订单最多？”
**财务报告：** - “给我上季度的财务健康报告” - “显示过去 6 个月的收入与费用” - “我的应收账款账龄是多少？” - “生成本月的管理层摘要” - “显示基于会计科目表的损益表”
**一般查询：** - “我们这个月收到了多少订单？” - “谁是前 10 名客户？” - “显示 [客户名称] 的发票状态”
该技能将执行以下操作： 1. 检查是否有多个公司并询问具体是哪一个 2. 解析您的请求 3. 询问任何缺失的信息 4. 使用分类账条目或直接 RPC 从 Odoo 获取数据 5. 生成图表 + WhatsApp 卡片 6. 通过 WhatsApp 卡片和/或 PDF 进行交付
## 严格规则
1. Odoo RPC 输出是事实来源 2. 严格只读（无创建/写入/取消链接操作） 3. 除非被要求，否则不采取主动操作 4. 每个数字都包含方法论说明 5. 在假设之前务必与用户核实 6. **始终包含可视化** - 如果报表能从图表/图形中受益，请自动包含它们，无需询问。报表应在视觉上呈现完整。
## 诊断
```bash python3 ./skills/odoo/assets/autonomous-cfo/src/tools/cfo_cli.py doctor ```
## 报表主题
- **WhatsApp 卡片：** "Midnight Ledger" —— 海军黑 (#0a0e1a)，铜色光晕 (#cd7f32) - **PDF 报表：** 纯净白色，铜色点缀，专业布局