soul-yongping/.cursor/agent/管理端开发工程师/evolution/2026-03-12.md

管理端开发工程师 经验记录 - 2026-03-12

ContentPage TypeScript 严格类型修复

问题

soul-admin 构建时 ContentPage.tsx 出现多处 TS2322 类型错误：

1. 可选字段赋给必填字段：LinkTagItem 的 appId、pagePath 为可选（string | undefined），setNewLinkTag 期望 string
2. 接口缺字段：SectionListItem 无 isPinned，但 ranking API 返回该字段
3. API 映射类型：loadPersons 中 p.token、p.label、p.ckbApiKey 可能为 undefined，映射后 PersonItem.id 等需为 string
4. 可选参数传 setState：setEditingPersonKey(p.personId) 中 personId 可选，setter 期望 string | null

解决方案

场景	写法
可选字段 → 必填 string	t.appId ?? ''、t.pagePath ?? ''
接口补字段	在 SectionListItem 添加 isPinned?: boolean
API 映射兜底	id: p.token ?? p.personId ?? ''，label: p.label ?? ''，ckbApiKey: p.ckbApiKey ?? ''
可选 → setState(string|null)	setEditingPersonKey(p.personId ?? null)

规则提炼

• 从可选类型（T | undefined）赋给必填类型（T）时，用 ?? defaultValue 兜底
• 接口类型需与 API 返回字段对齐，缺字段时补 field?: Type
• useState<string | null> 的 setter 传参时，undefined 需显式转为 null

---

关联小程序与 @ 人物：密钥/token 设计

关联小程序

• 添加时生成 32 位 key，链接标签选择小程序时存 key（非 appId）
• 列表展示：名称、密钥、AppID、路径；编辑/删除用 key
• 链接标签下拉：选项显示 name + key，选中后 appId 字段存 key

@ 人物

• 添加时生成 32 位 token，PersonItem.id = token（RichEditor 插入用）
• 列表展示 token；编辑/删除用 personId（API 仍用 personId）
• 文章 @ 时 data-id 存 token