feat: sd_features功能/需求表(models+appcodes) + SDLC概念→能力+skill全景映射文档
This commit is contained in:
ymq
parent
d8bfbd8ed4
commit
7ff03afbc5
321
docs/sdlc-concept-capability-map.md
Normal file
321
docs/sdlc-concept-capability-map.md
Normal file
@ -0,0 +1,321 @@
|
||||
# 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 | ❌ 缺能力+skill |
|
||||
| 2 | 迭代 | iteration | sd_iterations | status | planning / in_progress / completed / cancelled | ❌ 缺能力+skill |
|
||||
| 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 | ❌ 缺能力+skill |
|
||||
| 6 | 测试计划 | test-plan | sd_test_plans | status | draft / approved / executing / completed | ❌ 缺能力+skill |
|
||||
| 7 | 测试用例 | test-case | sd_test_cases | status | pending / pass / fail / blocked / skipped | ❌ 缺能力+skill |
|
||||
| 8 | Bug | bug | sd_bugs | status | open / confirmed / fixing / fixed / verified / closed / rejected | ⚠️ 仅 add_bug 一个工具 |
|
||||
| 9 | 问题 | problem | pipeline_agent_questions | status | pending / answered | ✅ 已固化 |
|
||||
| 10 | 部署环境 | deploy-env | sd_deploy_envs | status | configured / verified / failed | ❌ 缺能力+skill |
|
||||
|
||||
### 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：任务、问题（基准模式）
|
||||
⚠️ 已有工具但无状态机 skill：仓库(add_repo/list_repos/clone_repo)、Bug(仅 add_bug)
|
||||
✅ 横切已实现：记忆、审计、技能提议、角色
|
||||
❌ 完全缺失能力+skill：项目、迭代、功能(无表)、交付件、测试计划、测试用例、部署环境
|
||||
```
|
||||
|
||||
实施顺序（由「被依赖最多」往下，避免返工）：
|
||||
|
||||
```
|
||||
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]
|
||||
---
|
||||
```
|
||||
@ -88,6 +88,20 @@
|
||||
{"k": "configured", "v": "已配置"},
|
||||
{"k": "verified", "v": "已验证"},
|
||||
{"k": "failed", "v": "验证失败"}
|
||||
]},
|
||||
{"parentid": "sd_feature_type", "parentname": "功能类型", "items": [
|
||||
{"k": "new_feature", "v": "新功能"},
|
||||
{"k": "enhancement", "v": "功能增强"},
|
||||
{"k": "bugfix", "v": "Bug修复"},
|
||||
{"k": "refactor", "v": "重构"}
|
||||
]},
|
||||
{"parentid": "sd_feature_status", "parentname": "功能状态", "items": [
|
||||
{"k": "proposed", "v": "已提出"},
|
||||
{"k": "approved", "v": "已批准"},
|
||||
{"k": "in_progress", "v": "开发中"},
|
||||
{"k": "delivered", "v": "已交付"},
|
||||
{"k": "verified", "v": "已验证"},
|
||||
{"k": "rejected", "v": "已驳回"}
|
||||
]}
|
||||
]
|
||||
}
|
||||
|
||||
37
models/sd_features.json
Normal file
37
models/sd_features.json
Normal file
@ -0,0 +1,37 @@
|
||||
{
|
||||
"summary": [
|
||||
{
|
||||
"name": "sd_features",
|
||||
"title": "功能/需求表",
|
||||
"primary": ["id"],
|
||||
"catelog": "entity"
|
||||
}
|
||||
],
|
||||
"fields": [
|
||||
{"name": "id", "title": "主键ID", "type": "str", "length": 32, "nullable": "no"},
|
||||
{"name": "project_id", "title": "项目ID", "type": "str", "length": 32, "nullable": "no"},
|
||||
{"name": "iteration_id", "title": "迭代ID", "type": "str", "length": 32},
|
||||
{"name": "feature_name", "title": "功能名称", "type": "str", "length": 200, "nullable": "no"},
|
||||
{"name": "description", "title": "功能描述", "type": "text"},
|
||||
{"name": "feature_type", "title": "功能类型", "type": "str", "length": 20, "nullable": "no", "default": "'new_feature'"},
|
||||
{"name": "priority", "title": "优先级", "type": "str", "length": 10, "nullable": "no", "default": "'P2'"},
|
||||
{"name": "status", "title": "功能状态", "type": "str", "length": 20, "nullable": "no", "default": "'proposed'"},
|
||||
{"name": "acceptance_criteria", "title": "验收标准", "type": "text"},
|
||||
{"name": "task_id", "title": "关联Pipeline任务ID", "type": "str", "length": 32},
|
||||
{"name": "created_by", "title": "创建人", "type": "str", "length": 32},
|
||||
{"name": "created_at", "title": "创建时间", "type": "timestamp", "nullable": "no"},
|
||||
{"name": "updated_at", "title": "更新时间", "type": "timestamp"}
|
||||
],
|
||||
"indexes": [
|
||||
{"name": "idx_sd_features_project", "idxtype": "index", "idxfields": ["project_id"]},
|
||||
{"name": "idx_sd_features_iteration", "idxtype": "index", "idxfields": ["iteration_id"]},
|
||||
{"name": "idx_sd_features_status", "idxtype": "index", "idxfields": ["status"]}
|
||||
],
|
||||
"codes": [
|
||||
{"field": "project_id", "table": "sd_projects", "valuefield": "id", "textfield": "name"},
|
||||
{"field": "iteration_id", "table": "sd_iterations", "valuefield": "id", "textfield": "iteration_name"},
|
||||
{"field": "feature_type", "table": "appcodes_kv", "valuefield": "k", "textfield": "v", "cond": "parentid='sd_feature_type'"},
|
||||
{"field": "priority", "table": "appcodes_kv", "valuefield": "k", "textfield": "v", "cond": "parentid='sd_priority'"},
|
||||
{"field": "status", "table": "appcodes_kv", "valuefield": "k", "textfield": "v", "cond": "parentid='sd_feature_status'"}
|
||||
]
|
||||
}
|
||||
Loading…
x
Reference in New Issue
Block a user