171 lines
7.5 KiB
Markdown
171 lines
7.5 KiB
Markdown
|
# 飞书多维表格操作手册（内网）
|
|||
|
|
|
|||
|
|
> **主路径**：批次登记与入湖已改为 HSAP **批次台账 + 审核入湖**（[BATCH_DELIVERY_OPS.md](./BATCH_DELIVERY_OPS.md)）。飞书表仅作可选人工备忘；默认 `FEISHU_BITABLE_SYNC_ENABLED=0`，勿再依赖 API 拉表。
|
|||
|
|
|
|||
|
|
配套开发说明：[FEISHU_INTEGRATION_DEV.md](./FEISHU_INTEGRATION_DEV.md)
|
|||
|
|
交接模板：[FEISHU_DEV_HANDOFF.md](./FEISHU_DEV_HANDOFF.md)
|
|||
|
|
对象暂存（可选）：[MINIO_STAGING.md](./MINIO_STAGING.md)
|
|||
|
|
联调小样批次：[PILOT_BATCH.md](./PILOT_BATCH.md)
|
|||
|
|
|
|||
|
|
内网 **不要** 配置多维表格「自动化 → Webhook → HSAP URL」。由 HSAP 定时 **出站** 回写表格（`FEISHU_BITABLE_SYNC_ENABLED=1`）。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 建群
|
|||
|
|
|
|||
|
|
| 项 | 内容 |
|
|||
|
|
|----|------|
|
|||
|
|
| 群名 | **HSAP·数据标注协作** |
|
|||
|
|
| 成员 | 协调员、内部标注员、数据/运维 |
|
|||
|
|
| 群公告 | ① 多维表格链接 ② 新批次先建表行 ③ 批次名 ≠ 任务名 ④ 内标须飞书登录 HSAP 至少一次 ⑤ `HSAP：http://<内网地址>:8787（运维补充）` |
|
|||
|
|
|
|||
|
|
外协另建 **HSAP·外协回传**（不进主表）。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 建多维表格
|
|||
|
|
|
|||
|
|
1. 群内 → **多维表格** → 新建
|
|||
|
|
2. Base：**HSAP 数据批次台账**
|
|||
|
|
3. 表 1：**数据批次台账**（主表；采集明细表 Phase C 再做）
|
|||
|
|
|
|||
|
|
记下并填入 [FEISHU_DEV_HANDOFF.md](./FEISHU_DEV_HANDOFF.md)：
|
|||
|
|
|
|||
|
|
- **app_token**：URL `/base/` 后一串
|
|||
|
|
- **table_id**：URL 参数 `table=`（无则交开发用 API 查询）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. 主表列（中文列名，顺序建议）
|
|||
|
|
|
|||
|
|
### 只标 addw / ddaw / addw_face 时（推荐简化）
|
|||
|
|
|
|||
|
|
若台账**只登记单层 DMS 任务**（不做 dam 0516、前向 detect 等），**可以不建「子模式」列**，或在各视图里 **隐藏** 该列。匹配与落盘只靠：
|
|||
|
|
|
|||
|
|
**项目 + 任务 + 批次名**（路径为 `inbox/<任务>/<批次名>/`）。
|
|||
|
|
|
|||
|
|
任务单选里也可只保留 `ddaw` `addw` `addw_face`，减少误填。
|
|||
|
|
|
|||
|
|
### 人工填写
|
|||
|
|
|
|||
|
|
| 列名 | 类型 | 必填 | 说明 |
|
|||
|
|
|------|------|------|------|
|
|||
|
|
| 批次编号 | 自动编号 | 是 | 如 `001`；同步到 HSAP `external_id` |
|
|||
|
|
| 项目 | 单选 `dms` `lane` | 是 | 舱内一般用 `dms` |
|
|||
|
|
| 任务 | 单选 | 是 | 单层任务：`ddaw` `addw` `addw_face`；若表内也登 dam/forward 见下节 |
|
|||
|
|
| 子模式 | 单选 | **可选列** | **仅**任务为 `dam`、`forward` 时填写；单层任务**不填、可删列/隐藏** |
|
|||
|
|
| 批次名 | 文本 | 是 | **≠ 任务名**；勿用训练包名 `dms_v1`/`dms_v2`，用 `YYYYMMDD_场景` |
|
|||
|
|
| 来源类型 | 单选 | 建议 | 采集车 / 回流标注 / 外协 / 实验集 / 其他 |
|
|||
|
|
| 车型或场景 | 文本 | 否 | 溯源，如车型、工控机 |
|
|||
|
|
| 采集开始 / 采集结束 | 日期 | 否 | |
|
|||
|
|
| 数据路径 | 文本 | 落盘前建议填 | 内网 NAS 绝对路径；与附件二选一 |
|
|||
|
|
| 数据附件 | 附件 | 否 | 仅小样本 ZIP |
|
|||
|
|
| 预估张数 | 数字 | 否 | |
|
|||
|
|
| 备注 | 多行文本 | 否 | 可写训练包目标，如「合并进 dms_v2」 |
|
|||
|
|
| 负责人 | 人员 | 建议 | 「待我处理」视图用 |
|
|||
|
|
| 标注员 | 人员多选 | 标注前 | 内标；须已飞书登录 HSAP |
|
|||
|
|
| 外协方 | 文本 | 否 | 有值则走 ZIP 回传，不内标分包 |
|
|||
|
|
|
|||
|
|
### 何时才需要「子模式」列
|
|||
|
|
|
|||
|
|
| 任务 | 子模式 | inbox 示例 |
|
|||
|
|
|------|--------|------------|
|
|||
|
|
| `ddaw` `addw` `addw_face` | **不需要** | `inbox/addw/20250526_SE882/` |
|
|||
|
|
| `dam` | 填 `batch_0516` 等 | `inbox/dam/batch_0516/` |
|
|||
|
|
| `forward` | 填 `detect` / `classify` | `inbox/forward/detect/` |
|
|||
|
|
|
|||
|
|
不登 dam/forward 时：**删除或隐藏「子模式」列即可**，HSAP 同步不依赖该列。
|
|||
|
|
|
|||
|
|
### 状态（单选，9 项）
|
|||
|
|
|
|||
|
|
`草稿` `待落盘` `分析中` `待送标` `标注中` `待入库` `已入库` `落盘失败` `驳回/作废`
|
|||
|
|
|
|||
|
|
内网用法：`待落盘` = 通知协调员去 HSAP 落盘；`分析中` 由 HSAP 回写，勿手改。
|
|||
|
|
|
|||
|
|
### 系统回写（勿手改）
|
|||
|
|
|
|||
|
|
候选ID、活动ID、Inbox路径、HSAP进度、HSAP链接、失败原因、最后同步、记录ID
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. 填写规范
|
|||
|
|
|
|||
|
|
1. **一批次一行**；批次名 = `YYYYMMDD_场景`（如 `20250526_SE882`），**不要**用任务名或训练包名（`addw`、`dms_v2`）。
|
|||
|
|
2. **流程**：草稿 → 填齐（路径/来源/负责人）→ **待落盘** → HSAP 落盘/送标。
|
|||
|
|
3. **子模式**：单层任务（addw/ddaw/addw_face）**一律不填**；表里没有这一列也可以。
|
|||
|
|
4. **训练包**（`dms_v1`、`dms_v2`）写在 **备注**，不要写在批次名。
|
|||
|
|
5. **外协**：填外协方，标注员留空。
|
|||
|
|
|
|||
|
|
**示例（addw，无子模式列）**
|
|||
|
|
|
|||
|
|
| 项目 | 任务 | 批次名 | 来源类型 | 车型或场景 | 数据路径 | 状态 |
|
|||
|
|
|------|------|--------|----------|------------|----------|------|
|
|||
|
|
| dms | addw | 20250526_SE882 | 采集车 | SE882电动垂卡 | `/NAS/.../images` | 草稿→待落盘 |
|
|||
|
|
|
|||
|
|
路径对照见 [LABELING_SOP.md](./LABELING_SOP.md) §5.2 飞书批次台账。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. 视图
|
|||
|
|
|
|||
|
|
- **全部批次**（默认）
|
|||
|
|
- **待我处理**：负责人=我，状态∈草稿/待落盘/待送标
|
|||
|
|
- **标注中**：状态=标注中
|
|||
|
|
|
|||
|
|
日常视图建议 **隐藏**：子模式（若不用）、记录ID、候选ID、活动ID（系统列可在「全部批次」保留以便核对）。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. 开放平台
|
|||
|
|
|
|||
|
|
1. [open.feishu.cn](https://open.feishu.cn) → 现有 HSAP 应用 → 权限：**查看、评论、编辑和管理多维表格** → 发布
|
|||
|
|
2. 表格 **分享** → 添加协作者 → **企业应用** → **可管理**（独立 `/base/` 多维表格；wiki 内嵌见 §8）
|
|||
|
|
3. 将 app_token、table_id 写入 `manifests/feishu.env`（见 example）
|
|||
|
|
|
|||
|
|
验证：`bash HSAP/scripts/feishu_bitable_verify.sh`（需平台已启动且 env 已填）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. 自检清单
|
|||
|
|
|
|||
|
|
- [ ] 群 + 表 + 群公告链接
|
|||
|
|
- [ ] 列与 9 态状态齐全
|
|||
|
|
- [ ] 3 个视图
|
|||
|
|
- [ ] 应用权限 + 表格协作者
|
|||
|
|
- [ ] feishu.env 已配置 BITABLE_*
|
|||
|
|
- [ ] 试填 1 行草稿（dms / addw / 批次名 `20250526_test`，**无子模式**）
|
|||
|
|
- [ ] 2 名内标已飞书登录 HSAP
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8. 文档库里加不上「企业应用」怎么办
|
|||
|
|
|
|||
|
|
知识库（wiki）内嵌的多维表格 + **高级权限** 时，分享里往往**只能加人/群，搜不到企业应用**。开放平台发布版本**不能**代替这一步。
|
|||
|
|
|
|||
|
|
**推荐（联调/生产）：复制为独立多维表格**
|
|||
|
|
|
|||
|
|
1. 飞书左侧 **多维表格**（不要只在 wiki 里操作）→ **新建** 或 **从现有复制**。
|
|||
|
|
2. 命名如 `HSAP数据批次台账-API`，把列/视图按本表建好（或整库复制）。
|
|||
|
|
3. 打开后地址栏为 `.../base/Basc...?table=tbl...` → 写入 `feishu.env`：
|
|||
|
|
- `FEISHU_BITABLE_APP_TOKEN=Basc...`
|
|||
|
|
- `FEISHU_BITABLE_TABLE_ID=tbl...`
|
|||
|
|
- `FEISHU_BITABLE_WIKI_NODE_TOKEN=`（留空）
|
|||
|
|
4. **分享 → 添加协作者 → 企业应用「主动安全算法平台」→ 可管理**（独立 base 一般能搜到）。
|
|||
|
|
5. wiki 原表可保留给人看；HSAP 只同步 **-API** 这张表。群公告里可写两个链接。
|
|||
|
|
|
|||
|
|
**临时联调（不做飞书回写）**
|
|||
|
|
|
|||
|
|
- `FEISHU_BITABLE_SYNC_ENABLED=0`，台账手填；HSAP 仍用 inbox / 送标工作台。
|
|||
|
|
- 小样 `20260525_pilot` 可照常走标注管线。
|
|||
|
|
|
|||
|
|
**可选**
|
|||
|
|
|
|||
|
|
- 所有者 **关闭高级权限** 后再试分享里加应用（不保证 wiki 仍可见应用）。
|
|||
|
|
- 找飞书租户管理员确认是否允许「企业应用」担任多维表格协作者。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 9. 已有 inbox 补录
|
|||
|
|
|
|||
|
|
例 `inbox/ddaw/ddaw`：新建一行，任务=ddaw，批次名用新命名规则，备注写「磁盘目录 ddaw」，状态按实际选待送标/标注中；HSAP 同步后会填 Inbox路径。
|