feat(finance): integrate quanttide-finance-toolkit v0.2.0

.github/workflows/dart-check.yml

@@ -0,0 +1,20 @@
+name: dart-check
+on:
+  push:
+    paths: ['packages/finance/dart/**']
+  pull_request:
+    paths: ['packages/finance/dart/**']
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/finance/dart
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dart-lang/setup-dart@v1
+        with:
+          sdk: stable
+      - run: dart pub get
+      - run: dart analyze
+      - run: dart test

.github/workflows/dart-publish.yml

@@ -0,0 +1,16 @@
+name: publish-dart
+on:
+  release:
+    types: [published]
+jobs:
+  publishing:
+    if: startsWith(github.ref, 'refs/tags/dart/')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: k-paxian/dart-package-publisher@master
+        with:
+          credentialJson: \${{ secrets.PUBDEV_CREDENTIAL_JSON }}
+          relativePath: packages/finance/dart
+          force: true
+          flutter: false

.gitignore

@@ -1,42 +1,82 @@
-# Python
+# ─── Python ───────────────────────────────────────────────
 __pycache__/
 *.py[cod]
 *$py.class
 *.so
 .Python
+*.egg-info/
+*.egg
+.venv*/
+venv/
+ENV/
 build/
 develop-eggs/
 dist/
 downloads/
 eggs/
 .eggs/
+lib/
 lib64/
 parts/
 sdist/
 var/
 wheels/
-*.egg-info/
+*.whl
 .installed.cfg
-*.egg
-.venv/
-venv/
-ENV/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage/
+htmlcov/
 
-# Data
-data/
+# ─── Dart / Flutter ──────────────────────────────────────
+.dart_tool/
+.pub/
+.builders/
+build/
+*.freezed.dart
+*.g.dart
+.pub-preload-cache/
+*.js_
+*.js.deps
+*.js.map
+
+# ─── Data / Environment ──────────────────────────────────
 .env
+.env.local
+.env.production
+*.db
+data/
+*.log
+logs/
 
-# IDE
+# ─── IDE / Editor ────────────────────────────────────────
 .idea/
 .vscode/
 *.swp
 *.swo
+*~
+.vs/
+*.suo
+*.user
+*.userosscache
+*.sln.docstates
 
-# OS
+# ─── OS ──────────────────────────────────────────────────
 .DS_Store
 Thumbs.db
+Desktop.ini
+ehthumbs.db
 
-# Terraform
+# ─── Terraform ───────────────────────────────────────────
 .terraform/
-terraform/terraform.tfstate
-terraform/terraform.tfstate.backup
+*.tfstate
+*.tfstate.backup
+*.tfvars
+
+# ─── Build Artifacts ─────────────────────────────────────
+*.tar.gz
+*.zip
+*.dmg
+*.pkg

CHANGELOG.md

@@ -4,6 +4,116 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/).
 
+## [0.2.0] - 2026-06-14
+
+### Added
+
+#### Finance 模块
+
+新增 `packages/finance/` 三层包结构，实现财务记录标准化、分类和统计的核心流程：
+
+```
+SourceRecord → NormalizedRecord → ClassificationResult → Statistics
+                                     ↓ (可选)
+                     Journal / JournalEntry / JournalEntryLine
+```
+
+##### `packages/finance/dart/`（版本 0.2.0）
+
+Dart 领域模型与共享 DTO：
+- `Journal` / `JournalEntry` / `JournalEntryLine` 凭证模型（freezed 不可变，`copyWith` + JSON 序列化）
+- 8 个枚举：`SourceType` / `IngestionStatus` / `RecordType` / `Direction` / `NormalizationStatus` / `ClassifierKind` / `ReviewStatus` / `LineType`（`@JsonEnum` + `@JsonValue` 显式映射 + `unknown` 兜底）
+- 测试：`journal_test.dart`
+
+##### `packages/finance/fastapi/`（版本 0.1.0）
+
+FastAPI 后端，Python 3.12+，SQLAlchemy 2.0 + SQLite：
+
+- **4 个 ORM 模型**：
+  - `SourceRecord`（`source_type` / `raw_text` / `evidence_refs` / `ingestion_status`）
+  - `NormalizedRecord`（`amount_cents` / `direction` / `department` / `person` / `business_date`）
+  - `RecordLink`（SourceRecord ←→ NormalizedRecord 多对多关联）
+  - `ClassificationResult`（`category` / `classifier_kind` / `confidence` / `review_status` / `is_active`）
+
+- **Pydantic schema 层**：Create/Read/Update 分离，字段约束：
+  - `amount_cents >= 0`（`Field(ge=0)`）
+  - `raw_text > 65535` → reject（422）
+  - `description > 1000` → 静默截断
+
+- **Alembic 迁移**：2 个脚本（M1 基础实体 + M2 tags JSON 修复）
+
+- **3 组 REST 路由器**：
+  - `source_records`：SourceRecord CRUD + NormalizedRecord CRUD + `POST /source-records/{id}/normalize`
+  - `classifications`：创建 + 列表 + `PATCH` 审核/软删除
+  - `statistics`：4 个统计端点 — `summary`（汇总卡片）、`breakdown?dimension=`（分组）、`trend?granularity=`（趋势）、`drilldown`（明细），支持 department / person / record_type / direction / currency / taxonomy+category 等多维度筛选
+
+- **Normalizer 接口 + 注册机制**，内置 2 个实现：
+  - `CsvRowNormalizer`：解析标准列 CSV（9 列自动映射，含 department / person / counterparty 可选列）
+  - `ManualNormalizer`：手工录入兜底（raw_text → description）
+
+- **测试**：7 个文件，30 项测试，涵盖 schema 验证、路由集成、normalizers、statistics 全端点
+- **测试基础设施**：Alembic 自动迁移 + SQLite `PRAGMA foreign_keys=ON` + 每测试独立临时数据库
+
+##### `packages/finance/flutter/`（版本 0.1.0）
+
+Flutter API 适配层：
+- `FinanceApiClient`：Dart HTTP 客户端，封装所有后端 REST 调用（CRUD + normalize + classify + 4 个 statistics 端点）
+- Mockito 测试：`client_test.dart` + `client_test.mocks.dart`
+- `main.dart`：独立验证壳（非 Studio 集成，仅用于单独启动测试）
+
+##### `examples/finance/`
+
+前端演示 Demo：
+- `index.html`：HTML/CSS/JS 实现的完整 5 步产品流程（录入 → 标准化确认 → 关键词预分类 → 批量审核 → 统计看板）
+- `seed.py`：种子数据脚本 + `demo.db` 预填充数据库
+- `RUN_DEMO.md` / `README.md`：启动说明
+
+#### Studio Finance 集成
+
+在 `packages/finance/` 三层之上新增的 Studio 专属层：
+
+- **新建 `src/studio/packages/qtadmin-finance/` 包**
+  - `FinanceModuleConfig`：API base URL + `enableReviewQueue` / `enableStatistics` 功能开关
+  - `FinanceWorkspaceScreen`：Flutter 工作区屏幕，包含：
+    - 3 张统计卡片（record count / amount / classified count）
+    - 手工录入表单（raw text / date / amount / department / person / description + record type + direction）
+    - 审核队列（分类浏览、单条编辑、审核对话、多选批量确认）
+    - 部门分布面板（top 5）+ 月度趋势面板（最近 6 期）
+    - 加载 / 错误 / 空数据三种状态 UI，`¥1,234.56` 中文金额格式化
+  - Widget 测试（表单验证、录入、编辑、批量审核）+ Route 测试
+
+- **路由注册**：`src/studio/lib/router.dart` 新增 `finance` 路由（`label: '财务管理'`，icon `Icons.account_balance_outlined`），API base URL 通过 `ScreenContext.financeConfig` 注入
+- **`ScreenContext`** 新增 `financeConfig` 字段
+- **`src/studio/lib/blocs/app_bloc.dart`**：传递 `financeConfig` 至 `ScreenContext`
+- **`src/studio/pubspec.yaml`**：新增 `qtadmin_finance` path 依赖
+
+#### CI 与发布管线
+
+- `.github/workflows/dart-check.yml`：push/PR 触发 `packages/finance/dart/**`，执行 `dart pub get` → `dart analyze` → `dart test`
+- `.github/workflows/dart-publish.yml`：标签 `dart/` 前缀触发 pub.dev 自动发布
+
+#### 文档
+
+- `docs/dev/finance-integration-plan.md`：finance 模块集成策略、分期计划（P0–P4）
+- `docs/user-guide/finance.md`：用户指南
+- `docs/user-guide/human.md`：人力资源职能用户手册
+- `docs/user-guide/asset.md`：资产职能用户手册
+- `docs/user-guide/business.md`：业务线用户手册
+- `docs/user-guide/index.md`：用户手册索引
+- `docs/add/hr-email-import.md`：招聘邮箱导入程序架构设计
+- `STATUS.md`：项目状态概览
+
+### Changed
+
+- `docs/myst.yml`：目录结构调整，保留 `user-guide` 目录
+- 侧边栏导航：新增"财务管理"入口，使用 `RouteConfig.all` 统一迭代
+
+### Removed
+
+- `.agents/skills/product-brd/SKILL.md`
+- `.agents/skills/product-drd/SKILL.md`
+- `.agents/skills/product-prd/SKILL.md`
+
 ## [0.1.0] - 2026-05-09
 
 ### Studio