[UX] Subdirectory CSV files are silently ignored; trailing-slash handling is unclear

[ogawsh]

[UX] サブディレクトリ配下の CSV が silent に無視される／末尾スラッシュ差異の扱いが不明瞭

概要

/admin/list-csv → /admin/analyze が参照する _list_csv_files は、以下の実装により S3 プレフィックス直下の .csv ファイルだけを列挙する。サブディレクトリ配下の CSV はすべて無視される。

# lambda/adminwebbackend/app.py
def _list_csv_files(prefix: str) -> list[str]:
    paginator = s3.get_paginator("list_objects_v2")
    keys: list[str] = []
    for page in paginator.paginate(Bucket=CSV_BUCKET_NAME, Prefix=prefix):
        for obj in page.get("Contents", []):
            key: str = obj["Key"]
            if key.lower().endswith(".csv"):
                filename = key[len(prefix):]
                if filename and "/" not in filename:   # ← サブディレクトリを除外
                    keys.append(key)
    return keys

観察される問題

1. サブディレクトリが silent に無視される

たとえば以下のレイアウトで /admin/list-csv に testcase/F02/ を渡すと、archive/ 配下は列挙されず、利用者には「そこに CSV があるのに無視された」ことが一切見えない。

testcase/F02/
├── report_1.csv        ← 拾われる
├── report_2.csv        ← 拾われる
└── archive/
    ├── 2023_report.csv ← silent 無視
    └── 2022_report.csv ← silent 無視

また Hive 風のパーティション配置はすべて silent 無視になる:

testcase/F03/
└── year=2024/
    ├── month=01/
    │   └── sales.csv   ← silent 無視
    └── month=02/
        └── sales.csv   ← silent 無視

2. 直下に CSV が 0 件だとエラーメッセージが不親切

testcase/F01/ 直下に CSV がなく、a/foo.csv, b/bar.csv のようにサブディレクトリにだけある場合、_list_csv_files は空リストを返し、UI には「指定された prefix 配下に CSV ファイルが見つかりません」とだけ出る。実際には CSV はある（サブディレクトリに）。利用者は「無いと言われたが S3 で見ると確かにある」という状態に陥る。

3. プレフィックス末尾スラッシュ差異

testcase/F04-foo と testcase/F04-foo/ のどちらで呼んでも動くように見えるが:

• len(prefix) で filename を切り出しているので、末尾スラッシュが無いと filename の先頭が / になり、"/" not in filename チェックを必ず落ちる（= 全部サブディレクトリ扱いで 0 件）
• 末尾スラッシュの正規化が _list_csv_files 側にも _analyze_csv_file 側にも無い

期待される挙動

以下のいずれか、または組み合わせ:

1. 再帰的に列挙し、サブディレクトリ配下の CSV も analyze 対象にする（データレイク互換、Hive パーティション対応）
2. 直下優先のまま、サブディレクトリに CSV があったら UI に警告を表示する（「この prefix の下に 5 個 CSV がありますが、サブディレクトリ配下のため無視されました」）
3. 末尾スラッシュの正規化を _list_csv_files の先頭で行い、スラッシュ有無で挙動が変わらないようにする
4. 直下 0 件 + サブディレクトリ有りのときは、エラーメッセージで「サブディレクトリ内の CSV は現在サポートされていません。prefix を testcase/F01/a/ のように指定してください」とヒントを返す

再現手順（テストケース F シリーズとして生成予定）

本リポ（ogawsh fork の fork、サンプルデータ生成ツール）に以下のケースを追加予定:

• F01: 直下に CSV なし、サブディレクトリ a/, b/ 配下にだけ CSV
• F02: 直下に CSV + archive/ サブディレクトリにも CSV
• F03: Hive スタイル year=2024/month=01/... のパーティション構造
• F04: 末尾スラッシュ差異（testcase/F04-foo vs testcase/F04-foo/）

参考情報

• 関連ファイル: lambda/adminwebbackend/app.py _list_csv_files, _group_csv_by_header

[ogawsh]

Confirmed the silent-ignore behavior on an actual environment.

Setup (F01 test case):

s3://.../testcase/F01-layout-subdir-only/
├── a/sales_a1.csv   (5,000 rows)
├── a/sales_a2.csv   (5,000 rows)
└── b/sales_b1.csv   (5,000 rows)

(No CSV directly under the prefix.)

Result: Admin UI returned:

指定された prefix 配下に CSV ファイルが見つかりません

No hint whatsoever that there are 3 valid CSV files one level below. A user who can browse the bucket in the S3 console will wonder "the files are right there, why does the app say they're missing?".

Recommendation (as noted in the issue): when _list_csv_files returns 0 but a second ListObjectsV2 with no filter would return > 0, surface a hint like:

この prefix 直下には CSV が見つかりませんでした。サブディレクトリ a/, b/ の下には CSV があります。現在サブディレクトリ配下の CSV はサポートされていません。

[ogawsh]

F02 also confirms the silent-ignore behavior (this time where apply succeeds, hiding the fact that subdirectory files were dropped).

Setup (F02):

s3://.../testcase/F02-layout-mixed-subdir/
├── report_1.csv       (5,000 rows, sale_id S0000000000〜S0000004999)
├── report_2.csv       (5,000 rows, sale_id S0000005000〜S0000009999)
├── report_3.csv       (5,000 rows, sale_id S0000010000〜S0000014999)
└── archive/
    ├── 2022_report.csv (5,000 rows, sale_id S0000015000〜S0000019999)
    └── 2023_report.csv (5,000 rows, sale_id S0000020000〜S0000024999)

Expected (data engineer's intent): 25,000 rows loaded.
Actual: analyze/apply both SUCCEEDED. Redshift report table contains 15,000 rows, sale_id ranges S0000000000 through S0000014999. The archive/ folder's 10,000 rows are silently absent.

No warning on the Admin UI. No log message. A user who did not personally inspect both S3 and Redshift would have no way to notice that 40% of their data was dropped.

This is the dangerous case: F01 at least errors out loudly with "CSV が見つかりません", but F02 reports success while silently losing data. This is worse than F01 from a correctness-of-analysis perspective.

[ogawsh]

F03 confirms the Hive-partition style layout (common for data lakes / AWS Glue / Athena) is also silently unsupported.

Setup (F03):

s3://.../testcase/F03-layout-hive-partition/
└── year=2024/
    ├── month=01/sales.csv   (2,000 rows)
    ├── month=02/sales.csv   (2,000 rows)
    └── month=03/sales.csv   (2,000 rows)

Result: Admin UI returned:

指定された prefix 配下に CSV ファイルが見つかりません

Hive partitioning is standard practice in AWS data ecosystems (Glue crawlers, Athena, S3 Tables, Redshift Spectrum). Users bringing existing data lake tables into this tool will hit this immediately.

Possible approaches (aside from the ideas already listed in the issue description):

• recursive mode: auto-detect key=value/ style paths and offer partition-aware loading (perhaps auto-derive additional columns from the partition keys)
• shallow pass-through: at minimum, recurse one level to find CSVs and warn about partition-like paths so the user understands what was picked up
• explicit opt-in: a recursive=true toggle on the UI so the user can choose

[ogawsh]

F04 confirms the trailing-slash hazard.

Setup (F04):

s3://.../testcase/F04-layout-trailing-slash/
├── sales_1.csv
└── sales_2.csv

Case A: prefix input = testcase/F04-layout-trailing-slash/ (trailing /)
→ 2 files picked up, apply SUCCEEDED in 21 s.

Case B: prefix input = testcase/F04-layout-trailing-slash (no trailing /)
→ UI: "指定された prefix 配下に CSV ファイルが見つかりません"

Same bucket, same files, different UX. The cause is clear from the current implementation:

# _list_csv_files
for obj in page.get("Contents", []):
    key = obj["Key"]                      # e.g. "testcase/F04-.../sales_1.csv"
    if key.lower().endswith(".csv"):
        filename = key[len(prefix):]      # with trailing-/, "sales_1.csv"
                                          # without trailing-/, "/sales_1.csv"
        if filename and "/" not in filename:   # "/sales_1.csv" fails this check
            keys.append(key)

And the paginate(Prefix=prefix) call itself does match correctly in Case B (the files show up in S3 listing), so S3 pagination is fine. The bug is purely in the post-filter.

Fix proposal (1 line): normalize the prefix at the top of _list_csv_files:

def _list_csv_files(prefix: str) -> list[str]:
    if prefix and not prefix.endswith("/"):
        prefix = prefix + "/"
    ...

Or switch the filename check to count forward slashes after stripping the prefix properly:

rel = key[len(prefix):].lstrip("/")
if rel and "/" not in rel:
    keys.append(key)

Either approach would collapse F04-A and F04-B into the same behavior.

(_analyze_csv_file and the prefix string saved into DynamoDB should probably also be normalized with trailing slash, otherwise later operations may hit variant bugs at the edge.)