FOSMVVM 字段生成器

按照FOSMVVM模式生成表单规范。

概念基础

完整架构上下文请参阅 FOSMVVMArchitecture.md | OpenClaw参考

表单规范（以{Name}Fields协议实现）是用户输入的单一事实来源。它回答了以下问题：

1. 1. 用户可以提供什么数据？（属性）
2. 应该如何呈现？（包含类型、键盘、自动填充语义的FormField）
3. 有哪些约束条件？（验证规则）
4. 应该显示什么消息？（本地化的标题、占位符、错误信息）

为什么这很重要

表单规范定义一次，处处使用：

swift
// 同一协议被不同的消费者采用：
struct CreateIdeaRequestBody: ServerRequestBody, IdeaFields { ... } // HTTP传输
@ViewModel struct IdeaFormViewModel: IdeaFields { ... } // 表单渲染
final class Idea: Model, IdeaFields { ... } // 持久化验证

这确保了：

• - 一致的验证 - 客户端和服务器端使用相同的规则
• 共享的本地化 - 一个YAML文件，处处使用
• 单一事实来源 - 修改一处，处处生效

与FOSMVVM的关联

表单规范与以下部分集成：

• - 本地化系统 - FormField的标题/占位符和验证消息使用LocalizableString
• 验证系统 - 实现ValidatableModel协议
• 请求系统 - RequestBody类型采用Fields进行验证传输
• ViewModel系统 - ViewModel采用Fields进行表单渲染

何时使用此技能

• - 定义新表单（创建、编辑、筛选、搜索）
• 为请求体添加验证
• 任何需要符合ValidatableModel的类型
• 当fosmvvm-fluent-datamodel-generator需要DataModel的表单字段时

此技能生成的内容

一个完整的表单规范包含3个文件：

项目结构配置

将占位符替换为项目的实际路径：

预期结构：

Sources/
{ViewModelsTarget}/
FieldModels/
{Name}Fields.swift
{Name}FieldsMessages.swift
{ResourcesPath}/
FieldModels/
{Name}FieldsMessages.yml

如何使用此技能

调用方式：
/fosmvvm-fields-generator

前置条件：

• - 从对话上下文中理解表单目的
• 已讨论字段需求（名称、类型、约束）
• 已识别实体关系（此表单创建/编辑的内容）

工作流集成：
此技能在定义表单验证和用户输入契约时使用。技能自动引用对话上下文——无需文件路径或问答。通常在表单支持模型之前使用fosmvvm-fluent-datamodel-generator。

模式实现

此技能引用对话上下文来确定Fields协议结构：

表单分析

从对话上下文中，技能识别：

• - 表单目的（创建、编辑、筛选、登录、设置）
• 实体关系（User、Idea、Document - 正在创建/编辑的内容）
• 协议命名（CreateIdeaFields、UpdateProfile、LoginCredentials）

字段设计

对于需求中的每个字段：

• - 属性规范（名称、类型、可选 vs 必填）
• 呈现类型（FormFieldType：text、textArea、select、checkbox）
• 输入语义（FormInputType：email、password、tel、date）
• 约束条件（必填、长度范围、值范围、日期范围）
• 本地化（标题、占位符、验证错误消息）

文件生成顺序

1. 1. 包含FormField定义和验证的Fields协议
2. 包含@LocalizedString属性的FieldsMessages结构体
3. 包含本地化字符串的FieldsMessages YAML文件

上下文来源

技能引用以下信息：

• - 先前的对话：讨论过的表单需求、字段规范
• 规范文件：如果Claude已将表单规范读入上下文
• 现有模式：来自类似Fields协议的代码库分析

关键模式

协议结构

swift
public protocol {Name}Fields: ValidatableModel, Codable, Sendable {
var fieldName: FieldType { get set }
var {name}ValidationMessages: {Name}FieldsMessages { get }
}

FormField定义

swift
static var contentField: FormField { .init(
fieldId: .init(id: content),
title: .localized(for: {Name}FieldsMessages.self, propertyName: content, messageKey: title),
placeholder: .localized(for: {Name}FieldsMessages.self, propertyName: content, messageKey: placeholder),
type: .textArea(inputType: .text),
options: [
.required(value: true)
] + FormInputOption.rangeLength(contentRange)
) }

FormField类型参考

FormInputType参考（常用）

验证方法模式

swift
internal func validateContent(_ fields: [FormFieldBase]?) -> [ValidationResult]? {
guard fields == nil || (fields?.contains(Self.contentField) == true) else {
return nil
}

var result = [ValidationResult]()

if content.isEmpty {
result.append(.init(
status: .error,
field: Self.contentField,
message: {name}ValidationMessages.contentRequiredMessage
))
} else if !Self.contentRange.contains(NSString(string: content).length) {
result.append(.init(
status: .error,
field: Self.contentField,
message: {name}ValidationMessages.contentOutOfRangeMessage
))
}

return result.isEmpty ? nil : result
}

消息结构体模式

swift
@FieldValidationModel public struct {Name}FieldsMessages {
@LocalizedString(content, messageGroup: validationMessages, messageKey: required)
public var contentRequiredMessage

@LocalizedString(content, messageGroup: validationMessages, messageKey: outOfRange)
public var contentOutOfRangeMessage
}

YAML结构

yaml
en:
{Name}FieldsMessages:
content:
title: 内容
placeholder: 请输入您的内容...
validationMessages:
required: 内容为必填项
outOfRange: 内容长度必须在1到10,000个字符之间

命名约定

另请参阅

• - FOSMVVMArchitecture.md - 完整FOSMVVM架构参考
• [fosmvvm-viewmodel-generator](../fosmv