# 内部小工具自助部署平台（internal-app-platform）

> **负责人**: lijian.dai
> **状态**: 🚧 契约设计中
> **最后更新**: 2026-05-13
> **关联工单**: [Issue #332](http://43.130.59.228/FFAIWorkspace/workspace/issues/332)

---

## 模块概述

让非技术员工（运营 / HR / 财务 等）**全程只做两件事**：

1. 在 Claude Code 里对话写业务代码
2. 对 Claude Code 说"部署一下" → 拿到内网可访问的 URL

中间所有事情——建仓、push、容器化、反代、域名、TLS、备份——员工完全不感知。

承担"AI 生成代码 → 真实可用工具"的最后一公里。

## 文档导航

| 文档 | 用途 | 何时读取 | 状态 |
|------|------|---------|------|
| [01-prd](./01-prd.md) | 功能边界、权限矩阵、边界规则、V2 路线图 | 任何任务前先读 | 🚧 Draft |
| [03-architecture](./03-architecture.md) | 技术分层（OA API / MCP / 引擎层）、关键流程图、Phase 0/1 实施阶段 | 实现前确认架构 | 🚧 Draft |
| [05-ui-interaction-spec](./05-ui-interaction-spec.md) | FFOA "我的 Apps" 接入页结构、关键交互、文案 i18n、可见态边界 | 前端实现接入页时 | 🚧 Draft |
| [06-data-model](./06-data-model.md) | InternalApp / Deployment / EnvVar / EmployeeToken / EmployeeSlugBinding 表结构 | 涉及 schema 变更时 | 🚧 Draft |
| [07-api](./07-api.md) | OA HTTP API + 远程 MCP 工具签名 + token 颁发端点 | API 实现时 | 🚧 Draft |
| [08-phase-0-poc-runbook](./08-phase-0-poc-runbook.md) | Phase 0 真员工 PoC 操作手册（IT 准备 / 员工操作 / 故障排查 / demo 剧本） | 跑 PoC、接新员工、给领导演示 | ✅ |
| [09-test-scenarios](./09-test-scenarios.md) | 集成测试场景（含 PoC 端到端验收剧本） | 编写测试时 | 🚧 Draft |
| [10-entra-middleware-design](./10-entra-middleware-design.md) | Phase 1 已落地的 JWT+binding 路径 + Phase 2 Entra middleware 升级设计 | 接 Entra middleware 或调 req.user 形状时 | ✅ |
| [11-dns-tls-rollout](./11-dns-tls-rollout.md) | DNS *.apps.ffworkspace.faradayfuture.com + LE 通配证书上线 runbook（工单模板 + 5min 切换动作 + 回滚） | 跑 DNS / TLS 上线时 | ✅ |
| [12-nginx-caddy-coexist](./12-nginx-caddy-coexist.md) | Phase 1 共机拓扑下 nginx 前置 + Caddy 走 127.0.0.1:8080 的 ADR / setup-test-server.sh 改造点 / nginx 模板 / cert 策略 / 回滚 | 跑 PoC infra 装载 / 改 setup 脚本 / 给 cert 找位置 | ✅ |
| [13-usage-guide](./13-usage-guide.md) | 员工日常使用 + IT-Ops 运维手册（onboarding、admin API、巡检、故障定位、监控、回滚） | 新员工接入 / 日常运维 / 处理用户报障 | ✅ |

> 当前状态：14-feature-request-workflow `Status/契约设计中`。01-prd / 03-architecture / 05-ui-interaction-spec / 06-data-model / 07-api / 09-test-scenarios 全部已起草，可进入审批阶段，审批通过后切到 `Status/实现中`。
>
> 注：MVP 阶段**不规划独立 `10-e2e-test-spec.md`**——E2E 验收嵌入 `09-test-scenarios.md` 的 PoC 剧本。05-ui-interaction-spec 仅覆盖唯一前端页"我的 Apps"（onboarding + 自助查看），日常部署 / 日志 / env / 销毁仍走 Claude Code 对话。

## 代码与数据位置（规划）

- **后端（OA API）**: `backend/src/modules/internal-app-platform/`
- **远程 MCP 端点**: `backend/src/modules/internal-app-platform/mcp/`（同进程暴露 Streamable HTTP，员工电脑不分发包）
- **FFOA 接入页**: `frontend/src/app/internal-apps/`（token 生成 / 撤销 / 复制 `claude mcp add` 命令）
- **数据库**: `platform_internal_apps.prisma`（待 状态 3 设计，含 InternalApp / Deployment / EnvVar / EmployeeToken）
- **app 运行时**: 服务器上 Docker 容器，数据卷挂载到 `/srv/internal-apps/<appId>/data/`
- **app 仓库**: Gitea organization `FFAIApps`，命名格式 `FFAIApps/<employeeSlug>-<app slug>`
- **备份**: Litestream → 对象存储桶（桶名待运维定）