diff --git a/.agent/rules/general-chs-guide.md b/.agent/rules/general-chs-guide.md new file mode 100644 index 0000000..f9a7c93 --- /dev/null +++ b/.agent/rules/general-chs-guide.md @@ -0,0 +1,35 @@ +--- +trigger: always_on +--- + +## 核心理念与原则 +- 以产品可用性为第一优先级 +- 本项目目标是构建一个真实可用的**产品**，而非概念展示或一次性Demo. +- 所有设计与实现应优先满足用户体验与实际使用价值。 +- 简洁与克制 +- 遵循 KISS原则 (Keep it Simple, Stupid) ，避免过度工程化、过早抽象与非必要的防御性设计。 +- 在功能与架构上，优先选择当前阶段最简单、最可则，维护的方案。 + + +### 第一性原理分析 +- 在提出方案或进行实现前，需从问题本质出发分析需求，避免套用通用模板或行业黑话。 +- 必要时应明确指出需求中的不合理或可优化之处。 +- 事实为准、允许纠错 +- 以事实与逻辑为最高准则。 +- 当发现需求描述、假设或技术判断存在问题时，应明确指出并给出改进建议，而非盲目迎合。 + +### 开发与协作工作流 +- 渐进式推进 +- 所有复杂功能应通过多轮对话逐步澄清与实现， +- 在未完成需求澄清与方案讨论前，不得直接进入详细编码阶段。 + +### 结构化执行严格遵循以下顺序: +- 需求理解与澄清 +- 方案构思与取舍说明 +- 经确认后拆解为可执行的具体任务 +- 与产品定位保持一致 +- 所有功能、内容生成与技术设计，必须服务于「产品」的产品定位: + +## 输出与沟通规范 +- 语言规范:所有回复、分析、方案说明与任务清单，必须使用中文。 +- 表达要求:结构清晰、层次分明，避免冗余说明与无关扩展。 \ No newline at end of file diff --git a/docs/overall.md b/docs/overall.md index f66631b..6778f83 100644 --- a/docs/overall.md +++ b/docs/overall.md @@ -2,8 +2,8 @@ **版本**：v1.0 | **优先级**：P0 | **受众**：后端架构师、数据工程师 ## 1. 核心设计理念 -“去科目化、重维度化” -摒弃传统金蝶/用友的“多级会计科目”挂账模式（如 `6601.01.05 销售费用-家办-张三`），采用**“扁平科目 + 必须维度标签”**的数据库结构。 +本系统旨在构建一个介于**前端业务数据（灵活、多维）** 与 **传统会计系统（合规、刚性）** 之间的独立** “会计引擎（Accounting Engine）” **。 +核心理念是：“去科目化、重维度化”。摒弃传统金蝶/用友的“多级会计科目”挂账模式（如 `6601.01.05 销售费用-家办-张三`），采用**“扁平科目 + 必须维度标签”**的数据库结构。 **系统行为逻辑：** 任何一笔收入或支出（Journal Entry Line），在入库时**必须**携带维度标签。所谓的“剩余/中后台”，在系统底层不应通过“减法”计算存储，而应作为**“默认兜底标签（Default Bucket）”**进行归集，报表展示时再按层级聚合。 @@ -24,21 +24,28 @@ | **Family_Office** | 家办整体 | 对应家办业务线的所有收支（将触发Level 2必填校验）。 | | **Corp_BackOffice** | 基金中后台 (剩余) | **默认值**。既不属于PM，也不属于市场和家办的通用行政、合规、房租、核心管理层成本。 | -### Level 2：家办子维度 (`dim_sub_segment`) -**触发条件**：仅当 Level 1 = `Family_Office` 时，该字段为**必填项**；否则为空或 N/A。 +### Level 2：业务子维度 (`dim_sub_segment`) +不再局限于家办，所有 Level 1 业务线均可定义自己的子维度。 -| 枚举值 (Value) | 业务含义 (Description) | 逻辑定义/自动化规则 | +| Level 1 | 枚举值 (Value) | 业务含义 (Description) | | :--- | :--- | :--- | -| **FO_Sales** | 家办员工 (销售) | 归属于家办的销售人员薪酬、提成、差旅。 | -| **FO_Channel** | 家办渠道 | 支付给外部家办渠道（三方财富、银行端）的尾佣、服务费。 | -| **FO_Admin** | 家办中后台 (剩余) | **默认值**。家办团队的行政分摊、未具体到人的团建费、家办负责人薪酬（若不计入销售）。 | +| **Family_Office** | **FO_Sales** | 家办员工 (销售) | +| **Family_Office** | **FO_Channel** | 家办渠道 | +| **Family_Office** | **FO_Admin** | 家办中后台 (默认) | +| **Marketing** | **MKT_Online** | 线上投放 | +| **Marketing** | **MKT_Offline** | 线下活动 | +| **PM_Strategy** | **Strat_Equity** | 股票策略 | +| **PM_Strategy** | **Strat_CTA** | 期货策略 | -### Level 3：颗粒度对象 (`dim_object_id`) -为了实现精细化核算（PM清单、员工个人），需挂载具体对象ID。 +### Level 3：精细化对象 (Specific Objects) +为了避免“多态ID”带来的外键约束缺失问题，**严禁**使用单一的 `dim_object_id`。 +数据库应设计分离的可空列（Nullable Foreign Keys）： -* **关联 PM/产品**：当 L1=`PM_Strategy`，关联 `Product_ID` 或 `PM_ID`。 -* **关联 员工**：当 L2=`FO_Sales`，关联 `Employee_ID`。 -* **关联 渠道**：当 L2=`FO_Channel`，关联 `Vendor_ID` (渠道方)。 +* **`dim_product_id`**: 关联产品表 (Product Table) +* **`dim_employee_id`**: 关联员工表 (Employee Table) +* **`dim_vendor_id`**: 关联客商表 (Vendor Table) + +**填值规则**：根据业务场景填充对应列，其余列留空。例如支付阿里云费用，填充 `dim_vendor_id`，而 `dim_employee_id` 为空。 --- @@ -54,7 +61,7 @@ * **IF** 收款人 = "招商证券" (托管费) **AND** 备注包含 "产品A" * **THEN** `dim_segment` = **PM_Strategy**, `dim_object_id` = **Product_A** * **IF** 收款人 = "阿里云" - * **THEN** (需要分摊逻辑，见规则2) OR 默认 `Corp_BackOffice` + * **THEN** 触发 **Split Transaction (拆单)** 逻辑，按预设比例分摊至不同PM，生成多行凭证。 ### 规则 2：基于“默认兜底”的减法逻辑实现 需求中提到的“剩余”概念，在系统录入时体现为**默认值**。 @@ -69,8 +76,7 @@ --- - -## 5. 报表视图需求 (Output Requirements) +## 4. 报表视图需求 (Output Requirements) 系统需前端需支持动态透视表（Pivot Table）展示，逻辑如下： @@ -95,99 +101,47 @@ ### 给技术团队的特别备注 (CFO Notes) 1. **数据清洗优先**：请优先开发“客商/人员”与“维度标签”的绑定配置页面，这是自动化的基础。没有这个，财务还是得手工录入。 -2. **分摊功能预留**：虽然目前需求是“剩余归集”，但未来一定会遇到“一笔阿里云账单要按比例分摊给3个PM”的情况，请预留 `Split_Transaction`（一拆多）的接口能力。 -3. **PM与产品的关系**：PM与产品是1对N的关系，建议在 `related_object_id` 记录产品ID，通过主数据表映射回PM，这样PM换人管理产品时，历史数据不会乱。 - - -这是一个非常典型且高价值的**“财务中台（Financial Data Middleware）”**架构需求。 - -你的核心诉求是：**前端业务数据（灵活、多维）** $\rightarrow$ **自动化处理（黑盒/规则）** $\rightarrow$ **传统会计系统（合规、刚性）**。 - -在2026年的技术与管理视角下，我们不应该试图改造传统会计软件（金蝶/用友/Xero），而是构建一个独立的**“会计引擎（Accounting Engine）”**。以下是为你设计的整体架构框架与技术栈选择。 +2. **必须支持一拆多 (Split Transaction)**：不要仅仅“预留接口”。在 V1.0 的数据库设计中，必须直接支持 **1行银行流水 $\rightarrow$ N行财务凭证** 的父子表结构。这是高频刚需。 +3. **PM与产品的关系**：建议建立明确的 Product 表和 Employee 表，处理好 managed_by 的时间维度关系。 --- -### 一、 整体架构设计逻辑：财务数据中台模式 +## 5. 技术架构总体设计 (Technical Architecture) -我们把系统分为三层：**数据接入层（Input）**、**核心处理层（Process）**、**合规输出层（Output）**。 +### 5.1 整体架构逻辑：财务数据中台模式 -#### 1. 数据接入层 (Data Ingestion) - "ETL" +系统架构分为三层：**数据接入层（Input）**、**核心处理层（Process）**、**合规输出层（Output）**。 + +#### 1. 数据接入层 (Data Ingestion) 负责将非标准的业务数据统一为系统可读的格式。 -* **数据源 A (资金流)**：银行对账单（Excel/API）、第三方支付流水。 -* **数据源 B (业务流)**：运营部发来的估值表、应收台账（管理费/业绩报酬）、应付台账（渠道佣金）。 -* **动作**：清洗（Cleaning）、去重（De-duplication）、标准化（Normalization）。 +* **资金流数据**：银行对账单（Excel/API）、第三方支付流水。 +* **业务流数据**：外部估值表、应收台账（管理费/业绩报酬）、应付台账（渠道佣金）。 +* **核心动作**：清洗（Cleaning）、去重（De-duplication）、标准化（Normalization）。 -#### 2. 核心处理层 (The Core Engine) - "Tagging & Mapping" -这是系统的“大脑”，包含三个核心步骤： +#### 2. 核心处理层 (The Core Engine) +系统的核心逻辑层，包含以下模块： -* **步骤 2.1：智能打标 (Labeling / Dimension Injection)** - * **输入**：原始流水摘要（如“付阿里云12月账单”）。 - * **处理**： - * **规则引擎（Rule-based）**：基于关键词（阿里云 -> IT成本）、账号（张三 -> 家办销售）、金额（精确匹配）自动打标签。 - * **机器学习（ML-based）**：对于规则无法覆盖的（如模糊摘要），利用NLP模型预测标签，并设置**“人工确认（Human-in-the-loop）”**机制。 - * **人工补录**：对于系统置信度低的数据，提供前端界面供财务人员手动打标。 - * **产出**：带有完整业务维度（PM、家办、渠道、员工）的“宽表数据”。 +* **智能打标 (Dimension Injection)**： + * **规则引擎**：基于关键词、账号、金额等规则自动匹配维度。 + * **人工补录**：对于置信度低的数据，提供界面供财务人员手动打标。 + * **产出**：带有完整业务维度（PM、家办、渠道、员工）的宽表数据。 -* **步骤 2.2：业务对账 (Reconciliation)** - * *这是管理人痛点*。运营的“应付渠道佣金台账”必须与“银行实际付款”进行核销。 - * 系统需自动匹配：`运营台账.金额 == 银行流水.金额` 且 `商户名近似`，实现自动核销。 +* **业务对账 (Reconciliation)**： + * 自动匹配运营台账与银行流水，实现应收/应付的自动核销。 -* **步骤 2.3：会计引擎 (Accounting Engine)** - * **配置**：预设“场景-分录映射表”（Mapping Table）。 - * **逻辑**： - * 场景：标签为`[家办渠道]` + `[支出]` - * 动作：生成 `借：销售费用-家办渠道` / `贷：银行存款`。 - * **产出**：标准化的凭证数据结构（Voucher Data）。 +* **会计引擎 (Accounting Engine)**： + * 基于预设的“场景-分录映射表”，将业务动作转化为标准化凭证数据（借：销售费用 / 贷：银行存款）。 -#### 3. 合规输出层 (Output Adapter) - "RPA/API" -* **目标**：传统会计软件（金蝶/用友/QuickBooks）。 -* **方式**： - * **API对接**（推荐）：直接调用目标系统的API写入凭证。 - * **标准引入模版**：生成目标系统要求的Excel/XML格式供导入。 +#### 3. 合规输出层 (Output Adapter) +* **目标**：传统会计软件（金蝶/用友）。 +* **实现**：通过API对接或生成标准导入模版（Excel/XML），实现凭证自动推送。 ---- - -### 二、 技术栈选择建议 (2026 Standard) - -考虑到灵活性、Python在量化金融圈的统治地位以及AI生态的适配性，强烈建议采用 **Python-based** 栈。 - -#### 1. 后端 (Backend) -* **语言**：**Python 3.x** - * *理由*：处理数据（Pandas）最强，对接AI模型（PyTorch/Scikit-learn）最无缝，且量化公司的IT对Python最熟悉，维护成本低。 -* **Web框架**：**FastAPI** - * *理由*：高性能，原生支持异步，自动生成API文档，适合构建微服务架构的中台。 - -#### 2. 数据库 (Database) -* **关系型数据库 (RDBMS)**：**PostgreSQL** - * *理由*：开源最强，支持JSONB格式（非常适合存储不确定的多维标签数据），支持复杂查询，且金融级稳定。 -* **缓存/队列**：**Redis** - * *理由*：用于处理流水打标的任务队列（Celery/RQ）。 - -#### 3. 核心算法与数据处理 (Data & AI) -* **数据处理**：**Pandas / Polars** - * *理由*：处理Excel、CSV、清洗数据的标准库。 -* **规则/AI引擎**： - * **规则流**：自定义Python逻辑（最快落地）。 - * **NLP分类**：使用轻量级预训练模型（如 DistilBERT 或 简单的 TF-IDF + Logistic Regression）进行文本分类。 - * *注意*：初期不要过度迷信大模型，基于规则+简单的贝叶斯分类器通常足够处理90%的银行流水。 - -#### 4. 前端 (Frontend) - 用于人工打标和审核 -* **框架**：**React** 或 **Vue 3** - * *理由*：生态成熟。你需要开发一个类似“Excel Grid”的界面（推荐使用 **AG Grid** 组件），让财务能快速批量审核、修改标签。 - -#### 5. 部署与调度 (DevOps) -* **容器化**：**Docker** -* **任务调度**：**Apache Airflow** 或 **Prefect** - * *理由*：你需要定时任务：每天凌晨拉取银行流水 -> 触发打标任务 -> 生成凭证 -> 推送ERP。 - ---- - -### 三、 系统运作流程图 (Data Flow) +### 5.2 系统运作流程图 (Data Flow) ```mermaid graph TD A[数据源] -->|Excel/API| B(数据清洗模块 ETL) - B --> C{规则引擎 + AI模型} + B --> C{规则引擎 + AI辅助} C -->|高置信度| D[已打标中间表] C -->|低置信度| E[人工审核界面 UI] @@ -210,23 +164,11 @@ graph TD end ``` ---- +### 5.3 关键实施要素 (Critical Success Factors) -### 四、 财务总监的特别提醒 (Critical Success Factors) - -作为CFO，我必须指出这套架构在落地时会遇到的三个**非技术性**坑： - -1. **权责发生制 vs 收付实现制 (Accrual vs Cash)** - * 银行流水是收付实现制，运营台账是权责发生制。 - * **设计难点**：系统必须能处理“先挂账、后核销”的逻辑。 - * *建议*：初期第一版可以先做“纯流水记账”（Cash Basis），跑通后再加入“应收应付核销”模块。 - -2. **数据源的唯一标识 (Unique Key)** - * 银行流水通常没有唯一的Transaction ID（特别是Excel导出），或者跨天会有变化。 - * *建议*：在ETL层必须计算每条流水的Hash值（MD5 of 日期+金额+对方户名+摘要），防止重复记账。 - -3. **人工介入的必要性 (Human-in-the-Loop)** - * 不要承诺100%自动化。财务的核心是**准确**。 - * *设计原则*：系统必须默认展示“待审核”状态，只有财务人员点击“Post/过账”按钮后，才允许推送到金蝶/用友。不要让机器直接写库，否则查错成本极高。 - -这套架构既能满足你对**多维度分析**的需求（在Python/Postgres层实现），又能满足**合规报税**的需求（在传统会计软件层实现），是目前金融科技公司最主流的财务架构方案。 \ No newline at end of file +1. **权责发生制支持**：系统需从设计之初考虑“挂账”与“核销”逻辑，以兼容运营台账（权责发生制）与银行流水（收付实现制）的差异。 +2. **数据唯一性保障 (Advanced Deduplication)**： + * 简单的MD5(日期+金额)不足以防重（如同日同给同一人的两笔相同报销）。 + * **改进方案**：引入 **“期末余额 (Ending Balance)”** 校验，或在哈希因子中加入“流水号/Sequence ID”。 + * **兜底机制**：对于完全相同的疑似重复交易，系统应标记为 `Duplicate_Suspect`，强制要求人工审核确认是“重复记账”还是“真实发生的第二笔交易”。 +3. **人工介入机制 (Human-in-the-Loop)**：系统必须遵循“机器预处理 -> 人工确认 -> 正式过账”的流程。在推送到金蝶/用友之前，必须保留人工审核的节点，确保财务数据的绝对准确性。 \ No newline at end of file