Add skills-lock.json to manage skill dependencies for drawio-skill and prd
This commit is contained in:
Guangfei.Zhao
@@ -4,26 +4,26 @@ Continental Retail APP 相关的文档参考仓库，用于沉淀架构决策、
|
||||
|
||||
## 目录说明
|
||||
|
||||
### App 架构决策文档
|
||||
### flutter-app/
|
||||
|
||||
Flutter APP 的分包、分层、技术选型等决策记录，按序号阅读：
|
||||
|
||||
| 文档 | 内容 |
|
||||
| --- | --- |
|
||||
| [01-project-structure.md](./01-project-structure.md) | 工程结构 / 分包策略（Melos monorepo） |
|
||||
| [02-layering.md](./02-layering.md) | 分层架构规范（presentation/domain/data） |
|
||||
| [03-state-management.md](./03-state-management.md) | 状态管理方案（Riverpod） |
|
||||
| [04-routing.md](./04-routing.md) | 路由方案（go_router） |
|
||||
| [05-networking.md](./05-networking.md) | 网络层设计（dio） |
|
||||
| [06-local-storage.md](./06-local-storage.md) | 本地存储方案（Drift / secure storage / shared_preferences） |
|
||||
| [07-native-integration.md](./07-native-integration.md) | 原生能力集成方式（Pigeon） |
|
||||
| [08-build-flavors.md](./08-build-flavors.md) | 多环境构建（dev/uat/prod flavor） |
|
||||
| [09-testing.md](./09-testing.md) | 测试策略（单元/Widget/集成测试） |
|
||||
| [10-webview-h5.md](./10-webview-h5.md) | Embedded H5 容器与 JSBridge（PRD 第 7 章核心链路） |
|
||||
| [11-store-context-and-session.md](./11-store-context-and-session.md) | 门店上下文与会话管理（切店级联失效、登出清理） |
|
||||
| [12-error-and-api-contract.md](./12-error-and-api-contract.md) | 错误处理与 API 契约（`ApiResult`、异常体系、降级） |
|
||||
| [13-observability-analytics.md](./13-observability-analytics.md) | 可观测性与埋点（Sentry 崩溃上报、神策客户端埋点、日志脱敏） |
|
||||
| [14-conventions-and-ci-gates.md](./14-conventions-and-ci-gates.md) | 工程规范与 CI 门禁（lint、格式化、分支、流水线卡点） |
|
||||
| [01-project-structure.md](./flutter-app/01-project-structure.md) | 工程结构 / 分包策略（Melos monorepo） |
|
||||
| [02-layering.md](./flutter-app/02-layering.md) | 分层架构规范（presentation/domain/data） |
|
||||
| [03-state-management.md](./flutter-app/03-state-management.md) | 状态管理方案（Riverpod） |
|
||||
| [04-routing.md](./flutter-app/04-routing.md) | 路由方案（go_router） |
|
||||
| [05-networking.md](./flutter-app/05-networking.md) | 网络层设计（dio） |
|
||||
| [06-local-storage.md](./flutter-app/06-local-storage.md) | 本地存储方案（Drift / secure storage / shared_preferences） |
|
||||
| [07-native-integration.md](./flutter-app/07-native-integration.md) | 原生能力集成方式（Pigeon） |
|
||||
| [08-build-flavors.md](./flutter-app/08-build-flavors.md) | 多环境构建（dev/uat/prod flavor） |
|
||||
| [09-testing.md](./flutter-app/09-testing.md) | 测试策略（单元/Widget/集成测试） |
|
||||
| [10-webview-h5.md](./flutter-app/10-webview-h5.md) | Embedded H5 容器与 JSBridge（PRD 第 7 章核心链路） |
|
||||
| [11-store-context-and-session.md](./flutter-app/11-store-context-and-session.md) | 门店上下文与会话管理（切店级联失效、登出清理） |
|
||||
| [12-error-and-api-contract.md](./flutter-app/12-error-and-api-contract.md) | 错误处理与 API 契约（`ApiResult`、异常体系、降级） |
|
||||
| [13-observability-analytics.md](./flutter-app/13-observability-analytics.md) | 可观测性与埋点（Bugly 崩溃上报、神策埋点与错误看板、日志脱敏） |
|
||||
| [14-conventions-and-ci-gates.md](./flutter-app/14-conventions-and-ci-gates.md) | 工程规范与 CI 门禁（lint、格式化、分支、流水线卡点） |
|
||||
|
||||
首版范围为 **Android / iOS**，鸿蒙 OHOS 不在首版内（但 SDK 基线锁 3.44.9 是为后续 OHOS 适配留窗口，见 01 和 07）。
|
||||
|
||||
@@ -49,7 +49,7 @@ Flutter APP 的分包、分层、技术选型等决策记录，按序号阅读
|
||||
|
||||
| 文档 | 内容 |
|
||||
| --- | --- |
|
||||
| [prd/Continental-Retail-APP-PRD.md](./prd/Continental-Retail-APP-PRD.md) | Continental Retail APP PRD V1.0 —— 20 个模块、191 条编号需求、173 张图、65 张表。**自包含文档**，不引用本仓库其它 md，可直接转 Word |
|
||||
| [prd/Continental-Retail-APP-PRD.md](./prd/Continental-Retail-APP-PRD.md) | Continental Retail APP PRD V1.0 —— 20 个模块、192 条编号需求、173 张图、43 张表。需求描述与编号需求以文本书写（表格只用于字段清单、矩阵与统计）。**自包含文档**，不引用本仓库其它 md，可直接转 Word |
|
||||
|
||||
同目录下的 `images/`（自 `origin-prd` 抢救的 F6 与后台原型图）、`app-design-images/`（设计稿）、`mini-program-images/{O2O,ROOS,Warranty}/`（现状小程序截图）为其图源。
|
||||
|
||||
@@ -91,14 +91,14 @@ V1.0 相对 V0.9 的主要变化：修复第 4 章编号断裂、将「我的」
|
||||
| # | 差异 | 前期材料 | 实际结论 | V1.0 处置 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | 技术路线 | `Architecture-Diagram/202606-Continental-Retail-APP-PRD.md` 表头写「主技术路线 React Native / 备选 Flutter」 | 实际选型是 **Flutter**，01-14 全部基于 Flutter | ✅ 文档控制表已写 Flutter（PRD C4） |
|
||||
| 2 | 扫码归属 | 202606 PRD 第 11.5 节 与 `Architecture-Diagram/202606-Conti-Retail-APP-Component-data-source.md` 写成「嵌入 F6 扫码页」 | 扫码是 **App 原生实现**（`native_scan`），同时服务 `feature_scan` 和 H5 的 JSBridge，见 [07](./07-native-integration.md) 和 [10](./10-webview-h5.md) | ✅ PRD REQ-INT-003 已校正（PRD C5） |
|
||||
| 3 | JSBridge 能力数 | 计划稿记 13 项、202606 PRD 记 12 项 | 以 [10](./10-webview-h5.md) 为准：表格 **13 行**，因 `toast`/`dialog`/`loading` 合并为一行，实际 `method` 名共 **15 个** | ✅ PRD 第 7.3 节的 JSBridge 能力清单已按此重述 |
|
||||
| 2 | 扫码归属 | 202606 PRD 第 11.5 节 与 `Architecture-Diagram/202606-Conti-Retail-APP-Component-data-source.md` 写成「嵌入 F6 扫码页」 | 扫码是 **App 原生实现**（`native_scan`），同时服务 `feature_scan` 和 H5 的 JSBridge，见 [07](./flutter-app/07-native-integration.md) 和 [10](./flutter-app/10-webview-h5.md) | ✅ PRD REQ-INT-003 已校正（PRD C5） |
|
||||
| 3 | JSBridge 能力数 | 计划稿记 13 项、202606 PRD 记 12 项 | 以 [10](./flutter-app/10-webview-h5.md) 为准：表格 **13 行**，因 `toast`/`dialog`/`loading` 合并为一行，实际 `method` 名共 **15 个** | ✅ PRD 第 7.3 节的 JSBridge 能力清单已按此重述 |
|
||||
|
||||
## 待补充
|
||||
|
||||
- API 文档
|
||||
- `15-ui-design-system.md` — `core_ui` 的 Material 3 主题、设计 token、暗色模式（对应 PRD 第 8.2 节统一交互规则）
|
||||
- `16-i18n.md` — 首版单语言，但需预留 `flutter_localizations` + `intl` 结构（后补代价高）
|
||||
- `flutter-app/15-ui-design-system.md` — `core_ui` 的 Material 3 主题、设计 token、暗色模式（对应 PRD 第 8.2 节统一交互规则）
|
||||
- `flutter-app/16-i18n.md` — 首版单语言，但需预留 `flutter_localizations` + `intl` 结构（后补代价高）
|
||||
|
||||
## 跨文档的阻塞项
|
||||
|
||||
@@ -106,23 +106,28 @@ V1.0 相对 V0.9 的主要变化：修复第 4 章编号断裂、将「我的」
|
||||
|
||||
| 阻塞项 | 出处 | 影响 |
|
||||
| --- | --- | --- |
|
||||
| **iOS 构建链路不成立** | [08](./08-build-flavors.md) | 现有 GitLab Runner 是与后端共用的 Linux runner，`flutter build ipa` 需要 macOS。需决策自建 mac runner / 云端 mac runner / iOS 手工出包 |
|
||||
| **后端错误码表未定** | [12](./12-error-and-api-contract.md)、[backend/06](./backend/06-api-design.md) | 客户端无法对错误码做分支处理，只能全部走默认文案 |
|
||||
| **Sentry 自建还是 SaaS 未定** | [13](./13-observability-analytics.md) | 崩溃平台已定为 Sentry（Bugly 无法还原 Dart 混淆堆栈，而我们的异常绝大多数是 Dart 异常）。但 `sentry.io` SaaS 属于数据出境且门店网络可达性存疑，自建则需要内网资源和运维承接方——需明确 |
|
||||
| **神策服务是否可用未确认** | [13](./13-observability-analytics.md) | 客户端埋点定为神策（团队有经验、官方插件在维护），但本项目**没有现成账号**。公司若未在用，开通是采购流程而非配置项。**不阻塞开工**——事件方案和 `core_analytics` 接口先做，两者与 SDK 无关；实在走不通再换自建 endpoint |
|
||||
| **内测分发渠道未定** | [08](./08-build-flavors.md) | Firebase App Distribution 国内可达性存疑，需选替代方案 |
|
||||
| **车牌识别技术路径未验证** | [07](./07-native-integration.md) | 通用扫码库只能解条码/二维码，VIN 印刷字符和车牌需要 OCR，车牌可能需要商用 SDK |
|
||||
| **神策服务是否可用未确认** | [13](./flutter-app/13-observability-analytics.md) | 客户端埋点定为神策，**且崩溃明细看板也要建在神策上**（见下方已解决表），但本项目**没有现成账号**。公司若未在用，开通是采购流程而非配置项。**不阻塞开工**——事件方案和 `core_analytics` 接口先做，两者与 SDK 无关；实在走不通，埋点和错误明细都要另找落点 |
|
||||
|
||||
### 已解决（2026-08 技术决策）
|
||||
|
||||
| 原阻塞项 | 结论 | 出处 |
|
||||
| --- | --- | --- |
|
||||
| iOS 构建链路不成立 | **远程一台 Mac 出包**。首版手工执行仓库内的 `scripts/build_ios.sh`；后续把这台 Mac 注册成 GitLab Runner（`macos` tag）接进流水线。构建命令必须来自仓库脚本，符号表/dSYM 要带回归档 | [08](./flutter-app/08-build-flavors.md) |
|
||||
| 后端错误码表未定 | **分段方案 + 一组基础码现在定死，业务码在开发对应模块时随接口增补**，不集中排期。客户端默认展示后端 `message`，只有需要特殊 UX 的码才进 `ApiCode` | [12](./flutter-app/12-error-and-api-contract.md)、[backend/06](./backend/06-api-design.md) |
|
||||
| Sentry 自建还是 SaaS 未定 | **不引入 Sentry**。崩溃走**现有的腾讯 Bugly**（原生崩溃/ANR），错误明细与看板走**神策自定义事件 `app_error` + 在神策上二次开发**。连带决策：**release 不开 `--obfuscate`**（两者都还原不了混淆后的 Dart 堆栈），只保留 `--split-debug-info` | [13](./flutter-app/13-observability-analytics.md)、[08](./flutter-app/08-build-flavors.md) |
|
||||
| 内测分发渠道未定 | **不用 Firebase**。Android 走自建/公司托管的 OTA 分发页，iOS 走 TestFlight；后续可能并入管理后台的「APP 发布管理」，把分发、版本检查、强制升级一起收口 | [08](./flutter-app/08-build-flavors.md) |
|
||||
| 车牌识别技术路径未验证 | **用付费的阿里云 OCR（`RecognizeLicensePlate`）**，拍照上传换识别结果，不做端侧模型。**客户端不直连**，由后端代理（AK/SK 不下发、图片经 OSS 中转）。交互随之从"取景框自动识别"变为"拍一张照"，且弱网下不可用——手工输码是常驻并列入口 | [07](./flutter-app/07-native-integration.md)、[backend/05](./backend/05-integration-layer.md) |
|
||||
|
||||
### 已解决（2026-08 后端文档评审）
|
||||
|
||||
| 原待确认项 | 结论 | 出处 |
|
||||
| --- | --- | --- |
|
||||
| 数据库选型未定 | **MySQL 8.4**（UAT/Prod 用 Azure Database for MySQL Flexible Server + Private Endpoint） | [backend/03](./backend/03-persistence.md)、[backend/09](./backend/09-build-deploy.md) |
|
||||
| `X-Trace-Id` 请求头契约未定 | 客户端传 32 位小写 hex；服务端校验通过则复用，否则忽略并自行生成，最终值在响应头和 `ApiResult.traceId` 里回写 | [backend/08](./backend/08-observability.md)、[05](./05-networking.md) |
|
||||
| `X-Trace-Id` 请求头契约未定 | 客户端传 32 位小写 hex；服务端校验通过则复用，否则忽略并自行生成，最终值在响应头和 `ApiResult.traceId` 里回写 | [backend/08](./backend/08-observability.md)、[05](./flutter-app/05-networking.md) |
|
||||
| 分页参数约定未定 | `pageNum`（1 起）/ `pageSize`（≤100）/ `sort`（白名单），响应含 `hasMore` | [backend/06](./backend/06-api-design.md) |
|
||||
| 集成层同步还是响应式 | **同步 `RestClient`**，不引入 WebClient/Mono | [backend/05](./backend/05-integration-layer.md) |
|
||||
|
||||
后端错误码表仍未定（见上表阻塞项）：分段规则已在 [backend/06](./backend/06-api-design.md) 定好，缺的是各业务域把自己的码填进去。
|
||||
上面几条都留了各自的收尾工作，散在对应文档的「待确认项」里：车牌识别的置信度阈值与图片压缩参数、OCR 调用量与计费口径、关掉混淆后的安全侧确认、Mac Runner 接入流水线的时点。
|
||||
|
||||
## 语言约定
|
||||
|
||||
|
||||
Reference in New Issue
Block a user