docs: 提交 demo 和文档

.gitignore

@@ -36,6 +36,17 @@ data/
 .DS_Store
 Thumbs.db
 
+# Database & backup
+*.db
+*.bak
+
+# Flutter
+.gradle/
+*.iml
+.metadata
+src/studio/build/
+src/studio/.dart_tool/
+
 # Terraform
 .terraform/
 terraform/terraform.tfstate

CHANGELOG-human.md

@@ -0,0 +1,251 @@
+# Human Module Changelog
+
+> QtCloud HR — 招聘人力资源模块（human）功能更新日志，从 v0 开始记录。
+
+---
+
+## v0.1.0 — Domain Models & Screening Engine (Dart)
+
+Initial domain logic library, pure Dart with zero Flutter dependency.
+
+### Added
+
+- **Recruitment Screening** (`packages/dart/lib/src/models/recruitment.dart`)
+  - `Resume`, `JobPosition`, `ScreeningRules`, `ScreeningResult` models
+  - `Decision` enum: `pass`, `priority`, `reject`
+  - `EducationLevel` enum: `high_school`, `associate`, `bachelor`, `master`, `doctorate`
+- **Screening Service** (`packages/dart/lib/src/services/recruitment_service.dart`)
+  - `RecruitmentService.screen(Resume, JobPosition) → ScreeningResult`
+  - Three-outcome decision logic: education, experience, required skills
+  - Hard requirements must all be met for `pass`; bonus skills elevate to `priority`
+- **Compensation Calculation** (`packages/dart/lib/src/models/compensation.dart`)
+  - `CompensationParams`, `CompensationResult`, `CompensationRuleConfig` models
+  - Non-negative validation via `assert`
+- **Compensation Service** (`packages/dart/lib/src/services/compensation_service.dart`)
+  - `CompensationService.calculate(CompensationParams) → CompensationResult`
+  - Formula: `netSalary = baseSalary + overtimePay + performanceBonus - deductions`
+  - Configurable overtime multiplier and performance bonus ratio
+- **Tests** (`packages/dart/test/`)
+  - Full test coverage for recruitment screening and compensation services
+
+---
+
+## v0.2.0 — FastAPI Backend: Talent Pipeline
+
+First backend release with SQLAlchemy + SQLite, focusing on talent lifecycle management.
+
+### Added
+
+- **Database** (`packages/fastapi/src/fastapi_quanttide_hr/database.py`)
+  - `DeclarativeBase`, `get_db` dependency (abstract — must be overridden by app)
+- **Talent Model** (`packages/fastapi/src/fastapi_quanttide_hr/models/talent.py`)
+  - 8-state state machine: `NEW -> CONTACTED -> EXAM_SENT -> EXAM_RECEIVED -> EVALUATING -> INTERVIEW -> OFFER -> CLOSED`
+  - Strict `STATUS_TRANSITIONS` dict enforcing valid transitions
+- **Recruitment Model** (`packages/fastapi/src/fastapi_quanttide_hr/models/recruitment.py`)
+  - Basic recruitment entity with title
+- **Talent Schemas** (`packages/fastapi/src/fastapi_quanttide_hr/schemas/talent.py`)
+  - `TalentCreate`, `TalentRead`, `TalentUpdate`, `TalentTransition`
+- **Recruitment Schemas** (`packages/fastapi/src/fastapi_quanttide_hr/schemas/recruitment.py`)
+  - `RecruitmentCreate`, `RecruitmentRead`
+- **Recruitment Routers** (`packages/fastapi/src/fastapi_quanttide_hr/routers/recruitments.py`)
+  - CRUD: list, create, get recruitments
+  - Talent CRUD: list/create talents under recruitment
+  - Talent transition with state validation
+- **Pipeline Router** (`packages/fastapi/src/fastapi_quanttide_hr/routers/pipeline.py`)
+  - Aggregated pipeline view grouped by status
+- **Pipeline Service** (`packages/fastapi/src/fastapi_quanttide_hr/services/pipeline.py`)
+  - `get_pipeline()` query logic with `_talent_to_card` mapping
+- **Seed Data** (`packages/fastapi/src/fastapi_quanttide_hr/seed.py`)
+  - `DEMO_TALENTS` constant for demo/testing
+- **Tests** (`packages/fastapi/tests/test_lib.py`)
+  - Full model, schema, service, and API test suite
+
+---
+
+## v0.3.0 — Email Screening Gateway
+
+Added pending email queue, classifier, and mail ingestion — the recruitment email screening gateway.
+
+### Added
+
+- **Pending Queue Model** (`packages/fastapi/src/fastapi_quanttide_hr/models/pending_queue.py`)
+  - `PendingQueueItem` with email metadata, attachments, extracted fields, classifier results
+- **Pending Queue Schemas** (`packages/fastapi/src/fastapi_quanttide_hr/schemas/pending_queue.py`)
+  - `QueueItemRead`, `ConfirmRequest/Response`, `IgnoreRequest`, `IngestItem/Request/Response`
+- **Queue Router** (`packages/fastapi/src/fastapi_quanttide_hr/routers/queue.py`)
+  - List queue items (with dedup by email), confirm/ignore/adjust items
+- **Ingest Router** (`packages/fastapi/src/fastapi_quanttide_hr/routers/ingest.py`)
+  - Batch ingest emails, dedup by message_id, auto-match candidates
+- **Classifier Service** (`packages/fastapi/src/fastapi_quanttide_hr/services/classifier.py`)
+  - Keyword-based rule classification for suggested status
+- **AI Classifier Service** (`packages/fastapi/src/fastapi_quanttide_hr/services/ai_classifier.py`)
+  - LLM-powered classification with configurable provider/model
+  - Fallback: keyword rules when AI unavailable
+- **Email Matcher Service** (`packages/fastapi/src/fastapi_quanttide_hr/services/email_matcher.py`)
+  - `effective_email()`, `has_pending_queue_for_email()`, `match_by_email()`, `find_active_application()`
+- **Transition Service** (`packages/fastapi/src/fastapi_quanttide_hr/services/transition.py`)
+  - Application/Talent dual-state management with sync
+- **Example Provider App** (`packages/examples/provider/app.py`)
+  - Full FastAPI app wiring example with dependency overrides
+
+---
+
+## v0.4.0 — Flutter Kanban UI (Pipeline + Queue + Pool)
+
+First Flutter UI release — responsive kanban board for recruitment pipeline management.
+
+### Added
+
+- **App Shell** (`packages/flutter/lib/main.dart`)
+  - `MaterialApp` with custom HR theme
+  - `MainShell` responsive layout: `NavigationRail` (>600px) / `NavigationBar` (<=600px)
+  - 3-tab navigation: Pipeline, Queue, Pool
+  - `IndexedStack` for tab state preservation
+- **Pipeline Screen** (`packages/flutter/lib/screens/pipeline_screen.dart`)
+  - Kanban-style pipeline grouped by TalentStatus (new -> closed)
+  - Candidate cards with name, email, sub-stage, wait-days badge
+  - Wait-days color coding: yellow (7+), orange (14+)
+  - Drag-and-drop status transitions
+  - Candidate detail bottom sheet with email, attachments, timeline
+- **Queue Screen** (`packages/flutter/lib/screens/queue_screen.dart`)
+  - Pending email queue list with confidence badges
+  - Confirm/ignore/adjust actions
+  - Recruitment title assignment on confirm
+- **Pool Screen** (`packages/flutter/lib/screens/pool_screen.dart`)
+  - Pooled (reserve) candidate list
+  - Unpool with recruitment reassignment
+- **API Service** (`packages/flutter/lib/services/api_service.dart`)
+  - Full REST client for all backend endpoints
+  - Mutable `baseUrl` for runtime server switching
+- **Widgets**
+  - `StatusBadge`: Color-coded status pill using theme colors
+  - `EmptyState`, `ErrorView`: Reusable state views
+  - `InfoRow`: Label-value detail row
+
+---
+
+## v0.5.0 — Recruitment Applications + Materials
+
+Replaced Talent-centric model with Application-centric architecture.
+
+### Added
+
+- **Application Model** (`packages/fastapi/src/fastapi_quanttide_hr/models/application.py`)
+  - `Application` entity linking Candidate + Recruitment
+  - Pooling support (pooled_at timestamp)
+  - Source queue item reference for traceability
+- **Candidate Model** (`packages/fastapi/src/fastapi_quanttide_hr/models/candidate.py`)
+  - `Candidate` entity (name, email, phone)
+  - Unique constraint on email
+- **Application Router** (`packages/fastapi/src/fastapi_quanttide_hr/routers/applications.py`)
+  - List applications with filters (status, candidate, recruitment, pooled)
+  - Transition applications (status + sub-stage)
+  - Pool/unpool applications
+  - Get application materials (queue source, attachments, classifier info, corrections)
+- **Candidate Router** (`packages/fastapi/src/fastapi_quanttide_hr/routers/candidates.py`)
+  - CRUD: list, get, update candidates
+  - Update syncs changes to associated talents
+- **Material Service** (`packages/fastapi/src/fastapi_quanttide_hr/services/material_service.py`)
+  - Artifact management (by queue, by candidate)
+- **Mail Message Model** (`packages/fastapi/src/fastapi_quanttide_hr/models/mail_message.py`)
+  - Full email thread tracking (inbound/outbound, send status, attachments)
+- **Messages Router** (`packages/fastapi/src/fastapi_quanttide_hr/routers/messages.py`)
+  - List messages by candidate/application
+  - Timeline events
+  - Reply-to-candidate
+  - Outbox management with send status
+  - Dead letter detection and requeue
+- **Correction Log Model** (`packages/fastapi/src/fastapi_quanttide_hr/models/correction_log.py`)
+  - Field-level correction tracking
+- **Application Materials (Flutter)** (`packages/flutter/lib/models/application_materials.dart`)
+  - `ApplicationMaterials`, `QueueItemMaterials`, `AttachmentInfo`, `ResumeParseResult`, `CorrectionEntry`
+- **Mail Message Models (Flutter)** (`packages/flutter/lib/models/mail_message.dart`)
+  - `MailMessage`, `TimelineItem` with direction badges
+- **Detail Panel** — Enhanced candidate detail in pipeline:
+  - Email body display (HTML/text)
+  - Clickable attachment preview via `url_launcher`
+  - Classifier info (rule vs AI source)
+  - Correction history
+  - Message thread with direction indicators
+  - Timeline with type-specific icons (transition/reply/note/system)
+  - Reply dialog for outbound messages
+- **Resume Parser Service** (`packages/fastapi/src/fastapi_quanttide_hr/services/resume_parser.py`)
+  - PDF/text resume parsing
+
+---
+
+## v0.6.0 — AI Configuration & Settings
+
+Added AI provider configuration UI and server address management.
+
+### Added
+
+- **AI Config Model** (`packages/fastapi/src/fastapi_quanttide_hr/models/ai_config.py`)
+  - Provider, model, API key, base URL, temperature, prompt template
+- **AI Config Router** (`packages/fastapi/src/fastapi_quanttide_hr/routers/ai_config.py`)
+  - GET/PUT config, test connection endpoint
+- **Settings Screen** (Flutter) (`packages/flutter/lib/screens/settings_screen.dart`)
+  - AI config form: provider dropdown, model, API key (obscured), URL, temperature slider, prompt template
+  - Server URL field with inline save
+  - Connection test with loading state
+- **Theme System** (`packages/flutter/lib/theme/hr_theme.dart`)
+  - `HrThemeExtension` (ThemeExtension): 8 status colors, spacing tokens, font tokens
+  - `buildHrTheme()` — dark theme with `ColorScheme.dark`
+  - `HrThemeContext` extension with `statusColor(String status)` lookup
+
+---
+
+## v0.7.0 — Headcount Planning & Export
+
+### Added
+
+- **Headcount Service** (`packages/fastapi/src/fastapi_quanttide_hr/services/headcount.py`)
+  - Headcount planning and tracking
+- **Export Router** (`packages/fastapi/src/fastapi_quanttide_hr/routers/export.py`)
+  - Data export endpoints
+- **Export Service** (`packages/fastapi/src/fastapi_quanttide_hr/services/export.py`)
+  - Export data generation
+- **Export Schema** (`packages/fastapi/src/fastapi_quanttide_hr/schemas/export.py`)
+  - Export request/response models
+
+---
+
+## v0.8.0 — Feishu/Lark Email Integration
+
+### Added
+
+- **Mail Reader** (`integrations/feishu/src/feishu_integration/mail_reader.py`)
+  - Feishu mail API reader for ingesting recruitment emails
+- **Mail Ingest Loop** (`integrations/feishu/src/feishu_integration/mail_ingest_loop.py`)
+  - Polling loop: fetch -> classify -> ingest
+- **Mail Sender** (`integrations/feishu/src/feishu_integration/mail_sender.py`)
+  - Outbound mail via Feishu API
+- **Mail Sender Loop** (`integrations/feishu/src/feishu_integration/mail_sender_loop.py`)
+  - Outbox polling and sending loop
+- **Pipeline Writer** (`integrations/feishu/src/feishu_integration/pipeline_writer.py`)
+  - Write pipeline updates to Feishu documents
+- **Feishu Classifier** (`integrations/feishu/src/feishu_integration/classifier.py`)
+  - Feishu-specific classification integration
+- **Tests** (`integrations/feishu/tests/`)
+  - Classifier integration tests
+
+---
+
+## v0.9.0 — Admin CLI
+
+### Added
+
+- **CLI App** (`qtadmin-human-cli/src/qtadmin/cli.py`)
+  - Command-line interface for HR operations
+- **API Client** (`qtadmin-human-cli/src/qtadmin/api_client.py`)
+  - HTTP client for all backend endpoints
+- **Config** (`qtadmin-human-cli/src/qtadmin/config.py`)
+  - Configuration management
+- **Classifier** (`qtadmin-human-cli/src/qtadmin/classifier.py`)
+  - Rule-based email classification
+- **Mail Sender** (`qtadmin-human-cli/src/qtadmin/mail_sender.py`)
+  - Outbound email sending via API
+- **Lark Client** (`qtadmin-human-cli/src/qtadmin/lark_client.py`)
+  - Feishu API integration
+- **Tests** (`qtadmin-human-cli/tests/`)
+  - Unit tests for CLI, API client, classifier, config, lark client

CHANGELOG.md

@@ -6,24 +6,57 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0
 
 ## [0.1.0] - 2026-05-09
 
+### Human
+
+独立发布 `v0.9.0`，详见 [CHANGELOG-human.md](CHANGELOG-human.md)。
+
+- **Admin CLI**: 命令行工具集（API 客户端、分类器、邮件发送、飞书集成）
+- **飞书集成**: 邮件读取/发送循环、管道看板推送
+
 ### Studio
 
 独立发布 `v0.1.0`，详见 [src/studio/CHANGELOG.md](src/studio/CHANGELOG.md)。
 
 ## [0.0.9] - 2026-05-09
 
+### Human
+
+独立发布 `v0.7.0` — Headcount Planning & Export。
+
+- **人数规划**: 招聘编制规划与跟踪服务
+- **数据导出**: 候选人数据导出端点与生成服务
+
 ### Studio
 
 独立发布 `v0.0.7`，详见 [src/studio/CHANGELOG.md](src/studio/CHANGELOG.md)。
 
 ## [0.0.8] - 2026-05-08
 
+### Human
+
+独立发布 `v0.6.0` — AI 配置与设置页面。
+
+- **AI 配置模型与路由**: 供应商、模型、API 密钥、温度、提示词模板
+- **Flutter 设置页面**: AI 配置表单、服务端地址切换、连接测试
+- **主题系统**: `HrThemeExtension`，8 种状态色彩、间距/字号 token、深色主题
+
 ### Studio
 
 独立发布 `v0.0.6`，详见 [src/studio/CHANGELOG.md](src/studio/CHANGELOG.md)。
 
 ## [0.0.7] - 2026-05-08
 
+### Human
+
+独立发布 `v0.5.0` — 申请中心与邮件往来。
+
+- **Application 模型/路由**: Candidate + Recruitment 关联、人才池、来源追踪
+- **Candidate 模型/路由**: 候选人实体、邮箱唯一约束、更新同步
+- **消息系统**: MailMessage 模型、邮件往来列表、时间线、回复、发件箱、死信队列
+- **素材服务**: 简历附件关联与查询
+- **修正日志**: 字段级人工修正追踪
+- **Flutter 详情面板**: 邮件正文展示、附件预览、分类器信息、修正记录、时间线
+
 ### Added
 
 - `docs/dev/pmd.md`：问题管理文档（业务问题 + 技术问题双维度记录）
@@ -46,6 +79,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0
 
 - `ROADMAP.md`：项目路线规划文档
 
+### Human
+
+独立发布 `v0.4.0` — Flutter 看板（Pipeline + Queue + Pool）。
+
+- **Flutter 看板**: 响应式布局（NavigationRail/NavigationBar）、3 标签导航
+- **管道看板**: 候选人状态分组、停留天数、搜索、拖拽流转、详情面板
+- **队列**: 待处理邮件列表、置信度标签、确认/调整/忽略
+- **人才池**: 候选人池管理、重新入池分配
+- **Flutter 通用组件**: StatusBadge、EmptyState、ErrorView、InfoRow
+
 ### Studio
 
 独立发布 `v0.0.6`，详见 [src/studio/CHANGELOG.md](src/studio/CHANGELOG.md)。
@@ -79,6 +122,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0
 
 ## [0.0.5] - 2026-05-08
 
+### Human
+
+独立发布 `v0.3.0` — 邮件筛选网关。
+
+- **待处理队列**: PendingQueueItem 模型、邮件元数据/AI 提取字段/分类结果
+- **队列路由**: 列表（按邮箱去重）、确认/忽略/调整
+- **邮箱导入路由**: 批量导入、message_id 去重、自动匹配候选人
+- **分类器服务**: 关键词规则分类 + LLM AI 分类（可配置供应商/模型/回退）
+- **邮件匹配服务**: 邮箱规范化、去重检查、候选人匹配
+
 ### Added
 
 - `assets/fixtures/metadata.json`：根注册表（Workspace工作空间清单 + 段定义）
@@ -149,6 +202,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0
 
 ## [0.0.2] - 2026-05-06
 
+### Human
+
+独立发布 `v0.2.0` — FastAPI 人才管道。
+
+- **Talent 状态机**: 8 状态（NEW→CONTACTED→EXAM_SENT→EXAM_RECEIVED→EVALUATING→INTERVIEW→OFFER→CLOSED）
+- **Recruitment 模型/路由**: 招聘项目 CRUD、Talent CRUD、状态流转校验
+- **管道路由**: 按状态聚合的管道视图
+- **种子数据**: DEMO_TALENTS 常量
+
 ### Added
 
 - `src/studio/`: 全景图今日看板（Flutter 实现）
@@ -167,6 +229,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0
 
 ## [0.0.1] - 2026-04-30
 
+### Human
+
+独立发布 `v0.1.0` — 领域模型与筛选引擎。
+
+- **Dart 招聘筛选**: Resume/JobPosition/ScreeningRules 模型、通过/优先/拒绝三态决策
+- **Dart 薪酬计算**: 净薪公式（base + overtime + bonus - deductions）、可配置规则
+- **FastAPI 后端骨架**: SQLAlchemy + SQLite、抽象 get_db 依赖
+
 ### Added
 
 - `src/provider/`: 基于 FastAPI + uv 的空后端项目骨架