diff --git a/CHANGELOG.md b/CHANGELOG.md index 60834b2..eef0015 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -76,6 +76,22 @@ > `0.1.12`),由 `scripts/version.py` 从 git **算出来**;开发交付的独立说明写入本文件“开发快照”章节,并打 `snapshot/vX.Y.Z` 注释标签 ⇒ 每次开发交付均可追溯, > 但"发布版本"仍然只能由人定(CI 不会自动升版本、不会打 tag)。 +## 开发快照 snapshot/v0.1.31 - 2026-10-18 + +### Added + +- 区域配置支持新增、改名业务区域;稳定区域 ID 与部门映射同版本保存,改名不丢失归属。部门按一级、二级、三级及更深层级展示,支持层级/完整路径筛选、多选及批量归属。 +- 勾选、批量应用、预览和保存分离;取消本次勾选不删除既有映射,批量配置父部门不清除未选子部门的显式规则。预览核对去重人数,保存后独立读取并校验配置版本。 + +### Changed + +- 新增治理库迁移 51,为历史区域修订补齐原四区目录;业务目录与映射原子留档,跨页问答、看板、使用统计、个人月明细和周报共用同一版本及名称。旧请求未传目录时沿用当前目录,不恢复固定四区白名单。 +- 迁移回退发现自定义区域历史时拒绝丢失目录;应用回退可保留加列迁移。统计人数不升级为在职或绩效分母,不改钉钉组织、DobotAI 原始数据及旧 Excel 流程。 + +### Security + +- 配置请求拒绝缺失版本、重复 JSON 字段及嵌套 null;区域目录校验稳定 ID、重名及保留键,名称按文本展示,自定义名称不读取原型属性。保留管理员同源写入、租户隔离和双版本冲突保护。 + ## 开发快照 snapshot/v0.1.30 - 2026-10-18 ### Changed diff --git a/api/openapi.yaml b/api/openapi.yaml index e080bf8..c1fa454 100644 --- a/api/openapi.yaml +++ b/api/openapi.yaml @@ -69,7 +69,7 @@ "operationId": "previewQAOrganizationRegions", "summary": "预览当前通讯录版本下的父子部门区域归属和去重人数,不保存修改", "parameters": [{"name":"X-Governance-Action","in":"header","required":true,"schema":{"const":"qa-organization"}}], - "requestBody": {"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["directory_id","base_revision","rules"],"properties":{"directory_id":{"type":"string"},"base_revision":{"type":"string"},"rules":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["department_id","region"],"properties":{"department_id":{"type":"string"},"region":{"enum":["国内工业","APAC","EMEA","America"]}}}}}}}}}, + "requestBody": {"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["directory_id","base_revision","rules"],"properties":{"directory_id":{"type":"string"},"base_revision":{"type":"string"},"regions":{"type":"array","maxItems":100,"description":"可选业务区域目录;缺省沿用当前目录,空数组表示无区域;ID稳定不随名称改动。与rules同一版本原子预览/保存。","items":{"type":"object","additionalProperties":false,"required":["id","name"],"properties":{"id":{"type":"string","minLength":1,"maxLength":256},"name":{"type":"string","minLength":1,"maxLength":256}}}},"rules":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["department_id","region"],"properties":{"department_id":{"type":"string"},"region":{"type":"string","description":"目录中稳定的区域ID,不是固定四区枚举"}}}}}}}}}, "responses": { "200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, @@ -99,7 +99,7 @@ } } }, - "/api/v1/qa-ops/usage/people": {"post": {"tags": ["QA operations"], "operationId": "queryQAOperationsMonthlyPeople", "summary": "按北京时间自然月列出当前名册人员的2.0用量(含零记录),仅管理员,不返回原始员工标识,不作为在职/考核名单", "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "完整名册缺失或目录/区域版本变化,请同步/重新查询,不返回伪零"}}, "description": "只读查询,不写治理库或生产库;姓名筛选置于 JSON 请求体,不进入 URL;整名册指标不随人员筛选变化。第2页起须带首页目录、区域版本及 end 截止。", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["month"], "properties": {"month": {"type": "string", "pattern": "^(?!0000)[0-9]{4}-(0[1-9]|1[0-2])$"}, "cutoff": {"type": "string", "format": "date-time"}, "region": {"type": "string", "enum": ["国内工业", "APAC", "EMEA", "America", "unassigned", "cross_region"]}, "department_id": {"type": "string"}, "activity": {"type": "string", "enum": ["all", "used", "zero"]}, "search": {"type": "string", "maxLength": 100}, "page": {"type": "integer", "minimum": 1, "maximum": 100000, "default": 1}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 30}, "directory_id": {"type": "string"}, "revision_id": {"type": "string"}}}}}}, "parameters": [{"name": "X-Governance-Action", "in": "header", "required": true, "schema": {"type": "string", "enum": ["qa-usage-read"]}}]}}, + "/api/v1/qa-ops/usage/people": {"post": {"tags": ["QA operations"], "operationId": "queryQAOperationsMonthlyPeople", "summary": "按北京时间自然月列出当前名册人员的2.0用量(含零记录),仅管理员,不返回原始员工标识,不作为在职/考核名单", "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "完整名册缺失或目录/区域版本变化,请同步/重新查询,不返回伪零"}}, "description": "只读查询,不写治理库或生产库;姓名筛选置于 JSON 请求体,不进入 URL;整名册指标不随人员筛选变化。第2页起须带首页目录、区域版本及 end 截止。", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["month"], "properties": {"month": {"type": "string", "pattern": "^(?!0000)[0-9]{4}-(0[1-9]|1[0-2])$"}, "cutoff": {"type": "string", "format": "date-time"}, "region": {"type": "string", "description": "当前组织版本中的区域显示名称,或unassigned/cross_region;无效名称拒绝查询"}, "department_id": {"type": "string"}, "activity": {"type": "string", "enum": ["all", "used", "zero"]}, "search": {"type": "string", "maxLength": 100}, "page": {"type": "integer", "minimum": 1, "maximum": 100000, "default": 1}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 30}, "directory_id": {"type": "string"}, "revision_id": {"type": "string"}}}}}}, "parameters": [{"name": "X-Governance-Action", "in": "header", "required": true, "schema": {"type": "string", "enum": ["qa-usage-read"]}}]}}, "/api/v1/qa-ops/usage": {"get": {"tags": ["QA operations"], "operationId": "getQAOperationsUsage", "summary": "完整筛选范围内按当前通讯录和区域版本回看2.0问答使用;固定租户、管理员访问,不输出绩效结论", "parameters": [{"name": "start", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}}, {"name": "end", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}}, {"name": "keyword", "in": "query", "schema": {"type": "string", "maxLength": 200}}], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/api/v1/qa-ops/quality/query": {"post": {"operationId": "queryQAQualityCounts", "summary": "按完整筛选范围读取指纹/规则元数据并留档统计,最多5000条;summary.rates 返回 quality-rates-human-first-v1、原始分子/分母、百分比与分母构成。覆盖率=covered/(covered+uncovered+partial),正确率=covered_correct/(covered_correct+covered_incorrect);失效/不计入/相应待确认与未评估排除,零分母percent=null。原文仅在读取问答/复核时采集", "parameters": [{"name": "X-Governance-Action", "in": "header", "required": true, "schema": {"type": "string", "enum": ["qa-quality"]}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "properties": {"start": {"type": "string", "format": "date-time"}, "end": {"type": "string", "format": "date-time"}, "keyword": {"type": "string", "maxLength": 200}}, "required": ["start", "end"]}}}}, "tags": ["QA operations"], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "输入或复核版本变化/重复操作载荷不一致,未覆盖原结论"}, "404": {"description": "当前授权范围内未找到记录/历史输入"}}}}, "/api/v1/qa-ops/records/{id}/reviews": {"post": {"operationId": "saveQAQualityReview", "summary": "治理库追加人工复核,登录身份审计,源端只读,输入/复核乐观锁和nonce幂等;正确时根因为空,不计入须说明原因", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "X-Governance-Action", "in": "header", "required": true, "schema": {"type": "string", "enum": ["qa-quality"]}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "properties": {"input_hash": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "input_epoch": {"type": "integer", "minimum": 1}, "base_revision": {"type": "integer", "minimum": 0}, "nonce": {"type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$"}, "fields": {"type": "object", "additionalProperties": false, "properties": {"coverage": {"type": "string", "enum": ["covered", "uncovered", "partial", "pending", "excluded"]}, "correctness": {"type": "string", "enum": ["correct", "incorrect", "pending"]}, "product_category": {"type": "string", "maxLength": 128}, "problem_type": {"type": "string", "maxLength": 128}, "root_cause": {"type": "string", "maxLength": 2000}, "exclusion_reason": {"type": "string", "maxLength": 2000}}, "required": ["coverage", "correctness"]}, "reason": {"type": "string", "minLength": 1, "maxLength": 4000}}, "required": ["input_hash", "input_epoch", "base_revision", "nonce", "fields", "reason"]}}}}, "tags": ["QA operations"], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "输入或复核版本变化/重复操作载荷不一致,未覆盖原结论"}, "404": {"description": "当前授权范围内未找到记录/历史输入"}}}}, diff --git a/internal/dobotaiops/organization_records.go b/internal/dobotaiops/organization_records.go index 8efdf74..41148d5 100644 --- a/internal/dobotaiops/organization_records.go +++ b/internal/dobotaiops/organization_records.go @@ -13,6 +13,7 @@ type ActorIdentity struct { UnionID string `json:"union_id"` } type OrganizationVersion struct { + RegionNames []string `json:"region_names"` State string `json:"state"` DirectoryID string `json:"directory_id"` DirectorySource string `json:"directory_source"` diff --git a/internal/httpapi/qa_attribution.go b/internal/httpapi/qa_attribution.go index 7aa967b..bd6de27 100644 --- a/internal/httpapi/qa_attribution.go +++ b/internal/httpapi/qa_attribution.go @@ -31,7 +31,7 @@ func recordAttribution(ctx context.Context, config Config) (*qaopsorg.Attributio return p, nil } func attributionVersion(p *qaopsorg.Attribution) dobotaiops.OrganizationVersion { - return dobotaiops.OrganizationVersion{State: p.Metadata.State, DirectoryID: p.Metadata.DirectoryID, DirectorySource: p.Metadata.DirectorySource, SyncedAt: p.Metadata.DirectorySyncedAt, RevisionID: p.Metadata.RevisionID, Basis: "current_directory"} + return dobotaiops.OrganizationVersion{State: p.Metadata.State, DirectoryID: p.Metadata.DirectoryID, DirectorySource: p.Metadata.DirectorySource, SyncedAt: p.Metadata.DirectorySyncedAt, RevisionID: p.Metadata.RevisionID, Basis: "current_directory", RegionNames: p.Metadata.RegionLabels()} } func enrichQARecord(item *dobotaiops.Record, p *qaopsorg.Attribution) { person := p.Resolve(item.Identity.StaffID, item.Identity.UnionID) @@ -92,7 +92,7 @@ type qaUsage struct { func summarizeQAUsage(groups dobotaiops.UsageGroups, p *qaopsorg.Attribution, query dobotaiops.RecordQuery) qaUsage { result := qaUsage{Organization: attributionVersion(p), AsOf: groups.AsOf, Start: query.Window.Start, End: query.Window.End, Keyword: query.Keyword, Rows: []qaUsageRow{}} - keys := append(append([]string{}, qaopsorg.RegionNames...), "unassigned", "cross_region", "unmatched", "identity_conflict", "no_identity", "directory_missing") + keys := append(append([]string{}, p.Metadata.RegionLabels()...), "unassigned", "cross_region", "unmatched", "identity_conflict", "no_identity", "directory_missing") rows := map[string]*qaUsageRow{} members := map[string]map[string]bool{} all := map[string]bool{} @@ -108,7 +108,12 @@ func summarizeQAUsage(groups dobotaiops.UsageGroups, p *qaopsorg.Attribution, qu n = p.Metadata.View.ConflictingPeople default: var ok bool - n, ok = p.Metadata.View.Regions[key] + for _, region := range p.Metadata.RegionDefinitions() { + if region.Name == key { + n, ok = p.Metadata.View.Regions[region.ID] + break + } + } valid = ok } if valid { diff --git a/internal/httpapi/qa_monthly.go b/internal/httpapi/qa_monthly.go index 825e3e6..1917285 100644 --- a/internal/httpapi/qa_monthly.go +++ b/internal/httpapi/qa_monthly.go @@ -97,11 +97,7 @@ func parseMonthlyFilter(values url.Values, now time.Time) (monthlyFilter, error) if f.Activity != "all" && f.Activity != "used" && f.Activity != "zero" { return f, dobotaiops.ErrInvalidQuery } - validRegion := f.Region == "" || f.Region == "unassigned" || f.Region == "cross_region" - for _, r := range qaopsorg.RegionNames { - validRegion = validRegion || f.Region == r - } - if !validRegion { + if !utf8.ValidString(f.Region) || len(f.Region) > 256 || strings.TrimSpace(f.Region) != f.Region || strings.ContainsAny(f.Region, "\x00\r\n") { return f, dobotaiops.ErrInvalidQuery } if !utf8.ValidString(f.Search) || utf8.RuneCountInString(f.Search) > 100 || strings.ContainsRune(f.Search, 0) { @@ -288,6 +284,16 @@ func qaMonthlyPeople(w http.ResponseWriter, r *http.Request, config Config) { return } } + if f.Region != "" && f.Region != "unassigned" && f.Region != "cross_region" { + found := false + for _, name := range p.Metadata.RegionLabels() { + found = found || f.Region == name + } + if !found { + qaOpsError(w, dobotaiops.ErrInvalidQuery) + return + } + } if f.Department != "" { found := false for _, d := range p.Metadata.View.Departments { diff --git a/internal/httpapi/qa_org.go b/internal/httpapi/qa_org.go index f1ff249..c9649c6 100644 --- a/internal/httpapi/qa_org.go +++ b/internal/httpapi/qa_org.go @@ -1,6 +1,7 @@ package httpapi import ( + "bytes" "context" "encoding/json" "errors" @@ -36,9 +37,14 @@ func qaOrganization(w http.ResponseWriter, r *http.Request, config Config) { return } var request qaopsorg.SaveRequest - decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20)) + raw, readErr := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20)) + check := json.NewDecoder(bytes.NewReader(raw)) + var fields map[string]json.RawMessage + var extra any + invalidJSON := readErr != nil || json.Unmarshal(raw, &fields) != nil || fields == nil || fields["base_revision"] == nil || walkQualityJSON(check) != nil || check.Decode(&extra) != io.EOF + decoder := json.NewDecoder(bytes.NewReader(raw)) decoder.DisallowUnknownFields() - if decoder.Decode(&request) != nil || decoder.Decode(&struct{}{}) != io.EOF || request.DirectoryID == "" || request.Rules == nil { + if invalidJSON || decoder.Decode(&request) != nil || decoder.Decode(&extra) != io.EOF || request.DirectoryID == "" || request.Rules == nil { writeOrgError(w, qaopsorg.ErrInvalid) return } diff --git a/internal/httpapi/qa_org_test.go b/internal/httpapi/qa_org_test.go index 882c9be..e6e4ce5 100644 --- a/internal/httpapi/qa_org_test.go +++ b/internal/httpapi/qa_org_test.go @@ -52,6 +52,12 @@ func TestQAOrganizationGuardsIdentityIntentAndErrors(t *testing.T) { {"PUT", base + "/regions", "org-admin", "qa-organization", "", `{} {}`, 400}, {"PUT", base + "/regions", "org-admin", "qa-organization", "", `{}`, 400}, {"PUT", base + "/regions", "org-admin", "qa-organization", "", `{"directory_id":"d","base_revision":"","rules":null}`, 400}, + {"PUT", base + "/regions", "org-admin", "qa-organization", "", `{"directory_id":"d","rules":[]}`, 400}, + {"PUT", base + "/regions", "org-admin", "qa-organization", "", `{"directory_id":"d","base_revision":"","regions":null,"rules":[]}`, 400}, + {"PUT", base + "/regions", "org-admin", "qa-organization", "", `{"directory_id":"d","base_revision":"","regions":[null],"rules":[]}`, 400}, + {"PUT", base + "/regions", "org-admin", "qa-organization", "", `{"directory_id":"d","base_revision":"","regions":[{"id":"edu","name":null}],"rules":[]}`, 400}, + {"PUT", base + "/regions", "org-admin", "qa-organization", "", `{"directory_id":"d","base_revision":"","rules":[],"rules":[]}`, 400}, + {"PUT", base + "/regions", "org-admin", "qa-organization", "", `{"directory_id":"d","base_revision":"","rules":[]}`, 200}, {"POST", base + "/preview", "org-admin", "qa-organization", "", `{"directory_id":"d","base_revision":"","rules":[]}`, 200}, } { diff --git a/internal/httpapi/qa_region_catalog_test.go b/internal/httpapi/qa_region_catalog_test.go new file mode 100644 index 0000000..204eb7f --- /dev/null +++ b/internal/httpapi/qa_region_catalog_test.go @@ -0,0 +1,30 @@ +package httpapi + +import ( + "knowledge-governance/internal/dobotaiops" + "knowledge-governance/internal/qaopsorg" + "testing" +) + +func TestQAUsageConsumesTheCustomRegionCatalog(t *testing.T) { + p, err := qaopsorg.BuildAttribution(qaopsorg.State{State: "ready", DirectoryID: "fixture-directory", Regions: []qaopsorg.RegionDefinition{{ID: "edu", Name: "国内教育"}}, Rules: []qaopsorg.Rule{{DepartmentID: "a", Region: "edu"}}}, qaopsorg.Directory{Departments: []qaopsorg.Department{{ID: "a", Name: "示例部门"}}, People: []qaopsorg.Person{{ID: "fixture-person", DepartmentIDs: []string{"a"}}}}) + if err != nil { + t.Fatal(err) + } + usage := summarizeQAUsage(dobotaiops.UsageGroups{Groups: []dobotaiops.UsageGroup{{Identity: dobotaiops.ActorIdentity{StaffID: "fixture-person"}, Total: 3, Succeeded: 2, Failed: 1}}}, p, dobotaiops.RecordQuery{}) + if usage.Questions != 3 || usage.IdentifiedUsers != 1 { + t.Fatal("the historical whitelist dropped custom-region events") + } + found := false + for _, row := range usage.Rows { + if row.Key == "国内教育" { + found = true + if row.Questions != 3 || row.RosterPeople == nil || *row.RosterPeople != 1 || row.Users == nil || *row.Users != 1 { + t.Fatal("custom-region counts or roster denominator were lost") + } + } + } + if !found { + t.Fatal("custom-region row missing") + } +} diff --git a/internal/platform/postgres/migrations/000051_qa_ops_region_catalog.down.sql b/internal/platform/postgres/migrations/000051_qa_ops_region_catalog.down.sql new file mode 100644 index 0000000..bdf22e6 --- /dev/null +++ b/internal/platform/postgres/migrations/000051_qa_ops_region_catalog.down.sql @@ -0,0 +1,6 @@ +DO $$ BEGIN + IF EXISTS (SELECT 1 FROM qa_ops_region_revisions WHERE region_definitions <> '[{"id":"国内工业","name":"国内工业"},{"id":"APAC","name":"APAC"},{"id":"EMEA","name":"EMEA"},{"id":"America","name":"America"}]'::jsonb) THEN + RAISE EXCEPTION 'custom region catalog exists; application rollback may keep migration 51, destructive catalog rollback refused'; + END IF; +END $$; +ALTER TABLE qa_ops_region_revisions DROP COLUMN region_definitions; diff --git a/internal/platform/postgres/migrations/000051_qa_ops_region_catalog.up.sql b/internal/platform/postgres/migrations/000051_qa_ops_region_catalog.up.sql new file mode 100644 index 0000000..91c54d1 --- /dev/null +++ b/internal/platform/postgres/migrations/000051_qa_ops_region_catalog.up.sql @@ -0,0 +1 @@ +ALTER TABLE qa_ops_region_revisions ADD COLUMN region_definitions JSONB NOT NULL DEFAULT '[{"id":"国内工业","name":"国内工业"},{"id":"APAC","name":"APAC"},{"id":"EMEA","name":"EMEA"},{"id":"America","name":"America"}]'::jsonb CHECK (jsonb_typeof(region_definitions)='array'); diff --git a/internal/platform/postgres/migrations_test.go b/internal/platform/postgres/migrations_test.go index 773313f..6ade4f8 100644 --- a/internal/platform/postgres/migrations_test.go +++ b/internal/platform/postgres/migrations_test.go @@ -11,8 +11,8 @@ func TestEmbeddedMigrationsAreVersionSorted(t *testing.T) { if err != nil { t.Fatalf("loadMigrations() error = %v", err) } - if len(migrations) != 50 { - t.Fatalf("migration count = %d, want 50", len(migrations)) + if len(migrations) != 51 { + t.Fatalf("migration count = %d, want 51", len(migrations)) } if migrations[0].Version != 1 || !strings.Contains(migrations[0].UpSQL, "CREATE TABLE IF NOT EXISTS jobs") { t.Fatalf("migration 1 = %#v", migrations[0]) diff --git a/internal/platform/postgres/qa_region_catalog_migration_test.go b/internal/platform/postgres/qa_region_catalog_migration_test.go new file mode 100644 index 0000000..389b0d0 --- /dev/null +++ b/internal/platform/postgres/qa_region_catalog_migration_test.go @@ -0,0 +1,28 @@ +package postgres + +import ( + "strings" + "testing" +) + +func TestRegionCatalogMigrationIsAdditiveAndRefusesLossyDown(t *testing.T) { + migrations, e := loadMigrations() + if e != nil { + t.Fatal(e) + } + var up, down string + for _, m := range migrations { + if m.Version == 51 { + up = m.UpSQL + down = m.DownSQL + } + } + for _, fragment := range []string{"ADD COLUMN region_definitions JSONB NOT NULL DEFAULT", "jsonb_typeof(region_definitions)='array'", "国内工业", "APAC", "EMEA", "America"} { + if !strings.Contains(up, fragment) { + t.Fatal("missing additive/backfill region contract", fragment) + } + } + if !strings.Contains(down, "RAISE EXCEPTION") || !strings.Contains(down, "region_definitions <>") || !strings.Contains(down, "DROP COLUMN region_definitions") { + t.Fatal("lossy down migration was not guarded") + } +} diff --git a/internal/qaopsorg/attribution.go b/internal/qaopsorg/attribution.go index bbf8852..196a3d1 100644 --- a/internal/qaopsorg/attribution.go +++ b/internal/qaopsorg/attribution.go @@ -39,7 +39,7 @@ func BuildAttribution(state State, directory Directory) (*Attribution, error) { if state.State != "ready" || state.DirectoryID == "" { return nil, ErrUnavailable } - view, err := Preview(directory, state.Rules) + view, err := PreviewRegions(directory, state.Rules, state.RegionDefinitions()) if err != nil { return nil, ErrUnavailable } @@ -65,7 +65,7 @@ func BuildAttribution(state State, directory Directory) (*Attribution, error) { if len(regions) == 1 { item.State = "matched" for region := range regions { - item.Region = region + item.Region = state.RegionLabel(region) } } else if len(regions) > 1 { item.State = "cross_region" diff --git a/internal/qaopsorg/catalog.go b/internal/qaopsorg/catalog.go new file mode 100644 index 0000000..3553db5 --- /dev/null +++ b/internal/qaopsorg/catalog.go @@ -0,0 +1,54 @@ +package qaopsorg + +import "unicode/utf8" + +// IDs are immutable mapping keys; names are editable labels. Existing keys remain +// intact when migrating the historical four-region configuration. +type RegionDefinition struct { + ID string `json:"id"` + Name string `json:"name"` +} + +func DefaultRegions() []RegionDefinition { + result := make([]RegionDefinition, 0, len(RegionNames)) + for _, name := range RegionNames { + result = append(result, RegionDefinition{ID: name, Name: name}) + } + return result +} +func (s State) RegionDefinitions() []RegionDefinition { + if s.Regions == nil { + return DefaultRegions() + } + return s.Regions +} +func (s State) RegionLabels() []string { + labels := []string{} + for _, region := range s.RegionDefinitions() { + labels = append(labels, region.Name) + } + return labels +} +func (s State) RegionLabel(id string) string { + for _, region := range s.RegionDefinitions() { + if region.ID == id { + return region.Name + } + } + return "" +} +func validRegions(regions []RegionDefinition) bool { + if len(regions) > 100 { + return false + } + reserved := map[string]bool{"unassigned": true, "cross_region": true, "unmatched": true, "identity_conflict": true, "no_identity": true, "directory_missing": true, "__proto__": true, "constructor": true, "prototype": true} + ids, names := map[string]bool{}, map[string]bool{} + for _, region := range regions { + if !validID(region.ID) || !validID(region.Name) || !utf8.ValidString(region.ID) || !utf8.ValidString(region.Name) || reserved[region.ID] || reserved[region.Name] || ids[region.ID] || names[region.Name] { + return false + } + ids[region.ID] = true + names[region.Name] = true + } + return true +} diff --git a/internal/qaopsorg/catalog_test.go b/internal/qaopsorg/catalog_test.go new file mode 100644 index 0000000..eca5b20 --- /dev/null +++ b/internal/qaopsorg/catalog_test.go @@ -0,0 +1,57 @@ +package qaopsorg + +import ( + "encoding/json" + "testing" +) + +func TestCustomRegionCatalogRejectsAmbiguousOrReservedDefinitions(t *testing.T) { + for _, regions := range [][]RegionDefinition{ + {{ID: "one", Name: "国内教育"}, {ID: "one", Name: "国外工业Amercia"}}, + {{ID: "one", Name: "国内教育"}, {ID: "two", Name: "国内教育"}}, + {{ID: "unassigned", Name: "区域"}}, {{ID: "one", Name: "cross_region"}}, + {{ID: "__proto__", Name: "区域"}}, {{ID: "one", Name: "constructor"}}, + {{ID: "one", Name: ""}}, {{ID: "one", Name: " 区域"}}, + } { + if _, err := PreviewRegions(exampleDirectory(), nil, regions); err == nil { + t.Fatal("invalid region catalog was accepted") + } + } + if _, err := PreviewRegions(exampleDirectory(), []Rule{{DepartmentID: "sales", Region: "missing"}}, []RegionDefinition{{ID: "education", Name: "国内教育"}}); err == nil { + t.Fatal("unknown mapping ID accepted") + } +} + +func TestCustomRegionCatalogBindsStableIDAndRenamePreservesRules(t *testing.T) { + directory := exampleDirectory() + state := State{State: "ready", DirectoryID: "d", Rules: []Rule{}} + var request SaveRequest + if err := json.Unmarshal([]byte(`{"directory_id":"d","base_revision":"","regions":[{"id":"education","name":"国内教育"},{"id":"overseas","name":"国外工业Amercia"}],"rules":[{"department_id":"sales","region":"education"},{"department_id":"apac","region":"overseas"}]}`), &request); err != nil { + t.Fatal(err) + } + next, err := applyRequest(state, directory, request) + if err != nil { + t.Fatalf("custom business regions must not be rejected by the old four-name whitelist: %v", err) + } + if next.View.Regions["education"] != 1 || next.View.Regions["overseas"] != 1 || next.View.ConflictingPeople != 1 { + t.Fatal("inheritance or stable-ID person dedup changed") + } + projection, err := BuildAttribution(next, directory) + if err != nil || projection.Resolve("p2", "").Region != "国外工业Amercia" { + t.Fatal("attribution did not use the same catalog display name") + } + raw, _ := json.Marshal(request) + var body map[string]any + _ = json.Unmarshal(raw, &body) + body["regions"].([]any)[1].(map[string]any)["name"] = "国外工业 EMEA" + raw, _ = json.Marshal(body) + _ = json.Unmarshal(raw, &request) + renamed, err := applyRequest(next, directory, request) + if err != nil || renamed.Rules[0].Region != next.Rules[0].Region { + t.Fatal("renaming changed the stable mapping") + } + projection, err = BuildAttribution(renamed, directory) + if err != nil || projection.Resolve("p2", "").Region != "国外工业 EMEA" { + t.Fatal("renamed catalog not consumed by attribution") + } +} diff --git a/internal/qaopsorg/regions.go b/internal/qaopsorg/regions.go index 983a4a3..ff0b9f8 100644 --- a/internal/qaopsorg/regions.go +++ b/internal/qaopsorg/regions.go @@ -46,12 +46,18 @@ type PreviewResult struct { // Identity is department ID. Names and legacy keyword rules never decide ownership. func Preview(directory Directory, rules []Rule) (PreviewResult, error) { + return PreviewRegions(directory, rules, DefaultRegions()) +} +func PreviewRegions(directory Directory, rules []Rule, regions []RegionDefinition) (PreviewResult, error) { result := PreviewResult{Departments: []DepartmentView{}, Regions: map[string]int{}, MissingDepartments: []string{}, TotalPeople: len(directory.People)} if len(directory.Departments) == 0 || len(directory.Departments) > 20000 || len(directory.People) == 0 || len(directory.People) > 100000 || len(rules) > 20000 { return result, ErrInvalid } - for _, region := range RegionNames { - result.Regions[region] = 0 + if !validRegions(regions) { + return result, ErrInvalid + } + for _, region := range regions { + result.Regions[region.ID] = 0 } departments := make(map[string]Department, len(directory.Departments)) for _, d := range directory.Departments { diff --git a/internal/qaopsorg/store.go b/internal/qaopsorg/store.go index fe0ebb2..231fffd 100644 --- a/internal/qaopsorg/store.go +++ b/internal/qaopsorg/store.go @@ -26,20 +26,22 @@ type Import struct { Directory Directory `json:"directory"` } type SaveRequest struct { - DirectoryID string `json:"directory_id"` - BaseRevision string `json:"base_revision"` - Rules []Rule `json:"rules"` + Regions []RegionDefinition `json:"regions,omitempty"` + DirectoryID string `json:"directory_id"` + BaseRevision string `json:"base_revision"` + Rules []Rule `json:"rules"` } type State struct { - State string `json:"state"` - DirectoryID string `json:"directory_id"` - DirectorySource string `json:"directory_source"` - DirectorySyncedAt *time.Time `json:"directory_synced_at"` - RevisionID string `json:"revision_id"` - UpdatedBy string `json:"updated_by"` - UpdatedAt *time.Time `json:"updated_at"` - Rules []Rule `json:"rules"` - View PreviewResult `json:"view"` + Regions []RegionDefinition `json:"regions"` + State string `json:"state"` + DirectoryID string `json:"directory_id"` + DirectorySource string `json:"directory_source"` + DirectorySyncedAt *time.Time `json:"directory_synced_at"` + RevisionID string `json:"revision_id"` + UpdatedBy string `json:"updated_by"` + UpdatedAt *time.Time `json:"updated_at"` + Rules []Rule `json:"rules"` + View PreviewResult `json:"view"` } type Store struct { pool *pgxpool.Pool @@ -53,12 +55,14 @@ type orgQuerier interface { QueryRow(context.Context, string, ...any) pgx.Row } -const readStateSQL = `SELECT d.id,d.source,d.synced_at,d.payload,COALESCE(r.id,''),COALESCE(r.rules,'[]'::jsonb),COALESCE(r.updated_by,''),r.created_at +const defaultRegionsJSON = `[{"id":"国内工业","name":"国内工业"},{"id":"APAC","name":"APAC"},{"id":"EMEA","name":"EMEA"},{"id":"America","name":"America"}]` + +const readStateSQL = `SELECT d.id,d.source,d.synced_at,d.payload,COALESCE(r.id,''),COALESCE(r.rules,'[]'::jsonb),COALESCE(r.updated_by,''),r.created_at,COALESCE(r.region_definitions,'` + defaultRegionsJSON + `'::jsonb) FROM qa_ops_organization_state st JOIN qa_ops_directory_snapshots d ON d.tenant_key=st.tenant_key AND d.id=st.directory_id LEFT JOIN qa_ops_region_revisions r ON r.tenant_key=st.tenant_key AND r.id=st.revision_id WHERE st.tenant_key=$1` func (s *Store) read(ctx context.Context, q orgQuerier, lock bool) (State, Directory, error) { - state := State{State: "empty", Rules: []Rule{}, View: PreviewResult{Departments: []DepartmentView{}, Regions: map[string]int{}, MissingDepartments: []string{}}} + state := State{Regions: DefaultRegions(), State: "empty", Rules: []Rule{}, View: PreviewResult{Departments: []DepartmentView{}, Regions: map[string]int{}, MissingDepartments: []string{}}} for _, r := range RegionNames { state.View.Regions[r] = 0 } @@ -67,15 +71,15 @@ func (s *Store) read(ctx context.Context, q orgQuerier, lock bool) (State, Direc if lock { query += " FOR UPDATE OF st" } - var payload, rules []byte - err := q.QueryRow(ctx, query, s.tenant).Scan(&state.DirectoryID, &state.DirectorySource, &state.DirectorySyncedAt, &payload, &state.RevisionID, &rules, &state.UpdatedBy, &state.UpdatedAt) + var payload, rules, regions []byte + err := q.QueryRow(ctx, query, s.tenant).Scan(&state.DirectoryID, &state.DirectorySource, &state.DirectorySyncedAt, &payload, &state.RevisionID, &rules, &state.UpdatedBy, &state.UpdatedAt, ®ions) if errors.Is(err, pgx.ErrNoRows) { return state, directory, nil } - if err != nil || json.Unmarshal(payload, &directory) != nil || json.Unmarshal(rules, &state.Rules) != nil { + if err != nil || json.Unmarshal(payload, &directory) != nil || json.Unmarshal(rules, &state.Rules) != nil || json.Unmarshal(regions, &state.Regions) != nil || state.Regions == nil { return State{}, directory, ErrUnavailable } - state.View, err = Preview(directory, state.Rules) + state.View, err = PreviewRegions(directory, state.Rules, state.RegionDefinitions()) if err != nil { return State{}, directory, ErrUnavailable } @@ -106,7 +110,11 @@ func applyRequest(state State, directory Directory, request SaveRequest) (State, if request.DirectoryID != state.DirectoryID || request.BaseRevision != state.RevisionID { return State{}, ErrConflict } - view, err := Preview(directory, request.Rules) + regions := request.Regions + if regions == nil { + regions = state.RegionDefinitions() + } + view, err := PreviewRegions(directory, request.Rules, regions) if err != nil { return State{}, err } @@ -123,6 +131,7 @@ func applyRequest(state State, directory Directory, request SaveRequest) (State, } } state.View = view + state.Regions = append([]RegionDefinition{}, regions...) state.Rules = append([]Rule{}, request.Rules...) sort.Slice(state.Rules, func(i, j int) bool { return state.Rules[i].DepartmentID < state.Rules[j].DepartmentID }) return state, nil @@ -151,7 +160,9 @@ func (s *Store) SaveRules(ctx context.Context, request SaveRequest, actor string sort.Slice(before, func(i, j int) bool { return before[i].DepartmentID < before[j].DepartmentID }) oldJSON, _ := json.Marshal(before) newJSON, _ := json.Marshal(next.Rules) - if current.RevisionID != "" && string(oldJSON) == string(newJSON) { + oldRegions, _ := json.Marshal(current.RegionDefinitions()) + newRegions, _ := json.Marshal(next.RegionDefinitions()) + if current.RevisionID != "" && string(oldJSON) == string(newJSON) && string(oldRegions) == string(newRegions) { if tx.Commit(ctx) != nil { return State{}, ErrUnavailable } @@ -164,7 +175,7 @@ func (s *Store) SaveRules(ctx context.Context, request SaveRequest, actor string next.RevisionID = "reg-" + hex.EncodeToString(nonce[:]) next.UpdatedBy = actor var at time.Time - if err = tx.QueryRow(ctx, `INSERT INTO qa_ops_region_revisions(tenant_key,id,directory_id,rules,updated_by) VALUES($1,$2,$3,$4,$5) RETURNING created_at`, s.tenant, next.RevisionID, next.DirectoryID, newJSON, actor).Scan(&at); err != nil { + if err = tx.QueryRow(ctx, `INSERT INTO qa_ops_region_revisions(tenant_key,id,directory_id,rules,updated_by,region_definitions) VALUES($1,$2,$3,$4,$5,$6) RETURNING created_at`, s.tenant, next.RevisionID, next.DirectoryID, newJSON, actor, newRegions).Scan(&at); err != nil { return State{}, ErrUnavailable } next.UpdatedAt = &at diff --git a/internal/qaopsorg/store_integration_test.go b/internal/qaopsorg/store_integration_test.go index 30a9ec6..de32740 100644 --- a/internal/qaopsorg/store_integration_test.go +++ b/internal/qaopsorg/store_integration_test.go @@ -134,6 +134,65 @@ func TestOrganizationStoreRoundTripAndOptimisticConflict(t *testing.T) { if err = pool.QueryRow(ctx, "SELECT count(*) FROM qa_ops_region_revisions WHERE tenant_key=$1", "fixture-tenant").Scan(&revisions); err != nil || revisions != 2 { t.Fatal("revision history changed unexpectedly") } + + t.Run("custom catalog persists with the mapping and rename advances revision", func(t *testing.T) { + custom := qaopsorg.NewStore(pool, "catalog-fixture") + imported, e := custom.ReplaceDirectory(ctx, input) + if e != nil { + t.Fatal(e) + } + request := qaopsorg.SaveRequest{DirectoryID: imported.DirectoryID, Regions: []qaopsorg.RegionDefinition{{ID: "education", Name: "国内教育"}}, Rules: []qaopsorg.Rule{{DepartmentID: "a", Region: "education"}}} + preview, e := custom.PreviewRules(ctx, request) + if e != nil || preview.View.Regions["education"] != 1 { + t.Fatal("custom preview failed", e) + } + unchanged, _ := custom.GetView(ctx) + if unchanged.RevisionID != "" { + t.Fatal("catalog preview wrote data") + } + saved, e := custom.SaveRules(ctx, request, "catalog-admin") + if e != nil { + t.Fatal(e) + } + fresh, e := pgxpool.New(ctx, dsn) + if e != nil { + t.Fatal(e) + } + defer fresh.Close() + read, e := qaopsorg.NewStore(fresh, "catalog-fixture").GetView(ctx) + if e != nil || len(read.Regions) != 1 || read.Regions[0].Name != "国内教育" || read.Rules[0].Region != "education" { + t.Fatal("catalog was not persisted with its rules", e) + } + request.BaseRevision = saved.RevisionID + request.Regions[0].Name = "国外工业Amercia" + renamed, e := custom.SaveRules(ctx, request, "catalog-admin") + if e != nil || renamed.RevisionID == saved.RevisionID { + t.Fatal("rename did not create an atomic revision", e) + } + projection, e := custom.GetAttribution(ctx) + if e != nil || projection.Resolve("u1", "").Region != "国外工业Amercia" { + t.Fatal("renamed labels not shared by the read paths") + } + if _, e = custom.SaveRules(ctx, request, "stale-admin"); !errors.Is(e, qaopsorg.ErrConflict) { + t.Fatal("rename allowed stale overwrite") + } + request.BaseRevision = renamed.RevisionID + repeated, e := custom.SaveRules(ctx, request, "catalog-admin") + if e != nil || repeated.RevisionID != renamed.RevisionID { + t.Fatal("unchanged catalog appended another revision") + } + if e = postgresstore.RollbackLatestMigration(ctx, pool); e == nil { + t.Fatal("down migration discarded a custom catalog") + } + if _, e = custom.GetView(ctx); e != nil { + t.Fatal("refused down migration damaged last-good catalog") + } + for _, table := range []string{"qa_ops_organization_state", "qa_ops_region_revisions", "qa_ops_directory_snapshots"} { + if _, e = pool.Exec(ctx, "DELETE FROM "+table+" WHERE tenant_key=$1", "catalog-fixture"); e != nil { + t.Fatal(e) + } + } + }) // This test exercises migration 48, not whichever unrelated migration is latest. for { var latest int64 diff --git a/web/src/QAMonthly.tsx b/web/src/QAMonthly.tsx index 211f52c..2866b58 100644 --- a/web/src/QAMonthly.tsx +++ b/web/src/QAMonthly.tsx @@ -73,7 +73,7 @@ export function QAMonthlyView({ data, loading, error, onRetry, onPage }: ViewPro
{p.error} @@ -98,13 +135,66 @@ export function RegionMappingView(p: Props) {
暂无通讯录,请先同步。
) : ( <> ++ {catalogError} +
+ ) : null} +勾选已修改,人数仍为已保存结果;请预览后保存。
- ) : null} + {p.dirty && !p.preview ?人数仍为已保存结果;请预览后保存。
: null} {display?.view.missing_departments.length ? (| 直接配置 | +选择 | +一级部门 | +二级部门 | +三级部门 | +四级及更深 | 完整部门路径 | +直接配置 | {p.dirty && !p.preview ? '已保存归属' : '生效归属'} | 依据 |
|---|---|---|---|---|---|---|---|---|---|
| - r.department_id === d.id && r.region === p.selectedRegion)} - disabled={p.busy} - onChange={(e) => p.onToggle(d.id, e.target.checked)} - /> - | -{d.path} | -{d.region || '未归属'} | -{d.explicit ? '直接配置' : d.inherited_from ? '继承上级' : '未配置'} | -||||||
| + choose(d.id, e.target.checked)} + /> + | +{levels[0] || '—'} | +{levels[1] || '—'} | +{levels[2] || '—'} | +{levels.slice(3).join(' / ') || '—'} | +{d.path} | ++ {direct ? ( + <> + {label(direct.region)} + + > + ) : ( + '—' + )} + | +{d.region ? label(d.region, organizationRegions(display)) : '未归属'} | ++ {d.explicit ? '直接配置' : d.inherited_from ? '继承上级' : '未配置'} + | +
没有匹配的部门路径
: null} @@ -188,8 +348,8 @@ export function RegionMappingView(p: Props) { ) } -function signature(rules: RegionRule[]) { - return JSON.stringify([...rules].sort((a, b) => a.department_id.localeCompare(b.department_id))) +function signature(rules: RegionRule[], regions: RegionDefinition[]) { + return JSON.stringify({ rules: [...rules].sort((a, b) => a.department_id.localeCompare(b.department_id)), regions }) } export function QARegions() { const [syncStatus, setSyncStatus] = useState