mopr 0.0.67__tar.gz → 0.0.69.dev0__tar.gz

{mopr-0.0.67 → mopr-0.0.69.dev0}/AGENTS.md

@@ -32,6 +32,21 @@ mopr 同一语义的多语言实现遵循固定的**角色与演进顺序**，
 - 跨语言差异处理先从 Python（spec）侧定案，再推广至 C++（生产）与 Rust/Go（扩展）；若 Python 缺少某能力而其他语言已有，应先补 Python spec。
 - 语言最低版本表（上文）与 README.md「语言与版本要求」不因角色调整而改变。
 
+## 文件命名与物理命名空间约定
+
+同一功能拆分为多个源文件时，文件名统一采用「**功能名前缀 + 下划线 + 角色/平台名**」，用前缀在目录内构成**物理层面的命名空间**：
+
+- **前缀即命名空间**：同族文件按前缀自然聚拢，按前缀即可检索到该功能的全部实现：
+  - `base/strings_camel.go` / `strings_snake.go` / `strings_kebab.go` / `strings_helper.go`；
+  - `distributed/id/state_lock_unix.go` / `state_lock_windows.go` / `state_lock_shared.go` / `state_lock_other.go`；
+  - `base/mmap/mmap_posix.go` / `mmap_windows.go` / `mmap_unsupported.go`；
+  - `benchmark/micro/ringbuffer_mpmc_probe.cpp` / `ringbuffer_sched_cost_probe.cpp` / `ringbuffer_single_thread_ablation.cpp`。
+- **两级正交**：前缀承载功能维度，后缀承载语言与角色维度——语言后缀沿用各语言惯例（`.py` / `.h` / `.cpp` / `.rs` / `.go` / `.md`），角色后缀用于平台分支（`_posix` / `_windows` / `_unsupported`）与测试（`_test`）；同一功能的跨语言实现因此同名不同后缀、同处一目录。
+- **适用边界**：前缀只用于同一功能的文件分组，不为无关文件强加公共前缀；功能名已唯一的文件直接以功能名命名（`region.go` / `cron.rs` / `crc32.h`），不画蛇添足。
+- **同目录优先，不按语言分目录**：语言工具链要求「目录即成包」时（Go 的 `package`、Java 的包路径），在**该功能目录内**加同名二级目录与其它语言对齐（`base/mmap/mmap.go` ↔ `base/mmap.py`）；**不得**在仓库根按语言拆分语言级目录，把同一功能的各语言实现物理隔离——同目录并列才能形成「看到 `mmap.py` 顺手去看 `mmap.h` / `mmap.rs` / `mmap/mmap.go`」的对照与主动学习。
+- 与「仓库根即实现根」配合：目录承载模块级命名空间，文件名前缀承载模块内的功能级命名空间，二者共同决定 C++ 命名空间与各语言模块路径（见下文与 [CONTRIBUTING.md](CONTRIBUTING.md)「目录与多语言布局约定」）。
+- 设计意图（同目录对照的收益、按语言分目录为何是反例、对 AI 的友好之处）见 [docs/directory-layout-rationale.md](docs/directory-layout-rationale.md)。
+
 ## Python 包形态与导入约定
 
 - mopr 的 Python 代码经 `pyproject.toml` package-dir 注册为 `mopr.*` 子包：`python/` → `mopr`（包入口，导出 `__version__`），`base/` → `mopr.base`，`log/` → `mopr.log`，`machine/` → `mopr.machine`，`runtime/` → `mopr.runtime`，`distributed/` → `mopr.distributed`，`tools/` → `mopr.tools`。仓库根目录无 `__init__.py`，源码形态下 `mopr` 是 PEP 420 隐式命名空间包。
@@ -47,6 +62,28 @@ mopr 同一语义的多语言实现遵循固定的**角色与演进顺序**，
 - `.cpp`、`tests/`、`benchmark/` 等不随安装分发的文件可用仓库根相对路径（构建期由 `$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}>` 提供 include 根）。
 - 使用方包含安装后的头文件写 `<mopr/<模块>/<头文件>.h>`（如 `<mopr/runtime/once.h>`）。
 
+## C++ 命名空间与头文件宏约定
+
+- **命名空间**：以项目名 `mopr` 为根，**仓库根路径下的子目录为第二级**，多级目录依次下探：
+  - `base/timestamp.h` → `mopr::base`；`storage/storage.h` → `mopr::storage`；
+  - `distributed/id/hlc.h` → `mopr::distributed::id`；`encoding/csv.h` → `mopr::encoding`。
+- 同一模块内可按文件/职责再设下一级子命名空间（如 `base/strings.h` → `mopr::base::strings`；`encoding/csv.h` → `mopr::encoding::csv`；`encoding/json.h` → `mopr::encoding::json`，含 `mopr::encoding::json_detail` / `mopr::encoding::safe_json` / `mopr::encoding::unsafe_json`；`encoding/yaml.h` → `mopr::encoding::yaml` / `mopr::encoding::safe_yaml`）。
+- **禁止**使用未挂 `mopr` 根的顶层命名空间（如 `namespace encoding`、`namespace runtime`）。第三方库自身的顶层命名空间（如 csv-parser 的 `csv`、yaml-cpp 的 `YAML`）不得作为本项目的命名空间根，与本项目命名空间冲突时一律以全局限定形式书写（`::csv::`）。
+- **头文件宏（`#ifndef` 守卫）**：`MOPR_{大写的目录名}_{文件名}_H`，目录层级用下划线连接，文件名取去扩展名的主体：
+  - `encoding/csv.h` → `MOPR_ENCODING_CSV_H`；`encoding/charsets.h` → `MOPR_ENCODING_CHARSETS_H`；
+  - `distributed/id/hlc.h` → `MOPR_DISTRIBUTED_ID_HLC_H`；`base/strings.h` → `MOPR_BASE_STRINGS_H`。
+- 守卫宏与 `#pragma once` 并存；`#endif` 行以注释回写宏名（如 `#endif // MOPR_ENCODING_CSV_H`）。
+- 新增公共头文件一律遵循上述规则。既有不合规处按模块逐个收敛（`runtime::*` → `mopr::runtime::*`、`base/filesystem.h` 的 `filesystem` → `mopr::base::filesystem`、`base/except.h` 的 `quant1x` → `mopr::base`、`base/mmap.h` 的全局 `file_mmap` / `mmap_open` / `mmap_flush` / `mmap_close` → `mopr::base` 内的 `MmapHandle` / `mmap_open` / `mmap_flush` / `mmap_close`），不做一次性大范围改名。
+- **公开符号命名跨语言一致**（同一语义在各语言同名，便于跨语言对照与回溯）：
+  - **公开函数名一致**：Python 与 C++ 使用同一函数名（如 Python `mmap_open` ↔ C++ `mmap_open`），不因语言差异改名；Rust / Go 沿用本语言惯例的，须在模块文档的 API 对照表中给出对应关系。
+  - **函数名带模块前缀时不套同名命名空间**：函数名已含模块前缀（如 `mmap_`）时，C++ 侧不再套一层同名命名空间——`mmap_open` 直接位于 `mopr::base`，而非 `mopr::base::mmap::mmap_open`（同风格参考 `base/region.h` 的 `region_currency` / `region_timezone`）。
+  - **公开结构体 typedef 统一 `mopr_` 前缀**：结构体标签与 typedef 用同名风格，如 `typedef struct mopr_xxx mopr_xxx_t;`；但跨语言共享的**句柄类型除外**——句柄跨语言同名，C++ 侧直接定义 `struct MmapHandle`（与 Python / Rust / Go 的 `MmapHandle` 一字不差），不套 `mopr_xxx_t` 风格。
+  - **句柄类型不得命名 `File`**：句柄承载的是映射而不是文件（文件句柄只是其内部成员之一），`File` 会与 `os.File` / 文件流混淆；跨语言统一用 `MmapHandle`（C++ 为 `struct MmapHandle`）。
+  - **句柄操作遵循语言惯例**：Python / Rust / Go 用句柄方法（`flush` / `close`、`Flush` / `Close`），C++ 句柄是 POD，用同名自由函数（`mmap_flush` / `mmap_close`）与之一一对应。
+  - **同一语义可同时提供「公开 API + RAII 类」两层**：第一层为跨平台公开 API（如 `mmap_open` / `mmap_flush` / `mmap_close` + 句柄），资源由调用方显式管理；第二层为跨语言同名的 RAII 类（如 `MappedMemory`：`MappedMemory.open` 打开，析构 / `Drop` / `with` / `defer` 自动释放）。两层共用同一实现、语义必须一致，区别仅在释放时机；模块文档须给出两层对照表（示例见 `base/mmap.md`「1. 分层与命名」）。
+  - **RAII 类名不得与模块名重复**：类名不叫 `mmap` / `Mmap`（与模块名、包名重复，且易被误读为句柄），统一用其语义名（如 `MappedMemory`），并跨语言同名；句柄另用 `XxxHandle`（如 `MmapHandle`，四语言同名，C++ 亦为 `struct MmapHandle`）。
+- 已知遗留（需按模块逐一评估，勿批量替换）：`base/common.h` 的全局 typedef 与常量（`i8` / `u8` / … 为标量别名、非结构体 typedef，不适用 `mopr_` 前缀约定），`base/format.h` 的全局探测模板与 `std::vector` 的 `operator<<`（依赖 ADL / 非限定查找，移入命名空间会导致使用方找不到），`tests/` 下 `*_test_types` 等测试辅助命名空间。
+
 ## git 提交规范
 
 ### 1. 提交信息规范（含上级仓库约定）

{mopr-0.0.67 → mopr-0.0.69.dev0}/BUILDING.md

@@ -625,7 +625,7 @@ go build ./...
 go test ./...
 ```
 
-现有包：`base/cache`（内存映射缓存）、`base/mem`（页与大小换算）、`runtime`（环形缓冲）、`distributed/id`（分布式 ID，含 `state_lock_windows.go` 等平台分文件）。也可按目录定向运行：
+现有包：`base/cache`（泛型内存映射缓存）、`base/mem`（页与大小换算）、`base/mmap`（文件内存映射）、`runtime`（环形缓冲）、`distributed/id`（分布式 ID，含 `state_lock_windows.go` 等平台分文件）。也可按目录定向运行：
 
 ```powershell
 go test ./runtime/... ./distributed/id/...
@@ -637,7 +637,7 @@ Go 侧唯一运行时第三方依赖为 `golang.org/x/sys` v0.47.0（声明于 `
 
 ### 5.4 平台分文件与许可证头
 
-`base/cache` 的 mmap 与 `distributed/id` 的 state_lock 均按平台拆分实现：`mmap_windows.go` / `mmap_posix.go` / `mmap_unsupported.go`、`state_lock_windows.go` / `state_lock_unix.go` / `state_lock_other.go`。平台分文件必须保留 `//go:build` 构建约束：许可证头位于其前（均为行注释，Go 允许 build constraint 被行注释与空行前置），批量写入版权/许可证头时不得删除 build tag；`mapFile`、`processAlive` 等平台符号由 build tag 决定唯一编译。平台分文件改动不得引入低于 Go 1.27.0 的特性。当前验证环境（Windows + `go1.27.0`）下 `go build ./...` 与 `go test ./...` 全绿（`base/cache`、`base/mem`、`distributed/id`、`runtime` 四个包）。
+`base/mmap` 的映射实现与 `distributed/id` 的 state_lock 均按平台拆分实现：`mmap_windows.go` / `mmap_posix.go` / `mmap_unsupported.go`、`state_lock_windows.go` / `state_lock_unix.go` / `state_lock_other.go`。平台分文件必须保留 `//go:build` 构建约束：许可证头位于其前（均为行注释，Go 允许 build constraint 被行注释与空行前置），批量写入版权/许可证头时不得删除 build tag；`Map`、`processAlive` 等平台符号由 build tag 决定唯一编译。平台分文件改动不得引入低于 Go 1.27.0 的特性。当前验证环境（Windows + `go1.27.0`）下 `go build ./...` 与 `go test ./...` 全绿（`base/cache`、`base/mem`、`base/mmap`、`distributed/id`、`runtime` 五个包）。
 
 ## 6. 第三方声明与许可证归档
 

{mopr-0.0.67 → mopr-0.0.69.dev0}/CHANGELOG.md

@@ -3,6 +3,243 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.0.68] - 2026-09-12
+### Changed
+- fix[web]: 调整键盘信息采集的web代码路径到tests
+- fix[python]: 补充版权信息
+- feat[multi]：新增 website/oa 内置 OA 办公协同系统
+  - 后端：Python 3.12+ 标准库 HTTP 服务 + SQLite 单文件库，覆盖公告通知、申请单、多级审批、任务待办、流程定义与系统管理（用户 / 部门 / 角色权限 / 操作日志），鉴权与菜单口径统一由 oa/rbac.py 权限点目录驱动
+  - 前端：Vue 3 + Vue Router + Vite 源码位于 frontend/，产物输出到 Vite 默认目录 frontend/dist
+  - 静态托管根目录由 oa/config.py 的 WEB_DIR 与 vite.config.js 的输出目录共同决定，两处绑定、改名须同改；产物缺失时 40400 提示直接给出构建命令
+  - 产物不入库：frontend/dist 由仓库根 .gitignore 的 dist/ 规则忽略，首次运行须先在 frontend/ 执行 npm run build
+  - 文档：README 补齐目录结构、快速开始、接口约定、权限模型与开发约定，并写明产物目录的后端绑定关系
+  - 验证：cd website/oa && python3 tests/smoke_test.py
+- fix[multi]：修正新建流程弹窗业务类型与审批人类型下拉为空
+  - 根因：FlowFormDialog.vue 中 bizTypes / approverTypes 被定义为普通箭头函数，模板用 v-for 直接迭代该函数；Vue 的 renderList 对函数走对象分支，遍历其自身可枚举属性（函数无此属性）结果为 0 项，下拉不显示任何选项
+  - 改动：两者改为 computed(() => optionList(...))，模板保持不变，与视图层既有的 v-for="option in <computed>" 写法统一，并补 computed 导入
+  - 影响范围：顺带修复同一缺陷导致的「审批人类型」下拉为空
+  - 接口与数据侧无改动：/api/meta 的 biz_types / approver_types 字典与登录时装载的 state.dicts 本身正常，无需调整
+  - 验证：cd website/oa/frontend && npm run build 构建通过，产物已刷新；界面效果需浏览器刷新后确认
+- feat[python]：新增合同审批与财务反向处理业务类型及样例流程
+  - 业务类型白名单 BIZ_TYPES（oa/services/approval.py）新增 contract 合同审批、reversal 财务冲正、red_reversal 红字冲销、adjustment 账务调整，并在注释中固化命名口径：合同审批指签前审批（对应内控「合同订立」，盖章另走 seal）；财务冲正指资金/清算层对某笔交易反向记账；红字冲销指会计凭证层对已入账凭证做负数分录更正（俗称红冲）；账务调整指人工发起、需审批留痕的账务更正单据；三者口径互不等价，不做合并
+  - 样例流程：seed.py 的 _FLOWS 补入上述四条流程定义（含各自表单字段与审批链路），财务复核统一取 role:finance，红字冲销与账务调整末步回到 applicant 确认；seed 内示例公告文案同步补「合同审批」
+  - 表结构注释：schema.sql 中 flow_defs.biz_type 的枚举注释补齐新取值；biz_type 为 TEXT 且无 CHECK 约束，老库无需迁移
+  - 前端零改动：业务类型选项全部经 /api/meta 的 biz_types 下发，前端无硬编码 code 列表，流程定义与申请单的下拉自动带出新类型
+  - 文档：README 新增「业务类型与样例流程」章节（业务类型口径表、审批人来源、首次初始化灌入的样例流程清单），并在「数据库」小节说明 seed 以 meta.seeded 为哨兵只执行一次、既有库不会补入新增样例流程
+  - 兼容性：既有库不会新增样例流程，需重置库或在「流程定义」页手工新建；业务类型来自代码、不依赖灌库，升级即生效
+  - 验证：cd website/oa && python3 tests/smoke_test.py（通过 39 项，失败 0 项）
+- feat[python]：内置样例流程改为启动时按缺失回填并记录删除墓碑
+  - schema.sql：flow_defs 增加 is_seed 列，标注内置样例流程
+  - db.py：SCHEMA_VERSION 升至 2，_migrate 补 v2 分支（ALTER TABLE 加列），替换原先的空循环占位
+  - seed.py：新增 sync_flows（每次启动按缺失回填；已存在与被停用的流程不动，同编码历史行补标 is_seed）、mark_flow_removed 与 _removed_flow_codes（meta.seed_flows_removed 删除墓碑）；抽出 _insert_flow 供首次灌入与启动回填共用
+  - server.py：create_server 在 database.initialize 之后接上 seed.sync_flows
+  - services/approval.py：delete_flow 删除样例流程时同事务写墓碑，审计事件补 detail.sample
+  - README.md：更新升级行为（样例流程升级即补齐）、结构版本与迁移约定、服务层对 seed 的例外依赖
+  - 验证：python3 tests/smoke_test.py 通过 39 项、失败 0 项；另在真实库的只读备份副本上实测三个用例——结构 v1 的库启动即迁移（schema_version 2、8 条流程补标 is_seed）、缺 4 条样例流程的老库启动后回填至 8 条、接口删除 purchase 写墓碑后重启不回填（同批裸删的 seal 被正常回填）
+- feat[multi]：流程定义页新增内置样例流程的恢复入口
+  - 后端把删除墓碑从「只写」变为可读可恢复：`seed._write_removed` 抽出整表回写，
+    新增 `seed.removed_flows`（墓碑中登记且库中缺失的内置样例流程）与
+    `seed.restore_flows`（按内置定义重建并摘除命中编码，`conn` 可复用调用方事务）
+  - `seed._flow_brief` 返回内置定义副本，步骤与表单字段逐项浅拷贝，避免上层补展示字段
+    时污染模块级 `_FLOWS`
+  - 服务层新增 `approval.list_removed_flows`（补齐 `biz_type_label`/`approver_type_label`/
+    `is_seed`，与 `/api/flows` 行形状一致）与 `approval.restore_flows`（校验 codes 落在
+    可恢复清单内，无可恢复项 409、编码非法 400，写 `flow:restore` 审计）
+  - 新增 `GET /api/flows/removed`（`flow:view`）与 `POST /api/flows/restore`
+    （`flow:create`，请求体 `codes` 缺省即恢复全部），路由排在 `{id}` 之前
+  - 前端流程定义页把墓碑中的样例流程渲染为灰行（状态「已删除」、名称旁「可恢复」），
+    行尾「恢复」按内置定义重建，多条时页头出现「恢复内置样例流程（N）」一次恢复全部；
+    删除内置样例流程的确认文案改为提示可找回
+  - 语义一致性：恢复即「按内置定义新建」，与手工新建同编码流程等价，故复用 `flow:create`
+    而不新增权限点（权限点只在首次初始化时灌入，新增权限码对既有库不生效）；恢复后编码
+    从墓碑摘除，交由 `sync_flows` 常规接管，此后再次删除会重新登记墓碑；自建流程删除既
+    不入墓碑也不可恢复
+  - 涉及语言与文件范围：Python（`oa/seed.py`、`oa/services/approval.py`、`oa/api.py`、
+    `tests/smoke_test.py`）+ 前端 JS/Vue（`frontend/src/api.js`、`frontend/src/views/FlowsView.vue`）
+    + `README.md`
+  - 验证：`cd website/oa && python3 tests/smoke_test.py` 通过 51 项、失败 0 项（新增第 5 节
+    覆盖 样例流程带 is_seed → 删除 → 进可恢复清单且列表消失 → 按编码恢复 → 步骤与出厂
+    定义一致且 is_seed 仍为 1 → 墓碑摘除 → 再恢复得 409 → 自建流程删除不进清单 →
+    普通员工恢复得 403）；`cd frontend && npm run build` 通过
+- feat[docs]: 新增安全与合规模块
+- feat[python]：新增 security/auth 通用安全模块
+  - 按 security/auth/README.md 的 spec 落地实现，模块只依赖标准库，与存储、传输解耦：
+    credential（口令哈希与策略校验）、token（令牌生成与签名编解码）、
+    session（会话与登录节流/锁定）、model / principal（主体与数据范围）、
+    catalog / authorize（权限点目录与鉴权）、errors，以及 spi（接入方实现的存储与目录接口）
+  - 对外只暴露 SPI 接口，由宿主提供 IdentityStore / SessionStore / LoginAttemptStore 等实现，
+    便于 OA、MES 等不同接入层复用同一套安全语义
+  - pyproject.toml：packages 与 package-dir 新增 mopr.security、mopr.security.auth
+  - 验证：python -m security.auth.credential_test / rbac_test / session_test / token_test 全部 OK
+    （须用 -m 方式运行：security/auth/token.py 会遮蔽同名标准库模块）
+- feat[python]：OA 认证授权接入 security/auth 通用模块
+  - website/oa/oa/security.py、rbac.py 由自带实现改为对 mopr.security.auth 的薄封装：
+    保留原有函数签名与返回结构，把口令哈希、令牌随机数、权限判定与数据范围计算下沉到通用模块
+  - 新增分流语义：库内口令摘要损坏（无法解析 / 算法不符 / 迭代次数非正 / base64 损坏）时，
+    不再计入失败次数、不触发锁定，也不当作「用户输错口令」，而是明示
+    「账号口令数据异常，请联系系统管理员重置口令」，并分别记 login_rejected / change_password_rejected 审计；
+    普通失败仍统一提示「账号或口令错误」，不泄露账号是否存在
+  - 改密路径同一分流但返回 400 而非 401：前端对 401 会强制清会话跳登录页，
+    而此刻会话是有效的，用户需要停在改密弹窗里看到原因；失败时库内摘要不会被改写
+  - 测试：security_test.py 28 项、smoke_test.py 60 项全部通过；冒烟第 7 节新增
+    「摘要损坏前可正常登录 / 登录 401 / 不计失败次数 / 改密 400 / 摘要未被改写 / 两条审计留痕」
+  - 文档：website/oa/README.md 登录安全与冒烟覆盖说明同步
+- feat[python]：新增 encoding/charsets 字符集转码的 Python 实现并导出至包入口
+  - 变更概述：新增 encoding/charsets.py，作为 UTF-8 与 GBK(GB18030) 双向转码的 Python spec 实现；encoding/__init__.py 同步导出
+  - 文件范围：encoding/charsets.py（新增）、encoding/__init__.py（包入口导出 utf8_to_gbk / gbk_to_utf8 并更新模块说明）
+  - 语义一致性：码表选用 GB18030，与 C++ 侧 iconv 的 GB18030//IGNORE 对齐；非法/不完整多字节序列按 //IGNORE 语义丢弃、两个方向均不抛异常；转换前在首个 NUL 处截断，均与 encoding/charsets.cpp 的 truncate_at_null 行为一致；Python str 为 Unicode、GBK 侧以 bytes 承载，与 C++ std::string 原始字节串语义等价
+  - 验证：python -c "from mopr.encoding import utf8_to_gbk, gbk_to_utf8"，'中文' 往返转换结果一致
+- refactor[c++]：统一 encoding 命名空间为 mopr::encoding 并落定命名空间与头文件宏规则
+  - 变更概述：encoding 模块的 C++ 命名空间由未挂根的 encoding::*（csv/json/yaml）收敛到 mopr::encoding::*，调用方 storage 同步改造；同时在文档中固化 C++ 命名空间与头文件 #ifndef 宏规则
+  - 命名空间映射：charsets.h/charsets.cpp → mopr::encoding；csv.h → mopr::encoding::csv；json.h/json.cpp → mopr::encoding::json（含 json_detail / safe_json / unsafe_json 子命名空间）；yaml.h → mopr::encoding::yaml（含 safe_yaml）
+  - 头文件守卫宏：encoding/charsets.h 的 MOPR_ENCODING_ICONV_H 按 MOPR_{大写的目录名}_{文件名}_H 规则改为 MOPR_ENCODING_CHARSETS_H
+  - 文件范围：encoding/{csv.h,json.h,json.cpp,yaml.h,charsets.h,charsets.cpp}、调用方 storage/storage.h、测试 tests/encoding/{charsets,csv,json,yaml}_test.cpp、文档 AGENTS.md（新增「C++ 命名空间与头文件宏约定」）、CONTRIBUTING.md、encoding/README.md、encoding/{csv,json,yaml}.md、storage/storage.md
+  - 语义一致性：仅命名空间、头文件守卫宏与文档调整，函数签名、序列化行为及与 Python(spec) / Go 侧契约不变
+  - 遗留：顶层 runtime、base/filesystem.h 的顶层 filesystem、base/except.h 的 quant1x 尚未收敛，已在 AGENTS.md 记为后续逐模块处理
+  - 验证：cmake --build --preset release-dynamic --target mopr_tests 编译通过；mopr_tests.exe --gtest_filter=*Charsets*:*Csv*:*Json*:*Yaml* 4 个测试套件 28 个用例全部通过
+- refactor[c++]：统一 base/mmap.h 命名空间为 mopr::base::mmap
+  - base/mmap.h：file_mmap / mmap_t / mmap_open / mmap_flush / mmap_close 全部纳入 mopr::base::mmap；
+    windows.h 的引入仍留在全局作用域（HANDLE 等平台类型不能落进本项目命名空间）
+  - base/mmap.cpp：Windows 与 POSIX 两分支由单个 mopr::base::mmap 块包裹；POSIX 的 sys/mman.h 等
+    系统头从 #else 分支上提到文件顶部——置于命名空间内会把 ::mmap 等系统声明误建到本项目命名空间，
+    平台分支代码体零改动
+  - distributed/id/state_store.h：前向声明由全局 struct file_mmap / typedef mmap_t 改为
+    namespace mopr::base::mmap { struct file_mmap; }，成员改用 mopr::base::mmap::file_mmap *，
+    继续只暴露不完整类型，不向使用方泄漏 mmap.h 与 windows.h
+  - distributed/id/state_store.cpp：8 处 mmap_* 调用改为 mopr::base::mmap:: 全限定形式，与同文件
+    既有 mopr::base::getenv 风格一致，未引入 using 声明
+  - 语义不变：共享映射的跨语言(Spec: Python → Go/Rust)文件格式、平台对齐修正与 flush 时机均未改动
+  - 验证：cmake --build --preset release-dynamic 通过；
+    build/release-dynamic/tests/Release/mopr_tests.exe 94 用例 93 通过、1 跳过
+    （CronTest.DstGapSkipsInsteadOfStalling：本地时区无夏令时的既有条件跳过）
+- refactor[c++,go]：抽出 Go 版 base/mmap 包并同步 C++ mmap 头注释
+  - 变更概述：把原先内嵌在 base/cache 的 Go 内存映射实现抽成独立包 base/mmap（与 C++
+    base/mmap.h 的目录/命名布局对齐），base/cache 退化为该映射包的使用方。
+  - 涉及语言与文件范围：
+    - go：新增 base/mmap/{mmap.go, mmap_posix.go, mmap_windows.go, mmap_unsupported.go,
+      mmap_test.go}；删除 base/cache/{mmap_file.go, mmap_posix.go, mmap_windows.go,
+      mmap_unsupported.go, mmap_file_test.go}；base/cache/cache.go 改用 mmap.MemObject 与
+      mmap.Map；distributed/id/state_store.go 改用 *mmap.File 与 mmap.Open；BUILDING.md 同步
+      Go 包清单（增至五个包）与平台分文件段落（base/cache → base/mmap、mapFile → Map）。
+    - c++：base/mmap.h 仅更新头部注释中的 Go 对应路径（base/cache/mmap_file.go →
+      base/mmap/mmap.go），无代码改动。
+  - 导出名按 Go 惯例去重：MappedFile / OpenMappedFile / mapFile → mmap.File / mmap.Open /
+    mmap.Map；MemObject 由 cache 迁至 mmap（描述映射操作，随映射功能归位）。
+  - 语义一致性：映射实现逐行搬运，未改逻辑——size 校验（非正数、超 MaxInt/MaxUint32）、父目录
+    按需创建、定长 Truncate、Flush 刷脏页与文件元数据、Close 幂等（先 Flush 再 Unmap 再关文件，
+    首个错误优先返回）；平台分文件保留 //go:build 约束且许可证头仍位于其前。
+  - 验证：
+    - gofmt -l base/cache base/mmap distributed/id 无输出；
+    - go build ./... 与 go vet ./... 通过；
+    - go test ./... 全绿（base/cache 5.0s、base/mmap 0.39s、distributed/id 0.51s、runtime、base、
+      encoding/base64）；
+    - 交叉平台分支核对：GOOS=linux go build/vet ./base/mmap/... ./base/cache/... ./distributed/id/...
+      通过（POSIX 分支），GOOS=js GOARCH=wasm go build ./base/mmap/... 通过（unsupported 分支）。
+- refactor[c++]：统一 runtime 命名空间为 mopr::runtime
+  - runtime/once.h：顶层 namespace runtime 收敛为 mopr::runtime，收尾注释同步回写
+  - runtime/ringbuffer.h：namespace runtime::ringbuffer → mopr::runtime::ringbuffer，detail 与
+    queue 两处代码块及收尾注释一并回写；头文件宏 MOPR_RUNTIME_RINGBUFFER_H 不变，文件内
+    「与 Rust runtime::Queue 语义一致」等指代他语言的描述保持原样
+  - runtime/scheduler.h：顶层 namespace runtime 收敛为 mopr::runtime，并把原先分处两个 namespace
+    块的 task_id/JobType 枚举与 AsyncScheduler 类合并到同一块内；JobInfo 成员随之去限定
+    （runtime::task_id → task_id、runtime::JobType → JobType）
+  - runtime/scheduler.cpp：add_job 返回类型与 7 处成员函数形参的 ID 类型改为 task_id /
+    mopr::runtime::task_id，4 处 JobType 使用去限定（文件自身处于 mopr::runtime 内，按资质查找可见）
+  - 调用点同步限定：tests/runtime/once_test.cpp、tests/runtime/scheduler_test.cpp（含
+    info->type == mopr::runtime::JobType::Cron 断言）、benchmark/micro/ringbuffer_mpmc_probe.cpp /
+    ringbuffer_single_thread_ablation.cpp / vyukov_bench.cpp（using namespace
+    mopr::runtime::ringbuffer）、distributed/id/queue.h（内嵌成员类型与注释）
+  - 文档与构建脚本：runtime/once.md 的 API 对照表与用法示例由 runtime::RollingOnce 改为
+    mopr::runtime::RollingOnce；CMakeLists.txt 说明注释中的 runtime::ringbuffer::queue<T> 同步
+  - 语义一致性：纯命名空间与限定名收敛，无逻辑、接口、头文件宏改动；公共头文件之间仍用相对路径
+    互引，头文件宏命名规则不变
+  - 验证：cmake --build --preset release-dynamic 成功（exit 0）；
+    build/release-dynamic/tests/Release/mopr_tests.exe 94 用例 93 通过、1 跳过
+    （CronTest.DstGapSkipsInsteadOfStalling：本地时区无夏令时的既有条件跳过），
+    12 个 SchedulerTest 用例全绿
+  - 范围说明：encoding/csv.h、encoding/csv.md 的 filesystem 限定名改动随 base/filesystem 批次提交
+    （csv 调用点依赖 filesystem 头命名空间收敛），不在本次提交内
+- refactor[c++]：统一 base/filesystem 命名空间为 mopr::base::filesystem
+  - base/filesystem.h：顶层 namespace filesystem 收敛为 mopr::base::filesystem，收尾注释同步回写；
+    头文件宏 MOPR_BASE_FILESYSTEM_H 与全部函数签名、默认参数不变
+  - base/filesystem.cpp：同名收敛（定义与收尾注释），文件内 namespace fs = std::filesystem 别名、
+    各平台分支（home/executable/写文件等）实现逻辑逐行未改
+  - encoding/csv.h：写出端口径的调用点由 filesystem::check_filepath 改为
+    mopr::base::filesystem::check_filepath——原写法依赖顶层 filesystem 命名空间的可见性，
+    收敛后必须显式全限定
+  - encoding/csv.md：写入端行为说明中的同名调用点同步更新
+  - 语义一致性：纯命名空间与限定名收敛，无逻辑、接口、头文件宏改动；std::filesystem 的使用方式
+    与调用点（含 distributed/id/state_store.cpp 等 std::filesystem 用法）保持原样
+  - 验证：cmake --build --preset release-dynamic 成功（exit 0）；
+    build/release-dynamic/tests/Release/mopr_tests.exe 94 用例 93 通过、1 跳过
+    （CronTest.DstGapSkipsInsteadOfStalling：本地时区无夏令时的既有条件跳过），
+    OnceTest 16 个、SchedulerTest 12 个用例全绿
+- refactor[c++]：统一 base/except 命名空间为 mopr::base
+  - base/except.h：BaseException 由全局命名空间移入 mopr::base；原 quant1x 命名空间内的 error
+    与 make_error_code 并入 mopr::base，收尾注释同步回写
+  - THROW_EXCEPTION 宏改为全限定展开（throw mopr::base::BaseException(msg, __FILE__, __LINE__)），
+    使任意命名空间下的调用点无需逐个补限定名
+  - 影响范围：仓库内唯一包含点为 base/time.cpp（其 THROW_EXCEPTION 调用当前处于注释状态），
+    全仓无其他 BaseException 引用或捕获点，调用方无需同步改动
+  - 语义一致性：仅命名空间归属与宏限定名变化；异常类定义（what()、file/line 成员与构造函数）、
+    error 继承 std::error_code 的接口与实现均逐行未改
+  - 遗留：storage/storage.h 头部 TODO 提到的 quant1x::data::meta::Instrument 属未移植的旧模块，
+    不在本次收敛范围
+  - 验证：cmake --build --preset release-dynamic 成功（exit 0）；
+    build/release-dynamic/tests/Release/mopr_tests.exe 94 用例 93 通过、1 跳过
+    （CronTest.DstGapSkipsInsteadOfStalling：本地时区无夏令时的既有条件跳过）
+- docs[c++]：记录命名空间按模块收敛结果与已知遗留清单
+  - AGENTS.md：把「既有不合规处随对应模块重构逐步收敛」改为已落地的四类对照写法
+    （runtime::* → mopr::runtime::*、base/filesystem.h 的 filesystem → mopr::base::filesystem、
+    base/except.h 的 quant1x → mopr::base、base/mmap.h 的全局 file_mmap / mmap_open / mmap_flush /
+    mmap_close → mopr::base::mmap），并保留「不做一次性大范围改名」的约束
+  - 新增「已知遗留」条目：base/common.h 的全局 typedef 与常量、base/format.h 的全局探测模板与
+    std::vector 的 operator<<（依赖 ADL/非限定查找，移入命名空间会导致使用方找不到）、tests/ 下
+    *_test_types 等测试辅助命名空间，须按模块逐一评估，勿批量替换
+  - 规范与现状对齐：该规则涉及的四个模块收敛已分别落地（base/mmap、runtime、base/filesystem、
+    base/except 四个批次），本次仅补记结论，不含代码改动
+  - 验证：纯文档改动，不触及编译；同批次的 C++ 全量构建与测试已通过
+    （cmake --build --preset release-dynamic、mopr_tests.exe 94 用例 93 通过、1 跳过）
+- refactor[python,c++]：统一 mmap 公开函数名并收敛 C++ 命名空间与句柄类型
+  - Python：base/mmap.py 的 open_file 更名为 mmap_open，与 C++ 公开函数名完全一致；mopr.base 包导出与 __all__ 同步更名
+  - C++：base/mmap.h 与 base/mmap.cpp 由 namespace mopr::base::mmap 收敛为 namespace mopr::base，函数名保留 mmap_ 前缀（mmap_open / mmap_flush / mmap_close），不再套一层同名命名空间
+  - C++：公开句柄类型 file_mmap / mmap_t 更名并统一 mopr_ 前缀，为 struct mopr_mmap 加 typedef struct mopr_mmap mopr_mmap_t；distributed/id/state_store.h 的前向声明与成员类型同步
+  - 调用点：distributed/id/state_store.cpp、distributed/id/state_store.py、base/mmap_test.py 全部切换到新符号名
+  - 语义一致性：Python（spec）与 C++（生产）的打开、刷盘、释放语义不变，仅调整符号命名与命名空间层级；刷盘与释放仍分别对应句柄方法 File.flush / File.close 与自由函数 mmap_flush / mmap_close，一一对应
+  - 规范沉淀：AGENTS.md 新增「公开符号命名跨语言一致」四条约定（函数名跨语言一致、带模块前缀不套同名命名空间、公开结构体 typedef 统一 mopr_ 前缀、句柄操作按语言惯例）；base/mmap.md 增加命名约定小节并同步清单、API 对照表与使用方表
+  - 验证：cmake --build --preset release-dynamic（exit 0）；build/release-dynamic/tests/Release/mopr_tests.exe 94 用例 93 通过 1 跳过；python -m unittest mopr.base.mmap_test mopr.distributed.id.tests 26 用例 OK；python -m mopr.tools.license_header --check 4 个改动文件通过
+- feat[python,c++,rust,go]：新增跨平台 mmap 基建并统一跨语言句柄命名
+  - 变更概述：落地两层 mmap API——第一层为跨平台公开 API（mmap_open / mmap_flush / mmap_close + 句柄 MmapHandle，资源由调用方显式管理），第二层为跨语言同名的 RAII 类 MappedMemory（析构 / Drop / with / defer 自动释放）；支持定长共享映射的 offset / length、按需创建父目录、文件短于请求长度时扩展（长于请求长度不截断，非破坏性）。
+  - 句柄命名跨语言统一为 MmapHandle：Python / Go 原先的 File 改名（File 名称过于通用，与 os.File / 文件流混淆）；C++ 由 struct mopr_mmap + typedef mopr_mmap_t 改为 struct MmapHandle 并删除 mopr_mmap_t 别名；Rust 随新增模块一并为 MmapHandle。Go 低层平台映射接口 MemObject 改名 Mapping，与第二层 MappedMemory、入口 Map 不再撞名。
+  - 文件范围：base/mmap.py、base/mmap.h、base/mmap.cpp、base/mmap.rs（新增）、base/mmap/mmap.go 与 mmap_posix.go / mmap_windows.go / mmap_unsupported.go、base/mmap.md、AGENTS.md 命名约定；使用方 distributed/id/state_store.py / .h / .cpp / .rs / .go、base/cache/cache.go、base/__init__.py、base/mod.rs；测试 base/mmap_test.py、base/mmap.rs 内联测试、base/mmap/mmap_test.go、tests/base/mmap_test.cpp（新增并接入 tests/CMakeLists.txt）。Rust 侧顺带做 rustfmt 风格统一（base/cron.rs、base/timestamp.rs、base/region.rs 的 BOM 清理、格式与导入排序）。
+  - 语义一致性：四语言第一层语义一致（打开即定长共享映射、flush 幂等刷盘、close 幂等释放且句柄置空 / 归零），第二层仅释放时机不同、共用同一实现；C++ 句柄为 POD 配同名自由函数，其余语言用句柄方法一一对应，两层 API 对照表见 base/mmap.md。
+  - 验证：cargo test（lib 与 doctests 全通过）；python -m unittest mopr.base.mmap_test（18 passed）；go test ./...（全部 ok）；cmake --build --preset release-dynamic --target mopr_tests 后运行 mopr_tests.exe（106 用例 105 passed + 1 skipped）。
+- docs[multi]：统一目录与命名约定并补齐 spec 占位、沉淀布局设计意图
+  - 目录布局：README「项目结构」改为「仓库根即实现根」，删除 `src/core` 与 `src/platform`
+    两级，功能模块目录平铺在仓库根，同一功能的多语言实现同目录、同名不同后缀
+  - 命名约定：AGENTS.md 新增「文件命名与物理命名空间约定」小节（前缀即命名空间、
+    两级正交、适用边界、同目录优先不按语言分目录）
+  - 规范条款：CONTRIBUTING.md §2 将原「语言边界冲突可下沉语言专属子目录做物理隔离」
+    改为「语言边界适配（不按语言分目录）」——工具链要求目录即成包时，在该功能目录内
+    加同名二级目录与其它语言对齐，禁止在仓库根按语言拆分目录
+  - spec 占位：新增 spec/api.md（接口契约）与 spec/behavior.md（行为语义），对齐
+    README「项目结构」与 CONTRIBUTING「Spec 驱动与基准验证工作流」的约定，均标注待起草
+  - 设计意图：新增 docs/directory-layout-rationale.md，记录约定收益、层级由语言工具链
+    决定、按语言分目录的反例、对 AI 友好的四点与三条不变式；README / CONTRIBUTING /
+    AGENTS 各留一处指针
+  - 语义一致性：布局与命名约定在 README / CONTRIBUTING / AGENTS / spec 四处表述一致，
+    未涉及代码与构建产物，无版本号与发布信息
+  - 验证：人工核对四处表述与交叉链接一致，docs 内引用根文档统一用 ../ 相对链接
+- chore[python]：发布脚本改为自动检测并安装发布依赖
+  - publish.ps1 / publish.bat / publish.sh 统一依赖处理流程：先升级 pip 本身（失败回退 --user，再失败仅告警继续，不阻断发布），再按需安装 build、twine
+  - 用 importlib.util.find_spec 探测模块是否可用，缺失时用 pip 安装（全局失败回退 --user），装完复检，仍缺失才明确报错
+  - pip 自身缺失时先用 python -m ensurepip --upgrade 自举
+  - 上传统一改为 python -m twine upload，避免 PATH 中的 twine 指向其它解释器；publish.ps1 与 publish.sh 改为上传已解析出的 sdist 与 wheel 产物
+  - publish.ps1 修正 Remove-ReleaseResidualDirs 在项目名尚未解析时触发 StrictMode 报错的问题
+  - 三个脚本的头部注释与帮助文本同步说明依赖处理行为
+  - 验证：publish.ps1 PowerShell 语法解析通过，实跑 Update-Pip（pip 26.1.1 升级至 26.2.1）与依赖探测、安装失败回退路径；publish.sh 的 bash -n 通过，并以真实 bash 抽取依赖 helper 验证模块存在性探测与安装失败退出码；publish.bat 保持 CRLF 行尾
+- release version 0.0.68
+
 ## [0.0.67] - 2026-09-11
 ### Changed
 - fix[c++]：修正 encoding 测试因 boost::pfr 反射类型无外部链接导致的编译失败
@@ -1688,7 +1925,8 @@ All notable changes to this project will be documented in this file.
 - release version 0.0.1
 
 
-[Unreleased]: https://gitee.com/quant1x/mopr/compare/v0.0.67...HEAD
+[Unreleased]: https://gitee.com/quant1x/mopr/compare/v0.0.68...HEAD
+[0.0.68]: https://gitee.com/quant1x/mopr/compare/v0.0.67...v0.0.68
 [0.0.67]: https://gitee.com/quant1x/mopr/compare/v0.0.66...v0.0.67
 [0.0.66]: https://gitee.com/quant1x/mopr/compare/v0.0.65...v0.0.66
 [0.0.65]: https://gitee.com/quant1x/mopr/compare/v0.0.64...v0.0.65

{mopr-0.0.67 → mopr-0.0.69.dev0}/CONTRIBUTING.md

@@ -30,9 +30,13 @@ MOPR（Monorepo Optimal Portable Runtime，单仓最优可移植运行时）是*
 └── （后续引入的其它语言，如 main.go / main.py，同样平铺在此目录）
 ```
 
+- **仓库根即实现根（不设 `src/` 层）**：功能模块目录直接平铺在仓库根，作为各语言共同的模块根，模块路径取自同一目录相对路径，保证同一功能在各语言的模块语义相同。
+- **与 Go 的 package 对齐**：Go 的包边界以目录划分，功能模块目录因此与 Go 的 `package` 一一对应（`distributed/id` 即 `package id`）；C++ 命名空间第二级（`distributed/id/hlc.h` → `mopr::distributed::id`）、Python 子模块路径、Rust `mod` 路径均取自同一目录路径。
+- **同功能多文件以统一前缀构成物理命名空间**：一个功能拆成多个源文件时，统一以「功能名_」为前缀命名——`strings_camel.go` / `strings_snake.go`、`state_lock_unix.go` / `state_lock_windows.go`、`mmap_posix.go` / `mmap_windows.go` / `mmap_unsupported.go`、`ringbuffer_mpmc_probe.cpp` / `ringbuffer_sched_cost_probe.cpp`；前缀承载功能维度，后缀承载语言与角色维度（`.py` / `.h` / `.cpp` / `.rs` / `.go`、`_posix` / `_windows` / `_test`），使同族文件在目录中自然聚拢、可按前缀检索；功能名已唯一时直接以功能名命名，不强行加前缀。完整约定见 [AGENTS.md](AGENTS.md)「文件命名与物理命名空间约定」。
+- **语言边界适配（不按语言分目录）**：语言工具链要求「目录即成包」时（Go 的 `package`、Java 的包路径），在**该功能目录内**加同名二级目录承载该语言实现，与其它语言保持同名对齐——`base/mmap/mmap.go` 与 `base/mmap.py` 同为 mmap。层级由语言工具链决定、服务于跨语言对齐，**不得**在仓库根按语言拆分语言级目录，把同一功能的各语言实现物理隔离；同目录并列才能形成「看到 `mmap.py` 顺手去看 `mmap.h` / `mmap.rs` / `mmap/mmap.go`」的对照与主动学习。
 - **语义对齐**：各语言实现的函数签名、命名前缀保持一致，降低跨语言阅读与二次开发成本。
-- **语言边界冲突**：若某语言的包/模块边界不允许与其它语言共处一目录（如 Go 的包边界以目录划分），可将该语言实现下沉到语言专属子目录做物理隔离，对外调用语义与命名前缀不变。
-- **结构总览**：仓库布局（`spec/`、`src/`、`benchmark/`、`docs/`）见 [README.md](README.md#项目结构)。
+- **结构总览**：仓库布局（`spec/`、功能模块目录、`benchmark/`、`tests/`、`docs/`、`tools/`）见 [README.md](README.md#项目结构)。
+- **设计意图**：上述条款为何如此、同目录并列的收益与反例，见 [docs/directory-layout-rationale.md](docs/directory-layout-rationale.md)。
 
 ## 3. 命名与数据契约
 
@@ -49,6 +53,8 @@ MOPR（Monorepo Optimal Portable Runtime，单仓最优可移植运行时）是*
 
 - **边界态**：跨实现落地的数据格式与字段命名属于 Spec 契约，以 `spec/` 为准，禁止各语言实现各自定义一套；字段命名统一小写蛇形。语言命名与契约不一致处（如 Go 结构体标签），通过语言特性映射到契约字段。
 
+- **C++ 命名空间与头文件宏**：命名空间以项目名 `mopr` 为根、仓库根路径下的子目录为第二级（`distributed/id/hlc.h` → `mopr::distributed::id`，`encoding/csv.h` → `mopr::encoding::csv`）；头文件 `#ifndef` 守卫宏为 `MOPR_{大写的目录名}_{文件名}_H`（如 `MOPR_ENCODING_CSV_H`），并与 `#pragma once` 并存。完整规则见 [AGENTS.md](AGENTS.md)「C++ 命名空间与头文件宏约定」。
+
 ## 4. 文档与 AI 协同规范
 
 Spec 与模块 `.md` 文档是跨语言实现的**真理之源（Source of Truth）**：业务定义、行为契约、边界与异常处理须在文档中一次性写明，并保持与代码同步。

{mopr-0.0.67/mopr.egg-info → mopr-0.0.69.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mopr
-Version: 0.0.67
+Version: 0.0.69.dev0
 Summary: Monorepo Optimal Portable Runtime
 Author: Quant1X
 Author-email: Quant1X <wangfengxy@sina.cn>
@@ -87,17 +87,32 @@ mopr/
 ├── spec/           # 规范定义
 │   ├── api.md      # 接口契约
 │   └── behavior.md # 行为语义
-├── src/            # MOPR 实现
-│   ├── core/       # 平台无关核心
-│   └── platform/   # 平台相关极致优化
+├── base/           # 基础组件：cache / mem / mmap / cron / timestamp ...
+├── runtime/        # 运行时：ringbuffer / scheduler / once ...
+├── distributed/    # 分布式：id（HLC / 生成器 / 状态存储）
+├── encoding/       # 编码：csv / charsets / json / base64 / barcode ...
+├── storage/        # 存储抽象
+├── security/       # 安全：auth / audit / compliance
+├── machine/        # 机器标识
+├── log/            # 日志
+├── finance/        # 金融：forex / exchange
 ├── benchmark/      # 基准测试套件
 │   ├── micro/      # 微基准：吞吐、延迟、内存
 │   ├── macro/      # 场景基准：端到端性能
 │   ├── stability/  # 稳定性：长时间运行、压力、边界
 │   └── regression/ # 性能回归检测
-└── docs/           # 设计决策记录
+├── tests/          # 跨语言测试用例
+├── docs/           # 设计决策记录
+└── tools/          # 辅助工具（许可审计、许可证头）
 ```
 
+**仓库根即实现根**：不设 `src/` 层，功能模块目录直接平铺在仓库根，同一功能的多语言实现共处同一目录、同名不同后缀（如 `base/mmap.py` / `base/mmap.h` / `base/mmap.rs` / `base/mmap/mmap.go`；各语言入口 `main.cpp` / `main.rs` 同样平铺在根）。
+
+- **与 Go 的 package 对齐**：Go 的包边界以目录划分，功能模块目录因此与 Go 的 `package` 一一对应（`distributed/id` 即 `package id`）；C++ 命名空间第二级（`distributed/id/hlc.h` → `mopr::distributed::id`）、Python 子模块路径、Rust `mod` 路径均取自同一目录路径，保证同一功能在各语言的模块语义相同。
+- **平台无关核心与平台极致优化就地组织**：核心语义落在各模块的公共实现中，平台相关优化留在同一模块内，按文件名后缀（`_posix` / `_windows` / `_unsupported`）或条件编译区分，不另设 `core/` / `platform/` 目录。
+
+这些约定只服务一件事：**让同一语义在各语言占据同一位置**——看到 `mmap.py`，顺手就能看到 `mmap.h` / `mmap.rs` / `mmap/mmap.go`，跨语言对照不必先找路径。完整论证（层级为何由语言工具链决定、按语言分目录为何是反例、对 AI 的友好之处）见 [docs/directory-layout-rationale.md](docs/directory-layout-rationale.md)。
+
 ## 语言与版本要求
 
 MOPR 是单仓多语言库（monolibrary），同一份规范下将来会有多种语言实现。各语言的版本基线由本项目独立维护，不要求与同系列 `quant1x` 仓库同步：

{mopr-0.0.67 → mopr-0.0.69.dev0}/README.md

@@ -67,17 +67,32 @@ mopr/
 ├── spec/           # 规范定义
 │   ├── api.md      # 接口契约
 │   └── behavior.md # 行为语义
-├── src/            # MOPR 实现
-│   ├── core/       # 平台无关核心
-│   └── platform/   # 平台相关极致优化
+├── base/           # 基础组件：cache / mem / mmap / cron / timestamp ...
+├── runtime/        # 运行时：ringbuffer / scheduler / once ...
+├── distributed/    # 分布式：id（HLC / 生成器 / 状态存储）
+├── encoding/       # 编码：csv / charsets / json / base64 / barcode ...
+├── storage/        # 存储抽象
+├── security/       # 安全：auth / audit / compliance
+├── machine/        # 机器标识
+├── log/            # 日志
+├── finance/        # 金融：forex / exchange
 ├── benchmark/      # 基准测试套件
 │   ├── micro/      # 微基准：吞吐、延迟、内存
 │   ├── macro/      # 场景基准：端到端性能
 │   ├── stability/  # 稳定性：长时间运行、压力、边界
 │   └── regression/ # 性能回归检测
-└── docs/           # 设计决策记录
+├── tests/          # 跨语言测试用例
+├── docs/           # 设计决策记录
+└── tools/          # 辅助工具（许可审计、许可证头）
 ```
 
+**仓库根即实现根**：不设 `src/` 层，功能模块目录直接平铺在仓库根，同一功能的多语言实现共处同一目录、同名不同后缀（如 `base/mmap.py` / `base/mmap.h` / `base/mmap.rs` / `base/mmap/mmap.go`；各语言入口 `main.cpp` / `main.rs` 同样平铺在根）。
+
+- **与 Go 的 package 对齐**：Go 的包边界以目录划分，功能模块目录因此与 Go 的 `package` 一一对应（`distributed/id` 即 `package id`）；C++ 命名空间第二级（`distributed/id/hlc.h` → `mopr::distributed::id`）、Python 子模块路径、Rust `mod` 路径均取自同一目录路径，保证同一功能在各语言的模块语义相同。
+- **平台无关核心与平台极致优化就地组织**：核心语义落在各模块的公共实现中，平台相关优化留在同一模块内，按文件名后缀（`_posix` / `_windows` / `_unsupported`）或条件编译区分，不另设 `core/` / `platform/` 目录。
+
+这些约定只服务一件事：**让同一语义在各语言占据同一位置**——看到 `mmap.py`，顺手就能看到 `mmap.h` / `mmap.rs` / `mmap/mmap.go`，跨语言对照不必先找路径。完整论证（层级为何由语言工具链决定、按语言分目录为何是反例、对 AI 的友好之处）见 [docs/directory-layout-rationale.md](docs/directory-layout-rationale.md)。
+
 ## 语言与版本要求
 
 MOPR 是单仓多语言库（monolibrary），同一份规范下将来会有多种语言实现。各语言的版本基线由本项目独立维护，不要求与同系列 `quant1x` 仓库同步：

{mopr-0.0.67 → mopr-0.0.69.dev0}/base/__init__.py

@@ -11,7 +11,7 @@ base 各单文件模块的公共函数与类型经 __init__ 直接导出, 业务
 """
 
 # 模块对象保留为包属性; environment 依赖 filesystem, 故 filesystem 在前
-from . import cron, dataclass_utils, environment, filesystem, region, strings, time, timestamp
+from . import cron, dataclass_utils, environment, filesystem, mmap, region, strings, time, timestamp
 
 # cron
 from .cron import CronExpr, make_cron, resolve_timezone
@@ -21,6 +21,8 @@ from .dataclass_utils import get_field_names
 from .filesystem import expand_user, homedir, mkdirs, touch, update_file_mtime
 # environment
 from .environment import app_entry, env, getuser, read_dotenv
+# mmap (MappedMemory / MmapHandle 名称过于通用, 连同两层 API 一并保留在 mopr.base.mmap 内)
+from .mmap import MmapError, mmap_open
 # time
 from .time import from_rfc1123, get_quarter_by_date, get_timezone_offset_standard, to_rfc1123
 # timestamp
@@ -41,6 +43,8 @@ __all__ = [
     "expand_user", "homedir", "mkdirs", "touch", "update_file_mtime",
     # environment
     "app_entry", "env", "getuser", "read_dotenv",
+    # mmap
+    "MmapError", "mmap_open",
     # time
     "from_rfc1123", "get_quarter_by_date", "get_timezone_offset_standard", "to_rfc1123",
     # timestamp