Skip to main content

job_formatter_core/
lib.rs

1//! # job-formatter-core
2//!
3//! *Industry-agnostic job-feed formatting engine: company CSV / Excel / JSON / JSONL
4//! → normalized JSONL → per-media output rows. Parallel, order-preserving, fault-isolating.*
5//!
6//! 求人フィード連携の**業界非依存基盤**。「各社のフィード(CSV / Excel / JSON / JSONL)→ 正規形(JSONL)」の取り込みと、
7//! その双対である「正規形 → 媒体別出力行」の整形、それぞれの**仕組み**を担う。
8//!
9//! ```text
10//! 会社A CSV ─┐                          ┌─→ 媒体X向け出力行
11//! 会社B CSV ─┼─→ 正規形レコード(JSONL)─┼─→ 媒体Y向け出力行
12//! 会社C CSV ─┘                          └─→ 媒体Z向け出力行
13//! ```
14//!
15//! ## 責務境界(横展開の設計)
16//!
17//! - **core(本クレート)**: アダプタの枠組み([`adapter::CompanyAdapter`])・
18//!   CSV 読取(UTF-8 / `Shift_JIS` 自動判別)・Excel 読取(feature `excel`、既定で有効)・
19//!   JSON 読取(レコードの配列。包まれていれば JSON Pointer で選ぶ)・
20//!   JSONL 読取(1 行 = 1 レコードの JSON)(いずれも UTF-8 のみ)・
21//!   独自ソースの組み立て口([`source::TableSource::new`])・列名アクセス・
22//!   レコード単位のエラー隔離・並列変換・JSONL 出力・媒体整形の枠組み
23//!   ([`media::MediaFormatter`])。レコード型に対してジェネリックで、
24//!   **業界知識・媒体知識を一切持たない**
25//! - **ドメインクレート**(業界ごと): 正規形レコード型の定義、各社アダプタ実装
26//!   (列マッピング・社別クレンジング)、CLI。タグ付けなど後段の加工もドメイン側に置く
27//! - **媒体実装**(出力先ごと、呼び出し側 — バーティカルの media モジュール等):
28//!   [`media::MediaFormatter`] の実装。マスタ ID 変換・出力形式・媒体検証などの
29//!   知識はすべて媒体側が持つ
30//!
31//! ## 速度
32//!
33//! 行単位の変換([`adapter::convert_source`])・媒体整形([`media::format_records`])・
34//! シリアライズ([`output::write_jsonl`])は rayon で並列実行し、入力順を保持する。
35//! 直列なのは入力の読み取りと構造の解析(CSV のパース・JSON の走査)、出力の書き込みのみ。
36//!
37//! ## 使い方
38//!
39//! ### 取り込み(各社のフィード → 正規形)
40//!
41//! ```
42//! use job_formatter_core::adapter::{CompanyAdapter, convert_source};
43//! use job_formatter_core::error::RecordError;
44//! use job_formatter_core::row::Row;
45//! use job_formatter_core::source::TableSource;
46//! use serde::Serialize;
47//!
48//! #[derive(Serialize)]
49//! struct MyJob {
50//!     job_no: String,
51//!     title: String,
52//! }
53//!
54//! struct MyAgentAdapter;
55//!
56//! impl CompanyAdapter for MyAgentAdapter {
57//!     type Record = MyJob;
58//!
59//!     fn company_id(&self) -> &'static str {
60//!         "my-agent"
61//!     }
62//!
63//!     fn required_columns(&self) -> &'static [&'static str] {
64//!         &["求人番号", "タイトル"]
65//!     }
66//!
67//!     fn convert(&self, row: &Row<'_>) -> Result<Self::Record, RecordError> {
68//!         Ok(MyJob {
69//!             job_no: row.require("求人番号")?.to_string(),
70//!             title: row.require("タイトル")?.to_string(),
71//!         })
72//!     }
73//! }
74//!
75//! # fn main() -> Result<(), job_formatter_core::error::ConvertError> {
76//! let csv = "求人番号,タイトル\nJ1,スタッフ募集\nJ2,\n";
77//! let source = TableSource::from_csv_bytes(csv.as_bytes(), "agent.csv")?;
78//! // Excel なら TableSource::from_xlsx_path、独自形式なら TableSource::new で同じ流れに載る。
79//! // JSON / JSONL(from_json_path / from_jsonl_path)は列が `record` 1 つなので、
80//! // それを serde で読む別のアダプタが要る(tests/convert.rs の JsonAdapter を参照)
81//! let outcome = convert_source(&MyAgentAdapter, &source)?;
82//! assert_eq!(outcome.records.len(), 1);   // J2 はタイトル空で隔離
83//! assert_eq!(outcome.errors.len(), 1);
84//! # Ok(())
85//! # }
86//! ```
87//!
88//! ### 媒体整形(正規形 → 媒体別 JSONL)
89//!
90//! ```
91//! use job_formatter_core::error::RecordError;
92//! use job_formatter_core::media::{MediaFormatter, format_records};
93//! use job_formatter_core::output::write_jsonl;
94//! use serde::Serialize;
95//!
96//! struct MyJob {
97//!     job_no: String,
98//!     employments: Vec<String>,
99//! }
100//!
101//! #[derive(Serialize)]
102//! struct MyMediaRow {
103//!     job_no: String,
104//!     employment: String,
105//! }
106//!
107//! struct MyMediaFormatter;
108//!
109//! impl MediaFormatter for MyMediaFormatter {
110//!     type Record = MyJob;
111//!     type Output = MyMediaRow;
112//!
113//!     fn media_id(&self) -> &'static str {
114//!         "my-media"
115//!     }
116//!
117//!     fn format(&self, record: &MyJob) -> Result<Vec<MyMediaRow>, RecordError> {
118//!         // 雇用形態ごとに 1 行へ展開。0 行なら「この媒体では出力しない」(選別)
119//!         Ok(record
120//!             .employments
121//!             .iter()
122//!             .map(|employment| MyMediaRow {
123//!                 job_no: record.job_no.clone(),
124//!                 employment: employment.clone(),
125//!             })
126//!             .collect())
127//!     }
128//! }
129//!
130//! # fn main() -> Result<(), job_formatter_core::error::OutputError> {
131//! let jobs = vec![
132//!     MyJob { job_no: "J1".into(), employments: vec!["正社員".into(), "パート".into()] },
133//!     MyJob { job_no: "J2".into(), employments: vec![] },
134//! ];
135//! let outcome = format_records(&MyMediaFormatter, &jobs);
136//! assert_eq!(outcome.rows.len(), 2);   // J1 は 2 行に展開、J2 は選別(エラーではない)
137//! assert!(outcome.errors.is_empty());
138//! let mut jsonl = Vec::new();
139//! write_jsonl(&mut jsonl, &outcome.rows)?;
140//! # Ok(())
141//! # }
142//! ```
143
144pub mod adapter;
145pub mod error;
146pub mod media;
147pub mod output;
148pub mod row;
149pub mod source;