feat: add project-scoped operations

.env.example

@@ -1,127 +1,135 @@
-# TJWater Server 环境变量配置模板
-# 复制此文件为 .env 并填写实际值
-# CI/CD: 生产环境变量由 Dev 主机的受控 backend.env 注入，不要将完整 .env 保存为 Gitea 仓库密钥。
-ENVIRONMENT="production"
-NETWORK_NAME="tjwater"
-# ============================================
-# 敏感配置加密 (必填)
-# ============================================
+# TJWater Server 环境变量模板
+# 复制为 .env 后按启用的功能填写；不要提交 .env 或任何真实凭据。
+# 生产配置由部署主机的受控 backend.env 注入，不要把完整配置保存为仓库密钥。
 
-# Fernet 格式，生产环境必须替换为独立密钥
-# 生成方式: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
-# 用于项目数据库 DSN、GeoServer 管理密码等敏感配置
+# 基础运行
+PROJECT_NAME="TJWater Server"
+ENVIRONMENT="production"
+API_V1_STR="/api/v1"
+NETWORK_NAME="tjwater"
+
+# Fernet 格式；用于加密项目数据库 DSN、GeoServer 管理密码等敏感配置。
+# 生成方式：python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
 DATABASE_ENCRYPTION_KEY="replace-with-generated-fernet-key"
 
-# ============================================
-# 数据库配置 (PostgreSQL)
-# ============================================
+# 业务数据库（PostgreSQL）
 DB_NAME="tjwater"
 DB_HOST="localhost"
 DB_PORT="5432"
 DB_USER="tjwater"
 DB_PASSWORD="password"
 
-# ============================================
-# 数据库配置 (TimescaleDB)
-# ============================================
+# 时序数据库（TimescaleDB）
 TIMESCALEDB_DB_NAME="tjwater"
 TIMESCALEDB_DB_HOST="localhost"
 TIMESCALEDB_DB_PORT="5433"
 TIMESCALEDB_DB_USER="tjwater"
 TIMESCALEDB_DB_PASSWORD="password"
-# 实时快照替换事务的解压预算；仅事务内生效，禁止0（无限制）。
+# 实时快照替换事务的解压预算；仅事务内生效，禁止设为 0（无限制）。
 TIMESCALEDB_REALTIME_MAX_DECOMPRESSED_TUPLES=1000000
 
-# ============================================
-# 元数据数据库配置 (Metadata DB)
-# ============================================
+# 元数据数据库
 METADATA_DB_NAME="system_hub"
 METADATA_DB_HOST="localhost"
 METADATA_DB_PORT="5432"
 METADATA_DB_USER="tjwater"
 METADATA_DB_PASSWORD="password"
+METADATA_DB_POOL_SIZE=5
+METADATA_DB_MAX_OVERFLOW=10
 
-# Per-project synchronous connection pools
-PROJECT_PG_CACHE_SIZE="16"
-PROJECT_TS_CACHE_SIZE="16"
-PROJECT_PG_POOL_MIN_SIZE="0"
-PROJECT_PG_POOL_SIZE="4"
-PROJECT_PG_MAX_OVERFLOW="2"
-PROJECT_TS_POOL_MIN_SIZE="0"
-PROJECT_TS_POOL_MAX_SIZE="4"
+# 项目数据库连接池、缓存与模板
+PROJECT_PG_CACHE_SIZE=16
+PROJECT_TS_CACHE_SIZE=16
+PROJECT_PG_POOL_MIN_SIZE=0
+PROJECT_PG_POOL_SIZE=4
+PROJECT_PG_MAX_OVERFLOW=2
+PROJECT_TS_POOL_MIN_SIZE=0
+PROJECT_TS_POOL_MAX_SIZE=4
 WNDB_SCHEMA_TEMPLATE_DB_NAME="tjwater_v2_schema_template"
 TIMESCALEDB_SCHEMA_TEMPLATE_DB_NAME="tjwater_v2_timescale_template"
-WNDB_TEMP_DB_MAX_COUNT="8"
+WNDB_TEMP_DB_MAX_COUNT=8
 
-# ============================================
 # GeoServer 项目供应
-# ============================================
 GEOSERVER_URL="http://localhost:8080/geoserver"
 GEOSERVER_USERNAME="admin"
 GEOSERVER_PASSWORD="password"
-# 留空时分别复用 DB_HOST / DB_PORT / DB_USER / DB_PASSWORD。
+# 留空时分别复用 DB_HOST、DB_PORT、DB_USER、DB_PASSWORD。
 # GeoServer 在容器内运行时，GEOSERVER_DB_HOST 通常应填写数据库服务名。
 GEOSERVER_DB_HOST=""
 GEOSERVER_DB_PORT=""
 GEOSERVER_DB_USER=""
 GEOSERVER_DB_PASSWORD=""
-# 30 天客户端缓存，单位为秒。
-GEOSERVER_CLIENT_CACHE_SECONDS="2592000"
+# 客户端缓存时间，单位为秒；默认 30 天。
+GEOSERVER_CLIENT_CACHE_SECONDS=2592000
 
-# ============================================
-# Keycloak JWT (可选)
-# ============================================
-KEYCLOAK_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
-KEYCLOAK_ALGORITHM=RS256
+# Keycloak JWT 校验
+# 未启用认证时可留空；生产环境应注入完整公钥和预期 audience。
+KEYCLOAK_PUBLIC_KEY=""
+KEYCLOAK_ALGORITHM="RS256"
 KEYCLOAK_AUDIENCE="account"
 KEYCLOAK_ACCESS_TOKEN_MAX_AGE_SECONDS=900
 
-# ============================================
-# 工作台事件同步
-# ============================================
+# 工作台事件与跨域
 # 认证接口必须使用明确来源，逗号分隔；不要配置为 *。
-CORS_ALLOWED_ORIGINS="http://127.0.0.1:5173,http://localhost:5173"
+CORS_ALLOWED_ORIGINS="http://127.0.0.1:5173,http://localhost:5173,http://127.0.0.1:15173,http://localhost:15173"
 WORKBENCH_EVENTS_ENABLED=true
 WORKBENCH_EVENT_RETENTION_DAYS=7
 
-# 每个项目启动一个 worker 实例。长期运行优先使用 OAuth 客户端凭据。
+# 天地图服务
+# 地理编码、逆地理编码和地名搜索共用同一令牌。
+TIANDITU_TOKEN=""
+TIANDITU_GEOCODER_URL="https://api.tianditu.gov.cn/geocoder"
+TIANDITU_GEOCODER_TIMEOUT_SECONDS=30
+TIANDITU_SEARCH_URL="https://api.tianditu.gov.cn/v2/search"
+TIANDITU_SEARCH_TIMEOUT_SECONDS=15
+
+# 调查任务 worker（独立进程）
+# 单项目填写 PROJECT_ID；多项目填写逗号分隔的 PROJECT_IDS，后者优先。
+# worker 与外围工单同步器共用项目范围，服务身份必须拥有每个项目的权限。
 OPERATIONAL_WORKER_PROJECT_ID=""
+OPERATIONAL_WORKER_PROJECT_IDS=""
 OPERATIONAL_WORKER_SERVER_URL="http://127.0.0.1:8000"
 OPERATIONAL_WORKER_AGENT_URL="http://127.0.0.1:8787"
 OPERATIONAL_WORKER_RECONCILE_SECONDS=30
 OPERATIONAL_WORKER_MAX_CONCURRENCY=4
+# 可选 ISO 8601 时间下界，必须包含时区，例如 2026-10-01T00:00:00+08:00。
+OPERATIONAL_WORKER_TASK_CREATED_FROM=""
+
+# 长期运行使用 OAuth 客户端凭据；固定 Bearer 仅用于受控开发或短期运行。
 OPERATIONAL_WORKER_TOKEN_URL=""
+# 仅 ENVIRONMENT=development 时覆盖 TOKEN_URL，其他环境忽略。
+OPERATIONAL_WORKER_DEV_TOKEN_URL=""
 OPERATIONAL_WORKER_CLIENT_ID=""
 OPERATIONAL_WORKER_CLIENT_SECRET=""
 OPERATIONAL_WORKER_TOKEN_REFRESH_SECONDS=300
+OPERATIONAL_WORKER_BEARER=""
+
+# 调查数据适配器
+OPERATIONAL_DATA_SERVER_URL="http://127.0.0.1:8000"
+OPERATIONAL_DATA_PERIPHERAL_URL=""
+OPERATIONAL_DATA_TIMEOUT_SECONDS=15
+# 仅供 Server 在已批准的兼容委托路径中使用，不传给 Agent。
 OPERATIONAL_DATA_DELEGATION_BEARER=""
 
+# 调查动作适配器
+OPERATIONAL_ACTION_PERIPHERAL_URL=""
+OPERATIONAL_ACTION_COMMAND_GATEWAY_URL=""
+OPERATIONAL_ACTION_TIMEOUT_SECONDS=10
 
-# ============================================
-# Tianditu shared API key and service URLs
-# ============================================
-TIANDITU_TOKEN="your-tianditu-token"
-TIANDITU_GEOCODER_URL="https://api.tianditu.gov.cn/geocoder"
-TIANDITU_GEOCODER_TIMEOUT_SECONDS=30
-
-# 地名搜索与地理编码共用 TIANDITU_TOKEN；也可沿用 TJWATER_TIANDITU_TOKEN。
-TIANDITU_SEARCH_URL="https://api.tianditu.gov.cn/v2/search"
-TIANDITU_SEARCH_TIMEOUT_SECONDS=15
-
-# MCP query resource, off until OAuth and every project BizDB are provisioned.
-# 仅 ENVIRONMENT=development 时覆盖 worker 取令牌地址；留空沿用 OPERATIONAL_WORKER_TOKEN_URL。
-OPERATIONAL_WORKER_DEV_TOKEN_URL=
+# MCP 查询服务；OAuth 和所有项目业务库就绪前保持关闭。
 TJWATER_MCP_ENABLED=false
-TJWATER_MCP_ISSUER_URI=
-# 仅 ENVIRONMENT=development，可填写与 issuer 完全相同的内网 HTTP IPv4 issuer。
-# 正式环境必须留空；此例外不放行远程 HTTP MCP resource。
-TJWATER_MCP_DEV_HTTP_ISSUER_URI=
-TJWATER_MCP_RESOURCE_URI=
-TJWATER_MCP_AUDIENCE=tjwater-mcp
-TJWATER_MCP_HOST_CLIENT_ID=tjwater-agent-mcp
-TJWATER_MCP_ALLOWED_HOSTS=["localhost:*","127.0.0.1:*"]
-TJWATER_MCP_ALLOWED_ORIGINS=[]
-# 普通查询预算；计算工具由 Agent 用 timeout_seconds 按次指定（默认120秒）。
+TJWATER_MCP_ISSUER_URI=""
+# 仅 ENVIRONMENT=development：可与 ISSUER_URI 同值并指向内网 HTTP IPv4 issuer。
+# 正式环境必须留空；该例外不允许远程 HTTP MCP resource。
+TJWATER_MCP_DEV_HTTP_ISSUER_URI=""
+TJWATER_MCP_RESOURCE_URI=""
+TJWATER_MCP_AUDIENCE="tjwater-mcp"
+TJWATER_MCP_HOST_CLIENT_ID="tjwater-agent-mcp"
+# 列表使用 JSON 格式。
+TJWATER_MCP_ALLOWED_HOSTS='["127.0.0.1:*","localhost:*"]'
+TJWATER_MCP_ALLOWED_ORIGINS='[]'
+TJWATER_MCP_CONTEXT_TTL_SECONDS=600
+# 普通查询预算；计算工具由 Agent 通过 timeout_seconds 按次指定。
 TJWATER_MCP_QUERY_TIMEOUT_SECONDS=30
-# 计算等待上限，默认1小时；管理员可配置120至86400秒，实际上限通过 tools/list 发布。
+# 计算等待上限为 120–86400 秒，实际上限通过 tools/list 发布。
 TJWATER_MCP_MAX_CALCULATION_TIMEOUT_SECONDS=3600