# FF AI Workspace

企业级智能工作空间平台，基于 Next.js + NestJS + Prisma + Temporal.io，全栈 TypeScript。

核心能力：动态表单引擎、审批工作流引擎（Temporal.io）、RBAC + PBAC 权限控制、多 Schema 数据库架构。

---

## 快速开始

### 1. 克隆项目

```bash
git clone ssh://git@43.130.59.228:2222/FFAIWorkspace/workspace.git
cd workspace
```

### 2. 让 AI 初始化环境

打开 Claude Code，输入：

> 帮我把项目跑起来

AI 会自动完成系统依赖检测、依赖安装、环境变量生成、Docker 启动、数据库初始化、前后端启动，最后跑验收门禁确认全部通过。

### 3. 开始开发

> 我要开发 xxx 功能

AI 会自动创建分支和隔离环境。

### 遇到问题？

直接告诉 AI 你遇到了什么问题。如果是 skill 本身的缺陷导致反复失败，请反馈给团队更新 skill。

---

## 开发环境说明

本项目所有开发均在**远程开发机**上进行，开发者通过 SSH 连接远端服务器后在服务器上编码、运行服务。

因此，服务启动后的 `localhost:3000`（前端）/ `localhost:3001`（后端）指向的是远程开发机的端口，**本地浏览器无法直接访问**。

### 访问方式

通过 SSH 端口转发将远端端口映射到本地：

```bash
# 一次性转发前端 + 后端端口（替换为你的用户名和开发机 IP）
ssh -N -L 3000:localhost:3000 -L 3001:localhost:3001 <user>@<dev-server-ip>
```

转发后，本地浏览器访问 `http://localhost:3000` 即可打开前端页面。

> 如果使用 VS Code Remote-SSH 开发，VS Code 会自动转发已监听的端口，通常无需手动操作。

### SAP 隧道

SAP 服务位于公司内网，通过内网跳板机的 SSH 反向隧道访问。详见 [SAP 内网隧道文档](docs/ops/06-sap-tunnel.md)。

---

## 文档导航

| 文档 | 说明 |
|------|------|
| [文档中心](docs/README.md) | 所有文档的导航中心（含新人阅读路径） |
| [系统架构](docs/standards/01-system-architecture.md) | 技术栈与整体架构 |
| [开发工作流](docs/standards/05-development-workflow.md) | 分支规范、测试策略、协作流程 |
| [模块文档索引](docs/modules/README.md) | 各业务模块的 PRD、API、数据模型等 |
| [运维部署](docs/ops/01-deploy-quick.md) | 生产环境部署 |

---

## Skills 速查

项目使用 AI 协作开发，以下技能可通过 `@skill-name` 触发。完整说明见 [Skills 文档](.agents/skills/README.md)。

| Skill | 用途 |
|-------|------|
| **setup-project** | 首次项目初始化：环境变量、依赖、Docker、数据库全流程 |
| **start-feature** | 启动功能开发：分支创建、worktree 隔离、环境配置 |
| **backend-main** | 后端功能开发：API、业务逻辑、认证授权 |
| **frontend-main** | 前端页面/组件开发、原型 Demo |
| **database-main** | Prisma schema 变更与迁移 |
| **docs-main** | 模块文档创建/补齐/一致性检查 |
| **plan-review** | 实施前方案审查 |
| **code-review** | PR 代码评审 |
| **test-main** | 三层测试总调度（L0-L3） |
| **test-backend** | 后端集成测试 |
| **test-frontend** | 前端 E2E 测试（Playwright MCP） |
| **git-main** | 分支、提交、合并、推送 |
| **pre-merge-build-fix** | 合并前构建检查与自动修复 |
| **retro** | 工程复盘 |
| **skill-creator** | 创建/修改 skill |
| **skill-audit** | 审计/评估 skill |
| **deploy-ops** | 生产/UAT 部署、更新、回滚 |
| **db-backup** | 数据库备份与恢复 |
| **troubleshoot** | 故障分层诊断与修复 |
| **temporal-ops** | Temporal 工作流清理与重置 |
| **infra-check** | 全栈健康检查与日志定位 |
| **self-improving-agent** | 经验沉淀与持续改进 |

---

## 开发模式：AI-first

本项目的核心方法论：**默认一切由 AI 完成，人工介入需要理由。**

不是"哪些工作可以让 AI 帮忙"，而是"哪些工作还不能交给 AI，为什么，怎么改进"。

### 核心原则

1. **AI 默认，人工例外** — 每项工作先问"AI 能不能做"，而不是"需不需要 AI 帮忙"。如果 AI 做不了，思考如何改进流程、文档或工具让它能做
2. **规格驱动实现** — 文档是唯一事实源，AI 依据规格生成代码。无文档不实现，需求变更先更新文档再改代码
3. **人类聚焦不可替代的事** — 定义业务目标、编写规格、做判断性决策、验收最终结果
4. **持续复盘人机分工** — 定期回顾：哪些工作是人做的、哪些是 AI 做的？人做的部分能否通过改进 skills、文档或工具转交给 AI？

### 实践方式

- 通过 **Skills 体系**调度 AI 完成编码、测试、文档、Git 全流程
- 通过**三层测试体系**（契约校验 → 集成测试 → E2E）保障质量，不依赖人工逐行检查
- 通过**经验沉淀**（self-improving-agent）让 AI 从错误中学习，减少重复问题

详见 [开发工作流](docs/standards/05-development-workflow.md)

---

**维护团队**: FF AI Workspace 开发团队