feat(oa): add permission-controlled shared finance remarks to done center

Share one finance remark per approval instance across Web and mobile. Require the explicit permission and the current tenant user's own done task for every read and write; keep general instance responses free of financial remarks. Add idempotent MySQL migration without automatic role grants, cross-end editors, isolated backend and frontend tests, and rollout requirements. Refs #7; platform validation and target database migration remain pending.
2026-10-30 20:42:05 +08:00
1 parent 86df360f35
commit 0e64b413ce
@@ -0,0 +1,12 @@
+# 设计
+
+`oa_instance.finance_remark VARCHAR(512)` 保存实例级备注，通用实例序列化不输出该字段。专用服务按真实用户租户、显式菜单权限及本人有效已办任务查询实例；审批任务状态沿用 approved/rejected/returned/transferred，软删任务/实例和其他租户不可访问。
+
+GET `/web/admin/oa-approval/tasks/done` 在 data 增加 `canManageFinanceRemark`。有权限时只给可访问实例行增加 `financeRemark`；无权限不返回字段。GET/PUT `/web/admin/oa-approval/instances/{id}/finance-remark` 返回 `{instanceId, financeRemark}`，PUT 接收 `{financeRemark: string}`，拒绝额外字段、超长和非字符串输入，允许空串清空。权限不足 403、实例不在本人已办范围 404。更新记录 update_by/update_time 并保留既有请求审计。
+
+各端采用后端能力标记，不依赖角色名称或仅前端隐藏。打开弹窗时重新读取最新备注，保存后刷新列表；取消不写入，失败保留编辑内容。文字按纯文本渲染。单字段最后成功保存值生效。
+
+简单列表字段和编辑交互沿用既有 OA/通用弹窗，无需另造复杂 UI 或 Figma 原型。权限菜单放在已办中心下，Web/移动对应菜单可用同一权限码，不自动授予角色。
+
+## 验证
+SQLite 隔离集成测试真实角色/菜单/任务：允许、拒绝、跨租户、伪造租户、无本人已办、软删/停用、角色/职位并集、保存读取清空、超长、非字符串、其他中心不泄露。各端 UI 行为检查和构建；uni-app HBuilderX 编译及可用平台检查。缺失环境如实记录，必要验证未完成前不关单。
@@ -0,0 +1,15 @@
+# OA 已办中心财务备注
+
+关联 Gitea #7。用户已确认 Web 和所有相关移动端、单一权限控制读写、同一审批实例共用备注、仍限本人已办单据。
+
+## Why
+已办列表缺少受控的财务补充说明入口。
+
+## What Changes
+- 审批实例新增独立财务备注（最多 512 字，可清空），不复用表单内容、审批意见或其他业务财务字段。
+- 权限 `oa:done:finance-remark` 控制读写，使用有效角色并集；无权限不返回内容。
+- Web 列表列和编辑弹窗、小程序/uni-app 已办卡片和编辑入口共用后端契约。mobile-oa-h5 当前只承载审批详情，不新增需求外的详情字段。
+- 新增 MySQL 5.7 结构迁移及可重复执行的菜单种子，部署先迁移后更新代码；不自动赋权。
+
+## Impact
+涉及 backend、web-admin、mobile-h5 和 docs/sql。原有已办筛选、分页、审批流程和其他中心返回保持原语义。mobile-oa-h5 的跳转与详情兼容性需回归检查。
@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: 实例级财务备注
+系统 SHALL 为同一审批实例保存一份最多 512 字的纯文本财务备注，允许修改与清空，各端共享；不改变审批意见或业务表单。
+
+#### Scenario: 已授权用户保存
+- **WHEN** 具备 `oa:done:finance-remark` 权限且有该实例有效已办任务的用户保存备注
+- **THEN** 记录备注、修改人和修改时间，其他有权限的相关已办用户读取同一份值，空串清空，超长拒绝。
+
+### Requirement: 权限与数据隔离
+系统 SHALL 按当前有效用户的真实租户及直接/职位继承有效角色并集校验显式权限。菜单权限不扩大本人已办数据范围。
+
+#### Scenario: 无权限或越权
+- **WHEN** 用户无该权限、无本人有效已办任务、访问其他租户或软删实例
+- **THEN** 拒绝读写；无权限的列表及其他通用实例接口不返回财务备注。
+
+### Requirement: 跨端已办入口
+系统 SHALL 在 Web 已办表格和 uni-app 已办卡片提供财务备注展示及编辑入口，以后端能力判定可见性；保留原有跳转、筛选和分页。
+
+#### Scenario: 打开和保存编辑器
+- **WHEN** 有权限的用户打开编辑器
+- **THEN** 读取最新备注；保存成功刷新列表，取消不写入，失败保留输入并提示；无权限用户看不到字段和编辑入口。
@@ -0,0 +1,13 @@
+# 实施与验证计划
+
+关联 Gitea #7；Web 与所有相关移动端，同一审批实例共用备注，单一权限控制查看和修改。默认 Agent 验证。
+
+- [x] 后端：新增真实权限、本人已办、租户隔离、共享读写与拒绝输入测试；实现独立财务备注服务、模型和 API。新增 32 项测试通过，OA 全部回归 314 项通过。
+- [x] 迁移：新增 MySQL 5.7 字段及对应已办菜单下按钮权限，不默认赋权；隔离 MySQL 5.7.24 连续执行两次通过，更新数据库变更入口。
+- [x] 前端：Web 列表列与编辑弹窗、uni-app 卡片与编辑入口；23 项行为测试通过，包含最新值、保存/取消/失败、清空、权限隐藏、纯文本和页面切换竞态。
+- [x] 静态与构建：OpenSpec 严格校验、字段链路、git diff 格式检查、Web 生产构建及 HBuilderX 微信小程序和 H5 编译通过。Web 构建使用 4 GB Node 堆；H5 验证复用现有 Sass 依赖，临时依赖不入库。字段一致性工具报告 5 项已知旧路径/映射警告、0 错误，OA 新字段另行逐层核对。
+- [x] 审查：独立规格与代码质量审查通过，无阻塞项。
+- [x] H5 页面验证：编译产物在 375px 浏览器中验证展示、读取最新值、取消、保存、纯文本、失败保留、清空和无权限隐藏；模拟接口，无业务数据写入，无页面异常。
+- [ ] 微信平台验证：开发者工具要求重新登录，等待用户完成；浏览器验证不代替微信平台验证。
+- [ ] 迁移安排：业务配置指向远程数据库，尚未执行迁移；等待用户确认测试库授权或由用户执行。更新应用前必须完成迁移，再由管理员授予角色权限。
+- [ ] 交付：推送任务分支和 PR；必要验证及迁移条件满足后核对最新 V2.0，合并推送并同步本地主分支，回写验收结果和合并提交后关闭 #7。当前保持工单开放，不打 tag、不部署、不启停服务。