# Web 端部署与持久化（app/server/data）

## 存储口径

| 形态 | 数据位置 | 说明 |
|------|----------|------|
| 桌面端 | `%USERPROFILE%\.aps`（Linux/macOS `~/.aps`） | 不变，仍读写本机文件 |
| Web 端 | 容器内 `/app/server/data`（PVC 持久卷） | 项目/会话/消息（SQLite `master.db`）、世界状态、知识库、导出等全部落此目录 |

路径解析优先级：`APS_HOME` >（desktop→`~/.aps`；web→`APS_DATA_DIR` 或仓库 `server/data`）。
镜像已内置 `APS_MODE=web`、`APS_DATA_DIR=/app/server/data`（见 Dockerfile）。

## 常见故障：创建项目失败（写入 500）

**根因**：K8s 挂载的 PVC 目录默认属 `root:root`，而容器以非 root 用户 `aps`（uid/gid **10001**）运行，数据目录不可写，所有写入（创建项目、排产、导入）都会失败。

**修复**：Deployment 必须配置 `securityContext`（完整清单见 `packaging/k8s/deployment.yaml`）：

```yaml
spec:
  template:
    spec:
      securityContext:
        runAsUser: 10001
        runAsGroup: 10001
        fsGroup: 10001
        fsGroupChangePolicy: OnRootMismatch
```

**自查**：`GET /api/health` 返回 `storage` 字段（`dataDir` / `writable` / `remedy`）；
`writable=false` 时服务启动日志会输出 `[APS][FATAL] 数据目录不可写 …`。

## Web 端演示数据

镜像内置 `APS_WEB_DEMO_SEED=1`：某租户首次打开工作区且没有任何项目时，
自动播种一套完整演示项目「演示项目 · 智能控制器装配排产」：

- 固定产线层：2 车间 / 3 产线 / 13 工位 / 5 工序，3 款产品 BOM + 工艺路线 + 换型矩阵
- 柔性能力池：4 类共线产品、7 个能力池、可调配压接机与模具
- 业务单据：7 张销售订单（含 VIP 急单）、10 张柔性订单、3 张预测订单、30 天班次日历
- 一段引导式演示对话 + 2 条示例文件记录

特性：

- **按租户隔离**：世界数据在 `server/data/tenants/<租户>/projects/<项目>/world.json`
- **幂等**：播种后落 `demo-seeded.ok` 标记；用户删光演示项目也不会回填
- **可关闭**：环境变量 `APS_WEB_DEMO_SEED=0`；桌面端与测试默认不播种

手动补播（如线上已有租户想要演示数据）：

```bash
# 容器内执行
python scripts/seed_web_demo.py --tenant <JMS租户uuid> --user-id 1001
# 已有项目时强制再播一套
python scripts/seed_web_demo.py --tenant <JMS租户uuid> --force
```

## 项目文件上传

侧栏「文件」区支持两种记录：

- **上传**：`POST /api/projects/{id}/files/upload`（multipart，多文件；单文件 ≤50MB、单次 ≤20 个）。
  字节持久化在数据目录 `tenants/<租户>/projects/<项目>/uploads/`（platform 租户为
  `projects/<项目>/uploads/`），随 PVC / 本机 `~/.aps` 持久化；同时登记项目文件记录。
- **登记**：仅元数据记录（无字节），下载返回 404。

已上传文件在侧栏可点击下载（`GET /api/project-files/{fileId}/download`）；
删除文件记录会联动清理磁盘字节。viewer 角色上传返回 403。