Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
ff87584980 | ||
|
|
f2c5cf80fa | ||
|
|
43f52ced20 | ||
|
|
7f8f6cd297 | ||
|
|
2a30def397 | ||
|
|
d3f5b2b9d1 | ||
|
|
871bde1abd | ||
|
|
5c26bbe8b5 | ||
|
|
3d7df25d00 | ||
|
|
4d589eee95 | ||
|
|
3c17e2eb3b | ||
|
|
54e30d4228 | ||
|
|
00b0af69c2 | ||
|
|
81ab7aac39 | ||
|
|
8748760594 | ||
|
|
9d553744a1 | ||
|
|
710c483f34 | ||
|
|
f19faf628e | ||
|
|
9fc269283b | ||
|
|
826c1d8ca5 | ||
|
|
9a98fafefb | ||
|
|
849c19e2ab | ||
|
|
1c7ddf2fcb | ||
|
|
e653f3b50e | ||
|
|
726b1ee745 | ||
|
|
aa6fabe970 | ||
|
|
7437aef346 | ||
|
|
849c7537ed | ||
|
|
ee03dc6cc7 | ||
|
|
4cf96e3fa9 | ||
|
|
ba9564fca2 | ||
|
|
3eba203009 | ||
|
|
3fd5695bb2 | ||
|
|
42b3aa09a7 | ||
|
|
7ece39f212 | ||
|
|
bb3de5ee0f | ||
|
|
1ca41f162e | ||
|
|
afb3c9aa03 | ||
|
|
c8d0086a9f | ||
|
|
6cab6fcc95 | ||
|
|
8ede9f2123 | ||
|
|
ca5036abfe | ||
|
|
1c2a468516 | ||
|
|
b50cfa818d | ||
|
|
0630a774cf | ||
|
|
4a7e907be7 | ||
|
|
96ed0949ca | ||
|
|
3d267afaee | ||
|
|
4c4b51270c | ||
|
|
940b6c93f9 | ||
|
|
a54fef6a0c | ||
|
|
d65b857c2a | ||
|
|
6be28418ab | ||
|
|
f8483badcf | ||
|
|
74aa167d16 | ||
|
|
f1573edfa7 | ||
|
|
f90161f380 | ||
|
|
9a5a1a1a69 | ||
|
|
05fc47d7c3 | ||
|
|
e40a32971d | ||
|
|
eff81c1504 | ||
|
|
779743fdb0 | ||
|
|
8f331a002f | ||
|
|
d428919b78 | ||
|
|
9d8ce6b67f | ||
|
|
852d639c45 | ||
|
|
b5adc09203 | ||
|
|
a153dc8765 | ||
|
|
3620bb734c | ||
|
|
830e1d0f0d | ||
|
|
fd28ed2201 | ||
|
|
a1bb3eab98 | ||
|
|
8bd2b53469 | ||
|
|
21325d4e5c | ||
|
|
48cb424afd | ||
|
|
e5a8326a5e | ||
|
|
770e7930d9 | ||
|
|
cb3ab76d2b | ||
|
|
01380d3c09 | ||
|
|
6a3a6f8da5 | ||
|
|
224646e9d7 | ||
|
|
1d5eda3d89 | ||
|
|
8f58995fd0 | ||
|
|
25c62d3fff | ||
|
|
2e77f6c3df | ||
|
|
28e42e8b55 | ||
|
|
2d3f0a35c6 | ||
|
|
aae9657b9e | ||
|
|
a2ef8e0bf0 | ||
|
|
5a80c021d3 | ||
|
|
133d847608 | ||
|
|
043d9d632d | ||
|
|
d01fdabd68 | ||
|
|
84ae32b8a3 | ||
|
|
1f6129e009 | ||
|
|
d6799ec59b | ||
|
|
fcab9e1239 | ||
|
|
d2fb4b81c0 | ||
|
|
f922f6e8c7 | ||
|
|
06e350fb1e | ||
|
|
e522b2eee3 | ||
|
|
228dfdaca0 | ||
|
|
6357648c9c | ||
|
|
b845316ee7 | ||
|
|
2d3b34f34b | ||
|
|
cc8cc1bce6 | ||
|
|
a68d3c315e | ||
|
|
ba669fad34 | ||
|
|
8f64131131 | ||
|
|
802bfd117e | ||
|
|
2281705c95 | ||
|
|
fc0473e7e2 | ||
|
|
e12a8a919c | ||
|
|
37050b1458 | ||
|
|
6bd4b05af2 | ||
|
|
0da2bcd82d | ||
|
|
0979b8f544 | ||
|
|
4d106903e1 | ||
|
|
4b2e5578cd | ||
|
|
0e276ae652 | ||
|
|
554a7ab5ff | ||
|
|
cf99f4532f | ||
|
|
5d72bb092d | ||
|
|
d96fc4d36b | ||
|
|
436806a834 | ||
|
|
3a89dc2196 | ||
|
|
69c62466ca | ||
|
|
36892aef77 | ||
|
|
ac611cc878 | ||
|
|
9ec03200fb | ||
|
|
03c5809d69 | ||
|
|
00922e6c09 | ||
|
|
e6b099cf31 | ||
|
|
d8a0646829 | ||
|
|
433c3059b9 | ||
|
|
4110aa54c9 | ||
|
|
db6ded4075 | ||
|
|
b68421bb5b | ||
|
|
223e06ee77 | ||
|
|
52027ecf81 | ||
|
|
e5a4dab5f3 | ||
|
|
e034fdb816 | ||
|
|
a34f516de8 | ||
|
|
3b41d1f20f | ||
|
|
752266d408 | ||
|
|
f6c9b9883a | ||
|
|
d6d029d98c | ||
|
|
9084fd4f16 | ||
|
|
02cf4e6e95 | ||
|
|
711700fcc9 | ||
|
|
6f809d3196 | ||
|
|
16f97d5f73 | ||
|
|
97803ca5de | ||
|
|
fb556228c7 | ||
|
|
e42c314552 | ||
|
|
7124c82bb6 | ||
|
|
892781522d | ||
|
|
5490b22275 | ||
|
|
5c78f7ebb8 | ||
|
|
d03da40eee | ||
|
|
fb1a67044c | ||
|
|
7ed85dae34 | ||
|
|
88fd84a515 | ||
|
|
6de2f47933 | ||
|
|
7912fdd8b6 | ||
|
|
075e58fa07 | ||
|
|
734631a12d | ||
|
|
0a30adb85f | ||
|
|
93e5fc5837 | ||
|
|
ac4380c8b3 | ||
|
|
2b5b79c6c2 | ||
|
|
9a80e08739 | ||
|
|
3b03331955 | ||
|
|
20d58963e7 | ||
|
|
a13343647a | ||
|
|
4e2e12f83a | ||
|
|
e1b7d502b2 | ||
|
|
2ffb02428b | ||
|
|
9c3cbee141 | ||
|
|
feb0ddde32 | ||
|
|
3afac00394 | ||
|
|
cf510f08f8 | ||
|
|
a3d82b45b5 | ||
|
|
6f8b668907 | ||
|
|
3b56445bb2 | ||
|
|
bc57cb82fe | ||
|
|
9832c0c795 | ||
|
|
5e029be5ee | ||
|
|
6d393d38bb | ||
|
|
2c43c7c9ad | ||
|
|
14e86ccdd8 | ||
|
|
47d51cd36b | ||
|
|
c2537cf445 | ||
|
|
dffe072ce2 | ||
|
|
06c275cc40 | ||
|
|
92051184f5 | ||
|
|
c048f20734 | ||
|
|
af6b0b8098 | ||
|
|
94ba04ff56 | ||
|
|
9fb266e8ac | ||
|
|
f045233a50 | ||
|
|
6a187760db | ||
|
|
90298fa6cc | ||
|
|
503cb1f074 | ||
|
|
4d276e0776 | ||
|
|
298191173e | ||
|
|
81b085dd9d | ||
|
|
b6ad392ab7 | ||
|
|
bb5edf3ae2 | ||
|
|
000cf467df | ||
|
|
f8f98dfe46 | ||
|
|
5f44981bd3 | ||
|
|
a1b4787930 | ||
|
|
b412315ac6 | ||
|
|
7e07f3ab8d | ||
|
|
70c70fb7dd | ||
|
|
e18d477852 | ||
|
|
062aaa0074 | ||
|
|
470745fce3 | ||
|
|
b2274fee6f | ||
|
|
abd244fefb | ||
|
|
8302c6b782 | ||
|
|
bbf8e7a9c8 | ||
|
|
bf0b6ff070 | ||
|
|
b91bc98611 | ||
|
|
4210c2493d | ||
|
|
711c9e525e | ||
|
|
808ac6c792 | ||
|
|
73eb938c03 | ||
|
|
cccae446ae | ||
|
|
24b3a2d422 | ||
|
|
f472a17897 | ||
|
|
182b87fff2 | ||
|
|
407dd2dc09 | ||
|
|
a594aec912 | ||
|
|
c5f651bdae | ||
|
|
f4cd453088 | ||
|
|
57e4645a11 | ||
|
|
9b28616cf4 | ||
|
|
e9da5a6ccc | ||
|
|
cb58e91d6b | ||
|
|
39896c74de | ||
|
|
f3f564ab08 | ||
|
|
ccbb2f0944 | ||
|
|
d468c869c0 | ||
|
|
47e03bbc4d | ||
|
|
eafc06f0bc | ||
|
|
9dcbcad9aa | ||
|
|
028062bd14 | ||
|
|
bb69ea54b7 | ||
|
|
0f309f34fa | ||
|
|
2ef33c5cc3 | ||
|
|
0ef6ad4d20 | ||
|
|
bc3951449a | ||
|
|
9b629d93e3 | ||
|
|
0bef90debd | ||
|
|
73ff287b20 | ||
|
|
8f47dbb4f0 | ||
|
|
1ad2e4b256 | ||
|
|
61681cde73 | ||
|
|
9781e93eaf | ||
|
|
601c7f085f | ||
|
|
69d4090f6d | ||
|
|
85672dc041 | ||
|
|
0f6f12e0e9 | ||
|
|
7a656cfc1a | ||
|
|
72de364f29 | ||
|
|
74873451ab | ||
|
|
2faac7b74e | ||
|
|
e3f08426d5 | ||
|
|
dc5399de0a | ||
|
|
8f0f0e3fbf | ||
|
|
9ef8b099df | ||
|
|
9318474a54 | ||
|
|
d701f714e1 | ||
|
|
575f4fa3af |
No files matched your search
@@ -0,0 +1,16 @@
|
||||
.git
|
||||
.gitignore
|
||||
.env
|
||||
.env.*
|
||||
*.json
|
||||
!backend/
|
||||
!backend/search/
|
||||
!backend/search/*.json
|
||||
*.xlsx
|
||||
*.pdf
|
||||
*.jpg
|
||||
data/
|
||||
docs/
|
||||
tools/
|
||||
__pycache__/
|
||||
*.pyc
|
||||
@@ -0,0 +1 @@
|
||||
FROM caddy:2.11.6-alpine@sha256:881bbc60f9986d5ab8e7cfd6cf7e4ef3c9c0439fef2429d035d065577882f028
|
||||
@@ -0,0 +1,16 @@
|
||||
name: Validate Caddyfile
|
||||
description: Run the pinned Caddy validator against the checked-out Caddyfile
|
||||
inputs:
|
||||
workspace:
|
||||
description: Repository workspace path supplied by the workflow
|
||||
required: true
|
||||
runs:
|
||||
using: docker
|
||||
image: Dockerfile
|
||||
entrypoint: /usr/bin/caddy
|
||||
args:
|
||||
- validate
|
||||
- --config
|
||||
- ${{ inputs.workspace }}/deploy/production/Caddyfile
|
||||
- --adapter
|
||||
- caddyfile
|
||||
@@ -0,0 +1 @@
|
||||
FROM ghcr.io/osscontainertools/kaniko:v1.28.5-debug@sha256:c73ca67a3b494bce79a8fb6090c4f73c18997ab272d80bffc460a62343aeb412
|
||||
@@ -0,0 +1,22 @@
|
||||
name: Build image with Kaniko in a rootless container
|
||||
description: Validate a Dockerfile by building it without publishing the image or cache
|
||||
inputs:
|
||||
workspace:
|
||||
description: Repository workspace path supplied by the workflow
|
||||
required: true
|
||||
dockerfile:
|
||||
description: Dockerfile path relative to the checked-out repository
|
||||
required: true
|
||||
destination:
|
||||
description: Image reference required by Kaniko; the image is not pushed
|
||||
required: true
|
||||
runs:
|
||||
using: docker
|
||||
image: Dockerfile
|
||||
entrypoint: /kaniko/executor
|
||||
args:
|
||||
- --context=dir://${{ inputs.workspace }}
|
||||
- --dockerfile=${{ inputs.workspace }}/${{ inputs.dockerfile }}
|
||||
- --destination=${{ inputs.destination }}
|
||||
- --no-push
|
||||
- --no-push-cache
|
||||
@@ -0,0 +1,4 @@
|
||||
FROM ghcr.io/osscontainertools/kaniko:v1.28.5-debug@sha256:c73ca67a3b494bce79a8fb6090c4f73c18997ab272d80bffc460a62343aeb412
|
||||
COPY release-build.sh /usr/local/bin/release-build
|
||||
COPY validate-destination.sh /usr/local/bin/validate-destination.sh
|
||||
ENTRYPOINT ["/busybox/sh", "/usr/local/bin/release-build"]
|
||||
@@ -0,0 +1,23 @@
|
||||
name: Publish a pinned Akyldash image
|
||||
description: Build and push one commit-tagged image with pinned rootless Kaniko
|
||||
inputs:
|
||||
workspace:
|
||||
description: Checked out source directory
|
||||
required: true
|
||||
dockerfile:
|
||||
description: Dockerfile path relative to workspace
|
||||
required: true
|
||||
destination:
|
||||
description: Commit-specific OCI tag
|
||||
required: true
|
||||
digest_file:
|
||||
description: Workspace path for Kaniko's resulting digest
|
||||
required: true
|
||||
runs:
|
||||
using: docker
|
||||
image: Dockerfile
|
||||
args:
|
||||
- ${{ inputs.workspace }}
|
||||
- ${{ inputs.dockerfile }}
|
||||
- ${{ inputs.destination }}
|
||||
- ${{ inputs.digest_file }}
|
||||
@@ -0,0 +1,22 @@
|
||||
#!/busybox/sh
|
||||
set -eu
|
||||
|
||||
workspace=$1
|
||||
dockerfile=$2
|
||||
destination=$3
|
||||
digest_file=$4
|
||||
: "${REGISTRY_USERNAME:?registry username secret is required}"
|
||||
: "${REGISTRY_PASSWORD:?registry password secret is required}"
|
||||
/busybox/sh /usr/local/bin/validate-destination.sh "$dockerfile" "$destination"
|
||||
|
||||
mkdir -p /kaniko/.docker "$(dirname "$digest_file")"
|
||||
auth=$(printf '%s:%s' "$REGISTRY_USERNAME" "$REGISTRY_PASSWORD" | base64 | tr -d '\n')
|
||||
umask 077
|
||||
printf '{"auths":{"git.vakanaut.ru":{"auth":"%s"}}}\n' "$auth" > /kaniko/.docker/config.json
|
||||
unset auth REGISTRY_USERNAME REGISTRY_PASSWORD
|
||||
/kaniko/executor \
|
||||
--context="dir://${workspace}" \
|
||||
--dockerfile="${workspace}/${dockerfile}" \
|
||||
--destination="$destination" \
|
||||
--digest-file="$digest_file" \
|
||||
--no-push-cache
|
||||
@@ -0,0 +1,49 @@
|
||||
#!/bin/sh
|
||||
set -eu
|
||||
|
||||
if [ "$#" -ne 2 ]; then
|
||||
echo 'ERROR: expected Dockerfile path and image destination' >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
dockerfile=$1
|
||||
destination=$2
|
||||
case "$dockerfile" in
|
||||
deploy/production/Dockerfile.backend)
|
||||
repository=git.vakanaut.ru/admin/akyldash/backend
|
||||
;;
|
||||
deploy/production/Dockerfile.opensearch)
|
||||
repository=git.vakanaut.ru/admin/akyldash/opensearch
|
||||
;;
|
||||
*)
|
||||
echo 'ERROR: Dockerfile is outside the approved production image set' >&2
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
|
||||
case "$destination" in
|
||||
"$repository":*) tag=${destination#"$repository":} ;;
|
||||
*)
|
||||
echo 'ERROR: destination is outside the approved registry repository' >&2
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
|
||||
commit=${tag%%-*}
|
||||
run_id=${tag#*-}
|
||||
case "$commit" in
|
||||
''|*[!0123456789abcdef]*)
|
||||
echo 'ERROR: destination commit must be a lowercase Git SHA-1' >&2
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
if [ "${#commit}" -ne 40 ] || [ "$run_id" = "$tag" ]; then
|
||||
echo 'ERROR: destination tag must contain a 40-character commit and run ID' >&2
|
||||
exit 2
|
||||
fi
|
||||
case "$run_id" in
|
||||
''|*[!0123456789]*)
|
||||
echo 'ERROR: destination run ID must be numeric' >&2
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
@@ -0,0 +1,95 @@
|
||||
name: CI
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
push:
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
tests-and-images:
|
||||
runs-on: akyldash-local-ci
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.12"
|
||||
- name: Run backend tests
|
||||
run: PYTHONPATH=backend python3 -m unittest discover -s backend -p 'test_*.py' -v
|
||||
- name: Run Telegram bot tests
|
||||
run: python3 -m unittest discover -s tools/telegram-bot -p 'test_*.py' -v
|
||||
- name: Run infrastructure backup tests
|
||||
run: python3 -m unittest discover -s infra/backup -p 'test_*.py' -v
|
||||
- name: Check root guard UID decisions
|
||||
run: bash infra/bootstrap/test-root-guard.sh
|
||||
- name: Check recovery host guard
|
||||
run: bash infra/bootstrap/test-host-guard.sh
|
||||
- name: Check verifier helper argument guard
|
||||
run: bash infra/bootstrap/test-verify-helper.sh
|
||||
- name: Check host audit root guard
|
||||
run: bash infra/bootstrap/test-audit-host.sh
|
||||
- name: Check Compose helper allowlist
|
||||
run: bash infra/deploy/test-compose-helper.sh
|
||||
- name: Check production config root guard
|
||||
run: bash infra/deploy/test-production-config-guard.sh
|
||||
- name: Check runner config and isolation guards
|
||||
run: |
|
||||
bash infra/runner/test-runner-config.sh
|
||||
bash infra/runner/test-install-runner-idempotency.sh
|
||||
bash infra/runner/test-install-runner-guard.sh
|
||||
- name: Check CI container operation isolation
|
||||
run: bash infra/runner/test-ci-container-builds.sh
|
||||
- name: Check infrastructure shell syntax
|
||||
run: |
|
||||
bash -n infra/bootstrap/bootstrap-ubuntu-24.04.sh infra/bootstrap/host-guard.sh \
|
||||
infra/bootstrap/verify.sh infra/bootstrap/verify-helper.sh infra/bootstrap/audit-host.sh \
|
||||
infra/deploy/install-helper.sh infra/deploy/compose-helper.sh infra/deploy/test-compose-helper.sh \
|
||||
infra/deploy/prepare-production-config.sh infra/deploy/test-production-config-guard.sh \
|
||||
.gitea/actions/kaniko-push/release-build.sh \
|
||||
infra/bootstrap/test-audit-host.sh infra/bootstrap/test-root-guard.sh \
|
||||
infra/bootstrap/test-verify-helper.sh infra/test/run-as-unprivileged.sh \
|
||||
infra/runner/install-runner.sh infra/runner/install-runner-lib.sh \
|
||||
infra/runner/act-runner-healthcheck.sh infra/runner/test-runner-config.sh \
|
||||
infra/runner/test-install-runner-idempotency.sh infra/runner/test-install-runner-guard.sh \
|
||||
infra/runner/test-ci-container-builds.sh
|
||||
python3 -c "import ast,pathlib; ast.parse(pathlib.Path('infra/runner/secure-runner-image.py').read_text())"
|
||||
python3 -c "import ast,pathlib; ast.parse(pathlib.Path('infra/deploy/validate_release.py').read_text())"
|
||||
python3 -c "import ast,pathlib; ast.parse(pathlib.Path('infra/deploy/deploy_release.py').read_text())"
|
||||
python3 -c "import ast,pathlib; ast.parse(pathlib.Path('infra/deploy/create_release_manifest.py').read_text())"
|
||||
python3 -c "import ast,pathlib; ast.parse(pathlib.Path('infra/deploy/release_handoff.py').read_text())"
|
||||
python3 -c "import ast,pathlib; ast.parse(pathlib.Path('infra/deploy/release_refs.py').read_text())"
|
||||
python3 -c "import ast,pathlib; ast.parse(pathlib.Path('infra/deploy/release_state.py').read_text())"
|
||||
python3 -c "import ast,pathlib; ast.parse(pathlib.Path('infra/deploy/deployment_lock.py').read_text())"
|
||||
- name: Run deployment contract and rollback tests
|
||||
run: python3 -m unittest discover -s infra/deploy -p 'test_*.py' -v
|
||||
- name: Validate production Compose and Caddyfile
|
||||
run: |
|
||||
secret_file=$(mktemp)
|
||||
trap 'rm -f "$secret_file"' EXIT
|
||||
REVIEW_SECRET_FILE="$secret_file" docker compose --env-file deploy/production/.env.example -f deploy/production/compose.yaml config --quiet
|
||||
- name: Validate Caddyfile in isolated container action
|
||||
uses: ./.gitea/actions/caddy-validate
|
||||
with:
|
||||
workspace: ${{ github.workspace }}
|
||||
- name: Build production images
|
||||
uses: ./.gitea/actions/kaniko-build
|
||||
with:
|
||||
workspace: ${{ github.workspace }}
|
||||
dockerfile: deploy/production/Dockerfile.backend
|
||||
destination: akyldash-backend:ci
|
||||
- name: Build OpenSearch production image
|
||||
uses: ./.gitea/actions/kaniko-build
|
||||
with:
|
||||
workspace: ${{ github.workspace }}
|
||||
dockerfile: deploy/production/Dockerfile.opensearch
|
||||
destination: akyldash-opensearch:ci
|
||||
- name: Prepare a synthetic artifact compatibility marker
|
||||
run: |
|
||||
mkdir -p artifact-smoke
|
||||
printf 'Gitea artifact upload smoke test; no release data.\n' > artifact-smoke/marker.txt
|
||||
- name: Verify Gitea runtime artifact upload
|
||||
uses: https://gitea.com/actions/gitea-upload-artifact@055b8b3f04a4a7ed853f2c6ab04256f83e4874dc
|
||||
with:
|
||||
name: artifact-smoke-${{ github.run_id }}
|
||||
path: artifact-smoke/marker.txt
|
||||
if-no-files-found: error
|
||||
retention-days: 1
|
||||
@@ -0,0 +1,64 @@
|
||||
name: Production handoff status (not deployed)
|
||||
|
||||
on:
|
||||
workflow_run:
|
||||
workflows: ["Release production images"]
|
||||
branches: [main]
|
||||
types: [completed]
|
||||
|
||||
jobs:
|
||||
deployment-status:
|
||||
name: NOT DEPLOYED - handoff status only
|
||||
if: >-
|
||||
gitea.event.workflow_run.conclusion == 'success' &&
|
||||
gitea.event.workflow_run.event == 'workflow_run' &&
|
||||
gitea.event.workflow_run.head_branch == 'main'
|
||||
runs-on: akyldash-local-ci
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
ref: main
|
||||
- name: Verify source release identity before artifact lookup
|
||||
env:
|
||||
SOURCE_WORKFLOW: ${{ gitea.event.workflow.name }}
|
||||
SOURCE_WORKFLOW_PATH: ${{ gitea.event.workflow_run.path }}
|
||||
SOURCE_EVENT: ${{ gitea.event.workflow_run.event }}
|
||||
SOURCE_CONCLUSION: ${{ gitea.event.workflow_run.conclusion }}
|
||||
SOURCE_BRANCH: ${{ gitea.event.workflow_run.head_branch }}
|
||||
SOURCE_RUN_ID: ${{ gitea.event.workflow_run.id }}
|
||||
SOURCE_SHA: ${{ gitea.event.workflow_run.head_sha }}
|
||||
SOURCE_REPOSITORY: ${{ gitea.event.repository.full_name }}
|
||||
run: python3 infra/deploy/release_handoff.py validate-handoff-source
|
||||
- name: Read artifact metadata with the installed Gitea helper when available
|
||||
env:
|
||||
GITEA_URL: ${{ gitea.server_url }}
|
||||
GITEA_TOKEN: ${{ gitea.token }}
|
||||
SOURCE_RUN_ID: ${{ gitea.event.workflow_run.id }}
|
||||
SOURCE_WORKFLOW: ${{ gitea.event.workflow.name }}
|
||||
SOURCE_WORKFLOW_PATH: ${{ gitea.event.workflow_run.path }}
|
||||
SOURCE_EVENT: ${{ gitea.event.workflow_run.event }}
|
||||
SOURCE_CONCLUSION: ${{ gitea.event.workflow_run.conclusion }}
|
||||
SOURCE_BRANCH: ${{ gitea.event.workflow_run.head_branch }}
|
||||
SOURCE_SHA: ${{ gitea.event.workflow_run.head_sha }}
|
||||
SOURCE_REPOSITORY: ${{ gitea.event.repository.full_name }}
|
||||
run: |
|
||||
if ! command -v gitea-api >/dev/null 2>&1; then
|
||||
echo 'DRY-RUN only: gitea-api is unavailable in this job; artifact metadata and host handoff are not verified.'
|
||||
python3 infra/deploy/release_handoff.py dry-run
|
||||
exit 0
|
||||
fi
|
||||
if [[ -z ${GITEA_TOKEN:-} ]]; then
|
||||
echo 'DRY-RUN only: GITEA_TOKEN is unavailable; artifact metadata and host handoff are not verified.'
|
||||
python3 infra/deploy/release_handoff.py dry-run
|
||||
exit 0
|
||||
fi
|
||||
metadata=$(mktemp)
|
||||
trap 'rm -f "$metadata"' EXIT
|
||||
gitea-api GET "/repos/admin/akyldash/actions/runs/${SOURCE_RUN_ID}/artifacts" > "$metadata"
|
||||
python3 infra/deploy/release_handoff.py dry-run --artifact-metadata "$metadata"
|
||||
- name: State that no deployment was performed
|
||||
run: |
|
||||
echo 'DEPLOYMENT STATUS: NOT DEPLOYED'
|
||||
echo 'This workflow checks source provenance and may inspect artifact metadata only.'
|
||||
echo 'It does not download the descriptor ZIP, open SSH, or invoke the Windows receiver.'
|
||||
echo 'No Windows execution runner or automatic runtime binding has been verified.'
|
||||
@@ -0,0 +1,90 @@
|
||||
name: Release production images
|
||||
|
||||
on:
|
||||
workflow_run:
|
||||
workflows: ["CI"]
|
||||
branches: [main]
|
||||
types: [completed]
|
||||
|
||||
jobs:
|
||||
publish-images:
|
||||
if: >-
|
||||
gitea.event.workflow_run.conclusion == 'success' &&
|
||||
gitea.event.workflow_run.event == 'push' &&
|
||||
gitea.event.workflow_run.head_branch == 'main'
|
||||
runs-on: akyldash-local-ci
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
ref: ${{ gitea.event.workflow_run.head_sha }}
|
||||
- name: Verify successful CI source before using registry credentials
|
||||
env:
|
||||
SOURCE_WORKFLOW: ${{ gitea.event.workflow.name }}
|
||||
SOURCE_WORKFLOW_PATH: ${{ gitea.event.workflow_run.path }}
|
||||
SOURCE_EVENT: ${{ gitea.event.workflow_run.event }}
|
||||
SOURCE_CONCLUSION: ${{ gitea.event.workflow_run.conclusion }}
|
||||
SOURCE_BRANCH: ${{ gitea.event.workflow_run.head_branch }}
|
||||
SOURCE_RUN_ID: ${{ gitea.event.workflow_run.id }}
|
||||
SOURCE_SHA: ${{ gitea.event.workflow_run.head_sha }}
|
||||
SOURCE_REPOSITORY: ${{ gitea.event.repository.full_name }}
|
||||
run: python3 infra/deploy/release_handoff.py validate-ci-source
|
||||
- name: Require explicitly configured Gitea registry credentials
|
||||
env:
|
||||
REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
|
||||
REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
|
||||
run: |
|
||||
test -n "$REGISTRY_USERNAME" || { echo 'REGISTRY_USERNAME repository secret is required'; exit 1; }
|
||||
test -n "$REGISTRY_PASSWORD" || { echo 'REGISTRY_PASSWORD repository secret is required'; exit 1; }
|
||||
- name: Build and publish backend image
|
||||
uses: ./.gitea/actions/kaniko-push
|
||||
env:
|
||||
REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
|
||||
REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
|
||||
with:
|
||||
workspace: ${{ github.workspace }}
|
||||
dockerfile: deploy/production/Dockerfile.backend
|
||||
destination: git.vakanaut.ru/admin/akyldash/backend:${{ gitea.event.workflow_run.head_sha }}-${{ gitea.run_id }}
|
||||
digest_file: ${{ github.workspace }}/release/backend.digest
|
||||
- name: Build and publish OpenSearch image
|
||||
uses: ./.gitea/actions/kaniko-push
|
||||
env:
|
||||
REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
|
||||
REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
|
||||
with:
|
||||
workspace: ${{ github.workspace }}
|
||||
dockerfile: deploy/production/Dockerfile.opensearch
|
||||
destination: git.vakanaut.ru/admin/akyldash/opensearch:${{ gitea.event.workflow_run.head_sha }}-${{ gitea.run_id }}
|
||||
digest_file: ${{ github.workspace }}/release/opensearch.digest
|
||||
- name: Create and validate release descriptor
|
||||
run: |
|
||||
python3 infra/deploy/create_release_manifest.py \
|
||||
--repository admin/akyldash \
|
||||
--commit '${{ gitea.event.workflow_run.head_sha }}' \
|
||||
--run-id '${{ gitea.run_id }}' \
|
||||
--source-run-id '${{ gitea.event.workflow_run.id }}' \
|
||||
--backend-digest release/backend.digest \
|
||||
--opensearch-digest release/opensearch.digest \
|
||||
--output release/release-manifest.json
|
||||
python3 infra/deploy/validate_release.py release/release-manifest.json \
|
||||
--policy infra/deploy/release-policy.json
|
||||
(cd release && sha256sum release-manifest.json > release-manifest.json.sha256)
|
||||
- id: descriptor
|
||||
name: Record release descriptor digest
|
||||
run: |
|
||||
(cd release && sha256sum -c release-manifest.json.sha256)
|
||||
digest=$(sha256sum release/release-manifest.json)
|
||||
digest=${digest%% *}
|
||||
printf 'descriptor_sha256=%s\n' "$digest" >> "$GITEA_OUTPUT"
|
||||
- name: Upload verified release descriptor
|
||||
uses: https://gitea.com/actions/gitea-upload-artifact@055b8b3f04a4a7ed853f2c6ab04256f83e4874dc
|
||||
with:
|
||||
name: release-descriptor-${{ gitea.run_id }}-${{ steps.descriptor.outputs.descriptor_sha256 }}
|
||||
path: |
|
||||
release/release-manifest.json
|
||||
release/release-manifest.json.sha256
|
||||
if-no-files-found: error
|
||||
retention-days: 90
|
||||
- name: Confirm uploaded release descriptor
|
||||
run: |
|
||||
(cd release && sha256sum -c release-manifest.json.sha256)
|
||||
echo 'Release descriptor and checksum are available as this run artifact.'
|
||||
@@ -0,0 +1,24 @@
|
||||
name: Runner smoke test
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
push:
|
||||
branches: [main]
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
runner-smoke:
|
||||
runs-on: akyldash-local-ci
|
||||
steps:
|
||||
- name: Verify isolated runner boundary
|
||||
run: |
|
||||
host_uid=$(awk 'NR == 1 {print $2}' /proc/self/uid_map)
|
||||
test "$host_uid" -gt 0
|
||||
test ! -S /var/run/docker.sock
|
||||
test ! -e /run/user/1000/docker.sock
|
||||
test -z "${DOCKER_HOST:-}"
|
||||
test ! -e /etc/akyldash/production.env
|
||||
test ! -e /etc/akyldash/review_secret
|
||||
test ! -e /opt/akyldash/current
|
||||
printf 'Isolated runner: version=%s host=%s uid-map=%s\n' \
|
||||
"$GITEA_ACTIONS_RUNNER_VERSION" "$(hostname)" "$host_uid"
|
||||
@@ -1,10 +1,12 @@
|
||||
# Local credentials and secrets
|
||||
credentials.json
|
||||
codex.json
|
||||
|
||||
# Python/runtime artifacts (for the upcoming bot implementation)
|
||||
__pycache__/
|
||||
.venv/
|
||||
*.py[cod]
|
||||
tools/frontend-visual-review/node_modules/
|
||||
|
||||
# Local environment files
|
||||
.env
|
||||
@@ -16,3 +18,7 @@ data/
|
||||
|
||||
# Local runtime logs
|
||||
logs/
|
||||
|
||||
# Local generated reports; deliberately publish reviewed/sanitized evidence with git add -f
|
||||
/reports/
|
||||
/tmp/
|
||||
@@ -0,0 +1,35 @@
|
||||
{
|
||||
"detector": {
|
||||
"ignoreRules": [],
|
||||
"ignoreFiles": [],
|
||||
"ignoreValues": [
|
||||
{
|
||||
"rule": "cream-palette",
|
||||
"value": "*",
|
||||
"files": [
|
||||
"backend/search/review.html"
|
||||
],
|
||||
"createdAt": "2026-10-11T15:40:02.635Z",
|
||||
"reason": "Agent: DESIGN.md explicitly approves the #F7F2E8 felt-inspired bg token for this portal; current page background matches that user-approved palette"
|
||||
},
|
||||
{
|
||||
"rule": "cramped-padding",
|
||||
"value": "*",
|
||||
"files": [
|
||||
"backend/search/review.html"
|
||||
],
|
||||
"createdAt": "2026-10-11T15:41:28.434Z",
|
||||
"reason": "Agent: current page uses 12–24px padding in bordered containers; the prior stop finding has no element detail and does not reproduce in the current detector"
|
||||
},
|
||||
{
|
||||
"rule": "design-system-font",
|
||||
"value": "sans",
|
||||
"files": [
|
||||
"backend/search/review.html"
|
||||
],
|
||||
"createdAt": "2026-10-11T15:41:33.020Z",
|
||||
"reason": "Agent: DESIGN.md specifies Noto Sans with sans-serif fallback; this finding is the inherited generic fallback"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,84 @@
|
||||
# Акылдаш — инструкции для агента
|
||||
|
||||
Проект: юридическая информационно-аналитическая платформа; Search API на
|
||||
Python, SQLite и OpenSearch. Для инфраструктурных задач используй Skill
|
||||
`commerce-infra`, контур `commerce`, проект `akyldash`. Сверяй состояние с
|
||||
[`CURRENT_STATE.md`](docs/operations/CURRENT_STATE.md) и
|
||||
[правилами доступа](docs/operations/ACCESS.md). HTTP 200 сам по себе не
|
||||
подтверждает готовность индекса или восстановимость данных.
|
||||
- Архитектура и процедуры: [инфраструктура](docs/operations/INFRASTRUCTURE.md),
|
||||
[деплой](docs/operations/DEPLOYMENT.md), [backup](docs/operations/BACKUP.md),
|
||||
[rollback](docs/operations/ROLLBACK.md), [восстановление](docs/operations/RECOVERY.md).
|
||||
- `main` защищена. Изменения проходят через PR по правилам ниже.
|
||||
- Доступ к VPS для диагностики ограничен read-only. Не давай серверному
|
||||
пользователю `codex` общий sudo или доступ к Docker socket. Root-действия
|
||||
выполняет владелец.
|
||||
- Репозиторный Gitea Actions runner описан в
|
||||
[CI_RUNNER.md](docs/operations/CI_RUNNER.md). Регистрация выполняется
|
||||
владельцем через Settings → Actions → Runners для `admin/akyldash`; токен
|
||||
вводится интерактивно и не попадает в Git. Runner использует отдельный
|
||||
rootless Docker daemon; job-контейнеры не получают Docker socket или
|
||||
production secrets. Не включай production deployment из CI без отдельного
|
||||
проверенного deploy-helper.
|
||||
- Локальные проверки: `PYTHONPATH=backend python3 -m unittest discover -s backend -p 'test_*.py' -v` и
|
||||
`python3 -m unittest discover -s tools/telegram-bot -p 'test_*.py' -v`,
|
||||
`python3 -m unittest discover -s infra/backup -p 'test_*.py' -v` и
|
||||
`python3 -m unittest discover -s infra/deploy -p 'test_*.py' -v`,
|
||||
`bash infra/bootstrap/test-host-guard.sh`.
|
||||
Production images собираются командами из `.gitea/workflows/ci.yaml`.
|
||||
- Перед изменениями production необходим проверенный backup. Формального
|
||||
механизма миграций нет; проверяй совместимость SQLite/OpenSearch. Не меняй
|
||||
SSH, firewall или production вручную без владельца и последующего PR.
|
||||
- Холодный backup требует согласованного окна простоя; восстановление допускается
|
||||
только в новый staging-каталог, пока владелец отдельно не проверил процедуру
|
||||
для нового хоста.
|
||||
- После каждого изменения инфраструктуры обновляй
|
||||
`docs/operations/CURRENT_STATE.md` по фактическим проверкам.
|
||||
|
||||
## Delivery First: проверка по уровню риска
|
||||
|
||||
- Перед работой укажи в PR уровень `LOW`, `MEDIUM` или `HIGH`; при сомнении
|
||||
выбери более высокий. Уровень добавляет нужную проверку, но никогда не
|
||||
отменяет CI, одобрение или защиту `main`.
|
||||
- Каждый PR сохраняет текущие проверки Gitea Actions: job IDs
|
||||
`tests-and-images` и `runner-smoke`. Не переименовывай и не обходи их, не
|
||||
удаляй тесты или проверки безопасности ради скорости.
|
||||
- `LOW`: документация, комментарии и тексты без изменения исполняемого
|
||||
поведения или контракта; проверяй diff и актуальность утверждений, затем
|
||||
дождись обычного CI.
|
||||
- `MEDIUM`: изменение поведения в одном компоненте; добавь регрессионный тест,
|
||||
выполни целевые проверки и обычный CI.
|
||||
- `HIGH`: доступ/авторизация, данные и ingestion, схемы/хранилища,
|
||||
backup/restore/recovery, production config, секреты, runner/CI, безопасность
|
||||
или deploy; выполни целевые тесты вместе с обычным CI и приложи проверяемое
|
||||
обоснование угроз, совместимости и rollback. Production-действия остаются
|
||||
за владельцем.
|
||||
- Ревью блокирует только конкретный воспроизводимый дефект, нарушение границы
|
||||
доступа/безопасности, несовместимость данных или контракта, пропущенную
|
||||
обязательную проверку либо отсутствие безопасного rollback. Идеи и стилистические
|
||||
замечания перечисляй отдельно как неблокирующие.
|
||||
- Полная процедура, метрики, Gitea-ограничения и проверенные временные бюджеты:
|
||||
[DELIVERY_POLICY.md](docs/development/DELIVERY_POLICY.md).
|
||||
|
||||
## Согласование изменений
|
||||
|
||||
- Создавай ветку от актуальной `main`, коммиты и PR через Gitea Codex MCP.
|
||||
Обновления вноси в тот же PR. Автор не одобряет и не сливает свой PR.
|
||||
- После каждого push отдельный ревьюер проверяет полный diff относительно
|
||||
base и ранее найденные дефекты. Формальное ревью публикуется через Gitea
|
||||
Agent MCP. Разные учётные записи обеспечивают разделение полномочий.
|
||||
Независимость требует отдельного исполнителя ревью.
|
||||
- После первого успешного ревью и CI внеси значимое изменение в существующий
|
||||
changelog и отправь коммит в тот же PR. Повтори полное ревью итогового diff
|
||||
и CI. Для docs-only задачи версию приложения повышай только при явном
|
||||
требовании к этой правке.
|
||||
- Merge через Gitea Agent MCP допускается после независимого ревью и только
|
||||
при явном разрешении владельца репозитория. Перед слиянием проверь `admin/akyldash`, номер PR, автора `codex`, base
|
||||
`main`, ожидаемую ветку и точные SHA head/base. Нужны все успешные
|
||||
обязательные checks и gates, отсутствие открытых блокеров и действующих
|
||||
`REQUEST_CHANGES`, формальный `APPROVED` от `agent` с
|
||||
`commit_id == head_sha`, `stale == false` и `dismissed == false`.
|
||||
При изменении head или base повтори проверки и ревью. Используй обычный
|
||||
server-side merge с `head_commit_id`, без force и обхода branch protection.
|
||||
При неизвестном, ожидающем или неуспешном обязательном условии оставь PR
|
||||
открытым и укажи причину.
|
||||
@@ -2,7 +2,187 @@
|
||||
|
||||
## Не выпущено
|
||||
|
||||
- Документация: инструкции Акылдаша переведены на нативный Windows Codex,
|
||||
`commerce-infra` и Gitea MCP. Сохранены независимое ревью, обязательные
|
||||
CI-проверки, одобрение текущего head и ограничения production-доступа.
|
||||
- Deployment: подготовлен внешний handoff для Windows-клиента от точного Gitea
|
||||
commit. Bundle фиксирует commit/tree/blob identity и SHA-256; installer
|
||||
проверяет bundle и ACL до записи и не запускает Git. Bootstrap на release A
|
||||
может подготовить release B только при точном совпадении pinned runtime-файлов
|
||||
и release policy. Первый Windows task остаётся preparation-only; отдельные
|
||||
auto-apply config и task выключены. Изолированный PowerShell 5.1 harness для
|
||||
bundle-проверки завершился успешно на точном PR SHA; реальная установка,
|
||||
регистрация задач, SSH и production не выполнялись и не активировались.
|
||||
- Infrastructure: Windows release installer и external receiver читают владельцев
|
||||
и ACL ACE напрямую как SID, без преобразования в имена учётных записей. Это
|
||||
устраняет зависимость проверки от разрешения имён; неизвестные SID остаются
|
||||
видимыми и отклоняются существующими fail-closed guard-политиками. Проверены
|
||||
synthetic unmapped-SID fixtures и read-only ACL preflight; production ACL не
|
||||
менялись.
|
||||
- Документация: объединены продуктовый, UI- и deployment-планы; уточнены
|
||||
внешняя backup-retention политика и обязательный owner-approved maintenance
|
||||
window для cold backup. Передача корпуса требует атомарной публикации
|
||||
проверенного staging в `DATA_ROOT`; безопасное возобновление либо fail-closed
|
||||
при прерывании остаётся release gate. Механизм атомарной публикации ещё не
|
||||
реализован.
|
||||
- Backend `0.13.4` / Frontend `0.3.4`, алгоритм поиска `search-8`: для явно
|
||||
заданного multi-index поиска включена глобальная статистика DFS; signed review
|
||||
snapshots сохраняют полный index scope, а пустую выдачу можно сохранить с
|
||||
обязательным общим комментарием и точной проверкой рангов. Узкое расширение
|
||||
термина аренды сохранено без глобальных весов. На executable SHA
|
||||
`1c7ddf2` выполнен полный isolated прогон 7 500 запросов: изменились 537
|
||||
порядков относительно исходного baseline, 6 выдач остались пустыми; это
|
||||
наблюдения ранжирования, не экспертная оценка права. Три актуальных акта
|
||||
проверялись только в отдельном локальном supplement; production и исходный
|
||||
индекс не менялись.
|
||||
- Успешный CI на `push` в `main` запускает release workflow: при настроенных
|
||||
registry secrets он собирает образы rootless Kaniko, публикует digest
|
||||
references и сохраняет schema-v4 descriptor с SHA-256 в Gitea artifact;
|
||||
sidecar проверяется после извлечения из корня. Следующий workflow проверяет
|
||||
source-run identity и, при доступном `gitea-api`, метаданные артефакта только
|
||||
в dry-run и явно сообщает `NOT DEPLOYED`: ZIP не скачивается, SSH и host
|
||||
apply не выполняются. Добавлена отдельная root-verified status→fixed-tuple→
|
||||
Windows `--once` привязка через строгий SSH dispatcher; она не использует
|
||||
Gitea/PR runner и не требует Gitea token на Windows. Config и Task Scheduler
|
||||
template выключены, задача не зарегистрирована и production CD не активирован.
|
||||
Зелёный handoff не означает деплой. Подготовлены owner-run cutover и rollback с
|
||||
проверкой backup, image IDs, RU/KY canaries и recovery journal; CI проверяет
|
||||
synthetic artifact и завершается ошибкой при отсутствии файлов. Windows
|
||||
receiver прошёл 17 synthetic client checks, 8 protocol checks и проверку
|
||||
private owner ACL на disposable real-NTFS fixture. Inert Windows argv probe
|
||||
подтвердил передачу пути скрипта с пробелами; Task Scheduler COM проверил
|
||||
XML с `TASK_VALIDATE_ONLY` — задачу не регистрировали, не обновляли и не
|
||||
запускали. Production D: path, SSH, установка на VPS и полный backup/restore
|
||||
не проверены; cutover остаётся заблокирован до отдельного restore-теста и
|
||||
owner bootstrap. Принимаются только завершённые успешные Gitea runs; pending
|
||||
recovery journal записывается до остановки
|
||||
сервисов, повторно применённый release отклоняется до простоя, а проверка
|
||||
`main` использует явно заданный production checkout. Windows preflight
|
||||
проверяет owner ACL и требует свободное место под максимальный допустимый
|
||||
архив.
|
||||
- Frontend `0.3.3` / Backend `0.13.2`: управление пользователями отображается
|
||||
согласно правам аккаунта, подписи ролей локализованы, повторяющиеся действия
|
||||
кабинета убраны, а знак лаборатории приведён к основному бренду.
|
||||
- Добавлена политика Delivery First по уровням `LOW`/`MEDIUM`/`HIGH`: описаны
|
||||
обязательная глубина проверок, регрессионные тесты и доказательства угроз,
|
||||
совместимости и отката; обычные CI, одобрение и защита `main` остаются
|
||||
обязательными.
|
||||
- Frontend `0.3.2`: устранены пересечения названия бренда с поиском и
|
||||
мобильной навигации документа; навигационные ссылки получили общие quiet и
|
||||
primary состояния.
|
||||
- Frontend `0.3.1`: уточнена компоновка поиска, лаборатории и кабинета;
|
||||
splitter сохраняет минимальную ширину панелей, а на средних экранах фильтры
|
||||
открываются доступной боковой панелью. Исправлено отображение футера на
|
||||
маршруте пользователей и browser fixture смены пароля.
|
||||
- Frontend `0.3.0` / Backend `0.13.1`: добавлен доступный splitter для
|
||||
изменения ширины результатов и документа. Язык поиска находится в фильтрах;
|
||||
состояния открытия, оглавление правовых заголовков, лаборатория и кабинет
|
||||
приведены к последовательной и компактной компоновке.
|
||||
- Добавлен план развития платформы со сравнением возможностей «Токтом Онлайн»,
|
||||
пробелов Акылдаша и этапов продуктовой проверки.
|
||||
- Frontend `0.2.6` / Backend `0.13.1`: двухпанельная компоновка поиска
|
||||
сохраняется до ширины 1175 px, чтобы три панели не обрезались при
|
||||
промежуточных ширинах окна.
|
||||
- Frontend `0.2.5` / Backend `0.13.1`: устранены промежуточные переполнения
|
||||
навигации, старый текст больше не остаётся при ошибке загрузки другого
|
||||
документа; очищаются дополнительные URL-атрибуты юридической разметки,
|
||||
включая `srcset` и `ping`. Добавлены fixture-проверки ошибок и гонок загрузки,
|
||||
изоляции ссылок, reflow и безопасных форм управления пользователями.
|
||||
- Frontend `0.2.4` / Backend `0.13.1`: исправлены состояния и адаптивный поиск,
|
||||
чтение документа и лаборатории, доступные диалоги; управление пользователями
|
||||
вынесено на отдельный защищённый экран. Документная разметка очищается от
|
||||
активного HTML и небезопасных ссылок. Добавлены проверки маршрутов и reflow;
|
||||
правовой текст и API управления пользователями не менялись.
|
||||
- Frontend `0.2.3`: добавлен публичный поиск по правовой базе с фильтрами,
|
||||
адаптивной выдачей, просмотром редакций и поиском по тексту документа;
|
||||
внутренняя лаборатория сохранена, её подсказки стали компактнее и привязаны
|
||||
к целевым элементам. Интерфейс использует локальные шрифты Noto Sans и Noto
|
||||
Serif.
|
||||
- Исправлены переключение на доступный язык редакции, очистка содержимого и
|
||||
ссылки на официальный источник при смене документа или ошибке загрузки;
|
||||
подписи фильтров локализуются на кыргызский язык.
|
||||
- Infrastructure: systemd unit Gitea Actions runner теперь использует
|
||||
`ProtectHome=read-only`, сохраняя доступность `/run/user` и существующий
|
||||
writable carve-out для rootless runtime; VPS не изменялся.
|
||||
- Backend `0.12.1`: добавлен ограниченный возобновляемый staging редакций из
|
||||
текущего API Минюста с проверкой точных ID и метаданных, изоляцией от
|
||||
legacy-корпуса и сохранением исходного порядка редакций при нормализации и
|
||||
экспорте. Тест overlap guard задаёт безопасные права fixture независимо от
|
||||
`umask` CI; сам guard не ослаблен.
|
||||
- Rollback preflight проверяет digest-pinned image references по сохранённому
|
||||
image ID и останавливается до изменений deployment; переключение production
|
||||
на digest и полноценный digest rollback пока не реализованы.
|
||||
- Infrastructure: добавлен офлайн-контракт release manifest с точной схемой,
|
||||
digest-ссылками и repository allowlist; проверен Compose override с
|
||||
`--no-build` как требованием будущего deploy. Публикация, provenance и
|
||||
production-деплой не включены.
|
||||
- Добавлен read-only возобновляемый inventory корпуса с полным хешированием,
|
||||
потоковой сверкой, индексируемыми диапазонами путей и provenance SHA-256
|
||||
проверяющего; значения `stat` хранятся без ограничения SQLite INTEGER.
|
||||
Сравнение source/staging сверяет путь, размер и SHA-256, удерживает shared
|
||||
locks и отклоняет пустые корпуса без документов или фрагментов. Runbook и
|
||||
`CURRENT_STATE.md` отражают, что полный аудит корпуса ещё выполняется; это
|
||||
изменение не означает готовность корпуса или production.
|
||||
- CI actions теперь используют workspace, переданный Gitea, для Caddyfile и Kaniko build context; CI run 69 и smoke run 70 прошли на self-hosted runner.
|
||||
- Runner installer сохраняет `HOME` и XDG-пути в user-unit `docker.service`, перезапускает активный daemon и проверяет окружение его процесса.
|
||||
- Runner installer защищает image и mountpoint root-owned home-каталогом, оставляет регистрацию и workspace в runner-owned каталоге, безопасно форматирует образ по открытому FD и проверяет `nosuid,nodev`.
|
||||
- Backend `0.11.3`: ключ подписи поисковых снимков читается из Docker secret-файла, а не из аргументов процесса. Добавлена базовая инфраструктура VPS, Caddy HTTPS proxy с разделёнными Compose-сетями и CI-проверка конфигурации; публикация образов и production-деплой остаются выключены до проверки runner, registry, backup/restore и ограниченного deploy-helper.
|
||||
- Frontend `0.1.2`: на планшетной ширине экран поиска переходит в одну колонку, чтобы фильтры, результаты и документ помещались в окно.
|
||||
- Backend `0.11.2`: смена пароля требует текущий пароль и запрещает оставить прежний, включая временный пароль при первом входе.
|
||||
- Backend `0.11.1` и frontend `0.1.1`: в управлении пользователями показываются даты первого и последнего входа, а также последнего сброса пароля.
|
||||
- Backend `0.11.0` и frontend `0.1.0`: лаборатория переоформлена по дизайн-системе «Түндүк»; добавлены учетные записи, обязательная смена временного пароля, личный кабинет и управление пользователями для `admin`.
|
||||
- Backend обновлён до `0.10.4`: многословный поиск получил низковесный OR fallback с требованием совпадения минимум двух терминов; fallback пропускает распознанные названия нормативных актов.
|
||||
- Backend обновлён до `0.10.3`: запрос о налоге на прибыль поднимает действующий
|
||||
Налоговый кодекс; точное совпадение фразы дополнительно усиливает результат.
|
||||
- Backend обновлён до `0.10.2`: действующие документы ранжируются выше, а
|
||||
утратившие силу — после остальных; из лаборатории удалён пустой блок фрагмента.
|
||||
- Backend обновлён до `0.10.1`: поисковая выдача по регистрации больше не
|
||||
ограничивается только тремя заранее выбранными нормативными актами.
|
||||
- Backend обновлён до `0.10.0`: поисковый API использует общий планировщик
|
||||
запросов, расширяет аббревиатуры ОсОО/ООО/ЖЧК и для запроса о регистрации
|
||||
приоритизирует положение КР 2026 года, закон об обществах и ГК КР.
|
||||
- Backend обновлён до `0.9.4`: из поисковых фрагментов убраны технические маркеры
|
||||
подсветки OpenSearch.
|
||||
- Backend обновлён до `0.9.3`: исправлен локальный индекс production Search API,
|
||||
ошибки поиска показываются в общем status-блоке, а панель сохранения и footer
|
||||
выстроены в обычном порядке документа.
|
||||
- Backend обновлён до `0.9.2`: внутренняя лаборатория получила визуальный
|
||||
polish-проход и короткий повторно запускаемый tutorial для новых проверяющих.
|
||||
- Backend обновлён до `0.9.1`: все статусы из нормализованного корпуса доступны
|
||||
как отдельные фильтры, варианты конституционного закона и указа сопоставляются
|
||||
с подтверждённой юридической силой, неизвестные типы документов сохраняются
|
||||
под общим фильтром без вывода юридической силы.
|
||||
- Уточнено, что внутренняя лаборатория оценивает выдачу собственного OpenSearch;
|
||||
ЦБД Минюста служит источником для подтверждения документов, а прежние Excel/PDF
|
||||
бланки удалены.
|
||||
- Исключены секреты и локальные данные из Docker build context; синхронизирована версия интерфейса.
|
||||
- Добавлен production deployment baseline для Search API и OpenSearch с
|
||||
постоянными хранилищами и healthcheck.
|
||||
- Добавлено восстановление незавершённой разметки из `localStorage` после перезагрузки страницы.
|
||||
- Добавлена внутренняя лаборатория проверки поисковой выдачи: просмотр документов,
|
||||
оценка релевантности 0–3, комментарии и SQLite-экспорт подписанных снимков.
|
||||
- Уточнены доступные состояния и адаптивное поведение внутреннего интерфейса
|
||||
оценки поисковой выдачи.
|
||||
- Добавлен план внутреннего интерфейса оценки поисковой выдачи юристами.
|
||||
- Завершён Search API v1: стабильные справочники, валидный OpenAPI, безопасная
|
||||
пагинация и проверка актуальных редакций в локальном OpenSearch.
|
||||
- Добавлен фильтр Search API v1 по укрупнённой юридической силе. Полная
|
||||
иерархия GeneralClassifiers экспортирована в отдельный черновой каталог;
|
||||
тематическая навигация остаётся вне API v1 до ручного утверждения рубрик и
|
||||
подписей.
|
||||
- Добавлено безопасное переключение alias на новую версию поискового индекса
|
||||
после полной загрузки; checkpoint защищает возобновление загрузки от смены
|
||||
alias.
|
||||
- Добавлен roadmap готовности данных, поиска и API перед проектированием
|
||||
frontend.
|
||||
- Исправлена выдача для явных запросов об открытии ОсОО и ЖЧК: первыми
|
||||
показываются действующие положение о регистрации и закон о хозяйственных
|
||||
товариществах и обществах.
|
||||
- Добавлен CLI `python3 -m search.query` для проверки текущей выдачи локального
|
||||
OpenSearch.
|
||||
- Добавлена инструкция по подготовке и независимой проверке relevance set.
|
||||
- Улучшено ранжирование relevance-оценки: запрос теперь сопоставляет название и
|
||||
текст документа как единое поле.
|
||||
|
||||
## 0.5.0 — 2026-08-15
|
||||
|
||||
|
||||
@@ -0,0 +1,325 @@
|
||||
---
|
||||
name: "Акылдаш · Түндүк"
|
||||
description: "Утверждённая дизайн-система правового портала Кыргызской Республики"
|
||||
colors:
|
||||
bg: "#F7F2E8"
|
||||
surface: "#FFFFFF"
|
||||
surface-muted: "#FBF8F4"
|
||||
text: "#38262A"
|
||||
text-secondary: "#786469"
|
||||
border: "#DED3CE"
|
||||
primary: "#9D2633"
|
||||
primary-hover: "#84202B"
|
||||
primary-active: "#701B24"
|
||||
on-primary: "#FFFFFF"
|
||||
primary-subtle: "#F8EBED"
|
||||
accent: "#A37B32"
|
||||
highlight: "#FFF0C7"
|
||||
focus: "#245C78"
|
||||
success: "#246843"
|
||||
success-bg: "#EAF4EC"
|
||||
warning: "#82520D"
|
||||
warning-bg: "#FFF3DA"
|
||||
error: "#9D2633"
|
||||
error-bg: "#FBEDEF"
|
||||
info: "#245C78"
|
||||
info-bg: "#EAF2F6"
|
||||
typography:
|
||||
document-title:
|
||||
fontFamily: "Noto Serif, serif"
|
||||
fontSize: "32px"
|
||||
fontWeight: 700
|
||||
lineHeight: 1.2
|
||||
section-title:
|
||||
fontFamily: "Noto Serif, serif"
|
||||
fontSize: "24px"
|
||||
fontWeight: 600
|
||||
lineHeight: 1.3
|
||||
document-body:
|
||||
fontFamily: "Noto Sans, sans-serif"
|
||||
fontSize: "18px"
|
||||
fontWeight: 400
|
||||
lineHeight: 1.65
|
||||
control:
|
||||
fontFamily: "Noto Sans, sans-serif"
|
||||
fontSize: "16px"
|
||||
fontWeight: 500
|
||||
lineHeight: 1.5
|
||||
metadata:
|
||||
fontFamily: "Noto Sans, sans-serif"
|
||||
fontSize: "14px"
|
||||
fontWeight: 400
|
||||
lineHeight: 1.5
|
||||
rounded:
|
||||
default: "6px"
|
||||
spacing:
|
||||
xs: "4px"
|
||||
sm: "8px"
|
||||
compact: "12px"
|
||||
md: "16px"
|
||||
lg: "24px"
|
||||
xl: "32px"
|
||||
section: "48px"
|
||||
---
|
||||
|
||||
# Design System: Акылдаш · Түндүк
|
||||
|
||||
## Overview
|
||||
|
||||
**Статус: утверждено пользователем 10 октября 2026 года.** Это нормативная
|
||||
дизайн-система портала и внутренней лаборатории проверки поисковой выдачи.
|
||||
Часть ресурсов и правил уже присутствует в исходном коде, но полное визуальное
|
||||
соответствие и доступность не подтверждаются одним наличием кода. Утверждение
|
||||
дизайна не означает готовность публичного сервиса или разрешение на deployment.
|
||||
|
||||
**Creative North Star: "Түндүк — спокойное пространство для работы с правом".**
|
||||
|
||||
Профессиональный правовой сервис с кыргызской идентичностью: светлый фон
|
||||
цвета войлока, белое поле документа, глубокий красный для действий,
|
||||
тёмный сливовый текст и небольшие золотистые геометрические детали.
|
||||
Главное — читаемость длинных документов и ясная иерархия.
|
||||
|
||||
Это единственная нормативная спецификация дизайна проекта. Требования
|
||||
исходного brief перенесены сюда; отдельный brief и ранние варианты удалены.
|
||||
Название продукта — **Акылдаш**; «УКУК» из ранних концепций не используется.
|
||||
|
||||
Целевые редактируемые состояния, композиция, измерения и критерии приёмки
|
||||
собраны в [плане реализации и приёмки](docs/product/implementation-roadmap.md).
|
||||
Макеты задают визуальное направление, но не источник юридических данных и не
|
||||
доказательство работающих функций. Утверждённые токены не заменяются цветами,
|
||||
взятыми пипеткой из растрового изображения. Изменения постоянных правил
|
||||
вносятся сюда явно.
|
||||
|
||||
**Key Characteristics:**
|
||||
|
||||
- Спокойное чтение и компактные, понятные элементы управления.
|
||||
- Национальная идентичность через палитру, знак и несколько точных деталей.
|
||||
- Поиск и документ сохраняют общий контекст на широком экране.
|
||||
- Единая визуальная система публичного сервиса и внутренней лаборатории.
|
||||
- Содержимое и доступные функции определяются реальными данными и API.
|
||||
|
||||
## Colors
|
||||
|
||||
Нормативные значения находятся в YAML выше. При реализации ключи `colors`
|
||||
переносятся в CSS custom properties `--color-<ключ>` либо эквивалентные
|
||||
семантические токены существующей системы тем. HEX не размножаются
|
||||
по компонентам.
|
||||
|
||||
| Роль | Токен | Применение |
|
||||
|---|---|---|
|
||||
| Светлый войлок | `bg` | Общий фон и окружение рабочей области |
|
||||
| Белый лист | `surface` | Документ, поля и основные поверхности |
|
||||
| Мягкая поверхность | `surface-muted` | Вторичные панели |
|
||||
| Сливовые чернила | `text` | Основной текст и заголовки |
|
||||
| Вторичный текст | `text-secondary` | Метаданные и пояснения |
|
||||
| Разделители | `border` | Контуры и границы панелей |
|
||||
| Глубокий красный | `primary` | Главное действие, ссылки и активная навигация |
|
||||
| Состояния красного | `primary-hover`, `primary-active` | Hover и нажатие |
|
||||
| Текст на красном | `on-primary` | Главная кнопка и активный пункт меню |
|
||||
| Мягкое красное выделение | `primary-subtle` | Выбранный результат, вторичная навигация |
|
||||
| Золотистая геометрия | `accent` | Небольшие декоративные линии |
|
||||
| Найденный фрагмент | `highlight` | Подсветка совпадения с исходным тёмным текстом |
|
||||
| Фокус | `focus` | Контрастная обводка клавиатурного фокуса |
|
||||
| Успех | `success`, `success-bg` | Подтверждение действия, подтверждённый статус |
|
||||
| Предупреждение | `warning`, `warning-bg` | Важные ограничения с текстовым объяснением |
|
||||
| Ошибка | `error`, `error-bg` | Ошибка с доступным действием для восстановления |
|
||||
| Информация | `info`, `info-bg` | Информационные сообщения |
|
||||
|
||||
Статус и ошибка всегда имеют текстовую подпись: цвет не передаёт смысл
|
||||
самостоятельно. Не назначать юридический статус по визуальной эвристике;
|
||||
использовать данные backend. Золотистый не используется для мелкого текста.
|
||||
Контраст проверяется на фактических сочетаниях: обычный текст не менее
|
||||
4.5:1, крупный текст и необходимые графические элементы не менее 3:1.
|
||||
|
||||
## Typography
|
||||
|
||||
**Заголовки документа и разделов:** Noto Serif, веса 600 и 700.
|
||||
**Интерфейс и основной текст:** Noto Sans, веса 400, 500 и 600.
|
||||
Шрифты подключаются штатным способом, предпочтительно локальными WOFF2
|
||||
с `font-display: swap`. В исходном коде на сверенном `main` есть локальные
|
||||
Noto Sans/Serif WOFF2 и OFL-лицензии в `backend/search/static/fonts/`;
|
||||
`review.html` объявляет `font-display: swap`. Это подтверждает наличие ресурсов
|
||||
и CSS, но не их загрузку на production и не полный визуальный аудит символов
|
||||
`Ө ө Ү ү Ң ң`. См. [план реализации и приёмки](docs/product/implementation-roadmap.md).
|
||||
|
||||
| Элемент | Размер | Межстрочный интервал |
|
||||
|---|---|---|
|
||||
| Заголовок документа / страницы документа | 30–32 px; на телефоне 24–26 px | 1.2 |
|
||||
| Заголовок раздела | 22–24 px | 1.3 |
|
||||
| Текст документа | 17–18 px | 1.6–1.7 |
|
||||
| Элементы управления | 14–16 px | По токену `control` |
|
||||
| Метаданные | 13–14 px | По токену `metadata` |
|
||||
|
||||
Мелкий текст не ниже 12 px. Ориентир ширины документа — 65–75 символов
|
||||
в строке. Длинные названия документов и кыргызские подписи переносятся,
|
||||
не обрезаются. Даты, суммы и числовые колонки используют `tabular-nums`,
|
||||
обычные данные не оформляются моноширинным шрифтом.
|
||||
|
||||
## Layout
|
||||
|
||||
Шкала отступов определяется `spacing`. Шапка на desktop — ориентировочно
|
||||
72–88 px. Навигация / фильтры — 220–240 px. Панель контекста, когда
|
||||
существуют соответствующие данные и функции, — 300–340 px. Центральная
|
||||
колонка занимает остаток; это адаптивные ориентиры, а не фиксированная
|
||||
ширина всей страницы.
|
||||
|
||||
Для поискового рабочего экрана: шапка с брендом, поиском и языком;
|
||||
фильтры слева, результаты в середине, открытый документ справа. Оглавление
|
||||
можно сворачивать в подписанную кнопку, чтобы не сужать область чтения.
|
||||
Разворачивание документа и поиск внутри него реализуются только вместе
|
||||
с работающим поведением, а не как декоративные кнопки.
|
||||
|
||||
### Композиция поискового экрана
|
||||
|
||||
- Первая строка desktop: знак и название, разделитель и подпись продукта
|
||||
слева; подписанное поле поиска с очисткой и кнопкой «Найти» в центре;
|
||||
переключатель языка интерфейса справа. Служебные действия авторизованного
|
||||
пользователя не вытесняют поиск и не меняют эту иерархию.
|
||||
- Вторая строка: навигация «Поиск» / «Об источниках» и удаляемые активные
|
||||
фильтры. Сведения о демонстрационном режиме показываются только в нём.
|
||||
- Ниже расположены три смежные панели: фильтры, результаты, документ.
|
||||
Иерархия создаётся фонами и непрерывными тонкими разделителями, без
|
||||
промежутков между самостоятельными карточками панелей.
|
||||
- Фильтры имеют компактные группы, текстовое действие сброса, выбор органа
|
||||
и пару полей даты в одной строке при достаточной ширине. Вид элемента
|
||||
выбора соответствует одиночному или множественному контракту API.
|
||||
- Заголовок результатов и счётчик находятся слева, сортировка справа.
|
||||
Высота строк зависит от содержимого; едины отступы и типографика.
|
||||
Выбранный результат имеет мягкий красный фон, тонкую красную рамку
|
||||
и текстовый признак открытия.
|
||||
- Панель документа начинается с контекстной навигации и разворачивания,
|
||||
затем идут название, компактные метаданные, действия, поиск внутри
|
||||
документа и единое поле чтения. Название документа имеет отдельную
|
||||
типографическую роль, отличную от заголовков интерфейсных панелей.
|
||||
- При коротком содержимом footer расположен у нижней границы окна;
|
||||
длинное содержимое доступно прокруткой без перекрытия текста и управления.
|
||||
Бренд находится слева, фактические версии frontend и backend справа.
|
||||
- Поисковая страница не показывает инструменты оценивания лаборатории.
|
||||
Общие стили и ресурсы не смешивают композицию этих двух сценариев.
|
||||
|
||||
Внутренняя лаборатория сохраняет свой двухпанельный сценарий: фактический
|
||||
порядок результатов и оценивание слева, текст выбранной редакции справа.
|
||||
Она не получает фильтры, аналитику или публичную навигацию исключительно
|
||||
для сходства с концепцией. Панель проверяющего и сохранения не перекрывает
|
||||
результаты и текст документа.
|
||||
|
||||
При недостатке места сначала сворачивается дополнительная панель контекста,
|
||||
затем навигация. На телефоне — одна колонка; связанные материалы и
|
||||
оглавление доступны через подписанные кнопки. В лаборатории сохраняется
|
||||
существующее мобильное открытие документа и возврат фокуса при закрытии.
|
||||
Поиск, действия и метаданные переносятся. Основной текст не требует
|
||||
горизонтальной прокрутки; широкие таблицы имеют отдельную обозначенную
|
||||
область прокрутки.
|
||||
|
||||
Проверочные размеры при реализации: **1280×800, 1440, 1024 и 390 px**.
|
||||
1280×800 — основной размер сравнения поискового экрана с референсом.
|
||||
Это размеры проверки, а не заранее навязанные CSS breakpoints.
|
||||
|
||||
## Elevation & Depth
|
||||
|
||||
Основные поверхности плоские. Иерархия создаётся белым листом на тёплом
|
||||
фоне, отступами, типографикой и тонкими разделителями. Мягкая тень нужна
|
||||
главным образом выпадающим меню и временным панелям. Значения теней
|
||||
уточняются при реализации; декоративное размытие и обилие теней запрещены.
|
||||
|
||||
## Shapes
|
||||
|
||||
Основное скругление — `rounded.default` (6 px), контуры — 1 px.
|
||||
Небольшие статусные метки могут быть округлее. Кнопки не превращаются
|
||||
в капсулы. Границы интерактивных полей обозначаются явным контуром,
|
||||
а не только фоновым цветом или разделителем соседней панели.
|
||||
|
||||
Если утверждённый логотип уже существует, он сохраняется. При отсутствии
|
||||
логотипа допускается небольшой оригинальный геометрический знак,
|
||||
вдохновлённый круглым верхним элементом юрты — түндүком. Знак из
|
||||
генеративного макета является направлением, а не готовым SVG-ассетом.
|
||||
Государственная символика не копируется.
|
||||
|
||||
Тонкий симметричный орнамент по мотивам шырдака допустим на краях шапки
|
||||
и в пустой нижней части навигации. Он выполняется простым SVG,
|
||||
помечается `aria-hidden`, не находится под текстом и не мешает нажатию.
|
||||
На телефоне орнамент сокращается либо убирается.
|
||||
|
||||
Поисковый desktop включает небольшой золотистый орнамент в свободной нижней
|
||||
части панели фильтров. Он не перекрывает длинные списки и не резервирует
|
||||
место ценой недоступности управления. Знак бренда и орнамент поставляются
|
||||
как SVG-ресурсы. Favicon использует тот же знак, адаптированный для малых
|
||||
размеров; проверяется читаемость 16×16 и 32×32. Иконки управления имеют
|
||||
согласованные толщину линий, оптический размер и выравнивание.
|
||||
|
||||
## Components
|
||||
|
||||
Это требования к будущей реализации, а не перечень уже обновлённых компонентов.
|
||||
|
||||
### Кнопки и поля
|
||||
|
||||
- Главная кнопка: `primary` и `on-primary`, высота около 40 px.
|
||||
- Вторичная кнопка: светлая поверхность и явный контур.
|
||||
- На touch-экране область нажатия не менее 44×44 px.
|
||||
- Поля белые, с постоянной подписью; placeholder не заменяет label.
|
||||
- Видимый фокус: обводка `focus` около 2 px с отступом.
|
||||
- Hover, active, focus-visible, disabled, loading, empty и error
|
||||
реализуются последовательно, с понятными сообщениями.
|
||||
- Переходы 120–180 мс, без анимации текста документа;
|
||||
учитывается `prefers-reduced-motion`.
|
||||
|
||||
### Навигация, результаты и документ
|
||||
|
||||
- Активный пункт меню — красный фон и белая подпись; вторичная
|
||||
навигация — `primary-subtle` и тёмно-красный текст.
|
||||
- Активная вкладка обозначена подписью и нижней линией. Длинные подписи
|
||||
переносятся либо прокручиваются без обрезки.
|
||||
- Результаты — упорядоченные строки: название, тип, статус, дата при
|
||||
наличии и выдержка. Каждое поле не оборачивается в отдельную карточку.
|
||||
- Выбранный результат обозначается мягким красным выделением и текстом.
|
||||
- Документ — единый белый лист: заголовок, реальные метаданные,
|
||||
доступные действия, оглавление и текст. Абзацы не разбиваются на карточки.
|
||||
- Подсветка совпадения сохраняет исходный текст; число совпадений
|
||||
и переходы между ними показываются только при работающем поиске.
|
||||
- Источник и выбранная редакция доступны рядом с документом.
|
||||
Недоступный язык не подменяется выдуманным переводом.
|
||||
- Язык интерфейса и язык документа — отдельные состояния:
|
||||
смена интерфейса не должна самовольно менять текст документа.
|
||||
- Footer сохраняет версии frontend и backend. Отсутствующий frontend
|
||||
или макет явно обозначаются, версия не придумывается.
|
||||
|
||||
### Внутренняя оценка выдачи
|
||||
|
||||
Сохраняются шкала 0–3 с полными текстовыми подписями, комментарии,
|
||||
черновик, идентификация проверяющего, сохранение подписанного снимка,
|
||||
обучение и существующие ограничения доступа. Оценки не передаются
|
||||
только цветом. Служебные данные не становятся публичными из-за редизайна.
|
||||
|
||||
### Доступность и состояния
|
||||
|
||||
Семантические заголовки, labels, ссылки и кнопки; иконки без текста
|
||||
имеют доступное имя. Проверяются Tab, Enter, Escape, возврат фокуса
|
||||
и отсутствие клавиатурных ловушек. Статусы доступны скринридеру.
|
||||
Пустая выдача предлагает изменить запрос; ошибка предлагает повторное
|
||||
действие. Ошибка сохранения не уничтожает черновик.
|
||||
|
||||
## Do's and Don'ts
|
||||
|
||||
### Do:
|
||||
|
||||
- Сохранять название «Акылдаш», реальные данные, маршруты, API и права доступа.
|
||||
- Использовать общий слой семантических токенов, существующие компоненты
|
||||
и CSS Modules / BEM согласно правилам соответствующей части проекта.
|
||||
- Разделять официальный текст, сведения о происхождении и выводы системы.
|
||||
- Проверять чтение длинных RU/KY-документов и одноязычные редакции.
|
||||
- Использовать этот документ как нормативную спецификацию для новых экранов.
|
||||
|
||||
### Don't:
|
||||
|
||||
- Не переносить демонстрационные даты, судебные материалы, связи
|
||||
и юридические формулировки из изображения в продукт.
|
||||
- Не добавлять аналитику, сравнение редакций, регистрацию и другие функции
|
||||
только ради сходства с концепцией.
|
||||
- Не менять поисковое ранжирование или сохранение разметки ради оформления.
|
||||
- Не использовать ковровые текстуры, фотографии гор, иллюстрации юрт,
|
||||
крупные флаги, золотые градиенты и декоративное размытие.
|
||||
- Не делать золотистыми мелкие подписи и не передавать смысл одним цветом.
|
||||
- Не добавлять отдельную тёмную тему без задачи; существующую сохранять.
|
||||
- Не считать генеративный скриншот доказательством точных HEX,
|
||||
загрузки Noto или проверки доступности работающего интерфейса.
|
||||
- Не считать утверждение дизайна разрешением на публикацию сервиса.
|
||||
@@ -9,16 +9,29 @@ Telegram-бот — только часть рабочего окружения
|
||||
|
||||
## Текущее состояние
|
||||
|
||||
Сейчас реализованы Telegram-бот-секретарь версии `0.2.2` и backend версии
|
||||
`0.5.0`: подготовка поискового индекса и оценка Recall@K/MRR@K на вручную
|
||||
размеченном наборе запросов.
|
||||
В исходном коде находятся Telegram-бот-секретарь версии `0.2.2`, Search API
|
||||
версии `0.13.4` (алгоритм поиска `search-8`) и frontend `0.3.4` с поисковым
|
||||
экраном, внутренней лабораторией и согласованным отображением доступных
|
||||
действий учетной записи.
|
||||
Авторизация хранится в
|
||||
SQLite; первый пользователь `admin` создаётся интерактивной CLI-командой.
|
||||
Поиск расширяет аббревиатуры организационно-правовых форм, применяет узкий
|
||||
юридический вариант для общего словосочетания «договор аренды» и поднимает
|
||||
действующий Налоговый кодекс для запросов о налоге на прибыль. Ограничения
|
||||
текущего индекса и подтверждённые тестовые ошибки описаны в
|
||||
[отчёте о релевантности](docs/product/search-relevance-findings-2026-11-03.md).
|
||||
Версии описывают код, а не установленный production-релиз; актуальное
|
||||
подтверждённое состояние среды см. в
|
||||
[`docs/operations/CURRENT_STATE.md`](docs/operations/CURRENT_STATE.md).
|
||||
|
||||
| Компонент | Версия | Состояние |
|
||||
|---|---:|---|
|
||||
| Telegram-бот | `0.2.2` | на Synology работает `0.2.1`; обновление после слияния |
|
||||
| Backend | `0.5.0` | добавлена воспроизводимая оценка качества поиска |
|
||||
| Frontend | — | ещё не создан |
|
||||
| Сбор и обработка правовых данных | `0.5.0` | добавлены relevance set и baseline-метрики |
|
||||
| Telegram-бот | `0.2.2` | исходный код; последняя заметка о Synology указывает `0.2.1`, актуальность не перепроверена |
|
||||
| Search API | `0.13.4` | авторизация, серверная capability управления пользователями, поиск и статические ресурсы |
|
||||
| Frontend | `0.3.4` | поиск по правовой базе, просмотр редакций, внутренняя лаборатория и контекстная навигация кабинета |
|
||||
| Загрузчик архива Минюста (`backend/ingestion/minjust_cbd.py`) | `0.9.3` (`APP_VERSION`) | версия CLI и User-Agent в исходном коде |
|
||||
| Нормализатор корпуса (`backend/normalization/minjust_cbd.py`) | CLI `0.10.0` (`APP_VERSION`); формат/алгоритм `1.1.0` (`NORMALIZER_VERSION`) | версия инструмента и версия нормализатора в manifest — разные значения |
|
||||
| Оценка релевантности | формат набора `relevance-set-v1` | отдельная версия компонента не задана; CLI использует Search API `0.13.4` |
|
||||
| RAG и база знаний | — | ещё не созданы |
|
||||
|
||||
## Структура репозитория
|
||||
@@ -34,11 +47,12 @@ tools/
|
||||
backend/
|
||||
ingestion/ получение и обновление правовых источников
|
||||
normalization/ воспроизводимая нормализация исходного архива
|
||||
search/ Search API, авторизация и внутренний frontend
|
||||
```
|
||||
|
||||
Каталоги для загрузки и обработки источников, RAG, backend и frontend будут
|
||||
создаваться с первой реальной задачей в соответствующей области. Это позволит
|
||||
выбрать структуру по фактическим требованиям, а не поддерживать пустой каркас.
|
||||
Внутренний frontend отдаётся существующим Search API без отдельного
|
||||
Node-сервиса. Отдельный публичный frontend остаётся за readiness gate в
|
||||
`docs/product/frontend-design-readiness-plan.md`.
|
||||
|
||||
Начать знакомство с проектом: [документация](docs/README.md) и
|
||||
[обзор продукта](docs/product/project-overview.md).
|
||||
@@ -59,4 +73,4 @@ python3 -m unittest discover -s tools/telegram-bot -v
|
||||
|
||||
---
|
||||
|
||||
Акылдаш · Telegram-бот v0.2.2 · Backend v0.5.0 · Frontend — не создан
|
||||
Акылдаш · Telegram-бот v0.2.2 · Backend v0.13.4 · Frontend v0.3.4
|
||||
@@ -1,11 +1,16 @@
|
||||
# Backend Акылдаш
|
||||
|
||||
Версия: `0.5.0`
|
||||
Версия загрузчика `minjust_cbd.py`: `0.9.3`
|
||||
|
||||
Первая backend-область проекта — загрузка правовых документов из официального
|
||||
Open Data API ЦБД Минюста Кыргызской Республики. Код расположен в
|
||||
`ingestion/minjust_cbd.py`: его можно запускать как CLI сейчас и импортировать
|
||||
из будущего планировщика backend без запуска отдельного процесса.
|
||||
Для передачи корпуса в production обязательна отдельная процедура
|
||||
[CORPUS_HANDOFF.md](../docs/operations/CORPUS_HANDOFF.md); она проверяет
|
||||
source/staging, inventory и checksum, решение по code 6, публикацию и
|
||||
готовность индекса. Этот runbook — release gate; команды передачи здесь не
|
||||
дублируются.
|
||||
|
||||
## Пробная загрузка
|
||||
|
||||
@@ -54,6 +59,49 @@ result = sync_archive(output_path)
|
||||
Планировщик, очередь задач и PostgreSQL пока не добавлены: модуль не зависит от
|
||||
выбора будущего backend-фреймворка.
|
||||
|
||||
## Текущий API Минюста и отдельный staging
|
||||
|
||||
Старый OpenData endpoint может возвращать `404`; для отдельной ограниченной
|
||||
выгрузки официальный сайт предоставляет `/api/v1/GetDocument` и
|
||||
`/api/v1/GetEdition`. Адаптер `ingestion.minjust_current` получает один
|
||||
указанный документ и сохраняет его в отдельное поколение staging:
|
||||
|
||||
```bash
|
||||
PYTHONPATH=backend python3 -m ingestion.minjust_current \
|
||||
--output /tmp/minjust-current-code6 \
|
||||
--document-code 6
|
||||
```
|
||||
|
||||
Продолжайте прерванную выгрузку только с тем же каталогом и `--resume`. По
|
||||
умолчанию лимит скачанного текста одного документа — 4 GiB, лимит запросов —
|
||||
один в секунду; каталог не должен совпадать или пересекаться с
|
||||
`data/minjust-cbd` и
|
||||
`data/minjust-normalized`. Адаптер сохраняет исходные ответы и checkpoints,
|
||||
публикует папку документа атомарно и не заменяет существующий код в staging.
|
||||
Каталог staging должен быть отдельной директорией режима 0700, принадлежащей
|
||||
текущему пользователю; его родитель должен быть существующим доверенным
|
||||
каталогом. Символические ссылки в generation, checkpoints и каталогах
|
||||
документов отклоняются. Legacy-корни вычисляются от корня репозитория, а не
|
||||
от текущего рабочего каталога.
|
||||
Для `/GetEdition?lang=kg` официальный ответ помещает кыргызский HTML в
|
||||
`contentRu` при `contentKg=null`; архивный язык определяется запрошенным
|
||||
`lang`, а не именем поля ответа.
|
||||
|
||||
Исторические редакции запрашиваются только с `exact=true`; без этого параметра
|
||||
официальный endpoint возвращал ID последней редакции даже для другого
|
||||
запрошенного ID. Адаптер требует совпадения response ID и запрошенного ID,
|
||||
сверяет названия RU/KY с metadata `GetDocument` и сохраняет request contract в
|
||||
checkpoint. Старые staging generations без этого contract нельзя возобновить.
|
||||
`exact=true` и совпадение ID проверены на двух контрольных редакциях; это не
|
||||
подтверждает полноту всего источника.
|
||||
|
||||
Порядок редакций сохраняется по ответу `/GetDocument` и используется как
|
||||
официальный порядок при нормализации и выборе текущей редакции в поисковом
|
||||
индексе. Вложения и встроенные изображения этим адаптером не подтверждаются:
|
||||
staging остаётся неполным до отдельной проверки медиа и не заменяет корпус.
|
||||
Получение полного списка документов не является частью этой ограниченной
|
||||
процедуры.
|
||||
|
||||
## Нормализация архива
|
||||
|
||||
Нормализатор читает исходный архив без изменений и создаёт отдельный набор
|
||||
@@ -128,6 +176,31 @@ python3 backend/search/minjust_opensearch.py \
|
||||
После проверки production-индекса следует переключать alias, чтобы удалённые
|
||||
фрагменты не оставались в поиске.
|
||||
|
||||
Alias переключается только после refresh, точного сравнения полного fragment
|
||||
count с inventory, обеих языковых canary-проверок и совпадения ожидаемого
|
||||
текущего индекса. Перед cutover обязательно укажите RU/KY запросы и точное имя
|
||||
старого target:
|
||||
|
||||
```bash
|
||||
python3 backend/search/minjust_opensearch.py \
|
||||
--url http://127.0.0.1:9200 \
|
||||
--index akyldash-fragments-v2 \
|
||||
--alias akyldash-fragments-current \
|
||||
--expected-old-index akyldash-fragments-v1 \
|
||||
--canary-ru 'утверждённый русский запрос' \
|
||||
--canary-ky 'бекитилген кыргызча суроо'
|
||||
```
|
||||
|
||||
Wildcard removal, пустой индекс и alias с несколькими target запрещены. Если
|
||||
старый target успел измениться после проверки, OpenSearch отклонит атомарную
|
||||
операцию удаления точного старого alias. `--resume` повторно проверяет весь
|
||||
ожидаемый inventory, а не только количество документов текущего запуска.
|
||||
Если ответ на alias request потерян после успешного переключения или процесс
|
||||
остановился до записи завершённого checkpoint, повторный запуск проверит
|
||||
фактическую цель alias. Уже опубликованный candidate оставляется на месте, и
|
||||
checkpoint завершается; старый target позволяет безопасно повторить cutover,
|
||||
а любой другой target останавливает операцию.
|
||||
|
||||
После каждого принятого Bulk-пакета загрузчик атомарно сохраняет checkpoint и
|
||||
печатает код безопасного возобновления. При временных HTTP 429/5xx, timeout и
|
||||
обрыве соединения запрос повторяется автоматически. Прерванную загрузку можно
|
||||
@@ -142,12 +215,29 @@ python3 backend/search/minjust_opensearch.py \
|
||||
|
||||
По умолчанию checkpoint хранится в
|
||||
`data/opensearch/<index>.checkpoint.json`; путь можно изменить через
|
||||
`--checkpoint`. Checkpoint привязан к URL, cluster UUID, index UUID, `--limit`
|
||||
и SHA-256 нормализованного manifest. Resume отклоняется при любом несовпадении:
|
||||
`--checkpoint`. Checkpoint привязан к URL, cluster UUID, index UUID, `--limit`,
|
||||
`--alias` и SHA-256 нормализованного manifest. При `--resume` передавайте то же
|
||||
значение `--alias`; старый checkpoint без alias можно продолжить только без
|
||||
него. Resume отклоняется при любом несовпадении:
|
||||
для обновлённого корпуса или пересозданного индекса нужно создать новый
|
||||
версионный индекс, проверить его и переключить alias. Это не оставляет
|
||||
удалённые trailing-фрагменты старых документов.
|
||||
|
||||
## HTTP API v1
|
||||
|
||||
Запустите публичный read-only API поверх текущего alias и нормализованного
|
||||
корпуса:
|
||||
|
||||
```bash
|
||||
PYTHONPATH=backend python3 -m search.api
|
||||
```
|
||||
|
||||
Он публикует OpenAPI в `GET /openapi.json` и поддерживает `GET /search`,
|
||||
`/search/filters`, `/documents/{code}`, `/documents/{code}/editions` и
|
||||
`/documents/{code}/editions/{edition}`. Значения фильтров возвращаются со
|
||||
стабильным кодом справочника v1 и подписями RU/KY; применяйте `code` как
|
||||
параметр поиска. API не подменяет отсутствующий язык документа.
|
||||
|
||||
## Локальный OpenSearch
|
||||
|
||||
Стенд использует один узел OpenSearch без Dashboards, устанавливает
|
||||
@@ -189,6 +279,45 @@ PYTHONPATH=backend python3 -m search.evaluate_relevance \
|
||||
Менять веса или анализаторы следует только после фиксации этого baseline и
|
||||
разбора ошибок выдачи.
|
||||
|
||||
Диагностический отчёт с измерениями, подтверждёнными ошибками и ограничениями
|
||||
текущего корпуса: [search relevance findings](../docs/product/search-relevance-findings-2026-11-03.md).
|
||||
|
||||
## Внутренняя лаборатория релевантности
|
||||
|
||||
Создайте первую учетную запись администратора:
|
||||
|
||||
```bash
|
||||
PYTHONPATH=backend python3 -m search.api --users-db data/search-users.sqlite3 --create-admin
|
||||
```
|
||||
|
||||
Команда запросит и подтвердит пароль `admin` в терминале. Затем запустите
|
||||
Search API на localhost и откройте `http://127.0.0.1:8080/review`:
|
||||
|
||||
```bash
|
||||
PYTHONPATH=backend python3 -m search.api \\
|
||||
--reviews-db data/search-reviews.sqlite3
|
||||
```
|
||||
|
||||
Лаборатория показывает фактический порядок выдачи OpenSearch, позволяет открыть
|
||||
текст редакции, поставить результату оценку от 0 до 3 и сохранить снимок с
|
||||
комментариями. Пустую выдачу можно сохранить как query-level оценку с
|
||||
обязательным общим комментарием. Поиск и API доступны только после входа. Пользователь `admin`
|
||||
управляет учетными записями; новые пользователи должны заменить временный
|
||||
пароль при первом входе. Хранилище пользователей `data/search-users.sqlite3`
|
||||
нужно резервировать отдельно от поискового индекса. Экспорт доступен
|
||||
авторизованным пользователям через `GET /search-reviews/export`.
|
||||
|
||||
При утере пароля `admin` используйте `PYTHONPATH=backend python3 -m search.api
|
||||
--users-db data/search-users.sqlite3 --reset-admin-password`; следующий вход
|
||||
потребует сменить временный пароль.
|
||||
|
||||
Для проверки текущей выдачи без будущего HTTP API используйте CLI:
|
||||
|
||||
```bash
|
||||
PYTHONPATH=backend python3 -m search.query "как открыть ОсОО" --language ru
|
||||
PYTHONPATH=backend python3 -m search.query "ЖЧК ачуу тартиби" --language ky
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Акылдаш · Backend v0.5.0 · Frontend — не создан
|
||||
Акылдаш · Search API v0.13.4 · Frontend v0.3.4 · Telegram-бот v0.2.2
|
||||
@@ -21,7 +21,7 @@ from datetime import datetime, timezone
|
||||
from pathlib import Path
|
||||
from typing import Callable, Iterable
|
||||
|
||||
APP_VERSION = "0.5.0"
|
||||
APP_VERSION = "0.9.3"
|
||||
API_BASE_URL = "https://cbd.minjust.gov.kg/api/v1/OpenData/"
|
||||
LANGUAGES = {"Rus": "ru", "Kyr": "ky"}
|
||||
IMAGE_LANGUAGES = {"Russian": "ru", "Kyrgyz": "ky"}
|
||||
@@ -364,7 +364,7 @@ def main() -> int:
|
||||
print(
|
||||
f"discovered={result.discovered} downloaded={result.downloaded} "
|
||||
f"skipped={result.skipped} failed={result.failed}\n"
|
||||
f"Akyldash Backend v{APP_VERSION} · Frontend — not created"
|
||||
f"Akyldash · Backend v{APP_VERSION} · Frontend v0.1.2"
|
||||
)
|
||||
return int(result.failed > 0)
|
||||
|
||||
|
||||
@@ -0,0 +1,720 @@
|
||||
"""Read-only staging client for the current MinJust CBD API."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import hashlib
|
||||
import http.client
|
||||
import json
|
||||
import logging
|
||||
import os
|
||||
import sqlite3
|
||||
import stat
|
||||
import time
|
||||
import urllib.error
|
||||
import urllib.parse
|
||||
import urllib.request
|
||||
from dataclasses import dataclass
|
||||
from datetime import datetime, timezone
|
||||
from email.utils import parsedate_to_datetime
|
||||
from pathlib import Path
|
||||
from typing import Callable
|
||||
|
||||
from ingestion.minjust_cbd import atomic_write, connect_manifest, json_bytes
|
||||
|
||||
API_ROOT = "https://cbd.minjust.gov.kg/api/v1"
|
||||
APP_VERSION = "0.13.0"
|
||||
REQUEST_CONTRACT = {
|
||||
"version": 2,
|
||||
"endpoint": "/GetEdition",
|
||||
"edition_id_parameter": "editionId",
|
||||
"exact_parameter": "true",
|
||||
"language_parameter": "lang",
|
||||
"response_id_must_match": True,
|
||||
}
|
||||
MAX_RESPONSE_BYTES = 16 * 1024 * 1024
|
||||
DEFAULT_DOCUMENT_BUDGET = 4 * 1024 * 1024 * 1024
|
||||
LANGUAGES = (("ru", "ru", "textRusType"), ("kg", "ky", "textKyrType"))
|
||||
LOGGER = logging.getLogger(__name__)
|
||||
REPOSITORY_ROOT = Path(__file__).resolve().parents[2]
|
||||
|
||||
|
||||
class SourceError(RuntimeError):
|
||||
pass
|
||||
|
||||
|
||||
class SourceChanged(SourceError):
|
||||
pass
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ApiResponse:
|
||||
value: dict
|
||||
body: bytes
|
||||
sha256: str
|
||||
|
||||
|
||||
class CurrentCbdClient:
|
||||
def __init__(
|
||||
self,
|
||||
requests_per_second: float = 1,
|
||||
timeout: int = 60,
|
||||
retries: int = 5,
|
||||
max_response_bytes: int = MAX_RESPONSE_BYTES,
|
||||
opener: Callable = urllib.request.urlopen,
|
||||
sleep: Callable[[float], None] = time.sleep,
|
||||
clock: Callable[[], float] = time.monotonic,
|
||||
) -> None:
|
||||
if requests_per_second <= 0 or timeout <= 0 or retries <= 0 or max_response_bytes <= 0:
|
||||
raise ValueError("rate, timeout, retries, and response limit must be positive")
|
||||
self.interval = 1 / requests_per_second
|
||||
self.timeout = timeout
|
||||
self.retries = retries
|
||||
self.max_response_bytes = max_response_bytes
|
||||
self.opener = opener
|
||||
self.sleep = sleep
|
||||
self.clock = clock
|
||||
self.last_request = 0.0
|
||||
|
||||
def request_json(
|
||||
self,
|
||||
path: str,
|
||||
*,
|
||||
method: str = "GET",
|
||||
parameters: tuple[tuple[str, object], ...] = (),
|
||||
payload: dict | None = None,
|
||||
) -> ApiResponse:
|
||||
if not path.startswith("/") or ".." in path.split("/"):
|
||||
raise ValueError("API path must be an absolute endpoint path")
|
||||
query = urllib.parse.urlencode(parameters, doseq=True)
|
||||
url = API_ROOT + path + (f"?{query}" if query else "")
|
||||
body = json.dumps(payload or {}, ensure_ascii=False, separators=(",", ":")).encode() if method == "POST" else None
|
||||
for attempt in range(self.retries):
|
||||
wait = self.interval - (self.clock() - self.last_request)
|
||||
if wait > 0:
|
||||
self.sleep(wait)
|
||||
request = urllib.request.Request(
|
||||
url,
|
||||
data=body,
|
||||
method=method,
|
||||
headers={
|
||||
"Accept": "application/json",
|
||||
**({"Content-Type": "application/json"} if body is not None else {}),
|
||||
"User-Agent": f"Akyldash/{APP_VERSION} (+https://cbd.minjust.gov.kg)",
|
||||
},
|
||||
)
|
||||
try:
|
||||
self.last_request = self.clock()
|
||||
with self.opener(request, timeout=self.timeout) as response:
|
||||
raw = response.read(self.max_response_bytes + 1)
|
||||
if len(raw) > self.max_response_bytes:
|
||||
raise SourceError(f"MinJust response exceeds {self.max_response_bytes} bytes")
|
||||
value = json.loads(raw)
|
||||
if not isinstance(value, dict):
|
||||
raise SourceError("MinJust response must be a JSON object")
|
||||
return ApiResponse(value, raw, hashlib.sha256(raw).hexdigest())
|
||||
except urllib.error.HTTPError as error:
|
||||
if error.code != 429 and error.code < 500:
|
||||
raise SourceError(f"MinJust returned HTTP {error.code} for {path}") from error
|
||||
delay = 2**attempt
|
||||
if error.code == 429:
|
||||
delay = max(delay, retry_after_seconds(error.headers.get("Retry-After")))
|
||||
except (TimeoutError, urllib.error.URLError, http.client.IncompleteRead, json.JSONDecodeError) as error:
|
||||
delay = 2**attempt
|
||||
LOGGER.warning("MinJust request failed for %s (attempt %s/%s)", path, attempt + 1, self.retries)
|
||||
last_error = error
|
||||
if attempt + 1 < self.retries:
|
||||
self.sleep(delay)
|
||||
raise SourceError(f"MinJust request failed after {self.retries} attempts: {path}") from locals().get("last_error")
|
||||
|
||||
def document(self, alias: str) -> ApiResponse:
|
||||
response = self.request_json("/GetDocument", parameters=(("DocumentCode", alias),))
|
||||
value = response.value
|
||||
canonical = value.get("documentCode")
|
||||
editions = value.get("editions")
|
||||
if not isinstance(canonical, int) or isinstance(canonical, bool) or canonical < 1:
|
||||
raise SourceError("MinJust document has an invalid canonical documentCode")
|
||||
if not isinstance(editions, list):
|
||||
raise SourceError("MinJust document is missing editions")
|
||||
ids = [edition_id(item) for item in editions]
|
||||
if len(ids) != len(set(ids)):
|
||||
raise SourceError(f"MinJust document {canonical} contains duplicate edition IDs")
|
||||
return response
|
||||
|
||||
def edition(self, identifier: int, language: str) -> ApiResponse:
|
||||
if identifier < 1 or language not in {"ru", "kg"}:
|
||||
raise ValueError("edition ID or requested language is invalid")
|
||||
response = self.request_json(
|
||||
"/GetEdition",
|
||||
parameters=(("editionId", identifier), ("lang", language), ("exact", "true")),
|
||||
)
|
||||
returned_id = response.value.get("id")
|
||||
if not isinstance(returned_id, int) or isinstance(returned_id, bool) or returned_id < 1:
|
||||
raise SourceError(f"MinJust returned an invalid edition response ID for {identifier}")
|
||||
if returned_id != identifier:
|
||||
raise SourceChanged(f"MinJust exact edition ID {returned_id} does not match requested ID {identifier}")
|
||||
return response
|
||||
|
||||
|
||||
def retry_after_seconds(value: str | None) -> float:
|
||||
if not value:
|
||||
return 0
|
||||
try:
|
||||
return max(0, float(value))
|
||||
except ValueError:
|
||||
try:
|
||||
return max(0, (parsedate_to_datetime(value) - datetime.now(timezone.utc)).total_seconds())
|
||||
except (TypeError, ValueError, OverflowError):
|
||||
return 0
|
||||
|
||||
|
||||
def edition_id(value: object) -> int:
|
||||
if not isinstance(value, dict):
|
||||
raise SourceError("MinJust document contains an invalid edition")
|
||||
identifier = value.get("id")
|
||||
if not isinstance(identifier, int) or isinstance(identifier, bool) or identifier < 1:
|
||||
raise SourceError("MinJust edition has an invalid id")
|
||||
return identifier
|
||||
|
||||
|
||||
def open_manifest(path: Path) -> sqlite3.Connection:
|
||||
connection = sqlite3.connect(path)
|
||||
connection.execute("PRAGMA journal_mode=DELETE")
|
||||
connection.executescript(
|
||||
"""
|
||||
CREATE TABLE IF NOT EXISTS documents (
|
||||
alias TEXT PRIMARY KEY,
|
||||
canonical_id INTEGER,
|
||||
response_sha256 TEXT,
|
||||
expected_editions INTEGER,
|
||||
state TEXT NOT NULL,
|
||||
error TEXT,
|
||||
updated_at TEXT NOT NULL
|
||||
);
|
||||
CREATE TABLE IF NOT EXISTS editions (
|
||||
canonical_id INTEGER NOT NULL,
|
||||
edition_id INTEGER NOT NULL,
|
||||
source_order INTEGER NOT NULL,
|
||||
response_sha256 TEXT NOT NULL,
|
||||
PRIMARY KEY (canonical_id, edition_id)
|
||||
);
|
||||
CREATE TABLE IF NOT EXISTS languages (
|
||||
canonical_id INTEGER NOT NULL,
|
||||
edition_id INTEGER NOT NULL,
|
||||
request_language TEXT NOT NULL,
|
||||
archive_language TEXT NOT NULL,
|
||||
response_sha256 TEXT,
|
||||
content_sha256 TEXT,
|
||||
byte_count INTEGER NOT NULL DEFAULT 0,
|
||||
state TEXT NOT NULL,
|
||||
error TEXT,
|
||||
updated_at TEXT NOT NULL,
|
||||
PRIMARY KEY (canonical_id, edition_id, request_language)
|
||||
);
|
||||
CREATE TABLE IF NOT EXISTS generation (
|
||||
contract_sha256 TEXT NOT NULL
|
||||
);
|
||||
"""
|
||||
)
|
||||
return connection
|
||||
|
||||
|
||||
def reject_symlink_components(path: Path) -> None:
|
||||
current = Path(path.anchor)
|
||||
for part in path.parts[1:]:
|
||||
current /= part
|
||||
try:
|
||||
mode = current.lstat().st_mode
|
||||
except FileNotFoundError:
|
||||
continue
|
||||
if stat.S_ISLNK(mode):
|
||||
raise ValueError(f"staging path must not contain a symbolic link: {current}")
|
||||
if current != path and not stat.S_ISDIR(mode):
|
||||
raise ValueError(f"staging parent must be a directory: {current}")
|
||||
|
||||
|
||||
def ensure_stage_path(root: Path, path: Path) -> Path:
|
||||
root = root.absolute()
|
||||
path = path.absolute()
|
||||
try:
|
||||
relative = path.relative_to(root)
|
||||
except ValueError as error:
|
||||
raise ValueError("staging file escaped its private generation") from error
|
||||
current = root
|
||||
if current.is_symlink():
|
||||
raise ValueError("staging root must not be a symbolic link")
|
||||
for part in relative.parts:
|
||||
current /= part
|
||||
try:
|
||||
mode = current.lstat().st_mode
|
||||
except FileNotFoundError:
|
||||
continue
|
||||
if stat.S_ISLNK(mode):
|
||||
raise ValueError(f"staging path must not contain a symbolic link: {relative}")
|
||||
if current != path and not stat.S_ISDIR(mode):
|
||||
raise ValueError(f"staging parent must be a directory: {relative}")
|
||||
return path
|
||||
|
||||
|
||||
def stage_write(root: Path, path: Path, content: bytes) -> None:
|
||||
path = ensure_stage_path(root, path)
|
||||
atomic_write(path, content)
|
||||
ensure_stage_path(root, path)
|
||||
|
||||
|
||||
def stage_mkdir(root: Path, path: Path) -> None:
|
||||
path = ensure_stage_path(root, path)
|
||||
path.mkdir(parents=True, exist_ok=True)
|
||||
ensure_stage_path(root, path)
|
||||
if not path.is_dir():
|
||||
raise ValueError("staging path must be a directory")
|
||||
|
||||
|
||||
def validate_stage_tree(output: Path) -> None:
|
||||
for relative in (
|
||||
Path("current-api.sqlite3"), Path("current-api.sqlite3-journal"),
|
||||
Path("current-api.sqlite3-wal"), Path("current-api.sqlite3-shm"),
|
||||
Path("manifest.sqlite3"), Path("manifest.sqlite3-journal"),
|
||||
Path("manifest.sqlite3-wal"), Path("manifest.sqlite3-shm"),
|
||||
Path("request-contract.json"),
|
||||
):
|
||||
path = ensure_stage_path(output, output / relative)
|
||||
if path.exists() and not path.is_file():
|
||||
raise ValueError(f"staging checkpoint must be a regular file: {relative}")
|
||||
for relative in (Path(".work"), Path("documents")):
|
||||
root = ensure_stage_path(output, output / relative)
|
||||
if root.exists() and not root.is_dir():
|
||||
raise ValueError(f"staging path must be a directory: {relative}")
|
||||
if root.is_dir():
|
||||
for directory, directories, files in os.walk(root, followlinks=False):
|
||||
for name in directories + files:
|
||||
ensure_stage_path(output, Path(directory) / name)
|
||||
|
||||
|
||||
def validate_stage_root(output: Path, resume: bool) -> Path:
|
||||
requested = Path(output)
|
||||
if ".." in requested.parts:
|
||||
raise ValueError("staging output path must not contain '..'")
|
||||
destination = Path(os.path.abspath(requested))
|
||||
reject_symlink_components(destination)
|
||||
parent = destination.parent
|
||||
if not parent.is_dir():
|
||||
raise ValueError("staging output parent must already exist")
|
||||
for ancestor in (parent, *parent.parents):
|
||||
info = ancestor.lstat()
|
||||
mode = stat.S_IMODE(info.st_mode)
|
||||
if stat.S_ISLNK(info.st_mode) or not stat.S_ISDIR(info.st_mode):
|
||||
raise ValueError("staging output ancestors must be real directories")
|
||||
sticky_parent = bool(mode & stat.S_ISVTX)
|
||||
if mode & 0o022 and not sticky_parent:
|
||||
raise ValueError("staging output parent is not trusted")
|
||||
for relative in (Path("data/minjust-cbd"), Path("data/minjust-normalized")):
|
||||
legacy = (REPOSITORY_ROOT / relative).resolve()
|
||||
if destination == legacy or destination.is_relative_to(legacy) or legacy.is_relative_to(destination):
|
||||
raise ValueError("current API staging must not overlap the existing corpus")
|
||||
if destination.exists():
|
||||
if destination.is_symlink() or not destination.is_dir():
|
||||
raise ValueError("staging output must be a real directory")
|
||||
else:
|
||||
destination.mkdir(mode=0o700)
|
||||
root_info = destination.lstat()
|
||||
root_mode = stat.S_IMODE(root_info.st_mode)
|
||||
if (
|
||||
stat.S_ISLNK(root_info.st_mode)
|
||||
or not stat.S_ISDIR(root_info.st_mode)
|
||||
or root_info.st_uid != os.geteuid()
|
||||
or root_mode & 0o077
|
||||
or (root_mode & 0o700) != 0o700
|
||||
):
|
||||
raise ValueError("staging output must be a private directory owned by the current user")
|
||||
validate_stage_tree(destination)
|
||||
if any(destination.iterdir()) and not resume:
|
||||
raise ValueError("staging output is not empty; use --resume for this generation")
|
||||
contract_path = destination / "request-contract.json"
|
||||
if contract_path.exists():
|
||||
try:
|
||||
contract = json.loads(contract_path.read_text(encoding="utf-8"))
|
||||
except (OSError, UnicodeError, json.JSONDecodeError) as error:
|
||||
raise SourceChanged("staging generation request contract is invalid") from error
|
||||
if contract != REQUEST_CONTRACT:
|
||||
raise SourceChanged("staging generation uses a different request contract")
|
||||
else:
|
||||
if any(destination.iterdir()):
|
||||
raise SourceChanged("staging generation has no exact-edition request contract; start a new generation")
|
||||
stage_write(destination, contract_path, json_bytes(REQUEST_CONTRACT))
|
||||
return destination
|
||||
|
||||
|
||||
def stage_document(
|
||||
output: Path,
|
||||
alias: str,
|
||||
client: CurrentCbdClient,
|
||||
*,
|
||||
resume: bool = False,
|
||||
max_document_bytes: int = DEFAULT_DOCUMENT_BUDGET,
|
||||
) -> dict:
|
||||
"""Stage one document and its official editions without touching legacy roots."""
|
||||
if not alias or len(alias) > 64 or "/" in alias or "\\" in alias:
|
||||
raise ValueError("document code is invalid")
|
||||
if max_document_bytes <= 0:
|
||||
raise ValueError("document byte budget must be positive")
|
||||
output = validate_stage_root(output, resume)
|
||||
work_root = output / ".work" / "documents"
|
||||
target_root = output / "documents"
|
||||
connection = open_manifest(output / "current-api.sqlite3")
|
||||
raw_manifest = connect_manifest(output / "manifest.sqlite3")
|
||||
try:
|
||||
contract_sha = hashlib.sha256(json.dumps(REQUEST_CONTRACT, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
|
||||
saved_contract = connection.execute("SELECT contract_sha256 FROM generation").fetchone()
|
||||
if saved_contract and saved_contract[0] != contract_sha:
|
||||
raise SourceChanged("checkpoint request contract changed; start a new staging generation")
|
||||
if not saved_contract:
|
||||
if connection.execute("SELECT COUNT(*) FROM documents").fetchone()[0]:
|
||||
raise SourceChanged("existing checkpoints have no request contract; start a new staging generation")
|
||||
with connection:
|
||||
connection.execute("INSERT INTO generation (contract_sha256) VALUES (?)", (contract_sha,))
|
||||
response = client.document(alias)
|
||||
source = response.value
|
||||
canonical = source["documentCode"]
|
||||
record_sha = response.sha256
|
||||
editions = source["editions"]
|
||||
previous = connection.execute(
|
||||
"SELECT canonical_id, response_sha256, expected_editions FROM documents WHERE alias = ?",
|
||||
(alias,),
|
||||
).fetchone()
|
||||
if previous and previous[1] is not None and (
|
||||
previous[0] != canonical or previous[1] != record_sha or previous[2] != len(editions)
|
||||
):
|
||||
raise SourceChanged("document metadata changed; start a new staging generation")
|
||||
working_document = work_root / str(canonical)
|
||||
final_document = target_root / str(canonical)
|
||||
ensure_stage_path(output, working_document)
|
||||
ensure_stage_path(output, final_document)
|
||||
if final_document.is_symlink():
|
||||
raise ValueError("staging target must not be a symbolic link")
|
||||
if final_document.exists() and not previous:
|
||||
raise ValueError("staging target already exists without a matching checkpoint")
|
||||
if final_document.exists():
|
||||
final_metadata = ensure_stage_path(output, final_document / "metadata.json")
|
||||
source_document = ensure_stage_path(output, final_document / "source-document.json")
|
||||
metadata = json.loads(final_metadata.read_text(encoding="utf-8"))
|
||||
if (
|
||||
metadata.get("SourceApi", {}).get("response_sha256") != record_sha
|
||||
or hashlib.sha256(source_document.read_bytes()).hexdigest() != record_sha
|
||||
):
|
||||
raise SourceChanged("published staging document does not match the current source record")
|
||||
for edition in editions:
|
||||
identifier = edition_id(edition)
|
||||
for request_language, archive_language, type_field in LANGUAGES:
|
||||
html_path = ensure_stage_path(
|
||||
output,
|
||||
final_document / "editions" / str(identifier) / f"{archive_language}.html",
|
||||
)
|
||||
checkpoint = connection.execute(
|
||||
"SELECT state, content_sha256 FROM languages WHERE canonical_id = ? AND edition_id = ? AND request_language = ?",
|
||||
(canonical, identifier, request_language),
|
||||
).fetchone()
|
||||
if not edition.get(type_field):
|
||||
if not checkpoint or checkpoint[0] != "unavailable":
|
||||
raise SourceError(f"published staging document has no checkpoint for edition {identifier} {request_language}")
|
||||
elif (
|
||||
not checkpoint
|
||||
or checkpoint[0] != "complete"
|
||||
or not html_path.is_file()
|
||||
or sha256_file(html_path) != checkpoint[1]
|
||||
):
|
||||
raise SourceError(f"published staging document failed verification for edition {identifier} {request_language}")
|
||||
document_sha = hash_tree(final_document)
|
||||
fetched_at = utc_now()
|
||||
manifest_row = raw_manifest.execute(
|
||||
"SELECT source_sha256 FROM documents WHERE code = ?", (canonical,)
|
||||
).fetchone()
|
||||
if manifest_row and manifest_row[0] != document_sha:
|
||||
raise SourceError("published staging document does not match its raw manifest")
|
||||
with raw_manifest:
|
||||
raw_manifest.execute(
|
||||
"INSERT OR IGNORE INTO documents (code, source_sha256, fetched_at) VALUES (?, ?, ?)",
|
||||
(canonical, document_sha, fetched_at),
|
||||
)
|
||||
raw_manifest.execute(
|
||||
"INSERT INTO errors (code, message, failed_at) VALUES (?, ?, ?) "
|
||||
"ON CONFLICT(code) DO UPDATE SET message=excluded.message, failed_at=excluded.failed_at",
|
||||
(canonical, "attachments and embedded media are not independently verified", fetched_at),
|
||||
)
|
||||
with connection:
|
||||
connection.execute(
|
||||
"UPDATE documents SET state='text_complete_incomplete_attachments', error=NULL, updated_at=? WHERE alias=?",
|
||||
(fetched_at, alias),
|
||||
)
|
||||
return {
|
||||
"alias": alias,
|
||||
"canonical_id": canonical,
|
||||
"editions": len(editions),
|
||||
"source_sha256": document_sha,
|
||||
"state": "text_complete_incomplete_attachments",
|
||||
"resumed": True,
|
||||
}
|
||||
stage_mkdir(output, working_document)
|
||||
document_metadata = map_document_metadata(source, alias, response.sha256)
|
||||
stage_write(output, working_document / "metadata.json", json_bytes(document_metadata))
|
||||
stage_write(output, working_document / "source-document.json", response.body)
|
||||
with connection:
|
||||
connection.execute(
|
||||
"INSERT INTO documents (alias, canonical_id, response_sha256, expected_editions, state, updated_at) VALUES (?, ?, ?, ?, 'fetching', ?) "
|
||||
"ON CONFLICT(alias) DO UPDATE SET canonical_id=excluded.canonical_id, response_sha256=excluded.response_sha256, "
|
||||
"expected_editions=excluded.expected_editions, state='fetching', error=NULL, updated_at=excluded.updated_at",
|
||||
(alias, canonical, record_sha, len(editions), utc_now()),
|
||||
)
|
||||
for order, edition in enumerate(editions):
|
||||
identifier = edition_id(edition)
|
||||
existing = connection.execute(
|
||||
"SELECT source_order, response_sha256 FROM editions WHERE canonical_id = ? AND edition_id = ?",
|
||||
(canonical, identifier),
|
||||
).fetchone()
|
||||
if existing and existing != (order, hashlib.sha256(json_bytes(edition)).hexdigest()):
|
||||
raise SourceChanged(f"edition metadata changed for {identifier}")
|
||||
connection.execute(
|
||||
"INSERT OR IGNORE INTO editions (canonical_id, edition_id, source_order, response_sha256) VALUES (?, ?, ?, ?)",
|
||||
(canonical, identifier, order, hashlib.sha256(json_bytes(edition)).hexdigest()),
|
||||
)
|
||||
|
||||
incomplete = []
|
||||
for order, edition in enumerate(editions):
|
||||
identifier = edition_id(edition)
|
||||
directory = working_document / "editions" / str(identifier)
|
||||
stage_mkdir(output, directory)
|
||||
stage_write(output, directory / "metadata.json", json_bytes(map_edition_metadata(edition, order)))
|
||||
for request_language, archive_language, type_field in LANGUAGES:
|
||||
html_path = ensure_stage_path(output, directory / f"{archive_language}.html")
|
||||
checkpoint = connection.execute(
|
||||
"SELECT state, content_sha256, byte_count FROM languages WHERE canonical_id = ? AND edition_id = ? AND request_language = ?",
|
||||
(canonical, identifier, request_language),
|
||||
).fetchone()
|
||||
if checkpoint and checkpoint[0] == "complete":
|
||||
if not html_path.is_file() or sha256_file(html_path) != checkpoint[1]:
|
||||
raise SourceError(f"staged content hash mismatch for edition {identifier} {request_language}")
|
||||
continue
|
||||
if not edition.get(type_field):
|
||||
save_language_checkpoint(
|
||||
connection, canonical, identifier, request_language, archive_language,
|
||||
None, None, 0, "unavailable", "source metadata reports no language file",
|
||||
)
|
||||
continue
|
||||
try:
|
||||
language_response = client.edition(identifier, request_language)
|
||||
response_id = language_response.value.get("id")
|
||||
if isinstance(response_id, bool) or not isinstance(response_id, int) or response_id != identifier:
|
||||
raise SourceChanged(f"MinJust exact edition ID mismatch for {identifier}")
|
||||
for field in ("nameRus", "nameKyr"):
|
||||
if edition.get(field) is not None and language_response.value.get(field) != edition[field]:
|
||||
raise SourceChanged(f"MinJust exact edition metadata mismatch for {identifier}: {field}")
|
||||
content = language_response.value.get("contentRu")
|
||||
if not isinstance(content, str) or not content:
|
||||
raise SourceError(f"MinJust returned no content for edition {identifier} language {request_language}")
|
||||
encoded = content.encode("utf-8")
|
||||
completed_bytes = connection.execute(
|
||||
"SELECT COALESCE(SUM(byte_count), 0) FROM languages WHERE canonical_id = ? AND state = 'complete'",
|
||||
(canonical,),
|
||||
).fetchone()[0]
|
||||
if completed_bytes + len(encoded) > max_document_bytes:
|
||||
raise SourceError(f"document {canonical} exceeds its {max_document_bytes}-byte staging budget")
|
||||
response_metadata = {
|
||||
key: value
|
||||
for key, value in language_response.value.items()
|
||||
if key not in {"contentRu", "contentKg"}
|
||||
}
|
||||
response_metadata["requested_language"] = request_language
|
||||
response_metadata["archive_language"] = archive_language
|
||||
response_metadata["requested_edition_id"] = identifier
|
||||
response_metadata["exact"] = True
|
||||
response_metadata["response_sha256"] = language_response.sha256
|
||||
stage_write(
|
||||
output,
|
||||
directory / "source" / f"{request_language}.json",
|
||||
json_bytes(response_metadata),
|
||||
)
|
||||
stage_write(output, html_path, encoded)
|
||||
save_language_checkpoint(
|
||||
connection, canonical, identifier, request_language, archive_language,
|
||||
language_response.sha256, hashlib.sha256(encoded).hexdigest(), len(encoded), "complete", None,
|
||||
)
|
||||
except Exception as error:
|
||||
message = str(error)[:500]
|
||||
save_language_checkpoint(
|
||||
connection, canonical, identifier, request_language, archive_language,
|
||||
None, None, 0, "error", message,
|
||||
)
|
||||
incomplete.append({"edition_id": identifier, "language": request_language, "error": message})
|
||||
if isinstance(error, SourceChanged) or (isinstance(error, SourceError) and "budget" in message):
|
||||
raise
|
||||
|
||||
if incomplete:
|
||||
with connection:
|
||||
connection.execute(
|
||||
"UPDATE documents SET state='incomplete', error=?, updated_at=? WHERE alias=?",
|
||||
(json.dumps(incomplete, ensure_ascii=False), utc_now(), alias),
|
||||
)
|
||||
return {"alias": alias, "canonical_id": canonical, "editions": len(editions), "incomplete": incomplete}
|
||||
|
||||
working_metadata = ensure_stage_path(output, working_document / "metadata.json")
|
||||
metadata = json.loads(working_metadata.read_text(encoding="utf-8"))
|
||||
metadata["SourceCompleteness"] = {
|
||||
"text": "complete",
|
||||
"attachments": "not independently verified",
|
||||
}
|
||||
stage_write(output, working_metadata, json_bytes(metadata))
|
||||
stage_mkdir(output, target_root)
|
||||
ensure_stage_path(output, working_document)
|
||||
ensure_stage_path(output, final_document)
|
||||
if final_document.exists():
|
||||
raise ValueError("refusing to replace a document in this staging generation")
|
||||
os.replace(working_document, final_document)
|
||||
validate_stage_tree(output)
|
||||
document_sha = hash_tree(final_document)
|
||||
fetched_at = utc_now()
|
||||
with raw_manifest:
|
||||
raw_manifest.execute(
|
||||
"INSERT INTO documents (code, source_sha256, fetched_at) VALUES (?, ?, ?)",
|
||||
(canonical, document_sha, fetched_at),
|
||||
)
|
||||
raw_manifest.execute(
|
||||
"INSERT INTO errors (code, message, failed_at) VALUES (?, ?, ?)",
|
||||
(canonical, "attachments and embedded media are not independently verified", fetched_at),
|
||||
)
|
||||
with connection:
|
||||
connection.execute(
|
||||
"UPDATE documents SET state='text_complete_incomplete_attachments', updated_at=? WHERE alias=?",
|
||||
(fetched_at, alias),
|
||||
)
|
||||
return {
|
||||
"alias": alias,
|
||||
"canonical_id": canonical,
|
||||
"editions": len(editions),
|
||||
"source_sha256": document_sha,
|
||||
"state": "text_complete_incomplete_attachments",
|
||||
}
|
||||
except Exception as error:
|
||||
with connection:
|
||||
connection.execute(
|
||||
"INSERT INTO documents (alias, state, error, updated_at) VALUES (?, 'error', ?, ?) "
|
||||
"ON CONFLICT(alias) DO UPDATE SET state='error', error=excluded.error, updated_at=excluded.updated_at",
|
||||
(alias, str(error)[:500], utc_now()),
|
||||
)
|
||||
raise
|
||||
finally:
|
||||
raw_manifest.close()
|
||||
connection.close()
|
||||
|
||||
|
||||
def map_document_metadata(source: dict, alias: str, response_sha256: str) -> dict:
|
||||
canonical = source["documentCode"]
|
||||
return {
|
||||
"Code": canonical,
|
||||
"Name": {"Rus": source.get("nameRus"), "Kyr": source.get("nameKyr")},
|
||||
"Title": {"Rus": source.get("headerRu"), "Kyr": source.get("headerKg")},
|
||||
"Number": source.get("number"),
|
||||
"DateAdopted": source.get("dateAdopted"),
|
||||
"DateInclusion": source.get("dateInclusion"),
|
||||
"DateOfEntry": source.get("dateOfEntry"),
|
||||
"DatePublication": source.get("datePublication"),
|
||||
"DateRegistration": source.get("dateRegistration"),
|
||||
"IsPublicInRegister": source.get("isPublicInRegister"),
|
||||
"SourceStatus": source.get("status"),
|
||||
"SourceClassId": source.get("classId"),
|
||||
"SourceRefTypeId": source.get("refTypeId"),
|
||||
"SourceAuthorityIds": source.get("authoritiesId"),
|
||||
"SourcePublicationIds": source.get("sourcePublicationsId"),
|
||||
"SourceMetadata": {key: value for key, value in source.items() if key != "editions"},
|
||||
"SourceDocumentCode": alias,
|
||||
"SourceMediaStatus": "not independently verified",
|
||||
"SourceApi": {"endpoint": "/GetDocument", "response_sha256": response_sha256},
|
||||
}
|
||||
|
||||
|
||||
def map_edition_metadata(source: dict, source_order: int) -> dict:
|
||||
return {
|
||||
"Code": edition_id(source),
|
||||
"Name": {"Rus": source.get("nameRus"), "Kyr": source.get("nameKyr")},
|
||||
"SourceOrder": source_order,
|
||||
"SourceTextTypes": {
|
||||
"ru": source.get("textRusType"),
|
||||
"ky": source.get("textKyrType"),
|
||||
},
|
||||
"SourceMediaStatus": "not independently verified",
|
||||
"SourceMetadata": source,
|
||||
}
|
||||
|
||||
|
||||
def save_language_checkpoint(
|
||||
connection: sqlite3.Connection,
|
||||
canonical: int,
|
||||
edition: int,
|
||||
request_language: str,
|
||||
archive_language: str,
|
||||
response_sha256: str | None,
|
||||
content_sha256: str | None,
|
||||
byte_count: int,
|
||||
state: str,
|
||||
error: str | None,
|
||||
) -> None:
|
||||
with connection:
|
||||
connection.execute(
|
||||
"INSERT INTO languages (canonical_id, edition_id, request_language, archive_language, response_sha256, content_sha256, byte_count, state, error, updated_at) "
|
||||
"VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(canonical_id, edition_id, request_language) DO UPDATE SET "
|
||||
"archive_language=excluded.archive_language, response_sha256=excluded.response_sha256, content_sha256=excluded.content_sha256, "
|
||||
"byte_count=excluded.byte_count, state=excluded.state, error=excluded.error, updated_at=excluded.updated_at",
|
||||
(canonical, edition, request_language, archive_language, response_sha256, content_sha256, byte_count, state, error, utc_now()),
|
||||
)
|
||||
|
||||
|
||||
def sha256_file(path: Path) -> str:
|
||||
digest = hashlib.sha256()
|
||||
with path.open("rb") as source:
|
||||
for block in iter(lambda: source.read(1024 * 1024), b""):
|
||||
digest.update(block)
|
||||
return digest.hexdigest()
|
||||
|
||||
|
||||
def hash_tree(root: Path) -> str:
|
||||
digest = hashlib.sha256()
|
||||
for path in sorted(item for item in root.rglob("*") if item.is_file()):
|
||||
digest.update(path.relative_to(root).as_posix().encode())
|
||||
digest.update(b"\0")
|
||||
digest.update(sha256_file(path).encode("ascii"))
|
||||
digest.update(b"\0")
|
||||
return digest.hexdigest()
|
||||
|
||||
|
||||
def utc_now() -> str:
|
||||
return datetime.now(timezone.utc).isoformat()
|
||||
|
||||
|
||||
def parse_args() -> argparse.Namespace:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("--output", type=Path, required=True, help="new, separate staging generation")
|
||||
parser.add_argument("--document-code", required=True, help="one official document alias or canonical code")
|
||||
parser.add_argument("--resume", action="store_true", help="resume only this staging generation")
|
||||
parser.add_argument("--requests-per-second", type=float, default=1)
|
||||
parser.add_argument("--timeout", type=int, default=60)
|
||||
parser.add_argument("--retries", type=int, default=5)
|
||||
parser.add_argument("--max-document-bytes", type=int, default=DEFAULT_DOCUMENT_BUDGET)
|
||||
parser.add_argument("--version", action="version", version=APP_VERSION)
|
||||
return parser.parse_args()
|
||||
|
||||
|
||||
def main() -> int:
|
||||
arguments = parse_args()
|
||||
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
|
||||
result = stage_document(
|
||||
arguments.output,
|
||||
arguments.document_code,
|
||||
CurrentCbdClient(arguments.requests_per_second, arguments.timeout, arguments.retries),
|
||||
resume=arguments.resume,
|
||||
max_document_bytes=arguments.max_document_bytes,
|
||||
)
|
||||
print(json.dumps(result, ensure_ascii=False, sort_keys=True))
|
||||
return int(result.get("state") != "text_complete_incomplete_attachments")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
@@ -23,9 +23,9 @@ from pathlib import Path
|
||||
from typing import Callable
|
||||
from urllib.parse import urlsplit
|
||||
|
||||
APP_VERSION = "0.5.0"
|
||||
APP_VERSION = "0.10.0"
|
||||
SCHEMA_VERSION = "1"
|
||||
NORMALIZER_VERSION = "1.0.0"
|
||||
NORMALIZER_VERSION = "1.1.0"
|
||||
LANGUAGES = ("ru", "ky")
|
||||
LOGGER = logging.getLogger(__name__)
|
||||
|
||||
@@ -376,13 +376,16 @@ def load_json(path: Path) -> dict:
|
||||
def edition_summary(edition_directory: Path, input_root: Path) -> dict:
|
||||
metadata = load_json(edition_directory / "metadata.json")
|
||||
languages = [language for language in LANGUAGES if (edition_directory / f"{language}.html").is_file()]
|
||||
return {
|
||||
summary = {
|
||||
"source_code": str(metadata.get("Code", edition_directory.name)),
|
||||
"name": bilingual(metadata.get("Name")),
|
||||
"source_type": clean_value(metadata.get("Type")),
|
||||
"available_languages": languages,
|
||||
"source_path": edition_directory.relative_to(input_root).as_posix(),
|
||||
}
|
||||
if "SourceOrder" in metadata:
|
||||
summary["source_order"] = metadata["SourceOrder"]
|
||||
return summary
|
||||
|
||||
|
||||
def normalize_document(
|
||||
@@ -406,6 +409,15 @@ def normalize_document(
|
||||
key=lambda path: (not path.name.isdigit(), int(path.name) if path.name.isdigit() else path.name),
|
||||
) if edition_root.is_dir() else []
|
||||
summaries = [edition_summary(path, input_root) for path in edition_directories]
|
||||
source_orders = [item.get("source_order") for item in summaries]
|
||||
if any(order is not None for order in source_orders):
|
||||
if any(not isinstance(order, int) or isinstance(order, bool) or order < 0 for order in source_orders):
|
||||
raise ValueError(f"Invalid source edition order in {document_directory}")
|
||||
if len(set(source_orders)) != len(source_orders):
|
||||
raise ValueError(f"Duplicate source edition order in {document_directory}")
|
||||
ordered = sorted(zip(source_orders, edition_directories, summaries), key=lambda item: item[0])
|
||||
edition_directories = [item[1] for item in ordered]
|
||||
summaries = [item[2] for item in ordered]
|
||||
available_languages = [language for language in LANGUAGES if any(language in item["available_languages"] for item in summaries)]
|
||||
normalized_metadata = clean_value(metadata)
|
||||
document = {
|
||||
@@ -720,7 +732,7 @@ def main() -> int:
|
||||
print(
|
||||
f"discovered={result.discovered} normalized={result.normalized} "
|
||||
f"skipped={result.skipped} failed={result.failed}\n"
|
||||
f"Akyldash Backend v{APP_VERSION} · Frontend — not created"
|
||||
f"Akyldash · Backend v{APP_VERSION} · Frontend v0.1.2"
|
||||
)
|
||||
return int(result.failed > 0)
|
||||
|
||||
|
||||
@@ -56,17 +56,19 @@ cp backend/search/relevance-set-v1.template.json data/search/relevance-set-v1.js
|
||||
|
||||
## Разметка одного запроса
|
||||
|
||||
1. До просмотра выдачи зафиксируйте информационную потребность и формулировку
|
||||
`query`.
|
||||
2. Найдите кандидатов в локальном OpenSearch и в официальной ЦБД Минюста.
|
||||
Проверьте исходный запрос, его короткий вариант и вариант с юридическим
|
||||
термином или известным номером акта.
|
||||
3. Просмотрите не только заголовки, но и текст, статус, дату и редакцию каждого
|
||||
кандидата.
|
||||
4. Запишите уникальные `document_code` всех документов, удовлетворяющих
|
||||
критерию релевантности.
|
||||
5. Повторите поиск по ключевым терминам найденных документов, чтобы обнаружить
|
||||
пропущенные альтернативные акты.
|
||||
1. Зафиксируйте исходную формулировку `query` и информационную потребность до
|
||||
оценки выдачи нашего поиска.
|
||||
2. Юрист устанавливает релевантные акты по содержанию и реквизитам документов.
|
||||
Используйте ЦБД Минюста как авторитетный источник для проверки текста,
|
||||
статуса и редакции акта. Порядок выдачи ЦБД не является объектом оценки и не
|
||||
переносится в эталон.
|
||||
3. Запишите уникальные `document_code` всех документов, которые прямо отвечают
|
||||
на запрос. Спорные документы передайте на независимую проверку.
|
||||
4. Зафиксируйте согласованный набор до просмотра результатов OpenSearch и
|
||||
сохраните его отдельно от рабочих данных.
|
||||
5. Проверьте запрос во внутренней лаборатории (`/review`): оцените фактические
|
||||
результаты OpenSearch в исходном порядке, сохраните снимок и комментарии.
|
||||
Лаборатория проверяет качество нашей поисковой системы, а не ЦБД Минюста.
|
||||
|
||||
Пример структуры (код условный):
|
||||
|
||||
|
||||
@@ -0,0 +1,549 @@
|
||||
"""Minimal HTTP API for the normalized legal-document corpus."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import datetime
|
||||
import getpass
|
||||
import http.cookies
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import urllib.parse
|
||||
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
|
||||
from pathlib import Path
|
||||
|
||||
from search.auth import AuthError, AuthStore, can_manage_users
|
||||
from search.minjust_opensearch import APP_VERSION, request_json
|
||||
from search.catalog import CATALOGS, labels
|
||||
from search.query import build_search_query
|
||||
from search.reviews import ReviewSnapshots, ReviewStore
|
||||
|
||||
|
||||
API_VERSION = "v1"
|
||||
SEARCH_ALGORITHM_VERSION = "search-8"
|
||||
LANGUAGES = {"ru", "ky"}
|
||||
CODE = re.compile(r"^[0-9]+$")
|
||||
MAX_PAGE_SIZE = 100
|
||||
MAX_RESULT_WINDOW = 10_000
|
||||
STATIC_ASSETS = {
|
||||
"/static/favicon.svg": ("favicon.svg", "image/svg+xml"),
|
||||
"/static/favicon-32.png": ("favicon-32.png", "image/png"),
|
||||
"/static/fonts/noto-sans-cyrillic-ext.woff2": ("fonts/noto-sans-cyrillic-ext.woff2", "font/woff2"),
|
||||
"/static/fonts/noto-sans-cyrillic.woff2": ("fonts/noto-sans-cyrillic.woff2", "font/woff2"),
|
||||
"/static/fonts/noto-sans-latin.woff2": ("fonts/noto-sans-latin.woff2", "font/woff2"),
|
||||
"/static/fonts/noto-serif-cyrillic-ext.woff2": ("fonts/noto-serif-cyrillic-ext.woff2", "font/woff2"),
|
||||
"/static/fonts/noto-serif-cyrillic.woff2": ("fonts/noto-serif-cyrillic.woff2", "font/woff2"),
|
||||
"/static/fonts/noto-serif-latin.woff2": ("fonts/noto-serif-latin.woff2", "font/woff2"),
|
||||
}
|
||||
|
||||
|
||||
class ApiError(Exception):
|
||||
def __init__(self, status: int, message: str):
|
||||
self.status = status
|
||||
self.message = message
|
||||
|
||||
|
||||
def parse_positive(value: str | None, name: str, default: int, maximum: int) -> int:
|
||||
if value is None:
|
||||
return default
|
||||
try:
|
||||
parsed = int(value)
|
||||
except ValueError as error:
|
||||
raise ApiError(400, f"{name} must be an integer") from error
|
||||
if not 1 <= parsed <= maximum:
|
||||
raise ApiError(400, f"{name} must be between 1 and {maximum}")
|
||||
return parsed
|
||||
|
||||
|
||||
def one(query: dict[str, list[str]], name: str) -> str | None:
|
||||
values = query.get(name, [])
|
||||
if len(values) > 1:
|
||||
raise ApiError(400, f"{name} must be specified once")
|
||||
return values[0] if values else None
|
||||
|
||||
|
||||
def date(value: str | None, name: str) -> str | None:
|
||||
if value is None:
|
||||
return None
|
||||
try:
|
||||
datetime.date.fromisoformat(value)
|
||||
except ValueError as error:
|
||||
raise ApiError(400, f"{name} must be an ISO date") from error
|
||||
return value
|
||||
|
||||
|
||||
def openapi() -> dict:
|
||||
responses = {"200": {"description": "Successful response"}, "400": {"description": "Invalid request"}, "401": {"description": "Authentication required"}, "403": {"description": "Additional access required"}, "404": {"description": "Not found"}, "502": {"description": "Search backend unavailable"}}
|
||||
return {
|
||||
"openapi": "3.0.3",
|
||||
"info": {"title": "Akyldash Search API", "version": API_VERSION},
|
||||
"components": {"securitySchemes": {"SessionCookie": {"type": "apiKey", "in": "cookie", "name": "akyldash_session"}}},
|
||||
"security": [{"SessionCookie": []}],
|
||||
"paths": {
|
||||
"/auth/login": {"post": {"security": [], "responses": {"200": {"description": "Signed in and session cookie issued"}, "401": {"description": "Invalid login or password"}}}},
|
||||
"/auth/logout": {"post": {"responses": {"200": {"description": "Signed out"}}}},
|
||||
"/auth/me": {"get": {"responses": {"200": {"description": "Current account"}, "401": {"description": "Authentication required"}}}},
|
||||
"/auth/change-password": {"post": {"description": "Requires the current password and a different new password", "responses": {"200": {"description": "Password changed"}, "400": {"description": "Current password is missing or invalid, or the new password is invalid or unchanged"}}}},
|
||||
"/admin/users": {"get": {"responses": {"200": {"description": "User list"}}}, "post": {"responses": {"201": {"description": "User created with a temporary password"}}}},
|
||||
"/admin/users/{username}": {"delete": {"responses": {"200": {"description": "User deleted"}}}},
|
||||
"/admin/users/{username}/reset-password": {"post": {"responses": {"200": {"description": "Temporary password set"}}}},
|
||||
"/search": {"get": {"responses": responses, "parameters": [
|
||||
{"name": "q", "in": "query", "required": True, "schema": {"type": "string"}},
|
||||
{"name": "language", "in": "query", "schema": {"type": "string", "enum": ["ru", "ky"]}},
|
||||
{"name": "page", "in": "query", "schema": {"type": "integer", "minimum": 1}},
|
||||
{"name": "page_size", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": MAX_PAGE_SIZE}},
|
||||
{"name": "document_type", "in": "query", "schema": {"type": "string"}},
|
||||
{"name": "status", "in": "query", "schema": {"type": "string"}},
|
||||
{"name": "authority", "in": "query", "schema": {"type": "string"}},
|
||||
{"name": "legal_force", "in": "query", "schema": {"type": "string"}},
|
||||
{"name": "date_from", "in": "query", "schema": {"type": "string", "format": "date"}},
|
||||
{"name": "date_to", "in": "query", "schema": {"type": "string", "format": "date"}},
|
||||
{"name": "sort", "in": "query", "schema": {"type": "string", "enum": ["relevance", "date"]}},
|
||||
]}},
|
||||
"/search/filters": {"get": {"responses": responses}},
|
||||
"/search-reviews": {"post": {"responses": {"201": {"description": "Review saved"}, "400": {"description": "Invalid review"}}}},
|
||||
"/search-reviews/export": {"get": {"responses": responses}},
|
||||
"/review": {"get": {"responses": {"200": {"description": "Review interface"}}}},
|
||||
"/documents/{code}": {"get": {"responses": responses, "parameters": [{"name": "code", "in": "path", "required": True, "schema": {"type": "string", "pattern": "^[0-9]+$"}}]}},
|
||||
"/documents/{code}/editions": {"get": {"responses": responses, "parameters": [{"name": "code", "in": "path", "required": True, "schema": {"type": "string", "pattern": "^[0-9]+$"}}]}},
|
||||
"/documents/{code}/editions/{edition}": {"get": {"responses": responses, "parameters": [{"name": "code", "in": "path", "required": True, "schema": {"type": "string", "pattern": "^[0-9]+$"}}, {"name": "edition", "in": "path", "required": True, "schema": {"type": "string", "pattern": "^[0-9]+$"}}]}},
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
class Api:
|
||||
def __init__(self, base_url: str, index: str, data_root: Path, reviews_db: Path | str = ":memory:", review_secret: bytes | None = None, users_db: Path | str = ":memory:", cookie_secure: bool = False):
|
||||
self.base_url = base_url.rstrip("/")
|
||||
self.index = index
|
||||
self.data_root = data_root
|
||||
self.review_store = ReviewStore(reviews_db)
|
||||
self.review_snapshots = ReviewSnapshots(review_secret)
|
||||
self.auth_store = AuthStore(users_db)
|
||||
self.cookie_secure = cookie_secure
|
||||
|
||||
def search_url(self, suffix: str) -> str:
|
||||
return f"{self.base_url}/{urllib.parse.quote(self.index, safe='')}/{suffix}"
|
||||
|
||||
def query_opensearch(self, body: dict, *, search_type: str | None = None) -> dict:
|
||||
try:
|
||||
url = self.search_url("_search")
|
||||
if search_type is not None:
|
||||
url = f"{url}?{urllib.parse.urlencode({'search_type': search_type})}"
|
||||
return request_json(url, "POST", json.dumps(body, ensure_ascii=False).encode(), "application/json")
|
||||
except RuntimeError as error:
|
||||
raise ApiError(502, "search backend is unavailable") from error
|
||||
|
||||
def search(self, query: dict[str, list[str]]) -> dict:
|
||||
text = one(query, "q")
|
||||
if not text or not text.strip():
|
||||
raise ApiError(400, "q is required")
|
||||
if len(text) > 500:
|
||||
raise ApiError(400, "q must not exceed 500 characters")
|
||||
language = one(query, "language") or "ru"
|
||||
if language not in LANGUAGES:
|
||||
raise ApiError(400, "language must be ru or ky")
|
||||
page = parse_positive(one(query, "page"), "page", 1, 1_000_000)
|
||||
page_size = parse_positive(one(query, "page_size"), "page_size", 20, MAX_PAGE_SIZE)
|
||||
if page * page_size >= MAX_RESULT_WINDOW:
|
||||
raise ApiError(400, f"page and page_size must stay within {MAX_RESULT_WINDOW} results")
|
||||
sort = one(query, "sort") or "relevance"
|
||||
if sort not in {"relevance", "date"}:
|
||||
raise ApiError(400, "sort must be relevance or date")
|
||||
filters: list[dict] = [{"term": {"language": language}}, {"term": {"is_current_edition": True}}]
|
||||
fields = {"document_type": "document_type_code", "status": "status_code", "authority": "authority_codes", "legal_force": "legal_force_code"}
|
||||
for parameter, field in fields.items():
|
||||
value = one(query, parameter)
|
||||
if value:
|
||||
if value not in CATALOGS[parameter]:
|
||||
raise ApiError(400, f"{parameter} must be a catalog code")
|
||||
filters.append({"term": {field: value}})
|
||||
date_from, date_to = date(one(query, "date_from"), "date_from"), date(one(query, "date_to"), "date_to")
|
||||
if date_from and date_to and date_from > date_to:
|
||||
raise ApiError(400, "date_from must not be later than date_to")
|
||||
if date_from or date_to:
|
||||
date_range = {key: value for key, value in (("gte", date_from), ("lte", date_to)) if value}
|
||||
filters.append({"range": {"date_adopted": date_range}})
|
||||
body = {
|
||||
"from": (page - 1) * page_size,
|
||||
"size": page_size + 1,
|
||||
"_source": ["document_code", "edition_code", "document_name_ru", "document_name_ky", "document_type_ru", "document_type_ky", "status_ru", "status_ky", "legal_force_code", "date_adopted", "number"],
|
||||
"query": {"bool": {"filter": filters, "must": build_search_query(language, text)}},
|
||||
"collapse": {"field": "document_code"},
|
||||
"highlight": {"fields": {f"text_{language}": {"number_of_fragments": 1}}},
|
||||
}
|
||||
body["sort"] = [{"_script": {
|
||||
"type": "number",
|
||||
"order": "asc",
|
||||
"script": {"lang": "painless", "source": "doc['status_code'].size() == 0 ? 1 : (doc['status_code'].value == 'active' ? 0 : (doc['status_code'].value == 'repealed' ? 2 : 1))"},
|
||||
}}]
|
||||
if sort == "date":
|
||||
body["sort"].append({"date_adopted": "desc"})
|
||||
body["sort"].append({"_score": "desc"})
|
||||
search_type = "dfs_query_then_fetch" if "," in self.index else None
|
||||
response = self.query_opensearch(body, search_type=search_type)
|
||||
try:
|
||||
hits = response["hits"]["hits"]
|
||||
except (KeyError, TypeError) as error:
|
||||
raise ApiError(502, "search backend returned an incomplete response") from error
|
||||
results = [self.search_hit(hit, language) for hit in hits[:page_size]]
|
||||
snapshot_results = [{"rank": rank, **result} for rank, result in enumerate(results, 1)]
|
||||
concrete_indexes = {hit.get("_index") for hit in hits[:page_size] if hit.get("_index")}
|
||||
# A comma-separated index expression is the searched dataset scope;
|
||||
# hits may come from only one of its members (or there may be no hits).
|
||||
# For a single configured index/alias, keep the concrete-index provenance
|
||||
# when OpenSearch returns exactly one concrete target.
|
||||
if "," in self.index:
|
||||
index_name = self.index
|
||||
else:
|
||||
index_name = next(iter(concrete_indexes)) if len(concrete_indexes) == 1 else self.index
|
||||
return {"api_version": API_VERSION, "query": text, "language": language, "page": page, "page_size": page_size, "has_next": len(hits) > page_size, "results": results, "review_token": self.review_snapshots.create(text, language, index_name, snapshot_results, SEARCH_ALGORITHM_VERSION)}
|
||||
|
||||
@staticmethod
|
||||
def search_hit(hit: dict, language: str) -> dict:
|
||||
source = hit.get("_source")
|
||||
if not isinstance(source, dict) or not source.get("document_code"):
|
||||
raise ApiError(502, "search backend returned an incomplete result")
|
||||
highlight = hit.get("highlight", {}).get(f"text_{language}", [])
|
||||
legal_force = source.get("legal_force_code")
|
||||
snippet = highlight[0].replace("<em>", "").replace("</em>", "") if highlight else None
|
||||
return {"code": source["document_code"], "edition": source.get("edition_code"), "name": source.get(f"document_name_{language}"), "type": source.get(f"document_type_{language}"), "status": source.get(f"status_{language}"), "legal_force": labels("legal_force", legal_force)[language] if legal_force else None, "date_adopted": source.get("date_adopted"), "number": source.get("number"), "snippet": snippet}
|
||||
|
||||
def filters(self, query: dict[str, list[str]]) -> dict:
|
||||
language = one(query, "language") or "ru"
|
||||
if language not in LANGUAGES:
|
||||
raise ApiError(400, "language must be ru or ky")
|
||||
fields = {"document_types": ("document_type", "document_type_code"), "statuses": ("status", "status_code"), "authorities": ("authority", "authority_codes"), "legal_forces": ("legal_force", "legal_force_code")}
|
||||
body = {"size": 0, "query": {"term": {"is_current_edition": True}}, "aggs": {name: {"terms": {"field": pair[1], "size": 1000}, "aggs": {"documents": {"cardinality": {"field": "document_code", "precision_threshold": 40000}}}} for name, pair in fields.items()}}
|
||||
response = self.query_opensearch(body)
|
||||
try:
|
||||
aggregations = response["aggregations"]
|
||||
values = {
|
||||
name: [{"code": item["key"], "labels": labels(pair[0], item["key"]), "count": item["documents"]["value"]} for item in aggregations[name]["buckets"]]
|
||||
for name, pair in fields.items()
|
||||
}
|
||||
except (KeyError, TypeError) as error:
|
||||
raise ApiError(502, "search backend returned incomplete filters") from error
|
||||
return {"api_version": API_VERSION, "language": language, **values}
|
||||
|
||||
def directory(self, code: str) -> Path:
|
||||
if not CODE.fullmatch(code):
|
||||
raise ApiError(404, "document not found")
|
||||
path = self.data_root / "documents" / code
|
||||
if not path.is_dir():
|
||||
raise ApiError(404, "document not found")
|
||||
return path
|
||||
|
||||
@staticmethod
|
||||
def read_json(path: Path, message: str) -> dict:
|
||||
try:
|
||||
value = json.loads(path.read_text(encoding="utf-8"))
|
||||
except (OSError, UnicodeError, json.JSONDecodeError) as error:
|
||||
raise ApiError(500, message) from error
|
||||
if not isinstance(value, dict):
|
||||
raise ApiError(500, message)
|
||||
return value
|
||||
|
||||
def document(self, code: str) -> dict:
|
||||
document = self.read_json(self.directory(code) / "document.json", "document data is unavailable")
|
||||
editions = document.get("editions")
|
||||
if not isinstance(editions, list):
|
||||
raise ApiError(500, "document data is unavailable")
|
||||
return {"api_version": API_VERSION, "document": document, "current_edition": editions[-1] if editions else None}
|
||||
|
||||
def editions(self, code: str) -> dict:
|
||||
document = self.read_json(self.directory(code) / "document.json", "document data is unavailable")
|
||||
return {"api_version": API_VERSION, "code": code, "available_languages": document.get("available_languages", []), "editions": document.get("editions", [])}
|
||||
|
||||
def edition(self, code: str, edition: str, query: dict[str, list[str]]) -> dict:
|
||||
if not CODE.fullmatch(edition):
|
||||
raise ApiError(404, "edition not found")
|
||||
directory = self.directory(code) / "editions" / edition
|
||||
if not directory.is_dir():
|
||||
raise ApiError(404, "edition not found")
|
||||
metadata = self.read_json(directory / "edition.json", "edition data is unavailable")
|
||||
language = one(query, "language")
|
||||
if language is not None and language not in LANGUAGES:
|
||||
raise ApiError(400, "language must be ru or ky")
|
||||
languages = [language] if language else metadata.get("available_languages", [])
|
||||
content = {}
|
||||
for item in languages:
|
||||
if item not in metadata.get("available_languages", []):
|
||||
continue
|
||||
try:
|
||||
content[item] = {"html": (directory / item / "content.html").read_text(encoding="utf-8"), "text": (directory / item / "content.txt").read_text(encoding="utf-8")}
|
||||
except (OSError, UnicodeError) as error:
|
||||
raise ApiError(500, "edition content is unavailable") from error
|
||||
if language and language not in content:
|
||||
raise ApiError(404, "edition language not found")
|
||||
return {"api_version": API_VERSION, "edition": metadata, "content": content}
|
||||
|
||||
def save_review(self, body: dict, username: str) -> dict:
|
||||
if not isinstance(body, dict):
|
||||
raise ApiError(400, "request body must be an object")
|
||||
try:
|
||||
snapshot = self.review_snapshots.verify(body["review_token"])
|
||||
reviewer = username
|
||||
overall_comment = body.get("overall_comment", "").strip()
|
||||
submitted = body["results"]
|
||||
except (KeyError, AttributeError, TypeError, ValueError) as error:
|
||||
raise ApiError(400, "review_token, reviewer and results are required") from error
|
||||
if not reviewer or len(reviewer) > 120:
|
||||
raise ApiError(400, "reviewer must be between 1 and 120 characters")
|
||||
if len(overall_comment) > 4000:
|
||||
raise ApiError(400, "overall_comment is too long")
|
||||
if not isinstance(submitted, list):
|
||||
raise ApiError(400, "results must be an array")
|
||||
if len(submitted) > MAX_PAGE_SIZE:
|
||||
raise ApiError(400, f"results must not exceed {MAX_PAGE_SIZE} items")
|
||||
if any(not isinstance(item, dict) for item in submitted):
|
||||
raise ApiError(400, "review result must be an object")
|
||||
ranks = [item.get("rank") for item in submitted]
|
||||
if any(type(rank) is not int for rank in ranks):
|
||||
raise ApiError(400, "review result rank is invalid")
|
||||
by_rank = {item["rank"]: item for item in snapshot["results"]}
|
||||
if len(ranks) != len(set(ranks)) or len(submitted) != len(by_rank) or set(ranks) != set(by_rank):
|
||||
raise ApiError(400, "all search results must be reviewed exactly once")
|
||||
if not snapshot["results"] and not overall_comment.strip():
|
||||
raise ApiError(400, "overall_comment is required for an empty search result")
|
||||
results = []
|
||||
for item in submitted:
|
||||
if not isinstance(item, dict) or not isinstance(item.get("rank"), int) or item["rank"] not in by_rank:
|
||||
raise ApiError(400, "review result rank is invalid")
|
||||
source = by_rank[item["rank"]]
|
||||
if item.get("code") != source["code"]:
|
||||
raise ApiError(400, "review result document does not match the search snapshot")
|
||||
rating = item.get("rating")
|
||||
if rating is not None and (isinstance(rating, bool) or not isinstance(rating, int) or not 0 <= rating <= 3):
|
||||
raise ApiError(400, "rating must be an integer from 0 to 3")
|
||||
comment = item.get("comment", "")
|
||||
if not isinstance(comment, str) or len(comment) > 4000:
|
||||
raise ApiError(400, "result comment is too long")
|
||||
results.append({**source, "rating": rating, "comment": comment.strip()})
|
||||
review = {"created_at": datetime.datetime.now(datetime.timezone.utc).isoformat(), "reviewer": reviewer, "query": snapshot["query"], "language": snapshot["language"], "index_name": snapshot["index_name"], "algorithm_version": snapshot["algorithm_version"], "top_result_code": snapshot["results"][0]["code"] if snapshot["results"] else None, "results": results, "overall_comment": overall_comment}
|
||||
review_id = self.review_store.save(review)
|
||||
return {"api_version": API_VERSION, "id": review_id, "created_at": review["created_at"]}
|
||||
|
||||
@staticmethod
|
||||
def review_page() -> str:
|
||||
try:
|
||||
return Path(__file__).with_name("review.html").read_text(encoding="utf-8")
|
||||
except (OSError, UnicodeError) as error:
|
||||
raise ApiError(500, "review interface is unavailable") from error
|
||||
|
||||
@staticmethod
|
||||
def static_asset(route: str) -> tuple[str, bytes]:
|
||||
asset = STATIC_ASSETS.get(route)
|
||||
if asset is None:
|
||||
raise ApiError(404, "static asset not found")
|
||||
path = Path(__file__).with_name("static") / asset[0]
|
||||
try:
|
||||
return asset[1], path.read_bytes()
|
||||
except OSError as error:
|
||||
raise ApiError(500, "static asset is unavailable") from error
|
||||
|
||||
def handle(self, method: str, path: str, body: dict | None = None, user: dict | None = None) -> tuple[int, dict]:
|
||||
parsed = urllib.parse.urlsplit(path)
|
||||
query = urllib.parse.parse_qs(parsed.query, keep_blank_values=True)
|
||||
parts = [urllib.parse.unquote(part) for part in parsed.path.split("/") if part]
|
||||
if method == "POST" and parts == ["auth", "login"]:
|
||||
try:
|
||||
token, account = self.auth_store.login(body.get("username"), body.get("password"))
|
||||
return 200, {"account": account, "session_token": token}
|
||||
except AuthError as error:
|
||||
raise ApiError(401, str(error)) from error
|
||||
if method == "POST" and parts == ["auth", "logout"]:
|
||||
return 200, {"ok": True}
|
||||
if method == "GET" and parts == ["auth", "me"]:
|
||||
return 200, {"account": user}
|
||||
if method == "POST" and parts == ["auth", "change-password"]:
|
||||
try:
|
||||
self.auth_store.change_password(user["username"], body.get("current_password"), body.get("new_password"))
|
||||
token, account = self.auth_store.login(user["username"], body.get("new_password"))
|
||||
return 200, {"account": account, "session_token": token}
|
||||
except AuthError as error:
|
||||
raise ApiError(400, str(error)) from error
|
||||
if user and can_manage_users(user["username"]) and method == "GET" and parts == ["admin", "users"]:
|
||||
return 200, {"users": self.auth_store.list_users()}
|
||||
if user and can_manage_users(user["username"]) and method == "POST" and parts == ["admin", "users"]:
|
||||
try:
|
||||
self.auth_store.create_user(body.get("username"), body.get("password"))
|
||||
return 201, {"ok": True}
|
||||
except AuthError as error:
|
||||
raise ApiError(400, str(error)) from error
|
||||
if user and can_manage_users(user["username"]) and method == "DELETE" and len(parts) == 3 and parts[:2] == ["admin", "users"]:
|
||||
try:
|
||||
self.auth_store.delete_user(parts[2])
|
||||
return 200, {"ok": True}
|
||||
except AuthError as error:
|
||||
raise ApiError(400, str(error)) from error
|
||||
if user and can_manage_users(user["username"]) and method == "POST" and len(parts) == 4 and parts[:2] == ["admin", "users"] and parts[3] == "reset-password":
|
||||
try:
|
||||
self.auth_store.reset_password(parts[2], body.get("password"))
|
||||
return 200, {"ok": True}
|
||||
except AuthError as error:
|
||||
raise ApiError(400, str(error)) from error
|
||||
if method == "POST" and parts == ["search-reviews"]:
|
||||
return 201, self.save_review(body, user["username"] if user else body.get("reviewer", ""))
|
||||
if method == "GET" and parts == ["search-reviews", "export"]:
|
||||
return 200, {"api_version": API_VERSION, "reviews": self.review_store.export()}
|
||||
if method != "GET":
|
||||
raise ApiError(405, "method not allowed")
|
||||
if parts == ["openapi.json"]:
|
||||
return 200, openapi()
|
||||
if parts == ["search"]:
|
||||
return 200, self.search(query)
|
||||
if parts == ["search", "filters"]:
|
||||
return 200, self.filters(query)
|
||||
if len(parts) == 2 and parts[0] == "documents":
|
||||
return 200, self.document(parts[1])
|
||||
if len(parts) == 3 and parts[:1] == ["documents"] and parts[2] == "editions":
|
||||
return 200, self.editions(parts[1])
|
||||
if len(parts) == 4 and parts[:1] == ["documents"] and parts[2] == "editions":
|
||||
return 200, self.edition(parts[1], parts[3], query)
|
||||
raise ApiError(404, "endpoint not found")
|
||||
|
||||
|
||||
def handler(api: Api):
|
||||
class RequestHandler(BaseHTTPRequestHandler):
|
||||
def respond(self, method: str):
|
||||
try:
|
||||
route = urllib.parse.urlsplit(self.path).path
|
||||
cookies = http.cookies.SimpleCookie(self.headers.get("Cookie", ""))
|
||||
session = cookies.get("akyldash_session")
|
||||
token = session.value if session else None
|
||||
user = api.auth_store.user_for_token(token)
|
||||
if method == "GET" and route in {"/", "/review", "/users"}:
|
||||
body = api.review_page().encode()
|
||||
self.send_response(200)
|
||||
self.send_header("Content-Type", "text/html; charset=utf-8")
|
||||
self.send_header("Cache-Control", "no-store")
|
||||
self.send_header("X-Content-Type-Options", "nosniff")
|
||||
self.send_header("X-Frame-Options", "DENY")
|
||||
self.send_header("Referrer-Policy", "no-referrer")
|
||||
self.send_header("Content-Length", str(len(body)))
|
||||
self.end_headers()
|
||||
self.wfile.write(body)
|
||||
return
|
||||
if method == "GET" and route in STATIC_ASSETS:
|
||||
content_type, body = api.static_asset(route)
|
||||
self.send_response(200)
|
||||
self.send_header("Content-Type", content_type)
|
||||
self.send_header("Cache-Control", "public, max-age=604800, immutable")
|
||||
self.send_header("X-Content-Type-Options", "nosniff")
|
||||
self.send_header("X-Frame-Options", "DENY")
|
||||
self.send_header("Referrer-Policy", "no-referrer")
|
||||
self.send_header("Content-Length", str(len(body)))
|
||||
self.end_headers()
|
||||
self.wfile.write(body)
|
||||
return
|
||||
if not (method == "POST" and route in {"/auth/login", "/auth/logout"}):
|
||||
if not user:
|
||||
raise ApiError(401, "authentication required")
|
||||
if user["must_change_password"] and not (method == "POST" and route == "/auth/change-password") and not (method == "GET" and route == "/auth/me"):
|
||||
raise ApiError(403, "change password before continuing")
|
||||
if route.startswith("/admin/users") and not can_manage_users(user["username"]):
|
||||
raise ApiError(403, "admin account required")
|
||||
body = None
|
||||
if method in {"POST", "DELETE"}:
|
||||
length = int(self.headers.get("Content-Length", "0"))
|
||||
if length > 1_000_000:
|
||||
raise ApiError(413, "request body is too large")
|
||||
body = json.loads(self.rfile.read(length) or b"{}")
|
||||
if not isinstance(body, dict):
|
||||
raise ApiError(400, "request body must be a JSON object")
|
||||
if method == "POST" and route == "/auth/logout":
|
||||
api.auth_store.logout(token)
|
||||
status, payload = api.handle(method, self.path, body, user)
|
||||
except json.JSONDecodeError:
|
||||
status, payload = 400, {"api_version": API_VERSION, "error": "request body must be valid JSON"}
|
||||
except ApiError as error:
|
||||
status, payload = error.status, {"api_version": API_VERSION, "error": error.message}
|
||||
except (ValueError, http.cookies.CookieError):
|
||||
status, payload = 400, {"api_version": API_VERSION, "error": "invalid request"}
|
||||
session_token = payload.pop("session_token", None) if isinstance(payload, dict) else None
|
||||
body = json.dumps(payload, ensure_ascii=False).encode()
|
||||
self.send_response(status)
|
||||
if session_token:
|
||||
secure = "; Secure" if api.cookie_secure else ""
|
||||
self.send_header("Set-Cookie", f"akyldash_session={session_token}; Path=/; HttpOnly; SameSite=Strict; Max-Age=43200{secure}")
|
||||
elif method == "POST" and urllib.parse.urlsplit(self.path).path == "/auth/logout":
|
||||
secure = "; Secure" if api.cookie_secure else ""
|
||||
self.send_header("Set-Cookie", f"akyldash_session=; Path=/; HttpOnly; SameSite=Strict; Max-Age=0{secure}")
|
||||
self.send_header("Content-Type", "application/json; charset=utf-8")
|
||||
self.send_header("Cache-Control", "no-store")
|
||||
self.send_header("X-Content-Type-Options", "nosniff")
|
||||
self.send_header("X-Frame-Options", "DENY")
|
||||
self.send_header("Referrer-Policy", "no-referrer")
|
||||
self.send_header("Content-Length", str(len(body)))
|
||||
self.end_headers()
|
||||
self.wfile.write(body)
|
||||
|
||||
def do_GET(self):
|
||||
self.respond("GET")
|
||||
|
||||
def do_POST(self):
|
||||
self.respond("POST")
|
||||
|
||||
def do_DELETE(self):
|
||||
self.respond("DELETE")
|
||||
|
||||
def log_message(self, format: str, *args):
|
||||
return
|
||||
|
||||
return RequestHandler
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("--url", default="http://127.0.0.1:9200")
|
||||
parser.add_argument("--index", default="akyldash-fragments-current")
|
||||
parser.add_argument("--data", type=Path, default=Path("data/minjust-normalized"))
|
||||
parser.add_argument("--reviews-db", type=Path, default=Path("data/search-reviews.sqlite3"))
|
||||
parser.add_argument("--users-db", type=Path, default=Path("data/search-users.sqlite3"))
|
||||
parser.add_argument("--review-secret", default=None)
|
||||
parser.add_argument("--review-secret-file", type=Path)
|
||||
parser.add_argument("--cookie-secure", action=argparse.BooleanOptionalAction, default=os.environ.get("COOKIE_SECURE", "false").lower() == "true")
|
||||
parser.add_argument("--create-admin", action="store_true", help="create the initial admin account and exit")
|
||||
parser.add_argument("--reset-admin-password", action="store_true", help="set a temporary password for admin and exit")
|
||||
parser.add_argument("--host", default="127.0.0.1")
|
||||
parser.add_argument("--port", type=int, default=8080)
|
||||
parser.add_argument("--version", action="version", version=APP_VERSION)
|
||||
arguments = parser.parse_args()
|
||||
if arguments.review_secret and arguments.review_secret_file:
|
||||
parser.error("choose either --review-secret or --review-secret-file")
|
||||
try:
|
||||
secret = arguments.review_secret.encode() if arguments.review_secret else arguments.review_secret_file.read_bytes().strip() if arguments.review_secret_file else None
|
||||
except OSError as error:
|
||||
parser.error(f"cannot read review secret file: {error}")
|
||||
if arguments.review_secret_file and not secret:
|
||||
parser.error("review secret file is empty")
|
||||
api = Api(arguments.url, arguments.index, arguments.data, arguments.reviews_db, secret, arguments.users_db, arguments.cookie_secure)
|
||||
if arguments.create_admin or arguments.reset_admin_password:
|
||||
users = api.auth_store.list_users()
|
||||
admin_exists = any(can_manage_users(user["username"]) for user in users)
|
||||
if arguments.create_admin and users:
|
||||
parser.error("accounts already exist")
|
||||
if arguments.reset_admin_password and not admin_exists:
|
||||
parser.error("admin account does not exist")
|
||||
if arguments.create_admin and arguments.reset_admin_password:
|
||||
parser.error("choose either --create-admin or --reset-admin-password")
|
||||
password = getpass.getpass("Password for admin (12+ characters): ")
|
||||
confirm = getpass.getpass("Confirm password: ")
|
||||
if password != confirm:
|
||||
parser.error("passwords do not match")
|
||||
try:
|
||||
if arguments.create_admin:
|
||||
api.auth_store.create_admin(password)
|
||||
else:
|
||||
api.auth_store.reset_password("admin", password)
|
||||
except AuthError as error:
|
||||
parser.error(str(error))
|
||||
print("Initial admin account created." if arguments.create_admin else "Admin password reset. Change it at next sign-in.")
|
||||
return 0
|
||||
ThreadingHTTPServer((arguments.host, arguments.port), handler(api)).serve_forever()
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
@@ -0,0 +1,183 @@
|
||||
"""Local user accounts and cookie sessions for the internal search workspace."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import hmac
|
||||
import os
|
||||
import re
|
||||
import secrets
|
||||
import sqlite3
|
||||
import threading
|
||||
import time
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
USERNAME = re.compile(r"^[A-Za-z0-9._-]{3,64}$")
|
||||
PASSWORD_ITERATIONS = 310_000
|
||||
SESSION_TTL = 60 * 60 * 12
|
||||
|
||||
|
||||
class AuthError(ValueError):
|
||||
pass
|
||||
|
||||
|
||||
def can_manage_users(username: str) -> bool:
|
||||
return isinstance(username, str) and username.casefold() == "admin"
|
||||
|
||||
|
||||
class AuthStore:
|
||||
def __init__(self, path: Path | str):
|
||||
if path != ":memory:":
|
||||
database = Path(path)
|
||||
database.parent.mkdir(parents=True, exist_ok=True)
|
||||
try:
|
||||
descriptor = os.open(database, os.O_CREAT | os.O_EXCL | os.O_RDWR, 0o600)
|
||||
os.close(descriptor)
|
||||
except FileExistsError:
|
||||
pass
|
||||
self.connection = sqlite3.connect(path, check_same_thread=False)
|
||||
self.connection.row_factory = sqlite3.Row
|
||||
self._lock = threading.RLock()
|
||||
self.connection.executescript("""
|
||||
CREATE TABLE IF NOT EXISTS users (
|
||||
username TEXT PRIMARY KEY COLLATE NOCASE,
|
||||
password_hash BLOB NOT NULL,
|
||||
password_salt BLOB NOT NULL,
|
||||
must_change_password INTEGER NOT NULL DEFAULT 1,
|
||||
created_at INTEGER NOT NULL,
|
||||
first_login_at INTEGER,
|
||||
last_login_at INTEGER,
|
||||
password_reset_at INTEGER
|
||||
);
|
||||
CREATE TABLE IF NOT EXISTS sessions (
|
||||
token_hash BLOB PRIMARY KEY,
|
||||
username TEXT NOT NULL REFERENCES users(username) ON DELETE CASCADE,
|
||||
expires_at INTEGER NOT NULL
|
||||
);
|
||||
""")
|
||||
user_columns = {row["name"] for row in self.connection.execute("PRAGMA table_info(users)")}
|
||||
for column in ("first_login_at", "last_login_at", "password_reset_at"):
|
||||
if column not in user_columns:
|
||||
self.connection.execute(f"ALTER TABLE users ADD COLUMN {column} INTEGER")
|
||||
self.connection.execute("PRAGMA foreign_keys = ON")
|
||||
self.connection.commit()
|
||||
|
||||
@staticmethod
|
||||
def _validate(username: str, password: str) -> tuple[str, str]:
|
||||
if not isinstance(username, str) or not USERNAME.fullmatch(username):
|
||||
raise AuthError("login must be 3–64 letters, numbers, dots, underscores or hyphens")
|
||||
if not isinstance(password, str) or not 12 <= len(password) <= 256:
|
||||
raise AuthError("password must be between 12 and 256 characters")
|
||||
return username, password
|
||||
|
||||
@staticmethod
|
||||
def _hash(password: str, salt: bytes) -> bytes:
|
||||
return hashlib.pbkdf2_hmac("sha256", password.encode(), salt, PASSWORD_ITERATIONS)
|
||||
|
||||
def create_admin(self, password: str) -> None:
|
||||
self._validate("admin", password)
|
||||
salt = secrets.token_bytes(16)
|
||||
with self._lock:
|
||||
if self.connection.execute("SELECT 1 FROM users LIMIT 1").fetchone():
|
||||
raise AuthError("accounts already exist")
|
||||
self.connection.execute("INSERT INTO users(username,password_hash,password_salt,must_change_password,created_at) VALUES('admin',?,?,0,?)", (self._hash(password, salt), salt, int(time.time())))
|
||||
self.connection.commit()
|
||||
|
||||
# shortcut: login throttling belongs to the HTTPS reverse proxy; add local limits before direct public exposure.
|
||||
def login(self, username: str, password: str) -> tuple[str, dict]:
|
||||
if not isinstance(username, str) or not isinstance(password, str):
|
||||
raise AuthError("invalid login or password")
|
||||
with self._lock:
|
||||
user = self.connection.execute("SELECT * FROM users WHERE username = ? COLLATE NOCASE", (username,)).fetchone()
|
||||
salt = user["password_salt"] if user else b"\0" * 16
|
||||
expected_hash = user["password_hash"] if user else b"\0" * 32
|
||||
valid = hmac.compare_digest(self._hash(password, salt), expected_hash)
|
||||
if not user or not valid:
|
||||
raise AuthError("invalid login or password")
|
||||
with self._lock:
|
||||
current = self.connection.execute("SELECT * FROM users WHERE username=?", (user["username"],)).fetchone()
|
||||
if not current or not hmac.compare_digest(current["password_hash"], expected_hash):
|
||||
raise AuthError("invalid login or password")
|
||||
token = secrets.token_urlsafe(32)
|
||||
now = int(time.time())
|
||||
self.connection.execute("DELETE FROM sessions WHERE expires_at <= ?", (now,))
|
||||
self.connection.execute("INSERT INTO sessions(token_hash,username,expires_at) VALUES(?,?,?)", (hashlib.sha256(token.encode()).digest(), user["username"], now + SESSION_TTL))
|
||||
self.connection.execute("UPDATE users SET first_login_at=COALESCE(first_login_at,?),last_login_at=? WHERE username=?", (now, now, user["username"]))
|
||||
self.connection.commit()
|
||||
current = self.connection.execute("SELECT * FROM users WHERE username=?", (user["username"],)).fetchone()
|
||||
return token, self._public(current)
|
||||
|
||||
@staticmethod
|
||||
def _public(user: sqlite3.Row) -> dict:
|
||||
can_manage = can_manage_users(user["username"])
|
||||
return {"username": user["username"], "role": "Администратор" if can_manage else "Пользователь", "can_manage_users": can_manage, "must_change_password": bool(user["must_change_password"]), "created_at": user["created_at"]}
|
||||
|
||||
def user_for_token(self, token: str | None) -> dict | None:
|
||||
if not token:
|
||||
return None
|
||||
with self._lock:
|
||||
user = self.connection.execute("SELECT users.* FROM sessions JOIN users USING(username) WHERE token_hash = ? AND expires_at > ?", (hashlib.sha256(token.encode()).digest(), int(time.time()))).fetchone()
|
||||
return self._public(user) if user else None
|
||||
|
||||
def logout(self, token: str | None) -> None:
|
||||
if token:
|
||||
with self._lock:
|
||||
self.connection.execute("DELETE FROM sessions WHERE token_hash = ?", (hashlib.sha256(token.encode()).digest(),))
|
||||
self.connection.commit()
|
||||
|
||||
def change_password(self, username: str, old_password: str, new_password: str) -> None:
|
||||
if not isinstance(old_password, str):
|
||||
raise AuthError("current password is required")
|
||||
self._validate(username, new_password)
|
||||
with self._lock:
|
||||
user = self.connection.execute("SELECT * FROM users WHERE username = ?", (username,)).fetchone()
|
||||
if not user:
|
||||
raise AuthError("account not found")
|
||||
if not hmac.compare_digest(self._hash(old_password, user["password_salt"]), user["password_hash"]):
|
||||
raise AuthError("current password is incorrect")
|
||||
if hmac.compare_digest(self._hash(new_password, user["password_salt"]), user["password_hash"]):
|
||||
raise AuthError("new password must be different")
|
||||
salt = secrets.token_bytes(16)
|
||||
password_hash = self._hash(new_password, salt)
|
||||
self.connection.execute("UPDATE users SET password_hash=?,password_salt=?,must_change_password=0 WHERE username=?", (password_hash, salt, username))
|
||||
self.connection.execute("DELETE FROM sessions WHERE username=?", (username,))
|
||||
self.connection.commit()
|
||||
|
||||
def create_user(self, username: str, password: str) -> None:
|
||||
self._validate(username, password)
|
||||
salt = secrets.token_bytes(16)
|
||||
password_hash = self._hash(password, salt)
|
||||
try:
|
||||
with self._lock:
|
||||
self.connection.execute("INSERT INTO users(username,password_hash,password_salt,must_change_password,created_at) VALUES(?,?,?,1,?)", (username, password_hash, salt, int(time.time())))
|
||||
self.connection.commit()
|
||||
except sqlite3.IntegrityError as error:
|
||||
raise AuthError("login already exists") from error
|
||||
|
||||
def delete_user(self, username: str) -> None:
|
||||
if can_manage_users(username):
|
||||
raise AuthError("admin account cannot be deleted")
|
||||
with self._lock:
|
||||
self.connection.execute("DELETE FROM users WHERE username=?", (username,))
|
||||
self.connection.commit()
|
||||
|
||||
def reset_password(self, username: str, password: str) -> None:
|
||||
self._validate(username, password)
|
||||
salt = secrets.token_bytes(16)
|
||||
password_hash = self._hash(password, salt)
|
||||
with self._lock:
|
||||
cursor = self.connection.execute("UPDATE users SET password_hash=?,password_salt=?,must_change_password=1,password_reset_at=? WHERE username=?", (password_hash, salt, int(time.time()), username))
|
||||
if not cursor.rowcount:
|
||||
raise AuthError("account not found")
|
||||
self.connection.execute("DELETE FROM sessions WHERE username=?", (username,))
|
||||
self.connection.commit()
|
||||
|
||||
def list_users(self) -> list[dict]:
|
||||
with self._lock:
|
||||
users = []
|
||||
for row in self.connection.execute("SELECT * FROM users ORDER BY username COLLATE NOCASE"):
|
||||
account = self._public(row)
|
||||
account.update(first_login_at=row["first_login_at"], last_login_at=row["last_login_at"], password_reset_at=row["password_reset_at"])
|
||||
users.append(account)
|
||||
return users
|
||||
@@ -0,0 +1,79 @@
|
||||
"""Immutable v1 search catalogs."""
|
||||
|
||||
DOCUMENT_TYPES = {
|
||||
"constitution": ("Конституция", "Конституция"), "constitutional_law": ("Конституционный Закон", "Конституциалык Мыйзам"), "code": ("Кодекс", "Кодекс"), "law": ("Закон", "Мыйзам"), "decree": ("Указ", "Жарлык"), "resolution": ("Постановление", "Токтом"), "order": ("Распоряжение", "Распоряжение"), "instruction": ("Инструкция", "Инструкция"), "rules": ("Правила", "Правила"), "procedure": ("Порядок", "Порядок"), "provision": ("Положение", "Жобо"), "regulation": ("Регламент", "Регламент"), "charter": ("Устав", "Жобо (Устав)"), "program": ("Программа", "Программа"), "plan": ("План", "План"), "strategy": ("Стратегия", "Стратегия"), "concept": ("Концепция", "Концепция"), "doctrine": ("Доктрина", "Доктрина"), "agreement": ("Соглашение", "Соглашение"), "declaration": ("Декларация", "Декларация"), "registry": ("Реестр", "Реестр"), "norms": ("Нормативы", "Нормативы"), "model": ("Модель", "Модель"), "matrix": ("Матрица", "Матрица"), "study": ("Исследование", "Исследование"), "report": ("Доклад", "Доклад"), "principles": ("Основные принципы", "Основные принципы"), "other": ("Прочие документы", "Башка документтер"), "unspecified": ("Не указан", "Көрсөтүлгөн эмес"),
|
||||
}
|
||||
STATUSES = {"active": ("Действует", "Күчүндө"), "repealed": ("Утратил силу", "Күчүн жоготту"), "not_yet_effective": ("Не вступил в силу", "Күчүнө кире элек"), "canceled": ("Отменено", "Жокко чыгарылды"), "inactive": ("Не действует", "Күчүндө эмес же Колдонулбайт"), "terminated": ("Прекратило действие", "Күчүн токтотту же Колдонуу токтотулган"), "suspended": ("Действие приостановлено", "Күчүнө кирүүсү токтотулган"), "unspecified": ("Не указан", "Көрсөтүлгөн эмес")}
|
||||
AUTHORITIES = {"president": ("Президент", "Президент"), "parliament": ("Органы законодательной власти", "Мыйзам чыгаруу бийлик органдары"), "cabinet": ("Правительство и Кабинет Министров", "Өкмөт жана Министрлер Кабинети"), "ministries_and_committees": ("Министерства и государственные комитеты", "Министрликтер жана мамлекеттик комитеттер"), "administrative_agencies": ("Административные ведомства", "Административдик ведомстволор"), "national_bank": ("Национальный банк", "Улуттук банк"), "other_state_bodies": ("Иные государственные органы", "Башка мамлекеттик органдар"), "local_representative_bodies": ("Представительные органы местного самоуправления", "Жергиликтүү өз алдынча башкаруунун өкүлчүлүктүү органдары"), "other": ("Прочие органы", "Башка органдар")}
|
||||
LEGAL_FORCE_LEVELS = {
|
||||
"constitutional": ("Конституционный уровень", "Конституциялык деңгээл"),
|
||||
"legislative": ("Законодательный уровень", "Мыйзам деңгээли"),
|
||||
"subordinate": ("Подзаконный уровень", "Мыйзам алдындагы деңгээл"),
|
||||
}
|
||||
LEGAL_FORCE_BY_DOCUMENT_TYPE = {
|
||||
"constitution": "constitutional",
|
||||
"constitutional_law": "constitutional",
|
||||
"code": "legislative",
|
||||
"law": "legislative",
|
||||
"decree": "subordinate",
|
||||
"resolution": "subordinate",
|
||||
}
|
||||
CATALOGS = {"document_type": DOCUMENT_TYPES, "status": STATUSES, "authority": AUTHORITIES, "legal_force": LEGAL_FORCE_LEVELS}
|
||||
DOCUMENT_TYPE_ALIASES = {
|
||||
("Положение", "Положение"): "provision",
|
||||
("Конституционный закон", "Конституционный закон"): "constitutional_law",
|
||||
("Указ", "Жарлыгы"): "decree",
|
||||
("устав", None): "charter",
|
||||
}
|
||||
|
||||
|
||||
def labels(category: str, code: str) -> dict[str, str]:
|
||||
try:
|
||||
ru, ky = CATALOGS[category][code]
|
||||
except KeyError as error:
|
||||
raise ValueError(f"Unknown {category} catalog code: {code}") from error
|
||||
return {"ru": ru, "ky": ky}
|
||||
|
||||
|
||||
def source_code(category: str, value: dict | None) -> str:
|
||||
pair = ((value or {}).get("ru"), (value or {}).get("ky"))
|
||||
if pair == (None, None):
|
||||
return "unspecified"
|
||||
if category == "document_type" and pair in DOCUMENT_TYPE_ALIASES:
|
||||
return DOCUMENT_TYPE_ALIASES[pair]
|
||||
for code, expected in CATALOGS[category].items():
|
||||
if pair == expected:
|
||||
return code
|
||||
# ponytail: uncurated source types share one filter; add reviewed codes when separate filtering is needed.
|
||||
if category == "document_type":
|
||||
return "other"
|
||||
raise ValueError(f"Unmapped {category} catalog value: {pair!r}")
|
||||
|
||||
|
||||
def authority_codes(paths: list[dict]) -> list[str]:
|
||||
codes = set()
|
||||
for path in paths:
|
||||
text = " ".join(path.get("ru", []) + path.get("ky", [])).lower()
|
||||
if "президент" in text:
|
||||
codes.add("president")
|
||||
elif "жогорку кенеш" in text or "верховный совет" in text or "мыйзам чыгаруу" in text:
|
||||
codes.add("parliament")
|
||||
elif "кабинет министров" in text or "правительство" in text or "өкмөт" in text:
|
||||
codes.add("cabinet")
|
||||
elif "министер" in text or "мамлекеттик комитет" in text:
|
||||
codes.add("ministries_and_committees")
|
||||
elif "административ" in text:
|
||||
codes.add("administrative_agencies")
|
||||
elif "национальн" in text and "банк" in text or "улуттук банк" in text:
|
||||
codes.add("national_bank")
|
||||
elif "кенеш" in text or "кеңеш" in text or "айыл" in text or "местного самоуправления" in text:
|
||||
codes.add("local_representative_bodies")
|
||||
elif "иные государственные" in text or "башка мамлекеттик" in text:
|
||||
codes.add("other_state_bodies")
|
||||
else:
|
||||
codes.add("other")
|
||||
return sorted(codes) or ["other"]
|
||||
|
||||
|
||||
def legal_force_code(document_type: dict | None) -> str | None:
|
||||
return LEGAL_FORCE_BY_DOCUMENT_TYPE.get(source_code("document_type", document_type))
|
||||
@@ -5,10 +5,10 @@ from __future__ import annotations
|
||||
import argparse
|
||||
import json
|
||||
import sys
|
||||
import urllib.parse
|
||||
from pathlib import Path
|
||||
|
||||
from search.minjust_opensearch import APP_VERSION, request_json
|
||||
from search.minjust_opensearch import APP_VERSION
|
||||
from search.query import search_documents
|
||||
|
||||
|
||||
def load_queries(path: Path) -> list[dict]:
|
||||
@@ -43,30 +43,7 @@ def load_queries(path: Path) -> list[dict]:
|
||||
|
||||
|
||||
def search(base_url: str, index: str, item: dict, top_k: int) -> list[str]:
|
||||
language = item["language"]
|
||||
body = json.dumps({
|
||||
"size": top_k,
|
||||
"track_total_hits": False,
|
||||
"_source": ["document_code"],
|
||||
"query": {
|
||||
"bool": {
|
||||
"filter": {"term": {"language": language}},
|
||||
"must": {
|
||||
"multi_match": {
|
||||
"query": item["query"],
|
||||
"fields": [f"document_name_{language}", f"text_{language}"],
|
||||
}
|
||||
},
|
||||
}
|
||||
},
|
||||
"collapse": {"field": "document_code"},
|
||||
}, ensure_ascii=False).encode()
|
||||
url = f"{base_url.rstrip('/')}/{urllib.parse.quote(index, safe='')}/_search"
|
||||
response = request_json(url, "POST", body, "application/json")
|
||||
try:
|
||||
return [hit["_source"]["document_code"] for hit in response["hits"]["hits"]]
|
||||
except (KeyError, TypeError) as error:
|
||||
raise RuntimeError("OpenSearch search response is incomplete") from error
|
||||
return search_documents(base_url, index, item["language"], item["query"], top_k)
|
||||
|
||||
|
||||
def evaluate(queries: list[dict], base_url: str, index: str, top_k: int) -> dict:
|
||||
@@ -105,7 +82,7 @@ def main() -> int:
|
||||
raise SystemExit("--top-k must be greater than zero")
|
||||
result = evaluate(load_queries(arguments.relevance_set), arguments.url, arguments.index, arguments.top_k)
|
||||
print(json.dumps(result, ensure_ascii=False, indent=2))
|
||||
print(f"Akyldash Backend v{APP_VERSION} · Frontend — not created", file=sys.stderr)
|
||||
print(f"Akyldash · Backend v{APP_VERSION} · Frontend v0.3.4", file=sys.stderr)
|
||||
return 0
|
||||
|
||||
|
||||
|
||||
@@ -12,6 +12,7 @@
|
||||
"schema_version": { "type": "keyword" },
|
||||
"document_code": { "type": "keyword" },
|
||||
"edition_code": { "type": "keyword" },
|
||||
"is_current_edition": { "type": "boolean" },
|
||||
"language": { "type": "keyword" },
|
||||
"position": { "type": "integer" },
|
||||
"fragment_type": { "type": "keyword" },
|
||||
@@ -21,12 +22,16 @@
|
||||
"document_name_ky": { "type": "text", "analyzer": "icu_analyzer", "fields": { "keyword": { "type": "keyword", "ignore_above": 1024 } } },
|
||||
"document_type_ru": { "type": "keyword" },
|
||||
"document_type_ky": { "type": "keyword" },
|
||||
"document_type_code": { "type": "keyword" },
|
||||
"legal_force_code": { "type": "keyword" },
|
||||
"status_ru": { "type": "keyword" },
|
||||
"status_ky": { "type": "keyword" },
|
||||
"status_code": { "type": "keyword" },
|
||||
"number": { "type": "keyword" },
|
||||
"date_adopted": { "type": "date", "format": "strict_date" },
|
||||
"authority_paths_ru": { "type": "keyword", "ignore_above": 2048 },
|
||||
"authority_paths_ky": { "type": "keyword", "ignore_above": 2048 },
|
||||
"authority_codes": { "type": "keyword" },
|
||||
"source_path": { "type": "keyword", "index": false },
|
||||
"source_sha256": { "type": "keyword", "index": false },
|
||||
"text_sha256": { "type": "keyword", "index": false }
|
||||
|
||||
@@ -15,7 +15,9 @@ import urllib.request
|
||||
from pathlib import Path
|
||||
from typing import Iterator
|
||||
|
||||
APP_VERSION = "0.5.0"
|
||||
from search.catalog import authority_codes, legal_force_code, source_code
|
||||
|
||||
APP_VERSION = "0.13.4"
|
||||
LANGUAGES = {"ru", "ky"}
|
||||
DEFAULT_MAPPING = Path(__file__).with_name("minjust-fragments-index.json")
|
||||
|
||||
@@ -42,7 +44,7 @@ def paths(document: dict, field: str, language: str) -> list[str]:
|
||||
return [" > ".join(item[language]) for item in document.get(field, []) if item.get(language)]
|
||||
|
||||
|
||||
def search_document(document: dict, fragment: dict, expected: tuple[str, str, str, int]) -> dict:
|
||||
def search_document(document: dict, fragment: dict, expected: tuple[str, str, str, int], current_edition: str) -> dict:
|
||||
document_code, edition_code, language, position = expected
|
||||
fragment_id = f"document:{document_code}:edition:{edition_code}:lang:{language}:fragment:{position}"
|
||||
required = ("id", "document_code", "edition_code", "language", "position", "type", "text", "text_sha256", "source_path", "source_sha256")
|
||||
@@ -64,6 +66,7 @@ def search_document(document: dict, fragment: dict, expected: tuple[str, str, st
|
||||
"schema_version": document["schema_version"],
|
||||
"document_code": document_code,
|
||||
"edition_code": edition_code,
|
||||
"is_current_edition": edition_code == current_edition,
|
||||
"language": language,
|
||||
"position": position,
|
||||
"fragment_type": fragment["type"],
|
||||
@@ -72,12 +75,16 @@ def search_document(document: dict, fragment: dict, expected: tuple[str, str, st
|
||||
"document_name_ky": localized(document.get("name"), "ky"),
|
||||
"document_type_ru": localized(document.get("type"), "ru"),
|
||||
"document_type_ky": localized(document.get("type"), "ky"),
|
||||
"document_type_code": source_code("document_type", document.get("type")),
|
||||
"legal_force_code": legal_force_code(document.get("type")),
|
||||
"status_ru": localized(document.get("status"), "ru"),
|
||||
"status_ky": localized(document.get("status"), "ky"),
|
||||
"status_code": source_code("status", document.get("status")),
|
||||
"number": document.get("number"),
|
||||
"date_adopted": dates.get("DateAdopted"),
|
||||
"authority_paths_ru": paths(document, "authority_paths", "ru"),
|
||||
"authority_paths_ky": paths(document, "authority_paths", "ky"),
|
||||
"authority_codes": authority_codes(document.get("authority_paths", [])),
|
||||
"source_path": fragment["source_path"],
|
||||
"source_sha256": fragment["source_sha256"],
|
||||
"text_sha256": fragment["text_sha256"],
|
||||
@@ -118,13 +125,23 @@ def bulk_pairs(
|
||||
document = read_json(directory / "document.json")
|
||||
if document.get("source_code") != directory.name:
|
||||
raise ValueError(f"Document identity does not match its path: {directory}")
|
||||
edition_root = directory / "editions"
|
||||
editions = [path.name for path in edition_root.iterdir() if path.is_dir()] if edition_root.is_dir() else []
|
||||
if not editions:
|
||||
continue
|
||||
official_editions = document.get("editions") or []
|
||||
current_edition = (
|
||||
str(official_editions[-1]["source_code"])
|
||||
if official_editions
|
||||
else max(editions, key=lambda value: (not value.isdigit(), int(value) if value.isdigit() else value))
|
||||
)
|
||||
for fragment_path in sorted(directory.glob("editions/*/*/fragments.json")):
|
||||
edition_code, language = fragment_path.parts[-3:-1]
|
||||
values = read_json(fragment_path)
|
||||
if not isinstance(values, list):
|
||||
raise ValueError(f"Fragments must be a list: {fragment_path}")
|
||||
for position, fragment in enumerate(values, 1):
|
||||
source = search_document(document, fragment, (directory.name, edition_code, language, position))
|
||||
source = search_document(document, fragment, (directory.name, edition_code, language, position), current_edition)
|
||||
action = json.dumps({"index": {"_index": index, "_id": fragment["id"]}}, ensure_ascii=False, allow_nan=False)
|
||||
body = json.dumps(source, ensure_ascii=False, allow_nan=False)
|
||||
yield directory.name, f"{action}\n{body}\n".encode()
|
||||
@@ -246,6 +263,7 @@ def checkpoint_state(
|
||||
cluster_uuid: str,
|
||||
index_uuid: str,
|
||||
limit: int | None,
|
||||
alias: str | None,
|
||||
) -> tuple[dict, str | None]:
|
||||
source = input_root.resolve()
|
||||
destination = checkpoint.resolve()
|
||||
@@ -254,7 +272,7 @@ def checkpoint_state(
|
||||
manifest_sha256 = file_sha256(input_root / "manifest.sqlite3")
|
||||
if not resume:
|
||||
return {
|
||||
"schema_version": 1,
|
||||
"schema_version": 2,
|
||||
"url": url,
|
||||
"cluster_uuid": cluster_uuid,
|
||||
"index": index,
|
||||
@@ -262,6 +280,7 @@ def checkpoint_state(
|
||||
"input": str(source),
|
||||
"manifest_sha256": manifest_sha256,
|
||||
"limit": limit,
|
||||
"alias": alias,
|
||||
"last_document_code": None,
|
||||
"complete": False,
|
||||
}, None
|
||||
@@ -276,13 +295,22 @@ def checkpoint_state(
|
||||
"input",
|
||||
"manifest_sha256",
|
||||
"limit",
|
||||
"alias",
|
||||
"last_document_code",
|
||||
"complete",
|
||||
}
|
||||
if not isinstance(state, dict) or set(state) != expected:
|
||||
legacy_expected = expected - {"alias"}
|
||||
if not isinstance(state, dict):
|
||||
raise ValueError(f"Invalid checkpoint: {checkpoint}")
|
||||
if set(state) == legacy_expected:
|
||||
if state["schema_version"] != 1 or alias is not None:
|
||||
raise ValueError(f"Legacy checkpoint does not support --alias: {checkpoint}")
|
||||
state["schema_version"] = 2
|
||||
state["alias"] = None
|
||||
elif set(state) != expected:
|
||||
raise ValueError(f"Invalid checkpoint: {checkpoint}")
|
||||
if (
|
||||
state["schema_version"] != 1
|
||||
state["schema_version"] != 2
|
||||
or state["url"] != url
|
||||
or state["cluster_uuid"] != cluster_uuid
|
||||
or state["index"] != index
|
||||
@@ -292,6 +320,8 @@ def checkpoint_state(
|
||||
raise ValueError(f"Checkpoint does not match this load: {checkpoint}")
|
||||
if state["limit"] != limit:
|
||||
raise ValueError(f"Checkpoint limit does not match --limit: {checkpoint}")
|
||||
if state["alias"] != alias:
|
||||
raise ValueError(f"Checkpoint alias does not match --alias: {checkpoint}")
|
||||
if state["manifest_sha256"] != manifest_sha256:
|
||||
raise ValueError("Normalized manifest changed; create a new versioned index")
|
||||
if state["complete"] is not False:
|
||||
@@ -311,8 +341,18 @@ def load_bulk(
|
||||
limit: int | None = None,
|
||||
resume: bool = False,
|
||||
checkpoint: Path = Path("data/opensearch/minjust-fragments.checkpoint.json"),
|
||||
alias: str | None = None,
|
||||
expected_old_index: str | None = None,
|
||||
canary_ru: str | None = None,
|
||||
canary_ky: str | None = None,
|
||||
) -> tuple[int, int]:
|
||||
base = url.rstrip("/")
|
||||
if alias is not None and (not alias or alias == index):
|
||||
raise ValueError("--alias must differ from --index")
|
||||
if alias is not None and (not expected_old_index or expected_old_index == index):
|
||||
raise ValueError("alias publication requires an exact --expected-old-index")
|
||||
if alias is not None and (not canary_ru or not canary_ky):
|
||||
raise ValueError("alias publication requires both Russian and Kyrgyz canary queries")
|
||||
index_url = f"{base}/{urllib.parse.quote(index, safe='')}"
|
||||
if resume:
|
||||
cluster_uuid, index_uuid = opensearch_identity(base, index, index_url)
|
||||
@@ -328,8 +368,10 @@ def load_bulk(
|
||||
cluster_uuid,
|
||||
index_uuid,
|
||||
limit,
|
||||
alias,
|
||||
)
|
||||
documents = document_count(input_root, limit, start_at)
|
||||
expected_fragments = sum(1 for _ in bulk_pairs(input_root, index, limit)) if alias else None
|
||||
if not resume:
|
||||
write_json_atomic(checkpoint, state)
|
||||
fragments = 0
|
||||
@@ -363,11 +405,104 @@ def load_bulk(
|
||||
state["last_document_code"] = last_code
|
||||
write_json_atomic(checkpoint, state)
|
||||
print(f"checkpoint={last_code} fragments={fragments}", flush=True)
|
||||
if alias:
|
||||
if not expected_fragments:
|
||||
raise ValueError("refusing to publish an index with an empty expected fragment inventory")
|
||||
validate_candidate_index(base, index, expected_fragments, canary_ru, canary_ky)
|
||||
switch_alias(base, index, alias, expected_old_index)
|
||||
state["complete"] = True
|
||||
write_json_atomic(checkpoint, state)
|
||||
return documents, fragments
|
||||
|
||||
|
||||
def alias_target(base: str, alias: str) -> str:
|
||||
alias_url = f"{base.rstrip('/')}/_alias/{urllib.parse.quote(alias, safe='')}"
|
||||
try:
|
||||
result = request_json(alias_url, "GET", None, "application/json")
|
||||
except RuntimeError as error:
|
||||
if "failed with HTTP 404:" in str(error):
|
||||
raise ValueError(f"alias {alias} has no current target; explicit bootstrap is required") from error
|
||||
raise
|
||||
if not isinstance(result, dict) or len(result) != 1:
|
||||
raise ValueError(f"alias {alias} must point to exactly one index")
|
||||
target, definition = next(iter(result.items()))
|
||||
if not isinstance(definition, dict) or alias not in definition.get("aliases", {}):
|
||||
raise ValueError(f"alias {alias} response is malformed")
|
||||
return target
|
||||
|
||||
|
||||
def validate_candidate_index(
|
||||
base: str, index: str, expected_fragments: int, canary_ru: str, canary_ky: str
|
||||
) -> None:
|
||||
if expected_fragments <= 0:
|
||||
raise ValueError("expected fragment count must be positive")
|
||||
encoded_index = urllib.parse.quote(index, safe='')
|
||||
refreshed = request_json(f"{base.rstrip('/')}/{encoded_index}/_refresh", "POST", None, "application/json")
|
||||
shards = refreshed.get("_shards", {})
|
||||
if not isinstance(shards, dict) or shards.get("failed") != 0:
|
||||
raise RuntimeError(f"refresh failed for candidate index {index}")
|
||||
count_result = request_json(f"{base.rstrip('/')}/{encoded_index}/_count", "GET", None, "application/json")
|
||||
if count_result.get("count") != expected_fragments:
|
||||
raise RuntimeError(
|
||||
f"candidate index {index} has {count_result.get('count')} fragments; expected {expected_fragments}"
|
||||
)
|
||||
for language, query in (("ru", canary_ru), ("ky", canary_ky)):
|
||||
payload = json.dumps({"size": 1, "query": {"match": {f"text_{language}": query}}}).encode()
|
||||
result = request_json(
|
||||
f"{base.rstrip('/')}/{encoded_index}/_search", "POST", payload, "application/json"
|
||||
)
|
||||
hits = result.get("hits", {}).get("hits", [])
|
||||
if not hits or not isinstance(hits[0].get("_source", {}).get(f"text_{language}"), str):
|
||||
raise RuntimeError(f"candidate index {index} failed the {language} canary query")
|
||||
|
||||
|
||||
def switch_alias(base: str, index: str, alias: str, expected_old_index: str) -> None:
|
||||
if not alias or alias == index:
|
||||
raise ValueError("--alias must differ from --index")
|
||||
if not expected_old_index or expected_old_index == index:
|
||||
raise ValueError("--expected-old-index must name the exact previous index")
|
||||
actual_old_index = alias_target(base, alias)
|
||||
if actual_old_index == index:
|
||||
return
|
||||
if actual_old_index != expected_old_index:
|
||||
raise ValueError(
|
||||
f"alias {alias} currently targets {actual_old_index}, expected {expected_old_index}; refusing cutover"
|
||||
)
|
||||
try:
|
||||
result = request_json(
|
||||
f"{base.rstrip('/')}/_aliases",
|
||||
"POST",
|
||||
json.dumps({
|
||||
"actions": [
|
||||
{"remove": {"index": expected_old_index, "alias": alias, "must_exist": True}},
|
||||
{"add": {"index": index, "alias": alias}},
|
||||
]
|
||||
}).encode(),
|
||||
"application/json",
|
||||
)
|
||||
except Exception as error:
|
||||
try:
|
||||
current = alias_target(base, alias)
|
||||
except Exception:
|
||||
raise RuntimeError(f"alias switch outcome is unknown; inspect {alias} before resuming") from error
|
||||
if current == index:
|
||||
return
|
||||
if current != expected_old_index:
|
||||
raise ValueError(
|
||||
f"alias {alias} now targets unexpected index {current}; refusing to retry publication"
|
||||
) from error
|
||||
raise RuntimeError(f"alias switch failed; {alias} still targets {expected_old_index}") from error
|
||||
if not isinstance(result, dict) or result.get("acknowledged") is not True:
|
||||
current = alias_target(base, alias)
|
||||
if current == index:
|
||||
return
|
||||
if current != expected_old_index:
|
||||
raise ValueError(
|
||||
f"alias {alias} now targets unexpected index {current}; refusing to retry publication"
|
||||
)
|
||||
raise RuntimeError(f"OpenSearch did not acknowledge alias switch: {alias}")
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("--input", type=Path, default=Path("data/minjust-normalized"))
|
||||
@@ -375,6 +510,10 @@ def main() -> int:
|
||||
parser.add_argument("--index", default="akyldash-fragments-v1")
|
||||
parser.add_argument("--limit", type=int)
|
||||
parser.add_argument("--url", help="create the index and stream bounded Bulk requests instead of writing a file")
|
||||
parser.add_argument("--alias", help="atomically point this alias at --index after a successful load")
|
||||
parser.add_argument("--expected-old-index", help="exact current alias target required for guarded cutover")
|
||||
parser.add_argument("--canary-ru", help="approved Russian query that must match the candidate index")
|
||||
parser.add_argument("--canary-ky", help="approved Kyrgyz query that must match the candidate index")
|
||||
parser.add_argument("--mapping", type=Path, default=DEFAULT_MAPPING)
|
||||
parser.add_argument("--batch-mb", type=int, default=25)
|
||||
parser.add_argument("--resume", action="store_true", help="load into an existing index")
|
||||
@@ -389,6 +528,10 @@ def main() -> int:
|
||||
raise SystemExit("--resume requires --url")
|
||||
if arguments.checkpoint and not arguments.url:
|
||||
raise SystemExit("--checkpoint requires --url")
|
||||
if arguments.alias == "":
|
||||
raise SystemExit("--alias must not be empty")
|
||||
if arguments.alias is not None and not arguments.url:
|
||||
raise SystemExit("--alias requires --url")
|
||||
if arguments.url:
|
||||
checkpoint = arguments.checkpoint or Path("data/opensearch") / f"{arguments.index}.checkpoint.json"
|
||||
documents, fragments = load_bulk(
|
||||
@@ -400,12 +543,16 @@ def main() -> int:
|
||||
arguments.limit,
|
||||
arguments.resume,
|
||||
checkpoint,
|
||||
arguments.alias,
|
||||
arguments.expected_old_index,
|
||||
arguments.canary_ru,
|
||||
arguments.canary_ky,
|
||||
)
|
||||
destination = arguments.url
|
||||
else:
|
||||
documents, fragments = export_bulk(arguments.input, arguments.output, arguments.index, arguments.limit)
|
||||
destination = arguments.output
|
||||
print(f"documents={documents} fragments={fragments} destination={destination}\nAkyldash Backend v{APP_VERSION} · Frontend — not created")
|
||||
print(f"documents={documents} fragments={fragments} destination={destination}\nAkyldash · Backend v{APP_VERSION} · Frontend v0.3.4")
|
||||
return 0
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,243 @@
|
||||
"""Run document searches against the local OpenSearch index."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import re
|
||||
import urllib.parse
|
||||
|
||||
from search.minjust_opensearch import APP_VERSION, request_json
|
||||
|
||||
|
||||
LEGAL_FORM_ALIASES = {
|
||||
"ru": {
|
||||
"осоо": ("ооо", "общество с ограниченной ответственностью"),
|
||||
"ооо": ("осоо", "общество с ограниченной ответственностью"),
|
||||
"общество с ограниченной ответственностью": ("осоо", "ооо"),
|
||||
"общества с ограниченной ответственностью": ("осоо", "ооо"),
|
||||
},
|
||||
"ky": {
|
||||
"жчк": ("жоопкерчилиги чектелген коом",),
|
||||
"жоопкерчилиги чектелген коом": ("жчк",),
|
||||
},
|
||||
}
|
||||
# The indexed Civil Code uses the legal term "имущественный наем" for a
|
||||
# договор аренды. Keep this exact legal phrase expansion narrow: it must not
|
||||
# rewrite residential hiring, employment, sublease, or leasing queries.
|
||||
LEASE_TERM_ALIAS = re.compile(
|
||||
r"(?<!\w)(договор(?:а|у|ом|е)?)[ \t]+аренд(?:а|ы|е|у|ой|ою)(?!\w)",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
LEASE_TERM_ALIAS_EXCLUSIONS = re.compile(
|
||||
r"\b(?:квартир\w*|жил\w*|дом\w*|помещен\w*|земл\w*|участк\w*|"
|
||||
r"поднайм\w*|подна[её]м\w*|субаренд\w*|лизинг\w*|труд\w*|работник\w*)\b",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
LEASE_TERM_PHRASE_BOOST = 12
|
||||
COMPANY_REGISTRATION_DOCUMENTS = (("230044970", 3000), ("667", 2000), ("4", 1000))
|
||||
TAX_PROFIT_DOCUMENTS = (("112340", 3000),)
|
||||
BOILERPLATE_PREFIXES = {
|
||||
"ru": (
|
||||
"как регулируется", "правовое регулирование", "судебная практика", "сроки и ответственность",
|
||||
"действующая редакция", "последние изменения", "основные положения", "комментарий к акту",
|
||||
),
|
||||
"ky": (),
|
||||
}
|
||||
ACT_TITLE_PREFIXES = {
|
||||
"ru": (
|
||||
r"(?:гражданский\s+)?процессуальный\s+кодекс(?:\s+(?:кыргызской\s+республики|кр))?",
|
||||
r"(?:гражданск\w*|уголовн\w*|налогов\w*|трудов\w*|семейн\w*)\s+кодекс\w*(?:\s+(?:кыргызской\s+республики|кр))?",
|
||||
r"кодекс\s+о\s+правонарушениях(?:\s+(?:кыргызской\s+республики|кр))?",
|
||||
r"конституци\w*(?:\s+(?:кыргызской\s+республики|кр))?",
|
||||
r"(?:гк|ук|нк|коап|гпк|упк|уик)(?:\s+(?:кыргызской\s+республики|кр))?",
|
||||
r"закон(?:\s+(?:кыргызской\s+республики|кр))?\s+о\s+(?:защит\w*\s+прав\w*\s+потребител\w*|государственн\w+\s+регистраци\w+\s+юридическ\w+\s+лиц|труд\w*)",
|
||||
),
|
||||
"ky": (
|
||||
r"кыргыз\w*\s+республикасынын\s+конституци\w*",
|
||||
r"(?:кыргыз\w*\s+республикасынын\s+)?(?:жарандык|кылмыш\w*|салык|эмгек|үй-бүлө|административдик|жарандык\s+процесстик)\s+кодекс\w*",
|
||||
r"(?:кыргыз\w*\s+республикасынын\s+)?(?:жк|үк)(?:\s+кр)?",
|
||||
),
|
||||
}
|
||||
|
||||
|
||||
def relaxed_query_text(language: str, query: str) -> str:
|
||||
value = query.strip()
|
||||
for prefix in BOILERPLATE_PREFIXES[language]:
|
||||
if value.casefold().startswith(prefix):
|
||||
value = value[len(prefix):].strip()
|
||||
break
|
||||
for pattern in ACT_TITLE_PREFIXES[language]:
|
||||
match = re.match(rf"\s*{pattern}(?=\s|$|[.,;:!?])", value, re.IGNORECASE)
|
||||
if match:
|
||||
value = value[match.end():].lstrip(" \t,;:—-")
|
||||
break
|
||||
return value
|
||||
|
||||
|
||||
def lease_term_variant(query: str) -> str | None:
|
||||
if LEASE_TERM_ALIAS.search(query) and not LEASE_TERM_ALIAS_EXCLUSIONS.search(query):
|
||||
return LEASE_TERM_ALIAS.sub(r"\1 имущественного найма", query)
|
||||
return None
|
||||
|
||||
|
||||
def query_variants(language: str, query: str) -> list[str]:
|
||||
variants = [query]
|
||||
for alias, expansions in LEGAL_FORM_ALIASES[language].items():
|
||||
pattern = re.compile(rf"(?<!\w){re.escape(alias)}(?!\w)", re.IGNORECASE)
|
||||
if pattern.search(query):
|
||||
variants.extend(pattern.sub(expansion, query) for expansion in expansions)
|
||||
if language == "ru":
|
||||
alias = lease_term_variant(query)
|
||||
if alias:
|
||||
variants.append(alias)
|
||||
return list(dict.fromkeys(variants))
|
||||
|
||||
|
||||
def document_priority_clauses(language: str, documents: tuple[tuple[str, int], ...]) -> list[dict]:
|
||||
status = {"ru": "Действует", "ky": "Күчүндө"}[language]
|
||||
return [
|
||||
{
|
||||
"constant_score": {
|
||||
"filter": {
|
||||
"bool": {
|
||||
"filter": [
|
||||
{"term": {"document_code": code}},
|
||||
{"term": {f"status_{language}": status}},
|
||||
]
|
||||
}
|
||||
},
|
||||
"boost": boost,
|
||||
}
|
||||
}
|
||||
for code, boost in documents
|
||||
]
|
||||
|
||||
|
||||
def company_registration_clauses(language: str, query: str) -> list[dict]:
|
||||
non_registration_context = {
|
||||
"ru": (r"\bсч[её]т\w*", r"\bбанк\w*", r"\bфилиал\w*", r"\bпредставительств\w*"),
|
||||
"ky": (r"\bбанк\w*", r"\bэсеп\w*", r"\bфилиал\w*", r"\bөкүлчүлүк\w*"),
|
||||
}[language]
|
||||
normalized_query = query.casefold()
|
||||
if any(re.search(pattern, normalized_query) for pattern in non_registration_context):
|
||||
return []
|
||||
|
||||
forms, patterns = {
|
||||
"ru": (
|
||||
r"(?:осоо|ооо|обществ\w*\s+с\s+ограниченной\s+ответственностью)",
|
||||
(
|
||||
r"\bкак\s+(?:откры\w*|созда\w*|зарегистр\w*)\s+{form}\b",
|
||||
r"\b(?:порядок|процедура)\s+(?:открыти\w*|создани\w*|регистраци\w*)\s+{form}\b",
|
||||
r"\b(?:государственн\w+\s+)?регистраци\w*\s+{form}\b",
|
||||
r"\bсоздани\w*\s+{form}\b",
|
||||
),
|
||||
),
|
||||
"ky": (
|
||||
r"(?:жчк|жоопкерчилиги\s+чектелген\s+коом)",
|
||||
(
|
||||
r"\bжчк\s+ач\w*\s+тартиби\b",
|
||||
r"\bжчк\s+кантип\s+ач\w*\b",
|
||||
r"\b{form}\s+(?:ачуу|ачуунун|каттоо|каттоонун)\b",
|
||||
r"\b(?:ачуу|каттоо)\s+{form}\b",
|
||||
),
|
||||
),
|
||||
}[language]
|
||||
if not any(re.search(pattern.format(form=forms), normalized_query) for pattern in patterns):
|
||||
return []
|
||||
|
||||
return document_priority_clauses(language, COMPANY_REGISTRATION_DOCUMENTS)
|
||||
|
||||
|
||||
def tax_profit_clauses(language: str, query: str) -> list[dict]:
|
||||
if language != "ru" or not re.search(r"\bналог\w*\s+(?:на\s+)?прибыл\w*\b", query.casefold()):
|
||||
return []
|
||||
# ponytail: exact topic anchor; expand only with verified tax-code sources.
|
||||
return document_priority_clauses(language, TAX_PROFIT_DOCUMENTS)
|
||||
|
||||
|
||||
def build_search_query(language: str, query: str) -> dict:
|
||||
registration_clauses = company_registration_clauses(language, query)
|
||||
intent_clauses = [*registration_clauses, *tax_profit_clauses(language, query)]
|
||||
variants = query_variants(language, query)
|
||||
full_text = [
|
||||
{
|
||||
"multi_match": {
|
||||
"query": variant,
|
||||
"fields": [f"document_name_{language}^4", f"text_{language}"],
|
||||
"type": "cross_fields",
|
||||
"operator": "OR" if registration_clauses else "AND",
|
||||
}
|
||||
}
|
||||
for variant in variants
|
||||
]
|
||||
relaxed_text = []
|
||||
if not registration_clauses:
|
||||
seen_relaxed = set()
|
||||
for variant in variants:
|
||||
value = relaxed_query_text(language, variant)
|
||||
words = value.split()
|
||||
if value in seen_relaxed or len(words) < 2 or (value == variant.strip() and len(words) < 3):
|
||||
continue
|
||||
if len(words) < 3 and not any(len(word) >= 5 for word in words):
|
||||
continue
|
||||
seen_relaxed.add(value)
|
||||
relaxed_text.append({
|
||||
"multi_match": {
|
||||
"query": value,
|
||||
"fields": [f"document_name_{language}^4", f"text_{language}"],
|
||||
"type": "cross_fields",
|
||||
"operator": "OR",
|
||||
"minimum_should_match": 2,
|
||||
"boost": 0.1,
|
||||
}
|
||||
})
|
||||
lease_variant = lease_term_variant(query) if language == "ru" else None
|
||||
phrase_matches = [
|
||||
{"match_phrase": {f"text_{language}": {
|
||||
"query": variant,
|
||||
"boost": LEASE_TERM_PHRASE_BOOST if variant == lease_variant else 3,
|
||||
}}}
|
||||
for variant in variants
|
||||
]
|
||||
planned = {"should": [*full_text, *phrase_matches, *relaxed_text, *intent_clauses], "minimum_should_match": 1}
|
||||
return {"bool": planned}
|
||||
|
||||
|
||||
def build_search_body(language: str, query: str, top_k: int) -> bytes:
|
||||
return json.dumps({
|
||||
"size": top_k,
|
||||
"track_total_hits": False,
|
||||
"_source": ["document_code"],
|
||||
"query": {"bool": {"filter": [{"term": {"language": language}}, {"term": {"is_current_edition": True}}], "must": build_search_query(language, query)}},
|
||||
"collapse": {"field": "document_code"},
|
||||
}, ensure_ascii=False).encode()
|
||||
|
||||
|
||||
def search_documents(base_url: str, index: str, language: str, query: str, top_k: int) -> list[str]:
|
||||
url = f"{base_url.rstrip('/')}/{urllib.parse.quote(index, safe='')}/_search"
|
||||
response = request_json(url, "POST", build_search_body(language, query, top_k), "application/json")
|
||||
try:
|
||||
return [hit["_source"]["document_code"] for hit in response["hits"]["hits"]]
|
||||
except (KeyError, TypeError) as error:
|
||||
raise RuntimeError("OpenSearch search response is incomplete") from error
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("query")
|
||||
parser.add_argument("--language", choices=("ru", "ky"), required=True)
|
||||
parser.add_argument("--url", default="http://127.0.0.1:9200")
|
||||
parser.add_argument("--index", default="akyldash-fragments-v1")
|
||||
parser.add_argument("--top-k", type=int, default=10)
|
||||
parser.add_argument("--version", action="version", version=APP_VERSION)
|
||||
arguments = parser.parse_args()
|
||||
if arguments.top_k <= 0:
|
||||
raise SystemExit("--top-k must be greater than zero")
|
||||
print(json.dumps(search_documents(arguments.url, arguments.index, arguments.language, arguments.query, arguments.top_k), ensure_ascii=False))
|
||||
print(f"Akyldash · Backend v{APP_VERSION} · Frontend v0.3.4")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
@@ -0,0 +1,83 @@
|
||||
"""Persistence and signed snapshots for search relevance reviews."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import base64
|
||||
import hashlib
|
||||
import hmac
|
||||
import json
|
||||
import secrets
|
||||
import sqlite3
|
||||
import threading
|
||||
import time
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
MAX_COMMENT = 4000
|
||||
MAX_REVIEWER = 120
|
||||
|
||||
|
||||
class ReviewStore:
|
||||
def __init__(self, path: Path | str = ":memory:"):
|
||||
if path != ":memory:":
|
||||
Path(path).parent.mkdir(parents=True, exist_ok=True)
|
||||
self.connection = sqlite3.connect(path, check_same_thread=False)
|
||||
self.connection.row_factory = sqlite3.Row
|
||||
# ponytail: one SQLite lock; split connections only if review throughput matters.
|
||||
self._lock = threading.Lock()
|
||||
self.connection.execute("""
|
||||
CREATE TABLE IF NOT EXISTS search_reviews (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
created_at TEXT NOT NULL,
|
||||
reviewer TEXT NOT NULL,
|
||||
query TEXT NOT NULL,
|
||||
language TEXT NOT NULL,
|
||||
index_name TEXT NOT NULL,
|
||||
algorithm_version TEXT NOT NULL,
|
||||
top_result_code TEXT,
|
||||
results_json TEXT NOT NULL,
|
||||
overall_comment TEXT NOT NULL
|
||||
)
|
||||
""")
|
||||
self.connection.commit()
|
||||
|
||||
def save(self, review: dict) -> int:
|
||||
with self._lock:
|
||||
cursor = self.connection.execute(
|
||||
"INSERT INTO search_reviews(created_at, reviewer, query, language, index_name, algorithm_version, top_result_code, results_json, overall_comment) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?)",
|
||||
(review["created_at"], review["reviewer"], review["query"], review["language"], review["index_name"], review["algorithm_version"], review["top_result_code"], json.dumps(review["results"], ensure_ascii=False), review["overall_comment"]),
|
||||
)
|
||||
self.connection.commit()
|
||||
return int(cursor.lastrowid)
|
||||
|
||||
def export(self) -> list[dict]:
|
||||
with self._lock:
|
||||
return [
|
||||
{**dict(row), "results": json.loads(row["results_json"])}
|
||||
for row in self.connection.execute("SELECT * FROM search_reviews ORDER BY id")
|
||||
]
|
||||
|
||||
|
||||
class ReviewSnapshots:
|
||||
def __init__(self, secret: bytes | None = None, ttl: int = 3600):
|
||||
self.secret = secret or secrets.token_bytes(32)
|
||||
self.ttl = ttl
|
||||
|
||||
def create(self, query: str, language: str, index: str, results: list[dict], algorithm_version: str) -> str:
|
||||
payload = {"query": query, "language": language, "index_name": index, "algorithm_version": algorithm_version, "results": results, "expires_at": int(time.time()) + self.ttl}
|
||||
encoded = base64.urlsafe_b64encode(json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode()).decode().rstrip("=")
|
||||
signature = hmac.new(self.secret, encoded.encode(), hashlib.sha256).hexdigest()
|
||||
return f"{encoded}.{signature}"
|
||||
|
||||
def verify(self, token: str) -> dict:
|
||||
try:
|
||||
encoded, signature = token.split(".", 1)
|
||||
expected = hmac.new(self.secret, encoded.encode(), hashlib.sha256).hexdigest()
|
||||
if not hmac.compare_digest(signature, expected):
|
||||
raise ValueError
|
||||
payload = json.loads(base64.urlsafe_b64decode(encoded + "=" * (-len(encoded) % 4)))
|
||||
if payload["expires_at"] < int(time.time()):
|
||||
raise ValueError
|
||||
return payload
|
||||
except (ValueError, KeyError, TypeError, json.JSONDecodeError, UnicodeError) as error:
|
||||
raise ValueError("invalid or expired search snapshot") from error
|
||||
|
After Width: | Height: | Size: 1.4 KiB |
@@ -0,0 +1,4 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48">
|
||||
<circle cx="24" cy="24" r="20" fill="#F7F2E8" stroke="#9D2633" stroke-width="3"/>
|
||||
<path d="M24 5v38M5 24h38M11 11l26 26M37 11 11 37" fill="none" stroke="#9D2633" stroke-width="3" stroke-linecap="round"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 276 B |
@@ -0,0 +1,93 @@
|
||||
Copyright 2022 The Noto Project Authors (https://github.com/notofonts/latin-greek-cyrillic) NotoSans-Italic[wdth,wght].ttf: Copyright 2022 The Noto Project Authors (https://github.com/notofonts/latin-greek-cyrillic)
|
||||
|
||||
This Font Software is licensed under the SIL Open Font License, Version 1.1.
|
||||
This license is copied below, and is also available with a FAQ at:
|
||||
http://scripts.sil.org/OFL
|
||||
|
||||
|
||||
-----------------------------------------------------------
|
||||
SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
|
||||
-----------------------------------------------------------
|
||||
|
||||
PREAMBLE
|
||||
The goals of the Open Font License (OFL) are to stimulate worldwide
|
||||
development of collaborative font projects, to support the font creation
|
||||
efforts of academic and linguistic communities, and to provide a free and
|
||||
open framework in which fonts may be shared and improved in partnership
|
||||
with others.
|
||||
|
||||
The OFL allows the licensed fonts to be used, studied, modified and
|
||||
redistributed freely as long as they are not sold by themselves. The
|
||||
fonts, including any derivative works, can be bundled, embedded,
|
||||
redistributed and/or sold with any software provided that any reserved
|
||||
names are not used by derivative works. The fonts and derivatives,
|
||||
however, cannot be released under any other type of license. The
|
||||
requirement for fonts to remain under this license does not apply
|
||||
to any document created using the fonts or their derivatives.
|
||||
|
||||
DEFINITIONS
|
||||
"Font Software" refers to the set of files released by the Copyright
|
||||
Holder(s) under this license and clearly marked as such. This may
|
||||
include source files, build scripts and documentation.
|
||||
|
||||
"Reserved Font Name" refers to any names specified as such after the
|
||||
copyright statement(s).
|
||||
|
||||
"Original Version" refers to the collection of Font Software components as
|
||||
distributed by the Copyright Holder(s).
|
||||
|
||||
"Modified Version" refers to any derivative made by adding to, deleting,
|
||||
or substituting -- in part or in whole -- any of the components of the
|
||||
Original Version, by changing formats or by porting the Font Software to a
|
||||
new environment.
|
||||
|
||||
"Author" refers to any designer, engineer, programmer, technical
|
||||
writer or other person who contributed to the Font Software.
|
||||
|
||||
PERMISSION & CONDITIONS
|
||||
Permission is hereby granted, free of charge, to any person obtaining
|
||||
a copy of the Font Software, to use, study, copy, merge, embed, modify,
|
||||
redistribute, and sell modified and unmodified copies of the Font
|
||||
Software, subject to the following conditions:
|
||||
|
||||
1) Neither the Font Software nor any of its individual components,
|
||||
in Original or Modified Versions, may be sold by itself.
|
||||
|
||||
2) Original or Modified Versions of the Font Software may be bundled,
|
||||
redistributed and/or sold with any software, provided that each copy
|
||||
contains the above copyright notice and this license. These can be
|
||||
included either as stand-alone text files, human-readable headers or
|
||||
in the appropriate machine-readable metadata fields within text or
|
||||
binary files as long as those fields can be easily viewed by the user.
|
||||
|
||||
3) No Modified Version of the Font Software may use the Reserved Font
|
||||
Name(s) unless explicit written permission is granted by the corresponding
|
||||
Copyright Holder. This restriction only applies to the primary font name as
|
||||
presented to the users.
|
||||
|
||||
4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
|
||||
Software shall not be used to promote, endorse or advertise any
|
||||
Modified Version, except to acknowledge the contribution(s) of the
|
||||
Copyright Holder(s) and the Author(s) or with their explicit written
|
||||
permission.
|
||||
|
||||
5) The Font Software, modified or unmodified, in part or in whole,
|
||||
must be distributed entirely under this license, and must not be
|
||||
distributed under any other license. The requirement for fonts to
|
||||
remain under this license does not apply to any document created
|
||||
using the Font Software.
|
||||
|
||||
TERMINATION
|
||||
This license becomes null and void if any of the above conditions are
|
||||
not met.
|
||||
|
||||
DISCLAIMER
|
||||
THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
|
||||
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
|
||||
OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
|
||||
COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
|
||||
INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
|
||||
DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
||||
FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
|
||||
OTHER DEALINGS IN THE FONT SOFTWARE.
|
||||
@@ -0,0 +1,93 @@
|
||||
Copyright 2022 The Noto Project Authors (https://github.com/notofonts/latin-greek-cyrillic) NotoSerif-Italic[wdth,wght].ttf: Copyright 2022 The Noto Project Authors (https://github.com/notofonts/latin-greek-cyrillic)
|
||||
|
||||
This Font Software is licensed under the SIL Open Font License, Version 1.1.
|
||||
This license is copied below, and is also available with a FAQ at:
|
||||
http://scripts.sil.org/OFL
|
||||
|
||||
|
||||
-----------------------------------------------------------
|
||||
SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
|
||||
-----------------------------------------------------------
|
||||
|
||||
PREAMBLE
|
||||
The goals of the Open Font License (OFL) are to stimulate worldwide
|
||||
development of collaborative font projects, to support the font creation
|
||||
efforts of academic and linguistic communities, and to provide a free and
|
||||
open framework in which fonts may be shared and improved in partnership
|
||||
with others.
|
||||
|
||||
The OFL allows the licensed fonts to be used, studied, modified and
|
||||
redistributed freely as long as they are not sold by themselves. The
|
||||
fonts, including any derivative works, can be bundled, embedded,
|
||||
redistributed and/or sold with any software provided that any reserved
|
||||
names are not used by derivative works. The fonts and derivatives,
|
||||
however, cannot be released under any other type of license. The
|
||||
requirement for fonts to remain under this license does not apply
|
||||
to any document created using the fonts or their derivatives.
|
||||
|
||||
DEFINITIONS
|
||||
"Font Software" refers to the set of files released by the Copyright
|
||||
Holder(s) under this license and clearly marked as such. This may
|
||||
include source files, build scripts and documentation.
|
||||
|
||||
"Reserved Font Name" refers to any names specified as such after the
|
||||
copyright statement(s).
|
||||
|
||||
"Original Version" refers to the collection of Font Software components as
|
||||
distributed by the Copyright Holder(s).
|
||||
|
||||
"Modified Version" refers to any derivative made by adding to, deleting,
|
||||
or substituting -- in part or in whole -- any of the components of the
|
||||
Original Version, by changing formats or by porting the Font Software to a
|
||||
new environment.
|
||||
|
||||
"Author" refers to any designer, engineer, programmer, technical
|
||||
writer or other person who contributed to the Font Software.
|
||||
|
||||
PERMISSION & CONDITIONS
|
||||
Permission is hereby granted, free of charge, to any person obtaining
|
||||
a copy of the Font Software, to use, study, copy, merge, embed, modify,
|
||||
redistribute, and sell modified and unmodified copies of the Font
|
||||
Software, subject to the following conditions:
|
||||
|
||||
1) Neither the Font Software nor any of its individual components,
|
||||
in Original or Modified Versions, may be sold by itself.
|
||||
|
||||
2) Original or Modified Versions of the Font Software may be bundled,
|
||||
redistributed and/or sold with any software, provided that each copy
|
||||
contains the above copyright notice and this license. These can be
|
||||
included either as stand-alone text files, human-readable headers or
|
||||
in the appropriate machine-readable metadata fields within text or
|
||||
binary files as long as those fields can be easily viewed by the user.
|
||||
|
||||
3) No Modified Version of the Font Software may use the Reserved Font
|
||||
Name(s) unless explicit written permission is granted by the corresponding
|
||||
Copyright Holder. This restriction only applies to the primary font name as
|
||||
presented to the users.
|
||||
|
||||
4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
|
||||
Software shall not be used to promote, endorse or advertise any
|
||||
Modified Version, except to acknowledge the contribution(s) of the
|
||||
Copyright Holder(s) and the Author(s) or with their explicit written
|
||||
permission.
|
||||
|
||||
5) The Font Software, modified or unmodified, in part or in whole,
|
||||
must be distributed entirely under this license, and must not be
|
||||
distributed under any other license. The requirement for fonts to
|
||||
remain under this license does not apply to any document created
|
||||
using the Font Software.
|
||||
|
||||
TERMINATION
|
||||
This license becomes null and void if any of the above conditions are
|
||||
not met.
|
||||
|
||||
DISCLAIMER
|
||||
THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
|
||||
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
|
||||
OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
|
||||
COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
|
||||
INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
|
||||
DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
||||
FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
|
||||
OTHER DEALINGS IN THE FONT SOFTWARE.
|
||||
@@ -0,0 +1,405 @@
|
||||
import json
|
||||
import os
|
||||
import sqlite3
|
||||
import tempfile
|
||||
import unittest
|
||||
import urllib.error
|
||||
from email.message import Message
|
||||
from pathlib import Path
|
||||
from unittest.mock import Mock, patch
|
||||
|
||||
from ingestion import minjust_current
|
||||
from ingestion.minjust_current import (
|
||||
ApiResponse,
|
||||
CurrentCbdClient,
|
||||
SourceChanged,
|
||||
SourceError,
|
||||
stage_document,
|
||||
)
|
||||
|
||||
|
||||
def api_response(value):
|
||||
body = json.dumps(value, ensure_ascii=False).encode()
|
||||
import hashlib
|
||||
|
||||
return ApiResponse(value, body, hashlib.sha256(body).hexdigest())
|
||||
|
||||
|
||||
def document_record(alias="6", canonical=6, editions=None):
|
||||
return api_response(
|
||||
{
|
||||
"documentCode": canonical,
|
||||
"nameRus": "Закон",
|
||||
"nameKyr": "Мыйзам",
|
||||
"headerRu": "Заголовок",
|
||||
"headerKg": "Баш сөз",
|
||||
"number": 114,
|
||||
"dateAdopted": "1998-08-04",
|
||||
"classId": 1,
|
||||
"refTypeId": 10,
|
||||
"status": 1,
|
||||
"editions": editions if editions is not None else [
|
||||
{"id": 920492, "nameRus": "Редакция A", "nameKyr": "Редакция A", "textRusType": "docx", "textKyrType": "docx"},
|
||||
{"id": 920292, "nameRus": "Редакция B", "nameKyr": "Редакция B", "textRusType": "docx", "textKyrType": "docx"},
|
||||
],
|
||||
}
|
||||
)
|
||||
|
||||
|
||||
class CurrentCbdClientTests(unittest.TestCase):
|
||||
def test_rejects_legacy_roots_when_called_from_an_unrelated_working_directory(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
base = Path(temporary)
|
||||
repository = base / "repository"
|
||||
elsewhere = base / "elsewhere"
|
||||
elsewhere.mkdir()
|
||||
legacy_roots = [
|
||||
repository / "data/minjust-cbd",
|
||||
repository / "data/minjust-normalized",
|
||||
]
|
||||
for legacy in legacy_roots:
|
||||
legacy.mkdir(parents=True)
|
||||
# Root CI uses umask 000, so make the trusted fixture's parent permissions explicit.
|
||||
for directory in (repository, repository / "data", *legacy_roots):
|
||||
directory.chmod(0o755)
|
||||
original_cwd = Path.cwd()
|
||||
client = Mock()
|
||||
try:
|
||||
os.chdir(elsewhere)
|
||||
with patch.object(minjust_current, "REPOSITORY_ROOT", repository):
|
||||
for legacy in legacy_roots:
|
||||
with self.subTest(legacy=legacy), self.assertRaisesRegex(ValueError, "must not overlap"):
|
||||
stage_document(legacy / "staging", "6", client)
|
||||
self.assertFalse((legacy / "staging").exists())
|
||||
finally:
|
||||
os.chdir(original_cwd)
|
||||
client.document.assert_not_called()
|
||||
|
||||
def test_requires_private_owned_staging_root(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
output = Path(temporary) / "shared"
|
||||
output.mkdir(mode=0o755)
|
||||
output.chmod(0o755)
|
||||
|
||||
with self.assertRaisesRegex(ValueError, "private directory"):
|
||||
stage_document(output, "6", Mock())
|
||||
|
||||
def test_resume_rejects_symlinked_checkpoints_and_document_paths(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
base = Path(temporary)
|
||||
targets = [
|
||||
("request-contract.json", False),
|
||||
("current-api.sqlite3", False),
|
||||
("manifest.sqlite3", False),
|
||||
(".work/documents/6", True),
|
||||
(".work/documents/6/editions/920492/ru.html", False),
|
||||
("documents/6", True),
|
||||
]
|
||||
client = Mock()
|
||||
for index, (relative, directory) in enumerate(targets):
|
||||
with self.subTest(relative=relative):
|
||||
output = base / f"generation-{index}"
|
||||
output.mkdir(mode=0o700)
|
||||
contract = output / "request-contract.json"
|
||||
if relative != "request-contract.json":
|
||||
contract.write_text(json.dumps(minjust_current.REQUEST_CONTRACT), encoding="utf-8")
|
||||
outside = base / f"outside-{index}"
|
||||
if directory:
|
||||
outside.mkdir()
|
||||
else:
|
||||
outside.write_text("preserve", encoding="utf-8")
|
||||
link = output / relative
|
||||
link.parent.mkdir(parents=True, exist_ok=True)
|
||||
try:
|
||||
link.symlink_to(outside, target_is_directory=directory)
|
||||
except (NotImplementedError, OSError):
|
||||
self.skipTest("symlinks are unavailable")
|
||||
|
||||
with self.assertRaisesRegex(ValueError, "symbolic link"):
|
||||
stage_document(output, "6", client, resume=True)
|
||||
|
||||
client.document.assert_not_called()
|
||||
if not directory:
|
||||
self.assertEqual(outside.read_text(encoding="utf-8"), "preserve")
|
||||
else:
|
||||
self.assertEqual(list(outside.iterdir()), [])
|
||||
|
||||
def test_respects_retry_after_and_retries_server_errors(self):
|
||||
headers = Message()
|
||||
headers["Retry-After"] = "7"
|
||||
response = Mock()
|
||||
response.read.return_value = b"{}"
|
||||
response.__enter__ = Mock(return_value=response)
|
||||
response.__exit__ = Mock(return_value=False)
|
||||
opener = Mock(side_effect=[
|
||||
urllib.error.HTTPError("https://example.test", 429, "", headers, None),
|
||||
urllib.error.HTTPError("https://example.test", 503, "", Message(), None),
|
||||
response,
|
||||
])
|
||||
delays = []
|
||||
|
||||
CurrentCbdClient(opener=opener, sleep=delays.append, clock=lambda: 0, retries=3).request_json("/GetEdition")
|
||||
|
||||
self.assertIn(7.0, delays)
|
||||
self.assertIn(2, delays)
|
||||
self.assertEqual(opener.call_count, 3)
|
||||
|
||||
def test_enforces_request_interval(self):
|
||||
now = [0.0]
|
||||
starts = []
|
||||
response = Mock()
|
||||
response.read.return_value = b"{}"
|
||||
response.__enter__ = Mock(return_value=response)
|
||||
response.__exit__ = Mock(return_value=False)
|
||||
|
||||
def opener(_request, timeout):
|
||||
starts.append(now[0])
|
||||
return response
|
||||
|
||||
client = CurrentCbdClient(
|
||||
opener=opener,
|
||||
clock=lambda: now[0],
|
||||
sleep=lambda delay: now.__setitem__(0, now[0] + delay),
|
||||
)
|
||||
client.request_json("/GetEdition")
|
||||
client.request_json("/GetEdition")
|
||||
|
||||
self.assertGreaterEqual(starts[1] - starts[0], 1.0)
|
||||
|
||||
def test_rejects_oversized_response(self):
|
||||
response = Mock()
|
||||
response.read.return_value = b"x" * 11
|
||||
response.__enter__ = Mock(return_value=response)
|
||||
response.__exit__ = Mock(return_value=False)
|
||||
with self.assertRaisesRegex(SourceError, "exceeds 10 bytes"):
|
||||
CurrentCbdClient(opener=lambda *_args, **_kwargs: response, max_response_bytes=10).request_json("/GetEdition")
|
||||
|
||||
def test_get_edition_uses_exact_query_and_checks_requested_id(self):
|
||||
response = Mock()
|
||||
response.read.return_value = json.dumps({"id": 920292, "contentRu": "text", "contentKg": None}).encode()
|
||||
response.__enter__ = Mock(return_value=response)
|
||||
response.__exit__ = Mock(return_value=False)
|
||||
requests = []
|
||||
|
||||
def opener(request, timeout):
|
||||
requests.append(request)
|
||||
return response
|
||||
|
||||
result = CurrentCbdClient(opener=opener, sleep=lambda _delay: None).edition(920292, "kg")
|
||||
|
||||
self.assertEqual(requests[0].full_url, "https://cbd.minjust.gov.kg/api/v1/GetEdition?editionId=920292&lang=kg&exact=true")
|
||||
self.assertEqual(requests[0].method, "GET")
|
||||
self.assertEqual(result.value["id"], 920292)
|
||||
|
||||
def test_rejects_response_id_that_does_not_match_exact_request(self):
|
||||
response = Mock()
|
||||
response.read.return_value = json.dumps({"id": 920492, "contentRu": "text", "contentKg": None}).encode()
|
||||
response.__enter__ = Mock(return_value=response)
|
||||
response.__exit__ = Mock(return_value=False)
|
||||
|
||||
with self.assertRaisesRegex(SourceChanged, "does not match requested ID"):
|
||||
CurrentCbdClient(opener=lambda *_args, **_kwargs: response).edition(920292, "ru")
|
||||
|
||||
def test_stages_alias_mapping_language_quirk_and_official_edition_order(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
base = Path(temporary)
|
||||
output = base / "generation"
|
||||
old_raw = base / "legacy" / "documents" / "6" / "sentinel"
|
||||
old_raw.parent.mkdir(parents=True)
|
||||
old_raw.write_text("preserve", encoding="utf-8")
|
||||
|
||||
class Client:
|
||||
def document(self, alias):
|
||||
self.alias = alias
|
||||
return document_record(alias=alias, canonical=6)
|
||||
|
||||
def edition(self, identifier, language):
|
||||
text = "<p>Russian</p>" if language == "ru" else "<p>Кыргызча</p>"
|
||||
name = "Редакция A" if identifier == 920492 else "Редакция B"
|
||||
return api_response({
|
||||
"id": identifier, "nameRus": name, "nameKyr": name,
|
||||
"contentRu": text, "contentKg": None,
|
||||
})
|
||||
|
||||
client = Client()
|
||||
result = stage_document(output, "6", client)
|
||||
raw = output / "documents" / "6"
|
||||
|
||||
self.assertEqual(result["state"], "text_complete_incomplete_attachments")
|
||||
self.assertEqual((raw / "editions/920492/ru.html").read_text(), "<p>Russian</p>")
|
||||
self.assertEqual((raw / "editions/920492/ky.html").read_text(), "<p>Кыргызча</p>")
|
||||
first = json.loads((raw / "editions/920492/metadata.json").read_text())
|
||||
second = json.loads((raw / "editions/920292/metadata.json").read_text())
|
||||
self.assertEqual((first["SourceOrder"], second["SourceOrder"]), (0, 1))
|
||||
language_meta = json.loads((raw / "editions/920292/source/ru.json").read_text())
|
||||
self.assertEqual((language_meta["requested_edition_id"], language_meta["exact"]), (920292, True))
|
||||
with sqlite3.connect(output / "current-api.sqlite3") as connection:
|
||||
self.assertTrue(connection.execute("SELECT contract_sha256 FROM generation").fetchone()[0])
|
||||
self.assertEqual(old_raw.read_text(), "preserve")
|
||||
with sqlite3.connect(output / "current-api.sqlite3") as connection:
|
||||
rows = connection.execute(
|
||||
"SELECT request_language, archive_language, state FROM languages ORDER BY request_language, edition_id"
|
||||
).fetchall()
|
||||
self.assertEqual(rows, [("kg", "ky", "complete")] * 2 + [("ru", "ru", "complete")] * 2)
|
||||
|
||||
def test_resolves_official_alias_to_canonical_staging_directory(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
output = Path(temporary) / "generation"
|
||||
|
||||
class Client:
|
||||
def document(self, alias):
|
||||
return document_record(alias=alias, canonical=205064, editions=[])
|
||||
|
||||
result = stage_document(output, "1-4", Client())
|
||||
|
||||
self.assertEqual(result["canonical_id"], 205064)
|
||||
self.assertTrue((output / "documents/205064/metadata.json").is_file())
|
||||
self.assertFalse((output / "documents/1-4").exists())
|
||||
|
||||
def test_rejects_non_exact_edition_response_id_without_publishing(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
output = Path(temporary) / "generation"
|
||||
|
||||
class Client:
|
||||
def document(self, _alias):
|
||||
return document_record(editions=[{"id": 920292, "textRusType": "docx", "textKyrType": "docx"}])
|
||||
|
||||
def edition(self, _identifier, language):
|
||||
return api_response({"id": 920492, "contentRu": f"<{language} edition>", "contentKg": None})
|
||||
|
||||
with self.assertRaisesRegex(SourceChanged, "exact edition ID mismatch"):
|
||||
stage_document(output, "6", Client())
|
||||
|
||||
self.assertFalse((output / "documents/6").exists())
|
||||
with sqlite3.connect(output / "current-api.sqlite3") as connection:
|
||||
self.assertEqual(connection.execute("SELECT state FROM languages").fetchone()[0], "error")
|
||||
|
||||
def test_rejects_exact_edition_metadata_contradiction(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
output = Path(temporary) / "generation"
|
||||
client = CurrentCbdClient()
|
||||
client.document = lambda _alias: document_record(editions=[{
|
||||
"id": 920292, "nameRus": "04.08.1998", "nameKyr": "04.08.1998",
|
||||
"textRusType": "docx", "textKyrType": "docx",
|
||||
}])
|
||||
client.request_json = lambda *_args, **_kwargs: api_response({
|
||||
"id": 920292, "nameRus": "13.04.2017", "nameKyr": "13.04.2017",
|
||||
"contentRu": "<wrong edition>", "contentKg": None,
|
||||
})
|
||||
|
||||
with self.assertRaisesRegex(SourceChanged, "metadata mismatch"):
|
||||
stage_document(output, "6", client)
|
||||
|
||||
self.assertFalse((output / "documents/6").exists())
|
||||
|
||||
def test_recovers_atomic_publish_before_manifest_checkpoint(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
output = Path(temporary) / "generation"
|
||||
|
||||
class Client:
|
||||
def document(self, _alias):
|
||||
return document_record(editions=[{"id": 920492, "textRusType": "docx", "textKyrType": "docx"}])
|
||||
|
||||
def edition(self, identifier, language):
|
||||
return api_response({"id": identifier, "contentRu": f"<{language}>", "contentKg": None})
|
||||
|
||||
client = Client()
|
||||
first = stage_document(output, "6", client)
|
||||
with sqlite3.connect(output / "current-api.sqlite3") as connection:
|
||||
connection.execute("UPDATE documents SET state='fetching' WHERE alias='6'")
|
||||
with sqlite3.connect(output / "manifest.sqlite3") as connection:
|
||||
connection.execute("DELETE FROM documents WHERE code=6")
|
||||
connection.execute("DELETE FROM errors WHERE code=6")
|
||||
|
||||
resumed = stage_document(output, "6", client, resume=True)
|
||||
|
||||
self.assertEqual(resumed["source_sha256"], first["source_sha256"])
|
||||
self.assertTrue(resumed["resumed"])
|
||||
with sqlite3.connect(output / "manifest.sqlite3") as connection:
|
||||
self.assertEqual(connection.execute("SELECT COUNT(*) FROM documents WHERE code=6").fetchone()[0], 1)
|
||||
self.assertEqual(connection.execute("SELECT COUNT(*) FROM errors WHERE code=6").fetchone()[0], 1)
|
||||
|
||||
def test_retries_after_document_metadata_request_failed_before_checkpoint(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
output = Path(temporary) / "generation"
|
||||
|
||||
class Client:
|
||||
failed = False
|
||||
|
||||
def document(self, _alias):
|
||||
if not self.failed:
|
||||
self.failed = True
|
||||
raise SourceError("temporary DNS failure")
|
||||
return document_record(editions=[])
|
||||
|
||||
client = Client()
|
||||
with self.assertRaisesRegex(SourceError, "DNS"):
|
||||
stage_document(output, "6", client)
|
||||
|
||||
result = stage_document(output, "6", client, resume=True)
|
||||
|
||||
self.assertEqual(result["canonical_id"], 6)
|
||||
with sqlite3.connect(output / "current-api.sqlite3") as connection:
|
||||
row = connection.execute(
|
||||
"SELECT canonical_id, response_sha256, expected_editions FROM documents WHERE alias='6'"
|
||||
).fetchone()
|
||||
self.assertEqual(row, (6, document_record(editions=[]).sha256, 0))
|
||||
|
||||
def test_does_not_resume_generation_without_exact_request_contract(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
output = Path(temporary) / "legacy-generation"
|
||||
output.mkdir(mode=0o700)
|
||||
sentinel = output / "old-response.json"
|
||||
sentinel.write_text("preserve", encoding="utf-8")
|
||||
client = Mock()
|
||||
|
||||
with self.assertRaisesRegex(SourceChanged, "no exact-edition request contract"):
|
||||
stage_document(output, "6", client, resume=True)
|
||||
|
||||
client.document.assert_not_called()
|
||||
self.assertEqual(sentinel.read_text(encoding="utf-8"), "preserve")
|
||||
|
||||
def test_incomplete_translation_resumes_without_rewriting_successful_language(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
output = Path(temporary) / "generation"
|
||||
|
||||
class Client:
|
||||
failed = False
|
||||
|
||||
def document(self, _alias):
|
||||
return document_record(editions=[{"id": 920492, "textRusType": "docx", "textKyrType": "docx"}])
|
||||
|
||||
def edition(self, identifier, language):
|
||||
if language == "kg" and not self.failed:
|
||||
self.failed = True
|
||||
raise SourceError("simulated interrupted response")
|
||||
return api_response({"id": identifier, "contentRu": f"<{language}>", "contentKg": None})
|
||||
|
||||
client = Client()
|
||||
first = stage_document(output, "6", client)
|
||||
self.assertIn("incomplete", first)
|
||||
self.assertFalse((output / "documents/6").exists())
|
||||
second = stage_document(output, "6", client, resume=True)
|
||||
self.assertEqual(second["state"], "text_complete_incomplete_attachments")
|
||||
self.assertEqual((output / "documents/6/editions/920492/ru.html").read_text(), "<ru>")
|
||||
self.assertEqual((output / "documents/6/editions/920492/ky.html").read_text(), "<kg>")
|
||||
self.assertEqual(client.failed, True)
|
||||
|
||||
def test_refuses_budget_overrun_without_publishing_partial_document(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
output = Path(temporary) / "generation"
|
||||
|
||||
class Client:
|
||||
def document(self, _alias):
|
||||
return document_record(editions=[{"id": 920492, "textRusType": "docx", "textKyrType": "docx"}])
|
||||
|
||||
def edition(self, identifier, _language):
|
||||
return api_response({"id": identifier, "contentRu": "123456", "contentKg": None})
|
||||
|
||||
with self.assertRaisesRegex(SourceError, "budget"):
|
||||
stage_document(output, "6", Client(), max_document_bytes=5)
|
||||
self.assertFalse((output / "documents/6").exists())
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -86,6 +86,47 @@ class MinjustNormalizationTest(unittest.TestCase):
|
||||
empty = json.loads((output / "documents/1/editions/40/edition.json").read_text(encoding="utf-8"))
|
||||
self.assertFalse(empty["quality"]["has_html"])
|
||||
|
||||
def test_preserves_official_edition_order_instead_of_sorting_ids(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
base = Path(temporary)
|
||||
source = base / "source"
|
||||
output = base / "normalized"
|
||||
document = self.document(source, 6)
|
||||
self.edition(document, 920492, {"ru": "<p>Первая редакция</p>"})
|
||||
self.edition(document, 920292, {"ru": "<p>Последняя редакция</p>"})
|
||||
for code, order in ((920492, 0), (920292, 1)):
|
||||
metadata_path = document / "editions" / str(code) / "metadata.json"
|
||||
metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
|
||||
metadata["SourceOrder"] = order
|
||||
metadata_path.write_text(json.dumps(metadata, ensure_ascii=False), encoding="utf-8")
|
||||
|
||||
normalize_archive(source, output)
|
||||
normalized = json.loads((output / "documents/6/document.json").read_text(encoding="utf-8"))
|
||||
|
||||
self.assertEqual([item["source_code"] for item in normalized["editions"]], ["920492", "920292"])
|
||||
self.assertEqual([item["source_order"] for item in normalized["editions"]], [0, 1])
|
||||
|
||||
def test_rejects_partial_source_edition_order(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
base = Path(temporary)
|
||||
source = base / "source"
|
||||
output = base / "normalized"
|
||||
document = self.document(source, 6)
|
||||
self.edition(document, 10, {"ru": "<p>Один</p>"})
|
||||
self.edition(document, 20, {"ru": "<p>Два</p>"})
|
||||
metadata_path = document / "editions/10/metadata.json"
|
||||
metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
|
||||
metadata["SourceOrder"] = 0
|
||||
metadata_path.write_text(json.dumps(metadata), encoding="utf-8")
|
||||
|
||||
with self.assertLogs("normalization.minjust_cbd", level="ERROR"):
|
||||
result = normalize_archive(source, output)
|
||||
|
||||
self.assertEqual((result.failed, result.normalized), (1, 0))
|
||||
with sqlite3.connect(output / "manifest.sqlite3") as connection:
|
||||
error = connection.execute("SELECT error FROM documents WHERE code='6'").fetchone()[0]
|
||||
self.assertIn("Invalid source edition order", error)
|
||||
|
||||
def test_continues_after_bad_document_and_clears_repaired_error(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
base = Path(temporary)
|
||||
|
||||
@@ -9,10 +9,240 @@ from contextlib import closing
|
||||
from pathlib import Path
|
||||
from unittest.mock import patch
|
||||
|
||||
from search.minjust_opensearch import bulk_batches, document_codes, export_bulk, load_bulk, request_json
|
||||
from search.catalog import legal_force_code, labels, source_code
|
||||
from search.minjust_opensearch import bulk_batches, document_codes, export_bulk, load_bulk, request_json, switch_alias
|
||||
|
||||
|
||||
class MinjustOpenSearchTest(unittest.TestCase):
|
||||
def test_unknown_document_type_keeps_source_label_and_has_no_inferred_force(self):
|
||||
value = {"ru": "Решение", "ky": "Решение"}
|
||||
|
||||
self.assertEqual(source_code("document_type", value), "other")
|
||||
self.assertEqual(labels("document_type", "other"), {"ru": "Прочие документы", "ky": "Башка документтер"})
|
||||
self.assertIsNone(legal_force_code(value))
|
||||
self.assertEqual(source_code("status", {"ru": "Не вступил в силу", "ky": "Күчүнө кире элек"}), "not_yet_effective")
|
||||
self.assertEqual(legal_force_code({"ru": "Конституционный закон", "ky": "Конституционный закон"}), "constitutional")
|
||||
self.assertEqual(legal_force_code({"ru": "Указ", "ky": "Жарлыгы"}), "subordinate")
|
||||
self.assertEqual(source_code("document_type", {"ru": "устав"}), "charter")
|
||||
|
||||
def test_export_marks_last_official_edition_current_even_when_ids_are_out_of_order(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
root = Path(temporary)
|
||||
input_root = root / "normalized"
|
||||
document_root = input_root / "documents/6"
|
||||
document_root.mkdir(parents=True)
|
||||
with closing(sqlite3.connect(input_root / "manifest.sqlite3")) as connection:
|
||||
with connection:
|
||||
connection.execute("CREATE TABLE documents (code TEXT, state TEXT)")
|
||||
connection.execute("INSERT INTO documents VALUES ('6', 'success')")
|
||||
(document_root / "document.json").write_text(
|
||||
json.dumps({"schema_version": "1", "source_code": "6", "editions": [
|
||||
{"source_code": "920492", "source_order": 0},
|
||||
{"source_code": "920292", "source_order": 1},
|
||||
]}),
|
||||
encoding="utf-8",
|
||||
)
|
||||
for edition in ("920292", "920492"):
|
||||
text = f"Текст {edition}"
|
||||
fragment_path = document_root / f"editions/{edition}/ru/fragments.json"
|
||||
fragment_path.parent.mkdir(parents=True)
|
||||
fragment_path.write_text(json.dumps([{
|
||||
"id": f"document:6:edition:{edition}:lang:ru:fragment:1",
|
||||
"document_code": "6",
|
||||
"edition_code": edition,
|
||||
"language": "ru",
|
||||
"position": 1,
|
||||
"type": "paragraph",
|
||||
"text": text,
|
||||
"text_sha256": hashlib.sha256(text.encode()).hexdigest(),
|
||||
"source_path": f"documents/6/editions/{edition}/ru.html",
|
||||
"source_sha256": "b" * 64,
|
||||
}]), encoding="utf-8")
|
||||
|
||||
output = root / "bulk.ndjson"
|
||||
self.assertEqual(export_bulk(input_root, output, "test-index"), (1, 2))
|
||||
lines = [json.loads(line) for line in output.read_text(encoding="utf-8").splitlines()]
|
||||
flags = {
|
||||
lines[index]["index"]["_id"].split(":")[3]: lines[index + 1]["is_current_edition"]
|
||||
for index in range(0, len(lines), 2)
|
||||
}
|
||||
|
||||
self.assertEqual(flags, {"920292": True, "920492": False})
|
||||
|
||||
def test_switches_alias_atomically_after_successful_load(self):
|
||||
with patch("search.minjust_opensearch.request_json", side_effect=[
|
||||
{"akyldash-fragments-v1": {"aliases": {"akyldash-fragments-current": {}}}},
|
||||
{"acknowledged": True},
|
||||
]) as request:
|
||||
switch_alias(
|
||||
"http://127.0.0.1:9200/", "akyldash-fragments-v2",
|
||||
"akyldash-fragments-current", "akyldash-fragments-v1",
|
||||
)
|
||||
|
||||
self.assertEqual(request.call_args_list[1].args[:2], ("http://127.0.0.1:9200/_aliases", "POST"))
|
||||
body = json.loads(request.call_args_list[1].args[2])
|
||||
self.assertEqual(body["actions"][0], {"remove": {"index": "akyldash-fragments-v1", "alias": "akyldash-fragments-current", "must_exist": True}})
|
||||
self.assertEqual(body["actions"][1], {"add": {"index": "akyldash-fragments-v2", "alias": "akyldash-fragments-current"}})
|
||||
|
||||
with self.assertRaisesRegex(ValueError, "differ"):
|
||||
switch_alias("http://127.0.0.1:9200", "same", "same", "old")
|
||||
with self.assertRaisesRegex(ValueError, "differ"):
|
||||
switch_alias("http://127.0.0.1:9200", "index", "", "old")
|
||||
with patch("search.minjust_opensearch.request_json", return_value={
|
||||
"akyldash-fragments-v3": {"aliases": {"alias": {}}}
|
||||
}) as request:
|
||||
with self.assertRaisesRegex(ValueError, "currently targets"):
|
||||
switch_alias("http://127.0.0.1:9200", "new", "alias", "akyldash-fragments-v1")
|
||||
request.assert_called_once()
|
||||
with patch("search.minjust_opensearch.request_json", side_effect=[
|
||||
{"old": {"aliases": {"alias": {}}}}, {"acknowledged": False},
|
||||
{"old": {"aliases": {"alias": {}}}},
|
||||
]):
|
||||
with self.assertRaisesRegex(RuntimeError, "did not acknowledge"):
|
||||
switch_alias("http://127.0.0.1:9200", "index", "alias", "old")
|
||||
|
||||
def test_switch_alias_recovers_when_post_succeeds_but_response_is_lost(self):
|
||||
with patch("search.minjust_opensearch.request_json", side_effect=[
|
||||
{"old": {"aliases": {"alias": {}}}},
|
||||
RuntimeError("response lost after OpenSearch applied request"),
|
||||
{"candidate": {"aliases": {"alias": {}}}},
|
||||
]) as request:
|
||||
switch_alias("http://os:9200", "candidate", "alias", "old")
|
||||
self.assertEqual(request.call_count, 3)
|
||||
self.assertEqual(request.call_args_list[1].args[1], "POST")
|
||||
self.assertEqual(request.call_args_list[2].args[1], "GET")
|
||||
|
||||
def test_switch_alias_is_idempotent_after_process_stops_before_checkpoint(self):
|
||||
with patch("search.minjust_opensearch.request_json", return_value={
|
||||
"candidate": {"aliases": {"alias": {}}}
|
||||
}) as request:
|
||||
switch_alias("http://os:9200", "candidate", "alias", "old")
|
||||
request.assert_called_once()
|
||||
|
||||
def test_switch_alias_refuses_to_retry_after_unexpected_target(self):
|
||||
with patch("search.minjust_opensearch.request_json", side_effect=[
|
||||
{"old": {"aliases": {"alias": {}}}},
|
||||
RuntimeError("response lost"),
|
||||
{"other": {"aliases": {"alias": {}}}},
|
||||
]):
|
||||
with self.assertRaisesRegex(ValueError, "unexpected index"):
|
||||
switch_alias("http://os:9200", "candidate", "alias", "old")
|
||||
|
||||
def test_resume_completes_checkpoint_when_alias_switched_before_previous_process_stopped(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
root = Path(temporary)
|
||||
input_root = root / "normalized"
|
||||
document_root = input_root / "documents/1"
|
||||
document_root.mkdir(parents=True)
|
||||
with closing(sqlite3.connect(input_root / "manifest.sqlite3")) as connection:
|
||||
with connection:
|
||||
connection.execute("CREATE TABLE documents (code TEXT, state TEXT)")
|
||||
connection.execute("INSERT INTO documents VALUES ('1', 'success')")
|
||||
(document_root / "document.json").write_text(
|
||||
json.dumps({"schema_version": "1", "source_code": "1", "editions": [
|
||||
{"source_code": "1", "source_order": 0},
|
||||
]}),
|
||||
encoding="utf-8",
|
||||
)
|
||||
text = "текст закона"
|
||||
fragment = document_root / "editions/1/ru/fragments.json"
|
||||
fragment.parent.mkdir(parents=True)
|
||||
fragment.write_text(json.dumps([{
|
||||
"id": "document:1:edition:1:lang:ru:fragment:1",
|
||||
"document_code": "1", "edition_code": "1", "language": "ru", "position": 1,
|
||||
"type": "paragraph", "text": text,
|
||||
"text_sha256": hashlib.sha256(text.encode()).hexdigest(),
|
||||
"source_path": "documents/1/editions/1/ru.html", "source_sha256": "b" * 64,
|
||||
}]), encoding="utf-8")
|
||||
checkpoint = root / "checkpoint.json"
|
||||
state = {
|
||||
"schema_version": 2,
|
||||
"url": "http://os:9200",
|
||||
"cluster_uuid": "cluster",
|
||||
"index": "candidate",
|
||||
"index_uuid": "index-uuid",
|
||||
"input": str(input_root.resolve()),
|
||||
"manifest_sha256": hashlib.sha256((input_root / "manifest.sqlite3").read_bytes()).hexdigest(),
|
||||
"limit": None,
|
||||
"alias": "current",
|
||||
"last_document_code": "1",
|
||||
"complete": False,
|
||||
}
|
||||
checkpoint.write_text(json.dumps(state), encoding="utf-8")
|
||||
|
||||
with (
|
||||
patch("search.minjust_opensearch.request_json", side_effect=[
|
||||
{"cluster_uuid": "cluster"},
|
||||
{"candidate": {"settings": {"index": {"uuid": "index-uuid"}}}},
|
||||
{"errors": False, "items": [{"index": {}}]},
|
||||
{"candidate": {"aliases": {"current": {}}}},
|
||||
]) as request,
|
||||
patch("search.minjust_opensearch.validate_candidate_index") as validate_candidate,
|
||||
):
|
||||
self.assertEqual(
|
||||
load_bulk(
|
||||
input_root, "http://os:9200", "candidate", resume=True, checkpoint=checkpoint,
|
||||
alias="current", expected_old_index="previous", canary_ru="закон", canary_ky="мыйзам",
|
||||
),
|
||||
(1, 1),
|
||||
)
|
||||
self.assertTrue(json.loads(checkpoint.read_text(encoding="utf-8"))["complete"])
|
||||
self.assertEqual(request.call_args_list[-1].args[1], "GET")
|
||||
validate_candidate.assert_called_once_with("http://os:9200", "candidate", 1, "закон", "мыйзам")
|
||||
|
||||
def test_zero_fragment_candidate_never_reaches_alias_switch(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
root = Path(temporary) / "normalized"
|
||||
document = root / "documents/1"
|
||||
document.mkdir(parents=True)
|
||||
with closing(sqlite3.connect(root / "manifest.sqlite3")) as connection:
|
||||
connection.execute("CREATE TABLE documents (code TEXT, state TEXT)")
|
||||
connection.execute("INSERT INTO documents VALUES ('1', 'success')")
|
||||
(document / "document.json").write_text(
|
||||
json.dumps({"source_code": "1", "editions": []}), encoding="utf-8"
|
||||
)
|
||||
with (
|
||||
patch("search.minjust_opensearch.request_json", side_effect=[
|
||||
{}, {"cluster_uuid": "cluster"},
|
||||
{"test-index": {"settings": {"index": {"uuid": "index"}}}},
|
||||
]) as request,
|
||||
patch("search.minjust_opensearch.validate_candidate_index") as validate_candidate,
|
||||
patch("search.minjust_opensearch.switch_alias") as switch,
|
||||
):
|
||||
with self.assertRaisesRegex(ValueError, "empty expected fragment inventory"):
|
||||
load_bulk(
|
||||
root, "http://127.0.0.1:9200", "test-index",
|
||||
checkpoint=Path(temporary) / "checkpoint.json", alias="current",
|
||||
expected_old_index="old-index", canary_ru="закон", canary_ky="мыйзам",
|
||||
)
|
||||
self.assertEqual(request.call_count, 3)
|
||||
validate_candidate.assert_not_called()
|
||||
switch.assert_not_called()
|
||||
|
||||
def test_candidate_index_requires_exact_count_and_both_language_canaries(self):
|
||||
from search.minjust_opensearch import validate_candidate_index
|
||||
|
||||
with patch("search.minjust_opensearch.request_json", side_effect=[
|
||||
{"_shards": {"failed": 0}},
|
||||
{"count": 2},
|
||||
{"hits": {"hits": [{"_source": {"text_ru": "тест"}}]}},
|
||||
{"hits": {"hits": [{"_source": {"text_ky": "сыноо"}}]}},
|
||||
]) as request:
|
||||
validate_candidate_index("http://os:9200", "candidate", 2, "тест", "сыноо")
|
||||
self.assertEqual(request.call_count, 4)
|
||||
with patch("search.minjust_opensearch.request_json", side_effect=[
|
||||
{"_shards": {"failed": 0}}, {"count": 1}
|
||||
]):
|
||||
with self.assertRaisesRegex(RuntimeError, "expected 2"):
|
||||
validate_candidate_index("http://os:9200", "candidate", 2, "тест", "сыноо")
|
||||
with patch("search.minjust_opensearch.request_json", side_effect=[
|
||||
{"_shards": {"failed": 0}}, {"count": 2},
|
||||
{"hits": {"hits": [{"_source": {"text_ru": "тест"}}]}},
|
||||
{"hits": {"hits": []}},
|
||||
]):
|
||||
with self.assertRaisesRegex(RuntimeError, "ky canary"):
|
||||
validate_candidate_index("http://os:9200", "candidate", 2, "тест", "сыноо")
|
||||
|
||||
def test_exports_atomic_bulk_and_rejects_mismatched_fragment(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
root = Path(temporary)
|
||||
@@ -74,7 +304,9 @@ class MinjustOpenSearchTest(unittest.TestCase):
|
||||
self.assertEqual(len(lines), 4)
|
||||
self.assertEqual(lines[0]["index"]["_id"], "document:7:edition:10:lang:ky:fragment:1")
|
||||
self.assertIn("text_ky", lines[1])
|
||||
self.assertTrue(lines[1]["is_current_edition"])
|
||||
self.assertNotIn("text_ru", lines[1])
|
||||
self.assertEqual(lines[1]["legal_force_code"], "legislative")
|
||||
self.assertEqual(lines[3]["text_ru"], "Текст \"RU\"\nстрока")
|
||||
self.assertEqual(
|
||||
list(bulk_batches(iter((("7", b"a\nb\n"), ("8", b"c\nd\n"))), 4)),
|
||||
@@ -85,7 +317,11 @@ class MinjustOpenSearchTest(unittest.TestCase):
|
||||
document_codes(root / "normalized", 1, "8")
|
||||
|
||||
checkpoint = root / "checkpoint.json"
|
||||
with patch("search.minjust_opensearch.request_json") as request:
|
||||
with (
|
||||
patch("search.minjust_opensearch.request_json") as request,
|
||||
patch("search.minjust_opensearch.validate_candidate_index") as validate_candidate,
|
||||
patch("search.minjust_opensearch.switch_alias") as switch,
|
||||
):
|
||||
request.side_effect = [
|
||||
{},
|
||||
{"cluster_uuid": "cluster-1"},
|
||||
@@ -99,14 +335,52 @@ class MinjustOpenSearchTest(unittest.TestCase):
|
||||
"test-index",
|
||||
maximum_bytes=4096,
|
||||
checkpoint=checkpoint,
|
||||
alias="test-current",
|
||||
expected_old_index="test-index-old",
|
||||
canary_ru="закон",
|
||||
canary_ky="мыйзам",
|
||||
),
|
||||
(2, 2),
|
||||
)
|
||||
self.assertEqual(request.call_args_list[-1].args[3], "application/x-ndjson")
|
||||
validate_candidate.assert_called_once_with(
|
||||
"http://127.0.0.1:9200", "test-index", 2, "закон", "мыйзам"
|
||||
)
|
||||
switch.assert_called_once_with(
|
||||
"http://127.0.0.1:9200", "test-index", "test-current", "test-index-old"
|
||||
)
|
||||
state = json.loads(checkpoint.read_text(encoding="utf-8"))
|
||||
self.assertEqual(state["last_document_code"], "7")
|
||||
self.assertTrue(state["complete"])
|
||||
|
||||
legacy = state.copy()
|
||||
legacy.pop("alias")
|
||||
legacy["schema_version"] = 1
|
||||
legacy["last_document_code"] = "8"
|
||||
legacy["complete"] = False
|
||||
checkpoint.write_text(json.dumps(legacy), encoding="utf-8")
|
||||
with (
|
||||
patch("search.minjust_opensearch.request_json") as request,
|
||||
patch("search.minjust_opensearch.validate_candidate_index") as validate_candidate,
|
||||
patch("search.minjust_opensearch.switch_alias"),
|
||||
):
|
||||
request.side_effect = [
|
||||
{"cluster_uuid": "cluster-1"},
|
||||
{"test-index": {"settings": {"index": {"uuid": "index-1"}}}},
|
||||
]
|
||||
self.assertEqual(
|
||||
load_bulk(
|
||||
root / "normalized",
|
||||
"http://127.0.0.1:9200",
|
||||
"test-index",
|
||||
maximum_bytes=4096,
|
||||
resume=True,
|
||||
checkpoint=checkpoint,
|
||||
),
|
||||
(1, 0),
|
||||
)
|
||||
self.assertEqual(json.loads(checkpoint.read_text(encoding="utf-8"))["schema_version"], 2)
|
||||
|
||||
state["last_document_code"] = "8"
|
||||
state["complete"] = False
|
||||
checkpoint.write_text(json.dumps(state), encoding="utf-8")
|
||||
@@ -116,6 +390,24 @@ class MinjustOpenSearchTest(unittest.TestCase):
|
||||
{"test-index": {"settings": {"index": {"uuid": "index-1"}}}},
|
||||
]
|
||||
with self.assertRaisesRegex(ValueError, "does not match"):
|
||||
load_bulk(
|
||||
root / "normalized",
|
||||
"http://127.0.0.1:9200",
|
||||
"test-index",
|
||||
maximum_bytes=4096,
|
||||
resume=True,
|
||||
checkpoint=checkpoint,
|
||||
alias="test-current",
|
||||
expected_old_index="test-index-old",
|
||||
canary_ru="закон",
|
||||
canary_ky="мыйзам",
|
||||
)
|
||||
with patch("search.minjust_opensearch.request_json") as request:
|
||||
request.side_effect = [
|
||||
{"cluster_uuid": "cluster-1"},
|
||||
{"test-index": {"settings": {"index": {"uuid": "index-1"}}}},
|
||||
]
|
||||
with self.assertRaisesRegex(ValueError, "alias"):
|
||||
load_bulk(
|
||||
root / "normalized",
|
||||
"http://127.0.0.1:9200",
|
||||
@@ -138,8 +430,16 @@ class MinjustOpenSearchTest(unittest.TestCase):
|
||||
limit=1,
|
||||
resume=True,
|
||||
checkpoint=checkpoint,
|
||||
alias="test-current",
|
||||
expected_old_index="test-index-old",
|
||||
canary_ru="закон",
|
||||
canary_ky="мыйзам",
|
||||
)
|
||||
with patch("search.minjust_opensearch.request_json") as request:
|
||||
with (
|
||||
patch("search.minjust_opensearch.request_json") as request,
|
||||
patch("search.minjust_opensearch.validate_candidate_index") as validate_candidate,
|
||||
patch("search.minjust_opensearch.switch_alias"),
|
||||
):
|
||||
request.side_effect = [
|
||||
{"cluster_uuid": "cluster-1"},
|
||||
{"test-index": {"settings": {"index": {"uuid": "index-1"}}}},
|
||||
@@ -152,10 +452,17 @@ class MinjustOpenSearchTest(unittest.TestCase):
|
||||
maximum_bytes=4096,
|
||||
resume=True,
|
||||
checkpoint=checkpoint,
|
||||
alias="test-current",
|
||||
expected_old_index="test-index-old",
|
||||
canary_ru="закон",
|
||||
canary_ky="мыйзам",
|
||||
),
|
||||
(1, 0),
|
||||
)
|
||||
self.assertTrue(all(call.args[1] == "GET" for call in request.call_args_list))
|
||||
validate_candidate.assert_called_once_with(
|
||||
"http://127.0.0.1:9200", "test-index", 2, "закон", "мыйзам"
|
||||
)
|
||||
|
||||
state["last_document_code"] = "9"
|
||||
state["complete"] = False
|
||||
@@ -173,6 +480,10 @@ class MinjustOpenSearchTest(unittest.TestCase):
|
||||
maximum_bytes=4096,
|
||||
resume=True,
|
||||
checkpoint=checkpoint,
|
||||
alias="test-current",
|
||||
expected_old_index="test-index-old",
|
||||
canary_ru="закон",
|
||||
canary_ky="мыйзам",
|
||||
)
|
||||
|
||||
failed_checkpoint = root / "failed-checkpoint.json"
|
||||
@@ -218,6 +529,10 @@ class MinjustOpenSearchTest(unittest.TestCase):
|
||||
maximum_bytes=4096,
|
||||
resume=True,
|
||||
checkpoint=checkpoint,
|
||||
alias="test-current",
|
||||
expected_old_index="test-index-old",
|
||||
canary_ru="закон",
|
||||
canary_ky="мыйзам",
|
||||
)
|
||||
|
||||
http_error = urllib.error.HTTPError(
|
||||
|
||||
@@ -0,0 +1,234 @@
|
||||
import json
|
||||
import contextlib
|
||||
import io
|
||||
import tempfile
|
||||
import unittest
|
||||
import urllib.parse
|
||||
from pathlib import Path
|
||||
from unittest.mock import Mock, patch
|
||||
|
||||
from search.api import Api, ApiError, handler
|
||||
|
||||
|
||||
class SearchApiTest(unittest.TestCase):
|
||||
def make_api(self, root: Path) -> Api:
|
||||
document = root / "documents/7"
|
||||
edition = document / "editions/10"
|
||||
edition.mkdir(parents=True)
|
||||
(document / "document.json").write_text(json.dumps({
|
||||
"source_code": "7", "available_languages": ["ru"],
|
||||
"editions": [{"source_code": "10", "available_languages": ["ru"]},],
|
||||
}), encoding="utf-8")
|
||||
(edition / "edition.json").write_text(json.dumps({"source_code": "10", "available_languages": ["ru"]}), encoding="utf-8")
|
||||
(edition / "ru").mkdir()
|
||||
(edition / "ru/content.html").write_text("<p>Текст</p>", encoding="utf-8")
|
||||
(edition / "ru/content.txt").write_text("Текст\n", encoding="utf-8")
|
||||
return Api("http://opensearch:9200", "current", root)
|
||||
|
||||
def test_static_font_assets_are_allowlisted(self):
|
||||
content_type, body = Api.static_asset("/static/fonts/noto-sans-cyrillic-ext.woff2")
|
||||
self.assertEqual(content_type, "font/woff2")
|
||||
self.assertTrue(body.startswith(b"wOF2"))
|
||||
content_type, body = Api.static_asset("/static/favicon.svg")
|
||||
self.assertEqual(content_type, "image/svg+xml")
|
||||
self.assertIn(b"<svg", body)
|
||||
content_type, body = Api.static_asset("/static/favicon-32.png")
|
||||
self.assertEqual(content_type, "image/png")
|
||||
self.assertTrue(body.startswith(b"\x89PNG\r\n\x1a\n"))
|
||||
with self.assertRaisesRegex(ApiError, "static asset not found"):
|
||||
Api.static_asset("/static/fonts/../../DESIGN.md")
|
||||
|
||||
def test_users_screen_is_served_without_exposing_admin_api(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
api = self.make_api(Path(temporary))
|
||||
request_handler = handler(api)
|
||||
|
||||
def get(path):
|
||||
request = request_handler.__new__(request_handler)
|
||||
request.path = path
|
||||
request.headers = {}
|
||||
request.wfile = io.BytesIO()
|
||||
request.send_response = Mock()
|
||||
request.send_header = Mock()
|
||||
request.end_headers = Mock()
|
||||
request.do_GET()
|
||||
return request
|
||||
|
||||
users_page = get("/users")
|
||||
users_page.send_response.assert_called_once_with(200)
|
||||
self.assertIn(b'id="users-page"', users_page.wfile.getvalue())
|
||||
admin_api = get("/admin/users")
|
||||
admin_api.send_response.assert_called_once_with(401)
|
||||
|
||||
def test_account_capability_matches_the_admin_users_api_guard(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
api = self.make_api(Path(temporary))
|
||||
api.auth_store.create_admin("Fixture-only-admin-password-2026")
|
||||
admin_token, _ = api.auth_store.login("admin", "Fixture-only-admin-password-2026")
|
||||
api.auth_store.create_user("fixture-user", "Fixture-only-temporary-password-2026")
|
||||
api.auth_store.change_password("fixture-user", "Fixture-only-temporary-password-2026", "Fixture-only-user-password-2026")
|
||||
user_token, _ = api.auth_store.login("fixture-user", "Fixture-only-user-password-2026")
|
||||
request_handler = handler(api)
|
||||
|
||||
def get(path, token):
|
||||
request = request_handler.__new__(request_handler)
|
||||
request.path = path
|
||||
request.headers = {"Cookie": f"akyldash_session={token}"}
|
||||
request.wfile = io.BytesIO()
|
||||
request.send_response = Mock()
|
||||
request.send_header = Mock()
|
||||
request.end_headers = Mock()
|
||||
request.do_GET()
|
||||
return request
|
||||
|
||||
admin_account = json.loads(get("/auth/me", admin_token).wfile.getvalue())["account"]
|
||||
user_account = json.loads(get("/auth/me", user_token).wfile.getvalue())["account"]
|
||||
self.assertEqual((admin_account["role"], admin_account["can_manage_users"]), ("Администратор", True))
|
||||
self.assertEqual((user_account["role"], user_account["can_manage_users"]), ("Пользователь", False))
|
||||
get("/admin/users", admin_token).send_response.assert_called_once_with(200)
|
||||
get("/admin/users", user_token).send_response.assert_called_once_with(403)
|
||||
|
||||
def test_search_pagination_filters_and_highlight(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
api = self.make_api(Path(temporary))
|
||||
response = {"hits": {"hits": [{"_source": {"document_code": "7", "edition_code": "10", "document_name_ru": "Закон"}, "highlight": {"text_ru": ["<em>Закон</em>"]}}]}}
|
||||
with patch("search.api.request_json", return_value=response) as request:
|
||||
status, payload = api.handle("GET", "/search?q=%D0%B7%D0%B0%D0%BA%D0%BE%D0%BD&language=ru&page=2&page_size=5&status=active")
|
||||
self.assertEqual(status, 200)
|
||||
self.assertEqual(payload["results"][0]["snippet"], "Закон")
|
||||
body = json.loads(request.call_args.args[2])
|
||||
self.assertEqual((body["from"], body["size"]), (5, 6))
|
||||
self.assertIn({"term": {"status_code": "active"}}, body["query"]["bool"]["filter"])
|
||||
with self.assertRaisesRegex(ApiError, "within 10000 results"):
|
||||
api.handle("GET", "/search?q=x&page=100&page_size=100")
|
||||
|
||||
def test_review_secret_file_is_read_without_command_line_value(self):
|
||||
from search.api import main
|
||||
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
secret_file = Path(temporary) / "secret"
|
||||
secret_file.write_text("secret-value\n", encoding="utf-8")
|
||||
with patch("sys.argv", ["search.api", "--review-secret-file", str(secret_file)]), patch("search.api.Api") as api, patch("search.api.ThreadingHTTPServer"):
|
||||
main()
|
||||
self.assertEqual(api.call_args.args[4], b"secret-value")
|
||||
|
||||
def test_review_secret_file_rejects_empty_content(self):
|
||||
from search.api import main
|
||||
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
secret_file = Path(temporary) / "secret"
|
||||
secret_file.touch()
|
||||
with patch("sys.argv", ["search.api", "--review-secret-file", str(secret_file)]), contextlib.redirect_stderr(io.StringIO()):
|
||||
with self.assertRaises(SystemExit) as result:
|
||||
main()
|
||||
self.assertEqual(result.exception.code, 2)
|
||||
|
||||
def test_production_api_uses_registration_intent_boosts(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
api = self.make_api(Path(temporary))
|
||||
response = {"hits": {"hits": []}}
|
||||
with patch("search.api.request_json", return_value=response) as request:
|
||||
api.handle("GET", "/search?q=%D0%BA%D0%B0%D0%BA+%D0%BE%D1%82%D0%BA%D1%80%D1%8B%D1%82%D1%8C+%D0%9E%D1%81%D0%9E%D0%9E&language=ru")
|
||||
body = json.loads(request.call_args.args[2])
|
||||
planned = body["query"]["bool"]["must"]["bool"]
|
||||
self.assertEqual(planned["minimum_should_match"], 1)
|
||||
self.assertNotIn("filter", planned)
|
||||
self.assertTrue(any("constant_score" in clause for clause in planned["should"]))
|
||||
self.assertTrue(any("общество с ограниченной ответственностью" in clause.get("multi_match", {}).get("query", "") for clause in planned["should"]))
|
||||
|
||||
def test_production_api_boosts_tax_code_for_profit_tax_query(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
api = self.make_api(Path(temporary))
|
||||
with patch("search.api.request_json", return_value={"hits": {"hits": []}}) as request:
|
||||
api.handle("GET", "/search?q=%D0%BD%D0%B0%D0%BB%D0%BE%D0%B3+%D0%BD%D0%B0+%D0%BF%D1%80%D0%B8%D0%B1%D1%8B%D0%BB%D1%8C&language=ru")
|
||||
body = json.loads(request.call_args.args[2])
|
||||
planned = body["query"]["bool"]["must"]["bool"]
|
||||
anchors = [clause["constant_score"]["filter"]["bool"]["filter"][0] for clause in planned["should"] if "constant_score" in clause]
|
||||
self.assertIn({"term": {"document_code": "112340"}}, anchors)
|
||||
|
||||
def test_search_sorts_repealed_documents_after_other_statuses(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
api = self.make_api(Path(temporary))
|
||||
with patch("search.api.request_json", return_value={"hits": {"hits": []}}) as request:
|
||||
api.handle("GET", "/search?q=НДС+на+импорт&language=ru")
|
||||
body = json.loads(request.call_args.args[2])
|
||||
source = body["sort"][0]["_script"]["script"]["source"]
|
||||
self.assertIn("'active' ? 0", source)
|
||||
self.assertIn("'repealed' ? 2", source)
|
||||
self.assertEqual(body["sort"][1], {"_score": "desc"})
|
||||
|
||||
api.handle("GET", "/search?q=НДС+на+импорт&language=ru&sort=date")
|
||||
body = json.loads(request.call_args.args[2])
|
||||
self.assertEqual(body["sort"][1], {"date_adopted": "desc"})
|
||||
|
||||
def test_document_editions_openapi_and_validation(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
api = self.make_api(Path(temporary))
|
||||
specification = api.handle("GET", "/openapi.json")[1]
|
||||
self.assertEqual(specification["info"]["version"], "v1")
|
||||
self.assertEqual(specification["paths"]["/documents/{code}"]["get"]["parameters"][0]["required"], True)
|
||||
self.assertEqual(specification["paths"]["/documents/{code}/editions/{edition}"]["get"]["parameters"][1]["name"], "edition")
|
||||
self.assertEqual(api.handle("GET", "/documents/7")[1]["current_edition"]["source_code"], "10")
|
||||
self.assertEqual(api.handle("GET", "/documents/7/editions/10?language=ru")[1]["content"]["ru"]["text"], "Текст\n")
|
||||
with self.assertRaisesRegex(ApiError, "q is required"):
|
||||
api.handle("GET", "/search")
|
||||
with self.assertRaisesRegex(ApiError, "date_from must be an ISO date"):
|
||||
api.handle("GET", "/search?q=x&date_from=tomorrow")
|
||||
with self.assertRaisesRegex(ApiError, "document not found"):
|
||||
api.handle("GET", "/documents/%2E%2E")
|
||||
|
||||
def test_filters_count_documents_and_return_bilingual_labels(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
api = self.make_api(Path(temporary))
|
||||
keys = {"document_types": "law", "statuses": "active", "authorities": "parliament", "legal_forces": "legislative"}
|
||||
response = {"aggregations": {name: {"buckets": [{"key": keys[name], "documents": {"value": 3}}]} for name in keys}}
|
||||
with patch("search.api.request_json", return_value=response) as request:
|
||||
payload = api.handle("GET", "/search/filters?language=ky")[1]
|
||||
self.assertEqual(payload["document_types"][0], {"code": "law", "labels": {"ru": "Закон", "ky": "Мыйзам"}, "count": 3})
|
||||
self.assertEqual(payload["legal_forces"][0]["labels"]["ky"], "Мыйзам деңгээли")
|
||||
body = json.loads(request.call_args.args[2])
|
||||
self.assertIn("terms", body["aggs"]["document_types"])
|
||||
self.assertIn("legal_force_code", body["aggs"]["legal_forces"]["terms"]["field"])
|
||||
self.assertEqual(body["query"], {"term": {"is_current_edition": True}})
|
||||
|
||||
def test_global_dfs_is_only_sent_for_explicit_multi_index_searches(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
multi = Api("http://opensearch:9200", "base-v2,supplement-v1", Path(temporary), review_secret=b"test-secret")
|
||||
alias = Api("http://opensearch:9200", "current", Path(temporary), review_secret=b"test-secret")
|
||||
single = Api("http://opensearch:9200", "single-v2", Path(temporary), review_secret=b"test-secret")
|
||||
one_hit = {"hits": {"hits": [{"_index": "base-v2", "_source": {"document_code": "5", "document_name_ru": "Кодекс", "document_name_ky": "Кодекс"}}]}}
|
||||
empty = {"hits": {"hits": []}}
|
||||
alias_hit = {"hits": {"hits": [{"_index": "current-20261103", "_source": {"document_code": "7", "document_name_ru": "Закон"}}]}}
|
||||
aggregations = {"aggregations": {name: {"buckets": []} for name in ("document_types", "statuses", "authorities", "legal_forces")}}
|
||||
with patch("search.api.request_json", side_effect=[one_hit, empty, alias_hit, one_hit, aggregations]) as request:
|
||||
multi_ru = multi.search({"q": ["test"], "language": ["ru"], "page_size": ["10"]})
|
||||
multi_ky_empty = multi.search({"q": ["test"], "language": ["ky"], "page_size": ["10"]})
|
||||
alias_ru = alias.search({"q": ["test"], "language": ["ru"], "page_size": ["10"]})
|
||||
single_ky = single.search({"q": ["test"], "language": ["ky"], "page_size": ["10"]})
|
||||
alias.filters({"language": ["ru"]})
|
||||
|
||||
calls = request.call_args_list
|
||||
multi_ru_url = urllib.parse.urlsplit(calls[0].args[0])
|
||||
multi_ky_url = urllib.parse.urlsplit(calls[1].args[0])
|
||||
self.assertEqual(multi_ru_url.path, "/base-v2%2Csupplement-v1/_search")
|
||||
self.assertEqual(urllib.parse.parse_qs(multi_ru_url.query), {"search_type": ["dfs_query_then_fetch"]})
|
||||
self.assertEqual(urllib.parse.parse_qs(multi_ky_url.query), {"search_type": ["dfs_query_then_fetch"]})
|
||||
self.assertEqual([item["code"] for item in multi_ru["results"]], ["5"])
|
||||
self.assertEqual(multi_ky_empty["results"], [])
|
||||
self.assertEqual(multi.review_snapshots.verify(multi_ru["review_token"])["index_name"], "base-v2,supplement-v1")
|
||||
self.assertEqual(multi.review_snapshots.verify(multi_ky_empty["review_token"])["index_name"], "base-v2,supplement-v1")
|
||||
|
||||
for call in calls[2:]:
|
||||
parsed = urllib.parse.urlsplit(call.args[0])
|
||||
self.assertEqual(parsed.query, "")
|
||||
self.assertEqual(alias.review_snapshots.verify(alias_ru["review_token"])["index_name"], "current-20261103")
|
||||
self.assertEqual(single.review_snapshots.verify(single_ky["review_token"])["index_name"], "base-v2")
|
||||
multi_body = json.loads(calls[0].args[2])
|
||||
alias_body = json.loads(calls[2].args[2])
|
||||
self.assertEqual(multi_body, alias_body)
|
||||
self.assertNotIn("search_type", multi_body)
|
||||
self.assertEqual(json.loads(calls[1].args[2])["query"]["bool"]["filter"][0], {"term": {"language": "ky"}})
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,65 @@
|
||||
import json
|
||||
import os
|
||||
import unittest
|
||||
import uuid
|
||||
from pathlib import Path
|
||||
|
||||
from search.api import Api
|
||||
from search.minjust_opensearch import DEFAULT_MAPPING, request_json
|
||||
|
||||
|
||||
@unittest.skipUnless(os.getenv("AKYLDASH_OPENSEARCH_URL"), "set AKYLDASH_OPENSEARCH_URL to run against local OpenSearch")
|
||||
class SearchApiOpenSearchTest(unittest.TestCase):
|
||||
def test_current_editions_filters_and_catalogs(self):
|
||||
base_url = os.environ["AKYLDASH_OPENSEARCH_URL"].rstrip("/")
|
||||
index = f"akyldash-api-test-{uuid.uuid4().hex}"
|
||||
request_json(f"{base_url}/{index}", "PUT", DEFAULT_MAPPING.read_bytes(), "application/json")
|
||||
try:
|
||||
documents = [
|
||||
{"document_code": "1", "edition_code": "1", "is_current_edition": False, "language": "ru", "position": 1, "fragment_type": "paragraph", "text_ru": "historic", "document_name_ru": "Old law", "document_type_ru": "Закон", "document_type_ky": "Мыйзам", "document_type_code": "law", "legal_force_code": "legislative", "status_ru": "Утратил силу", "status_ky": "Күчүн жоготту", "status_code": "repealed", "date_adopted": "2020-01-01", "authority_paths_ru": ["Парламент"], "authority_paths_ky": ["Парламент"], "authority_codes": ["parliament"]},
|
||||
{"document_code": "1", "edition_code": "2", "is_current_edition": True, "language": "ru", "position": 1, "fragment_type": "paragraph", "text_ru": "needle", "document_name_ru": "Current law", "document_type_ru": "Закон", "document_type_ky": "Мыйзам", "document_type_code": "law", "legal_force_code": "legislative", "status_ru": "Действует", "status_ky": "Күчүндө", "status_code": "active", "date_adopted": "2021-01-01", "authority_paths_ru": ["Парламент"], "authority_paths_ky": ["Парламент"], "authority_codes": ["parliament"]},
|
||||
{"document_code": "2", "edition_code": "1", "is_current_edition": True, "language": "ru", "position": 1, "fragment_type": "paragraph", "text_ru": "needle", "document_name_ru": "Current decree", "document_type_ru": "Указ", "document_type_ky": "Жарлык", "document_type_code": "decree", "legal_force_code": "subordinate", "status_ru": "Действует", "status_ky": "Күчүндө", "status_code": "active", "date_adopted": "2022-01-01", "authority_paths_ru": ["Президент"], "authority_paths_ky": ["Президент"], "authority_codes": ["president"]},
|
||||
]
|
||||
for number, document in enumerate(documents):
|
||||
request_json(f"{base_url}/{index}/_doc/{number}", "PUT", json.dumps(document).encode(), "application/json")
|
||||
request_json(f"{base_url}/{index}/_refresh", "POST", None, "application/json")
|
||||
api = Api(base_url, index, Path("."))
|
||||
self.assertEqual(api.handle("GET", "/search?q=historic")[1]["results"], [])
|
||||
filtered = api.handle("GET", "/search?q=needle&document_type=law")[1]
|
||||
self.assertEqual([result["code"] for result in filtered["results"]], ["1"])
|
||||
force_filtered = api.handle("GET", "/search?q=needle&legal_force=subordinate")[1]
|
||||
self.assertEqual([result["code"] for result in force_filtered["results"]], ["2"])
|
||||
self.assertEqual(force_filtered["results"][0]["legal_force"], "Подзаконный уровень")
|
||||
filters = api.handle("GET", "/search/filters")[1]
|
||||
self.assertEqual({item["count"] for item in filters["statuses"]}, {2})
|
||||
self.assertEqual({item["code"] for item in filters["legal_forces"]}, {"legislative", "subordinate"})
|
||||
finally:
|
||||
request_json(f"{base_url}/{index}", "DELETE", None, "application/json")
|
||||
|
||||
|
||||
@unittest.skipUnless(os.getenv("AKYLDASH_OPENSEARCH_URL"), "set AKYLDASH_OPENSEARCH_URL to run against local OpenSearch")
|
||||
class SearchRankingOpenSearchTest(unittest.TestCase):
|
||||
def test_generic_lease_query_ranks_general_civil_code_first(self):
|
||||
base_url = os.environ["AKYLDASH_OPENSEARCH_URL"].rstrip("/")
|
||||
index = os.getenv("AKYLDASH_OPENSEARCH_INDEX", "akyldash-fragments-v2")
|
||||
api = Api(base_url, index, Path("."))
|
||||
result = api.search({"q": ["расторжение договора аренды"], "language": ["ru"], "page_size": ["10"]})
|
||||
self.assertEqual(result["results"][0]["code"], "5")
|
||||
|
||||
|
||||
@unittest.skipUnless(
|
||||
os.getenv("AKYLDASH_OPENSEARCH_URL") and "," in os.getenv("AKYLDASH_OPENSEARCH_INDEX", ""),
|
||||
"set AKYLDASH_OPENSEARCH_URL and a comma-separated AKYLDASH_OPENSEARCH_INDEX for read-only multi-index search",
|
||||
)
|
||||
class SearchMultiIndexDfsOpenSearchTest(unittest.TestCase):
|
||||
def test_global_statistics_mode_accepts_read_only_multi_index_search(self):
|
||||
base_url = os.environ["AKYLDASH_OPENSEARCH_URL"].rstrip("/")
|
||||
index = os.environ["AKYLDASH_OPENSEARCH_INDEX"]
|
||||
api = Api(base_url, index, Path("."))
|
||||
result = api.search({"q": ["расторжение договора аренды"], "language": ["ru"], "page_size": ["10"]})
|
||||
self.assertIsInstance(result["results"], list)
|
||||
self.assertEqual(api.review_snapshots.verify(result["review_token"])["index_name"], index)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -5,6 +5,7 @@ from pathlib import Path
|
||||
from unittest.mock import patch
|
||||
|
||||
from search.evaluate_relevance import evaluate, load_queries
|
||||
from search.query import COMPANY_REGISTRATION_DOCUMENTS, LEASE_TERM_PHRASE_BOOST, TAX_PROFIT_DOCUMENTS, build_search_body, query_variants
|
||||
|
||||
|
||||
class SearchRelevanceTest(unittest.TestCase):
|
||||
@@ -28,18 +29,173 @@ class SearchRelevanceTest(unittest.TestCase):
|
||||
path.write_text(json.dumps(queries, ensure_ascii=False), encoding="utf-8")
|
||||
loaded = load_queries(path)
|
||||
|
||||
responses = [
|
||||
{"hits": {"hits": [{"_source": {"document_code": code}} for code in ["7", "10", "8"]]}},
|
||||
{"hits": {"hits": [{"_source": {"document_code": code}} for code in ["10", "9"]]}},
|
||||
]
|
||||
with patch("search.evaluate_relevance.request_json", side_effect=responses) as request:
|
||||
with patch("search.evaluate_relevance.search_documents", side_effect=[["7", "10", "8"], ["10", "9"]]):
|
||||
result = evaluate(loaded, "http://127.0.0.1:9200", "test", 10)
|
||||
|
||||
self.assertEqual(result["summary"], {"query_count": 2, "recall_at_10": 1.0, "mrr_at_10": 0.75})
|
||||
self.assertEqual(result["queries"][0]["reciprocal_rank_at_10"], 1.0)
|
||||
body = json.loads(request.call_args_list[0].args[2])
|
||||
body = json.loads(build_search_body("ru", "трудовой договор", 10))
|
||||
self.assertFalse(body["track_total_hits"])
|
||||
self.assertEqual(body["collapse"], {"field": "document_code"})
|
||||
self.assertIn({"term": {"is_current_edition": True}}, body["query"]["bool"]["filter"])
|
||||
lexical_query = body["query"]["bool"]["must"]["bool"]["should"][0]["multi_match"]
|
||||
self.assertEqual(lexical_query["type"], "cross_fields")
|
||||
self.assertEqual(lexical_query["fields"], ["document_name_ru^4", "text_ru"])
|
||||
self.assertEqual(lexical_query["operator"], "AND")
|
||||
self.assertTrue(any("match_phrase" in clause for clause in body["query"]["bool"]["must"]["bool"]["should"]))
|
||||
|
||||
def test_legal_form_abbreviations_expand_in_both_directions(self):
|
||||
self.assertIn("как открыть общество с ограниченной ответственностью", query_variants("ru", "как открыть ОсОО"))
|
||||
self.assertIn("регистрация осоо", [variant.casefold() for variant in query_variants("ru", "регистрация общества с ограниченной ответственностью")])
|
||||
self.assertIn("жчк ачуу тартиби", [variant.casefold() for variant in query_variants("ky", "жоопкерчилиги чектелген коом ачуу тартиби")])
|
||||
|
||||
def test_russian_lease_phrase_expands_only_the_exact_legal_construction(self):
|
||||
original = "расторжение договора аренды"
|
||||
variants = query_variants("ru", original)
|
||||
self.assertEqual(variants[0], original)
|
||||
self.assertIn("расторжение договора имущественного найма", variants)
|
||||
body = json.loads(build_search_body("ru", original, 10))
|
||||
clauses = body["query"]["bool"]["must"]["bool"]["should"]
|
||||
full_text = [item["multi_match"]["query"] for item in clauses if "multi_match" in item and item["multi_match"].get("operator") == "AND"]
|
||||
self.assertEqual(full_text, variants)
|
||||
phrase_matches = [item["match_phrase"]["text_ru"] for item in clauses if "match_phrase" in item]
|
||||
self.assertEqual([item["boost"] for item in phrase_matches], [3, LEASE_TERM_PHRASE_BOOST])
|
||||
|
||||
for query in (
|
||||
"аренда квартиры",
|
||||
"расторжение договора аренды квартиры",
|
||||
"договор аренды земельного участка",
|
||||
"договор поднайма",
|
||||
"договор аренды с правом поднайма",
|
||||
"наем работника",
|
||||
"договор лизинга",
|
||||
):
|
||||
self.assertEqual(query_variants("ru", query), [query])
|
||||
|
||||
self.assertEqual(query_variants("ky", "договор аренды"), ["договор аренды"])
|
||||
|
||||
self.assertEqual(
|
||||
query_variants("ru", "договору аренды"),
|
||||
["договору аренды", "договору имущественного найма"],
|
||||
)
|
||||
|
||||
def test_relaxed_match_drops_ru_template_prefix_and_stays_low_weight(self):
|
||||
body = json.loads(build_search_body("ru", "правовое регулирование расторжение договора аренды", 10))
|
||||
clauses = body["query"]["bool"]["must"]["bool"]["should"]
|
||||
strict = [item["multi_match"] for item in clauses if "multi_match" in item and item["multi_match"].get("operator") == "AND"]
|
||||
relaxed = [item["multi_match"] for item in clauses if "multi_match" in item and item["multi_match"].get("boost") == 0.1]
|
||||
self.assertEqual(strict[0]["query"], "правовое регулирование расторжение договора аренды")
|
||||
self.assertEqual(relaxed[0]["query"], "расторжение договора аренды")
|
||||
self.assertEqual(relaxed[0]["operator"], "OR")
|
||||
self.assertEqual(relaxed[0]["minimum_should_match"], 2)
|
||||
self.assertNotIn("boost", strict[0])
|
||||
|
||||
def test_relaxed_match_supports_kyrgyz_and_avoids_short_named_acts(self):
|
||||
ky = json.loads(build_search_body("ky", "эмгек келишимин бузуу шарттары", 10))
|
||||
ky_clauses = ky["query"]["bool"]["must"]["bool"]["should"]
|
||||
self.assertTrue(any(item.get("multi_match", {}).get("operator") == "OR" and item["multi_match"].get("boost") == 0.1 for item in ky_clauses))
|
||||
|
||||
named_act = json.loads(build_search_body("ru", "Гражданский кодекс", 10))
|
||||
act_clauses = named_act["query"]["bool"]["must"]["bool"]["should"]
|
||||
self.assertFalse(any(item.get("multi_match", {}).get("boost") == 0.1 for item in act_clauses))
|
||||
|
||||
long_named_act = json.loads(build_search_body("ru", "последние изменения Гражданского кодекса Кыргызской Республики", 10))
|
||||
long_act_clauses = long_named_act["query"]["bool"]["must"]["bool"]["should"]
|
||||
self.assertFalse(any(item.get("multi_match", {}).get("boost") == 0.1 for item in long_act_clauses))
|
||||
|
||||
short_template = json.loads(build_search_body("ru", "как регулируется взыскание алиментов", 10))
|
||||
short_clauses = short_template["query"]["bool"]["must"]["bool"]["should"]
|
||||
short_fallback = next(item["multi_match"] for item in short_clauses if item.get("multi_match", {}).get("boost") == 0.1)
|
||||
self.assertEqual(short_fallback["query"], "взыскание алиментов")
|
||||
self.assertEqual(short_fallback["minimum_should_match"], 2)
|
||||
|
||||
stopword_query = json.loads(build_search_body("ru", "правовое регулирование права и обязанности", 10))
|
||||
stopword_clauses = stopword_query["query"]["bool"]["must"]["bool"]["should"]
|
||||
stopword_fallback = next(item["multi_match"] for item in stopword_clauses if item.get("multi_match", {}).get("boost") == 0.1)
|
||||
self.assertEqual(stopword_fallback["minimum_should_match"], 2)
|
||||
|
||||
for language, query in (("ru", "последние изменения ГК КР"), ("ky", "Кыргыз Республикасынын Конституциясы")):
|
||||
act_body = json.loads(build_search_body(language, query, 10))
|
||||
act_clauses = act_body["query"]["bool"]["must"]["bool"]["should"]
|
||||
self.assertFalse(any(item.get("multi_match", {}).get("boost") == 0.1 for item in act_clauses))
|
||||
|
||||
for language, query, expected in (
|
||||
("ru", "Налоговый кодекс ответственность за неуплату налога", "ответственность за неуплату налога"),
|
||||
("ru", "Налоговый кодекс налоговая ставка", "налоговая ставка"),
|
||||
("ru", "Налоговый кодекс: налоговая ставка", "налоговая ставка"),
|
||||
("ru", "закон о труде порядок выплаты зарплаты", "порядок выплаты зарплаты"),
|
||||
("ky", "Кыргыз Республикасынын Конституциясы укуктарды чектөө тартиби", "укуктарды чектөө тартиби"),
|
||||
):
|
||||
body = json.loads(build_search_body(language, query, 10))
|
||||
clauses = body["query"]["bool"]["must"]["bool"]["should"]
|
||||
fallback = next(item["multi_match"] for item in clauses if item.get("multi_match", {}).get("boost") == 0.1)
|
||||
self.assertEqual(fallback["query"], expected)
|
||||
|
||||
for query in (
|
||||
"Закон о защите прав потребителей",
|
||||
"Закон Кыргызской Республики о защите прав потребителей",
|
||||
"Закон Кыргызской Республики о государственной регистрации юридических лиц",
|
||||
):
|
||||
body = json.loads(build_search_body("ru", query, 10))
|
||||
clauses = body["query"]["bool"]["must"]["bool"]["should"]
|
||||
self.assertFalse(any(item.get("multi_match", {}).get("boost") == 0.1 for item in clauses))
|
||||
|
||||
consumer_rights = json.loads(build_search_body("ru", "Закон о защите прав потребителей возврат денег", 10))
|
||||
consumer_clauses = consumer_rights["query"]["bool"]["must"]["bool"]["should"]
|
||||
consumer_fallback = next(item["multi_match"] for item in consumer_clauses if item.get("multi_match", {}).get("boost") == 0.1)
|
||||
self.assertEqual(consumer_fallback["query"], "возврат денег")
|
||||
|
||||
def test_company_registration_intent_boosts_current_documents(self):
|
||||
for language, query, status in (
|
||||
("ru", "как открыть ОсОО", "Действует"),
|
||||
("ky", "ЖЧК ачуу тартиби", "Күчүндө"),
|
||||
):
|
||||
body = json.loads(build_search_body(language, query, 10))
|
||||
search_query = body["query"]["bool"]["must"]["bool"]
|
||||
self.assertEqual(search_query["minimum_should_match"], 1)
|
||||
self.assertNotIn("filter", search_query)
|
||||
lexical = [clause["multi_match"] for clause in search_query["should"] if "multi_match" in clause]
|
||||
self.assertTrue(all(clause["type"] == "cross_fields" and clause["operator"] == "OR" for clause in lexical))
|
||||
boosts = [clause["constant_score"] for clause in search_query["should"] if "constant_score" in clause]
|
||||
self.assertEqual([item["boost"] for item in boosts], [boost for _, boost in COMPANY_REGISTRATION_DOCUMENTS])
|
||||
self.assertEqual(
|
||||
[item["filter"]["bool"]["filter"][0]["term"]["document_code"] for item in boosts],
|
||||
[code for code, _ in COMPANY_REGISTRATION_DOCUMENTS],
|
||||
)
|
||||
self.assertTrue(all(item["filter"]["bool"]["filter"][1] == {"term": {f"status_{language}": status}} for item in boosts))
|
||||
|
||||
def test_profit_tax_intent_prioritizes_the_current_tax_code(self):
|
||||
for query in ("налог на прибыль", "налога на прибыль организаций", "налогообложение прибыли"):
|
||||
body = json.loads(build_search_body("ru", query, 10))
|
||||
clauses = body["query"]["bool"]["must"]["bool"]["should"]
|
||||
boosts = [clause["constant_score"] for clause in clauses if "constant_score" in clause]
|
||||
self.assertEqual([item["boost"] for item in boosts], [boost for _, boost in TAX_PROFIT_DOCUMENTS])
|
||||
self.assertEqual([item["filter"]["bool"]["filter"][0]["term"]["document_code"] for item in boosts], ["112340"])
|
||||
self.assertTrue(all(item["filter"]["bool"]["filter"][1] == {"term": {"status_ru": "Действует"}} for item in boosts))
|
||||
|
||||
for query in ("прибыль организации", "налог на доходы", "налог на имущество"):
|
||||
body = json.loads(build_search_body("ru", query, 10))
|
||||
clauses = body["query"]["bool"]["must"]["bool"]["should"]
|
||||
self.assertFalse(any("constant_score" in clause for clause in clauses))
|
||||
|
||||
def test_company_registration_intent_ignores_non_procedural_queries(self):
|
||||
for language, query in (
|
||||
("ru", "ОсОО зарегистрирован?"),
|
||||
("ru", "кто зарегистрировал ОсОО"),
|
||||
("ru", "как открыть счет ОсОО"),
|
||||
("ru", "как открыть ОсОО банковский счет"),
|
||||
("ru", "как открыть ОсОО банковский счёт"),
|
||||
("ru", "как открыть филиал ОсОО"),
|
||||
("ru", "как создать договор для ОсОО"),
|
||||
("ru", "порядок создания логотипа ОсОО"),
|
||||
("ky", "ЖЧК ачык маалымат"),
|
||||
("ky", "ЖЧК кантип банк эсебин ачуу"),
|
||||
("ky", "ЖЧК кантип келишим түзүү"),
|
||||
("ky", "ЖЧК кантип логотип түзүү"),
|
||||
):
|
||||
body = json.loads(build_search_body(language, query, 10))
|
||||
clauses = body["query"]["bool"]["must"]["bool"]["should"]
|
||||
self.assertFalse(any("constant_score" in clause for clause in clauses))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
@@ -0,0 +1,174 @@
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
from unittest.mock import patch
|
||||
|
||||
from search.api import Api, ApiError, SEARCH_ALGORITHM_VERSION
|
||||
|
||||
|
||||
class SearchReviewTest(unittest.TestCase):
|
||||
def test_multi_index_snapshot_and_saved_review_preserve_configured_scope(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
api = Api("http://opensearch:9200", "A,B", Path(temporary), Path(temporary) / "reviews.sqlite3", b"test-secret")
|
||||
cases = (
|
||||
("no hits", []),
|
||||
("A only", [{"_index": "A", "_source": {"document_code": "7", "document_name_ru": "Закон A"}}]),
|
||||
("B only", [{"_index": "B", "_source": {"document_code": "8", "document_name_ru": "Закон B"}}]),
|
||||
("mixed", [
|
||||
{"_index": "A", "_source": {"document_code": "7", "document_name_ru": "Закон A"}},
|
||||
{"_index": "B", "_source": {"document_code": "8", "document_name_ru": "Закон B"}},
|
||||
]),
|
||||
)
|
||||
for label, hits in cases:
|
||||
with self.subTest(case=label):
|
||||
with patch("search.api.request_json", return_value={"hits": {"hits": hits}}):
|
||||
result = api.handle("GET", "/search?q=test&language=ru")[1]
|
||||
token = result["review_token"]
|
||||
self.assertEqual(api.review_snapshots.verify(token)["index_name"], "A,B")
|
||||
review_results = [
|
||||
{"rank": rank, "code": item["code"], "rating": 3}
|
||||
for rank, item in enumerate(result["results"], 1)
|
||||
]
|
||||
api.handle("POST", "/search-reviews", {
|
||||
"review_token": token,
|
||||
"reviewer": "Юрист",
|
||||
"results": review_results,
|
||||
"overall_comment": "Проверена выдача для настроенного scope.",
|
||||
})
|
||||
saved = api.handle("GET", "/search-reviews/export")[1]["reviews"][-1]
|
||||
self.assertEqual(saved["index_name"], "A,B")
|
||||
|
||||
def test_review_must_cover_each_snapshot_rank_once(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
api = Api("http://opensearch:9200", "current", Path(temporary), Path(temporary) / "reviews.sqlite3", b"test-secret")
|
||||
response = {"hits": {"hits": [{"_index": "search-20260827", "_source": {"document_code": "7", "edition_code": "10", "document_name_ru": "Закон"}}, {"_index": "search-20260827", "_source": {"document_code": "8", "edition_code": "11", "document_name_ru": "Кодекс"}}]}}
|
||||
with patch("search.api.request_json", return_value=response):
|
||||
result = api.handle("GET", "/search?q=test&language=ru&page_size=2")[1]
|
||||
with self.assertRaisesRegex(ApiError, "exactly once"):
|
||||
api.handle("POST", "/search-reviews", {"review_token": result["review_token"], "reviewer": "Юрист", "results": []})
|
||||
with self.assertRaisesRegex(ApiError, "exactly once"):
|
||||
api.handle("POST", "/search-reviews", {"review_token": result["review_token"], "reviewer": "Юрист", "results": [{"rank": 1, "code": "7", "rating": 3}]})
|
||||
|
||||
def test_invalid_rank_types_and_sets_are_rejected_as_bad_requests(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
api = Api("http://opensearch:9200", "current", Path(temporary), review_secret=b"test-secret")
|
||||
response = {"hits": {"hits": [
|
||||
{"_source": {"document_code": "7", "edition_code": "10", "document_name_ru": "Закон"}},
|
||||
{"_source": {"document_code": "8", "edition_code": "11", "document_name_ru": "Кодекс"}},
|
||||
]}}
|
||||
with patch("search.api.request_json", return_value=response):
|
||||
result = api.handle("GET", "/search?q=test&language=ru&page_size=2")[1]
|
||||
token = result["review_token"]
|
||||
|
||||
malformed = [
|
||||
{"rank": True, "code": "7", "rating": 3},
|
||||
{"rank": [1], "code": "7", "rating": 3},
|
||||
{"rank": {"value": 1}, "code": "7", "rating": 3},
|
||||
{"rank": None, "code": "7", "rating": 3},
|
||||
{"rank": "1", "code": "7", "rating": 3},
|
||||
{"rank": 1.0, "code": "7", "rating": 3},
|
||||
None,
|
||||
]
|
||||
for item in malformed:
|
||||
with self.subTest(item=item):
|
||||
with self.assertRaises(ApiError) as raised:
|
||||
api.handle("POST", "/search-reviews", {"review_token": token, "reviewer": "Юрист", "results": [item]})
|
||||
self.assertEqual(raised.exception.status, 400)
|
||||
|
||||
for submitted in (
|
||||
[],
|
||||
[{"rank": 1, "code": "7", "rating": 3}, {"rank": 1, "code": "7", "rating": 3}],
|
||||
[{"rank": 1, "code": "7", "rating": 3}, {"rank": 3, "code": "8", "rating": 3}],
|
||||
[{"rank": 1, "code": "7", "rating": 3}],
|
||||
{"rank": 1, "code": "7", "rating": 3},
|
||||
):
|
||||
with self.subTest(submitted=submitted):
|
||||
with self.assertRaises(ApiError) as raised:
|
||||
api.handle("POST", "/search-reviews", {"review_token": token, "reviewer": "Юрист", "results": submitted})
|
||||
self.assertEqual(raised.exception.status, 400)
|
||||
|
||||
oversized = [{"rank": 1, "code": "7", "rating": 3}] * 101
|
||||
with self.assertRaises(ApiError) as raised:
|
||||
api.handle("POST", "/search-reviews", {"review_token": token, "reviewer": "Юрист", "results": oversized})
|
||||
self.assertEqual(raised.exception.status, 400)
|
||||
|
||||
def test_saves_signed_search_snapshot_and_rejects_tampering(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
api = Api("http://opensearch:9200", "current", Path(temporary), Path(temporary) / "reviews.sqlite3", b"test-secret")
|
||||
response = {"hits": {"hits": [{"_index": "search-20260827", "_source": {"document_code": "7", "edition_code": "10", "document_name_ru": "Закон"}}]}}
|
||||
with patch("search.api.request_json", return_value=response):
|
||||
result = api.handle("GET", "/search?q=%D0%B7%D0%B0%D0%BA%D0%BE%D0%BD&language=ru")[1]
|
||||
self.assertEqual(api.review_snapshots.verify(result["review_token"])["index_name"], "search-20260827")
|
||||
saved = api.handle("POST", "/search-reviews", {"review_token": result["review_token"], "reviewer": "Юрист", "results": [{"rank": 1, "code": "7", "rating": 3, "comment": "Прямой ответ"}]})
|
||||
self.assertEqual(saved[0], 201)
|
||||
exported = api.handle("GET", "/search-reviews/export")[1]["reviews"]
|
||||
self.assertEqual(exported[0]["index_name"], "search-20260827")
|
||||
self.assertEqual(exported[0]["top_result_code"], "7")
|
||||
self.assertEqual(exported[0]["results"][0]["rating"], 3)
|
||||
with self.assertRaisesRegex(ApiError, "does not match"):
|
||||
api.handle("POST", "/search-reviews", {"review_token": result["review_token"], "reviewer": "Юрист", "results": [{"rank": 1, "code": "8", "rating": 3}]})
|
||||
|
||||
def test_saves_signed_empty_snapshot_with_query_level_comment(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
api = Api("http://opensearch:9200", "current", Path(temporary), Path(temporary) / "reviews.sqlite3", b"test-secret")
|
||||
with patch("search.api.request_json", return_value={"hits": {"hits": []}}):
|
||||
result = api.handle("GET", "/search?q=редкий+запрос&language=ru")[1]
|
||||
self.assertEqual(api.review_snapshots.verify(result["review_token"])["index_name"], "current")
|
||||
body = {
|
||||
"review_token": result["review_token"],
|
||||
"reviewer": "Юрист",
|
||||
"overall_comment": "Пустая выдача подтверждена.",
|
||||
"results": [],
|
||||
}
|
||||
with self.assertRaisesRegex(ApiError, "overall_comment is required"):
|
||||
api.handle("POST", "/search-reviews", {**body, "overall_comment": ""})
|
||||
saved = api.handle("POST", "/search-reviews", body)
|
||||
self.assertEqual(saved[0], 201)
|
||||
review = api.handle("GET", "/search-reviews/export")[1]["reviews"][0]
|
||||
self.assertIsNone(review["top_result_code"])
|
||||
self.assertEqual(review["results"], [])
|
||||
self.assertEqual(review["overall_comment"], body["overall_comment"])
|
||||
|
||||
def test_review_page_enables_query_level_review_for_empty_results(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
api = Api("http://opensearch:9200", "current", Path(temporary))
|
||||
page = api.review_page()
|
||||
self.assertIn("state.results.length ? 'Сохранить оценку' : 'Сохранить пустую выдачу'", page)
|
||||
self.assertIn("aria-required', String(!state.results.length)", page)
|
||||
self.assertIn("const results = state.results.map((result, index) => { const item", page)
|
||||
|
||||
def test_snapshot_and_review_page_are_available(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
api = Api("http://opensearch:9200", "current", Path(temporary))
|
||||
page = api.review_page()
|
||||
self.assertIn("Оценка поисковой выдачи", page)
|
||||
self.assertIn("akyldash-search-review-draft", page)
|
||||
self.assertIn("tutorial-dialog", page)
|
||||
self.assertIn("Как это работает", page)
|
||||
self.assertNotIn('id="error"', page)
|
||||
self.assertIn("localStorage", page)
|
||||
|
||||
def test_new_search_snapshots_use_search_8_without_invalidating_search_7(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
api = Api("http://opensearch:9200", "current", Path(temporary), Path(temporary) / "reviews.sqlite3", b"test-secret")
|
||||
with patch("search.api.request_json", return_value={"hits": {"hits": [{"_index": "current-v2", "_source": {"document_code": "7", "document_name_ru": "Закон"}}]}}):
|
||||
result = api.handle("GET", "/search?q=test&language=ru")[1]
|
||||
current = api.review_snapshots.verify(result["review_token"])
|
||||
self.assertEqual(SEARCH_ALGORITHM_VERSION, "search-8")
|
||||
self.assertEqual(current["algorithm_version"], "search-8")
|
||||
|
||||
legacy_token = api.review_snapshots.create(
|
||||
"legacy query", "ru", "current-v1", [{"rank": 1, "code": "7"}], "search-7"
|
||||
)
|
||||
legacy_saved = api.handle("POST", "/search-reviews", {
|
||||
"review_token": legacy_token,
|
||||
"reviewer": "Юрист",
|
||||
"results": [{"rank": 1, "code": "7", "rating": 3}],
|
||||
})
|
||||
self.assertEqual(legacy_saved[0], 201)
|
||||
exported = api.handle("GET", "/search-reviews/export")[1]["reviews"]
|
||||
self.assertEqual(exported[-1]["algorithm_version"], "search-7")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,102 @@
|
||||
import json
|
||||
import sqlite3
|
||||
import tempfile
|
||||
import unittest
|
||||
from contextlib import closing
|
||||
from pathlib import Path
|
||||
|
||||
from tools.build_search_topic_taxonomy import build, group_for
|
||||
|
||||
|
||||
class SearchTopicTaxonomyTest(unittest.TestCase):
|
||||
def test_ambiguous_roots_are_left_for_manual_review(self):
|
||||
self.assertEqual(group_for("Иностранные инвестиции"), "review_required")
|
||||
|
||||
def test_preserves_source_tree_counts_and_marks_unclassified_roots(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
root = Path(temporary)
|
||||
(root / "documents/1").mkdir(parents=True)
|
||||
(root / "documents/2").mkdir(parents=True)
|
||||
with closing(sqlite3.connect(root / "manifest.sqlite3")) as db:
|
||||
db.execute("CREATE TABLE documents (code TEXT, state TEXT)")
|
||||
db.executemany("INSERT INTO documents VALUES (?, 'success')", [("1",), ("2",)])
|
||||
db.commit()
|
||||
classifier = {
|
||||
"Code": None,
|
||||
"Name": {"Rus": "ЗАКОНОДАТЕЛЬСТВО О ТРУДЕ", "Kyr": None},
|
||||
"GeneralClassifiers": [{
|
||||
"Code": "child-1",
|
||||
"Name": {"Rus": "Рабочее время", "Kyr": "Иш убактысы"},
|
||||
"GeneralClassifiers": [],
|
||||
}],
|
||||
}
|
||||
unknown = {
|
||||
"Code": None,
|
||||
"Name": {"Rus": "НЕИЗВЕСТНАЯ РУБРИКА", "Kyr": None},
|
||||
"GeneralClassifiers": [],
|
||||
}
|
||||
(root / "documents/1/document.json").write_text(
|
||||
json.dumps({"general_classifiers": [classifier]}, ensure_ascii=False),
|
||||
encoding="utf-8",
|
||||
)
|
||||
(root / "documents/2/document.json").write_text(
|
||||
json.dumps({"general_classifiers": [classifier, unknown]}, ensure_ascii=False),
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
catalog = build(root)
|
||||
groups = {group["code"]: group for group in catalog["groups"]}
|
||||
labor_root = groups["labor_social"]["children"][0]
|
||||
|
||||
self.assertEqual((catalog["source_document_count"], catalog["source_node_count"], catalog["source_root_count"]), (2, 3, 2))
|
||||
self.assertEqual(labor_root["document_count"], 2)
|
||||
self.assertEqual(labor_root["children"][0]["document_count"], 2)
|
||||
self.assertEqual(groups["review_required"]["children"][0]["grouping_status"], "manual_review")
|
||||
self.assertEqual(catalog["nodes_missing_kyrgyz_label"], 2)
|
||||
|
||||
def test_rebuild_fails_instead_of_omitting_successful_manifest_document(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
root = Path(temporary)
|
||||
(root / "documents/1").mkdir(parents=True)
|
||||
with closing(sqlite3.connect(root / "manifest.sqlite3")) as db:
|
||||
db.execute("CREATE TABLE documents (code TEXT, state TEXT)")
|
||||
db.execute("INSERT INTO documents VALUES ('1', 'success')")
|
||||
db.commit()
|
||||
|
||||
with self.assertRaisesRegex(RuntimeError, "normalized document 1"):
|
||||
build(root)
|
||||
|
||||
def test_rebuild_rejects_normalized_document_without_classifier_list(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
root = Path(temporary)
|
||||
document = root / "documents/1"
|
||||
document.mkdir(parents=True)
|
||||
with closing(sqlite3.connect(root / "manifest.sqlite3")) as db:
|
||||
db.execute("CREATE TABLE documents (code TEXT, state TEXT)")
|
||||
db.execute("INSERT INTO documents VALUES ('1', 'success')")
|
||||
db.commit()
|
||||
(document / "document.json").write_text("{}", encoding="utf-8")
|
||||
|
||||
with self.assertRaisesRegex(RuntimeError, "general_classifiers list"):
|
||||
build(root)
|
||||
|
||||
def test_rebuild_rejects_invalid_nested_classifier_branch(self):
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
root = Path(temporary)
|
||||
document = root / "documents/1"
|
||||
document.mkdir(parents=True)
|
||||
with closing(sqlite3.connect(root / "manifest.sqlite3")) as db:
|
||||
db.execute("CREATE TABLE documents (code TEXT, state TEXT)")
|
||||
db.execute("INSERT INTO documents VALUES ('1', 'success')")
|
||||
db.commit()
|
||||
(document / "document.json").write_text(
|
||||
json.dumps({"general_classifiers": [{"Name": {"Rus": "Корень"}, "GeneralClassifiers": "bad"}]}),
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
with self.assertRaisesRegex(RuntimeError, "non-list GeneralClassifiers branch"):
|
||||
build(root)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,9 @@
|
||||
# Absolute path on the production host containing minjust-normalized/.
|
||||
DATA_ROOT=/var/lib/akyldash/data
|
||||
REVIEW_SECRET_FILE=/etc/akyldash/review_secret
|
||||
BACKEND_IMAGE=akyldash/backend:local
|
||||
OPENSEARCH_IMAGE=akyldash/opensearch:local
|
||||
SEARCH_INDEX=akyldash-fragments-current
|
||||
OPENSEARCH_MEM_LIMIT=4g
|
||||
OPENSEARCH_JAVA_OPTS=-Xms2g -Xmx2g
|
||||
COOKIE_SECURE=true
|
||||
@@ -0,0 +1,4 @@
|
||||
akyldash.kg {
|
||||
encode zstd gzip
|
||||
reverse_proxy backend:8080
|
||||
}
|
||||
@@ -0,0 +1,11 @@
|
||||
FROM python:3.12-slim
|
||||
|
||||
WORKDIR /app
|
||||
COPY backend /app/backend
|
||||
|
||||
ENV PYTHONPATH=/app/backend
|
||||
EXPOSE 8080
|
||||
|
||||
CMD ["python", "-m", "search.api", "--host", "0.0.0.0", "--port", "8080", "--url", "http://opensearch:9200", "--index", "akyldash-fragments-current", "--data", "/app/data/minjust-normalized", "--reviews-db", "/app/data/search-reviews.sqlite3"]
|
||||
|
||||
HEALTHCHECK --interval=30s --timeout=5s --start-period=20s CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/review', timeout=3)"]
|
||||
@@ -0,0 +1,3 @@
|
||||
FROM opensearchproject/opensearch:3.7.0
|
||||
|
||||
RUN /usr/share/opensearch/bin/opensearch-plugin install --batch analysis-icu
|
||||
@@ -0,0 +1,164 @@
|
||||
# Production deployment
|
||||
|
||||
Compose runs Caddy, the Search API, and a private OpenSearch node. Only Caddy
|
||||
publishes ports `80` and `443`; backend and OpenSearch have no host ports. The
|
||||
OpenSearch security plugin is disabled to match the current API client, so keep
|
||||
it on the private network.
|
||||
|
||||
## Host access and configuration
|
||||
|
||||
The production environment file is `/etc/akyldash/production.env`; the review
|
||||
secret is `/etc/akyldash/review_secret`. Both must stay outside the checkout,
|
||||
root-owned, and mode `0600`. `DATA_ROOT` must be an absolute path. The `codex`
|
||||
account is intentionally outside the `sudo` and `docker` groups because access
|
||||
to the Docker socket grants root-equivalent control. Run host operations with
|
||||
the narrowly required `sudo` command; do not use `docker` as `codex` directly.
|
||||
|
||||
After reviewing the host audit and confirming these files do not already exist,
|
||||
the owner can create them from the approved checkout with
|
||||
`sudo bash infra/deploy/prepare-production-config.sh`. The script refuses to
|
||||
overwrite existing configuration, installs the tracked env example with mode
|
||||
`0600`, and generates a random review secret with mode `0600`. It does not
|
||||
start Compose or create volumes. Review and set `DATA_ROOT` in the protected
|
||||
env file before deployment.
|
||||
|
||||
Set `DATA_ROOT` to the approved data directory and ensure the normalized corpus
|
||||
is at `$DATA_ROOT/minjust-normalized/`. The first host setup is documented in
|
||||
[`docs/operations/DEPLOYMENT.md`](../../docs/operations/DEPLOYMENT.md); the
|
||||
root bootstrap installs packages and creates directories, but does not deploy
|
||||
the application or alter SSH, firewall, user groups, or sudoers. The restricted
|
||||
`akyldash-compose` helper allows only root-owned Compose `config` and `status`;
|
||||
service start/stop remains an owner-run root operation.
|
||||
|
||||
The repository Gitea Actions runner is an isolated CI worker described in
|
||||
[`docs/operations/CI_RUNNER.md`](../../docs/operations/CI_RUNNER.md). It has no
|
||||
production Docker socket, production env files, or application checkout. CI
|
||||
does not deploy or change production; all deployment remains owner-run.
|
||||
|
||||
## First deployment and upgrades
|
||||
|
||||
Run commands from the root-owned checkout at `/opt/akyldash/current`. Render
|
||||
and review Compose before changing services:
|
||||
|
||||
```bash
|
||||
cd /opt/akyldash/current
|
||||
sudo docker compose --env-file /etc/akyldash/production.env -f deploy/production/compose.yaml config --quiet
|
||||
```
|
||||
|
||||
On a clean first deployment, `infra/backup/archive.py create` reports that no
|
||||
backup is required when all persistent mounts are empty and no Compose
|
||||
containers exist. Continue without a backup in that case. If any persistent
|
||||
data exists, create and verify a backup before changing schema, images, or
|
||||
starting a new application version. This also applies when containers are
|
||||
absent, including an initial installation where the normalized corpus was
|
||||
preloaded under `DATA_ROOT`; create the archive before the first `up`. When
|
||||
named volumes do not exist, pass `--initial-deployment`; this is accepted only
|
||||
without Compose containers and when `DATA_ROOT` contains only
|
||||
`minjust-normalized/`. During upgrades, missing volumes are an error because
|
||||
they can indicate lost production data. The archive tool also refuses
|
||||
ambiguous storage state, running containers, and incomplete Compose service
|
||||
containers. See
|
||||
[`docs/operations/BACKUP.md`](../../docs/operations/BACKUP.md) for the exact
|
||||
commands. Do not remove an older usable backup to make room; retain the
|
||||
pre-change archive until the new deployment and a newer verified backup are
|
||||
confirmed.
|
||||
|
||||
For an initial clean installation, start the stack only after config review:
|
||||
|
||||
```bash
|
||||
sudo docker compose --env-file /etc/akyldash/production.env -f deploy/production/compose.yaml up -d --build
|
||||
sudo docker compose --env-file /etc/akyldash/production.env -f deploy/production/compose.yaml ps
|
||||
curl -fsS https://akyldash.kg/review >/dev/null
|
||||
```
|
||||
|
||||
Before this step, confirm DNS and have the owner review firewall rules for TCP
|
||||
`80` and `443`. Caddy manages the origin certificate; confirm HTTPS before
|
||||
setting Cloudflare to Full (strict). On the initial start, create the `admin`
|
||||
account interactively:
|
||||
|
||||
```bash
|
||||
sudo docker compose --env-file /etc/akyldash/production.env -f deploy/production/compose.yaml exec backend python -m search.api --create-admin
|
||||
```
|
||||
|
||||
The account database is `$DATA_ROOT/search-users.sqlite3` and is included in
|
||||
the `data` backup. Admin password reset is also interactive:
|
||||
|
||||
```bash
|
||||
sudo docker compose --env-file /etc/akyldash/production.env -f deploy/production/compose.yaml exec backend python -m search.api --reset-admin-password
|
||||
```
|
||||
|
||||
After the initial OpenSearch index is loaded and validated, the `admin` account
|
||||
is created, and `/review` works over HTTPS, create and verify the required
|
||||
post-setup baseline backup before treating deployment as complete. It captures
|
||||
the initialized index, account database, and Caddy certificate data. Follow
|
||||
the exact stop/create/verify/start sequence in
|
||||
[`docs/operations/BACKUP.md`](../../docs/operations/BACKUP.md#initial-post-setup-baseline).
|
||||
|
||||
## Backup, restore, and rollback
|
||||
|
||||
Backups are cold and require downtime. Stop services, create the archive, then
|
||||
verify both its checksum and contents before proceeding. Do not run an upgrade
|
||||
or schema change until verification succeeds. Keep archives root-only under
|
||||
`/var/backups/akyldash` and copy them to separately managed encrypted storage.
|
||||
|
||||
Restore is a staged operation on a marked replacement host; it does not
|
||||
overwrite production. For application-only rollback, use the guarded helper
|
||||
with a verified pre-release backup and explicit data-compatibility review.
|
||||
Follow the procedures in [`BACKUP.md`](../../docs/operations/BACKUP.md),
|
||||
[`ROLLBACK.md`](../../docs/operations/ROLLBACK.md), and
|
||||
[`RECOVERY.md`](../../docs/operations/RECOVERY.md).
|
||||
|
||||
Automated production deployment is not enabled. Deployments remain owner-run;
|
||||
record the release and verify service health before considering it complete.
|
||||
|
||||
## Image release and owner-run cutover
|
||||
|
||||
PR CI still builds both production images with Kaniko `--no-push`. The separate
|
||||
`Release production images` workflow is manual and runs only when dispatched
|
||||
from protected `main`. It requires repository secrets named
|
||||
`REGISTRY_USERNAME` and `REGISTRY_PASSWORD`; without them it fails before any
|
||||
build. Configure those secrets only after the owner confirms a dedicated
|
||||
Gitea account/token with write access to the two repository packages and no
|
||||
unneeded administration rights. Do not reuse a runner or production host
|
||||
credential. The workflow uses the Gitea host and fixed package namespace
|
||||
`git.vakanaut.ru/admin/akyldash/{backend,opensearch}`, pushes unique
|
||||
commit/run-ID tags, captures registry digests, validates the release
|
||||
descriptor, and uploads the JSON plus SHA-256 sidecar as a Gitea Actions
|
||||
artifact using a full-SHA-pinned Gitea-compatible v3 action. PR CI also uploads
|
||||
a tiny synthetic marker with one-day retention to verify the runner's runtime
|
||||
artifact path without registry credentials. The runner cache stays disabled;
|
||||
artifact compatibility is based on the runtime API supported by act_runner
|
||||
0.2.13/Gitea 1.25.5 and will be empirically checked by PR CI. Registry and
|
||||
artifact retention must preserve release digests and descriptors for the full
|
||||
rollback window; the owner must confirm both policies.
|
||||
|
||||
The schema-v3 descriptor records source repository/ref/commit, workflow run ID,
|
||||
pinned Kaniko builder and both image digests. It is an unsigned trace record,
|
||||
not a cryptographic attestation; deployment relies on retrieving it from the
|
||||
authenticated Gitea run artifact and verifying its checksum and repository
|
||||
allowlist. Do not treat the sidecar alone as proof of authenticity.
|
||||
|
||||
For a future owner-approved cutover, use the root-owned checkout and run
|
||||
`infra/deploy/deploy_release.py` as root with the downloaded manifest, its
|
||||
matching verified cold backup, and `infra/deploy/release-policy.json`, plus
|
||||
owner-verified non-empty Russian and Kyrgyz canary queries, for example
|
||||
`--canary-ru '<known Russian query>' --canary-ky '<known Kyrgyz query>'`.
|
||||
The helper checks both queries against the public Search API through local
|
||||
HTTPS after Compose reports healthy, and requires at least one result with a
|
||||
document code before recording the new release state. Select queries only
|
||||
after corpus/index canaries have been verified; do not use generic terms that
|
||||
can match unrelated test data. The helper requires the backup image references and image IDs to match the live
|
||||
stack, serializes deploy and rollback with `/run/akyldash-deploy.lock`,
|
||||
atomically switches both protected env image refs, and always runs Compose with
|
||||
`--no-build`. It records recovery state before changing references. If ref
|
||||
replacement reports an error after an atomic rename, recovery rereads the
|
||||
actual file and restores the prior pair before restarting; an unexpected or
|
||||
unverifiable pair stops recovery and leaves a secret-free journal. A failed
|
||||
cutover refuses a subsequent release until an owner resolves the journal.
|
||||
Rollback accepts a digest-pinned previous release
|
||||
only when that backup matches the separately recorded previous refs and image
|
||||
IDs. Legacy tag rollback remains supported. Neither the helper nor registry
|
||||
secrets are installed on the VPS by this PR; deployment remains an owner-only
|
||||
operation and must wait for host/data/backup review. The exact sanitized
|
||||
evidence required from the owner is listed in
|
||||
[`DEPLOYMENT_OWNER_PACKET.md`](../../docs/operations/DEPLOYMENT_OWNER_PACKET.md).
|
||||
@@ -0,0 +1,124 @@
|
||||
name: akyldash
|
||||
|
||||
services:
|
||||
caddy:
|
||||
image: caddy:2.11.6-alpine@sha256:881bbc60f9986d5ab8e7cfd6cf7e4ef3c9c0439fef2429d035d065577882f028
|
||||
restart: unless-stopped
|
||||
logging:
|
||||
driver: local
|
||||
options:
|
||||
max-size: 10m
|
||||
max-file: "3"
|
||||
ports:
|
||||
- "80:80"
|
||||
- "443:443"
|
||||
volumes:
|
||||
- ./Caddyfile:/etc/caddy/Caddyfile:ro
|
||||
- caddy-data:/data
|
||||
- caddy-config:/config
|
||||
networks:
|
||||
- proxy
|
||||
depends_on:
|
||||
backend:
|
||||
condition: service_healthy
|
||||
healthcheck:
|
||||
test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:2019/config/"]
|
||||
interval: 30s
|
||||
timeout: 5s
|
||||
retries: 3
|
||||
|
||||
opensearch:
|
||||
image: ${OPENSEARCH_IMAGE:-akyldash/opensearch:local}
|
||||
build:
|
||||
context: ../..
|
||||
dockerfile: deploy/production/Dockerfile.opensearch
|
||||
restart: unless-stopped
|
||||
logging:
|
||||
driver: local
|
||||
options:
|
||||
max-size: 10m
|
||||
max-file: "3"
|
||||
environment:
|
||||
discovery.type: single-node
|
||||
bootstrap.memory_lock: "true"
|
||||
DISABLE_SECURITY_PLUGIN: "true"
|
||||
OPENSEARCH_JAVA_OPTS: ${OPENSEARCH_JAVA_OPTS:--Xms2g -Xmx2g}
|
||||
mem_limit: ${OPENSEARCH_MEM_LIMIT:-4g}
|
||||
expose:
|
||||
- "9200"
|
||||
ulimits:
|
||||
memlock:
|
||||
soft: -1
|
||||
hard: -1
|
||||
nofile:
|
||||
soft: 65536
|
||||
hard: 65536
|
||||
volumes:
|
||||
- opensearch-data:/usr/share/opensearch/data
|
||||
networks:
|
||||
- search
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:9200/_cluster/health || exit 1"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 10
|
||||
|
||||
backend:
|
||||
image: ${BACKEND_IMAGE:-akyldash/backend:local}
|
||||
build:
|
||||
context: ../..
|
||||
dockerfile: deploy/production/Dockerfile.backend
|
||||
restart: unless-stopped
|
||||
logging:
|
||||
driver: local
|
||||
options:
|
||||
max-size: 10m
|
||||
max-file: "3"
|
||||
environment:
|
||||
COOKIE_SECURE: ${COOKIE_SECURE:-true}
|
||||
command:
|
||||
- python
|
||||
- -m
|
||||
- search.api
|
||||
- --host
|
||||
- 0.0.0.0
|
||||
- --port
|
||||
- "8080"
|
||||
- --url
|
||||
- http://opensearch:9200
|
||||
- --index
|
||||
- ${SEARCH_INDEX:-akyldash-fragments-current}
|
||||
- --data
|
||||
- /app/data/minjust-normalized
|
||||
- --reviews-db
|
||||
- /app/data/search-reviews.sqlite3
|
||||
- --users-db
|
||||
- /app/data/search-users.sqlite3
|
||||
- --review-secret-file
|
||||
- /run/secrets/review_secret
|
||||
secrets:
|
||||
- review_secret
|
||||
expose:
|
||||
- "8080"
|
||||
depends_on:
|
||||
opensearch:
|
||||
condition: service_healthy
|
||||
volumes:
|
||||
- ${DATA_ROOT:?set DATA_ROOT in .env}:/app/data
|
||||
networks:
|
||||
- proxy
|
||||
- search
|
||||
|
||||
volumes:
|
||||
caddy-data:
|
||||
caddy-config:
|
||||
opensearch-data:
|
||||
|
||||
networks:
|
||||
proxy:
|
||||
search:
|
||||
internal: true
|
||||
|
||||
secrets:
|
||||
review_secret:
|
||||
file: ${REVIEW_SECRET_FILE:?set REVIEW_SECRET_FILE in .env}
|
||||
@@ -2,10 +2,23 @@
|
||||
|
||||
## Продукт
|
||||
|
||||
- [Дизайн-система «Түндүк»](../DESIGN.md) — утверждённые палитра,
|
||||
типографика, компоненты и правила адаптивности портала и лаборатории.
|
||||
- [Обзор проекта](product/project-overview.md) — назначение, основные области и
|
||||
правила работы с данными.
|
||||
- [Стратегическое сравнение с Токтом](product/platform-development-plan-toktom-2026-10-24.md) —
|
||||
продуктовая гипотеза и конкурентный анализ; это не план исполнения задач.
|
||||
- [План frontend поисковой СПС](product/frontend-search-sps-plan.md) — границы
|
||||
MVP, зависимости и спринты.
|
||||
- [Готовность к проектированию frontend](product/frontend-design-readiness-plan.md) —
|
||||
обязательные работы и критерии перехода к frontend.
|
||||
- [План реализации и приёмки](product/implementation-roadmap.md) — единая
|
||||
очередность UI и deployment gates, со статусом доказательств; не дублирует
|
||||
продуктовую стратегию или эксплуатационные процедуры.
|
||||
- [План интерфейса оценки поисковой выдачи](product/search-relevance-review-interface-plan.md) —
|
||||
внутренняя лаборатория сбора оценок юристов для настройки OpenSearch.
|
||||
- [Разметка relevance set](../backend/search/RELEVANCE_ANNOTATION.md) — подготовка
|
||||
эталонных документов и воспроизводимая оценка собственного поиска.
|
||||
- [Задание по нормализации документов](product/minjust-document-normalization-agent-task.md) —
|
||||
требования и критерии приёмки нормализатора ЦБД Минюста КР.
|
||||
|
||||
@@ -18,6 +31,15 @@
|
||||
|
||||
- [Текущий статус](operations/project-status.md) — выполненные шаги, риски и
|
||||
ближайшие действия.
|
||||
- [Состояние инфраструктуры](operations/CURRENT_STATE.md) — подтверждённое
|
||||
состояние production и оставшиеся проверки.
|
||||
- [Инфраструктура и эксплуатация](operations/INFRASTRUCTURE.md) — схема,
|
||||
доступы, deployment, backup, rollback и recovery.
|
||||
- [Операционные процедуры](operations/DEPLOYMENT.md) — связанные инструкции по
|
||||
deployment, [backup](operations/BACKUP.md), [rollback](operations/ROLLBACK.md),
|
||||
[recovery](operations/RECOVERY.md), обязательная процедура
|
||||
[передачи корпуса](operations/CORPUS_HANDOFF.md) и
|
||||
[пакет владельца](operations/DEPLOYMENT_OWNER_PACKET.md).
|
||||
- [План Telegram-пространства](operations/telegram-workspace-plan.md) — темы,
|
||||
роли и этапы развития командного окружения.
|
||||
|
||||
@@ -33,4 +55,4 @@
|
||||
|
||||
---
|
||||
|
||||
Акылдаш · Telegram-бот v0.2.2 · Backend v0.5.0 · Frontend — не создан
|
||||
Акылдаш · Telegram-бот v0.2.2 · Backend v0.13.4 · Frontend v0.3.4
|
||||
@@ -78,4 +78,4 @@ Telegram позволяет запретить пользователям отп
|
||||
|
||||
---
|
||||
|
||||
Акылдаш · Telegram-бот v0.2.2 · Backend v0.5.0 · Frontend — не создан
|
||||
Акылдаш · Telegram-бот v0.2.2 · Backend v0.7.1 · Frontend — не создан
|
||||
|
After Width: | Height: | Size: 140 KiB |
|
After Width: | Height: | Size: 1.5 MiB |
|
After Width: | Height: | Size: 133 KiB |
|
After Width: | Height: | Size: 157 KiB |
@@ -0,0 +1,174 @@
|
||||
# Delivery First: проверка изменений по риску
|
||||
|
||||
Эта политика помогает быстро принимать небольшие изменения и добавляет
|
||||
проверки там, где ошибка затрагивает пользователей, данные или границы
|
||||
безопасности. Класс риска выбирает глубину проверки; он не позволяет снять
|
||||
обязательную проверку, одобрение или защиту `main`.
|
||||
|
||||
## Порядок работы
|
||||
|
||||
1. До реализации укажи в PR `LOW`, `MEDIUM` или `HIGH` и коротко объясни
|
||||
причину. Если изменение пересекает несколько областей, выбери самый высокий
|
||||
класс. При неопределённости используй более высокий класс.
|
||||
2. Сначала проследи путь изменения от пользовательского/API входа до данных,
|
||||
внешних систем и отката. Для изменения поведения добавь регрессионный тест,
|
||||
который подтверждает конкретный контракт или прежний дефект.
|
||||
3. Запусти проверку именно затронутого поведения и обычный Gitea CI. Для UI
|
||||
дополнительно выполни `cd tools/frontend-visual-review && npm ci && npm test`;
|
||||
этот браузерный набор сейчас не входит в Gitea CI.
|
||||
4. В PR перечисли класс риска, команды и результаты, остаточные ограничения,
|
||||
а для high-risk — совместимость, угрозы и безопасный rollback. Не заявляй
|
||||
проверку, которой фактически не было.
|
||||
5. Ревьюер отделяет блокирующие дефекты от улучшений. Блокер должен указывать
|
||||
конкретное место, условие воспроизведения и последствие. Стилистические
|
||||
предпочтения и предложения на будущее фиксируются отдельно и не задерживают
|
||||
PR.
|
||||
|
||||
## Классы риска
|
||||
|
||||
| Класс | Когда применять | Требуемое подтверждение |
|
||||
|---|---|---|
|
||||
| `LOW` | Документация, комментарии, переименование без изменения поведения, форматирование без изменения конфигурационной семантики. Нет изменения контракта, доступа, данных или исполнения. | Проверить diff и сверить утверждения/команды с исходным кодом и действующей процедурой. Выполнить обычный CI. Если документация меняет операторский шаг, проверить его в безопасном локальном или synthetic окружении. |
|
||||
| `MEDIUM` | Ограниченное изменение поведения одного компонента, внутреннего API, UI или локального скрипта без изменения модели доверия и формата хранимых данных. | Целевые тесты затронутого компонента и регрессионная проверка, если меняется поведение; обычный CI. Для UI приложить результаты браузерного набора и synthetic визуальной проверки, если они относятся к изменённому экрану/потоку. Проверить обратную совместимость публичных запросов и ответов. |
|
||||
| `HIGH` | Авторизация и роли; secrets и credential flow; ingestion и происхождение данных; формат/миграция хранилища; backup/restore/recovery; production config; runner, CI и supply chain; безопасность; сетевые/host-границы; deploy и rollback. | Обычный CI плюс целевые проверки каждого затронутого trust/data boundary; regression-тест; проверка негативного пути и совместимости; независимое ревью конкретных угроз и последствий. Для операций с данными использовать synthetic/staging данные и план отката. Изменение production допускается только владельцем после отдельного согласования, проверки backup и готового rollback. |
|
||||
|
||||
Нельзя понижать класс из-за малого diff, срочности или простоты реализации:
|
||||
маленькое изменение правила доступа или восстановления всё равно `HIGH`.
|
||||
Нельзя считать отсутствие найденных тестов доказательством отсутствия риска.
|
||||
|
||||
## CI и ограничения Gitea
|
||||
|
||||
Проверенная конфигурация проекта:
|
||||
|
||||
- Репозиторий `admin/akyldash`, Gitea API вернул `1.25.5` 2026-10-24.
|
||||
- Workflow `.gitea/workflows/ci.yaml` запускается на `pull_request` и `push` в
|
||||
`main`; job ID, который следует сохранять для совместимости статусов, —
|
||||
`tests-and-images`.
|
||||
Он последовательно выполняет backend, Telegram, backup/restore, shell guards,
|
||||
deployment tests, Compose/Caddy validation и две production image builds.
|
||||
- `.gitea/workflows/runner-smoke.yaml` сохраняет отдельный job ID `runner-smoke`
|
||||
и проверяет runtime-изоляцию job-контейнера: отсутствие системного и
|
||||
rootless Docker socket, production env/secrets и host checkout. Smoke дополняет
|
||||
статические проверки runner/CI и не дублирует их.
|
||||
- Все задания используют `akyldash-local-ci` в Docker Desktop владельца. Конфигурация `infra/runner/desktop` выделяет заданию 4 CPU, 6 GiB RAM и 512 процессов, capacity 1. Данные внутреннего Docker хранятся в отдельном томе. Job-контейнеры не получают Docker socket.
|
||||
- Текущая политика `main` из branch API: ветка защищена и требует одного
|
||||
одобрения. На момент проверки API также сообщил `enable_status_check=false`
|
||||
и пустой список status contexts. Это PR не меняет branch protection.
|
||||
Если владелец отдельно включит обязательные статусы, сначала проверьте их
|
||||
точные контексты: `CI / tests-and-images (pull_request)` и
|
||||
`Runner smoke test / runner-smoke (pull_request)`. Не переименовывайте job IDs.
|
||||
|
||||
Функции и границы текущих проверок:
|
||||
|
||||
| Блок workflow | Назначение и риск пропуска | Перекрытие |
|
||||
|---|---|---|
|
||||
| Checkout и Python setup | Подготовка повторяемой среды; пропуск может дать ложный успех на неподходящем образе. | Инфраструктурный шаг, не покрывается тестами приложения. |
|
||||
| Backend и Telegram tests | Регрессии API, логики поиска/аккаунтов и Telegram bot. Риск продуктовый; для auth/data изменений — `HIGH`. | Разные пакеты и контракты; отдельная ветка тестов. |
|
||||
| Backup/restore tests | Целостность backup, восстановление и отказные сценарии; риск потери данных — `HIGH`. | Не дублируется тестами backend. |
|
||||
| Bootstrap/recovery/verifier/host-audit/production-config guards | Отказ от root и защиты host identity, аргументов и production paths; обход может дать административное действие или затронуть host — `HIGH`. | Несколько guard-тестов проверяют разные скрипты и условия; считать их дублями без анализа каждого контракта нельзя. |
|
||||
| Runner config, installer guards и CI container isolation | Ограничения runner, repeatability установки и запрет socket/privileged/host mounts; риск — доступ к host/production — `HIGH`. | Статические/синтетические проверки дополняются реальным runtime smoke, это разные уровни. |
|
||||
| Shell syntax и Python AST parse | Раннее обнаружение ошибок парсинга; риск пропуска — поломка запуска скрипта/проверки. | Это синтаксис, а не функциональные тесты. |
|
||||
| Deployment contract/rollback tests, Compose config и Caddy validation | Совместимость deploy contract/rollback и конфигурации production stack/proxy; риск — deploy outage/data impact — `HIGH`. | Compose проверяет интерпретацию конфигурации, Caddy — синтаксис proxy, Python suite — contract/rollback logic. Функции отличаются. |
|
||||
| Две Kaniko image builds | Проверка Dockerfile и воспроизводимости backend/OpenSearch production images; риск — сломанная сборка/небезопасный путь supply chain — `HIGH`. | Два Dockerfile — две разные целевые images; build-only, оба `--no-push`. |
|
||||
| Runner smoke (отдельный workflow) | Runtime-проверка известного системного socket path, production paths/secrets и host checkout отсутствия в job; риск — нарушение изоляции — `HIGH`. | Дополняет статические runner/CI guards; не повторяет их. |
|
||||
|
||||
Gitea API не предоставляет пригодный список steps для завершённого run в этой
|
||||
версии; длительность каждой строки таблицы поэтому `N/A`. Не распределяй общий
|
||||
CI runtime между блоками пропорционально числу тестов или строк кода.
|
||||
|
||||
Gitea 1.25 документация подтверждает используемые события `push`,
|
||||
`pull_request` и `workflow_dispatch`. Она также документирует ограничения,
|
||||
которые запрещают строить безопасное ускорение на привычных GitHub Actions
|
||||
предположениях:
|
||||
|
||||
- `runs-on` поддерживает статическую метку или список меток; текущая
|
||||
`akyldash-local-ci` — статическая метка.
|
||||
- Выражения доступны ограниченно; в сравнении с GitHub Actions Gitea 1.25
|
||||
обещает функцию `always()`, поэтому workflow не должен зависеть от
|
||||
`if:`-выражений для динамического выбора набора тестов по diff или уровню
|
||||
риска.
|
||||
- `jobs.<job_id>.timeout-minutes`, `permissions`, `concurrency` и
|
||||
`jobs.<job_id>.environment` в Gitea 1.25 игнорируются. Не используйте их как
|
||||
защиту, срок исполнения, обязательный approval или средство экономии.
|
||||
- У runner capacity 1. Разделение текущей последовательной работы на
|
||||
параллельные jobs не даёт измеримого параллельного исполнения на этом runner
|
||||
и может добавить запуск/очередь. Сохраняйте проверку сборки обеих production
|
||||
images: она подтверждает Dockerfiles, но использует Kaniko с `--no-push` и не
|
||||
публикует образы.
|
||||
|
||||
Источники семантики: [Gitea 1.25 Actions comparison](https://docs.gitea.com/1.25/usage/actions/comparison/),
|
||||
[Gitea 1.25 Actions FAQ](https://docs.gitea.com/1.25/usage/actions/faq/) и
|
||||
[act_runner guide](https://docs.gitea.com/1.25/usage/actions/act-runner/).
|
||||
Перед использованием новой workflow-семантики сверяй её с документацией
|
||||
установленной версии и проверяй фактическим run. Не добавляй проверки самой
|
||||
этой политики или статические тесты, утверждающие её текст.
|
||||
|
||||
## Временные ориентиры и фактические измерения
|
||||
|
||||
Ориентиры — цель для поиска затрат, а не разрешение убрать тесты:
|
||||
|
||||
- Обычный полный CI: до 5 минут от старта job до завершения. При превышении
|
||||
сначала измерить и оптимизировать узкий участок, сохраняя тесты и изоляцию.
|
||||
- Расширенный путь для `HIGH` (обычный CI плюс целевые проверки): целевой
|
||||
суммарный интервал 10–15 минут. Это пока ориентир, а не отдельный
|
||||
автоматический workflow или установленный timeout.
|
||||
|
||||
Срез 2026-10-24 получен из документированного [Gitea Actions task API](https://docs.gitea.com/api/1.25/operations/list-action-tasks/)
|
||||
`/repos/admin/akyldash/actions/tasks?limit=50`. Взяты 20 последних завершённых
|
||||
`tests-and-images`; длительность оценена как `updated_at - run_started_at`:
|
||||
|
||||
| Метрика | Измерение |
|
||||
|---|---:|
|
||||
| CI completed sample | 20 прогонов, 20 success |
|
||||
| CI median | 147.5 s (2:27.5) |
|
||||
| CI p90 | 172 s (2:52) |
|
||||
| CI max | 192 s (3:12) |
|
||||
| Runner smoke median / max | 2 s / 3 s, последние 20 прогонов |
|
||||
|
||||
Прежней reconciliation или оценок длительности в доступной документации
|
||||
репозитория, workflows, PR и issues не найдено; этот срез является первой
|
||||
подтверждённой базой, и сравнить его с прежней оценкой нельзя.
|
||||
Все 20 измеренных полных CI прогонов ниже пяти минут; текущая конфигурация уже
|
||||
достигает обычного ориентира. Отдельного extended workflow нет, поэтому
|
||||
10–15-минутная цель пока не имеет фактической базы. В выборке нет breakdown по
|
||||
steps: документированный endpoint для jobs завершённого run возвратил пустой
|
||||
список; это известное ограничение Gitea 1.25.5 ([upstream issue #38286](https://github.com/go-gitea/gitea/issues/38286)).
|
||||
Не распределяй время между тестами и image builds по предположению. При будущих
|
||||
изменениях workflow записывай доступные timestamps и точный размер выборки;
|
||||
после изменения Gitea/runner перепроверь, стал ли доступен надёжный step timing.
|
||||
|
||||
## Метрики потока поставки
|
||||
|
||||
Для каждого релиза/месячного обзора отдельно собирать:
|
||||
|
||||
| Метрика | Определение и источник |
|
||||
|---|---|
|
||||
| Ready → merge | Время с момента, когда PR реально готов к ревью, до merge. Не подменять датой создания draft PR; при отсутствии точного ready timestamp записывать `N/A`. |
|
||||
| Merge → deploy | Merge timestamp до фактического production deploy timestamp. Deploy пока не автоматизирован; пока нет подтверждённого deploy evidence, записывать `N/A`, не ноль. |
|
||||
| CI duration | `run_started_at` → task completion (`updated_at`) по Actions API; отдельно указывать медиану, p90, максимум, период и число прогонов. |
|
||||
| Повторные прогоны | Число неуспешных/повторных прогонов на commit до первого успеха; отличать rerun от нового commit/push. |
|
||||
| Блокирующие замечания | Число ревью-находок, удовлетворяющих критериям blockers выше; неблокирующие считать отдельно. |
|
||||
| Вышедшие регрессии | Подтверждённые после merge дефекты, связанные с изменением; фиксировать компонент, тяжесть и пропущенный сигнал. |
|
||||
| Rollback | Количество фактически выполненных rollback, причина и результат проверки данных/сервиса. Не считать написанный план фактическим rollback. |
|
||||
|
||||
На момент этого аудита PR/API не дают надёжного ready timestamp для старых
|
||||
изменений; production deployment не автоматизирован, а задачи этого PR не
|
||||
содержат deploy telemetry. Поэтому ready→merge, merge→deploy, escaped
|
||||
regressions и rollback baseline остаются `N/A`, пока не появится проверяемая
|
||||
запись. Не придумывай значения из `created_at` или даты последнего update.
|
||||
|
||||
## Критерий блокирующего ревью
|
||||
|
||||
Блокирующие замечания ограничены случаями:
|
||||
|
||||
- воспроизводимый дефект с конкретным условием и последствием;
|
||||
- расширение доступа, утечка секрета или обход границы runner/production;
|
||||
- потеря/искажение данных или несовместимость API/storage без безопасного пути;
|
||||
- обязательный тест или подтверждение из таблицы риска отсутствует/не проходит;
|
||||
- опасная операция не имеет проверяемого backup/rollback плана.
|
||||
|
||||
Каждый блокер содержит файл/участок, шаги воспроизведения или точное условие,
|
||||
последствие и минимальный безопасный fix. Остальные замечания — отдельный
|
||||
неблокирующий список. Независимый ревьюер проверяет полный diff и передаёт
|
||||
результат через Gitea Agent MCP. Формальное одобрение и разрешённый Merge
|
||||
следуют условиям [AGENTS.md](../../AGENTS.md#согласование-изменений).
|
||||
@@ -0,0 +1,69 @@
|
||||
# Infrastructure access
|
||||
|
||||
## Discover existing access first
|
||||
|
||||
For repository work in Windows Codex, use `commerce-infra` to read the
|
||||
`commerce/akyldash` context through Gitea Infrastructure Registry MCP. Use
|
||||
Gitea Codex MCP to read the project sources and prepare changes.
|
||||
Use the repository PR rules for formal review and permitted merge.
|
||||
|
||||
Host access is needed only for separately authorized runtime diagnostics.
|
||||
Check the configured SSH alias and key metadata without reading key contents.
|
||||
Do not request passwords, tokens, or keys, or print a complete environment file.
|
||||
|
||||
## VPS
|
||||
|
||||
- SSH alias: `akyldash_vps`, user `codex`, host `206.223.249.118`, port `22`.
|
||||
- SSH configuration: `~/.ssh/config`.
|
||||
- Identity file: `~/.ssh/akyldash_codex` (path only; never copy its contents).
|
||||
- `codex` can run unprivileged read-only diagnostics. It has no sudo or Docker
|
||||
group membership; Docker CLI access to the daemon is denied. Do not add it to
|
||||
either group.
|
||||
- Bootstrap is complete. Docker and Compose are active, but no root-owned
|
||||
repository checkout or restricted helper is installed yet. The owner can run
|
||||
`infra/bootstrap/audit-host.sh` from the reviewed root-owned checkout to
|
||||
report Docker containers/volumes, protected-file metadata, UFW rules, ports,
|
||||
and ISPmanager status without showing secret contents or changing state.
|
||||
- Host package/service configuration, firewall changes, protected env/secret
|
||||
creation, backup creation, recovery apply, and production deployment require
|
||||
a reviewed owner/root command. `infra/deploy/install-helper.sh` grants the
|
||||
fixed verifier, read-only Compose `config`/`status`, and guarded rollback
|
||||
commands. It does not grant general sudo or Docker access; it is not
|
||||
installed on the VPS.
|
||||
- `infra/deploy/prepare-production-config.sh` is an owner-run root operation.
|
||||
It refuses to overwrite existing files, copies only the tracked env example,
|
||||
generates a random review secret, and writes both files with mode `0600`.
|
||||
It does not start Compose or create volumes.
|
||||
- Never connect to other VPS hosts or Synology as part of this deployment.
|
||||
|
||||
For authorized runtime diagnostics, use the configured read-only SSH access.
|
||||
Validate the resolved alias, hostname, user and port before connecting. Only
|
||||
use an existing approved key for this environment. If access is unavailable,
|
||||
record the limitation. Do not copy keys between environments.
|
||||
|
||||
## Gitea
|
||||
|
||||
- Repository: `https://git.vakanaut.ru/admin/akyldash`.
|
||||
- Use Gitea Codex MCP to read the repository, prepare changes in a separate
|
||||
branch and open the PR. Use Gitea Agent MCP for formal review, approval and
|
||||
permitted merge according to [AGENTS.md](../../AGENTS.md#согласование-изменений).
|
||||
Do not inspect credential files, print secret environment values, or construct
|
||||
authorization headers.
|
||||
- Protected `main` requires at least one independent approval and the required
|
||||
CI checks. Direct push to `main` is prohibited. Merge requires the current
|
||||
head approval and the checks listed in AGENTS.md.
|
||||
- A `403` can indicate missing scope or owner permissions. It does not establish
|
||||
runner absence. Only a repository owner may obtain the repository runner
|
||||
registration token in `admin/akyldash` Settings → Actions → Runners. Do not use
|
||||
organization or instance tokens or put the token in Git, a command argument,
|
||||
or a report. See [CI_RUNNER.md](CI_RUNNER.md).
|
||||
|
||||
## Who can do what
|
||||
|
||||
| Role | Operations |
|
||||
|---|---|
|
||||
| `codex` over SSH | Unprivileged diagnostics; Docker daemon, UFW rules, and protected paths require the root audit script |
|
||||
| Restricted helpers | Read-only drift check and Compose `config`/`status`, plus guarded rollback; not installed on the audited VPS |
|
||||
| Restricted rollback helper | Can restore prior local backend/OpenSearch images from a verified backup after an explicit data-compatibility confirmation; not installed on the audited VPS |
|
||||
| VPS owner/root | Bootstrap, package installation, SSH/firewall, secret setup, recovery, and approval of production changes |
|
||||
| Gitea repository writer | Feature branch push and PR creation; protected-main merge needs an approval |
|
||||
@@ -0,0 +1,80 @@
|
||||
# Backup and restore
|
||||
|
||||
## Current status
|
||||
|
||||
The owner requires that a complete production archive never be written to the
|
||||
VPS, even temporarily. The reviewed implementation in PR #59 streams stopped
|
||||
Compose state directly from the root receiver to the owner's Windows client;
|
||||
the client stores it only under `D:\Dev\akyldash\.backups`. The VPS retains
|
||||
only a secret-free identity (backup ID, size, archive and manifest hashes,
|
||||
manifest) in root-owned release state. The Windows rerun passed 12 synthetic
|
||||
client checks, 8 protocol checks, and a disposable real-NTFS private owner-ACL
|
||||
fixture. The production D: path, SSH connection, VPS installation, and
|
||||
full production backup remain unverified. There is no verified production
|
||||
backup, so production deployment remains blocked.
|
||||
|
||||
## External backup flow
|
||||
|
||||
- The release receiver takes the shared deployment lock and stops the stack.
|
||||
- It streams a tar/gzip archive through a bounded binary SSH session. It does
|
||||
not create a local archive or temporary full-size copy on the VPS.
|
||||
- The Windows receiver requires the exact D: repository, a real NTFS path,
|
||||
restrictive ACLs, and the exact `/.backups/` rule in that checkout's local
|
||||
`.git/info/exclude`. Before SSH connects, it also requires at least 100 GiB
|
||||
plus 1 MiB of free D: space, matching the protocol's maximum archive size.
|
||||
The ACL owner and every allowed full-control entry must be the current user,
|
||||
SYSTEM, or local Administrators; other and deny entries fail closed.
|
||||
It writes into a private staging directory, checks the
|
||||
stream size and SHA-256, verifies the archive and manifest, then publishes
|
||||
the complete backup directory without overwriting an existing ID. It checks
|
||||
the published ACL before acknowledging; on failure it removes only the same
|
||||
verified staging directory, and refuses cleanup if its identity or contents
|
||||
have changed.
|
||||
- Only after Windows confirms the stored archive identity does the VPS proceed
|
||||
with image cutover. If backup transport or verification fails, it attempts
|
||||
to restart the previous services and records a recovery journal if restart
|
||||
fails.
|
||||
- Rollback first challenges Windows with the root-pinned previous backup
|
||||
identity. Windows verifies the local archive and streams it back; the VPS
|
||||
compares its exact size and SHA-256 before stopping services. Rollback then
|
||||
creates a fresh external backup of the current state before changing image
|
||||
references. It restores images only, never application data or OpenSearch
|
||||
state.
|
||||
|
||||
Windows PowerShell is the intended client. The Windows checks exercised the
|
||||
destination and ACL rules, including a disposable real-NTFS private owner-ACL
|
||||
fixture. The actual production D: destination and SSH path remain unverified.
|
||||
An owner must separately test archive restore on an isolated target before
|
||||
relying on this path. Do not restore over production as a test.
|
||||
|
||||
## Backup contents and limits
|
||||
|
||||
The existing `infra/backup/archive.py` manifest records the Git revision,
|
||||
deployment-file hashes, image references and IDs, and the components included
|
||||
in the archive: application data, OpenSearch, Caddy data/configuration,
|
||||
`production.env`, and the review secret. Secret-bearing files and SQLite files
|
||||
are archived with restrictive modes. The archive verifier rejects unsafe
|
||||
members and checks SQLite integrity. SSH encrypts archive bytes in transit.
|
||||
The destination contains secrets and private keys; D: encryption at rest (for
|
||||
example, BitLocker) has not been verified. This PR adds no client-side
|
||||
encryption or signing, so the owner must verify storage encryption and retain
|
||||
the restrictive ACLs before using it.
|
||||
|
||||
The external protocol caps control frames at 64 KiB, chunks at 1 MiB, and the
|
||||
archive at 100 GiB. SSH provides transport encryption and server host-key
|
||||
verification. The receiver uses a fixed SSH command and does not accept a
|
||||
caller-supplied path or shell command. It relies on the existing owner SSH
|
||||
configuration; no key, host entry, sudo rule, or VPS setting is added here.
|
||||
|
||||
## Restore
|
||||
|
||||
Use `infra/backup/archive.py restore` only with an archive already present in a
|
||||
protected owner-controlled location, and target a new staging directory on an
|
||||
isolated recovery host. Review [recovery](RECOVERY.md) and
|
||||
[deployment](DEPLOYMENT.md) first. This PR does not perform or authorize a
|
||||
production restore, data migration, or VPS operation. Keep the previous
|
||||
external archive until the owner has verified the replacement and explicitly
|
||||
approved its retention period.
|
||||
|
||||
The former `/var/backups/akyldash` create/verify procedure is superseded and
|
||||
must not be used for a full production archive on the VPS.
|
||||
@@ -0,0 +1,266 @@
|
||||
# AkylDash Gitea Actions runner
|
||||
|
||||
## Local Docker Desktop runner
|
||||
|
||||
All four workflows target the repository-scoped label `akyldash-local-ci` on the owner's Windows PC. Use the pinned rootless DinD image and Compose files in `infra/runner/desktop`. This requires Docker Desktop's `desktop-linux` context and the existing Gitea HTTPS proxy on `home-runner_runner`. Registration and Docker data use separate named volumes. The outer container runs privileged for rootless DinD. Jobs receive no host mounts, Docker socket or privileged mode. Capacity is one job with 4 CPUs, 6 GiB memory and 512 processes. Docker data shares the Desktop VM's free disk space.
|
||||
|
||||
From PowerShell run `.\infra\runner\desktop\register.ps1` once and enter the repository runner registration token at the hidden prompt. Verify `akyldash-desktop-local` is online and both required PR jobs pass. To pause, use `docker --context desktop-linux compose --project-directory infra/runner/desktop stop runner`; use `up -d runner` to resume with the existing registration and data. Old workflow revisions still request the VPS label. Update outstanding branches before retrying.
|
||||
|
||||
## Historical VPS configuration
|
||||
|
||||
The remainder records the former VPS installation and its test history. Its label must not be assigned to the local runner. Do not install it for current workflows.
|
||||
|
||||
### Scope and isolation
|
||||
|
||||
The deployment follows the official [Gitea 1.25 act_runner guide](https://docs.gitea.com/1.25/usage/actions/act-runner/)
|
||||
for repository-scoped registration. Gitea warns that access to a Docker daemon
|
||||
is root-equivalent; the dedicated rootless daemon is used instead of the
|
||||
production daemon. The pinned binary and checksum are published in the
|
||||
[official Gitea download directory](https://dl.gitea.com/gitea-runner/0.2.13/).
|
||||
|
||||
The runner is reserved to repository `admin/akyldash`, using the token under
|
||||
`https://git.vakanaut.ru/admin/akyldash/settings/actions/runners`. Do not use
|
||||
organization or instance runner settings. Pin the official `act_runner`
|
||||
`0.2.13` x86_64 binary from `dl.gitea.com`; the installer verifies its SHA-256
|
||||
before placing it on the host.
|
||||
|
||||
CI jobs run in `docker.gitea.com/runner-images:ubuntu-24.04` containers with
|
||||
capacity 1, per-job limits of 2 CPU, 3 GiB RAM and 512 processes, and a 15 GiB
|
||||
dedicated ext4 loop-backed Docker data filesystem. The runner account's home
|
||||
directory is root-owned mode `0711`, so CI cannot rename the image or mountpoint
|
||||
entries. Docker config remains under `.config`; registration state and the
|
||||
runner workspace live in `.config/act-runner`, which is runner-owned. The
|
||||
rootless Docker setup and user service use `.config/act-runner` as writable
|
||||
`HOME`, `.config` as `XDG_CONFIG_HOME`, and
|
||||
`.config/act-runner/.local/share` as `XDG_DATA_HOME`. This keeps Docker config
|
||||
and its systemd user unit in the existing `.config` tree without granting
|
||||
write access to the protected home.
|
||||
The runner systemd unit uses `ProtectHome=read-only` so `/run/user` remains
|
||||
visible; `ReadWritePaths` retains the existing `/run/user/$uid` writable
|
||||
carve-out for the runner's rootless runtime. `ProtectHome=yes` would hide
|
||||
`/run/user` and break the configured runtime and Docker socket paths. See the
|
||||
[systemd.exec documentation](https://www.freedesktop.org/software/systemd/man/255/systemd.exec.html#ProtectHome=).
|
||||
The rootless Docker daemon and runner user are separate from production Docker;
|
||||
`codex` is not added to
|
||||
sudo or Docker groups. Jobs do not receive the rootless Docker socket, the
|
||||
production Docker socket, production environment/secrets, or arbitrary host
|
||||
bind mounts. The runner account has no access to `/etc/akyldash` or the
|
||||
root-owned application checkout. These are host permission boundaries, not a
|
||||
claim that untrusted project code is safe; review workflow changes and actions
|
||||
before merging them.
|
||||
|
||||
The runner service restarts on failure and boot. Systemd caps the runner
|
||||
account's shared slice to 2.5 CPU, 4 GiB RAM and 2048 tasks; the rootless
|
||||
daemon is separately capped to 2 CPU, 4 GiB and 1024 tasks, while each job has
|
||||
the limits above. Runner logs go to a rotated file (10 MiB, 7 copies). A
|
||||
systemd timer checks the runner service and the rootless Docker API each minute;
|
||||
on failure it restarts the fixed runner service. No UFW changes or public
|
||||
metrics ports are needed. Runner cache is disabled.
|
||||
|
||||
The CI workflow and `runner-smoke.yaml` target the repository runner label
|
||||
`akyldash-ci`. CI keeps the backend, Telegram, backup/restore, deployment,
|
||||
bootstrap, runner, Compose, and Caddy checks. Caddy validation runs in a pinned
|
||||
container action with explicit `/usr/bin/caddy` entrypoint. The workflow passes
|
||||
Gitea's `${{ github.workspace }}` value into each container action; Caddy and
|
||||
Kaniko use that supplied path for repository files instead of assuming a
|
||||
container workspace location. Both production
|
||||
Dockerfiles are built in a separate pinned Kaniko container action with explicit
|
||||
`/kaniko/executor` entrypoint using the runner's rootless container engine; the
|
||||
job container receives no Docker socket. Kaniko uses `--no-push` and
|
||||
`--no-push-cache`, so CI validates the full backend and OpenSearch builds but
|
||||
does not publish images or export build output. The two builds run sequentially
|
||||
within one job. CI run 69 completed both builds historically; the latest
|
||||
verified main CI run 175 and smoke run 176 succeeded on `b5adc092`. Actual per-action
|
||||
resource-limit enforcement and peak memory or disk usage were not independently
|
||||
measured or verified. No registry credentials, production service secrets,
|
||||
elevated container options, or arbitrary host mounts are configured in PR CI.
|
||||
|
||||
The Kaniko action uses the `linux/amd64` v1.28.5-debug manifest
|
||||
`sha256:c73ca67a3b494bce79a8fb6090c4f73c18997ab272d80bffc460a62343aeb412`,
|
||||
listed in the [official GitHub Packages entry](https://github.com/osscontainertools/kaniko/pkgs/container/kaniko/1271366984?tag=v1.28.5-debug).
|
||||
The pinned Caddy image digest remains the same as the former `docker run`
|
||||
validation. act_runner starts these container actions; they do not expose its
|
||||
rootless Docker socket to workflow steps.
|
||||
Production deployment is not enabled. `release-images.yaml` now starts only
|
||||
after a successful `CI` workflow run for a push to `main`; it checks the source
|
||||
workflow, event, branch, conclusion, and SHA and checks that the SHA is still
|
||||
the current `main` before exposing Registry credentials. It checks out that
|
||||
exact source SHA and uses the release workflow's own run ID for image tags and
|
||||
the schema-v3 descriptor. PR CI remains no-push and receives no Registry or
|
||||
production credentials.
|
||||
|
||||
Image publication still requires the existing `REGISTRY_USERNAME` and
|
||||
`REGISTRY_PASSWORD` Actions secrets, which are not configured or verified.
|
||||
When configured, they must be package-write-only for the two approved image
|
||||
names. The release descriptor is unsigned. The SHA-256 is included in the
|
||||
artifact name so a later workflow can identify the expected digest from
|
||||
artifact metadata without treating job output as trusted input. The existing
|
||||
SHA-256 sidecar remains inside the artifact. The workflow has not yet run with
|
||||
Registry credentials, and the sequential Kaniko build's peak resources have not
|
||||
been measured beyond the configured 2 CPU, 3 GiB RAM, 512-process job limits.
|
||||
|
||||
`deploy-handoff.yaml` runs after a successful release on `main`. It rechecks the
|
||||
source run and stale-SHA guard. Its current mode is explicitly dry-run: it may
|
||||
read JSON artifact metadata using the installed `gitea-api` helper when present,
|
||||
but it never downloads the ZIP or opens an SSH connection. If the helper is not
|
||||
present in the job image, it reports that artifact metadata and host handoff
|
||||
remain unverified. No SSH, sudo, production secret, or Docker socket is passed
|
||||
to the runner.
|
||||
|
||||
Gitea 1.25.5 documents a run-artifact metadata endpoint and a ZIP endpoint that
|
||||
redirects to a blob URL. The currently audited `gitea-api` helper supports JSON
|
||||
GET requests but has no binary output option and does not follow redirects, so
|
||||
it cannot yet fetch and independently verify the host-side artifact. Do not
|
||||
enable a live handoff until an owner-approved binary-safe retrieval capability
|
||||
validates HTTPS redirects and never forwards the API token across origins. The
|
||||
host must independently validate the successful `main` release run, artifact
|
||||
name and ZIP sidecar before any guarded deployment. The owner must also verify
|
||||
artifact and Registry retention covers the rollback window.
|
||||
|
||||
## Installation and registration
|
||||
|
||||
Review the root script and host audit output before running it. It installs
|
||||
`uidmap`, `dbus-user-session`, `curl`, `logrotate`, and Docker's rootless extras;
|
||||
creates the dedicated system user and selects the first free, shared 65536-ID
|
||||
range from `/etc/subuid` and `/etc/subgid`; reserves 15 GiB
|
||||
for runner images/workspaces; and configures systemd services. It starts only
|
||||
the separate rootless Docker daemon; the runner and health timer stay disabled
|
||||
until repository registration. It does not change
|
||||
SSH/UFW, production Docker configuration, application data, or production
|
||||
secrets. It can be rerun after partial setup: it validates and reuses an
|
||||
existing runner account, subordinate ID mappings, image, and mount unit. An
|
||||
existing image must be exactly 15 GiB and contain ext4; a mismatch stops the
|
||||
installer without resizing or formatting it. The runner account must retain
|
||||
a non-root system UID below `UID_MIN`, its expected home, primary group, and
|
||||
sole supplementary group. After validating the account, the installer locks
|
||||
its home directory to root ownership and mode `0711`; it refuses to rerun while
|
||||
the runner service is active, so it cannot interrupt a job. The mount
|
||||
is started only when it is not already active, and an active mount must be the
|
||||
expected ext4 loop device backed by the runner image with both `nosuid` and
|
||||
`nodev` active. Runner-home directories and user configuration files are
|
||||
created in runner-owned subdirectories. Root creates only the first `.config`
|
||||
entry beneath the already locked home; subsequent directory and config writes
|
||||
run as `akyldash-runner`. The installer rejects static symlinks and validates
|
||||
ownership and mode after setup. This also normalizes the `0755` intermediate
|
||||
directories left by the first installer version. Conflicting files or state
|
||||
stop the installer for manual inspection. A new image requires at least 25 GiB
|
||||
free on `/`. Image creation opens each parent component without following
|
||||
symlinks, creates the image exclusively relative to the opened directory, and
|
||||
passes the open file descriptor to `mkfs.ext4`; validation checks the same inode
|
||||
and rejects path replacement. Systemd mounts the image under the root-owned home
|
||||
entry, which the runner cannot replace after validation.
|
||||
|
||||
If the reviewed checkout is not present at the inventoried path, first verify
|
||||
that the target is absent and clone the reviewed `main` there. Do not overwrite
|
||||
an existing checkout.
|
||||
|
||||
```bash
|
||||
sudo test ! -e /opt/akyldash/current
|
||||
sudo git clone --branch main \
|
||||
--single-branch https://git.vakanaut.ru/admin/akyldash.git \
|
||||
/opt/akyldash/current
|
||||
```
|
||||
|
||||
From that root-owned reviewed checkout on the VPS:
|
||||
|
||||
```bash
|
||||
sudo bash /opt/akyldash/current/infra/runner/install-runner.sh
|
||||
```
|
||||
|
||||
Then, as a repository owner, open repository **Settings → Actions → Runners**,
|
||||
create a repository-level runner, and copy its registration token locally. Do
|
||||
not send the token in chat or save it in the checkout. Register interactively
|
||||
in a terminal so it is not placed in shell history or process arguments:
|
||||
|
||||
```bash
|
||||
sudo -u akyldash-runner env HOME=/var/lib/akyldash-runner/.config/act-runner \
|
||||
/usr/local/bin/act_runner \
|
||||
--config /etc/akyldash-runner/config.yaml register
|
||||
```
|
||||
|
||||
Enter `https://git.vakanaut.ru/`, the token, runner name `akyldash-ci-vps-01`,
|
||||
and label `akyldash-ci:docker://docker.gitea.com/runner-images:ubuntu-24.04`
|
||||
when prompted. The config sets the label and capacity; verify them in the
|
||||
repository runner settings. The token is saved only in the mode-0700 runner
|
||||
runtime directory, outside Git. Start/enable the runner after registration:
|
||||
|
||||
```bash
|
||||
sudo systemctl enable --now akyldash-act-runner.service
|
||||
sudo systemctl enable --now akyldash-runner-healthcheck.timer
|
||||
sudo systemctl status akyldash-act-runner.service
|
||||
sudo systemctl status akyldash-runner-healthcheck.timer
|
||||
```
|
||||
|
||||
The interactive command's terminal behavior should be confirmed before pasting
|
||||
the token. If it echoes input, stop and use the repository settings to revoke
|
||||
that token; do not put it in command-line arguments or environment variables.
|
||||
|
||||
## Validation
|
||||
|
||||
1. Confirm the runner is **Online** in the repository runner settings, with the
|
||||
expected name and `akyldash-ci` label.
|
||||
2. Confirm **Runner smoke test** runs for the open PR (or dispatch it manually).
|
||||
It checks that production
|
||||
sockets, files, environment secrets, and writable application paths are not
|
||||
present in the job container.
|
||||
3. Confirm the run reports the expected runner, succeeds, and the runner
|
||||
service and health timer remain active.
|
||||
4. Inspect the `CI` workflow run and confirm Caddy plus both no-push Kaniko
|
||||
actions pass on `akyldash-ci`. Image publication is a distinct manual
|
||||
main-only workflow with package-only credentials; it does not deploy.
|
||||
Never add production service secrets, Docker socket access, or host mounts
|
||||
to this runner.
|
||||
|
||||
## Upgrade
|
||||
|
||||
Update `runner_version` and its expected official SHA-256 together in
|
||||
`infra/runner/install-runner.sh`, review upstream release compatibility with
|
||||
the installed Gitea, and open a PR. Do not replace the binary while a job is
|
||||
active. Stop the runner, install/verify the new binary, then start it and
|
||||
confirm Online plus a smoke run. Preserve
|
||||
`/var/lib/akyldash-runner/.config/act-runner/.runner`.
|
||||
|
||||
## Recovery and rollback
|
||||
|
||||
The runner is disposable: production data and secrets are not on its filesystem.
|
||||
For a runner process failure, inspect `systemctl status` and
|
||||
`journalctl -u akyldash-act-runner.service`; restart the fixed runner service.
|
||||
If installation stops after creating or enabling the mount unit, inspect the
|
||||
image and mount with `stat`, `blkid`, `findmnt`, and `losetup`, then rerun the
|
||||
reviewed installer only when the image is 15 GiB ext4 and the active mount is
|
||||
backed by it. The installer recognizes that state and does not format or
|
||||
restart the mounted filesystem. If size, filesystem, unit contents, or backing
|
||||
device differ, stop and resolve the state manually; never format the existing
|
||||
image as a retry.
|
||||
For lost/corrupt registration state, stop the service and obtain a fresh
|
||||
repository-level token from Settings → Actions → Runners. Preserve the 15 GiB
|
||||
data image and state for diagnosis; re-register only after the repository
|
||||
owner confirms/revokes the old runner in Gitea. The images/cache can be rebuilt
|
||||
from the workflow. Never format or remove an existing runner store as an
|
||||
automatic recovery step.
|
||||
|
||||
## Status
|
||||
|
||||
The owner reports that the repository-scoped runner is registered, appears
|
||||
Idle in Gitea, and its rootless Docker daemon works; the report date was not
|
||||
recorded. Gitea status checked 2026-10-18 showed smoke run 62 successful and CI
|
||||
run 61 pending on head `69c62466`. That workflow requested `ubuntu-latest`,
|
||||
while the smoke workflow used `akyldash-ci`; the label difference is a
|
||||
plausible explanation for the pending status, but the runner inventory API
|
||||
returned 403 and the scheduler's reason was not independently confirmed.
|
||||
|
||||
On head `3a89dc21`, CI run 63 failed at the host audit root guard and smoke run
|
||||
64 succeeded. On head `436806a8`, CI run 65 failed in the Caddy container action
|
||||
with `exec: "validate": executable file not found`; Kaniko was skipped and smoke
|
||||
run 66 succeeded. On head `d96fc4d3`, CI run 67 failed because the Caddy action
|
||||
looked for `/github/workspace/deploy/production/Caddyfile`, which was not
|
||||
mounted at that fixed path; Kaniko was skipped and smoke run 68 succeeded. On
|
||||
head `5d72bb09`, CI run 69 and smoke run 70 succeeded. CI validated the Caddyfile
|
||||
and built the backend and OpenSearch images using `${{ github.workspace }}`.
|
||||
Actual per-action resource-limit enforcement and peak usage were not
|
||||
independently measured or verified. Image publishing, host-wide resource
|
||||
metrics, and production deployment remain unverified. Root-guard tests
|
||||
use `setpriv` for negative cases when jobs start as UID 0 and separately test
|
||||
the host-audit guard with simulated UID 0 and UID 65534; the real host audit,
|
||||
production config setup, and runner installer are never executed as root by
|
||||
those tests. No VPS changes are part of this PR.
|
||||
@@ -0,0 +1,209 @@
|
||||
# Corpus inventory and production handoff
|
||||
|
||||
The repository contains a read-only verifier for the ignored local corpus at
|
||||
`data/minjust-cbd/` and `data/minjust-normalized/`. It does not download,
|
||||
normalize, copy, index, or modify source files. Keep inventory artifacts outside
|
||||
the repository and both source trees.
|
||||
|
||||
## Run the inventory
|
||||
|
||||
From the repository root, create a private artifact directory and run:
|
||||
|
||||
```bash
|
||||
artifact_dir=$(mktemp -d /tmp/akyldash-corpus-audit.XXXXXXXX)
|
||||
python3 infra/deploy/verify_corpus.py \
|
||||
--raw-root data/minjust-cbd \
|
||||
--normalized-root data/minjust-normalized \
|
||||
--output-dir "$artifact_dir"
|
||||
```
|
||||
|
||||
The tool writes `result.json`, `inventory.sqlite3`, and a persistent lock file
|
||||
into that directory. Keep the directory private: the inventory contains source
|
||||
paths and checksums. A second run against the same artifact directory is
|
||||
rejected while a scan is active. Exit
|
||||
status `0` means the scan and structural checks completed without errors; `1`
|
||||
means findings were recorded or the run is incomplete; `2` means the arguments
|
||||
or artifact path were invalid. Read `result.json` to distinguish those states.
|
||||
Warnings, including documents with zero text fragments, are reported
|
||||
separately and do not turn the scan into a failure.
|
||||
|
||||
For an interrupted run, use the same artifact directory and add `--resume`.
|
||||
Resume rehashes every source file instead of trusting cached timestamps, then
|
||||
reports added, changed, and removed paths relative to entries already stored
|
||||
in the inventory. After resuming an interrupted first pass, those counters are
|
||||
relative to the partial saved inventory; the full rehash and final checks still
|
||||
cover every path. A successful result therefore describes the latest complete
|
||||
pass. Run against a quiescent corpus; do not normalize, fetch, or copy files
|
||||
into either source tree during the scan. Do not point `--output-dir` inside
|
||||
either source tree or through a symlink. The verifier rejects such paths before
|
||||
creating or changing them; it also flags symlinks, reparse points, hard links,
|
||||
unsupported file types, and files that change while being read.
|
||||
|
||||
The inventory database schema is versioned. Resume requires the same root
|
||||
metadata and verifier SHA-256 recorded in `result.json`; start a new artifact
|
||||
directory after changing the verifier. `entries` counts files plus directories;
|
||||
`files` and `directories` are separate counts. Document-prefix checks use
|
||||
indexed path ranges, and stale-path reporting streams rows from SQLite.
|
||||
|
||||
The audit checks SQLite integrity, manifest/document directory agreement,
|
||||
normalized schema and normalizer versions, source inventory checksums,
|
||||
fragment identities and text hashes, required output files, and text assembled
|
||||
from fragments. It does not establish the legal authority, completeness, or
|
||||
semantic correctness of MinJust content.
|
||||
|
||||
## Compare source and staging before transfer
|
||||
|
||||
Run a complete inventory of the approved normalized source and the copied
|
||||
staging tree into separate private artifact directories, using
|
||||
`--normalized-root` for each. Require `status: complete` and
|
||||
`verification_status: passed` in both results. The comparison command also
|
||||
requires each manifest to contain at least one document and each normalized
|
||||
tree to contain at least one fragment; an empty source or staging tree is a
|
||||
failure.
|
||||
|
||||
```bash
|
||||
python3 infra/deploy/compare_corpus_inventories.py \
|
||||
"$source_artifacts/result.json" "$staging_artifacts/result.json"
|
||||
```
|
||||
|
||||
The checker streams every relative path, size, and SHA-256 from both SQLite
|
||||
inventories, and requires the same verifier/schema version and different
|
||||
normalized roots. It opens both existing private `.inventory.lock` files
|
||||
read-only and holds shared nonblocking locks through comparison; a missing,
|
||||
unsafe, or busy lock fails closed. A zero exit status confirms a non-empty
|
||||
staging tree matches the source. Keep both trees quiescent during their scans
|
||||
and comparison. This is an equality check only; the owner still reviews the
|
||||
code `6` disposition and approves the transfer destination.
|
||||
|
||||
## Current data disposition
|
||||
|
||||
As measured on 2026-10-18, both local manifests contain 209,958 documents and
|
||||
pass SQLite `quick_check`. All normalized manifest entries are `success` at
|
||||
schema `1` and normalizer `1.0.0`. The raw manifest records one fetch error for
|
||||
code `6`, which is absent from its `documents` table; this does not prove that
|
||||
the source document is absent. On 2026-10-18, bounded calls through the
|
||||
repository's rate-limited MinJust client received HTTP `404` for
|
||||
`GetDocumentListByQuery`, `GetDocument(6)`, control `GetDocument(1096)`, and
|
||||
`CheckAvailable`. The listing call failed before returning a code list, and
|
||||
both document calls failed identically. The repeated `404` is consistent with
|
||||
the OpenData endpoint being unavailable or its route having changed, but does
|
||||
not identify which. It is not evidence that code `6` is absent. The [public
|
||||
document listing page](https://cbd.minjust.gov.kg/list-docs/kg) was reachable,
|
||||
but it does not confirm this numeric API code. Do not describe the corpus as
|
||||
fully verified or silently waive this error. Recheck the official listing and
|
||||
API when the endpoint responds, then record an explicit owner disposition.
|
||||
From the VPS, a metadata-only HTTPS check to `CheckAvailable` failed at the
|
||||
HTTP/2 transport layer (`curl` exit 92, `INTERNAL_ERROR`, HTTP status `000`,
|
||||
TLS verification `0`). An HTTP/1.1 retry was not completed.
|
||||
|
||||
## Current API and bounded code 6 recovery (2026-10-20)
|
||||
|
||||
The current official site uses `POST /api/v1/GetDocuments` (page size 12),
|
||||
`GET /api/v1/GetDocument?DocumentCode=...`, and
|
||||
`GET /api/v1/GetEdition?editionId=...&lang=ru|kg`. A bounded first-page probe
|
||||
reported 210,639 records; this recovery does not enumerate the full list. The
|
||||
official alias `1-4` resolves to canonical code `205064`. Code `6` is present
|
||||
and has 201 editions. The edition order in `GetDocument` is authoritative;
|
||||
numeric IDs do not define currentness.
|
||||
|
||||
For `lang=kg`, the API returns Kyrgyz HTML in `contentRu` and `contentKg=null`.
|
||||
The bounded adapter maps that response by the requested language to archive
|
||||
`ky`, preserves the response and checkpoints, limits requests to one per
|
||||
second, caps JSON responses at 16 MiB, and caps one document's text at 4 GiB.
|
||||
It writes only to a separate generation under `/tmp`; it neither resumes nor
|
||||
overwrites the existing ignored corpus.
|
||||
|
||||
Without `exact=true`, a request for `920292` returned response field
|
||||
`id=920492` despite different text length/hash. Two exact probes for `920292`
|
||||
and `920492` returned matching IDs and names/dates (`04.08.1998` and
|
||||
`13.04.2017`) matching `GetDocument`; their RU text lengths/hashes were
|
||||
485,487 / `2b51c2ff4e9b91cbe2a7ed052a5a9ed9150bda993fc15c120ac948580926b718`
|
||||
and 1,139,908 / `e5f0fdbb47766e5a5dbb971183d765e4c1dcaf9c969a218a84206244ce9132e8`.
|
||||
The adapter now requires `exact=true`, returned-ID equality, and matching RU/KY
|
||||
names before a language checkpoint can complete. Its versioned request
|
||||
contract is part of both staging metadata and the SQLite resume identity;
|
||||
pre-contract generations cannot be resumed.
|
||||
|
||||
The adapter does not independently validate attachments or embedded media.
|
||||
Even after the text stage completes, the raw manifest records this as an
|
||||
unresolved error. Do not merge this single document into the existing corpus,
|
||||
claim corpus completeness, or transfer it to production without a separate
|
||||
review and comparison. The prior no-exact pass at
|
||||
`/tmp/akyldash-current-code6.ZAMC37u4ex` is marked quarantined in
|
||||
`qualification.json`; its 240 text checkpoints and 304,493,520 bytes are
|
||||
retained as unverified, with no document directory published. Its preserved
|
||||
work-tree SHA-256 is
|
||||
`1e874c1d7fab1e00e7e45ff1b16422ea474e22ee13c901ac9a0612f47aa5d24a`. It must
|
||||
not be reused or normalized.
|
||||
|
||||
The exact-only generation at `/tmp/akyldash-current-code6-exact.L4k3AvnOlP`
|
||||
contains 201 editions and 402 complete RU/KY text checkpoints (604,377,885
|
||||
raw bytes). The raw manifest passes `quick_check`; its stored source SHA-256
|
||||
matches the staged document tree at
|
||||
`81d8e1a53b2ebef61f08b56d04b3f0a80077d587a4fadae0152bb4b7f13055ea`. Separate
|
||||
normalization at `/tmp/akyldash-current-code6-exact.L4k3AvnOlP-normalized`
|
||||
passes `quick_check`, records normalizer `1.1.0`, and preserves first/last
|
||||
edition order `920292` (`04.08.1998`) to `920492` (`13.04.2017`). The normalized
|
||||
generation is about 2.05 GB. Neither temporary generation has been merged into
|
||||
the existing corpus. Attachments and embedded media remain unverified.
|
||||
|
||||
The first full pass (run `b4a4556e30cc464d90bc8d75ef1673e9`) stopped before
|
||||
validation with `Python int too large to convert to SQLite INTEGER` after
|
||||
2,120,420 raw entries and 397,856 normalized entries. This was an inventory
|
||||
metadata storage failure, not a corpus finding. The verifier now stores file
|
||||
identity values as text and records its own SHA-256. A complete rehash with the
|
||||
updated verifier is required; do not treat the failed pass or progress output
|
||||
as a completed audit.
|
||||
|
||||
A fresh full rehash is now running in `/tmp/akyldash-corpus-audit-final.gtsD87vc`,
|
||||
run `f4dd5e53020f442bbbecee2d0e4986a6`, verifier SHA-256
|
||||
`83dac230099fc91972cd14e86e9f8ec72d13bca08f53d402f13a169e096d98f5`. Check
|
||||
its private `result.json` for final counters, findings, and manifest comparison.
|
||||
|
||||
## Production transfer and indexing gates
|
||||
|
||||
Production deployment is not enabled. Before any transfer, the owner must
|
||||
review the root-only host audit, confirm the target data location is empty or
|
||||
backed up, resolve the raw code `6` finding, and approve the exact normalized
|
||||
corpus to use. Transfer only `minjust-normalized/`; keep the raw source archive
|
||||
offline. Do not preserve the source's Windows/WSL file permission bits. Copy
|
||||
to a new staging location with owner-approved permissions, verify the copied
|
||||
manifest and files there, and only then consider publishing it under
|
||||
`DATA_ROOT/minjust-normalized`.
|
||||
|
||||
### Atomic publication gate for `DATA_ROOT`
|
||||
|
||||
The verified staging tree must be published to
|
||||
`DATA_ROOT/minjust-normalized` as one all-or-nothing operation, using an
|
||||
owner-approved atomic mechanism or a separately documented equivalent. An
|
||||
in-place copy into the live target is not an acceptable publication method.
|
||||
Preserve the current published corpus until the candidate is fully verified and
|
||||
ready for the atomic switch; never overwrite its contents in place.
|
||||
The publication mechanism and its interrupted-operation recovery have not yet
|
||||
been specified or tested; this is a release gate, not a claim that atomic corpus
|
||||
publication is implemented. Until that gate is completed, do not publish or
|
||||
replace a corpus in `DATA_ROOT`.
|
||||
|
||||
If preparation is interrupted before publication, keep the current target
|
||||
untouched. Resume only from the isolated staging tree after a full rehash and
|
||||
source comparison; if that cannot be established, fail closed and prepare a
|
||||
new staging candidate. If interruption makes the outcome of the final
|
||||
publication ambiguous, do not retry or replace anything automatically. Verify
|
||||
the target against the approved manifest and resolve the state with the owner
|
||||
before any retry. Never overwrite an existing corpus or OpenSearch volume.
|
||||
|
||||
The atomic filesystem publication of the approved corpus into `DATA_ROOT` and
|
||||
the OpenSearch alias switch are separate gates. A successful corpus publish
|
||||
does not authorize indexing or alias changes; do not conflate the two.
|
||||
|
||||
The bulk importer now refuses alias publication until all Bulk item results
|
||||
are successful, the full staged index is refreshed, its fragment count exactly
|
||||
matches the complete normalized inventory (including on resume), and approved
|
||||
Russian and Kyrgyz canaries both return text. The alias must currently target
|
||||
the exact `--expected-old-index`; wildcard removals and implicit first-time
|
||||
alias creation are rejected. OpenSearch performs removal of that exact target
|
||||
and addition of the candidate in one alias request. A mismatch or validation
|
||||
failure leaves the existing alias untouched. This is a code-level gate only:
|
||||
no production index or corpus was changed, and the live inventory and canary
|
||||
terms still require owner verification. See `backend/README.md` for the
|
||||
operator flags and use a new versioned index for every candidate.
|
||||
@@ -0,0 +1,481 @@
|
||||
# Infrastructure current state
|
||||
|
||||
## Local runner storage — 2026-11-21
|
||||
|
||||
The AkylDash Docker Desktop data volume reported 931.6 GiB available. A container using the runner configuration reached Gitea over HTTPS. The dedicated local label is `akyldash-local-ci`. Registration and successful Actions jobs require separate verification in Gitea.
|
||||
|
||||
## Windows ACL SID resolution — 2026-11-03
|
||||
|
||||
- Read-only PowerShell 5.1 inspection found that display-name conversion of
|
||||
ACL entries can throw `IdentityNotMappedException` even though the ACL itself
|
||||
is readable. The installer and external-receiver guards now enumerate access
|
||||
rules directly as `SecurityIdentifier` values and read owners as SIDs; unknown
|
||||
principals remain visible to the existing fail-closed policy. Regression
|
||||
coverage exercises synthetic unmapped SIDs through the actual installer guard
|
||||
functions. These repository changes are pending review; no Windows ACL,
|
||||
installer, task, VPS, or production state was changed. The native PowerShell
|
||||
harness still requires execution on Windows before this behavior is confirmed
|
||||
in that runtime.
|
||||
|
||||
## External deployment runtime binding — 2026-11-03
|
||||
|
||||
- PR #59 is merged to `main`; it contains the root-only read-only status
|
||||
endpoint and exact-literal SSH dispatcher for `status` and `deploy`. The
|
||||
status path bounds the Gitea run list to ten entries, verifies the selected
|
||||
run/workflow/current `main`,
|
||||
validates artifact metadata and ZIP bytes, and returns only a release tuple.
|
||||
This unmerged change adds a two-SHA compatibility gate: the fixed root helper
|
||||
compares protected Compose/Caddy bytes and installed release policy with
|
||||
Gitea content pinned to the release SHA, verifying each Git blob hash and
|
||||
size. This permits application-only release B after bootstrap A without
|
||||
advancing the root checkout or executing new root code. A runtime config or
|
||||
policy change fails closed and requires a reviewed bootstrap update. The
|
||||
Windows response state is `prepared`, never `candidate`; the `--once` task
|
||||
stores a protected local tuple and cannot call deploy. A separate disabled
|
||||
auto-apply task and config gate require the tuple to match a fresh status
|
||||
response from a previous poll. Status and apply retain current-main,
|
||||
successful CI/release provenance, descriptor digest, external backup,
|
||||
cutover, canary, and rollback checks. The receiver repeats the config check
|
||||
before journaling/stopping services and again after backup immediately before
|
||||
switching refs.
|
||||
- Windows client предназначен для подготовки и auto-apply; обе задачи по умолчанию
|
||||
выключены, целевой путь фиксирован: `D:\Dev\akyldash`, SSH alias —
|
||||
`akyldash_release`. Примеры config и Task Scheduler XML также выключены; задачи
|
||||
запускаются от интерактивного пользователя с минимальными правами, не допускают
|
||||
параллельных запусков и не будят компьютер. Windows task, SSH key, VPS command,
|
||||
helper и trigger не устанавливались и не запускались. Путь canonical
|
||||
`C:\ProgramData\Akyldash\release-trigger.json` известен, но содержимое и
|
||||
enabled-состояние не читались. Метаданные Windows подтверждают
|
||||
`C:\Python313\python.exe`, действительную Authenticode-подпись Python Software
|
||||
Foundation и защищённые ACL интерпретатора.
|
||||
- Linux fixtures прошли для Python import и command-path poisoning, включая очистку
|
||||
унаследованных `GIT_*` и фиксацию путей `ssh.exe`/`git.exe`/`powershell.exe`.
|
||||
Installer получает ограниченный bundle из точной вершины `main`: упаковщик
|
||||
читает Git objects commit, tree и allowlist-файлов; elevated installer проверяет
|
||||
SHA-256 ZIP и цепочку `commit → tree → файлы` из одного read-locked потока до
|
||||
записи и не запускает Git. ACL проверяются явными масками мутаций и подмены;
|
||||
текущая учётная запись не может владеть кодовыми путями, а право создать
|
||||
соседнюю папку не считается подменой предка. Windows ACL/install проверки пока
|
||||
только прошли код-ревью; installer и launcher на Windows не запускались.
|
||||
Production CD остаётся выключенным.
|
||||
- Remaining owner prerequisites are installation of the reviewed root helper,
|
||||
exact forced-command/SSH host-key setup, a protected Windows client and its
|
||||
private state/config ACLs, private D: backup ACLs, and all previously listed
|
||||
backup/restore and production readiness gates. Neither the status endpoint nor client advances
|
||||
the host checkout or updates root helper code.
|
||||
|
||||
- Read-only Gitea check for fresh `main` SHA
|
||||
`f19faf628e67015febac22d0ec93ce4782caf4bf`: CI run #706 succeeded; release
|
||||
run #708 failed at the explicit registry credential-presence check because
|
||||
`REGISTRY_USERNAME` and `REGISTRY_PASSWORD` are absent; handoff run #709 was
|
||||
skipped. No secret values were read. Image publication remains owner-blocked.
|
||||
|
||||
Owner decision recorded 2026-10-26: a complete backup must not be stored on
|
||||
the VPS, including temporarily. The local archive/full cold-backup commands in
|
||||
`BACKUP.md` are superseded and unauthorized. PR #59 now contains a proposed
|
||||
Windows-controlled external stream receiver and root-side deploy/rollback
|
||||
code. The Windows rerun passed 12 synthetic client checks and 8 protocol
|
||||
checks, plus a disposable real-NTFS fixture for the private owner ACL. The
|
||||
production D: path, SSH connection, VPS installation, full backup, and
|
||||
separate-target restore remain unverified. No verified external backup or
|
||||
separate-target restore exists, so production deployment remains blocked by
|
||||
the backup gate.
|
||||
|
||||
## Code-only deployment work — 2026-10-31
|
||||
|
||||
- Work is being prepared in the existing PR #59 branch from the then-current
|
||||
`main`; no merge, VPS operation, live release, or workflow dispatch was
|
||||
performed for this work.
|
||||
- The release descriptor now binds both the release run and its successful CI
|
||||
source run. Host-side source verification uses the installed `gitea-api`
|
||||
helper contract; the PR carries the inspected helper fixture plus a bounded
|
||||
binary-download patch. The installer verifies the fixture hash before
|
||||
applying the patch.
|
||||
- Backup bytes are streamed through a bounded SSH protocol to the fixed
|
||||
Windows destination. Root release state stores only a secret-free backup
|
||||
identity. The rollback handshake requires the exact previously pinned
|
||||
archive and creates a fresh external backup before image references change.
|
||||
Local VPS archive paths fail closed.
|
||||
- Review fixes in this PR require Gitea `status=completed` with
|
||||
`conclusion=success`, resolve `main` from `/opt/akyldash/current`, write a
|
||||
durable pending journal before stopping services, and reject an already
|
||||
applied release before downtime. The Windows client checks D: capacity,
|
||||
NTFS/path/ACL owner and allowed entries, and the local ignore rule before
|
||||
SSH; it requires 100 GiB plus 1 MiB free. The Windows rerun passed 12
|
||||
synthetic client checks, 8 protocol checks, and a disposable real-NTFS
|
||||
private owner-ACL fixture; actual D:, SSH, and VPS remain unverified.
|
||||
- Receiver cleanup after a post-publication ACL failure is identity-bound to
|
||||
the owned staging directory and permits only the expected archive files. A
|
||||
replaced, reparse, or unexpected target is left for manual review without an
|
||||
ACK; this path is covered by local fixtures and the Windows rerun.
|
||||
- Synthetic tests cover archive/protocol integrity, helper download rules,
|
||||
artifact/run provenance, receiver publication, release schema, and rollback
|
||||
refusal. The 12 synthetic Windows client checks, 8 protocol checks, and
|
||||
disposable real-NTFS private owner-ACL fixture passed. The actual D: path,
|
||||
SSH alias, Gitea helper against
|
||||
the live instance, root helper installation, artifact redirect, production
|
||||
backup/restore, and actual release/rollback remain unverified.
|
||||
- Owner bootstrap blockers remain: verify a root-controlled SSH route for the
|
||||
fixed commands using existing host-key checking; provision only the
|
||||
necessary read-only Gitea token, exact redirect origin if needed, and
|
||||
approved RU/KY canaries; confirm registry pull and retention policy; test
|
||||
the Windows client and a separate-target restore. No new key, sudo rule,
|
||||
Docker access, credential, or VPS setting is added by the code change.
|
||||
|
||||
Read-only deployment recheck: 2026-10-25. Source: SSH as `codex`, direct-origin
|
||||
and public HTTPS probes, local `main` checkout, and Gitea API. No VPS files,
|
||||
services, firewall, containers, volumes, production data, or credentials were
|
||||
changed or inspected. Root-only Docker state, UFW rule details, protected file
|
||||
metadata, current backup/restore validity, and the live corpus/index remain
|
||||
unverified. The 2026-10-18 inventory below is a historical snapshot where it
|
||||
conflicts with this dated recheck.
|
||||
|
||||
## Latest read-only recheck — 2026-10-25
|
||||
|
||||
- `https://akyldash.kg/review` returned HTTP 200 with valid TLS through the
|
||||
public Cloudflare edge and through direct HTTPS to origin `206.223.249.118`.
|
||||
This verifies that route only; it does not prove search or index readiness.
|
||||
- TCP listeners now include 22, 80, and 443. The older no-listener/Cloudflare
|
||||
521 observations below are historical, not current state.
|
||||
- VPS reports 4 CPUs, 7.7 GiB RAM (about 3.7 GiB available), and 31 GiB free
|
||||
on `/`. Current runner-mount free space was not rechecked.
|
||||
- `/opt/akyldash/current` exists, is a root-owned directory mode `0755`.
|
||||
Reading its Git SHA failed with Git's `dubious ownership` safety guard; no
|
||||
`safe.directory` setting was added, so the installed revision is unknown.
|
||||
- `akyldash-act-runner.service` is active under `akyldash-runner`; installed
|
||||
`act_runner` is `0.2.13`. The separate `akyldash-runner-restart.service`
|
||||
remains failed since 2026-10-14; its cause could not be read from the
|
||||
unprivileged journal view. No restart was attempted.
|
||||
- `akyldash-verify`, `akyldash-compose`, and `akyldash-rollback` are absent
|
||||
from PATH in the unprivileged check; no root helper or Docker operation was
|
||||
run.
|
||||
- Gitea is `1.25.5`; `main` is `b5adc09203cbbbd298054248206b9f47ae4a44ca`.
|
||||
CI run 175 and runner smoke 176 succeeded on that commit. Package write
|
||||
access and runner inventory remain outside this API principal's permissions.
|
||||
- PR #59 head `852d639c455ff1c60202405e112d47b8128d66c6` received formal
|
||||
review #308 with five requested fixes. CI run 177 failed in
|
||||
`test_digest_rollback_fails_before_stopping_or_changing_references` because
|
||||
the test's global `Path.stat` mock made `Path.exists()` report a false
|
||||
recovery-journal hit under CI Python 3.12; runner smoke 178 succeeded. A
|
||||
fix batch in this PR isolates state paths, handles ambiguous alias/cutover
|
||||
outcomes, verifies rollback image IDs, and adds a synthetic artifact upload
|
||||
check. On 2026-10-25 CI run 179 and runner smoke 180 succeeded at PR head
|
||||
`9d8ce6b6`; CI took 2m43s and the synthetic upload step reported success.
|
||||
The run API identifies run ID 567 and reports `run_attempt: 0`, Gitea's
|
||||
legacy sentinel. The release workflow therefore uses the unique run ID and
|
||||
does not depend on the unavailable attempt value. The run's artifact link was
|
||||
downloaded from Gitea UI as `artifact-smoke-567-`: the ZIP was 191 bytes,
|
||||
SHA-256 `ae0a2262147f222aacb4fdd1d12459f7160c67b1d0ee5d7ae2db1de8958f120f`,
|
||||
and contained the expected 51-byte `marker.txt`. The API artifact listing
|
||||
available to this principal returned no entries, but the downloaded file
|
||||
verifies artifact availability. No live release or VPS change was made.
|
||||
- The release descriptor SHA-256 sidecar now records `release-manifest.json`
|
||||
relative to the `release` directory, matching the flattened layout observed
|
||||
for downloaded Gitea artifacts. A local synthetic regression verifies the
|
||||
checksum from the artifact extraction root; the credentialed release
|
||||
workflow remains unrun.
|
||||
- Owner-only outstanding evidence: sanitized container/volume and protected
|
||||
file metadata; current backup and separate-target restore verification;
|
||||
live corpus/index counts and RU/KY canaries; Cloudflare TLS mode; registry
|
||||
writer identity and digest retention. Never include secret values in that
|
||||
evidence packet. The checklist is in
|
||||
[`DEPLOYMENT_OWNER_PACKET.md`](DEPLOYMENT_OWNER_PACKET.md).
|
||||
|
||||
The deployment PR adds a manual main-only image-publish workflow and an
|
||||
owner-run `--no-build` cutover path, but neither has been executed against the
|
||||
VPS. Its release descriptor is an unsigned trace record; cryptographic image
|
||||
attestation remains a separate owner decision.
|
||||
|
||||
## Historical host snapshot — 2026-10-18
|
||||
|
||||
Source: SSH as `codex`, local repository inspection, and Gitea API. Root-only
|
||||
Docker state, UFW rule details, and protected file metadata were not verified.
|
||||
|
||||
## Historical VPS facts — 2026-10-18
|
||||
|
||||
- Host: `avprogs.hlab.kz`, `206.223.249.118`, SSH port `22`, user `codex`.
|
||||
- OS: Ubuntu Server `24.04.5 LTS`; kernel `6.8.0-142-generic` from the prior
|
||||
inventory audit.
|
||||
- Resources: 4 vCPU, 7.7 GiB RAM, 3.8 GiB swap, 99 GiB root filesystem with
|
||||
84 GiB free on 2026-10-18. Runner storage is a separate 15 GiB ext4 loop
|
||||
mount with 12 GiB free at that check.
|
||||
- Network: interface `ens3`, IPv4 `206.223.249.118/32`.
|
||||
- `codex` is UID/GID 1000, groups `codex` and `users`; `sudo -n true` requires
|
||||
a password. Docker CLI cannot access `/var/run/docker.sock` as `codex`.
|
||||
- SSH service is running. The inspected sshd configuration has public-key and
|
||||
password authentication enabled and `PermitRootLogin yes`; no SSH changes
|
||||
were made.
|
||||
- Bootstrap completed. Docker CLI `29.9.0` and Compose `5.6.0` were rechecked
|
||||
over SSH on 2026-10-18; containerd `2.4.1` and runc `1.5.2` are from the
|
||||
prior package audit. The Docker daemon API remains root-only.
|
||||
- `/etc/docker/daemon.json` has the expected `local` log driver and `10m` / `3`
|
||||
rotation limits. Bootstrap paths exist with root ownership: `/opt/akyldash`
|
||||
mode `0755`, `/etc/akyldash` and `/var/backups/akyldash` mode `0700`, and
|
||||
`/var/lib/akyldash/data` mode `0750`.
|
||||
- `/opt/akyldash/current`, verifier/rollback binaries, and the sudoers file are
|
||||
absent. `codex` has not received sudo or Docker-group access. Metadata for
|
||||
`/etc/akyldash/production.env` and `/etc/akyldash/review_secret` could not be
|
||||
checked because access is denied. The target
|
||||
`/var/lib/akyldash/data/minjust-normalized` and its manifest metadata were
|
||||
also denied; their presence, ownership, and contents are unknown. No sudo was
|
||||
used.
|
||||
- TCP listeners observed: SSH `22` and loopback DNS only; no listener on `1500`,
|
||||
`80`, or `443`. No ISPmanager package or service unit was found through the
|
||||
unprivileged checks; root can confirm with the audit script below.
|
||||
- Owner reports UFW is active and allows TCP `22`, `80`, `443`, and `1500`.
|
||||
Rule details were not independently read; no firewall changes were made.
|
||||
- Additional read-only runner checks on 2026-10-12 confirmed `/` is ext4 with
|
||||
about 92 GiB free at the prior audit, `/usr/bin/dockerd-rootless.sh` exists,
|
||||
and `git.vakanaut.ru` resolves to `195.209.48.28`. From the VPS,
|
||||
`https://git.vakanaut.ru/api/v1/version` returned Gitea `1.25.5`; runner
|
||||
registration and Gitea Actions protocol connectivity are not confirmed.
|
||||
- `akyldash.kg` resolved to Cloudflare IPv4/IPv6 edge addresses. HTTPS returned
|
||||
Cloudflare `521` on this historical 2026-10-18 check; current recheck is
|
||||
recorded above. Cloudflare Full (strict) mode remains unverified.
|
||||
|
||||
## Historical application and Gitea facts — 2026-10-18
|
||||
|
||||
- Repository: `admin/akyldash`, default branch `main`; Gitea version `1.25.5`.
|
||||
- The repository API reports push permission, Actions and packages enabled, and
|
||||
PRs enabled. `main` is protected and requires one approval; the current API
|
||||
principal cannot push or merge directly to `main`.
|
||||
- The repository runner-list API returns `403` because this API principal is
|
||||
not the repository owner. The latest verified CI run 75 and smoke run 76 both
|
||||
succeeded on `main` head `0e276ae6`. The Actions run-list endpoint returned
|
||||
`403` for this API principal during this recheck, so no newer run state was
|
||||
independently retrieved. The owner reports the runner is registered and
|
||||
Idle; repository runner inventory and package publishing permissions remain
|
||||
unverified.
|
||||
- No public application listener is observed on TCP `80`/`443`. Docker
|
||||
container/volume state still requires the root audit. Repository Compose describes
|
||||
Caddy `2.11.6` pinned by digest, Python Search API `0.12.2` in this branch,
|
||||
SQLite account/review data, and OpenSearch `3.7.0` with `analysis-icu`.
|
||||
- The target publishes only Caddy on TCP `80`/`443`. Backend and Caddy share a
|
||||
proxy network; OpenSearch and backend share a separate internal network, and
|
||||
backend has no host port. Caddy certificate storage, OpenSearch, and
|
||||
application data use persistent volumes/bind mounts.
|
||||
- The root-owned repository checkout, production env/secret files, Compose
|
||||
volumes/containers, backup, verifier/rollback helpers, and application are
|
||||
not confirmed installed. TLS and registry digest deployment for
|
||||
backend/OpenSearch are not configured.
|
||||
- The repository has a cold-backup archive/verification tool and a one-shot
|
||||
restore apply tool that requires a marked replacement host. Backup/restore
|
||||
tests use synthetic data; neither tool has run against production. The
|
||||
archive preflight permits a clean first deployment to skip backup, requires
|
||||
backup for existing persistent data even without containers, allows absent
|
||||
named volumes only in explicit corpus-only initial-deployment mode, and
|
||||
rejects inaccessible/ambiguous mounts and incomplete/running service
|
||||
containers. Initial deployment docs require a second verified backup after
|
||||
index and admin initialization.
|
||||
- Recovery bootstrap has an explicit `--recovery-target` mode that refuses the
|
||||
inventoried production hostname/IP; its host-identity guard has shell tests.
|
||||
The mode has not been run on a VPS.
|
||||
- The repository defines a root-owned read-only verifier, Compose `config` and
|
||||
`status` helper, guarded rollback helper, and installer with exact sudoers
|
||||
command rules. None was installed on the VPS at this inventory. The current
|
||||
PR adds fixed root-side release/rollback receivers without adding a `codex`
|
||||
sudoers rule or Docker access. Neither receiver has been installed or run.
|
||||
- The former local-VPS rollback path has been superseded and now fails closed.
|
||||
The PR rollback path requires a root-pinned external archive identity,
|
||||
rechecks its exact bytes through the owner client, creates a fresh external
|
||||
backup before changing refs, and preserves a secret-free recovery journal on
|
||||
failure. Synthetic tests only; no production rollback was performed.
|
||||
- The image release workflow now starts after successful CI for a push to
|
||||
`main`. It checks the source workflow/event/branch/conclusion and exact source
|
||||
SHA, checks out that SHA, and uses both release and source run IDs in the
|
||||
schema-v4 descriptor. Registry secrets `REGISTRY_USERNAME` and
|
||||
`REGISTRY_PASSWORD` remain unconfigured/unverified; no values were created or
|
||||
inspected. PR image builds remain no-push. The descriptor SHA-256 is included
|
||||
in the artifact name, and the artifact also retains its checksum sidecar.
|
||||
The descriptor remains unsigned trace metadata, not cryptographic
|
||||
attestation.
|
||||
- A separate `deploy-handoff.yaml` runs after a successful release and checks
|
||||
the source run and stale-main guards. Its job is explicitly
|
||||
`NOT DEPLOYED - handoff status only`; a green result is not a deployment. It
|
||||
reads artifact metadata through `gitea-api` only if that helper is available
|
||||
in the job image; otherwise it reports metadata and host handoff as
|
||||
unverified. It does not download artifact ZIPs, connect to SSH, or apply a
|
||||
release. No repository workflow binding to a Windows runtime starts the
|
||||
receiver. PR #59 now proposes a separate disabled local `--once` trigger
|
||||
that queries a root-verified tuple; it is not installed or active. Image
|
||||
release is automated, but production deployment is not yet automatic CD. The original
|
||||
audited `gitea-api` helper lacks binary output and safe 302 handling; the
|
||||
current PR carries a tested patch and host-side artifact verifier, but
|
||||
neither is installed. No deploy key, fixed SSH entry, extra sudo rule, or
|
||||
Gitea CD variable has been configured. Production apply remains blocked on
|
||||
owner bootstrap, external backup and separate-target restore, and the other
|
||||
gates above.
|
||||
- A repository-scoped official `act_runner` `0.2.13` installation is
|
||||
configured in `infra/runner/`: rootless Docker under `akyldash-runner`, 15 GiB
|
||||
ext4 loop-backed image/workspace storage, capacity 1, per-job limits (2 CPU,
|
||||
3 GiB RAM, 512 processes), account slice limits (2.5 CPU, 4 GiB RAM, 2048
|
||||
tasks), rotated file logs, and a systemd health timer. Jobs target the
|
||||
`akyldash-ci` label and do not receive either Docker socket. Latest verified
|
||||
main CI run 175 and smoke run 176 succeeded on `b5adc092`. On 2026-10-18,
|
||||
SSH showed `akyldash-act-runner.service` active under `akyldash-runner`, with
|
||||
zero restarts and about 115 MiB current memory. Its rootless Docker store is
|
||||
mounted from `/dev/loop0` as ext4 with `rw,nosuid,nodev`; the 15 GiB mount had
|
||||
12 GiB free. The separate `akyldash-runner-restart.service` remains failed
|
||||
with exit status 1 since 2026-10-14; its journal had no entries, so the cause
|
||||
is unknown. The latest verified main CI run 75 and smoke run 76 succeeded on
|
||||
head `0e276ae6`. The Actions API returned 403 during this recheck, so no newer
|
||||
run state was independently retrieved. A read-only SSH recheck on 2026-10-21
|
||||
confirmed the active `akyldash-act-runner.service` runs as
|
||||
`akyldash-runner` with `ProtectHome=read-only`; `ReadWritePaths` includes the
|
||||
runner runtime/config/log paths and `/run/user/999`. Its `ExecStart` uses
|
||||
`/etc/akyldash-runner/config.yaml`. The live unit retains a writable carveout
|
||||
for `/run/user/999`; the installer keeps that existing carveout and changes
|
||||
`ProtectHome` from `yes` to `read-only` so the runtime path remains visible.
|
||||
No VPS unit was changed. Main commit
|
||||
`d2fb4b81` passed CI run 115 and smoke run 116. On
|
||||
head `3a89dc21`, CI run 63 failed at the host audit root guard and smoke run 64
|
||||
succeeded. On head `436806a8`, CI run 65 failed in the Caddy container action
|
||||
with `exec: "validate": executable file not found`; Kaniko was skipped and
|
||||
smoke run 66 succeeded. On head `d96fc4d3`, CI run 67 failed because the
|
||||
Caddy action's fixed `/github/workspace/...` path did not exist; Kaniko was
|
||||
skipped and smoke run 68 succeeded. On head `5d72bb09`, CI run 69 and smoke
|
||||
run 70 succeeded. CI validated the Caddyfile and built the backend and
|
||||
OpenSearch images using `${{ github.workspace }}`. Actual per-action
|
||||
resource-limit enforcement and peak usage were not independently measured or
|
||||
verified. Image publishing, host-wide resource metrics, and production
|
||||
deployment remain unverified. No VPS changes are made.
|
||||
- An isolated local Compose smoke test built backend/OpenSearch images,
|
||||
reached healthy status for OpenSearch, backend, and Caddy, and returned HTTP
|
||||
200 for `/review` through Caddy. Its containers, networks, and volumes were
|
||||
removed afterward. This does not verify VPS startup, DNS, or public TLS.
|
||||
- The app has no migration framework or SMTP setup. Repository versions on this
|
||||
branch are:
|
||||
backend `0.13.0`, frontend `0.2.0`, Telegram bot `0.2.2` (the bot is not
|
||||
deployed on this VPS).
|
||||
|
||||
## Corpus readiness (2026-10-18)
|
||||
|
||||
- The local raw archive and normalized corpus are ignored under `data/`; no
|
||||
corpus files were changed. Their read-only SQLite manifests both pass
|
||||
`quick_check` and each report 209,958 documents. The raw manifest is
|
||||
28,295,168 bytes with SHA-256
|
||||
`f8e3dd2fdec607583ca09cfdb5b76171bb7bfa1e41a0e07ee5aca8481e18e17e`; it has
|
||||
one fetch error, code `6`, absent from `documents`. The normalized manifest
|
||||
is 31,571,968 bytes with SHA-256
|
||||
`1679c20e6d0f3e5a9b50737c006c4417a28ebcaf7467d194d3bf8243538f83bf`; all
|
||||
entries are `success`, schema `1`, normalizer `1.0.0`.
|
||||
- The read-only full-file inventory in `/tmp/akyldash-corpus-audit.Mjr6aa`
|
||||
stopped before validation in run `b4a4556e30cc464d90bc8d75ef1673e9` with
|
||||
`Python int too large to convert to SQLite INTEGER`. At stop it had processed
|
||||
2,120,420 raw entries (1,081,428 files, 1,038,992 directories) and 397,856
|
||||
normalized entries (246,321 files, 151,535 directories). This is a verifier
|
||||
metadata storage failure, not a corpus finding. A full rehash with the
|
||||
corrected, versioned verifier is required before readiness can be stated.
|
||||
- A fresh full rehash is running in `/tmp/akyldash-corpus-audit-final.gtsD87vc`,
|
||||
run `f4dd5e53020f442bbbecee2d0e4986a6`, with verifier SHA-256
|
||||
`83dac230099fc91972cd14e86e9f8ec72d13bca08f53d402f13a169e096d98f5`.
|
||||
`result.json` currently reports `scan_status: running`; its live counters
|
||||
must be recorded after completion. Sources remain read-only.
|
||||
- Through the repository client, bounded MinJust OpenData requests for
|
||||
`GetDocumentListByQuery`, `GetDocument(6)`, control `GetDocument(1096)`, and
|
||||
`CheckAvailable` each returned HTTP `404`. The list API returned no code list;
|
||||
the direct requests do not establish whether code `6` exists. The public
|
||||
listing page is reachable, but it does not map the numeric API code. A
|
||||
metadata-only `CheckAvailable` request from the VPS failed in HTTP/2 with
|
||||
`curl` exit 92 (`INTERNAL_ERROR`), HTTP status `000`, and TLS verification 0;
|
||||
the HTTP/1.1 retry was not completed. Treat the code `6` disposition and
|
||||
full corpus readiness as unresolved.
|
||||
- On the VPS, read-only `stat` of `/var/lib/akyldash/data/minjust-normalized`
|
||||
and its manifest was denied. Production corpus presence and metadata remain
|
||||
unknown. No corpus was transferred and no production service, Docker socket,
|
||||
runner policy, or VPS configuration was changed.
|
||||
|
||||
## Current MinJust API staging (2026-10-20)
|
||||
|
||||
- The public site's current API uses `POST /api/v1/GetDocuments` with page size
|
||||
12, `GET /api/v1/GetDocument?DocumentCode=...`, and
|
||||
`GET /api/v1/GetEdition?editionId=...&lang=ru|kg`. A bounded page-1 probe
|
||||
reported 210,639 filtered records; no full listing was enumerated for this
|
||||
recovery. Official alias `1-4` resolves to canonical document code `205064`.
|
||||
- Document code `6` has 201 official editions. The API's `lang=kg` response
|
||||
places Kyrgyz HTML in `contentRu` while returning `contentKg=null`; staging
|
||||
maps by requested language (`kg` to archive `ky`) and preserves the edition
|
||||
order from the document response. Normalization and search export now retain
|
||||
and use that order instead of sorting IDs.
|
||||
- Without `exact=true`, one probe for edition `920292` returned response field
|
||||
`id=920492` despite a different text length/hash. Two bounded `exact=true`
|
||||
probes returned matching IDs and names/dates from `GetDocument`: edition
|
||||
`920292` / `04.08.1998` (485,487 RU characters, SHA-256
|
||||
`2b51c2ff4e9b91cbe2a7ed052a5a9ed9150bda993fc15c120ac948580926b718`) and
|
||||
edition `920492` / `13.04.2017` (1,139,908 RU characters, SHA-256
|
||||
`e5f0fdbb47766e5a5dbb971183d765e4c1dcaf9c969a218a84206244ce9132e8`).
|
||||
Every edition request now uses `exact=true`, requires returned ID equality,
|
||||
and checks RU/KY names against `GetDocument` metadata.
|
||||
- `backend/ingestion/minjust_current.py` stages one document into a separate
|
||||
generation, at no more than one request per second, with a 16 MiB response
|
||||
limit, a 4 GiB text budget per document, contract-bound checkpoints, and
|
||||
atomic publication. Staging requires a private 0700 directory owned by the
|
||||
current user and rejects symlinks under checkpoints/document paths; legacy
|
||||
corpus exclusions are anchored to the repository root. The corpus verifier
|
||||
continues to validate unchanged normalized manifests from versions 1.0.0
|
||||
and 1.1.0. The earlier non-exact pass is quarantined at
|
||||
`/tmp/akyldash-current-code6.ZAMC37u4ex/qualification.json`: its 240 language
|
||||
responses (304,493,520 bytes) remain unverified and are not reusable. The
|
||||
retained work-tree SHA-256 is
|
||||
`1e874c1d7fab1e00e7e45ff1b16422ea474e22ee13c901ac9a0612f47aa5d24a`.
|
||||
- Exact-only code-6 staging is complete at
|
||||
`/tmp/akyldash-current-code6-exact.L4k3AvnOlP`: 201 editions and 402
|
||||
complete language checkpoints, 604,377,885 raw bytes. The raw manifest
|
||||
passes `quick_check`; its document checksum matches the staged directory at
|
||||
`81d8e1a53b2ebef61f08b56d04b3f0a80077d587a4fadae0152bb4b7f13055ea`.
|
||||
Separate normalization at
|
||||
`/tmp/akyldash-current-code6-exact.L4k3AvnOlP-normalized` contains 201
|
||||
editions in official response order, passes `quick_check`, and records
|
||||
normalizer `1.1.0` (2,048,797,024 bytes). The prior `data/minjust-cbd` and
|
||||
`data/minjust-normalized` trees and production were not used as input or
|
||||
modified. The raw staging manifest still records attachments and embedded
|
||||
media as unverified; this single document does not establish corpus
|
||||
completeness or production readiness.
|
||||
|
||||
## Checks not completed
|
||||
|
||||
- Docker Engine version from the server API, container and volume inventory,
|
||||
protected env/secret metadata, sudoers, and detailed UFW rules require root.
|
||||
`infra/bootstrap/audit-host.sh` is provided for an owner-run read-only audit.
|
||||
- The backup archive/restore tool was tested with synthetic local data; a backup
|
||||
and restore of real production data remain unverified because production is
|
||||
not deployed.
|
||||
- Cloudflare edge response was checked; origin DNS target, origin certificate,
|
||||
Full (strict), registry publishing, host-wide runner metrics, and production
|
||||
deployment have not been verified. The
|
||||
owner-reported Idle state has not been independently checked through runner
|
||||
inventory because the API returned 403.
|
||||
- This audit made no host changes. No package or service was installed by this
|
||||
audit; the owner performed the initial bootstrap beforehand.
|
||||
|
||||
## Next owner actions
|
||||
|
||||
1. Install the approved root-owned checkout after its PR is reviewed, then run
|
||||
`sudo bash /opt/akyldash/current/infra/bootstrap/audit-host.sh` and share
|
||||
the output. The script prints no secret values and does not mutate the host.
|
||||
2. After reviewing the audit output and confirming the target files are absent,
|
||||
run
|
||||
`sudo bash /opt/akyldash/current/infra/deploy/prepare-production-config.sh`;
|
||||
it refuses to overwrite existing files. Set the approved `DATA_ROOT` and
|
||||
place the approved corpus/index and Cloudflare origin configuration. Do not
|
||||
deploy until data/service state and the required backup path are reviewed.
|
||||
3. Run `sudo bash /opt/akyldash/current/infra/deploy/install-helper.sh` after
|
||||
reviewing the checkout; it grants only fixed verification, Compose
|
||||
`config`/`status`, and guarded rollback commands.
|
||||
4. After merging the reviewed PR, confirm a subsequent CI and smoke run on
|
||||
`akyldash-local-ci`. Image publishing and production deployment remain manual and
|
||||
are not part of CI.
|
||||
5. Test backup/restore and rollback only with synthetic data in an isolated
|
||||
environment before any production deployment.
|
||||
|
||||
## Change in this PR
|
||||
|
||||
Adds a read-only, resumable full-file corpus inventory and normalized-data
|
||||
cross-check, a source/staging comparator requiring nonzero documents and
|
||||
fragments plus held shared artifact locks, synthetic regression tests, and an
|
||||
operator handoff runbook. CI's
|
||||
existing `infra/deploy` unittest discovery includes the new tests. No workflow,
|
||||
runner, VPS, production data, or Docker settings are changed. The first real
|
||||
corpus scan stopped on an integer-storage bug; full validation with the
|
||||
corrected verifier is still required. The source API's code `6` outcome remains
|
||||
unconfirmed.
|
||||
@@ -0,0 +1,10 @@
|
||||
# Infrastructure decisions
|
||||
|
||||
| Date | Decision | Reason and alternatives | Status / limits |
|
||||
|---|---|---|---|
|
||||
| 2026-10-11 | Use Docker Compose on the dedicated Ubuntu VPS | Matches the existing production Compose baseline and workload; Kubernetes adds no demonstrated need | Planned; Docker is not installed |
|
||||
| 2026-10-11 | Keep `codex` out of sudo and the Docker group | Docker socket access is effectively root; a separate installer can grant only a fixed read-only verifier and root-owned rollback helper after checkout ownership and sudoers validation | Helpers are defined in Git; not installed on VPS |
|
||||
| 2026-10-11 | Put Caddy and Search API on a proxy network and OpenSearch on a separate internal network | Keeps OpenSearch unreachable from the proxy and host; the API has no published host port | Repository Compose target only; not deployed |
|
||||
| 2026-10-11 | Use Caddy in Compose for HTTPS at `akyldash.kg` | Automatic certificate issuance/renewal keeps proxy config small; Nginx with separately managed certificates was considered | Caddy image pinned by digest; requires public ports 80/443 and owner confirmation of Cloudflare Full (strict) |
|
||||
| 2026-10-11 | Mount the review signing key as a Compose secret file | Avoids putting its value in command-line arguments; an environment variable or CLI value is easier to inspect in process metadata | Implemented in repository Compose; not deployed |
|
||||
| 2026-10-11 | Do not enable production deployment from Gitea Actions yet | Runner, package publishing scope, deploy-helper, backup/restore, and production health are not verified | Revisit after controlled end-to-end test |
|
||||
@@ -0,0 +1,237 @@
|
||||
# Deployment
|
||||
|
||||
## Status and authorization
|
||||
|
||||
The release and fixed-receiver code from PR #59 is on `main`, but has not been
|
||||
installed or exercised against the VPS. This PR's compatibility and Windows
|
||||
bootstrap changes are still proposed. No release, backup, restore, or
|
||||
production service operation has been performed by this change. Production
|
||||
deployment remains blocked until the owner has verified host state, registry
|
||||
access, protected configuration,
|
||||
corpus/index readiness, RU/KY canaries, an external backup, and restore on a
|
||||
separate target. See [current state](CURRENT_STATE.md) and the
|
||||
[owner evidence packet](DEPLOYMENT_OWNER_PACKET.md).
|
||||
|
||||
The existing `codex` account has no Docker socket access and receives no new
|
||||
privilege in this change. The external receiver requires an owner-controlled
|
||||
SSH entry that runs the fixed root command; no SSH key, `authorized_keys`
|
||||
entry, sudo rule, or root alias is created here. If `akyldash_vps` logs in as
|
||||
`codex`, it cannot run the root-only receiver and the client fails closed.
|
||||
Do not grant general sudo or Docker access to make the flow work.
|
||||
|
||||
## Release verification and image publication
|
||||
|
||||
`.gitea/workflows/ci.yaml` remains the required test and image-build workflow.
|
||||
The release workflow runs after successful main CI, verifies the source run and
|
||||
commit, and publishes digest-pinned images plus a small release descriptor.
|
||||
The descriptor records both the release workflow run ID and the successful CI
|
||||
source run ID. PR builds do not publish images. Production runtime secrets are
|
||||
not supplied to CI.
|
||||
|
||||
Read-only Gitea check on 2026-11-03 for current `main` SHA
|
||||
`f19faf628e67015febac22d0ec93ce4782caf4bf`: CI run #706 succeeded, release
|
||||
run #708 failed at the explicit registry-credential-presence check because
|
||||
`REGISTRY_USERNAME` and `REGISTRY_PASSWORD` are not configured, and handoff run
|
||||
#709 was skipped. No secret values were read. Image publication therefore
|
||||
remains blocked until the owner provisions the required registry secrets.
|
||||
|
||||
On the host, the fixed root receiver uses the installed `gitea-api` helper to
|
||||
re-fetch and verify the exact successful CI and release runs, current `main`,
|
||||
artifact name, checksum, manifest schema, builder pin, image policy, and commit
|
||||
binding. Its binary `DOWNLOAD` extension accepts HTTPS and at most one
|
||||
allowlisted HTTPS redirect, does not forward the token across origins, bounds
|
||||
the response, and refuses to overwrite an existing file. The installer checks
|
||||
the exact audited helper fixture hash before applying its patch. The helper
|
||||
and source code are not installed on the VPS by this PR.
|
||||
|
||||
## One-shot runtime binding and bootstrap compatibility
|
||||
|
||||
`main` includes a root-only, read-only status command and a fixed SSH dispatcher.
|
||||
The dispatcher accepts only the literal status or deploy command in
|
||||
`SSH_ORIGINAL_COMMAND`; it accepts no arguments and performs no shell
|
||||
evaluation. Status verifies successful current-main provenance, artifact
|
||||
metadata/ZIP, and host runtime compatibility before returning only a run ID,
|
||||
commit, and descriptor digest in a `prepared` response. It fails closed on a
|
||||
recovery journal, incomplete Gitea run listing, invalid release data, changed
|
||||
host runtime configuration, or an already applied release. The root receiver
|
||||
independently repeats release verification and the existing backup/ACK/cutover
|
||||
guards.
|
||||
|
||||
The Windows `--once` mode only polls the fixed read-only status endpoint and
|
||||
stores a protected local `PREPARED` tuple. It never sends a deploy request.
|
||||
Automatic deployment uses a second task and a separate
|
||||
`release-auto-apply.json` gate; both config files and both scheduler XML
|
||||
templates default to disabled. The apply task acts only when its current
|
||||
verified tuple exactly matches a tuple saved by a previous poll. An owner can
|
||||
also use `--apply-prepared`, which requires an interactive exact-SHA
|
||||
confirmation. Both deploy paths re-enter the existing root receiver and all
|
||||
backup/ACK/cutover guards. Rollback remains a separate explicit owner-run
|
||||
командой. Планировщик запускает задачи от интерактивного владельца с минимальными
|
||||
правами, пропускает повторный запуск при активном экземпляре и не будит компьютер.
|
||||
Этот PR не зарегистрировал и не включил ни одну задачу.
|
||||
|
||||
Сначала подготовьте bundle под обычной учётной записью из точной локальной
|
||||
вершины `main` командой `prepare_windows_release_bundle.py`. Упаковщик читает
|
||||
только Git objects указанного полного commit SHA, сверяет Git blob identity
|
||||
исходников и создаёт небольшой ZIP с SHA-256; рабочее дерево он не читает и не
|
||||
копирует. Elevated installer получает путь к ZIP, ожидаемый commit и SHA-256.
|
||||
Он один раз открывает пакет с запретом записи/удаления, проверяет SHA-256 архива,
|
||||
manifest и Git blob IDs в памяти, затем копирует только проверенные байты.
|
||||
Дополнительно installer проверяет цепочку Git objects `commit → tree → файлы`.
|
||||
На elevated этапе Git не запускается; `.git/config`, hooks и состояние checkout
|
||||
не используются. Не изменяйте ZIP между подготовкой и установкой.
|
||||
Упаковщик ставит всем ZIP entries тип regular file и mode `0100600`; installer
|
||||
проверяет тот же mode (`0x8180`) до чтения содержимого. Для проверки стыка
|
||||
упаковщика и фактической функции mode-валидации на Windows используйте
|
||||
`powershell.exe -NoProfile -File infra/deploy/test_windows_release_bundle_mode.ps1 -PythonPath C:\Python313\python.exe`;
|
||||
`git.exe` должен уже разрешаться обычным `PATH`. Harness создаёт синтетический
|
||||
Git репозиторий и временный ZIP, извлекает только эту функцию из PowerShell AST и
|
||||
проверяет принятие штатного пакета и отказ после изменения mode. Он не запускает
|
||||
installer, не требует elevation, не меняет ACL и не регистрирует задачи; политику
|
||||
выполнения PowerShell менять для него не следует.
|
||||
|
||||
Проверенный bootstrap installer проверяет подпись PSF у
|
||||
`C:\Python313\python.exe` и защищённые ACL, затем размещает файлы клиента в
|
||||
SHA-версионном каталоге `Program Files`, не перезаписывая существующую версию.
|
||||
Для новых файлов кода владельцем назначается `Administrators`. У кода владельцем
|
||||
могут быть только SYSTEM, Administrators или TrustedInstaller; учётная запись
|
||||
задачи допускается владельцем только для отдельного private state/config.
|
||||
Проверка ACL файла и защищённого каталога запрещает недоверенным субъектам запись,
|
||||
добавление, удаление, удаление дочерних объектов, смену прав или владельца. Для
|
||||
родительских каталогов проверяются права, способные подменить защищённый путь;
|
||||
разрешение создать посторонний соседний каталог подменой не считается.
|
||||
Installer сохраняет существующий canonical-файл
|
||||
`C:\ProgramData\Akyldash\release-trigger.json`, только если он выключен; второй
|
||||
disabled auto-apply config создаётся только при отсутствии. Installer формирует
|
||||
два disabled task XML для проверки владельцем, но не регистрирует и не включает
|
||||
задачи. Launcher запускает Python с `-B -E -s -S`, оставляет в import path только
|
||||
стандартную библиотеку и защищённый каталог клиента, затем проверяет происхождение
|
||||
импортированных модулей. До импорта receiver он заменяет унаследованный command
|
||||
lookup фиксированными каталогами Windows, OpenSSH и Git, очищает `GIT_*` и
|
||||
проверяет, что `ssh.exe`, `git.exe` и `powershell.exe` разрешаются в заданные пути.
|
||||
Для самих бинарников и их родительских каталогов проверяются reparse points,
|
||||
владельцы и ACL по правилам выше. Тесты подмены Python imports и command paths
|
||||
выполнены на Linux; installer и launcher на Windows не запускались. Оставляйте оба
|
||||
config gate и обе задачи выключенными до фиксации владельцем обычных backup/restore
|
||||
и production readiness gate. Не привязывайте Windows-хост к Gitea workflow или PR runner.
|
||||
|
||||
The root status/deploy helper remains the reviewed root-installed bootstrap
|
||||
code; it never checks out or executes target release code. A newer app release
|
||||
is eligible without manually advancing `/opt/akyldash/current` only when the
|
||||
host's Compose file, Caddyfile, and installed release policy match the exact
|
||||
bytes at the prepared commit in Gitea. File metadata is pinned to that commit;
|
||||
the Git blob SHA and size are verified. Status checks before preparing the
|
||||
tuple; the receiver repeats the check before creating a journal or stopping
|
||||
services, and cutover checks again after the verified external backup and
|
||||
immediately before switching image references. A Compose/Caddy mismatch
|
||||
returns `runtime_config_changed`; a policy mismatch returns
|
||||
`release_policy_changed` and requires a reviewed owner bootstrap update. No
|
||||
host checkout or root helper is automatically changed. The release must still
|
||||
be current `main`; CI/release provenance, digest, backup, canary, and rollback
|
||||
checks remain required. Gitea's filtered workflow-run listing is bounded to
|
||||
ten entries; if Gitea reports more entries or an inconsistent page, status
|
||||
returns unavailable rather than guessing.
|
||||
|
||||
## Automation boundary: deployment is not active
|
||||
|
||||
Until the owner separately activates both Windows tasks and the auto-apply
|
||||
configuration after the backup/restore and production gates, the chain ends at
|
||||
release publication. After that explicit one-time owner authorization, the
|
||||
prepared-state poll and separate apply task can process later matching
|
||||
application releases without advancing `/opt/akyldash/current` or approving
|
||||
each commit individually. A release that changes protected runtime files still
|
||||
requires a reviewed bootstrap update.
|
||||
|
||||
1. Successful `main` CI triggers image builds and publishes digest references
|
||||
plus the release descriptor artifact.
|
||||
2. `deploy-handoff.yaml` verifies the source run and may read artifact metadata.
|
||||
Its job is explicitly status-only: **NOT DEPLOYED**. It does not download
|
||||
the descriptor ZIP, call the Windows client, open SSH, or invoke the root
|
||||
receiver. A green result means only that this status check completed.
|
||||
3. The fixed receiver is physically started only by the separately enabled
|
||||
owner-controlled auto-apply task or by an interactive owner command. The
|
||||
`--once` preparation task stores a verified tuple and never sends deploy;
|
||||
the separate apply task requires the tuple to match a fresh status response.
|
||||
No repository workflow invokes either task. Both scheduler templates and
|
||||
both configuration gates remain disabled, and neither task has been
|
||||
installed or exercised.
|
||||
|
||||
Production CD is still not active: task/credential setup has not been verified,
|
||||
and no VPS or live D: operation has been performed. This design avoids a
|
||||
Windows Actions runner entirely; the owner-controlled local task is not exposed
|
||||
to PR jobs. The SSH account/key must be restricted to the exact dispatcher
|
||||
commands and verified host key. Do not use an unrestricted `authorized_keys`
|
||||
entry or a persistent host-mode runner with D: and SSH access.
|
||||
|
||||
## External backup and cutover
|
||||
|
||||
The fixed root release receiver accepts only a bounded protocol request over
|
||||
stdin. It does not accept a remote shell command, artifact path, or image
|
||||
reference from the caller. It rechecks the release and current `main`, takes a
|
||||
shared lock, captures running image IDs, and stops the stack. It streams the
|
||||
cold archive directly to the owner's Windows client at
|
||||
`D:\Dev\akyldash\.backups`; the VPS does not hold a full archive, including
|
||||
temporarily. The Windows client requires a real NTFS destination with private
|
||||
ACLs and a precise local Git exclude rule. It publishes only after hash,
|
||||
archive, and manifest verification, and acknowledges the exact live session
|
||||
nonce and backup identity.
|
||||
|
||||
Only after the acknowledgement does the host pull approved digest references,
|
||||
atomically replace both image refs, and start Compose with `--no-build`. It
|
||||
checks running image IDs, `/review`, and non-empty Russian and Kyrgyz search
|
||||
canaries. A stale main, source mismatch, invalid archive, image mismatch, or
|
||||
failed health/canary check stops cutover and attempts recovery using the
|
||||
pre-change references. A recovery journal blocks another operation if
|
||||
automatic recovery cannot be verified.
|
||||
|
||||
Rollback uses the root-pinned prior external archive and creates a fresh
|
||||
external backup of current state before switching refs. It restores images
|
||||
only, not data. Old local VPS backup paths and legacy release states without a
|
||||
pinned external backup identity are rejected. See [backup and restore](BACKUP.md)
|
||||
and [rollback](ROLLBACK.md).
|
||||
|
||||
The receiver records a durable pending recovery journal before stopping
|
||||
services. A retry of the exact release already recorded in pinned state is
|
||||
rejected before backup or downtime. Gitea source verification requires
|
||||
`status=completed` and `conclusion=success`, and resolves current `main` from
|
||||
the explicit production checkout. The Windows client checks the destination,
|
||||
ACL, ignore rule, and full protocol archive capacity before opening SSH.
|
||||
|
||||
## Owner bootstrap still required
|
||||
|
||||
After review and merge, the owner must decide whether to install the helper
|
||||
from a root-owned checkout and provision, without exposing values in logs:
|
||||
|
||||
- a read-only Gitea API token in `/etc/akyldash/gitea-api-token`, root-owned
|
||||
mode `0600`;
|
||||
- the exact artifact redirect origin allowlist in
|
||||
`/etc/akyldash/gitea-download-origins`, if the Gitea artifact endpoint
|
||||
redirects;
|
||||
- approved Russian and Kyrgyz search canaries in
|
||||
`/etc/akyldash/release-canaries.json`, root-owned mode `0600`;
|
||||
- a root-only SSH path to `/usr/local/sbin/akyldash-release-deploy` and
|
||||
`/usr/local/sbin/akyldash-release-rollback` using the existing owner key and
|
||||
verified host key.
|
||||
- a dedicated SSH alias `akyldash_release` backed by a key restricted to
|
||||
`/usr/local/sbin/akyldash-release-dispatch`; its forced command must preserve
|
||||
exact `SSH_ORIGINAL_COMMAND` matching and grant no shell, forwarding, PTY,
|
||||
or arbitrary command access;
|
||||
- a protected installation of the Windows client under
|
||||
`C:\Program Files\Akyldash`, with both config files and both Task Scheduler
|
||||
XML templates reviewed. Keep the preparation task/config separate from the
|
||||
auto-apply task/config; the auto-apply pair remains disabled until the owner
|
||||
explicitly accepts unattended production deployment.
|
||||
|
||||
The installer intentionally does not create credentials, SSH entries, canary
|
||||
values, registry permissions, or a new privilege rule. Existing files with
|
||||
unexpected owner, mode, or content cause installation to stop for owner
|
||||
review. Do not run the installer or receiver from CI. The owner's first use
|
||||
must be a separate-target restore check and a reviewed dry run; this PR does
|
||||
not authorize a production cutover.
|
||||
|
||||
The Windows client uses the existing OpenSSH host-key checking. Its configured
|
||||
alias must reach a root-controlled endpoint capable of invoking the fixed
|
||||
receiver; no new key or sudo permission is requested. Windows ACL and NTFS
|
||||
checks, SSH host configuration, artifact redirect origin, registry pull
|
||||
access, and every production health gate remain unverified until the owner
|
||||
checks them.
|
||||
@@ -0,0 +1,125 @@
|
||||
# Пакет проверок владельца перед деплоем
|
||||
|
||||
Здесь перечислены проверки, которые выполняет владелец. Этот документ не
|
||||
разрешает production-изменения. Не включайте значения токенов и паролей,
|
||||
содержимое env-файлов, приватные ключи, другие секреты или полный вывод
|
||||
переменных окружения.
|
||||
|
||||
## Что требуется до использования CD
|
||||
|
||||
- Отключённый одноразовый Windows trigger из PR #59 уже находится в `main`, но
|
||||
не установлен и не запускался. Bootstrap из этого PR также не установлен.
|
||||
После ревью и слияния обновите локальный `main` до проверенного полного SHA.
|
||||
Под обычным пользователем подготовьте bundle командой
|
||||
`prepare_windows_release_bundle.py --repository D:\Dev\akyldash --commit <SHA> --output <new ZIP path>`.
|
||||
Упаковщик требует, чтобы SHA совпадал с локальной вершиной `main`; он читает
|
||||
Git objects этого commit, а не рабочее дерево, проверяет SHA-1 объектов
|
||||
commit/tree/blob и печатает SHA-256 ZIP. Передайте именно эти SHA и путь
|
||||
elevated installer:
|
||||
`install_windows_release_client.ps1 -ExpectedCommit <SHA> -BundlePath <path> -ExpectedBundleSha256 <digest>`.
|
||||
Installer открывает ZIP один раз с запретом записи и удаления, сверяет SHA-256,
|
||||
manifest и цепочку `commit → tree → файлы` в памяти и только после полной
|
||||
проверки копирует эти байты. Elevated installer не запускает Git и не читает
|
||||
`.git/config`, hooks или файлы checkout. Не меняйте ZIP между подготовкой и
|
||||
установкой; сохраните SHA и полный commit для журнала владельца.
|
||||
- Installer проверяет подпись PSF у `C:\Python313\python.exe` и защищённые
|
||||
ACL, создаёт версионный каталог в `Program Files` без перезаписи существующей
|
||||
версии и назначает владельцем новых файлов кода `Administrators`. Кодовые
|
||||
пути должны принадлежать только SYSTEM, Administrators или TrustedInstaller;
|
||||
учётная запись задачи допускается владельцем только для отдельных private
|
||||
state/config. ACL-проверка файла/кодового каталога выявляет запись, добавление,
|
||||
удаление, удаление дочерних объектов, смену ACL и владельца. Проверка родительских
|
||||
каталогов выявляет права, позволяющие заменить защищённый путь; создание
|
||||
постороннего соседнего каталога само по себе не считается подменой.
|
||||
- Installer сохраняет существующий `C:\ProgramData\Akyldash\release-trigger.json`
|
||||
только если он остаётся отключённым, создаёт disabled auto-apply config лишь
|
||||
при отсутствии и формирует два disabled Task Scheduler XML для проверки.
|
||||
Он не регистрирует и не включает задачи. Путь trigger известен, но содержимое
|
||||
и его enabled-состояние не читались.
|
||||
- Launcher использует проверенный `C:\Python313\python.exe` с `-B -E -s -S`,
|
||||
проверяет происхождение импортированных модулей, заменяет унаследованный `PATH`,
|
||||
очищает `GIT_*` и фиксирует разрешение `ssh.exe`, `git.exe` и `powershell.exe`
|
||||
в доверенные пути. Задача подготовки сохраняет защищённый `PREPARED` tuple и
|
||||
никогда не отправляет deploy-запрос.
|
||||
- Задача auto-apply и её отдельный конфиг тоже остаются выключенными. Одного
|
||||
`enabled` в preparation config недостаточно для деплоя. Auto-apply разрешён,
|
||||
только если свежий root status точно совпал с tuple, сохранённым предыдущим
|
||||
опросом. После явного согласования владельцем unattended deployment отдельное
|
||||
подтверждение каждого SHA не требуется. Включайте preparation config и задачу
|
||||
только после отдельного разрешения на опрос; auto-apply config и задачу — только
|
||||
после отдельного разрешения на unattended production deployment и выполнения
|
||||
всех backup/restore gate. Отключение любого auto-apply control останавливает
|
||||
будущие автодеплои; уже начатый cold backup/deploy должен завершиться либо быть
|
||||
восстановлен по процедуре.
|
||||
- Ключ `akyldash_release` должен быть отдельным и привязанным к root forced-command
|
||||
dispatcher с OpenSSH `restrict` (или эквивалентным запретом PTY и forwarding),
|
||||
проверкой host key и точным сопоставлением status/deploy-команд. Не добавляйте
|
||||
unrestricted shell или команду в root `authorized_keys`. Существующий ключ и
|
||||
путь rollback остаются отдельным ручным действием владельца. PR не создаёт,
|
||||
не копирует и не устанавливает ключи.
|
||||
- Решите, допустим ли unattended production CD. Сейчас он не включён:
|
||||
`deploy-handoff.yaml` остаётся только status-проверкой и сообщает
|
||||
`NOT DEPLOYED`; обе локальные задачи и оба config gate выключены. Windows-хост
|
||||
не открыт workflow и PR runner. Убедитесь, что root status command установлен
|
||||
из проверенного bootstrap и ключ forced command ограничен.
|
||||
- Checkout на хосте не обязан совпадать с текущим `main`: status сравнивает
|
||||
защищённые root Compose/Caddy файлы и установленную release policy с файлами
|
||||
точного candidate SHA через pinned Gitea Contents API и проверяет Git blob IDs
|
||||
и размеры. Receiver повторяет сравнение до остановки сервисов; cutover повторяет
|
||||
его после backup. Несовпадение требует отдельного проверенного owner bootstrap
|
||||
update; код release или root helper автоматически не выполняется и не обновляется.
|
||||
Текущий `main` и CI/release provenance всё равно перепроверяются перед apply.
|
||||
Endpoint закрывается при неполной странице workflow-run API (более десяти
|
||||
кандидатов или несовпадение count). Перед включением проверьте поведение этого
|
||||
API на установленной версии Gitea.
|
||||
- Подтвердите имена registry packages и минимальные права записи/чтения для
|
||||
`admin/akyldash/backend` и `admin/akyldash/opensearch`; сохраните digest не
|
||||
короче rollback window. Последняя read-only проверка Gitea: main CI run #706
|
||||
завершился успешно, image release run #708 завершился ошибкой из-за отсутствия
|
||||
repository secrets `REGISTRY_USERNAME` и `REGISTRY_PASSWORD`, status-only
|
||||
handoff run #709 был пропущен. Добавьте эти secrets через настройки Gitea;
|
||||
не помещайте значения в Git или логи.
|
||||
- Проверьте, что срок хранения Gitea artifacts покрывает rollback window.
|
||||
Workflow запрашивает хранение небольшого release descriptor и checksum на 90 дней.
|
||||
- Подготовьте датированный очищенный root audit: SHA установленного checkout,
|
||||
Compose services и image IDs, состояние health, пути и режимы volumes,
|
||||
владельца/режим защищённых файлов, сводку listeners и состояние recovery journal.
|
||||
- Подтвердите root-controlled SSH путь для фиксированных deploy/rollback-команд,
|
||||
используя существующую owner SSH-конфигурацию и проверенный host key. Репозиторный
|
||||
`codex` не должен получать общий sudo, членство в Docker group или Docker socket.
|
||||
PR не устанавливает SSH key или root alias.
|
||||
- Если потребуется, установите узко ограниченный read-only Gitea API token в
|
||||
`/etc/akyldash/gitea-api-token`, владелец root, mode `0600`. Запишите только
|
||||
наличие и scope токена, не его значение.
|
||||
- Проверьте origin скачивания Gitea artifacts. При redirect добавляйте только
|
||||
точный HTTPS origin в `/etc/akyldash/gitea-download-origins`, root-owned,
|
||||
mode `0600`. Исправленный helper не должен отправлять этому origin token.
|
||||
- Добавьте одобренные владельцем RU и KY search canary queries в
|
||||
`/etc/akyldash/release-canaries.json`, root-owned, mode `0600`. Убедитесь, что
|
||||
они возвращают ожидаемые непустые результаты; не передавайте тексты корпуса.
|
||||
- Проверьте TLS mode Cloudflare, продление origin certificate и текущую доступность
|
||||
публичных `/review` и search.
|
||||
|
||||
## Backup и восстановление
|
||||
|
||||
- Полный архив хранится только на Windows-носителе владельца
|
||||
`D:\Dev\akyldash\.backups`; не размещайте полный архив на VPS.
|
||||
- Synthetic Windows protocol проверки и временная private-NTFS owner-ACL fixture
|
||||
прошли. До использования проверьте реальный путь D: и локальное правило
|
||||
`.git/info/exclude`; затем подтвердите, что одобренный backup публикуется только
|
||||
после проверки hash и manifest.
|
||||
- Подтвердите шифрование D: при хранении. Архив содержит production secrets и
|
||||
private keys; протокол шифрует передачу, но не хранение файлов.
|
||||
- Восстановите проверенный архив на отдельной изолированной цели и проверьте данные,
|
||||
SQLite integrity, OpenSearch и необходимые secrets. Не проверяйте restore на production.
|
||||
- Подтвердите текущие counts данных и индекса, corpus generation и совместимость
|
||||
миграций. Откат образа не восстанавливает данные и не отменяет изменения схемы.
|
||||
- Задайте срок хранения архивов и сохраняйте предыдущий проверенный архив весь
|
||||
rollback window.
|
||||
|
||||
Installer не создаёт credentials, SSH configuration, canary values, доступ к
|
||||
registry или новые sudo rules. PR не установлен и не запускался на production.
|
||||
Windows validation прошла 12 synthetic client checks, 8 protocol checks и временную
|
||||
private owner-ACL fixture на NTFS. Installer и launcher на Windows не запускались;
|
||||
реальный путь D:, SSH, полный backup и restore на отдельную цель не проверены.
|
||||
Не включайте deployment до фиксации владельцем результатов всех проверок выше.
|
||||
@@ -0,0 +1,59 @@
|
||||
# Infrastructure
|
||||
|
||||
## Intended layout
|
||||
|
||||
Production is planned for the dedicated Ubuntu VPS at `206.223.249.118`.
|
||||
`deploy/production/compose.yaml` defines Caddy, a Python Search API, and private
|
||||
OpenSearch 3.7. Caddy terminates HTTPS for `akyldash.kg` and proxies to the API.
|
||||
The API is reachable only on private Compose networks; OpenSearch is reachable
|
||||
only by the backend. Cloudflare should use Full (strict) only after the origin
|
||||
certificate and DNS path are verified.
|
||||
|
||||
The API stores its account and review SQLite files beside the normalized corpus
|
||||
under the persistent data directory. OpenSearch and Caddy use named volumes.
|
||||
The API's review signing key is mounted from a host file; it is not passed in
|
||||
process arguments or committed to Git. Docker logs are bounded to 10 MiB per
|
||||
file and three files per service.
|
||||
|
||||
## Actual state
|
||||
|
||||
The 2026-10-11 read-only audit found a fresh Ubuntu 24.04.5 host with SSH only.
|
||||
Docker, Git, a reverse proxy, application directories, Compose services, TLS,
|
||||
and backups are not installed/configured. The `codex` account has no
|
||||
non-interactive sudo. See [CURRENT_STATE.md](CURRENT_STATE.md) and the
|
||||
[production inventory](../../infra/inventory/production.yml).
|
||||
|
||||
The Compose file is a repository target, not proof of deployment. The Caddy
|
||||
image is pinned by digest, while backend and OpenSearch still build locally;
|
||||
immutable registry images and automated deploy are not configured. No migration
|
||||
framework exists. The application uses SQLite and OpenSearch; SMTP
|
||||
registration/recovery is not implemented.
|
||||
|
||||
## Repository paths and target host paths
|
||||
|
||||
- Compose and Dockerfiles: `deploy/production/`.
|
||||
- Host checkout target: `/opt/akyldash/current`.
|
||||
- Environment configuration: `/etc/akyldash/production.env`.
|
||||
- Secret file: `/etc/akyldash/review_secret`, mode `0600`.
|
||||
- Application data: `/var/lib/akyldash/data`.
|
||||
- Intended backups: `/var/backups/akyldash`.
|
||||
|
||||
All host paths above are targets; none existed at audit time. Root bootstrap is
|
||||
prepared at [bootstrap-ubuntu-24.04.sh](../../infra/bootstrap/bootstrap-ubuntu-24.04.sh).
|
||||
It does not edit SSH or firewall configuration, create credentials, deploy the
|
||||
application, or grant `codex` Docker/root access.
|
||||
|
||||
## Network and operations
|
||||
|
||||
Target public TCP listeners are SSH `22` and Caddy `80`/`443`. Backend `8080`
|
||||
and OpenSearch `9200` must remain private to Compose. The
|
||||
firewall state could not be independently verified because the SSH account has
|
||||
no sudo; do not change it without owner approval. The domain resolves to
|
||||
Cloudflare edge addresses, but HTTP and HTTPS return `521`, so the origin is
|
||||
unreachable. Cloudflare origin mode, certificate validity, and production
|
||||
health have not been verified.
|
||||
|
||||
Use [DEPLOYMENT.md](DEPLOYMENT.md), [BACKUP.md](BACKUP.md),
|
||||
[ROLLBACK.md](ROLLBACK.md), and [RECOVERY.md](RECOVERY.md) for operational
|
||||
limits and procedures. Configuration changes must go through Git and review;
|
||||
do not reconcile a Git/server difference by overwriting the VPS automatically.
|
||||
@@ -0,0 +1,47 @@
|
||||
# Recovery on a clean VPS
|
||||
|
||||
## Scope and safety
|
||||
|
||||
The bootstrap below prepares Ubuntu packages and directories only. It is not a
|
||||
complete recovery: production secrets, data, reverse proxy, TLS, registry
|
||||
credentials, backup restore, and deploy-helper still require owner-controlled
|
||||
setup. Run only on the new recovery host after verifying its identity. Never
|
||||
run recovery commands against the existing production by accident.
|
||||
|
||||
## Procedure
|
||||
|
||||
1. Provision a clean Ubuntu Server 24.04 host and confirm hostname, IP, console
|
||||
access, and a tested owner recovery path.
|
||||
2. Create the SSH-authorized `codex` account without sudo or Docker group access.
|
||||
Preserve the host's existing root SSH and firewall policy until an owner has
|
||||
reviewed the change.
|
||||
3. Check out the approved Git revision, root-owned and not group/world-writable,
|
||||
at `/opt/akyldash/current`, then run
|
||||
`sudo bash infra/bootstrap/bootstrap-ubuntu-24.04.sh --recovery-target`. The
|
||||
recovery mode refuses the inventoried production hostname/IP and writes a
|
||||
root-only marker at `/etc/akyldash/recovery-target`. It installs Docker
|
||||
Engine, Compose, Git, Docker log limits, and target directories.
|
||||
4. Install the limited read-only verifier and rollback helper with
|
||||
`sudo bash infra/deploy/install-helper.sh`. It validates the root-owned
|
||||
checkout and gives `codex` access only to those fixed commands.
|
||||
5. Configure DNS to point through Cloudflare to the recovery host and allow the
|
||||
owner to review/open TCP `80` and `443`. The production Compose Caddy service
|
||||
obtains its origin certificate automatically. Verify Cloudflare Full
|
||||
(strict) end to end before cutover.
|
||||
6. Transfer the protected backup to the new host through the owner's approved
|
||||
channel. The archive contains the production environment and review secret;
|
||||
keep it root-only and never paste secret values into chat.
|
||||
7. Extract the verified archive to a new `/var/tmp/akyldash-restore-*` staging
|
||||
directory with `infra/backup/archive.py`, then run
|
||||
`sudo python3 infra/backup/apply_restore.py --staging-dir <staging-dir>`.
|
||||
Apply requires the recovery marker, matching clean Git revision, empty data
|
||||
path, absent Compose volumes/config files, and no running containers. It
|
||||
refuses the inventoried production host and leaves services stopped.
|
||||
8. Build the backend and OpenSearch images from the matching checked-out Git
|
||||
revision and explicitly start Compose with `--wait`. Verify HTTPS and
|
||||
container health, record the backend image ID as described in
|
||||
[DEPLOYMENT.md](DEPLOYMENT.md), then record actual versions and checks in
|
||||
[CURRENT_STATE.md](CURRENT_STATE.md).
|
||||
|
||||
Do not repoint DNS or retire the old host until the owner verifies recovery and
|
||||
approves the cutover. The restore and cutover have not been practiced yet.
|
||||
@@ -0,0 +1,34 @@
|
||||
# Rollback
|
||||
|
||||
The current rollback implementation is code only. PR #59 has not been merged,
|
||||
installed, or run against the VPS. No current production release state or
|
||||
external backup has been verified; production rollback is therefore not
|
||||
available yet.
|
||||
|
||||
After owner installation and separate-target restore validation, rollback is
|
||||
an owner-controlled Windows-to-VPS session. The Windows client reads the exact
|
||||
previous backup identity pinned in root-owned release state, validates the
|
||||
saved archive and sidecar, then sends it over SSH. The VPS accepts the bytes
|
||||
only when size and SHA-256 match that root-pinned identity. It verifies the
|
||||
current deployment against release state, stops Compose, and streams a fresh
|
||||
cold backup to Windows before changing either image reference.
|
||||
|
||||
The rollback helper verifies deployment-file hashes, previous image refs and
|
||||
image IDs, and that the fresh backup matches the current image IDs. It does not
|
||||
restore application data, OpenSearch contents, or secrets. It uses the shared
|
||||
deployment lock, atomically switches both image references, starts Compose
|
||||
with `--no-build`, verifies running image IDs and the local `/review` health
|
||||
route, then records the new release state. Failures attempt to restore the
|
||||
pre-rollback references and services; unresolved recovery is recorded in a
|
||||
root-owned journal and blocks subsequent release/rollback operations.
|
||||
|
||||
The former `akyldash-rollback <VPS path>` interface now fails closed and performs
|
||||
no Docker operation. Local `/var/backups/akyldash` archives cannot authorize a
|
||||
rollback. Legacy release states without a verified external `previous_backup`
|
||||
identity also cannot authorize this rollback path.
|
||||
|
||||
The application has no formal migration framework. Check schema and index
|
||||
compatibility before rollback. If compatibility is uncertain, stop; do not
|
||||
attempt a data restore as part of an image rollback. A data restore requires a
|
||||
separate owner-approved recovery plan and maintenance window. See
|
||||
[backup and restore](BACKUP.md) and [deployment](DEPLOYMENT.md).
|
||||
@@ -1,19 +1,37 @@
|
||||
# Статус проекта
|
||||
|
||||
Последняя проверка: 2026-08-14
|
||||
Последняя проверка: 2026-10-10
|
||||
Назначение документа: быстро восстановить контекст проекта для участников команды и будущих агентов.
|
||||
|
||||
- Telegram-бот: `0.2.2`
|
||||
- Telegram-бот на Synology: `0.2.1`
|
||||
- Backend: `0.5.0`
|
||||
- Frontend: не создан
|
||||
- Backend: `0.12.2`
|
||||
- Frontend: `0.1.2` — поиск, лаборатория релевантности, аккаунты
|
||||
|
||||
## Краткий итог
|
||||
|
||||
Репозиторий переориентирован с отдельного бота на весь проект юридической информационно-аналитической платформы. Telegram-бот выделен в инструмент рабочего окружения. Реализованы возобновляемая выгрузка документов из официального Open Data API ЦБД Минюста КР и их локальная воспроизводимая нормализация.
|
||||
|
||||
Ближайшая цель — оценить полный локальный индекс на 50–100 запросах RU/KY и
|
||||
настроить ранжирование до начала разработки поискового API.
|
||||
Поисковая система и внутренняя лаборатория оценки выдачи реализованы. Ближайшая
|
||||
цель — проверить собственную выдачу на практических RU/KY-запросах, разобрать
|
||||
оценки юристов и зафиксировать baseline. ЦБД Минюста служит источником для
|
||||
проверки документов и редакций, а не системой для сравнения поисковой выдачи.
|
||||
|
||||
### Точка остановки на 2026-09-18
|
||||
|
||||
- В PR #37 из ветки `feature/tax-profit-search-intent` тематический запрос
|
||||
«налог на прибыль» поднимает действующий НК КР; для обычных запросов сохранён
|
||||
`cross_fields`, добавлено усиление точной фразы. Нужна дальнейшая проверка на
|
||||
контрольном наборе запросов.
|
||||
- Независимое ревью поискового кода не выявило дефектов; замечание об устаревшем
|
||||
handoff исправлено. Backend-тесты: 33 пройдены, 1 пропущен;
|
||||
`git diff --check` чистый.
|
||||
- Текущий локальный backend-контейнер при последней проверке был `0.10.2`;
|
||||
изменения ветки (`0.10.3`) не развёрнуты. Не деплоить без отдельного запроса.
|
||||
- В рабочем дереве есть постороннее пользовательское изменение `.gitignore`;
|
||||
не включать его в коммиты и не удалять.
|
||||
- Следующий шаг: повторно проверить полный diff PR #37 и после успешных проверок
|
||||
передать его на слияние; затем продолжить оценку поиска на контрольном наборе.
|
||||
|
||||
## Уже сделано
|
||||
|
||||
@@ -77,6 +95,8 @@
|
||||
- Полный проход завершён: 209 958 документов нормализованы без ошибок.
|
||||
- Контрольная выборка RU/KY прошла проверки текста, фрагментов, ID и SHA-256.
|
||||
- Добавлены строгий mapping и атомарный Bulk NDJSON-экспорт для OpenSearch.
|
||||
- На предыдущей итерации использовались Excel/PDF-бланки юридической проверки;
|
||||
текущий процесс опирается на relevance set и внутреннюю лабораторию.
|
||||
|
||||
### Развёртывание
|
||||
|
||||
@@ -90,8 +110,9 @@
|
||||
|
||||
### Развёртывание и сопровождение
|
||||
|
||||
- Docker-конфигурация развёртывания не хранится в репозитории.
|
||||
- Не настроен CI/CD.
|
||||
- Production Compose, Ubuntu bootstrap и drift-проверка описаны в репозитории.
|
||||
- CI workflow добавлен в PR #42, но его Gitea run остаётся в очереди; наличие
|
||||
runner и автоматический production-деплой не подтверждены.
|
||||
|
||||
### Хранилище
|
||||
|
||||
@@ -112,6 +133,20 @@
|
||||
- Не настроены уведомления Gitea.
|
||||
- Не проведён полный пользовательский тест: сообщение → сохранение → экспорт → анализ в ChatGPT → возврат отчёта.
|
||||
|
||||
### Готовность поиска к публичному frontend
|
||||
|
||||
- Реализована внутренняя лаборатория для просмотра и оценки фактической
|
||||
выдачи OpenSearch; пилот с юристами ещё не проведён.
|
||||
- Не завершена независимая юридическая проверка всех 50 запросов relevance set
|
||||
v1; спорные строки нельзя включать в baseline.
|
||||
- Не зафиксированы неизменяемая копия подтверждённого relevance set и baseline
|
||||
`Recall@10`/`MRR@10`.
|
||||
- Публичный readiness gate остаётся открытым: нужны обновление корпуса,
|
||||
переиндексация, проверка выдачи и API-сценарии для RU, KY и одноязычных актов.
|
||||
- Создан внутренний авторизованный frontend поиска и лаборатории; первая
|
||||
учетная запись `admin` создаётся CLI-командой, новых пользователей добавляет
|
||||
только `admin`.
|
||||
|
||||
## Важные неизвестные
|
||||
|
||||
По мере реального использования нужно принять решения по следующим вопросам:
|
||||
@@ -122,19 +157,40 @@
|
||||
|
||||
## Следующий этап
|
||||
|
||||
### Фиксация MVP и проверка полного цикла
|
||||
### Проверка собственной поисковой выдачи
|
||||
|
||||
Рекомендуемый порядок:
|
||||
|
||||
1. Настроить резервное копирование `/volume1/docker/akyldash/data`.
|
||||
2. Зафиксировать состав MVP с командой и закрыть тему `MVP`.
|
||||
3. Провести одно реальное обсуждение с ответами, правками и вложением.
|
||||
4. Экспортировать обсуждение и вручную проанализировать Markdown в ChatGPT.
|
||||
5. Вернуть подтверждённый итог в тему `Решения` и зафиксировать его в Git/Gitea.
|
||||
6. Записать обнаруженные неудобства и только после этого выбирать следующую доработку.
|
||||
1. Подготовить согласованный RU/KY relevance set: фиксировать потребность
|
||||
запроса и подтверждённые `document_code`, не ориентируясь на порядок выдачи.
|
||||
2. Проверить практические запросы во внутренней лаборатории `/review`, сохранить
|
||||
снимки и оценки фактических результатов OpenSearch.
|
||||
3. Разобрать ошибки ранжирования, сохранить baseline и повторить ту же проверку
|
||||
после изменений.
|
||||
4. Затем пройти readiness gate issue #21 для корпуса, индекса и Search API перед
|
||||
подготовкой публичного frontend.
|
||||
|
||||
## История изменений статуса
|
||||
|
||||
### 2026-09-12
|
||||
|
||||
- Внутренняя лаборатория оценивает фактическую выдачу собственного OpenSearch;
|
||||
ЦБД Минюста используется только для проверки источников и редакций актов.
|
||||
- Backend `0.8.3`; закрытая внутренняя лаборатория готова к пилоту.
|
||||
|
||||
### 2026-09-06
|
||||
|
||||
- Подготовлены бланки независимой юридической проверки relevance set v1 для
|
||||
русского и кыргызского языков и инструкция для юриста.
|
||||
- Ближайшим этапом зафиксированы юридическая верификация, baseline качества
|
||||
поиска и финальный readiness gate перед frontend.
|
||||
|
||||
### 2026-08-18
|
||||
|
||||
- Оценщик поиска использует `cross_fields` для совместного сопоставления
|
||||
названия и текста документа.
|
||||
- На размеченном наборе из 50 запросов Recall@10 вырос с `0.23` до `0.30`,
|
||||
MRR@10 — с `0.1854` до `0.2272`.
|
||||
- Версия backend обновлена до `0.5.1`.
|
||||
|
||||
### 2026-08-14
|
||||
|
||||
- Добавлены шаблон relevance set v1 и воспроизводимый расчёт Recall@K/MRR@K.
|
||||
@@ -226,4 +282,4 @@
|
||||
|
||||
---
|
||||
|
||||
Акылдаш · Telegram-бот v0.2.2 · Backend v0.5.0 · Frontend — не создан
|
||||
Акылдаш · Telegram-бот v0.2.2 · Backend v0.12.2 · Frontend v0.1.2
|
||||
@@ -398,4 +398,4 @@ Git сохраняет актуальную версию
|
||||
|
||||
---
|
||||
|
||||
Акылдаш · Telegram-бот v0.2.2 · Backend v0.5.0 · Frontend — не создан
|
||||
Акылдаш · Telegram-бот v0.2.2 · Backend v0.7.1 · Frontend — не создан
|
||||
@@ -0,0 +1,128 @@
|
||||
# Готовность к публичному frontend
|
||||
|
||||
Этот документ определяет обязательный результат до начала проектирования и
|
||||
разработки публичной пользовательской системы. Он дополняет
|
||||
[план frontend поисковой СПС](frontend-search-sps-plan.md): тот описывает MVP и
|
||||
спринты frontend, этот — критерий перехода к ним.
|
||||
|
||||
## Правило перехода
|
||||
|
||||
Публичный frontend и его выпуск начинаются, когда выполнены все обязательные
|
||||
пункты этого плана и пройден финальный readiness gate. Внутренняя
|
||||
авторизованная поисковая страница и лаборатория могут развиваться отдельно по
|
||||
явной задаче и используют только реальные существующие API.
|
||||
|
||||
Персональные функции вне этого этапа: закладки, заметки, уведомления, RAG,
|
||||
судебная практика и внешние коммерческие сервисы. Внутренние учетные записи
|
||||
для лаборатории не включают публичную регистрацию.
|
||||
|
||||
## 1. Данные и поисковый индекс
|
||||
|
||||
### Результат
|
||||
|
||||
В локальном OpenSearch доступен воспроизводимо собранный корпус актуальных
|
||||
редакций ЦБД Минюста КР, пригодный для поиска на русском и кыргызском языках.
|
||||
|
||||
### Обязательные работы
|
||||
|
||||
1. Подтвердить для каждого индексируемого документа наличие канонических
|
||||
реквизитов: код, редакция, язык, статус, тип, орган, дата, номер, название
|
||||
и ссылка на официальный источник.
|
||||
2. Зафиксировать правила для документов без текста и одноязычных редакций:
|
||||
они не скрываются и не получают выдуманный перевод.
|
||||
3. Проверить versioned-индекс, mapping, анализаторы RU/KY, полноту актуальных
|
||||
редакций и процедуру безопасной переиндексации с переключением alias.
|
||||
4. Описать и выполнить воспроизводимый сценарий обновления:
|
||||
выгрузка → нормализация → новый индекс → проверка → переключение alias.
|
||||
|
||||
### Критерий приёмки
|
||||
|
||||
Команда может повторить обновление на чистом локальном окружении, проверить
|
||||
количество документов и фрагментов, а затем безопасно переключить поисковый
|
||||
alias без смешивания старого и нового корпуса.
|
||||
|
||||
## 2. Relevance set и качество поиска
|
||||
|
||||
### Результат
|
||||
|
||||
Есть замороженный набор `relevance set v1` из 50 практических запросов:
|
||||
минимум 25 на русском и 25 на кыргызском языках.
|
||||
|
||||
### Обязательные работы
|
||||
|
||||
1. Заполнить рабочую копию из `backend/search/relevance-set-v1.template.json`
|
||||
естественными формулировками пользователей и подтверждёнными
|
||||
`document_code` релевантных действующих актов.
|
||||
2. Подтвердить документы по официальной ЦБД и проверить их наличие в локальном
|
||||
индексе по `document_code`, не оценивая порядок поисковой выдачи. Не включать
|
||||
запросы без установленного эталонного результата.
|
||||
3. Провести независимую вторую проверку языка, формулировки и полного списка
|
||||
кодов. Спорные результаты не включать до согласования.
|
||||
4. После независимой проверки сохранить неизменяемую копию набора, затем
|
||||
оценить собственную выдачу и сохранить baseline `Recall@10`/`MRR@10`. Новые
|
||||
правила ранжирования проверять на том же наборе и сравнивать с baseline.
|
||||
5. Отдельно проверить распространённые сокращения, опечатки и запросы о
|
||||
практическом действии. Правило принимается, только если улучшает
|
||||
подтверждённые запросы и не создаёт ложных срабатываний в негативных
|
||||
сценариях.
|
||||
|
||||
### Критерий приёмки
|
||||
|
||||
Оценщик проходит на полном наборе, выводит метрики и выдачу для каждого
|
||||
запроса; baseline и результаты его повторного запуска воспроизводимы.
|
||||
|
||||
## 3. Справочники и контракт API
|
||||
|
||||
### Результат
|
||||
|
||||
Frontend получает все юридически значимые данные через версионированный
|
||||
OpenAPI-контракт, а не реконструирует их из текста фрагментов.
|
||||
|
||||
### Обязательные работы
|
||||
|
||||
1. Утвердить справочники v1: типы документов, органы принятия, статусы,
|
||||
уровни действия и темы. Для каждого значения определить стабильный код и
|
||||
подписи RU/KY.
|
||||
2. Реализовать и описать OpenAPI для:
|
||||
- `GET /search` — запрос, язык, фильтры, сортировка, серверная пагинация,
|
||||
выдержка и подсветка;
|
||||
- `GET /search/filters` — допустимые значения фильтров;
|
||||
- `GET /documents/{code}` — карточка актуального документа;
|
||||
- `GET /documents/{code}/editions` и
|
||||
`GET /documents/{code}/editions/{edition}` — редакции и их содержимое.
|
||||
3. Зафиксировать единые ответы для пустой выдачи, неизвестного документа,
|
||||
недоступной редакции и ошибки upstream; для документов с одним языком
|
||||
вернуть доступные языки явно.
|
||||
4. Добавить контрактные и интеграционные проверки API на локальном OpenSearch:
|
||||
поиск, фильтры, пагинация, сортировка, документ, редакции и одноязычные
|
||||
акты.
|
||||
|
||||
### Критерий приёмки
|
||||
|
||||
OpenAPI опубликован вместе с backend, тестовый клиент получает реальные данные
|
||||
по всем endpoint без mock-слоя, а результаты поиска открывают актуальный
|
||||
документ и выбранную редакцию.
|
||||
|
||||
## 4. Финальный readiness gate
|
||||
|
||||
Перед началом frontend выполнить и зафиксировать один сквозной сценарий:
|
||||
|
||||
1. Обновить корпус из официальной ЦБД.
|
||||
2. Нормализовать данные и собрать новый versioned-индекс.
|
||||
3. Прогнать проверки индекса и relevance baseline.
|
||||
4. Переключить alias на проверенный индекс.
|
||||
5. Выполнить API-сценарии поиска, фильтрации, просмотра документа и редакции
|
||||
на RU, KY и одноязычном документе.
|
||||
|
||||
Gate считается пройденным, если все проверки успешны, зафиксированы версии
|
||||
backend и индекса, опубликованы известные ограничения и назначен ответственный
|
||||
за юридическую проверку relevance set.
|
||||
|
||||
## Порядок issues
|
||||
|
||||
1. Собрать и независимо проверить relevance set v1.
|
||||
2. Завершить проверку полноты данных и воспроизводимую переиндексацию с alias.
|
||||
3. Утвердить справочники v1.
|
||||
4. Реализовать OpenAPI и интеграционные проверки.
|
||||
5. Провести финальный readiness gate и только затем открыть задачу на
|
||||
проектирование frontend.
|
||||
@@ -105,6 +105,11 @@ MVP не входят.
|
||||
|
||||
## Рекомендуемая основа frontend
|
||||
|
||||
Для внутреннего frontend лаборатории и авторизованного поиска используется
|
||||
одна HTML-страница, которую отдаёт существующий Search API, и браузерный
|
||||
JavaScript без сборщика и runtime-зависимостей. Это сохраняет текущую схему
|
||||
развёртывания. Публичный frontend после readiness gate можно оценить отдельно.
|
||||
|
||||
- Next.js App Router и TypeScript;
|
||||
- CSS Modules с BEM-именованием;
|
||||
- дизайн-токены для цветов, отступов, типографики и состояний;
|
||||
@@ -131,13 +136,13 @@ TypeScript в стандартной конфигурации. См.
|
||||
|
||||
Правила применения:
|
||||
|
||||
1. До разработки экранов выбрать в Refero не более трёх подходящих направлений
|
||||
и на их основе утвердить одно собственное направление Акылдаша.
|
||||
1. Визуальное направление «Түндүк» утверждено пользователем. Применять
|
||||
корневой [DESIGN.md](../../DESIGN.md); повторный выбор направления не нужен.
|
||||
2. Не копировать чужую дизайн-систему целиком. Цвета, типографика, плотность и
|
||||
компоненты должны учитывать длинные юридические тексты, два языка и
|
||||
доступность.
|
||||
3. Зафиксировать утверждённое направление в `frontend/DESIGN.md` и перенести
|
||||
значения в дизайн-токены проекта.
|
||||
3. Перенести значения из корневого `DESIGN.md` в дизайн-токены проекта.
|
||||
Не создавать отдельный `frontend/DESIGN.md` или конкурирующие спецификации.
|
||||
4. Дизайн-токены и компоненты Акылдаша являются источником истины. Внешние
|
||||
рекомендации не могут отменять BEM, доступность, требования безопасности и
|
||||
продуктовые ограничения проекта.
|
||||
@@ -156,9 +161,7 @@ runtime-зависимостями frontend. Регистрация в стор
|
||||
|
||||
- создать `frontend/`;
|
||||
- настроить Next.js, TypeScript, lint и сборку;
|
||||
- выбрать до трёх референсов в Refero Styles и утвердить одно визуальное
|
||||
направление;
|
||||
- создать `frontend/DESIGN.md` с правилами выбранного направления;
|
||||
- применить утверждённую дизайн-систему «Түндүк» из корневого `DESIGN.md`;
|
||||
- установить полный набор `jakubkrehel/skills` для проектных design review;
|
||||
- определить маршруты и типы API;
|
||||
- создать дизайн-токены;
|
||||
@@ -230,9 +233,10 @@ runtime-зависимостями frontend. Регистрация в стор
|
||||
|
||||
## Спринты после MVP
|
||||
|
||||
### Спринт 5 — персональный кабинет
|
||||
### Спринт 5 — персональные функции
|
||||
|
||||
Авторизация, закладки, заметки, подборки и сохранённые фильтры.
|
||||
Базовый вход и смена пароля для внутреннего frontend уже реализованы. Для
|
||||
публичного продукта остаются закладки, заметки, подборки и сохранённые фильтры.
|
||||
|
||||
### Спринт 6 — контроль изменений
|
||||
|
||||
@@ -258,4 +262,4 @@ runtime-зависимостями frontend. Регистрация в стор
|
||||
|
||||
---
|
||||
|
||||
Акылдаш · Telegram-бот v0.2.2 · Backend v0.5.0 · Frontend — не создан
|
||||
Акылдаш · Telegram-бот v0.2.2 · Backend v0.12.2 · Frontend v0.1.2
|
||||
@@ -0,0 +1,462 @@
|
||||
# План реализации и приёмки Акылдаш
|
||||
|
||||
Дата актуализации: **2 ноября 2026 года**. Основа сверки: `main` на
|
||||
`7ece39f212b67e497a8dfb360d5d271ab088ef57`. Это единый план работ по продукту,
|
||||
интерфейсу и переходу к production. Он не заменяет эксплуатационные runbooks
|
||||
и не подтверждает состояние живого сервиса.
|
||||
|
||||
## 1. Статус и границы достоверности
|
||||
|
||||
Различаем три вида сведений:
|
||||
|
||||
- **В коде** — наличие исходного кода на указанном commit; это не доказывает,
|
||||
что функция развёрнута или доступна пользователям.
|
||||
- **Историческое наблюдение** — результат конкретного аудита, дата и пределы
|
||||
которого указаны рядом. Оно не является повторной проверкой текущего сайта.
|
||||
- **Цель / gate** — требование, которое нужно выполнить и подтвердить до
|
||||
следующего этапа.
|
||||
|
||||
На сверенном commit источники кода показывают Backend `0.13.3`
|
||||
(`backend/search/minjust_opensearch.py`), Frontend `0.3.3`
|
||||
(`backend/search/review.html`) и Telegram-бот `0.2.2`
|
||||
(`tools/telegram-bot/bot.py`). Это версии исходного кода, а не подтверждение
|
||||
установленных production-версий. В этом PR согласованы версии в корневом и
|
||||
общем документационном README; `backend/README.md` отдельно называет версию
|
||||
загрузчика `minjust_cbd.py` (`0.9.3`). При новых изменениях сверять версию
|
||||
компонента с соответствующим исполняемым кодом.
|
||||
|
||||
В Search API и frontend реализованы поиск RU/KY, фильтры, карточка документа,
|
||||
редакции, поиск в тексте, внутренняя лаборатория, вход и административные
|
||||
действия. В коде также есть локальные Noto Sans/Serif с лицензиями, favicon и
|
||||
встроенный SVG-знак бренда. Наличие файлов и ссылок в HTML не подтверждает,
|
||||
что они загрузились в live-браузере. Результаты браузерной проверки приведены
|
||||
только в [отчёте визуальной приёмки](visual-review/README.md).
|
||||
|
||||
Production readiness не следует из наличия Compose, release workflow или
|
||||
deploy-кода. Подтверждённое состояние и ограничения находятся в
|
||||
[CURRENT_STATE.md](../operations/CURRENT_STATE.md); статус релиза — в
|
||||
[DEPLOYMENT.md](../operations/DEPLOYMENT.md), ограничения backup/restore — в
|
||||
[BACKUP.md](../operations/BACKUP.md), rollback — в
|
||||
[ROLLBACK.md](../operations/ROLLBACK.md), аварийное восстановление — в
|
||||
[RECOVERY.md](../operations/RECOVERY.md). Этот план не повторяет команды из
|
||||
этих runbooks.
|
||||
|
||||
## 2. Очерёдность работ
|
||||
|
||||
### 2.1 Продукт и качество правовых данных
|
||||
|
||||
1. Поддерживать воспроизводимое получение и нормализацию официальных
|
||||
правовых материалов с сохранением источника, редакции и контрольных сумм.
|
||||
2. Подтвердить полноту и актуальность RU/KY корпуса, правила для отсутствующих
|
||||
текстов и одноязычных редакций; не выдумывать перевод или реквизиты.
|
||||
3. Развивать замороженный relevance set и измерять качество на одной и той же
|
||||
выборке до и после изменений ранжирования.
|
||||
4. Развивать версионируемые API и справочники, сохраняя совместимость
|
||||
существующих клиентов.
|
||||
5. Публичный frontend, персональные функции и RAG остаются отдельными
|
||||
продуктовыми решениями и readiness gates. Сверяться с [обзором проекта](project-overview.md),
|
||||
[планом frontend](frontend-search-sps-plan.md) и
|
||||
[готовностью публичного frontend](frontend-design-readiness-plan.md). Конкурентная
|
||||
гипотеза и сегмент рынка отдельно описаны в
|
||||
[стратегическом сравнении с Токтом](platform-development-plan-toktom-2026-10-24.md).
|
||||
|
||||
### 2.2 Интерфейс: датированный реестр UI-01—UI-33
|
||||
|
||||
Реестр ниже сохраняет исходные наблюдения аудита **23 октября 2026 года** и
|
||||
критерии приёмки; это не список текущих открытых дефектов. Актуальный план на
|
||||
`main` указывает, что все UI-01—UI-33 реализованы в PR #54. Он также описывает
|
||||
follow-up по поиску, кабинету и лаборатории, локальную браузерную проверку и
|
||||
синтетические regression fixtures. Их результаты привязаны к указанным в
|
||||
исходном документе commits и окружению, а не являются повторным live-аудитом в
|
||||
этой документационной задаче. Сверяться с [отчётом visual-review](visual-review/README.md);
|
||||
не открывать снова выполненные пункты без нового воспроизводимого свидетельства.
|
||||
|
||||
Источники по состоянию на базовый commit этого PR сохранены постоянными
|
||||
ссылками: [UI-план на `7ece39f`](https://git.vakanaut.ru/admin/akyldash/src/commit/7ece39f212b67e497a8dfb360d5d271ab088ef57/docs/product/interface-correction-plan.md)
|
||||
и [план pixel-perfect на `7ece39f`](https://git.vakanaut.ru/admin/akyldash/src/commit/7ece39f212b67e497a8dfb360d5d271ab088ef57/docs/product/frontend-pixel-perfect-plan.md).
|
||||
UI-01—UI-33 вошли в [PR #54](https://git.vakanaut.ru/admin/akyldash/pulls/54)
|
||||
(merge commit [`01380d3c`](https://git.vakanaut.ru/admin/akyldash/commit/01380d3c09d71e32c965d974a39a4d82de0a15c5));
|
||||
последующий follow-up поиска, кабинета и лаборатории записан в
|
||||
[commit `e5a8326a`](https://git.vakanaut.ru/admin/akyldash/commit/e5a8326a5e3def1bf5d5dc94794da82a2af801ab).
|
||||
|
||||
В исходном реестре **P1** означает обязательное исправление до визуальной
|
||||
приёмки/выпуска, **P2** — существенное улучшение понятности и
|
||||
последовательности. Отсутствие функции само по себе не считается багом;
|
||||
обозначенные целевые корректировки требуют подтверждения по коду и дизайну.
|
||||
|
||||
| ID | Приоритет | Историческое наблюдение 23.10.2026 | Требование / критерий |
|
||||
|---|---|---|---|
|
||||
| UI-01 | P1 | При пустом запросе одновременно показывались подсказка и empty-состояние | Разделить initial/loading/results/empty/error; empty показывать после завершённого поиска |
|
||||
| UI-02 | P1 | До выбора документа были доступны действия и пустые select | До загрузки документа показывать понятное приглашение; действия доступны после выбора |
|
||||
| UI-03 | P1 | Фильтры имели горизонтальное переполнение (`clientWidth=194`, `scrollWidth=231` при 1064 px) | Исключить переполнение; длинные списки раскрывать по запросу |
|
||||
| UI-04 | P1 | Действие «Сбросить» обрезалось заголовком | Заголовок и действие видны целиком на поддерживаемых размерах |
|
||||
| UI-05 | P1 | Счётчики отрывались от подписей, переносы растягивали панель | Разделить колонки выбора/подписи/числа; переносить только длинные названия |
|
||||
| UI-06 | P1 | Все 28 видов и 8 статусов были раскрыты, орган и даты находились ниже первого экрана | Показывать основные значения и сворачиваемые группы, сохраняя доступ ко всему каталогу |
|
||||
| UI-07 | P1 | Ширины около 78 px не хватало для RU/KY названий языка | Подбирать размер по самой длинной локализованной подписи без обрезки |
|
||||
| UI-08 | P1 | На 390 px навигация прокручивалась горизонтально, кабинет и фильтры уходили за край | Адаптивно показывать поиск, фильтры и кабинет без горизонтальной прокрутки основных действий |
|
||||
| UI-09 | P2 | Кабинет был малозаметной иконкой во второй строке | Подписанная desktop-кнопка; на mobile — доступное имя и достаточная touch-область |
|
||||
| UI-10 | P1 | Три колонки оставались тесными на 1024/1064 px | Перейти к двухпанельному режиму и скрытию фильтров, не сжимать колонки бесконечно |
|
||||
| UI-11 | P2 | Название документа повторялось в breadcrumb, заголовке и тексте | Breadcrumb обозначает контекст; официальный текст не переписывать |
|
||||
| UI-12 | P1 | Ссылка на источник и toolbar переполнялись на промежуточной ширине | Переносить действия группами без обрезки; сохранять подписи редакции и языка |
|
||||
| UI-13 | P2 | Пустые абзацы и синие ссылки конфликтовали с оболочкой | Нормализовать отступы и ссылки без потери структуры официального текста |
|
||||
| UI-14 | P1 | Таблицы в документе шире панели (`clientWidth=412`, `scrollWidth=834`) | Дать таблице отдельную обозначенную прокрутку; не прокручивать всю страницу по горизонтали |
|
||||
| UI-15 | P1 | Встречались Temp-пути и HTTP-ссылки исходного редактора | Классифицировать ссылки безопасно, не удалять юридический текст; не считать локальные/IP-ссылки проверенными |
|
||||
| UI-16 | P2 | Развёрнутый документ терял поиск, совпадение и toolbar | Сохранять редакцию, язык, позицию и навигацию; обеспечить очевидный возврат |
|
||||
| UI-17 | P2 | Часть KY-интерфейса оставалась на русском | Инвентаризировать строки интерфейса; не заменять переводом язык документа |
|
||||
| UI-18 | P1 | На `/review` отображались два footer, общий footer был выше сохранения | Один footer после основного содержимого и панели сохранения |
|
||||
| UI-19 | P1 | Шапка, формы, панели и footer лаборатории имели разные направляющие | Единая оболочка и совпадающие границы контента |
|
||||
| UI-20 | P1 | Высокая шапка лаборатории отодвигала работу на mobile | Компактный заголовок и помощь; поиск и рабочая область доступны сразу |
|
||||
| UI-21 | P1 | Заголовок кабинета был пустым | Видимый заголовок и доступное имя диалога |
|
||||
| UI-22 | P1 | Не было постоянного крестика; закрытие находилось внизу формы | Крестик 44×44, доступное имя, Escape и возврат фокуса; отмена редактирования остаётся |
|
||||
| UI-23 | P1 | Навигация, выход, профиль и смена пароля были смешаны | Разделить «Профиль» и «Безопасность», отделить выход от формы |
|
||||
| UI-24 | P1 | Окно пользователей открывалось поверх кабинета | Не оставлять конкурирующие модальные окна; сохранять контекст и корректный фокус |
|
||||
| UI-25 | P1 | Список пользователей был длинным модальным окном с закрытием ниже экрана | Отдельный экран списка и короткие диалоги для создания/сброса |
|
||||
| UI-26 | P2 | Создание, удаление, сброс и входные данные смешивались | Действия на строке, отдельное подтверждение удаления, не раскрывать лишние формы |
|
||||
| UI-27 | P2 | Бренд, навигация, шрифты и ссылки различались между экранами | Общие header, logo, button, link, dialog и footer |
|
||||
| UI-28 | P2 | Диалоги закрывались разными способами | Единая модель окна и доступного закрытия |
|
||||
| UI-29 | P2 | Обучение появлялось с задержкой и перехватывало ввод | Запуск по запросу или ненавязчиво до начала ввода; не отбирать фокус |
|
||||
| UI-30 | P2 | Шкала 0–3 переносилась, комментарии всегда занимали место | Полные подписи; допустима сетка 2×2; раскрываемый комментарий без потери текста |
|
||||
| UI-31 | P2 | Пустой экран лаборатории выглядел готовым к отправке оценки | Явное состояние снимка, прогресс и статус черновика; не менять смысл пустой оценки |
|
||||
| UI-32 | P2 | Footer live-сайта показывал «Концепция Түндүк» | Рабочий интерфейс показывает продукт и реальные версии; концепция подписывается только в макете/демо |
|
||||
| UI-33 | P1 | Документ растягивал лабораторию до y≈636935 px, сохранение уходило ниже | Ограничить высоту области чтения и прокручивать её отдельно; сохранение доступно независимо от длины текста |
|
||||
|
||||
Дополнительные целевые критерии исходного аудита:
|
||||
|
||||
- **Сетка и ресайз колонок:** desktop — три колонки с доступными разделителями;
|
||||
ориентиры 1440 px: `280 / 408 / 736` плюс два захвата по 8 px, 1280 px:
|
||||
`256 / 384 / 624` плюс захваты. Рекомендуемые пределы фильтров 256–360 px,
|
||||
выдачи от 360 px, документа от 560 px. При недостатке ширины сначала скрыть
|
||||
фильтры, затем показывать документ отдельно.
|
||||
- Разделители должны иметь `role=separator`, доступное имя, min/max/current
|
||||
значения, pointer drag и управление стрелками клавиатуры. Отдельные кнопки
|
||||
скрытия/показа фильтров и сброса ширины обязательны; двойной клик не заменяет
|
||||
доступный сброс. Сохранённая ширина ограничивается текущим viewport.
|
||||
- Остальные правила сетки: фильтры не становятся постоянно прокручиваемой
|
||||
узкой колонкой; полный каталог значений всегда достижим; API single-select не
|
||||
изображается множественными checkbox. Длинное название органа читается в
|
||||
панели выбора полностью. Поля дат имеют постоянные «От» / «До» и переходят
|
||||
в столбец, когда не помещаются. На desktop выдача и документ могут иметь
|
||||
отдельную вертикальную прокрутку с доступными заголовком/toolbar; на mobile
|
||||
основной поток вертикальный с отдельными панелями. Footer использует
|
||||
растущий main (`min-height: 100dvh`), не перекрывает контент и следует за ним;
|
||||
панель сохранения имеет собственное место.
|
||||
- **Панели и формы:** понятный заголовок и крестик 44×44; именованный modal
|
||||
dialog, фокус внутри, Tab/Shift+Tab без выхода в фон, Escape там, где закрытие
|
||||
допустимо, возврат фокуса инициатору; фон не интерактивен. Не наслаивать
|
||||
кабинет и пользователей. Профиль и безопасность — отдельные разделы; права
|
||||
по-прежнему проверяет сервер. В форме пароля постоянные подписи, требования,
|
||||
доступное показать/скрыть и подтверждение нового пароля. Пароли не
|
||||
предзаполнять и не сохранять в материалах аудита; ввод выполняет человек.
|
||||
- Основное действие одно; отмена вторична, выход отдельно; Enter отправляет
|
||||
только активную форму. Ошибка у поля и в доступном сообщении, допустимый ввод
|
||||
сохраняется, loading исключает повторную отправку. Несохранённое редактирование
|
||||
защищено от случайной потери, обычный просмотр закрывается без лишнего
|
||||
подтверждения. После успеха сообщается результат, при ошибке есть путь
|
||||
восстановления; состояние не кодируется одним цветом.
|
||||
- Правила применяются к кабинету, входу, обязательной смене пароля, источникам,
|
||||
созданию/сбросу/удалению пользователя, обучению и просмотру документа.
|
||||
- **Приёмка:** единая оболочка/header/footer; нет общей горизонтальной
|
||||
прокрутки; initial не сообщает об empty до поиска; действия документа
|
||||
активируются по состоянию; keyboard и touch работают; RU/KY подписи и язык
|
||||
документа независимы; таблицы прокручиваются отдельно; тестируются contrast
|
||||
WCAG AA, видимый focus, reduced motion, zoom/reflow и доступные имена.
|
||||
- Viewport: **1440×900, 1280×800, 1024×768, 390×844**, дополнительно 320 CSS px
|
||||
для reflow. Визуальное сравнение — детерминированное fixture; нулевой
|
||||
pixel-diff не является критерием. Авторизация и destructive-сценарии
|
||||
проверяются только в безопасном тестовом контуре.
|
||||
|
||||
Исторически выполненные браузерные сценарии и ограничения аудита 23.10.2026:
|
||||
|
||||
| Область | Выполнено в том аудите | Не проверено тогда |
|
||||
|---|---|---|
|
||||
| Начальная страница и поиск RU | Пустой запрос, фильтры, footer; поиск «налог на прибыль», открытие кодекса | Экспертная оценка юридической релевантности |
|
||||
| Фильтры, сортировка, страницы | Статус, chip, снятие фильтра, дата/релевантность, страница 2 и сброс на страницу 1 | Все комбинации справочников |
|
||||
| Пустая выдача и документ | Контрольный заведомо пустой запрос, реальные текст и редакции, язык, разворот | Искусственное создание серверного сбоя, реальная печать/PDF |
|
||||
| Поиск в документе и локализация | Совпадения, переход к следующему, переключение RU/KY и чтение подписей | Поиск после смены редакции; полная проверка всех переводов |
|
||||
| Источники и мобильные фильтры | Открытие/закрытие панели и раздела источников | Внешний сайт Минюста, полный touch на физическом устройстве |
|
||||
| Кабинет и пользователи | Профиль, поля смены пароля, Escape/возврат фокуса; просмотр списка | Ввод пароля, создание/удаление пользователя, сброс пароля |
|
||||
| `/review` | Пустое состояние, поиск, шкала, документ, обучение | Отправка оценки и подтверждение серверного сохранения |
|
||||
| Авторизация | Наличие локальной реализации | Live login, истечение сессии и обязательная смена пароля |
|
||||
|
||||
Этот перечень описывает только прежний браузерный сеанс. Не использовать его
|
||||
как подтверждение текущих production-сценариев.
|
||||
|
||||
#### Реализация, зафиксированная в текущем плане `main`
|
||||
|
||||
UI-план, находившийся на базовом commit этого PR, отмечает UI-01—UI-33
|
||||
реализованными в PR #54 и связывает группы изменений с
|
||||
регрессионными сценариями:
|
||||
|
||||
| Пункты | Изменение, зафиксированное в плане `main` | Regression evidence, указанное там |
|
||||
|---|---|---|
|
||||
| UI-01—02 | Разделены initial/loading/results/empty/error; действия документа зависят от выбранной редакции | Empty, API error и редакция без текста |
|
||||
| UI-03—08 | Компактные/сворачиваемые фильтры, счётчики, локализованные языковые select и адаптивная навигация | Reflow 320/390/640/1024/1280/1440; на 640 px проверены основные действия `/`, `/review`, `/users` |
|
||||
| UI-09—10 | Подписанный кабинет и адаптивный layout вместо бесконечного сжатия трёх колонок | Геометрия и overflow на 640/1024/1280/1440 |
|
||||
| UI-11—16 | Breadcrumb, toolbar, отдельный scroll таблиц, очистка небезопасных URL-атрибутов и разворот документа в панели | Синтетические private-IP/relative/HTTP ссылки; ошибки и гонки редакций A/B |
|
||||
| UI-17 | Перевод интерфейсных подписей RU/KY с независимым языком документа | Переключение языка; полный ручной лингвистический review остаётся открытым |
|
||||
| UI-18—20 | Один footer, общие направляющие и ограниченная по высоте лаборатория | Один footer и длинный синтетический документ с собственным scroll |
|
||||
| UI-21—24 | Имя и разделы кабинета, безопасный переход к пользователям без наложенных диалогов | ARIA name, Escape, focus trap/return и отдельные маршруты |
|
||||
| UI-25—28 | Отдельный экран пользователей, целевые окна для действий, общий способ закрытия | Только фиктивный `fixture-created`; реальные аккаунты/API не использовались |
|
||||
| UI-29 | Обучение запускается пользователем | Локальный regression scenario |
|
||||
| UI-30—31 | Оценка 2×2, раскрываемый комментарий, disable до результата и draft state | Фиктивное сохранение и сохранность оценок при ошибке/устаревшем ответе |
|
||||
| UI-32—33 | Версии в footer и отдельная прокрутка длинного текста лаборатории | Footer versions и длинный fixture, сохранение остаётся доступно |
|
||||
|
||||
Тот же план `main` фиксирует локальный browser run на **320×800, 390×844,
|
||||
640×450, 1024×900, 1280×800 и 1440×900 CSS px**; на 1280 px измерена
|
||||
сетка 256 / 384 / 640 px. Экран лаборатории с длинным текстом имел собственную
|
||||
панель прокрутки, а сохранение/footer оставались доступны. Встроенная
|
||||
проверка fixture не использовала production API или реальные учётные записи.
|
||||
Это точная передача прежнего отчёта; её не следует трактовать как результат
|
||||
нового прогона в этом PR. Полный screen-reader review, 200–400% zoom,
|
||||
физический touch и полный ручной лингвистический review в исходном плане
|
||||
оставлены непроверенными.
|
||||
|
||||
Отдельный follow-up в плане `main` описывает реализованные после PR #54
|
||||
корректировки и regression coverage:
|
||||
|
||||
- **Поиск:** «Открыт» сбрасывается при смене результата/редакции и ставится
|
||||
только после успешной загрузки. Оглавление распознаёт самостоятельные
|
||||
заголовки RU/KY из структурированных абзацев (`p > b > span`), задаёт
|
||||
уникальные якоря и вложенность, не принимает обычные упоминания за заголовки.
|
||||
Выбор языка поиска находится в фильтрах и не обрезается; декоративный SVG и
|
||||
пустое резервное место удалены; активная навигация использует палитру.
|
||||
Проверены ошибки и гонки загрузки, структура заголовков, splitter и
|
||||
доступность диапазона его ширины.
|
||||
- **Кабинет:** ссылки действий сохраняют `<a>` семантику, крестик остаётся
|
||||
подписанной SVG-кнопкой 44×44, значения профиля стоят в парах «поле—значение»,
|
||||
длинные значения переносятся, заголовок компактнее; администратору явно
|
||||
доступно «Управление пользователями». Проверены RU/KY, отсутствие ссылки у
|
||||
не-администратора, фокус/закрытие и ширина.
|
||||
- **Лаборатория:** имя показывается без дублирующей роли; ссылки навигации имеют
|
||||
вид кнопок; оболочка, форма, рабочая область, сохранение и footer выровнены.
|
||||
Пустой live status не резервирует высоту, результаты и документ образуют
|
||||
общую поверхность с внутренней прокруткой на desktop, заголовок использует
|
||||
доступную ширину, а mobile возвращается к естественному потоку. Проверены
|
||||
desktop/mobile, пустой status, сохранение после длинного документа и page
|
||||
overflow.
|
||||
|
||||
Исходный план сообщает о локальной проверке этих изменений 24 октября 2026
|
||||
года и повышении frontend до `0.3.0` из-за регулируемой ширины панелей. Текущий
|
||||
source footer и версия кода — `0.3.3`. Его отметка «ожидаются CI и review»
|
||||
относилась к конкретному pushed SHA и не задаёт статус этого или любого нового
|
||||
PR.
|
||||
|
||||
#### Общие критерии окон и форм
|
||||
|
||||
- Desktop-окно обычно 480–640 px и не шире viewport; на mobile — отступ 16 px
|
||||
или полноэкранный режим для длинной формы. Заголовок и закрытие остаются
|
||||
доступны при прокрутке.
|
||||
- Диалог именуется через заголовок, держит фокус внутри и не делает фон
|
||||
интерактивным. Escape закрывает обычные окна; исключения (например,
|
||||
обязательная смена пароля) должны объясняться, а не маскироваться.
|
||||
- Профиль и безопасность разделены. Удаление требует отдельного подтверждения;
|
||||
создание/сброс не раскрывают дополнительные формы без запроса.
|
||||
- Поля имеют постоянные подписи; пароль не предзаполняется и не записывается
|
||||
в отчёт. Ошибки объясняют восстановление, допустимый ввод сохраняется,
|
||||
повторная отправка во время loading исключена.
|
||||
- «Отмена» вторична, выход не смешивается с сохранением; несохранённое
|
||||
редактирование защищено от случайной потери. Обычный просмотр закрывается
|
||||
без лишнего подтверждения.
|
||||
|
||||
#### Последовательность при возобновлении UI-работ
|
||||
|
||||
1. Зафиксировать актуальные SHA и версии; читать маршрут, API, `DESIGN.md`,
|
||||
UI tests и CI. Не переносить состояние live-сайта без новой проверки.
|
||||
2. Исправить общую оболочку и разделение поиска, лаборатории и служебных
|
||||
экранов; затем initial/loading/empty/error и жизненный цикл документа.
|
||||
3. Исправить фильтры, адаптивные минимумы и RU/KY; после этого — регулируемые
|
||||
колонки и скрытие фильтров.
|
||||
4. Привести формы/диалоги к общей модели с сохранением серверной авторизации,
|
||||
прав, валидации, снимков оценок и черновиков.
|
||||
5. Проверить текст, таблицы, ссылки, редакции, печать, адаптивность,
|
||||
локализацию, доступность и состояния на реальном корпусе, где доступен.
|
||||
6. Сделать детерминированный fixture-проход и независимый review; обновить
|
||||
версию только при изменении кода, а changelog — после зелёных проверок и
|
||||
разрешения blocking findings.
|
||||
|
||||
Не переносить существующий Python frontend на React/Next.js ради визуальной
|
||||
корректировки. UI-работа не меняет ранжирование, корпус или права доступа.
|
||||
|
||||
| Приёмка | Условие |
|
||||
|---|---|
|
||||
| Оболочка | Один header/footer на маршруте, единые границы и порядок контента |
|
||||
| Фильтры | Нет общей горизонтальной прокрутки; подписи/действия/счётчики видны полностью |
|
||||
| Начальное состояние | До первого завершённого запроса empty-сообщение не показано |
|
||||
| Документ | До выбора неактивные действия не вводят в заблуждение |
|
||||
| Колонки | Pointer и клавиатура; min/max; скрытие/возврат; reset; адаптация сохранённой ширины к viewport |
|
||||
| Телефон | Основные действия без горизонтального скролла; понятный возврат из фильтров/документа |
|
||||
| Окна | Заголовок, крестик, Escape, trap/return focus; окна не конкурируют слоями |
|
||||
| Лаборатория | Поиск → чтение → оценка → черновик → сохранение; текст не теряется, панель доступна при длинном документе |
|
||||
| Локализация | RU/KY labels и символы; язык UI не подменяет язык документа |
|
||||
| Геометрия | При 1280×800 границы основных зон и отступы/размеры controls отличаются от измеренного fixture не более чем на 2 CSS px; согласованные исключения описаны |
|
||||
| Типографика и таблицы | Noto действительно загружается; читаемый длинный текст; у широкой таблицы собственный скролл |
|
||||
| Доступность | Контраст AA, focus, Tab/Shift+Tab/Enter/Escape, zoom/reflow, reduced motion и touch targets |
|
||||
| Авторизация | Неверный пароль, expired session и обязательная смена проверены только в безопасном тестовом контуре |
|
||||
| Снимки | 1440×900, 1280×800, 1024×768, 390×844 и 320 CSS px; стабильные fixture и объяснённые различия |
|
||||
|
||||
Допуск **до 2 CSS px** для границ крупных зон и отступов/размеров controls при
|
||||
1280×800 перенесён из исторического pixel-perfect плана по стабильной ссылке
|
||||
выше. Он применяется к одинаковым детерминированным fixture; расхождения
|
||||
растра, вызванные сглаживанием текста или содержимым, сами по себе не дают
|
||||
основания обрезать или уплотнять юридический текст.
|
||||
|
||||
#### Нормативный орнамент и фактическое состояние
|
||||
|
||||
`DESIGN.md` нормативно требует небольшой золотистый SVG-орнамент в свободной
|
||||
нижней части desktop-панели фильтров, не перекрывающий длинные списки и не
|
||||
резервирующий место за счёт управления. Follow-up из commit `e5a8326a` удалил
|
||||
предыдущий декоративный SVG и его пустой резерв; в `backend/search/review.html`
|
||||
на базовом `main` целевого орнамента нет. Это не выполненное требование, а
|
||||
подтверждённое расхождение между `DESIGN.md` и реализацией. Дизайн остаётся
|
||||
нормативным до отдельного решения владельца: UI-задача должна либо вернуть
|
||||
орнамент в свободную область без влияния на управление, либо получить явное
|
||||
одобрение на изменение `DESIGN.md` и подтвердить его визуальной приёмкой.
|
||||
|
||||
### 2.3 Инфраструктура и переход к production
|
||||
|
||||
Инфраструктурные источники содержали повторяющиеся этапы deployment и
|
||||
устаревшие снимки VPS. В этом плане оставлены только gates; актуальные
|
||||
подтверждённые данные и процедуры находятся в операционных документах.
|
||||
|
||||
1. **Аудит:** сверить commit `main`, CI, Compose, зависимости, порты, volumes,
|
||||
healthchecks, данные и перечень env-переменных без вывода секретов. Для VPS
|
||||
пользоваться только read-only инвентаризацией, разрешённой
|
||||
[правилами доступа](../operations/ACCESS.md). Не переносить IP, версии,
|
||||
DNS-статус или ресурсы из старых планов как текущие факты.
|
||||
2. **Данные и конфигурация:** установить источник и допустимость корпуса,
|
||||
формат, состав, checksum/manifest, размер и воспроизводимую цепочку импорта.
|
||||
Обязательный gate любой передачи/публикации корпуса — процедура
|
||||
[CORPUS_HANDOFF.md](../operations/CORPUS_HANDOFF.md): source → staging →
|
||||
inventory/manifest и checksum comparison → атомарная публикация
|
||||
проверенного staging-корпуса в `DATA_ROOT/minjust-normalized` → отдельная
|
||||
проверка и импорт в индекс → OpenSearch alias switch. Runbook требует
|
||||
непустые source и staging, явное решение по исключению code 6 и fail-closed
|
||||
при неполных/несовпадающих данных. Атомарная файловая публикация и
|
||||
возобновление/отказ после прерывания — обязательный, но ещё не реализованный
|
||||
gate; до описания и проверки all-or-nothing механизма не заменять им
|
||||
действующий корпус. Не смешивать его с атомарным переключением OpenSearch
|
||||
alias. Следовать runbook без копирования его команд сюда; до прохождения
|
||||
gates корпус в production не передавать и не индексировать. Не подменять
|
||||
корпус пустым каталогом. Production env/секреты создаются вне Git; в
|
||||
репозитории остаются только имена переменных и шаблоны без значений.
|
||||
3. **Build/CI:** PR-проверки не получают production secrets и Docker socket.
|
||||
Публикация образов должна фиксировать digest и provenance; release workflow
|
||||
не равен deployment. Production CD не включать до прохождения owner gates,
|
||||
безопасной сборки, backup и отдельного restore.
|
||||
4. **Контролируемое изменение существующего production:** последняя датированная
|
||||
проверка `https://akyldash.kg/review` вернула HTTP 200 25 октября 2026 года
|
||||
([CURRENT_STATE](../operations/CURRENT_STATE.md)); установленный на хосте
|
||||
SHA остался неизвестен. План относится к безопасному
|
||||
обновлению существующего сервиса, а не к первому развёртыванию. До изменения
|
||||
проверять реальные данные и конфигурацию, доступное место, опубликованные
|
||||
порты, права, совместимость схем и backup readiness. Выполнять через
|
||||
существующую ограниченную процедуру; не добавлять общие sudo/Docker-
|
||||
привилегии. Базы данных и внутренние сервисы не публиковать в интернет.
|
||||
DNS, reverse proxy и TLS
|
||||
проверять до выпуска; для Cloudflare применять Full (strict). SSH/UFW и
|
||||
сетевые ограничения меняются только после owner approval.
|
||||
5. **Проверка и recovery:** проверять health/API, RU/KY canaries, доступность
|
||||
HTTPS, сохранность данных и rollback в пределах его документированных
|
||||
ограничений. Data restore — отдельная процедура в staging, не автоматический
|
||||
побочный эффект отката образа.
|
||||
6. **Автоматизация:** только после одобренного отдельного bootstrap и
|
||||
end-to-end проверки; serial deployment, digest verification, backup ACK,
|
||||
health gates и отказ без destructive cleanup. Не включать триггер только
|
||||
потому, что workflow завершился зелёным.
|
||||
|
||||
**Backup/maintenance gate:** настройки CI, проверка конфигурации и подготовка
|
||||
release provenance должны быть отделены от production cutover. Production CD
|
||||
в `CURRENT_STATE.md` остаётся неактивным. Перед каждым фактическим production
|
||||
изменением, включая миграции, создать и проверить внешний pre-change backup.
|
||||
Полный cold backup требует остановки Compose и может выполняться только в
|
||||
заранее согласованное с владельцем окно.
|
||||
Ни полный архив, ни его временная копия никогда не записываются на VPS. По
|
||||
текущей утверждённой схеме архив передаётся напрямую на фиксированный
|
||||
`D:\Dev\akyldash\.backups`; фактическая готовность D:, SSH и отдельное
|
||||
восстановление всё ещё не подтверждены. На VPS остаётся только secret-free
|
||||
идентификатор/manifest согласно `BACKUP.md`. Политика — одна retained,
|
||||
проверенная внешняя копия. При замене прежняя копия сохраняется до тех пор,
|
||||
пока новый candidate не опубликован и не проверен; на время этой проверки две
|
||||
копии могут сосуществовать. После подтверждения новой копии retention может
|
||||
изменить только владелец явным решением; автоматическая очистка запрещена.
|
||||
При неудачной публикации или проверке прежняя подтверждённая копия остаётся.
|
||||
Локальные VPS cold-backup команды из старых документов superseded и
|
||||
использоваться не должны.
|
||||
|
||||
#### Локальные generated reports
|
||||
|
||||
`/reports/` и `/tmp/` игнорируются по умолчанию, чтобы generated bulk не
|
||||
попадал в обычный `git status`. Уже отслеживаемые historical evidence остаются
|
||||
отслеживаемыми. Если конкретный отчёт нужен в Git, сначала проверить его
|
||||
содержимое, удалить секреты, персональные данные, production corpus и
|
||||
временные файлы, затем добавить только предназначенный к публикации файл
|
||||
явной командой `git add -f reports/<path>`. Не добавлять каталоги целиком.
|
||||
|
||||
Нынешний статус не переопределяется этим roadmap: на сверенной документации
|
||||
production CD остаётся неактивным, а backup/restore и внешний bootstrap имеют
|
||||
непроверенные owner prerequisites. Все точные блокировки сверять с
|
||||
`CURRENT_STATE.md` и `DEPLOYMENT.md` перед планированием действий.
|
||||
|
||||
## 3. Визуальные материалы и исходная база
|
||||
|
||||
### Макеты Figma
|
||||
|
||||
Целевые редактируемые экраны — гипотезы компоновки, а не работающий интерфейс,
|
||||
источник юридических данных или доказательство доступности.
|
||||
|
||||
| Экран | Макет |
|
||||
|---|---|
|
||||
| 01. Поиск с документом, 1440×900 | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=3-2) |
|
||||
| 02. Фильтры скрыты | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=3-173) |
|
||||
| 03. Начальный поиск | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=3-288) |
|
||||
| 04. Лаборатория и сохранение | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=3-395) |
|
||||
| 05. Кабинет: профиль и закрытие | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=5-30) |
|
||||
| 06. Кабинет: безопасность | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=5-229) |
|
||||
| 07. Источники | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=5-428) |
|
||||
| 08. Пользователи: отдельный экран | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=5-605) |
|
||||
| 09–11. Телефон: выдача, чтение и фильтры (общий Figma-узел) | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=5-670) |
|
||||
| 12. Эталон 1280×800 | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=7-74) |
|
||||
| 13. Планшет: две панели | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=7-245) |
|
||||
| 14. Кабинет на телефоне | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=7-360) |
|
||||
| 15. Вход, создание и подтверждение удаления | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=8-118) |
|
||||
|
||||
Локальные target exports: [поиск](../design/tunduk-search-target.png),
|
||||
[лаборатория](../design/tunduk-review-target.png),
|
||||
[кабинет](../design/tunduk-account-target.png). Это изображения цели; они не
|
||||
заменяют браузерную проверку.
|
||||
|
||||
В Figma экраны собраны из редактируемого текста, Auto Layout, SVG, локальных
|
||||
переменных цвета/отступов и общих экземпляров кнопок; это не один растр.
|
||||
Состояния 09–11 ведут на один общий мобильный узел, как в исходном плане.
|
||||
Прокрутка длинной выдачи/текста показывает продолжение содержимого.
|
||||
Splitter, закрытие и формы описывают целевое поведение, но не являются
|
||||
работающим web-кодом.
|
||||
|
||||
### Исторические свидетельства
|
||||
|
||||
Аудит UI выполнен **23 октября 2026 года** в авторизованной сессии на
|
||||
`https://akyldash.kg/`, где footer показывал Frontend `0.2.3`, Backend
|
||||
`0.13.0`. Сверка SHA сервиса с checkout не выполнялась. Проверены
|
||||
1440×900, 1280×800, 1024×768, 390×844 CSS px и дополнительный browser viewport
|
||||
1064×1244. Пароли не вводились; создание/удаление пользователей и отправка
|
||||
оценки не выполнялись; полный физический touch, screen-reader и принтерный
|
||||
прогоны не выполнялись. Существующие локальные browser evidence и screenshots
|
||||
собраны в [отчёте visual-review](visual-review/README.md). Ветка `main` не
|
||||
содержит отдельный архив live screenshots этого аудита. Любое использование
|
||||
результатов требует повторной проверки актуальной версии и окружения.
|
||||
|
||||
## 4. Постоянные правила дизайна и полномочия
|
||||
|
||||
[DESIGN.md](../../DESIGN.md) остаётся нормативной дизайн-системой: цветовые
|
||||
токены, типографика, бренд, композиционные принципы и доступность не
|
||||
дублируются здесь. Этот roadmap задаёт работы, исторические критерии и gates;
|
||||
он не утверждает новый дизайн и не разрешает production deployment.
|
||||
|
||||
Все пункты плана отмечать выполненными только при наличии актуального
|
||||
свидетельства. Изменения приложения проходят обычные тесты, версионирование,
|
||||
CI и независимое review. Инфраструктурные изменения отражаются в
|
||||
`CURRENT_STATE.md` только по фактическим проверкам. Никакие действия с
|
||||
production, секретами, пользователями или правовым корпусом не следуют из
|
||||
наличия этого документа. Root-only bootstrap и предоставление секретов
|
||||
выполняет/утверждает владелец в защищённой среде; DEV готовит проверяемый код
|
||||
и точный план, reviewer независимо проверяет безопасность и failure paths.
|
||||
@@ -11,8 +11,13 @@
|
||||
|
||||
- загрузчик находится в `backend/ingestion/minjust_cbd.py`;
|
||||
- сырой архив хранится в `data/minjust-cbd` и исключён из Git;
|
||||
- в манифесте 209 811 успешно загруженных документов;
|
||||
- 13 кодов остаются в таблице `errors` и отсутствуют в таблице `documents`;
|
||||
- в read-only проверенном манифесте 209 958 документов;
|
||||
- один код, `6`, остаётся в таблице `errors` и отсутствует в `documents`;
|
||||
это не подтверждает отсутствие документа в источнике: при последней
|
||||
проверке OpenData API возвращал HTTP `404` для списка, `GetDocument(6)`,
|
||||
контрольного `GetDocument(1096)` и `CheckAvailable`;
|
||||
- в нормализованном манифесте 209 958 успешных записей, schema `1`,
|
||||
normalizer `1.0.0`; полная потоковая проверка всех файлов ещё выполняется.
|
||||
- документ содержит `metadata.json` и каталог `editions`;
|
||||
- редакция содержит `metadata.json`, `ru.html` и/или `ky.html`, иногда
|
||||
изображения;
|
||||
@@ -214,4 +219,4 @@ python3 backend/normalization/minjust_cbd.py
|
||||
|
||||
---
|
||||
|
||||
Акылдаш · Telegram-бот v0.2.2 · Backend v0.5.0 · Frontend — не создан
|
||||
Акылдаш · Telegram-бот v0.2.2 · Backend v0.7.1 · Frontend — не создан
|
||||
@@ -0,0 +1,307 @@
|
||||
# План развития «Акылдаш»: конкурентный анализ «Токтом Онлайн»
|
||||
|
||||
Дата: 24 октября 2026 года. Статус: предложение для продуктового решения;
|
||||
не утверждённый бюджет или срок выпуска. Изменения приложения этим документом
|
||||
не выполняются.
|
||||
|
||||
## 1. Вывод и оценка шансов
|
||||
|
||||
**На текущем этапе «Акылдаш» не готов заменить профессиональную СПС целиком.
|
||||
Шанс построить востребованный продукт есть, если начать с ограниченного
|
||||
практического сегмента и доказать качество данных и экономию времени.**
|
||||
|
||||
Копирование всей широты конкурента потребует не только разработки, но и
|
||||
постоянной юридической редакции, получения материалов, сопровождения клиентов
|
||||
и продаж. Рекомендуемая стартовая гипотеза — поиск и контроль норм для
|
||||
небольших юридических и бухгалтерских команд, работающих с ОсОО/ЖЧК,
|
||||
налогообложением и трудовыми вопросами. Наличие отдельных поисковых улучшений
|
||||
по ОсОО и налогам делает этот сегмент удобным для проверки, но само по себе
|
||||
не подтверждает спрос.
|
||||
|
||||
| Сценарий | Оценка | Что должно измениться |
|
||||
| --- | --- | --- |
|
||||
| Быстрая полная замена привычной СПС | Низкие шансы сейчас | Нужны надёжный выпуск, полнота материалов и профессиональные инструменты |
|
||||
| Дополнительный инструмент для одной практической задачи | Наиболее реалистичная гипотеза | Пилот должен показать измеримую пользу без обязательного отказа от прежней системы |
|
||||
| Основное рабочее место небольшой команды | Условно достижимо после пилота | Нужны удержание, обновления, персональная работа и подтверждённая готовность платить |
|
||||
| Массовая платформа с ИИ-консультантом | Долгосрочная гипотеза | Нужны проверяемые ответы, экономика обслуживания и контроль юридических ошибок |
|
||||
|
||||
Проценты вероятности успеха не рассчитываются: нет данных о числе клиентов
|
||||
конкурента, продажах, удержании, нашей команде, бюджете и стоимости привлечения.
|
||||
Цены, скорость и качество поиска систем в одинаковых условиях не сравнивались.
|
||||
Техническая возможность создать функцию не доказывает коммерческое преимущество.
|
||||
|
||||
## 2. Основание и ограничения исследования
|
||||
|
||||
Изучено открытое [руководство «Токтом Онлайн»](https://online.toktom.kg/cms/Topic/273)
|
||||
целиком: портал, учётные записи, продукты, поиск и работа с документами.
|
||||
В таблице ниже номера означают разделы этого руководства. Описание функции
|
||||
подтверждает её документирование, но не результат испытания платной системы.
|
||||
Дата последнего обновления руководства не установлена; старый год в подвале
|
||||
не позволяет определить актуальность отдельных инструкций.
|
||||
|
||||
Отдельная [страница продукта](https://online.toktom.kg/cms/Topic/292)
|
||||
заявляет ежедневное обновление и работу через интернет с синхронизацией
|
||||
персональных данных. Это заявления поставщика; их фактическое выполнение
|
||||
не проверялось. Актуальный тариф на этой странице предлагается запрашивать.
|
||||
|
||||
База сравнения «Акылдаш»: актуальная на повторной сверке `origin/main`, commit
|
||||
`c8d0086a9f20485c5efe6f9d3ccd476dd9f07065` (2 ноября 2026 года). Матрица
|
||||
G01–G25, описание текущих возможностей в разделе 3 и этапы A–F в разделе 6
|
||||
повторно сверены с этой базой. Проверены:
|
||||
|
||||
- [README](../../README.md), [обзор продукта](project-overview.md);
|
||||
- [API](../../backend/search/api.py), [поисковый интерфейс](../../backend/search/review.html),
|
||||
[учётные записи](../../backend/search/auth.py), [запросы](../../backend/search/query.py);
|
||||
- [каталоги](search-catalog-v1.md), [план frontend](frontend-search-sps-plan.md),
|
||||
[readiness gate](frontend-design-readiness-plan.md);
|
||||
- [состояние инфраструктуры и корпуса](../operations/CURRENT_STATE.md),
|
||||
[доступ](../operations/ACCESS.md), а также актуальные реализации Search API,
|
||||
учётных записей и поискового интерфейса.
|
||||
|
||||
Матрица отражает возможности реализации на указанном commit, а не только
|
||||
состояние прежней базы исследования. В частности, в текущем внутреннем контуре
|
||||
администратор может создавать и удалять учётные записи и сбрасывать пароль;
|
||||
публичная регистрация и восстановление по email по-прежнему отсутствуют.
|
||||
Технические версии кода: Backend 0.13.3 (`APP_VERSION` в
|
||||
`backend/search/minjust_opensearch.py`), Frontend 0.3.3 (подвал
|
||||
`backend/search/review.html`), Telegram-бот 0.2.2 (`APP_VERSION` в
|
||||
`tools/telegram-bot/bot.py`). Корневой README указывает Backend 0.13.2;
|
||||
`backend/README.md` содержит более старые Backend 0.13.0 / Frontend 0.2.3.
|
||||
При расхождении использованы версия backend и подвал интерфейса в указанном
|
||||
commit. Эти версии не подтверждают развёртывание соответствующего кода.
|
||||
Живой production, полнота локального корпуса и пользовательская доступность
|
||||
не подтверждены текущими проверками. Нельзя считать функцию доступной клиентам
|
||||
только на основании наличия кода.
|
||||
|
||||
## 3. Что уже есть у нас
|
||||
|
||||
В реализации есть полнотекстовый поиск RU/KY, фильтры по виду, статусу, группе
|
||||
органа, юридической силе и дате; пагинация и сортировка по релевантности/дате.
|
||||
Есть API карточки и редакций, чтение выбранной редакции и языка, оглавление,
|
||||
поиск внутри текста, печать и переход на официальный источник.
|
||||
Это **не нужно разрабатывать заново**.
|
||||
|
||||
Учётные записи SQLite, проверка полномочий на сервере,
|
||||
смена пароля и административные создание, удаление и сброс пароля доступны
|
||||
во внутреннем контуре. Лаборатория собирает оценки выдачи и комментарии
|
||||
проверяющих. Это не публичная регистрация, не восстановление пароля по email,
|
||||
не пользовательские заметки к нормам и не история исследований между устройствами.
|
||||
|
||||
По состоянию, записанному в `CURRENT_STATE.md`, публичный запуск и готовность
|
||||
всего корпуса не подтверждены. В документе есть исторические проверки архива
|
||||
и ограниченного staging; успешная обработка одного документа не доказывает
|
||||
полноту и актуальность базы. RAG в README отмечен как ещё не созданный.
|
||||
|
||||
## 4. Функциональные пробелы
|
||||
|
||||
Обозначения: **нет** — в проверенных API, UI и профильных планах отсутствует
|
||||
готовая возможность; **частично** — есть основа, но сценарий неполон;
|
||||
**не подтверждено** — без аудита корпуса или рабочего сервиса вывод невозможен.
|
||||
«Нет» относится к реализации указанного commit, а не ко всем внешним наработкам.
|
||||
P0 — до публичного пилота; P1 — основное рабочее место; P2 — после спроса;
|
||||
P3 — только при отдельном обосновании.
|
||||
|
||||
| ID | Возможность в руководстве «Токтом» | Состояние «Акылдаш» и необходимое дополнение | Приоритет |
|
||||
| --- | --- | --- | --- |
|
||||
| G01 | Регистрация, восстановление, соцвход (§1.1–1.2) | Частично: внутренние аккаунты есть; публичный onboarding и восстановление по email отсутствуют. Соцвход отложить | P1 / P3 |
|
||||
| G02 | Организация и профиль (§3.1.1) | Частично: есть кабинет, но нет полноценной модели организаций | P2 |
|
||||
| G03 | Счёт, платежи (§3.1.2) | Нет: коммерческий учёт и сверка оплат | P2 |
|
||||
| G04 | Продукты, сроки, промокоды (§3.2.1–3) | Нет: тарифные права и жизненный цикл подписки | P2 |
|
||||
| G05 | Подключение коллег (§3.2.4–5) | Нет: приглашения и права внутри организации; внутренние роли не заменяют это | P2 |
|
||||
| G06 | Настройки выдачи (§3.2.6) | Частично: параметры доступны, серверного сохранения предпочтений нет | P1 |
|
||||
| G07 | Тематические разделы (§3.3.1) | Частично: черновая таксономия есть, публичный тематический фильтр отсутствует | P1 |
|
||||
| G08 | Судебные, справочные, зарубежные материалы (§3.3.1) | Не подтверждено: специализированные полные коллекции и их поиск не показаны; наличие отдельных актов в ЦБД не исключается | P2 / P3 |
|
||||
| G09 | Новые документы (§3.3.3) | Нет отдельной пользовательской ленты поступлений | P1 |
|
||||
| G10 | Избранное, изменения (§3.3.4) | Нет серверного списка и пользовательского контроля изменений | P1 |
|
||||
| G11 | История документов/запросов (§3.3.5) | Нет синхронизированной истории исследования; URL браузера и история входов — другие данные | P1 |
|
||||
| G12 | Обзор обновлений (§3.3.6) | Нет журнала новых, изменённых и отменённых актов для пользователя | P0 / P1 |
|
||||
| G13 | Открытие по коду (§3.4.2) | Частично: API принимает код, отдельного пользовательского сценария нет | P1 |
|
||||
| G14 | Расширенные реквизиты (§3.4.3) | Частично: нужны номер, раздельные поля названия/текста, тематический отбор, множественные значения и поиск без обязательного q | P1 |
|
||||
| G15 | Детальные органы, публикация (§3.4.3.1) | Частично: API ограничен группами органов; нет полного реестра и фильтров по регистрации/источнику публикации | P2 |
|
||||
| G16 | Шаблоны запросов (§3.4.3.2) | Нет именованных сохранённых поисков | P1 |
|
||||
| G17 | Сортировка по органу/виду (§3.5.3) | Нет таких режимов и выбора направления; текущая дата имеет дополнительный приоритет статуса | P2 |
|
||||
| G18 | Word: выдача/документ (§3.5.4; 3.6.6) | Нет DOCX-экспорта; браузерная печать уже есть | P1 |
|
||||
| G19 | Справка и реквизиты (§3.6.1) | Частично: метаданные есть, полная читаемая паспортная карточка требует доработки | P1 |
|
||||
| G20 | Связи, обратные ссылки (§3.6.7–8) | Нет собственного проверенного графа связей и обратного индекса; исходные HTML-ссылки не равнозначны | P1 |
|
||||
| G21 | Предпросмотр, «Связной» (§3.6.9; 13) | Нет контекстного просмотра и связей на уровне конкретной нормы | P2 |
|
||||
| G22 | Графические копии (§3.6.10) | Частично на уровне архива: готовая выдача оригиналов не подтверждена; вложения staging не верифицированы | P2 |
|
||||
| G23 | Сравнение редакций (§3.6.12) | Нет сопоставления двух текстов и выделения изменений; переключатель редакций уже есть | P1 |
|
||||
| G24 | Языковое сравнение (§3.6.14) | Нет параллельного просмотра; переключение RU/KY уже есть | P1 |
|
||||
| G25 | Форум, сообщения (§2; 3.2.7–8) | Нет пользовательского сообщества; рабочий Telegram-бот команды его не заменяет | P3 |
|
||||
|
||||
Редакции, языки, оглавление и печать (§3.6.2–5) в перечень отсутствующих
|
||||
функций не включены. Для сравнительного списка использовано
|
||||
[руководство поставщика](https://online.toktom.kg/cms/Topic/273).
|
||||
|
||||
## 5. Стратегия отличия
|
||||
|
||||
Это гипотезы развития, а не установленные преимущества над конкурентом.
|
||||
Отсутствие описания в его руководстве не доказывает отсутствия функции.
|
||||
|
||||
1. **Проверяемая актуальность.** На каждой норме показывать источник, редакцию,
|
||||
время последней успешной проверки и ограничения данных. Разделять дату
|
||||
получения, принятия, вступления в силу и период применимости.
|
||||
2. **Практический двуязычный поиск.** Измерять RU и KY отдельно на реальных
|
||||
задачах, сокращениях и опечатках. Не обещать кыргызскую морфологию только
|
||||
из-за наличия ICU. Не подменять отсутствующий официальный текст переводом.
|
||||
3. **Рабочая задача вместо набора документов.** Проверить сценарий
|
||||
«найти применимую норму → проверить редакцию → сохранить доказательство →
|
||||
получить сигнал об изменении». Он должен занимать меньше времени у пилота.
|
||||
4. **Объяснение с проверяемыми ссылками.** После надёжного поиска добавить
|
||||
ответы с точными цитатами и открытием фрагмента. При недостатке источников
|
||||
система сообщает об этом; юридические выводы требуют проверки специалистом.
|
||||
|
||||
Удобный интерфейс и низкая цена сами по себе не обеспечат переход клиентов.
|
||||
Открытые источники также не дают автоматического разрешения на любой способ
|
||||
их использования. Права на каждый новый источник проверяются отдельно;
|
||||
копирование базы и редакционных материалов конкурента в план не входит.
|
||||
|
||||
## 6. Последовательность развития и приёмка
|
||||
|
||||
Сроки ниже — предварительные диапазоны для команды из двух разработчиков
|
||||
с регулярным участием юриста и частичным участием дизайнера/эксплуатации.
|
||||
Это предположение для обсуждения, не оценка существующего штата. При иной
|
||||
команде и после обследования данных сроки нужно пересчитать. Переходы
|
||||
определяются результатами, а не истечением недель.
|
||||
|
||||
### Этап A. Данные и воспроизводимый запуск — P0, ориентир 3–6 недель
|
||||
|
||||
Зависимости: состояние официального API, доступный корпус и участие владельца
|
||||
инфраструктуры. Назначить ответственных за данные, эксплуатацию и юридическую
|
||||
проверку. Согласовать правила текущей редакции и обработки неизвестного статуса.
|
||||
|
||||
- Завершить квалификацию источника и полный аудит корпуса; отдельно проверить
|
||||
языки, порядок редакций, контрольные суммы, ошибки, вложения и пропуски.
|
||||
- Запустить воспроизводимый цикл проверки обновлений с журналом изменений
|
||||
и безопасным переключением индекса. Из этого журнала строить G12 и G09.
|
||||
- Выполнить существующий readiness gate, зафиксировать baseline и ограничения.
|
||||
- Подготовить пилотное развёртывание, наблюдение за ошибками, проверенный backup
|
||||
и восстановление в изолированной среде по существующим процедурам.
|
||||
|
||||
Приёмка: завершённый отчёт о полноте с объяснёнными исключениями; повторный
|
||||
запуск не создаёт дубликатов; неудачное обновление сохраняет рабочий индекс;
|
||||
сквозные сценарии RU/KY проходят; восстановление проверено. Рекомендуемая цель
|
||||
актуализации — не более суток от доступности изменения у источника; сначала
|
||||
измерить достижимость и только затем обещать SLA пользователям.
|
||||
|
||||
### Этап B. Поисковое рабочее место — P1, ориентир 4–6 недель
|
||||
|
||||
Зависимость: этап A. Закрыть G07, G13–14, G18–19 и уточнить G06.
|
||||
Использовать готовые просмотр, печать и оглавление; не переписывать их.
|
||||
|
||||
- Утвердить темы и устойчивые идентификаторы; не превращать черновые хеши
|
||||
классификатора в публичный контракт без проверки.
|
||||
- Добавить точный номер и независимые поля поиска; разрешить отбор только
|
||||
по реквизитам; определить семантику AND/OR и множественного выбора.
|
||||
- Сделать паспорт документа, пользовательский сценарий открытия по коду и
|
||||
DOCX с редакцией, языком, источником и временем выгрузки. Не обещать PDF-
|
||||
экспорт сверх печати до подтверждения отдельной потребности.
|
||||
|
||||
Приёмка: 20 задач пилота успешно проходят путь от запроса до нужного фрагмента;
|
||||
документы без языка/текста имеют понятное состояние; файл экспорта воспроизводит
|
||||
выбранную редакцию; новые правила не ухудшают замороженный relevance baseline.
|
||||
|
||||
### Этап C. Возвращение к работе и контроль — P1, ориентир 3–5 недель
|
||||
|
||||
Зависимости: A–B; для внешних пользователей — выбранная модель доступа и
|
||||
проверенное восстановление аккаунта G01. Для закрытого пилота допустимы
|
||||
создаваемые администратором внутренние аккаунты без публичной регистрации.
|
||||
|
||||
Закрыть G06, G10–11, G16: серверные избранное, история и шаблоны; G09/G12
|
||||
показать как пользовательскую ленту. Добавить настройки контроля и доставки
|
||||
уведомлений только после появления надёжного журнала обновлений. Выбор канала
|
||||
и согласие пользователя — отдельное решение; наличие бота команды не означает
|
||||
готовность продуктовых уведомлений.
|
||||
|
||||
Приёмка: сохранённое доступно со второго устройства; данные разных аккаунтов
|
||||
изолированы; удаление/отключение контроля работает; повторная обработка события
|
||||
не дублирует сигнал. Правила хранения истории и удаления аккаунта документированы.
|
||||
|
||||
### Этап D. Анализ нормы — P1/P2, ориентир 5–8 недель
|
||||
|
||||
Зависимости: проверенные редакции, структура фрагментов и метаданные A–B.
|
||||
Закрыть G23–24 и базовую часть G20; затем G21, G22 и G15 по результатам пилота.
|
||||
Для связей сохранять источник, целевую редакцию и уверенность сопоставления.
|
||||
|
||||
Приёмка: юрист проверяет не менее 30 разнообразных пар редакций, включая
|
||||
перенумерацию и перемещение статей; интерфейс отличает техническую правку от
|
||||
содержательной, а неопределённость показывает явно. Параллельный RU/KY-просмотр
|
||||
использует одну редакцию и не выдумывает соответствия. Неуверенные ссылки
|
||||
не выдаются как подтверждённые связи. Текстовый diff не считается юридическим
|
||||
заключением о дате применимости нормы.
|
||||
|
||||
### Этап E. Платный командный продукт — P2, ориентир 4–8 недель
|
||||
|
||||
Зависимость: подтверждённые повторное использование и готовность платить.
|
||||
Закрыть G02–05 и недостающую часть G01. Сначала выбрать одну понятную модель
|
||||
подписки и необходимый канал оплаты; не воспроизводить весь биллинг конкурента.
|
||||
|
||||
Приёмка: организация приглашает и отзывает участника; сервер проверяет права
|
||||
и срок доступа; повторное платёжное событие не создаёт повторное начисление;
|
||||
просроченная подписка не уничтожает сохранённые данные. Стоимость эксплуатации,
|
||||
юридической редакции и поддержки учитывается в экономике тарифа.
|
||||
|
||||
### Этап F. Новые источники и ответы — P2/P3, отдельная оценка
|
||||
|
||||
G08, G17, G25 и оставшиеся расширения включать по измеренному спросу.
|
||||
Для судебной практики сначала исследовать законность получения, полноту,
|
||||
обезличивание и обновляемость; для экспертных материалов — лицензирование
|
||||
и редакционную ответственность. Международные акты проверять в существующем
|
||||
корпусе прежде, чем создавать отдельный загрузчик. Зарубежную базу и форум
|
||||
не ставить на критический путь первого продукта.
|
||||
|
||||
RAG — отдельная разработка после A–D. Начать с поиска доказательств и цитат,
|
||||
затем краткого ответа. Приёмка: замороженный экспертный набор, проверка каждой
|
||||
ссылки и редакции, отказ при недостатке данных и ноль критических неподтверждённых
|
||||
юридических утверждений на приёмочном наборе. Это критерий допуска, а не гарантия
|
||||
безошибочности вне набора. Сравнение качества ИИ конкурентов пока не выполнено.
|
||||
|
||||
## 7. Проверка рыночной гипотезы и условия остановки
|
||||
|
||||
Параллельно этапу A провести 12–15 интервью с юристами и бухгалтерами, включая
|
||||
пользователей действующих СПС. Собирать обезличенные задачи, частоту,
|
||||
потери времени, критичные источники и причины отказа от нового сервиса.
|
||||
Цены сравнивать после получения актуальных коммерческих предложений.
|
||||
|
||||
Предлагаемый пилот: 10–15 специалистов, 4 недели, 20 одинаковых задач с RU/KY
|
||||
и простыми/сложными запросами. С согласия участников сравнить время и долю
|
||||
правильных решений в текущем инструменте и «Акылдаш»; менять порядок систем,
|
||||
чтобы уменьшить эффект обучения. Результат оценивает юрист по первоисточнику.
|
||||
|
||||
Цели ниже — предлагаемые пороги решения, не уже достигнутые показатели:
|
||||
|
||||
| Измерение | Предлагаемый порог | Решение |
|
||||
| --- | --- | --- |
|
||||
| Качество поиска | Recall@10 ≥ 0,90 и MRR@10 ≥ 0,75 на независимо проверенном наборе, отдельно RU и KY | При недостижении улучшать поиск до расширения функций |
|
||||
| Практическая польза | Медианное время правильного выполнения задач меньше минимум на 25% | При отсутствии выигрыша пересмотреть сценарий и сегмент |
|
||||
| Возвращаемость | Не менее 60% активированных участников пользуются продуктом на четвёртой неделе | При провале сначала исследовать причины, затем решать о биллинге |
|
||||
| Готовность платить | Не менее трёх независимых организаций готовы на платный пилот по названной цене | Переходить к этапу E после проверки экономики |
|
||||
| Доверие | Нет критических ошибок редакции/источника в приёмочных задачах | Любая такая ошибка блокирует публичные обещания надёжности |
|
||||
|
||||
Малый пилот помогает выбрать направление, но не даёт оценки доли рынка.
|
||||
Если пользователям необходимы источники, которые мы не можем законно получить,
|
||||
либо стоимость сопровождения превышает приемлемый тариф, сузить сегмент или
|
||||
остановить выбранную модель до дальнейших вложений.
|
||||
|
||||
## 8. Ближайший рабочий цикл
|
||||
|
||||
1. Назначить владельца продукта и юридического редактора; согласовать сегмент.
|
||||
2. Зафиксировать состояние корпуса и readiness gate на актуальной main.
|
||||
3. Провести интервью, собрать задачи и заморозить критерии пилота.
|
||||
4. Превратить этап A и минимальную часть B в отдельные задачи с зависимостями
|
||||
и критериями приёмки. Согласовать связь с существующим планом frontend,
|
||||
не отменяя его gate этим документом.
|
||||
5. После пилота пересчитать сроки, стоимость и порядок C–F; выбрать, какие
|
||||
пробелы действительно мешают продаже, а какие можно отложить.
|
||||
|
||||
Для реализации сохранять существующую архитектуру Python/SQLite/OpenSearch,
|
||||
использовать текущие API и компоненты, добавлять зависимости только по
|
||||
обоснованной необходимости. Изменения проводить отдельными PR с проверками,
|
||||
версией при изменении кода, независимым review и changelog. Production-действия
|
||||
и изменение инфраструктуры требуют действующих процедур доступа и backup.
|
||||
|
||||
---
|
||||
|
||||
Повторная сверка реализации: `main` `c8d0086a9f20485c5efe6f9d3ccd476dd9f07065`.
|
||||
Backend v0.13.3 · Frontend v0.3.3 · Telegram-бот v0.2.2. Это версии
|
||||
исследованного кода; они не подтверждают развёртывание этих версий.
|
||||
@@ -44,4 +44,4 @@
|
||||
|
||||
---
|
||||
|
||||
Акылдаш · Telegram-бот v0.2.2 · Backend v0.5.0 · Frontend — не создан
|
||||
Акылдаш · Telegram-бот v0.2.2 · Backend v0.12.2 · Frontend v0.1.2
|
||||
@@ -0,0 +1,128 @@
|
||||
# Справочники Search API v1
|
||||
|
||||
Статус: рабочий контракт Search API v1. Тематическая иерархия вынесена в
|
||||
отдельный черновой каталог и не входит в фильтры API v1.
|
||||
|
||||
`code` — неизменяемый идентификатор, независимый от языка. Клиент хранит и
|
||||
передаёт только `code`; русское и кыргызское названия являются подписями и могут
|
||||
исправляться без изменения кода.
|
||||
|
||||
## Типы документов
|
||||
|
||||
| Code | RU | KY |
|
||||
| --- | --- | --- |
|
||||
| `constitution` | Конституция | Конституция |
|
||||
| `constitutional_law` | Конституционный Закон | Конституциалык Мыйзам |
|
||||
| `code` | Кодекс | Кодекс |
|
||||
| `law` | Закон | Мыйзам |
|
||||
| `decree` | Указ | Жарлык |
|
||||
| `resolution` | Постановление | Токтом |
|
||||
| `order` | Распоряжение | Распоряжение |
|
||||
| `instruction` | Инструкция | Инструкция |
|
||||
| `rules` | Правила | Правила |
|
||||
| `procedure` | Порядок | Порядок |
|
||||
| `provision` | Положение | Жобо |
|
||||
| `regulation` | Регламент | Регламент |
|
||||
| `charter` | Устав | Жобо (Устав) |
|
||||
| `program` | Программа | Программа |
|
||||
| `plan` | План | План |
|
||||
| `strategy` | Стратегия | Стратегия |
|
||||
| `concept` | Концепция | Концепция |
|
||||
| `doctrine` | Доктрина | Доктрина |
|
||||
| `agreement` | Соглашение | Соглашение |
|
||||
| `declaration` | Декларация | Декларация |
|
||||
| `registry` | Реестр | Реестр |
|
||||
| `norms` | Нормативы | Нормативы |
|
||||
| `model` | Модель | Модель |
|
||||
| `matrix` | Матрица | Матрица |
|
||||
| `study` | Исследование | Исследование |
|
||||
| `report` | Доклад | Доклад |
|
||||
| `principles` | Основные принципы | Основные принципы |
|
||||
| `unspecified` | Не указан | Көрсөтүлгөн эмес |
|
||||
|
||||
## Статусы
|
||||
|
||||
| Code | RU | KY |
|
||||
| --- | --- | --- |
|
||||
| `active` | Действует | Күчүндө |
|
||||
| `repealed` | Утратил силу | Күчүн жоготту |
|
||||
| `unspecified` | Не указан | Көрсөтүлгөн эмес |
|
||||
|
||||
## Юридическая сила
|
||||
|
||||
Это укрупнённая группировка для фильтра Search API, а не полная иерархия
|
||||
нормативных правовых актов из статьи 6 Закона КР «О нормативных правовых
|
||||
актах». В этой группировке Конституция и конституционные законы относятся к
|
||||
конституционному уровню, кодексы и законы — к законодательному, указы и
|
||||
постановления, перечисленные законом как виды НПА, — к подзаконному.
|
||||
|
||||
| Code | RU | KY |
|
||||
| --- | --- | --- |
|
||||
| `constitutional` | Конституционный уровень | Конституциялык деңгээл |
|
||||
| `legislative` | Законодательный уровень | Мыйзам деңгээли |
|
||||
| `subordinate` | Подзаконный уровень | Мыйзам алдындагы деңгээл |
|
||||
|
||||
Для прочих типов значение не назначается автоматически: одного названия типа
|
||||
недостаточно, чтобы установить юридическую силу утверждающего НПА. Основание:
|
||||
[статьи 4 и 6 Закона КР «О нормативных правовых актах»](https://cbd.minjust.gov.kg/4-3987/edition/53304/ru).
|
||||
Эта группировка реализована как фильтр `legal_force` Search API v1.
|
||||
|
||||
## Органы принятия
|
||||
|
||||
Орган содержит два уровня: стабильную группу и конкретный орган. В v1 группы
|
||||
следующие:
|
||||
|
||||
| Code | RU | KY |
|
||||
| --- | --- | --- |
|
||||
| `president` | Президент | Президент |
|
||||
| `parliament` | Органы законодательной власти | Мыйзам чыгаруу бийлик органдары |
|
||||
| `cabinet` | Правительство и Кабинет Министров | Өкмөт жана Министрлер Кабинети |
|
||||
| `ministries_and_committees` | Министерства и государственные комитеты | Министрликтер жана мамлекеттик комитеттер |
|
||||
| `administrative_agencies` | Административные ведомства | Административдик ведомстволор |
|
||||
| `national_bank` | Национальный банк | Улуттук банк |
|
||||
| `other_state_bodies` | Иные государственные органы | Башка мамлекеттик органдар |
|
||||
| `local_representative_bodies` | Представительные органы местного самоуправления | Жергиликтүү өз алдынча башкаруунун өкүлчүлүктүү органдары |
|
||||
| `other` | Прочие органы | Башка органдар |
|
||||
|
||||
Конкретные министерства, муниципальные и айылные кенеши не получают ID из
|
||||
подписи: в выгрузке ЦБД их поле `Code` часто равно `null`. До появления
|
||||
первичного неизменяемого идентификатора API v1 выдаёт и принимает только код
|
||||
группы органа. Полный каталог конкретных органов — отдельная версия (`v2`),
|
||||
когда источник предоставит такие идентификаторы либо будет утверждён вручную
|
||||
поддерживаемый реестр.
|
||||
|
||||
## Темы
|
||||
|
||||
Полная исходная иерархия `GeneralClassifiers` сохранена отдельно в
|
||||
[`search-topic-taxonomy-v1.json`](search-topic-taxonomy-v1.json). Над исходными
|
||||
ветвями добавлены предложенные смысловые группы; исходные подписи и вложенность
|
||||
не переставляются. Поле `document_count` показывает число документов, где узел
|
||||
встречается. Предлагаются группы: конституционный строй и права; государство и
|
||||
публичное управление; право, суд и правопорядок; международные отношения;
|
||||
оборона и безопасность; экономика, финансы и предпринимательство; труд и
|
||||
социальная защита; здравоохранение; образование, наука и культура; земля,
|
||||
природные ресурсы и окружающая среда; сельское хозяйство; транспорт, связь,
|
||||
строительство и жильё; информация и СМИ; гражданские, семейные и жилищные
|
||||
отношения; общие и межотраслевые вопросы.
|
||||
|
||||
Каталог является черновиком: группа корневой рубрики предложена по русской
|
||||
подписи, рубрики с несколькими совпадениями правил или без совпадений помещены
|
||||
в `review_required` и отмечены `manual_review`; остальные помечены
|
||||
`provisional_lexical`. В корпусе 2 065 узлов и 687 вариантов корневых рубрик;
|
||||
328 корневых вариантов ожидают ручной классификации. Отсутствующие в источнике
|
||||
кыргызские подписи оставлены пустыми: они отсутствуют у 1 524 узлов, новые
|
||||
переводы не придуманы. Внутренние `source-*` ID являются
|
||||
временными хешами кода источника и цепочки подписей; при `Code: null` они
|
||||
зависят от подписей и не утверждаются как публичные стабильные коды.
|
||||
|
||||
Тематическая навигация и фильтр не входят в Search API v1. До включения в API
|
||||
нужно вручную утвердить смысловые группы, идентификаторы и недостающие KY-
|
||||
подписи. Источник — нормализованные данные ЦБД Минюста; команда для пересборки
|
||||
каталога находится в `tools/build_search_topic_taxonomy.py`.
|
||||
|
||||
## Правила совместимости
|
||||
|
||||
- Код из этой таблицы нельзя переиспользовать и нельзя менять его значение.
|
||||
- Новое значение добавляется только новой записью; удалённое остаётся доступно
|
||||
для старых документов.
|
||||
- Запрос с неизвестным кодом возвращает `400`.
|
||||
@@ -0,0 +1,318 @@
|
||||
# Диагностика релевантности поиска — 3 ноября 2026 года
|
||||
|
||||
## Решения и границы
|
||||
|
||||
Эта заметка фиксирует исходные измерения от 2 ноября, узкое исправление
|
||||
терминологии, условный multi-index scoring и контракт для закрытия пробела
|
||||
корпуса. Выдачи и AI-аннотации не являются юридической оценкой. Целевой A/B
|
||||
прогон и полный benchmark для итогового SHA описаны ниже; они не заменяют
|
||||
экспертную оценку.
|
||||
|
||||
Изменён backend `0.13.3` → `0.13.4`, frontend внутренней лаборатории
|
||||
`0.3.3` → `0.3.4`, версия алгоритма `search-6` → `search-8`. `search-7`
|
||||
относится к предшествующему составу ranking semantics; новые подписанные
|
||||
снимки этого PR помечаются `search-8`. Сохранённые отзывы не переписываются.
|
||||
Финальный runtime/batch прогон кода выполнен на `1c7ddf2`; последующий коммит
|
||||
этого отчёта и changelog меняет только документацию.
|
||||
|
||||
## Исходный benchmark
|
||||
|
||||
Зафиксированный набор содержит 7 500 русских формулировок: 15 тематических
|
||||
групп, по 500 запросов в каждой. Это 750 тем с десятью вариантами формулировки,
|
||||
а не 7 500 независимых правовых ситуаций. Исходный индекс
|
||||
`akyldash-fragments-v2` содержал около 42,6 млн фрагментов и занимал 11,2 ГБ.
|
||||
|
||||
| Показатель Акылдаш, исходный прогон | Результат |
|
||||
|---|---:|
|
||||
| Собранные выдачи | 7 500 / 7 500 |
|
||||
| Пустые выдачи | 6 |
|
||||
| Медиана / P95 ответа | 21,67 / 77,36 мс |
|
||||
| Совпадение основ темы в видимых названии/фрагменте, top 1 | 40,57% |
|
||||
| То же, top 3 / top 10 | 47,05% / 51,40% |
|
||||
|
||||
Сравнение с КонсультантПлюс в исходном отчёте — только диагностическое:
|
||||
юрисдикции и корпуса различаются. Совпадение основ темы не измеряет Recall,
|
||||
MRR, полноту ответа или юридическую правильность; российская выдача не является
|
||||
эталоном права Кыргызстана. Для вывода о качестве нужны экспертные релевантные
|
||||
коды, контрольный набор и отдельные метрики.
|
||||
|
||||
## Подтверждённые классы ошибок
|
||||
|
||||
14 коротких документов прочитаны целиком; Codex (ИИ) подготовил по ним 79
|
||||
предварительных оценок пар «запрос—документ» в 71 сессии: 59 помечены как
|
||||
нерелевантные и 20 как косвенно полезные. Это тематическая AI-разметка для
|
||||
триажа, а не заключение юриста или независимая экспертная проверка. Она не
|
||||
подтверждает полноту правового ответа. Неоценённые результаты не считались
|
||||
ошибками.
|
||||
|
||||
| Тема | Наблюдавшийся неверный приоритет | Вывод |
|
||||
|---|---:|---|
|
||||
| Расторжение договора аренды | 135066 | Решение по одной сделке с землёй не даёт общих оснований расторжения |
|
||||
| Международный коммерческий арбитраж | 26411 | Продажа земельных участков не регулирует арбитраж и отказ в признании решения |
|
||||
| Испытательный срок работника | 94603 | Земельный участок под завод/испытательный полигон совпадает словами, но не предметом |
|
||||
| Место жительства ребёнка | 50760 | Финансирование приюта не устанавливает порядок спора родителей |
|
||||
| Перевод студента в другой вуз | 14165 | Разовое финансирование студентов не устанавливает процедуру перевода |
|
||||
| Таможенные пошлины | 41854 | Индивидуальная отсрочка одному предприятию не задаёт общие правила |
|
||||
| Общий порядок предоставления земли | 54735, 54571 | Решения по отдельным участкам не являются общей процедурой |
|
||||
| Защита критической инфраструктуры | 59082 | Предоставление земли под завод не устанавливает защитные требования |
|
||||
| Купля-продажа / расторжение договора | 60053 | Расторжение одной сделки с госакциями не является общей нормой |
|
||||
| Подача искового заявления | 18516, 7115 | Отдельный спор и узкая льгота по пошлине не дают общего порядка подачи иска |
|
||||
| Принятие нормативных актов | 77190 | Первое чтение одного законопроекта не устанавливает общий процесс |
|
||||
| Подключение к водоснабжению | 135061 | Целевая помощь отдельным домохозяйствам не задаёт технические условия |
|
||||
|
||||
Проверенные варианты глобального повышения веса кодексов отвергнуты: вес 2 не
|
||||
исправил аренду и подачу иска, а вес 4 поднял Налоговый кодекс выше профильных
|
||||
источников по воинской обязанности и подаче иска. Общие веса или жёсткие
|
||||
приоритеты кодексов не добавлялись.
|
||||
|
||||
## Узкая терминологическая поправка
|
||||
|
||||
В исследованной редакции ГК КР II (код 5, редакция 460) глава 27 и статья 542
|
||||
связывают договор аренды с имущественным наймом; статьи 558–559 используют
|
||||
термин «имущественный наем». В полном тексте этой редакции буквальная фраза
|
||||
«расторжение договора аренды» не встречалась. Исходный запрос возвращал код
|
||||
135066 на первом месте, а формулировка «расторжение договора имущественного
|
||||
найма» — код 5.
|
||||
|
||||
Backend теперь сохраняет исходную строку и добавляет только для точного
|
||||
сочетания «договор [арендная форма]» вариант «договор [та же форма]
|
||||
имущественного найма». В частности, `договора аренды` превращается в
|
||||
`договора имущественного найма`. Расширение не срабатывает для аренды квартиры
|
||||
или земельного участка, поднайма, найма работника или лизинга. Точный запрос
|
||||
остаётся в строгой лексической ветке, поэтому его профильный муниципальный акт
|
||||
не исключается из поиска.
|
||||
|
||||
В read-only пробе предыдущей версии `aa6fabe` для общего запроса код 5 поднялся
|
||||
с позиции за пределами top 10 на #5, но нерелевантный индивидуальный акт 135066
|
||||
оставался первым. На SHA `726b1ee` isolated code-only прогон на исходном индексе
|
||||
поставил код 5 первым для общего запроса; из 7 500 запросов изменились 19
|
||||
выдач, 7 481 совпала с baseline, число пустых осталось 6. Этот результат
|
||||
проверяет `search-7` с `match_phrase` boost 12 для синтетической юридической
|
||||
фразы, исходный phrase boost 3; он не описывает multi-index DFS. После
|
||||
подключения трёх актов в отдельном supplement на `e653f3b` изменились 184
|
||||
выдачи против code-only варианта и 38 top-1; все шесть пустых выдач
|
||||
сохранились. Разные наборы индексов нельзя считать одним benchmark. Итоговый
|
||||
conditional-DFS прогон на `1c7ddf2` приведён ниже. Контроль запросов об аренде
|
||||
жилья/земли, поднайме, трудовых отношениях, международном праве и KY
|
||||
формулировках выполнялся отдельно; rank-метрики не являются юридической
|
||||
оценкой.
|
||||
|
||||
## Условный scoring для явного multi-index scope
|
||||
|
||||
При поиске по явно настроенному comma-separated scope (`base,supplement`) API
|
||||
передаёт `search_type=dfs_query_then_fetch` как URL query parameter. Запросы по
|
||||
одному настроенному индексу или alias сохраняют прежний `query_then_fetch`;
|
||||
одиночные wildcard и alias не классифицируются по результату их expansion.
|
||||
DFS включается только при запятой в настроенной строке scope.
|
||||
Тело DSL, фильтры, query weights, сортировка, индексы и документы не меняются.
|
||||
Параметр применяется только к `/search`; фильтры и остальные API вызовы
|
||||
используют прежний режим.
|
||||
|
||||
OpenSearch описывает `query_then_fetch` как scoring по локальным term/document
|
||||
frequencies шардов, а DFS — по глобальным frequencies через шарды; DFS обычно
|
||||
точнее, но может быть медленнее. `search_type` поддерживается именно как
|
||||
параметр Search API URL ([OpenSearch Search API](https://docs.opensearch.org/latest/api-reference/search-apis/search/)).
|
||||
Поэтому ограниченный режим использует глобальные statistics для явной
|
||||
multi-index конфигурации и не меняет behavior одиночного поиска.
|
||||
|
||||
На изолированном OpenSearch 3.7.0 оба режима сравнили на одинаковых DSL bytes и
|
||||
одном неизменном наборе данных: 300 заранее выбранных запросов, максимум 300.
|
||||
Порядок менялся в 93 случаях, top-1 — в 29; из 9 именованных риск-кейсов
|
||||
изменились 3, все 5 выбранных positive controls сохранили top-1. Контроль с
|
||||
индивидуальным актом 135066 сохранил этот акт первым. В пяти запросах о
|
||||
педагогических/научных работниках и одном запросе о болезнях животных top-1 не
|
||||
изменился. Эти шесть случаев требуют предметной оценки и не объявляются
|
||||
автоматически нерелевантными: статья 150(8) закона об охране здоровья связывает
|
||||
аттестацию педагогических/научных работников с медицинской деятельностью, а
|
||||
случай с болезнями животных остаётся без экспертной оценки. Новые оценки пар не
|
||||
выставлялись; специальные веса или document IDs не добавлялись. Сравнение
|
||||
ограничено выборкой и не является разметкой юридической правильности.
|
||||
Медианы 22,955 мс для default и 16,115 мс для DFS не используются как оценка
|
||||
скорости: default всегда исполнялся первым, возможен cache/order bias.
|
||||
|
||||
Frozen experiment metadata is stored outside the repository in
|
||||
`reports/search-benchmark-2026-11-02/dfs-probe-e653-summary.json`. The paired
|
||||
response-capture artifact `dfs-probe-e653.jsonl` has SHA-256
|
||||
`4a9373ba5236c5c5a1d85139b6dbe67bcf01df02216f8b2f292e5c451e6432c8`.
|
||||
Выборка содержала base index (42 624 501 fragments) и read-only supplement
|
||||
(8 934 fragments); UUID/count guards прошли, основной индекс и сохранённые
|
||||
отзывы во время эксперимента не менялись. В PR не включены сырые ответы,
|
||||
персональные данные или выдачи документов.
|
||||
|
||||
Кодовый тест проверяет URL, encoded multi-index path, RU/KY, пустую выдачу,
|
||||
прежнее тело запроса и неизменность single alias/index и filters. Read-only
|
||||
integration gate для root-owned runtime:
|
||||
|
||||
```bash
|
||||
AKYLDASH_OPENSEARCH_URL=http://127.0.0.1:8081 \
|
||||
AKYLDASH_OPENSEARCH_INDEX='akyldash-fragments-v2,akyldash-benchmark-supplement-20261103-r1' \
|
||||
PYTHONPATH=backend python3 -m unittest \
|
||||
backend.test_search_api_opensearch.SearchMultiIndexDfsOpenSearchTest.test_global_statistics_mode_accepts_read_only_multi_index_search -v
|
||||
```
|
||||
|
||||
Root выполнил этот read-only gate на 8081 для `1c7ddf2`: фактический multi-index
|
||||
URI использовал DFS и подписанный token сохранял полный scope. Gate выполняет
|
||||
только поиск и не создаёт/удаляет индексы. Полный benchmark на том же code SHA
|
||||
и frozen baseline приведён ниже; 300-query experiment и более ранние прогоны
|
||||
остаются отдельными сравнительными срезами.
|
||||
|
||||
Откат к предшествующему приложению возвращает `query_then_fetch` для multi-index
|
||||
поиска. Индекс, документы, saved reviews и старые подписанные токены при этом
|
||||
не требуют изменений или миграции; новые отзывы, сохранённые до rollback,
|
||||
остаются помечены `search-8`. Для supplement действует отдельный rollback
|
||||
контракт ниже: отключение его подключения скрывает только добавленные редакции,
|
||||
не удаляя подготовленные файлы и базовый индекс.
|
||||
|
||||
## Итоговый pinned прогон search-8
|
||||
|
||||
Полный isolated прогон для executable SHA `1c7ddf2fcbd7c55920470e7ac52339fdab0366db`
|
||||
собрал 7 500 уникальных запросов с версией `search-8`. SHA-256 выдачи:
|
||||
`fc02e22e5b3d612813ffc0bdaf9892bb16ee4c29af3e1b77f79e58a0a45c8ec1`. Итог
|
||||
сопоставлен с frozen baseline и двумя явно указанными промежуточными режимами:
|
||||
|
||||
| Сравнение | Изменён порядок | Изменён top-1 |
|
||||
|---|---:|---:|
|
||||
| Исходный baseline `search-6` | 537 | 103 |
|
||||
| Code-only `726b1ee`, `search-7` | 521 | 93 |
|
||||
| Code + три акта, `e653f3b`, без DFS | 425 | 63 |
|
||||
|
||||
Это число изменений порядка, а не улучшений. Все шесть пустых выдач сохранились
|
||||
во всех четырёх прогонах. Среди ранее проверенных Codex (ИИ) пар с нулевой
|
||||
оценкой top-1 стало 26 вместо 28 в baseline; остальные 26 не объявлены
|
||||
исправленными, и новые выдачи автоматически не оценивались.
|
||||
|
||||
| Добавленный акт | Наблюдался в top-1 / top-3 / top-10 |
|
||||
|---|---:|
|
||||
| Трудовой кодекс КР `230021083` | 24 / 58 / 105 |
|
||||
| Земельный кодекс КР `230029465` | 4 / 11 / 26 |
|
||||
| Закон об охране здоровья `230000918` | 34 / 51 / 92 |
|
||||
|
||||
Все шесть точных названий новых актов на RU/KY дали ожидаемый текущий акт первым.
|
||||
Все 284 запроса, общие с целевым DFS экспериментом, совпали с ним по полному
|
||||
порядку кодов и редакций. Проверки dataset guard подтвердили неизменность
|
||||
исходного индекса, manifest, mappings и UUID/count, а также 115 подключённых
|
||||
файлов. 7 503 записи локальной лаборатории совпали с backup; обе SQLite
|
||||
integrity checks прошли. Записи оценок, комментарии и пользователи не менялись.
|
||||
|
||||
Шесть межтематических контекстов нельзя автоматически считать нерелевантными:
|
||||
медицинский закон остался первым в пяти запросах о педагогических/научных
|
||||
работниках и в одном запросе о болезнях животных. Для педагогических случаев
|
||||
проверенная статья 150(8) связывает аттестацию этих работников с медицинской
|
||||
деятельностью; новые оценки пар не выставлялись. Вопрос о животных также
|
||||
остался без экспертной оценки. ИИ-аннотации не доказывают полноту правового
|
||||
ответа или юридическую правильность ранжирования.
|
||||
|
||||
Режим и scope дополнительно проверены на runtime `8081`: для multi-index `/search`
|
||||
уходит DFS, для одиночного индекса и filters — прежний default; тело DSL
|
||||
одинаково. Alias проверен transport mock без создания alias. Runtime mode/API
|
||||
smoke включал HMAC/TTL, signed scope, сохранение пустого результата и
|
||||
отрицательные rank/code сценарии. Browser UI fixture прошёл на `726b1ee`; UI
|
||||
побайтно не менялся в следующих SHA, но отдельный browser прогон на `1c7ddf2`
|
||||
не выполнялся. Медиана backend `23.685 мс` описательна и не является SLO или
|
||||
доказательством ускорения.
|
||||
|
||||
Эксперимент подключал только три акта в отдельном supplement и не доказывает
|
||||
полноту всего корпуса, актуальность всех редакций, наличие вложений или
|
||||
production-готовность. Отключение overlay/supplement скроет эти новые редакции
|
||||
из локального поиска/API, но сохранит подготовленные файлы, review-записи и
|
||||
исходный индекс. Production не менялся. Подробный технический отчёт и raw
|
||||
benchmark остаются во внешнем рабочем наборе и в PR не включены.
|
||||
|
||||
## Пустые выдачи в лаборатории
|
||||
|
||||
Исходный контракт блокировал сохранение шести подписанных пустых снимков:
|
||||
API отвергал `results: []`, а интерфейс читал поля из пустого placeholder.
|
||||
Теперь signed snapshot может сохранить пустую оценку с обязательным общим
|
||||
комментарием. В записи `top_result_code` остаётся `null`, список результатов
|
||||
пустой. Непустой снимок по-прежнему обязан получить оценку каждого ранга ровно
|
||||
один раз, совпадающую с подписанным кодом документа. HMAC, TTL и текущая
|
||||
аутентификация не меняются.
|
||||
|
||||
Подписанный снимок теперь сохраняет scope запроса при явно настроенном
|
||||
multi-index выражении (`A,B`): provenance не сужается до индекса, который
|
||||
случайно вернул единственный результат, и сохраняется при пустой выдаче. Для
|
||||
одного настроенного индекса или alias остаётся прежнее поведение: единственный
|
||||
concrete `_index` записывается как provenance; если OpenSearch не сообщил его,
|
||||
сохраняется настроенный scope. Новые отзывы получают эту метку при сохранении.
|
||||
SQLite-схема, исторические записи и формат подписанных токенов не меняются.
|
||||
Откат к старому коду не требует миграции и не переписывает существующие
|
||||
отзывы; пока работает откатанная версия, новые multi-index отзывы снова могут
|
||||
получить суженную метку, поэтому исправление provenance следует вернуть вместе
|
||||
с основным выпуском.
|
||||
|
||||
Существующая отдельная база локальной лаборатории содержала 7 494 сохранённых
|
||||
сессии, 79 AI-оценок и 55 516 диагностических комментариев; 74 715
|
||||
оценок результатов остались пустыми намеренно. Integrity check прошёл,
|
||||
порядок кодов и редакций baseline не менялся. Эти сохранённые оценки не
|
||||
переписывались. В последующем изолированном trial шесть реальных подписанных
|
||||
пустых отзывов с общими комментариями были сохранены как записи 7498–7503;
|
||||
итоговые 7 503 строки лаборатории совпали с backup, integrity check прошёл.
|
||||
Пустые query-level отзывы не являются оценками отдельных документов.
|
||||
|
||||
## Пробел актуального корпуса и безопасный контракт закрытия
|
||||
|
||||
Отдельно от ранжирования, в исходном base index не было трёх
|
||||
подтверждённых действующих актов (все три canonical ID имели `_count = 0`):
|
||||
|
||||
| Акт | Canonical ID | Последняя проверенная редакция |
|
||||
|---|---:|---|
|
||||
| Трудовой кодекс КР от 23.01.2025 № 23 | 230021083 | 57548 от 28.07.2026 |
|
||||
| Земельный кодекс КР от 18.07.2025 № 149 | 230029465 | 34746 от 18.07.2025 |
|
||||
| Об охране здоровья граждан КР от 12.01.2024 № 14 | 230000918 | 47553 от 23.01.2026 |
|
||||
|
||||
Это разрыв между нормализованными документами и индексом, а не полное
|
||||
отсутствие актов в локальном архиве: в `data/minjust-normalized` уже есть
|
||||
canonical-каталоги всех трёх документов, manifest сообщает 209 958 успешно
|
||||
обработанных документов. Однако трудовой акт там отстаёт от официальной
|
||||
редакции 57548 от 28.07.2026 (последняя подготовленная — № 60 от 23.06.2026);
|
||||
земельный акт нормализован до редакции № 10 от 18.07.2025; для акта о здоровье
|
||||
последняя подготовленная — № 60 от 23.01.2026. В base index эти три canonical
|
||||
ID не попали. Прежние отменённые трудовой и земельный кодексы нельзя переименовать
|
||||
или поднять как замену актуальным нормам.
|
||||
|
||||
Для локальной изолированной проверки подготовлены точные официальные RU/KY
|
||||
редакции: 3 документа и 8 934 фрагмента. На runtime 8081 они были временно
|
||||
подключены отдельным supplement-index и доступны API через read-only overlay
|
||||
catalogues. Это не изменение base index или production и не доказательство
|
||||
полноты корпуса. Вложения и полная история новых canonical ID отдельно не
|
||||
подтверждены.
|
||||
|
||||
Закрытие пробела требует отдельного контролируемого обновления данных:
|
||||
|
||||
1. Заново сверить официальные canonical ID, статус, edition ID и дату; сохранить
|
||||
исходный ответ, хеши и provenance в отдельном staging-каталоге.
|
||||
2. Проверить полноту обеих языковых версий, ссылки на редакции, историю и
|
||||
вложения; не импортировать метаданные с ненужными персональными полями.
|
||||
3. Нормализовать документы отдельно и проверить exact-count/hash. Для
|
||||
ограниченного дополнения собрать отдельный версионный индекс только из этих
|
||||
актов; не пересобирать и не перезаписывать индекс из 42,6 млн фрагментов.
|
||||
4. Изолированный read-only trial уже проверил отдельный supplement-index,
|
||||
подключённые каталоги `data_root`, RU/KY выдачу, current-edition routes,
|
||||
collapse и контрольные запросы. Перед новым подключением нужно повторно
|
||||
сверить official source и dataset guards; trial не записывал новые документы
|
||||
в base index и не менял alias.
|
||||
5. Публикация требует отдельного владельческого разрешения и проверенного
|
||||
rollback. При отключении локального supplement-index поиск и просмотр новых
|
||||
редакций из него прекращаются; подготовленные файлы и уже сохранённые отзывы
|
||||
сохраняются, базовый индекс не удаляется. PR
|
||||
фиксирует код и результаты локального испытания; production, base index и
|
||||
исходные данные не менялись.
|
||||
|
||||
## Что остаётся проверить
|
||||
|
||||
- Финальный code/data эксперимент и full 7 500 run относятся к executable SHA
|
||||
`1c7ddf2`; текущий follow-up commit меняет только этот report и changelog.
|
||||
CI и полное независимое ревью должны повторно пройти на новом PR head.
|
||||
- Browser fixture пустой выдачи прошёл на `726b1ee`; UI побайтно неизменён в
|
||||
следующих commit. Для `1c7ddf2` выполнены реальные API/runtime smokes, но новый
|
||||
полный browser run не заявляется.
|
||||
- Три supplement-акта не подтверждают полноту всего корпуса, полную историю,
|
||||
вложения, лицензирование или production readiness. Для новой публикации нужен
|
||||
свежий source/edition check и отдельное разрешение владельца.
|
||||
- Измерения top-k, AI-разметка и технические smoke checks не заменяют независимую
|
||||
экспертную оценку юридической релевантности.
|
||||
|
||||
Исходные измерения и хеши хранятся вне репозитория в рабочем наборе
|
||||
`search-benchmark-2026-11-02`. В этот репозиторий не включаются сырые ответы
|
||||
MinJust, диагностические логи, внешние пользовательские данные или выгрузка
|
||||
лабораторных комментариев.
|
||||
@@ -0,0 +1,179 @@
|
||||
# План внутреннего интерфейса оценки поисковой выдачи
|
||||
|
||||
## Цель
|
||||
|
||||
Создать закрытую лабораторию релевантности: юрист оценивает фактическую выдачу
|
||||
нашего OpenSearch по практическим запросам. Цель — улучшать собственное
|
||||
ранжирование, а не воспроизводить алгоритм сайта Минюста КР.
|
||||
|
||||
ЦБД Минюста используется как официальный источник текста, реквизитов, статуса
|
||||
и редакции акта. Порядок результатов и оценка их полезности определяются в
|
||||
нашем сервисе.
|
||||
|
||||
Это внутренний рабочий инструмент, а не публичный frontend MVP. Он не включает
|
||||
регистрацию, личные кабинеты, публичный дизайн, сложные фильтры или сравнение
|
||||
редакций.
|
||||
|
||||
## Сценарий юриста
|
||||
|
||||
1. Указать поисковый запрос и язык.
|
||||
2. Получить первые 10–20 результатов в точном порядке OpenSearch.
|
||||
3. Увидеть позицию каждого результата: `#1`, `#2` и далее.
|
||||
4. Открыть выбранный документ по клику на название в правой панели страницы.
|
||||
5. Поставить каждому просмотренному результату оценку и комментарий.
|
||||
6. Сохранить снимок выдачи и оценок.
|
||||
7. Передать накопленные записи на анализ ранжирования.
|
||||
|
||||
## Оценка результата
|
||||
|
||||
| Балл | Значение |
|
||||
| ---: | --- |
|
||||
| 0 | Нерелевантен: совпали слова, но акт не отвечает на вопрос. |
|
||||
| 1 | Косвенно полезен: относится к теме, но прямого ответа нет. |
|
||||
| 2 | Частично полезен: отвечает не полностью или требует другого акта. |
|
||||
| 3 | Прямо и достаточно отвечает на запрос. |
|
||||
|
||||
Оценка относится к отдельному документу, а не ко всей выдаче. Результат без
|
||||
оценки считается непросмотренным, а не нерелевантным.
|
||||
|
||||
## Интерфейс
|
||||
|
||||
Рекомендуемый экран — две панели.
|
||||
|
||||
- Вверху: поле запроса, переключатель RU/KY, выбор числа результатов и кнопка
|
||||
«Найти».
|
||||
- Слева: карточки результатов в порядке выдачи. Карточка содержит позицию,
|
||||
название, тип, статус, дату, номер и фрагмент текста.
|
||||
- Справа: заголовок, реквизиты, очищенный HTML выбранной редакции и ссылка на
|
||||
официальный источник.
|
||||
- В карточке: кнопки оценки `0`, `1`, `2`, `3` и раскрываемое поле
|
||||
комментария.
|
||||
- Внизу: имя или псевдоним проверяющего, общий комментарий и кнопка
|
||||
«Сохранить оценку».
|
||||
|
||||
Правая панель предпочтительнее popup: она не блокируется браузером, сохраняет
|
||||
контекст выдачи и работает на одном экране с оценкой.
|
||||
|
||||
### Доступность оценки и документа
|
||||
|
||||
Оценка реализуется нативной группой `radio` внутри `fieldset` с `legend`
|
||||
«Оценка результата». У каждого значения есть видимая подпись: «0 —
|
||||
нерелевантен», «1 — косвенно полезен», «2 — частично полезен», «3 — прямо
|
||||
отвечает». Нельзя передавать смысл оценки только цветом. Все элементы управления
|
||||
доступны с клавиатуры, имеют видимый `:focus-visible`; выбранный результат
|
||||
обозначается текстом и визуальным состоянием.
|
||||
|
||||
На узком экране список результатов занимает всю страницу. Кнопка «Открыть
|
||||
документ» открывает полноэкранный нативный `<dialog>` с явной кнопкой
|
||||
«Закрыть». При закрытии фокус возвращается на исходную кнопку «Открыть
|
||||
документ».
|
||||
|
||||
### Состояния
|
||||
|
||||
- Во время поиска и сохранения показывается состояние загрузки; повторная
|
||||
отправка на это время недоступна. Стабильная пустая область `role="status"`
|
||||
в DOM объявляет начало поиска, число результатов и успешное сохранение.
|
||||
- Пустая выдача сообщает: «По запросу „…“ ничего не найдено» и предлагает
|
||||
«Изменить запрос».
|
||||
- Ошибка поиска сообщает причину и предлагает «Повторить поиск»; текст ошибки
|
||||
выводится в `role="alert"`.
|
||||
- Ошибка сохранения сообщает: «Не удалось сохранить. Проверьте подключение и
|
||||
повторите». Черновик остаётся в браузере, текст ошибки выводится в
|
||||
`role="alert"`.
|
||||
- После сохранения выводится: «Оценка сохранена · № … · дата и время» в
|
||||
указанной стабильной области `role="status"`.
|
||||
|
||||
До сохранения черновик хранится в `localStorage`. После успешного сохранения
|
||||
интерфейс показывает ID записи и время сохранения.
|
||||
|
||||
## Backend и хранение
|
||||
|
||||
Использовать существующие endpoint:
|
||||
|
||||
- `GET /search` — получить ранжированный список результатов;
|
||||
- `GET /documents/{code}/editions/{edition}` — получить текст выбранной
|
||||
редакции.
|
||||
|
||||
Добавить два endpoint:
|
||||
|
||||
- `POST /search-reviews` — валидирует и сохраняет оценку;
|
||||
- `GET /search-reviews/export` — отдаёт накопленные записи в JSON.
|
||||
|
||||
Для первой версии достаточно отдельной SQLite-базы. Это стандартная библиотека
|
||||
Python, данные переживают перезапуск и легко выгружаются для анализа. Доступ к
|
||||
интерфейсу и всем endpoint `search-reviews`, включая экспорт, должен быть
|
||||
ограничен локальной сетью/VPN или аутентификацией reverse proxy.
|
||||
|
||||
Одна запись представляет один сохранённый поисковый сеанс:
|
||||
|
||||
| Поле | Назначение |
|
||||
| --- | --- |
|
||||
| `id`, `created_at` | Идентификатор и время сохранения. |
|
||||
| `reviewer` | Имя или псевдоним проверяющего. |
|
||||
| `query`, `language` | Исходный запрос и язык поиска. |
|
||||
| `index_name`, `algorithm_version` | Версия индекса и алгоритма на момент оценки. |
|
||||
| `top_result_code` | Код документа в позиции `#1`. |
|
||||
| `results_json` | Снимок результатов в исходном порядке с оценками и комментариями. |
|
||||
| `overall_comment` | Общий комментарий к выдаче. |
|
||||
|
||||
В `results_json` для каждого результата сохраняются: `rank`, `document_code`,
|
||||
`edition_code`, название, реквизиты, фрагмент, оценка и комментарий. Снимок
|
||||
выдачи обязателен: после изменения алгоритма можно будет восстановить именно
|
||||
тот результат, который видел юрист.
|
||||
|
||||
## Правила сохранения
|
||||
|
||||
- Запрос не пустой, не длиннее 500 символов.
|
||||
- Оценка может быть только целым числом от 0 до 3 либо отсутствовать у
|
||||
непросмотренного результата.
|
||||
- Комментарии имеют ограничение длины; пользовательские значения не вставляются
|
||||
в HTML.
|
||||
- `GET /search` возвращает краткоживущий HMAC-подписанный снимок выдачи:
|
||||
запрос, язык, индекс, результаты и их позиции. `POST /search-reviews`
|
||||
принимает этот снимок и только оценки с комментариями. Сервер проверяет
|
||||
подпись и срок, самостоятельно формирует `results_json` и отклоняет оценки
|
||||
для отсутствующих либо подменённых позиций и документов.
|
||||
- Нельзя передавать персональные данные или закрытые материалы в комментариях.
|
||||
- Кнопка «Сохранить оценку» остаётся доступной до отправки: отсутствующие
|
||||
обязательные поля проверяются после нажатия, ошибка показана рядом с полем и
|
||||
фокус переводится на первое некорректное поле.
|
||||
|
||||
## Анализ данных
|
||||
|
||||
Экспорт должен содержать исходный JSON-снимок, чтобы его можно было обработать
|
||||
скриптом или открыть в табличном инструменте. Первый отчёт строит:
|
||||
|
||||
- среднюю оценку для каждой позиции выдачи;
|
||||
- долю результатов с оценкой `3` в top-1, top-3 и top-10;
|
||||
- запросы, где нет результатов с оценкой `2` или `3`;
|
||||
- документы, которые часто получают низкую оценку в первых позициях;
|
||||
- комментарии для ручного разбора ошибок.
|
||||
|
||||
Сырые оценки не должны автоматически менять веса поиска. Сначала команда
|
||||
разбирает причины: анализатор, синонимы, статус, отсутствие документа,
|
||||
неправильная формулировка запроса или юридическая неоднозначность.
|
||||
|
||||
## Этапы реализации
|
||||
|
||||
1. Утвердить шкалу 0–3, обязательность имени проверяющего и правила доступа.
|
||||
2. Добавить SQLite-хранилище, валидацию, сохранение и JSON-экспорт.
|
||||
3. Добавить статическую внутреннюю страницу в существующий Python-сервер, без
|
||||
Next.js и отдельного публичного приложения.
|
||||
4. Подключить поиск, правую панель документа, черновик, адаптивный режим и
|
||||
сохранение в закреплённой панели действий на широком экране.
|
||||
5. Добавить минимальные backend-проверки сохранения, повторного запуска,
|
||||
экспорта и недопустимых оценок.
|
||||
6. Провести ручный прогон на десяти русскоязычных практических запросах с
|
||||
двумя юристами.
|
||||
7. На собранных записях настроить OpenSearch и повторить тот же набор запросов.
|
||||
|
||||
## Критерий готовности
|
||||
|
||||
Юрист вводит запрос, видит порядок выдачи, открывает документ, выставляет
|
||||
оценки и комментарии, сохраняет их. Экспорт содержит запрос, язык, документ
|
||||
на позиции `#1`, полный порядок результатов, оценки, комментарии и версию
|
||||
индекса. Данные можно сравнить до и после изменения алгоритма.
|
||||
|
||||
---
|
||||
|
||||
Акылдаш · Telegram-бот v0.2.2 · Backend v0.7.1 · Frontend — не создан
|
||||
@@ -0,0 +1,100 @@
|
||||
# Приёмка поискового экрана и лаборатории
|
||||
|
||||
Проверка выполнена 23 октября 2026 года в Chromium 156.0.8078.4, Playwright
|
||||
1.64.1, headless, device scale factor 1. Макеты проверены при 1280×800,
|
||||
1440×900, 1024×900 и 390×844 CSS px; reflow дополнительно проверен при
|
||||
320×800 CSS px. Среда: Ubuntu 26.04 LTS под WSL2 Linux x86_64, Chromium
|
||||
156.0.8078.4 headless, масштаб 100%, device scale factor 1.
|
||||
|
||||
## Снимки
|
||||
|
||||
- [1280×800 — основной экран](desktop-1280x800.png)
|
||||
- [1440 px](desktop-1440px.png)
|
||||
- [1024 px](desktop-1024px.png)
|
||||
- [390 px — мобильный просмотр документа](mobile-390px.png)
|
||||
- [Лаборатория `/review` — подсказка на desktop](review-tour-desktop.png)
|
||||
- [Лаборатория `/review` — подсказка на mobile](review-tour-mobile.png)
|
||||
- [Overlay 50% с приложенным референсом](overlay-50.png)
|
||||
- [Карта абсолютной разницы пикселей](pixel-difference.png)
|
||||
|
||||
Покропленные сравнения областей для отдельного просмотра:
|
||||
|
||||
| Область | Overlay | Разница пикселей |
|
||||
|---|---|---|
|
||||
| Шапка и навигация | [Overlay](region-header-overlay.png) | [Diff](region-header-difference.png) |
|
||||
| Фильтры | [Overlay](region-filters-overlay.png) | [Diff](region-filters-difference.png) |
|
||||
| Результаты | [Overlay](region-results-overlay.png) | [Diff](region-results-difference.png) |
|
||||
| Документ | [Overlay](region-document-overlay.png) | [Diff](region-document-difference.png) |
|
||||
| Footer | [Overlay](region-footer-overlay.png) | [Diff](region-footer-difference.png) |
|
||||
|
||||
## Фактическая проверка
|
||||
|
||||
- Снимок референса 1586×992 пропорционально вписан в 1280×800. Границы
|
||||
крупных зон расходятся с реализацией не более чем на 1 CSS px: колонки
|
||||
x=0/226/648/1280; рабочая область начинается около y=126, заканчивается
|
||||
на y=744; footer — y=744–800.
|
||||
- Вторая строка навигации измерена по макету: поиск x=26–123, «Источники»
|
||||
x=146–245, язык x=285–373, статус x=381–486, начало демо-подписи x=511.
|
||||
Референсная подпись и элементы попадают в эти координаты с расхождением
|
||||
около 1–2 px; у статуса остаётся несколько лишних пикселей по ширине.
|
||||
- Горизонтального переполнения при 1440, 1024 и 390 px нет.
|
||||
- При 320 px также нет горизонтального переполнения.
|
||||
- Загружены Noto Sans и Noto Serif, включая кириллические наборы; повторяющихся
|
||||
HTML id нет, ошибок JavaScript в сценарии не зарегистрировано.
|
||||
- В fixture проверены ответы 200 для SVG и PNG favicon; локализация проверена
|
||||
на фильтрах, результатах, счётчике совпадений и открытом статусе.
|
||||
- Мобильная панель фильтров удерживает фокус в цикле, делает фон inert,
|
||||
показывает 3 px focus ring, закрывается по Escape и возвращает фокус на
|
||||
кнопку открытия.
|
||||
- Playwright проверил сохранение второго фильтра при удалении первого, URL,
|
||||
открытие редакции, поиск по документу
|
||||
(1-е и 2-е совпадения), независимость языка текста от языка интерфейса,
|
||||
отображение поисковых подписей и выбранного статуса на кыргызском,
|
||||
разворачивание документа, действия профиля/пользователей/выхода, мобильную
|
||||
панель и возврат к результатам, изоляцию `/review`, ошибки поиска и редакции,
|
||||
повтор после ошибки и отсутствие доступных редакций.
|
||||
- Проверены print CSS (служебные панели скрыты, документ и официальный источник
|
||||
остаются), горизонтальная прокрутка широкой таблицы и изображения внутри
|
||||
документа без общей прокрутки страницы, длинные названия, `prefers-reduced-motion`,
|
||||
ошибки/повтор после ошибки, состояние без редакций, загрузка и сохранение
|
||||
остальных URL-фильтров при удалении одного.
|
||||
- Для фильтров и открытых `<dialog>` проверены Tab/Shift+Tab, Escape и возврат
|
||||
фокуса. При Tab с последней кнопки в кабинете обнаружено и исправлено
|
||||
выпадение фокуса на `body`; повторный прогон подтверждает цикл внутри диалога.
|
||||
Полный скринридерный аудит этим не заменяется.
|
||||
- Обучающая подсказка `/review` проверена на всех четырёх шагах при 1280×800
|
||||
и 390×844: карточка не шире 320 px, использует Noto Sans/Noto Serif,
|
||||
полупрозрачный фон и располагается у целевого элемента без пересечения.
|
||||
Снимки первого шага сохранены для desktop и mobile.
|
||||
|
||||
Для снимков Playwright перехватывал API и отдавал локальные детерминированные
|
||||
fixture-ответы. Подпись «Демонстрационные данные» добавлялась только в тестовой
|
||||
странице перед снимком. Эти юридические тексты и результаты не входят в код
|
||||
продукта. Для overlay и difference исходный растр 1586×992 вписывается
|
||||
в 1280×800 с сохранением пропорций и полем около 1 px по бокам. В эталоне
|
||||
нет кнопки кабинета; в интерфейсе она сохранена для доступности действий
|
||||
учётной записи и остаётся заметным дополнительным элементом справа во второй
|
||||
строке. Макет показывает язык поиска как удаляемый чип, интерфейс использует
|
||||
доступный select; это функциональное расхождение пока оставлено явно видимым.
|
||||
Содержимое документа, системный формат даты и сглаживание текста также не
|
||||
совпадают попиксельно с концептом.
|
||||
|
||||
## Повторный запуск
|
||||
|
||||
Из корня репозитория выполните `cd tools/frontend-visual-review`, затем
|
||||
`npm ci`, `npx playwright install chromium` и `npm test`. Скрипт читает текущий
|
||||
`backend/search/review.html`, перехватывает API детерминированными fixture-
|
||||
ответами и обновляет перечисленные выше снимки. Overlay и pixel-difference
|
||||
создаются, если найден исходный файл по стандартному пути или передан путь в
|
||||
переменной `REFERENCE_IMAGE`.
|
||||
|
||||
## Оставшиеся визуальные отличия
|
||||
|
||||
Сглаживание текста и содержимое документа отличаются от растрового макета.
|
||||
Поля даты показывают системный формат Chromium. Переключатель языка интерфейса
|
||||
и поле языка поиска остаются разными состояниями; в макете язык показан как
|
||||
удаляемый чип. Дополнительная кнопка кабинета отсутствует в концепте. Не
|
||||
проверялись полный набор ошибок авторизации, скринридер, видимый фокус на каждом
|
||||
шаге, длинные реальные редакции и таблицы из корпуса. Автоматические снимки
|
||||
показывают композицию, но не подтверждают юридическое содержимое или доступность
|
||||
во всех браузерах.
|
||||
|
After Width: | Height: | Size: 128 KiB |
|
After Width: | Height: | Size: 199 KiB |
|
After Width: | Height: | Size: 182 KiB |
|
After Width: | Height: | Size: 201 KiB |
|
After Width: | Height: | Size: 113 KiB |
|
After Width: | Height: | Size: 454 KiB |
|
After Width: | Height: | Size: 311 KiB |
|
After Width: | Height: | Size: 126 KiB |
|
After Width: | Height: | Size: 181 KiB |
|
After Width: | Height: | Size: 44 KiB |
|
After Width: | Height: | Size: 62 KiB |
|
After Width: | Height: | Size: 15 KiB |