Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions COMMUNICATING.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,11 @@
| D-014 | 2026-09-07 | **决策日志 supersedes 机制**:确认/变更一律追加新行并注明 supersedes 旧 ID,历史行不改;废除「直接修改旧决策状态」的做法 | ✅ 已定(工程约定) | R-14;本文档维护规则 2 |
| D-015 | 2026-09-07 | **迁移工具锁定 golang-migrate**:SQL 成对文件 + Go 库嵌入测试 + `cmd/migrate`(down-all 带守卫);关闭 S-2 二选一遗留 | ✅ 已定(工程约定) | TECH_SPEC §3.2;ADR-0003 |
| D-016 | 2026-09-07 | **模型供应商选定阶跃星辰(StepFun)**:PO 直接确认;开放平台 API key 待提供(本机仅有已过期的桌面 Web 会话凭据,不可用于 API 调用);首次真实调用按方案 §6 预算 ≤6 次 | ✅ 已定(PO 确认) | supersedes D-007(豆包主+Qwen 备的暂定方案作废,历史行保留) |
| D-017 | 2026-09-07 | **比赛交付 deadline = 今日 24:00**(PO 确认);按方案 §8 时间盒,交付目标诚实降级为技术切片(Slice 1–3),不声称完整比赛 MVP;PRD P0 完成状态以交付声明为准 | ✅ 已定(PO 确认) | supersedes D-006 |
| D-018 | 2026-09-07 | **ADR-0002 评分与人审语义按草案生效**:WARN=0.5、NA 需理由排除分母、UNKNOWN 不计分压覆盖率、Reject 不转 PASS、全覆盖才出总分否则部分评估、S0/S1 独立清单 | ✅ 已定(PO 确认) | supersedes ADR-0002「提议」状态;B10 依此实现 |
| D-019 | 2026-09-07 | **IRRS 0.1.0 首批 10 条规则按草案生效**(severity/weight 逐条认可;D5-002 支付实际可用纯人工、缺证据必 UNKNOWN) | ✅ 已定(PO 确认) | T-004 部分:30–50 条扩充仍开放 |
| D-020 | 2026-09-07 | **交互与语言策略确认**:评估字段英文、报告展示中文、证据保留原文;手机上传/人审可用 | ✅ 已定(PO 确认) | supersedes D-012 草案状态 |
| D-021 | 2026-09-07 | **URL 自动抓取:批准做,但因 deadline 显式声明本期未完成**(SSRF 隔离执行器为 2–3 人日工作量,时间盒内不可交付);URL 来源登记保留;此为 P0 未完成项,进交付声明 | 🟡 已批准 / 本期未完成 | supersedes D-011 中 URL 部分裁剪悬置;D-011 其余确认 |

> 注:D-006 ~ D-009 为 AI 代拟的暂定项(讨论发起后未获 PO 回复),D-011/D-012 为 B01 草案——以上均**不是已确认决策**。确认或变更时**不要修改历史行**:按 D-014 追加新行并注明 `supersedes D-0XX`。

Expand Down
158 changes: 79 additions & 79 deletions docs/adr/0002-scoring-and-review.md
Original file line number Diff line number Diff line change
@@ -1,79 +1,79 @@
# ADR-0002:确定性评分与人审语义(v1 草案)

- 状态:**提议(草案,待 Product Owner 审定后才能实现为正式评分代码)**
- 日期:2026-09-07
- 决策人:AI 起草;审定后状态改为已接受并登记决策日志(supersedes 机制)
- 关闭问题:[文档审查记录 R-04](../04_DOCUMENT_REVIEW_2026-09-07.md)(评分语义未定,不同实现可算出不同分数)
- 关联:PRD §11.3(评分原则)、TECH_SPEC §2.3/§7.7(确定性内核)、执行方案 §5.1(建议草案来源)

## 1. 背景与问题

PRD §11.3 只约定「LLM 不直接打分、按 rule weights 确定性计算、run 绑定 standard_version」,但 WARN 折算、N/A、Reject、Info、覆盖率、零分母、Critical 门槛均未定义。不先固定这些语义,Go 评分服务(B10)无法通过「手算样例一致」验收。

## 2. 决策(建议值,审定前不实现)

### 2.1 输入与分母

1. 每个 AuditRun 创建时冻结「**适用检查项全集**」为分母来源:候选规则先按 `applicability`(entity_types、target_locales、evidence_requirements)做确定性筛选,筛选结果与每项的稳定 key(rule code)在 run 输入快照中记录;后续不得悄悄缩小范围。
2. 同一检查项多个 Evidence / 多条候选 Finding 只计一次——按稳定 key 去重后聚合。
3. `draft` 状态的规则不得进入适用全集;`Info` 严重度规则不扣分也**不进入计分分母**(单独列为建议清单)。

### 2.2 状态折算

| 状态 | 数值 | 说明 |
|---|---|---|
| PASS | 1 | |
| WARN | 0.5 | 部分可达/部分可用 |
| FAIL | 0 | |
| UNKNOWN | 不进入已评估分数 | 缺证据或无法判断;既不奖励也不惩罚 |
| 未审核项 | 不进入已评估分数 | review_required 且尚无人工处置的项 |
| N/A | 从适用全集排除 | **仅限人审给出理由后**;与 UNKNOWN 是不同决策 |
| Reject | 不自动转 PASS | 认可=维持候选状态值;不认可且无替代判断=保留 UNKNOWN |

### 2.3 公式

- 维度分:`100 × Σ(规则权重 × 状态值) / Σ(已评估规则权重)`,仅对该维度**已评估**的适用项求和。
- 维度覆盖率:`已评估适用权重 / 全部适用权重`;同时展示条目覆盖数(n/M)。
- 总分:`Σ(维度分 × 维度权重) / Σ(参评维度权重)`,维度权重取 run 冻结的标准版本定义(PRD §11.1)。
- **发布条件**:仅当所有适用计分项已审定且不含 UNKNOWN 时发布最终总分;否则展示维度分与覆盖率,`total_score = null`,报告标注「部分评估」。若产品希望低覆盖率也出总分,须另定阈值并书面接受风险——不默认。
- 整维处理:整维 N/A(人审确认)可排除并重新归一化;整维缺证据**不得**按 N/A 处理(它压低覆盖率,不消失)。全部适用项均为 N/A/UNKNOWN 时无分数——显示无分数,不得给 0 或 100 冒充已验收。

### 2.4 关键规则

1. S0/S1 FAIL 独立列为「阻断/关键问题」清单,任何均分都不能隐藏;严重度不再乘第二次权重。
2. 置信度(confidence)只做人审排序提示,**不参与算分**。
3. 报告冻结:评分算法版本 + 规则包 hash + 维度权重,写入 run;历史报告读取时按冻结值复算演示,不读当前 active 版本(R-03)。
4. 数值精度:内部全程浮点,**仅在最终展示与持久化时**四舍五入到小数点后 2 位(ROUND_HALF_UP);比较、Diff、回归一律使用未取整值。
5. 评分修复通过「新算法版本 + 新标准版本」发布,不得重算历史;历史更正显式生成新 run/报告。

### 2.5 人审语义(与评分的衔接)

- confirm:接受候选结论(状态值按候选 status 计);
- edit:保留原始候选字段 + 修订字段 + 理由 + actor + 时间(可追溯、可重放);评分取修订值;
- na:必须填理由;把该项从适用全集排除(影响分母),这与缺证据(UNKNOWN,留在分母外但压覆盖率)不同;
- reject:候选结论未获认可——要么给人工替代判断(走 edit 语义),要么该项保留 UNKNOWN;**reject 不产生 PASS**;
- finalize 前置条件:所有 review_required 项都有处置(confirm/edit/na/reject→替代或 UNKNOWN);存在 UNKNOWN 的报告明确标「部分评估」。

## 3. 手算验收例(B10 实现必须与之一致)

设某维度有 3 项,权重分别为 2/1/1:

1. 结果 PASS / WARN / FAIL:
维度分 = `100 × (2×1 + 1×0.5 + 1×0) / 4 = 62.50`,覆盖率 4/4 = 100%。
2. 将第三项改 UNKNOWN:
部分分 = `100 × (2 + 0.5) / 3 ≈ 83.33`,覆盖率 3/4 = 75%,`total_score = null`(部分评估)。
**不得**因 62.50→83.33 宣称「准备度改善」——分母变了。
3. 第三项经人审判定 N/A(附理由):
适用权重全集变为 3,结果 = `100 × (2 + 0.5) / 3 ≈ 83.33`,覆盖率 100%,可发布总分。
这与情形 2 数值巧合相同,但语义不同:N/A 缩小范围,UNKNOWN 是未完成评估。

## 4. 后果

- 审定通过后:B10 按本 ADR 实现 Go 评分服务,手算样例进单元测试;B02 规则 YAML 的 severity/weight 语义按本 ADR 解释。
- 审定前:本 ADR 是草案,任何代码不得实现其中数值;规则包保持 draft。
- 覆盖率门槛(如「覆盖率 ≥ X% 才可出总分」)若产品需要,必须由 PO 在审定时补充,不允许实现后看结果再定。

## 5. 验证

- B10 的 verify:本 ADR §3 手算例 + 零分母 + 整维 N/A + S0/S1 清单 + 并发 review/finalize 测试全部通过;
- 报告展示层:部分评估与无分数状态可见,不得渲染成 0/100。
# ADR-0002:确定性评分与人审语义(v1 草案)
- 状态:**已接受(2026-09-07 PO 确认,D-018;B10 依此实现)**
- 日期:2026-09-07
- 决策人:AI 起草;审定后状态改为已接受并登记决策日志(supersedes 机制)
- 关闭问题:[文档审查记录 R-04](../04_DOCUMENT_REVIEW_2026-09-07.md)(评分语义未定,不同实现可算出不同分数)
- 关联:PRD §11.3(评分原则)、TECH_SPEC §2.3/§7.7(确定性内核)、执行方案 §5.1(建议草案来源)
## 1. 背景与问题
PRD §11.3 只约定「LLM 不直接打分、按 rule weights 确定性计算、run 绑定 standard_version」,但 WARN 折算、N/A、Reject、Info、覆盖率、零分母、Critical 门槛均未定义。不先固定这些语义,Go 评分服务(B10)无法通过「手算样例一致」验收。
## 2. 决策(建议值,审定前不实现)
### 2.1 输入与分母
1. 每个 AuditRun 创建时冻结「**适用检查项全集**」为分母来源:候选规则先按 `applicability`(entity_types、target_locales、evidence_requirements)做确定性筛选,筛选结果与每项的稳定 key(rule code)在 run 输入快照中记录;后续不得悄悄缩小范围。
2. 同一检查项多个 Evidence / 多条候选 Finding 只计一次——按稳定 key 去重后聚合。
3. `draft` 状态的规则不得进入适用全集;`Info` 严重度规则不扣分也**不进入计分分母**(单独列为建议清单)。
### 2.2 状态折算
| 状态 | 数值 | 说明 |
|---|---|---|
| PASS | 1 | |
| WARN | 0.5 | 部分可达/部分可用 |
| FAIL | 0 | |
| UNKNOWN | 不进入已评估分数 | 缺证据或无法判断;既不奖励也不惩罚 |
| 未审核项 | 不进入已评估分数 | review_required 且尚无人工处置的项 |
| N/A | 从适用全集排除 | **仅限人审给出理由后**;与 UNKNOWN 是不同决策 |
| Reject | 不自动转 PASS | 认可=维持候选状态值;不认可且无替代判断=保留 UNKNOWN |
### 2.3 公式
- 维度分:`100 × Σ(规则权重 × 状态值) / Σ(已评估规则权重)`,仅对该维度**已评估**的适用项求和。
- 维度覆盖率:`已评估适用权重 / 全部适用权重`;同时展示条目覆盖数(n/M)。
- 总分:`Σ(维度分 × 维度权重) / Σ(参评维度权重)`,维度权重取 run 冻结的标准版本定义(PRD §11.1)。
- **发布条件**:仅当所有适用计分项已审定且不含 UNKNOWN 时发布最终总分;否则展示维度分与覆盖率,`total_score = null`,报告标注「部分评估」。若产品希望低覆盖率也出总分,须另定阈值并书面接受风险——不默认。
- 整维处理:整维 N/A(人审确认)可排除并重新归一化;整维缺证据**不得**按 N/A 处理(它压低覆盖率,不消失)。全部适用项均为 N/A/UNKNOWN 时无分数——显示无分数,不得给 0 或 100 冒充已验收。
### 2.4 关键规则
1. S0/S1 FAIL 独立列为「阻断/关键问题」清单,任何均分都不能隐藏;严重度不再乘第二次权重。
2. 置信度(confidence)只做人审排序提示,**不参与算分**。
3. 报告冻结:评分算法版本 + 规则包 hash + 维度权重,写入 run;历史报告读取时按冻结值复算演示,不读当前 active 版本(R-03)。
4. 数值精度:内部全程浮点,**仅在最终展示与持久化时**四舍五入到小数点后 2 位(ROUND_HALF_UP);比较、Diff、回归一律使用未取整值。
5. 评分修复通过「新算法版本 + 新标准版本」发布,不得重算历史;历史更正显式生成新 run/报告。
### 2.5 人审语义(与评分的衔接)
- confirm:接受候选结论(状态值按候选 status 计);
- edit:保留原始候选字段 + 修订字段 + 理由 + actor + 时间(可追溯、可重放);评分取修订值;
- na:必须填理由;把该项从适用全集排除(影响分母),这与缺证据(UNKNOWN,留在分母外但压覆盖率)不同;
- reject:候选结论未获认可——要么给人工替代判断(走 edit 语义),要么该项保留 UNKNOWN;**reject 不产生 PASS**;
- finalize 前置条件:所有 review_required 项都有处置(confirm/edit/na/reject→替代或 UNKNOWN);存在 UNKNOWN 的报告明确标「部分评估」。
## 3. 手算验收例(B10 实现必须与之一致)
设某维度有 3 项,权重分别为 2/1/1:
1. 结果 PASS / WARN / FAIL:
维度分 = `100 × (2×1 + 1×0.5 + 1×0) / 4 = 62.50`,覆盖率 4/4 = 100%。
2. 将第三项改 UNKNOWN:
部分分 = `100 × (2 + 0.5) / 3 ≈ 83.33`,覆盖率 3/4 = 75%,`total_score = null`(部分评估)。
**不得**因 62.50→83.33 宣称「准备度改善」——分母变了。
3. 第三项经人审判定 N/A(附理由):
适用权重全集变为 3,结果 = `100 × (2 + 0.5) / 3 ≈ 83.33`,覆盖率 100%,可发布总分。
这与情形 2 数值巧合相同,但语义不同:N/A 缩小范围,UNKNOWN 是未完成评估。
## 4. 后果
- 审定通过后:B10 按本 ADR 实现 Go 评分服务,手算样例进单元测试;B02 规则 YAML 的 severity/weight 语义按本 ADR 解释。
- 审定前:本 ADR 是草案,任何代码不得实现其中数值;规则包保持 draft。
- 覆盖率门槛(如「覆盖率 ≥ X% 才可出总分」)若产品需要,必须由 PO 在审定时补充,不允许实现后看结果再定。
## 5. 验证
- B10 的 verify:本 ADR §3 手算例 + 零分母 + 整维 N/A + S0/S1 清单 + 并发 review/finalize 测试全部通过;
- 报告展示层:部分评估与无分数状态可见,不得渲染成 0/100。
20 changes: 10 additions & 10 deletions docs/adr/README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# ADR 索引(Architecture Decision Records)

> 格式:MADR(docs/03 §4.4);触发清单见 TECH_SPEC §21.5。
> 规则:已接受的 ADR 不修改;推翻时新增一篇并标注 supersedes。新 ADR 编号按本表顺延,落盘前先在本表登记。

| 编号 | 标题 | 状态 | 日期 | supersedes |
|---|---|---|---|---|
| [0001](0001-canonical-repository-layout.md) | 规则、契约、评测与 Prompt 的唯一目录来源 | 已接受 | 2026-09-07 | TECH_SPEC v0.1 §8.1 候选布局 |
| [0002](0002-scoring-and-review.md) | 确定性评分与人审语义 v1 | 提议(待 PO 审定) | 2026-09-07 | — |
| [0003](0003-migration-tool.md) | 迁移工具选用 golang-migrate | 已接受 | 2026-09-07 | —(关闭 S-2 二选一遗留) |
# ADR 索引(Architecture Decision Records)
> 格式:MADR(docs/03 §4.4);触发清单见 TECH_SPEC §21.5。
> 规则:已接受的 ADR 不修改;推翻时新增一篇并标注 supersedes。新 ADR 编号按本表顺延,落盘前先在本表登记。
| 编号 | 标题 | 状态 | 日期 | supersedes |
|---|---|---|---|---|
| [0001](0001-canonical-repository-layout.md) | 规则、契约、评测与 Prompt 的唯一目录来源 | 已接受 | 2026-09-07 | TECH_SPEC v0.1 §8.1 候选布局 |
| [0002](0002-scoring-and-review.md) | 确定性评分与人审语义 v1 | 已接受(D-018) | 2026-09-07 | — |
| [0003](0003-migration-tool.md) | 迁移工具选用 golang-migrate | 已接受 | 2026-09-07 | —(关闭 S-2 二选一遗留) |
24 changes: 12 additions & 12 deletions standards/irrs/0.1.0/rules.yaml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# IRRS 0.1.0 首批规则(B02 草稿)
#
# 状态:整个规则包 status=draft——未经 Product Owner 审定前不得用于生产评分(ADR-0002)。
# 状态:active(2026-09-07 PO 审定生效,D-019)。发布版本不可原地修改——问题修复出新版本目录。
# 审定要点:逐条复核 severity_default 与 weight(rationale 是审定依据)、examples 是否符合实际场景。
# 约束:
# - 规则文件按 ADR-0001 唯一存放于 standards/irrs/<semver>/;发布后不可原地修改,只能出新版本目录。
Expand All @@ -10,7 +10,7 @@
standard:
code: IRRS
version: 0.1.0
status: draft
status: active
created_at: "2026-09-07"
notes: >
B02 首批 10 条,覆盖 D1–D7,优先餐饮业态。
Expand Down Expand Up @@ -45,7 +45,7 @@ rules:
detail: 门头挂中文招牌+菜品实拍图,无文字也可识别为餐饮店。
- outcome: fail
detail: 招牌仅在建筑侧面且夜间无照明,正门视角无法识别店名。
status: draft
status: active

- code: IRRS-D2-001
title: 菜单目标访客语言可达
Expand Down Expand Up @@ -75,7 +75,7 @@ rules:
detail: 提供中英双语菜单,品类与价格完整对应。
- outcome: fail
detail: 菜单仅中文且无翻译入口,仅一道菜印有英文单词。
status: draft
status: active

- code: IRRS-D2-002
title: 特色菜品文化概念可理解
Expand Down Expand Up @@ -104,7 +104,7 @@ rules:
detail: 招牌菜附英文一句话说明原料与辣度。
- outcome: fail
detail: 菜品仅有音译名(如 Mapo Tofu),无任何口感/原料说明。
status: draft
status: active

- code: IRRS-D3-001
title: 价格与关键成分信息透明
Expand Down Expand Up @@ -135,7 +135,7 @@ rules:
detail: 菜单标注价格、例/份说明,过敏原以图标列出并有英文图例。
- outcome: fail
detail: 价格齐全但辣度/过敏原完全无标注,且目标语言版本缺失。
status: draft
status: active

- code: IRRS-D4-001
title: 扫码点单流程语言可达
Expand Down Expand Up @@ -164,7 +164,7 @@ rules:
detail: 扫码进入支持 en/ja 切换的点单页,选品到下单全程可完成。
- outcome: fail
detail: 落地页仅中文且无语言切换,需手机号注册才能浏览。
status: draft
status: active

- code: IRRS-D4-002
title: 自助流程不可用时的协助降级路径
Expand Down Expand Up @@ -195,7 +195,7 @@ rules:
detail: 柜台提供图片菜单与双语点单卡,访谈确认店员可协助。
- outcome: fail
detail: 仅扫码点单且柜台不接受口头点单,无可替代路径。
status: draft
status: active

- code: IRRS-D5-001
title: 支付方式明示
Expand Down Expand Up @@ -225,7 +225,7 @@ rules:
detail: 收银台张贴银联/Visa/支付宝/微信标识,含英文 ACCEPTED HERE。
- outcome: fail
detail: 全店无任何支付方式标识,支付方式仅能口头询问。
status: draft
status: active

- code: IRRS-D5-002
title: 支付路径实际可用(人工确认)
Expand Down Expand Up @@ -255,7 +255,7 @@ rules:
detail: 实测Visa刷卡成功并留存小票,与标识一致。
- outcome: fail
detail: 标识Visa可用,实测POS拒绝外卡且无其他国际支付路径。
status: draft
status: active

- code: IRRS-D6-001
title: 求助与投诉渠道可见
Expand Down Expand Up @@ -284,7 +284,7 @@ rules:
detail: 桌贴含双语「如需帮助请联系店员」及店长微信二维码。
- outcome: fail
detail: 店内无任何求助/投诉指引,仅中文小票含客服电话。
status: draft
status: active

- code: IRRS-D7-001
title: 就餐习俗与文化语境提示
Expand Down Expand Up @@ -313,4 +313,4 @@ rules:
detail: 菜单尾页英文说明收取10%服务费、免费茶水与等位规则。
- outcome: fail
detail: 外卡访客结账时才被告知现金-only 且无小费/服务费说明。
status: draft
status: active
Loading