# 小正方助手 · 表单题目数据结构（`subjectArray`）

`subjectArray` 位于表单根对象中，是题目列表，每个元素为一道题目：

```json
{
  "name": "表单名称",
  "subjectArray": []
}
```

---

## 1. 题目通用字段

每道题目包含下列 6 个通用字段，另有 5 个可选字段。

```json
{
  "_id": "A001",
  "name": "题目名称",
  "description": "",
  "required": true,
  "type": "radio",
  "typeName": "单选"
}
```

| 字段            | 类型             | 必填 | 说明                                                    |
| ------------- | -------------- | -- | ----------------------------------------------------- |
| `_id`         | string         | 是  | 题目唯一标识，4 位，仅 `A-Za-z0-9`，同一表单内不重复，如 `A001`、`R01`、`C01` |
| `name`        | string         | 是  | 题目标题，即填答者看到的文字                                        |
| `description` | string         | 是  | 题目说明，无内容时为 `""`                                       |
| `required`    | bool           | 是  | 是否必答，取值 `true` / `false`                              |
| `type`        | string         | 是  | 题型，取值见第 2 节                                           |
| `typeName`    | string         | 是  | 题型名称，与 `type` 一一对应                                    |
| `logic`       | object         | 否  | 显示逻辑，结构见 5.1                                          |
| `placeholder` | string         | 否  | 输入类题目的灰字提示                                            |
| `scoreValue`  | number         | 否  | 分值，见 5.2                                             |
| `correct`     | string / array | 否  | 正确答案，见 5.2                                            |
| `analysis`    | string         | 否  | 答案解析                                                 |

---

## 2. 题型枚举

共 20 种，`type` 与 `typeName` 一一对应：

| type             | typeName |
| ---------------- | -------- |
| `radio`          | 单选       |
| `checkbox`       | 多选       |
| `select`         | 下拉       |
| `singleLineText` | 单行文本     |
| `multiLineText`  | 多行文本     |
| `region`         | 省市区      |
| `date`           | 日期       |
| `time`           | 时间       |
| `datetime`       | 日期时间     |
| `grade`          | 打分       |
| `mapLocation`    | 地图选点     |
| `distance`       | 距离打卡     |
| `multiSelect`    | 多级联动     |
| `scanCode`       | 扫码       |
| `licensePlate`   | 车牌号      |
| `reorder`        | 排序       |
| `fujian`         | 文件上传     |
| `sign`           | 手写签名     |
| `maxdiff`        | MaxDiff  |
| `desc`           | 文本描述     |

---

## 3. 选项结构 `optionArray`

带选项的题型共 6 种：`radio`、`checkbox`、`select`、`reorder`、`multiSelect`、`maxdiff`。
这些题型的数据中包含 `optionArray`；其余 14 种题型不含该字段。

### 3.1 平铺型（`radio` / `checkbox` / `select` / `reorder` / `maxdiff`）

元素只含 `name`：

```json
"optionArray": [
  { "name": "非常满意" },
  { "name": "满意" },
  { "name": "一般" },
  { "name": "不满意" }
]
```

### 3.2 树形（`multiSelect`）

`multiSelect` 的 `optionArray` 为多级树结构，节点为 `{name, text, value, children}`：
`text` 与 `value` 均等于 `name`，叶子节点 `children` 为空数组。

```json
"optionArray": [
  {
    "name": "家电", "text": "家电", "value": "家电",
    "children": [
      { "name": "冰箱", "text": "冰箱", "value": "冰箱", "children": [] },
      { "name": "洗衣机", "text": "洗衣机", "value": "洗衣机", "children": [] }
    ]
  },
  {
    "name": "数码", "text": "数码", "value": "数码",
    "children": [
      { "name": "手机", "text": "手机", "value": "手机", "children": [] },
      { "name": "电脑", "text": "电脑", "value": "电脑", "children": [] }
    ]
  }
]
```

层级连续，不出现从一级直接跳到三级的情况。

### 3.3 常见选项数量

| 题型            | 数量范围        |
| ------------- | ----------- |
| `radio`       | 2 ~ 7       |
| `checkbox`    | 2 ~ 10      |
| `select`      | 2 ~ 20      |
| `reorder`     | 3 ~ 10      |
| `maxdiff`     | 3 ~ 10      |
| `multiSelect` | 3 ~ 20（按层级） |

---

## 4. 各题型字段明细

以下仅列各题型的专属字段，通用字段见第 1 节。

### 4.1 `radio` 单选

| 字段                                    | 类型     | 说明                        |
| ------------------------------------- | ------ | ------------------------- |
| `optionArray`                         | array  | 选项，平铺结构                   |
| `other`                               | bool   | 是否带「其他」项，默认 `false`       |
| `otherOptionTips`                     | string | 「其他」项的显示文案，默认 `"其他"`      |
| `scoreValue` / `correct` / `analysis` | —      | 计分相关字段，见 5.2             |

```json
{ "_id": "A001", "name": "您的性别是？", "description": "", "required": true,
  "type": "radio", "typeName": "单选",
  "optionArray": [{ "name": "男" }, { "name": "女" }, { "name": "不方便透露" }] }
```

### 4.2 `checkbox` 多选

| 字段                          | 类型             | 说明                        |
| --------------------------- | -------------- | ------------------------- |
| `optionArray`               | array          | 选项，平铺结构                   |
| `maxChecked`                | number         | 最多可选数量，缺省表示不限             |
| `minChecked`                | number         | 最少可选数量，缺省表示不限             |
| `other` / `otherOptionTips` | bool / string  | 是否带「其他」项及其文案，默认 `false`   |
| `correct`                   | array          | 正确答案为数组形式                 |

`other` 为 `true` 时与 `maxChecked` / `minChecked` 互斥。

### 4.3 `select` 下拉

| 字段            | 类型     | 说明                             |
| ------------- | ------ | ------------------------------ |
| `optionArray` | array  | 选项，平铺结构                        |
| `oldStyle`    | bool   | `true` 使用原生下拉框，默认 `false`       |
| `multiple`    | bool   | 是否多选，默认 `false`；`oldStyle` 为 `true` 时无效 |

### 4.4 `singleLineText` 单行文本

| 字段                                    | 类型     | 说明                                                    |
| ------------------------------------- | ------ | ----------------------------------------------------- |
| `textStyle`                           | object | 文本格式校验，结构 `{text, value}`，取值见 5.3                       |
| `smsVerify`                           | bool   | 是否短信验证，默认 `false`；仅在 `textStyle.value` 为 `phone` 时生效  |
| `qlCantInput`                         | bool   | 短信余量不足时是否禁止输入，默认 `false`                              |
| `placeholder`                         | string | 灰字提示                                                  |
| `scoreValue` / `correct` / `analysis` | —      | 计分相关字段，见 5.2                                          |

### 4.5 `multiLineText` 多行文本

| 字段                    | 类型     | 说明                        |
| --------------------- | ------ | ------------------------- |
| `height`              | number | 输入框高度，常见取值 100            |
| `placeholder`         | string | 灰字提示                      |
| `autoGetLocation`     | bool   | 是否自动获取定位，地址类题目使用          |
| `autoGetInvoiceTitle` | bool   | 是否自动获取发票抬头，发票类题目使用        |

### 4.6 `region` 省市区

| 字段      | 类型     | 说明                                     |
| ------- | ------ | -------------------------------------- |
| `level` | object | 层级限制，结构 `{text, value}`；省略该字段即区级        |

`level` 的可选值：省级 `province`、市级 `city`、街道级 `sub-district`。

### 4.7 `date` 日期

| 字段                      | 类型     | 说明                                              |
| ----------------------- | ------ | ----------------------------------------------- |
| `dateStyle`             | object | 粒度，结构 `{text, value}`：`day` 年月日、`month` 年月、`year` 年；省略即年月日 |
| `calendar`              | bool   | 是否日历模式，默认 `false`                                |
| `lunar`                 | bool   | 是否显示农历，仅在 `calendar` 为 `true` 且粒度为 `day` 时有效   |
| `startDate` / `endDate` | string | 可选范围，格式 `YYYY-MM-DD`，粒度随 `dateStyle`；空字符串表示不限   |

### 4.8 `time` 时间

| 字段                      | 类型     | 说明                          |
| ----------------------- | ------ | --------------------------- |
| `startTime` / `endTime` | string | 可选范围，格式 `HH:mm`；空字符串表示不限    |
| `placeholder`           | string | 灰字提示                        |

### 4.9 `datetime` 日期时间

仅通用字段，另可含 `placeholder`。

### 4.10 `grade` 打分 / NPS

| 字段                       | 类型     | 说明                                                        |
| ------------------------ | ------ | --------------------------------------------------------- |
| `quantity`               | number | 总分值，取值 3 ~ 10                                             |
| `shape`                  | object | 样式，结构 `{text, value}`，取值见 5.4                             |
| `leftText` / `rightText` | string | 两端文案                                                      |

两种常见配置：普通评分 `quantity` 为 `5`、`shape` 为星星；NPS 为 `quantity` 10、`shape` 为 `square`，两端文案为语义短语。

```json
{ "_id": "A003", "name": "您有多大可能推荐我们给朋友或同事？",
  "description": "0 表示绝无可能，10 表示极有可能", "required": true,
  "type": "grade", "typeName": "打分",
  "quantity": 10, "shape": { "text": "数字框(NPS)", "value": "square" },
  "leftText": "绝不可能", "rightText": "极有可能" }
```

### 4.11 `mapLocation` 地图选点

仅通用字段，另可含 `placeholder`。

### 4.12 `distance` 距离打卡

| 字段              | 类型     | 说明                                       |
| --------------- | ------ | ---------------------------------------- |
| `location`      | object | 打卡地点，结构 `{name, address, longitude, latitude}` |
| `location.name` | string | 地点名称                                     |
| `range`         | number | 允许打卡半径，单位米；空值表示不限                        |

坐标未知时经纬度记为 `0`。

### 4.13 `multiSelect` 多级联动

数据来源二选一：`optionArray`（树形，见 3.2）或 `optionKeyword`（内置词库，见 5.5），两者互斥。

### 4.14 `scanCode` 扫码

| 字段           | 类型     | 说明                |
| ------------ | ------ | ----------------- |
| `cameraOnly` | bool   | 是否仅限相机扫码，默认 `false` |
| `continuous` | bool   | 是否连续扫码，默认 `false`   |
| `placeholder` | string | 灰字提示              |

### 4.15 `licensePlate` 车牌号

仅通用字段，另可含 `placeholder`。

### 4.16 `reorder` 排序

`optionArray`（平铺结构，3 项以上）。无其他专属字段。

### 4.17 `fujian` 文件上传

| 字段            | 类型     | 说明                                          |
| ------------- | ------ | ------------------------------------------- |
| `imageOnly`   | bool   | 是否仅限图片：图片类 `true`，文件类 `false`                |
| `cameraOnly`  | bool   | 是否仅限拍摄，默认 `false`；仅在 `imageOnly` 为 `true` 且未开启 `wxAvatar` 时适用 |
| `wxAvatar`    | bool   | 是否为微信头像模式，默认 `false`                         |
| `extension`   | array  | 允许的文件格式，仅在 `imageOnly` 为 `false` 时使用         |
| `placeholder` | string | 灰字提示                                        |

`extension` 可取的值：

```text
"jpg", "jpeg", "png", "doc", "docx", "xls", "xlsx", "ppt", "pptx",
"pdf", "zip", "rar", "wps", "et", "dps"
```

平台限制：图片题最多 1 张；文件题单个不超过 20M、每题最多 1 个。需要多份时拆成多道题目。

### 4.18 `sign` 手写签名

仅通用字段，另可含 `placeholder`。

### 4.19 `maxdiff` MaxDiff

| 字段             | 类型     | 说明                                   |
| -------------- | ------ | ------------------------------------ |
| `optionArray`  | array  | 属性列表，平铺结构，3 ~ 10 项                   |
| `best`         | string | 「最好」端文案，默认 `"最重要"`                   |
| `worst`        | string | 「最差」端文案，默认 `"最不重要"`                  |
| `itemsPerTask` | number | 每个任务展示的属性数，取值 3 / 4 / 5，默认 `4`       |
| `taskCount`    | number | 任务数，由属性总数与 `itemsPerTask` 计算得出，数据中不写入    |

### 4.20 `desc` 文本描述

| 字段                          | 类型     | 说明                          |
| --------------------------- | ------ | --------------------------- |
| `name`                      | string | 说明正文                        |
| `required`                  | bool   | 固定 `false`，不采集数据             |
| `ignoreSubNo`               | bool   | 是否忽略题目序号，默认 `true`           |
| `borderTop` / `borderBottom` | bool   | 是否显示上 / 下分割线                |

`desc` 不采集数据，用于填写说明、温馨提示、协议、分组标题等场景。

---

## 5. 进阶字段

### 5.1 显示逻辑 `logic`

```json
"logic": {
  "thatsIndex": 3,
  "meet": "all",
  "conditions": [
    {
      "_id": "A001",
      "name": "您的性别是？",
      "index": 1,
      "originIndex": 0,
      "valueType": "sin",
      "comparison": "eq",
      "comparisonText": "等于",
      "value": "男"
    }
  ]
}
```

| 字段                            | 说明                        |
| ----------------------------- | ------------------------- |
| `thatsIndex`                  | 本题在 `subjectArray` 中的下标     |
| `meet`                        | `all` 全部条件满足 / `any` 任一条件满足 |
| `conditions[]._id` / `name`   | 被引用题目的 `_id` 与名称          |
| `conditions[].index`          | 被引用题目在候选项中的序号             |
| `conditions[].originIndex`    | 被引用题目在 `subjectArray` 中的下标 |
| `valueType`                   | `sin` 单值 / `mul` 多值 / `str` 文本 |
| `comparison` + `comparisonText` | 比较符，取值见下表                |
| `value`                       | 比较值；`mul` 时为数组，其余为字符串     |

比较符：

| comparisonText | comparison |
| -------------- | ---------- |
| 等于             | `eq`       |
| 不等于            | `neq`      |
| 包含             | `in`       |
| 不包含            | `nin`      |
| 为空             | `emp`      |
| 不为空            | `nemp`     |
| 大于             | `gt`       |
| 大于或等于          | `gte`      |
| 小于             | `lt`       |
| 小于或等于          | `lte`      |

结构约束：

- 首题的 `logic` 恒为空，该字段只出现在后续题目上。
- 单题的条件数量上限为 3。
- 作为条件来源的题型限 `radio`、`checkbox`、`select`、`singleLineText`、`grade`。
- `conditions[]._id` 指向表单内已存在的题目。
- `comparison` 为 `emp` / `nemp` 时，`value` 为空字符串。
- `valueType` 与来源题型对应：`radio`、非多选 `select`、`grade` 为 `sin`；`checkbox`、多选 `select` 为 `mul`；其余为 `str`。

### 5.2 自动计分

题目级用到三个字段：`scoreValue`（分值）、`correct`（正确答案）、`analysis`（解析）。
`scoreValue` 与 `correct` 均非空时该题参与计分，多选题需完全匹配才得分。
`checkbox` 的 `correct` 为数组，其余题型为字符串。

表单级 `score` 由题目派生：

| 字段           | 含义                          |
| ------------ | --------------------------- |
| `totalCount` | 参与计分的题目数量                   |
| `totalValue` | 这些题目的 `scoreValue` 之和       |
| `showGrade`  | 是否向填答者展示得分                  |

无计分题时：

```json
"score": { "showGrade": false, "totalCount": 0, "totalValue": 0 }
```

### 5.3 `textStyle`（`singleLineText` 文本格式）

结构为 `{text, value}`：

| text   | value      | 含义               |
| ------ | ---------- | ---------------- |
| 无限制    | `""`       | 不校验，此时整个 `textStyle` 省略 |
| 整数     | `number`   | 整数               |
| 小数     | `digit`    | 小数               |
| 邮箱     | `email`    | 邮箱地址             |
| 中文     | `chinese`  | 纯中文              |
| 英文     | `english`  | 纯英文              |
| 网址     | `web`      | URL              |
| 身份证号   | `idcard`   | 身份证号             |
| 手机号    | `phone`    | 中国大陆手机号          |
| 微信昵称   | `nickname` | 微信昵称             |

### 5.4 `grade.shape` 样式枚举

| text      | value    |
| --------- | -------- |
| 星星        | `star`   |
| 数字框(NPS)  | `square` |
| 爱心        | `heart`  |
| 点赞        | `good`   |
| 笑脸        | `smile`  |
| 哭脸        | `cry`    |

### 5.5 `optionKeyword` 内置多级联动词库

`multiSelect` 可直接引用内置词库，此时不使用 `optionArray`：

| optionKeyword | 含义   |
| ------------- | ---- |
| `area`        | 国家地区 |
| `nationality` | 民族   |
| `university`  | 高校   |
| `major`       | 专业   |
| `industry`    | 行业   |

---