erp/docs/superpowers/specs/2026-04-19-shantou-zhijie-it-services-plugins-design.md

# 汕头市智界科技有限公司 — 行业插件设计规格

> 日期: 2026-04-19
> 来源: 无主题发散式互动探讨（多专家头脑风暴）
> 状态: Draft

---

## 1. 背景与动机

以汕头市智界科技有限公司（一人 IT 服务公司）为案例，设计针对 IT 服务行业的 ERP 插件组合，覆盖其全部经营范围。

**公司经营范围：**
1. 软件开发
2. 数字文化创意软件开发
3. 人工智能基础/应用软件开发
4. 信息系统集成服务
5. 网络技术服务
6. 软件销售
7. 软件外包服务
8. 计算机软硬件及辅助设备批发/零售
9. 信息技术咨询服务
10. 信息系统运行维护服务
11. 数字内容制作服务
12. 市场营销策划

**设计原则：**
- 一人公司优先：所有功能对单人操作友好，减少上下文切换
- 最少插件覆盖最多场景：3 个插件覆盖全部经营范围
- 快捷操作优先：高频操作一键完成，不打开完整表单
- 全局工作台：一个仪表盘掌握全局

**插件组合与经营范围对照：**

| 插件 | 覆盖的经营范围 |
|------|--------------|
| freelance（自由职业者工作台） | 软件开发、AI开发、系统集成、外包、IT咨询、数字内容、营销策划 |
| itops（IT 运维服务台） | IT 运维服务、网络技术服务 |
| inventory（已有，需扩展） | 软硬件批发零售 |

---

## 2. 插件 1：erp-plugin-freelance（自由职业者工作台）

### 2.1 插件元数据

```toml
[metadata]
id = "erp-freelance"
name = "自由职业者工作台"
version = "0.1.0"
description = "一人 IT 服务公司的全链路业务管理：客户→商机→报价→合同→项目→工时→开票→收支"
author = "ERP Platform"
min_platform_version = "0.1.0"
```

### 2.2 权限声明（10 实体 × 2 = 20 个权限码）

```toml
[[permissions]]
code = "client.list"
name = "查看客户"
description = "查看客户列表和详情"

[[permissions]]
code = "client.manage"
name = "管理客户"
description = "创建、编辑、删除客户"

[[permissions]]
code = "opportunity.list"
name = "查看商机"
description = "查看商机列表和详情"

[[permissions]]
code = "opportunity.manage"
name = "管理商机"
description = "创建、编辑、删除商机"

[[permissions]]
code = "quote.list"
name = "查看报价"
description = "查看报价单列表和详情"

[[permissions]]
code = "quote.manage"
name = "管理报价"
description = "创建、编辑、删除报价单"

[[permissions]]
code = "quote_line.list"
name = "查看报价明细"
description = "查看报价明细列表"

[[permissions]]
code = "quote_line.manage"
name = "管理报价明细"
description = "创建、编辑、删除报价明细"

[[permissions]]
code = "contract.list"
name = "查看合同"
description = "查看合同列表和详情"

[[permissions]]
code = "contract.manage"
name = "管理合同"
description = "创建、编辑、删除合同"

[[permissions]]
code = "project.list"
name = "查看项目"
description = "查看项目列表和详情"

[[permissions]]
code = "project.manage"
name = "管理项目"
description = "创建、编辑、删除项目"

[[permissions]]
code = "task.list"
name = "查看任务"
description = "查看任务列表和详情"

[[permissions]]
code = "task.manage"
name = "管理任务"
description = "创建、编辑、删除任务"

[[permissions]]
code = "time_entry.list"
name = "查看工时"
description = "查看工时记录列表"

[[permissions]]
code = "time_entry.manage"
name = "管理工时"
description = "创建、编辑、删除工时记录"

[[permissions]]
code = "invoice.list"
name = "查看发票"
description = "查看发票/收款列表和详情"

[[permissions]]
code = "invoice.manage"
name = "管理发票"
description = "创建、编辑、删除发票/收款记录"

[[permissions]]
code = "expense.list"
name = "查看支出"
description = "查看支出列表和详情"

[[permissions]]
code = "expense.manage"
name = "管理支出"
description = "创建、编辑、删除支出记录"
```

### 2.3 实体设计（10 个实体）

#### 2.3.1 client（客户）

```toml
[[schema.entities]]
name = "client"
display_name = "客户"
is_public = true

  [[schema.entities.fields]]
  name = "name"
  field_type = "string"
  required = true
  display_name = "客户名称"
  searchable = true

  [[schema.entities.fields]]
  name = "contact_name"
  field_type = "string"
  display_name = "联系人"

  [[schema.entities.fields]]
  name = "phone"
  field_type = "string"
  display_name = "电话"

  [[schema.entities.fields]]
  name = "email"
  field_type = "string"
  display_name = "邮箱"

  [[schema.entities.fields]]
  name = "industry"
  field_type = "string"
  display_name = "行业"
  ui_widget = "select"
  filterable = true
  options = [
    { label = "制造业", value = "manufacturing" },
    { label = "零售", value = "retail" },
    { label = "教育", value = "education" },
    { label = "医疗", value = "healthcare" },
    { label = "政府", value = "government" },
    { label = "金融", value = "finance" },
    { label = "其他", value = "other" }
  ]

  [[schema.entities.fields]]
  name = "source"
  field_type = "string"
  display_name = "来源"
  ui_widget = "select"
  options = [
    { label = "转介绍", value = "referral" },
    { label = "线上", value = "online" },
    { label = "展会", value = "exhibition" },
    { label = "老客户", value = "repeat" },
    { label = "主动开发", value = "outreach" }
  ]

  [[schema.entities.fields]]
  name = "level"
  field_type = "string"
  display_name = "重要等级"
  ui_widget = "select"
  filterable = true
  options = [
    { label = "A", value = "a" },
    { label = "B", value = "b" },
    { label = "C", value = "c" }
  ]

  [[schema.entities.fields]]
  name = "status"
  field_type = "string"
  required = true
  display_name = "状态"
  ui_widget = "select"
  filterable = true
  default = "potential"
  options = [
    { label = "潜在", value = "potential" },
    { label = "活跃", value = "active" },
    { label = "休眠", value = "dormant" },
    { label = "流失", value = "lost" }
  ]

  [[schema.entities.fields]]
  name = "address"
  field_type = "string"
  display_name = "地址"

  [[schema.entities.fields]]
  name = "notes"
  field_type = "string"
  display_name = "备注"
  ui_widget = "textarea"
```

#### 2.3.2 opportunity（商机）

```toml
[[schema.entities]]
name = "opportunity"
display_name = "商机"

  [[schema.entities.fields]]
  name = "client_id"
  field_type = "uuid"
  required = true
  display_name = "客户"
  ui_widget = "entity_select"
  ref_entity = "client"
  ref_label_field = "name"
  ref_search_fields = ["name"]

  [[schema.entities.fields]]
  name = "title"
  field_type = "string"
  required = true
  display_name = "商机名称"
  searchable = true

  [[schema.entities.fields]]
  name = "business_type"
  field_type = "string"
  required = true
  display_name = "业务类型"
  ui_widget = "select"
  filterable = true
  options = [
    { label = "软件开发", value = "software_development" },
    { label = "AI 开发", value = "ai_development" },
    { label = "系统集成", value = "system_integration" },
    { label = "软件外包", value = "software_outsourcing" },
    { label = "IT 咨询", value = "it_consulting" },
    { label = "数字内容", value = "digital_content" },
    { label = "营销策划", value = "marketing_planning" }
  ]

  [[schema.entities.fields]]
  name = "stage"
  field_type = "string"
  required = true
  display_name = "阶段"
  ui_widget = "select"
  filterable = true
  default = "visit"
  options = [
    { label = "初访", value = "visit" },
    { label = "需求确认", value = "requirement" },
    { label = "报价", value = "quote" },
    { label = "谈判", value = "negotiation" },
    { label = "成交", value = "won" },
    { label = "失败", value = "lost" }
  ]

  [[schema.entities.fields]]
  name = "estimated_amount"
  field_type = "decimal"
  display_name = "预估金额"
  sortable = true

  [[schema.entities.fields]]
  name = "probability"
  field_type = "integer"
  display_name = "成交概率(%)"

  [[schema.entities.fields]]
  name = "expected_close_date"
  field_type = "date"
  display_name = "预计成交日期"

  [[schema.entities.fields]]
  name = "next_follow_up"
  field_type = "date"
  display_name = "下次跟进日期"

  [[schema.entities.fields]]
  name = "description"
  field_type = "string"
  display_name = "需求描述"
  ui_widget = "textarea"
```

#### 2.3.3 quote（报价单）

```toml
[[schema.entities]]
name = "quote"
display_name = "报价单"

  [[schema.entities.fields]]
  name = "client_id"
  field_type = "uuid"
  required = true
  display_name = "客户"
  ui_widget = "entity_select"
  ref_entity = "client"
  ref_label_field = "name"
  ref_search_fields = ["name"]

  [[schema.entities.fields]]
  name = "opportunity_id"
  field_type = "uuid"
  display_name = "关联商机"
  ref_entity = "opportunity"

  [[schema.entities.fields]]
  name = "quote_number"
  field_type = "string"
  required = true
  display_name = "报价单号"
  unique = true

  [[schema.entities.fields]]
  name = "status"
  field_type = "string"
  required = true
  display_name = "状态"
  ui_widget = "select"
  filterable = true
  default = "draft"
  options = [
    { label = "草稿", value = "draft" },
    { label = "已发送", value = "sent" },
    { label = "已接受", value = "accepted" },
    { label = "已拒绝", value = "rejected" },
    { label = "已过期", value = "expired" }
  ]

  [[schema.entities.fields]]
  name = "valid_until"
  field_type = "date"
  display_name = "有效期至"

  [[schema.entities.fields]]
  name = "subtotal"
  field_type = "decimal"
  display_name = "小计"
  sortable = true

  [[schema.entities.fields]]
  name = "tax_rate"
  field_type = "decimal"
  display_name = "税率(%)"

  [[schema.entities.fields]]
  name = "total_amount"
  field_type = "decimal"
  display_name = "总金额"
  sortable = true

  [[schema.entities.fields]]
  name = "notes"
  field_type = "string"
  display_name = "备注"
  ui_widget = "textarea"

  [[schema.entities.relations]]
  entity = "quote_line"
  foreign_key = "quote_id"
  on_delete = "cascade"
  name = "lines"
  type = "one_to_many"
  display_field = "item_name"
```

#### 2.3.4 quote_line（报价明细行）

```toml
[[schema.entities]]
name = "quote_line"
display_name = "报价明细"

  [[schema.entities.fields]]
  name = "quote_id"
  field_type = "uuid"
  required = true
  display_name = "报价单"
  ref_entity = "quote"

  [[schema.entities.fields]]
  name = "item_name"
  field_type = "string"
  required = true
  display_name = "项目名称"

  [[schema.entities.fields]]
  name = "description"
  field_type = "string"
  display_name = "描述"

  [[schema.entities.fields]]
  name = "quantity"
  field_type = "decimal"
  required = true
  display_name = "数量"
  default = 1

  [[schema.entities.fields]]
  name = "unit_price"
  field_type = "decimal"
  required = true
  display_name = "单价"

  [[schema.entities.fields]]
  name = "unit"
  field_type = "string"
  display_name = "单位"
  ui_widget = "select"
  default = "project"
  options = [
    { label = "项目", value = "project" },
    { label = "人月", value = "person_month" },
    { label = "人天", value = "person_day" },
    { label = "小时", value = "hour" },
    { label = "个", value = "piece" },
    { label = "套", value = "set" }
  ]

  [[schema.entities.fields]]
  name = "amount"
  field_type = "decimal"
  display_name = "金额"
```

#### 2.3.5 contract（合同）

```toml
[[schema.entities]]
name = "contract"
display_name = "合同"

  [[schema.entities.fields]]
  name = "client_id"
  field_type = "uuid"
  required = true
  display_name = "客户"
  ui_widget = "entity_select"
  ref_entity = "client"
  ref_label_field = "name"
  ref_search_fields = ["name"]

  [[schema.entities.fields]]
  name = "opportunity_id"
  field_type = "uuid"
  display_name = "关联商机"
  ref_entity = "opportunity"

  [[schema.entities.fields]]
  name = "quote_id"
  field_type = "uuid"
  display_name = "关联报价"
  ref_entity = "quote"

  [[schema.entities.fields]]
  name = "contract_number"
  field_type = "string"
  required = true
  display_name = "合同编号"
  unique = true

  [[schema.entities.fields]]
  name = "title"
  field_type = "string"
  required = true
  display_name = "合同名称"
  searchable = true

  [[schema.entities.fields]]
  name = "type"
  field_type = "string"
  required = true
  display_name = "合同类型"
  ui_widget = "select"
  filterable = true
  options = [
    { label = "开发合同", value = "development" },
    { label = "集成合同", value = "integration" },
    { label = "外包合同", value = "outsourcing" },
    { label = "咨询合同", value = "consulting" },
    { label = "维保合同", value = "maintenance" },
    { label = "销售合同", value = "sales" },
    { label = "其他", value = "other" }
  ]

  [[schema.entities.fields]]
  name = "status"
  field_type = "string"
  required = true
  display_name = "状态"
  ui_widget = "select"
  filterable = true
  default = "drafting"
  options = [
    { label = "草拟中", value = "drafting" },
    { label = "待签署", value = "pending_signature" },
    { label = "执行中", value = "active" },
    { label = "已完成", value = "completed" },
    { label = "已终止", value = "terminated" }
  ]

  [[schema.entities.fields]]
  name = "amount"
  field_type = "decimal"
  required = true
  display_name = "合同金额"
  sortable = true

  [[schema.entities.fields]]
  name = "paid_amount"
  field_type = "decimal"
  display_name = "已付金额"
  default = 0

  [[schema.entities.fields]]
  name = "start_date"
  field_type = "date"
  display_name = "开始日期"

  [[schema.entities.fields]]
  name = "end_date"
  field_type = "date"
  display_name = "结束日期"

  [[schema.entities.fields]]
  name = "payment_terms"
  field_type = "string"
  display_name = "付款条款"

  [[schema.entities.fields]]
  name = "notes"
  field_type = "string"
  display_name = "备注"
  ui_widget = "textarea"
```

#### 2.3.6 project（项目）

```toml
[[schema.entities]]
name = "project"
display_name = "项目"

  [[schema.entities.fields]]
  name = "client_id"
  field_type = "uuid"
  required = true
  display_name = "客户"
  ui_widget = "entity_select"
  ref_entity = "client"
  ref_label_field = "name"
  ref_search_fields = ["name"]

  [[schema.entities.fields]]
  name = "contract_id"
  field_type = "uuid"
  display_name = "关联合同"
  ref_entity = "contract"

  [[schema.entities.fields]]
  name = "opportunity_id"
  field_type = "uuid"
  display_name = "关联商机"
  ref_entity = "opportunity"

  [[schema.entities.fields]]
  name = "name"
  field_type = "string"
  required = true
  display_name = "项目名称"
  searchable = true

  [[schema.entities.fields]]
  name = "business_type"
  field_type = "string"
  display_name = "业务类型"
  ui_widget = "select"
  filterable = true
  options = [
    { label = "软件开发", value = "software_development" },
    { label = "AI 开发", value = "ai_development" },
    { label = "系统集成", value = "system_integration" },
    { label = "软件外包", value = "software_outsourcing" },
    { label = "IT 咨询", value = "it_consulting" },
    { label = "数字内容", value = "digital_content" },
    { label = "营销策划", value = "marketing_planning" }
  ]

  [[schema.entities.fields]]
  name = "deliverable_type"
  field_type = "string"
  display_name = "交付物类型"
  ui_widget = "select"
  options = [
    { label = "软件", value = "software" },
    { label = "网站", value = "website" },
    { label = "小程序", value = "miniprogram" },
    { label = "视频", value = "video" },
    { label = "设计稿", value = "design" },
    { label = "文档", value = "document" },
    { label = "咨询报告", value = "consulting_report" }
  ]

  [[schema.entities.fields]]
  name = "status"
  field_type = "string"
  required = true
  display_name = "状态"
  ui_widget = "select"
  filterable = true
  default = "pending"
  options = [
    { label = "待开始", value = "pending" },
    { label = "进行中", value = "in_progress" },
    { label = "已交付", value = "delivered" },
    { label = "验收中", value = "accepting" },
    { label = "已完成", value = "completed" },
    { label = "已搁置", value = "shelved" }
  ]

  [[schema.entities.fields]]
  name = "start_date"
  field_type = "date"
  display_name = "开始日期"

  [[schema.entities.fields]]
  name = "end_date"
  field_type = "date"
  display_name = "截止日期"

  [[schema.entities.fields]]
  name = "contract_amount"
  field_type = "decimal"
  display_name = "合同金额"
  sortable = true

  [[schema.entities.fields]]
  name = "description"
  field_type = "string"
  display_name = "项目说明"
  ui_widget = "textarea"

  [[schema.entities.relations]]
  entity = "task"
  foreign_key = "project_id"
  on_delete = "cascade"
  name = "tasks"
  type = "one_to_many"
  display_field = "title"

  [[schema.entities.relations]]
  entity = "time_entry"
  foreign_key = "project_id"
  on_delete = "cascade"
  name = "time_entries"
  type = "one_to_many"
  display_field = "description"
```

#### 2.3.7 task（任务）

```toml
[[schema.entities]]
name = "task"
display_name = "任务"

  [[schema.entities.fields]]
  name = "project_id"
  field_type = "uuid"
  required = true
  display_name = "所属项目"
  ui_widget = "entity_select"
  ref_entity = "project"
  ref_label_field = "name"
  ref_search_fields = ["name"]

  [[schema.entities.fields]]
  name = "title"
  field_type = "string"
  required = true
  display_name = "任务标题"
  searchable = true

  [[schema.entities.fields]]
  name = "status"
  field_type = "string"
  required = true
  display_name = "状态"
  ui_widget = "select"
  filterable = true
  default = "todo"
  options = [
    { label = "待办", value = "todo" },
    { label = "进行中", value = "in_progress" },
    { label = "已完成", value = "done" },
    { label = "已取消", value = "cancelled" }
  ]

  [[schema.entities.fields]]
  name = "priority"
  field_type = "string"
  required = true
  display_name = "优先级"
  ui_widget = "select"
  filterable = true
  default = "medium"
  options = [
    { label = "紧急", value = "urgent" },
    { label = "高", value = "high" },
    { label = "中", value = "medium" },
    { label = "低", value = "low" }
  ]

  [[schema.entities.fields]]
  name = "due_date"
  field_type = "date"
  display_name = "截止日期"

  [[schema.entities.fields]]
  name = "estimated_hours"
  field_type = "decimal"
  display_name = "预估工时"

  [[schema.entities.fields]]
  name = "actual_hours"
  field_type = "decimal"
  display_name = "实际工时"

  [[schema.entities.fields]]
  name = "description"
  field_type = "string"
  display_name = "详细说明"
  ui_widget = "textarea"
```

#### 2.3.8 time_entry（工时记录）

```toml
[[schema.entities]]
name = "time_entry"
display_name = "工时记录"

  [[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"]

  [[schema.entities.fields]]
  name = "project_id"
  field_type = "uuid"
  required = true
  display_name = "关联项目"
  ui_widget = "entity_select"
  ref_entity = "project"
  ref_label_field = "name"
  ref_search_fields = ["name"]

  [[schema.entities.fields]]
  name = "date"
  field_type = "date"
  required = true
  display_name = "日期"

  [[schema.entities.fields]]
  name = "hours"
  field_type = "decimal"
  required = true
  display_name = "时长(小时)"

  [[schema.entities.fields]]
  name = "description"
  field_type = "string"
  display_name = "工作内容"
```

#### 2.3.9 invoice（发票/收款）

```toml
[[schema.entities]]
name = "invoice"
display_name = "发票/收款"

  [[schema.entities.fields]]
  name = "client_id"
  field_type = "uuid"
  required = true
  display_name = "客户"
  ui_widget = "entity_select"
  ref_entity = "client"
  ref_label_field = "name"
  ref_search_fields = ["name"]

  [[schema.entities.fields]]
  name = "project_id"
  field_type = "uuid"
  display_name = "关联项目"
  ref_entity = "project"

  [[schema.entities.fields]]
  name = "contract_id"
  field_type = "uuid"
  display_name = "关联合同"
  ref_entity = "contract"

  [[schema.entities.fields]]
  name = "invoice_number"
  field_type = "string"
  required = true
  display_name = "发票号"
  unique = true

  [[schema.entities.fields]]
  name = "type"
  field_type = "string"
  required = true
  display_name = "类型"
  ui_widget = "select"
  filterable = true
  options = [
    { label = "开票", value = "invoice" },
    { label = "收款记录", value = "payment" }
  ]

  [[schema.entities.fields]]
  name = "amount"
  field_type = "decimal"
  required = true
  display_name = "金额"
  sortable = true

  [[schema.entities.fields]]
  name = "status"
  field_type = "string"
  required = true
  display_name = "状态"
  ui_widget = "select"
  filterable = true
  default = "pending"
  options = [
    { label = "待开票", value = "pending" },
    { label = "已开票", value = "issued" },
    { label = "部分收款", value = "partial" },
    { label = "已收款", value = "paid" },
    { label = "已逾期", value = "overdue" }
  ]

  [[schema.entities.fields]]
  name = "issue_date"
  field_type = "date"
  display_name = "开票日期"

  [[schema.entities.fields]]
  name = "due_date"
  field_type = "date"
  display_name = "到期日"

  [[schema.entities.fields]]
  name = "payment_date"
  field_type = "date"
  display_name = "实际收款日期"

  [[schema.entities.fields]]
  name = "notes"
  field_type = "string"
  display_name = "备注"
  ui_widget = "textarea"
```

#### 2.3.10 expense（支出）

```toml
[[schema.entities]]
name = "expense"
display_name = "支出"

  [[schema.entities.fields]]
  name = "project_id"
  field_type = "uuid"
  display_name = "关联项目"
  ref_entity = "project"

  [[schema.entities.fields]]
  name = "category"
  field_type = "string"
  required = true
  display_name = "类别"
  ui_widget = "select"
  filterable = true
  options = [
    { label = "硬件", value = "hardware" },
    { label = "软件订阅", value = "software" },
    { label = "云服务", value = "cloud" },
    { label = "差旅", value = "travel" },
    { label = "餐饮", value = "meal" },
    { label = "办公用品", value = "office" },
    { label = "其他", value = "other" }
  ]

  [[schema.entities.fields]]
  name = "amount"
  field_type = "decimal"
  required = true
  display_name = "金额"
  sortable = true

  [[schema.entities.fields]]
  name = "date"
  field_type = "date"
  required = true
  display_name = "日期"

  [[schema.entities.fields]]
  name = "vendor"
  field_type = "string"
  display_name = "供应商"

  [[schema.entities.fields]]
  name = "description"
  field_type = "string"
  display_name = "描述"
```

### 2.4 编号规则

```toml
[[numbering]]
entity = "quote"
field = "quote_number"
prefix = "QT"
format = "{PREFIX}-{YEAR}-{SEQ}"
seq_length = 4

[[numbering]]
entity = "contract"
field = "contract_number"
prefix = "CT"
format = "{PREFIX}-{YEAR}-{SEQ}"
seq_length = 4

[[numbering]]
entity = "invoice"
field = "invoice_number"
prefix = "INV"
format = "{PREFIX}-{YEAR}-{SEQ}"
seq_length = 4
```

### 2.5 页面设计（4 个页面）

#### 页面 1：全局工作台（Dashboard）

展示内容：
- **财务概览**：本月收入/支出/利润、应收总额、逾期金额
- **紧急待办**：今日到期任务、逾期收款、即将到期合同（7天内）
- **活跃项目**：进行中项目卡片（进度条 = 已用工时/预估工时）
- **最新工单**：最近 5 条 itops 工单（如已安装）
- **商机跟进提醒**：next_follow_up 在本周内的商机

快捷操作按钮条（页面顶部）：
- 开始/停止计时（悬浮计时器）
- 快速记支出（3 字段：金额+分类+备注）
- 新建报价
- 新建工单（如 itops 已安装）

```toml
[[ui.pages]]
type = "dashboard"
label = "工作台"
icon = "DashboardOutlined"
```

#### 页面 2：客户管理

客户列表（支持搜索、按来源/行业/等级/状态筛选）+ 客户详情 Tab 页：
- Tab 1：基本信息
- Tab 2：商机列表（看板视图，按阶段分列）
- Tab 3：报价/合同
- Tab 4：项目
- Tab 5：发票/收支

从客户详情一键生成：报价单 / 合同 / 项目

```toml
[[ui.pages]]
type = "tabs"
label = "客户管理"
icon = "team"

  [[ui.pages.tabs]]
  label = "客户列表"
  type = "crud"
  entity = "client"
  enable_search = true

[[ui.pages]]
type = "detail"
entity = "client"
label = "客户详情"

  [[ui.pages.sections]]
  type = "fields"
  label = "基本信息"
  fields = ["name", "contact_name", "phone", "email", "industry", "source", "level", "status", "address", "notes"]

  [[ui.pages.sections]]
  type = "crud"
  label = "商机"
  entity = "opportunity"
  filter_field = "client_id"

  [[ui.pages.sections]]
  type = "crud"
  label = "报价/合同"
  entity = "quote"
  filter_field = "client_id"

  [[ui.pages.sections]]
  type = "crud"
  label = "项目"
  entity = "project"
  filter_field = "client_id"

  [[ui.pages.sections]]
  type = "crud"
  label = "发票"
  entity = "invoice"
  filter_field = "client_id"

[[ui.pages]]
type = "kanban"
entity = "opportunity"
label = "商机看板"
icon = "swap"
lane_field = "stage"
lane_order = ["visit", "requirement", "quote", "negotiation", "won", "lost"]
card_title_field = "title"
card_subtitle_field = "estimated_amount"
card_fields = ["business_type", "probability"]
enable_drag = true
```

#### 页面 3：项目工作台

项目列表 → 项目详情 Tab 页：
- Tab 1：项目信息
- Tab 2：任务列表（状态分组，支持拖拽排序）
- Tab 3：工时记录（支持快速录入）
- Tab 4：关联发票

```toml
[[ui.pages]]
type = "crud"
entity = "project"
label = "项目管理"
icon = "project"
enable_search = true

[[ui.pages]]
type = "detail"
entity = "project"
label = "项目详情"

  [[ui.pages.sections]]
  type = "fields"
  label = "项目信息"
  fields = ["name", "client_id", "contract_id", "business_type", "deliverable_type", "status", "start_date", "end_date", "contract_amount", "description"]

  [[ui.pages.sections]]
  type = "crud"
  label = "任务"
  entity = "task"
  filter_field = "project_id"

  [[ui.pages.sections]]
  type = "crud"
  label = "工时记录"
  entity = "time_entry"
  filter_field = "project_id"

  [[ui.pages.sections]]
  type = "crud"
  label = "发票"
  entity = "invoice"
  filter_field = "project_id"
```

#### 页面 4：财务中心

Tab 1：报价管理（报价单列表 + 详情）
Tab 2：合同管理（合同列表 + 详情 + 到期预警）
Tab 3：发票/收款（发票列表 + 收支统计图表）

```toml
[[ui.pages]]
type = "tabs"
label = "财务中心"
icon = "account-book"

  [[ui.pages.tabs]]
  label = "报价管理"
  type = "crud"
  entity = "quote"
  enable_search = true

  [[ui.pages.tabs]]
  label = "合同管理"
  type = "crud"
  entity = "contract"
  enable_search = true

  [[ui.pages.tabs]]
  label = "发票/收款"
  type = "crud"
  entity = "invoice"
  enable_search = true

[[ui.pages]]
type = "crud"
entity = "expense"
label = "支出管理"
icon = "pay-circle"
enable_search = true
```

---

## 3. 插件 2：erp-plugin-itops（IT 运维服务台）

### 3.1 插件元数据

```toml
[metadata]
id = "erp-itops"
name = "IT 运维服务台"
version = "0.1.0"
description = "IT 运维工单管理 + SLA 追踪 + 定期巡检"
author = "ERP Platform"
min_platform_version = "0.1.0"
```

注意：itops 对 freelance 是松耦合可选依赖，不在 `metadata.dependencies` 中声明。跨插件引用通过 `ref_plugin` + `ref_fallback_label` 运行时降级。

### 3.2 权限声明（4 实体 × 2 = 8 个权限码）

```toml
[[permissions]]
code = "service_contract.list"
name = "查看维保合同"
description = "查看维保合同列表和详情"

[[permissions]]
code = "service_contract.manage"
name = "管理维保合同"
description = "创建、编辑、删除维保合同"

[[permissions]]
code = "ticket.list"
name = "查看工单"
description = "查看工单列表和详情"

[[permissions]]
code = "ticket.manage"
name = "管理工单"
description = "创建、编辑、删除工单"

[[permissions]]
code = "check_plan.list"
name = "查看巡检计划"
description = "查看巡检计划列表和详情"

[[permissions]]
code = "check_plan.manage"
name = "管理巡检计划"
description = "创建、编辑、删除巡检计划"

[[permissions]]
code = "check_record.list"
name = "查看巡检记录"
description = "查看巡检记录列表"

[[permissions]]
code = "check_record.manage"
name = "管理巡检记录"
description = "创建、编辑、删除巡检记录"
```

### 3.3 实体设计（4 个实体）

#### 3.3.1 service_contract（维保合同）

```toml
[[schema.entities]]
name = "service_contract"
display_name = "维保合同"

  [[schema.entities.fields]]
  name = "client_id"
  field_type = "uuid"
  display_name = "客户"
  ui_widget = "entity_select"
  ref_plugin = "erp-freelance"
  ref_entity = "client"
  ref_label_field = "name"
  ref_search_fields = ["name"]
  ref_fallback_label = "外部客户"

  [[schema.entities.fields]]
  name = "contract_number"
  field_type = "string"
  required = true
  display_name = "合同编号"
  unique = true

  [[schema.entities.fields]]
  name = "name"
  field_type = "string"
  required = true
  display_name = "合同名称"
  searchable = true

  [[schema.entities.fields]]
  name = "service_scope"
  field_type = "string"
  display_name = "服务范围"
  ui_widget = "textarea"

  [[schema.entities.fields]]
  name = "sla_level"
  field_type = "string"
  required = true
  display_name = "SLA 等级"
  ui_widget = "select"
  filterable = true
  default = "standard"
  options = [
    { label = "标准", value = "standard" },
    { label = "银牌", value = "silver" },
    { label = "金牌", value = "gold" }
  ]

  [[schema.entities.fields]]
  name = "sla_response_hours"
  field_type = "integer"
  display_name = "SLA 响应时间(小时)"
  default = 8

  [[schema.entities.fields]]
  name = "sla_resolve_hours"
  field_type = "integer"
  display_name = "SLA 解决时间(小时)"
  default = 48

  [[schema.entities.fields]]
  name = "status"
  field_type = "string"
  required = true
  display_name = "状态"
  ui_widget = "select"
  filterable = true
  default = "active"
  options = [
    { label = "生效中", value = "active" },
    { label = "即将到期", value = "expiring" },
    { label = "已过期", value = "expired" },
    { label = "已终止", value = "terminated" }
  ]

  [[schema.entities.fields]]
  name = "start_date"
  field_type = "date"
  required = true
  display_name = "开始日期"

  [[schema.entities.fields]]
  name = "end_date"
  field_type = "date"
  required = true
  display_name = "结束日期"

  [[schema.entities.fields]]
  name = "amount"
  field_type = "decimal"
  display_name = "合同金额"
  sortable = true

  [[schema.entities.fields]]
  name = "payment_terms"
  field_type = "string"
  display_name = "付款条款"

  [[schema.entities.fields]]
  name = "notes"
  field_type = "string"
  display_name = "备注"
  ui_widget = "textarea"

  [[schema.entities.relations]]
  entity = "ticket"
  foreign_key = "contract_id"
  on_delete = "nullify"
  name = "tickets"
  type = "one_to_many"
  display_field = "title"

  [[schema.entities.relations]]
  entity = "check_plan"
  foreign_key = "contract_id"
  on_delete = "cascade"
  name = "check_plans"
  type = "one_to_many"
  display_field = "name"
```

#### 3.3.2 ticket（工单）

```toml
[[schema.entities]]
name = "ticket"
display_name = "工单"

  [[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"]

  [[schema.entities.fields]]
  name = "client_id"
  field_type = "uuid"
  display_name = "客户"
  ui_widget = "entity_select"
  ref_plugin = "erp-freelance"
  ref_entity = "client"
  ref_label_field = "name"
  ref_search_fields = ["name"]
  ref_fallback_label = "外部客户"

  [[schema.entities.fields]]
  name = "title"
  field_type = "string"
  required = true
  display_name = "工单标题"
  searchable = true

  [[schema.entities.fields]]
  name = "type"
  field_type = "string"
  required = true
  display_name = "类型"
  ui_widget = "select"
  filterable = true
  default = "fault"
  options = [
    { label = "故障", value = "fault" },
    { label = "巡检", value = "check" },
    { label = "咨询", value = "consult" },
    { label = "变更", value = "change" },
    { label = "其他", value = "other" }
  ]

  [[schema.entities.fields]]
  name = "priority"
  field_type = "string"
  required = true
  display_name = "优先级"
  ui_widget = "select"
  filterable = true
  default = "medium"
  options = [
    { label = "紧急", value = "urgent" },
    { label = "高", value = "high" },
    { label = "中", value = "medium" },
    { label = "低", value = "low" }
  ]

  [[schema.entities.fields]]
  name = "status"
  field_type = "string"
  required = true
  display_name = "状态"
  ui_widget = "select"
  filterable = true
  default = "open"
  options = [
    { label = "待处理", value = "open" },
    { label = "处理中", value = "in_progress" },
    { label = "等待客户", value = "waiting_client" },
    { label = "已解决", value = "resolved" },
    { label = "已关闭", value = "closed" }
  ]

  [[schema.entities.fields]]
  name = "channel"
  field_type = "string"
  display_name = "来源渠道"
  ui_widget = "select"
  options = [
    { label = "电话", value = "phone" },
    { label = "微信", value = "wechat" },
    { label = "邮件", value = "email" },
    { label = "系统", value = "system" }
  ]

  [[schema.entities.fields]]
  name = "description"
  field_type = "string"
  display_name = "问题描述"
  ui_widget = "textarea"

  [[schema.entities.fields]]
  name = "resolution"
  field_type = "string"
  display_name = "解决方案"
  ui_widget = "textarea"

  [[schema.entities.fields]]
  name = "responded_at"
  field_type = "date_time"
  display_name = "首次响应时间"

  [[schema.entities.fields]]
  name = "resolved_at"
  field_type = "date_time"
  display_name = "解决时间"

  [[schema.entities.fields]]
  name = "closed_at"
  field_type = "date_time"
  display_name = "关闭时间"
```

#### 3.3.3 check_plan（巡检计划）

```toml
[[schema.entities]]
name = "check_plan"
display_name = "巡检计划"

  [[schema.entities.fields]]
  name = "contract_id"
  field_type = "uuid"
  required = true
  display_name = "维保合同"
  ui_widget = "entity_select"
  ref_entity = "service_contract"
  ref_label_field = "name"
  ref_search_fields = ["name"]

  [[schema.entities.fields]]
  name = "client_id"
  field_type = "uuid"
  display_name = "客户"
  ui_widget = "entity_select"
  ref_plugin = "erp-freelance"
  ref_entity = "client"
  ref_label_field = "name"
  ref_search_fields = ["name"]
  ref_fallback_label = "外部客户"

  [[schema.entities.fields]]
  name = "name"
  field_type = "string"
  required = true
  display_name = "计划名称"
  searchable = true

  [[schema.entities.fields]]
  name = "frequency"
  field_type = "string"
  required = true
  display_name = "巡检频率"
  ui_widget = "select"
  options = [
    { label = "每周", value = "weekly" },
    { label = "每两周", value = "biweekly" },
    { label = "每月", value = "monthly" },
    { label = "每季度", value = "quarterly" }
  ]

  [[schema.entities.fields]]
  name = "check_items"
  field_type = "json"
  display_name = "检查项"

  [[schema.entities.fields]]
  name = "status"
  field_type = "string"
  required = true
  display_name = "状态"
  ui_widget = "select"
  default = "active"
  options = [
    { label = "启用", value = "active" },
    { label = "停用", value = "inactive" }
  ]

  [[schema.entities.fields]]
  name = "next_check_date"
  field_type = "date"
  display_name = "下次巡检日期"

  [[schema.entities.fields]]
  name = "notes"
  field_type = "string"
  display_name = "备注"
  ui_widget = "textarea"

  [[schema.entities.relations]]
  entity = "check_record"
  foreign_key = "plan_id"
  on_delete = "cascade"
  name = "records"
  type = "one_to_many"
  display_field = "check_date"
```

#### 3.3.4 check_record（巡检记录）

```toml
[[schema.entities]]
name = "check_record"
display_name = "巡检记录"

  [[schema.entities.fields]]
  name = "plan_id"
  field_type = "uuid"
  required = true
  display_name = "巡检计划"
  ui_widget = "entity_select"
  ref_entity = "check_plan"
  ref_label_field = "name"
  ref_search_fields = ["name"]

  [[schema.entities.fields]]
  name = "contract_id"
  field_type = "uuid"
  display_name = "维保合同"
  ref_entity = "service_contract"

  [[schema.entities.fields]]
  name = "client_id"
  field_type = "uuid"
  display_name = "客户"
  ui_widget = "entity_select"
  ref_plugin = "erp-freelance"
  ref_entity = "client"
  ref_label_field = "name"
  ref_search_fields = ["name"]
  ref_fallback_label = "外部客户"

  [[schema.entities.fields]]
  name = "check_date"
  field_type = "date"
  required = true
  display_name = "巡检日期"

  [[schema.entities.fields]]
  name = "result"
  field_type = "string"
  required = true
  display_name = "结果"
  ui_widget = "select"
  filterable = true
  options = [
    { label = "正常", value = "normal" },
    { label = "有异常", value = "abnormal" }
  ]

  [[schema.entities.fields]]
  name = "items_data"
  field_type = "json"
  display_name = "检查项结果"

  [[schema.entities.fields]]
  name = "issues_found"
  field_type = "string"
  display_name = "发现的问题"
  ui_widget = "textarea"

  [[schema.entities.fields]]
  name = "actions_taken"
  field_type = "string"
  display_name = "采取措施"
  ui_widget = "textarea"

  [[schema.entities.fields]]
  name = "notes"
  field_type = "string"
  display_name = "备注"
  ui_widget = "textarea"
```

### 3.4 编号规则

```toml
[[numbering]]
entity = "service_contract"
field = "contract_number"
prefix = "SC"
format = "{PREFIX}-{YEAR}-{SEQ}"
seq_length = 4
```

### 3.5 页面设计（3 个页面）

#### 页面 1：运维概览（全局工作台的一部分）

作为全局工作台的一个区域展示：
- 活跃合同数 + 即将到期合同预警
- 本月工单统计（按状态饼图）
- SLA 达标率（百分比 + 趋势）
- 今日待巡检列表
- 最近 5 条工单

快捷操作：快速创建工单（3 字段：标题+客户+优先级）

#### 页面 2：合同管理

维保合同列表（支持按状态/客户/到期日筛选）+ 合同详情 Tab 页：
- Tab 1：合同信息
- Tab 2：关联工单
- Tab 3：巡检计划 + 巡检记录

```toml
[[ui.pages]]
type = "crud"
entity = "service_contract"
label = "合同管理"
icon = "file-text"
enable_search = true

[[ui.pages]]
type = "detail"
entity = "service_contract"
label = "合同详情"

  [[ui.pages.sections]]
  type = "fields"
  label = "合同信息"
  fields = ["name", "client_id", "service_scope", "sla_level", "sla_response_hours", "sla_resolve_hours", "status", "start_date", "end_date", "amount", "payment_terms", "notes"]

  [[ui.pages.sections]]
  type = "crud"
  label = "工单"
  entity = "ticket"
  filter_field = "contract_id"

  [[ui.pages.sections]]
  type = "crud"
  label = "巡检计划"
  entity = "check_plan"
  filter_field = "contract_id"

  [[ui.pages.sections]]
  type = "crud"
  label = "巡检记录"
  entity = "check_record"
  filter_field = "contract_id"
```

#### 页面 3：工单中心

Tab 1：工单列表（按状态分 Tab：待处理/处理中/已解决/已关闭）
Tab 2：巡检管理（巡检计划列表 + 巡检记录列表）

工单详情展示 SLA 倒计时（超时变红预警）

```toml
[[ui.pages]]
type = "tabs"
label = "工单中心"
icon = "tool"

  [[ui.pages.tabs]]
  label = "工单列表"
  type = "crud"
  entity = "ticket"
  enable_search = true

  [[ui.pages.tabs]]
  label = "巡检计划"
  type = "crud"
  entity = "check_plan"
  enable_search = true

  [[ui.pages.tabs]]
  label = "巡检记录"
  type = "crud"
  entity = "check_record"
  enable_search = true
```

### 3.6 SLA 自动计算规则

| SLA 等级 | 响应时间 | 解决时间 | 创建工单时自动带入 |
|----------|---------|---------|-------------------|
| 标准 | 8 小时 | 48 小时 | sla_response_hours=8, sla_resolve_hours=48 |
| 银牌 | 4 小时 | 24 小时 | sla_response_hours=4, sla_resolve_hours=24 |
| 金牌 | 2 小时 | 8 小时 | sla_response_hours=2, sla_resolve_hours=8 |

工单列表中实时显示 SLA 倒计时，超时变红预警。

---

## 4. 跨插件引用关系

```
itops.service_contract.client_id  → erp-freelance.client (ref_plugin + ref_fallback_label 降级)
itops.ticket.client_id            → erp-freelance.client
itops.check_plan.client_id        → erp-freelance.client
itops.check_record.client_id      → erp-freelance.client
```

降级行为（freelance 未安装时）：client_id 降级为文本输入字段，显示 ref_fallback_label "外部客户"。

---

## 5. inventory 插件扩展建议

在现有 inventory 插件的 product 实体增加字段：

```toml
  [[schema.entities.fields]]
  name = "product_type"
  field_type = "string"
  display_name = "产品类型"
  ui_widget = "select"
  filterable = true
  default = "physical"
  options = [
    { label = "实物", value = "physical" },
    { label = "虚拟", value = "virtual" },
    { label = "服务", value = "service" }
  ]
```

覆盖"计算机软硬件及辅助设备批发/零售"的经营范围。virtual/service 走零库存逻辑。

---

## 6. 全局工作台合并设计

freelance 和 itops 的仪表盘合并为一个全局工作台，布局如下：

```
┌─────────────────────────────────────────────────────┐
│  快捷操作栏：[计时] [记支出] [新报价] [新工单]       │
├──────────────────────┬──────────────────────────────┤
│  财务概览             │  紧急待办                     │
│  本月收入: ¥XX,XXX   │  逾期收款: 2 笔               │
│  本月支出: ¥X,XXX    │  今日到期任务: 3 项            │
│  利润: ¥XX,XXX       │  即将到期合同: 1 份(7天内)     │
│  应收: ¥XX,XXX       │  待处理工单: 4 条              │
├──────────────────────┼──────────────────────────────┤
│  活跃项目 (4)         │  运维概览                     │
│  [项目A ████░░ 60%]  │  活跃合同: 5 份               │
│  [项目B ██░░░░ 30%]  │  SLA 达标率: 96%              │
│  [项目C ██████ 100%] │  今日待巡检: 2 项              │
│                      │  最新工单: ...                 │
├──────────────────────┴──────────────────────────────┤
│  商机跟进提醒                                        │
│  张三(XX公司) - 网站开发 - 明天需跟进                 │
│  李四(YY公司) - AI方案 - 后天到期                     │
└─────────────────────────────────────────────────────┘
```

---

## 7. 实施优先级

```
P1: freelance 插件核心实体（client, opportunity, project, task, time_entry）
P2: freelance 插件财务实体（quote, quote_line, contract, invoice, expense）
P3: freelance 页面（全局工作台 + 客户管理 + 项目工作台 + 财务中心）
P4: itops 插件（全部实体 + 页面）
P5: inventory 扩展（product_type 字段）
P6: 全局工作台合并 + 快捷操作
```

---

## 8. 验证矩阵

| 验证场景 | 预期结果 |
|---------|---------|
| 单独安装 freelance | 全部功能正常，客户字段内部关联 |
| 单独安装 itops（不装 freelance） | client_id 降级为文本输入 |
| 同时安装 freelance + itops | client_id 自动关联 freelance.client，下拉选择客户 |
| 创建商机 → 创建报价 → 转合同 → 创建项目 | 全链路数据流通 |
| 项目中记录工时 → 生成发票 | 工时汇总可关联到发票 |
| 创建维保合同 → 设定巡检计划 → 执行巡检 → 创建工单 | 运维全流程 |
| SLA 超时预警 | 工单创建后超时自动标红 |
| 合同到期提醒 | 全局工作台显示即将到期合同 |
| 报价单号/合同编号/发票号自动生成 | QT-2026-0001 / CT-2026-0001 / INV-2026-0001 |

---

## 9. 讨论溯源

本文档基于 2026-04-19 的无主题发散式互动探讨产出，经过多专家头脑风暴审查（UX 专家、技术架构专家、业务顾问），采纳了以下关键建议：

- 新增 contract 实体（B2B 必要环节）
- 页面从 10 个压缩到 7 个（合并仪表盘+整合 tab）
- project 增加 business_type/deliverable_type 枚举覆盖全部经营范围
- 全局工作台 + 快捷操作（瑞士军刀原则）
- itops client_id 使用 ref_plugin + ref_fallback_label 实现可选跨插件引用
- inventory 扩展 product_type 支持软硬件销售

Spec 审查修正记录：
- C1: options 改为 `{ label, value }` 对象数组
- C2: `default_value` 改为 `default`
- C3: `generated = true` 改为 `[[numbering]]` 段
- C4: 跨插件引用改用 `ref_plugin` + `ref_label_field`
- C5: `datetime` 改为 `date_time`
- C6: `text` 改为 `string` + `ui_widget = "textarea"`
- I2: `number` 改为 `decimal` / `integer`
- I5: uuid 字段移除 `filterable`，改用 `ui_widget = "entity_select"`