DEV Community: hoyeon

Keep shipping quotes honest with versioned inputs

hoyeon — Wed, 23 Sep 2026 13:18:10 +0000

Disclosure: I am involved with Kimfast, a package-forwarding service. I used AI to help structure and edit this article. The code below is a standalone design example, not a claim about Kimfast's production implementation or conversion results.

A quote is more than one displayed number. A customer may enter a product link before purchase, while the warehouse later measures a packed parcel. If the UI shows both values as “shipping cost” without their inputs and timestamps, a reasonable user may treat an estimate as a final charge.

Model the evidence, not only the amount

A small quote record can preserve its source and state:

enum QuoteStage { PRE_PURCHASE_ESTIMATE, PACKED_MEASUREMENT, FINAL_AMOUNT }

record QuoteSnapshot {
country: string
stage: QuoteStage
amount: Decimal
currency: string
measuredWeightKg: Decimal | null
observedAt: timestamp
policyVersion: string
}

This is language-neutral pseudocode. The stage names are not a proposed public API. The useful constraint is that every amount has a country, a meaning, and the policy version used to calculate it. A later calculation creates a new snapshot instead of silently overwriting an older one.

Three invariants worth testing

Do not relabel an estimate as final. A UI component should render the stage with the amount. If the packed measurement is unavailable, it must not invent one from the product listing.

Do not reuse a quote across countries. A link for one forwarding route does not establish the cost of another. Validate the country code against the quote and the route before showing a comparison.

Do not compare unlike inputs. If one amount includes a warehouse measurement and another uses a seller's stated weight, show that difference before calculating a “savings” figure. A price comparison needs the same scope and included services.

A review table makes the boundary explicit:

Input	What the UI can say	What it must not infer
Product URL only	Estimated amount under stated assumptions	Final packed weight
Warehouse measurement	Amount based on observed package dimensions	Customs outcome or delivery date
Confirmed final amount	Charge and the applicable conditions	That all future orders cost the same

Make change observable

Keep the old snapshot when a pricing rule changes. The support team should be able to answer: which inputs produced the figure the customer saw, when was it shown, and which version of the rules was in effect? That is more useful than storing only the last amount.

The public Kimfast Spain forwarding guide describes an order flow in which the parcel is measured before payment. It is a reference for the user-facing sequence, not evidence that Kimfast has adopted the record structure above. Any quoted price or service condition should be checked against the current guide before a product screen or an external article repeats it.

Where to start

Before changing code, collect one example of each stage from the current product flow without exposing customer data. Label every UI amount with its source, units, and date. Then test transitions with missing measurements, changed country selection, and a price-rule update. If the UI cannot explain why two amounts differ, adding more decimal places will not resolve the underlying ambiguity.

A forwarding form becomes more trustworthy when the system can explain the number it shows and the conditions under which that number may change.

Backlinks as structured observations: designing a conservative link-audit result

hoyeon — Mon, 21 Sep 2026 15:34:32 +0000

A backlink audit is easier to debug when it returns observations rather than a single success flag. A page can be reachable while its link is missing; a link can exist while the checker has no evidence about indexing.

This article proposes a small data contract for that distinction. It is a design note prepared with AI assistance, not a production benchmark.

Keep evidence separate from conclusions

For each check, record:

source URL and intended destination;
check timestamp and observation method (raw HTML or rendered DOM);
fetch outcome, including timeout and access denial;
observed href, anchor text, and rel tokens;
redirect destination, if actually followed;
scope limitations.

An empty list of anchors is meaningful only if you successfully inspected the relevant document. If the request failed, an empty list says nothing about the page's links.

Use explicit states

A minimal result can look like this:

{
  "fetch_state": "ok",
  "document_scope": "raw_html",
  "link_state": "present",
  "observed_href": "https://example.org/guide",
  "rel": ["ugc", "nofollow"],
  "index_state": "not_checked",
  "referral_state": "not_measured"
}

In this contract, present means the expected anchor was observed. It does not mean that the link passes ranking value or has generated visits. Likewise, nofollow belongs in metadata, not in a missing-link bucket.

A reducer with a conservative failure path

def link_state(fetch_state, document_complete, matching_anchor_count):
    if fetch_state != "ok" or not document_complete:
        return "unknown"
    return "present" if matching_anchor_count > 0 else "absent_in_observed_document"

assert link_state("timeout", False, 0) == "unknown"
assert link_state("denied", False, 0) == "unknown"
assert link_state("ok", False, 0) == "unknown"
assert link_state("ok", True, 1) == "present"
assert link_state("ok", True, 0) == "absent_in_observed_document"

These are illustrative assertions for the reducer, not evidence about any external website. The caller must decide what complete means. Raw HTML can be complete as an HTTP response while still lacking links added by JavaScript.

What to test around the reducer

Use fixtures for plain URL text, an anchor with href, a relative link, a different subdomain, a redirect, and a lookalike hostname. Match hosts using a URL parser rather than substring checks. Decide explicitly whether www and other subdomains belong to the same target set. Resolve relative links against the observed page URL before matching.

In a scheduled job, preserve the last successful observation and the latest attempt separately. An outage should not silently overwrite a previously observed link with a deletion claim. Retry conservatively and honor the site's access rules.

Where human review still matters

A technically present anchor can point to the wrong guide or appear in an irrelevant paragraph. A reviewer should assess the surrounding explanation and whether the destination answers the reader's question. That is an editorial decision, not a parser feature.

Google's link documentation provides the crawlable-anchor guidance. The contract above is one implementation proposal; it does not describe Google's internal systems.

Disclosure: I am involved in Keyserp. This example is shared as a technical design note about backlinks and evidence handling. It was prepared with AI assistance and makes no ranking or conversion claims.

스페인·미국·영국 배송대행 콘텐츠의 데이터 설계: 검색어와 운영 사실 분리하기

hoyeon — Mon, 21 Sep 2026 15:34:18 +0000

배송대행 안내 페이지를 여러 국가로 나눌 때 URL 경로만 바꾸면 운영 정보가 섞이기 쉽습니다. 이 글은 김빠른을 예시로, 검색어와 검증된 운영 정보를 서로 다른 필드로 관리하는 데이터 설계 제안입니다. 실제 운영 시스템에 배포했다는 사례나 성과 보고는 아닙니다.

키워드는 사실 데이터가 아닙니다

스페인 배송대행, 미국 배송대행, 영국 배송대행은 콘텐츠 기획에 쓰는 표현입니다. LA 배송대행도 검색어 후보가 될 수 있지만, 그 문자열만으로 LA 거점이 존재한다고 추론해서는 안 됩니다.

따라서 검색어를 warehouse_city 같은 운영 필드에 자동으로 복사하지 않습니다. 이 원고에서는 김빠른의 LA 거점을 검증하지 않았습니다.

데이터 구조를 분리합니다

def make_brief(keyword, country, verified_city=None):
    return {
        "editorial": {"keyword": keyword, "country": country},
        "operations": {"verified_city": verified_city},
        "review": {"city_claim_allowed": verified_city is not None},
    }

brief = make_brief("LA 배송대행", "US")
assert brief["operations"]["verified_city"] is None
assert brief["review"]["city_claim_allowed"] is False

위 코드는 최소 설계 예시입니다. 실무에서는 verified_city라는 변수명만 믿으면 안 됩니다. 출처 URL, 확인 시각, 검토자, 유효 기간까지 함께 저장해야 합니다. 오래된 확인은 최신 사실과 같지 않습니다.

생성 프롬프트에는 미확인 상태를 전달합니다

“editorial은 독자의 관심사이고 operations만 운영 사실이다. verified_city가 null이면 도시 거점을 단정하지 마라. 부족한 정보를 채우지 말고 review_required에 기록하라.”

이 지시도 모델의 오류를 완전히 막지는 못합니다. 생성 후 도시·가격·기간 같은 주장을 추출해 근거표와 대조하는 검수 단계가 필요합니다. 문장에 링크가 붙어 있다는 이유만으로 근거가 일치한다고 판단하면 안 됩니다.

페이지 연결은 별도 매핑으로 둡니다

실제 국가별 안내의 예시는 김빠른 스페인 배송대행, 미국 배송대행, 영국 배송대행입니다. 링크는 각 국가의 안내 경로를 보여주는 예시이며, 이 글의 코드가 해당 사이트에 적용됐다는 뜻은 아닙니다.

국가 코드를 URL에 매핑할 때 기본값을 아무 국가로 두지 않는 편이 좋습니다. 알 수 없는 국가 코드라면 오류를 반환하거나 사람이 확인하도록 해야 합니다. 누락된 국가를 미국으로 처리하면 잘못된 안내로 이어질 수 있습니다.

테스트 계획

확인 자료가 없는 도시, 만료된 자료, 알 수 없는 국가 코드, 빈 키워드, 국가와 목적지 URL이 다른 입력을 각각 테스트 대상으로 둡니다. 위 예시 두 assertion은 설계 의도를 보여주지만, 실제 서비스 검증을 대신하지는 않습니다.

이해관계 공개: 작성자는 김빠른 운영에 참여합니다. AI의 도움으로 작성한 개발 설계 제안이며, 배포 완료나 고객 성과를 주장하지 않습니다.

A link checker needs an unknown state, not just true or false

hoyeon — Fri, 18 Sep 2026 10:58:02 +0000

Disclosure: I work on Keyserp. This article was generated by an AI agent at the account owner’s request, using the design of our internal article-monitoring tool as context. It has not received independent human editorial review. It is a design note, not a claim about search rankings or a public product release.

The boolean that loses information

A published-page checker seems like a simple function: fetch a URL and return true or false. But a timeout, a login wall, and a missing article are three different observations. Mapping all three to false gives an operator the wrong next action.

Our internal workflow tracks whether an external article remains readable and whether its expected reference is present. The important design decision was to preserve uncertainty instead of hiding it behind a green or red badge.

Keep observations separate from conclusions

A useful result has at least these fields:

requested URL and final URL after redirects
checked-at timestamp
transport outcome and HTTP status, if available
whether the article body was identified
whether an article-specific text marker matched
whether the expected link was found inside that body
a reason for any unknown result

Use null for a link that could not be checked. Reserve false for a completed inspection that did not find it. A missing observation should not silently become negative evidence.

A small decision table

Observation	Classification	Next action
Timeout or access denial	Unknown	Retry later within the site's limits
Successful response showing a login page	Unknown	Check permitted access manually
Expected article body and expected link	Verified at this time	Schedule the next check
Expected article body, complete inspection, no expected link	Link not found	Review the article
404 or 410	Missing response observed	Recheck before escalating
Body selector no longer matches	Unknown	Review the site adapter

These are illustrative fixtures, not measured incident counts. A repeated missing response may justify a removal-suspected state; it still does not prove why the publisher removed anything.

Link matching deserves its own contract

A domain appearing somewhere in the HTML is weak evidence. Navigation, comments, related articles, and advertising can all contain links outside the author's text.

Scope the inspection to the identified article body. Resolve relative URLs against the final page URL. Then compare the parsed destination with the explicitly configured target. Do not use substring matching: an unrelated hostname can contain your domain as text.

Decide deliberately whether trailing slashes, query parameters, or fragments are significant for each target. Do not strip every query parameter by default; some applications use them to identify the resource. If a publisher wraps links through a redirect service, report that wrapper as an observation and review it separately instead of declaring a direct match.

Store the observed anchor text and rel attribute as evidence. Finding a link does not establish that a search engine indexed it or assigned it value.

Tests that challenge the happy path

Before connecting a classifier to live pages, I would give it fixtures that deliberately look almost correct:

A 200 login page with the expected domain in its footer.
The correct article with the target link only in a reader comment.
The correct article with a relative link that resolves to a different destination.
An article shell whose body is rendered only after JavaScript runs.
The expected article with no link after a complete body inspection.
A transient missing response followed by a successful check.

The expected outcome for the first four is unknown or a narrowly described mismatch, depending on what the adapter actually inspected. It should never be verified merely because a string was found.

Fixture tests establish classifier behavior. They do not establish that a live publisher's current markup is supported. Record those two checks separately.

A checker should not become a publisher

An unknown or missing result should create a review task, not automatically repost the article. Otherwise a temporary outage can turn into duplicate content and unwanted community activity.

The same boundary helps with alerting: keep the last verified observation visible alongside the latest failed attempt. That tells an operator what was known, when it was known, and what changed.

Our tool is still internal, and long-term resilience to layout changes remains an open operational question. The practical lesson is to design the unknown state before automating the next action.

Affiliation: Keyserp. I have an operational interest in the service mentioned here.