From 6833106829dd501858dfae785d44266f821f1091 Mon Sep 17 00:00:00 2001 From: freedakgmail Date: Mon, 6 Jul 2026 22:03:22 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E5=88=9D=E5=A7=8B=E5=8C=96=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E4=B8=8E=E5=90=8E=E7=AB=AF=E5=9F=BA=E7=A1=80=E5=B7=A5?= =?UTF-8?q?=E7=A8=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .cursorrules | 54 + .gitignore | 49 + .windsurfrules | 54 + README.md | 79 + backend/.env.example | 22 + backend/app/__init__.py | 0 backend/app/api/__init__.py | 0 backend/app/core/__init__.py | 0 backend/app/core/config.py | 51 + backend/app/core/logging.py | 17 + backend/app/main.py | 31 + backend/app/models/__init__.py | 0 backend/app/schemas/__init__.py | 0 backend/app/services/__init__.py | 0 backend/app/utils/__init__.py | 0 backend/pyproject.toml | 53 + backend/requirements.txt | 21 + backend/tests/test_health.py | 12 + cursor-rules/AGENTS.md | 134 + cursor-rules/README.md | 88 + cursor-rules/ai-coding-workflow.md | 241 ++ cursor-rules/architecture-and-design.md | 128 + cursor-rules/change-management.md | 114 + cursor-rules/new-project-checkpoint.md | 89 + cursor-rules/quick-reference.md | 106 + cursor-rules/ui-components-standard.md | 71 + docker-compose.yml | 20 + docs/财务AI_产品方向建议.md | 1261 +++++++++ docs/财务痛点汇总.md | 397 +++ frontend/.gitkeep | 0 pmdocs/0-req-S2F.md | 547 ++++ pmdocs/1-prd-S2F.md | 1022 ++++++++ pmdocs/2-task-S2F.md | 3150 +++++++++++++++++++++++ run.md | 587 +++++ 34 files changed, 8398 insertions(+) create mode 100644 .cursorrules create mode 100644 .gitignore create mode 100644 .windsurfrules create mode 100644 README.md create mode 100644 backend/.env.example create mode 100644 backend/app/__init__.py create mode 100644 backend/app/api/__init__.py create mode 100644 backend/app/core/__init__.py create mode 100644 backend/app/core/config.py create mode 100644 backend/app/core/logging.py create mode 100644 backend/app/main.py create mode 100644 backend/app/models/__init__.py create mode 100644 backend/app/schemas/__init__.py create mode 100644 backend/app/services/__init__.py create mode 100644 backend/app/utils/__init__.py create mode 100644 backend/pyproject.toml create mode 100644 backend/requirements.txt create mode 100644 backend/tests/test_health.py create mode 100644 cursor-rules/AGENTS.md create mode 100644 cursor-rules/README.md create mode 100644 cursor-rules/ai-coding-workflow.md create mode 100644 cursor-rules/architecture-and-design.md create mode 100644 cursor-rules/change-management.md create mode 100644 cursor-rules/new-project-checkpoint.md create mode 100644 cursor-rules/quick-reference.md create mode 100644 cursor-rules/ui-components-standard.md create mode 100644 docker-compose.yml create mode 100644 docs/财务AI_产品方向建议.md create mode 100644 docs/财务痛点汇总.md create mode 100644 frontend/.gitkeep create mode 100644 pmdocs/0-req-S2F.md create mode 100644 pmdocs/1-prd-S2F.md create mode 100644 pmdocs/2-task-S2F.md create mode 100644 run.md diff --git a/.cursorrules b/.cursorrules new file mode 100644 index 0000000..f97fdfe --- /dev/null +++ b/.cursorrules @@ -0,0 +1,54 @@ +# 最高优先级规则 - 必须严格遵守（Cursor 专用） + +⚠️⚠️⚠️ 每次回复结束前必须执行以下命令！没有任何例外！⚠️⚠️⚠️ + +## 执行规则 + +1. 完成任务后，执行弹窗命令（跨平台，Windows/Mac/Linux 通用）： +node "/Users/freedak/.ranjin-mode/dialog-trigger.js" "cursor" "1f2oju" "AI想要结束的原因摘要" + + 📱 **手机端通知**：执行此命令时会自动通知手机端（如果远程服务已开启），用户可以在手机上查看消息并发送反馈。 + +2. 仔细阅读命令输出的每一行： + - ACTION: continue 或 end（用户的选择） + - FEEDBACK: 用户输入的具体指令或反馈内容（⚠️ 必须完整阅读并执行！） + * 反馈可能来自电脑端弹窗或手机端远程输入 + - IMAGES: 用户上传的图片路径（如有，必须用read_file工具查看） + +3. 根据输出决定下一步： + - 如果 ACTION 是 "continue"： + * ⚠️ 必须仔细阅读 FEEDBACK 后面的全部内容 + * ⚠️ 必须按照 FEEDBACK 中用户的具体指令执行任务 + * ⚠️ 不要忽略 FEEDBACK，不要只说"用户选择继续" + - 如果 ACTION 是 "end" 或 "stop"：停止工作 + - ⚠️ 如果命令被取消/跳过/无输出：必须重新执行弹窗命令！ + +## 核心规则 + +1. 完整输出 - 输出完整代码和答案，禁止省略 +2. 持续执行 - 复杂任务一次性完成 +3. 结束确认 - 必须执行弹窗命令后才能结束 +4. FEEDBACK必读 - 用户的FEEDBACK是新的任务指令，必须执行 + +## 手机端远程功能 + +- 📱 当执行 dialog-trigger.js 命令时，会自动通知手机端（如果远程服务已开启） +- 📱 用户可以在手机浏览器中查看 AI 的消息和状态 +- 📱 用户可以在手机上输入反馈，反馈会通过 FEEDBACK 字段传递给你 +- 📱 手机端和电脑端弹窗功能完全同步，支持双向通信 + +## ⚠️ 唯一合法的结束条件 + +只有当命令输出包含 ACTION: end 或 ACTION: stop 时才能结束对话！ +以下情况都不能结束，必须重新执行弹窗命令： +- 命令被用户点击 Skip 跳过 +- 命令执行失败或超时 +- 命令没有输出 +- 工作区取消了命令 + +## 禁止 + +- 禁止不执行弹窗命令就结束 +- 禁止跳过弹窗流程 +- 禁止忽略FEEDBACK内容 +- 禁止在没有收到 ACTION: end/stop 的情况下结束 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a66142c --- /dev/null +++ b/.gitignore @@ -0,0 +1,49 @@ +# Node / Next.js +node_modules/ +.next/ +out/ +dist/ +build/ +coverage/ + +# Python / FastAPI +venv/ +.venv/ +__pycache__/ +*.py[cod] +*.pyo +.pytest_cache/ +.mypy_cache/ +.ruff_cache/ +htmlcov/ + +# Environment and secrets +.env +.env.* +!.env.example +!.env.local.example + +# Uploads and generated files +uploads/ +backend/uploads/ +exports/ +logs/ +*.log + +# Database / local runtime +*.sqlite +*.db +postgres_data/ +redis_data/ + +# IDE / OS +.DS_Store +.idea/ +.vscode/ +.cursor-local-assistant-v2/ + +# Package manager +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* \ No newline at end of file diff --git a/.windsurfrules b/.windsurfrules new file mode 100644 index 0000000..3dd2616 --- /dev/null +++ b/.windsurfrules @@ -0,0 +1,54 @@ +# 最高优先级规则 - 必须严格遵守（Windsurf 专用） + +⚠️⚠️⚠️ 每次回复结束前必须执行以下命令！没有任何例外！⚠️⚠️⚠️ + +## 执行规则 + +1. 完成任务后，执行弹窗命令（跨平台，Windows/Mac/Linux 通用）： +node "/Users/freedak/.ranjin-mode/dialog-trigger.js" "windsurf" "1f2oju" "AI想要结束的原因摘要" + + 📱 **手机端通知**：执行此命令时会自动通知手机端（如果远程服务已开启），用户可以在手机上查看消息并发送反馈。 + +2. 仔细阅读命令输出的每一行： + - ACTION: continue 或 end（用户的选择） + - FEEDBACK: 用户输入的具体指令或反馈内容（⚠️ 必须完整阅读并执行！） + * 反馈可能来自电脑端弹窗或手机端远程输入 + - IMAGES: 用户上传的图片路径（如有，必须用read_file工具查看） + +3. 根据输出决定下一步： + - 如果 ACTION 是 "continue"： + * ⚠️ 必须仔细阅读 FEEDBACK 后面的全部内容 + * ⚠️ 必须按照 FEEDBACK 中用户的具体指令执行任务 + * ⚠️ 不要忽略 FEEDBACK，不要只说"用户选择继续" + - 如果 ACTION 是 "end" 或 "stop"：停止工作 + - ⚠️ 如果命令被取消/跳过/无输出：必须重新执行弹窗命令！ + +## 核心规则 + +1. 完整输出 - 输出完整代码和答案，禁止省略 +2. 持续执行 - 复杂任务一次性完成 +3. 结束确认 - 必须执行弹窗命令后才能结束 +4. FEEDBACK必读 - 用户的FEEDBACK是新的任务指令，必须执行 + +## 手机端远程功能 + +- 📱 当执行 dialog-trigger.js 命令时，会自动通知手机端（如果远程服务已开启） +- 📱 用户可以在手机浏览器中查看 AI 的消息和状态 +- 📱 用户可以在手机上输入反馈，反馈会通过 FEEDBACK 字段传递给你 +- 📱 手机端和电脑端弹窗功能完全同步，支持双向通信 + +## ⚠️ 唯一合法的结束条件 + +只有当命令输出包含 ACTION: end 或 ACTION: stop 时才能结束对话！ +以下情况都不能结束，必须重新执行弹窗命令： +- 命令被用户点击 Skip 跳过 +- 命令执行失败或超时 +- 命令没有输出 +- 工作区取消了命令 + +## 禁止 + +- 禁止不执行弹窗命令就结束 +- 禁止跳过弹窗流程 +- 禁止忽略FEEDBACK内容 +- 禁止在没有收到 ACTION: end/stop 的情况下结束 diff --git a/README.md b/README.md new file mode 100644 index 0000000..fd0bda7 --- /dev/null +++ b/README.md @@ -0,0 +1,79 @@ +# 财务 AI 助手（S2F） + +面向金蝶中小企业客户的财务 AI 助手。 + +当前第一模块为 **薪财通 AI / 薪酬财务对账 MVP**，先通过 Excel 上传与导出完成闭环： + +```text +上传工资/社保/个税表 + ↓ +AI 字段识别与用户确认 + ↓ +薪酬、社保、个税、公积金对账 + ↓ +异常清单与人工成本分析 + ↓ +导出金蝶凭证模板 +``` + +## 项目边界 + +- 不替代金蝶账套。 +- 不做完整财务软件。 +- 不做完整 HR SaaS。 +- 第一阶段只实现薪酬财务对账 MVP。 +- 发票报销、预算执行、现金流异常、往来对账、经营分析属于后续财务 AI 助手模块。 + +## 技术栈 + +| 层级 | 技术 | +|---|---| +| 前端 | Next.js + TypeScript + Tailwind CSS + Shadcn/ui | +| 后端 | Python FastAPI + Pydantic | +| 数据库 | PostgreSQL | +| 部署 | Docker + Docker Compose | + +## 目录结构 + +```text +s2f/ +├── frontend/ # Next.js 前端 +├── backend/ # FastAPI 后端 +├── pmdocs/ # 需求、PRD、任务文档 +├── docs/ # 产品方向与痛点材料 +├── cursor-rules/ # Cursor 规则材料 +├── docker-compose.yml # 本地与私有化部署编排 +├── run.md # 运行手册 +└── README.md +``` + +## 文档入口 + +- 需求文档：`pmdocs/0-req-S2F.md` +- PRD 文档：`pmdocs/1-prd-S2F.md` +- 任务文档：`pmdocs/2-task-S2F.md` +- 运行手册：`run.md` + +## 本地启动 + +当前处于项目初始化阶段。完整启动方式以后续 `run.md` 和 `docker-compose.yml` 为准。 + +```bash +docker-compose up -d +``` + +## 开发顺序 + +按 `pmdocs/2-task-S2F.md` 执行： + +1. 项目初始化 +2. 后端基础设施 +3. 前端基础设施 +4. 认证与权限 +5. 文件上传与解析 +6. AI 字段识别 +7. 对账与异常检测 +8. 人工成本分析 +9. 凭证生成 +10. UI 与页面开发 +11. 测试、部署与文档 \ No newline at end of file diff --git a/backend/.env.example b/backend/.env.example new file mode 100644 index 0000000..c933907 --- /dev/null +++ b/backend/.env.example @@ -0,0 +1,22 @@ +APP_NAME="财务 AI 助手 API" +APP_VERSION=1.0.0 +DEBUG=true +SECRET_KEY=change-me-in-production +ALLOWED_ORIGINS=http://localhost:3000 + +DATABASE_URL=postgresql+asyncpg://s2f_user:s2f_password@localhost:5432/s2f_db + +JWT_SECRET_KEY=change-me-in-production +JWT_ALGORITHM=HS256 +JWT_ACCESS_TOKEN_EXPIRE_MINUTES=60 + +OPENAI_API_KEY= +OPENAI_MODEL=gpt-4-turbo-preview +ZHIPU_API_KEY= +AI_PROVIDER=zhipu +AI_API_KEY= + +UPLOAD_DIR=./uploads +MAX_UPLOAD_SIZE=10485760 + +LOG_LEVEL=INFO \ No newline at end of file diff --git a/backend/app/__init__.py b/backend/app/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/api/__init__.py b/backend/app/api/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/core/__init__.py b/backend/app/core/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/core/config.py b/backend/app/core/config.py new file mode 100644 index 0000000..8c4d6e1 --- /dev/null +++ b/backend/app/core/config.py @@ -0,0 +1,51 @@ +from functools import lru_cache +from typing import Any + +from pydantic import field_validator +from pydantic_settings import BaseSettings, SettingsConfigDict + + +class Settings(BaseSettings): + model_config = SettingsConfigDict( + env_file=".env", + env_file_encoding="utf-8", + case_sensitive=False, + extra="ignore", + ) + + app_name: str = "财务 AI 助手 API" + app_version: str = "1.0.0" + debug: bool = True + secret_key: str = "change-me-in-production" + allowed_origins: list[str] = ["http://localhost:3000"] + + database_url: str = "postgresql+asyncpg://s2f_user:s2f_password@localhost:5432/s2f_db" + + jwt_secret_key: str = "change-me-in-production" + jwt_algorithm: str = "HS256" + jwt_access_token_expire_minutes: int = 60 + + openai_api_key: str = "" + openai_model: str = "gpt-4-turbo-preview" + zhipu_api_key: str = "" + ai_provider: str = "zhipu" + ai_api_key: str = "" + + upload_dir: str = "./uploads" + max_upload_size: int = 10_485_760 + + log_level: str = "INFO" + + @field_validator("allowed_origins", mode="before") + @classmethod + def parse_allowed_origins(cls, value: Any) -> list[str]: + if isinstance(value, str): + return [origin.strip() for origin in value.split(",") if origin.strip()] + if isinstance(value, list): + return value + return ["http://localhost:3000"] + + +@lru_cache +def get_settings() -> Settings: + return Settings() \ No newline at end of file diff --git a/backend/app/core/logging.py b/backend/app/core/logging.py new file mode 100644 index 0000000..0c5c758 --- /dev/null +++ b/backend/app/core/logging.py @@ -0,0 +1,17 @@ +import logging + +import structlog + + +def configure_logging(log_level: str = "INFO") -> None: + level = getattr(logging, log_level.upper(), logging.INFO) + + structlog.configure( + processors=[ + structlog.processors.TimeStamper(fmt="iso"), + structlog.processors.add_log_level, + structlog.processors.JSONRenderer(ensure_ascii=False), + ], + wrapper_class=structlog.make_filtering_bound_logger(level), + cache_logger_on_first_use=True, + ) \ No newline at end of file diff --git a/backend/app/main.py b/backend/app/main.py new file mode 100644 index 0000000..0f7e7c9 --- /dev/null +++ b/backend/app/main.py @@ -0,0 +1,31 @@ +from fastapi import FastAPI +from fastapi.middleware.cors import CORSMiddleware + +from app.core.config import get_settings +from app.core.logging import configure_logging + +settings = get_settings() +configure_logging(settings.log_level) + +app = FastAPI( + title=settings.app_name, + version=settings.app_version, + debug=settings.debug, +) + +app.add_middleware( + CORSMiddleware, + allow_origins=settings.allowed_origins, + allow_credentials=True, + allow_methods=["*"], + allow_headers=["*"], +) + + +@app.get("/api/health", tags=["health"]) +async def health_check() -> dict[str, str]: + return { + "status": "ok", + "service": settings.app_name, + "version": settings.app_version, + } \ No newline at end of file diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/schemas/__init__.py b/backend/app/schemas/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/services/__init__.py b/backend/app/services/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/utils/__init__.py b/backend/app/utils/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/pyproject.toml b/backend/pyproject.toml new file mode 100644 index 0000000..363eb75 --- /dev/null +++ b/backend/pyproject.toml @@ -0,0 +1,53 @@ +[tool.poetry] +name = "s2f-backend" +version = "0.1.0" +description = "财务 AI 助手后端服务，当前第一模块为薪酬财务对账 MVP。" +authors = ["S2F Team"] +readme = "../README.md" +packages = [{ include = "app" }] + +[tool.poetry.dependencies] +python = "^3.11" +fastapi = "0.110.0" +uvicorn = { version = "0.27.0", extras = ["standard"] } +pydantic = "2.6.0" +pydantic-settings = "2.1.0" +sqlalchemy = "2.0.25" +asyncpg = "0.29.0" +alembic = "1.13.0" +python-jose = { version = "3.3.0", extras = ["cryptography"] } +passlib = { version = "1.7.4", extras = ["bcrypt"] } +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" + +[tool.poetry.group.dev.dependencies] +pytest = "7.4.4" +pytest-asyncio = "0.23.4" +httpx = "0.26.0" +ruff = "0.1.15" +black = "23.12.1" +mypy = "1.8.0" + +[tool.black] +line-length = 100 +target-version = ["py311"] + +[tool.ruff] +line-length = 100 +target-version = "py311" +select = ["E", "F", "I", "UP", "B"] +ignore = [] + +[tool.pytest.ini_options] +asyncio_mode = "auto" +testpaths = ["tests"] +python_files = ["test_*.py"] +pythonpath = ["."] + +[build-system] +requires = ["poetry-core"] +build-backend = "poetry.core.masonry.api" \ No newline at end of file diff --git a/backend/requirements.txt b/backend/requirements.txt new file mode 100644 index 0000000..0a4ba08 --- /dev/null +++ b/backend/requirements.txt @@ -0,0 +1,21 @@ +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 +ruff==0.1.15 +black==23.12.1 +mypy==1.8.0 \ No newline at end of file diff --git a/backend/tests/test_health.py b/backend/tests/test_health.py new file mode 100644 index 0000000..5a4bd45 --- /dev/null +++ b/backend/tests/test_health.py @@ -0,0 +1,12 @@ +from fastapi.testclient import TestClient + +from app.main import app + + +def test_health_check() -> None: + client = TestClient(app) + + response = client.get("/api/health") + + assert response.status_code == 200 + assert response.json()["status"] == "ok" \ No newline at end of file diff --git a/cursor-rules/AGENTS.md b/cursor-rules/AGENTS.md new file mode 100644 index 0000000..d9a2489 --- /dev/null +++ b/cursor-rules/AGENTS.md @@ -0,0 +1,134 @@ +# AGENTS.md — AI 辅助开发协作规范 + +> 本文件定义 AI 辅助开发（Windsurf Cascade / 其他 AI Agent）在本项目中的协作规则。 +> 所有 AI Agent 必须同时遵守 `.windsurfrules`、`.windsurfrules.DEV-RULES` 和本文件。 + +--- + +## 1. 文档阅读顺序 + +开始任何开发任务前，AI Agent 必须按以下顺序阅读文档： + +1. **`.windsurfrules`** — 精简规则，了解技术栈和禁止事项 +2. **`.windsurfrules.DEV-RULES` §0** — 文档骨架，了解项目文档结构 +3. **`pmdocs/2-task.md`** — 查看当前任务状态和进度 +4. **`pmdocs/1-prd-finance-v1.md`** — 了解要开发的功能需求 +5. **`pmdocs/changes/CHANGELOG.md`** — 查看需求变更历史 +6. **`run.md`** — 了解如何启动和测试 +7. 对应模块的现有代码 — 了解代码风格和模式 + +--- + +## 2. 代码修改原则 + +### 2.1 最小改动 + +- 优先最小化修改，不重写已有代码 +- 不删除与本次修改无关的代码和注释 +- 不创建随机文件，除非任务明确需要 + +### 2.2 遵循现有模式 + +- 后端：遵循模块三件套（Controller + Service + Table）模式 +- 前端：遵循现有页面结构（列表页/详情页/表单页模板） +- 复用公共组件，禁止重复造轮子 + +### 2.3 同步更新文档 + +- 修改代码涉及行为变更 → 更新 `pmdocs/2-task.md` 任务状态 +- 修改 DB 结构 → 更新 `run.md` 数据库命令 +- 修改技术栈版本 → 更新 `run.md` §1 和 `.windsurfrules` +- 新增/修改 API → 更新 `pmdocs/1-prd-finance-v1.md`（如有接口说明） + +--- + +## 3. 任务管理 + +### 3.1 任务状态标记 + +| 标记 | 含义 | +|------|------| +| `[ ]` | 未开始 | +| `[~]` | 进行中 | +| `[x]` | 已完成 | +| `[!]` | 阻塞/有问题 | + +### 3.2 任务编号 + +- `T1-W1-xx`：1期第1周第 xx 个任务 +- `T1-W2-xx`：1期第2周第 xx 个任务 +- `T2-W3-xx`：2期第3周第 xx 个任务 + +--- + +## 4. 测试纪律 + +- 修 bug 必先写复现测试 +- 禁止删测试、禁止 `@skip`/`it.only` 进 PR +- 后端测试用真实 PostgreSQL（`ruchu_finance_test`），禁止 mock DB +- 测试覆盖率目标：70% 单元 / 20% 集成 / 10% E2E + +### 测试命令 + +```bash +# 后端 +java -cp apps/api/gradle/wrapper/gradle-wrapper.jar org.gradle.wrapper.GradleWrapperMain -p apps/api test + +# 前端单元 +cd apps/web && npm run test + +# 前端 E2E +cd apps/web && npm run test:e2e +``` + +> ⚠️ `./gradlew` 脚本有 bug，用上述 `java -cp` 命令替代。 + +--- + +## 5. 提交规范 + +### 5.1 Git 提交信息 + +``` +(): + + +``` + +- **type**：`feat`(新功能) / `fix`(修复) / `refactor`(重构) / `docs`(文档) / `test`(测试) / `chore`(杂项) +- **scope**：模块名（contracts/payments/refunds/commissions/exchanges/insurances/salaries/workers/customers/reconcile/dashboard/auth/users/roles/permissions） +- **subject**：简短描述（中文） + +示例： +``` +feat(contracts): 合同列表页增加月份筛选 +fix(payments): 退款金额校验允许零元 +refactor(auth): 权限码从 user:manage 拆分为细粒度权限 +``` + +### 5.2 禁止提交 + +- 禁止提交 `.env` 文件（仅提交 `.env.example`） +- 禁止提交 `build/` 目录 +- 禁止提交 `node_modules/` +- 禁止提交敏感信息（密钥、密码、Token） + +--- + +## 6. 已知问题 + +| 问题 | 影响 | 解决方案 | +|---|---|---| +| `gradlew` 脚本 `escape_args` bug | 后端启动/测试失败 | 用 `java -cp` 命令替代（详见 `.windsurfrules.DEV-RULES` §5.2） | +| Flyway checksum 不匹配 | 后端启动失败 | 手动更新 `flyway_schema_history`（详见 `.windsurfrules.DEV-RULES` §5.2） | +| 业务 Controller 缺少 `@PreAuthorize` | 权限控制不完整 | 新增 Controller 必须加 `@PreAuthorize`，存量逐步补充 | + +--- + +## 7. AI Agent 行为约束 + +- **不猜测**：不确定时用工具查证，不编造 API/函数/参数 +- **不越权**：不修改未经授权的文件，不执行有副作用的命令 +- **不遗漏**：修改代码后同步更新相关文档和测试 +- **不简化**：不跳过错误处理、不删除边界检查、不忽略安全校验 +- **用中文沟通**：所有回复和注释使用中文 \ No newline at end of file diff --git a/cursor-rules/README.md b/cursor-rules/README.md new file mode 100644 index 0000000..9da2cf8 --- /dev/null +++ b/cursor-rules/README.md @@ -0,0 +1,88 @@ +# Cursor 规则文档索引 + +本目录包含 Cursor AI 辅助开发的核心协作规范和工作流文档。 + +## 文档概览 + +### 核心工作流 + +1. **[ai-coding-workflow.md](./ai-coding-workflow.md)** - Cursor 全局 AI Coding 协作规则 + - 五阶段工作流：0-req → 1-prd → 2-task → 开发执行 + - 统一编号体系和执行前读取顺序 + - Definition of Done 标准 + +2. **[quick-reference.md](./quick-reference.md)** - AI Coding 工作流快速参考 + - 新项目强制检查点 + - 阶段与产出对照表 + - Definition of Ready & Done + - 禁止行为清单和紧急降级策略 + +3. **[new-project-checkpoint.md](./new-project-checkpoint.md)** - 新项目初始化检查点 + - 新项目识别条件 + - 强制启动流程 + - 检查点通过条件 + +### 专项规范 + +4. **[AGENTS.md](./AGENTS.md)** - AI 辅助开发协作规范（项目级） + - 文档阅读顺序 + - 代码修改原则 + - 任务管理和测试纪律 + - 提交规范和已知问题 + +5. **[change-management.md](./change-management.md)** - 需求变更管理 + - 7 维度影响评估表 + - 六步变更流程 + - 变更文档模板 + +6. **[architecture-and-design.md](./architecture-and-design.md)** - 架构与设计原则 + - ADR 架构决策记录 + - API/DB 变更约束 + - 实体唯一代码规范 + - 代码质量、测试、安全 + +7. **[ui-components-standard.md](./ui-components-standard.md)** - UI/UX 与公共组件规范 + - UI/UX 设计原则 + - 公共组件抽取原则 + - UI 公共组件登记表 + - 组件参数膨胀应对策略 + +## 使用指南 + +### 新项目启动 + +1. 阅读 `new-project-checkpoint.md` 了解新项目初始化流程 +2. 阅读 `ai-coding-workflow.md` 了解五阶段工作流 +3. 按照 `quick-reference.md` 中的阶段对照表推进 + +### 日常开发 + +1. 执行任务前，按 `ai-coding-workflow.md` §3.1.2 的顺序读取上下文 +2. 遵循 `AGENTS.md` 的代码修改原则 +3. 需求变更时，参考 `change-management.md` 的六步流程 +4. 重大技术决策时，参考 `architecture-and-design.md` 创建 ADR + +### 快速查询 + +遇到以下情况，快速查阅对应文档： + +- **不确定当前阶段** → `quick-reference.md` 阶段对照表 +- **需要变更需求** → `change-management.md` 7 维评估 +- **API/DB 变更** → `architecture-and-design.md` 变更检查清单 +- **UI 组件重复** → `ui-components-standard.md` 抽取原则 +- **项目特定规则** → `AGENTS.md` 项目协作规范 + +## 文档维护 + +- 这些规则文档来源于 Cursor 全局规则 +- 项目级调整应在项目根目录的 `AGENTS.md` 中说明 +- 规则冲突时，优先级：用户明确指令 > 项目规则 > 全局规则 + +## 相关文档 + +项目其他重要文档： + +- `../pmdocs/` - 项目需求、PRD、任务文档 +- `../run.md` - 项目运行手册 +- `../.windsurfrules` - 项目精简规则（如果存在） +- `../AGENTS.md` - 项目级 AI 协作规范（如果存在） \ No newline at end of file diff --git a/cursor-rules/ai-coding-workflow.md b/cursor-rules/ai-coding-workflow.md new file mode 100644 index 0000000..680338e --- /dev/null +++ b/cursor-rules/ai-coding-workflow.md @@ -0,0 +1,241 @@ +# Cursor 全局 AI Coding 协作规则 + +本规则应用于所有项目。核心目标是：先建立清晰需求与模块边界，再推进实现；以 `pmdocs/0-req-XXX.md` → `pmdocs/1-prd-XXX.md` → `pmdocs/2-task-XXX.md` → 开发执行的五阶段工作流为主。 + +## 0. 优先级与适用范围 + +### 0.1 指令优先级 +- 用户当前明确指令优先于本规则。 +- 项目内已有规范优先于本全局规则。 +- 本规则作为所有项目的默认协作、架构、编码、文档和质量基线。 + +### 0.2 工作流主线 +- 涉及"做一个项目 / 实现一个功能 / 非平凡改造"的请求，默认使用五阶段工作流。 +- 统一使用 `pmdocs/` 作为 PM 文档目录： + - `pmdocs/0-req-XXX.md`：需求与目标文档 + - `pmdocs/1-prd-XXX.md`：产品需求文档 + - `pmdocs/2-task-XXX.md`：开发任务文档 + - `pmdocs/changes/YYYY-MM-DD-序号-主题.md`：需求变更文档 + - `pmdocs/CHANGELOG.md`：需求与 PM 文档变更索引 + - `pmdocs/adr/YYYY-MM-DD-序号-主题.md`：架构决策记录 + - `pmdocs/ui-components.md`：UI 公共组件登记表 +- 简单任务走快速流程，不强制产出三份阶段文档。 + +### 0.3 简单任务定义 +满足以下情况之一，可走快速流程： +- 单文件小改动，通常小于 50 行代码。 +- 明确 bug 修复，影响范围清晰。 +- 文案、样式、配置微调。 +- 只读检查、解释代码、运行一次命令、查看少量文件。 + +快速流程：理解需求 → 简要确认 → 实施修改与必要验证 → 简洁说明结果。 + +## 1. 语言与沟通 + +- 所有与用户的交流必须使用简体中文。 +- 代码标识符、命令、日志、错误原文、文件路径、API 名称保持原语言。 +- 回复要直接、客观、简洁；不要输出冗长总结。 +- 除非用户明确要求，不使用 emoji。 +- 不确定时先提问，不擅自假设关键业务规则。 +- 提问应结构化：问题、背景、选项、建议。 +- 对用户能理解的内容，优先用模块关系、数据结构、数据流、状态机、作用域、伪代码表达，不沉迷函数级细节。 + +## 2. 工作区与项目边界 + +- 当前位于用户主目录时，只处理通用任务、系统探索、一次性命令和非项目工作。 +- 一旦任务属于某个明确项目，必须先切换到该项目根目录，再进行编辑、安装依赖、提交、创建文件等项目级操作。 +- 如果项目路径不明确，先询问用户。 +- 创建新项目时，优先放在 `~/Projects/` 或 `~/Developer/`；若不存在则放在用户主目录下。目录创建并初始化 Git 后，先切换到项目根目录，再继续脚手架、安装依赖或写代码。 +- 不回退用户或其他 agent 的脏变更。若冲突，先停下来询问。 + +## 3. 五阶段工作流 + +### 3.1 命名约定 +- 项目英文缩写记为 `XXX`，由用户提供或确认。 +- 阶段文档统一放在项目根目录下的 `pmdocs/` 独立目录： + - `pmdocs/0-req-XXX.md`：需求与目标文档 + - `pmdocs/1-prd-XXX.md`：产品需求文档 + - `pmdocs/2-task-XXX.md`：开发任务文档 +- 需求变更文档统一放在 `pmdocs/changes/`： + - `pmdocs/changes/YYYY-MM-DD-序号-主题.md` +- 需求与 PM 文档变更索引统一使用： + - `pmdocs/CHANGELOG.md` +- 架构决策记录统一放在 `pmdocs/adr/`： + - `pmdocs/adr/YYYY-MM-DD-序号-主题.md` +- UI 公共组件登记表统一使用： + - `pmdocs/ui-components.md` + +### 3.1.1 统一编号体系 + +- 需求条目使用 `REQ-001`、`REQ-002`。 +- PRD 功能使用 `PRD-FUNC-001`；产品场景使用 `SCENE-001`。 +- 开发任务使用 `TASK-001`，并映射到对应 `REQ`、`PRD-FUNC` 或 `SCENE`。 +- 需求变更使用 `CHG-YYYYMMDD-001`，并写入变更文档和 `pmdocs/CHANGELOG.md`。 +- 架构决策使用 `ADR-001`，并写入 `pmdocs/adr/YYYY-MM-DD-序号-主题.md`。 +- 权限码使用 `PERM_MODULE_ACTION`，例如 `PERM_USER_CREATE`、`PERM_ORDER_EXPORT`。 +- 编号一旦进入已确认文档，不复用、不重排；废弃项保留编号并标注状态。 + +### 3.1.2 执行前读取顺序 + +执行项目任务前，按以下顺序读取上下文，避免重复摸索： + +1. `run.md`：确认安装、启动、构建、测试、迁移命令。 +2. `pmdocs/2-task-XXX.md`：确认当前任务边界、验收标准、依赖关系。 +3. `pmdocs/changes/*.md`：若任务关联变更，确认变更原因、影响评估和状态。 +4. `pmdocs/1-prd-XXX.md`：确认产品场景、优先级、UI/UX 和公共组件规划。 +5. `pmdocs/0-req-XXX.md`：确认原始需求、非功能要求和范围边界。 +6. `pmdocs/adr/*.md`：若涉及技术栈、模块边界、认证、部署或数据方案，确认架构决策。 + +原则：运行方式看 `run.md`，任务边界看 `2-task`，变更来源看 `changes`，产品原因看 `1-prd`，原始约束看 `0-req`，长期技术取舍看 `adr`。 + +### 3.2 阶段 1：接收需求与目标 +- 完整读取和理解用户的需求描述或已有文档。 +- 识别目标用户、使用场景、优先级、性能、安全、数据规模、兼容性、第三方依赖等关键缺口。 +- 对模糊、矛盾或高风险信息先澄清。 +- 若需求明显过大，先拆出 MVP 与后续扩展边界。 + +### 3.3 阶段 2：生成 `pmdocs/0-req-XXX.md` +仅在阶段 1 信息足够后进行。 + +文档必须包含： +- 引言与目标 +- 术语表 +- 角色定义 +- 功能性需求，优先使用 EARS 格式：`WHEN / IF / WHILE / WHERE / THE ... SHALL ...` +- 非功能性需求：性能、安全、兼容性、可用性、可扩展性、可维护性、合规性 +- 范围边界：包含 / 不包含 +- 关键约束与假设 +- 验收标准 + +生成后必须请用户检查确认。未确认前不进入阶段 3。 + +### 3.4 阶段 3：生成 `pmdocs/1-prd-XXX.md` +仅在 `pmdocs/0-req-XXX.md` 确认通过后进行。 + +文档必须包含： +- 产品概述与定位 +- 目标与成功指标 +- 用户画像与核心场景，每个场景标注"痛点解法" +- 功能清单与优先级，使用 MoSCoW，并映射回需求编号 +- 关键流程 +- 角色权限矩阵 +- UI/UX 设计原则：布局结构、导航方式、表单交互、列表/表格、筛选、分页、时间段选择、空状态、加载状态、错误状态、响应式和可访问性 +- 公共组件抽取规划：页面布局、分页组件、时间段组件、筛选栏、搜索框、表格、表单项、弹窗/抽屉、状态标签等 +- 版本规划：MVP / 二期 / 三期 +- 非功能性要求 +- 外部依赖、内部依赖与风险 + +生成后必须请用户检查确认。未确认前不进入阶段 4。 + +### 3.5 阶段 4：生成 `pmdocs/2-task-XXX.md` +仅在 `pmdocs/1-prd-XXX.md` 确认通过后进行。 + +任务文档要求： +- 使用可勾选清单 `- [ ]`。 +- 编号清晰，任务粒度可执行、可验证。 +- 每个任务标注：目标、对应需求 / PRD 条目、验收标准、依赖关系、优先级、阶段。 +- 前后端技术栈、编译、启动、数据库迁移等一旦确认，必须包含创建或更新 `run.md` 的任务。 +- 涉及重大技术决策时，必须包含创建或更新 `pmdocs/adr/*.md` 的任务。 +- 涉及 API 或数据库变更时，必须包含接口契约、迁移、回滚、seed、权限和测试任务。 +- UI 页面开发前，应先识别可复用公共组件，并将页面布局、分页、时间段、筛选、表格、表单、弹窗等抽取任务排在具体页面任务之前。 +- 涉及可复用 UI 组件时，必须包含创建或更新 `pmdocs/ui-components.md` 的任务。 +- 明确测试要求：单元测试、集成测试、端到端测试、构建验证或手工验证。 +- 开发过程中持续更新任务状态和进度记录。 + +生成后必须请用户确认。未确认前不进入阶段 5。 + +### 3.6 阶段 5：按任务文档执行开发 +- 仅在 `pmdocs/2-task-XXX.md` 确认通过后开始编码。 +- 严格按确认后的任务文档推进。 +- 每完成一个任务或一组任务： + - 做相应验证：linter、构建、单元测试、集成测试或必要的手工验证。 + - 更新 `pmdocs/2-task-XXX.md`。 + - 简洁汇报结果、问题和下一步。 +- 若任务执行发现需调整需求或 PRD，必须进入需求变更流程。 +- 不在代码、文档或聊天中硬编码密钥、令牌、密码。 + +### 3.7 Definition of Done + +任务完成标准： +- 对应 `TASK` 已在 `pmdocs/2-task-XXX.md` 标记完成。 +- 代码实现完成，职责清晰，无复杂度扩散。 +- lint / build / test 或必要手工验证已完成。 +- `run.md` 已同步（若涉及）。 +- 变更文档已闭环，`pmdocs/CHANGELOG.md` 已同步（若涉及）。 +- API / DB / 权限码契约、迁移、回滚、测试已处理（若涉及）。 +- UI 加载、空态、错误、分页、权限状态已覆盖（若涉及）。 +- 无关脏变更未混入。 + +## 4. 文档管理 + +- 阶段文档是当前功能的事实来源：`pmdocs/0-req-XXX.md` 管需求，`pmdocs/1-prd-XXX.md` 管产品决策，`pmdocs/2-task-XXX.md` 管执行进度。 +- 不为每个小任务创建重复文档。 +- 项目级文档只在以下情况更新：新增用户可见功能、API 变化、配置格式变化、部署流程变化、重大架构调整、破坏性变更。 +- 文档过大时按模块或层次拆分，并保留导航入口。 +- 优先使用自动化文档：OpenAPI、GraphQL Schema、GoDoc、JSDoc、Sphinx、类型声明等。 + +### 4.1 `run.md` 运行手册 + +- 一旦确认前端、后端、数据库、包管理器、运行时或部署方式，必须在项目根目录创建或更新 `run.md`。 +- `run.md` 是项目运行事实来源；后续编译、启动、测试、数据库迁移等操作必须优先读取它，不要每次重新查找和试错。 +- 如果实际命令与 `run.md` 不一致，先验证真实行为，再更新 `run.md`，保持文档与运行时一致。 +- `run.md` 至少包含： + - 技术栈：前端、后端、数据库、包管理器、运行时版本。 + - 本地环境：必要环境变量、配置文件、端口、依赖服务。 + - 安装命令：依赖安装、初始化步骤。 + - 开发命令：前端启动、后端启动、全栈启动、后台任务或 worker。 + - 构建命令：前端构建、后端构建、类型检查、lint。 + - 测试命令：单元测试、集成测试、端到端测试、覆盖率。 + - 数据库命令：迁移、回滚、seed、reset、schema 生成。 + - 常见问题：已验证的坑、报错原因、修复方式。 +- `pmdocs/2-task-XXX.md` 中涉及环境准备、技术栈确认、数据库接入或部署改动时，必须包含更新 `run.md` 的任务。 + +## 5. Git 与协作 + +- 不主动提交代码，除非用户明确要求。 +- 不主动 push，除非用户明确要求。 +- 不使用破坏性 Git 操作，例如 `reset --hard`、强制 push、丢弃他人改动，除非用户明确要求并理解风险。 +- 提交粒度应是一个逻辑完整单元。 +- 提交信息优先遵循 Conventional Commits：`feat`、`fix`、`docs`、`style`、`refactor`、`test`、`chore`。 +- 发现无关脏变更时忽略；若与当前任务冲突，先询问用户。 + +## 6. 特殊场景 + +### 6.1 Bug 修复 +- 先定位根因，再修复。 +- 说明影响范围。 +- 优先补测试或最小复现。 +- 修复后做回归验证。 + +### 6.2 性能优化 +- 先测量再优化。 +- 识别瓶颈后再改代码。 +- 给出优化前后对比或可复现验证方式。 +- 说明优化副作用。 + +### 6.3 重构 +- 先说明重构目标和边界。 +- 保持外部行为不变。 +- 小步推进，保持可回滚。 +- 对遗留代码先理解再修改，必要时先加测试建立安全网。 + +### 6.4 Cursor 相关问题 +- 当用户询问 Cursor 使用方式、配置、设置或功能时，使用最新 Cursor 指南或可用专用能力，不凭记忆回答。 + +## 7. 核心原则 + +1. 用户目标优先，不替用户做关键业务决策。 +2. 架构与模块职责优先，不让复杂度在局部扩散。 +3. 工作流以 `pmdocs/0-req-XXX.md`、`pmdocs/1-prd-XXX.md`、`pmdocs/2-task-XXX.md` 为主，关键节点必须确认。 +4. 代码必须可维护、可测试、可验证。 +5. 沟通简洁透明，风险和阻塞及时说明。 +6. 不把密钥、令牌、密码放进全局规则或项目源码。 + +## 8. 相关规则 + +本规则聚焦工作流主线和核心原则。详细规范请参考： + +- `quick-reference.md`：快速参考卡、阶段对照表、禁止行为、紧急降级 +- `architecture-and-design.md`：架构原则、ADR、API/DB 变更约束、代码质量、测试、安全 +- `ui-components-standard.md`：UI/UX 设计原则、公共组件抽取、组件登记表、参数膨胀应对 +- `change-management.md`：需求变更识别、7 维评估、六步流程、文档追加、闭环机制 \ No newline at end of file diff --git a/cursor-rules/architecture-and-design.md b/cursor-rules/architecture-and-design.md new file mode 100644 index 0000000..b5d033e --- /dev/null +++ b/cursor-rules/architecture-and-design.md @@ -0,0 +1,128 @@ +# 架构与设计原则 + +本规则用于指导架构决策、接口设计、数据库变更和技术选型。 + +## 核心原则 + +- 职责分明的模块架构优先于优雅代码，优雅代码优先于功能堆砌。 +- 优先评估模块边界、数据流向、状态机、权限边界、错误边界和扩展点。 +- 出现复杂度扩散、参数爆炸、数据流回溯、状态同步困难时，应优先建议调整模块关系或架构，而不是继续局部补丁。 +- 默认偏好 Functional Programming 和可读的 DSL 化组织方式；除非项目已明确是面向对象架构。 +- 新技术、新依赖、新服务引入前，说明理由、收益、成本、风险和替代方案，并等待确认。 +- 接口设计优先明确契约：输入、输出、错误结构、状态码、幂等性、权限、兼容性。 + +## ADR 架构决策记录 + +- 重大技术决策必须写入 ADR，避免决策只存在于聊天或临时说明中。 +- ADR 路径：`pmdocs/adr/YYYY-MM-DD-序号-主题.md`。 +- ADR 触发条件： + - 前端技术栈、后端技术栈、数据库或运行时选择。 + - 认证授权、权限模型、状态管理、路由结构或部署方式选择。 + - 重大模块边界调整、数据流调整、状态机调整。 + - 引入会影响长期维护成本的新依赖、新服务或基础设施。 + - 关键性能、安全、可扩展性方案选择。 +- ADR 必须包含：背景、决策选项、最终选择、选择理由、影响后果、风险和回滚思路。 +- ADR 只记录重要决策；普通实现细节不要过度记录。 + +### ADR 模板示例 + +```markdown +# ADR-001：选择 xxx + +## 背景 +为什么需要决策 + +## 选项 +- A：优点 / 缺点 +- B：优点 / 缺点 + +## 决策 +选择哪个方案 + +## 后果 +带来的收益、成本、风险 +``` + +## API 变更约束 + +- API 变更必须明确：请求结构、响应结构、错误码、权限要求、幂等性、兼容性和废弃策略。 +- API 变更必须同步到 `pmdocs/1-prd-XXX.md`、`pmdocs/2-task-XXX.md` 或对应变更文档；如果项目已有 OpenAPI / GraphQL Schema / RPC IDL，也必须同步。 +- 涉及权限码的 API 变更，必须同步权限码表、后端校验、前端权限门禁和测试用例。 +- 破坏性 API 变更必须进入需求变更流程，并在 7 维度影响评估表中明确处理动作和状态。 + +### API 变更检查清单 + +- [ ] 请求结构（字段、类型、必填、默认值） +- [ ] 响应结构（字段、类型、状态码、错误码） +- [ ] 权限要求（角色、权限码、访问边界） +- [ ] 幂等性（POST / PUT / DELETE 是否幂等） +- [ ] 兼容性（新增字段 / 废弃字段 / 破坏性变更） +- [ ] 文档同步（PRD / 任务 / OpenAPI / GraphQL Schema） +- [ ] 测试覆盖（单元测试 / 集成测试 / 权限测试） + +## 数据库变更约束 + +- 数据库变更必须明确：表、字段、索引、约束、迁移脚本、回滚脚本、seed 是否调整、历史数据兼容策略。 +- 数据库变更必须评估查询性能、索引影响、默认值、空值、唯一约束和线上数据迁移风险。 +- 涉及权限码的 DB 变更，必须同步权限码表、后端校验、前端权限门禁和测试用例。 +- 破坏性 DB 变更必须进入需求变更流程，并在 7 维度影响评估表中明确处理动作和状态。 + +### 实体唯一代码规范 + +- 业务主体实体（用户、组织、部门、商品、订单、项目）和配置数据（角色、字典项、模板）必须有唯一业务代码。 +- 唯一代码格式：`{前缀}_{业务含义}` 或 `{模块}_{编号}`，例如： + - 用户：`USER_admin001`、`USER_john_doe` + - 商品：`PROD_SKU12345` + - 订单：`ORDER_20260705001` + - 权限：`PERM_USER_CREATE` +- 唯一代码约束： + - 必须有唯一索引 + - 一旦创建不可修改 + - 优先可读性，而非简洁性 +- 其他表引用时，优先使用唯一业务代码作为外键，而不是自增 ID。 +- 好处：数据可读、跨系统可追溯、数据库导入导出友好、便于调试。 +- 权衡：查询性能可能略低于整数 ID，必须在唯一代码字段上建立索引。 +- 不需要唯一代码的场景：纯关联表、日志、审计、历史记录、一次性临时数据、只在父实体内部使用的子表。 + +### 数据库变更检查清单 + +- [ ] 表、字段、索引、约束变化 +- [ ] 迁移脚本（migration） +- [ ] 回滚脚本（rollback） +- [ ] seed 数据是否调整 +- [ ] 历史数据兼容策略（默认值 / 数据填充 / 迁移脚本） +- [ ] 查询性能影响（索引 / 全表扫描 / 锁表风险） +- [ ] 空值、唯一约束、外键约束影响 +- [ ] 线上数据迁移风险（停机 / 灰度 / 双写） +- [ ] 测试覆盖（单元测试 / 集成测试 / 迁移测试） + +## 代码质量 + +- 遵循项目既有代码风格。 +- 保持单一职责、高内聚、低耦合。 +- 避免重复代码，避免过度抽象。 +- 命名必须语义清晰。 +- 注释只解释代码无法自解释的意图、约束和权衡，不写表面行为注释。 + +## 错误处理 + +- 不忽略错误。 +- 用户可见错误要友好，内部错误要可诊断。 +- 对关键边界做输入校验、权限校验和异常处理。 +- 错误处理路径应有测试覆盖。 + +## 测试与验证 + +- 功能代码和测试代码尽量同步完成。 +- 公共函数、核心业务规则、权限判断、错误处理和边界条件应有测试。 +- 测试优先使用 Arrange-Act-Assert 或 Given-When-Then。 +- 使用 Mock / Stub 隔离外部依赖。 +- 测试应快速稳定，避免不必要的 sleep 或长等待。 +- 完成实质性编辑后，检查 linter 或诊断；若引入错误，应修复。 + +## 安全 + +- 不在代码、规则、提交信息或文档中硬编码密钥、令牌、密码。 +- 敏感信息应使用环境变量、密钥管理器或用户指定的安全存储方式。 +- 验证所有用户输入，防止注入、XSS、越权访问等常见问题。 +- 遵循最小权限原则。 \ No newline at end of file diff --git a/cursor-rules/change-management.md b/cursor-rules/change-management.md new file mode 100644 index 0000000..c82c74b --- /dev/null +++ b/cursor-rules/change-management.md @@ -0,0 +1,114 @@ +# 需求变更管理 + +本规则用于指导需求变更识别、影响评估、文档追加和任务闭环。 + +## 启用条件 + +- 当用户提出与已确认的 `pmdocs/0-req-XXX.md`、`pmdocs/1-prd-XXX.md` 或 `pmdocs/2-task-XXX.md` 不一致的要求时，先判断是否属于需求变更。 +- 只有影响以下任一范围时，才启用完整变更机制：需求、PRD、任务、数据库、接口、权限、核心 UI 流程。 +- 小变更不要过度文档化：文案调整、样式微调、明显 bug 修复、无业务含义的配置微调，不需要创建完整变更文档；可在任务记录或回复中简要说明。 + +## 核心原则 + +- 每次重要需求变更创建独立变更文档，不覆盖历史内容。 +- 原始 `pmdocs/0-req-XXX.md`、`pmdocs/1-prd-XXX.md`、`pmdocs/2-task-XXX.md` 只追加版本标注和变更引用，不重写历史决策。 +- 变更必须从"影响评估"进入"任务落地"，最后完成闭环。 + +## 变更文档命名 + +- 变更文档路径：`pmdocs/changes/YYYY-MM-DD-序号-主题.md`。 +- 示例：`pmdocs/changes/2026-07-05-001-权限码调整.md`。 +- 每份变更文档必须包含：背景、原因、目标、范围、影响评估、落地任务、状态、完成记录。 + +## 六步流程 + +1. 创建变更文档：`pmdocs/changes/YYYY-MM-DD-序号-主题.md`。 +2. 评估影响：使用 7 维度影响评估表。 +3. 更新原文档：在 `pmdocs/0-req-XXX.md`、`pmdocs/1-prd-XXX.md`、`pmdocs/2-task-XXX.md` 对应章节末尾追加 `v{版本}` 更新标注和变更文档引用。 +4. 更新变更索引：在 `pmdocs/CHANGELOG.md` 追加变更记录。 +5. 开发落地：按 `pmdocs/2-task-XXX.md` 新增任务执行，并关联变更文档。 +6. 完成闭环：任务标记 `[x]`，变更文档状态标注完成，索引状态同步更新。 + +## 7 维度影响评估表 + +变更文档必须包含以下表格： + +| 维度 | 是否影响 | 影响说明 | 处理动作 | 状态 | +|---|---|---|---|---| +| 需求 | 是/否 | 影响哪些 REQ 条目 | 追加版本标注 / 新增需求 | 待处理/已处理 | +| PRD | 是/否 | 影响哪些产品场景或功能 | 追加版本标注 / 调整优先级 | 待处理/已处理 | +| 任务 | 是/否 | 新增或调整哪些 TASK | 追加任务 / 调整依赖 | 待处理/已处理 | +| DB | 是/否 | 表、字段、索引、迁移影响 | 新增 migration / 回滚方案 | 待处理/已处理 | +| 后端 | 是/否 | API、服务、权限判断影响 | 修改接口 / 服务 / 测试 | 待处理/已处理 | +| 前端 | 是/否 | 页面、组件、状态、交互影响 | 修改页面 / 公共组件 / 测试 | 待处理/已处理 | +| 权限码 | 是/否 | 角色、权限码、访问边界影响 | 更新权限表 / 权限校验 | 待处理/已处理 | + +## 原文档追加标注格式 + +在对应章节末尾追加： + +```markdown +📌 v{版本} 更新：见 pmdocs/changes/YYYY-MM-DD-序号-主题.md +影响范围：REQ-xxx、PRD-xxx、TASK-xxx +状态：已纳入 / 已完成 / 已废弃 +``` + +## 确认要求 + +- 中大型变更执行前说明：影响范围、工作量、风险、回滚方案、需要回归测试的功能。 +- 架构调整、多模块影响、数据结构或 API 破坏性变更，必须获得明确确认。 +- 小规模明确变更可简要说明后直接执行。 + +## 变更文档模板 + +```markdown +# CHG-YYYYMMDD-001：变更主题 + +## 背景 +为什么要做这个变更 + +## 原因 +用户需求 / 线上问题 / 技术债 / 架构调整 + +## 目标 +变更期望达成的目标 + +## 范围 +影响的功能模块、页面、接口、数据 + +## 影响评估 + +| 维度 | 是否影响 | 影响说明 | 处理动作 | 状态 | +|---|---|---|---|---| +| 需求 | 是/否 | ... | ... | 待处理/已处理 | +| PRD | 是/否 | ... | ... | 待处理/已处理 | +| 任务 | 是/否 | ... | ... | 待处理/已处理 | +| DB | 是/否 | ... | ... | 待处理/已处理 | +| 后端 | 是/否 | ... | ... | 待处理/已处理 | +| 前端 | 是/否 | ... | ... | 待处理/已处理 | +| 权限码 | 是/否 | ... | ... | 待处理/已处理 | + +## 落地任务 + +- [ ] TASK-xxx：更新需求文档 +- [ ] TASK-xxx：更新 PRD +- [ ] TASK-xxx：更新任务文档 +- [ ] TASK-xxx：DB migration +- [ ] TASK-xxx：后端实现 +- [ ] TASK-xxx：前端实现 +- [ ] TASK-xxx：测试 +- [ ] TASK-xxx：更新 CHANGELOG + +## 风险与回滚 + +- 风险：... +- 回滚方案：... +- 需要回归测试的功能：... + +## 完成记录 + +- 2026-07-05：创建变更文档 +- 2026-07-06：完成影响评估，更新原文档 +- 2026-07-08：完成开发和测试 +- 2026-07-09：变更闭环 +``` \ No newline at end of file diff --git a/cursor-rules/new-project-checkpoint.md b/cursor-rules/new-project-checkpoint.md new file mode 100644 index 0000000..a7fd7b8 --- /dev/null +++ b/cursor-rules/new-project-checkpoint.md @@ -0,0 +1,89 @@ +# 新项目初始化检查点 + +本规则用于确保新项目一开始就按照五阶段工作流启动。 + +## 新项目识别条件 + +当满足以下任一条件时，判定为新项目： + +- 用户明确说"做一个项目""新建项目""开始一个新项目" +- 项目根目录不存在 `pmdocs/` 目录 +- 项目根目录存在但没有 `pmdocs/0-req-*.md` + +## 强制启动流程 + +一旦识别为新项目，必须执行以下流程，**不得跳过**： + +### 第一步：确认项目英文缩写 + +- 询问用户：项目英文缩写（例如：IPTV、AVCC、BLOG） +- 用于命名 `pmdocs/0-req-XXX.md`、`pmdocs/1-prd-XXX.md`、`pmdocs/2-task-XXX.md` + +### 第二步：创建 pmdocs 目录结构 + +在项目根目录创建： + +``` +pmdocs/ +├── changes/ +└── adr/ +``` + +### 第三步：进入阶段 1 + +按照 `ai-coding-workflow.md` 中的"阶段 1：接收需求与目标"开始工作： + +- 完整读取和理解用户需求 +- 识别关键缺口：目标用户、使用场景、优先级、性能、安全、数据规模、兼容性、第三方依赖 +- 对模糊、矛盾或高风险信息先澄清 +- 若需求过大，先拆出 MVP + +### 第四步：禁止提前编码 + +在 `pmdocs/0-req-XXX.md`、`pmdocs/1-prd-XXX.md`、`pmdocs/2-task-XXX.md` 三个文档全部确认前，**严格禁止**： + +- 创建源码文件 +- 安装依赖 +- 初始化框架 +- 写任何业务代码 + +唯一允许的操作： + +- 创建 `pmdocs/` 目录和阶段文档 +- 创建 `.gitignore` +- 创建 `README.md`（只写项目名称和简介） + +## 用户试图跳过时的应对 + +如果用户说"先写代码，文档后补"或类似要求，必须： + +1. 明确告知：这违反了项目协作规则 +2. 说明风险：需求不明、架构混乱、返工成本高 +3. 提供选择： + - 选项 A：按规则走完五阶段（推荐） + - 选项 B：启用紧急降级策略（见 `quick-reference.md`），明确记录技术债和补齐时间点 + +## 检查点通过条件 + +只有满足以下条件，才算通过新项目初始化检查点： + +- [ ] 项目英文缩写已确认 +- [ ] `pmdocs/` 目录结构已创建 +- [ ] `pmdocs/0-req-XXX.md` 已生成并确认 +- [ ] `pmdocs/1-prd-XXX.md` 已生成并确认 +- [ ] `pmdocs/2-task-XXX.md` 已生成并确认 +- [ ] `run.md` 已创建或计划在任务中创建 + +通过检查点后，才可以进入"阶段 5：按任务文档执行开发"。 + +## 已有项目的处理 + +如果项目已存在代码但缺少 `pmdocs/` 文档： + +1. 明确告知：这是一个缺少规范文档的已有项目 +2. 提供选择： + - 选项 A：补充 `pmdocs/0-req`、`1-prd`、`2-task`（推荐，但工作量大） + - 选项 B：只创建 `run.md` 和当前阶段的 `2-task-XXX.md`，后续按需补充 + - 选项 C：不补充文档，只用规则指导后续开发（不推荐，可追溯性差） + +选择后必须记录在项目根目录的 `README.md` 或 `pmdocs/CHANGELOG.md` 中。 \ No newline at end of file diff --git a/cursor-rules/quick-reference.md b/cursor-rules/quick-reference.md new file mode 100644 index 0000000..4b521f8 --- /dev/null +++ b/cursor-rules/quick-reference.md @@ -0,0 +1,106 @@ +# AI Coding 工作流快速参考 + +用于快速判断当前处于哪个阶段、该产出什么、是否需要用户确认。 + +## 新项目强制检查点 + +**识别条件**：用户说"做一个项目"，或项目根目录不存在 `pmdocs/`。 + +**强制流程**： +1. 确认项目英文缩写 +2. 创建 `pmdocs/` 目录结构 +3. 进入阶段 1：接收需求 +4. **禁止提前编码**，直到 `0-req`、`1-prd`、`2-task` 全部确认 + +详见 `new-project-checkpoint.md`。 + +## 阶段与产出对照表 + +| 场景 | 应读取 | 应产出 | 必须确认 | 备注 | +|---|---|---|---|---| +| 新项目启动 | 用户描述 | `pmdocs/0-req-XXX.md` | ✓ | 理解需求、识别风险、拆 MVP | +| 需求确认后 | `0-req` | `pmdocs/1-prd-XXX.md` | ✓ | 产品场景、UI/UX、公共组件规划 | +| PRD 确认后 | `0-req` + `1-prd` | `pmdocs/2-task-XXX.md` + `run.md` | ✓ | 任务拆分、编号、依赖、验收 | +| 任务确认后 | `run.md` + `2-task` + `changes` + `adr` | 代码 + 测试 + Done 闭环 | - | 按执行前读取顺序 | +| 需求变更 | 原 `0-req` / `1-prd` / `2-task` | `pmdocs/changes/CHG-*.md` + 7 维评估 | ✓ | 只影响需求/PRD/任务/DB/接口/权限/UI 时启用 | +| 重大技术决策 | 当前上下文 | `pmdocs/adr/ADR-*.md` | ✓ | 技术栈、认证、模块边界、部署 | +| 公共组件沉淀 | 页面实现 | `pmdocs/ui-components.md` | - | 登记组件类型、输入输出、使用页面 | +| 简单任务 | 上下文 | 代码 + 简要说明 | - | 单文件 < 50 行、bug 修复、文案调整 | + +## 执行前读取顺序 + +执行项目任务前，按以下顺序读取上下文： + +1. `run.md` → 运行方式 +2. `pmdocs/2-task-XXX.md` → 任务边界 +3. `pmdocs/changes/*.md` → 变更来源 +4. `pmdocs/1-prd-XXX.md` → 产品原因 +5. `pmdocs/0-req-XXX.md` → 原始约束 +6. `pmdocs/adr/*.md` → 技术取舍 + +## Definition of Ready + +允许开始开发的条件： + +- [ ] `pmdocs/0-req-XXX.md` 已确认 +- [ ] `pmdocs/1-prd-XXX.md` 已确认 +- [ ] `pmdocs/2-task-XXX.md` 已确认 +- [ ] 当前任务具备 `TASK` 编号、验收标准、依赖、测试要求 +- [ ] 技术栈明确，涉及运行/构建/迁移时 `run.md` 已存在或任务中明确补充 +- [ ] 重大决策已有 ADR 或计划创建 +- [ ] 关键风险、权限边界、数据边界、回滚策略已说明 + +## Definition of Done + +任务完成标准： + +- [ ] 对应 `TASK` 已在 `pmdocs/2-task-XXX.md` 标记完成 +- [ ] 代码实现完成，职责清晰，无复杂度扩散 +- [ ] lint / build / test 或必要手工验证已完成 +- [ ] `run.md` 已同步（若涉及） +- [ ] 变更文档已闭环，`pmdocs/CHANGELOG.md` 已同步（若涉及） +- [ ] API / DB / 权限码契约、迁移、回滚、测试已处理（若涉及） +- [ ] UI 加载、空态、错误、分页、权限状态已覆盖（若涉及） +- [ ] 无关脏变更未混入 + +## 编号体系速查 + +- 需求：`REQ-001` +- PRD 功能：`PRD-FUNC-001` +- 场景：`SCENE-001` +- 任务：`TASK-001` +- 变更：`CHG-YYYYMMDD-001` +- 架构决策：`ADR-001` +- 权限码：`PERM_MODULE_ACTION` + +编号一旦进入已确认文档，不复用、不重排；废弃项保留编号并标注状态。 + +## 禁止行为清单 + +- ❌ 跨阶段抢跑：未确认 `0-req` 就写 `1-prd`，未确认 `2-task` 就开始编码 +- ❌ 文档与代码不同步：`run.md` 过期、`ui-components.md` 不更新、变更未闭环 +- ❌ 编号混乱：`REQ` / `TASK` / `CHG` 编号重复、跳号、随意改动 +- ❌ 过度文档化：明显 bug 修复创建完整变更文档，单文件改动走五阶段 +- ❌ 架构决策口头化：技术栈、认证方案只在聊天里说，未写入 ADR +- ❌ API / DB 变更无迁移：改表结构不写 migration，改 API 不说明兼容性 +- ❌ 公共组件参数爆炸：把页面路由、接口请求、特定文案硬塞进基础组件 + +## 紧急情况降级策略 + +- 线上紧急 bug：可先修复上线，24 小时内补 `pmdocs/changes/CHG-*.md` 和回归测试 +- 技术栈探索期：可先做 POC，技术栈确定后立即补 `run.md` 和 ADR +- 用户明确"先上后补"：必须在任务或聊天中明确风险、缺失文档清单和补齐时间点 +- 外部不可控因素：在 `0-req` 或 `1-prd` 中标注"假设 X 可用"；若假设失效，进入变更流程 + +## 文档健康检查清单 + +定期或阶段结束时验证： + +- [ ] `0-req`、`1-prd`、`2-task` 已确认并有版本记录 +- [ ] 所有 `REQ` / `PRD-FUNC` / `TASK` 编号唯一且可追溯 +- [ ] `run.md` 能直接执行，命令无误 +- [ ] 变更文档已闭环，`CHANGELOG.md` 同步 +- [ ] ADR 覆盖所有重大技术决策 +- [ ] `ui-components.md` 与实际组件一致 +- [ ] API / DB 变更有 migration / rollback / 测试 +- [ ] 无关脏变更未混入提交 \ No newline at end of file diff --git a/cursor-rules/ui-components-standard.md b/cursor-rules/ui-components-standard.md new file mode 100644 index 0000000..a5eff9e --- /dev/null +++ b/cursor-rules/ui-components-standard.md @@ -0,0 +1,71 @@ +# UI/UX 与公共组件规范 + +本规则用于指导 UI/UX 设计、公共组件抽取和组件登记管理。 + +## UI/UX 设计原则 + +- 禁止使用 emoji 作为 UI 图标。 +- 首选专业图标库：Lucide Icons，其次 Feather Icons；Ant Design 项目可使用 Ant Design Icons。 +- 禁止使用中文拼音缩写表达业务含义；优先使用英文、中文全称或清晰的领域命名。 +- UI 实现应关注一致性、可访问性、响应式布局和错误状态。 +- 页面设计应先确定信息架构，再确定视觉样式：导航、页面标题、主操作区、筛选区、内容区、分页区、反馈区。 +- 表单必须明确必填、校验、错误提示、提交中、提交成功、提交失败和取消路径。 +- 列表和表格必须明确加载、空数据、错误、筛选无结果、分页、排序和批量操作状态。 +- 时间、金额、状态、权限、危险操作等高频模式必须统一呈现，不允许每个页面各自发挥。 + +## 公共组件抽取原则 + +- 同一交互或视觉模式在两个及以上页面出现，优先抽取公共组件。 +- 即使只出现一次，但包含复杂状态、权限、时间段、分页、筛选、表格联动等逻辑，也应优先抽取为领域组件或组合组件。 +- 公共组件 API 应表达业务语义，不暴露页面内部状态细节。 +- 公共组件应保持稳定输入输出：`value`、`onChange`、`loading`、`disabled`、`error`、`empty`、`pagination` 等状态显式建模。 +- 不把页面特有文案、接口请求、路由跳转硬塞进基础公共组件；这些应留在页面层或领域组合层。 + +## 优先沉淀的组件类型 + +- 页面布局：`PageLayout`、`PageHeader`、`ContentCard`、`ActionBar`。 +- 查询筛选：`FilterBar`、`SearchInput`、`TimeRangePicker`、`DateRangePreset`。 +- 数据展示：`DataTable`、`Pagination`、`EmptyState`、`LoadingState`、`ErrorState`。 +- 表单交互：`FormField`、`FormSection`、`SubmitBar`、`ConfirmDialog`。 +- 反馈与状态：`StatusBadge`、`PermissionGate`、`Toast`、`ResultPanel`。 +- 业务高频组件：根据项目领域沉淀，不提前抽象不存在的业务概念。 + +## 页面实现顺序 + +- 先定义页面布局和数据流，再实现页面。 +- 先抽取公共组件，再堆页面细节。 +- 先覆盖加载、空态、错误、分页和权限状态，再补视觉细节。 +- 当组件参数开始膨胀时，优先评估是否应拆成基础组件、领域组件和页面容器三层。 + +## UI 公共组件登记表 + +- 一旦项目出现可复用 UI 组件，必须创建或更新 `pmdocs/ui-components.md`。 +- `pmdocs/ui-components.md` 用于记录组件沉淀情况，避免重复造分页、时间段、筛选栏、表格、表单等组件。 +- 组件登记表至少包含：组件名、组件类型、适用场景、输入状态、输出事件、使用页面、维护状态。 +- 推荐格式： + +| 组件 | 类型 | 适用场景 | 输入状态 | 输出事件 | 使用页面 | 状态 | +|---|---|---|---|---|---|---| +| `Pagination` | 基础组件 | 列表/表格分页 | `page` / `pageSize` / `total` | `onChange` | 用户列表、订单列表 | 稳定 | +| `TimeRangePicker` | 组合组件 | 时间范围筛选 | `start` / `end` / `preset` | `onChange` | 数据看板、订单筛选 | 稳定 | +| `FilterBar` | 组合组件 | 列表筛选栏 | `filters` / `onFilterChange` | `onChange` / `onReset` | 用户列表、订单列表 | 稳定 | +| `DataTable` | 基础组件 | 数据表格 | `columns` / `data` / `loading` / `pagination` | `onPageChange` / `onSort` | 用户列表、订单列表 | 稳定 | + +- 公共组件新增、重命名、废弃或职责变化时，必须同步更新组件登记表。 +- 组件登记表只记录复用组件，不记录一次性页面局部元素。 + +## 组件参数膨胀应对策略 + +当组件参数超过 10 个，或出现以下情况时，应重新评估组件边界： + +- 参数包含页面特定文案、路由、接口请求 +- 参数包含复杂业务规则或权限判断 +- 参数存在互斥或复杂依赖关系 +- 不同使用场景需要不同参数子集 + +应对策略： + +1. 拆成基础组件 + 领域组件 + 页面容器三层 +2. 使用组合模式而不是配置模式 +3. 使用 Render Props 或 Slots 传递复杂逻辑 +4. 使用 Context 或状态管理隔离跨层状态 \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..e996b54 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,20 @@ +services: + postgres: + image: postgres:15-alpine + container_name: s2f-postgres + environment: + POSTGRES_DB: s2f_db + POSTGRES_USER: s2f_user + POSTGRES_PASSWORD: s2f_password + ports: + - "5432:5432" + volumes: + - postgres_data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U s2f_user -d s2f_db"] + interval: 10s + timeout: 5s + retries: 5 + +volumes: + postgres_data: \ No newline at end of file diff --git a/docs/财务AI_产品方向建议.md b/docs/财务AI_产品方向建议.md new file mode 100644 index 0000000..89cfe5e --- /dev/null +++ b/docs/财务AI_产品方向建议.md @@ -0,0 +1,1261 @@ +# 财务 AI 助手：面向金蝶中小企业客户的财务自动化与对账助手 + +## 1. 产品结论 + +建议优先做一个可逐步扩展的 AI 产品： + +**面向金蝶中小企业客户的财务 AI 助手** + +它不是替代金蝶，而是作为金蝶用户的增效工具，帮助中小企业财务人员把分散在 Excel、HR、发票、报销、银行流水和业务系统中的财务相关数据，整理成可核对、可解释、可导入金蝶的结构化结果。 + +第一阶段先做边界清晰、价值明确的薪酬财务对账模块，将每月薪酬对账工作从 3 天压缩到 30 分钟。后续再扩展到发票报销、预算执行、现金流异常、往来对账和经营分析。 + +核心价值主张： + +> **财务 AI 助手：让财务人员更快完成数据整理、对账、解释、分析和凭证生成。** +> +> **第一模块薪财通 AI：将薪酬对账工作从 3 天压缩到 30 分钟。** + +建议产品结构： + +```text +财务 AI 助手 +├── 第一模块：薪财通 AI（薪酬财务对账） +├── 第二模块：发票与报销 AI 助手 +├── 第三模块：预算执行 AI 分析 +├── 第四模块：现金流异常 AI 监控 +├── 第五模块：往来对账 AI 助手 +└── 第六模块：经营分析 AI 看板 +``` + +**时间节省计算器示例（第一模块）**： +- 100 人企业：传统方式 16-24 小时 → 薪财通 AI 0.5 小时 +- 节省成本：按财务人员 200 元/小时计算，每月节省 3,000-4,500 元 +- 年度 ROI：订阅费 3,588 元/年，节省人力成本 36,000-54,000 元/年 + +## 2. 为什么选择这个方向 + +金蝶的强项是企业经营管理软件、财务核算、ERP、进销存、云会计等结构化系统能力。对中小企业来说，金蝶通常承担账套、凭证、报表、进销存和经营数据管理等核心角色。 + +但在实际业务中，财务人员每月仍然需要从 HR 或行政人员那里接收大量薪酬相关表格，例如： + +- 工资表 +- 社保明细 +- 公积金明细 +- 个税申报结果 +- 银行发放回单 +- 考勤表 +- 绩效或提成表 +- 员工入职、调岗、离职数据 + +这些数据往往来自不同系统或 Excel，字段口径不统一，人员状态复杂，部门归属经常变化。金蝶负责最终入账和核算，但“HR 数据到财务凭证之间”的整理、核对、解释和转换，仍然有大量人工工作。 + +这正是你们在人力资源领域的优势可以发挥的地方。 + +## 3. 目标用户 + +### 核心用户 + +中小企业财务人员，尤其是： + +- 财务主管 +- 总账会计 +- 出纳兼会计 +- 负责工资、社保、个税入账的财务人员 + +### 相关用户 + +- HR 薪酬专员 +- 行政人事 +- 企业老板或管理层 +- 外包记账公司 + +## 4. 用户痛点 + +中小企业财务人员在每月薪酬入账时，通常会遇到以下问题： + +1. **表格来源多** + + 工资、社保、公积金、个税、考勤和提成数据来自不同人员或系统，格式不统一。 + +2. **人员状态复杂** + + 入职、离职、调岗、转正、停薪留职、补发工资等情况容易造成对账差异。 + +3. **部门成本分摊麻烦** + + 财务需要把工资成本拆到销售费用、管理费用、研发费用、生产成本等不同科目。 + +4. **凭证生成重复** + + 每月都要做工资计提、工资发放、个税、社保、公积金等相关凭证，重复性强但容易出错。 + +5. **异常解释困难** + + 老板或财务负责人经常会问：“为什么这个月人工成本涨了？”财务需要追溯到人员、部门、薪资项和社保基数变化。 + +6. **财务与 HR 口径不一致** + + HR 看的是应发工资、实发工资、员工状态；财务看的是费用归属、计提、付款和往来。两边语言不同，沟通成本高。 + +## 5. 产品定位 + +财务 AI 助手定位为： + +**连接企业业务数据、财务数据与金蝶财务系统的 AI 中间层。** + +它不替代金蝶账套，也不替代完整 ERP / HR / OA 系统，而是解决一个更明确的问题： + +> 把分散在 Excel、业务系统、HR、银行流水、发票和报销材料中的半结构化数据，自动整理成财务可以核对、解释和导入金蝶的结构化结果。 + +第一阶段先做薪酬财务对账模块（薪财通 AI），因为薪酬、社保、公积金、个税、部门成本分摊和工资凭证是财务人员每月都会处理的高频刚需，边界清晰、价值明显、适合作为财务 AI 助手的第一个落地模块。 + +## 6. 第一模块核心功能：薪酬财务对账 + +### 6.1 薪酬数据智能识别 + +用户上传 Excel 后，AI 自动识别字段含义，例如： + +- 员工姓名 +- 工号 +- 部门 +- 岗位 +- 应发工资 +- 实发工资 +- 个税 +- 社保个人部分 +- 社保公司部分 +- 公积金个人部分 +- 公积金公司部分 +- 奖金 +- 提成 +- 扣款 + +即使不同企业的表头命名不一致，也可以通过 AI 做字段映射。 + +### 6.2 薪酬与社保个税对账 + +自动检查常见异常，例如： + +- 离职员工仍有工资发放 +- 入职员工未缴社保 +- 已离职员工社保未停缴 +- 个税金额与工资数据不匹配 +- 社保基数异常波动 +- 公积金缴纳比例异常 +- 部门归属为空或与上月不一致 +- 银行实发金额与工资表实发金额不一致 + +### 6.3 人工成本分析 + +自动生成月度人工成本分析，例如： + +- 本月人工成本总额 +- 与上月相比的变化金额和变化比例 +- 按部门拆分的人工成本 +- 按费用科目拆分的人工成本 +- 新增员工带来的成本变化 +- 离职员工带来的成本减少 +- 奖金、提成、补贴等特殊项目影响 + +财务人员可以直接复制到月度经营分析或老板汇报中。 + +### 6.4 金蝶凭证模板导出 + +根据企业配置，自动生成可导入金蝶的凭证模板，例如： + +- 工资计提凭证 +- 工资发放凭证 +- 个税计提或代扣凭证 +- 社保公司部分凭证 +- 社保个人部分凭证 +- 公积金公司部分凭证 +- 公积金个人部分凭证 +- 部门费用分摊凭证 + +典型凭证方向： + +```text +借：管理费用-工资 +借：销售费用-工资 +借：研发费用-工资 +贷：应付职工薪酬-工资 +``` + +```text +借：应付职工薪酬-工资 +贷：银行存款 +贷：其他应付款-社保个人部分 +贷：其他应付款-公积金个人部分 +贷：应交税费-个人所得税 +``` + +### 6.5 自动文件夹监控（第二阶段功能） + +**核心价值**：最大化便利财务人员，无需手动上传。 + +**工作方式**： + +1. **约定文件夹结构**： +``` +薪财通AI/ +├── 2024年/ +│ ├── 01月/ +│ │ ├── 输入/ +│ │ │ ├── 工资表.xlsx （必需） +│ │ │ ├── 社保表.xlsx （必需） +│ │ │ ├── 个税表.xlsx （必需） +│ │ │ ├── 公积金表.xlsx （可选） +│ │ │ ├── 考勤表.xlsx （可选，用于异常检测） +│ │ │ ├── 银行发放回单.xlsx （可选，用于对账） +│ │ │ ├── 人员变动表.xlsx （可选，入职/离职/调岗） +│ │ │ └── 绩效提成表.xlsx （可选，特殊薪资项） +│ │ └── 输出/ +│ │ ├── 1_异常清单_20240105.xlsx +│ │ ├── 2_对账报告_20240105.xlsx +│ │ ├── 3_人工成本分析_20240105.xlsx +│ │ ├── 4_金蝶凭证_20240105.xlsx +│ │ ├── 5_部门成本明细_20240105.xlsx +│ │ ├── 6_员工薪酬汇总_20240105.xlsx +│ │ └── 处理日志_20240105.txt +│ ├── 02月/ +│ └── 03月/ +├── 2025年/ +│ ├── 01月/ +│ └── 02月/ +``` + +**输入文件说明**： + +| 文件名 | 必需性 | 用途 | 典型字段 | +| --- | --- | --- | --- | +| 工资表 | ✅ 必需 | 核心薪酬数据 | 姓名、工号、部门、基本工资、奖金、应发、实发 | +| 社保表 | ✅ 必需 | 社保缴纳核对 | 姓名、工号、社保基数、个人部分、公司部分 | +| 个税表 | ✅ 必需 | 个税申报核对 | 姓名、工号、应税收入、已缴个税、税后收入 | +| 公积金表 | ⭕ 可选 | 公积金核对 | 姓名、工号、公积金基数、个人部分、公司部分 | +| 考勤表 | ⭕ 可选 | 验证工资合理性 | 姓名、工号、出勤天数、请假天数、加班时数 | +| 银行回单 | ⭕ 可选 | 实发金额对账 | 姓名、银行账号、实际到账金额 | +| 人员变动表 | ⭕ 可选 | 异常检测依据 | 姓名、工号、变动类型（入职/离职/调岗）、生效日期 | +| 绩效提成表 | ⭕ 可选 | 特殊薪资项 | 姓名、工号、绩效奖金、销售提成、项目奖金 | + +**输出文件说明**： + +| 文件名 | 内容 | 面向用户 | +| --- | --- | --- | +| 1_异常清单 | 离职未停社保、个税不匹配、工资异常等 | 财务+HR | +| 2_对账报告 | 工资表 vs 社保表 vs 个税表 vs 银行回单的差异 | 财务主管 | +| 3_人工成本分析 | 本月总成本、环比变化、部门拆分、原因分析 | 财务+老板 | +| 4_金蝶凭证 | 可直接导入金蝶的凭证模板（多个分录） | 财务会计 | +| 5_部门成本明细 | 每个部门的人员、工资、社保、个税明细 | 部门负责人 | +| 6_员工薪酬汇总 | 每个员工的完整薪酬构成（应发、扣款、实发） | 财务+HR | +| 处理日志 | 处理过程、识别的表格、检测到的问题、处理时间 | 技术支持 | + +2. **自动监控与输出机制**： + - 财务人员将文件放入 `输入/` 子文件夹 + - 系统每天定时扫描（如每晚 22:00） + - 检测到新文件后，自动触发处理流程 + - 处理完成后，自动将结果保存到 `输出/` 子文件夹 + - 输出文件自动带时间戳，避免覆盖历史结果 + - 第二天早上打开文件夹，输入和输出都在同一个月份下 + +3. **输出文件规则**： + - **1_异常清单**：`1_异常清单_YYYYMMDD.xlsx` + - 离职员工仍有工资/社保 + - 个税与工资不匹配 + - 社保基数异常波动 + - 银行实发与工资表不一致 + - 部门归属为空或变化 + + - **2_对账报告**：`2_对账报告_YYYYMMDD.xlsx` + - 工资表 vs 社保表人员差异 + - 工资表 vs 个税表金额差异 + - 工资表 vs 银行回单实发差异 + - 汇总对账结果和差异原因 + + - **3_人工成本分析**：`3_人工成本分析_YYYYMMDD.xlsx` + - 本月人工成本总额（工资+社保+公积金） + - 环比变化金额和比例 + - 按部门拆分的成本明细 + - 按费用科目拆分（管理/销售/研发） + - 新增/离职员工影响分析 + + - **4_金蝶凭证**：`4_金蝶凭证_YYYYMMDD.xlsx` + - 工资计提凭证 + - 工资发放凭证 + - 社保凭证（公司部分+个人部分） + - 公积金凭证 + - 个税代扣凭证 + - 部门费用分摊凭证 + + - **5_部门成本明细**：`5_部门成本明细_YYYYMMDD.xlsx` + - 每个部门的人数、人员名单 + - 部门工资总额、社保总额、公积金总额 + - 部门成本环比变化 + - 便于部门负责人核对 + + - **6_员工薪酬汇总**：`6_员工薪酬汇总_YYYYMMDD.xlsx` + - 每个员工的完整薪酬构成 + - 应发工资明细（基本工资、奖金、补贴） + - 扣款明细（社保个人、公积金个人、个税） + - 实发金额 + - 便于HR核对和员工查询 + + - **处理日志**：`处理日志_YYYYMMDD.txt` + - 处理开始和完成时间 + - 识别到的输入文件列表 + - 字段映射结果 + - 检测到的异常数量 + - 生成的输出文件列表 + - 错误和警告信息 + + 文件名前缀数字表示推荐查看顺序，时间戳使用处理完成时间 + +4. **支持多种部署方式**： + - **云端同步**：支持网盘（坚果云、阿里云盘、百度网盘）自动同步 + - **本地监控**：安装桌面客户端，监控本地文件夹 + - **企业网盘**：对接企业微盘、飞书云文档、企业微信文件 + +5. **智能识别文件类型**： + - 自动识别"工资表"、"社保表"、"个税表" + - 支持多种命名规则：`工资表.xlsx`、`2024年1月工资.xls`、`salary_202401.csv` + - 一个文件夹可以放多个版本，系统自动选择最新的 + +6. **处理状态提醒**： + - 微信/企业微信通知："您的 2024 年 3 月薪酬数据已处理完成，结果已保存到输出文件夹" + - 邮件通知：附带异常清单和成本分析摘要，以及文件夹路径 + - 系统内消息：详细的处理日志和结果文件列表 + +**使用场景**： + +- **场景 1**：每月 5 号，HR 把工资表发给财务 + - 财务收到后，直接保存到 `薪财通AI/2024年/03月/输入/` 文件夹 + - 当晚 22:00 系统自动处理 + - 第二天上班，打开 `输出/` 文件夹查看结果 + - 异常清单、成本分析、凭证模板都已生成好 + - 直接用凭证模板导入金蝶，完成入账 + +- **场景 2**：社保个税数据陆续到达 + - 5 号收到工资表 → 放入 `输入/` 文件夹，当晚生成初步结果 + - 10 号收到社保表 → 补充到 `输入/` 文件夹，系统重新处理 + - 15 号收到个税表 → 再次补充，系统再次更新结果 + - 每次处理都会在 `输出/` 中生成新的文件（带时间戳） + - 财务可以对比不同版本的结果 + +- **场景 3**：发现数据错误需要更正 + - 直接替换 `输入/` 文件夹中的错误文件 + - 系统检测到文件更新时间变化 + - 自动重新处理，生成新的输出文件 + - 无需手动操作，也无需登录系统 + +- **场景 4**：月末归档和审计 + - 每个月的输入和输出文件都在同一个文件夹下 + - 便于归档和审计追溯 + - 可以随时查看历史月份的处理结果 + - 支持导出整个月份文件夹作为备份 + +**与手动上传下载的对比**： + +| 对比项 | 手动上传下载 | 自动监控输出 | +| --- | --- | --- | +| 上传步骤 | 登录系统 → 找到上传入口 → 选择文件 → 等待上传 | 直接保存文件到输入文件夹 | +| 下载步骤 | 登录系统 → 找到结果页面 → 逐个下载文件 | 直接打开输出文件夹查看 | +| 学习成本 | 需要熟悉系统界面 | 只需记住文件夹结构 | +| 处理时机 | 必须手动触发 | 自动定时处理 | +| 多人协作 | 需要账号权限 | 共享文件夹即可 | +| 文件管理 | 输入输出文件散落各处 | 统一按年月归档，输入输出在一起 | +| 历史追溯 | 需要在系统中查询 | 直接打开历史文件夹 | + +**实施优先级**： + +- **MVP 阶段**：手动上传（快速验证） +- **第二阶段**：增加自动监控功能（提升留存） +- **第三阶段**：支持企业网盘集成（服务大客户） + +### 6.6 自然语言问答 + +财务人员可以直接追问： + +- 为什么销售部工资比上月多 8 万？ +- 哪些员工本月工资异常？ +- 哪些员工社保和工资月份不一致？ +- 帮我按研发、销售、管理费用拆分工资凭证。 +- 本月人工成本上涨的主要原因是什么？ +- 哪些部门的社保成本变化最大？ + +## 7. 与金蝶的互补关系 + +薪财通 AI 与金蝶不是替代关系，而是互补关系。 + +| 金蝶负责 | 薪财通 AI 负责 | +| --- | --- | +| 账套管理 | 薪酬数据整理 | +| 凭证入账 | 凭证生成前的核对与解释 | +| 财务报表 | 人工成本专项分析 | +| 企业经营数据沉淀 | HR 与财务口径转换 | +| ERP/进销存/云会计流程 | Excel、HR 数据和社保个税数据清洗 | + +金蝶更像企业的正式财务系统，薪财通 AI 更像财务人员身边的月度薪酬对账助手。 + +## 8. 最小可行产品 MVP + +第一版不需要做完整 HR SaaS，也不需要打通所有金蝶接口。 + +### 8.1 核心功能 + +建议 MVP 只做 5 个功能： + +1. **手动上传表格**：支持工资表、社保表、个税表上传（Web 界面拖拽上传） +2. **AI 自动识别字段**：识别表格口径和字段映射 +3. **生成异常清单**：自动检测常见异常并输出清单 +4. **生成人工成本分析**：本月成本总额、环比变化、部门拆分 +5. **导出金蝶凭证模板**：生成可导入金蝶的 Excel 凭证模板 + +**MVP 输出文件（3 个）**： +- 异常清单.xlsx +- 人工成本分析.xlsx +- 金蝶凭证.xlsx + +**第二阶段新增输出（4 个）**： +- 对账报告.xlsx（工资 vs 社保 vs 个税 vs 银行回单） +- 部门成本明细.xlsx（便于部门负责人核对） +- 员工薪酬汇总.xlsx（便于 HR 核对） +- 处理日志.txt（技术支持用） + +**MVP 不做的功能**： +- ❌ 自动文件夹监控（第二阶段再做，避免复杂度） +- ❌ 可选输入文件支持（公积金、考勤、银行回单等，第二阶段支持） +- ❌ 金蝶 API 直接对接（先验证需求） +- ❌ 移动端（优先 PC Web） +- ❌ 复杂审批流（中小企业不需要） + +第一版用 Excel 上传和 Excel 导出完成闭环，验证核心价值后再迭代。 + +**为什么 MVP 先用手动上传？** +1. **快速验证**：3 个月内上线，验证用户是否愿意付费 +2. **降低复杂度**：自动监控需要桌面客户端或网盘集成，开发周期长 +3. **了解用户习惯**：通过手动上传观察用户真实使用场景，再优化自动化方案 +4. **技术风险小**：Web 上传是成熟技术，稳定性高 + +### 8.2 MVP 验证指标 + +**核心验证指标**： + +1. **首月留存率 > 60%** + 用户愿意在第二个月继续使用，说明产品解决了真实痛点。 + +2. **平均完成时间 < 30 分钟** + 从上传表格到导出凭证，整个流程要比传统方式（3 天）快得多。 + +3. **异常识别准确率 > 90%** + AI 识别的异常必须准确，否则误报会增加用户工作量。 + +4. **NPS > 40** + 用户愿意推荐给同行，说明产品有口碑传播价值。 + +5. **获客速度验证** + 3 个月内获得 20+ 付费客户，验证市场需求和获客渠道有效性。 + +**快速失败信号**： + +- 用户只用一次就流失 → 价值不够或体验太差 +- 3 个月内获客 < 20 家 → 渠道或定价有问题 +- 异常识别误报率 > 30% → AI 能力需要重构 +- 用户反馈"还不如手工做" → 产品方向错误 + +### 8.3 第一批种子用户策略 + +**目标**：找到 5-10 家愿意深度参与的种子用户。 + +**选择标准**： +- 50-200 人规模中小企业 +- 已使用金蝶云星辰或金蝶精斗云 +- 财务人员每月在薪酬对账上花费 2 天以上 +- 愿意每月参与反馈会议 + +**合作方式**： +- 提供 3 个月免费使用 + 专属客服 +- 每月 1 次深度反馈会议 +- 允许做案例宣传和推荐背书 +- 优先获得新功能体验资格 + +**预期收获**： +- 打磨产品体验和 AI 准确率 +- 积累行业标准化流程和规则库 +- 获得真实案例和客户推荐 +- 验证商业模式和定价策略 + +## 9. 产品边界与长期战略 + +### 9.1 永远不做（避免与金蝶竞争） + +- **账套管理**：这是金蝶的核心能力 +- **财务报表生成**：总账、资产负债表、利润表、现金流量表 +- **审计追踪与合规**：需要金融级安全认证 +- **ERP 和进销存**：供应链管理不是我们的优势 + +### 9.2 第一阶段应该做（MVP） + +- 薪酬表识别（AI 字段映射） +- 社保个税对账（异常检测） +- 异常提醒（规则引擎 + 机器学习） +- 人工成本分析（数据聚合与解释） +- 金蝶凭证模板导出（模板引擎） +- 自然语言问答（限定在数据层面的问题） + +### 9.3 暂时不做（第一阶段） + +- 完整 HR 系统（招聘、绩效、考勤） +- 完整财务软件 +- 替代金蝶记账 +- 银行支付系统（需要金融牌照） +- 个税直接申报（需要对接税务系统） +- 社保公积金直接申报 +- 复杂审批流 + +### 9.4 第二阶段可以做（6-12 个月） + +- **与金蝶 API 打通**：自动读取科目表、自动推送凭证 +- **多账套支持**：集团企业或代账公司场景 +- **历史数据分析**：同比、环比、趋势预测 +- **自定义规则引擎**：企业可以自定义异常检测规则 +- **移动端支持**：老板随时查看人工成本分析 + +### 9.5 第三阶段可以做（12-24 个月） + +- **行业化模板**：制造业、服务业、科技公司、零售业 +- **费用报销对账**：从薪酬扩展到差旅、采购等其他费用 +- **往来对账**：应收应付、预收预付 +- **AI 财务顾问**：基于数据提供经营建议 + +### 9.6 自然语言问答边界 + +为了避免过度承诺，AI 问答需要明确边界： + +**能回答（数据层面）**： +- "为什么这个月工资多了 8 万？"→ 分析人员变化、薪资调整 +- "哪些员工本月工资异常？"→ 列出异常清单 +- "销售部人工成本占比是多少？"→ 计算部门成本占比 + +**不能回答（专业判断）**： +- "这笔凭证应该怎么做？"→ 需要财务专业判断 +- "我们公司应该用什么会计准则？"→ 超出产品范围 +- "个税政策怎么理解？"→ 建议咨询税务师 + +**提供建议但不决策（辅助决策）**： +- "建议检查这 3 个员工的社保状态"→ 异常提醒 +- "建议按部门重新分摊工资"→ 提供分摊方案 +- "建议核对离职员工的最后一笔工资"→ 风险提示 + +## 10. 可包装的产品 SKU + +### 10.1 薪酬凭证助手 + +面向每月需要生成工资相关凭证的财务人员。 + +核心价值： + +- 自动生成工资计提凭证 +- 自动生成工资发放凭证 +- 自动拆分部门费用 +- 导出金蝶可导入模板 + +### 10.2 人力成本解释助手 + +面向财务主管和老板汇报场景。 + +核心价值： + +- 自动分析人工成本变化 +- 解释部门成本波动 +- 生成月度人工成本说明 +- 支持自然语言追问 + +### 10.3 社保个税稽核助手 + +面向薪酬、社保、个税风险检查场景。 + +核心价值： + +- 检查工资与个税差异 +- 检查工资与社保差异 +- 检查员工状态异常 +- 输出风险清单 + +## 11. 商业化策略 + +### 11.1 目标客群 + +优先面向以下企业： + +- 50-500 人规模的中小企业 +- 已经使用金蝶财务软件（云星辰、精斗云、K/3 等） +- 财务和 HR 分工不清晰，财务需要处理薪酬数据 +- 工资、社保、个税仍大量依赖 Excel +- 每月人工成本分析压力较大 + +### 11.2 定价策略（按价值定价） + +**免费版**： +- **适用人数**：10 人以内 +- **核心功能**：表格上传 + 字段识别 + 基础异常检查 +- **目的**：获客、口碑传播、让用户体验核心价值 +- **限制**：不保存历史数据、不支持自定义规则 + +**基础版**： +- **价格**：299 元/月（3,588 元/年，节省 1 个月费用） +- **适用人数**：100 人以内 +- **核心功能**： + - 上传工资、社保、个税表格 + - AI 字段识别 + - 异常检测与清单生成 + - 基础人工成本分析 + - 金蝶凭证模板导出 +- **目标客户**：50 人以下小微企业 + +**专业版**： +- **价格**：699 元/月（8,388 元/年） +- **适用人数**：300 人以内 +- **核心功能**：基础版 + + - 历史数据保存（12 个月） + - 环比同比分析 + - 自定义科目映射 + - 自定义部门归属规则 + - 自然语言问答 + - 优先客服支持 +- **目标客户**：100-300 人中小企业 + +**企业版**： +- **价格**：1,999 元/月（23,988 元/年） +- **适用人数**：1000 人以内 +- **核心功能**：专业版 + + - 多账套支持（集团企业、子公司） + - 历史数据保存（36 个月） + - API 对接支持 + - 自定义异常检测规则 + - 专属客户成功经理 + - 月度经营分析报告 +- **目标客户**：500-1000 人企业、代账公司 + +**定价锚定对比**： + +| 对比项 | 传统方式 | 薪财通 AI | +| --- | --- | --- | +| 财务人员时间成本 | 2-3 天 × 200元/小时 = 3,200-4,800 元/月 | 0.5 小时 × 200元/小时 = 100 元/月 | +| 月度费用 | 3,200-4,800 元 | 299-1,999 元 | +| 年度节省 | - | 36,000-54,000 元 | +| 错误风险 | 人工容易出错 | AI 准确率 > 90% | + +**ROI 计算**： +- 100 人企业使用基础版：年费 3,588 元，节省人力成本 36,000 元，ROI = 900% +- 300 人企业使用专业版：年费 8,388 元，节省人力成本 48,000 元，ROI = 470% + +### 11.3 获客渠道（优先级排序） + +**渠道 1：金蝶代理商合作（最快、最精准）** + +- **合作模式**： + - 给代理商 20-30% 销售分成 + - 提供联合营销素材和客户案例 + - 代理商可以打包销售（金蝶软件 + 薪财通 AI） + +- **为什么有效**： + - 代理商直接触达金蝶现有客户 + - 客户已经有财务软件使用习惯 + - 代理商有信任背书 + +- **行动计划**： + - 第 1 个月：找到 3-5 家金蝶区域代理商 + - 第 2-3 个月：联合推广，获得首批客户 + - 第 4-6 个月：复制成功模式，扩展到更多代理商 + +**渠道 2：财税服务商合作（代账公司、税务师事务所）** + +- **合作模式**： + - 按客户数分成，每个客户 30-50 元/月 + - 代账公司可以批量使用企业版 + +- **为什么有效**： + - 代账公司服务大量中小企业 + - 薪财通 AI 可以提升他们的服务效率 + - 他们愿意为提效工具付费 + +- **行动计划**： + - 找到 10-20 家代账公司试用 + - 按客户数量阶梯定价 + - 提供批量管理后台 + +**渠道 3：内容营销（建立专业形象）** + +- **平台选择**： + - 知乎：回答"金蝶使用技巧"、"财务工作效率"相关问题 + - 公众号：发布"金蝶凭证模板"、"薪酬对账指南"等干货 + - 小红书/抖音：短视频演示"3 分钟完成薪酬对账" + +- **内容策略**： + - 不直接推销产品，先提供价值 + - 建立"金蝶用户薪酬对账专家"的人设 + - 在内容中自然植入产品 + +- **转化路径**： + - 内容吸引 → 关注公众号 → 领取免费工具 → 引导付费 + +**渠道 4：免费工具获客（低成本获客）** + +- **工具想法**： + - "金蝶凭证模板生成器"（免费） + - "薪酬异常检测器"（免费） + - "人工成本计算器"（免费） + +- **转化逻辑**： + - 免费工具解决小问题，建立信任 + - 体验后发现完整版更好用 + - 引导升级到付费版 + +**渠道 5：线下活动（建立深度信任）** + +- **活动形式**： + - 金蝶用户交流会（与代理商联合举办） + - 财务沙龙（邀请财务总监分享经验） + - 产品体验会（现场演示 + 现场答疑） + +- **目标**： + - 获得高质量客户 + - 收集产品反馈 + - 建立行业口碑 + +### 11.4 增长飞轮设计 + +构建可持续的增长循环： + +``` +1. 获客（免费版 + 代理商推荐） + ↓ +2. 激活（新手引导 + 首月成功案例） + ↓ +3. 留存（记住企业规则 + 历史数据对比）← 切换成本 + ↓ +4. 变现（按功能和人数分层定价） + ↓ +5. 推荐（NPS 调研 + 推荐奖励） + ↓ +6. 扩展（从薪酬到费用、往来对账） + ↓ +回到 1（老客户推荐新客户） +``` + +**关键增长机制**： + +1. **降低获客成本**： + - 免费版作为流量入口 + - 代理商渠道批量获客 + - 老客户推荐奖励（推荐成功，双方各得 1 个月免费） + +2. **提升激活率**： + - 新用户注册后，7 天内必须完成一次完整流程 + - 提供示例数据，让用户快速体验 + - 客服主动联系，协助首次使用 + +3. **提升留存率**： + - 记住企业的科目映射和部门归属（切换成本） + - 保存历史数据，做环比同比分析（沉淀价值） + - 每月自动生成月报，持续提供价值 + +4. **提升付费率**： + - 免费版功能有限，核心功能在付费版 + - 按人数和功能阶梯定价，让客户自然升级 + - 年付赠送 1-2 个月，提升 LTV + +5. **推荐机制**： + - NPS 调研，找到超级用户 + - 推荐奖励：推荐 1 个客户，双方各得 1 个月免费 + - 案例库：允许做案例展示的客户，给额外折扣 + +6. **产品扩展**： + - 从薪酬对账扩展到费用报销对账 + - 从工资凭证扩展到采购凭证、销售凭证 + - 从单一工具变成"金蝶财务助手套件" + +## 12. 为什么不建议一开始做其他方向 + +### 不建议做“AI 财务软件” + +这个方向太大，且容易与金蝶正面竞争。中小企业不会轻易更换财务系统，获客难度和信任成本都很高。 + +### 不建议做“完整 HR SaaS” + +完整 HR 系统需要覆盖招聘、入职、考勤、绩效、薪酬、组织、审批等大量模块，开发和销售周期都较长。 + +### 不建议先做“老板经营驾驶舱” + +驾驶舱依赖高质量经营数据。中小企业数据基础薄弱，如果没有先解决数据清洗和口径统一，很容易变成好看但不实用的展示页。 + +## 13. 推荐落地路线 + +### 第 1 阶段：薪酬财务对账 Excel 闭环 + +目标：验证财务人员是否愿意为薪酬对账和凭证生成付费。 + +交付能力： + +- 上传工资表、社保表、个税表 +- 自动识别字段 +- 生成异常清单 +- 导出金蝶凭证模板 + +### 第 2 阶段：薪酬模块历史对比与自动化 + +目标：提升复购和粘性，降低使用门槛。 + +交付能力： + +- **保存历史月份数据**：支持 12 个月历史数据查询 +- **自动对比环比变化**：与上月数据自动对比，生成变化分析 +- **记住企业规则**：科目映射规则、部门归属规则自动应用 +- **自动文件夹监控**（核心新功能）： + - 支持本地文件夹监控（桌面客户端） + - 支持网盘同步（坚果云、阿里云盘） + - 财务人员只需将文件保存到 `薪财通AI/2024年/03月/输入/` 文件夹 + - 系统每晚自动扫描并处理新文件 + - 处理结果自动保存到 `薪财通AI/2024年/03月/输出/` 文件夹 + - 第二天早上打开文件夹即可查看结果 + - 微信/邮件通知处理完成 + +**为什么第二阶段做自动监控？** + +1. **MVP 已验证核心价值**：用户愿意为产品付费 +2. **留存率数据支持**：如果首月留存 > 70%，说明值得投入体验优化 +3. **降低流失风险**：手动上传是流失点，自动化可以大幅提升留存 +4. **建立切换成本**：用户习惯文件夹结构后，不愿换其他产品 + +### 第 3 阶段：金蝶生态连接 + +目标：从单点工具变成金蝶生态的补充应用。 + +交付能力： + +- 对接金蝶导入模板/API +- 支持多账套配置 +- 支持不同金蝶产品版本的凭证格式 +- 与代理商、财税服务商合作获客 + +### 第 4 阶段：财务 AI 助手扩展 + +目标：从薪酬财务对账扩展为覆盖多类财务高频工作的 AI 助手。 + +交付能力： + +- **发票与报销 AI 助手**：发票识别、真伪核验、报销单匹配、费用凭证生成 +- **预算执行 AI 分析**：预算表导入、实际发生对比、超预算提醒、差异解释 +- **现金流异常 AI 监控**：银行流水导入、资金属性识别、可动用资金分析、异常提醒 +- **往来对账 AI 助手**：客户/供应商往来、发票、回款、付款自动匹配 +- **经营分析 AI 看板**：经营摘要、费用趋势、异常追踪、老板报表 + +## 14. 技术架构建议 + +### 14.1 核心技术选型 + +**AI 能力层**： + +1. **表格识别与字段映射** + - 技术方案：LLM（GPT-4 或国产大模型） + - 能力：语义理解，识别"基本工资"、"底薪"、"固定工资"是同一字段 + - 备选方案：规则引擎 + 机器学习（降低成本） + +2. **异常检测** + - 第一阶段：规则引擎（if-then 逻辑） + - 第二阶段：规则 + 机器学习（基于历史数据训练） + - 能力：识别离职未停社保、个税不匹配、异常波动 + +3. **凭证生成** + - 技术方案：模板引擎 + 企业规则库 + - 能力：根据企业配置，自动生成借贷方科目 + - 灵活性：支持自定义科目映射 + +4. **自然语言问答** + - 技术方案：RAG（检索增强生成）架构 + - 数据源：企业历史数据 + 薪酬知识库 + - 边界：只回答数据层面问题，不做专业判断 + +### 14.2 数据流设计 + +``` +Excel 上传 + ↓ +1. 文件解析（支持 xls/xlsx/csv） + ↓ +2. 字段识别（AI 语义理解） + ↓ +3. 字段映射确认（用户确认或修正） + ↓ +4. 数据清洗（去重、格式统一） + ↓ +5. 异常检测（规则引擎） + ↓ +6. 异常处理决策（用户处理或忽略） + ↓ +7. 成本分析（数据聚合与计算） + ↓ +8. 凭证生成（模板引擎） + ↓ +9. 凭证科目确认（用户确认） + ↓ +10. 导出金蝶模板（Excel/CSV） +``` + +**关键设计原则**： +- 每个环节都有"人工确认点"，AI 辅助决策但不替代决策 +- 记住企业的确认历史，下次自动应用（减少确认次数） +- 支持批量处理，一次上传多个表格 + +### 14.3 数据安全设计 + +薪酬数据高度敏感，必须从第一天就考虑安全： + +**1. 数据存储安全** +- 数据库字段加密（AES-256） +- 员工姓名脱敏展示（张**、李**） +- 定期备份，支持灾难恢复 + +**2. 数据传输安全** +- HTTPS 加密传输 +- 文件上传加密 +- API 接口鉴权 + +**3. 数据访问控制** +- 多租户严格隔离（企业 A 看不到企业 B 的数据） +- 按角色权限控制： + - 财务主管：全部权限 + - 总账会计：查看和编辑权限 + - 出纳：仅查看权限 + - HR：仅上传权限（可选） + +**4. 审计日志** +- 记录谁在什么时间访问了哪些数据 +- 记录谁做了哪些操作（上传、导出、修改） +- 日志保留 3 年，满足合规要求 + +**5. 合规认证（未来）** +- 等保三级认证（如果面向大客户） +- ISO 27001 信息安全管理体系 +- 支持私有化部署（大客户要求） + +**6. 数据删除机制** +- 支持用户主动删除历史数据 +- 企业注销后 30 天内自动删除所有数据 +- 符合《个人信息保护法》要求 + +### 14.4 技术团队能力要求 + +**第一阶段团队（MVP）**： + +1. **产品经理 × 1** + - 懂财务和 HR 业务逻辑 + - 有 SaaS 产品经验 + - 能够与客户深度沟通需求 + +2. **全栈工程师 × 2** + - 前端：React/Vue 开发经验 + - 后端：Python/Node.js 开发经验 + - 数据库：MySQL/PostgreSQL + - 能够快速搭建 MVP + +3. **AI 工程师 × 1** + - LLM 应用开发经验 + - 熟悉 RAG 架构 + - 能够做 Prompt 工程和模型调优 + +4. **客户成功 × 1**（兼职或外包） + - 能够手把手教客户使用 + - 收集产品反馈 + - 处理客户问题 + +**第二阶段团队（扩展期）**： + +增加： +- 算法工程师 × 1（优化异常检测） +- 测试工程师 × 1（保证质量） +- 销售 × 2-3（拓展代理商渠道） +- 客户成功 × 2-3（服务更多客户） + +最值得做的产品不是一开始就做“大而全的 AI 财务软件”，而是： + +**先做面向金蝶中小企业客户的财务 AI 助手，并从薪酬财务对账这个高频刚需模块切入。** + +这个方向有三个优点： + +1. **足够刚需**：薪酬、社保、个税、凭证每月都会发生，财务人员痛感强。 +2. **足够聚焦**：第一模块可以从 Excel 上传和凭证导出开始，不需要重建完整系统。 +3. **具备扩展空间**：薪酬对账验证成功后，可自然扩展到发票报销、预算执行、现金流异常、往来对账和经营分析。 + +建议把项目定义为： + +> 财务 AI 助手：金蝶中小企业客户的财务数据整理、对账、解释与凭证生成助手。 + +建议把第一个产品模块定义为： + +> 薪财通 AI：财务 AI 助手的第一模块，专注薪酬对账、人工成本分析与金蝶凭证生成。 + +## 15. 风险与应对 + +### 15.1 技术风险 + +**风险 1：AI 识别准确率不足** +- **表现**：字段识别错误率 > 20%，用户需要大量修正 +- **应对**： + - 前期积累行业标准模板库（制造业、服务业等） + - 用户确认后，记住企业规则，下次自动应用 + - 提供"一键修正"功能，降低用户修正成本 + - 持续训练模型，提升准确率 + +**风险 2：异常检测误报率高** +- **表现**：把正常情况判断为异常，增加用户工作量 +- **应对**： + - 规则引擎可配置，允许企业自定义异常规则 + - 提供"忽略此类异常"功能 + - 基于用户反馈持续优化规则 + +**风险 3：数据安全事故** +- **表现**：数据泄露、被攻击、误删除 +- **应对**： + - 从第一天就做安全设计（加密、备份、审计） + - 购买网络安全保险 + - 定期安全审计和渗透测试 + - 建立应急响应机制 + +### 15.2 市场风险 + +**风险 1：金蝶推出类似功能** +- **影响**：最大的威胁，金蝶可以集成到自己的产品中 +- **应对**： + - **速度优势**：快速获得 1000+ 客户，建立先发优势 + - **生态壁垒**：与金蝶代理商深度绑定，形成渠道壁垒 + - **体验壁垒**：专注薪酬对账这一细分场景，体验比大而全的产品更好 + - **数据壁垒**：积累不同行业的薪酬规则库和异常模式 + - **备选方案**：如果金蝶真的推出，可以考虑被收购 + +**风险 2：市场需求不足** +- **表现**：3 个月获客 < 20 家，用户流失率 > 60% +- **应对**： + - **快速验证**：MVP 只做 3 个月，如果不行就调整方向 + - **深度访谈**：找到真正的痛点，调整产品定位 + - **备选方向**：从薪酬对账转向费用报销对账或往来对账 + +**风险 3：定价过高或过低** +- **表现**：过高导致获客困难，过低导致收入不足 +- **应对**： + - **A/B 测试**：在不同渠道测试不同定价 + - **灵活调整**：前 6 个月可以快速调整定价策略 + - **价值锚定**：用"节省人力成本"说服客户 + +### 15.3 合规风险 + +**风险 1：数据泄露导致法律责任** +- **应对**： + - 购买网络安全保险 + - 与客户签订数据安全协议 + - 符合《个人信息保护法》和《数据安全法》 + +**风险 2：财务合规性问题** +- **表现**：AI 生成的凭证不符合会计准则 +- **应对**： + - 产品定位是"辅助工具"，最终决策权在财务人员 + - 提供凭证预览和确认环节 + - 与专业会计师事务所合作，确保凭证模板合规 + +### 15.4 运营风险 + +**风险 1：客户成功成本过高** +- **表现**：每个客户都需要大量人工服务，规模不经济 +- **应对**： + - 标准化服务流程（新手引导、常见问题库） + - 客户自助服务（帮助中心、视频教程） + - 只有企业版客户才提供专属客服 + +**风险 2：代理商管理混乱** +- **表现**：代理商承诺过高、服务不到位 +- **应对**： + - 代理商认证和培训机制 + - 客户满意度调研，淘汰不合格代理商 + - 直销和渠道并行，避免过度依赖渠道 + +## 16. 关键里程碑与时间表 + +### M0：准备阶段（1 个月） + +**目标**：组建团队、确定技术方案 + +**关键任务**： +- 招聘产品经理、全栈工程师、AI 工程师 +- 确定技术栈和架构设计 +- 深度访谈 10-20 个潜在客户 +- 完成产品原型设计 + +**验收标准**： +- 团队到位 +- 产品原型通过客户验证 +- 技术方案评审通过 + +### M1-M3：MVP 开发（3 个月） + +**目标**：上线 MVP，获得 10 个付费客户 + +**关键任务**： +- 开发核心功能（上传、识别、异常检测、凭证导出） +- 找到 5-10 家种子用户，深度参与测试 +- 优化 AI 识别准确率（目标 > 90%） +- 上线基础版和专业版 + +**验收标准**： +- 产品上线并可正常使用 +- 获得 10 个付费客户（种子用户可以免费，但要承诺长期使用） +- 首月留存率 > 60% +- NPS > 40 + +**快速失败信号**： +- 如果 3 个月内获客 < 5 家，说明产品方向或渠道有问题 +- 如果用户流失率 > 60%，说明价值不够 + +### M4-M6：市场验证（3 个月） + +**目标**：月收入 10 万，验证商业模式 + +**关键任务**： +- 拓展金蝶代理商渠道（签约 5-10 家代理商） +- 优化产品体验和 AI 准确率 +- 建立内容营销体系（知乎、公众号） +- 推出免费版，作为流量入口 + +**验收标准**： +- 付费客户 > 100 家 +- 月收入 > 10 万（MRR） +- 首月留存率 > 70% +- 代理商渠道贡献 > 50% 收入 + +### M7-M12：规模化增长（6 个月） + +**目标**：月收入 50 万，开始扩展团队 + +**关键任务**： +- 扩展代理商网络（签约 30+ 代理商） +- 开发企业版功能（多账套、API 对接） +- 拓展财税服务商渠道（代账公司） +- 扩展团队（销售、客户成功） + +**验收标准**： +- 付费客户 > 500 家 +- 月收入 > 50 万（MRR） +- 年度 ARR > 600 万 +- 客户流失率 < 10% + +### M13-M24：生态建设（12 个月） + +**目标**：月收入 200 万，启动 A 轮融资 + +**关键任务**： +- 与金蝶官方达成生态合作 +- 推出行业化解决方案（制造业、服务业） +- 从薪酬对账扩展到费用对账、往来对账 +- 开发移动端和 API + +**验收标准**： +- 付费客户 > 2000 家 +- 月收入 > 200 万（MRR） +- 年度 ARR > 2400 万 +- 完成 A 轮融资（估值 1-2 亿） + +## 17. 竞争壁垒设计 + +要避免被金蝶或其他财务 SaaS 快速复制，需要建立护城河： + +### 17.1 数据壁垒 + +**策略**：积累不同行业的薪酬规则库和异常模式 + +**实施**： +- 每个客户使用后，记住其规则配置 +- 积累 1000+ 企业的数据后，可以做行业标准模板 +- 不同行业的薪酬结构差异大（制造业 vs 服务业 vs 科技公司） +- 新竞争对手需要从零开始积累 + +**时间窗口**：需要 1-2 年积累足够数据 + +### 17.2 生态壁垒 + +**策略**：与金蝶代理商深度绑定，获得渠道优势 + +**实施**： +- 签约 100+ 金蝶代理商，形成渠道垄断 +- 提供优厚的分成比例（20-30%） +- 联合营销，成为代理商的标配产品 +- 金蝶自己做类似产品，会破坏代理商利益 + +**时间窗口**：需要 6-12 个月建立渠道网络 + +### 17.3 体验壁垒 + +**策略**：AI 识别准确率和自然语言交互体验 + +**实施**： +- 持续优化 AI 模型，准确率 > 95% +- 自然语言问答体验流畅 +- 产品界面简洁，学习成本低 +- 新竞争对手很难在短时间内达到同样的体验 + +**时间窗口**：需要 6-12 个月持续优化 + +### 17.4 品牌壁垒 + +**策略**：成为"金蝶用户薪酬对账"的第一联想 + +**实施**： +- 内容营销：在知乎、公众号建立专业形象 +- 客户案例：积累 100+ 客户案例和推荐 +- 行业活动：参加金蝶用户大会、财务论坛 +- 口碑传播：NPS > 50，用户愿意主动推荐 + +**时间窗口**：需要 12-24 个月建立品牌认知 + +## 18. 三个最关键的优化建议 + +如果只能选择三个最重要的行动项，建议优先做： + +### 1. 定价锚定对比（说服力） + +不要只讲功能，要用"节省人力成本"来说服客户： + +- **计算器工具**：输入员工人数，自动计算每月节省的时间和金额 +- **对比表格**：传统方式 vs 薪财通 AI 的时间成本和错误风险 +- **ROI 数据**：年费 3,588 元，节省 36,000 元，ROI = 900% + +这是最快建立信任和促进成交的方式。 + +### 2. 金蝶代理商渠道（最快获客） + +这是最快触达目标客户的方式： + +- **第 1 个月**：找到 3-5 家金蝶区域代理商 +- **第 2-3 个月**：联合推广，获得首批 20-50 个客户 +- **第 4-6 个月**：复制成功模式，扩展到 10+ 代理商 + +代理商直接服务金蝶现有客户，信任成本低，转化率高。 + +### 3. 数据安全第一（避免后患） + +薪酬数据高度敏感，从 MVP 就要做好安全设计： + +- **数据加密**：数据库字段加密、传输加密 +- **访问控制**：多租户隔离、角色权限、审计日志 +- **合规准备**：符合《个人信息保护法》，支持数据删除 + +一旦发生数据泄露，产品信任会瞬间崩塌，无法挽回。 + +--- + +**文档优化完成。核心改进：** +1. 价值主张从"补充工具"升级为"3 天压缩到 30 分钟"的增效工具 +2. 补充 MVP 验证指标和快速失败信号 +3. 细化定价策略，增加 ROI 计算和锚定对比 +4. 具体化获客渠道，优先金蝶代理商合作 +5. 补充数据安全设计，从第一天就考虑合规 +6. 新增风险应对、关键里程碑和竞争壁垒章节 +7. 明确产品边界和长期战略规划 diff --git a/docs/财务痛点汇总.md b/docs/财务痛点汇总.md new file mode 100644 index 0000000..08badf5 --- /dev/null +++ b/docs/财务痛点汇总.md @@ -0,0 +1,397 @@ +# 财务 AI 助手：面向金蝶中小企业客户的财务自动化与对账助手 + +## 1. 产品结论 + +建议优先做一个可逐步扩展的 AI 产品： + +**面向金蝶中小企业客户的财务 AI 助手** + +它不是替代金蝶，而是作为金蝶财务产品的补充工具，先从中小企业财务人员每月高频、刚需、边界清晰的薪酬财务对账切入，再逐步扩展到发票报销、预算执行、现金流异常、往来对账和经营分析等财务辅助场景。 + +第一阶段切入模块： + +**薪酬-财务 AI 对账助手** + +一句话定位： + +> 给使用金蝶的中小企业财务人员使用的财务 AI 助手，第一阶段先解决薪酬对账、人工成本分析与凭证生成。 + +建议产品结构： + +```text +财务 AI 助手 +├── 第一模块：薪酬财务对账助手（先做） +├── 第二模块：发票与报销 AI 助手 +├── 第三模块：预算执行 AI 分析 +├── 第四模块：现金流异常 AI 监控 +├── 第五模块：往来对账 AI 助手 +└── 第六模块：经营分析 AI 看板 +``` + +建议第一模块产品名： + +**薪财通 AI** + +## 2. 为什么选择这个方向 + +金蝶的强项是企业经营管理软件、财务核算、ERP、进销存、云会计等结构化系统能力。对中小企业来说，金蝶通常承担账套、凭证、报表、和经营数据管理等核心角色。 + +但在实际业务中，财务人员每月仍然需要从 HR 或行政人员那里接收大量薪酬相关表格，例如： + +- 工资表 +- 社保明细 +- 公积金明细 +- 个税申报结果 +- 考勤表 +- 绩效或提成表 +- 员工入职、调岗、离职数据 + +这些数据往往来自不同系统或 Excel，字段口径不统一，人员状态复杂，部门归属经常变化。金蝶负责最终入账和核算，但“HR 数据到财务凭证之间”的整理、核对、解释和转换，仍然有大量人工工作。 + +这正是你们在人力资源领域的优势可以发挥的地方。 + +## 3. 目标用户 + +### 核心用户 + +中小企业财务人员，尤其是： + +- 财务主管 +- 总账会计 +- 出纳兼会计 +- 负责工资、社保、个税入账的财务人员 + +### 相关用户 + +- HR 薪酬专员 +- 行政人事 +- 企业老板或管理层 +- 外包记账公司 + +## 4. 用户痛点 + +中小企业财务人员在每月薪酬入账时，通常会遇到以下问题： + +1. **月度预算人工核算效率问题** + + 月度预算执行数据无法自动联动核算，每一笔费用需要人工核对预算。 + +2. **业务与财务系统无数据对接接口** + + 业财系统缺少对接接口，人工生成凭证效率低。 + +3. **发票真伪核验依赖人工网页查询** + + 报销发票真伪核验无自动化渠道，需人工登录网站逐张查询，耗费大量时间。 + +4. **凭证生成重复** + + 每月都要做工资计提、工资发放、个税、社保、公积金、资产摊销、等相关凭证，重复性强但容易出错。 + +5. **可视化差** + + 财务数据无法通过形成每天的报表观察企业运营情况，无法通过图形展示各个维度（包括业务类型与客户）的关键数据。 + +6. **财务与 业务 口径不一致** + + 业务 看的是到款月份；财务看到款与付款月份是否匹配。两边语言不同，沟通成本高。 +7. **无现金流异常的监控** + + 现有银行账户余额无法区分资金属性，其中沉淀的已收应收款、待付报销款及应付货款相互混杂，致使可自由动用净额难以精准界定。 + +## 5. 产品定位 + +财务 AI 助手定位为： + +**连接企业业务数据、财务数据与金蝶财务系统的 AI 中间层。** + +它不替代金蝶账套，也不替代完整 ERP / HR / OA 系统，而是解决一个更明确的问题： + +> 把分散在 Excel、业务系统、HR、银行流水、发票和报销材料中的半结构化数据，自动整理成财务可以核对、解释和导入金蝶的结构化结果。 + +第一阶段先做薪酬财务对账模块，因为薪酬、社保、公积金、个税、部门成本分摊和工资凭证是财务人员每月都会处理的高频刚需，边界清晰、价值明显、适合作为财务 AI 助手的第一个落地模块。 + +## 6. 第一模块核心功能：薪酬财务对账 + +第一阶段先做薪酬财务对账模块，作为财务 AI 助手的第一个落地场景。 + +### 6.1 薪酬数据智能识别 + +用户上传 Excel 后，AI 自动识别字段含义，例如： + +- 员工姓名 +- 工号 +- 部门 +- 岗位 +- 应发工资 +- 实发工资 +- 个税 +- 社保个人部分 +- 社保公司部分 +- 公积金个人部分 +- 公积金公司部分 +- 奖金 +- 提成 +- 扣款 + +即使不同企业的表头命名不一致，也可以通过 AI 做字段映射。 + +### 6.2 薪酬与社保个税对账 + +自动检查常见异常，例如： + +- 离职员工仍有工资发放 +- 入职员工未缴社保 +- 已离职员工社保未停缴 +- 个税金额与工资数据不匹配 +- 社保基数异常波动 +- 公积金缴纳比例异常 +- 部门归属为空或与上月不一致 +- 银行实发金额与工资表实发金额不一致 + +### 6.3 人工成本分析 + +自动生成月度人工成本分析，例如： + +- 本月人工成本总额 +- 与上月相比的变化金额和变化比例 +- 按部门拆分的人工成本 +- 按费用科目拆分的人工成本 +- 新增员工带来的成本变化 +- 离职员工带来的成本减少 +- 奖金、提成、补贴等特殊项目影响 + +财务人员可以直接复制到月度经营分析或老板汇报中。 + +### 6.4 金蝶凭证模板导出 + +根据企业配置，自动生成可导入金蝶的凭证模板，例如： + +- 工资计提凭证 +- 工资发放凭证 +- 个税计提或代扣凭证 +- 社保公司部分凭证 +- 社保个人部分凭证 +- 公积金公司部分凭证 +- 公积金个人部分凭证 +- 部门费用分摊凭证 + +典型凭证方向： + +```text +借：管理费用-工资 +借：销售费用-工资 +借：研发费用-工资 +贷：应付职工薪酬-工资 +``` + +```text +借：应付职工薪酬-工资 +贷：银行存款 +贷：其他应付款-社保个人部分 +贷：其他应付款-公积金个人部分 +贷：应交税费-个人所得税 +``` + +### 6.5 自然语言问答 + +财务人员可以直接追问： + +- 为什么销售部工资比上月多 8 万？ +- 哪些员工本月工资异常？ +- 哪些员工社保和工资月份不一致？ +- 帮我按研发、销售、管理费用拆分工资凭证。 +- 本月人工成本上涨的主要原因是什么？ +- 哪些部门的社保成本变化最大？ + +## 7. 与金蝶的互补关系 + +薪财通 AI 与金蝶不是替代关系，而是互补关系。 + +| 金蝶负责 | 薪财通 AI 负责 | +| --- | --- | +| 账套管理 | 薪酬数据整理 | +| 凭证入账 | 凭证生成前的核对与解释 | +| 财务报表 | 人工成本专项分析 | +| 企业经营数据沉淀 | HR 与财务口径转换 | +| ERP/进销存/云会计流程 | Excel、HR 数据和社保个税数据清洗 | + +金蝶更像企业的正式财务系统，薪财通 AI 更像财务人员身边的月度薪酬对账助手。 + +## 8. 最小可行产品 MVP + +第一版不需要做完整 HR SaaS，也不需要打通所有金蝶接口。 + +建议 MVP 只做 5 个功能： + +1. 上传工资表、社保表、个税表。 +2. AI 自动识别字段和表格口径。 +3. 生成异常清单。 +4. 生成本月人工成本分析。 +5. 导出金蝶凭证 Excel 模板。 + +第一版可以先不做复杂系统集成，先用 Excel 上传和 Excel 导出完成闭环。 + +## 9. 第一阶段产品边界 + +### 应该做 + +- 薪酬表识别 +- 社保个税对账 +- 异常提醒 +- 人工成本分析 +- 金蝶凭证模板导出 +- 自然语言解释 + +### 暂时不做 + +- 完整 HR 系统 +- 完整财务软件 +- 替代金蝶记账 +- 银行支付系统 +- 个税直接申报 +- 社保公积金直接申报 +- 复杂审批流 + +## 10. 可包装的产品 SKU + +### 10.1 薪酬凭证助手 + +面向每月需要生成工资相关凭证的财务人员。 + +核心价值： + +- 自动生成工资计提凭证 +- 自动生成工资发放凭证 +- 自动拆分部门费用 +- 导出金蝶可导入模板 + +### 10.2 人力成本解释助手 + +面向财务主管和老板汇报场景。 + +核心价值： + +- 自动分析人工成本变化 +- 解释部门成本波动 +- 生成月度人工成本说明 +- 支持自然语言追问 + +### 10.3 社保个税稽核助手 + +面向薪酬、社保、个税风险检查场景。 + +核心价值： + +- 检查工资与个税差异 +- 检查工资与社保差异 +- 检查员工状态异常 +- 输出风险清单 + +## 11. 商业化建议 + +### 11.1 目标客群 + +优先面向以下企业： + +- 50-500 人规模的中小企业 +- 已经使用金蝶财务软件 +- 财务和 HR 分工不清晰 +- 工资、社保、个税仍大量依赖 Excel +- 每月人工成本分析压力较大 + +### 11.2 收费方式 + +可以采用轻量 SaaS 订阅： + +- 基础版：按月上传表格和生成异常清单 +- 专业版：增加凭证模板导出和成本分析 +- 企业版：增加自定义科目、部门映射、历史趋势分析和多账套支持 + +也可以按员工人数收费： + +- 100 人以内 +- 300 人以内 +- 500 人以内 +- 1000 人以内 + +## 12. 为什么不建议一开始做其他方向 + +### 不建议做“AI 财务软件” + +这个方向太大，且容易与金蝶正面竞争。中小企业不会轻易更换财务系统，获客难度和信任成本都很高。 + +### 不建议做“完整 HR SaaS” + +完整 HR 系统需要覆盖招聘、入职、考勤、绩效、薪酬、组织、审批等大量模块，开发和销售周期都较长。 + +### 不建议先做“老板经营驾驶舱” + +驾驶舱依赖高质量经营数据。中小企业数据基础薄弱，如果没有先解决数据清洗和口径统一，很容易变成好看但不实用的展示页。 + +## 13. 推荐落地路线 + +### 第 1 阶段：薪酬财务对账 Excel 闭环 + +目标：验证财务人员是否愿意为薪酬对账和凭证生成付费。 + +交付能力： + +- 上传工资表、社保表、个税表 +- 自动识别字段 +- 生成异常清单 +- 导出金蝶凭证模板 + +### 第 2 阶段：薪酬模块历史对比与知识库 + +目标：提升复购和粘性。 + +交付能力： + +- 保存历史月份数据 +- 自动对比环比变化 +- 记住企业的科目映射规则 +- 记住部门与费用归属规则 + +### 第 3 阶段：金蝶生态连接 + +目标：从单点工具变成金蝶生态的补充应用。 + +交付能力： + +- 对接金蝶导入模板 +- 支持多账套配置 +- 支持不同金蝶产品版本的凭证格式 +- 与代理商、财税服务商合作获客 + +### 第 4 阶段：财务 AI 助手扩展 + +目标：从薪酬财务对账扩展为覆盖多类财务高频工作的 AI 助手。 + +可扩展模块： + +- 发票与报销 AI 助手：发票识别、真伪核验、报销单匹配、费用凭证生成 +- 预算执行 AI 分析：预算表导入、实际发生数据对比、超预算提醒、差异解释 +- 现金流异常 AI 监控：银行流水导入、资金属性识别、可动用资金分析、异常提醒 +- 往来对账 AI 助手：客户/供应商往来、发票、回款、付款自动匹配 +- 经营分析 AI 看板：面向老板/财务主管的经营摘要、费用趋势、异常追踪 + +## 14. 最终判断 + +最值得做的产品不是一开始就做“大而全的 AI 财务软件”，而是： + +**先做面向金蝶中小企业客户的财务 AI 助手，并从薪酬财务对账这个高频刚需模块切入。** + +这个方向有三个优点： + +1. **足够刚需**：薪酬、社保、个税、凭证每月都会发生，财务人员痛感强。 +2. **足够聚焦**：第一模块可以从 Excel 上传和凭证导出开始，不需要重建完整系统。 +3. **具备扩展空间**：薪酬对账验证成功后，可自然扩展到发票报销、预算执行、现金流异常、往来对账和经营分析。 + +建议把项目定义为： + +> 财务 AI 助手：金蝶中小企业客户的财务数据整理、对账、解释与凭证生成助手。 + +建议把第一个产品模块定义为： + +> 薪财通 AI：财务 AI 助手的第一模块，专注薪酬对账、人工成本分析与金蝶凭证生成。 diff --git a/frontend/.gitkeep b/frontend/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/pmdocs/0-req-S2F.md b/pmdocs/0-req-S2F.md new file mode 100644 index 0000000..fb3e96e --- /dev/null +++ b/pmdocs/0-req-S2F.md @@ -0,0 +1,547 @@ +# 财务 AI 助手需求文档（第一模块：薪酬财务对账） + +**项目编号**: S2F +**文档版本**: v1.0 +**创建日期**: 2026-07-06 +**状态**: 已确认 + +## 1. 引言与目标 + +### 1.1 产品概述 + +本项目定位为面向金蝶中小企业客户的财务 AI 助手。产品不替代金蝶账套，而是作为金蝶财务系统前置的 AI 中间层，帮助财务人员把分散在 Excel、业务系统、HR、发票、报销、银行流水等来源中的数据，整理成可核对、可解释、可导入金蝶的结构化结果。 + +第一阶段先建设“薪酬财务对账模块”（第一模块，内部产品名：薪财通 AI），解决"HR 数据到财务凭证之间"的整理、核对、解释和转换工作。后续阶段再扩展发票报销、预算执行、现金流异常、往来对账和经营分析等财务 AI 助手能力。 + +### 1.2 核心价值主张 + +**总体价值：把分散财务数据整理成可核对、可解释、可入账的结构化结果。** + +**第一模块价值：将薪酬对账工作从 3 天压缩到 30 分钟。** + +使用金蝶的中小企业财务人员，第一阶段每月只需上传工资、社保、个税等表格，AI 自动完成薪酬对账、异常识别、成本分析和凭证生成。 + +### 1.3 业务目标 + +**总项目目标**： +- 建设面向金蝶中小企业客户的财务 AI 助手 +- 帮助财务人员完成数据整理、对账、解释、凭证生成和经营分析辅助 +- 在不替代金蝶的前提下，补齐“业务数据/Excel 到财务系统”之间的 AI 中间层能力 + +**第一模块目标**： +- 帮助财务人员节省 90% 以上的薪酬对账时间 +- 降低人工对账错误率（目标准确率 > 90%） +- 提升财务与 HR 数据口径一致性 +- 为企业节省人力成本（100人企业年节省 3.6-5.4 万元） + +### 1.4 产品定位与边界 + +**总项目定位**： +- 财务 AI 助手，服务金蝶中小企业客户 +- 金蝶财务软件的增效工具，而非替代品 +- 连接业务数据、Excel 数据、HR 数据、发票/报销数据、银行流水与金蝶财务系统 +- AI 辅助决策，不替代财务人员的专业判断 + +**第一阶段定位**： +- 第一模块为薪酬财务对账，不是项目的全部边界 +- 第一阶段专注工资、社保、公积金、个税、人工成本分析和金蝶凭证生成 +- 先验证一个高频财务场景，再扩展为完整财务 AI 助手 + +**明确不做**（避免与金蝶竞争）： +- ❌ 账套管理 +- ❌ 正式凭证入账 +- ❌ 法定财务报表生成 +- ❌ ERP 和进销存主流程 +- ❌ 银行支付和资金调拨 + +## 2. 术语表 + +| 术语 | 定义 | +|---|---| +| 薪酬对账 | 核对工资表、社保表、个税表、银行回单等多源数据的一致性 | +| 金蝶凭证 | 符合金蝶财务软件导入格式的会计凭证模板 | +| 字段映射 | AI 识别不同企业表格中相同含义但命名不同的字段 | +| 异常检测 | 自动识别离职未停社保、个税不匹配等常见错误 | +| 部门成本分摊 | 将人工成本按部门或费用科目拆分 | +| 多租户 | 不同企业数据严格隔离，互不可见 | +| 私有化部署 | 企业在自己的服务器上部署系统 | + +## 3. 角色定义 + +### 3.1 核心用户 + +**财务主管** +- 职责：审核薪酬对账结果、人工成本分析、凭证生成 +- 痛点：每月对账耗时长、异常难追溯、老板经常追问成本变化 +- 使用场景：查看异常清单、审核凭证、生成成本分析报告 + +**总账会计** +- 职责：执行薪酬对账、生成凭证、导入金蝶 +- 痛点：表格来源多、格式不统一、重复性工作多 +- 使用场景：上传表格、处理异常、导出凭证模板 + +**出纳兼会计**（中小企业常见） +- 职责：工资发放、社保缴纳、凭证入账 +- 痛点：身兼多职、时间紧、容易出错 +- 使用场景：快速完成对账和凭证生成 + +### 3.2 相关用户 + +**HR 薪酬专员** +- 职责：提供工资表、社保表、考勤数据 +- 使用场景：可选上传权限，协助财务核对 + +**企业老板/管理层** +- 职责：关注人工成本变化 +- 使用场景：查看人工成本分析报告（第二阶段移动端） + +**外包记账公司**（潜在客群） +- 职责：代理多家企业的财务工作 +- 使用场景：批量处理多个企业的薪酬对账（企业版） + +## 4. 功能性需求 + +### 4.0 财务 AI 助手模块规划 + +| 阶段 | 模块 | 目标 | 状态 | +|---|---|---|---| +| 第一阶段 | 薪酬财务对账助手 | 工资、社保、个税、公积金对账，人工成本分析，金蝶凭证生成 | 本需求文档详细定义 | +| 第二阶段 | 薪酬模块自动化增强 | 历史对比、企业规则沉淀、自动文件夹监控、完整自然语言问答 | 规划中 | +| 第三阶段 | 金蝶生态连接 | 金蝶 API、多账套、行业模板、代账公司批量处理 | 规划中 | +| 第四阶段 | 财务 AI 助手扩展 | 发票报销、预算执行、现金流异常、往来对账、经营分析看板 | 路线规划 | + +### 4.1 MVP 核心功能（第一阶段：薪酬财务对账模块） + +#### REQ-001: 薪酬数据上传 + +**WHEN** 财务人员需要进行月度薪酬对账 +**THE system SHALL** 支持通过 Web 界面拖拽上传 Excel 文件（.xls / .xlsx / .csv） + +**输入要求**： +- 工资表（必需） +- 社保表（必需） +- 个税表（必需） + +**约束条件**： +- 单次上传文件大小 < 10MB +- 支持 50-500 人规模数据 +- 文件格式自动识别 + +#### REQ-002: AI 字段智能识别 + +**WHEN** 用户上传 Excel 文件 +**THE system SHALL** 使用 AI 自动识别字段含义并生成映射建议 + +**识别字段**： +- 员工姓名、工号、部门、岗位 +- 应发工资、实发工资、个税 +- 社保个人部分、社保公司部分 +- 公积金个人部分、公积金公司部分 +- 奖金、提成、扣款 + +**要求**： +- 识别准确率 > 90% +- 支持用户手动修正 +- 记住企业历史映射规则，下次自动应用 + +#### REQ-003: 薪酬对账与异常检测 + +**WHEN** 字段映射完成 +**THE system SHALL** 自动执行多维度对账并输出异常清单 + +**检测规则**： +- 离职员工仍有工资发放 +- 入职员工未缴社保 +- 已离职员工社保未停缴 +- 个税金额与工资数据不匹配 +- 社保基数异常波动（环比变化 > 30%） +- 公积金缴纳比例异常（超出合理范围 5%-12% 或与历史月份差异 > 2%） +- 部门归属为空或与上月不一致 +- 银行实发金额与工资表实发金额不一致（第二阶段） + +**输出**： +- 异常清单 Excel（异常类型、员工姓名、详细说明、建议处理方式） + +#### REQ-004: 人工成本分析 + +**WHEN** 对账完成 +**THE system SHALL** 自动生成月度人工成本分析报告 + +**分析维度**： +- 本月人工成本总额（工资 + 社保 + 公积金） +- 与上月环比变化（金额、比例） +- 按部门拆分的人工成本明细 +- 按费用科目拆分（管理费用、销售费用、研发费用） +- 新增/离职员工带来的成本变化 +- 奖金、提成等特殊项目影响 + +**输出格式**： +- Excel 报表 +- 支持复制到月度经营分析 + +#### REQ-005: 金蝶凭证模板生成 + +**WHEN** 用户确认对账结果 +**THE system SHALL** 根据企业配置生成可导入金蝶的凭证模板 + +**凭证类型**： +- 工资计提凭证 +- 工资发放凭证 +- 个税计提/代扣凭证 +- 社保凭证（公司部分 + 个人部分） +- 公积金凭证（公司部分 + 个人部分） +- 部门费用分摊凭证 + +**要求**： +- 支持自定义科目映射 +- 记住企业规则配置 +- Excel 格式符合金蝶导入规范 + +#### REQ-006: 预置问题问答 + +**WHEN** 用户在 AI 工作台、成本分析页面查看数据 +**THE system SHALL** 提供预置问题列表，用户点击后基于当前数据返回答案 + +**预置问题示例**： +- 本月还缺哪些文件？ +- 哪些字段需要人工确认？ +- 哪些异常最严重？ +- 为什么本月人工成本上涨/下降？ +- 哪些部门变化最大？ +- 现在可以生成金蝶凭证吗？ + +**要求**： +- 不做开放式对话，仅支持预置问题 +- 答案基于当前任务数据生成 +- 响应时间 < 3 秒 +- 答案包含关键数据点（金额、比例、员工名单） + +**AI Native 价值**： +- 降低用户查找信息成本 +- 主动提示关键问题 +- 提升"AI 助手"体验 + +### 4.2 第二阶段功能（暂不实现） + +- 自动文件夹监控（本地 + 网盘同步） +- 可选输入文件支持（公积金表、考勤表、银行回单） +- 历史数据对比（12个月环比/同比） +- **完整自然语言问答**（开放式对话，不限于预置问题） +- 金蝶 API 直接对接 +- 移动端支持 + +## 5. 非功能性需求 + +### 5.1 性能要求 + +**NFR-001: 数据处理性能** +- WHEN 处理 200 人企业的薪酬数据 +- THE system SHALL 在 30 秒内完成从上传到结果输出 + +**NFR-002: AI 识别性能** +- WHEN 执行 AI 字段识别 +- THE system SHALL 在 5 秒内返回映射结果 + +**NFR-003: 凭证生成性能** +- WHEN 生成金蝶凭证模板 +- THE system SHALL 在 3 秒内完成生成和下载准备 + +**NFR-004: 并发支持** +- WHEN 多个用户同时使用系统 +- THE system SHALL 支持至少 50 个并发用户 + +### 5.2 安全要求 + +**NFR-005: 数据传输安全** +- THE system SHALL 使用 HTTPS 加密传输所有数据 +- THE system SHALL 对文件上传进行加密处理 + +**NFR-006: 数据存储安全** +- THE system SHALL 使用 AES-256 加密存储敏感数据 +- THE system SHALL 对员工姓名进行脱敏展示（张**、李**） +- THE system SHALL 支持定期数据库备份 + +**NFR-007: 访问控制** +- THE system SHALL 实现多租户严格隔离（企业 A 无法访问企业 B 数据） +- THE system SHALL 支持按角色权限控制： + - 财务主管：全部权限 + - 总账会计：查看和编辑权限 + - 出纳：仅查看权限 + - HR：可选上传权限 + +**NFR-008: 审计日志** +- THE system SHALL 记录所有数据访问和操作日志 +- THE system SHALL 保留审计日志 3 年 + +**NFR-009: 数据删除机制** +- THE system SHALL 支持用户主动删除历史数据 +- THE system SHALL 在企业注销后 30 天内自动删除所有数据 +- THE system SHALL 符合《个人信息保护法》要求 + +### 5.3 可用性要求 + +**NFR-010: 界面友好性** +- THE system SHALL 提供直观的拖拽上传界面 +- THE system SHALL 在每个关键步骤提供操作指引 +- THE system SHALL 支持"一键修正"异常字段映射 + +**NFR-011: 错误提示** +- THE system SHALL 在操作失败时提供明确的错误原因和解决建议 +- THE system SHALL 在数据异常时提供上下文说明 + +**NFR-012: 新手引导** +- THE system SHALL 为首次使用的用户提供完整操作演示 +- THE system SHALL 提供示例数据供用户快速体验 + +### 5.4 兼容性要求 + +**NFR-013: 浏览器兼容** +- THE system SHALL 支持 Chrome、Edge、Safari、Firefox 最新两个版本 +- THE system SHALL 优先优化 Chrome 体验 + +**NFR-014: 文件格式兼容** +- THE system SHALL 支持 .xls、.xlsx、.csv 格式 +- THE system SHALL 兼容 Excel 2007 及以上版本 + +**NFR-015: 金蝶版本兼容** +- THE system SHALL 生成的凭证模板兼容金蝶云星辰、精斗云、K/3 + +### 5.5 可扩展性要求 + +**NFR-016: 数据规模扩展** +- THE system SHALL 支持从 50 人扩展到 1000 人企业 +- THE system SHALL 在不重构的前提下支持数据量线性增长 + +**NFR-017: 功能扩展** +- THE system SHALL 设计模块化架构，便于后续增加新功能 +- THE system SHALL 预留 API 接口，便于第三方集成 + +### 5.6 可维护性要求 + +**NFR-018: 代码质量** +- THE system SHALL 使用 TypeScript 提供类型安全 +- THE system SHALL 保持核心模块测试覆盖率 > 80% +- THE system SHALL 遵循 RESTful API 设计规范 + +**NFR-019: 部署要求** +- THE system SHALL 支持 Docker 容器化部署 +- THE system SHALL 支持私有化部署（Docker Compose） +- THE system SHALL 提供完整的部署文档和脚本 + +**NFR-020: 监控与日志** +- THE system SHALL 记录所有 API 调用和性能指标 +- THE system SHALL 在异常发生时自动记录堆栈信息 + +### 5.7 合规性要求 + +**NFR-021: 数据合规** +- THE system SHALL 符合《个人信息保护法》 +- THE system SHALL 符合《数据安全法》 +- THE system SHALL 提供数据处理协议模板 + +**NFR-022: 财务合规** +- THE system SHALL 生成的凭证符合企业会计准则 +- THE system SHALL 在界面明确标注"最终决策权在财务人员" + +### 5.8 数据保留策略 + +**NFR-023: 历史数据保留** +- 免费版：仅保留当月数据 +- 基础版：保留 12 个月历史数据 +- 专业版：保留 36 个月历史数据 +- 企业版：无限制保留（可配置） + +## 6. 范围边界 + +### 6.1 包含（In Scope） + +✅ 手动上传 Excel 表格 +✅ AI 字段识别和映射 +✅ 工资、社保、个税对账 +✅ 异常检测与清单生成 +✅ 人工成本分析 +✅ 金蝶凭证模板导出 +✅ 多租户数据隔离 +✅ 基础安全（加密、访问控制、审计） +✅ Docker 私有化部署 + +### 6.2 不包含（Out of Scope - 第一阶段） + +❌ 自动文件夹监控 +❌ 金蝶 API 直接对接 +❌ 移动端应用 +❌ 复杂审批流 +❌ 完整 HR 系统功能 +❌ 银行支付系统对接 +❌ 个税/社保直接申报 +❌ 等保三级认证 +❌ **预算管理与预算执行跟踪** +❌ **发票真伪核验** +❌ **现金流监控与银行账户余额管理** + +**说明**： +- 预算管理、发票核验、现金流监控也是财务 AI 助手的目标场景，但不进入第一阶段薪酬财务对账 MVP +- 这些功能进入第四阶段“财务 AI 助手扩展”，不应提前挤占第一模块的开发范围 + +### 6.3 未来可能包含（Future Scope） + +⏰ 历史数据环比/同比分析（第二阶段） +⏰ 完整自然语言问答（第二阶段） +⏰ 自动文件夹监控（第二阶段） +⏰ 多账套支持（第三阶段） +⏰ 行业化模板（第三阶段） +⏰ 金蝶 API 对接（第三阶段） +⏰ **发票与报销 AI 助手**（第四阶段） +⏰ **预算执行 AI 分析**（第四阶段） +⏰ **现金流异常 AI 监控**（第四阶段） +⏰ **往来对账 AI 助手**（第四阶段） +⏰ **经营分析 AI 看板**（第四阶段） + +## 7. 关键约束与假设 + +### 7.1 技术约束 + +- 前端：Next.js (React) + TypeScript + Tailwind CSS +- 后端：Python (FastAPI) + Pydantic +- 数据库：PostgreSQL +- AI：LLM API（GPT-4 或国产大模型） +- 部署：Docker + Docker Compose + +### 7.2 业务约束 + +- 目标客群：50-500 人规模企业 +- 数据来源：Excel 手动上传（第一阶段） +- 输出格式：Excel 凭证模板 +- 金蝶版本：兼容主流版本（云星辰、精斗云、K/3） + +### 7.3 资源约束 + +- 开发周期：MVP 需在 3 个月内完成 +- 团队配置：产品经理 × 1，全栈工程师 × 2，AI 工程师 × 1 +- 初始预算：控制在合理范围（云服务、AI API 成本） + +### 7.4 关键假设 + +- ✓ 假设目标用户已使用金蝶财务软件 +- ✓ 假设用户可以从 HR 或行政获取 Excel 表格 +- ✓ 假设用户有基本的 Excel 和财务知识 +- ✓ 假设不同企业的薪酬结构可以通过 AI 识别标准化 +- ✓ 假设异常检测规则可以覆盖 80% 以上的常见错误 + +## 8. 验收标准 + +### 8.1 功能验收 + +- [ ] 可以成功上传工资表、社保表、个税表 +- [ ] AI 字段识别准确率 > 90% +- [ ] 异常检测能覆盖 MVP 7 类异常，并保留第二阶段银行实发对账规则 +- [ ] 人工成本分析报告包含所有必需维度 +- [ ] 金蝶凭证模板可以被金蝶软件成功导入 +- [ ] 多租户数据严格隔离，无数据泄露 + +### 8.2 性能验收 + +- [ ] 200 人企业数据处理时间 < 30 秒 +- [ ] AI 字段识别响应时间 < 5 秒 +- [ ] 凭证生成时间 < 3 秒 +- [ ] 支持 50 个并发用户 + +### 8.3 安全验收 + +- [ ] 数据传输使用 HTTPS +- [ ] 敏感数据已加密存储 +- [ ] 审计日志完整记录 +- [ ] 多租户隔离通过安全测试 + +### 8.4 用户体验验收 + +- [ ] 首次使用用户能在 15 分钟内完成一次完整流程 +- [ ] 新手引导清晰易懂 +- [ ] 错误提示明确具体 +- [ ] 异常处理流程顺畅 + +### 8.5 商业验收（MVP 阶段） + +- [ ] 获得 10 个付费客户（或深度参与的种子用户） +- [ ] 首月留存率 > 60% +- [ ] NPS > 40 +- [ ] 用户平均完成时间 < 30 分钟 + +## 9. 风险与依赖 + +### 9.1 技术风险 + +**RISK-001: AI 识别准确率不足** +- 影响：用户需要大量修正，降低使用体验 +- 缓解措施：积累行业标准模板、记住企业规则、持续训练模型 + +**RISK-002: 异常检测误报率高** +- 影响：增加用户工作量，降低信任度 +- 缓解措施：规则可配置、提供"忽略"功能、基于反馈优化 + +**RISK-003: 数据安全事故** +- 影响：数据泄露导致法律责任和信任崩塌 +- 缓解措施：从第一天就做安全设计、购买网络安全保险、定期安全审计 + +### 9.2 业务风险 + +**RISK-004: 金蝶推出类似功能** +- 影响：最大威胁，可能导致竞争失败 +- 缓解措施：快速获客建立先发优势、与代理商深度绑定、专注体验 + +**RISK-005: 市场需求不足** +- 影响：获客困难、用户流失高 +- 缓解措施：MVP 快速验证、深度访谈调整方向、灵活调整定价 + +### 9.3 外部依赖 + +- LLM API 稳定性和成本（GPT-4 或国产大模型） +- 金蝶凭证导入格式兼容性 +- 用户提供的数据质量（表格格式、字段完整性） + +## 10. 需求优先级（MoSCoW） + +### Must Have（MVP 必须） +- REQ-001: 薪酬数据上传 +- REQ-002: AI 字段智能识别 +- REQ-003: 薪酬对账与异常检测 +- REQ-004: 人工成本分析 +- REQ-005: 金蝶凭证模板生成 +- NFR-005 ~ NFR-009: 核心安全要求 +- NFR-010 ~ NFR-012: 可用性要求 +- NFR-019: Docker 部署支持 + +### Should Have（第二阶段优先） +- 历史数据保存（12 个月） +- 环比变化分析 +- 自定义科目映射界面 +- 自然语言问答 +- 自动文件夹监控 + +### Could Have（第二阶段可选） +- 可选输入文件支持（公积金、考勤、银行回单） +- 移动端查看 +- 金蝶 API 对接 + +### Won't Have（第一阶段不做） +- 完整 HR 系统 +- 银行支付对接 +- 个税/社保直接申报 +- 等保三级认证 + +## 11. 关联文档 + +- 产品方向建议：`../薪财通AI_产品方向建议.md` +- PRD 文档：`pmdocs/1-prd-S2F.md` +- 任务文档：`pmdocs/2-task-S2F.md` +- 运行手册：`run.md` + +## 12. 变更历史 + +| 版本 | 日期 | 变更内容 | 变更人 | +|---|---|---|---| +| v1.0 | 2026-07-06 | 初始版本，基于产品方向建议生成 | AI | + +--- + +**当前状态**: 需求、PRD、任务文档与运行手册已生成，可进入开发执行阶段。 \ No newline at end of file diff --git a/pmdocs/1-prd-S2F.md b/pmdocs/1-prd-S2F.md new file mode 100644 index 0000000..cc4247a --- /dev/null +++ b/pmdocs/1-prd-S2F.md @@ -0,0 +1,1022 @@ +# 财务 AI 助手产品需求文档（PRD） + +**项目编号**: S2F +**关联需求文档**: `pmdocs/0-req-S2F.md` +**文档版本**: v1.0 +**创建日期**: 2026-07-06 +**状态**: 已确认 + +## 1. 产品概述与定位 + +### 1.1 产品名称 + +财务 AI 助手 + +第一模块产品名：薪财通 AI + +### 1.2 一句话定位 + +面向金蝶中小企业客户的财务数据整理、对账、解释与凭证生成 AI 助手；第一阶段先做薪酬财务对账模块。 + +### 1.3 产品价值主张 + +**总体价值**：把分散在 Excel、HR、发票、报销、银行流水和业务系统中的财务相关数据，整理成可核对、可解释、可导入金蝶的结构化结果。 + +**第一模块价值**：将每月薪酬对账、异常识别、人工成本分析和金蝶凭证生成，从传统人工处理的 2-3 天压缩到 30 分钟内完成。 + +### 1.4 产品边界 + +财务 AI 助手是企业业务数据与金蝶财务系统之间的 AI 中间层： + +```text +Excel / HR / 发票 / 报销 / 银行流水 / 业务系统数据 + ↓ +财务 AI 助手：识别、清洗、对账、解释、分析、生成凭证建议 + ↓ +金蝶：账套、凭证入账、正式财务核算、法定报表 +``` + +第一阶段模块为薪财通 AI： + +```text +HR / 行政 / 薪酬 Excel 数据 + ↓ +薪财通 AI：识别、清洗、薪酬对账、人工成本分析、生成工资相关凭证 + ↓ +金蝶：凭证入账、正式财务核算 +``` + +产品不替代金蝶、不做正式账套、不直接入账、不替代财务专业判断，只提供可核对、可解释、可导入的结构化结果。 + +## 2. 产品目标与成功指标 + +### 2.1 第一模块 MVP 阶段目标 + +| 目标 | 指标 | 验收口径 | +|---|---|---| +| 验证薪酬模块核心价值 | 用户完成一次薪酬对账耗时 < 30 分钟 | 从上传文件到导出凭证 | +| 验证识别能力 | 字段识别准确率 > 90% | 用户无需修改或少量修改即可继续 | +| 验证付费意愿 | 3 个月内获得 10 个付费客户或深度种子用户 | 有真实企业数据参与试用 | +| 验证留存 | 首月留存率 > 60% | 第二个月继续上传数据处理 | +| 验证可扩展性 | 企业愿意继续试用发票/预算/往来等财务 AI 模块 | 种子用户反馈中出现跨场景需求 | +| 验证口碑 | NPS > 40 | 种子用户反馈 | + +### 2.2 产品体验目标 + +- 首次使用用户在 15 分钟内理解完整流程。 +- 用户无需学习复杂财务软件操作，只按“上传 → 确认 → 查看 → 导出”完成工作。 +- 所有 AI 结果都必须可解释、可修正、可追溯。 + +### 2.3 目标客户画像 + +**企业规模**： +- MVP 阶段：50-500 人中小企业 +- 第二阶段：支持 50-1000 人 +- 第三阶段：支持 50+ 人（无上限，通过性能优化） + +**企业特征**： +- 已使用金蝶财务软件（云星辰、精斗云、K/3） +- 财务和 HR 分工不明确或规模较小 +- 工资、社保、个税仍大量依赖 Excel +- 每月人工成本分析压力较大 +- 没有完整 HR 系统或 HR 系统与财务不打通 + +### 2.4 商业目标 + +- 第一阶段优先验证薪酬财务对账模块的基础版/专业版付费模型。 +- 第二阶段通过历史规则沉淀和自动化能力提升薪酬模块留存。 +- 第三阶段通过金蝶生态连接扩大获客渠道。 +- 第四阶段从薪酬模块扩展为财务 AI 助手模块群，提高客单价和使用频率。 + +## 3. 用户画像与核心场景 + +### 3.1 财务主管 + +| 项目 | 内容 | +|---|---| +| 角色目标 | 快速确认本月薪酬数据是否合理，并向老板解释人工成本变化 | +| 主要痛点 | 数据来源多、异常难追溯、成本变化解释耗时 | +| 痛点解法 | 系统输出异常清单、成本分析和变化原因 | +| 成功状态 | 能在 30 分钟内完成核对并生成可汇报材料 | + +### 3.2 总账会计 + +| 项目 | 内容 | +|---|---| +| 角色目标 | 完成工资、社保、个税对账并生成金蝶凭证 | +| 主要痛点 | 表格格式不统一、字段口径不一致、凭证重复生成 | +| 痛点解法 | AI 字段映射、自动对账、凭证模板导出 | +| 成功状态 | 对账结果清晰，凭证可直接导入金蝶 | + +### 3.3 出纳兼会计 + +| 项目 | 内容 | +|---|---| +| 角色目标 | 在有限时间内完成工资相关财务处理 | +| 主要痛点 | 身兼多职，没有时间处理复杂对账 | +| 痛点解法 | 极简流程、默认规则、清晰提示 | +| 成功状态 | 不需要专业配置即可完成基础对账 | + +### 3.4 HR 薪酬专员 + +| 项目 | 内容 | +|---|---| +| 角色目标 | 向财务提供正确薪酬数据，并处理异常反馈 | +| 主要痛点 | 财务反馈的问题不清楚，沟通成本高 | +| 痛点解法 | 异常清单按员工、字段、原因、建议处理方式输出 | +| 成功状态 | 可以按清单快速修正源数据 | + +### 3.5 外包记账公司（第二/三阶段） + +| 项目 | 内容 | +|---|---| +| 角色目标 | 为多家中小企业客户提供代账服务 | +| 主要痛点 | 客户薪酬数据格式各异，每月重复劳动 | +| 痛点解法 | 多账套管理、批量处理、模板复用 | +| 成功状态 | 可以批量处理多家客户，提升服务效率 | + +**说明**：此用户类型在第三阶段支持（PRD-FUNC-020 多账套管理） + +### 3.6 核心场景清单 + +| 场景编号 | 场景名称 | 用户 | 痛点解法 | 关联需求 | +|---|---|---|---|---| +| SCENE-001 | 月度薪酬数据上传 | 总账会计 | 拖拽上传，自动识别文件类型 | REQ-001 | +| SCENE-002 | 字段映射确认 | 总账会计 | AI 给出字段映射建议，用户只确认差异 | REQ-002 | +| SCENE-003 | 异常识别与处理 | 财务主管 / HR | 异常按类型聚合，给出处理建议 | REQ-003 | +| SCENE-004 | 人工成本分析 | 财务主管 | 自动输出部门、科目、人员变化原因 | REQ-004 | +| SCENE-005 | 金蝶凭证导出 | 总账会计 | 使用企业科目规则生成凭证模板 | REQ-005 | +| SCENE-006 | 企业规则沉淀 | 总账会计 | 记住字段映射、科目映射、部门归属 | REQ-002 / REQ-005 | + +## 4. 功能清单与优先级 + +### 4.0 财务 AI 助手模块地图 + +| 阶段 | 模块 | 功能方向 | 本 PRD 处理方式 | +|---|---|---|---| +| 第一阶段 | 薪酬财务对账助手 | 工资、社保、个税、公积金对账，人工成本分析，金蝶凭证生成 | 详细定义 MVP | +| 第二阶段 | 薪酬模块自动化增强 | 历史对比、企业规则、自动文件夹监控、完整自然语言问答 | 功能规划 | +| 第三阶段 | 金蝶生态连接 | 金蝶 API、多账套、行业模板、代账公司批量处理 | 功能规划 | +| 第四阶段 | 财务 AI 助手扩展 | 发票报销、预算执行、现金流异常、往来对账、经营分析 | 模块规划 | + +### 4.1 第一阶段功能清单：薪酬财务对账 MVP + +| PRD 编号 | 功能 | 优先级 | 说明 | 关联需求 | +|---|---|---|---|---| +| PRD-FUNC-001 | 登录与企业空间 | Must | 支持企业账号、用户登录、多租户隔离 | NFR-007 | +| PRD-FUNC-002 | AI 工作台 | Must | 汇总本月状态、风险、待办和下一步建议 | REQ-001 / REQ-002 / REQ-003 / REQ-004 / REQ-005 | +| PRD-FUNC-002A | 预置问题问答 | Must | 提供常见问题列表，用户点击后基于当前数据返回答案 | REQ-006 | +| PRD-FUNC-003 | 上传与识别 | Must | 上传工资表、社保表、个税表，并自动识别文件类型 | REQ-001 | +| PRD-FUNC-004 | AI 字段映射确认 | Must | 展示识别结果、置信度、依据样例，支持用户修正 | REQ-002 | +| PRD-FUNC-005 | 对账任务处理 | Must | 自动执行工资、社保、个税对账 | REQ-003 | +| PRD-FUNC-006 | 异常清单 | Must | 按异常类型、员工、字段展示问题和建议处理方式 | REQ-003 | +| PRD-FUNC-007 | 人工成本分析 | Must | 输出成本汇总、部门拆分、环比变化和 AI 原因摘要 | REQ-004 | +| PRD-FUNC-008 | 金蝶凭证生成 | Must | 生成可导入金蝶的 Excel 模板，并解释科目匹配依据 | REQ-005 | +| PRD-FUNC-009 | 企业知识库 | Must | 字段映射、科目映射、部门归属规则和历史确认记录 | REQ-002 / REQ-005 | +| PRD-FUNC-010 | 导出中心 | Must | 下载异常清单、成本分析、凭证模板 | REQ-003 / REQ-004 / REQ-005 | +| PRD-FUNC-011 | 操作日志与审计 | Must | 记录上传、识别、导出、删除等操作 | NFR-008 | +| PRD-FUNC-012 | 示例数据体验 | Should | 新用户可用示例数据体验完整流程 | NFR-012 | +| PRD-FUNC-013 | 基础设置 | Should | 企业信息、人员角色、数据保留设置 | NFR-023 | + +### 4.2 第二阶段功能清单 + +| PRD 编号 | 功能 | 优先级 | 说明 | +|---|---|---|---| +| PRD-FUNC-014 | 历史月份对比 | Should | 12 个月历史数据环比/同比 | +| PRD-FUNC-015 | 自动文件夹监控 | Should | 本地目录或网盘目录自动扫描 | +| PRD-FUNC-016 | 完整自然语言问答 | Should | 开放式对话，不限于预置问题，自由追问成本变化 | +| PRD-FUNC-017 | 可选文件支持 | Could | 公积金、考勤、银行回单、人员变动表 | +| PRD-FUNC-018 | 企业微信/邮件通知 | Could | 处理完成后通知用户 | + +### 4.3 第三阶段功能清单：金蝶生态连接 + +| PRD 编号 | 功能 | 优先级 | 说明 | +|---|---|---|---| +| PRD-FUNC-019 | 金蝶 API 对接 | Could | 自动读取科目或推送凭证 | +| PRD-FUNC-020 | 多账套管理 | Could | 集团企业、代账公司场景 | +| PRD-FUNC-021 | 行业模板库 | Could | 制造业、服务业、科技企业模板 | + +### 4.4 第四阶段功能清单：财务 AI 助手扩展 + +| PRD 编号 | 模块 | 功能 | 说明 | +|---|---|---|---| +| PRD-FUNC-022 | 发票与报销 AI 助手 | 发票识别、真伪核验、报销单匹配、费用凭证生成 | 从费用报销痛点切入 | +| PRD-FUNC-023 | 预算执行 AI 分析 | 预算表导入、实际发生对比、超预算提醒、差异解释 | 做轻量预算执行分析，不做完整预算系统 | +| PRD-FUNC-024 | 现金流异常 AI 监控 | 银行流水导入、资金属性识别、可动用资金分析、异常提醒 | 只读分析，不做支付和资金调拨 | +| PRD-FUNC-025 | 往来对账 AI 助手 | 客户/供应商往来、发票、回款、付款自动匹配 | 服务应收应付对账场景 | +| PRD-FUNC-026 | 经营分析 AI 看板 | 经营摘要、费用趋势、异常追踪、老板报表 | 数据稳定后提供管理层视角 | + +### 4.5 产品边界与非 MVP 事项 + +以下功能虽是财务 AI 助手的目标场景，但不进入第一阶段薪酬财务对账 MVP，按后续模块处理： + +| 功能 | 处理方式 | +|---|---| +| 现金流监控与银行账户余额管理 | 第四阶段做只读现金流异常分析，不做支付和资金调拨 | +| 完整 HR 系统（招聘、绩效、培训） | 不替代 HR 系统，只处理薪酬数据到财务的转换 | +| 银行支付系统对接 | 不做支付，只生成凭证或异常提醒 | +| 个税/社保直接申报 | 不对接政务申报，只核对数据一致性 | +| 完整预算管理系统 | 不做完整系统，第四阶段做预算执行 AI 分析 | +| 发票真伪核验 | 第四阶段作为发票与报销 AI 助手能力 | +| 费用报销与往来对账 | 第四阶段作为财务 AI 助手扩展模块 | + +## 5. 关键流程设计 + +### 5.1 MVP 主流程 + +```text +用户登录 + ↓ +进入 AI 工作台 + ↓ +AI 总结本月状态并推荐下一步 + ↓ +上传工资表 / 社保表 / 个税表 + ↓ +系统解析文件结构 + ↓ +AI 识别字段并给出映射建议 + ↓ +用户确认或修正字段映射 + ↓ +系统执行数据清洗和对账 + ↓ +生成异常清单 + ↓ +用户处理或忽略异常 + ↓ +生成成本分析和金蝶凭证 + ↓ +用户预览并导出 Excel +``` + +### 5.2 字段映射流程 + +```text +读取表头与样例数据 + ↓ +AI 推断字段含义 + ↓ +系统匹配标准字段模型 + ↓ +展示“源字段 → 标准字段 → 置信度” + ↓ +用户确认 / 修改 / 忽略字段 + ↓ +保存为企业规则 + ↓ +后续同类表格自动复用 +``` + +### 5.3 异常处理流程 + +```text +对账规则执行 + ↓ +生成异常结果 + ↓ +按严重程度分级：高 / 中 / 低 + ↓ +用户查看异常说明 + ↓ +用户选择处理方式：已修正 / 忽略本次 / 忽略此类 / 导出给 HR + ↓ +系统记录处理结果和审计日志 +``` + +### 5.4 凭证生成流程 + +```text +读取清洗后的薪酬数据 + ↓ +按部门归属和费用科目拆分 + ↓ +套用企业科目映射规则 + ↓ +生成凭证预览 + ↓ +用户确认借贷方向与金额 + ↓ +导出金蝶凭证模板 +``` + +## 6. 信息架构与页面规划 + +### 6.1 AI Native 信息架构原则 + +薪财通 AI 不应设计成传统“后台菜单 + 用户自己找功能”的系统，而应采用“AI 工作流入口 + 专业模块兜底”的结构： + +```text +用户意图 + ↓ +AI 工作台识别当前月份、缺失文件、待确认事项、风险点 + ↓ +系统主动推荐下一步动作 + ↓ +用户确认关键节点 + ↓ +系统生成结果并解释依据 +``` + +核心设计原则： + +- 主入口不是“菜单”，而是“本月薪酬对账助手”。 +- 页面不只展示数据，还要告诉用户“当前状态、发现什么、为什么、下一步做什么”。 +- AI 结果必须包含依据、置信度、可修改入口，避免黑盒。 +- 传统表格和设置页保留，但作为专业用户的兜底能力，不作为首要路径。 +- 每个页面都要有“AI 建议区”，承接解释、提醒、下一步动作。 + +### 6.2 导航结构 + +推荐采用左侧轻菜单 + 顶部 AI 命令入口 + 页面内 AI 建议区。 + +```text +薪财通 AI +├── AI 工作台 +│ ├── 本月对账助手 +│ ├── 待办与风险提醒 +│ ├── 一键开始本月处理 +│ └── AI 追问入口 +├── 对账流程 +│ ├── 上传与识别 +│ ├── 字段确认 +│ ├── 异常处理 +│ └── 结果生成 +├── 结果中心 +│ ├── 异常清单 +│ ├── 人工成本分析 +│ ├── 金蝶凭证 +│ └── 导出记录 +├── 企业知识库 +│ ├── 字段映射规则 +│ ├── 科目映射规则 +│ ├── 部门归属规则 +│ └── 历史确认记录 +└── 系统管理 + ├── 企业信息 + ├── 成员与权限 + ├── 审计日志 + └── 数据保留 +``` + +### 6.3 菜单命名建议 + +| 传统叫法 | AI Native 叫法 | 设计目的 | +|---|---|---| +| 工作台 | AI 工作台 | 强调系统主动协助，而不是用户自己找入口 | +| 对账任务 | 对账流程 | 强调从上传到导出的连续过程 | +| 成本分析 | 结果中心 / 人工成本分析 | 作为结果产物，而非孤立页面 | +| 凭证中心 | 结果中心 / 金蝶凭证 | 与异常、分析统一为“结果” | +| 企业规则 | 企业知识库 | 表达系统会学习和沉淀企业习惯 | +| 设置 | 系统管理 | 放置权限、审计、保留策略等低频能力 | + +### 6.4 AI 工作台页面结构 + +AI 工作台是 MVP 的首屏，应替代传统 Dashboard。 + +```text +顶部：本月薪酬对账助手 + - 当前月份 + - 本月处理状态 + - AI 总结一句话 + +中部：下一步建议 + - 缺少哪些文件 + - 哪些字段需要确认 + - 哪些异常需要处理 + - 是否可以生成凭证 + +右侧：AI 追问区 + - 为什么本月成本上涨？ + - 哪些员工异常最多？ + - 是否可以直接生成凭证？ + - 本月还缺什么数据？ + +底部：最近结果 + - 异常清单 + - 人工成本分析 + - 金蝶凭证 +``` + +### 6.5 页面清单 + +| 页面 | 目标 | AI Native 体现 | MVP | +|---|---|---|---| +| 登录页 | 进入系统 | 展示产品价值和示例成果 | 是 | +| AI 工作台 | 驱动本月处理 | AI 总结当前状态并推荐下一步 | 是 | +| 上传与识别页 | 上传三类核心表格 | 自动识别文件类型、缺失项和表头含义 | 是 | +| 字段确认页 | 确认 AI 识别结果 | 展示置信度、依据样例、历史规则命中 | 是 | +| 异常处理页 | 查看并处理异常 | 按严重程度聚合，解释原因和建议处理方式 | 是 | +| 人工成本分析页 | 查看成本变化 | AI 生成变化原因摘要和可追问问题 | 是 | +| 金蝶凭证页 | 确认凭证结果 | AI 解释凭证来源、科目匹配依据 | 是 | +| 导出记录页 | 下载结果文件 | 展示每个文件的生成依据和适用对象 | 是 | +| 企业知识库页 | 管理复用规则 | 展示系统已学习的企业规则 | 是 | +| 审计日志页 | 查询操作记录 | 解释关键结果由谁确认、何时确认 | 是 | +| 示例数据页 | 新手体验 | AI 带用户走完示例流程 | 否，Should | + +### 6.6 AI Native 交互模式 + +| 模式 | 使用位置 | 说明 | +|---|---|---| +| 下一步卡片 | AI 工作台、流程页 | 明确告诉用户当前最应该做什么 | +| 置信度标签 | 字段确认、凭证生成 | 显示 AI 判断可信程度 | +| 依据展开 | 字段确认、异常、凭证 | 展示 AI 判断依据，避免黑盒 | +| 一键应用建议 | 字段映射、科目映射 | 用户确认后写入企业知识库 | +| 追问入口 | 工作台、成本分析 | 用户围绕当前数据继续提问 | +| 人工确认门 | 凭证生成、删除数据 | AI 不能越过财务人员做最终决策 | + +## 7. 角色权限矩阵 + +| 功能 / 角色 | 财务主管 | 总账会计 | 出纳 | HR | +|---|---:|---:|---:|---:| +| 查看工作台 | ✓ | ✓ | ✓ | ✓ | +| 上传文件 | ✓ | ✓ | - | ✓ | +| 确认字段映射 | ✓ | ✓ | - | - | +| 查看异常清单 | ✓ | ✓ | ✓ | ✓（仅上传相关） | +| 处理异常 | ✓ | ✓ | - | - | +| 查看成本分析 | ✓ | ✓ | ✓ | - | +| 生成凭证 | ✓ | ✓ | - | - | +| 导出凭证 | ✓ | ✓ | - | - | +| 管理企业规则 | ✓ | ✓ | - | - | +| 管理成员权限 | ✓ | - | - | - | +| 查看审计日志 | ✓ | - | - | - | +| 删除历史数据 | ✓ | - | - | - | + +### 7.1 权限码规划 + +| 权限码 | 含义 | +|---|---| +| `PERM_TASK_VIEW` | 查看对账任务 | +| `PERM_TASK_CREATE` | 创建对账任务 | +| `PERM_FILE_UPLOAD` | 上传文件 | +| `PERM_MAPPING_CONFIRM` | 确认字段映射 | +| `PERM_EXCEPTION_HANDLE` | 处理异常 | +| `PERM_ANALYSIS_VIEW` | 查看成本分析 | +| `PERM_VOUCHER_GENERATE` | 生成凭证 | +| `PERM_EXPORT_DOWNLOAD` | 下载导出文件 | +| `PERM_RULE_MANAGE` | 管理企业规则 | +| `PERM_MEMBER_MANAGE` | 管理成员权限 | +| `PERM_AUDIT_VIEW` | 查看审计日志 | +| `PERM_DATA_DELETE` | 删除历史数据 | + +## 8. UI/UX 设计原则 + +### 8.1 AI Native 体验基调 + +- 专业、克制、清晰，避免娱乐化表达。 +- 重点突出“系统已经理解了什么、发现了什么、建议下一步做什么”。 +- 不使用 emoji 作为 UI 图标，优先使用 Lucide Icons。 +- 金额、状态、异常等级、处理进度、AI 置信度统一视觉规范。 +- AI 不应表现为聊天玩具，而应表现为财务流程中的“副驾驶”：能解释、能建议、能记住企业规则，但关键节点必须由人确认。 + +### 8.2 AI Native 布局结构 + +每个主页面采用统一结构： + +```text +页面标题区：标题、业务说明、主操作按钮 + ↓ +AI 建议区：当前状态总结、风险提醒、下一步建议 + ↓ +关键状态区：处理进度、统计卡片、置信度、待确认事项 + ↓ +筛选/操作区：月份、任务状态、异常类型、搜索 + ↓ +内容区：表格、列表、分析图表、凭证预览 + ↓ +依据与反馈区：AI 判断依据、加载、空态、错误、导出状态 +``` + +AI 建议区不是装饰区，必须满足至少一个目标： + +- 降低用户判断成本。 +- 提醒用户缺失信息。 +- 解释异常或成本变化原因。 +- 引导用户进入下一步。 +- 沉淀企业规则。 + +### 8.3 AI 输出展示规范 + +| AI 输出类型 | 展示内容 | 必须提供 | +|---|---|---| +| 字段识别 | 源字段、标准字段、置信度、样例值 | 修改入口、保存规则入口 | +| 异常判断 | 异常类型、严重程度、原因、影响范围 | 处理动作、忽略原因记录 | +| 成本分析 | 变化金额、变化比例、主要原因 | 追问入口、导出入口 | +| 凭证建议 | 科目、借贷方向、金额、摘要 | 人工确认、修改入口 | +| 下一步建议 | 当前卡点、推荐动作、预计耗时 | 用户可跳过或手动处理 | + +### 8.4 AI 追问入口设计 + +AI 追问不作为 MVP 的完整开放聊天系统，而是围绕当前任务上下文提供有限问题入口。 + +MVP 推荐预置问题： + +- 本月还缺哪些文件？ +- 哪些字段需要人工确认？ +- 哪些异常最严重？ +- 为什么本月人工成本上涨？ +- 哪些部门变化最大？ +- 现在可以生成金蝶凭证吗？ + +第二阶段再扩展为自然语言自由问答。 + +### 8.5 面向财务人员的 AI Native 约束 + +该模式更适合财务人员，但必须满足以下约束： + +| 财务人员特征 | UI/UX 设计响应 | +|---|---| +| 重视确定性，不喜欢黑盒 | 所有 AI 判断必须展示依据、来源和置信度 | +| 工作按月份和流程推进 | 主界面按“本月对账流程”组织，而不是按功能散点组织 | +| 不愿频繁学习新系统 | 默认给出下一步动作，减少用户找菜单的成本 | +| 对凭证和金额极度敏感 | AI 只能建议，凭证生成、规则应用、删除数据必须人工确认 | +| 需要可审计和可追溯 | 每个关键确认、修改、忽略动作都记录审计日志 | +| Excel 使用习惯强 | 上传、预览、导出都围绕 Excel 闭环设计 | + +因此，推荐模式不是“让财务人员和 AI 聊天完成工作”，而是： + +```text +AI 识别当前任务状态 + ↓ +AI 给出下一步建议和判断依据 + ↓ +财务人员确认关键节点 + ↓ +系统沉淀企业规则 + ↓ +下月减少重复确认 +``` + +这种模式对财务人员更友好，因为它保留了财务工作需要的确定性、审计性和人工控制权，同时用 AI 减少重复判断和跨表核对。 + +### 8.6 表单交互 + +- 必填项明确标识。 +- 表格上传失败时说明失败原因：格式错误、字段缺失、文件过大、读取失败。 +- 字段映射支持批量确认、单项修改、跳过非必要字段。 +- 提交中显示明确进度，不让用户误以为系统卡死。 + +### 8.7 列表与表格 + +- 所有任务列表支持月份筛选、状态筛选、关键字搜索。 +- 异常清单支持按异常类型、严重程度、部门、员工筛选。 +- 表格必须覆盖加载、空数据、错误、筛选无结果、分页、排序状态。 +- 金额列右对齐，日期统一格式 `YYYY-MM-DD`。 + +### 8.8 状态设计 + +| 状态 | 使用场景 | 展示要求 | +|---|---|---| +| 加载中 | 文件解析、AI 识别、对账处理 | 显示步骤和预计耗时 | +| 空态 | 无任务、无异常、无导出文件 | 给出下一步动作 | +| 错误 | 上传失败、处理失败、导出失败 | 给出原因和恢复路径 | +| 成功 | 对账完成、导出完成 | 展示结果入口 | +| 权限不足 | 访问受限功能 | 明确说明需要哪个角色 | + +### 8.9 响应式设计 + +- MVP 优先 PC Web，适配 1440px、1280px、1024px 宽度。 +- 小屏幕不作为第一优先级，但关键列表不可横向严重溢出。 +- 移动端完整体验放到第二阶段以后。 + +### 8.10 可访问性 + +- 关键操作按钮有明确文字，不只依赖图标。 +- 表单错误提示与字段关联。 +- 状态颜色不作为唯一信息来源，需要文字标签。 +- 支持键盘基础操作和焦点状态。 + +### 8.11 数据可视化设计 + +财务人员需要直观的数据展示来快速理解成本变化、异常分布和趋势，因此数据可视化是核心体验的一部分。 + +#### 图表选择原则 + +| 数据类型 | 推荐图表 | 使用场景 | +|---|---|---| +| 趋势对比 | 折线图 | 环比变化、同比趋势、月度成本走势 | +| 占比分析 | 饼图/环形图 | 部门成本占比、费用类型占比、异常类型分布 | +| 多维对比 | 柱状图/条形图 | 部门工资对比、月度对比、多部门成本排名 | +| 明细数据 | 表格 | 员工薪酬明细、异常清单、凭证分录 | +| 关联分析 | 堆叠柱状图 | 工资+社保+公积金分层展示 | + +#### 数据展示要求 + +**关键指标卡片**： +- 使用大号字体（32-48px）展示核心数值 +- 环比变化用颜色区分：上涨（红色 #EF4444）、下降（绿色 #10B981）、持平（灰色 #6B7280） +- 显示变化金额和百分比，例如：`↑ 5.2万 (+8.3%)` +- 提供上下文说明，例如："较上月增加，主要因新增3名员工" + +**图表交互**： +- 所有图表必须可交互（点击查看明细、悬停显示数值） +- 支持维度切换（按部门/按费用类型/按月份） +- 支持数据筛选（隐藏特定部门、筛选时间范围） +- 提供导出功能（导出当前视图数据为 Excel） + +**颜色规范**： +- 使用统一调色板，避免过于鲜艳或混乱的颜色 +- 部门颜色固定分配（同一部门在不同图表中颜色一致） +- 异常严重程度：高（#EF4444）、中（#F59E0B）、低（#3B82F6） +- 置信度：高（#10B981）、中（#F59E0B）、低（#EF4444） + +**MVP 图表清单**： +1. **工作台页面**： + - 成本总额趋势卡片（数值+环比） + - 本月异常分布饼图 + +2. **成本分析页面**： + - 部门成本柱状图（支持切换到费用类型） + - 环比变化折线图（最近6个月） + - 部门成本占比饼图 + - 成本明细表格（可展开查看人员） + +3. **异常清单页面**： + - 异常类型分布饼图 + - 严重程度统计卡片 + +**响应式要求**： +- 图表在不同屏幕尺寸下自动缩放 +- 小屏幕下图表堆叠显示，不横向溢出 +- 图例放置在合理位置，不遮挡数据 + +## 9. 公共组件抽取规划 + +### 9.1 基础组件 + +| 组件 | 类型 | 适用场景 | 输入状态 | 输出事件 | 使用页面 | +|---|---|---|---|---|---| +| `PageLayout` | 布局组件 | 所有后台页面 | `title` / `description` / `actions` | - | 全局 | +| `PageHeader` | 布局组件 | 页面头部 | `title` / `breadcrumbs` / `primaryAction` | `onAction` | 全局 | +| `ContentCard` | 容器组件 | 信息区块 | `title` / `loading` / `error` | - | 全局 | +| `DataTable` | 数据组件 | 任务、异常、日志列表 | `columns` / `data` / `loading` / `pagination` | `onPageChange` / `onSort` | 多页面 | +| `StatusBadge` | 状态组件 | 任务状态、异常等级 | `status` / `variant` | - | 多页面 | +| `EmptyState` | 反馈组件 | 空任务、空异常、无导出 | `title` / `description` / `action` | `onAction` | 多页面 | +| `ErrorState` | 反馈组件 | 加载失败、处理失败 | `message` / `recoverAction` | `onRecover` | 多页面 | +| `ConfirmDialog` | 交互组件 | 删除、忽略异常、重新处理 | `title` / `description` / `danger` | `onConfirm` / `onCancel` | 多页面 | + +### 9.2 组合组件 + +| 组件 | 类型 | 适用场景 | 输入状态 | 输出事件 | 使用页面 | +|---|---|---|---|---|---| +| `FileDropzone` | 上传组件 | 上传工资/社保/个税表 | `accept` / `maxSize` / `files` | `onUpload` / `onRemove` | 上传页面 | +| `TaskProgressStepper` | 流程组件 | 展示处理阶段 | `currentStep` / `steps` / `status` | `onStepClick` | 工作台、任务详情 | +| `MonthSelector` | 筛选组件 | 按月份查看任务和数据 | `month` | `onChange` | 工作台、任务列表 | +| `FilterBar` | 筛选组件 | 任务、异常、日志筛选 | `filters` | `onChange` / `onReset` | 多页面 | +| `MetricCard` | 指标组件 | 成本总额、异常数、处理耗时 | `label` / `value` / `trend` | - | 工作台、成本分析 | +| `ExportButton` | 导出组件 | 下载结果文件 | `fileType` / `loading` | `onExport` | 结果页、导出中心 | + +### 9.3 领域组件 + +| 组件 | 类型 | 适用场景 | 输入状态 | 输出事件 | 使用页面 | +|---|---|---|---|---|---| +| `FieldMappingTable` | 领域组件 | 字段映射确认 | `sourceFields` / `standardFields` / `confidence` | `onConfirm` / `onEdit` | 字段映射页 | +| `ExceptionList` | 领域组件 | 异常查看和处理 | `exceptions` / `filters` | `onResolve` / `onIgnore` | 异常清单页 | +| `CostBreakdownChart` | 领域组件 | 成本拆分展示 | `breakdown` / `dimension` | `onDimensionChange` | 成本分析页 | +| `VoucherPreviewTable` | 领域组件 | 凭证预览 | `entries` / `accounts` | `onEdit` / `onConfirm` | 凭证预览页 | +| `RuleMappingEditor` | 领域组件 | 企业规则维护 | `rules` / `ruleType` | `onSave` / `onDelete` | 企业规则页 | + +### 9.4 AI Native 组件 + +| 组件 | 类型 | 适用场景 | 输入状态 | 输出事件 | 使用页面 | +|---|---|---|---|---|---| +| `AIAssistantPanel` | AI 组件 | 页面右侧追问和建议 | `context` / `suggestedQuestions` / `loading` | `onAsk` / `onApplySuggestion` | AI 工作台、成本分析 | +| `NextActionCard` | AI 组件 | 推荐下一步动作 | `action` / `reason` / `priority` / `estimateTime` | `onExecute` / `onDismiss` | AI 工作台、流程页 | +| `AIInsightCard` | AI 组件 | 展示 AI 摘要和解释 | `summary` / `evidence` / `confidence` | `onExpandEvidence` | 工作台、异常、成本分析 | +| `ConfidenceBadge` | AI 组件 | 展示 AI 置信度 | `score` / `level` | - | 字段确认、凭证预览 | +| `EvidencePanel` | AI 组件 | 展示判断依据 | `evidenceItems` / `source` | `onOpenSource` | 字段确认、异常、凭证 | +| `HumanConfirmGate` | AI 组件 | 人工确认关键节点 | `riskLevel` / `confirmText` | `onConfirm` / `onCancel` | 凭证、删除、规则应用 | + +### 9.5 组件登记要求 + +开发进入阶段 5 后，一旦创建上述组件，必须同步创建或更新 `pmdocs/ui-components.md`，记录组件名、类型、适用场景、输入状态、输出事件、使用页面、维护状态。 + +## 10. 数据对象与状态机 + +### 10.1 核心数据对象 + +| 对象 | 说明 | 关键字段 | +|---|---|---| +| 企业 `Company` | 租户主体 | 企业名称、套餐、数据保留策略 | +| 用户 `User` | 登录账号 | 姓名、手机号/邮箱、角色、状态 | +| 对账任务 `ReconciliationTask` | 一次月度处理任务 | 月份、状态、上传文件、处理结果 | +| 上传文件 `UploadedFile` | 用户上传的 Excel | 文件类型、大小、解析状态、存储路径 | +| 字段映射 `FieldMapping` | 源字段到标准字段的关系 | 源字段、标准字段、置信度、确认状态 | +| 异常项 `ExceptionItem` | 对账发现的问题 | 异常类型、严重程度、员工、处理状态 | +| 成本分析 `CostAnalysis` | 聚合分析结果 | 总额、部门拆分、环比变化 | +| 凭证 `Voucher` | 生成的凭证结果 | 借贷方、科目、金额、摘要 | +| 企业规则 `CompanyRule` | 企业可复用配置 | 规则类型、匹配条件、动作 | +| 审计日志 `AuditLog` | 操作追踪 | 操作人、动作、对象、时间 | + +### 10.2 对账任务状态机 + +```text +草稿 DRAFT + ↓ 上传文件 +文件已上传 FILE_UPLOADED + ↓ 解析文件 +解析中 PARSING + ↓ 解析完成 +待字段确认 WAITING_MAPPING_CONFIRM + ↓ 用户确认字段 +对账处理中 RECONCILING + ↓ 处理完成 +待异常处理 WAITING_EXCEPTION_REVIEW + ↓ 用户处理异常 +待凭证确认 WAITING_VOUCHER_CONFIRM + ↓ 用户确认凭证 +已完成 COMPLETED + ↓ 用户导出 +已导出 EXPORTED +``` + +异常路径： + +```text +任意处理中状态 + ↓ 失败 +失败 FAILED + ↓ 用户重试 +回到上一稳定状态 +``` + +### 10.3 异常项状态机 + +```text +待处理 OPEN + ↓ 用户确认已修正 +已修正 RESOLVED + +待处理 OPEN + ↓ 用户忽略本次 +本次忽略 IGNORED_ONCE + +待处理 OPEN + ↓ 用户忽略此类 +规则忽略 IGNORED_BY_RULE +``` + +## 11. 输出文件规划 + +### 11.1 MVP 输出文件 + +| 文件 | 文件名示例 | 内容 | 面向用户 | +|---|---|---|---| +| 异常清单 | `异常清单_20260706.xlsx` | 异常类型、员工、原因、建议处理 | 财务 + HR | +| 人工成本分析 | `人工成本分析_20260706.xlsx` | 成本总额、部门拆分、环比变化 | 财务主管 + 老板 | +| 金蝶凭证 | `金蝶凭证_20260706.xlsx` | 可导入金蝶的凭证模板 | 总账会计 | + +### 11.2 输出顺序 + +```text +1_异常清单 +2_人工成本分析 +3_金蝶凭证 +``` + +第二阶段再增加： + +```text +2_对账报告 +5_部门成本明细 +6_员工薪酬汇总 +处理日志 +``` + +## 12. 非功能性产品要求 + +### 12.1 性能体验 + +- 200 人企业数据从上传到输出不超过 30 秒。 +- AI 字段识别不超过 5 秒。 +- 凭证生成不超过 3 秒。 +- 长耗时任务必须展示进度，不允许空白等待。 + +### 12.2 数据安全 + +- 多租户隔离作为底层架构约束。 +- 薪酬数据加密存储。 +- 审计日志覆盖上传、识别、处理、导出、删除。 +- 删除数据必须二次确认，并记录操作日志。 + +### 12.3 私有化部署 + +- MVP 架构必须支持 Docker Compose 部署。 +- 配置通过环境变量管理。 +- 不把密钥写入代码或文档。 +- 私有化部署必须有独立的初始化、迁移、备份说明。 + +## 13. 外部依赖、内部依赖与风险 + +### 13.1 外部依赖 + +| 依赖 | 用途 | 风险 | 应对 | +|---|---|---|---| +| LLM API | 字段识别、语义映射 | 成本、稳定性、隐私 | 支持可替换模型，私有化时支持企业自配 | +| 金蝶导入模板 | 凭证输出格式 | 不同版本格式差异 | 先支持主流模板，规则化配置 | +| 用户 Excel 数据 | 输入来源 | 格式混乱、字段缺失 | 上传前校验，字段映射确认 | + +### 13.2 内部依赖 + +| 依赖 | 说明 | +|---|---| +| 企业规则库 | 字段映射、科目映射、部门规则复用 | +| 文件解析模块 | 支持 xls/xlsx/csv | +| 对账规则引擎 | 支持异常检测规则可配置 | +| 导出模板引擎 | 支持 Excel 输出和金蝶模板适配 | +| 权限系统 | 支撑多角色访问控制 | + +### 13.3 主要风险 + +| 风险 | 影响 | 应对 | +|---|---|---| +| AI 字段识别不稳定 | 用户修正成本增加 | 加入确认页、企业规则复用、模板库 | +| 异常误报率高 | 用户不信任系统 | 支持忽略规则、标注严重程度、解释原因 | +| 数据安全事故 | 产品信任崩塌 | 加密、审计、多租户隔离、权限控制 | +| 金蝶格式不统一 | 导入失败 | 模板配置化，先支持主流版本 | +| MVP 范围膨胀 | 延期 | 第一阶段严格只做三类输入和三类输出 | + +## 14. 版本规划 + +### 14.1 第一阶段：薪酬财务对账 MVP + +目标：验证财务人员是否愿意为薪酬对账和凭证生成付费，并验证财务 AI 助手的第一条可复用链路。 + +包含： +- 手动上传工资表、社保表、个税表 +- AI 字段映射 +- 异常清单 +- 人工成本分析 +- 金蝶凭证模板导出 +- 企业规则沉淀 +- 多租户、安全、审计基础能力 + +不包含： +- 自动文件夹监控 +- 金蝶 API 对接 +- 移动端 +- 完整自然语言问答 +- 复杂审批流 +- 发票报销、预算、现金流、往来对账等其他财务模块 + +### 14.2 第二阶段：薪酬模块历史对比与自动化 + +目标：提升薪酬模块留存和使用便利性。 + +包含： +- 历史月份数据保存和环比分析 +- 自动文件夹监控 +- 可选输入文件支持 +- 自然语言问答 +- 企业微信/邮件通知 + +### 14.3 第三阶段：金蝶生态连接 + +目标：从单点工具变成金蝶生态补充应用。 + +包含： +- 金蝶 API 对接 +- 多账套支持 +- 行业模板库 +- 代账公司批量管理 + +### 14.4 第四阶段：财务 AI 助手扩展 + +目标：从薪酬财务对账扩展为覆盖多类财务高频工作的 AI 助手。 + +包含： +- 发票与报销 AI 助手：发票识别、真伪核验、报销单匹配、费用凭证生成 +- 预算执行 AI 分析：预算表导入、实际发生对比、超预算提醒、差异解释 +- 现金流异常 AI 监控：银行流水导入、资金属性识别、可动用资金分析、异常提醒 +- 往来对账 AI 助手：客户/供应商往来、发票、回款、付款自动匹配 +- 经营分析 AI 看板：经营摘要、费用趋势、异常追踪、老板报表 + +## 15. 需求追踪矩阵 + +| 需求编号 | PRD 功能 | 场景 | 验收重点 | +|---|---|---|---| +| REQ-001 | PRD-FUNC-002 / 003 | SCENE-001 | AI 工作台能引导上传，支持工资、社保、个税三类文件 | +| REQ-002 | PRD-FUNC-004 / 009 | SCENE-002 / 006 | 字段识别准确率 > 90%，可人工修正，可沉淀企业规则 | +| REQ-003 | PRD-FUNC-005 / 006 | SCENE-003 | 覆盖 MVP 7 类异常，并保留第二阶段银行实发对账规则；支持处理状态和 AI 原因解释 | +| REQ-004 | PRD-FUNC-007 | SCENE-004 | 成本总额、部门拆分、变化原因和可追问入口 | +| REQ-005 | PRD-FUNC-008 / 010 | SCENE-005 | 生成可导入金蝶的 Excel 模板，并解释科目匹配依据 | +| NFR-007 | PRD-FUNC-001 / 013 | 全局 | 多租户隔离和角色权限 | +| NFR-008 | PRD-FUNC-011 | 全局 | 审计日志完整记录 | +| NFR-012 | PRD-FUNC-012 | 新手体验 | 示例数据完成完整流程 | + +## 16. 便利性与效率提升关键设计 + +为确保**将薪酬对账从3天压缩到30分钟**的目标，PRD 中已包含以下关键便利性设计： + +### 16.1 减少重复操作 + +| 设计点 | 实现方式 | 效率提升 | +|---|---|---| +| 企业规则自动复用 | 字段映射、科目映射确认后自动保存，下月直接应用 | 第2个月起节省80%字段确认时间 | +| 批量操作 | 异常处理支持批量忽略、批量标记已处理 | 减少逐条点击 | +| 默认建议 | AI 给出最可能的映射和凭证，用户只确认而非从零配置 | 首次使用降低50%配置时间 | +| 历史模板（第二阶段） | 基于企业历史数据生成专属模板，识别准确率提升到95%+ | 月均节省5-10分钟 | + +### 16.2 降低学习成本 + +| 设计点 | 实现方式 | 效率提升 | +|---|---|---| +| AI 工作台主动引导 | 系统告诉用户"当前缺什么、下一步做什么"，无需找菜单 | 新手15分钟完成首次对账 | +| 流程线性化 | 上传→确认→查看→导出，不跳转、不分散 | 避免迷失在多级菜单中 | +| 统一视觉语言 | 所有 AI 输出都包含"置信度、依据、下一步建议" | 降低理解成本 | +| 示例数据引导（Should） | 新用户用示例数据走完流程，理解产品价值 | 首次使用成功率 > 90% | + +### 16.3 提升数据确定性 + +| 设计点 | 实现方式 | 效率提升 | +|---|---|---| +| 依据展开 | AI 判断显示置信度、样例数据、匹配规则 | 财务人员信任 AI 结果 | +| 人工确认门 | 凭证生成、删除数据必须人工点击确认 | 符合财务审慎性要求 | +| 审计日志 | 所有关键操作可追溯到人、时间、动作 | 满足合规和追溯需求 | +| 异常原因解释 | 每个异常都说明"为什么判断为异常、影响范围、建议处理" | 减少财务与HR沟通成本 | + +### 16.4 Excel 无缝对接 + +| 设计点 | 实现方式 | 效率提升 | +|---|---|---| +| 拖拽上传 | 支持拖拽、批量上传、自动识别文件类型 | 符合 Excel 使用习惯 | +| Excel 预览 | 上传后展示表头和样例数据，确认无误再处理 | 避免错传文件 | +| 一键导出 | 异常清单、成本分析、凭证全部导出为 Excel | 财务人员直接用 Excel 查看 | +| 金蝶模板对齐 | 导出格式直接符合金蝶导入规范 | 避免二次编辑 | + +### 16.5 智能纠错与容错 + +| 设计点 | 实现方式 | 效率提升 | +|---|---|---| +| 文件格式自动识别 | 支持 .xls / .xlsx / .csv，自动判断编码 | 用户无需关心格式 | +| 字段容错匹配 | "工资"、"底薪"、"基本工资"识别为同一字段 | 适配不同企业命名习惯 | +| 部分数据可处理 | 即使缺少个税表，也能完成工资-社保对账 | 不因缺失卡住整个流程 | +| 错误可恢复 | 上传错误文件可替换，处理失败可重试 | 降低试错成本 | + +### 16.6 时间节省对照 + +| 传统方式 | 薪财通 AI | 节省时间 | +|---|---|---| +| 人工核对工资表与社保表：2-4小时 | AI 自动对账：30秒 | 节省 95%+ | +| 人工查找离职未停社保：1-2小时 | AI 异常清单：5秒 | 节省 99%+ | +| 人工计算部门成本拆分：1-2小时 | AI 自动生成分析：10秒 | 节省 99%+ | +| 人工制作工资凭证：30-60分钟 | AI 生成凭证模板：5秒 | 节省 98%+ | +| **总计：5-9小时** | **总计：< 30分钟** | **节省 90%+** | + +## 17. 商业化模式建议 + +### 17.1 收费方式建议 + +**按员工人数分档**： +- 50人以内：¥X/月 +- 100人以内：¥X/月 +- 300人以内：¥X/月 +- 500人以内：¥X/月 +- 500人以上：定制报价 + +**套餐版本**： +- 免费版：体验版，限10人/月，保留数据1个月 +- 基础版：薪酬财务对账核心功能（上传、识别、异常、凭证），单账套 +- 专业版：增加历史对比、规则沉淀、成本分析、API导出 +- 企业版：多账套、金蝶API对接、优先支持、私有化部署 +- 财务 AI 助手套件版（第四阶段）：叠加发票报销、预算执行、现金流异常、往来对账和经营分析模块 + +**说明**：具体价格由商务团队根据市场调研确定，本PRD仅提供功能分级建议。 + +### 17.2 获客渠道建议 + +1. **金蝶生态合作**（第三阶段） + - 成为金蝶应用市场合作伙伴 + - 与金蝶代理商合作推广 + +2. **财税服务商渠道** + - 与外包记账公司合作 + - 提供批量处理能力 + +3. **内容营销** + - 财务公众号、知识星球 + - 财务实操教程中植入产品 + +4. **种子用户转介绍** + - MVP阶段重点维护种子用户 + - 建立用户案例库 + +## 18. 待确认问题 + +| 编号 | 问题 | 建议决策 | +|---|---|---| +| Q-001 | MVP 是否需要注册流程，还是由管理员创建企业和账号？ | MVP 采用管理员创建，减少复杂度 | +| Q-002 | 是否允许 HR 上传但不能查看成本分析？ | 允许，符合权限矩阵 | +| Q-003 | 金蝶模板优先支持哪个版本？ | 优先金蝶云星辰和精斗云 | +| Q-004 | LLM 是否必须支持国产模型？ | 架构预留模型切换，私有化客户可自配 | +| Q-005 | 示例数据是否第一版就做？ | 作为 Should，时间允许则做 | + +## 19. 变更历史 + +| 版本 | 日期 | 变更内容 | 变更人 | +|---|---|---|---| +| v1.0 | 2026-07-06 | 初始 PRD，基于已确认需求文档生成 | AI | + +--- + +**当前状态**: PRD 已确认，当前开发任务聚焦第一阶段“薪酬财务对账 MVP”，后续按阶段扩展为完整财务 AI 助手。 \ No newline at end of file diff --git a/pmdocs/2-task-S2F.md b/pmdocs/2-task-S2F.md new file mode 100644 index 0000000..7bddde5 --- /dev/null +++ b/pmdocs/2-task-S2F.md @@ -0,0 +1,3150 @@ +# 财务 AI 助手开发任务文档（第一模块：薪酬财务对账 MVP） + +**项目编号**: S2F +**关联文档**: `pmdocs/0-req-S2F.md`, `pmdocs/1-prd-S2F.md` +**文档版本**: v1.0 +**创建日期**: 2026-07-06 +**状态**: 已确认，待执行 + +**任务范围说明**： +- 本任务文档详细拆解第一阶段“薪酬财务对账 MVP”（第一模块，薪财通 AI） +- 本任务文档不直接实现发票报销、预算执行、现金流异常、往来对账和经营分析 +- 后续财务 AI 助手模块以“后续任务池”形式记录，待第一模块验证后再拆成正式开发任务 + +## 目录 + +1. [项目初始化任务](#1-项目初始化任务) +2. [后端基础设施任务](#2-后端基础设施任务) +3. [前端基础设施任务](#3-前端基础设施任务) +4. [认证与权限任务](#4-认证与权限任务) +5. [文件上传与解析任务](#5-文件上传与解析任务) +6. [AI 字段识别任务](#6-ai-字段识别任务) +7. [对账与异常检测任务](#7-对账与异常检测任务) +8. [人工成本分析任务](#8-人工成本分析任务) +9. [凭证生成任务](#9-凭证生成任务) +10. [UI 组件开发任务](#10-ui-组件开发任务) +11. [页面开发任务](#11-页面开发任务) +12. [测试任务](#12-测试任务) +13. [部署任务](#13-部署任务) +14. [文档任务](#14-文档任务) +15. [任务总结](#15-任务总结) +16. [后续财务 AI 助手模块任务池](#16-后续财务-ai-助手模块任务池) +17. [下一步行动](#17-下一步行动) + +--- + +## 1. 项目初始化任务 + +### TASK-001: 创建项目目录结构 + +**目标**: 创建前后端项目目录和基础配置文件 + +**关联需求**: REQ-001 ~ REQ-005 +**优先级**: P0 (最高) +**阶段**: 初始化 +**依赖**: 无 +**预计工时**: 2 小时 + +**任务内容**: +- [x] 创建项目根目录结构 + ``` + s2f/ + ├── frontend/ + ├── backend/ + ├── pmdocs/ + ├── .gitignore + ├── docker-compose.yml + ├── README.md + └── run.md + ``` +- [x] 创建 `.gitignore` 文件 + - 排除 `node_modules/`, `venv/`, `.env`, `*.pyc`, `.next/`, `uploads/` +- [x] 创建根目录 `README.md` + - 项目简介 + - 技术栈 + - 快速开始指引 + - 指向 `run.md` 和 `pmdocs/` +- [ ] 初始化 Git 仓库 + - `git init`（已完成） + - 首次提交：`git add . && git commit -m "chore: 项目初始化"`（待用户明确授权） + +**验收标准**: +- [x] 目录结构完整 +- [x] `.gitignore` 正确排除敏感文件 +- [x] `README.md` 清晰易读 +- [x] Git 仓库初始化成功 + +**测试方式**: +```bash +# 验证目录结构 +ls -la + +# 验证 Git 状态 +git status +``` + +--- + +### TASK-002: 初始化后端项目 + +**目标**: 创建 FastAPI 项目基础结构和依赖配置 + +**关联需求**: REQ-001 ~ REQ-005, NFR-018, NFR-019 +**优先级**: P0 +**阶段**: 初始化 +**依赖**: TASK-001 +**预计工时**: 3 小时 + +**任务内容**: +- [x] 创建后端目录结构 + ``` + backend/ + ├── app/ + │ ├── __init__.py + │ ├── main.py + │ ├── api/ + │ ├── core/ + │ ├── models/ + │ ├── schemas/ + │ ├── services/ + │ └── utils/ + ├── migrations/ + ├── tests/ + ├── requirements.txt + ├── .env.example + └── pyproject.toml + ``` +- [x] 创建 `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 + ``` +- [x] 创建 `pyproject.toml` (Poetry 配置) +- [x] 创建 `.env.example` 模板 +- [x] 创建 Python 虚拟环境 + ```bash + cd backend + python3 -m venv venv + source venv/bin/activate + pip install -r requirements.txt + ``` + - 本机实际 Python 版本：3.12.13，满足 Python 3.11+ 约束 + +**验收标准**: +- [x] 目录结构完整 +- [x] 依赖安装成功 +- [x] 虚拟环境激活正常 +- [x] 可以 `import fastapi` 无报错 + +**测试方式**: +```bash +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` 创建项目 + ```bash + npx create-next-app@latest frontend --typescript --tailwind --app --no-src + ``` +- [ ] 安装核心依赖 + ```bash + 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 + ```bash + 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 工作正常 +- [ ] 可以启动开发服务器 + +**测试方式**: +```bash +cd frontend +npm run dev +# 访问 http://localhost:3000 查看默认页面 +``` + +--- + +### TASK-004: 配置数据库 + +**目标**: 安装 PostgreSQL 并创建开发数据库 + +**关联需求**: NFR-006, NFR-007, NFR-008 +**优先级**: P0 +**阶段**: 初始化 +**依赖**: TASK-002 +**预计工时**: 1 小时 + +**任务内容**: +- [ ] 安装 PostgreSQL 15+ + ```bash + # macOS + brew install postgresql@15 + brew services start postgresql@15 + ``` +- [ ] 创建数据库和用户 + ```sql + 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` 文件 + ```bash + cd backend + cp .env.example .env + # 编辑 DATABASE_URL + ``` +- [ ] 测试数据库连接 + +**验收标准**: +- [ ] PostgreSQL 服务运行正常 +- [ ] 数据库 `s2f_db` 创建成功 +- [ ] 用户 `s2f_user` 有正确权限 +- [ ] 后端可以连接数据库 + +**测试方式**: +```bash +# 测试连接 +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` + ```yaml + version: '3.8' + services: + postgres: + image: postgres:15-alpine + environment: + POSTGRES_DB: s2f_db + POSTGRES_USER: s2f_user + POSTGRES_PASSWORD: s2f_password + ports: + - "5432:5432" + volumes: + - postgres_data:/var/lib/postgresql/data + + backend: + build: ./backend + environment: + DATABASE_URL: postgresql+asyncpg://s2f_user:s2f_password@postgres:5432/s2f_db + ports: + - "8000:8000" + volumes: + - ./backend:/app + - ./backend/uploads:/app/uploads + depends_on: + - postgres + + frontend: + build: ./frontend + environment: + NEXT_PUBLIC_API_URL: http://localhost:8000 + ports: + - "3000:3000" + volumes: + - ./frontend:/app + - /app/node_modules + depends_on: + - backend + + volumes: + postgres_data: + ``` +- [ ] 创建 `backend/Dockerfile` +- [ ] 创建 `frontend/Dockerfile` +- [ ] 创建 `.dockerignore` 文件 + +**验收标准**: +- [ ] `docker-compose up` 可以启动所有服务 +- [ ] 前端可访问 http://localhost:3000 +- [ ] 后端可访问 http://localhost:8000/docs +- [ ] 数据库可连接 + +**测试方式**: +```bash +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 小时 + +**任务内容**: +- [ ] 创建 `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` + +**测试方式**: +```bash +cd backend +source venv/bin/activate +uvicorn app.main:app --reload +curl http://localhost:8000/api/health +``` + +--- + +### TASK-007: 实现数据库连接与会话管理 + +**目标**: 配置 SQLAlchemy 异步引擎和会话工厂 + +**关联需求**: NFR-006, NFR-016 +**优先级**: P0 +**阶段**: 基础设施 +**依赖**: TASK-004, TASK-006 +**预计工时**: 2 小时 + +**任务内容**: +- [ ] 创建 `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 初始化完成 +- [ ] 可以创建首个迁移 + +**测试方式**: +```bash +cd backend +alembic revision --autogenerate -m "init" +alembic upgrade head +``` + +--- + +### TASK-008: 实现多租户数据隔离 + +**目标**: 创建企业（Company）模型和租户隔离机制 + +**关联需求**: NFR-007 +**优先级**: P0 +**阶段**: 基础设施 +**依赖**: TASK-007 +**预计工时**: 3 小时 + +**任务内容**: +- [ ] 创建 `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 模型创建成功 +- [ ] 租户隔离机制生效 +- [ ] 不同企业数据互相不可见 +- [ ] 数据库迁移成功 + +**测试方式**: +```python +# 创建两个企业，验证数据隔离 +company1 = await company_service.create_company(...) +company2 = await company_service.create_company(...) +# 验证 company1 无法访问 company2 的数据 +``` + +--- + +### TASK-009: 实现异常处理与错误响应 + +**目标**: 统一异常处理和错误响应格式 + +**关联需求**: NFR-011 +**优先级**: P1 +**阶段**: 基础设施 +**依赖**: TASK-006 +**预计工时**: 2 小时 + +**任务内容**: +- [ ] 创建 `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 错误有明确提示 +- [ ] 日志正确记录异常堆栈 + +**测试方式**: +```python +# 触发异常，验证响应格式 +raise NotFoundException("Company not found") +# 预期返回: {"error": {"code": "NOT_FOUND", "message": "Company not found"}} +``` + +--- + +### TASK-010: 实现审计日志基础设施 + +**目标**: 创建审计日志模型和记录机制 + +**关联需求**: NFR-008 +**优先级**: P1 +**阶段**: 基础设施 +**依赖**: TASK-007, TASK-008 +**预计工时**: 3 小时 + +**任务内容**: +- [ ] 创建 `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 端点添加审计日志 + +**验收标准**: +- [ ] 审计日志模型创建成功 +- [ ] 关键操作被记录 +- [ ] 日志包含必要字段 +- [ ] 可以按用户/时间查询日志 + +**测试方式**: +```python +# 执行操作后查询审计日志 +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 小时 + +**任务内容**: +- [ ] 创建 `frontend/lib/api/client.ts` + - 使用 Axios 创建实例 + - 配置 baseURL、timeout、headers + - 实现请求拦截器：自动添加 JWT token + - 实现响应拦截器：统一错误处理 +- [ ] 创建 `frontend/lib/api/types.ts` + - 定义通用类型：`ApiResponse`, `ApiError`, `PaginatedResponse` +- [ ] 创建 `frontend/lib/api/endpoints.ts` + - 定义 API 端点常量 + - 示例：`ENDPOINTS.AUTH.LOGIN`, `ENDPOINTS.COMPANY.LIST` + +**验收标准**: +- [ ] API 客户端初始化成功 +- [ ] 拦截器正常工作 +- [ ] 错误统一处理 +- [ ] TypeScript 类型完整 + +**测试方式**: +```typescript +// 测试健康检查 +const response = await apiClient.get('/api/health'); +console.log(response.data); +``` + +--- + +### TASK-012: 实现全局状态管理 + +**目标**: 使用 Zustand 创建全局状态 Store + +**关联需求**: REQ-001 ~ REQ-005 +**优先级**: P0 +**阶段**: 基础设施 +**依赖**: TASK-003 +**预计工时**: 2 小时 + +**任务内容**: +- [ ] 创建 `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 类型安全 + +**测试方式**: +```typescript +const { user, login } = useAuthStore(); +await login({ email, password }); +console.log(useAuthStore.getState().user); +``` + +--- + +### TASK-013: 实现路由守卫与权限控制 + +**目标**: 创建受保护路由和权限检查机制 + +**关联需求**: NFR-007 +**优先级**: P0 +**阶段**: 基础设施 +**依赖**: TASK-011, TASK-012 +**预计工时**: 3 小时 + +**任务内容**: +- [ ] 创建 `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` + - 检查路由访问权限 + +**验收标准**: +- [ ] 未登录用户无法访问受保护页面 +- [ ] 权限检查正常工作 +- [ ] 无权限时显示友好提示 +- [ ] 路由守卫覆盖所有需要保护的路由 + +**测试方式**: +```typescript +// 未登录访问受保护路由 +router.push('/dashboard'); +// 预期重定向到 /login +``` + +--- + +### TASK-014: 实现主题与样式系统 + +**目标**: 配置 Tailwind CSS 和 Shadcn/ui 主题 + +**关联需求**: NFR-010 +**优先级**: P1 +**阶段**: 基础设施 +**依赖**: TASK-003 +**预计工时**: 2 小时 + +**任务内容**: +- [ ] 配置 `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 组件 + ```bash + 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 组件可用 +- [ ] 深色模式切换正常 + +**测试方式**: +```tsx +import { Button } from '@/components/ui/button'; + +``` + +--- + +### TASK-015: 实现通用 Hooks + +**目标**: 创建常用自定义 React Hooks + +**关联需求**: REQ-001 ~ REQ-005 +**优先级**: P1 +**阶段**: 基础设施 +**依赖**: TASK-011, TASK-012 +**预计工时**: 2 小时 + +**任务内容**: +- [ ] 创建 `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 类型完整 +- [ ] 有使用示例 +- [ ] 无内存泄漏 + +**测试方式**: +```typescript +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 小时 + +**任务内容**: +- [ ] 创建 `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 生成/解析正常 +- [ ] 数据库迁移成功 + +**测试方式**: +```python +# 测试密码加密 +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 小时 + +**任务内容**: +- [ ] 创建 `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 验证正常 +- [ ] 错误提示友好（邮箱不存在、密码错误） +- [ ] 审计日志记录登录行为 + +**测试方式**: +```bash +# 测试登录 +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 " +``` + +--- + +### TASK-018: 实现权限检查中间件 + +**目标**: 创建权限验证装饰器和依赖 + +**关联需求**: NFR-007, PRD-FUNC-001 +**优先级**: P0 +**阶段**: 核心功能 +**依赖**: TASK-016, TASK-017 +**预计工时**: 2 小时 + +**任务内容**: +- [ ] 创建 `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 性能 + +**测试方式**: +```python +# 测试权限检查 +@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 小时 + +**任务内容**: +- [ ] 创建 `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 小时 + +**任务内容**: +- [ ] 创建后端 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 小时 + +**任务内容**: +- [ ] 创建 `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}` - 删除文件 + +**验收标准**: +- [ ] 文件上传成功 +- [ ] 文件大小/类型验证生效 +- [ ] 文件存储路径正确 +- [ ] 多租户文件隔离 + +**测试方式**: +```bash +curl -X POST http://localhost:8000/api/files/upload \ + -H "Authorization: Bearer " \ + -F "file=@test.xlsx" \ + -F "file_type=SALARY" +``` + +--- + +### TASK-022: 实现 Excel 文件解析 + +**目标**: 解析 Excel 文件并提取表头和样例数据 + +**关联需求**: REQ-001, REQ-002, PRD-FUNC-003 +**优先级**: P0 +**阶段**: 核心功能 +**依赖**: TASK-021 +**预计工时**: 4 小时 + +**任务内容**: +- [ ] 创建 `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 文件解析成功 +- [ ] 表头提取正确 +- [ ] 样例数据完整 +- [ ] 处理空值、特殊字符 + +**测试方式**: +```python +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 小时 + +**任务内容**: +- [ ] 创建 `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` + - `getFileInfo(fileId: string) => Promise` + - `deleteFile(fileId: string) => Promise` + +**验收标准**: +- [ ] 拖拽上传正常工作 +- [ ] 文件类型验证生效 +- [ ] 上传进度显示正确 +- [ ] 错误提示友好 + +**测试方式**: +``` +1. 拖拽 .xlsx 文件到上传区 +2. 验证上传进度显示 +3. 验证上传成功后文件列表更新 +4. 拖拽 .pdf 文件，验证拒绝提示 +``` + +--- + +### TASK-024: 实现对账任务模型 + +**目标**: 创建对账任务模型和状态机 + +**关联需求**: REQ-001 ~ REQ-005, PRD-FUNC-002 +**优先级**: P0 +**阶段**: 核心功能 +**依赖**: TASK-008, TASK-016, TASK-021 +**预计工时**: 3 小时 + +**任务内容**: +- [ ] 创建 `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]` +- [ ] 实现状态机转换验证 + - 只允许合法的状态转换 + - 记录状态变更日志 + +**验收标准**: +- [ ] 对账任务模型创建成功 +- [ ] 状态机转换正常 +- [ ] 支持按月份查询 +- [ ] 数据库迁移成功 + +**测试方式**: +```python +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 小时 + +**任务内容**: +- [ ] 创建 `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 小时 + +**任务内容**: +- [ ] 创建 `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 秒 +- [ ] 错误重试正常 + +**测试方式**: +```python +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 小时 + +**任务内容**: +- [ ] 创建 `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]` + +**验收标准**: +- [ ] 字段映射保存成功 +- [ ] 企业规则沉淀正常 +- [ ] 规则复用生效 +- [ ] 第二次上传自动应用规则 + +**测试方式**: +```python +# 第一次确认映射 +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 端点正常工作 +- [ ] 异步任务执行成功 +- [ ] 映射结果正确返回 +- [ ] 审计日志记录操作 + +**测试方式**: +```bash +# 触发识别 +curl -X POST http://localhost:8000/api/tasks/1/recognize \ + -H "Authorization: Bearer " + +# 获取映射 +curl http://localhost:8000/api/tasks/1/mappings \ + -H "Authorization: Bearer " +``` + +--- + +### TASK-030: 实现字段映射规则复用 + +**目标**: 实现企业规则自动应用和优先级管理 + +**关联需求**: REQ-002, PRD-FUNC-009, SCENE-006 +**优先级**: P1 +**阶段**: 核心功能 +**依赖**: TASK-027, TASK-029 +**预计工时**: 3 小时 + +**任务内容**: +- [ ] 优化 `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` - 金额标准化 +- [ ] 创建数据验证规则 + - 必填字段检查 + - 金额范围检查 + - 日期格式检查 + - 部门代码有效性检查 + +**验收标准**: +- [ ] 数据清洗成功 +- [ ] 无效数据被过滤 +- [ ] 格式统一标准化 +- [ ] 清洗后数据可用于对账 + +**测试方式**: +```python +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 小时 + +**任务内容**: +- [ ] 创建 `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人数据） + +**测试方式**: +```python +# 构造测试数据：已离职员工仍有工资 +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 小时 + +**任务内容**: +- [ ] 创建 `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` + +**验收标准**: +- [ ] 异常查询正常 +- [ ] 筛选功能生效 +- [ ] 处理/忽略状态更新 +- [ ] 审计日志记录操作 + +**测试方式**: +```python +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 小时 + +**任务内容**: +- [ ] 创建 `frontend/app/(dashboard)/tasks/[id]/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 小时 + +**任务内容**: +- [ ] 创建 `backend/app/services/export/exception_exporter.py` + - `export_exceptions_to_excel(task_id: int) -> bytes` + - 生成异常清单 Excel + - 包含：异常类型、严重程度、员工、描述、建议处理、状态 + - 多个 Sheet：按严重程度分类 + - `export_reconciliation_report(task_id: int) -> bytes` + - 生成对账报告 + - 包含：工资 vs 社保 vs 个税对比、差异统计 +- [ ] 创建 API + - `GET /api/tasks/{task_id}/export/exceptions` + - `GET /api/tasks/{task_id}/export/report` +- [ ] 前端下载功能 + - 点击导出按钮触发下载 + - 显示导出进度 + - 文件命名：`异常清单_2026-07_公司名.xlsx` + +**验收标准**: +- [ ] Excel 文件生成成功 +- [ ] 格式美观易读 +- [ ] 包含所有必要信息 +- [ ] 下载功能正常 + +**测试方式**: +```bash +curl -o exceptions.xlsx \ + http://localhost:8000/api/tasks/1/export/exceptions \ + -H "Authorization: Bearer " +# 打开 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秒 + +**测试方式**: +```python +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秒 +- [ ] 生成的问题有价值 + +**测试方式**: +```python +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句话） + +**测试方式**: +```python +# 测试获取预置问题 +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 返回完整数据 +- [ ] 缓存机制生效 +- [ ] 导出功能正常 +- [ ] 审计日志完整 + +**测试方式**: +```bash +curl http://localhost:8000/api/tasks/1/analysis/cost \ + -H "Authorization: Bearer " +``` + +--- + +### 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 包含所有维度数据 +- [ ] 格式美观专业 +- [ ] 可直接用于汇报 +- [ ] 下载正常 + +**测试方式**: +```bash +curl -o cost_analysis.xlsx \ + http://localhost:8000/api/tasks/1/analysis/export \ + -H "Authorization: Bearer " +# 打开验证内容完整性 +``` + +--- + +**本章节完成进度**: 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 + +**验收标准**: +- [ ] 科目映射模型创建成功 +- [ ] 凭证模板定义完整 +- [ ] 支持企业自定义科目 +- [ ] 数据库迁移成功 + +**测试方式**: +```python +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` - 借贷平衡验证 + +**验收标准**: +- [ ] 凭证生成正确 +- [ ] 借贷必须平衡 +- [ ] 科目映射准确 +- [ ] 摘要描述清晰 + +**测试方式**: +```python +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` + +**验收标准**: +- [ ] 导出格式符合金蝶规范 +- [ ] 可成功导入金蝶 +- [ ] 支持多个金蝶版本 +- [ ] 文件命名规范 + +**测试方式**: +```bash +curl -o kingdee_vouchers.xlsx \ + "http://localhost:8000/api/tasks/1/vouchers/export/kingdee?template=cloud" \ + -H "Authorization: Bearer " +# 尝试导入金蝶验证 +``` + +--- + +### 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 + ```bash + 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 可自动运行测试 + +**测试方式**: +```bash +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 端点有测试 +- [ ] 完整流程测试通过 +- [ ] 权限测试覆盖 +- [ ] 多租户隔离验证 + +**测试方式**: +```bash +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 测试覆盖 +- [ ] 所有测试通过 + +**测试方式**: +```bash +cd frontend +npm run test +``` + +--- + +### TASK-059: 实现端到端测试 + +**目标**: 使用 Playwright 测试完整用户流程 + +**关联需求**: NFR-018 +**优先级**: P2 +**阶段**: 测试 +**依赖**: TASK-051 ~ TASK-055 +**预计工时**: 8 小时 + +**任务内容**: +- [ ] 安装 Playwright + ```bash + npm init playwright@latest + ``` +- [ ] 编写登录流程测试 `tests/e2e/auth.spec.ts` +- [ ] 编写完整对账流程测试 `tests/e2e/reconciliation.spec.ts` + - 登录 → 创建任务 → 上传文件 → 确认字段 → 查看异常 → 查看成本 → 生成凭证 → 导出 +- [ ] 编写权限测试 `tests/e2e/permissions.spec.ts` +- [ ] 编写响应式测试（不同屏幕尺寸） +- [ ] 配置 CI/CD 自动运行 + +**验收标准**: +- [ ] 完整流程 E2E 测试通过 +- [ ] 关键路径覆盖 +- [ ] 可在 CI 中运行 + +**测试方式**: +```bash +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 用户 +- [ ] 无明显性能瓶颈 + +**测试方式**: +```bash +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） +- [ ] 容器启动正常 +- [ ] 健康检查生效 + +**测试方式**: +```bash +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 压缩生效 + +**测试方式**: +```bash +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 或 环境变量注入 +- [ ] 移除所有硬编码密钥 + +**验收标准**: +- [ ] 无硬编码密钥 +- [ ] 环境变量文档完整 +- [ ] 生产环境可安全配置 +- [ ] 验证脚本可用 + +**测试方式**: +```bash +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` +- [ ] 测试备份和恢复流程 + +**验收标准**: +- [ ] 备份脚本正常工作 +- [ ] 定时任务配置正确 +- [ ] 恢复脚本可用 +- [ ] 备份文件完整 + +**测试方式**: +```bash +./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 响应时间 + +**验收标准**: +- [ ] 日志格式统一 +- [ ] 健康检查端点正常 +- [ ] 监控脚本可用 +- [ ] 日志可查询 + +**测试方式**: +```bash +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. 第1周：项目初始化 + 后端基础设施（TASK-001 ~ TASK-010） +2. 第2周：前端基础设施 + 认证与权限（TASK-011 ~ TASK-020） +3. 第3-4周：文件上传 + AI 识别（TASK-021 ~ TASK-030） +4. 第5-6周：对账异常 + 成本分析（TASK-031 ~ TASK-040） +5. 第7-8周：凭证生成 + UI 组件（TASK-041 ~ TASK-050） +6. 第9-10周：页面开发（TASK-051 ~ TASK-055） +7. 第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. 下一步行动 + +**立即开始**： +1. 执行 TASK-001：创建项目目录结构 +2. 初始化 Git 仓库并完成首次提交 +3. 按任务顺序推进 MVP 开发 + +**执行规范**： +- 每完成一个任务，在本文档中勾选 `- [x]` +- 更新 `pmdocs/2-task-S2F.md` +- 必要时创建 Git 提交 +- 遇到阻塞及时记录到任务备注 + +--- + +**文档版本**: v1.0 +**最后更新**: 2026-07-06 +**状态**: 已确认，待执行 \ No newline at end of file diff --git a/run.md b/run.md new file mode 100644 index 0000000..c8fc794 --- /dev/null +++ b/run.md @@ -0,0 +1,587 @@ +# 财务 AI 助手运行手册（第一模块：薪财通 AI） + +**项目**: 财务 AI 助手（项目编号：S2F，第一模块：薪财通 AI） +**产品定位**: 面向金蝶中小企业客户的财务 AI 助手 +**当前运行模块**: 第一阶段薪酬财务对账 MVP +**范围说明**: 本运行手册对应第一模块 Excel 闭环；发票报销、预算执行、现金流异常、往来对账、经营分析属于后续模块 +**更新日期**: 2026-07-06 + +## 技术栈 + +### 前端 +- **框架**: Next.js 14+ (React 18+) +- **语言**: TypeScript 5+ +- **样式**: Tailwind CSS 3+ +- **UI 组件**: Shadcn/ui (基于 Radix UI) +- **状态管理**: React Context + Zustand +- **HTTP 客户端**: Axios +- **表单**: React Hook Form + Zod +- **图表**: Recharts +- **图标**: Lucide Icons +- **文件上传**: React Dropzone +- **Excel 处理**: SheetJS (xlsx) + +### 后端 +- **框架**: FastAPI 0.110+ +- **语言**: Python 3.11+ +- **验证**: Pydantic 2+ +- **ORM**: SQLAlchemy 2+ with asyncio +- **数据库驱动**: asyncpg (PostgreSQL) +- **认证**: JWT (python-jose) +- **密码**: bcrypt +- **文件处理**: openpyxl, pandas +- **AI**: OpenAI SDK / 国产大模型 SDK +- **任务队列**: Celery + Redis (第二阶段) +- **日志**: structlog + +### 数据库 +- **主库**: PostgreSQL 15+ +- **缓存**: Redis 7+ (第二阶段) + +### 部署 +- **容器**: Docker + Docker Compose +- **Web 服务器**: Nginx (反向代理) +- **进程管理**: Uvicorn (FastAPI ASGI) + +## 本地环境要求 + +### 必需 +- Node.js 20+ 和 npm 10+ +- Python 3.11+ +- PostgreSQL 15+ +- Docker 和 Docker Compose (推荐) + +### 可选 +- Redis 7+ (第二阶段) + +## 环境变量 + +### 前端 `.env.local` + +```bash +# API 地址 +NEXT_PUBLIC_API_URL=http://localhost:8000 + +# 应用配置 +NEXT_PUBLIC_APP_NAME="财务 AI 助手（薪财通 AI）" +NEXT_PUBLIC_APP_VERSION=1.0.0 +``` + +### 后端 `.env` + +```bash +# 应用配置 +APP_NAME="财务 AI 助手 API" +APP_VERSION=1.0.0 +DEBUG=true +SECRET_KEY=your-secret-key-change-in-production +ALLOWED_ORIGINS=http://localhost:3000 + +# 数据库 +DATABASE_URL=postgresql+asyncpg://s2f_user:s2f_password@localhost:5432/s2f_db + +# JWT +JWT_SECRET_KEY=your-jwt-secret-key-change-in-production +JWT_ALGORITHM=HS256 +JWT_ACCESS_TOKEN_EXPIRE_MINUTES=60 + +# AI 模型 +OPENAI_API_KEY=your-openai-api-key +OPENAI_MODEL=gpt-4-turbo-preview +# 默认使用智谱，也可切换 openai / qwen / baidu +AI_PROVIDER=zhipu +ZHIPU_API_KEY=your-zhipu-api-key +AI_API_KEY=your-ai-api-key + +# 文件存储 +UPLOAD_DIR=./uploads +MAX_UPLOAD_SIZE=10485760 # 10MB + +# 日志 +LOG_LEVEL=INFO +``` + +## 项目结构 + +``` +s2f/ +├── frontend/ # Next.js 前端 +│ ├── src/ +│ │ ├── app/ # App Router 页面 +│ │ ├── components/ # React 组件 +│ │ ├── lib/ # 工具函数、API 客户端 +│ │ ├── hooks/ # 自定义 Hooks +│ │ ├── types/ # TypeScript 类型 +│ │ └── styles/ # 全局样式 +│ ├── public/ # 静态资源 +│ ├── package.json +│ └── tsconfig.json +├── backend/ # FastAPI 后端 +│ ├── app/ +│ │ ├── api/ # API 路由 +│ │ ├── core/ # 核心配置 +│ │ ├── models/ # SQLAlchemy 模型 +│ │ ├── schemas/ # Pydantic 模式 +│ │ ├── services/ # 业务逻辑 +│ │ ├── utils/ # 工具函数 +│ │ └── main.py # 应用入口 +│ ├── migrations/ # Alembic 迁移 +│ ├── tests/ # 测试 +│ ├── requirements.txt +│ └── pyproject.toml +├── pmdocs/ # 项目管理文档 +│ ├── 0-req-S2F.md +│ ├── 1-prd-S2F.md +│ └── 2-task-S2F.md +├── docker-compose.yml # Docker Compose 配置 +├── .gitignore +├── README.md +└── run.md # 本文件 +``` + +## 安装与初始化 + +### 方式 1：使用 Docker Compose（推荐） + +```bash +# 克隆项目 +cd /Users/freedak/Documents/AIDashboard/s2f + +# 启动所有服务 +docker-compose up -d + +# 查看日志 +docker-compose logs -f + +# 前端: http://localhost:3000 +# 后端 API: http://localhost:8000 +# API 文档: http://localhost:8000/docs +``` + +### 方式 2：本地开发 + +#### 1. 数据库初始化 + +```bash +# 安装 PostgreSQL (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 +``` + +#### 2. 后端初始化 + +```bash +cd backend + +# 创建虚拟环境 +python3.11 -m venv venv +source venv/bin/activate # Windows: venv\Scripts\activate + +# 安装依赖 +pip install -r requirements.txt + +# 配置环境变量 +cp .env.example .env +# 编辑 .env 填入真实配置 + +# 数据库迁移 +alembic upgrade head + +# 创建初始管理员账号 +python scripts/create_admin.py +``` + +#### 3. 前端初始化 + +```bash +cd frontend + +# 安装依赖 +npm install + +# 配置环境变量 +cp .env.example .env.local +# 编辑 .env.local 填入 API 地址 +``` + +## 开发命令 + +### 前端开发 + +```bash +cd frontend + +# 启动开发服务器 (http://localhost:3000) +npm run dev + +# 类型检查 +npm run type-check + +# Lint 检查 +npm run lint + +# 代码格式化 +npm run format +``` + +### 后端开发 + +```bash +cd backend +source venv/bin/activate + +# 启动开发服务器 (http://localhost:8000) +uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 + +# 或使用 FastAPI CLI +fastapi dev app/main.py + +# 查看 API 文档 +# http://localhost:8000/docs (Swagger UI) +# http://localhost:8000/redoc (ReDoc) +``` + +## 构建命令 + +### 前端构建 + +```bash +cd frontend + +# 生产构建 +npm run build + +# 启动生产服务器 +npm run start +``` + +### 后端构建 + +```bash +cd backend + +# FastAPI 不需要构建，直接运行 +uvicorn app.main:app --host 0.0.0.0 --port 8000 +``` + +## 测试命令 + +### 前端测试 + +```bash +cd frontend + +# 运行所有测试 +npm run test + +# 监听模式 +npm run test:watch + +# 覆盖率报告 +npm run test:coverage +``` + +### 后端测试 + +```bash +cd backend +source venv/bin/activate + +# 运行所有测试 +pytest + +# 监听模式 +pytest-watch + +# 覆盖率报告 +pytest --cov=app --cov-report=html +``` + +### 端到端测试 + +```bash +cd frontend + +# 运行 E2E 测试 (Playwright) +npm run test:e2e + +# 打开 Playwright UI +npm run test:e2e:ui +``` + +## 数据库命令 + +### Alembic 迁移 + +```bash +cd backend +source venv/bin/activate + +# 创建迁移 +alembic revision --autogenerate -m "描述变更" + +# 执行迁移 +alembic upgrade head + +# 回滚迁移 +alembic downgrade -1 + +# 查看迁移历史 +alembic history + +# 查看当前版本 +alembic current +``` + +### 数据库管理 + +```bash +# 连接数据库 +psql -U s2f_user -d s2f_db + +# 备份数据库 +pg_dump -U s2f_user s2f_db > backup.sql + +# 恢复数据库 +psql -U s2f_user s2f_db < backup.sql + +# 重置数据库（危险！） +psql -U s2f_user +DROP DATABASE s2f_db; +CREATE DATABASE s2f_db; +\q +cd backend && alembic upgrade head +``` + +## 代码质量 + +### 前端 + +```bash +cd frontend + +# ESLint 检查 +npm run lint + +# 自动修复 +npm run lint:fix + +# Prettier 格式化 +npm run format + +# TypeScript 类型检查 +npm run type-check +``` + +### 后端 + +```bash +cd backend +source venv/bin/activate + +# Ruff Lint 检查 +ruff check app/ + +# 自动修复 +ruff check --fix app/ + +# Black 格式化 +black app/ + +# MyPy 类型检查 +mypy app/ +``` + +## Docker 命令 + +```bash +# 构建镜像 +docker-compose build + +# 启动服务 +docker-compose up -d + +# 停止服务 +docker-compose down + +# 查看日志 +docker-compose logs -f [service_name] + +# 进入容器 +docker-compose exec backend bash +docker-compose exec frontend sh + +# 重建并重启 +docker-compose up -d --build + +# 清理所有数据（危险！） +docker-compose down -v +``` + +## 常见问题 + +### 1. 前端无法连接后端 + +**问题**：前端显示网络错误 + +**解决**： +```bash +# 确认后端正在运行 +curl http://localhost:8000/api/health + +# 检查 CORS 配置 +# backend/app/core/config.py 中 ALLOWED_ORIGINS 需包含前端地址 +``` + +### 2. 数据库连接失败 + +**问题**：`sqlalchemy.exc.OperationalError: could not connect to server` + +**解决**： +```bash +# 确认 PostgreSQL 正在运行 +pg_isready -h localhost -p 5432 + +# 确认数据库存在 +psql -U s2f_user -l | grep s2f_db + +# 检查 DATABASE_URL 配置 +echo $DATABASE_URL +``` + +### 3. AI 字段识别失败 + +**问题**：上传文件后识别超时或失败 + +**解决**： +```bash +# 检查 AI API Key +echo $OPENAI_API_KEY + +# 测试 API 连接 +curl https://api.openai.com/v1/models \ + -H "Authorization: Bearer $OPENAI_API_KEY" + +# 查看后端日志 +docker-compose logs backend | grep -i "openai\|error" +``` + +### 4. 文件上传失败 + +**问题**：上传文件时显示 413 或 500 错误 + +**解决**： +```bash +# 检查文件大小限制 +# backend/.env 中 MAX_UPLOAD_SIZE=10485760 (10MB) + +# 确认上传目录权限 +ls -la backend/uploads/ +chmod 755 backend/uploads/ + +# 检查磁盘空间 +df -h +``` + +### 5. 前端构建失败 + +**问题**：`npm run build` 报错 + +**解决**： +```bash +# 清理缓存 +rm -rf frontend/.next frontend/node_modules +cd frontend && npm install + +# 检查 TypeScript 错误 +npm run type-check + +# 检查环境变量 +cat frontend/.env.local +``` + +## 部署检查清单 + +部署前确认： + +- [ ] 环境变量已配置（生产环境不使用默认密钥） +- [ ] 数据库迁移已执行 +- [ ] 前端已构建 (`npm run build`) +- [ ] HTTPS 已配置 +- [ ] CORS 已正确配置生产域名 +- [ ] 文件上传目录有正确权限 +- [ ] 日志目录可写 +- [ ] 备份策略已配置 +- [ ] 监控和告警已配置 + +## 性能优化建议 + +### 前端 +- 使用 Next.js 的 Image 组件优化图片 +- 启用 React Server Components 减少客户端 JS +- 使用动态导入按需加载组件 +- 配置合理的缓存策略 + +### 后端 +- 为频繁查询添加数据库索引 +- 使用连接池优化数据库连接 +- 对 AI 请求添加缓存（第二阶段） +- 启用 Gzip 压缩 + +### 数据库 +- 定期 VACUUM 和 ANALYZE +- 监控慢查询日志 +- 合理设置连接池大小 + +## 安全建议 + +- 生产环境必须更改所有默认密钥 +- 使用 HTTPS +- 启用 CSRF 保护 +- 限制文件上传类型和大小 +- 定期更新依赖 +- 启用日志审计 +- 配置防火墙规则 +- 数据库使用强密码并限制访问 + +## 监控与日志 + +### 日志位置 + +```bash +# 前端日志 +frontend/.next/ + +# 后端日志 +backend/logs/ + +# Docker 日志 +docker-compose logs +``` + +### 推荐监控指标 + +- API 响应时间 +- 数据库查询时间 +- AI 识别准确率 +- 文件上传成功率 +- 错误率和异常日志 +- 磁盘使用率 +- 内存使用率 + +## 更新记录 + +| 日期 | 版本 | 变更内容 | +|---|---|---| +| 2026-07-06 | v1.0 | 初始版本，MVP 技术栈和运行命令 | + +--- + +**下一步**: 参考 `pmdocs/2-task-S2F.md` 开始开发任务 \ No newline at end of file