应用前置规划（plan-application）¶

目标：在**从零新建**业务软件时，先产出一份可执行的 PLAN.md，再按清单调用各 generate-* 技能落盘。本技能**只写规划，不生成业务 XML**。

规划写法（强制）¶

只描述业务逻辑：值怎么算、选项从哪来、字段如何联动、何时隐藏/只读、操作前后做什么、视图查什么数据。用自然语言写清业务意图与规则。
**禁止**在 PLAN.md 中写具体 iScript / JavaScript / SQL / 伪代码实现；实施落盘时再由对应 generate-* + iscript-usage 补脚本。
规划表中的「逻辑 / 条件」列：写**业务规则**（例：「部门变更后清空并重算岗位选项」），不写代码。

产出物¶

部分	落盘	形态
应用规划 + 实施清单	`{软件名}.application/PLAN.md`	Markdown

storage/workspace/{软件名}.application/PLAN.md

约定：先创建 {软件名}.application/ 目录（可为空，尚无 .application XML），再写入 PLAN.md，避免路径悬空。PLAN.md 不进平台索引、不被 Runtime 监视。

何时触发（强建议门禁）¶

在以下情况**必须先走本技能**，在用户确认 PLAN.md 之前**禁止**批量调用 generate-* 写业务 XML：

用户要「新建应用 / 从零搭业务软件 / 做一套 OA/CRM…」
目标软件目录下**没有**可用的、用户已确认过的 PLAN.md

可跳过访谈、直接实施的情况：

用户明确说「跳过规划直接生成」
已有完整且用户确认过的 PLAN.md（按清单执行即可）
小改动（只改一张表单、一个菜单等）——本技能不强制介入

工作流¶

与库表设计的流水线（必须遵守）：

SCHEMA 定库表 → PLAN 定蓝图
  → 事务表：普通表单 type=1/3/16 + .create_form_table → TLK_*
  → 主数据表 / 手工 SQL 表（需界面维护）：映射表单 type=65536（先 DDL 建表，不投递 create_form_table）

有需求且需定库表时：先确认 DATABASE_SCHEMA.md（design-database-schema），再写本技能的 PLAN.md。用户明确跳过库表设计时可直接规划。

表类型 → 表单 type（与 SCHEMA 对齐，硬规则）：

SCHEMA 表类型 / 创建方式	表单 `type`	建表方式	`.create_form_table`
事务表（动态表单）	`1`（或 `3`/`16`）	平台 `TLK_*`	必须
主数据表（手工 SQL）	`65536` 映射表单	部署侧/SQL 先建物理表	禁止
统计表等仅脚本/ETL 读写、无界面维护	无表单（见「非表单库表」）	手工 SQL	否
统计表等手工表需要界面增删改	`65536` 映射表单	同上先 DDL	禁止

禁止：把主数据建成 type=1 普通表单（会误建 TLK_）；禁止对映射表单投递 .create_form_table。

用户要新建应用
  → 已有确认过的 PLAN.md？
      是 → 按 §9 实施清单分步调用 generate-* / verify-workspace / rebuild-index
      否 → 宜先有确认过的 DATABASE_SCHEMA.md（复杂数据模型 / 主数据 / 统计表时）
              → 访谈（依据 SCHEMA + 需求）→ 写 PLAN.md → 请用户确认
              → 要改：改规划再确认
              → 确认：再按清单实施

表单落盘后：type∈{1,3,16} 须投递 .create_form_table；type=65536 不投递（目标表须已存在）。大批量落盘后先 verify-workspace 再 rebuild-index（见对应 skill）。

访谈规则¶

一次只问 1～2 个关键问题；信息够即可写初稿，未定事项写入「开放问题」
软件 / 模块 / 表单 / 视图 / 流程等资源 name 用**英文标识**；中文放显示名或描述
例外（硬规则）：.menu / .mobilemenu / .widget / .widgetgroup 的 name 即前台标题，除非用户明确指定其它语言，默认中文（目录名/文件名与 name 一致用中文）。PLAN 菜单表可只写中文名，不必再拆「英文 name + 显示名」
优先澄清：数据源参数（见下）、业务目标、模块边界、核心表单与字段（按 SCHEMA：事务表→普通表单、主数据→映射表单；类型 + 值/选项/联动/隐藏/只读等**业务逻辑**）、可编辑表单工具栏 activity（至少保存；含动作前/后与显隐只读逻辑）、是否审批流、角色、PC/移动入口
数据源参数必须写入 PLAN.md；缺「数据库类型」或「数据库名」时**不得**请用户确认规划，也**不得**进入 generate-datasource-file
有**非默认数据源**、手工库表（主数据/统计）、**公用函数库**时须在对应节写清用途；**报表**无对应 generate skill，规划中仅可一句带过，不必展开
未获用户确认前，不调用任何 generate-* 写业务 XML

数据源参数（规划必填）¶

参数	是否必填	说明
数据库类型（dbType）	必填	整数；`4`=MySQL（最常见）；见 `generate-datasource-file` dbType 表
数据库名	必填	业务库名；写入 JDBC URL
schema	按需必填	Oracle / PostgreSQL / 达梦 / KingBase / OceanBase 等需要时必须写清；MySQL 通常不需要，写「无」
host	可默认	未指定时用库类型默认（MySQL：`localhost` / `${DB_HOST:localhost}`）
port	可默认	未指定时用库类型默认（MySQL：`3307` / `${DB_PORT:3307}`）
username	可默认	未指定时用库类型默认（MySQL：`root`）
password	可默认	未指定时用库类型默认（MySQL：`${DB_PASSWORD:Teemlink2010}`）

访谈策略：先问 数据库类型 + 数据库名（及需要时的 schema）；host/port/username/password 可直接采用默认值，仅当用户声明非默认环境时再追问。MySQL 默认值与落盘细则见 generate-datasource-file「MySQL 默认约定」。

建议访谈顺序（可合并提问）：

软件英文 name、显示名、业务目标（一段话）
数据源：默认库（数据库类型、数据库名；schema 若需要；host/port/username/password 可默认）；是否有非默认库及用途
模块划分
核心表单与字段：对照 SCHEMA——事务表→普通表单 type=1；主数据表/需界面维护的手工 SQL 表→映射表单 type=65536（并问清物理表名、主键列、字段↔列映射）；每个存值字段：**必须**字段名 + 类型/控件；**按需**值计算、选项计算、联动、隐藏、只读；可编辑表单须定工具栏 activity（默认保存；挂流程再加流程类操作）；跨表取数则问清来源与回写
手工库表：SCHEMA 中主数据/统计表的建表与 DDL（由 design-database-schema 写入 DATABASE_SCHEMA.md）；需界面维护的主数据在上一步已归入映射表单；仅脚本/ETL 读写、无表单的表写入「非表单库表」
角色与菜单入口
按需：视图（类型、数据来源/查询表单/过滤、列、工具栏操作逻辑）、流程（功能+节点关系）、统计图、Excel 导入、定时任务、Widget、函数库、API 等
报表：无则写「无」；有则一句说明即可（不展开设计）

PLAN.md 模板（必须按此结构落盘）¶

将下列模板填实后写入 {软件名}.application/PLAN.md。实施清单按实际范围增删行，但**顺序**与推荐搭建顺序一致；每项标注对应 skill 名。

# {软件显示名} — 应用规划

## 1. 概述

- 软件 name：`{EnglishName}`
- 显示名：
- type：`0`（常规业务）/ 其他
- activated：`true` / `false`
- 业务目标：（1 段）
- 范围：
- 不做事项：

## 2. 数据源（必填）

### 默认数据源（必有）

默认业务库；实施 `generate-datasource-file` 时按本表落盘，并投递 `*.init_default_datasource`。

| 参数 | 值 | 必填/默认可空 | 说明 |
|------|-----|---------------|------|
| 数据库类型 dbType | `4`（例：MySQL） | **必填** | 整数；与真实库一致 |
| 数据库名 | | **必填** | 写入 JDBC URL |
| schema | 无 / `{schema}` | **按需必填** | Oracle/PG/DM/KingBase/OceanBase 等需要时必填；MySQL 写「无」 |
| host | `localhost` | 可默认 | MySQL 默认可写 `${DB_HOST:localhost}` |
| port | `3307` | 可默认 | MySQL 默认 `3307`；其它库用常见端口 |
| username | `root` | 可默认 | MySQL 默认 `root` |
| password | `${DB_PASSWORD:Teemlink2010}` | 可默认 | MySQL 默认见 `generate-datasource-file` |
| 数据源 name | `main` | 建议 | `.datasource` 文件名；脚本 `dsName` |
| defaultDataSource | `true` | **必填语义** | 默认库须 true |
| 用途 | 本软件主业务库 | **必填语义** | 一句话说明 |

> **硬约束**：缺「数据库类型」或「数据库名」则 PLAN.md 不完整，禁止请用户确认、禁止实施 datasource。host/port/username/password 未写时，实施阶段按 `generate-datasource-file` 库类型默认值补全（MySQL 见「MySQL 默认约定」）。

### 非默认数据源（无则写「无」）

外系统库、只读报表库、历史库等；`defaultDataSource=false`。规划须讲清**用途**与谁会读写（视图 SQL、定时任务、导入等）。

| 数据源 name | 数据库类型 | 数据库名 | schema | 用途说明 | 读写方（视图/任务/…） |
|-------------|------------|----------|--------|----------|----------------------|
|             |            |          |        |          |                      |

连接参数可另附小表或与默认库同列结构；未指定的 host/port/账号仍可走库类型默认。

## 3. 角色规划

| 角色 name | 显示名/职责说明 | status=1 前台可见 | 权限要点（菜单/视图级） |
|-----------|-----------------|-------------------|-------------------------|
| admin     |                 | 是                |                         |

> permissions JSON 细节在实施 `generate-role-file` 时再写；此处只定角色与授权范围。

## 4. 模块划分

| 模块 name | 显示名/职责 | 依赖其他模块 |
|-----------|-------------|--------------|
|           |             |              |

## 5. 表单规划（含动态表、映射表单与非表单库表）

### 表单清单

| 表单 name | 所属模块 | type | SCHEMA 表/创建方式 | 映射物理表（65536） | 是否挂流程 | 关联视图 | 工具栏 activity（必填/无） |
|-----------|----------|------|-------------------|---------------------|------------|----------|---------------------------|
|           |          | 1 / 65536 / 256 | 事务表 / 主数据表 / — | 无 / `MD_…` |            |          | 必填（见操作规划）        |

- **事务表** → `type=1`（或 `3`/`16`）：落库后投递 `*.create_form_table` → `TLK_*`
- **版式：所有表单默认拖拽三栏**（`showType=new`、`pcLayoutMode=pc`、三栏 `layout.pc`）；有业务区块时规划 **分割线**（`splitField`）分组。仅用户明确要求印刷 / 经典 / 纸张排版时，规划印刷表单（`showType=old`、`pcLayoutMode=classic`）。规划中无需写印刷 document，除非用户要求。
- **主数据表 / 需维护的手工 SQL 表** → **`type=65536` 映射表单**：先手工 DDL 建表；**不**投递 `.create_form_table`；须规划 `mappingStr`（见下）
- 查询/片段/模板等：规划中注明「不建动态表」
- 视图需要列表上方条件筛选时：另规划 `type=256` **查询表单**，并在 §6 视图的 `searchFormId` 绑定（见下）

### 映射表单规划（每个 type=65536 一张；无则写「无」）

对应 SCHEMA **主数据表**（及需界面维护的其它手工 SQL 表）。实施见 `generate-form-file`「创建映射表单」。

| 表单 name | 物理表 tableName | 主键列（MAPPINGID→） | 字段 name → 物理列 columnName（摘要） |
|-----------|------------------|----------------------|----------------------------------------|
|           | MD_…             | ID                   | name→NAME；…（必含 MAPPINGID→主键列） |

硬约束：

- `formName` = 表单 `name`；`tableName` = SCHEMA 物理表名（已存在或实施清单先 DDL）
- `columnMappings`：业务字段 `fieldName`=表单字段 name，`columnName`=真实列名（**无 `ITEM_`**）
- **必须**含 `MAPPINGID` → 主键列；`MAPPINGID` **不**出现在字段规划的控件行里
- 可编辑映射表单须规划保存类 activity（同普通表单，至少 `34`）

### Activity 定义（表单工具栏）

**Activity** = 表单打开后顶部/工具栏上的操作按钮，与字段模板分离，落盘为：

```text
{表单名}.form/{操作名}.activity

实施时由 generate-form-file 写入；规划阶段须在 PLAN.md 中写清每个**可编辑**表单要哪些操作（name + type），不可只写字段。

表单类别	type 示例	是否必须规划 activity	默认最低配置
普通表单（normal form）	`1`（及需可编辑落库的 `3`/`16`）	必须	至少一个保存类：`type=34`（保存）；按需再加返回 `10`、关闭 `8`、保存并返回 `11` 等
映射表单（主数据/手工 SQL）	`65536`	必须（可编辑时）	同普通：至少保存 `34`；按需返回等
挂流程的普通表单	同上 + §7 有 flow	必须	保存 `34` + 流程处理 `5`（或保存并启动 `4` / 流程启动 `33`，按业务选）
查询表单	`256`	通常无	可不规划工具栏
片段/模板等	其它	按需	无编辑保存需求时可写「无」

硬约束：凡 type=1 的普通业务表单与可编辑的 type=65536 映射表单，§5 必须附「操作规划」表且至少一行；实施清单勾选 form 时须同时落盘对应 .activity。禁止只生成 .form 而无工具栏 activity。

常用 type（规划填整数即可；完整表见 generate-form-file）：

type	含义	规划何时用
34	保存	普通表单默认必备
11	保存并返回	从视图进入编辑后需回列表
42	保存并新建	连续录入
4	保存并启动流程	保存后立刻启流程
5	流程处理	审批节点提交（预设流程时注明关联 flow name）
33	流程启动	单独「启动流程」按钮
10	返回	不保存返回
8	关闭窗口	弹层/新窗关闭
13	自定义	需脚本或关联表单时

操作规划（每个可编辑表单一张表；工具栏 `.activity`）¶

每个 normal form（type=1，以及同样需要可编辑保存的 3/16） 与 可编辑映射表单（type=65536） 必须有下表；查询等无工具栏时写「无」并在表单清单注明。

操作 name	type	动作前执行逻辑	动作后执行逻辑	隐藏条件逻辑	只读条件逻辑	说明（关联流程 name 等）
保存	34					普通/映射表单默认必备

必须（可编辑表单每行不可空）：

规划项	说明	对应 `.activity`
操作 name	按钮显示名	`name`
type	整数；可编辑表单至少含 `34`	`type`

按需（有业务规则才填；写**业务逻辑**，不写脚本代码）：

规划项	说明	对应 `.activity`
动作前执行逻辑	点击后、默认动作前：校验、提示、是否中断等	`beforeActionScript`
动作后执行逻辑	默认动作成功后：回写、跳转、消息等	`afterActionScript`
隐藏条件逻辑	何时不显示该按钮	`hiddenScript`
只读条件逻辑	何时按钮不可点	`readonlyScript`
关联流程	流程类按钮注明 flow name	`onActionFlow` 等

实施时按 generate-form-file + iscript-usage 将上列业务逻辑落成脚本。

字段规划（每个表单一张表；字段 `name` 用英文标识）¶

实施 generate-form-file 时依此填写 JsonTemplate；未列「按需」项视为空/默认。所有表单默认拖拽三栏（showType=new、pcLayoutMode=pc，见 generate-form-file「布局约定」）；规划中无需逐字段写栏位坐标，除非用户要求单列/两栏/四栏、全宽控件，或明确要求印刷表单。

分组：字段有明确业务区块时，在字段表中插入 splitField 行（显示名=分组标题，如「基本信息」），实施时用 split_f；勿规划 labelField 冒充分组。

规划阶段只写业务逻辑（值怎么算、选项从哪来、改谁影响谁、何时隐藏/只读），**不要**写 iScript。

字段名 name	显示名	类型/控件 scope	值计算逻辑	选项计算逻辑	联动关系	隐藏条件	只读条件	必填	备注（视图选择/映射等）
splitBasic	基本信息	splitField（分割线）	—	—	—	—	—	—	分组标题；其后字段进三栏

必须（每行不可空）：

规划项	说明	对应 JsonTemplate
字段名	英文标识；事务表动态列 `ITEM_`+大写 name；映射表单列名见 mappingStr，无 ITEM_	`name`
类型/控件	存值字段写 `fieldtype`；控件写 scope（如 `selectField`）	`fieldtype` + 节点 `scope`

按需（有业务规则才填；无则留空；均写业务意图）：

规划项	说明	对应 JsonTemplate / 机制
值计算逻辑	默认值、根据他字段计算、取当前用户等	`valuescript`
选项计算逻辑	固定枚举或按条件动态选项；存值英文码、显示中文（如存 `DRAFT` 显「草稿」）	`optionsscript`（`optionseditmode=01`；`opts.add(中文,英文)`）
联动关系	改 A 时如何影响 B/C（清空、重算值、刷新选项、显示/隐藏等）；写清触发字段与受影响字段	`refreshonchanged` / `refreshfields` / 受影响字段的值·选项·显隐逻辑
隐藏条件	何时不显示该字段（含打印场景可在备注区分）	`hiddenscript`（打印另见 `hiddenprintscript`）
只读条件	固定只读或条件只读	`texttype=readonly` / `readonlyscript`
必填	是/否或条件必填说明	无条件必填：`validatelibs` 挂系统默认 `checkEmpty_system`；其它校验：自定义 `.valid` 勾选进 `validatelibs`
备注	视图选择框：不存值；规划写清回写到哪些存值字段；`dialogview` 实施用视图 id	`viewdialogField`（store=N）+ 目标 `xxxxField` 的 `mapping`

实施时按 generate-form-file + iscript-usage 将「逻辑/条件」列落成脚本；规划表可不出现「脚本」字样。

控件选型（字段规划时写清 scope）¶

业务场景	控件 scope	规划要点
单据号 / 单号 / 流水号（平台自动生成）	`noField`（按需）	见下「编号/单号 → NoField」；存值（TEXT）；备注写清前缀/`digit`/是否含年月日
人员 / 用户 / 员工（选人）	`userField`	见下「人员/用户/员工 → UserField」；存值（用户 id，TEXT）；备注写清单选/多选
部门 / 单位 / 组织（选组织节点）	`treedepartmentField`	见下「部门/单位/组织 → TreeDepartmentField」；存值（部门 id，TEXT）
附件 / 上传文件	`attachmentField`	见下「附件 → AttachmentField」；存值（TEXT，附件元数据 JSON）
简单选择（固定少量选项、单选）	`selectField`（下拉）或 `radioField`（平铺）	按展示习惯二选一；填选项计算逻辑（库存英文、界面中文）；存值
多选（固定选项）	`checkboxField`	按业务规则；多值 `;` 分隔；填选项计算逻辑（库存英文、界面中文）；存值
从其它表单/视图快速挑选并填入本表	`viewdialogField`（视图选择框）+ 至少一个存值字段	仅选择填充，本身不存库；见下节；禁止只规划 viewdialog 而无目标字段
多行纯文本	`textareaField`	备注/说明；不是 HTML 编辑器
HTML / 富文本编辑器	`htmleditorField`	需求名含「HTML编辑器」「富文本」必须用此 scope；禁止写成 `textareaField`

文本/数字/日期等仍用 inputField / dataField / textareaField / htmleditorField 等（见 generate-form-file）。

编号/单号 → NoField（按需）¶

需求里的「编号 / 单号 / 流水号 / 单据号」**不要默认**一律 inputField（只读）或手写值脚本拼号；按生成方式选型：

需求口径	规划控件	说明
由平台流水号控件自动生成（新建即出号；前缀+位数±年月日）	`noField`	字段规划 scope=`noField`；备注：`headText` 前缀、`digit`、是否 `isYear`/`isMonth`/`isDay`
用户手工录入 / 外部系统传入 / 导入带入	`inputField`	可编辑或按需只读
按业务编号规则表（如分类规则、自定义规则引擎）计算	`inputField` + 值计算逻辑	写清规则来源；不是 noField
从已有主数据/单据挑选已有编号	`inputField`（存）+ `viewdialogField`（选）	见「视图选择框」

按需使用（硬规则）：

需求明确「自动编号 / 流水号 / 系统生成单号」且无独立编号规则实体 → 优先 noField
需求未要求自动出号、或编号语义是业务主键/档案编码（如物料编码、分类编码由主数据维护）→ 勿用 noField
禁止：把所有 *No / *Code 字段无脑改成 noField；禁止用只读 inputField + 空值冒充「会自动出号」
实施：generate-form-file 的 noField / ftb.no_f(...)；SCHEMA 列仍按存值 TEXT/VARCHAR 规划（动态表 ITEM_*）

人员/用户/员工 → UserField¶

需求里表示**平台组织中的人**（人员、用户、员工、申请人、审批人、借阅人、编制人、签收人、责任人等）时，规划与落盘使用 userField（用户选择框），**不要**用普通 inputField 手填姓名/id，也**不要**用 selectField 枚举全员。

需求口径	规划控件	说明
选一个人或多个（通讯录/组织用户）	`userField`	scope=`userField`；备注：`selectmode`=`single` 或 `multiSelect`；存用户 id
默认当前登录人	`userField` + 值计算逻辑	如「默认申请人=当前用户」；实施用 `valuescript`（见 iscript-usage）
选部门 / 单位 / 组织（非个人）	`treedepartmentField`	见下节；禁止用 userField 冒充部门
仅展示姓名文本、不参与选人（接口写入的纯展示）	`inputField`（只读）	例外；备注写明「非选人、只读展示」
从业务单据视图挑一行顺带带出人员	`userField`（存）或目标 id 字段 + `viewdialogField`（选）	人仍优先 userField；视图只作辅助填充

硬规则：

字段语义含人员/用户/员工/…人/…员（申请人、审批人、借阅人、编制人、签收人、执行人、监销人、责任人等）且需在界面**选择组织用户** → 必须 userField
**禁止**用 inputField 存用户 id/姓名冒充选人控件
禁止**把部门字段建成 userField；部门/单位/组织用 **treedepartmentField
角色/岗位多选若需求明确是「角色」而非「人」，用角色相关控件或视图选择，不是 userField
实施：generate-form-file 的 userField / ftb.user_f(...)；SCHEMA 列按 TEXT/VARCHAR 存用户 id（动态表 ITEM_*）

部门/单位/组织 → TreeDepartmentField¶

需求里表示**平台组织树节点**（部门、单位、组织、所属部门、申请部门、责任部门、分发部门等）时，规划与落盘使用 treedepartmentField（树形部门选择框），**不要**用普通 inputField 手填部门名/id，也**不要**用 userField 或固定选项 selectField 枚举全部门。

需求口径	规划控件	说明
从组织树选部门/单位/组织	`treedepartmentField`	scope=`treedepartmentField`；存部门 id；备注：是否仅叶子 `selectleafnodesonly`
默认当前用户部门	`treedepartmentField` + 值计算逻辑	实施用 `valuescript`（见 iscript-usage）
选人（非组织节点）	`userField`	禁止用 treedepartmentField 冒充选人
仅展示部门名称文本、不参与选树（接口写入的纯展示）	`inputField`（只读）	例外；备注写明「非选部门、只读展示」
从业务视图挑一行顺带带出部门	`treedepartmentField`（存）+ `viewdialogField`（选）	部门仍优先 treedepartmentField

硬规则：

字段语义含部门/单位/组织/…部/所属部门/申请部门/责任部门/分发部门等且需在界面**选择组织树节点** → 必须 treedepartmentField
**禁止**用 inputField 存部门 id/名称冒充选部门控件
**禁止**用 userField 选部门；**禁止**用 deptField 作为新建默认（遗留兼容见 generate-form-file，新规划一律树形部门）
实施：generate-form-file 的 treedepartmentField / ftb.dept_f(...)；SCHEMA 列按 TEXT/VARCHAR 存部门 id（动态表 ITEM_*）

附件 → AttachmentField¶

需求里表示**上传/挂载文件**（附件、附件上传、证明材料、发行版文件、草稿附件、外发副本、模板文件、销毁证明等）时，规划与落盘使用 attachmentField（附件上传控件），**不要**用 textareaField / inputField 手填路径或 JSON 冒充附件。

需求口径	规划控件	说明
通用附件上传（单/多文件）	`attachmentField`	scope=`attachmentField`；存附件元数据 JSON（TEXT）；备注：`limitnumber`、扩展名限制等
仅图片上传/拍照（需求明确「图片」）	`imageuploadField` / `onlinetakephotoField`	不是通用附件；见 `generate-form-file`
知识库/文档库专用上传（需求明确 KM）	`kmdataField`	例外；新建业务表单默认仍用 `attachmentField`
纯文本备注、路径字符串展示（不上传）	`textareaField` / `inputField`	例外；备注写明「非附件上传」

硬规则：

字段语义含附件/上传/文件/证明材料/发行版/草稿附件/外发副本/模板文件等且界面需**上传文件** → 必须 attachmentField
**禁止**用 textareaField 或 inputField 存附件 JSON/路径冒充附件控件
**禁止**把通用附件建成 htmleditorField；富文本与附件勿混用
实施：generate-form-file 的 attachmentField / ftb.attach_f(...)；SCHEMA 列按 TEXT 规划（动态表 ITEM_*，存元数据非 BLOB）

业务引用键：用编码，不用 XXID（硬规则）¶

在业务实现过程中，避免使用 XXID，而应用由业务含义的 XX编码。ID 通常为无意义的非重复序列号。

场景	应规划	禁止默认
流水引用主数据/档案	`suppliesCode` / `roomCode` / `vehiclePlate` / `sealCode` / `customerCode` 等业务编码（可另存名称快照）	`suppliesId` / `roomId` / `vehicleId` / `sealId` / `customerId` 等无业务语义的平台/文档 id
选择视图回写	mapping 优先回写编码列（及名称）；校验/扣减/关联 SQL 按编码查主数据表	回写隐藏「ID」脚本列（`doc.getId()` / `MAPPINGID`）作为唯一业务外键
库表关联（SCHEMA）	逻辑外键列对应 `ITEM_CODE` / 业务键；文档说明「对 MD_.CODE」	事务表业务列对 `MD_*.ID` 当默认关联键（平台内部主键除外：如 `PARENT`、`userField` 存用户 id）

例外（允许存平台 id）： userField（用户）、treedepartmentField（部门）、子表 PARENT、映射表单自身 MAPPINGID→表主键——这些是平台身份/结构键，不是「用品/会议室/客户」这类业务档案引用。

枚举/选项：库存英文、界面中文（硬规则）¶

表单优先：数据库存储英文，在表单界面显示中文。

规划项	应写	禁止
固定枚举（状态/类型/库位/是否等）	选项计算逻辑写清「显中文 / 存英文码」对照（如草稿=`DRAFT`、是=`Y`）	存中文文案；或只写中文不给英文码
与 SCHEMA	英文码与 `DATABASE_SCHEMA.md` 枚举列一致	表单一套中文存值、库表另一套英文码
实施落盘	`generate-form-file`：`opts.add("中文","EN")` / `opts_pairs(("EN","中文"))`	`opts.add("EN","中文")` 颠倒

列表/视图展示中文标签见 generate-view-file 状态类列（码→中文）。

视图选择框（快速选择填充；不存储）¶

viewdialogField 在平台中为 store=N：只提供「打开选择视图 → 选中行 → 按 mapping 回写本表其它字段」的交互，不产生动态表列、不持久化业务值。业务数据必须落在其它存值控件上（inputField / selectField / textareaField / dataField / number 型 inputField 等 store=Y 字段）。

规划与实施模式（强制）：

角色	规划什么	落盘
存值字段（1…N）	真正要入库/参与校验/列表展示的业务项（如分类编码、密级、物料编码）	`inputField` 等；有 `fieldtype`；事务表对应 `ITEM_*`
视图选择框（辅助）	仅作「快速选择」按钮/入口；name 与存值字段不要抢同一业务语义当唯一字段	`viewdialogField`；`dialogview`=选择视图 id；`mapping` 指向上述存值字段；优先 `eventmapping`=主存值字段 name（跟随控件显示）

推荐成对规划示例（分类编码 / 用品档案）：

字段 name	控件	作用
`categoryCode` / `suppliesCode`	`inputField`（可只读）	存业务编码（主关联键）
`categoryName` / `suppliesName`	`inputField`（可只读，按需）	存/显名称快照
`pickCategory` / `pickSupplies`	`viewdialogField`	打开选择视图，mapping 回写 Code（及 Name）；`eventmapping`=编码字段

禁止：

仅规划一个 viewdialogField（如 name=categoryCode）却期望它入库——不会建列、不会存值
用 viewdialog 替代 select/radio 做「本表枚举存值」（枚举存值用 select/radio/checkbox）
mapping 目标指向不存在的字段，或只指向另一个 store=N 字段
业务档案引用默认规划/回写 *Id（无业务含义的序列号/文档 id）；应回写 *Code / 车牌 / 文号等业务键

当字段值需从**另一张业务表单的数据**中挑选时，规划并实施按下列顺序：

**先**有来源业务表单（被选数据所在 .form：事务表多为 type=1，主数据多为 type=65536）
再**规划/创建一张**选择用视图（relatedForm=来源表单；列覆盖需展示与需回写的字段；用途注明「供 xxx 表单视图选择框」）
再**在目标表单规划：**存值字段（承接回写）+ viewdialogField（绑定 module + dialogview=选择视图 id；规划表可暂写视图 name，实施换 id）
规划 mapping：选中行后，视图列 → 本表存值字段 name（不是 viewdialog 自己当唯一存值目标）

每个视图选择框附一张映射表（可放在字段备注或附录）：

目标表单存值字段 formField	选择视图列（规划写 fieldName/显示名；实施换列 id）	说明

实施对应：viewdialogField.dialogview = 选择视图根 id（禁止写视图 name）；mapping = [{ "视图列id": "本表存值字段name" }, …]，用 map_cols(("存值字段","列id"))（列 id 来自选择视图下 *.column，可用 load_column_field_map；**禁止**用列 fieldName 如 code 当键）；**优先**设 eventmapping = 主存值字段 name（设计器「跟随控件显示」），独立大按钮才留空字符串。

依赖顺序：来源表单 → 选择视图 → 目标表单（存值字段 + viewdialogField）。实施清单中若目标表单早于选择视图，须拆步或调序，禁止先写 dialogview 指向尚不存在的视图。禁止：dialogview="CategorySelect" 这类视图 name；运行时按 id 加载，写成 name 会导致选择框无法打开。禁止：mapping: [{"code":"categoryCode"}]（键是列 fieldName）；正确形如 [{"__Lc3GlJjkeR1t2gdPc45":"categoryCode"}]（值必须是**已规划的存值字段** name）。禁止：把 viewdialogField 当成「带存储的选型控件」；它只做快速选择填充，须配合其它 xxxxField 满足业务存取。

非表单数据库表（仅无界面表单时；无则写「无」）¶

指**没有**对应业务表单、由脚本/SQL/ETL 直接读写**的库表（典型：仅聚合刷新的**统计表、对接中间表等）。

主数据表**若需界面维护：归入上文 **映射表单 type=65536，**不要**只写在本节而不建表单
事务表（TLK_*）字段规划已在「字段规划」；此处**不要**重复罗列
本节写清：表名、作用、主要字段、谁读写；细结构对齐 DATABASE_SCHEMA.md

表名	类型（统计/其它）	作用说明	主要字段摘要	读写方

6. 视图与菜单¶

视图清单¶

先定**视图类型**（根标签），再定数据来源与列/操作。

根标签	类型	规划何时用
`ListView`	列表（默认）	常规列表、网格、选择框数据源
`TreeView`	树形	层级数据（须规划上级/本级/名称等映射列）
`CalendarView`	日历	按日期展示（须规划日期映射列）
`GanttView`	甘特	计划/进度（须规划名称/开始/结束/完成等映射）
`MapView`	地图	按地址/坐标展示

视图 name	所属模块	类型（根标签）	relatedForm	用途（列表/选择框/树/…）
		ListView

用途含「供某表单视图选择框」时：须在 §5 对应 viewdialogField 中引用本视图；规划可写 name，实施 dialogview 必须写本视图 id。

数据来源规划（每个视图一块；决定查什么数据）¶

实施时写入 {视图名}.view 元数据。editMode 与「数据来源逻辑 / 过滤」必须配对，缺一不可。

规划写**业务语义**：绑定哪张表单、是否要查询表单筛选项、过滤规则是什么（谁可见、默认只看未完成等）。**不要**在规划里写完整 SQL/DQL/iScript；实施时再按 editMode 落盘。

视图 name	视图类型	editMode	relatedForm	数据源 dataSourceId	查询表单 searchFormId	查询字段（若有查询表单）	数据来源逻辑及过滤条件	设计代码摘要（实施用，可后补）
	ListView	00		（默认库可空）

必须：

规划项	说明	对应 `.view`
视图类型	上表根标签	根元素名
editMode	`00` 设计 / `01` DQL / `02` SQL / `03` 存储过程 / `04` 脚本数据	`editMode`
relatedForm	设计模式（`00`）必填：数据来源表单（规划写 name）；`04` 通常无数据来源表单	`relatedForm`
数据来源逻辑及过滤条件	业务描述：查哪些单据、默认过滤、权限范围；`04` 写清脚本如何组装行与分页	见下表落盘位置

editMode → 落盘对照（实施用；规划「数据来源逻辑」列只写业务规则）：

editMode	含义	实施时设计代码形态	对应元素
`00`	设计	`relatedForm` + 过滤条件 JSON 数组（无条件 `[]`）	`filterCondition` 等
`01`	DQL	iScript return DQL 串	`filterScript`
`02`	SQL	iScript return SQL 串	`sqlFilterScript`
`03`	存储过程	iScript return 过程调用串	`procedureFilterScript`
`04`	脚本数据	iScript return `{row_count, data[]}`（自行分页）；列 `name`↔`items[].columnName`	`scriptDataFilterScript`

按需：

规划项	说明	对应 `.view`
dataSourceId	非默认库时指定 §2 非默认数据源	`dataSourceId`
searchFormId	列表需条件筛选 UI 时绑定 `type=256` 查询表单	`searchFormId`
查询字段	查询表单上有哪些筛选项、与过滤逻辑如何对应	查询表单字段规划 + 过滤说明
默认排序	排序字段与升降	`orderField` / `orderType`
只读	只读视图去掉写操作	`readonly`

查询表单绑定（按需）¶

列表视图需要「按条件查询」时，在规划中同时完成：

§5 增加一张 type=256 查询表单（字段=可筛条件；不建动态表）
本视图数据来源填写 searchFormId = 该查询表单（规划写 name，实施换 id）
查询表单字段与过滤条件的对应关系写在「数据来源逻辑及过滤条件」或「查询字段」列

无列表筛选需求时：searchFormId 留空，不必造查询表单。

设计模式业务表约定：TLK_ + 表单 name；业务列 ITEM_ + 字段名大写。

列规划（每个视图一张表）¶

实施 generate-view-file 时落盘为 {视图}.view/{列名}.column。列表视图至少一列。写清**有哪些列、数据从哪来**（表单字段 / 脚本计算列 / 行号等）。

列 name	列类型 type	数据来源（绑定字段 fieldName / 计算说明）	宽度/顺序	备注（树/日历/甘特映射等）
	COLUMN_TYPE_FIELD

必须：

规划项	说明	对应 `.column`
列 name	表头显示名	`name`
列类型	`COLUMN_TYPE_FIELD` / `SCRIPT` / `OPERATE` / `LOGO` / `ROWNUM`	`type`
数据来源	字段列：表单字段英文 name；脚本列：计算业务含义（不写代码）	`fieldName` / `valueScript`

映射表视图（relatedForm 为 type=65536）： 普通列与需取值的状态列均规划为 COLUMN_TYPE_SCRIPT（兼容表单字段名与物理列名）；**禁止**默认填 COLUMN_TYPE_FIELD。事务表视图仍用 FIELD。细则见 generate-view-file「硬规则：映射表列表列」。

按需：宽度/顺序；树/日历/甘特 mappingField；行内按钮等（见 generate-view-file）。

操作规划（每个视图一张表；工具栏 `.activity`）¶

实施时落盘为 {视图}.view/{操作名}.activity。常用：新建 type=2、删除 type=3；只读列表可无写操作。逻辑列写**业务规则**，不写脚本。

操作 name	type	动作前执行逻辑	动作后执行逻辑	隐藏条件逻辑	只读条件逻辑	说明
新建	2
删除	3

必须（有工具栏时每行不可空）：操作 name、type。

按需：动作前/后、隐藏、只读（对应 beforeActionScript / afterActionScript / hiddenScript / readonlyScript）；打开方式、关联流程等。实施时按 generate-view-file + iscript-usage 落盘。

菜单规划¶

描述有哪些菜单、PC/移动、挂到哪张表单/视图/图表。菜单 name 默认中文（与落盘目录名一致；即前台标题），除非用户明确要求英文。

菜单 name（中文标题）	PC/移动	挂接目标（表单/视图/图表 name）	说明
	PC

7. 流程规划（若有；无则写「无」）¶

写清**实现什么业务审批/流转**，以及**节点与关系**（谁审批、流转条件、回退等）。不写流程图 JSON/XML / 脚本实现。

流程 name	关联表单	功能描述	节点概要（含角色/处理人规则）	节点关系与流转条件	表单操作要点

可按需附录节点明细表（列：节点 name、类型、处理人规则、进入/离开条件、说明）。

有流程时：§5 对应表单操作须含流程处理/启动类；§8 Widget 默认含流程摘要。

8. 按需能力（无则各条写「无」）¶

图表（chart）¶

chart name	所属模块	图表类型（如折线/柱/饼）	功能描述	数据来源逻辑（查什么、如何聚合）	是否挂菜单/Widget

规划写业务意图与数据口径；**不要**写 ECharts option / scripttext 代码。实施 generate-chart-file。有首页展示则 §8 Widget 增加 type=chart。

Excel 导入（excelconfig）¶

配置 name	功能描述	目标表单/表	导入逻辑（列映射、校验、去重/更新策略）

实施 generate-excelconfig-file；规划只写映射与业务规则，不写 jsonTemplate 代码。

定时任务（task）¶

任务 name	功能描述	触发周期/启动方式	执行逻辑（做什么、读写哪些表/接口）

实施 generate-task-file；规划只写业务步骤，不写 taskScript。

函数库规划¶

描述应用内**公用函数**（多处表单/视图/任务复用的计算、校验、取数封装）。无则写「无」。

函数名	用途说明	入参（业务含义）	返回（业务含义）	主要调用方

规划只写契约与业务含义；实现脚本在实施阶段编写。

API / apigroup / statelabel¶

有则各列一行说明用途；无则写「无」。

报表¶

当前无独立报表 generate skill：**不必**在 PLAN 中展开报表设计。若需求提到报表，写一句「报表：…（实施时另行处理）」即可。

首页门户砖块；落盘在应用级 widget/（**不是**模块下）。实施 generate-widget-file。须先有分组 .widgetgroup，再写 .widget（widgetGroupId=parentId=分组 id）。

默认规则（规划时自动纳入，除非用户明确不要）：

条件	必须规划的 Widget	type	依赖
§7 有流程（非「无」）	至少一个流程摘要（流程处理）	`system_workflow`	无；`actionContent` 可空；按需 `showAll`
§8 有统计图 chart	每个需上首页的图对应一个统计图 Widget	`chart`	先有对应 `.chart`；`moduleid`=图表所在模块；`actionContent`=图表 id

Widget name（默认中文标题）	分组 widgetgroup（默认中文）	type	功能描述	挂接目标（图表/视图 name 等）
流程摘要	默认分组	system_workflow	待办/流程处理入口	—
		chart		{图表 name}

type 速查（规划常用）：

type	含义	规划要点
`system_workflow`	流程摘要 / 流程处理	有审批流时默认建；`showAll` 是否跨全部软件
`chart`	统计图	依赖已存在的 chart；写清模块 + 图表 name
`view`	挂接视图	`moduleid` + 视图 name
`summary`	表单摘要（待办/分享等）	`actionContent`=SummaryCfg id（实施时解析）
其他	page / iscript / carousel…	有明确需求再写

9. 实施清单（可勾选）¶

按顺序执行；完成后把 [ ] 改为 [x]。

10. 开放问题¶

（确认前尽量清空；留下的必须标明谁拍板）

## 确认与实施

1. 写出 `PLAN.md` 后，向用户展示路径，并明确询问：「请确认规划；确认后按实施清单分步落盘。」确认前须已填 §2「数据库类型」「数据库名」（及需要时的 schema）。
2. 用户要求修改 → 更新 `PLAN.md` → 再次确认。
3. 用户确认后：严格按 §9 顺序，**一次推进一小步或一批明确范围**，调用对应 skill（如 `generate-application-file`、`generate-form-file`）。实施 datasource 时严格按 §2 参数 + `generate-datasource-file`。
4. 每完成清单项，把对应 `[ ]` 勾成 `[x]` 并保存 `PLAN.md`。
5. 实施中若发现规划缺口，先改 `PLAN.md` 再继续生成，避免 silent drift。

## 硬规则清单

新建整应用且无已确认 PLAN.md 时，先本技能；确认前不批量 generate-*
先建 {软件名}.application/ 目录，再写 PLAN.md
PLAN.md 结构含 §1–§10；§9 顺序与推荐搭建顺序一致
规划只写业务逻辑，禁止在 PLAN.md 写具体 iScript/JS/SQL/伪代码实现
§2 默认数据源必填：数据库类型、数据库名；schema 按需；host/port/username/password 可默认；须写用途
§2 非默认数据源：有则写清 name、连接要点、用途与读写方；无则写「无」
缺 §2 默认库数据库类型或数据库名时，禁止请用户确认、禁止 generate-datasource-file
资源 name：模块/表单/视图/流程等英文；菜单/移动菜单/Widget/WidgetGroup 的 name 默认中文（除非用户明确指定其它语言）
type∈{1,3,16} 在清单中标注需 .create_form_table；type=65536 标注不投递且 mappingStr 已规划
§5 表单**默认拖拽三栏**（实施 showType=new、pcLayoutMode=pc）；有业务区块时规划 分割线 splitField 分组；仅用户明确要求印刷/经典/纸张或其它栏数时偏离
§5 字段规划：必须含字段名+类型/控件；按需含值计算、选项计算、联动关系、隐藏条件、只读条件（业务描述）；系统自动单号→noField；人员/用户/员工→userField；部门/单位/组织→treedepartmentField；附件上传→attachmentField（勿用 textarea/input 冒充）
§5 表单操作规划：必须含 name+type（普通表单与可编辑映射表单至少保存 34）；按需含动作前/后、隐藏、只读逻辑
§5 主数据表 / 需维护的手工 SQL 表 → type=65536 映射表单（禁止用 type=1）；规划 mappingStr（tableName、列映射、MAPPINGID→主键）；DDL 先于映射表单
§5 非表单库表：仅无界面表单的手工表（如纯统计/中间表）；主数据有界面则走映射表单，勿只列在非表单节
简单单选：selectField 或 radioField；多选：checkboxField；枚举存英文码、界面显中文（选项计算逻辑写清对照）；跨表快速挑选：viewdialogField（store=N，不存值）+ 存值 xxxxField + 选择视图 + mapping（目标必须是存值字段）
业务引用键用编码不用 XXID：流水引用主数据/档案存 *Code（或车牌等业务键）+ 可选名称；禁止默认 *Id；选择视图 mapping 优先回写编码列；iScript/SQL 按编码查主数据（平台 user/dept/PARENT/MAPPINGID 除外）
§6 视图：定类型（List/Tree/Calendar/Gantt/Map）；数据来源（查询表单/过滤业务逻辑）；列（含数据来源）；操作（含动作前/后与显隐只读逻辑）；映射表视图列规划 SCRIPT（禁止默认 FIELD）
§6 菜单规划：列出菜单与挂接目标
§7 流程：功能描述 + 节点 + 关系；无则「无」
§8：图表/Excel导入/定时任务/函数库/Widget 等按有无填写；报表不展开
§3 角色规划：角色说明与权限要点
§7 有流程时：Widget 须含 system_workflow（用户明确不要除外）
统计图 Widget（type=chart）：先规划并落盘对应 .chart，再写 Widget
小改动或用户声明跳过规划时，可不走本技能 ```

应用前置规划（plan-application）¶

规划写法（强制）¶

产出物¶

何时触发（强建议门禁）¶

工作流¶

访谈规则¶

数据源参数（规划必填）¶

PLAN.md 模板（必须按此结构落盘）¶

操作规划（每个可编辑表单一张表；工具栏 `.activity`）¶

字段规划（每个表单一张表；字段 `name` 用英文标识）¶

控件选型（字段规划时写清 scope）¶

编号/单号 → NoField（按需）¶

人员/用户/员工 → UserField¶

部门/单位/组织 → TreeDepartmentField¶

附件 → AttachmentField¶

业务引用键：用编码，不用 XXID（硬规则）¶

枚举/选项：库存英文、界面中文（硬规则）¶

视图选择框（快速选择填充；不存储）¶

非表单数据库表（仅无界面表单时；无则写「无」）¶

6. 视图与菜单¶

视图清单¶

数据来源规划（每个视图一块；决定查什么数据）¶

查询表单绑定（按需）¶

列规划（每个视图一张表）¶

操作规划（每个视图一张表；工具栏 `.activity`）¶

菜单规划¶

7. 流程规划（若有；无则写「无」）¶

8. 按需能力（无则各条写「无」）¶

图表（chart）¶

Excel 导入（excelconfig）¶

定时任务（task）¶

函数库规划¶

API / apigroup / statelabel¶

报表¶

Widget / WidgetGroup¶

Widget 清单¶

9. 实施清单（可勾选）¶

10. 开放问题¶

应用前置规划（plan-application）¶

规划写法（强制）¶

产出物¶

何时触发（强建议门禁）¶

工作流¶

访谈规则¶

数据源参数（规划必填）¶

PLAN.md 模板（必须按此结构落盘）¶

操作规划（每个可编辑表单一张表；工具栏 .activity）¶

字段规划（每个表单一张表；字段 name 用英文标识）¶

控件选型（字段规划时写清 scope）¶

编号/单号 → NoField（按需）¶

人员/用户/员工 → UserField¶

部门/单位/组织 → TreeDepartmentField¶

附件 → AttachmentField¶

业务引用键：用编码，不用 XXID（硬规则）¶

枚举/选项：库存英文、界面中文（硬规则）¶

视图选择框（快速选择填充；不存储）¶

非表单数据库表（仅无界面表单时；无则写「无」）¶

6. 视图与菜单¶

视图清单¶

数据来源规划（每个视图一块；决定查什么数据）¶

查询表单绑定（按需）¶

列规划（每个视图一张表）¶

操作规划（每个视图一张表；工具栏 .activity）¶

菜单规划¶

7. 流程规划（若有；无则写「无」）¶

8. 按需能力（无则各条写「无」）¶

图表（chart）¶

Excel 导入（excelconfig）¶

定时任务（task）¶

函数库规划¶

API / apigroup / statelabel¶

报表¶

Widget / WidgetGroup¶

Widget 清单¶

9. 实施清单（可勾选）¶

10. 开放问题¶

操作规划（每个可编辑表单一张表；工具栏 `.activity`）¶

字段规划（每个表单一张表；字段 `name` 用英文标识）¶

操作规划（每个视图一张表；工具栏 `.activity`）¶