# skillhub 领域模型与数据模型 ## 0. 用户标识约束 - 用户身份主键全链路统一为 `string`。 - 本约束覆盖 `user_id`、`owner_id`、`created_by`、`updated_by`、`published_by`、`reviewed_by`、`actor_user_id` 及所有等价语义字段。 - 历史文档里写成 `bigint` / `BIGINT` 的用户关联字段均应按字符串重新解释;这些旧类型描述不再作为实现依据。 - 若未来数据库为了索引或存储效率引入内部 surrogate key,也只能作为内部实现细节,不能替代字符串 `userId` 成为认证、授权、审计和 API 契约的主键。 ## 3.1 核心实体 ### namespace | 字段 | 类型 | 说明 | |------|------|------| | id | bigint | 主键 | | slug | varchar(64) | URL 友好标识 | | display_name | varchar(128) | 展示名 | | type | enum | `GLOBAL` / `CATALOG` / `TEAM` | | description | text | 描述 | | avatar_url | varchar(512) | 头像 | | status | enum | `ACTIVE` / `FROZEN` / `ARCHIVED` | | created_by | varchar(128) | 创建人 | | created_at | datetime | | | updated_at | datetime | | - `GLOBAL` 类型全局唯一(只有一个 `@global`),由平台管理员管理 - `CATALOG` 为系统管理的来源目录;首个 `@github` 通过迁移创建,普通用户不能修改或删除 - `@github` 迁移同时创建不可登录的系统 actor `github-sync-publisher`;若 namespace slug 或 actor ID 已被占用,迁移明确失败而不接管已有记录 - `TEAM` 类型对应部门/团队,可创建多个 - 技能完整寻址:`@{namespace_slug}/{skill_slug}` - slug 唯一约束:`slug` - slug 格式校验:`[a-z0-9]([a-z0-9-]*[a-z0-9])?`,长度 2-64,且不得包含连续两个以上的连字符 `--`(为兼容层坐标映射保留) - slug 保留词列表(用户创建 namespace 时不可使用):`admin`, `api`, `dashboard`, `search`, `auth`, `me`, `global`, `github`, `system`, `static`, `assets`, `health`;`github` 仅在 namespace 创建入口保留,不禁止同名 Skill - 系统内置 namespace(`@global`)在数据库初始化时由 Flyway 脚本预置,绕过 slug 校验规则。保留词校验仅作用于用户创建 namespace 的接口 - 状态语义: - `ACTIVE`:正常使用 - `FROZEN`:冻结,只读不可发布新版本,已有技能仍可浏览/下载 - `ARCHIVED`:归档,对外不可见 ### namespace_member | 字段 | 类型 | 说明 | |------|------|------| | id | bigint | | | namespace_id | bigint | | | user_id | varchar(128) | | | role | enum | `OWNER` / `ADMIN` / `MEMBER` | | created_at | datetime | | | updated_at | datetime | | - `OWNER`:命名空间创建者,可转让 - `ADMIN`:可审核该空间内的技能发布、管理成员 - `MEMBER`:可在该空间内发布技能(提交审核) - 唯一约束:`(namespace_id, user_id)`,一个用户在一个空间只有一个角色 ### skill | 字段 | 类型 | 说明 | |------|------|------| | id | bigint | | | namespace_id | bigint | 所属命名空间 | | slug | varchar(128) | URL 友好标识 | | display_name | varchar(256) | | | summary | varchar(512) | | | owner_id | varchar(128) | 当前技能所有者;不等同于命名空间 OWNER,当前无独立技能转让入口 | | source_skill_id | bigint | 派生来源(团队技能提升到全局时记录原 skill ID),nullable | | visibility | enum | `PUBLIC` / `NAMESPACE_ONLY` / `PRIVATE` | | status | enum | `ACTIVE` / `ARCHIVED` | | latest_version_id | bigint | 内部生命周期指针;PRIVATE 上传可指向未发布版本。对外最新发布版本由 `publishedVersion` 解析,不直接以此字段授权 | | download_count | bigint | | | star_count | int | | | rating_avg | decimal(3,2) | 平均评分 | | rating_count | int | 评分人数 | | created_by | varchar(128) | | | created_at | datetime | | | updated_by | varchar(128) | | | updated_at | datetime | | - 唯一约束:`(namespace_id, slug, owner_id)`;面向公众的同名冲突还须按已发布记录检查不同 owner,避免地址解析歧义 - `status` 表示 skill 容器生命周期,不再承载“隐藏”语义。隐藏是独立的治理覆盖层,由 `hidden` / `hidden_at` / `hidden_by` 表达 - 容器可见性判定以 `VisibilityChecker` 为准;传入 `SUPER_ADMIN` 平台角色时该检查短路放行,但不表示所有调用方都传入角色,也不绕过调用方的其他限制。普通调用规则如下: - 若 `hidden=true`:仅 skill owner 或该 namespace 的 `ADMIN` / `OWNER` 可读 - 若 `latest_version_id is null`:仅 skill owner 可读;即使 `visibility=PUBLIC` 也不会对外公开 - `PUBLIC`:任意人可读 skill 容器与已发布版本 - `NAMESPACE_ONLY`:该 namespace 任意成员及当前技能 owner 可读;owner 被移出 TEAM 空间后保留自己内容的只读访问 - `PRIVATE`:仅 skill owner 或该 namespace 的 `ADMIN` / `OWNER` 可读,普通 `MEMBER` 不可读 - `owner_id` 表示当前技能所有者,空间角色与技能所有权分别参与授权: - 正常账号且仍为 TEAM 空间成员的 owner 按既有规则维护自己的 skill。 - 被移出 TEAM 空间但仍是当前 owner 时,可以查看、下载自己的内容,不能凭 owner 身份继续写入;不自动转移技能或所有权。 - 账号正常、重新加入且仍为 owner 时恢复正常维护权限;停用账号继续服从认证层限制。 - namespace ADMIN/OWNER 与平台角色的既有独立治理、审核权限保持不变,不因本条成为内容作者,也不新增全员覆盖能力。 - 历史提交人不是当前 owner 时,按普通可见性与已有角色判断访问,不获得永久私有内容读取权。 - `rating_avg` / `rating_count` 冗余字段,避免每次查询聚合 - `slug`:面向用户的 URL 标识,来自 SKILL.md 的 `name` 字段,首次发布后不可变更。slug 格式校验规则与 namespace slug 相同:`[a-z0-9]([a-z0-9-]*[a-z0-9])?`,同样适用保留词限制,且不得包含连续两个以上的连字符 `--`(为兼容层坐标映射保留)。全局空间(`@global`)下的 skill slug 额外禁止包含 `--`,以避免与兼容层 canonical slug 产生歧义 - `source_skill_id`:仅在"团队技能提升到全局"场景下填充,记录原始团队空间的 skill ID,用于追溯来源 - 提升关系的唯一事实来源是 `promotion_request` 表。当前有效全局目标由 `request_kind='INITIAL' AND status='APPROVED' AND target_skill_id IS NOT NULL` 的首次提升记录确定;后续更新记录指向同一目标,撤销时解除目标引用并保留快照。 ### skill_version | 字段 | 类型 | 说明 | |------|------|------| | id | bigint | | | skill_id | bigint | | | version | varchar(32) | 版本标识;可来自 SKILL.md 或系统生成,不按字符串大小判断“最新” | | version_sort | bigint | 排序用数值 | | changelog | text | | | manifest_json | json | 文件清单 | | parsed_metadata_json | json | SKILL.md frontmatter 解析结果 | | status | enum | `DRAFT` / `SCANNING` / `SCAN_FAILED` / `UPLOADED` / `PENDING_REVIEW` / `PUBLISHED` / `REJECTED` / `YANKED` | | reject_reason | varchar(512) | 拒绝原因 | | published_by | varchar(128) | | | published_at | datetime | | | created_at | datetime | | - `status` 表示 version 发布生命周期,和 skill 容器状态、review task 状态分离 - 完整状态定义、上传/扫描/审核转换和治理操作以 [生命周期文档](./14-skill-lifecycle.md) 为准;`DRAFT` 保留为旧数据兼容状态,当前撤回审核回到 `UPLOADED`。 - 上传结果取决于请求可见性、扫描配置与发布权限,不能统一描述为“普通用户直接待审”或“超管发布即代表可安装”。 - 唯一约束:`(skill_id, version)` 防止重复版本记录;已发布版本不可原地覆盖。允许删除的未发布版本删除后可复用版本号,但不能删除技能的最后一个版本。 - `YANKED` 表示已发布后撤回,版本记录和版本号仍保留,不可下载。 - 版本列表、详情/文件预览、下载与公共分发是不同权限路径:管理者能预览的版本不一定能下载,`UPLOADED` / `PENDING_REVIEW` 的受限下载也不代表对外发布。具体边界见 [生命周期文档的对外协议与权限章节](./14-skill-lifecycle.md)。 - 审核详情使用独立 review 读路径,可查看审核快照;不能由普通详情的访问规则推导审核权限。 ### skill_file | 字段 | 类型 | 说明 | |------|------|------| | id | bigint | | | skill_version_id | bigint | | | file_path | varchar(512) | | | content_type | varchar(128) | | | size_bytes | bigint | | | sha256 | varchar(64) | | | object_key | varchar(512) | | | is_entry_file | boolean | | | created_at | datetime | | ### skill_tag | 字段 | 类型 | 说明 | |------|------|------| | id | bigint | | | skill_id | bigint | | | tag_name | varchar(64) | | | target_version_id | bigint | | | created_by | varchar(128) | | | created_at | datetime | | | updated_by | varchar(128) | | | updated_at | datetime | | - `latest` 是系统保留标签,不允许 API 手动移动。当前标签列表在读取授权后按原始 `latest_version_id` 动态合成,不检查目标版本状态,因此 PRIVATE 上传的未发布指针也可能反映到授权用户的列表中;标签存在不等于可公开分发,下载仍需通过授权、版本状态与就绪检查 - 自定义标签(如 `beta`、`stable-2026q1`)允许人工创建和移动 - 唯一约束:`(skill_id, tag_name)` - `target_version_id` 必须指向 `status = PUBLISHED` 的版本,应用层校验 ### review_task | 字段 | 类型 | 说明 | |------|------|------| | id | bigint | | | skill_version_id | bigint | 关联的版本 | | namespace_id | bigint | 所属空间(决定谁能审核) | | status | enum | `PENDING` / `APPROVED` / `REJECTED` | | version | int | 乐观锁版本号,默认 1 | | submitted_by | varchar(128) | 提交人 | | reviewed_by | varchar(128) | 审核人 | | review_comment | text | 审核意见 | | submitted_at | datetime | | | reviewed_at | datetime | | - 仅用于普通发布审核,"提升到全局"使用独立的 `promotion_request` 表 - `version` 字段用于乐观锁,防止多 Pod 并发审核 - 业务约束:同一 `skill_version_id` 在 `status=PENDING` 时只能存在一条记录,重复提交返回 409 Conflict。撤回时删除 `PENDING` review_task,并将 `skill_version` 回退到 `UPLOADED` - PostgreSQL 并发约束落地:通过唯一索引 `(skill_version_id)` + 软删除标记实现。`review_task` 表增加 `deleted` 字段(bigint, 默认 0),唯一索引改为 `(skill_version_id, deleted)`。撤回时将 `deleted` 设为 `id`(非零值),新提交时 `deleted=0`,利用唯一索引防止并发重复提交。或者采用更简单的方案:撤回时物理删除 review_task 记录,依赖 `INSERT` 的唯一约束 `(skill_version_id)` 防并发。PostgreSQL 还支持 partial unique index 方案:`CREATE UNIQUE INDEX ON review_task (skill_version_id) WHERE status = 'PENDING'`,更优雅地实现"PENDING 状态唯一"约束 ### promotion_request | 字段 | 类型 | 说明 | |------|------|------| | id | bigint | | | source_skill_id | bigint | 来源团队 skill | | source_version_id | bigint | 申请提升的版本 | | target_namespace_id | bigint | 目标全局 namespace | | target_skill_id | bigint | 审批通过后生成的全局 skill ID,nullable | | request_kind | varchar(16) | `INITIAL` / `UPDATE`;存量记录迁移为 `INITIAL` | | target_version_id | bigint | 审批形成的全局版本 ID 快照,允许目标撤销后保留 | | target_skill_id_snapshot | bigint | 撤销后仍保留原全局 skill ID | | target_version_id_snapshot | bigint | 撤销后保留结果版本 ID | | revoked_at / revoked_by | datetime / varchar(128) | 撤销生效时间和操作者 | | status | enum | `PENDING` / `APPROVED` / `REJECTED` | | version | int | 乐观锁版本号,默认 1 | | submitted_by | varchar(128) | 提交人 | | reviewed_by | varchar(128) | 审核人 | | review_comment | text | 审核意见 | | submitted_at | datetime | | | reviewed_at | datetime | | - 完整表达"哪个团队 skill 的哪一版被申请提升到哪个全局空间"。首次提升新建目标 skill;后续 UPDATE 在同一目标下增加不可变版本,两次发布审核分开进行。 - 审批通过后填充 `target_skill_id`,指向当前关联的全局 skill;撤销后清空该外键并保留快照和提升历史。 - `promotion_request` 是提升关系的唯一事实来源,skill 表不再冗余 `promoted_to_skill_id` - 业务约束:同一来源 skill 同时最多有一条 `PENDING` 提升申请;同一来源同时最多有一条有效 `INITIAL` 提升关系。全局目标有任何同号版本时,不允许 UPDATE 审批覆盖;异号审批按实际发布时间更新 latest。 - PostgreSQL 以 `source_skill_id WHERE status='PENDING'` 和 `source_skill_id WHERE request_kind='INITIAL' AND status='APPROVED' AND target_skill_id IS NOT NULL` 两个部分唯一索引防止并发重复。 ### promotion_revocation_request - 来源技能所有者或团队管理员可提交撤销,平台管理员审核;平台管理员直接撤销也留存申请和审计。 - 审核通过时删除全局派生 skill 及其版本、统计和公开入口,不把数据迁回团队 skill;团队原件和共用的文件对象保留。 - 记录保留原始来源/目标 ID 与坐标、提交人、审核人、理由、状态及时间。目标全局 skill 物理删除后,这些字段仍供管理员审计。 - 撤销释放旧全局坐标;重新提升须重新申请、审核,并再次检查同名冲突。此前已下载的客户端文件无法收回。 ### skill_star | 字段 | 类型 | 说明 | |------|------|------| | id | bigint | | | skill_id | bigint | | | user_id | varchar(128) | | | created_at | datetime | | 唯一约束:`(skill_id, user_id)` ### skill_rating | 字段 | 类型 | 说明 | |------|------|------| | id | bigint | | | skill_id | bigint | | | user_id | varchar(128) | | | score | tinyint | 1-5 | | review_text | varchar(2000) | 可选文字评价;空值表示仅评分 | | review_status | enum | `VISIBLE` / `HIDDEN`,隐藏不影响评分聚合 | | moderated_by | varchar(128) | 最近一次管理操作人,nullable | | moderated_at | datetime | 最近一次管理时间,nullable | | moderation_reason | varchar(500) | 隐藏原因,nullable | | lock_version | bigint | 乐观锁版本;并发编辑或治理冲突返回 409 | | created_at | datetime | | | updated_at | datetime | | 唯一约束:`(skill_id, user_id)`,每人每技能一条,可修改。删除文字评价只清空 `review_text`,保留评分和既有治理状态;管理员隐藏评价时也保留评分,避免作者通过 清空后重新提交绕过治理,或治理动作改变聚合分数。 ### user_account | 字段 | 类型 | 说明 | |------|------|------| | id | bigint | | | display_name | varchar(128) | | | email | varchar(256) | | | avatar_url | varchar(512) | | | status | enum | `ACTIVE` / `PENDING` / `DISABLED` / `MERGED` | | merged_to_user_id | varchar(128) | 合并目标用户 ID,仅 MERGED 状态有值 | | system_account | boolean | 系统服务账号,禁止交互式 Web/OAuth 登录 | | created_at | datetime | | | updated_at | datetime | | - 状态语义: - `ACTIVE`:正常使用 - `PENDING`:等待管理员审批(AccessPolicy 返回 PENDING_APPROVAL 时创建) - `DISABLED`:管理员封禁,登录后拒绝所有操作,返回 403 - `MERGED`:已合并到其他账号,保留记录不物理删除;登录直接拒绝,不向调用方泄露合并目标 - 授权层在每次请求时检查用户状态,非 `ACTIVE` 用户拒绝所有写操作 - system account 可按独立 Token Policy 使用非交互凭证,但不能通过本地密码或外部 OAuth 建立普通用户 Session ### identity_binding | 字段 | 类型 | 说明 | |------|------|------| | id | bigint | | | user_id | varchar(128) | | | provider_code | varchar(64) | 如 `github` | | subject | varchar(256) | OAuth Provider 返回的唯一用户标识 | | login_name | varchar(128) | 如 GitHub login | | extra_json | json | 原始扩展字段 | | created_at | datetime | | | updated_at | datetime | | - 唯一约束:`(provider_code, subject)` - 一期只接入 GitHub OAuth,但表结构支持后续扩展多个 OAuth Provider ### api_token | 字段 | 类型 | 说明 | |------|------|------| | id | bigint | | | subject_type | varchar(32) | `USER`(一期)/ `SERVICE_ACCOUNT`(预留) | | subject_id | varchar(128) | 关联主体 ID(一期等同于 user_id) | | user_id | varchar(128) | 兼容字段,一期与 subject_id 相同 | | name | varchar(128) | Token 名称(必填),如"CI/CD"、"本地开发" | | token_prefix | varchar(16) | | | token_hash | varchar(64) | | | scope_json | json | | | expires_at | datetime | | | last_used_at | datetime | | | revoked_at | datetime | | | created_at | datetime | | ### audit_log | 字段 | 类型 | 说明 | |------|------|------| | id | bigint | | | actor_user_id | varchar(128) | | | action | varchar(64) | | | target_type | varchar(64) | | | target_id | bigint | | | request_id | varchar(64) | | | client_ip | varchar(64) | | | user_agent | varchar(512) | | | detail_json | json | | | created_at | datetime | | ## 3.2 RBAC 实体 一期即上线完整 RBAC,平台角色按最小权限拆分,避免所有治理能力压在单一超管角色上。 平台角色(一期内置,Flyway 预置): | 角色 code | 说明 | 典型权限 | |-----------|------|---------| | `SUPER_ADMIN` | 平台超管,拥有所有权限 | 全部 | | `SKILL_ADMIN` | 技能治理:全局空间审核、提升审核、隐藏/恢复、撤回已发布版本 | `review:approve`, `skill:manage`, `promotion:approve` | | `USER_ADMIN` | 用户治理:准入审批、封禁/解封、角色分配(不可分配 SUPER_ADMIN) | `user:manage`, `user:approve` | | `AUDITOR` | 审计只读:查看审计日志 | `audit:read` | - 命名空间权限仍由 `namespace_member.role`(OWNER / ADMIN / MEMBER)决定,不走 RBAC 表 - 一个用户可持有多个平台角色(多条 `user_role_binding`) - `SUPER_ADMIN` 隐含所有权限,代码中硬判定短路 ### role | 字段 | 类型 | 说明 | |------|------|------| | id | bigint | | | code | varchar(64) | `SUPER_ADMIN` / `SKILL_ADMIN` / `USER_ADMIN` / `AUDITOR` | | name | varchar(128) | 展示名 | | description | varchar(512) | | | is_system | boolean | 系统内置角色不可删除 | | created_at | datetime | | ### permission | 字段 | 类型 | 说明 | |------|------|------| | id | bigint | | | code | varchar(128) | 如 `skill:publish`, `review:approve`, `user:manage` | | name | varchar(128) | | | group_code | varchar(64) | 权限分组 | ### role_permission | 字段 | 类型 | 说明 | |------|------|------| | role_id | bigint | | | permission_id | bigint | | ### user_role_binding | 字段 | 类型 | 说明 | |------|------|------| | id | bigint | | | user_id | varchar(128) | | | role_id | bigint | | | created_at | datetime | | ## 3.3 搜索文档表 ### skill_search_document 一个 skill 对应一条搜索文档,内容取 `publishedVersion` 表示的“最新已发布版本”。内部 `latest_version_id` 可能在 PRIVATE 上传时指向未发布版本,不能不校验状态就用于公开搜索。 | 字段 | 类型 | 说明 | |------|------|------| | id | bigint | | | skill_id | bigint | 唯一,一 skill 一条 | | namespace_id | bigint | 用于空间过滤 | | owner_id | varchar(128) | 用于 PRIVATE 可见性判定 | | title | varchar(256) | | | summary | varchar(512) | | | keywords | varchar(512) | | | search_text | text | `displayName`、`slug`、`summary`,以及 frontmatter 中除 `name` / `description` / `version` 外的字段展开结果 | | visibility | enum | 冗余,避免搜索时 join | | status | enum | | | updated_at | datetime | | PostgreSQL Full-Text Index:在 `skill_search_document` 表增加 `search_vector tsvector` 列,通过触发器或 `GENERATED ALWAYS AS` 自动维护,建立 GIN 索引。 ## 3.4 幂等记录表 ### idempotency_record | 字段 | 类型 | 说明 | |------|------|------| | request_id | varchar(64) | 主键,客户端传入的 UUID v4 | | resource_type | varchar(64) | 如 `skill_version`, `api_token` | | resource_id | bigint | 业务操作产生的资源 ID | | status | enum | `PROCESSING` / `COMPLETED` / `FAILED` | | response_status_code | int | 原始响应状态码 | | created_at | datetime | | | expires_at | datetime | 过期时间(默认 24h) | - 流程:收到请求 → 插入 record(PROCESSING)→ 业务处理 → 更新为 COMPLETED + resource_id → 重复请求时查 record 返回已有结果 - Redis 做快速去重缓存(SETNX),PostgreSQL 做持久化兜底 - 定时任务清理过期记录 ## 3.5 关键索引设计 | 表 | 索引 | 用途 | |------|------|------| | namespace | `(slug)` UNIQUE | 唯一约束 | | skill | `(namespace_id, status)` | 命名空间内技能列表 | | skill | `(namespace_id, slug)` UNIQUE | 唯一约束 | | skill_version | `(skill_id, status)` | 版本列表 | | skill_version | `(skill_id, version)` UNIQUE | 唯一约束 | | skill_tag | `(skill_id, tag_name)` UNIQUE | 标签唯一约束 | | review_task | `(namespace_id, status)` | 审核列表 | | review_task | `(submitted_by, status)` | 我的提交 | | promotion_request | `(source_skill_id)` | 按来源 skill 查询 | | promotion_request | `(status)` | 待审核列表 | | idempotency_record | `(expires_at)` | 过期清理 | | audit_log | `(created_at)` | 审计查询 | | audit_log | `(actor_user_id, created_at)` | 用户操作历史 | | skill_star | `(user_id)` | 我的收藏 | | skill_star | `(skill_id)` | 技能收藏数 | | skill_rating | `(skill_id)` | 评分聚合 | | namespace_member | `(namespace_id, user_id)` UNIQUE | 成员唯一约束 | | namespace_member | `(user_id)` | 用户所属空间 | | identity_binding | `(provider_code, subject)` UNIQUE | 身份查找 | | api_token | `(token_hash)` | Token 校验 |