# 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）

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

定位：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）

```yaml
---
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

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