Files

T

freedakgmail b93929eb1a feat: UI优化和功能完善

- 添加公共分页组件，支持上边显示、分页大小10
- 侧边栏/Header按Liner风格优化，添加动画效果
- 异常处理列表支持分页和明细弹窗
- 任务结果页面支持已匹配列表分页
- 修复Dialog弹窗背景透明问题
- 新增dropdown-menu组件
- 添加parsed_file_record模型和回填脚本
- 前端枚举中文化

2026-07-07 12:57:15 +08:00

89 KiB

Raw Permalink Blame History

财务 AI 助手开发任务文档（第一模块：薪酬财务对账 MVP）

项目编号: S2F
关联文档: pmdocs/0-req-S2F.md, pmdocs/1-prd-S2F.md
文档版本: v2.0
创建日期: 2026-07-06
最后更新: 2026-07-07
状态: 开发中，核心功能模块已完成

任务范围说明：

本任务文档详细拆解第一阶段“薪酬财务对账 MVP”（第一模块，薪财通 AI）
本任务文档不直接实现发票报销、预算执行、现金流异常、往来对账和经营分析
后续财务 AI 助手模块以“后续任务池”形式记录，待第一模块验证后再拆成正式开发任务

项目初始化任务
后端基础设施任务
前端基础设施任务
认证与权限任务
文件上传与解析任务
AI 字段识别任务
对账与异常检测任务
人工成本分析任务
凭证生成任务
UI 组件开发任务
页面开发任务
测试任务
部署任务
文档任务
任务总结
后续财务 AI 助手模块任务池
下一步行动

1. 项目初始化任务

TASK-001: 创建项目目录结构

目标: 创建前后端项目目录和基础配置文件

关联需求: REQ-001 ~ REQ-005
优先级: P0 (最高)
阶段: 初始化
依赖: 无
预计工时: 2 小时

任务内容:

创建项目根目录结构

s2f/
├── frontend/
├── backend/
├── pmdocs/
├── .gitignore
├── docker-compose.yml
├── README.md
└── run.md

创建 .gitignore 文件
- 排除 node_modules/, venv/, .env, *.pyc, .next/, uploads/
创建根目录 README.md
- 项目简介
- 技术栈
- 快速开始指引
- 指向 run.md 和 pmdocs/
初始化 Git 仓库
- git init（已完成）
- 首次提交：git add . && git commit -m "chore: 项目初始化"（待用户明确授权）

验收标准:

目录结构完整
.gitignore 正确排除敏感文件
README.md 清晰易读
Git 仓库初始化成功

测试方式:

# 验证目录结构
ls -la

# 验证 Git 状态
git status

TASK-002: 初始化后端项目

目标: 创建 FastAPI 项目基础结构和依赖配置

关联需求: REQ-001 ~ REQ-005, NFR-018, NFR-019
优先级: P0
阶段: 初始化
依赖: TASK-001
预计工时: 3 小时

任务内容:

创建后端目录结构

backend/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── api/
│   ├── core/
│   ├── models/
│   ├── schemas/
│   ├── services/
│   └── utils/
├── migrations/
├── tests/
├── requirements.txt
├── .env.example
└── pyproject.toml

创建 requirements.txt

fastapi==0.110.0
uvicorn[standard]==0.27.0
pydantic==2.6.0
pydantic-settings==2.1.0
sqlalchemy==2.0.25
asyncpg==0.29.0
alembic==1.13.0
python-jose[cryptography]==3.3.0
passlib[bcrypt]==1.7.4
python-multipart==0.0.6
openpyxl==3.1.2
pandas==2.2.0
openai==1.10.0
python-dotenv==1.0.0
structlog==24.1.0
pytest==7.4.4
pytest-asyncio==0.23.4
httpx==0.26.0

创建 pyproject.toml (Poetry 配置)
创建 .env.example 模板

创建 Python 虚拟环境

cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

本机实际 Python 版本：3.12.13，满足 Python 3.11+ 约束

验收标准:

目录结构完整
依赖安装成功
虚拟环境激活正常
可以 import fastapi 无报错

测试方式:

cd backend
source venv/bin/activate
python -c "import fastapi; print(fastapi.__version__)"

TASK-003: 初始化前端项目

目标: 创建 Next.js 项目和基础配置

关联需求: REQ-001 ~ REQ-005, NFR-013, NFR-018
优先级: P0
阶段: 初始化
依赖: TASK-001
预计工时: 3 小时

任务内容:

使用 create-next-app 创建项目

npx create-next-app@latest frontend --typescript --tailwind --app --no-src

安装核心依赖

cd frontend
npm install axios react-hook-form zod @hookform/resolvers
npm install zustand react-dropzone lucide-react
npm install recharts date-fns
npm install -D @types/node

安装 Shadcn/ui
```
npx shadcn-ui@latest init
```
配置 tsconfig.json
- 启用严格模式
- 配置路径别名 @/*

配置 .env.local.example

NEXT_PUBLIC_API_URL=http://localhost:8000

创建基础目录结构

frontend/
├── app/
├── components/
├── lib/
├── hooks/
├── types/
└── styles/

验收标准:

Next.js 项目创建成功
依赖安装完整
TypeScript 配置正确
Tailwind CSS 工作正常
可以启动开发服务器

测试方式:

cd frontend
npm run dev
# 访问 http://localhost:3000 查看默认页面

TASK-004: 配置数据库

目标: 安装 PostgreSQL 并创建开发数据库

关联需求: NFR-006, NFR-007, NFR-008
优先级: P0
阶段: 初始化
依赖: TASK-002
预计工时: 1 小时

任务内容:

安装 PostgreSQL 15+

# macOS
brew install postgresql@15
brew services start postgresql@15

创建数据库和用户

psql postgres
CREATE DATABASE s2f_db;
CREATE USER s2f_user WITH PASSWORD 's2f_password';
GRANT ALL PRIVILEGES ON DATABASE s2f_db TO s2f_user;
\q

配置后端 .env 文件

cd backend
cp .env.example .env
# 编辑 DATABASE_URL

测试数据库连接

说明：本机检测到已有 PostgreSQL 16.9 (Postgres.app) 运行，直接复用。数据库和用户创建成功，连接测试通过。

验收标准:

PostgreSQL 服务运行正常
数据库 s2f_db 创建成功
用户 s2f_user 有正确权限
后端可以连接数据库

测试方式:

# 测试连接
psql -U s2f_user -d s2f_db -c "SELECT version();"

TASK-005: 配置 Docker Compose

目标: 创建容器化开发环境配置

关联需求: NFR-019
优先级: P1
阶段: 初始化
依赖: TASK-002, TASK-003, TASK-004
预计工时: 2 小时

任务内容:

创建 docker-compose.yml
- postgres: PostgreSQL 15-alpine
- backend: FastAPI + uvicorn --reload
- frontend: Next.js dev server
- 配置 healthcheck 和服务依赖
创建 backend/Dockerfile
- 基于 python:3.12-slim
- 安装系统依赖和 Python 包
创建 frontend/Dockerfile
- 基于 node:20-alpine
- npm ci 安装依赖
创建 .dockerignore 文件
- backend/.dockerignore
- frontend/.dockerignore

验收标准:

docker-compose up 可以启动所有服务
前端可访问 http://localhost:3000
后端可访问 http://localhost:8000/docs
数据库可连接

说明：配置文件已创建并通过语法验证。完整构建测试因耗时较长暂缓，后续按需执行。

测试方式:

docker-compose up -d
docker-compose ps
curl http://localhost:8000/api/health

本章节完成进度: TASK-001 ~ TASK-005 (5个任务)
下一章节: 后端基础设施任务

2. 后端基础设施任务

TASK-006: 实现后端核心配置

目标: 创建 FastAPI 应用配置、环境变量管理和 CORS 设置

关联需求: NFR-005, NFR-013
优先级: P0
阶段: 基础设施
依赖: TASK-002
预计工时: 2 小时
实际工时: 0.5 小时
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 backend/app/core/config.py
- 使用 pydantic-settings 管理环境变量
- 定义 Settings 类：APP_NAME, VERSION, DEBUG, SECRET_KEY, DATABASE_URL, JWT_SECRET_KEY, ALLOWED_ORIGINS 等
- 实现 get_settings() 函数
创建 backend/app/main.py
- 初始化 FastAPI 应用
- 配置 CORS 中间件
- 添加健康检查端点 /api/health
- 配置 Swagger UI
创建 backend/app/core/logging.py
- 配置 structlog
- 定义日志格式和级别

验收标准:

环境变量正确加载
CORS 配置生效
/api/health 返回 200
Swagger UI 可访问 /docs

测试结果:

✓ 配置加载成功
✓ API 健康检查正常
✓ CORS 中间件已注册
✓ 异常处理器已注册

TASK-007: 实现数据库连接与会话管理

目标: 配置 SQLAlchemy 异步引擎和会话工厂

关联需求: NFR-006, NFR-016
优先级: P0
阶段: 基础设施
依赖: TASK-004, TASK-006
预计工时: 2 小时
实际工时: 1 小时
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 backend/app/core/database.py
- 使用 create_async_engine 创建数据库引擎
- 配置连接池：pool_size=5, max_overflow=10
- 创建 async_session_maker
- 实现 get_db() 依赖注入函数
创建 backend/app/models/base.py
- 定义 Base = declarative_base()
- 定义基础模型字段：id, created_at, updated_at
配置 Alembic
- 初始化 Alembic：alembic init migrations
- 配置 alembic.ini 和 env.py
- 支持异步迁移

验收标准:

数据库连接成功
会话管理正常
Alembic 初始化完成
可以创建首个迁移

测试方式:


**测试结果**:

✓ 数据库连接成功 ✓ 异步引擎工作正常 ✓ Alembic 迁移完成 ✓ 首个迁移已创建: f6e668e45bff

cd backend
alembic revision --autogenerate -m "init"
alembic upgrade head

TASK-008: 实现多租户数据隔离

目标: 创建企业（Company）模型和租户隔离机制

关联需求: NFR-007
优先级: P0
阶段: 基础设施
依赖: TASK-007
预计工时: 3 小时
实际工时: 1.5 小时
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 backend/app/models/company.py
- 字段：id, name, plan (免费版/基础版/专业版/企业版), data_retention_months, status, created_at
创建 backend/app/schemas/company.py
- CompanyCreate, CompanyUpdate, CompanyResponse
创建 backend/app/services/company.py
- create_company(), get_company(), update_company()
创建租户中间件 backend/app/core/tenant.py
- 从请求头或 JWT 中获取 company_id
- 所有数据库查询自动过滤 company_id
- 实现 get_current_company() 依赖

验收标准:

Company 模型创建成功
租户隔离机制生效
不同企业数据互相不可见
数据库迁移成功

测试方式:


**测试结果**:

✓ Company 模型创建成功 ✓ 租户中间件实现完成 ✓ Schema 和 Service 正常工作

# 创建两个企业，验证数据隔离
company1 = await company_service.create_company(...)
company2 = await company_service.create_company(...)
# 验证 company1 无法访问 company2 的数据

TASK-009: 实现异常处理与错误响应

目标: 统一异常处理和错误响应格式

关联需求: NFR-011
优先级: P1
阶段: 基础设施
依赖: TASK-006
预计工时: 2 小时
实际工时: 1 小时
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 backend/app/core/exceptions.py
- 定义自定义异常类：S2FException, NotFoundException, UnauthorizedException, ForbiddenException, ValidationException
- 定义 HTTP 状态码映射
创建 backend/app/core/error_handlers.py
- 实现全局异常处理器
- 返回统一 JSON 格式：{"error": {"code": "...", "message": "...", "details": ...}}
在 main.py 中注册异常处理器

验收标准:

异常被正确捕获
错误响应格式统一
4xx/5xx 错误有明确提示
日志正确记录异常堆栈

测试方式:


**测试结果**:

✓ 异常处理类定义完成 ✓ 错误处理器注册成功 ✓ 统一错误响应格式生效

# 触发异常，验证响应格式
raise NotFoundException("Company not found")
# 预期返回: {"error": {"code": "NOT_FOUND", "message": "Company not found"}}

TASK-010: 实现审计日志基础设施

目标: 创建审计日志模型和记录机制

关联需求: NFR-008
优先级: P1
阶段: 基础设施
依赖: TASK-007, TASK-008
预计工时: 3 小时
实际工时: 1.5 小时
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 backend/app/models/audit_log.py
- 字段：id, company_id, user_id, action (CREATE/UPDATE/DELETE/VIEW/EXPORT), resource_type, resource_id, details (JSON), ip_address, user_agent, created_at
创建 backend/app/services/audit.py
- log_action() 函数
- 自动记录关键操作
创建审计日志装饰器 @audit_log(action="...", resource_type="...")
在关键 API 端点添加审计日志

验收标准:

审计日志模型创建成功
关键操作被记录
日志包含必要字段
可以按用户/时间查询日志

测试方式:


**测试结果**:

✓ AuditLog 模型创建成功 ✓ AuditService 实现完成 ✓ 审计日志装饰器ready

# 执行操作后查询审计日志
logs = await audit_service.get_logs(company_id=1, user_id=1)
assert len(logs) > 0
assert logs[0].action == "CREATE"

本章节完成进度: TASK-006 ~ TASK-010 (5个任务)
下一章节: 前端基础设施任务

3. 前端基础设施任务

TASK-011: 实现 API 客户端封装

目标: 创建统一的 HTTP 客户端和 API 调用封装

关联需求: REQ-001 ~ REQ-005
优先级: P0
阶段: 基础设施
依赖: TASK-003, TASK-006
预计工时: 2 小时
实际工时: 1 小时
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 frontend/lib/api/client.ts
- 使用 Axios 创建实例
- 配置 baseURL、timeout、headers
- 实现请求拦截器：自动添加 JWT token
- 实现响应拦截器：统一错误处理
创建 frontend/lib/api/types.ts
- 定义通用类型：ApiResponse<T>, ApiError, PaginatedResponse<T>
创建 frontend/lib/api/endpoints.ts
- 定义 API 端点常量
- 示例：ENDPOINTS.AUTH.LOGIN, ENDPOINTS.COMPANY.LIST

验收标准:

API 客户端初始化成功
拦截器正常工作
错误统一处理
TypeScript 类型完整

测试方式:


**测试结果**:

✓ API 客户端封装完成 ✓ TypeScript 类型定义完整 ✓ 端点常量配置完成

// 测试健康检查
const response = await apiClient.get('/api/health');
console.log(response.data);

TASK-012: 实现全局状态管理

目标: 使用 Zustand 创建全局状态 Store

关联需求: REQ-001 ~ REQ-005
优先级: P0
阶段: 基础设施
依赖: TASK-003
预计工时: 2 小时
实际工时: 1 小时
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 frontend/lib/stores/auth-store.ts
- 状态：user, token, isAuthenticated
- 方法：login(), logout(), setUser()
创建 frontend/lib/stores/company-store.ts
- 状态：currentCompany, companies
- 方法：setCompany(), loadCompanies()
创建 frontend/lib/stores/ui-store.ts
- 状态：sidebarOpen, theme, loading
- 方法：toggleSidebar(), setLoading()
配置 Zustand 持久化（localStorage）

验收标准:

Store 创建成功
状态可正常读写
持久化正常工作
TypeScript 类型安全

测试方式:


**测试结果**:

✓ auth-store 创建完成 ✓ company-store 创建完成 ✓ ui-store 创建完成 ✓ Zustand 持久化配置正确

const { user, login } = useAuthStore();
await login({ email, password });
console.log(useAuthStore.getState().user);

TASK-013: 实现路由守卫与权限控制

目标: 创建受保护路由和权限检查机制

关联需求: NFR-007
优先级: P0
阶段: 基础设施
依赖: TASK-011, TASK-012
预计工时: 3 小时
实际工时: 1.5 小时
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 frontend/components/auth/ProtectedRoute.tsx
- 检查用户登录状态
- 未登录重定向到登录页
创建 frontend/components/auth/PermissionGate.tsx
- 按权限码控制组件显示
- 支持 permission 和 role 两种模式
创建 frontend/lib/hooks/usePermission.ts
- 检查用户是否有指定权限
- hasPermission(permission: string): boolean
在 App Router 中实现中间件
- frontend/middleware.ts
- 检查路由访问权限

验收标准:

未登录用户无法访问受保护页面
权限检查正常工作
无权限时显示友好提示
路由守卫覆盖所有需要保护的路由

测试方式:


**测试结果**:

✓ ProtectedRoute 组件完成 ✓ PermissionGate 组件完成 ✓ usePermission Hook 完成 ✓ Next.js middleware 配置完成

// 未登录访问受保护路由
router.push('/dashboard');
// 预期重定向到 /login

TASK-014: 实现主题与样式系统

目标: 配置 Tailwind CSS 和 Shadcn/ui 主题

关联需求: NFR-010
优先级: P1
阶段: 基础设施
依赖: TASK-003
预计工时: 2 小时
实际工时: 1 小时
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

配置 tailwind.config.ts
- 定义主题色：primary, secondary, accent, success, warning, error
- 定义字体：Inter, Noto Sans SC
- 配置深色模式支持
创建 frontend/styles/globals.css
- 定义 CSS 变量
- 定义全局样式重置
创建 frontend/components/theme-provider.tsx
- 使用 next-themes 实现主题切换

安装并配置 Shadcn/ui 组件

npx shadcn-ui@latest add button card input label
npx shadcn-ui@latest add dialog dropdown-menu tabs
npx shadcn-ui@latest add table badge alert

验收标准:

Tailwind 配置生效
主题色正确应用
Shadcn/ui 组件可用
深色模式切换正常

测试方式:


**测试结果**:

✓ Tailwind 配置完成 ✓ 主题色定义完成 ✓ ThemeProvider 创建完成 ✓ 深色模式支持完成

import { Button } from '@/components/ui/button';
<Button variant="primary">测试按钮</Button>

TASK-015: 实现通用 Hooks

目标: 创建常用自定义 React Hooks

关联需求: REQ-001 ~ REQ-005
优先级: P1
阶段: 基础设施
依赖: TASK-011, TASK-012
预计工时: 2 小时
实际工时: 1 小时
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 frontend/lib/hooks/useAsync.ts
- 异步请求状态管理
- 返回：{ data, loading, error, execute }
创建 frontend/lib/hooks/useToast.ts
- 全局 Toast 通知
- 支持 success/error/info/warning 类型
创建 frontend/lib/hooks/useConfirm.ts
- 确认对话框 Hook
- 返回：{ confirm, ConfirmDialog }
创建 frontend/lib/hooks/useDebounce.ts
- 防抖 Hook
- 用于搜索输入等场景

验收标准:

所有 Hooks 正常工作
TypeScript 类型完整
有使用示例
无内存泄漏

测试方式:


**测试结果**:

✓ useAsync Hook 完成 ✓ useToast Hook 完成 ✓ useConfirm Hook 完成 ✓ useDebounce Hook 完成

const { data, loading, execute } = useAsync(fetchData);
await execute();
console.log(data);

本章节完成进度: TASK-011 ~ TASK-015 (5个任务)
下一章节: 认证与权限任务

4. 认证与权限任务

TASK-016: 实现用户模型与认证后端

目标: 创建用户模型、JWT 认证和密码加密

关联需求: NFR-007, PRD-FUNC-001
优先级: P0
阶段: 核心功能
依赖: TASK-007, TASK-008
预计工时: 4 小时
实际工时: 1 小时
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 backend/app/models/user.py
- 字段：id, company_id, email, hashed_password, full_name, role (ADMIN/FINANCE_MANAGER/ACCOUNTANT/CASHIER/HR), permissions (JSONB), status, last_login_at, created_at
- 外键关联 Company
创建 backend/app/core/security.py
- hash_password(password: str) -> str
- verify_password(plain: str, hashed: str) -> bool
- create_access_token(data: dict) -> str
- decode_access_token(token: str) -> dict
创建 backend/app/schemas/user.py
- UserCreate, UserLogin, UserResponse, Token
创建 backend/app/services/auth.py
- register_user(), authenticate_user(), get_current_user()

验收标准:

用户模型创建成功
密码加密/验证正常
JWT 生成/解析正常
数据库迁移成功

测试方式:

# 测试密码加密
hashed = hash_password("test123")
assert verify_password("test123", hashed) == True

# 测试 JWT
token = create_access_token({"sub": user_id})
payload = decode_access_token(token)
assert payload["sub"] == user_id

TASK-017: 实现认证 API 端点

目标: 创建登录、注册、登出 API

关联需求: NFR-007, PRD-FUNC-001
优先级: P0
阶段: 核心功能
依赖: TASK-016
预计工时: 3 小时
实际工时: 0.5 小时
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 backend/app/api/auth.py
- POST /api/auth/login - 用户登录
  - 输入：email, password
  - 输出：access_token, user
- POST /api/auth/logout - 用户登出
- GET /api/auth/me - 获取当前用户信息
- POST /api/auth/refresh - 刷新 Token
实现依赖注入 get_current_user(token: str = Depends(oauth2_scheme))
添加速率限制（防暴力破解）
记录登录审计日志

验收标准:

登录 API 返回正确 Token
Token 验证正常
错误提示友好（邮箱不存在、密码错误）
审计日志记录登录行为

测试方式:

# 测试登录
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "admin123"}'

# 测试获取当前用户
curl http://localhost:8000/api/auth/me \
  -H "Authorization: Bearer <token>"

TASK-018: 实现权限检查中间件

目标: 创建权限验证装饰器和依赖

关联需求: NFR-007, PRD-FUNC-001
优先级: P0
阶段: 核心功能
依赖: TASK-016, TASK-017
预计工时: 2 小时
实际工时: 0.5 小时
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 backend/app/core/permissions.py
- 定义权限常量（如 PRD 第7章）
- 实现 require_permission(permission: str) 装饰器
- 实现 require_role(role: str) 装饰器
创建权限检查依赖
- check_permission(user: User, permission: str) -> bool
- PermissionChecker 类
在关键 API 端点添加权限检查
- 示例：@require_permission(PERM_TASK_CREATE)

验收标准:

权限检查正常工作
无权限返回 403 错误
错误消息清晰
不影响已有 API 性能

测试方式:

# 测试权限检查
@require_permission("PERM_TASK_CREATE")
async def create_task():
    pass

# 无权限用户调用应返回 403

TASK-019: 实现前端登录页面

目标: 创建登录页面和登录流程

关联需求: NFR-007, PRD-FUNC-001
优先级: P0
阶段: 核心功能
依赖: TASK-011, TASK-012, TASK-017
预计工时: 3 小时
实际工时: 待前端实现
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 frontend/app/(auth)/login/page.tsx
- 邮箱/密码输入框
- 记住我选项
- 登录按钮
- 错误提示
使用 React Hook Form + Zod 验证
- 邮箱格式验证
- 密码非空验证
集成 API 调用
- 调用 /api/auth/login
- 成功后保存 Token 到 Store
- 重定向到工作台
添加加载状态和错误处理

验收标准:

登录页面样式美观
表单验证正常
登录成功跳转正确
错误提示友好

测试方式:

1. 访问 /login
2. 输入错误密码，验证错误提示
3. 输入正确密码，验证跳转到 /dashboard

TASK-020: 实现用户管理页面

目标: 创建用户列表、添加、编辑、角色管理页面

关联需求: PRD-FUNC-001, PRD-FUNC-013
优先级: P1
阶段: 核心功能
依赖: TASK-016, TASK-017, TASK-019
预计工时: 4 小时
实际工时: 待前端实现
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建后端 API backend/app/api/users.py
- GET /api/users - 用户列表（分页）
- POST /api/users - 创建用户
- PUT /api/users/{id} - 更新用户
- DELETE /api/users/{id} - 删除用户（软删除）
- PUT /api/users/{id}/role - 修改角色
创建前端页面 frontend/app/(dashboard)/settings/users/page.tsx
- 用户列表表格
- 添加/编辑对话框
- 角色下拉选择
- 权限分配界面
权限控制：仅财务主管可访问

验收标准:

用户 CRUD 正常工作
角色修改生效
权限控制正确
审计日志记录操作

测试方式:

1. 以财务主管登录
2. 进入用户管理页面
3. 添加新用户，验证成功
4. 修改用户角色，验证生效
5. 以普通会计登录，验证无法访问

本章节完成进度: TASK-016 ~ TASK-020 (5个任务)
下一章节: 文件上传与解析任务

5. 文件上传与解析任务

TASK-021: 实现文件上传后端

目标: 创建文件上传 API 和存储管理

关联需求: REQ-001, PRD-FUNC-003
优先级: P0
阶段: 核心功能
依赖: TASK-016, TASK-008
预计工时: 3 小时
实际工时: 1 小时
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 backend/app/models/uploaded_file.py
- 字段：id, company_id, task_id, file_type (SALARY/SOCIAL_SECURITY/TAX), original_filename, stored_filename, file_size, mime_type, parse_status (PENDING/PARSING/SUCCESS/FAILED), parse_error, created_at
创建 backend/app/services/file_storage.py
- save_file(file: UploadFile, company_id: int) -> str
- get_file_path(stored_filename: str) -> str
- delete_file(stored_filename: str) -> bool
- 文件命名：{company_id}/{uuid}_{original_name}
创建 backend/app/api/files.py
- POST /api/files/upload - 上传文件
  - 支持 multipart/form-data
  - 验证文件类型（xls/xlsx/csv）
  - 验证文件大小（< 10MB）
  - 返回文件 ID 和预览 URL
- GET /api/files/{id} - 获取文件信息
- DELETE /api/files/{id} - 删除文件

验收标准:

文件上传成功
文件大小/类型验证生效
文件存储路径正确
多租户文件隔离

测试方式:

curl -X POST http://localhost:8000/api/files/upload \
  -H "Authorization: Bearer <token>" \
  -F "file=@test.xlsx" \
  -F "file_type=SALARY"

TASK-022: 实现 Excel 文件解析

目标: 解析 Excel 文件并提取表头和样例数据

关联需求: REQ-001, REQ-002, PRD-FUNC-003
优先级: P0
阶段: 核心功能
依赖: TASK-021
预计工时: 4 小时
实际工时: 1 小时
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 backend/app/services/file_parser.py
- parse_excel(file_path: str) -> dict
  - 使用 openpyxl 解析 .xlsx
  - 使用 xlrd 解析 .xls
  - 返回：表头、前5行样例数据、总行数
- parse_csv(file_path: str) -> dict
  - 自动检测编码（UTF-8/GBK）
  - 自动检测分隔符（逗号/制表符）
- detect_file_type(file_content: bytes) -> str
创建 backend/app/schemas/file_parse.py
- ParsedData 模型
- headers: List[str]
- sample_rows: List[Dict[str, Any]]
- total_rows: int
异步任务：上传后自动触发解析
- 更新 parse_status
- 保存解析结果到数据库

验收标准:

.xlsx / .xls / .csv 文件解析成功
表头提取正确
样例数据完整
处理空值、特殊字符

测试方式:

parsed = await file_parser.parse_excel("test.xlsx")
assert len(parsed["headers"]) > 0
assert len(parsed["sample_rows"]) <= 5

TASK-023: 实现文件上传前端组件

目标: 创建拖拽上传组件和文件预览

关联需求: REQ-001, PRD-FUNC-003, NFR-010
优先级: P0
阶段: 核心功能
依赖: TASK-021, TASK-022, TASK-015
预计工时: 4 小时
实际工时: 待前端实现
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 frontend/components/upload/FileDropzone.tsx
- 使用 react-dropzone
- 支持拖拽和点击上传
- 文件类型限制（.xls, .xlsx, .csv）
- 文件大小限制（10MB）
- 显示上传进度
- 显示文件列表
创建 frontend/components/upload/FilePreview.tsx
- 显示文件名、大小、类型
- 显示解析状态
- 支持删除文件
创建 frontend/lib/api/files.ts
- uploadFile(file: File, fileType: string) => Promise<UploadedFile>
- getFileInfo(fileId: string) => Promise<UploadedFile>
- deleteFile(fileId: string) => Promise<void>

验收标准:

拖拽上传正常工作
文件类型验证生效
上传进度显示正确
错误提示友好

测试方式:

1. 拖拽 .xlsx 文件到上传区
2. 验证上传进度显示
3. 验证上传成功后文件列表更新
4. 拖拽 .pdf 文件，验证拒绝提示

TASK-024: 实现对账任务模型

目标: 创建对账任务模型和状态机

关联需求: REQ-001 ~ REQ-005, PRD-FUNC-002
优先级: P0
阶段: 核心功能
依赖: TASK-008, TASK-016, TASK-021
预计工时: 3 小时
实际工时: 待实现
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 backend/app/models/reconciliation_task.py
- 字段：id, company_id, created_by, month (YYYY-MM), status (DRAFT/FILE_UPLOADED/PARSING/WAITING_MAPPING_CONFIRM/RECONCILING/WAITING_EXCEPTION_REVIEW/WAITING_VOUCHER_CONFIRM/COMPLETED/FAILED), salary_file_id, social_security_file_id, tax_file_id, progress (JSON), result_summary (JSON), created_at, updated_at, completed_at
创建 backend/app/services/task.py
- create_task(company_id: int, month: str) -> Task
- get_task(task_id: int) -> Task
- update_task_status(task_id: int, status: str) -> Task
- get_tasks_by_month(company_id: int, month: str) -> List[Task]
实现状态机转换验证
- 只允许合法的状态转换
- 记录状态变更日志

验收标准:

对账任务模型创建成功
状态机转换正常
支持按月份查询
数据库迁移成功

测试方式:

task = await task_service.create_task(company_id=1, month="2026-07")
assert task.status == "DRAFT"
await task_service.update_task_status(task.id, "FILE_UPLOADED")
assert task.status == "FILE_UPLOADED"

TASK-025: 实现上传页面

目标: 创建文件上传与识别页面

关联需求: REQ-001, PRD-FUNC-002, PRD-FUNC-003, SCENE-001
优先级: P0
阶段: 核心功能
依赖: TASK-023, TASK-024
预计工时: 4 小时
实际工时: 待实现
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 frontend/app/(dashboard)/tasks/[id]/upload/page.tsx
- 显示三个上传区域：工资表、社保表、个税表
- 每个区域独立的 FileDropzone
- 实时显示解析状态
- 解析成功后显示表头预览
- "下一步"按钮（进入字段确认）
创建任务流程进度条组件
- 显示当前所处阶段
- 高亮已完成阶段
集成 AI 建议区
- 显示"已上传X个文件，还需X个"
- 显示下一步建议

验收标准:

三个上传区域独立工作
解析状态实时更新
表头预览正确显示
流程进度条清晰

测试方式:

1. 创建新任务
2. 上传工资表、社保表、个税表
3. 验证每个文件解析成功
4. 验证可进入下一步

本章节完成进度: TASK-021 ~ TASK-025 (5个任务)
下一章节: AI 字段识别任务

6. AI 字段识别任务

TASK-026: 实现 AI 字段识别服务

目标: 使用 LLM 识别表格字段含义并生成映射建议

关联需求: REQ-002, PRD-FUNC-004
优先级: P0
阶段: 核心功能
依赖: TASK-022
预计工时: 6 小时
实际工时: 待实现
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 backend/app/services/ai/field_recognizer.py
- recognize_fields(headers: List[str], sample_data: List[Dict]) -> List[FieldMapping]
- 构建 Prompt：包含标准字段定义、表头、样例数据
- 调用 OpenAI API（gpt-4-turbo-preview）
- 解析 AI 返回的 JSON 结果
- 返回字段映射建议和置信度
定义标准字段模型 backend/app/models/standard_field.py
- 工资相关：姓名、工号、部门、岗位、基本工资、奖金、补贴、应发工资、实发工资
- 社保相关：社保基数、个人部分、公司部分
- 个税相关：应税收入、已缴个税、税后收入
创建 Prompt 模板库
- 工资表识别 Prompt
- 社保表识别 Prompt
- 个税表识别 Prompt
实现错误重试和降级策略
- 3次重试
- 超时处理
- API 失败时使用规则匹配兜底

验收标准:

AI 识别准确率 > 90%
置信度计算合理
响应时间 < 5 秒
错误重试正常

测试方式:

headers = ["员工姓名", "基本工资", "实际发放"]
sample = [{"员工姓名": "张三", "基本工资": 8000, "实际发放": 7200}]
mappings = await ai_recognizer.recognize_fields(headers, sample)
assert mappings[0].standard_field == "full_name"
assert mappings[0].confidence > 0.9

TASK-027: 实现字段映射模型与服务

目标: 创建字段映射存储和企业规则沉淀

关联需求: REQ-002, PRD-FUNC-009, SCENE-006
优先级: P0
阶段: 核心功能
依赖: TASK-026
预计工时: 3 小时
实际工时: 待实现
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 backend/app/models/field_mapping.py
- 字段：id, company_id, file_id, source_field, standard_field, confidence, confirmed, confirmed_by, confirmed_at, sample_values (JSON)
创建 backend/app/models/company_rule.py
- 字段：id, company_id, rule_type (FIELD_MAPPING/ACCOUNT_MAPPING/DEPARTMENT_MAPPING), match_condition (JSON), target_value, priority, status, created_at
创建 backend/app/services/mapping.py
- save_mappings(file_id: int, mappings: List[FieldMapping])
- get_mappings(file_id: int) -> List[FieldMapping]
- confirm_mapping(mapping_id: int, user_id: int)
- save_as_rule(mapping: FieldMapping) -> CompanyRule
- apply_rules(company_id: int, headers: List[str]) -> List[FieldMapping]

验收标准:

字段映射保存成功
企业规则沉淀正常
规则复用生效
第二次上传自动应用规则

测试方式:

# 第一次确认映射
await mapping_service.confirm_mapping(mapping_id=1, user_id=1)
await mapping_service.save_as_rule(mapping)

# 第二次上传同类文件
new_mappings = await mapping_service.apply_rules(company_id=1, headers)
assert len(new_mappings) > 0
assert new_mappings[0].confidence == 1.0  # 规则命中置信度为1

TASK-028: 实现字段确认页面

目标: 创建字段映射确认界面

关联需求: REQ-002, PRD-FUNC-004, SCENE-002
优先级: P0
阶段: 核心功能
依赖: TASK-026, TASK-027
预计工时: 5 小时

任务内容:

创建 frontend/app/(dashboard)/tasks/[id]/mapping/page.tsx
- 显示三个文件的字段映射表格
- 每行显示：源字段、标准字段、置信度、样例值
- 支持修改标准字段（下拉选择）
- 支持跳过字段
- 批量确认按钮
- 单个修改按钮
创建 frontend/components/mapping/FieldMappingTable.tsx
- 可编辑表格组件
- 置信度徽章（高/中/低）
- 样例值展开查看
- 依据说明（AI 为什么这样判断）
创建 frontend/components/mapping/ConfidenceBadge.tsx
- 根据置信度显示不同颜色
- 0.9: 绿色（高）
- 0.7-0.9: 黄色（中）
- < 0.7: 红色（低）
集成 AI 建议区
- "X个字段需要确认"
- "可直接确认"或"建议检查低置信度字段"

验收标准:

字段映射表格显示正确
修改功能正常
批量/单个确认都可用
置信度可视化清晰

测试方式:

1. 进入字段确认页面
2. 查看AI识别结果
3. 修改一个低置信度字段
4. 批量确认所有字段
5. 验证进入下一步

TASK-029: 实现字段映射 API

目标: 创建字段识别和确认的 API 端点

关联需求: REQ-002, PRD-FUNC-004
优先级: P0
阶段: 核心功能
依赖: TASK-026, TASK-027
预计工时: 3 小时

任务内容:

创建 backend/app/api/mappings.py
- POST /api/tasks/{task_id}/recognize - 触发 AI 字段识别
  - 读取已上传文件的表头和样例数据
  - 调用 AI 识别服务
  - 保存映射建议
  - 返回映射结果
- GET /api/tasks/{task_id}/mappings - 获取字段映射列表
- PUT /api/mappings/{id} - 修改字段映射
- POST /api/mappings/confirm - 批量确认映射
- POST /api/mappings/{id}/save-as-rule - 保存为企业规则
实现异步任务
- 识别可能耗时，使用后台任务
- 更新任务状态为 PARSING / WAITING_MAPPING_CONFIRM
添加审计日志

验收标准:

API 端点正常工作
异步任务执行成功
映射结果正确返回
审计日志记录操作

测试方式:

# 触发识别
curl -X POST http://localhost:8000/api/tasks/1/recognize \
  -H "Authorization: Bearer <token>"

# 获取映射
curl http://localhost:8000/api/tasks/1/mappings \
  -H "Authorization: Bearer <token>"

TASK-030: 实现字段映射规则复用

目标: 实现企业规则自动应用和优先级管理

关联需求: REQ-002, PRD-FUNC-009, SCENE-006
优先级: P1
阶段: 核心功能
依赖: TASK-027, TASK-029
预计工时: 3 小时 实际工时: 待前端实现
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

优化 apply_rules() 函数
- 精确匹配优先（字段名完全相同）
- 模糊匹配次之（包含关键词）
- 历史确认记录作为参考
- 支持规则优先级排序
创建规则管理页面（简化版）
- frontend/app/(dashboard)/settings/rules/page.tsx
- 显示已沉淀的字段映射规则
- 支持启用/禁用规则
- 支持删除规则
实现规则冲突处理
- 多个规则匹配同一字段时，取置信度最高的
- 记录冲突日志供后续优化

验收标准:

规则自动应用生效
第二次上传节省80%确认时间
规则管理页面可用
冲突处理合理

测试方式:

1. 首次上传工资表，手动确认所有字段
2. 第二次上传工资表（相同格式）
3. 验证字段自动映射，置信度为1.0
4. 进入规则管理页面，验证规则已保存

本章节完成进度: TASK-026 ~ TASK-030 (5个任务)
下一章节: 对账与异常检测任务

7. 对账与异常检测任务

TASK-031: 实现数据清洗服务

目标: 清洗和标准化薪酬数据

关联需求: REQ-002, REQ-003
优先级: P0
阶段: 核心功能
依赖: TASK-027, TASK-029
预计工时: 4 小时

任务内容:

创建 backend/app/services/data_cleaner.py
- clean_salary_data(file_id: int, mappings: List[FieldMapping]) -> DataFrame
  - 根据字段映射转换为标准格式
  - 处理空值、异常值
  - 数据类型转换（金额、日期）
  - 去重、去除无效行
- clean_social_security_data(file_id: int, mappings) -> DataFrame
- clean_tax_data(file_id: int, mappings) -> DataFrame
- standardize_employee_name(name: str) -> str - 去除空格、统一格式
- standardize_amount(value: Any) -> Decimal - 金额标准化
创建数据验证规则
- 必填字段检查
- 金额范围检查
- 日期格式检查
- 部门代码有效性检查

验收标准:

数据清洗成功
无效数据被过滤
格式统一标准化
清洗后数据可用于对账

测试方式:

raw_data = pd.read_excel("salary.xlsx")
cleaned = await data_cleaner.clean_salary_data(file_id=1, mappings)
assert cleaned["full_name"].isnull().sum() == 0  # 无空值
assert cleaned["gross_salary"].dtype == Decimal  # 类型正确

TASK-032: 实现异常检测规则引擎

目标: 创建对账规则和异常检测逻辑

关联需求: REQ-003, PRD-FUNC-005, PRD-FUNC-006
优先级: P0
阶段: 核心功能
依赖: TASK-031
预计工时: 6 小时 实际工时: 待前端实现
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 backend/app/services/reconciliation/rules.py
- 定义 MVP 7 类异常检测规则，并预留第二阶段银行实发对账规则（如 PRD §4.1 REQ-003）
- Rule 基类：check(data) -> List[Exception]
- LeftEmployeeWithSalaryRule - 离职员工仍有工资
- NewEmployeeNoSocialSecurityRule - 入职员工未缴社保
- LeftEmployeeWithSocialSecurityRule - 离职员工社保未停
- TaxMismatchRule - 个税与工资不匹配
- SocialSecurityBaseDriftRule - 社保基数异常波动
- FundRatioAnomalyRule - 公积金缴纳比例异常（超出5%-12%或与历史月份差异>2%）
- DepartmentMissingRule - 部门归属为空
- BankAmountMismatchRule - 银行实发与工资表不一致（第二阶段）
创建 backend/app/models/exception_item.py
- 字段：id, task_id, exception_type, severity (HIGH/MEDIUM/LOW), employee_name, employee_id, description, suggested_action, status (PENDING/RESOLVED/IGNORED), resolved_by, resolved_at, created_at
创建 backend/app/services/reconciliation/engine.py
- run_reconciliation(task_id: int) -> ReconciliationResult
- 加载三类数据
- 应用所有规则
- 生成异常清单
- 更新任务状态

验收标准:

MVP 7 类异常检测规则实现，并预留第二阶段银行实发对账规则
异常检测准确
误报率 < 10%
执行时间 < 30秒（200人数据）

测试方式:

# 构造测试数据：已离职员工仍有工资
test_data = create_test_case_left_employee_with_salary()
exceptions = await engine.run_reconciliation(task_id=1)
assert any(e.exception_type == "LEFT_EMPLOYEE_WITH_SALARY" for e in exceptions)

TASK-033: 实现异常处理服务

目标: 创建异常查看、处理、忽略功能

关联需求: REQ-003, PRD-FUNC-006, SCENE-003
优先级: P0
阶段: 核心功能
依赖: TASK-032
预计工时: 3 小时 实际工时: 待前端实现
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 backend/app/services/exception_handler.py
- get_exceptions(task_id: int, filters: dict) -> List[ExceptionItem]
  - 支持按类型、严重程度、员工筛选
  - 支持分页
- resolve_exception(exception_id: int, user_id: int, note: str)
- ignore_exception(exception_id: int, user_id: int, reason: str)
- ignore_exception_type(company_id: int, exception_type: str) - 忽略此类异常
- batch_resolve(exception_ids: List[int], user_id: int)
创建 API backend/app/api/exceptions.py
- GET /api/tasks/{task_id}/exceptions
- PUT /api/exceptions/{id}/resolve
- PUT /api/exceptions/{id}/ignore
- POST /api/exceptions/batch-resolve

验收标准:

异常查询正常
筛选功能生效
处理/忽略状态更新
审计日志记录操作

测试方式:

exceptions = await handler.get_exceptions(task_id=1)
assert len(exceptions) > 0
await handler.resolve_exception(exceptions[0].id, user_id=1, note="已核实")
assert exceptions[0].status == "RESOLVED"

TASK-034: 实现异常清单页面

目标: 创建异常查看和处理界面

关联需求: REQ-003, PRD-FUNC-006, SCENE-003
优先级: P0
阶段: 核心功能
依赖: TASK-032, TASK-033
预计工时: 5 小时 实际工时: 待前端实现
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 frontend/app/(dashboard)/exceptions/page.tsx
- 异常统计卡片：总数、高/中/低严重程度分布
- 异常列表表格
- 筛选器：类型、严重程度、状态、员工搜索
- 批量操作按钮
- 单个处理按钮
创建 frontend/components/exceptions/ExceptionList.tsx
- 展开查看异常详情
- 显示建议处理方式
- 显示关联数据（员工、金额、时间）
- 处理历史记录
创建 frontend/components/exceptions/ExceptionFilters.tsx
- 类型多选
- 严重程度多选
- 状态单选
- 员工搜索
集成 AI 建议区
- "发现X个异常，Y个高优先级"
- "建议优先处理：离职员工社保"

验收标准:

异常列表显示正确
筛选功能正常
批量/单个操作都可用
详情展示完整

测试方式:

1. 进入异常清单页面
2. 验证统计卡片数据正确
3. 筛选"高严重程度"异常
4. 批量标记为"已处理"
5. 验证状态更新

TASK-035: 实现对账结果导出

目标: 导出异常清单和对账报告

关联需求: REQ-003, PRD-FUNC-010
优先级: P1
阶段: 核心功能
依赖: TASK-033
预计工时: 3 小时 实际工时: 待前端实现
完成日期: 2026-07-06
状态: ✅ 已完成

任务内容:

创建 backend/app/services/export_service.py
- export_task_result(task_id: int) -> bytes
  - 生成异常清单 Excel
  - 包含：异常类型、严重程度、员工、描述、建议处理、状态
  - 多个 Sheet：概览、异常列表、异常统计
创建 API backend/app/api/exports.py
- GET /api/tasks/{task_id}/export/exceptions
- GET /api/tasks/{task_id}/export/report
前端下载功能
- 点击导出按钮触发下载
- 显示导出进度
- 文件命名：异常清单_2026-07_公司名.xlsx

验收标准:

Excel 文件生成成功
格式美观易读
包含所有必要信息
下载功能正常

测试方式:

curl -o exceptions.xlsx \
  http://localhost:8000/api/tasks/1/export/exceptions \
  -H "Authorization: Bearer <token>"
# 打开 Excel 验证内容

本章节完成进度: TASK-031 ~ TASK-035 (5个任务)
下一章节: 人工成本分析任务

8. 人工成本分析任务

TASK-036: 实现成本分析计算服务

目标: 计算人工成本总额、部门拆分、环比变化

关联需求: REQ-004, PRD-FUNC-007, SCENE-004
优先级: P0
阶段: 核心功能
依赖: TASK-031
预计工时: 5 小时

任务内容:

创建 backend/app/services/analysis/cost_calculator.py
- calculate_total_cost(task_id: int) -> CostSummary
  - 工资总额 + 社保公司部分 + 公积金公司部分
- calculate_by_department(task_id: int) -> List[DepartmentCost]
  - 按部门汇总人工成本
  - 包含人数、工资、社保、公积金
- calculate_by_expense_type(task_id: int) -> Dict[str, Decimal]
  - 按费用科目拆分：管理费用、销售费用、研发费用
- calculate_month_over_month(task_id: int, prev_task_id: int) -> Comparison
  - 环比变化金额和比例
- analyze_cost_changes(curr_task_id, prev_task_id) -> ChangeAnalysis
  - 新增/离职员工影响
  - 薪资调整影响
  - 奖金/提成影响
创建 backend/app/models/cost_analysis.py
- 字段：id, task_id, total_cost, salary_cost, social_security_cost, fund_cost, department_breakdown (JSON), expense_breakdown (JSON), month_over_month (JSON), created_at

验收标准:

成本计算准确
部门拆分正确
环比变化计算无误
计算速度 < 10秒

测试方式:

summary = await calculator.calculate_total_cost(task_id=1)
assert summary.total_cost > 0
assert summary.salary_cost + summary.social_security_cost > 0

dept_costs = await calculator.calculate_by_department(task_id=1)
assert len(dept_costs) > 0

TASK-037: 实现 AI 成本变化分析

目标: 使用 LLM 生成成本变化原因摘要

关联需求: REQ-004, PRD-FUNC-007
优先级: P1
阶段: 核心功能
依赖: TASK-036
预计工时: 4 小时

任务内容:

创建 backend/app/services/ai/cost_analyzer.py
- analyze_cost_changes(current_data, previous_data, changes) -> str
  - 构建 Prompt：包含成本对比、人员变动、薪资调整
  - 调用 LLM 生成摘要
  - 返回：主要原因、关键数据、建议追问问题
- generate_suggested_questions(analysis: ChangeAnalysis) -> List[str]
  - 基于变化生成可追问的问题
  - 示例："哪个部门成本上涨最多？"
优化 Prompt 模板
- 要求输出简洁、数据准确、逻辑清晰
- 包含金额和比例
- 指出top变化项

验收标准:

AI 摘要清晰易懂
包含关键数据点
响应时间 < 5秒
生成的问题有价值

测试方式:

analysis = await analyzer.analyze_cost_changes(curr_data, prev_data, changes)
assert "成本上涨" in analysis or "成本下降" in analysis
assert any(char.isdigit() for char in analysis)  # 包含数字

TASK-037A: 实现预置问题问答

目标: 创建预置问题列表和基于数据的问答服务

关联需求: REQ-006, PRD-FUNC-002A
优先级: P0
阶段: 核心功能
依赖: TASK-036, TASK-037
预计工时: 4 小时

任务内容:

创建 backend/app/services/ai/qa_service.py
- answer_preset_question(task_id: int, question: str) -> str
  - 根据问题类型加载相关数据
  - 构建上下文 Prompt
  - 调用 LLM 生成答案
  - 返回包含数据点的简洁答案
- get_suggested_questions(task_id: int, context: str) -> List[str]
  - 根据当前任务状态生成合适的预置问题
  - 返回 5-8 个预置问题
定义预置问题模板
- 文件上传阶段："本月还缺哪些文件？"
- 字段确认阶段："哪些字段需要人工确认？"
- 异常处理阶段："哪些异常最严重？"
- 成本分析阶段："为什么本月人工成本上涨？" / "哪些部门变化最大？"
- 凭证生成阶段："现在可以生成金蝶凭证吗？"
创建 API backend/app/api/qa.py
- GET /api/tasks/{task_id}/questions - 获取当前阶段的预置问题
- POST /api/tasks/{task_id}/ask - 回答预置问题
前端集成
- 在 AI 工作台显示预置问题卡片
- 在成本分析页面显示相关问题
- 点击问题后显示答案（含加载状态）

验收标准:

预置问题列表根据任务状态动态生成
答案基于真实数据，包含关键数字
响应时间 < 3 秒
答案简洁易懂（2-3句话）

测试方式:

# 测试获取预置问题
questions = await qa_service.get_suggested_questions(task_id=1, context="cost_analysis")
assert len(questions) >= 5

# 测试回答问题
answer = await qa_service.answer_preset_question(task_id=1, question="为什么本月人工成本上涨？")
assert "成本" in answer
assert any(char.isdigit() for char in answer)  # 包含数字

TASK-038: 实现成本分析API

目标: 创建成本分析查询和导出 API

关联需求: REQ-004, PRD-FUNC-007, PRD-FUNC-010
优先级: P0
阶段: 核心功能
依赖: TASK-036, TASK-037
预计工时: 3 小时

任务内容:

创建 backend/app/api/analysis.py
- GET /api/tasks/{task_id}/analysis/cost - 获取成本分析
  - 返回：总额、部门拆分、费用科目、环比变化、AI摘要
- GET /api/tasks/{task_id}/analysis/comparison - 对比分析
  - 对比当前月与上月
- GET /api/tasks/{task_id}/analysis/export - 导出成本分析Excel
实现缓存机制
- 成本分析结果缓存1小时
- 数据更新后清除缓存
添加审计日志

验收标准:

API 返回完整数据
缓存机制生效
导出功能正常
审计日志完整

测试方式:

curl http://localhost:8000/api/tasks/1/analysis/cost \
  -H "Authorization: Bearer <token>"

TASK-039: 实现成本分析页面

目标: 创建人工成本分析展示页面

关联需求: REQ-004, PRD-FUNC-007, SCENE-004
优先级: P0
阶段: 核心功能
依赖: TASK-036, TASK-037, TASK-038
预计工时: 6 小时

任务内容:

创建 frontend/app/(dashboard)/tasks/[id]/analysis/page.tsx
- 顶部：总成本卡片、环比变化、AI摘要
- 中部：部门成本柱状图、费用科目饼图
- 底部：部门明细表格、可展开查看人员
创建 frontend/components/analysis/CostBreakdownChart.tsx
- 使用 Recharts 绘制柱状图
- 支持切换维度：部门/费用科目
- 支持点击查看明细
创建 frontend/components/analysis/MetricCard.tsx
- 显示指标名称、数值、趋势
- 支持环比变化展示
- 颜色区分涨/跌
创建 frontend/components/analysis/AIInsightCard.tsx
- 显示 AI 生成的成本分析摘要
- 显示建议追问问题
- 展开查看详细依据

验收标准:

页面布局清晰
图表数据准确
交互流畅
AI 摘要易读

测试方式:

1. 进入成本分析页面
2. 验证总成本卡片显示正确
3. 查看部门成本图表
4. 点击部门查看明细
5. 阅读 AI 摘要

TASK-040: 实现成本分析导出

目标: 导出成本分析 Excel 报告

关联需求: REQ-004, PRD-FUNC-010
优先级: P1
阶段: 核心功能
依赖: TASK-036, TASK-038
预计工时: 3 小时

任务内容:

创建 backend/app/services/export/cost_exporter.py
- export_cost_analysis(task_id: int) -> bytes
  - Sheet 1: 成本汇总（总额、环比）
  - Sheet 2: 部门成本明细
  - Sheet 3: 费用科目明细
  - Sheet 4: 人员成本清单
  - 包含图表
- 美化 Excel：标题、颜色、边框
前端下载功能
- 文件命名：人工成本分析_2026-07_公司名.xlsx

验收标准:

Excel 包含所有维度数据
格式美观专业
可直接用于汇报
下载正常

测试方式:

curl -o cost_analysis.xlsx \
  http://localhost:8000/api/tasks/1/analysis/export \
  -H "Authorization: Bearer <token>"
# 打开验证内容完整性

本章节完成进度: TASK-036 ~ TASK-040 (5个任务)
下一章节: 凭证生成任务

9. 凭证生成任务

TASK-041: 实现科目映射与凭证模板

目标: 创建科目映射规则和凭证生成模板

关联需求: REQ-005, PRD-FUNC-008, SCENE-005
优先级: P0
阶段: 核心功能
依赖: TASK-027, TASK-036
预计工时: 5 小时

任务内容:

创建 backend/app/models/account_mapping.py
- 字段：id, company_id, mapping_type (SALARY/SOCIAL_SECURITY/TAX/FUND), department, expense_type (管理费用/销售费用/研发费用), debit_account, credit_account, description_template, priority, status
创建 backend/app/services/voucher/template.py
- VoucherTemplate 类：定义凭证模板结构
- 预置模板：
  - 工资计提凭证模板
  - 工资发放凭证模板
  - 社保凭证模板
  - 公积金凭证模板
  - 个税凭证模板
- apply_template(template: VoucherTemplate, data: dict) -> Voucher
创建默认科目映射
- 管理费用-工资：6602
- 销售费用-工资：6602
- 研发费用-工资：6602
- 应付职工薪酬-工资：2211
- 其他应付款-社保：2241
- 应交税费-个人所得税：2121

验收标准:

科目映射模型创建成功
凭证模板定义完整
支持企业自定义科目
数据库迁移成功

测试方式:

mapping = await account_service.get_mapping(
    company_id=1, 
    mapping_type="SALARY", 
    department="研发部"
)
assert mapping.debit_account == "6602"

TASK-042: 实现凭证生成引擎

目标: 根据薪酬数据和科目映射生成金蝶凭证

关联需求: REQ-005, PRD-FUNC-008
优先级: P0
阶段: 核心功能
依赖: TASK-041
预计工时: 6 小时

任务内容:

创建 backend/app/models/voucher.py
- 字段：id, task_id, voucher_type (SALARY_ACCRUAL/SALARY_PAYMENT/SOCIAL_SECURITY/FUND/TAX), voucher_date, entries (JSON数组), description, total_debit, total_credit, status (DRAFT/CONFIRMED), confirmed_by, created_at
创建 backend/app/services/voucher/generator.py
- generate_vouchers(task_id: int) -> List[Voucher]
  - 读取清洗后的薪酬数据
  - 按部门和费用类型分组
  - 应用科目映射规则
  - 生成凭证分录
  - 验证借贷平衡
- generate_salary_accrual_voucher() - 工资计提
- generate_salary_payment_voucher() - 工资发放
- generate_social_security_voucher() - 社保
- generate_fund_voucher() - 公积金
- generate_tax_voucher() - 个税
- validate_voucher(voucher: Voucher) -> bool - 借贷平衡验证

验收标准:

凭证生成正确
借贷必须平衡
科目映射准确
摘要描述清晰

测试方式:

vouchers = await generator.generate_vouchers(task_id=1)
assert len(vouchers) >= 5  # 至少5类凭证
for voucher in vouchers:
    assert voucher.total_debit == voucher.total_credit  # 借贷平衡

TASK-043: 实现金蝶格式导出

目标: 导出符合金蝶导入规范的 Excel 凭证模板

关联需求: REQ-005, PRD-FUNC-008, PRD-FUNC-010, NFR-015
优先级: P0
阶段: 核心功能
依赖: TASK-042
预计工时: 4 小时

任务内容:

创建 backend/app/services/export/kingdee_exporter.py
- export_to_kingdee(task_id: int, template: str) -> bytes
  - 支持金蝶云星辰格式
  - 支持精斗云格式
  - 支持 K/3 格式
- 字段映射：凭证类别、凭证日期、凭证号、摘要、科目编码、科目名称、借方金额、贷方金额、辅助核算
- Excel 格式要求：
  - 表头行固定
  - 每个凭证之间空一行
  - 金额保留2位小数
  - 日期格式 YYYY-MM-DD
创建模板配置
- 可配置字段顺序
- 可配置辅助核算项
创建 API
- GET /api/tasks/{task_id}/vouchers/export/kingdee?template=cloud

验收标准:

导出格式符合金蝶规范
可成功导入金蝶
支持多个金蝶版本
文件命名规范

测试方式:

curl -o kingdee_vouchers.xlsx \
  "http://localhost:8000/api/tasks/1/vouchers/export/kingdee?template=cloud" \
  -H "Authorization: Bearer <token>"
# 尝试导入金蝶验证

TASK-044: 实现凭证预览与确认页面

目标: 创建凭证查看、编辑、确认界面

关联需求: REQ-005, PRD-FUNC-008, SCENE-005
优先级: P0
阶段: 核心功能
依赖: TASK-042, TASK-043
预计工时: 6 小时

任务内容:

创建 frontend/app/(dashboard)/tasks/[id]/vouchers/page.tsx
- 凭证列表：按类型分组显示
- 每个凭证显示：凭证类型、日期、分录数、借贷总额
- 展开查看分录明细
- 支持编辑科目和金额
- 人工确认按钮（HumanConfirmGate）
- 导出按钮
创建 frontend/components/voucher/VoucherPreviewTable.tsx
- 表格显示：摘要、科目、借方、贷方
- 显示借贷平衡状态
- 支持行内编辑
- 显示科目匹配依据（AI 解释）
创建 frontend/components/voucher/VoucherEditor.tsx
- 修改科目代码
- 修改金额
- 修改摘要
- 实时验证借贷平衡
集成 AI 建议区
- "凭证已生成，请确认后导出"
- "发现X处需要人工确认"

验收标准:

凭证展示清晰
编辑功能正常
借贷平衡验证生效
人工确认流程完整

测试方式:

1. 进入凭证页面
2. 查看工资计提凭证
3. 展开分录明细
4. 修改一个科目代码
5. 验证借贷平衡
6. 确认凭证
7. 导出金蝶模板

TASK-045: 实现科目映射管理页面

目标: 创建企业自定义科目映射配置页面

关联需求: PRD-FUNC-009, PRD-FUNC-013
优先级: P1
阶段: 核心功能
依赖: TASK-041, TASK-042
预计工时: 4 小时

任务内容:

创建后端 API backend/app/api/accounts.py
- GET /api/accounts/mappings - 获取科目映射列表
- POST /api/accounts/mappings - 创建科目映射
- PUT /api/accounts/mappings/{id} - 更新科目映射
- DELETE /api/accounts/mappings/{id} - 删除科目映射
创建前端页面 frontend/app/(dashboard)/settings/accounts/page.tsx
- 科目映射列表表格
- 按映射类型分组
- 添加/编辑对话框
- 支持导入科目表
创建 frontend/components/accounts/AccountMappingForm.tsx
- 映射类型选择
- 部门选择
- 费用类型选择
- 借方科目输入
- 贷方科目输入
- 摘要模板输入

验收标准:

科目映射 CRUD 正常
企业自定义生效
凭证生成使用自定义科目
权限控制：仅财务主管可修改

测试方式:

1. 以财务主管登录
2. 进入科目映射管理
3. 添加自定义科目映射
4. 生成凭证验证使用新科目

本章节完成进度: TASK-041 ~ TASK-045 (5个任务)
下一章节: UI 组件开发任务

10. UI 组件开发任务

TASK-046: 实现基础 UI 组件库

目标: 创建项目通用的基础组件

关联需求: PRD 第9章
优先级: P1
阶段: UI 组件
依赖: TASK-014
预计工时: 4 小时

任务内容:

创建 frontend/components/layout/PageLayout.tsx
创建 frontend/components/layout/PageHeader.tsx
创建 frontend/components/ui/ContentCard.tsx
创建 frontend/components/ui/DataTable.tsx (基于 Shadcn/ui Table)
创建 frontend/components/ui/StatusBadge.tsx
创建 frontend/components/ui/EmptyState.tsx
创建 frontend/components/ui/ErrorState.tsx
更新 pmdocs/ui-components.md 登记组件

验收标准:

所有组件可复用
TypeScript 类型完整
样式统一
文档已登记

TASK-047: 实现组合组件

目标: 创建业务场景组合组件

关联需求: PRD 第9章
优先级: P1
阶段: UI 组件
依赖: TASK-046
预计工时: 4 小时

任务内容:

创建 frontend/components/task/TaskProgressStepper.tsx
创建 frontend/components/filters/MonthSelector.tsx
创建 frontend/components/filters/FilterBar.tsx
创建 frontend/components/metrics/MetricCard.tsx
创建 frontend/components/export/ExportButton.tsx
更新组件登记表

验收标准:

组件在多页面复用
交互体验统一
Props 设计合理

TASK-048: 实现 AI Native 组件

目标: 创建 AI 相关展示和交互组件

关联需求: PRD 第6章, 第8章
优先级: P0
阶段: UI 组件
依赖: TASK-046
预计工时: 5 小时

任务内容:

创建 frontend/components/ai/NextActionCard.tsx - 下一步建议卡片
创建 frontend/components/ai/AIInsightCard.tsx - AI 摘要卡片
创建 frontend/components/ai/ConfidenceBadge.tsx - 置信度徽章
创建 frontend/components/ai/EvidencePanel.tsx - 依据展开面板
创建 frontend/components/ai/HumanConfirmGate.tsx - 人工确认组件
更新组件登记表

验收标准:

AI 组件统一风格
置信度可视化清晰
依据展示完整
人工确认流程友好

TASK-049: 实现 AI 工作台组件

目标: 创建 AI 工作台专用组件

关联需求: PRD-FUNC-002, PRD 第6章
优先级: P0
阶段: UI 组件
依赖: TASK-048
预计工时: 3 小时

任务内容:

创建 frontend/components/dashboard/MonthSummaryCard.tsx
创建 frontend/components/dashboard/QuickActions.tsx
创建 frontend/components/dashboard/RecentResults.tsx
创建 frontend/components/dashboard/AIAssistantPanel.tsx
更新组件登记表

验收标准:

工作台组件完整
信息层次清晰
快速操作便捷

TASK-050: 组件文档与 Storybook

目标: 为组件创建文档和示例

关联需求: PRD 第9章
优先级: P2
阶段: UI 组件
依赖: TASK-046, TASK-047, TASK-048
预计工时: 4 小时

任务内容:

安装 Storybook
```
npx storybook@latest init
```
为基础组件创建 Stories
为组合组件创建 Stories
为 AI 组件创建 Stories
部署 Storybook 文档站点

验收标准:

Storybook 可访问
所有组件有示例
文档清晰易懂

本章节完成进度: TASK-046 ~ TASK-050 (5个任务)
下一章节: 页面开发任务

11. 页面开发任务

TASK-051: 实现 AI 工作台页面

目标: 创建核心工作台页面（首页）

关联需求: PRD-FUNC-002, PRD 第6章
优先级: P0
阶段: 页面开发
依赖: TASK-048, TASK-049
预计工时: 6 小时

任务内容:

创建 frontend/app/(dashboard)/dashboard/page.tsx
- 顶部：本月薪酬对账助手标题和月份选择
- AI 总结区：当前状态、待办事项、下一步建议
- 中部：快速操作按钮（开始新任务、继续未完成任务）
- 底部：最近结果（异常清单、成本分析、凭证）
集成 API 调用
- 获取当前月份任务状态
- 获取待办事项列表
- 获取最近导出记录
实现响应式布局
添加空状态（无任务时的引导）

验收标准:

工作台清晰展示当前状态
AI 建议准确有用
快速操作便捷
空状态引导友好

测试方式:

1. 首次登录查看工作台
2. 验证显示"开始新任务"引导
3. 创建任务后验证显示任务状态
4. 验证下一步建议正确

TASK-052: 实现任务列表页面

目标: 创建历史任务查看页面

关联需求: PRD-FUNC-002
优先级: P1
阶段: 页面开发
依赖: TASK-046, TASK-047
预计工时: 4 小时

任务内容:

创建 frontend/app/(dashboard)/tasks/page.tsx
- 任务列表表格：月份、状态、创建人、创建时间、操作
- 筛选器：月份范围、状态
- 搜索：按创建人搜索
- 分页
- 操作：查看详情、继续处理、删除
创建 API 集成
- 获取任务列表
- 删除任务（软删除）
状态标签可视化

验收标准:

任务列表显示完整
筛选功能正常
分页正常工作
删除需要二次确认

测试方式:

1. 进入任务列表
2. 筛选"已完成"任务
3. 搜索特定创建人
4. 删除一个任务，验证确认流程

TASK-053: 实现导出中心页面

目标: 统一管理所有导出文件

关联需求: PRD-FUNC-010
优先级: P1
阶段: 页面开发
依赖: TASK-046, TASK-047
预计工时: 3 小时

任务内容:

创建 frontend/app/(dashboard)/exports/page.tsx
- 导出文件列表：文件名、类型、大小、创建时间
- 筛选：按文件类型（异常清单/成本分析/凭证）
- 操作：下载、删除
- 显示生成依据（来自哪个任务）
创建 API 集成
- 获取导出记录列表
- 下载文件
- 删除文件

验收标准:

导出文件列表完整
下载功能正常
文件类型图标清晰

测试方式:

1. 进入导出中心
2. 查看已导出文件
3. 下载一个文件验证正确
4. 删除旧文件

TASK-054: 实现企业知识库页面

目标: 展示企业已沉淀的规则

关联需求: PRD-FUNC-009
优先级: P1
阶段: 页面开发
依赖: TASK-027, TASK-041, TASK-046
预计工时: 4 小时

任务内容:

创建 frontend/app/(dashboard)/knowledge/page.tsx
- Tab 切换：字段映射规则、科目映射规则、部门归属规则
- 字段映射 Tab：源字段、标准字段、确认次数、最后使用时间
- 科目映射 Tab：映射类型、部门、科目、状态
- 操作：启用/禁用、删除、导出规则
创建 API 集成
- 获取各类规则列表
- 更新规则状态
- 删除规则

验收标准:

三类规则清晰展示
启用/禁用生效
导出规则可用于备份

测试方式:

1. 进入企业知识库
2. 查看字段映射规则
3. 禁用一个规则
4. 下次上传验证该规则不自动应用

TASK-055: 实现系统设置页面

目标: 创建企业信息和系统配置页面

关联需求: PRD-FUNC-013
优先级: P1
阶段: 页面开发
依赖: TASK-020, TASK-046
预计工时: 4 小时

任务内容:

创建 frontend/app/(dashboard)/settings/page.tsx
- Tab 切换：企业信息、成员管理、数据保留、审计日志
- 企业信息：公司名称、套餐、数据保留策略
- 成员管理：用户列表（复用 TASK-020）
- 数据保留：设置保留月数、手动清理
- 审计日志：查询日志列表
权限控制：仅财务主管可访问

验收标准:

所有设置项可正常修改
审计日志可查询
权限控制生效

测试方式:

1. 以财务主管登录
2. 修改企业信息
3. 查看审计日志
4. 以普通会计登录，验证无法访问

本章节完成进度: TASK-051 ~ TASK-055 (5个任务)
下一章节: 测试任务

12. 测试任务

TASK-056: 实现后端单元测试

目标: 为核心服务编写单元测试

关联需求: NFR-018
优先级: P1
阶段: 测试
依赖: TASK-006 ~ TASK-045
预计工时: 8 小时

任务内容:

配置 pytest 和 pytest-asyncio
创建测试数据库配置
编写认证服务测试 tests/services/test_auth.py
- 测试密码加密/验证
- 测试 JWT 生成/解析
- 测试登录流程
编写文件解析测试 tests/services/test_file_parser.py
编写 AI 识别测试 tests/services/test_field_recognizer.py（Mock LLM API）
编写对账规则测试 tests/services/test_reconciliation_rules.py
编写凭证生成测试 tests/services/test_voucher_generator.py
目标覆盖率 > 80%

验收标准:

所有核心服务有测试
测试覆盖率 > 80%
所有测试通过
CI 可自动运行测试

测试方式:

cd backend
pytest --cov=app --cov-report=html

TASK-057: 实现后端集成测试

目标: 测试 API 端点和数据库交互

关联需求: NFR-018
优先级: P1
阶段: 测试
依赖: TASK-056
预计工时: 6 小时

任务内容:

创建测试客户端 fixture
编写认证 API 测试 tests/api/test_auth.py
- 测试登录成功/失败
- 测试 Token 验证
编写文件上传 API 测试 tests/api/test_files.py
编写对账任务 API 测试 tests/api/test_tasks.py
编写完整流程集成测试
- 创建任务 → 上传文件 → 识别字段 → 对账 → 生成凭证
测试权限控制
测试多租户隔离

验收标准:

所有 API 端点有测试
完整流程测试通过
权限测试覆盖
多租户隔离验证

测试方式:

cd backend
pytest tests/api/ -v

TASK-058: 实现前端单元测试

目标: 为组件和 Hooks 编写测试

关联需求: NFR-018
优先级: P2
阶段: 测试
依赖: TASK-046 ~ TASK-050
预计工时: 6 小时

任务内容:

配置 Jest 和 React Testing Library
编写基础组件测试
- Button、Card、Input、Badge 等
编写业务组件测试
- FileDropzone、FieldMappingTable、VoucherPreviewTable
编写 Hooks 测试
- useAsync、usePermission、useToast
编写 Store 测试
- authStore、companyStore

验收标准:

核心组件有测试
Hooks 测试覆盖
所有测试通过

测试方式:

cd frontend
npm run test

TASK-059: 实现端到端测试

目标: 使用 Playwright 测试完整用户流程

关联需求: NFR-018
优先级: P2
阶段: 测试
依赖: TASK-051 ~ TASK-055
预计工时: 8 小时

任务内容:

安装 Playwright
```
npm init playwright@latest
```
编写登录流程测试 tests/e2e/auth.spec.ts
编写完整对账流程测试 tests/e2e/reconciliation.spec.ts
- 登录 → 创建任务 → 上传文件 → 确认字段 → 查看异常 → 查看成本 → 生成凭证 → 导出
编写权限测试 tests/e2e/permissions.spec.ts
编写响应式测试（不同屏幕尺寸）
配置 CI/CD 自动运行

验收标准:

完整流程 E2E 测试通过
关键路径覆盖
可在 CI 中运行

测试方式:

cd frontend
npx playwright test
npx playwright show-report

TASK-060: 实现性能测试

目标: 验证系统性能指标

关联需求: NFR-001 ~ NFR-004
优先级: P2
阶段: 测试
依赖: TASK-056, TASK-057
预计工时: 4 小时

任务内容:

使用 Locust 编写负载测试脚本
- 并发用户测试（50 并发）
- API 响应时间测试
- 数据库查询性能测试
测试场景：
- 200 人数据处理时间 < 30秒
- AI 识别响应时间 < 5秒
- 凭证生成时间 < 3秒
生成性能报告
识别性能瓶颈并优化

验收标准:

所有性能指标达标
并发支持 50 用户
无明显性能瓶颈

测试方式:

cd backend/tests/load
locust -f locustfile.py --host=http://localhost:8000

本章节完成进度: TASK-056 ~ TASK-060 (5个任务)
下一章节: 部署任务

13. 部署任务

TASK-061: 配置 Docker 镜像

目标: 创建生产环境 Docker 镜像

关联需求: NFR-019
优先级: P0
阶段: 部署
依赖: TASK-002, TASK-003
预计工时: 4 小时

任务内容:

优化 backend/Dockerfile
- 多阶段构建
- 精简镜像大小
- 安全配置（非 root 用户）
优化 frontend/Dockerfile
- 使用 Next.js standalone 输出
- 多阶段构建
- Nginx 或 Node standalone
创建 docker-compose.prod.yml
- 生产环境配置
- 环境变量管理
- 健康检查
- 重启策略
创建 .dockerignore

验收标准:

镜像构建成功
镜像大小合理（< 500MB）
容器启动正常
健康检查生效

测试方式:

docker-compose -f docker-compose.prod.yml build
docker-compose -f docker-compose.prod.yml up -d
docker-compose ps

TASK-062: 配置 Nginx 反向代理

目标: 配置 Nginx 作为前端和 API 网关

关联需求: NFR-019
优先级: P0
阶段: 部署
依赖: TASK-061
预计工时: 3 小时

任务内容:

创建 nginx/nginx.conf
- 前端静态文件服务
- API 反向代理到后端
- Gzip 压缩
- 缓存策略
- 文件上传大小限制
配置 SSL/TLS（开发环境自签名）
配置日志
添加 Nginx 到 docker-compose

验收标准:

Nginx 正常启动
前端可通过 Nginx 访问
API 代理正常工作
Gzip 压缩生效

测试方式:

curl -I http://localhost
curl http://localhost/api/health

TASK-063: 配置环境变量管理

目标: 安全管理生产环境变量

关联需求: NFR-006, NFR-009
优先级: P0
阶段: 部署
依赖: TASK-061
预计工时: 2 小时

任务内容:

创建 .env.production.example
文档化所有环境变量
创建环境变量验证脚本
配置密钥管理方案
- 开发环境：.env 文件
- 生产环境：Docker secrets 或环境变量注入
移除所有硬编码密钥

验收标准:

无硬编码密钥
环境变量文档完整
生产环境可安全配置
验证脚本可用

测试方式:

python scripts/validate_env.py

TASK-064: 配置数据库备份

目标: 实现数据库自动备份机制

关联需求: NFR-006
优先级: P1
阶段: 部署
依赖: TASK-004
预计工时: 3 小时

任务内容:

创建备份脚本 scripts/backup_db.sh
- 使用 pg_dump 备份
- 压缩备份文件
- 保留最近 30 天备份
- 自动清理旧备份
配置 Cron 定时任务
- 每天凌晨 2:00 自动备份
创建恢复脚本 scripts/restore_db.sh
测试备份和恢复流程

验收标准:

备份脚本正常工作
定时任务配置正确
恢复脚本可用
备份文件完整

测试方式:

./scripts/backup_db.sh
ls -lh backups/
./scripts/restore_db.sh backups/latest.sql.gz

TASK-065: 配置监控和日志

目标: 实现系统监控和日志收集

关联需求: NFR-020
优先级: P1
阶段: 部署
依赖: TASK-061
预计工时: 4 小时

任务内容:

配置后端结构化日志
- 使用 structlog
- 输出 JSON 格式
- 日志级别配置
配置前端错误追踪
- 捕获未处理异常
- 记录用户操作路径
配置日志收集（可选）
- Docker 日志驱动
- 或 ELK Stack（Elasticsearch + Logstash + Kibana）
创建健康检查端点
- /api/health/live - 存活检查
- /api/health/ready - 就绪检查
创建监控脚本
- 监控磁盘使用
- 监控数据库连接
- 监控 API 响应时间

验收标准:

日志格式统一
健康检查端点正常
监控脚本可用
日志可查询

测试方式:

curl http://localhost:8000/api/health/live
curl http://localhost:8000/api/health/ready
tail -f backend/logs/app.log

本章节完成进度: TASK-061 ~ TASK-065 (5个任务)
下一章节: 文档任务

14. 文档任务

TASK-066: 完善 API 文档

目标: 完善后端 API 文档

关联需求: NFR-018
优先级: P1
阶段: 文档
依赖: TASK-017 ~ TASK-045
预计工时: 4 小时

任务内容:

优化 FastAPI 自动生成的 Swagger 文档
- 添加 API 描述和示例
- 添加请求/响应示例
- 分组和标签
创建 docs/api/README.md
- API 概览
- 认证说明
- 错误码说明
- 分页说明
添加 Postman Collection
- 导出完整 API 集合
- 包含示例请求

验收标准:

Swagger UI 文档完整
API 说明清晰
Postman Collection 可用

TASK-067: 编写用户使用手册

目标: 为财务人员编写使用指南

关联需求: NFR-012
优先级: P1
阶段: 文档
依赖: TASK-051 ~ TASK-055
预计工时: 6 小时

任务内容:

创建 docs/user-guide/README.md
- 产品介绍
- 快速开始
- 核心功能介绍
创建分步教程
- docs/user-guide/01-login.md - 登录和首次使用
- docs/user-guide/02-upload.md - 上传文件
- docs/user-guide/03-mapping.md - 确认字段映射
- docs/user-guide/04-exceptions.md - 处理异常
- docs/user-guide/05-analysis.md - 查看成本分析
- docs/user-guide/06-vouchers.md - 生成和导出凭证
添加截图和操作动图
创建常见问题 FAQ

验收标准:

用户手册完整清晰
截图准确
FAQ 覆盖常见问题

TASK-068: 编写管理员手册

目标: 为系统管理员编写部署和维护指南

关联需求: NFR-019
优先级: P1
阶段: 文档
依赖: TASK-061 ~ TASK-065
预计工时: 4 小时

任务内容:

创建 docs/admin-guide/README.md
编写部署指南
- docs/admin-guide/deployment.md - Docker 部署
- 环境要求
- 安装步骤
- 配置说明
编写维护指南
- docs/admin-guide/maintenance.md
- 数据库备份恢复
- 日志查看
- 性能优化
- 故障排查
编写安全指南
- docs/admin-guide/security.md
- 密钥管理
- 访问控制
- 数据加密

验收标准:

部署文档可按步骤执行
维护指南实用
安全指南完整

TASK-069: 更新项目 README

目标: 完善项目根目录 README

关联需求: 全局
优先级: P0
阶段: 文档
依赖: TASK-001, TASK-066, TASK-067
预计工时: 2 小时

任务内容:

更新 README.md
- 项目简介：财务 AI 助手，第一模块为薪酬财务对账
- 第一阶段核心功能列表
- 后续财务 AI 助手模块路线
- 技术栈
- 快速开始
- 文档索引
- 贡献指南
- 许可证
添加徽章（Badge）
- 构建状态
- 测试覆盖率
- 版本号
添加截图和 Demo

验收标准:

README 清晰完整
快速开始可用
文档链接正确

TASK-070: 创建发布检查清单

目标: 编写 MVP 发布前检查清单

关联需求: 全局
优先级: P0
阶段: 文档
依赖: 所有任务
预计工时: 2 小时

任务内容:

创建 docs/release-checklist.md
- 功能完整性检查
- 测试通过检查
- 安全检查
- 性能检查
- 文档完整性检查
- 部署准备检查
创建发布流程文档
- 版本命名规范
- 发布步骤
- 回滚计划
创建已知问题文档
- MVP 限制说明
- 计划功能清单

验收标准:

检查清单完整
发布流程清晰
已知问题已记录

本章节完成进度: TASK-066 ~ TASK-070 (5个任务)

15. 任务总结

15.1 任务统计

章节	任务编号	任务数	预计工时
1. 项目初始化	TASK-001 ~ TASK-005	5	11h
2. 后端基础设施	TASK-006 ~ TASK-010	5	12h
3. 前端基础设施	TASK-011 ~ TASK-015	5	11h
4. 认证与权限	TASK-016 ~ TASK-020	5	16h
5. 文件上传与解析	TASK-021 ~ TASK-025	5	18h
6. AI 字段识别	TASK-026 ~ TASK-030	5	20h
7. 对账与异常检测	TASK-031 ~ TASK-035	5	21h
8. 人工成本分析	TASK-036 ~ TASK-037A, TASK-038 ~ TASK-040	6	25h
9. 凭证生成	TASK-041 ~ TASK-045	5	24h
10. UI 组件开发	TASK-046 ~ TASK-050	5	20h
11. 页面开发	TASK-051 ~ TASK-055	5	21h
12. 测试	TASK-056 ~ TASK-060	5	32h
13. 部署	TASK-061 ~ TASK-065	5	16h
14. 文档	TASK-066 ~ TASK-070	5	18h
合计	TASK-001 ~ TASK-070 (含 037A)	71	265h

15.2 关键路径

P0 优先级任务（MVP 必须）共 46 个任务，预计 174 小时

建议开发顺序：

第1周：项目初始化 + 后端基础设施（TASK-001 ~ TASK-010）
第2周：前端基础设施 + 认证与权限（TASK-011 ~ TASK-020）
第3-4周：文件上传 + AI 识别（TASK-021 ~ TASK-030）
第5-6周：对账异常 + 成本分析（TASK-031 ~ TASK-040）
第7-8周：凭证生成 + UI 组件（TASK-041 ~ TASK-050）
第9-10周：页面开发（TASK-051 ~ TASK-055）
第11周：测试 + 部署 + 文档（TASK-056 ~ TASK-070）

15.3 里程碑

M1（第4周）：基础设施完成

前后端项目搭建
认证与权限
文件上传与解析
AI 字段识别

M2（第8周）：核心功能完成

对账与异常检测
人工成本分析
凭证生成
UI 组件库

M3（第11周）：MVP 就绪

所有页面完成
测试通过
部署配置
文档完整

15.4 验收标准

MVP 完成需满足：

所有 P0 任务（46个）完成
功能验收标准达标
测试覆盖率 > 80%
性能指标达标
文档完整
可成功部署

15.5 风险提示

高风险任务：

TASK-026：AI 字段识别（LLM API 稳定性）
TASK-032：异常检测规则（业务复杂度）
TASK-042：凭证生成引擎（财务准确性）
TASK-059：端到端测试（流程覆盖度）

建议应对：

提前准备 LLM API 备选方案
与财务专家深度验证业务规则
增加单元测试和人工验证
分阶段测试，逐步覆盖

16. 后续财务 AI 助手模块任务池

以下任务不进入第一阶段薪酬财务对账 MVP，仅作为后续阶段的任务池。第一模块验证通过后，再根据客户反馈拆成正式 TASK 编号。

16.1 第二阶段：薪酬模块自动化增强

模块	候选任务	说明
历史对比	保存 12 个月历史数据，支持同比/环比	增强薪酬模块复购和留存
自动文件夹监控	本地目录/网盘目录自动扫描	降低上传下载操作成本
完整自然语言问答	支持开放式追问成本、异常、凭证	从预置问题升级为对话式分析
企业通知	企业微信/邮件通知处理完成结果	提升协作效率

16.2 第三阶段：金蝶生态连接

模块	候选任务	说明
金蝶 API 对接	读取科目、辅助核算、推送凭证草稿	仍由金蝶完成正式入账
多账套管理	支持集团企业、代账公司多客户处理	对应外包记账公司用户画像
行业模板库	制造业、服务业、科技企业模板	提升识别准确率和配置效率

16.3 第四阶段：财务 AI 助手扩展

模块	候选任务	边界
发票与报销 AI 助手	发票识别、真伪核验、报销单匹配、费用凭证生成	不做完整报销审批流
预算执行 AI 分析	导入预算表、匹配实际发生、生成差异解释	不做完整预算编制系统
现金流异常 AI 监控	导入银行流水、识别资金属性、输出可动用资金与异常提醒	只读分析，不做支付和调拨
往来对账 AI 助手	客户/供应商往来、发票、回款、付款自动匹配	不替代金蝶应收应付总账
经营分析 AI 看板	费用趋势、经营摘要、老板日报、异常追踪	不做脱离数据来源的展示页

16.4 后续模块拆分原则

先验证第一模块的客户付费和留存，再拆第四阶段正式任务
每个新模块都必须形成“输入 → 识别 → 对账/分析 → 异常 → 凭证/报告”的闭环
不做金蝶已有的正式账套、正式入账、法定财报能力
不做高风险资金动作，只做只读分析、异常提醒和凭证建议

17. 下一步行动

立即开始：

执行 TASK-001：创建项目目录结构
初始化 Git 仓库并完成首次提交
按任务顺序推进 MVP 开发

执行规范：

每完成一个任务，在本文档中勾选 - [x]
更新 pmdocs/2-task-S2F.md
必要时创建 Git 提交
遇到阻塞及时记录到任务备注

文档版本: v2.0
最后更新: 2026-07-07
状态: 开发中，核心功能模块已完成

89 KiB Raw Permalink Blame History Unescape Escape

财务 AI 助手开发任务文档（第一模块：薪酬财务对账 MVP）

目录

1. 项目初始化任务

TASK-001: 创建项目目录结构

TASK-002: 初始化后端项目

TASK-003: 初始化前端项目

TASK-004: 配置数据库

TASK-005: 配置 Docker Compose

2. 后端基础设施任务

TASK-006: 实现后端核心配置

TASK-007: 实现数据库连接与会话管理

TASK-008: 实现多租户数据隔离

TASK-009: 实现异常处理与错误响应

TASK-010: 实现审计日志基础设施

3. 前端基础设施任务

TASK-011: 实现 API 客户端封装

TASK-012: 实现全局状态管理

TASK-013: 实现路由守卫与权限控制

TASK-014: 实现主题与样式系统

TASK-015: 实现通用 Hooks

4. 认证与权限任务

TASK-016: 实现用户模型与认证后端

TASK-017: 实现认证 API 端点

TASK-018: 实现权限检查中间件

TASK-019: 实现前端登录页面

TASK-020: 实现用户管理页面

5. 文件上传与解析任务

TASK-021: 实现文件上传后端

TASK-022: 实现 Excel 文件解析

TASK-023: 实现文件上传前端组件

TASK-024: 实现对账任务模型

TASK-025: 实现上传页面

6. AI 字段识别任务

TASK-026: 实现 AI 字段识别服务

TASK-027: 实现字段映射模型与服务

TASK-028: 实现字段确认页面

TASK-029: 实现字段映射 API

TASK-030: 实现字段映射规则复用

7. 对账与异常检测任务

TASK-031: 实现数据清洗服务

TASK-032: 实现异常检测规则引擎

TASK-033: 实现异常处理服务

TASK-034: 实现异常清单页面

TASK-035: 实现对账结果导出

8. 人工成本分析任务

TASK-036: 实现成本分析计算服务

TASK-037: 实现 AI 成本变化分析

TASK-037A: 实现预置问题问答

TASK-038: 实现成本分析API

TASK-039: 实现成本分析页面

TASK-040: 实现成本分析导出

9. 凭证生成任务

TASK-041: 实现科目映射与凭证模板

TASK-042: 实现凭证生成引擎

TASK-043: 实现金蝶格式导出

TASK-044: 实现凭证预览与确认页面

TASK-045: 实现科目映射管理页面

10. UI 组件开发任务

TASK-046: 实现基础 UI 组件库

TASK-047: 实现组合组件

TASK-048: 实现 AI Native 组件

TASK-049: 实现 AI 工作台组件

TASK-050: 组件文档与 Storybook

11. 页面开发任务

TASK-051: 实现 AI 工作台页面

TASK-052: 实现任务列表页面

TASK-053: 实现导出中心页面

TASK-054: 实现企业知识库页面

TASK-055: 实现系统设置页面

12. 测试任务

TASK-056: 实现后端单元测试

TASK-057: 实现后端集成测试

TASK-058: 实现前端单元测试

TASK-059: 实现端到端测试

TASK-060: 实现性能测试

13. 部署任务

TASK-061: 配置 Docker 镜像

TASK-062: 配置 Nginx 反向代理

TASK-063: 配置环境变量管理

89 KiB

Raw Permalink Blame History