tiennm99bot/plans/260818-2158-amlich-converter-improvements/phase-02-handler-replies.md

phase, title, status, effort, priority, dependencies

phase	title	status	effort	priority	dependencies
2	Handler replies	completed	S	P2	1

Phase 2: Handler replies

Overview

Wire the leap-month hint into /duonglich and the razor-edge caveat into both commands. Reply sentences gain optional trailing lines only; existing first-line format is unchanged.

Requirements

• Functional (/duonglich hint): after a successful conversion with leap == false, if lunarToSolar(day, month, year, true) returns nil error, append: Lưu ý: năm âm lịch <year> có tháng <month> nhuận — thêm "nhuan" nếu ý bạn là tháng nhuận.
• Functional (caveat, both commands): if nearDisputedBoundary(jd) — where jd is the solar JD of the queried/resulting date — append: Lưu ý: ngày này gần ranh giới tháng âm lịch chưa chắc chắn; kết quả có thể lệch 1 ngày so với lịch chính thức sau này.
• Hint NOT shown when nhuan was explicit (user already disambiguated) or when the exact leap date doesn't exist. Both lines may co-occur (hint first, then caveat), each on its own line after the main sentence, separated by \n.
• Non-functional: no change to usage strings, error paths, or year-range checks.

Architecture

• /amlich: jd := jdFromDate(day, month, year) (already-parsed solar input) → caveat check.
• /duonglich: caveat check on jdFromDate(solarDay, solarMonth, solarYear) from the conversion result; hint check via the leap-variant probe before assembling the reply.
• Message constants live next to the usage constants in handlers.go.

Related Code Files

• Modify: internal/modules/amlich/handlers.go
• Modify: internal/modules/amlich/handlers_test.go

Implementation Steps

1. Add the two message constants (hint as format string taking year + month).
2. /duonglich: after successful lunarToSolar, build reply, conditionally append hint (probe with leap=true only when input leap == false), then conditionally append caveat.
3. /amlich: conditionally append caveat after the main sentence.
4. Tests (extend existing fake-reply pattern in handlers_test.go):
   • /duonglich 5/5/2028 → hint present (2028 has leap 5); /duonglich 5/5/2028 nhuan → absent; /duonglich 5/5/2027 → absent (no leap 5 in 2027).
   • /amlich on a date inside the disputed month at 09/12/2072 → caveat present; ordinary date → absent. /duonglich case whose result lands in that month → caveat present.
   • Assert exact full reply strings (repo test style asserts exact text — keep it strict).

Success Criteria

• Hint behavior matches the three /duonglich cases above
• Caveat fires for disputed-month dates in both commands, silent elsewhere
• All pre-existing handler tests pass without assertion loosening

Risk Assessment

• Double-probe cost: one extra lunarToSolar call per leap-year query — microseconds, irrelevant.
• Wording is user-visible contract; if the user wants different Vietnamese phrasing, only the constants change. Flag wording in the PR description for review.