feat: add true solar time resolution

Author: jiwenxu025-boop

README.md

@@ -8,6 +8,7 @@
 
 ### 精确排盘
 - **四柱计算** — 年/月/日/时柱，ephem 天文库节气精度 ±1 秒
+- **真太阳时口径** — 选择内置城市时按经度与均时差校正；城市未知时严格保留用户输入时间，不伪造地点精度
 - **藏干十神** — 地支藏干（本气/中气/余气），天干十神定位
 - **格局判定** — 月令透干优先 + 建禄/羊刃特殊处理
 - **神煞检测** — 天乙贵人/红鸾/天喜/桃花/驿马/文昌/羊刃/灾煞/丧门/吊客
@@ -82,6 +83,8 @@ python -m uvicorn bazi_engine.api:app --host 0.0.0.0 --port 8000
 
 浏览器打开 `http://localhost:8000` 使用前端界面。
 
+出生城市由本地清单搜索选择；未选城市默认“未知”。高级设置可填写手动经度和时区。时间口径、校正分钟数、UTC 出生瞬间和最终排盘时间会写入报告元数据，详见 [时间口径](docs/time-basis.md)。
+
 ### 测试
 
 ```bash

docs/time-basis.md

@@ -0,0 +1,38 @@
+# 出生时间与真太阳时口径
+
+## 默认行为
+
+- 出生城市默认“未知”。未知城市按用户录入的钟表时间排盘，默认时区为中国标准时间 `UTC+8`。
+- 从内置城市清单选择地点后，系统默认使用真太阳时。
+- 高级设置的手动经度优先于城市经度；时区偏移可同时手动指定。
+- 运行时不调用第三方地理编码、定位或地图服务。城市名称的自由输入不作为经度来源，只有从内置清单选中后才会启用城市经度。
+
+## 两条时间线
+
+每次排盘都会保留三种可追溯时间：
+
+| 名称 | 用途 |
+|---|---|
+| 输入民用时间 | 用户出生记录、年龄计算与报告原始输入 |
+| 真实出生瞬间 | 将输入时间按时区换算为 UTC；用于节气、年柱、月柱、起运与交运距离 |
+| 最终排盘时间 | 输入民用时间加真太阳时校正；用于日柱、时柱、命宫、身宫、小运与时柱下游规则 |
+
+真太阳时校正使用：
+
+`均时差 + 4 × (经度 - 时区中央经线)` 分钟。
+
+均时差采用 NOAA 的标准近似式。报告会显示总校正分钟数及最终排盘时间；它不是对出生记录本身精确性的证明。
+
+## 23 点边界
+
+无论城市是否已知，最终排盘时间在 `23:00` 至 `23:59` 时，日柱统一按次日计算。年柱、月柱和起运仍使用真实出生瞬间，不会因真太阳时跨日而重算。
+
+## 准确度与历史报告
+
+`time_accuracy` 表示出生记录精度（分钟、时辰或未知），与 `hour_confirmed` 的分析确认状态独立保存。报告元数据从 `schema_version 1.1` 起记录 `time_resolution_version: 2.0`、城市清单版本、时间模式、UTC 瞬间、经度来源与最终排盘时间。
+
+旧报告不会在读取时自动套用新算法。只有新的排盘请求会生成新的时间口径元数据。
+
+## 城市清单范围
+
+当前内置清单版本为 `cn-major-cities-v1`，覆盖省会、直辖市、特别行政区及常用主要城市，坐标为城市中心经度。它不把未覆盖的县区、乡镇或同名地自动映射到附近城市；遇到未列地点应保持“未知”或由用户在高级设置填写经度。后续扩充必须随清单版本、坐标来源与回归用例一起提交。

frontend/app.js

@@ -55,6 +55,7 @@ document.getElementById('themeToggle').addEventListener('click', toggleTheme);
    Form: Enter to submit
    ========================================== */
 document.getElementById('formCard').addEventListener('keydown', function(e){
+  if (e.target && e.target.id === 'citySearch') return;
   if (e.key === 'Enter') {
     e.preventDefault();
     go();
@@ -78,6 +79,177 @@ function updateHourHint(){
 document.getElementById('hourConfirmed').addEventListener('change', updateHourHint);
 updateHourHint();
 
+/* ==========================================
+   Birth place and time basis
+   ========================================== */
+let LocationState = {
+  city: null,
+  citySearchTimer: null,
+  previewTimer: null,
+  requestId: 0,
+  previewRequestId: 0,
+};
+
+function getApiBase(){
+  return document.getElementById('apiUrl').value.replace(/\/$/, '');
+}
+
+function getLocationPayload(){
+  let longitude = document.getElementById('longitude').value.trim();
+  let timezoneOffset = document.getElementById('timezoneOffset').value.trim();
+  return {
+    city_id: LocationState.city ? LocationState.city.id : null,
+    longitude: longitude === '' ? null : Number(longitude),
+    timezone_offset_minutes: timezoneOffset === '' ? null : Number(timezoneOffset),
+    requested_time_mode: 'auto',
+    time_accuracy: document.getElementById('timeAccuracy').value,
+  };
+}
+
+function setTimeBasisNote(text){
+  let note = document.getElementById('timeBasisNote');
+  if (note) note.textContent = text;
+}
+
+function hideCityOptions(){
+  let options = document.getElementById('cityOptions');
+  let search = document.getElementById('citySearch');
+  options.hidden = true;
+  search.setAttribute('aria-expanded', 'false');
+}
+
+function selectCity(city){
+  LocationState.city = city;
+  document.getElementById('citySearch').value = city.name;
+  hideCityOptions();
+  queueTimePreview();
+}
+
+function clearCity(){
+  LocationState.city = null;
+  document.getElementById('citySearch').value = '';
+  hideCityOptions();
+  queueTimePreview();
+}
+
+function renderCityOptions(items){
+  let options = document.getElementById('cityOptions');
+  let search = document.getElementById('citySearch');
+  if (!items.length){
+    options.hidden = true;
+    search.setAttribute('aria-expanded', 'false');
+    return;
+  }
+  let html = '';
+  for (let i = 0; i < items.length; i++){
+    let city = items[i];
+    html += '<button type="button" class="city-option" role="option" aria-selected="false" data-city-id="' + esc(city.id) + '">';
+    html += '<span>' + esc(city.name) + '</span><small>' + esc(city.province || '') + '</small></button>';
+  }
+  options.innerHTML = html;
+  options.hidden = false;
+  search.setAttribute('aria-expanded', 'true');
+  let buttons = options.querySelectorAll('.city-option');
+  for (let i = 0; i < buttons.length; i++){
+    buttons[i].addEventListener('click', function(){
+      for (let j = 0; j < items.length; j++){
+        if (items[j].id === this.dataset.cityId){
+          selectCity(items[j]);
+          return;
+        }
+      }
+    });
+  }
+}
+
+function searchCities(){
+  let search = document.getElementById('citySearch');
+  let query = search.value.trim();
+  if (!query){
+    hideCityOptions();
+    return;
+  }
+  let requestId = ++LocationState.requestId;
+  fetch(getApiBase() + '/api/locations?q=' + encodeURIComponent(query))
+    .then(function(response){ return response.ok ? response.json() : {items: []}; })
+    .then(function(data){
+      if (requestId !== LocationState.requestId) return;
+      renderCityOptions(Array.isArray(data.items) ? data.items : []);
+    })
+    .catch(function(){ hideCityOptions(); });
+}
+
+function scheduleCitySearch(){
+  let search = document.getElementById('citySearch');
+  if (LocationState.city && search.value !== LocationState.city.name) LocationState.city = null;
+  window.clearTimeout(LocationState.citySearchTimer);
+  LocationState.citySearchTimer = window.setTimeout(searchCities, 160);
+  queueTimePreview();
+}
+
+function timeFieldsAreComplete(){
+  let fields = ['year', 'month', 'day', 'hour', 'minute'];
+  for (let i = 0; i < fields.length; i++){
+    let value = document.getElementById(fields[i]).value;
+    if (value === '') return false;
+  }
+  return true;
+}
+
+function formatTimeBasisPreview(preview){
+  if (preview.effective_time_mode !== 'true_solar'){
+    setTimeBasisNote('出生地未知：按输入时间排盘，默认采用中国标准时间（UTC+8）。');
+    return;
+  }
+  let correction = Number(preview.solar_correction_minutes || 0);
+  let signed = (correction >= 0 ? '+' : '') + correction.toFixed(1);
+  let city = preview.city ? preview.city.label : '手动经度';
+  let rollover = preview.day_pillar_uses_next_date ? '；23 点后按次日子时取日柱' : '';
+  setTimeBasisNote(city + '：真太阳时 ' + preview.pillar_time + '（校正 ' + signed + ' 分钟）' + rollover + '。');
+}
+
+function requestTimePreview(){
+  if (!timeFieldsAreComplete()) return;
+  let previewRequestId = ++LocationState.previewRequestId;
+  let payload = getLocationPayload();
+  payload.year = Number(document.getElementById('year').value);
+  payload.month = Number(document.getElementById('month').value);
+  payload.day = Number(document.getElementById('day').value);
+  payload.hour = Number(document.getElementById('hour').value);
+  payload.minute = Number(document.getElementById('minute').value);
+  fetch(getApiBase() + '/api/time/preview', {
+    method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify(payload),
+  }).then(function(response){
+    return response.ok ? response.json() : null;
+  }).then(function(preview){
+    if (preview && previewRequestId === LocationState.previewRequestId) formatTimeBasisPreview(preview);
+  }).catch(function(){
+    if (previewRequestId === LocationState.previewRequestId) {
+      setTimeBasisNote('出生地未知：按输入时间排盘，默认采用中国标准时间（UTC+8）。');
+    }
+  });
+}
+
+function queueTimePreview(){
+  window.clearTimeout(LocationState.previewTimer);
+  LocationState.previewTimer = window.setTimeout(requestTimePreview, 180);
+}
+
+document.getElementById('citySearch').addEventListener('input', scheduleCitySearch);
+document.getElementById('citySearch').addEventListener('keydown', function(event){
+  if (event.key !== 'Enter') return;
+  let options = document.querySelectorAll('#cityOptions .city-option');
+  if (!options.length) return;
+  event.preventDefault();
+  options[0].click();
+});
+document.getElementById('citySearch').addEventListener('blur', function(){ window.setTimeout(hideCityOptions, 120); });
+document.getElementById('cityClear').addEventListener('click', clearCity);
+['year', 'month', 'day', 'hour', 'minute', 'longitude', 'timezoneOffset', 'timeAccuracy'].forEach(function(id){
+  document.getElementById(id).addEventListener('input', queueTimePreview);
+  document.getElementById(id).addEventListener('change', queueTimePreview);
+});
+
 /* ==========================================
    Shared app state
    ========================================== */
@@ -309,6 +481,14 @@ function _buildChartParams(){
     hour_confirmed: document.getElementById('hourConfirmed').checked,
     practical: true,  // 公网只显示白话解读，不暴露技术推导
   });
+  let location = getLocationPayload();
+  if (location.city_id) params.set('city_id', location.city_id);
+  if (location.longitude !== null && Number.isFinite(location.longitude)) params.set('longitude', String(location.longitude));
+  if (location.timezone_offset_minutes !== null && Number.isFinite(location.timezone_offset_minutes)) {
+    params.set('timezone_offset_minutes', String(location.timezone_offset_minutes));
+  }
+  params.set('requested_time_mode', location.requested_time_mode);
+  params.set('time_accuracy', location.time_accuracy);
   if (lnFrom) params.set('liunian_from', lnFrom);
   if (lnTo) params.set('liunian_to', lnTo);
   let lsOverride = sessionStorage.getItem('bazi-life-stage');
@@ -352,7 +532,7 @@ async function go(){
   document.getElementById('copyBtn').style.display = 'none';
   document.getElementById('reportActions').classList.remove('active');
 
-  let api = document.getElementById('apiUrl').value.replace(/\/$/, '');
+  let api = getApiBase();
   let payload = _buildChartRequest();
   let controller = beginStreamRequest('chart');
 
@@ -1437,7 +1617,18 @@ function render(d){
     let daySource = traceability.day_pillar_source === 'override' ? '用户提供的日柱覆盖' : '公式计算';
     h += '<details class="evidence-details" style="margin-bottom:16px"><summary>报告依据与边界</summary>';
     h += '<div class="evidence-scale-content">';
-    h += '<div>出生时间：' + esc(input.birth_time || d.birth || '') + '（分钟精度）</div>';
+    let accuracyLabels = {minute: '精确到分钟', hour: '仅确认时辰', unknown: '时间不确定'};
+    let accuracy = accuracyLabels[input.time_accuracy || input.time_precision] || '未说明';
+    let isTrueSolar = input.effective_time_mode === 'true_solar';
+    let cityLabel = input.city && input.city.label ? input.city.label : '未知';
+    h += '<div>出生时间：' + esc(input.birth_time || d.birth || '') + '（' + esc(accuracy) + '）</div>';
+    if (isTrueSolar){
+      let correction = Number(input.solar_correction_minutes || 0);
+      let signed = (correction >= 0 ? '+' : '') + correction.toFixed(1);
+      h += '<div>排盘时间：' + esc(input.pillar_time || '') + '（' + esc(cityLabel) + '真太阳时，校正 ' + esc(signed) + ' 分钟）</div>';
+    } else {
+      h += '<div>排盘时间：按输入时间；出生地：' + esc(cityLabel) + '（默认 UTC+8）</div>';
+    }
     h += '<div>日柱来源：' + esc(daySource) + '；流年信号：' + esc(signalSources) + '</div>';
     h += '<div>' + esc(uncertainty.scope || '传统文化参考，不构成对具体事件的确定性判断') + '</div>';
     h += '</div></details>';

frontend/index.html

@@ -6,7 +6,7 @@
 <title>八字解读</title>
 <script>(function(){var t=localStorage.getItem('bazi-theme');if(t==='dark'||(!t&&window.matchMedia('(prefers-color-scheme:dark)').matches))document.documentElement.classList.add('dark')})()</script>
 <link rel="icon" href="favicon.svg?v=20260716" type="image/svg+xml">
-<link rel="stylesheet" href="style.css?v=20260718-birth-layout1">
+<link rel="stylesheet" href="style.css?v=20260718-time-resolution1">
 <link rel=stylesheet href=chat.css>
 </head>
 <body>
@@ -45,7 +45,15 @@ <h1>八字解读</h1>
     <label><span>时</span><input id="hour" type="number" placeholder="12" min="0" max="23"></label>
     <label><span>分</span><input id="minute" type="number" placeholder="00" min="0" max="59" value="0"></label>
   </div>
-  <p class="time-basis-note">出生时间按中国标准时间（UTC+8）计算，暂不自动校正真太阳时。</p>
+  <div class="birth-location-row">
+    <label for="citySearch"><span>出生城市（默认未知）</span></label>
+    <div class="city-picker">
+      <input id="citySearch" type="search" placeholder="搜索内置城市，如成都" autocomplete="off" role="combobox" aria-autocomplete="list" aria-expanded="false" aria-controls="cityOptions">
+      <button type="button" class="city-clear" id="cityClear" title="清除城市" aria-label="清除城市">&times;</button>
+      <div class="city-options" id="cityOptions" role="listbox" hidden></div>
+    </div>
+  </div>
+  <p class="time-basis-note" id="timeBasisNote">出生地未知：按输入时间排盘，默认采用中国标准时间（UTC+8）。</p>
   <div class="form-row" style="margin-bottom:6px">
     <label style="flex-direction:row;align-items:center;gap:8px;font-size:13px;color:var(--text-secondary)">
       <input type="checkbox" id="hourConfirmed" style="width:16px;height:16px;accent-color:var(--accent);cursor:pointer">
@@ -55,6 +63,11 @@ <h1>八字解读</h1>
   </div>
   <details class="advanced-options">
     <summary>高级设置</summary>
+    <div class="form-row advanced-time-grid" style="margin-top:10px">
+      <label><span>出生记录精度</span><select id="timeAccuracy"><option value="minute">精确到分钟</option><option value="hour">仅确认时辰</option><option value="unknown">时间不确定</option></select></label>
+      <label><span>手动经度（东经为正）</span><input id="longitude" type="number" step="0.0001" min="-180" max="180" placeholder="可选"></label>
+      <label><span>时区偏移（分钟）</span><input id="timezoneOffset" type="number" min="-720" max="840" value="480"></label>
+    </div>
     <div class="form-row" style="margin-top:10px">
       <label><span>流年范围</span><input id="lnFrom" type="number" placeholder="2026" min="1900" max="2100"></label>
       <label><span>至</span><input id="lnTo" type="number" placeholder="2031" min="1900" max="2100"></label>
@@ -88,7 +101,7 @@ <h3>日主详情 <button class="modal-close" id="modalClose">&times;</button></h
   <button type="button" onclick="window.scrollTo({top:0,behavior:'smooth'})">顶部</button>
 </div>
 
-<script src="app.js?v=20260718-ai-review1"></script>
+<script src="app.js?v=20260718-time-resolution1"></script>
 
 <!-- ═══ Chat Toggle ═══ -->
 <button class=chat-toggle id=chatToggle onclick=toggleChat() title="AI 追问">💬<span class=badge id=chatBadge></span></button>

frontend/style.css

@@ -142,6 +142,32 @@ body{
 .birth-date-context{grid-column:1 / 4}
 .birth-time-context{grid-column:4 / 6}
 .birth-datetime-grid label{grid-row:2;min-width:0}
+.birth-datetime-grid label span{white-space:nowrap}
+.birth-location-row{margin:-2px 0 12px}
+.birth-location-row > label{display:block;margin-bottom:4px}
+.birth-location-row > label span{font-size:12px;font-weight:500;color:var(--text-secondary)}
+.city-picker{position:relative}
+.city-picker input{padding-right:40px}
+.city-clear{
+  position:absolute;right:6px;top:50%;transform:translateY(-50%);
+  width:28px;height:28px;border:0;background:transparent;color:var(--text-tertiary);
+  font-size:22px;line-height:1;cursor:pointer;
+}
+.city-clear:hover{color:var(--text)}
+.city-options{
+  position:absolute;z-index:30;left:0;right:0;top:calc(100% + 4px);
+  max-height:228px;overflow-y:auto;background:var(--surface);border:1px solid var(--border);
+  border-radius:var(--radius-sm);box-shadow:var(--shadow-modal);padding:4px;
+}
+.city-option{
+  display:flex;align-items:baseline;justify-content:space-between;width:100%;border:0;
+  background:transparent;color:var(--text);font:inherit;text-align:left;padding:8px 9px;
+  border-radius:4px;cursor:pointer;
+}
+.city-option:hover,.city-option[aria-selected="true"]{background:var(--tag-bg)}
+.city-option small{font-size:11px;color:var(--text-tertiary);margin-left:8px}
+.advanced-time-grid{align-items:flex-end}
+.advanced-time-grid label{min-width:0}
 .advanced-options{
   margin-bottom:var(--space-md);
   color:var(--text-secondary);
@@ -830,7 +856,7 @@ html.dark .tag-xi{background:#1a3b2a;color:#6ee7b7}
 .event-main .direction-good{font-size:12px;font-weight:600;color:var(--good)}
 .event-main .prediction-text{font-size:13px;color:var(--text);font-weight:500}
 .event-main .llm-badge{font-size:11px;background:linear-gradient(135deg,#a78bfa,#7c3aed);color:#fff;border-radius:3px;padding:0 4px;line-height:1.5}
-.time-basis-note{margin:-6px 0 12px;font-size:12px;line-height:1.5;color:var(--text-tertiary)}
+.time-basis-note{margin:-2px 0 12px;font-size:12px;line-height:1.5;color:var(--text-tertiary)}
 .ai-review{margin:8px 18px 14px;padding:10px 12px;border:1px solid var(--border);border-radius:4px;background:var(--tag-bg)}
 .ai-review summary{cursor:pointer;font-size:12px;font-weight:600;color:var(--text-secondary)}
 .ai-review-item{padding:8px 0;border-top:1px solid var(--border);font-size:12px;line-height:1.6}
@@ -1358,6 +1384,8 @@ html.dark .calendar-legend .dot.bad{background:#c53030}
   .form-row{flex-wrap:wrap;gap:8px}
   .birth-datetime-grid{column-gap:6px;row-gap:5px}
   .birth-datetime-grid input{padding:10px 7px}
+  .advanced-time-grid{display:grid;grid-template-columns:1fr 1fr;gap:8px}
+  .advanced-time-grid label:last-child{grid-column:1 / -1}
   .info-grid{grid-template-columns:1fr;gap:8px}
   .traits-grid{grid-template-columns:1fr;gap:6px}
   .evidence-signals{grid-template-columns:1fr 1fr;gap:6px 12px}