# Ziin 协作用户验收清单 v1

适用对象：

- `learnops` 这类标准协作用户
- 实施同事、交付同事、CI 执行用户
- 需要确认仓库不是只能在 `root` 身份下工作的维护人员

目标：

- 验证标准协作用户可以完成基础工程门禁
- 验证仓库输出目录和测试临时目录不依赖手工修权限
- 验证交付文档与示例资源可直接使用

## 1. 登录与目录准备

验收人需要确认：

- 已使用标准协作账号登录服务器
- 协作账号可进入仓库目录
- 仓库目录下依赖已安装完成

推荐命令：

```bash
cd <ziin-repo>
pwd
whoami
node -v
npm -v
```

通过标准：

- 能进入仓库目录
- `node` 和 `npm` 可正常执行

## 2. 工程门禁验收

按顺序执行：

```bash
cd <ziin-repo>
npm run typecheck
npm test
npm run build
```

说明：

- 这三条命令现在都会先自动执行 `npm run workspace:prepare`
- 不需要手工创建 `.next`、`.tmp-tests`、`sdk/js/dist`、`public/sdk/js`
- 不需要手工创建 `tsconfig.tsbuildinfo`

通过标准：

- `npm run typecheck` 返回 `0`
- `npm test` 全部通过
- `npm run build` 成功完成 Next.js 构建

失败优先排查：

- 当前账号是否能进入仓库目录
- 是否缺失 `node_modules`
- 是否误删 `public/sdk/js`、`sdk/js/dist` 等输出目录
- 是否有本地环境变量把路径指到不存在的位置

## 3. 测试临时目录验收

当前测试默认会优先使用仓库内 `.tmp-tests`，也支持自定义目录。

可选验证：

```bash
cd <ziin-repo>
export ZIIN_TEST_TMP_ROOT=/tmp/ziin-tests
npm test
```

通过标准：

- 测试在自定义临时目录下仍可通过
- 不依赖写死的 `/root/ziin/.tmp-tests`

## 4. 示例资源验收

当前 Node / Media 示例默认读取：

```text
public/examples/fixtures/Audio.mp3
```

如果要换成自己的音频：

```bash
export ZIIN_AUDIO_FILE=/absolute/path/to/your/audio.mp3
```

通过标准：

- 示例默认资源在仓库中真实存在
- 不依赖服务器本机缓存目录或个人目录

## 5. 部署路径验收

当前运行时路径默认基于仓库根目录解析，不再要求仓库必须部署在 `/root/ziin`。

重点检查对象：

- `ecosystem.config.cjs`
- `scripts/regression-image-ocr.ts`
- `tests/helpers/test-db.ts`
- `tests/media-gateway.test.ts`

通过标准：

- 代码运行路径基于仓库目录而不是写死绝对路径
- 仍允许通过环境变量覆盖实际部署路径

## 6. 验收结论记录

建议记录以下结果：

- 验收账号
- 验收时间
- `typecheck / test / build` 是否通过
- 是否使用了自定义 `ZIIN_TEST_TMP_ROOT`
- 是否确认示例音频存在
- 是否发现新的绝对路径假设

建议输出格式：

```text
验收账号：learnops
typecheck：pass
test：pass
build：pass
示例资源：pass
路径假设：pass
备注：无
```

## 7. 当前边界

这份清单验证的是：

- 仓库是否具备标准协作执行能力
- 工程门禁是否仍然依赖 `root`
- 示例和交付材料是否带有明显机器绑定假设

这份清单不负责验证：

- 线上公网接口可用性
- 外部 OCR / ASR 供应商额度与网络状态
- 真实客户宿主系统接入效果