pipeline-sdlc/docs/sdlc-concept-capability-map.md

SDLC 概念 → 能力 + skill 全景映射

本文档回答一个问题：开发产线里每一个软件工程概念，如何用「能力（固化工具）+ skill（规范）」覆盖。 元模式来自已固化的「任务 / 问题」两个概念，其余概念照此扩展，避免每个概念一套野路子。

---

一、元模式（六条铁律，所有概念统一遵守）

任务（task_capability.py + task skill）和问题（communication.py + team-communication skill） 已经固化出下面的不变量，新概念一律照抄，不得发明新范式：

1. 状态存表，规则存 skill，迁移靠 LLM 决策 + 工具 CAS 原子校验
   • 工具只做 UPDATE ... WHERE state=from AND <scope>=... 的 CAS，不校验合法性；
   • 合法性（能走哪条边、谁能操作）由 LLM 读 skill 判断。
2. 归属用显式列，不靠 status 反推（问题用 current_handler_role + current_handler_agentid）。
3. 流转路径/规则是 skill 知识，不存快照——改 skill 后历史数据不残留旧路径。
4. 每次迁移写审计：record_audit(tenant_id, entity, entity_id, action, from_state, to_state, who, agent_id, detail, sor)，append-only，微秒时间戳。
5. 角色规范名：agent 角色 agent.{role}（无点自动补前缀），人角色 {orgtype}.{role}（如 owner.superuser）。
6. skill frontmatter 带 capability + tools 字段，声明配套能力模块与工具清单；项目可用同名 skill 覆盖（六级 scope：global→org→pipeline(common)→role→project→user）。

能力模块统一骨架（照抄 task_capability.py）

"""<概念>能力 — <表> 的状态机语义化迁移（通用、产线无关）。

定位：storage/CRUD 是数据层；本模块是状态机语义化操作层，每个迁移 CAS 原子 + 租户隔离 + 审计。
状态机/流转规则在 <concept> skill 里（LLM 读 skill 判断合法性）；本模块只固化操作原语。
"""
import logging
from sqlor.dbpools import DBPools
from appPublic.uniqueID import getID
from .audit import record_audit

DBNAME = "pipeline"

S_XXX = "..."   # 状态常量

def _get_db():
    db = DBPools()
    if not db.databases:
        from appPublic.jsonConfig import getConfig
        config = getConfig()
        if config.databases:
            db.databases = config.databases
    return db, DBNAME

def _normalize_role(role):
    role = (role or "").strip()
    if not role:
        return ""
    if "." in role:
        return role
    return f"agent.{role}"

async def _transition(entity_id, scope_col, scope_val, from_state, to_state, action,
                      table, who=None, agent_id=None, detail=None):
    """CAS 状态迁移 + 审计。返回 (ok, message)。"""
    ...
    # UPDATE {table} SET status={to}, updated_at=NOW() WHERE id={id} AND {scope_col}={scope_val} AND status={from}
    # 校验落库后实际状态 == to，否则 "状态迁移失败(CAS)"
    # await record_audit(scope_val, table, entity_id, action, from_state, to_state, who, agent_id, detail, sor)

skill 统一模板（照抄 task/SKILL.md）

---
name: <concept>
description: SDLC 产线默认 <概念> 状态机规范——定义状态、合法流转、角色→操作权限、门禁、人拍板点。项目可同名覆盖。触发：<何时加载>。
capability: <concept>_capability
tools: [<工具1>, <工具2>, ...]
---
# <概念> 状态机规范（SDLC 产线默认）

## 一、核心模型（状态存表，规则在本 skill，工具只 CAS，每次迁移写审计）
## 二、状态枚举表
## 三、合法流转图
## 四、角色 → 操作权限（业务级 RBAC）
## 五、门禁
## 六、人拍板点（human gate，走问题冒泡到 owner.superuser）
## 七、配套能力工具清单
## 八、分层覆盖（项目同名 skill 覆盖）

---

二、概念全景抽取（三类）

A. 状态机概念（有生命周期 → 能力 + skill，共 10 个）

#	概念	skill 名	表	状态字段	状态枚举（真实 appcodes）	现状
1	项目	project	sd_projects	status	draft / active / completed / archived	✅ 已固化
2	迭代	iteration	sd_iterations	status	planning / in_progress / completed / cancelled	✅ 已固化
3	功能/需求	feature	sd_features	status	proposed / approved / in_progress / delivered / verified / rejected	✅ 已固化
4	任务	task	pipeline_tasks	state	submitted / running / review / approved / completed / waiting / failed	✅ 已固化
5	交付件	deliverable	pipeline_deliverables	review_status	pending / approved / rejected	✅ 已固化
6	测试计划	test-plan	sd_test_plans	status	draft / approved / executing / completed	✅ 已固化
7	测试用例	test-case	sd_test_cases	status	pending / pass / fail / blocked / skipped	✅ 已固化
8	Bug	bug	sd_bugs	status	open / confirmed / fixing / fixed / verified / closed / rejected	✅ 已固化
9	问题	problem	pipeline_agent_questions	status	pending / answered	✅ 已固化
10	部署环境	deploy-env	sd_deploy_envs	status	configured / verified / failed	✅ 已固化

B. 资源/配置概念（纯 CRUD，无生命周期 → CRUD + 简单工具，不做状态机 skill）

概念	表	说明
仓库 repository	sd_project_repos	无状态字段。add_repo / list_repos / clone_repo 已存在 ✅

C. 横切/基础设施概念（已实现或无需业务 skill）

概念	实现	说明
会话 conversation	sd_conversations	append-only 记录，历史注入
记忆 memory	pipeline_user_memory + MemoryStore	分域（global/pipeline/project/user）
审计 audit	audit_log + audit.py	通用原语 record_audit
技能提议 skill-proposal	skill_proposals	pending→testing→approved→published
角色 role	RoleSpec + SDL_ROLES	规范在 team-communication + 各角色 system_prompt

---

三、逐概念映射（A 类，含工具签名草稿）

scope 约定：pipeline_tasks / pipeline_agent_questions 用 tenant_id=project_id（引擎层）； sd_* 业务表用各自的归属列（project_id / iteration_id / plan_id）做 CAS 范围校验。

1. 项目 project

能力  pipeline_service/project_capability.py（表 sd_projects，scope=org_id + id）
工具  create_project(name, project_type, description) → draft
      start_project(project_id)      draft → active
      complete_project(project_id)   active → completed
      archive_project(project_id)    completed → archived
      reopen_project(project_id)     archived → active
      list_projects(org_id)
skill project — 项目生命周期、归档/完成门禁、项目→迭代→功能的包含关系、pipeline_id 绑定规则

2. 迭代 iteration

能力  pipeline_service/iteration_capability.py（表 sd_iterations，scope=project_id）
工具  create_iteration(project_id, iteration_name, iteration_type) → planning
      start_iteration(iteration_id, project_id)    planning → in_progress
      complete_iteration(iteration_id, project_id) in_progress → completed
      cancel_iteration(iteration_id, project_id)   planning/in_progress → cancelled
      list_iterations(project_id)
skill iteration — 迭代准入/准出条件（测试计划 exit_criteria、Bug 清零门禁）

3. 功能 feature（✅ 已实现）

表    sd_features（待建，字段见下）
状态  proposed / approved / in_progress / delivered / verified / rejected
能力  pipeline_service/feature_capability.py（scope=project_id）
工具  propose_feature(project_id, feature_name, description, iteration_id?) → proposed
      approve_feature(feature_id, project_id)   proposed → approved
      reject_feature(feature_id, project_id, comment)  proposed/approved → rejected
      start_feature(feature_id, project_id)     approved → in_progress
      deliver_feature(feature_id, project_id)   in_progress → delivered
      verify_feature(feature_id, project_id)    delivered → verified
      reopen_feature(feature_id, project_id)    rejected/verified → proposed
      list_features(project_id, status?)
skill feature — 功能从需求拆解到验收闭环；迭代 scope 与用例/Bug 都挂 feature_id

4. 任务 task（✅ 已固化，基准参考）

能力  pipeline_service/task_capability.py
工具  claim_task / submit_task / approve_task / reject_task / complete_task
      mark_failed / retry_task / suspend_task / revive_task / set_task_state
skill task

5. 交付件 deliverable

能力  pipeline_service/deliverable_capability.py（表 pipeline_deliverables，scope=project_id）
工具  submit_deliverable(...)  → review_status=pending
      approve_deliverable(deliverable_id, project_id)  pending → approved
      reject_deliverable(deliverable_id, project_id, comment)  pending → rejected
      list_deliverables(project_id, task_id?)
skill deliverable — 交付件类型(code/doc/config)、评审标准、与任务/仓库的关联规则
说明  现状 review_status 由 PM review_complete 顺带改，散在 agent_loop 里，应收敛到本能力

6. 测试计划 test-plan

能力  pipeline_service/test_plan_capability.py（表 sd_test_plans，scope=iteration_id）
工具  create_test_plan(iteration_id, plan_name, plan_type) → draft
      approve_plan(plan_id)   draft → approved
      start_plan(plan_id)     approved → executing
      complete_plan(plan_id)  executing → completed
      list_plans(iteration_id)
skill test-plan — 准入/准出条件（entry_criteria/exit_criteria）如何 gate 迭代完成

7. 测试用例 test-case

能力  pipeline_service/test_case_capability.py（表 sd_test_cases，scope=plan_id）
工具  create_case(plan_id, case_name, case_type) → pending
      pass_case(case_id)   pending/fail → pass
      fail_case(case_id)   pending/pass → fail（触发联动建 Bug 的规范在 skill）
      skip_case(case_id)   pending → skipped
      block_case(case_id)  pending → blocked
      list_cases(plan_id)
skill test-case — 用例执行规范、失败用例如何联动建 Bug（case_id 关联 sd_bugs.case_id）

8. Bug

能力  pipeline_service/bug_capability.py（表 sd_bugs，scope=iteration_id）
工具  report_bug(...)  → open
      confirm_bug(bug_id)  open → confirmed
      start_fix(bug_id)    confirmed → fixing
      fix_bug(bug_id, fix_description, fix_commit)  fixing → fixed
      verify_bug(bug_id)   fixed → verified
      close_bug(bug_id)    verified → closed
      reject_bug(bug_id)   open/confirmed → rejected
      reopen_bug(bug_id)   closed/rejected → open
      list_bugs(iteration_id)
skill bug — 严重度/优先级规则、关闭前「迭代 Bug 清零」门禁、reporter_type(human/agent) 语义
说明  现状只有 sdlc_ability 里的 add_bug，其余流转靠 CRUD 手改，应收敛

9. 问题 problem（✅ 已固化）

能力  pipeline_service/communication.py
工具  raise_problem / resolve_problem / escalate_problem / list_problems_for
skill team-communication

10. 部署环境 deploy-env

能力  pipeline_service/deploy_capability.py（表 sd_deploy_envs，scope=project_id）
工具  configure_env(project_id, env_type, host, ...)  → configured
      verify_env(env_id)     configured → verified / failed
      list_envs(project_id)
skill deploy — 环境类型(test/staging/production)、验证标准、发布门禁、回滚路径
说明  发布本体（部署动作）复用 task 状态机（deploy 角色）；本能力管「环境」这个可追踪实体

---

四、GAP 结论与实施顺序

✅ 已固化能力+skill（10 个状态机概念全齐）：任务、问题、功能、项目、迭代、交付件、测试计划、测试用例、Bug、部署环境
✅ 已有工具但无状态机 skill（资源概念）：仓库(add_repo/list_repos/clone_repo)
✅ 横切已实现：记忆、审计、技能提议、角色

实施顺序（由「被依赖最多」往下，避免返工）：

1. feature（新建 sd_features 表）—— 需求/功能的可追踪根，迭代 scope、用例、Bug 都要挂它
2. project + iteration —— 规划层容器，feature/task/bug 都挂 project_id/iteration_id
3. deliverable —— 任务产出物，评审收敛
4. bug + test-case + test-plan —— 质量闭环（用例失败→建 Bug→修复→回归）
5. deploy —— 收尾，复用 task 状态机

---

五、附录：feature 概念详细设计（第一批实现）

sd_features 表（models/sd_features.json 草稿）

字段	类型	说明
id	str 32, PK	主键
project_id	str 32, not null	所属项目
iteration_id	str 32	所属迭代（规划阶段可空）
feature_name	str 200, not null	功能名称
description	text	功能描述
feature_type	str 20, default 'new_feature'	功能类型（new_feature/enhancement/bugfix）
priority	str 10, default 'P2'	优先级（P0/P1/P2/P3）
status	str 20, not null, default 'proposed'	功能状态
acceptance_criteria	text	验收标准
task_id	str 32	关联 pipeline 任务ID
created_by	str 32	创建人
created_at / updated_at	timestamp	时间戳

索引：idx_sd_features_project(project_id)、idx_sd_features_iteration(iteration_id)、idx_sd_features_status(status)

sd_feature_status appcodes（需新增）

proposed 已提出 / approved 已批准 / in_progress 开发中 / delivered 已交付 / verified 已验证 / rejected 已驳回

feature 状态机流转图

proposed ──approve──▶ approved ──start──▶ in_progress ──deliver──▶ delivered ──verify──▶ verified
    │                    │                                                  ▲
    │ reject             │ reject                                           │
    ▼                    ▼                                                  │
rejected ◀───────────────┴────────── reopen ───────────────────────────────┘

feature skill frontmatter

---
name: feature
description: SDLC 产线默认功能/需求状态机规范——定义功能状态、合法流转、角色→操作权限、门禁、验收标准。项目可同名覆盖。触发：提出/审批/开发/交付/验证功能，或用户提到新功能、需求拆解。
capability: feature_capability
tools: [propose_feature, approve_feature, reject_feature, start_feature, deliver_feature, verify_feature, reopen_feature, list_features]
---