-
-
-
-
-
\ No newline at end of file
diff --git a/docs/ai-operating-handbook.md b/docs/ai-operating-handbook.md
index a183fa7..0735684 100644
--- a/docs/ai-operating-handbook.md
+++ b/docs/ai-operating-handbook.md
@@ -137,12 +137,10 @@ Current-session tool evidence wins over configured inventory. Use PowerShell,
`rg` after confirming it runs, and `apply_patch` for local edits. Treat
unexposed or replaced plugins as fallback routes, not hard dependencies.
-## Next Enhancement Queue
-
-1. Add browser automation for range-mode and region-mode smoke tests when a
- local Playwright or equivalent dependency is available.
-2. Continue reducing legacy `plans` naming after compatibility is no longer
- needed.
-3. Improve failure retry UX on top of persisted failure records.
-4. Handle global overgrown system skills, such as `imagegen`, in a separate
- global-control tranche so repo guidance remains focused.
+## Maintenance Priorities
+
+Browser automation and cumulative failure retries are implemented and covered
+by the validation chain. Use [the maintenance audit](maintenance-audit-2026-09-11.md)
+for remaining work instead of recreating completed tasks. Keep legacy `plans`
+tables while compatibility still depends on them. Global environment work is
+outside repository maintenance.
diff --git a/docs/automation-guardrails.md b/docs/automation-guardrails.md
index 30f3e7f..9686571 100644
--- a/docs/automation-guardrails.md
+++ b/docs/automation-guardrails.md
@@ -36,7 +36,7 @@ Facts:
- Start from AGENTS.md, docs/project-map.md, docs/done-definition.md, docs/ai-operating-handbook.md, and git status.
- Confirm the repository only contains the in-scope app under apps/admin-region-tiler.
- Confirm retired .NET range downloader runtime code has not reappeared.
-- Check for drift between README.md, PROJECT_MANIFEST.md, RELEASE_HANDOFF_PROMPT.md, LICENSE, and docs/merge-plan.md.
+- Check for drift between README.md, PROJECT_MANIFEST.md, docs/long-term-memory.md, LICENSE, and docs/merge-plan.md.
- Check that docs/knowledge-graph.md still names the current single-app architecture and AI control surfaces.
- Check that docs/long-term-memory.md still follows the handoff contract if it exists.
- Check for sensitive token or password literals, allowing documented placeholders and the documented development default admin password only.
@@ -67,7 +67,7 @@ python C:\Users\32674\.codex\skills\deep-execution-upgrade\scripts\audit_environ
```
```powershell
-rg -n "Apache|MIT|License|许可证|许可" README.md PROJECT_MANIFEST.md RELEASE_HANDOFF_PROMPT.md docs LICENSE
+rg -n "Apache|MIT|License|许可证|许可" README.md PROJECT_MANIFEST.md docs LICENSE
```
```powershell
diff --git a/docs/github-growth-playbook.md b/docs/github-growth-playbook.md
index 9efa342..d29a41f 100644
--- a/docs/github-growth-playbook.md
+++ b/docs/github-growth-playbook.md
@@ -1,5 +1,9 @@
# GitHub Star Conversion Playbook
+> Historical promotion plan. The release checklist below still targets v0.1.0
+> and is not a validated procedure for current releases. See the
+> [maintenance audit](maintenance-audit-2026-09-11.md) before reusing it.
+
This playbook is the first-stage execution guide for improving Map Tile
Fetcher conversion from repository visitor to star. It is intentionally focused
on Chinese GIS and map-development audiences.
diff --git a/docs/long-term-memory.md b/docs/long-term-memory.md
index 61f4969..7e1282c 100644
--- a/docs/long-term-memory.md
+++ b/docs/long-term-memory.md
@@ -2,6 +2,13 @@
## Facts
+- 2026-09-11 repository cleanup: removed 24 redundant docs, unused package
+ scaffolding, unreferenced static files and a generated report. Actual region
+ geometry, runtime compatibility tables and active UI/test assets remain.
+ `docs/maintenance-audit-2026-09-11.md` records the deletion evidence and seven
+ unresolved maintenance issues, including five confirmed missing region files.
+- README follow-up PR #4 merged as `37cfe7c`; its main CI passed and the
+ temporary `codex/readme-sync` branch was removed locally and remotely.
- 2026-09-11 README follow-up: root documentation now covers repair behavior,
limits, legacy handling and validation. Source/binary runs read process
environment variables, not `.env` automatically; initial credentials do not
@@ -55,8 +62,9 @@
## Decisions
-- Keep `main` as the only long-term branch. Merge the validated PR #3 head and
- remove `agent/audit-hardening` only after the resulting main CI succeeds.
+- Keep `main` as the only long-term branch. PR #3 and its branch cleanup are
+ complete. For future batches, merge the checked PR head and remove its
+ temporary branch only after the resulting main CI succeeds.
- Defaults: 1,000,000 tiles per parent across sources, three active children,
paused children retaining their slot, and three requested workers (1-50).
- Preserve legacy records and artifacts; reconcile explicitly without tile
@@ -157,8 +165,9 @@
## Next Action
-- For this delivery, verify the final PR head checks, merge with the validated
- bilingual message, wait for main CI, and remove only the fully merged repair
- branch. Use live GitHub state to determine whether these steps are complete.
+- Use `docs/maintenance-audit-2026-09-11.md` for remaining issues. Start with
+ region maintenance script data preservation and geometry correctness, then
+ existing-user password rotation. Check live GitHub state for any pending
+ cleanup PR before creating a duplicate batch.
- Before any future release, rerun preflight and verify `main` CI. Plan a
separate, explicitly authorized deployment and database backup/copy validation.
diff --git a/docs/maintenance-audit-2026-09-11.md b/docs/maintenance-audit-2026-09-11.md
new file mode 100644
index 0000000..f7d6563
--- /dev/null
+++ b/docs/maintenance-audit-2026-09-11.md
@@ -0,0 +1,70 @@
+# 仓库清理与待处理清单
+
+检查日期：2026-09-11。基线：`37cfe7c`（README 同步后的 `main`）。
+本轮检查仓库文件用途、代码导入、静态资源引用、文档一致性和维护脚本。
+清理不执行生产部署、区域下载或生产数据修改，不等同于重新审计全部业务逻辑。
+
+## 已清理
+
+共删除 24 个文件，Git 历史保留其原内容。
+
+| 对象 | 原问题与处理依据 |
+| --- | --- |
+| `README_ZH.md`、应用目录 `README-EN.md` | 根 README 已有中英文入口；两个副本缺少新行为且产生启动说明漂移，删除副本。 |
+| `RELEASE_HANDOFF_PROMPT.md` | 一次性交接提示仍要求中英文 README 分开，现有项目地图、验证链路和长期交接已覆盖其用途；删除并更新自动审查引用。 |
+| 应用目录 `CHANGES.md` | 仅有 2022 年 `timedelay` 说明且使用旧 `works` 参数，不是当前变更记录；删除，当前规则见 README 和配置。 |
+| `static/test.html` | 仅测试按钮事件，无应用或回归测试引用；原先随整个 `static/` 发布，现已删除。 |
+| `internal/api`、`auth`、`config`、`artifact`、`web` 的 5 个 `doc.go` | 只有“将来负责”的说明，无实现或导入；删除空包，文档改为真实代码职责。 |
+| `internal/planner` 的 3 个文件 | 只有自身测试引用，主应用不调用；重复校验已经与真实 API 的名称长度规则不一致。删除未接入代码及其测试，保留真实 API 集成测试。 |
+| 10 个静态资源 | 8 个无调用图标：`calendar`、`clock`、`error`、`filter`、`folder`、`pause`、`play`、`search`；另有旧 `static/favicon.svg`、未使用的 `assets/logo/logo.svg`。已核对 HTML/CSS 直接引用及 JS 动态图标分支。 |
+| `geojson/materialize-report.json` | 一次性生成结果，不是区域数据；其中缺失项转录并重新核实如下，生成报告加入 Git 和 Docker 忽略规则。 |
+
+同时修正：应用架构说明、源码与 systemd 配置说明、部署前初始账号要求、删除范围、
+PR #3/#4 已完成状态，以及 AI 手册中已经完成的待办。历史发布草稿和推广方案加上
+过时标记；这些文件仍有历史或推广用途，未整份删除。
+
+## 待处理问题
+
+优先级 P1 表示执行相关维护操作前应处理，P2 表示下一轮维护应补齐。
+以下均未在本轮修改业务实现，不能因清理或现有测试通过而视为已解决。
+
+| 编号 | 优先级 | 已确认事实与影响 | 处理建议与验收 |
+| --- | --- | --- | --- |
+| M1 | P1 | [区域镜像脚本](../apps/admin-region-tiler/scripts/materialize_geojson_from_mirror.py) 的 `sync_to_deploy` 对目标 `geojson/` 先执行 `shutil.rmtree` 再复制；没有引用核对，启用 `--deploy-root` 会整目录替换现有文件。 | 改为有路径约束、备份及差异清单的发布过程；保护任务生成和自定义文件，复制失败可恢复。用临时目录验证，不能直接在生产试运行。 |
+| M2 | P1 | [区域下载脚本](../apps/admin-region-tiler/scripts/download_aliyun_geojson.py) 在城市请求 404 时复制父区域文件或下载父区域，仍写入子区域路径；文件存在不代表范围正确，后续下载可能扩大到父区域。 | 缺失区域显式失败；仅在能从数据中按行政编码提取目标几何时落盘。模拟 404，核对编码和几何，不能以父区域代替。 |
+| M3 | P1 | [初始用户创建](../apps/admin-region-tiler/db.go) 遇到同名用户直接返回；[API 路由](../apps/admin-region-tiler/server.go) 没有改密接口。已使用默认账号初始化的实例不能通过改环境变量轮换密码。原部署文档“上线后修改”已纠正，但功能缺口仍在。 | 增加受认证的密码修改流程或明确的离线恢复命令，保留任务归属并撤销旧会话；验证旧密码失效、其他用户不受影响。 |
+| M4 | P2 | [区域目录](../apps/admin-region-tiler/geojson/regions.json) 有 3227 项，其中 5 项引用的文件不存在，详见下表。服务会把它们归入 `missing`，对应区域无法直接选择下载。 | 从明确来源补齐并校验几何和行政编码；若无法取得准确边界，继续标记缺失，不能用近似区域替代。 |
+| M5 | P2 | [main.go](../apps/admin-region-tiler/main.go) 帮助文本及默认版本、[conf.toml](../apps/admin-region-tiler/conf.toml) 仍写 `0.1.0`；仓库发布预览为 `v0.3.0`，当前修复又在其后。版本显示无法准确识别构建。 | 建立单一构建版本来源，包含 tag/commit；开发构建明确标记，检查帮助、服务元信息和发布包一致。不要仅手改版本号伪装为新发布。 |
+| M6 | P2 | [旧发布步骤](github-growth-playbook.md) 写死 `v0.1.0`，使用未定义的 `$winDir`/`$linuxDir`；打包二进制名为 `map-tile-fetcher`，而 [systemd 模板](../apps/admin-region-tiler/deploy/systemd/tiler.service) 运行 `/opt/tiler/tiler`。 | 将可复现构建打包过程从推广方案提取成脚本，统一二进制名、版本、资源与校验和；在新目录解压后验证启动。当前历史步骤已标记不可直接照用。 |
+| M7 | P2 | 两个区域维护脚本缺少依赖锁定和回归验证；镜像脚本直接依赖 Shapely，下载脚本遇到错误仅打印报告，进程仍可成功退出；`--limit` 说明称 dry run 但仍实际下载写盘。 | 建立独立维护工具依赖及测试，明确只检查与写入模式，失败返回非零退出码；使用本地模拟服务验证，不触达真实服务。 |
+
+### 已核实的区域缺口
+
+仅解析区域目录并检查路径是否存在，没有读取或重写全部几何数据。
+
+| 行政编码 | 区域 |
+| --- | --- |
+| 460323 | 中沙群岛的岛礁及其海域 |
+| 653228 | 和康县 |
+| 653229 | 和安县 |
+| 659011 | 新星市 |
+| 659012 | 白杨市 |
+
+## 保留依据
+
+- `internal/area`、`internal/downloader` 被主应用直接调用，保留实现和测试。
+- `plans`、旧运行与关联表仍参与兼容迁移、查询及删除，不能因为名称旧就删除。
+- `geojson/` 的真实区域资源、Leaflet 及其图标、页面正在引用的 SVG 和 README 图片均保留。
+- 区域维护脚本有数据重建用途，保留并列出缺陷；本轮未执行其下载或同步动作。
+- `AGENTS.md`、项目地图、验证链路、交接和本地技能仍有明确规则及引用，保留。
+- 本地忽略目录与运行数据不属于本轮 Git 文件清理；没有执行临时目录的递归删除。
+
+## 验证路径
+
+删除前核对 tracked 文件、导入关系、静态资源的直接和动态引用；清理后执行完整
+`node scripts/release_preflight.mjs`、`go vet ./...`、文档链接与静态资源存在性检查、
+仓库审计、交接校验和 `git diff --check`。精确通过记录写入本批双语提交正文，
+Linux `go test -race ./...` 由 PR 和合并后 `main` CI 验证。
+
+后续实施优先处理 M1/M2 的区域维护工具，再处理 M3 的账号轮换；M4 需要可靠区域
+数据来源，M5/M6 应随下一次正式发布一并收敛，M7 与维护工具修复一起验证。
diff --git a/docs/merge-plan.md b/docs/merge-plan.md
index d77177f..60ea784 100644
--- a/docs/merge-plan.md
+++ b/docs/merge-plan.md
@@ -44,9 +44,13 @@ Keep `apps/admin-region-tiler` as the base for:
## Branch Convergence
-`main` is the only long-term branch. The full repair delivery uses existing
-PR #3 and `agent/audit-hardening`, with validated bilingual commits per batch.
-Keep strict required checks (`Commit Message`, `Admin Region Tiler`) enabled.
-Merge only the checked PR head with a complete bilingual merge message, wait
-for the resulting `main` CI, then remove the repair branch and synchronize the
-local checkout. Preserve historical CI failures and commit history.
+`main` is the only long-term branch. PR #3 was merged as `8b0933b`; its main CI
+passed and `agent/audit-hardening` was deleted. README follow-up PR #4 was merged
+as `37cfe7c`, with main CI passing and its temporary branch removed.
+
+For future batches, keep strict required checks (`Commit Message`,
+`Admin Region Tiler`) enabled. Merge only the checked PR head with a complete
+bilingual merge message, wait for the resulting `main` CI, then remove that
+temporary branch and synchronize the local checkout. Preserve historical CI
+failures and commit history. Current cleanup findings are tracked in
+[the maintenance audit](maintenance-audit-2026-09-11.md).
diff --git a/docs/project-map.md b/docs/project-map.md
index 8c4c468..1a6316d 100644
--- a/docs/project-map.md
+++ b/docs/project-map.md
@@ -31,13 +31,12 @@ Out of scope unless the user explicitly changes direction:
manager, and HTTP server
- supports worker mode via runtime flags/environment
- `internal/`
- - package boundaries for API, auth, config, area selection, planning,
- downloading, artifacts, and static Web helpers
+ - the two implemented packages shared by the main application
- `internal/area` validates bbox and region area selectors plus zoom ranges
- - `internal/planner` normalizes unified task requests before persistence or
- execution
- `internal/downloader` contains bbox tile math shared by API validation and
range UI estimates
+ - task normalization, authentication and artifact management remain in the
+ main package; unused extraction scaffolding has been removed
- `server.go`
- Gin routes for login, current user, task CRUD, task control, artifact
download, failure records, map source config, region catalog, and GeoJSON
@@ -142,8 +141,10 @@ See `docs/range-migration.md` for the historical note.
- Source-of-truth license: Apache License 2.0 in `LICENSE` and `README.md`.
- Safe token placeholders include `YOUR_TIANDITU_TOKEN`, `YOUR_MAPBOX_TOKEN`,
and `YOUR_MAPBOX_SKU`.
-- `adminmap` is a documented development default password; production must use
- `.env` overrides.
+- `adminmap` is a documented development default password. Configure initial
+ production credentials before the first start through process environment
+ variables or local configuration; Docker injects `.env`. Existing users are
+ not reset by changing initial-user settings.
- Generated or local-only paths stay out of Git: `.env`, `data/`, `output/`,
`tiles/`, `bin/`, `obj/`, `publish*/`, logs, binaries, and archives.
- Browser UI smoke validation uses an optional local or global browser
@@ -163,6 +164,7 @@ See `docs/range-migration.md` for the historical note.
| `docs/knowledge-graph.md` | Durable relationship graph | When recovering context or avoiding broad re-exploration |
| `docs/long-term-memory.md` | Handoff-style restart state | Long-running, merge, release, or AI-control work |
| `docs/automation-guardrails.md` | Read-only recurring review constraints | Automation prompt creation or review |
+| `docs/maintenance-audit-2026-09-11.md` | Cleanup decisions and remaining maintenance issues | Before deleting more files or planning follow-up fixes |
## Context Loading Order
diff --git a/docs/releases/v0.1.0.md b/docs/releases/v0.1.0.md
index cc86633..3820ccd 100644
--- a/docs/releases/v0.1.0.md
+++ b/docs/releases/v0.1.0.md
@@ -1,5 +1,9 @@
# v0.1.0 Release Notes
+> Historical release draft, retained for provenance. Version names, startup
+> instructions and planned assets below are not the current release procedure.
+> 当前安装配置见 [README](../../README.md)，历史版本记录不代表当前主分支行为。
+
Release date: 2026-06-29
这是 Map Tile Fetcher 合并为单一 Go Web 应用后的第一个开源预览版本。