freedak/s2f
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: 初始化项目与后端基础工程

Browse Source
This commit is contained in:
freedakgmail
2026-07-06 22:03:22 +08:00
commit 6833106829
34 changed files with 8398 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cursorrules
+54
View File
@@ -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 的情况下结束
.gitignore
+49
View File
@@ -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*
.windsurfrules
+54
View File
@@ -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 的情况下结束
README.md
+79
View File
@@ -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. 测试、部署与文档
backend/.env.example
+22
View File
@@ -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
backend/app/__init__.py
View File
backend/app/api/__init__.py
View File
backend/app/core/__init__.py
View File
backend/app/core/config.py
+51
View File
@@ -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()
backend/app/core/logging.py
+17
View File
@@ -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,
)
backend/app/main.py
+31
View File
@@ -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,
}
backend/app/models/__init__.py
View File
backend/app/schemas/__init__.py
View File
backend/app/services/__init__.py
View File
backend/app/utils/__init__.py
View File
backend/pyproject.toml
+53
View File
@@ -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"
backend/requirements.txt
+21
View File
@@ -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
backend/tests/test_health.py
+12
View File
@@ -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"
cursor-rules/AGENTS.md
+134
View File
@@ -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>(<scope>): <subject>
<body>
```
- **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/函数/参数
- **不越权**：不修改未经授权的文件，不执行有副作用的命令
- **不遗漏**：修改代码后同步更新相关文档和测试
- **不简化**：不跳过错误处理、不删除边界检查、不忽略安全校验
- **用中文沟通**：所有回复和注释使用中文
cursor-rules/README.md
+88
View File
@@ -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 协作规范（如果存在）
cursor-rules/ai-coding-workflow.md
+241
View File
@@ -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 维评估、六步流程、文档追加、闭环机制
cursor-rules/architecture-and-design.md
+128
View File
@@ -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、越权访问等常见问题。
- 遵循最小权限原则。
cursor-rules/change-management.md
+114
View File
@@ -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：变更闭环
```
cursor-rules/new-project-checkpoint.md
+89
View File
@@ -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` 中。
cursor-rules/quick-reference.md
+106
View File
@@ -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 / 测试
- [ ] 无关脏变更未混入提交
cursor-rules/ui-components-standard.md
+71
View File
@@ -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 或状态管理隔离跨层状态
docker-compose.yml
+20
View File
@@ -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:
docs/财务AI_产品方向建议.md
+1261
View File
File diff suppressed because it is too large Load Diff
docs/财务痛点汇总.md
+397
View File
@@ -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 助手的第一模块，专注薪酬对账、人工成本分析与金蝶凭证生成。
frontend/.gitkeep
View File
pmdocs/0-req-S2F.md
+547
View File
@@ -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、任务文档与运行手册已生成，可进入开发执行阶段。
pmdocs/1-prd-S2F.md
+1022
View File
File diff suppressed because it is too large Load Diff
pmdocs/2-task-S2F.md
+3150
View File
File diff suppressed because it is too large Load Diff
run.md
+587
View File
@@ -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` 开始开发任务