# 源码模块与修改入口地图

本页将目录、关键文件、跨模块依赖和验证入口对应起来，便于定位变更边界。路径均相对其所属仓库，不代表公开源码下载授权。App 仓库含 iOS、Android、聊天和加密核心；Account 另有当前维护的主仓库，App 工作树附带的 `identity/` 是历史快照。二者不能以目录同名认定版本相同，更不能把旧副本整体覆盖到共享服务。

## 从需求定位负责层

| 需求或故障 | 首要入口 | 继续追踪的依赖 |
| --- | --- | --- |
| 启动页、导航、默认页面 | iOS App／Home，Android MainActivity／StarlineDesign | 本机偏好、页面状态与生命周期 |
| 登录、取消、回跳与重开 | ChatNativeAuth／ChatAuthenticator，Android NativeAuth | ChatAPI／ServiceApi、聊天授权路由、当前 Account OIDC |
| 好友、群、消息、已读与删除 | ChatStore／AppState、聊天 server／database | 关系权限、个人历史边界、事件刷新 |
| 新事、评论、可见性与视频 | MomentsStore／MomentsScreens、moments-repository | 聊天身份、独立媒体与成员关系 |
| 本机任务、收藏与最近访问 | LocalWorkspaceStore／WorkScreens、LocalData | 本机文件／偏好，非企业服务 |
| 记忆、模板与附件 | MemoryStore／MemoryTemplates、MemoryScreens | 设备密钥、格式兼容、本机识别与搜索 |
| 定位、城市与实时共享 | 城市 resolver／ChatLocation／LiveLocationService | 系统权限、目录、IP 城市及显式共享状态 |
| 通话与来电 | ChatCallCoordinator／CallScreen、calls 仓储 | LiveKit、APNs、系统能力、有效 session |
| MLS 独立协议 | ChatEncryptedTransport／chat-crypto／e2ee-delivery | 密钥包、设备身份固定、checkpoint、成员状态机 |

优先沿现有领域入口修改，不直接在视图里另建网络客户端、会话或持久化。页面隐藏只影响展示，服务端授权仍须在资源入口检查；双端使用同一业务服务也不代表本机实现和数据格式一致。

## iOS 文件职责

| 相对路径 | 职责与修改注意事项 |
| --- | --- |
| `ios-app/project.yml`、`StarlineWorkbench.xcodeproj` | XcodeGen 配置与实际工程；新增文件、资源和能力后核对二者 |
| `Sources/App/StarlineWorkbenchApp.swift` | Store 创建、系统来电桥、前后台与 URL 回调分发 |
| `Sources/Features/Home/HomeView.swift` | 根页面组织、本机工作台入口与偏好；不要混入服务端企业权限 |
| `Sources/Features/Chat/ChatAPI.swift`、`ChatModels.swift` | HTTP、解码、错误与 Debug base URL；服务字段改动需同步模型 |
| `ChatNativeAuth.swift`、`ChatAuthenticator.swift`、`ChatKeychain.swift` | PKCE／pending、系统授权会话与安全存储；检查取消、进程恢复和提交顺序 |
| `ChatStore.swift` | 账号、关系、消息、pending、已读、事件与位置业务协调；异步操作核对当前账号和范围 |
| `ChatComposer.swift`、`ChatThreadView.swift`、`GroupThreadView.swift` | 输入、附件、消息展示及目标会话；文件上传与消息引用是两步 |
| `ChatCallCoordinator.swift`、`ChatCallView.swift`、`CallSystemBridge.swift` | 媒体与系统通话桥接；信令 active 不等于轨道可用 |
| `CityStickerSelection.swift`、`CityStickerDeviceLocator.swift` | 设备城市、IP／手选优先级、缓存与迟到响应保护 |
| `ChatCryptoDevice.swift`、`ChatCryptoTrustStore.swift`、`ChatEncryptedTransport.swift` | 独立 MLS 核心包装、设备公钥固定和加密投递；不等于主消息全部接入 |
| `Sources/Features/Moments/` | 新事模型、Store、发布、详情和媒体；与普通聊天媒体契约分开 |
| `Sources/Data/MemoryStore.swift`、`MemoryVaultCrypto.swift` | 加密索引、附件、迁移、写入顺序与损坏保护 |
| `MemoryLocalRecognizer.swift`、`MemoryLocalSearch.swift` | 本机推荐与搜索；系统模型可用性与本机回退 |
| `Sources/Domain/MemoryTemplate.swift`、`MemoryGeneratedSchema.swift` | 固定模板、字段、长度与生成结构兼容 |
| `Sources/Features/Profile/MemoryExportDocument.swift` | 额外授权后的本机明文输出与临时文件清理 |
| `Sources/Data/LocalWorkspaceStore.swift` | 本机任务、收藏、最近访问的原子快照 |
| `Sources/Features/Scanner/`、`Browser/` | 相机／相册识别、网页、账号确认浏览会话 |

除完整路径的表项外，Chat 文件均位于 `ios-app/Sources/Features/Chat/`，Data 文件位于 `ios-app/Sources/Data/`。界面改动检查真实视口、键盘、大字号与辅助技术语义；资源名称存在不代表已放进当前 target。当前主设备族是 iPhone，没有 watchOS target，iPad 审核仍需独立验收。

## Android 文件职责

下表文件位于 `android-app/app/src/main/java/cn/thestarline/workbench/`。

| 文件 | 职责与联动范围 |
| --- | --- |
| `MainActivity.kt`、`StarlineDesign.kt` | Activity、Intent、根 Compose 布局、导航与系统 inset |
| `AppState.kt` | 当前账号、页面、事件循环、业务请求、通话与位置协调；注意协程取消和迟到结果 |
| `AppData.kt` | ServiceApi、错误、SecureFile、LocalData；任务偏好与加密会话／记忆分类不同 |
| `NativeAuth.kt` | verifier、state、目标 URL、回调与 pending；没有 Debug 本地 Account 例外 |
| `MessageSendIdCoordinator.kt` | 未确认发送的 clientId 复用；确认、换账号和换范围要保持隔离 |
| `ChatScreens.kt`、`ChatManagementScreens.kt`、`ChatMediaBubble.kt` | 消息、群、关系菜单、附件读取；引用权限来自服务端 |
| `MomentsScreens.kt` | 新事流、评论、通知、图片／视频发布与播放 |
| `CallScreen.kt`、`CallMediaControls.kt` | 运行时权限、LiveKit 控件与输出轨道；绑定当前通话 generation |
| `LiveLocationService.kt`、`LiveLocationPanel.kt`、`ChatLocation.kt` | 显式共享、前台服务、地图与更新时间；停止采集和删除共享要协调 |
| `CitySticker.kt`、`CityStickerLocation.kt`、`CityStickerSheet.kt` | 城市匹配、短时定位、IP 回退、手选、缓存与发送目标检查 |
| `MemoryTemplates.kt`、`MemoryScreens.kt` | 固定主题、关键词、编辑、搜索和旧字段保留 |
| `MemoryExport.kt`、`MemoryExportDocument.kt` | 一次性授权、生成输出、系统保存位置与取消清理 |
| `WorkScreens.kt`、`ProfileScreens.kt`、`AccountExtras.kt` | 工作台、本机任务／收藏、设置与账号展示 |
| `ScannerScreen.kt`、`ScanCameraPreview.kt` | CameraX、ML Kit、图片与手动输入 |

配置还分布在 `app/build.gradle.kts`、主／Debug `AndroidManifest.xml` 与资源目录。主清单关闭自动备份并禁止明文网络，Debug 另允许本地 API；这一网络例外不改变原生授权 URL 信任。当前 Kotlin、AGP、Gradle 和 JDK 组合应实际验证，不能把工具链声明直接当作可构建保证。

## 聊天与加密服务

| 相对路径 | 职责 |
| --- | --- |
| `chat-service/src/main.mjs` | 环境变量、生产启动条件、监听和信号退出 |
| `src/server.mjs` | HTTP 解析、授权、资源路由、长轮询、模型桥接与定时协调 |
| `src/database.mjs` | SQLite 表、启动迁移、事务、关系、消息、媒体、事件与设备会话 |
| `src/moments-repository.mjs` | 新事可见范围、互动、通知、媒体与孤立资源清理 |
| `src/call-repository.mjs`、`call-media.mjs` | 通话状态与参与者、媒体 token、房间和成员清理 |
| `src/apns-voip.mjs`、`voip-devices.mjs` | APNs 签名发送、设备与 session 关联；提供商接受不等于设备到达 |
| `src/city-location.mjs`、`city-stickers.mjs` | 可信来源与离线城市、白名单素材和媒体去重 |
| `src/memory-recognition.mjs` | 配置模型的结构生成与固定补充；请求文字会离开设备 |
| `src/e2ee-verifier.mjs`、`e2ee-delivery.mjs` | WASM 结构校验与设备密钥包、范围、密文、ack 状态 |
| `src/enterprise-*`、`src/enterprise/` | 共享后台的独立星企领域；不构成星线 App 个人前台功能 |
| `chat-crypto/src/`、`include/`、`scripts/` | Rust OpenMLS、C ABI、平台与 WASM 构建；状态快照与设备私钥由端侧保护 |

表中 `src/` 均相对 `chat-service/`。媒体 BLOB 与消息元数据存于同一 SQLite 数据集；数据库构造会迁移，不能为了检查 schema 随意用新服务打开真实旧库。恢复测试使用副本和配套密钥，见[故障手册](https://document.thestarline.cn/app/incident-runbooks.md)。

## Account 权威源与历史副本

Account 的当前 `server/config.ts`、`store.ts`、`notify.ts`、`captcha.ts`、`oidc.ts`、`admin-policy.ts` 与 `main.ts` 分别定义配置、MySQL／PII、投递、人机验证、协议、管理策略与启动。现行代码还包含资料、扫码／手机授权、小程序、实名与开放接口等模块；这些不能凭 App 历史副本的文件清单推断缺失。

目前可确认的差异有：主迁移为 001–007 并有 PII 加密审批；生产邮件为腾讯 SES、短信为阿里云；管理员通行密钥开关由环境精确值读取；开发注册也有 captcha 门禁。App 副本中的本地聊天客户端登记脚本在当前 Account 主仓库不存在，旧注册 fixture 也没有新的 captcha 请求字段。应先修订隔离夹具并验证，不能称为现成一键联调。记忆转出 redeem 契约在当前主源码缺失，不能用旧副本证明跨服务可用。

修改共享身份时，应在当前 Account 仓库执行其类型与测试检查；修改 App 侧协议时同时核对目标部署的实际契约。两个仓库的版本和授权是独立边界，文档发布不等于身份服务升级，文件拷贝也不是协议迁移方案。

## 修改入口与验证命令

| 修改类型 | 最少关联入口 | 进一步验证 |
| --- | --- | --- |
| 原生授权 | iOS `ChatNativeAuthTests`、Android `NativeAuthTest`、服务端 native-auth | 系统浏览器、取消、冷启动、401／断网与真实目标平台 |
| 发送与关系 | chat、group、management、media 测试；双端发送状态 | 丢响应重试、三账号拒绝、删除历史和双端已读 |
| 新事 | moments 测试与两端发布／媒体界面 | 可见范围、屏蔽、视频 Range、取消与孤立资源 |
| 本机记忆 | MemoryLocal／MemoryStore、MemoryTemplates／MedicalMemory | 损坏库、丢密钥、旧字段、多行、附件与重开 |
| 城市／位置 | city-location、city-stickers、live-location 及原生 resolver | 权限拒绝、缓存、换账号／会话、停止、前后台 |
| 通话 | calls、call-media、apns-voip、voip-devices | 两台真机音画、跨网、后台、锁屏与多设备 |

真实命令入口示例，本次未执行：

```sh
node --test chat-service/tests/native-auth.test.mjs
node --test chat-service/tests/group.test.mjs chat-service/tests/management.test.mjs
node --test chat-service/tests/memory.test.mjs chat-service/tests/moments.test.mjs
zsh ios-app/scripts/test-native-auth.sh
```

```sh
cd android-app
./gradlew :app:testDebugUnitTest --max-workers=1
```

```sh
cd identity
npm run typecheck
npm test
npm --prefix client run typecheck
```

最后一组必须在当前 Account 源码上下文执行。文档统一构建入口位于 `technical-docs/build.mjs`、`technical-docs/check.mjs`；App 的内容与导航继续从 `app-download/docs/` 读取，作为全产品文档站的一个产品目录。构建只处理公开静态资料，不运行产品后台。它们的通过只能说明文档产物，不能成为业务验收。完整模块×故障矩阵见[测试矩阵](https://document.thestarline.cn/app/qa-matrix.md)，配置与发行门禁见[配置参考](https://document.thestarline.cn/app/configuration-reference.md)和[发行清单](https://document.thestarline.cn/app/release-checklist.md)。