From d782c5688c22257e559c4c195d8f5a112bfe65ac Mon Sep 17 00:00:00 2001 From: Thang Le Quoc Date: Sun, 12 Jul 2026 22:58:26 +0700 Subject: [PATCH 1/3] Update Q&A --- README.md | 8 ++++++++ README_vi.md | 8 ++++++++ 2 files changed, 16 insertions(+) diff --git a/README.md b/README.md index faa8ab59..3519686d 100644 --- a/README.md +++ b/README.md @@ -266,6 +266,14 @@ GIS boundary data was derived from the [Vietnam Administrative Units Reference M |`provinces`|Key: `code`. Officially referenced from government unit code |`wards`|Key: `code`. Officially referenced from government unit code +### Why use this repository instead of another administrative dataset/API Provider on the market? + +The official administrative codes are defined by the Vietnamese government, so datasets generated from the same official source are generally compatible with each other. + +The main difference is **transparency** and **maintainability**. Many public datasets eventually become outdated because they only publish the generated data. This repository also includes the complete data generation pipeline (dataset-generation-scripts), allowing anyone to inspect how the dataset is collected, cleaned, normalized, and exported. Every step is transparent and reproducible, making it easy to verify the data, customize the output, regenerate the latest dataset from the official source, and continue maintaining the project even if the original maintainer is no longer active. + +Released under the MIT License — just use it. No fees. No permission required. + ### The province - administrative region relationship is dropped from v3.0.0? After the provinces merge down to 37 provinces, the new province e.g: Phú Thọ, which is formed from Vĩnh Phúc, Phú Thọ and Hoà Bình that previously span across 3 different regions, so it's no longer applicable to determine which region does the new province belongs to. diff --git a/README_vi.md b/README_vi.md index bfca6f97..bbe37234 100644 --- a/README_vi.md +++ b/README_vi.md @@ -263,6 +263,14 @@ Dữ liệu ranh giới GIS được xây dựng dựa trên dữ liệu từ [B |`provinces`|Khoá chính: `code`. Được quy ước theo đối tượng **Tỉnh thành** do chính phủ ban hành |`wards`|Khoá chính: `code`. Được quy ước theo đối tượng **Phường xã** do chính phủ ban hành +### Sao không dùng API từ nhà cung cấp khác, hay dataset khác trên thị trường? + +Mã đơn vị hành chính được Chính phủ Việt Nam quy định thống nhất, vì vậy các bộ dữ liệu được xây dựng từ cùng một nguồn dữ liệu chính thức nhìn chung đều tương thích với nhau. + +Điểm khác biệt lớn nhất của repository này là tính minh bạch của mã nguồn và khả năng duy trì lâu dài. Nhiều bộ dữ liệu công khai khác dần trở nên lỗi thời theo thời gian vì chỉ phát hành dữ liệu đã được sinh sẵn. Repository này công khai toàn bộ quy trình sinh dữ liệu (dataset-generation-scripts), giúp mọi người có thể xem chính xác cách dữ liệu được thu thập, làm sạch, chuẩn hóa và xuất ra. Mọi bước đều minh bạch và có thể tái tạo, giúp bạn dễ dàng kiểm chứng dữ liệu, tùy biến theo nhu cầu, tạo lại dataset mới nhất từ nguồn dữ liệu chính thức, hoặc tiếp tục duy trì dự án ngay cả khi tác giả ban đầu không còn hoạt động nữa. + +Repository được phát hành theo MIT License — cứ clone về dùng thôi. Bạn không mất phí, và không cần phải xin phép ai để sử dụng. + ### Tại sao mối quan hệ giữa tỉnh và vùng hành chính (region) bị loại bỏ từ phiên bản v3.0.0? Sau khi số lượng tỉnh được sáp nhập còn 37, các tỉnh mới — chẳng hạn như Phú Thọ, được hình thành từ Vĩnh Phúc, Phú Thọ và Hòa Bình — hiện nay trải dài trên nhiều vùng hành chính trước đây. Do các tỉnh cũ thuộc các vùng khác nhau, nên việc xác định vùng hành chính cho tỉnh mới không còn chính xác nữa. From 1069812ce238460a9ae9b58ce8a35454ece05ef3 Mon Sep 17 00:00:00 2001 From: Thang Le Quoc Date: Sun, 12 Jul 2026 23:01:51 +0700 Subject: [PATCH 2/3] Update GIS source url --- docs/gis/gis_readme.md | 9 +- .../2026-07-12-universal-db-query-skill.md | 378 ------------------ ...6-07-12-universal-db-query-skill-design.md | 179 --------- 3 files changed, 5 insertions(+), 561 deletions(-) delete mode 100644 docs/superpowers/plans/2026-07-12-universal-db-query-skill.md delete mode 100644 docs/superpowers/specs/2026-07-12-universal-db-query-skill-design.md diff --git a/docs/gis/gis_readme.md b/docs/gis/gis_readme.md index f6d9e68e..412de5d5 100644 --- a/docs/gis/gis_readme.md +++ b/docs/gis/gis_readme.md @@ -6,12 +6,13 @@ |PostgreSQL/PostGIS|[Download raw GIS Dataset for PostgreSQL][gis_dataset_postgresql_bucket_url]|~152.07 MB| |MySQL|[Download raw GIS Dataset for MySQL][gis_dataset_mysql_bucket_url]|~150.44 MB| |Microsoft SQL Server|[Download raw GIS Dataset for SQL Server][gis_dataset_sqlserver_bucket_url]|~152.13 MB| +|GeoJSON| Access the geojson data in the `json/geojson/` folder of this repository | - | ## Table of Contents 1. [Introduction](#introduction) 2. [Dataset Coverage](#dataset-coverage) -3. [GeoJSON Export](#geojson-export) +3. [GeoJSON](#geojson) 4. [Installation](#installation) 5. [Database Schema](#database-schema) 6. [Query Optimization Tips](#query-optimization-tips) @@ -449,6 +450,6 @@ If you find issues with the GIS dataset or have suggestions for improvements, pl **Last Updated:** June 20, 2026 -[gis_dataset_postgresql_bucket_url]: https://vn-provinces-ds.thanglequoc.xyz/v4.0.0/GISDataSet/postgresql_ImportData_gis_2026-06-20__12_32_01.sql -[gis_dataset_mysql_bucket_url]: https://vn-provinces-ds.thanglequoc.xyz/v4.0.0/GISDataSet/mysql_ImportData_gis_2026-06-20__12_32_01.sql -[gis_dataset_sqlserver_bucket_url]: https://vn-provinces-ds.thanglequoc.xyz/v4.0.0/GISDataSet/mssql_ImportData_gis_2026-06-20__12_32_02.sql +[gis_dataset_postgresql_bucket_url]: https://vn-provinces-ds.thanglequoc.xyz/v4.1.0/GISDataSet/postgresql_ImportData_gis_2026-07-12__19_50_50.sql +[gis_dataset_mysql_bucket_url]: https://vn-provinces-ds.thanglequoc.xyz/v4.1.0/GISDataSet/mysql_ImportData_gis_2026-07-12__19_50_50.sql +[gis_dataset_sqlserver_bucket_url]: https://vn-provinces-ds.thanglequoc.xyz/v4.1.0/GISDataSet/mssql_ImportData_gis_2026-07-12__19_50_51.sql diff --git a/docs/superpowers/plans/2026-07-12-universal-db-query-skill.md b/docs/superpowers/plans/2026-07-12-universal-db-query-skill.md deleted file mode 100644 index a27ca3da..00000000 --- a/docs/superpowers/plans/2026-07-12-universal-db-query-skill.md +++ /dev/null @@ -1,378 +0,0 @@ -# Universal db-query Skill in AGENTS.md — Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Consolidate the project's database query skill from a Claude Code-specific `.claude/skills/db-query.md` into a universal section within `AGENTS.md`, usable by any AI agent. - -**Architecture:** Add a comprehensive "Database Query Skill" section to `AGENTS.md` containing auto-trigger rules, connection details, schema/table reference, and query patterns. Delete the old `.claude/skills/db-query.md` file. Trim duplicate content from `CLAUDE.md` with a pointer to AGENTS.md. Update the memory feedback file to reflect the new location. - -**Tech Stack:** No code changes — documentation reorganization only. - -## Global Constraints - -- No database schema or data changes -- No Go code changes -- No changes to `settings.local.json` -- No changes to CI/CD pipeline -- All content must remain accurate against the current database schema (tables, columns, relationships) - ---- - -### Task 1: Add "Database Query Skill" section to AGENTS.md - -**Files:** -- Modify: `AGENTS.md` (replace lines 28-42) - -**Interfaces:** -- Produces: A new `## Database Query Skill` section in AGENTS.md that all agents can read for auto-trigger rules, connection details, schema, and query patterns. -- This section replaces the existing `### Database Connection (Docker)` subsection (lines 28-42) with the expanded content. - -- [ ] **Step 1: Replace the "Database Connection (Docker)" subsection in AGENTS.md with the full Database Query Skill section** - -Replace lines 28-42 of `AGENTS.md`: - -**Content to insert (replacing existing lines 28-42):** - -```markdown -## Database Query Skill - -**CRITICAL: Proactively query the database whenever the task involves data verification, counts, searching, or GIS data. Do NOT wait for explicit command invocation — the triggers below signal when to auto-query.** - -### Auto-Trigger Rules - -Execute database queries automatically when user asks about any of these: - -| Category | Trigger Keywords | -|----------|-----------------| -| Count/total | "how many", "count", "total", "number of", "how much" | -| Search/find | "find", "search", "show", "list", "get", "lookup" | -| Verification | "check", "verify", "validate", "missing", "orphaned" | -| Data topics | "database", "table", "data", "records", "provinces", "wards", "schema" | -| GIS | "geometry", "bbox", "geom", "gis", "spatial", "geojson", "coordinates" | -| Direct requests | "query from", "read from database", "get from [table]", "run a query" | - -**Examples:** -- "How many wards are in Hà Nội?" → Run query immediately -- "Check if there are any missing GIS data" → Run verification query -- "Show me provinces without codes" → Query and display results -- "List all tables" → Run `\dt` -- "Get data from sapnhap_geojson_objects" → Query the table - -### Connection Details - -The temporary database runs in Docker: - -```bash -# Container: vn_provinces_postgres_container -# Database: vn_provinces_tmp -# Username: postgres -# Host: localhost -# Port: 15432 - -# Single query -docker exec vn_provinces_postgres_container psql -U postgres -d vn_provinces_tmp -c "YOUR_SQL_QUERY_HERE" - -# Multi-line query (heredoc) -docker exec vn_provinces_postgres_container psql -U postgres -d vn_provinces_tmp <<'EOF' -YOUR_MULTI_LINE_SQL_QUERY_HERE -EOF -``` - -### Table Reference - -| Table | Records | Description | -|-------|---------|-------------| -| `provinces_tmp` | 34 | Vietnam provinces (code, name, name_en, full_name, administrative_unit_id) | -| `wards_tmp` | 3,321 | Vietnam wards (code, name, name_en, province_code FK, administrative_unit_id) | -| `administrative_regions` | 8 | Region lookup (id, name, name_en) | -| `administrative_units` | 8 | Unit type lookup (id, full_name, short_name) | -| `sapnhap_geojson_objects` | 3,355 | Combined geo objects with PostGIS geometry (ma, ten, magoc, malk, truocsapnhap, dientichkm2, bbox_wkt, geom_wkt, vn_ds_province_code FK, vn_ds_ward_code FK) | - -### Key Columns - -**`provinces_tmp`**: `code` (PK, e.g. "01", "02"), `name`, `name_en`, `full_name`, `code_name`, `administrative_unit_id` - -**`wards_tmp`**: `code` (PK), `name`, `name_en`, `full_name`, `province_code` (FK → `provinces_tmp.code`), `administrative_unit_id` - -**`sapnhap_geojson_objects`**: `ma` (PK), `ten` (name), `magoc` (parent FK, self-ref), `truocsapnhap` (pre-merge name), `dientichkm2` (area in km²), `bbox_wkt` (WKT POLYGON), `geom_wkt` (WKT MULTIPOLYGON), `vn_ds_province_code` (FK → `provinces_tmp.code`), `vn_ds_ward_code` (FK → `wards_tmp.code`) - -### Common Query Patterns - -**Count records:** -```sql -SELECT COUNT(*) FROM provinces_tmp; -SELECT COUNT(*) FROM wards_tmp; -``` - -**Data completeness check:** -```sql -SELECT - (SELECT COUNT(*) FROM provinces_tmp) as provinces, - (SELECT COUNT(*) FROM wards_tmp) as wards, - (SELECT COUNT(*) FROM sapnhap_geojson_objects) as geo_objects; -``` - -**Join provinces and wards:** -```sql -SELECT p.name as province, w.name as ward -FROM provinces_tmp p -JOIN wards_tmp w ON p.code = w.province_code -WHERE p.code = '01' -LIMIT 10; -``` - -**GIS geometry completeness:** -```sql -SELECT - COUNT(*) as total, - COUNT(bbox_wkt) as with_bbox, - COUNT(geom_wkt) as with_geom -FROM sapnhap_geojson_objects; -``` - -**Find orphaned records:** -```sql --- Geo objects without matching province -SELECT COUNT(*) FROM sapnhap_geojson_objects -WHERE vn_ds_province_code IS NULL; - --- Geo objects without matching ward -SELECT COUNT(*) FROM sapnhap_geojson_objects -WHERE vn_ds_ward_code IS NULL; -``` - -**List wards in a specific province:** -```sql -SELECT code, name, name_en FROM wards_tmp -WHERE province_code = '01' -ORDER BY name; -``` - -**PostGIS spatial queries:** -```sql --- Get area of a province geometry -SELECT ten, ST_Area(geom::geography) / 1000000 as area_km2 -FROM sapnhap_geojson_objects -WHERE vn_ds_province_code = '01'; - --- Find objects within a bounding box (example: Hà Nội area) -SELECT ma, ten, ST_AsText(bbox) FROM sapnhap_geojson_objects -WHERE ST_Within(geom, ST_MakeEnvelope(105.5, 20.5, 106.0, 21.5, 4326)); -``` - -### Agent Instructions - -When context triggers a database query: -1. Execute the SQL query using the `docker exec` command pattern above -2. Format results in a readable way (tables, lists, summaries) -3. Provide insights or follow-up suggestions if relevant -4. If the query returns an error, explain the issue and suggest a fix -5. Use `LIMIT` for large result sets to avoid overwhelming output -6. Explore schema with: `\dt` (list tables), `\d table_name` (describe table) -``` - -- [ ] **Step 2: Verify the replacement was applied correctly** - -Run: `grep -n "## Database Query Skill" AGENTS.md` -Expected: Line number output showing the new section exists. - -Run: `grep -n "### Database Connection (Docker)" AGENTS.md` -Expected: No output (old subsection removed). - -- [ ] **Step 3: Commit** - -```bash -git add AGENTS.md -git commit -m "docs: add universal Database Query Skill section to AGENTS.md" -``` - ---- - -### Task 2: Delete .claude/skills/db-query.md - -**Files:** -- Delete: `dataset-generation-scripts/.claude/skills/db-query.md` - -**Interfaces:** -- Consumes: Task 1 (new AGENTS.md section replaces this content) -- Produces: Clean removal of Claude Code-specific skill file; skill is now solely in AGENTS.md - -- [ ] **Step 1: Delete the old skill file** - -```bash -rm dataset-generation-scripts/.claude/skills/db-query.md -``` - -- [ ] **Step 2: Verify deletion** - -```bash -test -f dataset-generation-scripts/.claude/skills/db-query.md && echo "STILL EXISTS" || echo "DELETED" -``` -Expected: `DELETED` - -- [ ] **Step 3: Remove empty skills directory if empty** - -```bash -if [ -d "dataset-generation-scripts/.claude/skills" ] && [ -z "$(ls -A dataset-generation-scripts/.claude/skills)" ]; then - rmdir dataset-generation-scripts/.claude/skills -fi -``` - -- [ ] **Step 4: Commit** - -```bash -git add dataset-generation-scripts/.claude/skills/db-query.md -git commit -m "refactor: remove Claude Code-specific db-query skill (consolidated into AGENTS.md)" -``` - ---- - -### Task 3: Update CLAUDE.md — trim DB sections, add pointer to AGENTS.md - -**Files:** -- Modify: `dataset-generation-scripts/CLAUDE.md` (lines 9-56 replaced, lines 31-41 replaced) - -**Interfaces:** -- Consumes: Task 1 (new AGENTS.md section to reference) -- Produces: CLAUDE.md with reduced duplicate content, pointing to AGENTS.md for db-query skill - -- [ ] **Step 1: Replace the "When to Use Database Queries" section (lines 9-30) and the "Database Access" section (lines 31-56) with a pointer** - -Replace lines 9-56 of `dataset-generation-scripts/CLAUDE.md`: - -**SEARCH block** (existing lines 9-56): -``` -## When to Use Database Queries - -**AUTOMATICALLY use database queries when the user asks about:** -- Data counts, totals, or statistics (e.g., "how many", "count", "total") -- Data verification or integrity checks (e.g., "check", "verify", "missing", "orphaned") -... -``` - -**REPLACE block:** -```markdown -## When to Use Database Queries - -See [../AGENTS.md#database-query-skill](../AGENTS.md) for the universal db-query skill — auto-trigger rules, connection details, schema/table reference, and query patterns. Apply these rules automatically; do not wait for explicit invocation. - -## Database Access - -See [../AGENTS.md#database-query-skill](../AGENTS.md). Quick reminder: the database is accessible via: -```bash -docker exec vn_provinces_postgres_container psql -U postgres -d vn_provinces_tmp -c "QUERY" -``` -Container: `vn_provinces_postgres_container`, Database: `vn_provinces_tmp`, Port: `15432` -``` - -- [ ] **Step 2: Verify the replacement** - -Run: `head -20 dataset-generation-scripts/CLAUDE.md | grep -A5 "When to Use Database Queries"` -Expected: Shows the new pointer text referencing AGENTS.md. - -Run: `grep "vn_provinces_postgres_container" dataset-generation-scripts/CLAUDE.md` -Expected: Still shows the connection info (quick reminder preserved). - -- [ ] **Step 3: Commit** - -```bash -git add dataset-generation-scripts/CLAUDE.md -git commit -m "docs: trim CLAUDE.md DB sections, point to AGENTS.md db-query skill" -``` - ---- - -### Task 4: Update memory/feedback_auto_db_query.md - -**Files:** -- Modify: `dataset-generation-scripts/memory/feedback_auto_db_query.md` - -**Interfaces:** -- Consumes: Tasks 1-3 (skill now in AGENTS.md) -- Produces: Updated memory reflecting new location - -- [ ] **Step 1: Update the feedback file to reference AGENTS.md instead of .claude/skills/** - -Replace the content of `dataset-generation-scripts/memory/feedback_auto_db_query.md`: - -```markdown ---- -name: feedback_auto_db_query -description: User wants automatic skill invocation without manual commands -type: feedback ---- - -**Rule:** Skills should automatically trigger based on context, not require manual invocation. - -**Why:** User explicitly asked "How can I make claude code aware when to use the db-query skill... I don't want to invoke the skill manually every time" - -**Current location:** `AGENTS.md` → `## Database Query Skill` section - -**How to apply:** -- The AGENTS.md section contains explicit auto-trigger keywords and patterns -- Be proactive: if user asks about data, statistics, or verification, run queries immediately -- Don't wait for explicit commands -- Common triggers: "how many", "count", "check", "find", "show", "verify", "missing", "database", "table" - -**Example:** -- User says: "How many wards are there?" -- Response: Immediately run `docker exec vn_provinces_postgres_container psql -U postgres -d vn_provinces_tmp -c "SELECT COUNT(*) FROM wards_tmp"` -- Don't say: "Would you like me to query the database?" -``` - -- [ ] **Step 2: Verify update** - -Run: `grep "AGENTS.md" dataset-generation-scripts/memory/feedback_auto_db_query.md` -Expected: Shows the new `Current location` line. - -- [ ] **Step 3: Commit** - -```bash -git add dataset-generation-scripts/memory/feedback_auto_db_query.md -git commit -m "docs: update memory to reference AGENTS.md-based db-query skill" -``` - ---- - -### Task 5: Final verification - -**Files:** -- Check: `AGENTS.md` (new section exists) -- Check: `dataset-generation-scripts/.claude/skills/db-query.md` (deleted) -- Check: `dataset-generation-scripts/CLAUDE.md` (points to AGENTS.md) -- Check: `dataset-generation-scripts/memory/feedback_auto_db_query.md` (updated) - -- [ ] **Step 1: Verify AGENTS.md has the new section** - -```bash -grep -c "## Database Query Skill" AGENTS.md -``` -Expected: `1` (or more if repeated across subsections) - -- [ ] **Step 2: Verify old file is deleted** - -```bash -test ! -f dataset-generation-scripts/.claude/skills/db-query.md && echo "OK: old file deleted" || echo "FAIL: old file still exists" -``` -Expected: `OK: old file deleted` - -- [ ] **Step 3: Verify CLAUDE.md references AGENTS.md** - -```bash -grep "AGENTS.md#database-query-skill" dataset-generation-scripts/CLAUDE.md -``` -Expected: Shows the reference - -- [ ] **Step 4: Verify all changes are committed** - -```bash -git status -``` -Expected: Working tree clean - -- [ ] **Step 5: Verify git log shows expected commits** - -```bash -git log --oneline -5 -``` -Expected: Recent commits show the 4 changes from Tasks 1-4 \ No newline at end of file diff --git a/docs/superpowers/specs/2026-07-12-universal-db-query-skill-design.md b/docs/superpowers/specs/2026-07-12-universal-db-query-skill-design.md deleted file mode 100644 index c8805526..00000000 --- a/docs/superpowers/specs/2026-07-12-universal-db-query-skill-design.md +++ /dev/null @@ -1,179 +0,0 @@ -# Design: Universal db-query Skill in AGENTS.md - -**Date:** 2026-07-12 -**Status:** Approved -**Approach:** A — Fully Inline in AGENTS.md - ---- - -## Objective - -Consolidate the project's database query skill into a single, universal definition in `AGENTS.md` so that any AI agent (Cline, Cursor, Windsurf, Claude Code, etc.) reading AGENTS.md automatically gets full db-query capabilities — auto-trigger rules, connection details, schema reference, and query patterns — without relying on agent-specific skill formats. - -## Background - -The project previously had a Claude Code-specific skill at `dataset-generation-scripts/.claude/skills/db-query.md`. This file used Claude Code's `.claude/skills/` format with YAML frontmatter and was only discoverable by Claude Code. Other agents had no access to this skill unless they happened to read that specific file. - -Additionally, `CLAUDE.md` contained duplicate "When to Use Database Queries" and "Database Access" sections that overlapped with the skill file, creating maintenance burden and potential inconsistency. - -The user's memory feedback (`feedback_auto_db_query.md`) explicitly states: skills should auto-trigger based on context, not require manual invocation. - -## Design - -### 1. New AGENTS.md Section: "Database Query Skill" - -Add a comprehensive section to `AGENTS.md` that replaces the existing brief "Database Connection (Docker)" subsection. The new section contains: - -#### Auto-Trigger Rules - -An explicit list of trigger keywords and phrases that signal the agent should proactively run database queries: -- Count/total: "how many", "count", "total", "number of" -- Search/find: "find", "search", "show", "list", "get" -- Verification: "check", "verify", "missing", "orphaned", "validate" -- Data topics: "database", "table", "data", "records", "provinces", "wards" -- GIS: "geometry", "bbox", "geom", "gis", "spatial" -- Direct requests: "query from", "read from database", "get from [table]" - -Instruction: "Do NOT wait for explicit skill invocation — proactively query when context suggests database information is needed." - -Examples of auto-triggers: -- "How many wards are in Hà Nội?" → Run query immediately -- "Check if there are any missing GIS data" → Run verification query -- "Show me provinces without codes" → Query and display results - -#### Connection Details - -- Container: `vn_provinces_postgres_container` -- Database: `vn_provinces_tmp` -- Username: `postgres` -- Host: `localhost` -- Port: `15432` -- Password: `root` - -Command patterns: -```bash -# Single query -docker exec vn_provinces_postgres_container psql -U postgres -d vn_provinces_tmp -c "YOUR_SQL_QUERY_HERE" - -# Multi-line query (heredoc) -docker exec vn_provinces_postgres_container psql -U postgres -d vn_provinces_tmp <<'EOF' -YOUR_MULTI_LINE_SQL_QUERY_HERE -EOF -``` - -#### Table & Schema Reference - -**Core Tables:** -| Table | Records | Description | -|-------|---------|-------------| -| `provinces_tmp` | 34 | Vietnam provinces with codes | -| `wards_tmp` | 3,321 | Vietnam wards with codes | -| `administrative_regions` | — | Administrative regions | -| `administrative_units` | — | Administrative unit types | - -**GIS Table:** -| Table | Records | Description | -|-------|---------|-------------| -| `sapnhap_geojson_objects` | 3,355 | Combined geo objects with geometry | - -**Key Columns:** - -`provinces_tmp`: -- `code` (PK) — Province code (e.g., "01", "02") -- `name` — Province name (cleaned, no prefix) -- `name_en` — English name -- `full_name` — Full name with administrative prefix -- `administrative_unit_id` (FK) — Unit type - -`wards_tmp`: -- `code` (PK) — Ward code -- `name` — Ward name (cleaned) -- `name_en` — English name -- `province_code` (FK) → `provinces_tmp.code` -- `administrative_unit_id` (FK) — Unit type - -`sapnhap_geojson_objects`: -- `ma` (PK) — Object identifier -- `ten` — Name -- `magoc` — Parent reference (self-referential FK) -- `malk` — Link code -- `truocsapnhap` — Pre-merge name -- `dientichkm2` — Area in km² -- `vn_ds_province_code` (FK) → `provinces_tmp.code` -- `vn_ds_ward_code` (FK) → `wards_tmp.code` -- `bbox_wkt` — Bounding box in WKT POLYGON format -- `geom_wkt` — Geometry in WKT MULTIPOLYGON format -- `bbox` — PostGIS geometry (generated from `bbox_wkt`) -- `geom` — PostGIS geometry (generated from `geom_wkt`) - -**Key Relationships:** -- `wards_tmp.province_code` → `provinces_tmp.code` -- `provinces_tmp.administrative_unit_id` → `administrative_units.id` -- `wards_tmp.administrative_unit_id` → `administrative_units.id` -- `sapnhap_geojson_objects.vn_ds_province_code` → `provinces_tmp.code` -- `sapnhap_geojson_objects.vn_ds_ward_code` → `wards_tmp.code` -- `sapnhap_geojson_objects.magoc` → `sapnhap_geojson_objects.ma` (self-reference) - -#### Common Query Patterns - -- Count records -- Join provinces and wards -- Check GIS data completeness -- Find orphaned/missing records -- PostGIS spatial queries (`ST_AsText()`, `ST_Area()`, `ST_Contains()`) - -#### Agent Instructions - -When the database context triggers: -1. Execute the SQL query using the docker exec command -2. Format results readably (tables, lists, etc.) -3. Provide insights or follow-up suggestions if relevant -4. If the query returns an error, explain the issue and suggest fixes -5. Use `LIMIT` to avoid large result sets -6. Use `\dt` to list all tables, `\d table_name` to see table structure - -### 2. Remove `.claude/skills/db-query.md` - -Delete the file entirely. The `.claude/skills/` directory may remain empty or be removed. The `settings.local.json` file remains unchanged (it contains unrelated permissions). - -### 3. Update `CLAUDE.md` - -Replace the following sections in `CLAUDE.md` with a brief pointer to AGENTS.md: -- "When to Use Database Queries" section → replaced with: "See [../AGENTS.md#database-query-skill](../AGENTS.md) for the universal db-query skill — auto-trigger rules, connection details, and query patterns." -- "Database Access" / "Quick Database Access" section → same pointer -- "Database Schema" / "Key Tables" section → same pointer - -Keep `CLAUDE.md` focused on Go subsystem-specific details (project structure, internal packages, modules, configuration) that are not in AGENTS.md. - -### 4. Update Memory - -Update `dataset-generation-scripts/memory/feedback_auto_db_query.md` to reflect: -- The skill is now AGENTS.md-based (not `.claude/skills/`) -- Location: `AGENTS.md` → "Database Query Skill" section -- The auto-trigger principle remains the same - -## Files Affected - -| File | Action | Details | -|------|--------|---------| -| `AGENTS.md` | Modify | Add "Database Query Skill" section (~80-100 lines), replace brief "Database Connection (Docker)" subsection | -| `dataset-generation-scripts/.claude/skills/db-query.md` | Delete | Content consolidated into AGENTS.md | -| `dataset-generation-scripts/CLAUDE.md` | Modify | Trim DB sections, add pointer to AGENTS.md | -| `dataset-generation-scripts/memory/feedback_auto_db_query.md` | Modify | Update skill location reference | - -## Risks & Mitigations - -| Risk | Severity | Mitigation | -|------|----------|------------| -| AGENTS.md grows by ~80-100 lines | Low | Well-structured with clear section headers; table format for schema keeps it compact | -| Claude Code loses `.claude/skills/` auto-discovery | Low | Claude Code reads AGENTS.md too; auto-trigger keywords in AGENTS.md serve the same purpose | -| Duplicate content between AGENTS.md and CLAUDE.md | Low | Design explicitly trims CLAUDE.md to a pointer, eliminating duplication | -| Schema changes in future | Low | Table reference is concise and easy to update in one place | - -## Out of Scope - -- No database schema or data changes -- No Go code changes -- No changes to `settings.local.json` (unrelated permissions) -- No changes to CI/CD pipeline -- No new tooling or scripts \ No newline at end of file From 060f9da445b0e923fb5fcdd53e2b6e1d98d57068 Mon Sep 17 00:00:00 2001 From: Thang Le Quoc Date: Sun, 12 Jul 2026 23:12:46 +0700 Subject: [PATCH 3/3] feat: update doc --- README.md | 1 + README_vi.md | 1 + docs/gis/gis_readme.md | 10 +++++----- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 3519686d..1cef70fc 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,7 @@ The following table contains a list of issued decrees and their effective dates, |Issued Decree/Description|Issued on |Effect from|Release Version| |-------------|-----------|-------------|---------------| +|Add GeoJSON GIS, patch name, patch GIS province data of Da Nang and Khanh Hoa|---|---|v4.1.0| |Add GIS dataset|---|---|v4.0.0| |[30/2026/QH16][decree 30/2026/QH16], [237/NQ-UBTVQH16][decree 237/NQ-UBTVQH16]|14/04/2026|30/04/2026|v3.1.0| |[19/2025/QĐ-TTg][decree 19/2025/QĐ-TTg]|30/06/2025|01/07/2025|v3.0.2| diff --git a/README_vi.md b/README_vi.md index bbe37234..37440fcb 100644 --- a/README_vi.md +++ b/README_vi.md @@ -33,6 +33,7 @@ Bảng dưới thông kê các nghị định đã được ban hành, cùng th |Nghị định/Mô tả|Ngày ban hành|Ngày có hiệu lực|Phiên bản| |-------------|-----------|-------------|---------------| +|Thêm định dạng GIS GeoJSON, vá tên tiếng Anh, vá dữ liệu GIS của tỉnh Đà Nẵng và Khánh Hòa|---|---|v4.1.0| |Thêm dữ liệu GIS|---|---|v4.0.0| |[30/2026/QH16][decree 30/2026/QH16], [237/NQ-UBTVQH16][decree 237/NQ-UBTVQH16]|14/04/2026|30/04/2026|v3.1.0| |[19/2025/QĐ-TTg][decree 19/2025/QĐ-TTg]|30/06/2025|01/07/2025|v3.0.2| diff --git a/docs/gis/gis_readme.md b/docs/gis/gis_readme.md index 412de5d5..496ac1dd 100644 --- a/docs/gis/gis_readme.md +++ b/docs/gis/gis_readme.md @@ -409,11 +409,11 @@ Typical workflow: **A**: Yes. The following tools work well with the GIS dataset: -|Tool Type Recommendation -|------|--------|---------------| -|DBeaver| Database Client| Recommended for most users. Supports PostgreSQL, MySQL, and SQL Server, and can preview geometry data directly on an OpenStreetMap-based map viewer. -|QGIS| Desktop GIS| Best for advanced GIS analysis, spatial editing, and cartographic visualization. -|geojson.io| Web Viewer| Lightweight online tool for visualizing and debugging the published GeoJSON export. +| Tool | Type | Recommendation | +|------|------|---------------| +| DBeaver | Database Client | Recommended for most users. Supports PostgreSQL, MySQL, and SQL Server, and can preview geometry data directly on an OpenStreetMap-based map viewer. | +| QGIS | Desktop GIS | Best for advanced GIS analysis, spatial editing, and cartographic visualization. | +| geojson.io | Web Viewer | Lightweight online tool for visualizing and debugging the published GeoJSON export. | Example: Visualize Geometry in DBeaver [![image.png](https://i.postimg.cc/dVmQJSFg/image.png)](https://postimg.cc/k2GPcsBy)