FR-044 稽核紀錄 xlsx 匯入 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 讓稽核員 / PM 在稽核執行頁上傳顧問的逐條檢查紀錄 xlsx，系統解析成控制層判定＋逐 AO 觀察＋佐證連結，預覽修改後批次寫入本輪 AR。

Architecture: Mirror FR-043 的三段式匯入管線（parse → preview → confirm），寫入全走 AssessmentResultAppService 既有方法（judge_finding / create_observation / add_risk / link_risk_findings），單一 @transaction 全成全敗。xlsx 是 AO 粒度（59 列），系統是控制層粒度（NIST 17 條）→ 透過 framework profile 對照表（AG 15 → NIST 17，一對多） 做「AO 判定 → 控制層判定」聚合。FR-043 的 adapter registry 與 _METHOD_KEYWORDS 上收為共用 import_adapter/ 基建，AP docx 與 AR xlsx 各為一個 instance。

Tech Stack: Flask-RESTful + marshmallow、DDD（domain/grc + infra/grc）、dependency-injector、SQLAlchemy + PostgreSQL RLS、openpyxl（xlsx 讀取）、jedi_oscal_v2（FindingState / AR domain services）、Vue 3 + PrimeVue（FE wizard）。

設計決策（Option A，user 2026-07-03 拍板）：一對多控制照順序拆分；preview 依 NIST 控制（17 組） 分組、每組標註來源 AG index；聚合、判定、風險都跑在 NIST finding 層。

套件（jedi_oscal_v2，dev 走 path dependency，不 commit pyproject path 改動）

• Modify: jedi_oscal_v2/common/enum/oscal_enums.py — FindingState 加 NOT_APPLICABLE
• Modify: jedi_oscal_v2/domain/service/ar/ar_finding_matrix_service.py — token 對照 + stats na 桶

BE 共用 import 基建（FR-043 泛化，本 FR 完成）

• Create: app/grc/service/import_adapter/__init__.py
• Create: app/grc/service/import_adapter/method_keywords.py — _METHOD_KEYWORDS + detect_methods()（自 airasia adapter 上收）
• Create: app/grc/service/import_adapter/registry_base.py — UnsupportedFormat + RegistryBase（loader 可注入）
• Modify: app/grc/service/ap_report_parser/registry.py / airasia_cmmc_l1_v1.py — 改 import 共用層，行為不變

BE parse job 持久層（mirror ap_docx_parse_job → ar_xlsx_parse_job）

• Create: infra/grc/model/ar_xlsx_parse_job.py
• Create: infra/grc/mapper/ar_xlsx_parse_job_mapper.py
• Create: infra/grc/repository/ar_xlsx_parse_job_repo_impl.py
• Create: domain/grc/entities/ar_xlsx_parse_job_entity.py
• Create: domain/grc/repository/i_ar_xlsx_parse_job_repo.py
• Create: domain/grc/service/ar_xlsx_parse_job_domain_service.py
• Create: scripts/sql/2026-07-03-ar-xlsx-parse-jobs.sql（含 org_unit_id）

BE framework profile + adapter

• Create: app/grc/service/ar_report_parser/__init__.py
• Create: app/grc/service/ar_report_parser/base.py — ParsedArRecord / ParsedArRow dataclass + ArReportParserAdapter
• Create: app/grc/service/ar_report_parser/registry.py — openpyxl loader instance of RegistryBase
• Create: app/grc/service/ar_report_parser/airasia_cmmc_l1_ar_v1.py — 亞航 adapter
• Create: app/grc/service/ar_framework_profile/__init__.py
• Create: app/grc/service/ar_framework_profile/cmmc_l1.py — AG→[NIST] 對照 + verdict 詞彙 + AO 對齊策略

BE 匯入 app service + 對齊/配對

• Create: app/grc/service/ar_import_app_service.py — 主流程（parse/preview/confirm/discard）
• Create: app/grc/service/ar_import/ao_alignment.py — AG 區塊 → NIST 控制 AO parts 攤平對齊
• Create: app/grc/service/ar_import/evidence_matcher.py — 佐證分級配對
• Create: app/grc/service/ar_import/aggregation.py — 逐 NIST 控制聚合四規則
• Modify: app/grc/service/assessment_result_app_service.py — create_observation 加 collected、judge_finding 綁多 observation、提 public gate helper
• Modify: common/code/grc_error_code.py — 新 error codes

BE route + serializer + DI

• Create: api/project/routes/ar_import_route.py
• Create: api/project/serializers/ar_import.py
• Modify: api/project/__init__.py — register routes
• Modify: di_containers/grc/grc_containers.py — wiring

FE

• Create: src/components/grc/ar-import/ArImportDialog.vue（mirror ap-docx-import/ApDocxImportDialog.vue）
• Modify: src/views/project/RoundAuditReviewView.vue — 入口按鈕 + verdict 第四態 + stats na 桶 + judgedCount
• Modify: src/config/api/api.js — AR import 端點常數
• Modify: i18n（verdict_not_applicable、stat_not_applicable、匯入 wizard 文案）

測試（BE 在主專案 test/；E2E 在 compliance-manager-test）

• Create: test/test_fr044_*.py（adapter / aggregation / evidence / app service / package regression）

目標：not_applicable 端到端可用，既有測試全綠（enum 加值的 regression）。此 Phase 不碰匯入，先讓「N/A」在系統站得住。

Task A1: jedi_oscal_v2 接上 path dependency（dev-only）

Files:

• Modify: pyproject.toml（主專案，取消註解 jedi_oscal_v2 的 path 形式；此改動不 commit）

• Step 1: 確認目前安裝形式

Run: python -c "import jedi_oscal_v2, os; print(os.path.realpath(jedi_oscal_v2.__file__))" 判讀：若 realpath 已指向 ~/Projects/Jedicogy/.../jedi-oscal-v2/（symlink/editable）→ 改套件源碼重啟即生效，跳過 A1 的 pyproject 改動；若指向 site-packages 的 pin 版本 → 執行 Step 2。

• Step 2:（僅 pin 版才做）pyproject.toml 改 path 形式

在 [tool.poetry.dependencies] 把 jedi-oscal-v2 那行改成本地 path（參照同檔其他 path = "..." 註解樣式），然後請 user 跑 poetry update jedi-oscal-v2（不自己跑、不自己起服務）。

• Step 3: 提醒 user：「jedi_oscal_v2 已接本地 path，改套件源碼後請重啟 BE」。此 pyproject 改動屬 dev-only，feature 收尾發版時才還原 pin。

Task A2: FindingState 加 NOT_APPLICABLE

Files:

• Modify: jedi_oscal_v2/common/enum/oscal_enums.py:31-37
• Test: jedi-oscal-v2/tests/ar/test_finding_matrix.py（既有）

• Step 1: 寫 failing test（在套件 tests/ar/test_finding_matrix.py 加）

def test_not_applicable_state_and_token():
    from jedi_oscal_v2.common.enum.oscal_enums import FindingState
    from jedi_oscal_v2.domain.service.ar.ar_finding_matrix_service import (
        _STATE_TO_TOKEN, _TOKEN_TO_STATE,
    )
    assert FindingState.NOT_APPLICABLE.value == "not_applicable"
    assert _STATE_TO_TOKEN["not_applicable"] == "not-applicable"
    assert _TOKEN_TO_STATE["not-applicable"] == "not_applicable"

• Step 2: 跑測試確認 FAIL

Run: cd ~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal-v2 && python -m pytest tests/ar/test_finding_matrix.py::test_not_applicable_state_and_token -v Expected: FAIL（AttributeError: NOT_APPLICABLE / KeyError）

• Step 3: 加 enum 值

class FindingState(StrEnum):
    """控制項評估結果狀態。"""
    MET = "met"
    NOT_MET = "not_met"
    NOT_APPLICABLE = "not_applicable"
    PENDING = "pending"

Task A3: ArFindingMatrixService token 對照 + stats na 桶

Files:

• Modify: jedi_oscal_v2/domain/service/ar/ar_finding_matrix_service.py:42-48, 134-159

• Step 1: 加 token 對照（_STATE_TO_TOKEN）

_STATE_TO_TOKEN: Dict[str, str] = {
    FindingState.MET.value: "satisfied",
    FindingState.NOT_MET.value: "not-satisfied",
    FindingState.NOT_APPLICABLE.value: "not-applicable",  # OSCAL 無此值，比照 pending 存 product token
    FindingState.PENDING.value: "pending",
}

（_TOKEN_TO_STATE 為反向 comprehension，自動帶到）

• Step 2: list_findings stats 加 na 桶（ar_finding_matrix_service.py:142-159）

在 stats 初始化與回傳加 FindingState.NOT_APPLICABLE.value：

stats = {
    FindingState.MET.value: 0,
    FindingState.NOT_MET.value: 0,
    FindingState.NOT_APPLICABLE.value: 0,
    FindingState.PENDING.value: 0,
}
...
return {
    "findings": findings,
    "stats": {
        "met": stats[FindingState.MET.value],
        "not_met": stats[FindingState.NOT_MET.value],
        "na": stats[FindingState.NOT_APPLICABLE.value],
        "pending": stats[FindingState.PENDING.value],
        "total": len(findings),
    },
}

• Step 3: 更新 module docstring 的 mapping 表註記（加 NOT_APPLICABLE → 'not-applicable'）。

• Step 4: 跑套件全測試（regression 門檻）

Run: cd ~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal-v2 && python -m pytest tests/ -q Expected: 全綠（含新 test）。任一既有測試因 stats 多一桶失敗 → 修正該測試斷言（改成容忍 na 桶），不改行為。

• Step 5: Commit（套件 repo）

cd ~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal-v2
git add jedi_oscal_v2/common/enum/oscal_enums.py jedi_oscal_v2/domain/service/ar/ar_finding_matrix_service.py tests/ar/test_finding_matrix.py
git commit -m "feat(FR-044): FindingState 加 NOT_APPLICABLE + matrix na token/stats 桶"

（不 push、不發版、不推 Nexus — 等 user 明示）

Task A4: 主專案 finalize_assessment na 桶不擋 finalize（驗證，多半零改）

Files:

• Modify(可能): app/grc/service/assessment_result_app_service.py:398-405, 758-761
• Test: test/test_fr044_finalize_na.py

• Step 1: 寫 test：一輪 findings = 部分 met + 部分 not_applicable（無 pending、無 not_met）→ finalize_assessment 應通過、不產 POA&M。

# 用既有 AR service test 樣式（記得 logger patch fixture，見 CLAUDE.md）
# 建 matrix → upsert 部分 finding 為 not_applicable → finalize 不 raise GRC_VERDICT_INCOMPLETE

• Step 2: 跑確認（na 桶加好後 stats["pending"] 天然不含 na）

Run: pytest test/test_fr044_finalize_na.py -v Expected: PASS。若 FAIL 表示 get_findings 的 stats["controls_with_not_met"] 或 finalize 有硬編 met/not_met/pending 桶漏 na — 補上再測。

Task A5: FE verdict 第四態 + stats na 桶 + judgedCount

Files:

• Modify: src/views/project/RoundAuditReviewView.vue:58, 112-115, 128, 335-338, 633-635
• Modify: i18n lang.round_audit.verdict_not_applicable / stat_not_applicable（zh_Hant_TW + en）

• Step 1: stats ref type 加 na（L58）：{ met; not_met; na; pending; total }，初始值同步。
• Step 2: verdictOptions 加第四項（L112-115）：{ label: t('lang.round_audit.verdict_not_applicable'), value: 'not_applicable' }。
• Step 3: judgedCount（L128）改 stats.met + stats.not_met + stats.na（na = 已判定）。
• Step 4: FE 控制層聚合（L335-338）加 na：任一 not_met→not_met；全 na→not_applicable；含 pending→pending；否則→met。
• Step 5: stats tags（L633-635）加 na tag（stats.na，severity secondary/info）。
• Step 6: verdictSeverity / toTreeVerdict（L619-621）處理 not_applicable（顯示灰或 info；tree verdict → null 不顯示 pass/fail 圓點）。
• Step 7: i18n 補鍵（zh + en），pybabel 不涉及（前端 i18n 走 FE lang 檔）。
• Step 8: Commit（FE repo，顯式 add）

cd ~/Projects/Billows/Audit-Manager/compliance-manager-fe
git add src/views/project/RoundAuditReviewView.vue src/i18n/... 
git commit -m "feat(FR-044): 稽核判定加 not_applicable 第四態 + stats na 桶"

• Step 9: Commit（BE package regression 用的 test）

cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
git add test/test_fr044_finalize_na.py app/grc/service/assessment_result_app_service.py
git commit -m "test(FR-044): finalize 不被 not_applicable 擋 + na 桶漣漪修正"

目標：解析工作記錄表可建可讀可軟刪。建表 SQL 一次含 org_unit_id（避開 FR-043 漏補的前例）。

Task B1: SQL migration（含 org_unit_id、GRANT、RLS、schema_migrations）

Files:

• Create: scripts/sql/2026-07-03-ar-xlsx-parse-jobs.sql

• Step 1: 寫 migration（照 2026-07-02-ap-docx-parse-jobs.sql + org_unit_id 併入）

-- Date: 2026-07-03
-- =============================================================================
-- FR-044 稽核紀錄 xlsx 匯入 — ar_xlsx_parse_jobs 表
-- 一次含 org_unit_id（TenantScopedMixinModel 多租戶需要；避開 FR-043 漏補前例）
-- =============================================================================
CREATE TABLE oscal.ar_xlsx_parse_jobs (
    id             SERIAL PRIMARY KEY,
    uid            VARCHAR(36) NOT NULL UNIQUE,
    tenant_id      INTEGER NOT NULL,
    org_unit_id    INTEGER REFERENCES public.org_units(id),
    source_type    VARCHAR(20) NOT NULL DEFAULT 'ar_round',
    source_uid     VARCHAR(36) NOT NULL,          -- round_uid
    status         VARCHAR(20) NOT NULL DEFAULT 'pending',
    file_path      VARCHAR(255),
    file_name      VARCHAR(255),
    file_size      BIGINT,
    parsed_result  JSONB,
    error_code     VARCHAR(40),
    error_message  TEXT,
    import_summary JSONB,
    is_active      BOOLEAN NOT NULL DEFAULT TRUE,
    created_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    created_user   VARCHAR(50) NOT NULL,
    updated_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_user   VARCHAR(50) NOT NULL
);
CREATE INDEX idx_ar_xlsx_parse_jobs_source ON oscal.ar_xlsx_parse_jobs(source_type, source_uid);
CREATE INDEX idx_ar_xlsx_parse_jobs_status ON oscal.ar_xlsx_parse_jobs(status, created_at);
CREATE INDEX idx_ar_xlsx_parse_jobs_tenant ON oscal.ar_xlsx_parse_jobs(tenant_id);
CREATE INDEX idx_ar_xlsx_parse_jobs_org_unit_id ON oscal.ar_xlsx_parse_jobs(org_unit_id);
ALTER TABLE oscal.ar_xlsx_parse_jobs ENABLE ROW LEVEL SECURITY;
CREATE POLICY rls_ar_xlsx_parse_jobs ON oscal.ar_xlsx_parse_jobs
    USING (tenant_id::text = current_setting('app.user_id', true)
        OR current_setting('app.allowed_tenant_paths', true) LIKE '%' || tenant_id::text || '%');
GRANT SELECT, INSERT, UPDATE, DELETE ON oscal.ar_xlsx_parse_jobs TO cm_app;
GRANT USAGE, SELECT ON SEQUENCE oscal.ar_xlsx_parse_jobs_id_seq TO cm_app;
INSERT INTO public.schema_migrations(filename, note) VALUES
  ('2026-07-03-ar-xlsx-parse-jobs.sql', 'FR-044 / 新建 oscal.ar_xlsx_parse_jobs（AR xlsx 匯入解析工作記錄，TTL 24h）')
ON CONFLICT (filename) DO NOTHING;

• Step 2: 套用 DEV（cmmgr、port 25432、single-transaction）

Run:

set -a; source .env; set +a
PGPASSWORD='<查 .env DB_SECRET>' psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_dev \
  --single-transaction -v ON_ERROR_STOP=1 -f scripts/sql/2026-07-03-ar-xlsx-parse-jobs.sql

Expected: CREATE TABLE … INSERT 0 1，無 ERROR。

• Step 3: 驗證

Run: PGPASSWORD='...' psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_dev -c "\d oscal.ar_xlsx_parse_jobs" Expected: 含 org_unit_id 欄；RLS enabled。

• Step 4: Commit

git add scripts/sql/2026-07-03-ar-xlsx-parse-jobs.sql
git commit -m "feat(FR-044): ar_xlsx_parse_jobs 表 migration（含 org_unit_id/RLS/GRANT）"

Task B2: entity / repo interface / model / mapper / repo impl / domain service

Files:（逐檔 mirror ap_docx_parse_job，把 Ap→Ar、docx→xlsx、source_type 預設 'ar_round'）

• Create: domain/grc/entities/ar_xlsx_parse_job_entity.py（ArXlsxParseJobEntity + ArXlsxParseJobQueryEntity，加 org_unit_id 欄位）
• Create: domain/grc/repository/i_ar_xlsx_parse_job_repo.py
• Create: infra/grc/model/ar_xlsx_parse_job.py（BaseModel, TenantScopedMixinModel、__tablename__='ar_xlsx_parse_jobs'、schema oscal）
• Create: infra/grc/mapper/ar_xlsx_parse_job_mapper.py
• Create: infra/grc/repository/ar_xlsx_parse_job_repo_impl.py
• Create: domain/grc/service/ar_xlsx_parse_job_domain_service.py（create 的 source_type="ar_round"）

• Step 1: 逐檔對照 ap_docx_parse_job_* 建立（entity 的 __init__ 加 org_unit_id: Optional[int] = None；model 由 TenantScopedMixinModel 自動帶 tenant_id/org_unit_id，不重複宣告）。
• Step 2: 寫 mapper roundtrip test

Files: Test: test/test_fr044_ar_xlsx_parse_job_mapper.py

def test_ar_xlsx_parse_job_mapper_roundtrip():
    from infra.grc.model.ar_xlsx_parse_job import ArXlsxParseJob
    from infra.grc.mapper.ar_xlsx_parse_job_mapper import ArXlsxParseJobMapper
    m = ArXlsxParseJob(id=1, uid="u", tenant_id=1, source_type="ar_round",
                       source_uid="r", status="pending", is_active=True)
    e = ArXlsxParseJobMapper.to_entity(m)
    assert e.uid == "u" and e.source_type == "ar_round"

• Step 3: 跑測試

Run: pytest test/test_fr044_ar_xlsx_parse_job_mapper.py -v Expected: PASS

• Step 4: Commit

git add domain/grc/entities/ar_xlsx_parse_job_entity.py domain/grc/repository/i_ar_xlsx_parse_job_repo.py \
        infra/grc/model/ar_xlsx_parse_job.py infra/grc/mapper/ar_xlsx_parse_job_mapper.py \
        infra/grc/repository/ar_xlsx_parse_job_repo_impl.py domain/grc/service/ar_xlsx_parse_job_domain_service.py \
        test/test_fr044_ar_xlsx_parse_job_mapper.py
git commit -m "feat(FR-044): ar_xlsx_parse_job 持久層（entity/repo/mapper/domain service）"

目標：把 FR-043 的 registry base + _METHOD_KEYWORDS 上收共用；建 AR xlsx adapter。FR-043 AP docx 匯入測試全綠 = regression 門檻。

Task C1: 上收 _METHOD_KEYWORDS + detect_methods 到共用層

Files:

• Create: app/grc/service/import_adapter/__init__.py
• Create: app/grc/service/import_adapter/method_keywords.py
• Modify: app/grc/service/ap_report_parser/airasia_cmmc_l1_v1.py（改 import 共用 _METHOD_KEYWORDS）
• Test: test/test_fr044_method_keywords.py

• Step 1: 寫 test（先鎖定共用行為）

def test_detect_methods_maps_keywords():
    from app.grc.service.import_adapter.method_keywords import detect_methods
    assert "DOCUMENT_REVIEW" in detect_methods("文件檢查：核對員工帳號申請")
    assert "COMPUTER_CONFIG_COMPARE" in detect_methods("電腦設定比對：windows 事件檢視器")
    assert detect_methods("無關文字") == []

• Step 2: 跑確認 FAIL（module 不存在）

Run: pytest test/test_fr044_method_keywords.py -v → FAIL

• Step 3: 建 method_keywords.py：把 airasia_cmmc_l1_v1.py:93-105 的 _METHOD_KEYWORDS 原樣搬入，加 detect_methods(text: str) -> list[str]（任一 keyword 命中即計入、去重、保序）。

• Step 4: airasia_cmmc_l1_v1.py 改 from app.grc.service.import_adapter.method_keywords import _METHOD_KEYWORDS（刪本地定義），method 偵測邏輯不動。

• Step 5: 跑 FR-043 adapter 測試（regression）

Run: pytest test/ -k "ap_docx or ap_report or fr043 or airasia" -q Expected: 全綠（沿用既有測試；找不到就先確認 FR-043 測試檔名並全跑一次 pytest test/ -q 存 baseline）。

• Step 6: Commit

git add app/grc/service/import_adapter/__init__.py app/grc/service/import_adapter/method_keywords.py \
        app/grc/service/ap_report_parser/airasia_cmmc_l1_v1.py test/test_fr044_method_keywords.py
git commit -m "refactor(FR-044): _METHOD_KEYWORDS 上收 import_adapter 共用層（FR-043 行為不變）"

Task C2: 上收 registry base（loader 可注入）

Files:

• Create: app/grc/service/import_adapter/registry_base.py
• Modify: app/grc/service/ap_report_parser/registry.py（改繼承共用 base，docx loader）
• Test: test/test_fr044_registry_base.py

• Step 1: 寫 test：RegistryBase 用假 loader + 兩個假 adapter，parse_file 命中第一個 detect()=True；全不中拋 UnsupportedFormat(supported_versions)。

• Step 2: 建 registry_base.py

class UnsupportedFormat(Exception):
    def __init__(self, supported_versions):
        self.supported_versions = supported_versions
        super().__init__("no adapter matched")

class RegistryBase:
    """loader(file_path) -> doc；adapters 逐一 detect(doc)。"""
    def __init__(self, adapters, loader):
        self._adapters = adapters
        self._loader = loader
    @property
    def supported_versions(self):
        return [a.version for a in self._adapters]
    def parse_file(self, file_path):
        doc = self._loader(file_path)
        for a in self._adapters:
            if a.detect(doc):
                return a.parse(doc)
        raise UnsupportedFormat(self.supported_versions)

• Step 3: ap_report_parser/registry.py 改成 RegistryBase 的 docx 實例（loader=docx.Document），保留 ApReportUnsupportedFormat 為 UnsupportedFormat 的 alias（避免改 FR-043 app service 的 except 型別）。

• Step 4: 跑 FR-043 regression

Run: pytest test/ -k "ap_docx or ap_report" -q → 全綠

• Step 5: Commit

git add app/grc/service/import_adapter/registry_base.py app/grc/service/ap_report_parser/registry.py test/test_fr044_registry_base.py
git commit -m "refactor(FR-044): registry base 上收共用層（loader 可注入；FR-043 行為不變）"

Task C3: AR 中介結構 + 亞航 xlsx adapter（TDD，樣本 fixture）

Files:

• Create: app/grc/service/ar_report_parser/base.py — ParsedArRow（row_no, control_ref, objective_seq, objective_text, verdict_raw, method_text, evidence_names[]）+ ParsedArRecord（adapter_version, framework, meta{project_name, verification_type, headcount, audit_date}, rows[]）+ ArReportParserAdapter(ABC)
• Create: app/grc/service/ar_report_parser/registry.py（RegistryBase(adapters=[AirAsiaCmmcL1ArV1Adapter()], loader=openpyxl 讀取)）
• Create: app/grc/service/ar_report_parser/airasia_cmmc_l1_ar_v1.py
• Test: test/test_fr044_ar_adapter.py（樣本 xlsx 進 fixture）

• Step 1: 樣本進 fixture：把 亞航-CMMC L1內部稽核報告附件-稽核紀錄.xlsx 複製到 test/fixtures/fr044/airasia_cmmc_l1_ar.xlsx（不含機敏；xlsx 表頭專案名等 meta 是測試資料）。

• Step 2: 寫 snapshot test

def test_airasia_ar_adapter_parses_59_rows():
    from app.grc.service.ar_report_parser.airasia_cmmc_l1_ar_v1 import AirAsiaCmmcL1ArV1Adapter
    import openpyxl
    wb = openpyxl.load_workbook("test/fixtures/fr044/airasia_cmmc_l1_ar.xlsx", data_only=True)
    a = AirAsiaCmmcL1ArV1Adapter()
    assert a.detect(wb) is True
    rec = a.parse(wb)
    assert rec.framework == "cmmc_l1"
    assert len(rec.rows) == 59
    # 15 個 AG 區塊、AO 數分佈
    from collections import Counter
    c = Counter(r.control_ref for r in rec.rows)
    assert list(c.values()) == [6,2,6,5,3,3,2,4,6,8,2,6,2,1,3]
    assert rec.meta["audit_date"] == "2026-06-02"   # 2026年6月2日 → ISO
    assert all(r.verdict_raw == "MET" for r in rec.rows)
    # 「(同N)」交叉引用保留原文，解析階段不展開（交給 evidence_matcher）

• Step 3: 跑確認 FAIL → 實作 adapter：

  • detect：sheet 名含「檢查紀錄」且 row5 表頭含「索引號/Objectives/稽核結果」。
  • parse：row1-4 抓 meta（專案名稱 / 受驗證型態 / 受稽核人數 / 稽核日期→ISO，日期解析復用 airasia_cmmc_l1_v1 的日期 helper 或搬到 import_adapter 共用）；row6+ 逐列成 ParsedArRow；control_ref strip 尾空白（row12 AC.L1-b.1.ii 有尾空白）；objective_seq 從 Objectives 欄的 [a]/[b] 前綴解；method_text=Status 欄；evidence_names=Evidence 欄一格多名先拆（換行/逗號/頓號）。

• Step 4: 跑測試 → PASS。加邊界 test：一格多名拆分、[a] 解析、control_ref 尾空白 normalize。

• Step 5: Commit

git add app/grc/service/ar_report_parser/ test/test_fr044_ar_adapter.py test/fixtures/fr044/airasia_cmmc_l1_ar.xlsx
git commit -m "feat(FR-044): 亞航 CMMC L1 AR xlsx adapter（59 列 snapshot + meta 解析）"

Task D1: CMMC L1 framework profile（AG→[NIST] 對照 + AO 對齊校驗）

Files:

• Create: app/grc/service/ar_framework_profile/__init__.py
• Create: app/grc/service/ar_framework_profile/cmmc_l1.py
• Test: test/test_fr044_framework_profile.py

• Step 1: 寫 test：對照表 15 鍵；PE.L1-b.1.ix → [PE.L1-3.10.3, PE.L1-3.10.4, PE.L1-3.10.5]；verdict 詞彙 MET→met / NOT MET→not_met / N/A→not_applicable / 空→pending。

• Step 2: 實作（把 pre-flight 驗證過的對照寫成常數）

FRAMEWORK = "cmmc_l1"
# AG (檢查紀錄) → NIST (catalog) 一對多對照，pre-flight 驗證 AO 數逐條對齊
AG_TO_NIST = {
    "AC.L1-b.1.i":   ["AC.L1-3.1.1"],
    "AC.L1-b.1.ii":  ["AC.L1-3.1.2"],
    "AC.L1-b.1.iii": ["AC.L1-3.1.20"],
    "AC.L1-b.1.iv":  ["AC.L1-3.1.22"],
    "IA.L1-b.1.v":   ["IA.L1-3.5.1"],
    "IA.L1-b.1.vi":  ["IA.L1-3.5.2"],
    "MP.L1-b.1.vii": ["MP.L1-3.8.3"],
    "PE.L1-b.1.viii":["PE.L1-3.10.1"],
    "PE.L1-b.1.ix":  ["PE.L1-3.10.3", "PE.L1-3.10.4", "PE.L1-3.10.5"],
    "SC.L1-b.1.x":   ["SC.L1-3.13.1"],
    "SC.L1-b.1.xi":  ["SC.L1-3.13.5"],
    "SI.L1-b.1.xii": ["SI.L1-3.14.1"],
    "SI.L1-b.1.xiii":["SI.L1-3.14.2"],
    "SI.L1-b.1.xiv": ["SI.L1-3.14.4"],
    "SI.L1-b.1.xv":  ["SI.L1-3.14.5"],
}
def map_verdict(raw: str) -> str:
    t = (raw or "").strip().upper().replace("／", "/")
    if t in ("MET",): return "met"
    if t in ("NOT MET", "NOTMET", "NOT-MET"): return "not_met"
    if t in ("N/A", "NA", "NOT APPLICABLE"): return "not_applicable"
    return "pending"  # 空值 / 無法辨識

• Step 3: 跑測試 → PASS。Commit。

Task D2: AO 對齊（AG 區塊 → NIST 控制 AO parts 攤平，Option A 拆分）

Files:

• Create: app/grc/service/ar_import/ao_alignment.py
• Test: test/test_fr044_ao_alignment.py

• Step 1: 寫 test（純函式、無 DB，用假 AO map）

def test_align_splits_one_to_many_by_order():
    # AG PE.L1-b.1.ix 6 列 → NIST [3.10.3(2AO), 3.10.4(1AO), 3.10.5(3AO)]
    # 期望：前2列→3.10.3、第3列→3.10.4、後3列→3.10.5
    from app.grc.service.ar_import.ao_alignment import align_block
    nist_ao_counts = {"PE.L1-3.10.3": 2, "PE.L1-3.10.4": 1, "PE.L1-3.10.5": 3}
    nist_order = ["PE.L1-3.10.3", "PE.L1-3.10.4", "PE.L1-3.10.5"]
    rows = list(range(6))  # 6 個 xlsx 列
    result = align_block(rows, nist_order, nist_ao_counts)
    assert result["PE.L1-3.10.3"] == [0, 1]
    assert result["PE.L1-3.10.4"] == [2]
    assert result["PE.L1-3.10.5"] == [3, 4, 5]

def test_align_count_mismatch_flags_degrade():
    from app.grc.service.ar_import.ao_alignment import align_block, AlignmentMismatch
    # xlsx 5 列 但 NIST AO 總數 6 → 降級
    import pytest
    with pytest.raises(AlignmentMismatch):
        align_block(list(range(5)), ["X"], {"X": 6})

• Step 2: 實作 align_block(xlsx_rows, nist_control_ids_in_order, nist_ao_counts) -> dict[nist_id, list[row]]：

  • 校驗 sum(nist_ao_counts) == len(xlsx_rows)，不合拋 AlignmentMismatch（caller 整 AG 區塊降級、標 preview 人工核對）。
  • 依 nist_control_ids_in_order 順序，各取該控制 AO 數個 xlsx 列。
  • NIST 控制的 AO 數與順序來源＝ derive_ao_pairs（caller 傳入解析好的 map，本函式純切分不碰 DB）。

• Step 3: 跑測試 → PASS。Commit。

Task D3: 佐證分級配對

Files:

• Create: app/grc/service/ar_import/evidence_matcher.py
• Test: test/test_fr044_evidence_matcher.py

• Step 1: 寫 test（88 名稱代表案例：精確 / 模糊 / l·I 打字錯 / 無配對 / 「(同8)」交叉引用）

def test_evidence_exact_fuzzy_none():
    from app.grc.service.ar_import.evidence_matcher import match_evidence
    pool = [{"uid":"e1","file_name":"Account_Privilege_Review_Plan.xlsx","description":""},
            {"uid":"e2","file_name":"Windows_Installer.log","description":""}]
    # 精確（去副檔名後全等）
    r1 = match_evidence(["Account_Privilege_Review_Plan"], pool)
    assert r1[0]["level"] == "exact" and r1[0]["matched"][0]["uid"] == "e1"
    # 模糊（Windowslnstaller l/I 打字錯）
    r2 = match_evidence(["Windowslnstaller"], pool)
    assert r2[0]["level"] == "fuzzy"
    # 無配對
    r3 = match_evidence(["完全不存在的檔"], pool)
    assert r3[0]["level"] == "none" and r3[0]["matched"] == []

• Step 2: 實作：

  • 正規化：去副檔名 → 去括號註記 → 去空白標點 → lower-case（含 l/I/1、0/O 常見打字錯的寬鬆比對）。
  • 級別：1 精確（正規化全等）／2 模糊（token 重疊 or 編輯距離達門檻）／3 無配對。
  • 「(同N)」：回傳 marker 讓 caller 解析為第 N 列的佐證集合（本函式只標記，不跨列展開）。
  • pool = 該控制各 AO 的 job_evidences（description + upload_files.file_name）+ surveys，去重同 FE obsEvidenceOptions。caller 組 pool，matcher 純比對。
  • 原則：寧漏配勿錯配（門檻用 fixture 調）。

• Step 3: 跑測試 → PASS。Commit。

Task D4: 聚合四規則（逐 NIST 控制）

Files:

• Create: app/grc/service/ar_import/aggregation.py
• Test: test/test_fr044_aggregation.py

• Step 1: 寫 test（五組合）

import pytest
from app.grc.service.ar_import.aggregation import aggregate_verdict
@pytest.mark.parametrize("states,expected", [
    (["met","met"], "met"),
    (["met","not_met"], "not_met"),
    (["not_applicable","not_applicable"], "not_applicable"),
    (["met","not_applicable"], "met"),          # met+na 混 → met（CMMC 計分 N/A 視同 MET）
    (["met","pending"], "pending"),
])
def test_aggregate(states, expected):
    assert aggregate_verdict(states) == expected

• Step 2: 實作

def aggregate_verdict(states: list[str]) -> str:
    if any(s == "not_met" for s in states): return "not_met"
    if states and all(s == "not_applicable" for s in states): return "not_applicable"
    if any(s == "pending" for s in states): return "pending"
    return "met"  # 全 met 或 met+na 混

• Step 3: 跑測試 → PASS。Commit。

Task D5: 擴充 AssessmentResultAppService（collected / 多 observation / public gate）

Files:

• Modify: app/grc/service/assessment_result_app_service.py
• Test: test/test_fr044_assessment_result_extensions.py（記得 logger patch fixture，見 feedback_test_logger_patch_db_handler）

• Step 1: 寫 test：

  • create_observation(..., collected=<dt>) → 回傳 obs.collected == 傳入值；不傳 → fallback now。
  • judge_finding(..., observation_uids=[o1,o2]) → finding.related_observations 含兩者（去重、累加不蓋）。
  • public gate helper resolve_round_for_import(round_uid, user_id)：auditor/manager 過、其他 raise ForbiddenError；stage≠auditing raise（既有 assert_round_phase）；無 ar_result raise 412 新碼。

• Step 2: 實作 create_observation 加 collected

def create_observation(self, round_uid, curr_user, curr_user_id, description,
                       title=None, methods=None, relevant_evidence=None,
                       subjects=None, collected=None, locale=None) -> dict:
    ...
    collected=collected or datetime.now(timezone.utc),

• Step 3: 實作 judge_finding 綁多 observation：加參數 observation_uids: Optional[List[str]] = None；沿用既有單 observation_uid 累加邏輯，對 list 逐一 resolve + dedup append 進 related_observations。

• Step 4: 提 public gate helper

def resolve_round_for_import(self, round_uid: str, user_id: int):
    """Import 專用守門：auditor/manager + stage=auditing + ar_result 已建。回 round。"""
    r = self._require_round_ar_result(round_uid)          # 含 assert_round_phase auditing + 404 無 ar_result
    self._check_auditor(r.project_id, user_id)            # 既有私有邏輯，經此 public 出口復用
    return r

（design 要求「gate 提 public helper」；此法零複製復用既有 _require_round_ar_result + _check_auditor。註：_require_round_ar_result 無 ar_result 時回 404 GRC_AR_NOT_FOUND — 若要 import 專屬 412 語意，另加 resolve_round_for_import 內先檢 r.ar_result_id，缺則 raise PreconditionFailedError(GRC_AR_ROUND_NOT_AUDITING)，符合 design §3「未啟動回 412」。）

• Step 5: 跑測試 → PASS。跑既有 AR service 測試 regression：pytest test/ -k assessment_result -q 全綠。

• Step 6: Commit

git add app/grc/service/assessment_result_app_service.py test/test_fr044_assessment_result_extensions.py
git commit -m "feat(FR-044): AR service 擴充 collected/多 observation 綁定/import gate helper"

Task D6: 錯誤碼

Files:

• Modify: common/code/grc_error_code.py

• Step 1: 加碼（各 band 從 pre-flight 查到的 max 下一號起；實作前再 grep 一次確認未被占用）

GRC_AR_XLSX_INVALID_FILE        = ("上傳檔案格式無效，請上傳 .xlsx 稽核紀錄檔",        "GRC_400092")
GRC_AR_XLSX_FILE_TOO_LARGE      = ("上傳檔案超過大小限制（10MB）",                    "GRC_400093")
GRC_AR_XLSX_FORMAT_UNSUPPORTED  = ("無法辨識的稽核紀錄格式，目前支援：{versions}",    "GRC_400094")
GRC_AR_XLSX_FRAMEWORK_MISMATCH  = ("檔案框架（{file_fw}）與本輪框架（{round_fw}）不符", "GRC_400095")
GRC_AR_XLSX_PARSE_JOB_NOT_FOUND = ("稽核紀錄解析任務不存在或已被刪除",                "GRC_404047")
GRC_AR_ROUND_NOT_AUDITING       = ("本輪尚未啟動稽核（無判定框架），無法匯入稽核紀錄", "GRC_412043")
GRC_AR_XLSX_PARSE_JOB_NOT_AWAITING = ("稽核紀錄解析任務狀態不是 awaiting_review，無法確認匯入", "GRC_412044")
GRC_AR_XLSX_PARSE_JOB_EXPIRED   = ("稽核紀錄解析任務已過期（24h）",                   "GRC_412045")

• Step 2: Commit（與 D7 一起或獨立皆可）

Task D7: ArImportAppService 主流程（parse / preview / confirm / discard）

Files:

• Create: app/grc/service/ar_import_app_service.py
• Test: test/test_fr044_ar_import_app_service.py

流程要點（mirror ap_docx_import_app_service.py）：

• upload_and_parse(file, round_uid, user_context)：resolve_round_for_import 守門 → .xlsx + 10MB 驗證 → 建 parse job → tempfile + file_upload → registry.parse_file → 框架一致性檢查（adapter.framework vs 本輪 AP 框架，不符 raise GRC_AR_XLSX_FRAMEWORK_MISMATCH）→ 建 parsed_result（見下）→ 持久化。單一 @transaction。
• get_parse_result：讀 parsed_result + TTL 標記 + 佐證/覆寫警示（讀路徑）。
• confirm_import：狀態=awaiting_review + 未過期 → 守門 → 逐 NIST 控制迴圈：judge_finding(聚合判定 + 綁該控制 observations) + 逐 AO create_observation(collected + methods + relevant_evidence + description 尾註判定)；not_met 控制 add_risk(severity medium) + link_risk_findings；單一 @transaction 全成全敗。
• discard_parse：軟刪。

parsed_result 結構（持久化 JSONB）：

{
  adapter_version, framework,
  meta: {project_name, verification_type, headcount, audit_date},
  overwrite_count: <本輪已有判定的 NIST 控制數（將被覆寫）>,
  degraded_blocks: [<AO 數不一致的 AG id>],
  controls: [   # 依 NIST 控制（17）分組
    { control_id(NIST), source_ag_id, source_row_range,
      aggregated_verdict, will_create_risk: bool,
      observations: [ {objective_seq, description(AO原文+方法+判定尾註),
                       methods:[...], evidence:[{level, names, matched:[{uid,file_name}]}]} ] }
  ]
}

• Step 1: 寫 app service test（mock domain services + AR app service；logger patch fixture）

  • parse 樣本 → parsed_result.controls 有 17 組、PE.L1-3.10.3/4/5 各自出現且 aggregated_verdict=met、observations 數 = 2/1/3；degraded_blocks 空；overwrite_count 依既有 findings 計。
  • 框架不符 → raise GRC_AR_XLSX_FRAMEWORK_MISMATCH。
  • 非 .xlsx / >10MB → 400。
  • confirm 全 MET → judge_finding 呼叫 17 次（met）、create_observation 59 次、add_risk 0 次。
  • 改造樣本（某 AG 區塊有 NOT MET）→ 對應 NIST 控制 aggregated not_met、add_risk severity=medium + link_risk_findings 呼叫、重複 confirm 不重複建 risk（防重見 Step 2）。
  • stage≠auditing / 無 ar_result → 412；TTL 過期 confirm → 412；非 awaiting → 412。

• Step 2: 實作。風險防重（對齊 design §2「同 control＋匯入來源＋open → skip」）：匯入建立的 risk 一律用 title 慣例 f"{control_id} 未符合" 當「匯入來源」標記；confirm 前掃本輪 risks，若已存在 status=open 且 title==f"{control_id} 未符合" 且已連該 NIST finding 的 risk → skip add_risk（避免與使用者手建風險混淆）。

• Step 3: 跑測試 → PASS。Commit。

Task E1: serializer + route + DI wiring

Files:

• Create: api/project/serializers/ar_import.py（Parse / Preview / Confirm schema，mirror ap_docx_import.py；Confirm schema 容忍 FE 回送完整 controls，Meta.unknown=EXCLUDE）
• Create: api/project/routes/ar_import_route.py（Upload / Get+Delete / Confirm，mirror ap_docx_import_route.py）
• Modify: api/project/__init__.py（register，URL 見 design §3）
• Modify: di_containers/grc/grc_containers.py（ar_xlsx_parse_job_repo/domain_service、ar_report_parser_registry、ar_import_app_service；注入 assessment_result_app_service + ssp_control_implementation_service 供佐證 pool + 控制樹）

• Step 1: 建 serializer + route。URL：
  • POST /audit-round/<round_uid>/ar-imports/parse
  • GET|DELETE /ar-import/<parse_uid>
  • POST /ar-import/<parse_uid>/confirm
• Step 2: DI wiring（parse job Singleton repo + Factory domain service；registry Singleton；app service Factory）。
• Step 3: 冒煙：請 user 重啟 BE 後，Swagger 出現四端點；GET /ar-import/<不存在> → 404 GRC_AR_XLSX_PARSE_JOB_NOT_FOUND（不 500）。
• Step 4: Commit（route + serializer + DI + error codes 一起）。

Task E2: FE ArImportDialog.vue + 入口按鈕

Files:

• Create: src/components/grc/ar-import/ArImportDialog.vue（mirror ap-docx-import/ApDocxImportDialog.vue 三步 wizard）
• Modify: src/views/project/RoundAuditReviewView.vue（header 入口按鈕）
• Modify: src/config/api/api.js（AR_IMPORT_PARSE/AR_IMPORT 常數）
• Modify: i18n（wizard 文案）

• Step 1: api.js 加常數（mirror AP_DOCX_IMPORT_PARSE/AP_DOCX_IMPORT）：

AR_IMPORT_PARSE: getUrl('/audit-round'),   // + /:roundUid/ar-imports/parse  POST multipart
AR_IMPORT:       getUrl('/ar-import'),      // GET /:uid | POST /:uid/confirm | DELETE /:uid

• Step 2: 入口按鈕：RoundAuditReviewView.vue header「匯入稽核紀錄」，顯示條件＝stage=auditing 且 participant role ∈ {auditor, manager} 且 findings 已建立。注意：現有 canEdit 只看 stage，participant role 需另取（呼叫 participant API 或既有 store；查 docs/claude/frontend-overview.md 既有取法，勿新造）。
• Step 3: ArImportDialog.vue 三步：
  • Step 1 上傳（.xlsx、10MB）→ 先開 dialog 再 spinner → parse。
  • Step 2 預覽：依 NIST 控制分組（17）、可摺疊；每 AO 列＝判定 SelectButton（四態可改）+ 觀察文字（可編）+ 佐證 chips（分級徽章 exact/fuzzy/none + 下拉補勾）+ NOT MET 列「將建立中風險」徽章；頂部摘要（樣板版本 / 框架 / overwrite_count 覆寫警示 / degraded_blocks 降級清單 + 來源 AG id 標註）；draft 存 localStorage（key by parse_uid）。
  • Step 3 完成：confirm → toast + 摘要（判定 N / 觀察 N / 風險 N / 佐證連結 N）→ refresh findings/stats/risks。
  • 關閉前未確認編輯二次確認。
• Step 4: 手測（見驗收）。Commit（FE repo，顯式 add）。

Task F1: 測試計畫（feature-test-planner agent）

• Step 1: 跑 feature-test-planner agent 讀 design.md + 本 plan，產 docs/features/FR-044-2607-ar-xlsx-import/test-plan.md（BE pytest 單元/整合 + FE E2E BDD + 追溯矩陣）。
• Step 2: 重點覆蓋（design §7）：adapter snapshot / AO 對齊一對多拆分 + 降級 / 佐證分級 / 聚合五組合 / 權限矩陣×parse-preview-confirm / stage 守門 412 / double-confirm 412 / TTL 412 / confirm 全成全敗 rollback / not_met 建 risk severity=medium + link + 防重 / na 不產 POA&M（finalize 掃描）/ stats na 桶 / FR-043 regression 全綠。

Task F2: E2E（compliance-manager-test repo）

• Step 1: 在 ~/Projects/Billows/Audit-Manager/compliance-manager-test/ 依該 repo CLAUDE.md 寫 BDD：上傳→改判定→確認→稽核頁狀態更新。不在主專案內加 e2e。

上傳樣本 xlsx 後：

• preview：17 個 NIST 控制分組（PE.L1-b.1.ix 拆成 PE.L1-3.10.3/4/5 三組，各標來源 AG id）全部聚合為 met（樣本 59 列全 MET）；59 筆 observation 預覽（各帶 AO 原文＋方法＋判定尾註）；佐證高信心自動勾選（模糊帶徽章、無配對灰列）；無風險建立。
• confirm 後稽核執行頁：17 控制項判定＝met（左側清單本就 17 條）、observations 掛對控制項、stats 正確（met=17、na=0、pending=0）、finalize_assessment 可正常推進（不被 pending / risk-no-finding 擋）。
• 改造樣本（改幾列 NOT MET／N/A／留空）驗：聚合四規則（含 PE.L1-b.1.ix 拆分後只有被判 not_met 的那條 NIST 控制建風險）＋中風險自動建立＋link_risk_findings 已連＋重複匯入 risk 防重＋na 不產 POA&M。

與 design §5 的差異說明：design 寫「15 個控制項」，實際系統粒度為 17 個 NIST finding（PE.L1-b.1.ix 一對多）。preview 以 NIST 分組並標註來源 AG，confirm 寫 17 筆。此為 Option A（user 2026-07-03 拍板）。

• @transaction 只在 app service public method；repo lazy session；route 不碰 DB；權限 app service 層 fail-closed。
• 顯式 git add <檔名>、禁 -am；push 等 user；不切 branch。
• SQL migration 用 cmmgr、-p 25432、--single-transaction -v ON_ERROR_STOP=1、先套 DEV、收尾補 STG/POC。
• 禁重複造輪子：寫任何新 method 前先 grep 既有行為（本 plan 的擴充皆為既有方法加參數，非新造）。
• app service test 記得 logger patch fixture；jedi_oscal_v2 dev 走 path dependency、不自行發版。
• 收尾動作（changelog / SUMMARY / Notion / memory）等 user 明示才做。