# freelance + itops 插件增强设计规格 > 日期: 2026-04-20 > 来源: 多专家头脑风暴（UX专家 + 业务顾问 + 运维专家 + 财务专家） > 状态: Draft > 前置: `docs/superpowers/specs/2026-04-19-shantou-zhijie-it-services-plugins-design.md` --- ## 1. 背景与动机 当前插件是「数据录入系统」，不是「赚钱工具」。一人 IT 服务公司的核心痛点： 1. **钱从哪里来？** — 商机跟进靠人记，没有自动提醒、没有漏斗分析 2. **项目做到哪了？** — 任务状态和工时手动填，跟合同金额/应收款脱节 3. **钱收回来了吗？** — 报价→合同→开票→收款割裂，没有串联 4. **运维服务会不会忘？** — 巡检计划写了没人催，SLA 超时了才知道 5. **税和利润算不清？** — 收支分散在不同表里，月底做账要手动汇总 **问题根因：** 平台已有 trigger_events、settings、templates、cascade_from、visible_when、validation 六大能力，但两个插件完全没有使用。 **改进目标：** 纯插件层增强，三层递进： - Layer 1: 智能业务引擎 — 让系统主动驱动用户做事 - Layer 2: 仪表盘重构 — 一个页面掌控全局 - Layer 3: 专业输出 — 一键生成报价单/发票/合同 PDF --- ## 2. Layer 1: 智能业务引擎 — freelance 插件 ### 2.1 Settings（插件配置页） 一次性配置公司信息和业务偏好，后续自动生效： ```toml [settings] # ── 基本信息 ── [[settings.fields]] name = "company_name" display_name = "公司名称" field_type = "text" required = true group = "基本信息" [[settings.fields]] name = "currency_symbol" display_name = "货币符号" field_type = "text" default_value = "¥" group = "基本信息" # ── 财务 ── [[settings.fields]] name = "default_tax_rate" display_name = "默认税率(%)" field_type = "number" default_value = 6 range = [0.0, 100.0] group = "财务" # ── 提醒 ── [[settings.fields]] name = "payment_reminder_days" display_name = "收款提前提醒(天)" field_type = "number" default_value = 3 range = [1.0, 30.0] group = "提醒" [[settings.fields]] name = "notify_contract_expiring" display_name = "合同到期提醒" field_type = "boolean" default_value = true group = "提醒" [[settings.fields]] name = "notify_payment_overdue" display_name = "逾期收款提醒" field_type = "boolean" default_value = true group = "提醒" [[settings.fields]] name = "notify_opportunity_followup" display_name = "商机跟进提醒" field_type = "boolean" default_value = true group = "提醒" ``` ### 2.2 Trigger Events（自动事件驱动） 关键操作时自动发通知，把"人找事"变"事找人"： ```toml [[trigger_events]] name = "opportunity_stage_changed" display_name = "商机阶段变更" description = "商机阶段发生变化时通知，特别是成交或失败" entity = "opportunity" on = "update" [[trigger_events]] name = "contract_status_changed" display_name = "合同状态变更" description = "合同状态变化时检查到期预警" entity = "contract" on = "update" [[trigger_events]] name = "invoice_status_changed" display_name = "发票状态变更" description = "发票状态变化时检查逾期收款" entity = "invoice" on = "update" [[trigger_events]] name = "task_status_changed" display_name = "任务状态变更" description = "任务完成或取消时通知" entity = "task" on = "update" [[trigger_events]] name = "expense_created" display_name = "新支出记录" description = "记录新支出时通知" entity = "expense" on = "create" ``` ### 2.3 Cascade（智能联动下拉） 选客户后自动过滤其关联数据： **contract 实体新增：** ```toml # client_id 选择后，opportunity_id 自动过滤只显示该客户的商机 [[schema.entities.fields]] name = "opportunity_id" field_type = "uuid" display_name = "关联商机" ref_entity = "opportunity" cascade_from = "client_id" cascade_filter = "client_id" # client_id 选择后，quote_id 自动过滤只显示该客户的报价 [[schema.entities.fields]] name = "quote_id" field_type = "uuid" display_name = "关联报价" ref_entity = "quote" cascade_from = "client_id" cascade_filter = "client_id" ``` **invoice 实体新增：** ```toml # client_id 选择后，project_id 自动过滤 [[schema.entities.fields]] name = "project_id" field_type = "uuid" display_name = "关联项目" ref_entity = "project" cascade_from = "client_id" cascade_filter = "client_id" # client_id 选择后，contract_id 自动过滤 [[schema.entities.fields]] name = "contract_id" field_type = "uuid" display_name = "关联合同" ref_entity = "contract" cascade_from = "client_id" cascade_filter = "client_id" ``` **time_entry 实体新增：** ```toml # project_id 选择后，task_id 自动过滤只显示该项目的任务 [[schema.entities.fields]] name = "task_id" field_type = "uuid" display_name = "关联任务" ui_widget = "entity_select" ref_entity = "task" ref_label_field = "title" ref_search_fields = ["title"] cascade_from = "project_id" cascade_filter = "project_id" ``` ### 2.4 Visible When（条件显示） 只在有意义时才显示字段： | 实体 | 字段 | 条件 | |------|------|------| | invoice | payment_date | `status == 'paid' \|\| status == 'partial'` | | contract | paid_amount | `status != 'drafting'` | | task | actual_hours | `status != 'todo'` | | quote | total_amount | `status != 'draft'` | ### 2.5 Validation（字段校验） ```toml # client 实体 - email 字段增加校验 [[schema.entities.fields]] name = "email" field_type = "string" display_name = "邮箱" validation = { pattern = "^[^@]+@[^@]+\\.[^@]+$", message = "请输入有效的邮箱地址" } # client 实体 - phone 字段增加校验 [[schema.entities.fields]] name = "phone" field_type = "string" display_name = "电话" validation = { pattern = "^1[3-9]\\d{9}$", message = "请输入有效的手机号" } ``` --- ## 3. Layer 2: 仪表盘重构 — freelance 插件 将占位符仪表盘升级为真正的指挥中心。通过 `widgets` 声明告诉平台该展示什么： ```toml [[ui.pages]] type = "dashboard" label = "工作台" icon = "DashboardOutlined" # ── 财务概览卡片 ── [[ui.pages.widgets]] type = "stat_cards" label = "财务概览" cards = [ { entity = "invoice", aggregate = "sum", field = "amount", filter = "type == 'payment' && status != 'overdue'", label = "本月收入", icon = "rise", color = "green" }, { entity = "expense", aggregate = "sum", field = "amount", label = "本月支出", icon = "fall", color = "red" }, { entity = "invoice", aggregate = "sum", field = "amount", filter = "status == 'overdue' || status == 'pending'", label = "应收总额", icon = "dollar", color = "orange" }, { entity = "invoice", aggregate = "count", filter = "status == 'overdue'", label = "逾期笔数", icon = "warning", color = "red" } ] # ── 紧急待办 ── [[ui.pages.widgets]] type = "action_list" label = "紧急待办" max_items = 5 queries = [ { entity = "invoice", filter = "status == 'overdue'", label_field = "invoice_number", subtitle_field = "amount", action = "查看", icon = "warning" }, { entity = "task", filter = "status != 'done' && status != 'cancelled'", sort = "due_date asc", label_field = "title", subtitle_field = "due_date", action = "处理", icon = "clock" }, { entity = "contract", filter = "status == 'active'", sort = "end_date asc", label_field = "title", subtitle_field = "end_date", action = "续约", icon = "file-text" }, { entity = "opportunity", filter = "next_follow_up <= today", label_field = "title", subtitle_field = "next_follow_up", action = "跟进", icon = "phone" } ] # ── 商机漏斗 ── [[ui.pages.widgets]] type = "funnel" label = "商机漏斗" entity = "opportunity" lane_field = "stage" value_field = "estimated_amount" lane_order = ["visit", "requirement", "quote", "negotiation", "won", "lost"] # ── 活跃项目卡片 ── [[ui.pages.widgets]] type = "card_list" label = "活跃项目" entity = "project" filter = "status == 'in_progress'" max_items = 4 title_field = "name" subtitle_field = "contract_amount" tags = ["business_type", "status"] ``` **依赖：** 仪表盘 widgets 渲染需要前端配合解析 `widgets` 声明。数据源来自平台已有的聚合 API（`/count`、`/aggregate`）。 --- ## 4. Layer 3: 专业输出 — freelance 插件 一键生成专业 PDF，替代手动排 Word： ### 4.1 报价单模板 ```toml [[templates]] name = "quote_pdf" display_name = "报价单" entity = "quote" format = "pdf" template_html = """

报价单 {{quote_number}}

客户：{{client.name}} | 有效期至：{{valid_until}}

{{#each lines}} {{/each}}
项目描述数量单价金额
{{item_name}}{{description}}{{quantity}}{{unit_price}}{{amount}}

小计：{{subtotal}} | 税率：{{tax_rate}}% | 总计：{{total_amount}}

备注：{{notes}}
""" ``` ### 4.2 发票模板 ```toml [[templates]] name = "invoice_pdf" display_name = "发票" entity = "invoice" format = "pdf" template_html = """

发票 {{invoice_number}}

客户：{{client.name}}
类型：{{type}}
开票日期：{{issue_date}}
到期日：{{due_date}}
¥{{amount}}

状态：{{status}}

备注：{{notes}}

""" ``` ### 4.3 合同模板 ```toml [[templates]] name = "contract_pdf" display_name = "合同" entity = "contract" format = "pdf" template_html = """

{{title}}

合同编号：{{contract_number}}

甲方：{{client.name}}

合同金额：¥{{amount}} | 已付：¥{{paid_amount}}

期限：{{start_date}} 至 {{end_date}}

付款条款：{{payment_terms}}

备注：{{notes}}

甲方签章
乙方签章
""" ``` --- ## 5. itops 插件增强 ### 5.1 Settings ```toml [settings] [[settings.fields]] name = "default_sla_response" display_name = "默认SLA响应时间(小时)" field_type = "number" default_value = 8 range = [1.0, 72.0] group = "SLA" [[settings.fields]] name = "default_sla_resolve" display_name = "默认SLA解决时间(小时)" field_type = "number" default_value = 48 range = [1.0, 168.0] group = "SLA" [[settings.fields]] name = "notify_sla_breach" display_name = "SLA超标提醒" field_type = "boolean" default_value = true group = "提醒" [[settings.fields]] name = "notify_check_due" display_name = "巡检到期提醒" field_type = "boolean" default_value = true group = "提醒" ``` ### 5.2 Trigger Events ```toml [[trigger_events]] name = "ticket_created" display_name = "新工单" description = "创建工单时开始SLA计时并通知" entity = "ticket" on = "create" [[trigger_events]] name = "ticket_status_changed" display_name = "工单状态变更" description = "工单状态变化时检查SLA是否达标" entity = "ticket" on = "update" [[trigger_events]] name = "contract_status_changed" display_name = "维保合同状态变更" description = "合同状态变化时检查到期预警" entity = "service_contract" on = "update" [[trigger_events]] name = "check_plan_updated" display_name = "巡检计划更新" description = "巡检计划更新时检查下次巡检日期" entity = "check_plan" on = "update" ``` ### 5.3 Cascade ```toml # ticket 实体：选客户后过滤其维保合同 [[schema.entities.fields]] name = "contract_id" field_type = "uuid" display_name = "维保合同" ui_widget = "entity_select" ref_entity = "service_contract" ref_label_field = "name" ref_search_fields = ["name"] cascade_from = "client_id" cascade_filter = "client_id" # check_record 实体：选巡检计划后过滤合同 [[schema.entities.fields]] name = "contract_id" field_type = "uuid" display_name = "维保合同" ref_entity = "service_contract" cascade_from = "plan_id" cascade_filter = "contract_id" ``` ### 5.4 Visible When | 实体 | 字段 | 条件 | |------|------|------| | ticket | resolution | `status == 'resolved' \|\| status == 'closed'` | | ticket | responded_at | `status != 'open'` | | ticket | resolved_at | `status == 'resolved' \|\| status == 'closed'` | | ticket | closed_at | `status == 'closed'` | | check_record | issues_found | `result == 'abnormal'` | | check_record | actions_taken | `result == 'abnormal'` | ### 5.5 Validation ```toml # service_contract - contract_number 格式校验 validation = { pattern = "^SC-\\d{4}-\\d{4}$", message = "格式：SC-YYYY-NNNN" } ``` ### 5.6 Dashboard ```toml [[ui.pages]] type = "dashboard" label = "运维概览" icon = "DashboardOutlined" [[ui.pages.widgets]] type = "stat_cards" label = "运维概览" cards = [ { entity = "service_contract", aggregate = "count", filter = "status == 'active'", label = "活跃合同", icon = "file-text", color = "blue" }, { entity = "ticket", aggregate = "count", filter = "status == 'open' || status == 'in_progress'", label = "待处理工单", icon = "tool", color = "orange" }, { entity = "ticket", aggregate = "count", filter = "status == 'resolved'", label = "已解决工单", icon = "check-circle", color = "green" }, { entity = "check_plan", aggregate = "count", filter = "status == 'active'", label = "活跃巡检", icon = "schedule", color = "blue" } ] [[ui.pages.widgets]] type = "action_list" label = "紧急待办" max_items = 5 queries = [ { entity = "ticket", filter = "status == 'open'", sort = "priority asc", label_field = "title", subtitle_field = "type", action = "处理", icon = "warning" }, { entity = "service_contract", filter = "status == 'active'", sort = "end_date asc", label_field = "name", subtitle_field = "end_date", action = "续约", icon = "file-text" }, { entity = "check_plan", filter = "status == 'active'", sort = "next_check_date asc", label_field = "name", subtitle_field = "next_check_date", action = "巡检", icon = "schedule" } ] ``` ### 5.7 Template（维保合同 PDF） ```toml [[templates]] name = "service_contract_pdf" display_name = "维保合同" entity = "service_contract" format = "pdf" template_html = """

{{name}}

合同编号：{{contract_number}}

客户：{{client.name}}
合同金额：¥{{amount}}
期限：{{start_date}} 至 {{end_date}}
状态：{{status}}
SLA 承诺：响应 {{sla_response_hours}} 小时内 / 解决 {{sla_resolve_hours}} 小时内

服务范围：{{service_scope}}

付款条款：{{payment_terms}}

备注：{{notes}}

甲方签章
乙方签章
""" ``` --- ## 6. 改进汇总 | 层次 | 能力 | freelance | itops | |------|------|-----------|-------| | Layer 1 | settings | 7 个配置项（公司名/税率/提醒偏好） | 4 个配置项（SLA默认值/提醒偏好） | | Layer 1 | trigger_events | 5 个事件（商机/合同/发票/任务/支出） | 4 个事件（工单/合同/巡检） | | Layer 1 | cascade | 4 处联动（合同/发票/工时表单） | 2 处联动（工单/巡检记录） | | Layer 1 | visible_when | 4 个条件字段 | 6 个条件字段 | | Layer 1 | validation | 2 个校验（邮箱/手机） | 1 个校验（合同编号格式） | | Layer 2 | dashboard widgets | 财务卡片+紧急待办+商机漏斗+项目卡片 | 运维卡片+紧急待办 | | Layer 3 | templates | 3 个 PDF（报价单/发票/合同） | 1 个 PDF（维保合同） | **总计：** 2 个插件 × 3 层增强，从「数据录入」升级为「赚钱工具」。 --- ## 7. 实施优先级 ``` P1: freelance Layer 1（settings + trigger_events + cascade + visible_when + validation） P2: itops Layer 1（settings + trigger_events + cascade + visible_when + validation） P3: freelance Layer 3（3 个 PDF 模板） P4: itops Layer 3（维保合同 PDF 模板） P5: freelance Layer 2（仪表盘 widgets） P6: itops Layer 2（仪表盘 widgets） ``` P1-P4 是纯 plugin.toml 改动，可立即实施。P5-P6 的仪表盘 widgets 需要前端配合解析 widgets 声明。