feat: update wallet punch point and report success

suixinkan/UI/PunchPoint/PunchPointDetailViewController.swift

@@ -0,0 +1,573 @@
+//
+//  PunchPointDetailViewController.swift
+//  suixinkan
+//
+
+import Kingfisher
+import Photos
+import SnapKit
+import UIKit
+
+/// 打卡点详情页，对齐 Android `PunchPointDetailScreen`。
+final class PunchPointDetailViewController: BaseViewController {
+    private let viewModel: PunchPointDetailViewModel
+    private let api: any PunchPointAPIProtocol
+
+    private let mapView = PunchPointMapView()
+    private let zoomStack = UIStackView()
+    private let zoomInButton = PunchPointMapControlButton(symbol: "plus")
+    private let zoomOutButton = PunchPointMapControlButton(symbol: "minus")
+    private let locateButton = PunchPointMapControlButton(symbol: "location.fill")
+    private let cardView = UIView()
+    private let scrollView = UIScrollView()
+    private let contentStack = UIStackView()
+    private let bottomBar = UIView()
+    private let editButton = UIButton(type: .system)
+    private let emptyContainer = UIStackView()
+    private let emptyLabel = UILabel()
+    private let retryButton = UIButton(type: .system)
+
+    var onChanged: (() -> Void)?
+
+    /// 初始化打卡点详情页。
+    init(
+        punchPointId: Int64,
+        viewModel: PunchPointDetailViewModel? = nil,
+        api: (any PunchPointAPIProtocol)? = nil
+    ) {
+        self.viewModel = viewModel ?? PunchPointDetailViewModel(punchPointId: punchPointId)
+        self.api = api ?? NetworkServices.shared.punchPointAPI
+        super.init(nibName: nil, bundle: nil)
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    override func setupNavigationBar() {
+        title = "打卡点详情"
+    }
+
+    override func setupUI() {
+        view.backgroundColor = AppColor.pageBackground
+
+        zoomStack.axis = .vertical
+        zoomStack.spacing = 0
+        zoomStack.addArrangedSubview(zoomInButton)
+        zoomStack.addArrangedSubview(zoomOutButton)
+        cardView.backgroundColor = .white
+        cardView.layer.cornerRadius = 12
+        cardView.clipsToBounds = true
+        scrollView.showsVerticalScrollIndicator = false
+        contentStack.axis = .vertical
+        contentStack.spacing = 12
+        bottomBar.backgroundColor = .white
+        editButton.setTitle("去编辑", for: .normal)
+        editButton.setTitleColor(.white, for: .normal)
+        editButton.titleLabel?.font = .systemFont(ofSize: 16, weight: .medium)
+        editButton.backgroundColor = AppColor.primary
+        editButton.layer.cornerRadius = 12
+
+        emptyContainer.axis = .vertical
+        emptyContainer.alignment = .center
+        emptyContainer.spacing = 12
+        emptyLabel.text = "暂未获取到打卡点信息"
+        emptyLabel.textColor = AppColor.textSecondary
+        emptyLabel.font = .systemFont(ofSize: 15)
+        retryButton.setTitle("重新加载", for: .normal)
+        retryButton.setTitleColor(.white, for: .normal)
+        retryButton.backgroundColor = AppColor.primary
+        retryButton.layer.cornerRadius = 8
+        emptyContainer.addArrangedSubview(emptyLabel)
+        emptyContainer.addArrangedSubview(retryButton)
+        emptyContainer.isHidden = true
+
+        view.addSubview(mapView)
+        view.addSubview(zoomStack)
+        view.addSubview(locateButton)
+        view.addSubview(cardView)
+        cardView.addSubview(scrollView)
+        scrollView.addSubview(contentStack)
+        view.addSubview(bottomBar)
+        bottomBar.addSubview(editButton)
+        view.addSubview(emptyContainer)
+    }
+
+    override func setupConstraints() {
+        mapView.snp.makeConstraints { make in
+            make.top.equalTo(view.safeAreaLayoutGuide)
+            make.leading.trailing.equalToSuperview()
+            make.height.equalToSuperview().multipliedBy(0.5)
+        }
+        zoomStack.snp.makeConstraints { make in
+            make.trailing.equalToSuperview().inset(16)
+            make.bottom.equalTo(cardView.snp.top).offset(-16)
+        }
+        locateButton.snp.makeConstraints { make in
+            make.trailing.equalToSuperview().inset(16)
+            make.bottom.equalTo(zoomStack.snp.top).offset(-12)
+            make.size.equalTo(40)
+        }
+        zoomInButton.snp.makeConstraints { make in
+            make.size.equalTo(40)
+        }
+        zoomOutButton.snp.makeConstraints { make in
+            make.size.equalTo(40)
+        }
+        bottomBar.snp.makeConstraints { make in
+            make.leading.trailing.bottom.equalToSuperview()
+        }
+        editButton.snp.makeConstraints { make in
+            make.top.equalToSuperview().offset(16)
+            make.leading.trailing.equalToSuperview().inset(16)
+            make.height.equalTo(48)
+            make.bottom.equalTo(view.safeAreaLayoutGuide).offset(-20)
+        }
+        cardView.snp.makeConstraints { make in
+            make.leading.trailing.equalToSuperview().inset(16)
+            make.bottom.equalTo(bottomBar.snp.top)
+            make.height.lessThanOrEqualToSuperview().multipliedBy(0.45)
+            make.top.greaterThanOrEqualTo(mapView.snp.top).offset(60)
+        }
+        scrollView.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+        contentStack.snp.makeConstraints { make in
+            make.edges.equalToSuperview().inset(UIEdgeInsets(top: 16, left: 12, bottom: 12, right: 12))
+            make.width.equalTo(scrollView.snp.width).offset(-24)
+        }
+        emptyContainer.snp.makeConstraints { make in
+            make.center.equalToSuperview()
+        }
+        retryButton.snp.makeConstraints { make in
+            make.width.equalTo(118)
+            make.height.equalTo(40)
+        }
+    }
+
+    override func bindActions() {
+        viewModel.onStateChange = { [weak self] in
+            Task { @MainActor in self?.applyViewModel() }
+        }
+        viewModel.onShowMessage = { [weak self] message in
+            Task { @MainActor in self?.showToast(message) }
+        }
+        zoomInButton.addTarget(self, action: #selector(zoomInTapped), for: .touchUpInside)
+        zoomOutButton.addTarget(self, action: #selector(zoomOutTapped), for: .touchUpInside)
+        locateButton.addTarget(self, action: #selector(locateTapped), for: .touchUpInside)
+        retryButton.addTarget(self, action: #selector(retryTapped), for: .touchUpInside)
+        editButton.addTarget(self, action: #selector(editTapped), for: .touchUpInside)
+    }
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        Task { await viewModel.load(api: api) }
+    }
+
+    @MainActor
+    private func applyViewModel() {
+        viewModel.isLoading && viewModel.detail == nil ? showLoading() : hideLoading()
+        emptyContainer.isHidden = viewModel.detail != nil || viewModel.isLoading
+        guard let detail = viewModel.detail else {
+            cardView.isHidden = true
+            bottomBar.isHidden = true
+            return
+        }
+        cardView.isHidden = false
+        bottomBar.isHidden = false
+        if let region = detail.region {
+            let coordinate = CLLocationCoordinate2D(latitude: region.lat, longitude: region.lot)
+            mapView.updateMarker(coordinate: coordinate)
+            mapView.setCenter(coordinate, zoomLevel: 16)
+        }
+        rebuildContent(detail)
+    }
+
+    private func rebuildContent(_ detail: PunchPointDetail) {
+        contentStack.arrangedSubviews.forEach { $0.removeFromSuperview() }
+        contentStack.addArrangedSubview(PunchPointReadOnlyField(title: "*打卡点名称", value: detail.name))
+        let coordinateText = detail.region.map { "\($0.lat),\($0.lot)" } ?? "--"
+        contentStack.addArrangedSubview(PunchPointReadOnlyField(title: "*打卡点坐标", value: coordinateText))
+        contentStack.addArrangedSubview(PunchPointReadOnlyField(title: "*打卡点地址", value: detail.displayAddress.nonEmptyTrimmed ?? "--"))
+        if let description = detail.description?.nonEmptyTrimmed {
+            contentStack.addArrangedSubview(PunchPointReadOnlyField(title: "打卡点描述", value: description, multiline: true))
+        }
+        contentStack.addArrangedSubview(makeImageSection(detail.guideImages))
+        contentStack.addArrangedSubview(PunchPointRowField(title: "负责人", value: detail.creator?.nonEmptyTrimmed ?? "--"))
+        contentStack.addArrangedSubview(PunchPointDivider())
+        contentStack.addArrangedSubview(PunchPointRowField(title: "负责人手机号", value: PunchPointDisplayFormatter.maskedPhone(detail.creatorPhone)))
+        contentStack.addArrangedSubview(PunchPointDivider())
+        contentStack.addArrangedSubview(makeStatusRow(detail))
+        contentStack.addArrangedSubview(PunchPointDivider())
+        contentStack.addArrangedSubview(PunchPointRowField(title: "审核人", value: detail.auditor?.nonEmptyTrimmed ?? "--"))
+        contentStack.addArrangedSubview(PunchPointDivider())
+        contentStack.addArrangedSubview(PunchPointRowField(title: "审核时间", value: detail.auditTime?.nonEmptyTrimmed ?? "--"))
+        contentStack.addArrangedSubview(PunchPointDivider())
+        contentStack.addArrangedSubview(PunchPointRowField(title: "审核备注", value: detail.auditRemark?.nonEmptyTrimmed ?? "--"))
+        contentStack.addArrangedSubview(makeQRSection(detail.mpQrcode))
+    }
+
+    private func makeImageSection(_ urls: [String]) -> UIView {
+        let section = UIStackView()
+        section.axis = .vertical
+        section.spacing = 8
+        let title = UILabel()
+        title.attributedText = requiredTitle("*上传图片 (最多9张)")
+        section.addArrangedSubview(title)
+        guard !urls.isEmpty else {
+            let empty = UILabel()
+            empty.text = "暂无图片"
+            empty.font = .systemFont(ofSize: 12)
+            empty.textColor = AppColor.textSecondary
+            section.addArrangedSubview(empty)
+            return section
+        }
+        let scroll = UIScrollView()
+        scroll.showsHorizontalScrollIndicator = false
+        let row = UIStackView()
+        row.axis = .horizontal
+        row.spacing = 12
+        scroll.addSubview(row)
+        row.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+            make.height.equalTo(90)
+        }
+        urls.enumerated().forEach { index, urlText in
+            let imageView = UIImageView()
+            imageView.contentMode = .scaleAspectFill
+            imageView.clipsToBounds = true
+            imageView.layer.cornerRadius = 10
+            imageView.isUserInteractionEnabled = true
+            imageView.tag = index
+            if let url = URL(string: urlText) {
+                imageView.kf.setImage(with: url)
+            }
+            imageView.snp.makeConstraints { make in
+                make.width.equalTo(120)
+            }
+            imageView.addGestureRecognizer(UITapGestureRecognizer(target: self, action: #selector(imageTapped(_:))))
+            row.addArrangedSubview(imageView)
+        }
+        scroll.snp.makeConstraints { make in
+            make.height.equalTo(90)
+        }
+        section.addArrangedSubview(scroll)
+        return section
+    }
+
+    private func makeStatusRow(_ detail: PunchPointDetail) -> UIView {
+        let row = UIStackView()
+        row.axis = .horizontal
+        row.alignment = .center
+        row.distribution = .equalSpacing
+        let label = UILabel()
+        label.text = "审核状态"
+        label.font = .systemFont(ofSize: 14)
+        label.textColor = UIColor(hex: 0x2E3746)
+        let chip = PunchPointStatusChip()
+        chip.apply(text: detail.statusLabel.nonEmptyTrimmed ?? "--", status: detail.status)
+        row.addArrangedSubview(label)
+        row.addArrangedSubview(chip)
+        row.isLayoutMarginsRelativeArrangement = true
+        row.layoutMargins = UIEdgeInsets(top: 12, left: 0, bottom: 12, right: 0)
+        return row
+    }
+
+    private func makeQRSection(_ qrCode: String?) -> UIView {
+        let section = UIStackView()
+        section.axis = .vertical
+        section.alignment = .center
+        section.spacing = 12
+        let title = UILabel()
+        title.text = "打卡点二维码"
+        title.font = .systemFont(ofSize: 14)
+        title.textColor = UIColor(hex: 0x2E3746)
+        title.textAlignment = .left
+        title.snp.makeConstraints { make in
+            make.width.equalTo(contentStack.snp.width)
+        }
+        section.addArrangedSubview(title)
+        guard let qrCode = qrCode?.nonEmptyTrimmed else {
+            let empty = UILabel()
+            empty.text = "暂无二维码"
+            empty.font = .systemFont(ofSize: 12)
+            empty.textColor = AppColor.textSecondary
+            section.addArrangedSubview(empty)
+            return section
+        }
+        let imageView = UIImageView()
+        imageView.contentMode = .scaleAspectFill
+        imageView.clipsToBounds = true
+        imageView.layer.cornerRadius = 16
+        if let url = URL(string: qrCode) {
+            imageView.kf.setImage(with: url)
+        }
+        imageView.snp.makeConstraints { make in
+            make.size.equalTo(180)
+        }
+        let download = UIButton(type: .system)
+        download.setTitle("下载二维码", for: .normal)
+        download.setTitleColor(AppColor.primary, for: .normal)
+        download.titleLabel?.font = .systemFont(ofSize: 14)
+        download.backgroundColor = AppColor.primaryLight
+        download.layer.cornerRadius = 8
+        download.snp.makeConstraints { make in
+            make.height.equalTo(38)
+            make.width.equalTo(128)
+        }
+        download.addAction(UIAction { [weak self] _ in
+            self?.downloadQRCode(qrCode)
+        }, for: .touchUpInside)
+        section.addArrangedSubview(imageView)
+        section.addArrangedSubview(download)
+        return section
+    }
+
+    private func downloadQRCode(_ urlText: String) {
+        guard let url = URL(string: urlText) else {
+            showToast("二维码地址无效")
+            return
+        }
+        Task {
+            do {
+                let (data, _) = try await URLSession.shared.data(from: url)
+                guard let image = UIImage(data: data) else { throw APIError.decodeFailed("二维码图片无效") }
+                try await PHPhotoLibrary.shared().performChanges {
+                    PHAssetChangeRequest.creationRequestForAsset(from: image)
+                }
+                await MainActor.run { self.showToast("已保存到相册") }
+            } catch {
+                await MainActor.run { self.showToast(error.localizedDescription.isEmpty ? "保存失败" : error.localizedDescription) }
+            }
+        }
+    }
+
+    private func requiredTitle(_ text: String) -> NSAttributedString {
+        let mutable = NSMutableAttributedString(string: text, attributes: [
+            .font: UIFont.systemFont(ofSize: 14, weight: .medium),
+            .foregroundColor: UIColor(hex: 0x2E3746),
+        ])
+        if text.hasPrefix("*") {
+            mutable.addAttribute(.foregroundColor, value: AppColor.danger, range: NSRange(location: 0, length: 1))
+        }
+        return mutable
+    }
+
+    @objc private func imageTapped(_ gesture: UITapGestureRecognizer) {
+        guard let imageView = gesture.view, let urls = viewModel.detail?.guideImages else { return }
+        presentImagePreview(imageURLs: urls, startIndex: imageView.tag)
+    }
+
+    @objc private func zoomInTapped() {
+        mapView.zoomIn()
+    }
+
+    @objc private func zoomOutTapped() {
+        mapView.zoomOut()
+    }
+
+    @objc private func locateTapped() {
+        mapView.centerOnUserLocation()
+    }
+
+    @objc private func retryTapped() {
+        Task { await viewModel.load(api: api) }
+    }
+
+    @objc private func editTapped() {
+        guard let detail = viewModel.detail else { return }
+        let controller = PunchPointFormViewController(mode: .edit(id: detail.id), initialDetail: detail)
+        controller.onSubmitSuccess = { [weak self] in
+            guard let self else { return }
+            self.onChanged?()
+            Task { await self.viewModel.load(api: self.api) }
+        }
+        navigationController?.pushViewController(controller, animated: true)
+    }
+}
+
+/// 高德地图容器，供打卡点详情与表单复用。
+/// 打卡点地图视图，封装高德地图 marker、缩放、定位与点击选点行为。
+final class PunchPointMapView: UIView, MAMapViewDelegate {
+    var onMapTap: ((CLLocationCoordinate2D) -> Void)?
+
+    private let mapView: MAMapView
+    private var markerAnnotation: MAPointAnnotation?
+
+    override init(frame: CGRect) {
+        _ = AMapBootstrap.configureIfNeeded()
+        mapView = MAMapView(frame: .zero)
+        super.init(frame: frame)
+        mapView.delegate = self
+        mapView.showsUserLocation = true
+        mapView.showsCompass = false
+        mapView.showsScale = false
+        mapView.zoomLevel = 15
+        addSubview(mapView)
+        mapView.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    /// 更新打卡点标记。
+    func updateMarker(coordinate: CLLocationCoordinate2D?) {
+        if let markerAnnotation {
+            mapView.removeAnnotation(markerAnnotation)
+            self.markerAnnotation = nil
+        }
+        guard let coordinate, CLLocationCoordinate2DIsValid(coordinate) else { return }
+        let annotation = MAPointAnnotation()
+        annotation.coordinate = coordinate
+        annotation.title = "打卡点位置"
+        markerAnnotation = annotation
+        mapView.addAnnotation(annotation)
+    }
+
+    /// 设置地图中心点。
+    func setCenter(_ coordinate: CLLocationCoordinate2D, zoomLevel: Double = 15, animated: Bool = true) {
+        mapView.setCenter(coordinate, animated: animated)
+        mapView.setZoomLevel(zoomLevel, animated: animated)
+    }
+
+    /// 放大地图。
+    func zoomIn() {
+        mapView.setZoomLevel(mapView.zoomLevel + 1, animated: true)
+    }
+
+    /// 缩小地图。
+    func zoomOut() {
+        mapView.setZoomLevel(mapView.zoomLevel - 1, animated: true)
+    }
+
+    /// 居中到用户当前位置。
+    func centerOnUserLocation() {
+        guard let coordinate = mapView.userLocation.location?.coordinate,
+              CLLocationCoordinate2DIsValid(coordinate),
+              coordinate.latitude != 0 || coordinate.longitude != 0 else { return }
+        setCenter(coordinate)
+    }
+
+    func mapView(_ mapView: MAMapView!, didSingleTappedAt coordinate: CLLocationCoordinate2D) {
+        onMapTap?(coordinate)
+    }
+}
+
+/// 打卡点地图控制按钮。
+/// 地图悬浮控制按钮。
+final class PunchPointMapControlButton: UIButton {
+    init(symbol: String) {
+        super.init(frame: .zero)
+        setImage(UIImage(systemName: symbol), for: .normal)
+        tintColor = AppColor.textPrimary
+        backgroundColor = .white
+        layer.cornerRadius = 12
+        clipsToBounds = true
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+}
+
+/// 打卡点只读字段。
+/// 详情页只读字段块。
+final class PunchPointReadOnlyField: UIView {
+    init(title: String, value: String, multiline: Bool = false) {
+        super.init(frame: .zero)
+        let stack = UIStackView()
+        stack.axis = .vertical
+        stack.spacing = 8
+        let titleLabel = UILabel()
+        titleLabel.attributedText = Self.requiredTitle(title)
+        let valueLabel = UILabel()
+        valueLabel.text = value.nonEmptyTrimmed ?? "--"
+        valueLabel.font = .systemFont(ofSize: 14, weight: .medium)
+        valueLabel.textColor = AppColor.textPrimary
+        valueLabel.numberOfLines = multiline ? 0 : 2
+        stack.addArrangedSubview(titleLabel)
+        stack.addArrangedSubview(valueLabel)
+        addSubview(stack)
+        stack.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    private static func requiredTitle(_ text: String) -> NSAttributedString {
+        let mutable = NSMutableAttributedString(string: text, attributes: [
+            .font: UIFont.systemFont(ofSize: 14, weight: .medium),
+            .foregroundColor: UIColor(hex: 0x2E3746),
+        ])
+        if text.hasPrefix("*") {
+            mutable.addAttribute(.foregroundColor, value: AppColor.danger, range: NSRange(location: 0, length: 1))
+        }
+        return mutable
+    }
+}
+
+/// 打卡点左右字段。
+/// 详情页横向键值字段。
+final class PunchPointRowField: UIView {
+    init(title: String, value: String) {
+        super.init(frame: .zero)
+        let titleLabel = UILabel()
+        titleLabel.text = title
+        titleLabel.font = .systemFont(ofSize: 14)
+        titleLabel.textColor = UIColor(hex: 0x2E3746)
+        let valueLabel = UILabel()
+        valueLabel.text = value.nonEmptyTrimmed ?? "--"
+        valueLabel.font = .systemFont(ofSize: 14, weight: .medium)
+        valueLabel.textColor = .black
+        valueLabel.textAlignment = .right
+        valueLabel.numberOfLines = 2
+        addSubview(titleLabel)
+        addSubview(valueLabel)
+        titleLabel.snp.makeConstraints { make in
+            make.leading.top.bottom.equalToSuperview().inset(UIEdgeInsets(top: 12, left: 0, bottom: 12, right: 0))
+        }
+        valueLabel.snp.makeConstraints { make in
+            make.leading.greaterThanOrEqualTo(titleLabel.snp.trailing).offset(12)
+            make.trailing.centerY.equalToSuperview()
+        }
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+}
+
+/// 打卡点详情分割线。
+/// 详情卡片内分割线。
+final class PunchPointDivider: UIView {
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        backgroundColor = UIColor(hex: 0xF0F0F0)
+        snp.makeConstraints { make in
+            make.height.equalTo(1)
+        }
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+}
+
+private extension String {
+    var nonEmptyTrimmed: String? {
+        let text = trimmingCharacters(in: .whitespacesAndNewlines)
+        return text.isEmpty ? nil : text
+    }
+}

suixinkan/UI/PunchPoint/PunchPointFormViewController.swift

@@ -0,0 +1,668 @@
+//
+//  PunchPointFormViewController.swift
+//  suixinkan
+//
+
+import Kingfisher
+import PhotosUI
+import SnapKit
+import UIKit
+
+/// 打卡点新建与编辑页，对齐 Android `AddPunchPointScreen` / `EditPunchPointScreen`。
+final class PunchPointFormViewController: BaseViewController {
+    private let viewModel: PunchPointFormViewModel
+    private let api: any PunchPointAPIProtocol
+    private let uploader: any PunchPointImageUploading
+    private let initialDetail: PunchPointDetail?
+
+    private let mapView = PunchPointMapView()
+    private let zoomStack = UIStackView()
+    private let zoomInButton = PunchPointMapControlButton(symbol: "plus")
+    private let zoomOutButton = PunchPointMapControlButton(symbol: "minus")
+    private let locateButton = PunchPointMapControlButton(symbol: "location.fill")
+    private let cardView = UIView()
+    private let scrollView = UIScrollView()
+    private let formStack = UIStackView()
+    private let nameField = PunchPointTextFieldView(title: "*打卡点名称", placeholder: "请输入打卡点名称")
+    private let coordinateField = PunchPointCoordinateFieldView(title: "*打卡点坐标", placeholder: "点击右侧按钮,定位打卡点坐标")
+    private let addressField = PunchPointTextFieldView(title: "*打卡点地址", placeholder: "请输入打卡点地址")
+    private let descriptionField = PunchPointTextViewFieldView(title: "打卡点描述", placeholder: "请输入内容 (50字以内)")
+    private let imageGrid = PunchPointImageGridView()
+    private let bottomBar = UIView()
+    private let submitButton = UIButton(type: .system)
+    private var progressAlert: UIAlertController?
+    private var progressView: UIProgressView?
+    private var progressLabel: UILabel?
+
+    var onSubmitSuccess: (() -> Void)?
+
+    /// 初始化打卡点表单页。
+    init(
+        mode: PunchPointFormViewModel.Mode,
+        initialDetail: PunchPointDetail? = nil,
+        viewModel: PunchPointFormViewModel? = nil,
+        api: (any PunchPointAPIProtocol)? = nil,
+        uploader: (any PunchPointImageUploading)? = nil
+    ) {
+        self.viewModel = viewModel ?? PunchPointFormViewModel(mode: mode)
+        self.api = api ?? NetworkServices.shared.punchPointAPI
+        self.uploader = uploader ?? NetworkServices.shared.ossUploadService
+        self.initialDetail = initialDetail
+        super.init(nibName: nil, bundle: nil)
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    override func setupNavigationBar() {
+        switch viewModel.mode {
+        case .create:
+            title = "新建打卡点"
+        case .edit:
+            title = "编辑打卡点"
+        }
+    }
+
+    override func setupUI() {
+        view.backgroundColor = AppColor.pageBackground
+        zoomStack.axis = .vertical
+        zoomStack.spacing = 0
+        zoomStack.addArrangedSubview(zoomInButton)
+        zoomStack.addArrangedSubview(zoomOutButton)
+        cardView.backgroundColor = .white
+        cardView.layer.cornerRadius = 12
+        cardView.clipsToBounds = true
+        scrollView.keyboardDismissMode = .interactive
+        scrollView.showsVerticalScrollIndicator = false
+        formStack.axis = .vertical
+        formStack.spacing = 16
+        imageGrid.title = "*上传图片 (最多9张)"
+        bottomBar.backgroundColor = .white
+        submitButton.setTitle("提交审核", for: .normal)
+        submitButton.setTitleColor(.white, for: .normal)
+        submitButton.titleLabel?.font = .systemFont(ofSize: 16, weight: .medium)
+        submitButton.backgroundColor = AppColor.primary
+        submitButton.layer.cornerRadius = 8
+
+        view.addSubview(mapView)
+        view.addSubview(zoomStack)
+        view.addSubview(locateButton)
+        view.addSubview(cardView)
+        cardView.addSubview(scrollView)
+        scrollView.addSubview(formStack)
+        [nameField, coordinateField, addressField, descriptionField, imageGrid].forEach(formStack.addArrangedSubview)
+        view.addSubview(bottomBar)
+        bottomBar.addSubview(submitButton)
+    }
+
+    override func setupConstraints() {
+        mapView.snp.makeConstraints { make in
+            make.top.equalTo(view.safeAreaLayoutGuide)
+            make.leading.trailing.equalToSuperview()
+            make.height.equalToSuperview().multipliedBy(0.4)
+        }
+        zoomStack.snp.makeConstraints { make in
+            make.trailing.equalToSuperview().inset(16)
+            make.bottom.equalTo(cardView.snp.top).offset(-16)
+        }
+        locateButton.snp.makeConstraints { make in
+            make.trailing.equalToSuperview().inset(16)
+            make.bottom.equalTo(zoomStack.snp.top).offset(-12)
+            make.size.equalTo(40)
+        }
+        zoomInButton.snp.makeConstraints { make in
+            make.size.equalTo(40)
+        }
+        zoomOutButton.snp.makeConstraints { make in
+            make.size.equalTo(40)
+        }
+        bottomBar.snp.makeConstraints { make in
+            make.leading.trailing.bottom.equalToSuperview()
+            make.height.greaterThanOrEqualTo(84)
+        }
+        submitButton.snp.makeConstraints { make in
+            make.top.equalToSuperview().offset(16)
+            make.leading.trailing.equalToSuperview().inset(16)
+            make.height.equalTo(52)
+            make.bottom.equalTo(view.safeAreaLayoutGuide).offset(-16)
+        }
+        cardView.snp.makeConstraints { make in
+            make.leading.trailing.equalToSuperview().inset(16)
+            make.bottom.equalTo(bottomBar.snp.top).offset(-16)
+            make.height.lessThanOrEqualToSuperview().multipliedBy(0.5)
+            make.top.greaterThanOrEqualTo(mapView.snp.top).offset(40)
+        }
+        scrollView.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+        formStack.snp.makeConstraints { make in
+            make.edges.equalToSuperview().inset(UIEdgeInsets(top: 16, left: 12, bottom: 12, right: 12))
+            make.width.equalTo(scrollView.snp.width).offset(-24)
+        }
+    }
+
+    override func bindActions() {
+        viewModel.onStateChange = { [weak self] in
+            Task { @MainActor in self?.applyViewModel() }
+        }
+        viewModel.onShowMessage = { [weak self] message in
+            Task { @MainActor in self?.showToast(message) }
+        }
+        viewModel.onCoordinateChange = { [weak self] coordinate in
+            Task { @MainActor in
+                self?.mapView.updateMarker(coordinate: coordinate)
+                self?.mapView.setCenter(coordinate, zoomLevel: 17)
+            }
+        }
+        viewModel.onSubmitSuccess = { [weak self] in
+            Task { @MainActor in
+                self?.onSubmitSuccess?()
+                self?.navigationController?.popViewController(animated: true)
+            }
+        }
+        nameField.onTextChange = { [weak self] text in self?.viewModel.updateName(text) }
+        addressField.onTextChange = { [weak self] text in self?.viewModel.updateAddress(text) }
+        descriptionField.onTextChange = { [weak self] text in self?.viewModel.updateDescription(text) }
+        coordinateField.onLocate = { [weak self] in
+            guard let self else { return }
+            Task { await self.viewModel.locateToCurrent() }
+        }
+        imageGrid.onAdd = { [weak self] in self?.presentImagePicker() }
+        imageGrid.onDelete = { [weak self] index in self?.viewModel.deleteImage(at: index) }
+        imageGrid.onRetry = { [weak self] index in
+            guard let self else { return }
+            Task { await self.viewModel.retryUpload(at: index, uploader: self.uploader) }
+        }
+        mapView.onMapTap = { [weak self] coordinate in
+            guard let self else { return }
+            Task { await self.viewModel.selectCoordinate(coordinate) }
+        }
+        zoomInButton.addTarget(self, action: #selector(zoomInTapped), for: .touchUpInside)
+        zoomOutButton.addTarget(self, action: #selector(zoomOutTapped), for: .touchUpInside)
+        locateButton.addTarget(self, action: #selector(locateTapped), for: .touchUpInside)
+        submitButton.addTarget(self, action: #selector(submitTapped), for: .touchUpInside)
+    }
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        if let initialDetail {
+            viewModel.initialize(with: initialDetail)
+        } else {
+            Task { await viewModel.autoLocation() }
+        }
+    }
+
+    @MainActor
+    private func applyViewModel() {
+        if !nameField.isEditing {
+            nameField.text = viewModel.name
+        }
+        if !addressField.isEditing {
+            addressField.text = viewModel.address
+        }
+        if !descriptionField.isEditing {
+            descriptionField.text = viewModel.description
+        }
+        coordinateField.text = viewModel.coordinatesText
+        imageGrid.apply(images: viewModel.images)
+        submitButton.isEnabled = !viewModel.isSubmitting
+        submitButton.alpha = submitButton.isEnabled ? 1 : 0.65
+        submitButton.setTitle(viewModel.isSubmitting ? "提交中..." : "提交审核", for: .normal)
+        updateUploadDialog(viewModel.uploadDialogState)
+    }
+
+    private func presentImagePicker() {
+        let remaining = max(0, 9 - viewModel.images.count)
+        guard remaining > 0 else {
+            showToast("最多只能选择9张图片")
+            return
+        }
+        var configuration = PHPickerConfiguration(photoLibrary: .shared())
+        configuration.filter = .images
+        configuration.selectionLimit = remaining
+        let picker = PHPickerViewController(configuration: configuration)
+        picker.delegate = self
+        present(picker, animated: true)
+    }
+
+    private func makeImageState(image: UIImage, fileName: String) -> PunchPointImageState? {
+        guard let data = image.jpegData(compressionQuality: 0.9) else { return nil }
+        return PunchPointImageState(data: data, fileName: fileName)
+    }
+
+    private func updateUploadDialog(_ state: PunchPointUploadDialogState?) {
+        guard let state else {
+            progressAlert?.dismiss(animated: true)
+            progressAlert = nil
+            progressView = nil
+            progressLabel = nil
+            return
+        }
+        if progressAlert == nil {
+            let alert = UIAlertController(title: state.title, message: "\n\n", preferredStyle: .alert)
+            let progress = UIProgressView(progressViewStyle: .default)
+            progress.progressTintColor = AppColor.primary
+            let label = UILabel()
+            label.font = .systemFont(ofSize: 14)
+            label.textColor = AppColor.textSecondary
+            label.textAlignment = .center
+            alert.view.addSubview(progress)
+            alert.view.addSubview(label)
+            progress.snp.makeConstraints { make in
+                make.leading.trailing.equalToSuperview().inset(28)
+                make.top.equalToSuperview().offset(88)
+            }
+            label.snp.makeConstraints { make in
+                make.top.equalTo(progress.snp.bottom).offset(12)
+                make.centerX.equalToSuperview()
+            }
+            progressAlert = alert
+            progressView = progress
+            progressLabel = label
+            present(alert, animated: true)
+        }
+        progressAlert?.title = state.title
+        progressView?.progress = Float(state.progress) / 100.0
+        progressLabel?.text = "\(state.progress)%"
+    }
+
+    @objc private func zoomInTapped() {
+        mapView.zoomIn()
+    }
+
+    @objc private func zoomOutTapped() {
+        mapView.zoomOut()
+    }
+
+    @objc private func locateTapped() {
+        Task { await viewModel.locateToCurrent() }
+    }
+
+    @objc private func submitTapped() {
+        Task { await viewModel.submit(api: api) }
+    }
+}
+
+extension PunchPointFormViewController: PHPickerViewControllerDelegate {
+    func picker(_ picker: PHPickerViewController, didFinishPicking results: [PHPickerResult]) {
+        picker.dismiss(animated: true)
+        guard !results.isEmpty else { return }
+        var loadedItems = [PunchPointImageState?](repeating: nil, count: results.count)
+        let group = DispatchGroup()
+
+        for (index, result) in results.enumerated() {
+            group.enter()
+            result.itemProvider.loadObject(ofClass: UIImage.self) { [weak self] object, _ in
+                defer { group.leave() }
+                guard let self, let image = object as? UIImage else { return }
+                let fileName = "punch_point_\(Int(Date().timeIntervalSince1970))_\(index).jpg"
+                loadedItems[index] = self.makeImageState(image: image, fileName: fileName)
+            }
+        }
+
+        group.notify(queue: .main) { [weak self] in
+            guard let self else { return }
+            Task { await self.viewModel.addLocalImages(loadedItems.compactMap { $0 }, uploader: self.uploader) }
+        }
+    }
+}
+
+/// 打卡点表单单行输入字段。
+/// 打卡点表单单行输入字段。
+private final class PunchPointTextFieldView: UIView {
+    private let titleLabel = UILabel()
+    private let textField = UITextField()
+    var onTextChange: ((String) -> Void)?
+    var isEditing: Bool { textField.isFirstResponder }
+    var text: String {
+        get { textField.text ?? "" }
+        set {
+            if textField.text != newValue {
+                textField.text = newValue
+            }
+        }
+    }
+
+    init(title: String, placeholder: String) {
+        super.init(frame: .zero)
+        titleLabel.attributedText = Self.requiredTitle(title)
+        textField.placeholder = placeholder
+        textField.font = .systemFont(ofSize: 14)
+        textField.textColor = AppColor.textPrimary
+        textField.backgroundColor = .white
+        textField.layer.cornerRadius = 8
+        textField.layer.borderColor = AppColor.border.cgColor
+        textField.layer.borderWidth = 1
+        textField.leftView = UIView(frame: CGRect(x: 0, y: 0, width: 12, height: 44))
+        textField.leftViewMode = .always
+        addSubview(titleLabel)
+        addSubview(textField)
+        titleLabel.snp.makeConstraints { make in
+            make.top.leading.trailing.equalToSuperview()
+        }
+        textField.snp.makeConstraints { make in
+            make.top.equalTo(titleLabel.snp.bottom).offset(8)
+            make.leading.trailing.bottom.equalToSuperview()
+            make.height.equalTo(44)
+        }
+        textField.addTarget(self, action: #selector(textChanged), for: .editingChanged)
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    fileprivate static func requiredTitle(_ text: String) -> NSAttributedString {
+        let mutable = NSMutableAttributedString(string: text, attributes: [
+            .font: UIFont.systemFont(ofSize: 14, weight: .medium),
+            .foregroundColor: UIColor(hex: 0x2E3746),
+        ])
+        if text.hasPrefix("*") {
+            mutable.addAttribute(.foregroundColor, value: AppColor.danger, range: NSRange(location: 0, length: 1))
+        }
+        return mutable
+    }
+
+    @objc private func textChanged() {
+        onTextChange?(textField.text ?? "")
+    }
+}
+
+/// 打卡点坐标只读字段。
+/// 打卡点表单坐标选择字段。
+private final class PunchPointCoordinateFieldView: UIView {
+    private let titleLabel = UILabel()
+    private let container = UIView()
+    private let valueLabel = UILabel()
+    private let locateButton = UIButton(type: .system)
+    private let placeholder: String
+    var onLocate: (() -> Void)?
+    var text: String = "" {
+        didSet {
+            valueLabel.text = text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty ? placeholder : text
+            valueLabel.textColor = text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty ? UIColor(hex: 0x999999) : AppColor.textPrimary
+        }
+    }
+
+    init(title: String, placeholder: String) {
+        self.placeholder = placeholder
+        super.init(frame: .zero)
+        titleLabel.attributedText = PunchPointTextFieldView.requiredTitle(title)
+        container.layer.cornerRadius = 8
+        container.layer.borderWidth = 1
+        container.layer.borderColor = AppColor.border.cgColor
+        valueLabel.text = placeholder
+        valueLabel.font = .systemFont(ofSize: 14)
+        valueLabel.textColor = UIColor(hex: 0x999999)
+        locateButton.setImage(UIImage(systemName: "location.fill"), for: .normal)
+        locateButton.tintColor = AppColor.textPrimary
+        addSubview(titleLabel)
+        addSubview(container)
+        container.addSubview(valueLabel)
+        container.addSubview(locateButton)
+        titleLabel.snp.makeConstraints { make in
+            make.top.leading.trailing.equalToSuperview()
+        }
+        container.snp.makeConstraints { make in
+            make.top.equalTo(titleLabel.snp.bottom).offset(8)
+            make.leading.trailing.bottom.equalToSuperview()
+            make.height.equalTo(44)
+        }
+        valueLabel.snp.makeConstraints { make in
+            make.leading.equalToSuperview().offset(12)
+            make.centerY.equalToSuperview()
+            make.trailing.equalTo(locateButton.snp.leading).offset(-8)
+        }
+        locateButton.snp.makeConstraints { make in
+            make.trailing.equalToSuperview().inset(10)
+            make.centerY.equalToSuperview()
+            make.size.equalTo(26)
+        }
+        locateButton.addTarget(self, action: #selector(locateTapped), for: .touchUpInside)
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    @objc private func locateTapped() {
+        onLocate?()
+    }
+}
+
+/// 打卡点描述输入字段。
+/// 打卡点表单多行描述字段。
+private final class PunchPointTextViewFieldView: UIView, UITextViewDelegate {
+    private let titleLabel = UILabel()
+    private let textView = UITextView()
+    private let placeholderLabel = UILabel()
+    var onTextChange: ((String) -> Void)?
+    var isEditing: Bool { textView.isFirstResponder }
+    var text: String {
+        get { textView.text ?? "" }
+        set {
+            if textView.text != newValue {
+                textView.text = newValue
+                placeholderLabel.isHidden = !newValue.isEmpty
+            }
+        }
+    }
+
+    init(title: String, placeholder: String) {
+        super.init(frame: .zero)
+        titleLabel.text = title
+        titleLabel.font = .systemFont(ofSize: 14, weight: .medium)
+        titleLabel.textColor = UIColor(hex: 0x333333)
+        textView.font = .systemFont(ofSize: 14)
+        textView.textColor = AppColor.textPrimary
+        textView.layer.cornerRadius = 8
+        textView.layer.borderWidth = 1
+        textView.layer.borderColor = AppColor.border.cgColor
+        textView.textContainerInset = UIEdgeInsets(top: 10, left: 8, bottom: 10, right: 8)
+        textView.delegate = self
+        placeholderLabel.text = placeholder
+        placeholderLabel.font = .systemFont(ofSize: 14)
+        placeholderLabel.textColor = UIColor(hex: 0x999999)
+        addSubview(titleLabel)
+        addSubview(textView)
+        textView.addSubview(placeholderLabel)
+        titleLabel.snp.makeConstraints { make in
+            make.top.leading.trailing.equalToSuperview()
+        }
+        textView.snp.makeConstraints { make in
+            make.top.equalTo(titleLabel.snp.bottom).offset(8)
+            make.leading.trailing.bottom.equalToSuperview()
+            make.height.equalTo(92)
+        }
+        placeholderLabel.snp.makeConstraints { make in
+            make.top.equalToSuperview().offset(10)
+            make.leading.equalToSuperview().offset(12)
+            make.trailing.equalToSuperview().inset(12)
+        }
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    func textViewDidChange(_ textView: UITextView) {
+        if textView.text.count > 50 {
+            textView.text = String(textView.text.prefix(50))
+        }
+        placeholderLabel.isHidden = !textView.text.isEmpty
+        onTextChange?(textView.text)
+    }
+}
+
+/// 打卡点图片上传网格。
+/// 打卡点表单图片网格，负责新增、预览、删除与重试入口展示。
+private final class PunchPointImageGridView: UIView {
+    private let titleLabel = UILabel()
+    private let stack = UIStackView()
+    var onAdd: (() -> Void)?
+    var onDelete: ((Int) -> Void)?
+    var onRetry: ((Int) -> Void)?
+    var title: String = "" {
+        didSet { titleLabel.attributedText = PunchPointTextFieldView.requiredTitle(title) }
+    }
+
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        titleLabel.font = .systemFont(ofSize: 14, weight: .medium)
+        stack.axis = .vertical
+        stack.spacing = 12
+        addSubview(titleLabel)
+        addSubview(stack)
+        titleLabel.snp.makeConstraints { make in
+            make.top.leading.trailing.equalToSuperview()
+        }
+        stack.snp.makeConstraints { make in
+            make.top.equalTo(titleLabel.snp.bottom).offset(8)
+            make.leading.trailing.bottom.equalToSuperview()
+        }
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    func apply(images: [PunchPointImageState]) {
+        stack.arrangedSubviews.forEach { $0.removeFromSuperview() }
+        let cells = images.map(Optional.some) + (images.count < 9 ? [nil] : [])
+        let rows = Int(ceil(Double(cells.count) / 3.0))
+        guard rows > 0 else { return }
+        for row in 0 ..< rows {
+            let rowStack = UIStackView()
+            rowStack.axis = .horizontal
+            rowStack.spacing = 12
+            rowStack.distribution = .fillEqually
+            stack.addArrangedSubview(rowStack)
+            for column in 0 ..< 3 {
+                let index = row * 3 + column
+                if index < cells.count {
+                    rowStack.addArrangedSubview(makeCell(item: cells[index], index: index))
+                } else {
+                    rowStack.addArrangedSubview(UIView())
+                }
+            }
+        }
+    }
+
+    private func makeCell(item: PunchPointImageState?, index: Int) -> UIView {
+        let cell = PunchPointImageThumbView()
+        cell.snp.makeConstraints { make in
+            make.height.equalTo(cell.snp.width).dividedBy(1.7)
+        }
+        if let item {
+            cell.apply(item: item)
+            cell.onDelete = { [weak self] in self?.onDelete?(index) }
+            cell.onRetry = { [weak self] in self?.onRetry?(index) }
+        } else {
+            cell.applyAdd()
+            cell.onAdd = { [weak self] in self?.onAdd?() }
+        }
+        return cell
+    }
+}
+
+/// 打卡点图片上传缩略图。
+/// 打卡点图片缩略图。
+private final class PunchPointImageThumbView: UIControl {
+    private let imageView = UIImageView()
+    private let addIcon = UIImageView(image: UIImage(systemName: "plus"))
+    private let deleteButton = UIButton(type: .system)
+    private let overlayLabel = UILabel()
+    var onAdd: (() -> Void)?
+    var onDelete: (() -> Void)?
+    var onRetry: (() -> Void)?
+
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        layer.cornerRadius = 8
+        clipsToBounds = true
+        backgroundColor = .white
+        imageView.contentMode = .scaleAspectFill
+        imageView.clipsToBounds = true
+        addIcon.tintColor = AppColor.primary
+        deleteButton.setImage(UIImage(systemName: "xmark.circle.fill"), for: .normal)
+        deleteButton.tintColor = .white
+        overlayLabel.font = .systemFont(ofSize: 14, weight: .medium)
+        overlayLabel.textColor = .white
+        overlayLabel.textAlignment = .center
+        overlayLabel.backgroundColor = UIColor.black.withAlphaComponent(0.45)
+        addSubview(imageView)
+        addSubview(addIcon)
+        addSubview(deleteButton)
+        addSubview(overlayLabel)
+        imageView.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+        addIcon.snp.makeConstraints { make in
+            make.center.equalToSuperview()
+            make.size.equalTo(28)
+        }
+        deleteButton.snp.makeConstraints { make in
+            make.top.trailing.equalToSuperview().inset(4)
+            make.size.equalTo(22)
+        }
+        overlayLabel.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+        addTarget(self, action: #selector(tapped), for: .touchUpInside)
+        deleteButton.addTarget(self, action: #selector(deleteTapped), for: .touchUpInside)
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    func applyAdd() {
+        layer.borderColor = UIColor(hex: 0xE5E7EB).cgColor
+        layer.borderWidth = 1
+        imageView.image = nil
+        imageView.kf.cancelDownloadTask()
+        addIcon.isHidden = false
+        deleteButton.isHidden = true
+        overlayLabel.isHidden = true
+    }
+
+    func apply(item: PunchPointImageState) {
+        layer.borderWidth = 0
+        addIcon.isHidden = true
+        deleteButton.isHidden = item.isUploading
+        if let urlText = item.previewURL, let url = URL(string: urlText), !urlText.isEmpty {
+            imageView.kf.setImage(with: url)
+        } else {
+            imageView.image = UIImage(data: item.data)
+        }
+        if item.isUploading {
+            overlayLabel.isHidden = false
+            overlayLabel.text = "\(item.uploadProgress)%"
+        } else if item.errorMessage != nil {
+            overlayLabel.isHidden = false
+            overlayLabel.text = "重新上传"
+            overlayLabel.backgroundColor = AppColor.danger.withAlphaComponent(0.65)
+        } else {
+            overlayLabel.isHidden = true
+        }
+    }
+
+    @objc private func tapped() {
+        if !addIcon.isHidden {
+            onAdd?()
+        } else if !overlayLabel.isHidden, overlayLabel.text == "重新上传" {
+            onRetry?()
+        }
+    }
+
+    @objc private func deleteTapped() {
+        onDelete?()
+    }
+}

suixinkan/UI/PunchPoint/PunchPointListViewController.swift

@@ -0,0 +1,506 @@
+//
+//  PunchPointListViewController.swift
+//  suixinkan
+//
+
+import Kingfisher
+import SnapKit
+import UIKit
+
+/// 打卡点列表页，对齐 Android `PunchPointListScreen`。
+final class PunchPointListViewController: BaseViewController {
+    private let viewModel: PunchPointListViewModel
+    private let api: any PunchPointAPIProtocol
+
+    private let filterContainer = UIView()
+    private let filterButton = UIButton(type: .system)
+    private let filterTitleLabel = UILabel()
+    private let filterChevronView = UIImageView(image: UIImage(systemName: "chevron.down"))
+    private let filterDropdownView = UIView()
+    private let filterDropdownStack = UIStackView()
+    private let tableView = UITableView(frame: .zero, style: .plain)
+    private let bottomBar = UIView()
+    private let addButton = UIButton(type: .system)
+    private let emptyView = PunchPointEmptyView()
+    private var dataSource: UITableViewDiffableDataSource<Int, PunchPointItem>!
+    private var filterButtons: [(PunchPointFilterType, UIButton)] = []
+    private var needsRefreshOnAppear = false
+
+    /// 初始化打卡点列表页。
+    init(
+        viewModel: PunchPointListViewModel = PunchPointListViewModel(),
+        api: (any PunchPointAPIProtocol)? = nil
+    ) {
+        self.viewModel = viewModel
+        self.api = api ?? NetworkServices.shared.punchPointAPI
+        super.init(nibName: nil, bundle: nil)
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    override func setupNavigationBar() {
+        title = "打卡点列表"
+    }
+
+    override func setupUI() {
+        view.backgroundColor = AppColor.pageBackground
+
+        filterContainer.backgroundColor = .white
+        filterButton.backgroundColor = UIColor(hex: 0xF5F5F5)
+        filterButton.layer.cornerRadius = 8
+        filterTitleLabel.text = PunchPointFilterType.all.title
+        filterTitleLabel.font = .systemFont(ofSize: 14)
+        filterTitleLabel.textColor = AppColor.textPrimary
+        filterChevronView.tintColor = AppColor.textSecondary
+        filterChevronView.contentMode = .scaleAspectFit
+
+        filterDropdownView.backgroundColor = .white
+        filterDropdownView.layer.cornerRadius = 8
+        filterDropdownView.layer.shadowColor = UIColor.black.cgColor
+        filterDropdownView.layer.shadowOpacity = 0.12
+        filterDropdownView.layer.shadowRadius = 10
+        filterDropdownView.layer.shadowOffset = CGSize(width: 0, height: 4)
+        filterDropdownView.isHidden = true
+        filterDropdownStack.axis = .vertical
+
+        tableView.backgroundColor = AppColor.pageBackground
+        tableView.separatorStyle = .none
+        tableView.delegate = self
+        tableView.rowHeight = UITableView.automaticDimension
+        tableView.estimatedRowHeight = 210
+        tableView.contentInset = UIEdgeInsets(top: 12, left: 0, bottom: 12, right: 0)
+        tableView.refreshControl = UIRefreshControl()
+        tableView.register(PunchPointListCell.self, forCellReuseIdentifier: PunchPointListCell.reuseIdentifier)
+        dataSource = UITableViewDiffableDataSource<Int, PunchPointItem>(tableView: tableView) { [weak self] tableView, indexPath, item in
+            let cell = tableView.dequeueReusableCell(
+                withIdentifier: PunchPointListCell.reuseIdentifier,
+                for: indexPath
+            ) as! PunchPointListCell
+            cell.apply(item: item)
+            cell.onQRCode = { [weak self] in self?.viewModel.showQRCode(for: item) }
+            cell.onDelete = { [weak self] in self?.confirmDelete(item) }
+            return cell
+        }
+
+        bottomBar.backgroundColor = .white
+        addButton.setTitle("添加", for: .normal)
+        addButton.setTitleColor(.white, for: .normal)
+        addButton.titleLabel?.font = .systemFont(ofSize: 16, weight: .medium)
+        addButton.backgroundColor = AppColor.primary
+        addButton.layer.cornerRadius = 8
+
+        emptyView.isHidden = true
+        emptyView.onAction = { [weak self] in self?.addTapped() }
+
+        view.addSubview(filterContainer)
+        filterContainer.addSubview(filterButton)
+        filterButton.addSubview(filterTitleLabel)
+        filterButton.addSubview(filterChevronView)
+        view.addSubview(tableView)
+        view.addSubview(emptyView)
+        view.addSubview(bottomBar)
+        bottomBar.addSubview(addButton)
+        view.addSubview(filterDropdownView)
+        filterDropdownView.addSubview(filterDropdownStack)
+        configureFilterDropdown()
+    }
+
+    override func setupConstraints() {
+        filterContainer.snp.makeConstraints { make in
+            make.top.equalTo(view.safeAreaLayoutGuide)
+            make.leading.trailing.equalToSuperview()
+            make.height.equalTo(64)
+        }
+        filterButton.snp.makeConstraints { make in
+            make.leading.trailing.equalToSuperview().inset(15)
+            make.centerY.equalToSuperview()
+            make.height.equalTo(48)
+        }
+        filterTitleLabel.snp.makeConstraints { make in
+            make.leading.equalToSuperview().offset(12)
+            make.centerY.equalToSuperview()
+        }
+        filterChevronView.snp.makeConstraints { make in
+            make.trailing.equalToSuperview().inset(12)
+            make.centerY.equalToSuperview()
+            make.size.equalTo(22)
+        }
+        bottomBar.snp.makeConstraints { make in
+            make.leading.trailing.bottom.equalToSuperview()
+        }
+        addButton.snp.makeConstraints { make in
+            make.top.equalToSuperview().offset(16)
+            make.leading.trailing.equalToSuperview().inset(15)
+            make.height.equalTo(48)
+            make.bottom.equalTo(view.safeAreaLayoutGuide).offset(-16)
+        }
+        tableView.snp.makeConstraints { make in
+            make.top.equalTo(filterContainer.snp.bottom)
+            make.leading.trailing.equalToSuperview()
+            make.bottom.equalTo(bottomBar.snp.top)
+        }
+        emptyView.snp.makeConstraints { make in
+            make.centerX.equalToSuperview()
+            make.centerY.equalTo(tableView)
+            make.leading.trailing.equalToSuperview().inset(24)
+        }
+        filterDropdownView.snp.makeConstraints { make in
+            make.top.equalTo(filterButton.snp.bottom)
+            make.leading.trailing.equalTo(filterButton)
+        }
+        filterDropdownStack.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+    }
+
+    override func bindActions() {
+        viewModel.onStateChange = { [weak self] in
+            Task { @MainActor in self?.applyViewModel() }
+        }
+        viewModel.onShowMessage = { [weak self] message in
+            Task { @MainActor in self?.showToast(message) }
+        }
+        viewModel.onShowQRCode = { [weak self] url in
+            Task { @MainActor in self?.showQRCodeDialog(url: url) }
+        }
+        tableView.refreshControl?.addTarget(self, action: #selector(refreshPulled), for: .valueChanged)
+        filterButton.addTarget(self, action: #selector(filterTapped), for: .touchUpInside)
+        addButton.addTarget(self, action: #selector(addTapped), for: .touchUpInside)
+    }
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        Task { await viewModel.loadInitial(api: api) }
+    }
+
+    override func viewWillAppear(_ animated: Bool) {
+        super.viewWillAppear(animated)
+        if needsRefreshOnAppear {
+            needsRefreshOnAppear = false
+            Task { await viewModel.refresh(api: api) }
+        }
+    }
+
+    @MainActor
+    private func applyViewModel() {
+        filterTitleLabel.text = viewModel.filterType.title
+        filterButtons.forEach { type, button in
+            let selected = type == viewModel.filterType
+            button.setTitleColor(selected ? AppColor.primary : AppColor.textPrimary, for: .normal)
+            button.titleLabel?.font = .systemFont(ofSize: 14, weight: selected ? .medium : .regular)
+        }
+        var snapshot = NSDiffableDataSourceSnapshot<Int, PunchPointItem>()
+        snapshot.appendSections([0])
+        snapshot.appendItems(viewModel.items)
+        dataSource.apply(snapshot, animatingDifferences: true)
+        tableView.refreshControl?.endRefreshing()
+        emptyView.isHidden = !viewModel.items.isEmpty || viewModel.isLoading || viewModel.isRefreshing
+        viewModel.isLoading && viewModel.items.isEmpty ? showLoading() : hideLoading()
+    }
+
+    private func configureFilterDropdown() {
+        filterDropdownStack.arrangedSubviews.forEach { $0.removeFromSuperview() }
+        filterButtons = PunchPointFilterType.allCases.map { type in
+            let button = UIButton(type: .system)
+            button.contentHorizontalAlignment = .left
+            button.setTitle(type.title, for: .normal)
+            button.titleLabel?.font = .systemFont(ofSize: 14)
+            var configuration = UIButton.Configuration.plain()
+            configuration.contentInsets = NSDirectionalEdgeInsets(top: 13, leading: 12, bottom: 13, trailing: 12)
+            button.configuration = configuration
+            button.addAction(UIAction { [weak self] _ in
+                guard let self else { return }
+                self.filterDropdownView.isHidden = true
+                Task { await self.viewModel.selectFilter(type, api: self.api) }
+            }, for: .touchUpInside)
+            filterDropdownStack.addArrangedSubview(button)
+            return (type, button)
+        }
+    }
+
+    private func confirmDelete(_ item: PunchPointItem) {
+        let alert = UIAlertController(
+            title: "删除打卡点",
+            message: "确定删除\(item.name)打卡点吗？",
+            preferredStyle: .alert
+        )
+        alert.addAction(UIAlertAction(title: "取消", style: .cancel))
+        alert.addAction(UIAlertAction(title: "确定", style: .destructive) { [weak self] _ in
+            guard let self else { return }
+            Task { await self.viewModel.delete(item: item, api: self.api) }
+        })
+        present(alert, animated: true)
+    }
+
+    private func showQRCodeDialog(url: String) {
+        let controller = UIAlertController(title: nil, message: "\n\n\n\n\n\n\n\n", preferredStyle: .alert)
+        let imageView = UIImageView()
+        imageView.contentMode = .scaleAspectFill
+        imageView.clipsToBounds = true
+        imageView.layer.cornerRadius = 12
+        if let imageURL = URL(string: url) {
+            imageView.kf.setImage(with: imageURL)
+        }
+        controller.view.addSubview(imageView)
+        imageView.snp.makeConstraints { make in
+            make.centerX.equalToSuperview()
+            make.top.equalToSuperview().offset(52)
+            make.size.equalTo(180)
+        }
+        controller.addAction(UIAlertAction(title: "确定", style: .default))
+        present(controller, animated: true)
+    }
+
+    @objc private func filterTapped() {
+        filterDropdownView.isHidden.toggle()
+    }
+
+    @objc private func refreshPulled() {
+        Task { await viewModel.refresh(api: api) }
+    }
+
+    @objc private func addTapped() {
+        let controller = PunchPointFormViewController(mode: .create)
+        controller.onSubmitSuccess = { [weak self] in self?.needsRefreshOnAppear = true }
+        navigationController?.pushViewController(controller, animated: true)
+    }
+}
+
+extension PunchPointListViewController: UITableViewDelegate {
+    func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
+        tableView.deselectRow(at: indexPath, animated: true)
+        guard let item = dataSource.itemIdentifier(for: indexPath) else { return }
+        let controller = PunchPointDetailViewController(punchPointId: item.id)
+        controller.onChanged = { [weak self] in self?.needsRefreshOnAppear = true }
+        navigationController?.pushViewController(controller, animated: true)
+    }
+
+    func tableView(_ tableView: UITableView, willDisplay cell: UITableViewCell, forRowAt indexPath: IndexPath) {
+        Task { await viewModel.loadMoreIfNeeded(lastVisibleIndex: indexPath.row, api: api) }
+    }
+}
+
+/// 打卡点列表卡片。
+/// 打卡点列表卡片，复刻 Android 卡片中的封面、状态、负责人、时间、地址与操作区。
+private final class PunchPointListCell: UITableViewCell {
+    static let reuseIdentifier = "PunchPointListCell"
+
+    private let cardView = UIView()
+    private let coverImageView = UIImageView()
+    private let nameLabel = UILabel()
+    private let operatingTag = PunchPointStatusChip()
+    private let creatorLabel = UILabel()
+    private let createdAtLabel = UILabel()
+    private let locationIcon = UIImageView(image: UIImage(systemName: "mappin.and.ellipse"))
+    private let addressLabel = UILabel()
+    private let reviewTag = PunchPointStatusChip()
+    private let auditTimeLabel = UILabel()
+    private let qrButton = UIButton(type: .system)
+    private let deleteButton = UIButton(type: .system)
+
+    var onQRCode: (() -> Void)?
+    var onDelete: (() -> Void)?
+
+    override init(style: UITableViewCell.CellStyle, reuseIdentifier: String?) {
+        super.init(style: style, reuseIdentifier: reuseIdentifier)
+        backgroundColor = .clear
+        contentView.backgroundColor = .clear
+        selectionStyle = .none
+        cardView.backgroundColor = .white
+        cardView.layer.cornerRadius = 16
+        cardView.clipsToBounds = true
+
+        coverImageView.contentMode = .scaleAspectFill
+        coverImageView.clipsToBounds = true
+        coverImageView.layer.cornerRadius = 12
+        coverImageView.backgroundColor = UIColor(hex: 0xF5F5F5)
+        nameLabel.font = .systemFont(ofSize: 16, weight: .semibold)
+        nameLabel.textColor = .black
+        nameLabel.lineBreakMode = .byTruncatingTail
+        [creatorLabel, createdAtLabel, auditTimeLabel].forEach {
+            $0.font = .systemFont(ofSize: 12)
+            $0.textColor = AppColor.textSecondary
+        }
+        locationIcon.tintColor = UIColor(hex: 0x4B5563)
+        addressLabel.font = .systemFont(ofSize: 12)
+        addressLabel.textColor = UIColor(hex: 0x4B5563)
+        addressLabel.numberOfLines = 2
+        qrButton.setImage(UIImage(systemName: "qrcode"), for: .normal)
+        qrButton.tintColor = AppColor.textPrimary
+        deleteButton.setImage(UIImage(systemName: "trash"), for: .normal)
+        deleteButton.tintColor = AppColor.textPrimary
+
+        contentView.addSubview(cardView)
+        [coverImageView, nameLabel, operatingTag, creatorLabel, createdAtLabel, locationIcon, addressLabel, reviewTag, auditTimeLabel, qrButton, deleteButton].forEach(cardView.addSubview)
+
+        cardView.snp.makeConstraints { make in
+            make.top.bottom.equalToSuperview().inset(6)
+            make.leading.trailing.equalToSuperview().inset(15)
+        }
+        coverImageView.snp.makeConstraints { make in
+            make.top.leading.equalToSuperview().offset(16)
+            make.size.equalTo(128)
+        }
+        nameLabel.snp.makeConstraints { make in
+            make.top.equalTo(coverImageView)
+            make.leading.equalTo(coverImageView.snp.trailing).offset(12)
+            make.trailing.lessThanOrEqualTo(operatingTag.snp.leading).offset(-8)
+        }
+        operatingTag.snp.makeConstraints { make in
+            make.centerY.equalTo(nameLabel)
+            make.trailing.equalToSuperview().inset(16)
+        }
+        creatorLabel.snp.makeConstraints { make in
+            make.top.equalTo(nameLabel.snp.bottom).offset(8)
+            make.leading.equalTo(nameLabel)
+            make.trailing.equalToSuperview().inset(16)
+        }
+        createdAtLabel.snp.makeConstraints { make in
+            make.top.equalTo(creatorLabel.snp.bottom).offset(6)
+            make.leading.trailing.equalTo(creatorLabel)
+        }
+        locationIcon.snp.makeConstraints { make in
+            make.top.equalTo(createdAtLabel.snp.bottom).offset(8)
+            make.leading.equalTo(nameLabel)
+            make.size.equalTo(14)
+        }
+        addressLabel.snp.makeConstraints { make in
+            make.top.equalTo(locationIcon).offset(-1)
+            make.leading.equalTo(locationIcon.snp.trailing).offset(4)
+            make.trailing.equalToSuperview().inset(16)
+        }
+        reviewTag.snp.makeConstraints { make in
+            make.top.equalTo(coverImageView.snp.bottom).offset(14)
+            make.leading.equalToSuperview().offset(16)
+            make.bottom.equalToSuperview().inset(16)
+        }
+        auditTimeLabel.snp.makeConstraints { make in
+            make.centerY.equalTo(reviewTag)
+            make.leading.equalTo(reviewTag.snp.trailing).offset(8)
+        }
+        deleteButton.snp.makeConstraints { make in
+            make.centerY.equalTo(reviewTag)
+            make.trailing.equalToSuperview().inset(16)
+            make.size.equalTo(32)
+        }
+        qrButton.snp.makeConstraints { make in
+            make.centerY.equalTo(reviewTag)
+            make.trailing.equalTo(deleteButton.snp.leading).offset(-4)
+            make.size.equalTo(32)
+        }
+
+        qrButton.addTarget(self, action: #selector(qrTapped), for: .touchUpInside)
+        deleteButton.addTarget(self, action: #selector(deleteTapped), for: .touchUpInside)
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    func apply(item: PunchPointItem) {
+        nameLabel.text = item.name
+        creatorLabel.text = "负责人:\(item.creator?.nonEmptyTrimmed ?? "--")"
+        createdAtLabel.text = "创建时间:\(item.createdAt)"
+        addressLabel.text = item.displayAddress.nonEmptyTrimmed ?? "--"
+        auditTimeLabel.text = "审核时间：\(item.auditTime?.nonEmptyTrimmed ?? "--")"
+        operatingTag.apply(text: item.statusLabel.nonEmptyTrimmed ?? "--", status: item.status)
+        reviewTag.apply(text: item.statusLabel.nonEmptyTrimmed ?? "--", status: item.status)
+        if let url = item.guideImages.first.flatMap(URL.init(string:)) {
+            coverImageView.kf.setImage(with: url, placeholder: UIImage(systemName: "photo"))
+        } else {
+            coverImageView.image = UIImage(systemName: "photo")
+        }
+    }
+
+    @objc private func qrTapped() {
+        onQRCode?()
+    }
+
+    @objc private func deleteTapped() {
+        onDelete?()
+    }
+}
+
+/// 打卡点状态标签。
+/// 打卡点状态标签视图。
+final class PunchPointStatusChip: UIView {
+    private let label = UILabel()
+
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        layer.cornerRadius = 10
+        clipsToBounds = true
+        label.font = .systemFont(ofSize: 12, weight: .medium)
+        label.textAlignment = .center
+        addSubview(label)
+        label.snp.makeConstraints { make in
+            make.edges.equalToSuperview().inset(UIEdgeInsets(top: 3, left: 8, bottom: 3, right: 8))
+        }
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    /// 应用标签文案和状态色。
+    func apply(text: String, status: Int) {
+        label.text = text
+        let colors = PunchPointDisplayFormatter.statusColors(status)
+        backgroundColor = UIColor(hex: colors.background)
+        label.textColor = UIColor(hex: colors.text)
+    }
+}
+
+/// 打卡点列表空状态。
+/// 打卡点空列表视图，提供空状态文案与新增入口。
+private final class PunchPointEmptyView: UIView {
+    private let titleLabel = UILabel()
+    private let button = UIButton(type: .system)
+    var onAction: (() -> Void)?
+
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        titleLabel.text = "暂无打卡点"
+        titleLabel.font = .systemFont(ofSize: 15)
+        titleLabel.textColor = AppColor.textSecondary
+        titleLabel.textAlignment = .center
+        button.setTitle("添加打卡点", for: .normal)
+        button.setTitleColor(.white, for: .normal)
+        button.titleLabel?.font = .systemFont(ofSize: 14, weight: .medium)
+        button.backgroundColor = AppColor.primary
+        button.layer.cornerRadius = 8
+        addSubview(titleLabel)
+        addSubview(button)
+        titleLabel.snp.makeConstraints { make in
+            make.top.leading.trailing.equalToSuperview()
+        }
+        button.snp.makeConstraints { make in
+            make.top.equalTo(titleLabel.snp.bottom).offset(12)
+            make.centerX.bottom.equalToSuperview()
+            make.width.equalTo(128)
+            make.height.equalTo(40)
+        }
+        button.addTarget(self, action: #selector(actionTapped), for: .touchUpInside)
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    @objc private func actionTapped() {
+        onAction?()
+    }
+}
+
+private extension String {
+    var nonEmptyTrimmed: String? {
+        let text = trimmingCharacters(in: .whitespacesAndNewlines)
+        return text.isEmpty ? nil : text
+    }
+}