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;